| name | run-plan |
| description | Execute a spec-driven plan from specs/plans/ following the repo's execution protocol. Usage: /run-plan v0.7 [phase N] |
Run a spec plan
Packages the execution protocol from specs/README.md and specs/SPEC.md §5.
Argument: the plan version (v0.7, v0.8, v0.9, v1.0). Optional phase N to target
a specific phase. With no argument, list the plans in specs/plans/ with their Status
headers and ask which to run.
Protocol — follow in order, do not skip
- Read
specs/GUARDRAILS.md. Hard rules, ripple effects, troubleshooting. It
overrides everything except direct user instructions. A plan never overrides it.
- Read
specs/SPEC.md §5 (execution protocol).
- Read the plan file top to bottom. Its Context primer replaces repo analysis —
trust it, don't re-derive the codebase.
- Verify entry state with the commands the plan lists (cheap, < 1 min). If they
fail, fix entry state or stop. Never build on a broken base.
- Work phase by phase, starting at the first unchecked phase (or the requested one).
Check off each task's checkbox in the plan file as you complete it.
- Copy code shapes from
specs/patterns/ — component anatomy, form-control contract
tests, overlay tests, docs pages. Do not invent shapes.
- After each meaningful unit run the narrow check first
(
pnpm vitest --run <file>), then the full suite before any commit.
Scope discipline
- Never expand scope. Work belonging to a later minor goes as a note in that plan
file — you do not do it.
- Blocked or unsure for more than ~15 minutes on one decision? Write it under an
## Open questions heading at the bottom of the plan file (create the heading if
missing), take the most conservative interpretation or skip the task, and continue.
- Never invent APIs. Never delete a test to make CI pass. Never loosen an assertion to
go green.
- No new npm dependency without writing the justification into the plan file first.
Stopping cleanly
Phases are sized so a session can finish at least one and stop. Before you finish:
- Run the plan's verification commands.
- Update the plan's Status header —
not started / in progress — phase N / done.
- Update
CHANGELOG.md under [Unreleased] if the minor isn't released yet.
- Report: phases completed, what's left, and any Open questions you recorded.
Audit phases write their findings into the plan file itself — that is what lets the
next session resume with full context. Do not report audit findings only in chat.
Release gate
Every plan ends with the same gate. Only run it if the plan says to, and only after the
user confirms:
pnpm release:check
Then version bumps, CHANGELOG, COMPONENT_STATUS.md. Never publish to npm or deploy
unless the plan's release phase explicitly says so and the user confirms
(GUARDRAILS rule 11). Commits use conventional style (feat:, fix:, test:,
docs:, chore:); do not push unless asked.
