| name | plan |
| description | Runs the implementation planning stage: writes plan.md (test strategy + task list) and scenarios.yml (QA replay scenarios) from an approved design.md, then reviews the plan via belt:spec-reviewer. Use standalone when a design already exists, or composed between the design and build stages of /belt:feature-dev. --codex enables adversarial plan review. |
| user-invocable | true |
| argument-hint | [--codex] |
plan
Belt pipeline for the implementation planning stage. Structure, gates,
and done criteria live in pipeline.yml; this file defines how to
execute each phase.
Entry check
docs/features/<topic>/goal-sheet.md and docs/features/<topic>/design.md
must exist. In a composed run resolve them via belt-agent status
artifacts; standalone, take the most recently modified glob match. If
either is missing, stop and ask the user.
Phase: plan
This phase has no invoke — execute these steps directly:
- Read goal-sheet.md and design.md.
- Write
docs/features/<topic>/plan.md with exactly these sections:
## Test Strategy — for each acceptance criterion in
goal-sheet.md, the test(s) that verify it (level:
unit/integration/qa + test name)## Tasks — checkbox list; every task names its target files and
its test
- Write
docs/features/<topic>/scenarios.yml — at least one scenario
per acceptance criterion, schema below.
- Append the plan entry to evidence.md.
Phase: plan-review
The invoke is declared in pipeline.yml; pass the plan.md path as the
review target and findings-plan as the output artifact. Complete the
review's batched triage, then append the plan-review entry to
evidence.md.
If a finding contests an approved design decision, do not edit
design.md — present the finding to the user as an objection to the
approved design; on acceptance, re-run the design stage standalone.
scenarios.yml schema
setup: # required if any scenario is kind: browser
start: "pnpm dev" # launch command; omit when nothing to launch
url: "http://localhost:3000"
teardown: auto # auto = QA kills processes it started
scenarios:
- id: login-ok # kebab-case, unique in this file
kind: browser # browser | cli
given: "a registered user on the login page"
when: "they submit valid credentials"
then: "the dashboard is shown"
For kind: cli, when is the exact command to run and then states
the expected stdout, exit code, or produced files.
Red flags
- Never write a task without file paths — build dispatches subagents
from this list alone.
- Never leave an acceptance criterion without both a Test Strategy row
and a scenario.
- Never author a
kind: browser scenario without a setup: block.
- Never hand-edit files under
docs/features/<topic>/ after a phase
completes (breaks the phase-start mtime filter).
References
../design/references/path-convention.md — naming rules (SSOT)plugins/belt-agent/references/authoring-principles.md — evidence entry format
