Process
SDD Workflow
The path from feature idea to verified implementation — each step enforces clarity before speed.
- 1
Feature idea
A need emerges
- 2
shape-spec
Structured conversation — clarify, don't assume
- 3
requirements.md
Living doc — stories, criteria, open items
- 4
Clarification Gate
Open items = 0?
- 5
Generate & implement
Tasks, plans, prompts, code
Gate condition: open items = 0 → then generate tasks & implement
Development Stages
From intent to verified software — each stage has a clear question, artifact, and output. Never skip ahead: spec before plan, plan before tasks, tasks before code.
Stage 1
Specification
Capture intent before any implementation. Use shape-spec to clarify requirements, write user stories, define acceptance criteria, and resolve all open items through the Clarification Gate.
Artifact
requirements.md · shaped specAnti-pattern
Skipping straight to prompts — vibe-coding without a spec
Outputs
- User stories with success criteria
- Acceptance criteria and data contracts
- Zero open items (Clarification Gate passed)
Specification → Plan → Tasks → Code → VerifyStage Reference
Specification
What must be built?
Capture intent before any implementation. Use shape-spec to clarify requirements, write user stories, define acceptance criteria, and resolve all open items through the Clarification Gate.
Plan
How will we build it?
Translate the approved spec into a structured plan. Define milestones, dependencies, technical approach, and the order of work — still without writing feature code.
Tasks
What are the concrete steps?
Break the plan into small, actionable, ordered tasks. Each task should trace back to a user story or acceptance criterion — executable enough for AI or a developer to pick up and run.
Code
Build it — does it match the spec?
Implement against the spec and tasks — not against vibes. Code is the output of clear intent, not the source of truth. When code and spec diverge, fix the code.
Verify
Does it match what the spec says should happen?
Validate against the spec — not against what the code happens to do. Run acceptance criteria, behaviour checks, and review open items are still resolved.
Shaping Workflow
Feature idea
A need emerges — but resist the urge to prompt-and-pray.
shape-spec
Structured conversation: frame the problem, map the journey, define contracts, capture open items.
requirements.md
Living document with user stories, acceptance criteria, and open items — committed to the repo.
Clarification Gate
Hard stop: open items must equal zero. Ambiguity is not carried forward.
Generate & implement
Tasks, plans, and AI prompts derived from the spec — then code, then verify against spec.
Remember: What does the spec say should happen — not what does the code happen to do. Verify implementation against the spec, not the other way around.