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`](../../../knowledge/gotchas.md) and
[`knowledge/tmdb-api-notes.md`](../../../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.:

```text
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:

```text
/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:

   ```bash
   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.