plan-review

name	plan-review
description	Use when docs/specs/changes/{name}/ has delta specs validated by review-changes but no tasks.md yet, or when user says "plan this change", "write the plan", "what are the tasks" — produces tasks.md grouped into stages with canonical subagent dispatch phrasings, mapping every ADDED/MODIFIED requirement to tasks, with verification and evidence recorded at the stage boundary (not per task). This is the workflow's sole user-approval gate.
metadata	{"tags":["tech:markdown","spec-driven","workflow","planning"]}

Plan Review

Overview

Produce docs/specs/changes/{name}/tasks.md from an approved change. Every ADDED or MODIFIED requirement maps to at least one task. Tasks are grouped into stages with explicit dependency boundaries so execution can dispatch parallel or sequential subagents correctly. Verification and evidence live at the stage level — one verification command and one evidence block per stage, gating the move to the next stage.

Violating the letter of the rules is violating the spirit of the rules.

Do NOT hand off to `execution` until (1) every ADDED and MODIFIED requirement in the delta maps to at least one task, (2) stages are declared with the canonical subagent phrasings, (3) every stage declares a Stage Verification command and expected outcome, (4) AGENTS.md has been read in every directory the plan will touch and relevant notes captured in `tasks.md`, (5) every task carries a `Dispatch` value (`inline` or `subagent`), and (6) the user has approved `tasks.md` in writing. This is the SOLE approval gate in the superspec workflow; `review-changes` hands findings inline to this stage for inclusion in the Review summary appendix.

Running plan-review itself as a subagent

For broad changes — multiple domains touched, meaningful AGENTS.md surface, or a coordinator session that has accumulated significant prior context — the coordinator MAY dispatch plan-review itself as a subagent. The subagent's job ends at producing a draft tasks.md (including the Review summary appendix) and returning it to the coordinator.

The user-approval gate stays with the coordinator. A plan-review subagent MUST NOT attempt to gather approval; it returns the draft and the coordinator presents it. Default to running plan-review inline for single-domain or small-surface changes.

The Iron Law

NO TASK WITHOUT A REQUIREMENT IT IMPLEMENTS FIRST

When to Use

Always:

• A change has been validated by review-changes (inline findings handed off) and has no tasks.md yet.
• tasks.md needs revision because a task was identified as missing, redundant, or dependency-misordered.

Exceptions: none.

AGENTS.md Discovery

plan-review is the only stage that reads AGENTS.md. Notes are captured in tasks.md and forwarded to execution and code-review via that file. No later stage re-reads AGENTS.md files.

Before writing any task, read AGENTS.md in every directory the plan will touch:

• Repo root
• docs/specs/ and each affected domain's docs/specs/{domain}/AGENTS.md
• Every source directory a task will modify (e.g., proto/AGENTS.md, src/frontend/AGENTS.md, src/server/AGENTS.md)

Capture notes about pattern exceptions, ambiguous dependencies, local conventions. Record them in tasks.md under the ## AGENTS.md Notes section. Cite specific notes in the tasks that must apply them.

Subagent Dispatch Phrasings (canonical, verbatim)

tasks.md MUST use these exact phrasings inside stage descriptions:

• Sequential stage: "Wait for the results from prior tasks before starting dependent sub agent tasks."
• Parallel stage: "Batch execute tasks that can be run in parallel sub agents."

Do not paraphrase. execution keys off these phrases.

See references/subagent-dispatch.md for prompt construction and status codes. See references/dependency-patterns.md for worked examples.

Per-Task Dispatch Mode (inline vs subagent)

Plan-review is where the inline-vs-subagent decision is made, not execution. Every task in tasks.md carries a Dispatch field with one of:

• inline — the executing agent implements the task directly in the current session.
• subagent — execution dispatches a subagent with a constructed prompt.

Default for broad changes is subagent. When in doubt, choose subagent.

Choose subagent when the task benefits from:

• Context isolation — the coordinator session has accumulated noise (prior research, unrelated debugging) that would bias or crowd the implementer.
• A well-bounded file set the stage verification will exercise — the subagent does not need to discover scope.
• Parallelism with a sibling task in the same stage — two or more tasks can proceed without shared files.
• A stronger or differently-suited model than the coordinator session is using.

Choose inline when the task:

• Is mechanical or obvious within the coordinator's current context.
• Requires rapid back-and-forth with the user.
• Has no sibling it could run in parallel with, and no context-isolation benefit.

These signals are qualitative on purpose. Judgement is yours; record a brief rationale in the task's Dispatch rationale field only when the choice is non-obvious.

Tie-break: if a task qualifies for both modes and a sibling task in the same stage is a clear subagent candidate, choose subagent so the stage can batch. A lone task in its own stage with no isolation benefit should be inline.

Independence check for parallel stages: before assigning two tasks to the same parallel stage as subagent, confirm they write to disjoint file sets. If they share a file, they belong in a sequential stage.

Stage-Level Verification

Each stage carries ONE Stage Verification block:

• Command(s): exact command(s) to run at the stage boundary after every task in the stage is implemented.
• Expected outcome: what passing looks like (exit code, test count, log line, artifact present).
• Evidence artifact: where output will live (path inline in tasks.md or a referenced file).

Tasks within a stage carry Implements, Depends on, Files, and Approach. Tasks do not carry their own verification or status. The stage's checkbox flips to - [x] once the stage verification passes and the Evidence block is recorded.

Verification commands SHOULD be additive so that passing means every task in the stage behaved correctly (e.g., go test ./auth/... exercises all auth tasks rather than one file).

Process

1. Read the delta specs. Capture inline review-changes findings from the handoff context for the Review summary appendix. Confirm Change Overview is present in the delta.
2. Read AGENTS.md in every directory the plan will touch. Capture notes for tasks.md.
3. Enumerate requirements. List every ADDED and MODIFIED requirement by domain.
4. Identify dependency boundaries. What must complete before what? Typical boundaries:
   • Proto/schema changes → codegen → dependent code
   • DB migrations → code using migrated schema
   • API contract → client + server (then can run in parallel)
   • Dependency bumps → build → tests
5. Group into stages. Each stage has either the sequential phrasing ("Wait for the results...") or the parallel phrasing ("Batch execute tasks..."). A stage with a single task may omit the phrase.
6. Map requirements to tasks. Every ADDED/MODIFIED requirement MUST appear in at least one task's "Implements" line. Tests go in tasks, not as an afterthought.
7. Assign Dispatch mode. For each task, choose inline or subagent using the criteria above. Within a parallel stage, confirm subagent tasks touch disjoint files. Default to subagent for broad changes.
8. Specify Stage Verification for each stage: command(s), expected outcome, evidence artifact location.
9. Write tasks.md using references/templates/tasks.md, including the Coverage Matrix, AGENTS.md Notes, and Review summary appendix sections.
10. Present tasks.md to the user with the Review summary appendix and request written approval. This is the workflow's sole approval gate.
11. Hand off to execution after approval.

Checklist

You MUST work through each of these items and complete them in order:

1. Delta specs read; review-changes findings captured from handoff context.
2. AGENTS.md files in every affected directory read; notes captured in tasks.md.
3. Every ADDED/MODIFIED requirement enumerated.
4. Dependency boundaries identified.
5. Stages declared with canonical subagent phrasings.
6. Every requirement mapped to ≥1 task via the Coverage Matrix.
7. Every task has a Dispatch value (inline or subagent).
8. Every parallel stage with ≥2 subagent tasks has confirmed-disjoint file sets.
9. Stage Verification specified for every stage.
10. tasks.md saved using the template.
11. Review summary appendix populated with any WARNING/SUGGESTION findings from review-changes (or "None").
12. Written user approval of tasks.md received.
13. Handoff to execution announced.

Common Rationalizations

Excuse	Reality
"Run everything in parallel, it'll be faster"	Parallel work that crosses a dependency boundary corrupts state. Stage properly.
"Refactor / cleanup / etc. — one catch-all task"	Catch-all tasks implement no named requirement. They are prohibited.
"Per-task verification is cleaner"	Verification is stage-level by design. One command, one evidence block, one gate.
"Stage verification is obvious, I don't need to specify it"	'Obvious' verification is skipped verification. Specify the command and expected outcome.
"Dependency boundary is obvious, skip stages"	Agents do not infer dependencies. Declare stages explicitly.
"Tests can go in a separate task group after"	Tests belong with the implementation task that produces the behavior. Not after.

Red Flags — STOP and Revise

• A requirement has no task
• A task has no requirement (except test-only tasks, which must still cite what they verify)
• A task has no Dispatch value
• Two tasks in the same parallel stage could conflict on the same file
• A parallel stage has two subagent tasks that share a file
• A stage has no subagent phrasing and contains multiple tasks
• A stage has no Stage Verification block
• Used informal phrasings like "do these in parallel" or "after this finishes"

All of these mean: go back to the plan structure, fix before handoff.

Anti-Pattern: "The dependency boundary is obvious, skip the stage"

Dependencies are never obvious to execution without declaration. Even if a human can see proto must come before codegen, the plan must declare it — otherwise execution may dispatch parallel subagents that race against each other. Always declare stages.

Example

Excerpt from a realistic tasks.md:

## Stage 1: Schema

Wait for the results from prior tasks before starting dependent sub agent tasks.

### Task 1.1: Update proto definition
- **Implements**: `auth` ADDED Requirement: Admin Two-Factor Authentication
- **Files**: `proto/auth.proto`
- **Approach**: Add TotpConfig message, wire into LoginRequest.
- **Dispatch**: subagent

### Task 1.2: Regenerate code
- **Depends on**: 1.1
- **Files**: `gen/auth/`
- **Approach**: Run `buf generate`; commit generated output.
- **Dispatch**: inline
- **Dispatch rationale**: mechanical codegen step; no isolation benefit.

### Stage Verification

- **Commands**:

buf lint proto/ buf generate git diff --exit-code gen/

- **Expected outcome**: lint passes; generate produces committed output; no diff.
- **Evidence artifact**: inline in this stage's Evidence block.

- [ ] Stage 1 complete

---

## Stage 2: Implementation

Batch execute tasks that can be run in parallel sub agents.

### Task 2.1: Server TOTP validator
- **Implements**: `auth` ADDED Requirement: Admin Two-Factor Authentication
- **Files**: `src/server/auth/totp.go`, `src/server/auth/totp_test.go`
- **Approach**: RFC 6238 TOTP with 30s window; clock skew +/- 1 step.
- **Dispatch**: subagent

### Task 2.2: Frontend admin login flow
- **Implements**: `auth` ADDED Requirement: Admin Two-Factor Authentication
- **Files**: `src/frontend/admin/login.tsx`, `src/frontend/admin/login.test.tsx`
- **Approach**: Add TOTP input step after password; surface validation errors inline.
- **Dispatch**: subagent

### Stage Verification

- **Commands**:

go test ./src/server/auth/... bun test src/frontend/admin/

- **Expected outcome**: both suites green; no skipped tests.
- **Evidence artifact**: inline in this stage's Evidence block.

- [ ] Stage 2 complete

Verification Checklist

• Every ADDED/MODIFIED requirement appears in an "Implements" line somewhere
• Every stage uses a canonical subagent phrasing (or is a single task)
• No parallel stage has tasks that touch the same file
• Every task has a Dispatch value (inline or subagent)
• Every stage has a Stage Verification block with command + expected outcome
• AGENTS.md notes section populated
• Written user approval recorded

Integration

Terminal state is invoking execution. Do NOT invoke code-review.

REQUIRED SUB-SKILL: Use execution once tasks.md is approved.