| name | spec |
| description | Creates or resumes a spec in docs/ai/specs/ following the SDD-WORKFLOW Phase 2 contract. Use at the start of any non-trivial task — anything beyond a typo, a doc tweak, or a one-line bug fix with an obvious cause. |
| disable-model-invocation | true |
Spec
Per docs/ai/SDD-WORKFLOW.md, non-trivial work gets a spec before any code. The spec doubles as
the resume point when a session dies mid-task, which is the main reason it exists.
First: is there already one?
ls docs/ai/specs/
grep -l "Status:.*\(draft\|approved\|in-progress\)" docs/ai/specs/*.md
If a spec covers this task, resume it — read it, find the first unticked step, continue there.
Do not start a new one. Restarting is the expensive failure mode this workflow exists to prevent.
Creating a new spec
- Next number = highest existing
NNN + 1, zero-padded to three digits.
- Copy the template, do not retype it:
cp docs/ai/specs/_TEMPLATE.md docs/ai/specs/NNN-short-name.md
- Fill in every section. Set
Created and Last updated to today's real date.
The sections that actually catch errors
- Out of scope — name specific files, APIs, and behaviors you will not touch. A vague "no
refactors" is not out-of-scope;
engines/waapi-player.ts is.
- Acceptance criteria — each one checkable by a command or a named manual step. "Works
correctly" is not a criterion. "
pnpm e2e passes and /demos/drag respects snap points" is.
- Breaks public API — if yes, you must get explicit user approval before implementing
(SDD-WORKFLOW Phase 2.3). Run the
public-api-guard agent if you are unsure whether it breaks.
Scope check before writing
docs/ai/CONTEXT.md lists non-goals and docs/ai/STATE.md lists known gotchas. If the task
contradicts either, stop and ask the user — do not spec around it.
Read the code you will touch before proposing anything: the target files, their colocated
.spec.ts, and one similar existing implementation. For a new interaction directive that means
reading move-hover.directive.ts end to end — it is the canonical pattern.
While implementing
Tick the checkboxes as you go, in spec order. When done, set Status: done, mark acceptance
criteria ✅/❌, and fill in Verification notes with the commands you actually ran and their real
results. Anything you deliberately skipped goes in Follow-ups, not silently omitted.
