implement-plan

name	implement-plan
description	Implement the current plan test-first, the Canon TDD way, driving to a single finishing condition — an empty test list. Derives a Canon TDD test list from the plan, shows it before any code, writes one failing test at a time, and keeps the list visible as it evolves. Use when the user asks to implement, build, or execute the current/approved plan.

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.

Commit at logical points

Build the change as a human engineer would — a sequence of small, working commits, each a coherent step — not one giant uncommitted blob at the end.

When to commit — at a logical checkpoint, when a cohesive increment is complete: a model + its decode tests; a service method + its unit (and integration) tests; a finished refactor; the fixtures + docs for a unit. Group a few related test-list items into one commit rather than committing every single red→green micro-cycle. A good commit tells a story ("✨ Add TVSeason watch providers endpoint", "✅ Cover decode branches for …", "♻️ Extract …").

Good state before every commit — never commit red:

• The suite is green — run /test (and /integration-test if the increment touches live-API behaviour) and confirm it passes.
• Lint is clean — /lint (the format hook handles most of it on write).
• No half-finished or dead code — no commented-out experiments, no stubbed function you haven't returned to, no debug prints. The tree compiles and every public symbol you added is documented.

If an increment isn't green yet, finish it (or stash the unfinished part) before committing — a commit is a working state. Use a gitmoji-prefixed message (the convention lives in the /pr skill). Committing as you go means that by the time the test list is empty, the work is fully committed — ready for review and PR with a clean history.

Document every public declaration

Every public symbol you add or change MUST have an accurate /// documentation comment — this is a hard requirement (CLAUDE.md), and make build-docs runs warnings-as-errors, so a missing one breaks the build. Document as you write it, in the same green step — never as a clean-up pass at the end.

This covers all public declarations, no exceptions:

• Types — protocol, class, struct, enum, actor, typealias, and every model.
• Members — stored and computed properties, initializers, methods, subscripts, enum cases where meaning isn't obvious, and associated values.
• Custom Codable — init(from:) and encode(to:) in a public extension need /// comments too (a common miss).

Quality, not just presence:

• Use correct DocC syntax — - Parameter name: (singular) for one parameter, - Parameters: (plural) for several; - Returns:; - Throws:.
• Write complete, specific descriptions — never placeholders (/// ?, Array of...). Watch for copy-paste errors (e.g. "movie" left in a Person doc, or Movie.ID where Person.ID is meant).
• Keep the DocC catalog in sync when public API changes: the service extension file (TMDb.docc/Extensions/<Service>Service.md), the catalog (TMDb.docc/TMDb.md) for new return types, TMDbClient.md for new properties, and the README.md service table — per the consistency checklist in the document-swift skill (its Verify before finishing section).

Apply the document-swift skill — the project's single source of DocC conventions — inline as you write each public symbol. For a bulk pass (a whole new service, or sweeping many undocumented symbols at once), delegate to the documentation-writer agent, which follows the same skill in an isolated context. Add a "document public API" item to the test list when a behaviour introduces public surface, so it can't be silently skipped.

Keep the test list visible

The list is the user's window into progress. Re-print the full checklist (done + remaining) whenever it changes — after checking off an item, after discovering and adding a new case, after rewording or removing one. Each re-print should make clear what just changed (e.g. "✓ added", "✓ done", "✗ removed — superseded by …"). Never let code changes outpace a stale on-screen list.

Use the right specialist skills

• swift-testing-expert — when writing or restructuring tests: macro usage, #require over force-unwrap, traits/tags, parameterised tests, async waiting.
• swift-concurrency — when the plan touches tasks, actors, @MainActor, Sendable, async/await conversion, or any data-race / Swift 6 strict-concurrency diagnostic.
• document-swift skill — the DocC conventions to apply inline for every public declaration; documentation-writer agent for bulk doc sweeps (see Document every public declaration).
• /test, /integration-test, /build, /lint, /format — delegate builds and test runs to these (they fan out to a Haiku subagent and keep this context lean); don't call make directly for them.

Invoke a specialist skill the moment its domain appears — not after you've already hand-written something it would have done better.

The lint/format hook (files change after you write them)

A PostToolUse hook matches Edit|Write and, for any .swift file, runs swiftlint --fix then swiftformat on it. Consequences to plan around:

• The file on disk may differ from what you wrote — imports reordered, whitespace/indentation normalised, trailing commas adjusted, self. removed, etc. This is expected and correct; do not fight it or revert it.
• Re-Read a .swift file before your next Edit to it if that edit depends on exact surrounding text — a stale old_string (pre-format) can fail to match.
• Don't attribute hook reformatting to your own diff. When reviewing changes, separate "what I changed" from "what the formatter normalised".
• It only autofixes the single edited file, not the whole tree, and it cannot fix real compile errors — so still run /lint and /test before finishing.

Done — when the test list is empty

When every item is checked off:

1. Run /test and /integration-test — both must pass (CLAUDE.md requires it). Then run make build-release: debug-green and release-red diverge exactly on access-level and @testable mistakes, and in #398 both full suites and --build-tests were green while the release build was broken.

2. Run /lint (and /format if needed); run make build-docs and /lint-markdown only if public API or docs changed.

3. Changed a literal string, symbol name or code sample? Grep for its siblings before calling it done. Fixing the one occurrence in front of you and leaving its twins is this repo's commonest half-fix, and **/*.docc/** and README.md are the habitual blind spot: no gate compiles a code sample — make build-docs compiles the DocC catalog, not the Swift inside a fence. Grep the whole tree for the old text, not the new:

   grep -rn '<the old spelling>' README.md Sources/ Tests/ knowledge/
   

   This applies to an incidental one-line fix, which is the gap: a task framed as "fix every instance of X" is already covered by the type-driven enumeration above, and a reflexive .claude/ change by /deliver's footprint sweep. #452 fixed a stale search("…") call in README.md and left the identical call in two .docc catalogs for code review to find.

4. Print the final, fully-checked test list and a short summary of what was implemented.

5. If a /goal was set, it clears automatically once the condition is confirmed.

Do not declare the plan implemented while any test-list item is unchecked or any required suite is red. An empty list with green suites — that is the finish line.