Spec-Driven Development (SDD)

Core Philosophy

1. Clarity before Code: Never generate code until requirements and design are approved.
2. Iterative Refinement: Loop through Req → Design → Tasks until solid.
3. Code via Docs: The truth is in the markdown files, not the chat.

Commands

Execute in the project root (where spec/ and steering/ live).

init

Scaffold the SDD folder structure and template files.

1. If spec/ already exists, skip or ask before overwriting.
2. Create spec/ and steering/.
3. Create spec/intent.md (blank or minimal placeholder).
4. Copy templates from this skill’s templates/ directory (in the same folder as SKILL.md, or from your install path under ~/.cursor/skills/sdd/ after copying the skill there) into the project:
   • templates/spec/requirements.md → spec/requirements.md
   • templates/spec/design.md → spec/design.md
   • templates/spec/tasks.md → spec/tasks.md
   • templates/steering/coding-standards.md → steering/coding-standards.md

reqs

Generate EARS requirements from intent.

1. Read spec/intent.md and steering/*.md.
2. Convert the intent into EARS requirements (see EARS Quick Reference below). Add a Properties (invariants) section.
3. Write to spec/requirements.md.
4. Ask for user approval before proceeding.

design

Generate technical design from requirements.

1. Read spec/requirements.md and steering/*.md.
2. Create a technical design: architecture, data models, component interfaces, error handling, security. Apply the Design Checklist below.
3. Write to spec/design.md.
4. Ask for user approval before proceeding.

tasks

Generate implementation tasks from design.

1. Read spec/design.md and spec/requirements.md.
2. Create a sequential task list: max two levels (Task > Subtask). Link each task to requirement IDs (e.g. REQ-001). Follow Task Rules below.
3. Write to spec/tasks.md.
4. Ask for user approval before proceeding.

status

Report current state of the spec.

1. List files in spec/ (and optionally steering/).
2. If spec/tasks.md exists, count unchecked [ ] vs checked [x] and summarize.

EARS Quick Reference

• Ubiquitous: <system> shall <response>
• Event-Driven: WHEN <trigger> [precondition] the <system> shall <response>
• Unwanted: IF <unwanted condition> THEN the <system> shall <response>
• State-Driven: WHILE <system state>, the <system> shall <response>
• Optional: WHERE <feature is included>, the <system> shall <response>

Use IDs like [REQ-001]; add a Properties (Invariants) section for universal correctness statements.

Design Checklist

• Edit ruthlessly (remove over-engineering).
• Check for circular dependencies; fix via interface extraction, layering, or events.
• Ensure alignment with steering documents.

Task Rules

• Two-level hierarchy maximum (Task > Subtask).
• Sequential order (each task builds on previous).
• Traceability: each task or subtask links back to requirement IDs (e.g. Traceability: Implements REQ-001).

Additional Resources

• For full framework detail (workflow, refinement, iteration triggers), see reference.md.