plan-implementation

---
name: plan-implementation
description: "Use when a validated business spec must become a DDD technical plan split into batches before coding. Traces RM/CU, DDD decisions and targeted test scenarios."
argument-hint: "[path of the specification to turn into a plan]"
---

# Implementation plan from a spec

Spec → plan. Unambiguous for the `run-plan` / `run-lot` workflows; design doc, not code.

$ARGUMENTS

## Mission

Plan split by feature, not layer:

1. Trace every RM-XX + CU-XX to owning code elements.
2. Per element: name, role, public signature, pseudo-code bullets, exact path — existing or new.
3. Classify + trace DDD/Architecture rules: owning aggregate, invariants, consistency, events, boundaries, access cost.
4. Test scenarios + RM + level (unit: handlers; integration: repositories; contract: endpoints; E2E: lifecycle) + anchors: test class file, fixture, shared builders, doubles.
5. Respect the conventions of `run-lot` (`implement-tdd` `references/`) + the repo's `/tests-*` skills (`rules/cctoolkit.md`).

## Workflow

### 1. Understand

0. **Gate — open blocking questions.** Before any read, one `Bash`: the gate, then the spec's headings:

   ```bash
   awk '/^## (.*<!-- *kit:open-questions *-->|12\. (Open questions|Questions ouvertes))/{p=1;next} /^## /{p=0} p && /\| *(Blocking|Bloquant) *\|/' <spec>; echo '--- headings'; grep -nE '^#{2,3} ' <spec>
   ```

   The section is found by its anchor, or by the title of a spec written before the anchors (`## 12. Questions ouvertes`, severity `Bloquant`). Any line before `--- headings` → **stop**: list them, end with `→ Open blocking questions: /business-spec to settle them.` No plan while a `Blocking` is open — same contract as `## BLOCKED` in a batch, moved before design. The headings give step 1 the bounded context, the aggregate and the `kit:modified` ids.
1. **Inventory in the background, reads beside it.** A `Read` under `src/` or `tests/` attaches layer rules to every later turn: the bounded context is inventoried by delegation. Gate passed → one message holding:
   - one `Explore` subagent, `model: sonnet`, `run_in_background: true`, the prompt below (the inventory includes local conventions);
   - `graphify explain "<Aggregate>"`;
   - with a knowledge base, `cctoolkit ask --id <id>,<id>…` on the spec's `kit:modified` ids;
   - `Read` of the spec, `references/ddd-rules.md`, `references/architecture-rules.md`, `references/plan-template.md`;
   - the `Naming` and `Folder layout` tables — bounded extract, never a full rule file, never a file under `src/`, a few dozen lines:

     ```bash
     for f in .claude/rules/*.md; do
       awk '/^## (Naming|Folder layout)/{p=1} /^## /{ if(p && $0 !~ /^## (Naming|Folder layout|No nullable)/) p=0 } p' "$f"
     done
     ```

   ```text
   Bounded context: … — spec: [path] — need: [one sentence]
   With a knowledge base: `cctoolkit ask --id` on the spec's `modified` use cases and the base ids it cites — their `handlers:` lines start item 2.
   Return `path:line` tables, 60 lines max, no code excerpt:
   1. Aggregates, value objects, entities, domain interfaces reusable for the need — exact names
   2. Repositories, handlers, endpoints owning the same business act or a similar one; per handler, the path of its folder CLAUDE.md
   3. Routes of the context in Endpoints/Endpoints.cs (collision risk)
   4. Test anchors: test class file and fixture per handler of item 2, and where the fixture builds that handler (constructor, factory or builder method); contract fixture and .verified.txt per route of item 3; builders and doubles under tests/{{PRODUCT}}.CoreTests/ for the aggregates of item 1; the first-level folders of the integration test project
   5. Tests asserting a message, error code, route or response field the spec changes — `grep -rln` of its current literal under the test roots; per file, the test methods asserting it
   6. Callers of each aggregate method the spec changes, production and tests
   7. Local conventions of the context — naming, folder layout — one line each
   ```

   Its result comes back as a notification: never wait on it, never search under `src/` or `tests/` for what it returns. Meanwhile, the spec against the rules. Its business decisions (`kit:decisions`) are inputs: a technical choice that would contradict one → AskUserQuestion. Its technical points (`kit:technical-points`) are the questions this plan answers, each in a sheet (step 3.4). Each rule id → applied in the owning batch sheet (`## Design`), or listed once in global plan `1. Scope` as `N/A — reason`; `references/ddd-examples.md` only if an id is ambiguous. Inventory back → a search only for an item it leaves empty, one call per gap.
2. You open only the folder `CLAUDE.md` of the handler owning the same business act, its `kit:rules` table — rewrite vs twin = your call. Inventory → "1. Scope > Reuse"; its items 5 and 6 → the `full` and `ripple` of the cycles that change those literals and methods.
3. Blast radius per existing type modified: one `graphify affected "<Type>"` per aggregate, VO, domain interface already in `src/`; new type: skip. Roll up per project (`grep -oE '(src|tests)/[^/]+' | sort | uniq -c | sort -rn`), never paste file:line. Rollup → "1. Scope" as measured cost; drives split (step 2) — radius over four test projects = own batch.
4. Blocking technical ambiguity → AskUserQuestion before planning (≤4 decisions/call, recommended answer first).
5. Technical challenge — ≤3 AskUserQuestion questions, only if answer removes work:
   - Ship without new type, service, endpoint, table?
   - Extending existing covers 80 % (see Maximum reuse)?
   - Which scope part waits for later batch without blocking value?

   Skip if obvious from inventory. Scope-reducing answer → section Scope.

### 2. Split

Cross-cutting functional batches (Domain + App + Infra + WebAPI + tests), each independently deliverable, build green.

Status per batch: `sequential` default, or `parallelisable with F?` (two worktrees). Parallelisable only if prerequisites done + nothing shared — functional dependency, file, fixture, configuration, migration, route. Same aggregate, handler, endpoint, `.csproj`, DI, EF migration, test fixture → sequential. Concrete reason in plan; doubt → sequential.

### 3. Write

1. Copy `references/plan-template.md` into `todo/[code-kebab-case]/` — the folder `/business-spec` wrote `SPEC-[code-kebab-case].md` in: global plan `[CODE]-PLAN.md`, one sheet `[CODE]-PLAN-F1.md`, `-F2.md`… per batch. `run-lot` on a sheet loads the global plan by section + that sheet alone.
2. **Before naming any element**, the `Naming` and `Folder layout` tables of step 1.1 in front of you. `run-lot` hands the names and paths of `## Cycles` to its agents verbatim: a wrong name here becomes a wrong file there, caught only at GREEN.
3. Handler doc — per handler created/modified: its folder `CLAUDE.md` in the `production` of the cycle that changes its rules (business rules, flow + access cost, events), written by that cycle's GREEN. Parent feature index `CLAUDE.md` only when its two or three sentences on the bounded context no longer hold — no handler list, no link, no table. Format: `/implement-tdd` `references/claude-md-handler.md`.
4. **Decisions** — every technical point of the spec, and every choice a reader of the sheet would otherwise ask about, is one entry of `## Decisions` in the sheet of the batch it governs, in the four-line format of `references/plan-template.md`. A decision that outlives the plan — it shapes code beyond this feature: storage model, contract with another context, a pattern the next features will follow — is an ADR: heading `### ADR-nnn — …` and a `Consequences` line. Its id: one `cctoolkit next-id ADR --count <n>` once every ADR of the plan is known; the sheet under `todo/` keeps it taken until the merge. Any other decision: heading without id, it ends with the plan. `2. Traceability` maps each technical point to its decision and batch.
5. Self-validation: re-read plan vs checklist. Deviation → fix plan. Doubt on business intent → ask user.
6. **Adversarial review.** In one message, one `Agent` per batch sheet with `subagent_type: cctoolkit:adversarial-reviewer`, a `description`, prompt starting `mode: sheet todo/<code>/<CODE>-PLAN-FX.md`, plus one prompt starting `mode: plan todo/<code>/` for cross-batch issues. `Blocking` → fix plan per its `Settled by` source, else AskUserQuestion: the plan never closes with a Blocking unanswered; `Major` → fix, or keep with one line in the sheet's `## Decisions` saying why. Never re-run it on the corrected plan. Settle here everything `run-plan` would otherwise ask mid-run: the run asks only `humanOnly` questions, so a choice left open now is taken without the user and reviewed after the plan.
7. Summary: batch count, RM/CU traced, technical points settled and ADRs taken, files produced, folder path, review rows settled and how.

## Execution-plan rules (`0. Summary` > `### Batch FX`)

- Step = end-to-end business behaviour, not layer, not file
- One step = one production artifact: Command/Query+Handler, endpoint, repository. Two steps on same handler + same aggregate method = one step. Guard, refusal, uniqueness/visibility check on method already in a step = not a step — one more method of that step's cycle.
- Every step → ≥1 test named per target skill convention + RM + target test project: `Should{Result}_When{Condition}`, unless the `Naming` table of `.claude/rules/tests.md` sets another pattern for a level (loaded at step 1.1). Unnameable behaviour = internal mechanism ("scan", "detect", "map", "convert") → recast as behaviour. Test names and paths → the sheet's `## Cycles` block; assertions → `/tests-*` skills.
- One entry of a cycle's `methods` = one test method, full final `Class.Method` name: condition chosen here, never left to the RED. Never an exception, a class, "N files", an ellipsis (`…`), a placeholder or an open `_When`: `cctoolkit sheet-cycles --index` rejects such a name, and the RED cannot match it. Existing tests rewritten → one entry per method.
- 2-5 behaviour steps per batch. Past 6: split hit rule level → regroup by target method. Legitimately >8 → split batch in two. No documentation nor verification step: the GREEN updates the handler `CLAUDE.md`, the run's global green replays the scopes of `## Test policy and scopes`.
- Guard test green at once on the current code (architecture or convention guard, no production code drives it) = its own cycle with `"guard": true`: `run-lot` writes it and runs it green, no GREEN follows. Any other test expected green at once stops `run-lot` on "RED not observed".
- Every message, error code, route or response field the batch changes → `grep -rln` its current literal under the test roots. Each test file asserting it goes into `full` of the cycle that changes it, its methods into that cycle's `methods`: the RED rewrites them to the new value (never a negative assertion that passes whatever the code does), the GREEN may not touch a test.
- Registry oracle (derived, never a count), shaped form of a helper-normalized value, guard reachable from a handler → `.claude/rules/tests.md` and the `Unreachable guard` check of `adversarial-reviewer`: the sheet names the oracle and the shaped form in the cycle's `scenarios`, a guard only the aggregate reaches (no handler calls the guarded method in that state) stays out of the plan.
- `## Test policy and scopes` names the verification scope: whole suites, filtered project + filter root, suites skipped + why. Bare "`dotnet test`" = weak criterion

## Plan contents

Structure, section order and anchors: `references/plan-template.md`, verbatim. What it can't show:

- **Global plan** = WHAT + WHY + ORDER, under 2 min to read. Never in it — sheet only: per-batch element list, test names, batch decisions, applied rule ids, signatures, pseudo-code, file paths, fixture/mock/builder structure, anything derivable from `.claude/rules/*.md`. A step title states the business behaviour, nothing else.
- **Batch sheet** = enough for `run-lot`. Test level per element: unit per handler behaviour; integration as soon as it lives in `src/{{PRODUCT}}.Infrastructure/`; contract if a route changes; E2E only for a multi-operation lifecycle. Sole integration waiver: element with no persistence effect (DI registration, adapter of an already-doubled external service), written as the sheet line `Integration test waiver: <reason>` — the label stays English whatever `language.docs`, only the reason follows it —, the line `cctoolkit pre-audit` reads.
- **`## Cycles`**: the TDD contract of the batch, one ```json block, fields and caps per `/implement-tdd` `references/design.md` § "The `## Cycles` block" and `parallelism.md`. `steps` = exact titles of the global-plan steps, every step carried by at least one cycle. Existing path from the inventory (1.1); new file mirrors the sibling it imitates, marked `(to create)` or listed in `toCreate`, that sibling in the cycle's `models`. `cctoolkit sheet-cycles <sheet> --index` exit 0 before the review: a path not copyable is a plan hole. The block never repeats the sheet: signatures stay in `## Code elements`, applied ids, invariants and access cost in `## Design` — `sheet-cycles --cycle` hands both to the GREEN; `elements`, `appliedIds`, `invariants`, `expectedCost` only for a cycle that departs from them, `scenarios` only for what a method name cannot carry.
- **Sheet size**: about 20 KB at most. No inventory table, no per-behaviour narrative: the block (tests and paths) and `## Code elements` (signatures) carry the contract, `## Decisions` the non-obvious choices.
- Never: C# method bodies, test assertions, SQL/DDL, LINQ, full DI configuration, fixture/mock/builder internals, long justifications.

## Conventions

Layer conventions → `.claude/rules/*.md`, never auto-loaded here (step 1.1 forbids a layer file read): load the `Naming` and `Folder layout` tables explicitly (step 1.1) before naming an element. Design rules → `references/ddd-rules.md`, `architecture-rules.md`. Cite ids in the sheet, never copy them.

## Maximum reuse

Before new class/service/VO: find mechanism already doing 80 %+. Extend, don't create.

- Business act already owned by handler → rewrite it, never second parallel use case. Same for endpoint: existing route evolves, no twin.
- Existing type of same shape → rename/extend, no second record.
- Existing method, similar pattern → optional parameter or overload, not new service
- Existing dictionary/lookup (a dependency map, a handler mapping) → reuse, no new mapping VO; existing filtering/exclusion (an excluded-ids parameter of a sibling handler) → extend; existing Application service → call directly, no wrapper

In plan: every "new" element justifies why existing insufficient. Weak justification = extension.

## Self-validation checklist

- DDD naming and folder layout conform (`Naming` / `Folder layout` tables loaded at step 1.1)
- Every DDD/APP/PERF id applied in a sheet `## Design` or listed `N/A — reason` in global plan `1. Scope`; every sheet cites its applied ids with aggregate, invariants, consistency, internal event, cost
- Every RM/CU → ≥1 named test; every step carried by a cycle of `## Cycles`, existing paths from inventory, never guessed; `cctoolkit sheet-cycles <sheet> --index` exit 0
- Every technical point of the spec (`kit:technical-points`) → one decision of a sheet, traced in `2. Traceability`; every ADR id from `cctoolkit next-id ADR`; no decision contradicts a business decision of the spec
- Element in `src/{{PRODUCT}}.Infrastructure/` → ≥1 integration scenario, or the `Integration test waiver: <reason>` sheet line
- Feasibility: dependencies resolved, no unflagged breaking change; no EF migration planned (other project — schema change flagged, not scheduled)
- `## Test policy and scopes` names test scope in Microsoft.Testing.Platform form (`--project` + `--filter-class`): VSTest `--filter "FullyQualifiedName~..."` doesn't exist here

## Next step

End with: `→ Manual plan validation required. Once validated: /cctoolkit:run-plan todo/[code-kebab-case]/[CODE]-PLAN.md (whole plan) or /cctoolkit:run-lot todo/[code-kebab-case]/[CODE]-PLAN-F1.md (one batch)`.

• SKILL.md 16 KB
• references/architecture-rules.md 2 KB
• references/ddd-examples.md 3 KB
• references/ddd-rules.md 3 KB
• references/plan-template.md 10 KB