sethdford /spec — Three-File Spec Workflow
/spec <feature-name> walks through requirements → design → tasks, then sets up the verification gate.
The three files
All under <project>/specs/<feature-name>/:
| File | Purpose | Lifecycle |
|---|---|---|
requirements.md |
User stories + acceptance criteria | Written first, treated as the contract |
design.md |
Architecture: components, data flow, decision rationale | Written after reqs, before tasks |
tasks.md |
Numbered list of implementable units, each maps to ≥1 acceptance criterion | Written last, drives execution |
The flow
1. requirements.md
Format:
# <feature> — Requirements
## User stories
- As a <role>, I want to <action>, so that <outcome>.
- ...
## Acceptance criteria
- [ ] AC-1: <testable behavior>
- [ ] AC-2: <testable behavior>
- ...
## Non-goals
- <what this feature does NOT do, to prevent scope creep>
## Constraints
- <perf budget, deps allowed/disallowed, compat surface, etc.>
Each AC must be one sentence and testable. "Robust error handling" is not an AC. "Returns 400 with {error: ...} for malformed JSON" is.
2. design.md
Format:
# <feature> — Design
## Components
- <name>: <what it does> — <where it lives>
- ...
## Data flow
1. <step>
2. ...
## Decisions
- **<decision>**: chose <option A> over <option B> because <reason>
- ...
## Risks
- <thing that could go wrong> — <mitigation>
Each Decision must reference one or more ACs it serves. If a decision doesn't tie to an AC, either the AC is missing or the decision is unjustified.
3. tasks.md
Format:
# <feature> — Tasks
| # | Task | ACs | Owner | Status |
|---|---|---|---|---|
| 1 | <imperative description> | AC-1, AC-2 | <agent or person> | pending |
| ... |
## Dependencies
- Task N depends on Task M
- ...
Each task maps to ≥1 AC. Each AC is covered by ≥1 task. If you can't make this map, the spec is incomplete.
Your protocol
Phase 1 — Requirements (with user)
- Distill the user's stated goal into 3–8 acceptance criteria.
- List the obvious non-goals (things you'd be tempted to add but shouldn't).
- Surface constraints the user implied (perf, security, compat).
- Show requirements.md to user for approval. Do not proceed without it.
Phase 2 — Design
- Write design.md based on the approved requirements + your read of the codebase.
- Use Plan Mode (Shift+Tab×2) before writing the design — let it spawn parallel subagents to explore relevant files.
- Every Decision tags ≥1 AC.
- Show design.md to user for approval before tasks.
Phase 3 — Tasks
- Decompose into independently verifiable units.
- Each task: imperative description, ACs covered, dependencies, owner.
- Tag tasks for
/teamif multi-agent dispatch makes sense.
Phase 4 — Hand off
- If the user wants to implement now: kick off
/teamwith the tasks list, OR proceed sequentially yourself. - The
spec-verifieragent will be spawned by the Stop hook to confirm impl satisfies spec before session close.
Verification at completion
Once implementation is done, spawn spec-verifier:
Agent({
description: "Verify spec satisfaction",
subagent_type: "spec-verifier",
prompt: "Spec at <path>. Impl at <files>. For each AC: does the implementation prove it? Output RESULT_spec-verifier=..."
})
If RESULT_spec-verifier=FAIL for any AC, the work isn't done — surface gaps, file new tasks.
When NOT to use /spec
- Single-file fixes — overhead exceeds value
- Refactors with no behavior change — use
/teamdirectly - Exploratory spikes — write a throwaway, commit nothing, spec the keeper afterwards
Anti-patterns to refuse
- Writing all three files in one shot without user review between phases
- Writing a design before requirements are signed off
- Tasks that don't map to ACs (these are wishful work)
- ACs that aren't testable ("works well", "is performant", "is intuitive")