plan

Plan

docs/staging/plans/YYYY-MM-DD-<topic>.md. Reference the spec; don't restate it.

If unresolved spec notes affect implementation or task order, return to design.

Multi-module plan

If topology=multi-module (triage announcement or coordinator spec/plan declaration), read ../references/multi-module.md. Open the workspace plan with the declaration block (topology: multi-module, change-set, coordinator, repos, module plan paths, integration task) - it is the on-disk mode marker downstream skills rely on.

• Write the workspace plan in the coordinator repository and a module plan in every affected module's owning repository.
• The workspace plan lists the change-set ID, coordinator, repositories, module plan paths, and the integration task.
• Every task names exactly one repository: and one module:. Cross-module verification is an integration task owned by the coordinator.
• Order contract tasks before consumers, local acceptance before integration, and integration before linked commits.
• Mark tasks parallel only when they have independent write scopes and acceptance.
• Adding a repository after implementation starts: update the declaration block and confirm with the user. Return to design only if the addition changes a shared contract.

Rolling wave

Spec references a milestone (milestone: MN)? Check docs/ROADMAP.md — expand only that milestone. Leave the rest as stubs.

After ship: open docs/ROADMAP.md, confirm which milestone is next, then expand it. Return to design only if the milestone's goal materially changed.

Milestone tasks (30-60 min each)

Every task is - [ ] T<n>: <name> - always a checkbox, never a heading. tdd/subagents flip it to - [x] on completion; ship refuses to run while any - [ ] remains.

goal:       <one sentence>
files:      <paths>
acceptance: <test or cmd>
spec:       <docs/staging/specs/...#anchor>

No exact code. No step-by-step. Acceptance is verifiable: a test, command, or scripted check — or, when none is possible, an explicit manual check (steps + expected result). Each task leaves the repo green.

Mark independent tasks: [parallel] T3, T4, T5.

Only mark [parallel] when shared contracts, state, errors, and acceptance are closed.

Atomic expansion is deferred until dispatch time - subagents expands a milestone into 2-5 min steps at dispatch time, not here.

for New project: derive an initialization task — scaffold code, tests, CI, and always include: README.md, CHANGELOG.md, .gitignore, and a Makefile (or equivalent task runner config).

Don't put in the plan

background, architecture, rationale (spec), CI commands, copy-pasted acceptance.

Hand off

<gate> The plan must exist on disk before handing off to tdd/subagents. For multi-module work, this means the coordinator workspace plan and every affected module plan in its owning repository. </gate>

Confirm plan with the user.

mostly [parallel] → subagents. Otherwise → tdd.