Plan Tasks

Read the written spec, break it down into ordered implementation steps. Output is a ## Plan section appended to the end of the spec file — do not create a new file.

Run

Step 1 — Read the inputs

Read: .ai/tasks/<task-name>.md          ← spec to plan
Read: .ai/context/architecture.md      ← understand current structure

Answer these questions before writing the plan:

• Is there existing code that needs to be read/modified? If so, read it now.
• Is this completely new (greenfield) or modifying existing code (brownfield)?
• Are there any dependencies that must be created first (DB schema, interface, type)?

Step 2 — Find "atoms"

An atom is the smallest unit that can be verified independently.

How to find them: read Scope in the spec → for each file/module, ask "what is the smallest piece that can be done and tested independently?"

Example decomposition:

Scope: "add password reset"
→ Break into:
   - token generation logic (pure function, testable)
   - DB schema (migration)
   - API endpoint request (HTTP layer)
   - email send (side effect, mockable)
   - API endpoint confirm (HTTP layer)
   - wiring (integration)

Step 3 — Order by dependency

Standard order (bottom-up):

1. Types / interfaces / contracts  ← depend on nothing
2. Pure business logic              ← depends on types
3. Data persistence (migrations, models)
4. Side effects (email, queue, cache)
5. API / interface layer            ← calls into logic + persistence
6. Wiring / integration             ← connects the layers
7. Tests covering the full flow     ← confirms end-to-end

Rule: step N must not call code from step N+1.

Step 4 — Write the plan

Append to the end of the spec file:

## Plan

<!-- Execute in order. Each step only begins when the previous one is done. -->

- [ ] 1. <verb> <specific file/function> — <short description>
         Done when: <specific, verifiable criteria>

- [ ] 2. ...

Requirements for each step:

• Start with an action verb: Create, Add, Update, Remove, Wire, Migrate, Test
• Include specific file/function names if known
• Done when: must be immediately verifiable (run a command, check output, read code) — must not be a "gut feeling"

Example of a good step:

- [ ] 1. Create `src/auth/reset-token.ts` — generateToken() and validateToken() functions
         Done when: unit tests pass for both functions, including the expired token case

Example of a bad step:

- [ ] 1. Implement password reset logic   ← too broad, no idea what "done" means
- [ ] 2. Make sure it works              ← not verifiable

Step 5 — Check plan quality

Before saving:

[ ] Does each step have a specific "Done when:"?
[ ] Does the first step not depend on anything that doesn't exist yet?
[ ] Does no step span more than one coding session (~2-3h)?
[ ] Can the largest step be broken down further?
[ ] If step 3 fails → can step 4 still start? (if not, note the dependency explicitly)

If any step fails a check → break it up or rewrite it before saving.

After the plan is done

Confirm with user: display the plan just written, ask "Start from step 1?" or "Are there any steps that need adjustment?"

Do not start coding automatically — do not implement until the user has approved the plan.

Gotchas

Brownfield: read the existing code before planning. Plans based on assumptions about old code will be wrong. Use grep/read to confirm function names, interfaces, and current patterns before writing them into the plan.

Avoid a "mega step" at the end. "Integration + testing + polish" lumped into one final step is a sign the plan is not detailed enough. Break it up.

Don't plan too far ahead. If the spec has unresolved Open questions → plan only up to the point before that decision is needed, and note clearly "⚠️ need to confirm X before continuing."