| name | sdd |
| description | Spec-driven development workflow for projects that use spec files as both product spec and manual. Use when writing specs, implementing tasks from specs, or updating docs after code changes. |
| disable-model-invocation | false |
Spec-Driven Development
No code without a spec. The spec is both the blueprint for the work and the manual for the result.
Cycle
- Spec — describe what needs to be built as a task in a spec file (
docs/specs/*.md)
- Build — implement the task
- Document — after the task is done:
- Mark the task
[x] and add **Implemented:** bullets inside the task body
- Update the feature description above
# Tasks based on what was implemented
Spec structure
Each spec file has two parts:
- Feature description (top) — what the product does, how to use it
- Task journal (bottom) — starts with
# Tasks; story groups under it use ## headings
The feature description is the manual.
A reader should understand what's available and how to use it without reading the tasks.
Example
Imagine building a smart kettle app.
Step 1 — Spec
We start by creating a spec file with tasks. No code yet, just the spec:
# Brewing — Smart Kettle
Wi-Fi kettle with app control.
# Tasks
- [ ] KTL-001 Basic boiling with auto shut-off
Basic boiling makes the kettle useful before advanced presets exist.
Heat to 100°C, beep on completion.
Physical button and app trigger.
Auto shut-off after timeout.
- [ ] KTL-002 Tea presets
Tea presets save users from remembering common brewing temperatures.
Predefined temperature + steep time for common tea types.
Allow user-created custom presets.
- [ ] KTL-003 Schedule boiling
Scheduling makes hot water ready for planned routines.
Set a time for the kettle to start automatically.
Morning routine: wake up to ready water.
No feature description yet — nothing is built.
Step 2 — Build and document KTL-001
We implement boiling. After the task is done, two things happen:
- The task gets marked
[x] with an **Implemented:** block
- A feature description appears above
# Tasks
# Brewing — Smart Kettle
Wi-Fi kettle with app control.
## Boiling
Tap "Boil" in the app or press the physical button. Heats water to 100°C,
beeps when done. Auto shut-off after 5 minutes.
# Tasks
- [x] KTL-001 Basic boiling with auto shut-off
Basic boiling makes the kettle useful before advanced presets exist.
Heat to 100°C, beep on completion.
Physical button and app trigger.
Auto shut-off after timeout.
**Implemented:**
- Heats to 100°C with ±1° accuracy
- Dual trigger: hardware button and app "Boil" command
- Auto shut-off after 5 minutes of inactivity
- [ ] KTL-002 Tea presets
Tea presets save users from remembering common brewing temperatures.
...
- [ ] KTL-003 Schedule boiling
Scheduling makes hot water ready for planned routines.
...
Step 3 — Build and document KTL-002
Tea presets is a different feature — it gets its own section:
# Brewing — Smart Kettle
Wi-Fi kettle with app control.
## Boiling
Tap "Boil" in the app or press the physical button. Heats water to 100°C,
beeps when done. Auto shut-off after 5 minutes.
## Tea presets
Three built-in presets:
- Green tea — 75°C, 2 min steep reminder
- Black tea — 95°C, 4 min steep reminder
- Herbal — 100°C, 6 min steep reminder
Custom presets: Settings → Presets → Add. Set temperature (40–100°C)
and steep time (1–15 min).
# Tasks
- [x] KTL-001 Basic boiling with auto shut-off
Basic boiling makes the kettle useful before advanced presets exist.
...
- [x] KTL-002 Tea presets
Tea presets save users from remembering common brewing temperatures.
Predefined temperature + steep time for common tea types.
Allow user-created custom presets.
**Implemented:**
- Three built-in presets (green, black, herbal)
- Custom presets via Settings → Presets → Add
- Temperature range 40–100°C, steep time 1–15 min
- [ ] KTL-003 Schedule boiling
Scheduling makes hot water ready for planned routines.
...
KTL-003 is still open — no "Scheduling" section yet. It will appear when the task is done.
When to create a new section vs update an existing one
- New feature → new section. KTL-001 created
## Boiling, KTL-002 created ## Tea presets.
- Extends existing feature → update the section. If a task added temperature selection to boiling, it would update
## Boiling, not create a new section.
The rule: match the section to the feature, not to the task.
What goes in a task
How to write a task — the format and what belongs in the body — lives in the mdtask skill, the single source. sdd adds only the rhythm: a task is the spec, written before the code, and documented once it's built (see the Cycle above).
