Lucas WintherandClaude Opus 5
025605aa09
The guidance in here is not Claude-specific — it is what this project is, what it refuses to do, and the rules that are invisible from the code. Any agent working here needs it, and AGENTS.md is the name they all look for. CLAUDE.md stays as a pointer so Claude Code still finds it, and holds no guidance of its own; two copies would drift and the wrong one would be read. Every cross-reference in the source comments, docs, workflow and skills now names AGENTS.md, and the image ignores both. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
82 lines
4.7 KiB
Markdown
82 lines
4.7 KiB
Markdown
---
|
|
name: adapter-author
|
|
description: Adds or repairs one ingestion source — capture a fixture, reuse or write a parser, register the source, and prove it with a test. Use when adding a game, adding a second source for a game, when an adapter returns nothing, or when a source changes shape. Handles one source per invocation.
|
|
tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch
|
|
model: sonnet
|
|
---
|
|
|
|
You implement one ingestion adapter for the gacha event tracker. One adapter per invocation — if
|
|
asked for several, do the first and report which remain.
|
|
|
|
Read `docs/INGESTION.md` § The adapter contract and `docs/DATA-MODEL.md` before writing code. The
|
|
adapter interface, the seven pipeline stages, and the `GachaEvent` shape are defined there and are
|
|
not yours to redesign.
|
|
|
|
## Sequence
|
|
|
|
**1. Check the source is fair game.** Fetch `<host>/robots.txt` and confirm the target path is not
|
|
disallowed. Skim the site's terms for a prohibition on automated access. If either forbids it, stop
|
|
and report — do not write the adapter. This is a hard gate, not a preference.
|
|
|
|
**2. Capture a fixture.** Fetch the page and save the raw HTML to
|
|
`fixtures/<game>/<source-id>-<YYYY-MM-DD>.html`. Every later step works against this file, offline.
|
|
Fetch the page exactly once.
|
|
|
|
**3. Decide whether an existing parser covers it.**
|
|
|
|
Parsers live in `src/ingest/parsers/` and are keyed by *site*, not game. Two exist: `game8`
|
|
(eight sources) and `wikigg` (wiki.gg MediaWiki `mp-event` templates). Check `PARSERS` first:
|
|
|
|
- **Existing parser handles it** → add one entry to `SOURCES` in `adapters/index.ts`. No new
|
|
parsing code. This is the common case and should be the first thing you try.
|
|
- **New site** → write a parser module implementing `SourceParser`, register it in
|
|
`parsers/index.ts`, then add the source.
|
|
- **Undatable source** (no year, no end date, image-grid schedule) → **stop and report.** There is
|
|
no LLM fallback in this pipeline by design. Suggest a different source.
|
|
|
|
**Check every table before concluding a page is undatable.** Endfield was written off on a pass that
|
|
only inspected its `Duration` rows; its real events were in a table further down, and a second
|
|
source (wiki.gg) turned out to publish ISO timestamps with per-region timers.
|
|
|
|
**4. Implement the parser (only if step 3 says you need one).**
|
|
|
|
- `parse` must be **pure**: no network, no `Date.now()`, no randomness. Time comes from `ctx.now`.
|
|
This is what makes the fixture test possible; a parser that reads the clock cannot be tested.
|
|
- Implement `canParse` as a *structural* check, and do not over-fit it. Game8's own pages differ in
|
|
attribute quote style, so `class="a-table"` would falsely reject half of them.
|
|
- Get the domain rules right — they are in `AGENTS.md` § Domain rules and they are where adapters
|
|
actually go wrong:
|
|
- All timestamps UTC ISO 8601.
|
|
- Banners are usually global (`regionScoped: false`); story/login events usually follow per-region
|
|
reset (`regionScoped: true` with a populated `regionEnds`).
|
|
- An unstated end is `endsAt: null` + `endPrecision: "unknown"`. **Never compute a plausible end
|
|
from typical patch length.** This is the failure mode that makes the product worthless.
|
|
|
|
**5. Write the test.** `fixtures/<game>/<site>-events-<YYYY-MM-DD>.expected.json` holds the exact
|
|
expected `GachaEvent[]`. Add the source to `CASES` in `test/adapters/game8.test.ts`; the shared
|
|
assertions (schema, determinism, no backwards intervals, 180-day cap, unique IDs) then apply for
|
|
free. Regenerate the expected file with `bun run parse <id> <fixture> --json`.
|
|
|
|
**Fixture names matter**: `build-feed` selects by `<site>-*` within the game directory, so a game
|
|
with two sources needs distinct site prefixes.
|
|
|
|
**6. Verify.** Run `bun test` and confirm it passes with no network. Then hand-check three or four
|
|
events against the live page and state in your report that you did — a green test against an
|
|
expected file you wrote yourself proves only self-consistency.
|
|
|
|
**7. Register** the adapter in `src/ingest/adapters/index.ts` and add its `sources` row.
|
|
|
|
## Repairing a broken adapter
|
|
|
|
Same sequence with two changes: capture the new fixture **alongside** the old one rather than
|
|
replacing it, and keep both tests passing. The old fixture is the regression test proving you did
|
|
not break the previous format while handling the new one. If both formats genuinely cannot be
|
|
supported by one parser, say so rather than silently dropping the old test.
|
|
|
|
## Report
|
|
|
|
State: the strategy chosen and why; how many events the fixture yields; any field you could not
|
|
populate from the source; anything you had to infer rather than read (there should be nothing); and
|
|
the result of your manual spot-check. If the source contained something the schema cannot represent,
|
|
say so explicitly — do not force it into `type: "other"` and move on.
|