Implement Plan (Canon TDD)

Implement Plan

Turn the current plan into working, tested code — strictly test-first. This skill is the wrapper that ties three things together: the plan (what to build), the canon-tdd skill (how to build it), and a single finishing condition — the test list is empty (when to stop). It does not invent its own TDD rules; it delegates the discipline to canon-tdd and adds plan-awareness, the finishing goal, and the project's specialist skills.

Red-Green-Refactor is the engine. The test list is the steering wheel. This skill keeps the wheel on screen and drives until the list is empty.

Agent Behaviour Contract

These are non-negotiable. Do them by default, without being reminded.

1. Canon TDD is mandatory — invoke the canon-tdd skill. No production code before a failing test. One test at a time. Refactor only on green. This skill exists to enforce that loop against the plan; do not freelance an implementation-first approach.
2. Show the test list before any code — and every time it changes. Print the Canon TDD test list as a checklist before the first edit, and re-print it whenever you add, remove, reword, or check off an item (see Keep the test list visible).
3. The finishing condition is an empty test list. "Done" means every item on the list has a written, passing test and the full suite is green — nothing less. Pair this with the /goal command for autonomous cross-turn iteration (see Set the finishing goal). Exactly three kinds of item are exempt, because canon-tdd puts them on the list and no test can assert them: the /// doc comment, the DocC catalog entry, and the README.md update. They are done when make build-docs passes and the README is in sync — not when a test covers them. Nothing else is exempt; don't reclassify a behavioural item into this set.
4. Reach for the right specialist skill. Use swift-testing-expert when writing/structuring tests and swift-concurrency for anything touching tasks, actors, @MainActor, Sendable, or data races — don't hand-roll what those skills know.
5. Document every public declaration — no exceptions. Documenting it is part of "make it pass". Every public protocol, class, struct, enum, actor, model, property, initializer, method, subscript, and typealias you add or change MUST carry an accurate /// doc comment, and the DocC catalog must stay in sync (see Document every public declaration). This is mandatory, not optional — make build-docs runs warnings-as-errors, so an undocumented public symbol is a build failure.
6. Expect Swift files to change after you write them. A PostToolUse hook runs swiftlint --fix + swiftformat on every .swift file you Edit/Write, so the on-disk content can differ from what you wrote (see The lint/format hook).
7. Commit at logical checkpoints — always green. Like a human engineer, commit when a cohesive increment is complete and the code is in a good state, and never commit a red or half-finished tree (see Commit at logical points). This keeps the work committed as you go, so a downstream review sees real history rather than an empty diff.
8. Finish with the completion checklist. Before declaring done, run /test and /integration-test — both REQUIRED to pass per CLAUDE.md — plus /lint, and make build-docs whenever public API changed.

Locate the plan

Use the first that applies, then restate the plan's goal in a sentence so the test list is anchored to it:

1. An explicit target the user named — a plan/design file path, or plan text passed as the skill argument.
2. The active plan-mode plan — the most recent plan you presented via ExitPlanMode.
3. A plan in the conversation — the most recent structured plan / task breakdown (including a TodoWrite list framed as the plan).

If there is no plan, stop and say so — offer to draft one first (e.g. via the Plan agent or plan mode), and to /review-plan it before implementing. Never fabricate a plan in order to implement it.

Step 0 — Consult the knowledge base

Before deriving the list, skim the entry headings of knowledge/gotchas.md and knowledge/tmdb-api-notes.md, read the entries (and any knowledge/decisions/ ADR) relevant to what you are about to build, and say in one line what you consulted — consulted: <entries | none relevant>. Captured knowledge only compounds if it is read before the code, and half these entries exist precisely to stop a test list being written with a known trap missing from it.

/deliver does this at its Phase 0, so a run reaching here through the pipeline has it already; this step is what makes a standalone /implement-plan equivalent rather than a knowledge-blind shortcut.

Step 1 — Derive and show the test list

Invoke the canon-tdd skill and follow its five steps. Start by translating the plan into a test list: enumerate every behaviour, edge case, and error path the plan implies — as a plain checklist, not code. For this package that means thinking about: each new/changed public method, Codable decode paths (every optional/appended branch — one fixture item per branch), empty/degenerate inputs at public boundaries, Sendable/concurrency expectations, and Linux portability.

Print the list before writing any code, e.g.:

Test list — <plan goal>
- [ ] decodes <X> with all appended fields present
- [ ] decodes <X> with appended fields absent → optionals are nil
- [ ] <service>.<method>() builds the expected request URL + query items
- [ ] <method>() throws on empty/degenerate input
- [ ] integration: <method>() returns live data

It is a living list — you will add cases as implementation reveals them. Confirm it with the user (or state it explicitly) before proceeding.

Enumerate by symbol, not by text — use the LSP. When the list needs "every site that does X" (every caller of a helper, every conformer to a protocol, every construction of a request type), ask the compiler, not grep. Load the tool once with ToolSearch("select:LSP"), then use findReferences / incomingCalls for call sites, goToImplementation for conformers, and hover for a symbol's real type behind any, a generic, or a typealias. Expect a cold start — the first call can fail with server is starting; retry once. Positions are 1-based and the character must land on the symbol.

A text pattern silently under-reports, and that is not hypothetical: ADR-0008 prescribed grep 'path = "/…\(stringVar)"' to find every path interpolation. It missed three builders whose let path = sat on its own line — four sites recorded, eight actual, and the three it missed carried a bearer-like credential for two months (issue #421). findReferences on the request initialiser would have listed all eight. Keep grep for exact strings, JSON fixtures, Markdown, and non-Swift files, where it is the better tool.

Mirror the family — probe the nearest siblings first. When an item adds a sibling to an existing family (another service method, another model, another addRating-style guarded method, another @Suite test), read the 1–2 closest existing siblings before writing the test, and capture the conventions they share as explicit test-list items: input validation (does the sibling guard empty/degenerate input?), the error case it throws (.badRequest vs a dedicated TMDbError case), the model conformance set and decode strategy (synthesised vs custom init(from:)), and the test-suite tag/structure. New code should match its family's pattern by default; a deliberate divergence is fine, but it should be a choice, not an accident. This is the prevent-half of the convention-conformance check .github/CODE_REVIEW.md enforces at review time.

Step 2 — Set the finishing goal

The completion condition for this whole effort is: the test list is empty — every item has a written, passing test, and make test + make integration-test are green, with no unrelated files modified.

For autonomous, cross-turn iteration toward that condition, use Claude Code's /goal command. You cannot set /goal yourself — it is user-initiated — so offer the user the exact command to run, then proceed with the TDD loop either way:

/goal every item on the Canon TDD test list has a written, passing test and
`make test` and `make integration-test` both pass — without modifying files
unrelated to this plan; or stop after 25 turns

If the user sets it, Claude keeps taking turns until a fast model confirms the condition. If they don't, drive the same loop yourself across the turn until the list is empty. Either way the destination is identical: zero unchecked items.

Step 3 — The TDD loop (one test at a time)

Per canon-tdd, repeat until the list is empty:

1. Pick the next item and write exactly one test (use swift-testing-expert for structure — @Test/#expect/#require, parameterisation, tags). Run it; watch it fail for the right reason.
2. Make it pass with the simplest production change that works — resist solving items still on the list. Any public symbol you introduce here is documented in the same step (see Document every public declaration) — a public declaration without a /// comment is not "passing".
3. Refactor only on green, keeping every test passing and every public symbol documented.
4. Update the list — check off the item, and add any new cases the work revealed — then re-print the list.
5. Commit when you reach a logical checkpoint — when the increment is cohesive and green (see Commit at logical points). Not every micro-cycle; at meaningful milestones.

Add JSON fixtures under Tests/TMDbTests/Resources/json/ as decode tests demand, and a paired integration test under Tests/TMDbIntegrationTests/ for new public behaviour. Use the TMDb MCP server (mcp__tmdb__*) to source real responses for fixtures rather than guessing structure.