execution

name	execution
description	Use when docs/specs/changes/{name}/tasks.md is user-approved and contains stages with unchecked stage-completion boxes, when about to write implementation code for a planned change, or when resuming work on a change with partially-complete stages — implements tasks one stage at a time, dispatching subagents in parallel or sequential batches as the plan specifies, running one Stage Verification at each stage boundary and recording one Evidence block per stage.
metadata	{"tags":["tech:markdown","spec-driven","workflow","execution"]}

Execution

Overview

Implement the approved plan one stage at a time. Within a stage, implement every task (inline or via subagent). At the stage boundary, run the stage's Stage Verification command and record one Evidence block per stage. Never modify stable specs directly, never invent requirements, never claim a stage complete without verification evidence. Forward AGENTS.md notes from tasks.md — do not re-read AGENTS.md (that happened in plan-review).

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

Do NOT modify `docs/specs/{domain}/spec.md` (stable specs) during execution — those are updated only by `code-review` during delta merge.

Do NOT invent new requirements in code. If execution discovers a missing or changed requirement, STOP and return to writing-specs.

Do NOT mark a stage complete without running its Stage Verification command and recording the evidence.

The Iron Law

NO CODE WITHOUT A TASK IT IMPLEMENTS FIRST

When to Use

Always:

• tasks.md is approved and has unchecked stage boxes.
• A prior execution session left a stage unfinished.

Exceptions: none. Even a trivial one-line change during execution must trace to a task.

AGENTS.md Notes (forwarded)

AGENTS.md files were read during plan-review and the relevant notes were captured in the ## AGENTS.md Notes section of tasks.md. Forward these notes into subagent prompts when a task cites them. Do NOT re-read AGENTS.md files from disk — use the notes in tasks.md as the source of truth.

If a task surfaces a gap that no captured AGENTS.md note covers and the work genuinely needs local-convention context that wasn't captured, STOP and return to plan-review to amend the notes.

Process

1. Open tasks.md. Identify the next unchecked stage. Stages are completed in order.
2. Read the stage's phrasing to determine dispatch mode:
   • "Wait for the results from prior tasks before starting dependent sub agent tasks." → sequential. Implement tasks one at a time within the stage.
   • "Batch execute tasks that can be run in parallel sub agents." → dispatch independent tasks at once.
   • No phrasing and single task → run inline.
3. For each task in the stage:
   • Read the task's Dispatch field (inline or subagent) — set by plan-review. Do NOT re-derive this decision. If the field is missing, STOP and return to plan-review.
   • If subagent: construct a prompt that embeds the full task text, relevant requirement block(s) from the delta, AGENTS.md notes from tasks.md cited by this task, and the status-code protocol. Subagents do NOT run stage verification; they write code and tests and return DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT.
   • If inline: implement directly. Make minimal, focused changes. Write tests alongside behavior. Do not expand scope.
4. Collect subagent statuses (if any were dispatched). Resolve BLOCKED / NEEDS_CONTEXT / DONE_WITH_CONCERNS before the stage boundary.
5. Run Stage Verification exactly as specified in the stage's Stage Verification block. Capture output.
6. Record stage evidence in tasks.md:
   • Append one Evidence block to the stage (see references/templates/stage-evidence.md).
   • Include: date, commands run, verbatim output, all files changed across the stage, AGENTS.md notes applied, aggregated subagent statuses.
   • Mark the stage - [x].
7. Assess stage outcome:
   • Pass → move to the next stage.
   • Stage verification failed → diagnose; rework the offending task(s); re-run stage verification.
   • Discovered missing/shifted requirement → STOP. Return to writing-specs.
8. All stages complete → hand off to code-review.

Handling Subagent Status Codes

Status	Action
DONE	Implementation and tests written. Proceed to stage boundary; verification runs there.
DONE_WITH_CONCERNS	Read concerns; decide to accept (record rationale in stage Evidence), rework, or escalate.
BLOCKED	Assess: context (re-dispatch with more context), reasoning (re-dispatch with a stronger model if available), plan (return to plan-review), or requirement (return to writing-specs).
NEEDS_CONTEXT	Provide missing info; re-dispatch. Do not assume the subagent can infer.

Never re-dispatch the same subagent with the same prompt without changing something.

Checklist (per stage)

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

1. Prior stage confirmed - [x] before starting this stage.
2. Stage phrasing read; dispatch mode determined.
3. For each task in the stage: Dispatch value read from tasks.md; no re-derivation.
4. (If subagent) prompts constructed with task text + requirement(s) + AGENTS.md notes (from tasks.md) + status-code protocol. No per-task verification command included — verification runs at stage boundary.
5. All tasks in the stage implemented; subagent statuses collected and resolved.
6. Tests written alongside implementation behavior.
7. Stage Verification command(s) run; output captured verbatim.
8. Stage Evidence block appended to tasks.md using the template.
9. Stage marked - [x].

Common Rationalizations

Excuse	Reality
"I can patch the stable spec while I'm here"	Stable specs are merged only by code-review. Stop.
"Parallel everything for speed"	Parallel across a dependency boundary corrupts state. Respect stages.
"This task is small, skip it and run stage verification"	Every task in the stage implements a requirement. Skipping one means the requirement is unimplemented.
"Stage verification passed on my machine — skip capturing output"	Evidence is how code-review verifies without re-running. Always capture verbatim.
"I noticed a missing requirement, I'll add it in code"	STOP. Return to writing-specs. Requirements live in specs, not code.
"Subagent returned DONE, that means the feature works"	DONE means implementation and tests were written. Stage verification at the boundary confirms it actually works.
"Per-task evidence would be more traceable"	Evidence is stage-level by design. One block per stage, one gate per stage.
"The task doesn't say inline or subagent, I'll pick"	Dispatch is plan-review's call. Stop and return to plan-review.

Red Flags — STOP

• Editing docs/specs/{domain}/spec.md directly
• Writing implementation that has no matching task in the current stage
• Marking a stage - [x] without running Stage Verification
• Dispatching parallel subagents that share files
• Scope creep: making "related" changes not in any task
• Subagent returned DONE but file hasn't changed
• Starting a new stage with the prior stage still - [ ]
• A task has no Dispatch value (return to plan-review; do not guess)

All of these mean: stop, revert the scope creep, or escalate.

Anti-Pattern: "Parallel everything for speed"

Stages exist because dependencies exist. Running parallel subagents across a stage boundary means later subagents read stale state. The plan's parallel phrasing only applies within a stage, and within a stage only to tasks the plan declared independent.

Anti-Pattern: "This task is too small to need a subagent"

Correct — inline execution is fine for small tasks. But "small" does not mean "skip the stage verification." Even a one-line fix belongs to a stage, and the stage's verification still runs and its evidence still gets recorded.

Example

Stage Evidence block appended after a stage completes:

## Stage 2: Implementation

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

### Task 2.1: Server TOTP validator
...

### Task 2.2: Frontend admin login flow
...

### Stage Verification

- **Commands**:

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

- **Expected outcome**: both suites green; no skipped tests.

#### Evidence

- **Date**: 2026-04-17
- **Commands**:

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

- **Output**:

ok example.com/server/auth 0.045s

bun test v1.1.x 8 pass 0 fail 12 expect() calls

- **Files changed (across the stage)**:
- `src/server/auth/totp.go`
- `src/server/auth/totp_test.go`
- `src/frontend/admin/login.tsx`
- `src/frontend/admin/login.test.tsx`
- **AGENTS.md notes applied**: server/AGENTS.md "always return typed errors" (Task 2.1)
- **Subagent statuses**:
- Task 2.1: DONE
- Task 2.2: DONE

- [x] Stage 2 complete

Verification Checklist

• Every completed stage has one Stage Evidence block
• No stable spec files were modified
• No requirements were invented
• Stage boundaries were respected
• Subagent status codes acknowledged
• AGENTS.md notes forwarded from tasks.md (no ad-hoc re-reads)

Integration

Terminal states:

• All stages complete: invoke code-review automatically. This is self-review — no approval gate exists here. Do NOT ask the user "should I proceed to code-review?"
• Requirements shifted or a new requirement surfaced: invoke writing-specs.

Do NOT invoke code-review with stages still unchecked.

REQUIRED SUB-SKILL: Use code-review immediately once all stages are - [x] with evidence. Do NOT ask the user to proceed — just invoke it. REQUIRED BACKGROUND: See plan-review/references/subagent-dispatch.md for prompt construction.