| name | implementation-planning |
| description | Use when running /spec:plan, after a Specification.md exists and before task breakdown — turns approved requirements into a technical approach, file structure, and testing strategy. Philosophy adapted from GitHub Spec-Kit's plan phase and BMAD-METHOD's architecture discipline. |
Implementation Planning
A plan translates an approved spec's WHAT/WHY into a concrete HOW: an approach, a file/module
structure, and a way to verify each requirement. It is still a document, not code.
Process
- Read the spec and the constitution first. If a functional requirement conflicts with a
constitution principle, flag it explicitly to the user — do not silently resolve the
conflict by picking whichever one is more convenient to implement.
- Propose 2-3 viable approaches before committing to one. For each: what it costs, what
it risks, what it makes easy later. Recommend one with a stated reason, not just "this is
simplest."
- Decompose into files/modules with single responsibilities. Each entry in the file
structure table should be describable in one sentence. If a description needs "and," the
module is probably doing two things. If the spec references a wireframe/prototype, every
UI-facing module should name which one it implements — a module with UI responsibility and
no wireframe behind it is either missing from the UX phase or scope creep.
- Map every functional requirement to a verification method. FR-N in the spec should
trace to a row in the testing strategy table. A requirement with no verification method is
a requirement that will silently rot.
- Write an ADR for costly-to-reverse decisions. Trigger conditions: choosing a framework
or library that's expensive to swap later, defining a data model or API shape other code
will depend on, or picking between architectures with materially different long-term
consequences. Not every plan needs an ADR — most don't.
Output discipline
- No code in the plan — pseudocode or interface sketches are fine if they clarify structure,
but this is still a document Claude will read before writing real code, not the code
itself.
- Every risk or open question gets written down, even if you have a leaning — surfacing it
lets the user veto before implementation starts, which is much cheaper than after.
Red flags
| Red flag | Why it matters |
|---|
| Only one approach was considered | Trade-offs are invisible when there's nothing to compare against |
| A file/module structure entry says "handles everything for X" | Single-responsibility violation waiting to happen |
| A spec requirement has no corresponding testing-strategy row | It will ship unverified |
| An ADR is written for a trivially reversible choice | Adds process weight where none is needed — reserve ADRs for real forks in the road |
