Sdd

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.

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.

Spec-Driven Development (SDD) Framework Extraction

Core Philosophy (Image 5, 13)

• Clarity before Code: Invest time to understand what to build.
• Iterative Refinement: Capture the evolution of the idea.
• Code via Docs: Move from ephemeral chat to persistent, shareable documents.
• Goal: AI under control. Specification driven lifecycle.

The Workflow (Image 3, 6, 15, 17)

1. The Vibe (Exploration): Use "vibe coding" (casual chat) to explore and experiment. Get a handle on what you really want. 2. Intent: "Spec-driven development" starts here. The output of "The Vibe" becomes the input for the Spec. 3. Opinionated Workflow (The "Spec" Loop):

• Requirements: Generate concrete, measurable requirements (EARS syntax).
• Design: Create initial design (Architecture, Data Models, Interfaces).
• Tasks: Define sequential, testable tasks.
• Loop: Iterate, Refine, Approval at each step.

4. Implementation:

• Generate code from tasks.
• Test/QA.
• Fix Issues (Loop back if needed).

5. Deployment & Maintenance.

Detailed Components

1. Context & Steering (Image 1, 7)

• Concept: "Steering Documents" align the AI with the Intent.
• Smart Context: Automatic, Pattern Match, or Manual.
• Strategies:
• Start small (core needs only).
• Use descriptive names (e.g., api-rest-conventions.md).
• Examples are key: Code snippets, input/outputs, style guides.
• Security First: No secrets in steering docs.

2. Requirements (Image 9, 10, 18, 22)

• Format: EARS (Easy Application Requirements Syntax). Optimized for LLMs.
• Ubiquitous: <system> shall <response>
• Event-Driven: WHEN <trigger> then <system> shall <response>
• Unwanted: IF <unwanted> THEN <system> shall <response>
• State-Driven: WHILE <state>, <system> shall <response>
• Optional: WHERE <feature>, <system> shall <response>
• Refinement:
• Review: Get stakeholder feedback.
• Identify Gaps: Missing scenarios?
• Clarify Ambiguities: Resolve vague/conflicting reqs.
• Edge Cases: Add missing details and error handling.
• Properties: Define invariants/correctness properties. "Universal statements about how system should behave" (Image 18).

3. Design (Image 8, 20, 21)

• Content: Architecture, Components, Interfaces, Data Models, Error Handling, Test Strategy, Security, Perf.
• Refinement:
• Include Examples: Help steer the AI.
• Edit Ruthlessly: LLMs over-engineer. Cut the fluff.
• Check Missing Items: Components or details dropped?
• Alignment: Does it match steering?
• Circular Dependencies: Watch out for them. Fix via Interface Extraction, Layering, or Decoupling (Events).

4. Tasks (Image 2, 4, 14, 41)

• Structure:
• Two-Level Max: Top-level tasks + sub-tasks. No deep nesting.
• Logical Grouping: Meaningful categories.
• Sequential: Build on previous work.
• Traceability: Link tasks back to Requirement IDs (e.g., Requirements: 1.1, 5.4).
• Dependency Management:
• Technical: Components that must exist first (e.g., DB models before endpoints).
• Logical: Features that conceptually build on others (e.g., User Reg before Profile Edit).
• Data: Tasks requiring specific state (e.g., Transaction history requires Transaction data).
• Prioritization:
• Core First: Essential functionality.
• Risk First: Uncertain/complex tasks early.
• Value First: High value, testable quickly.

Comparison (Image 19)

• vs TDD: SDD is higher level (business reqs + system design).
• vs Waterfall: SDD is iterative within phases. Living docs. Optimized for feature-level dev.
• vs BDD: SDD uses explicit requirements gathering (EARS) + AI-focused structure.

Iteration & Maintenance (Image 22)

Triggers for updating your specification: 1. Clarification: Minor updates for precision (no functional change). 2. Changes: New requirements or modifications to existing ones. 3. Discoveries: Implementation details (tech constraints) found during coding that force design changes. 4. Technical Constraints: Library limitations, performance issues, security concerns found during generation. 5. Integration Challenges: Data format mismatches, auth issues, interface updates. 6. Feedback: User feedback, accessibility, mobile support issues.

Artifacts to Generate

• spec/intent.md
• spec/requirements.md (EARS)
• spec/design.md
• spec/tasks.md
• steering/*.md (Context)

Design Specification

Guidance:

- Edit ruthlessly (remove over-engineering).

- Check for circular dependencies.

- Ensure alignment with Steering docs.

Architecture

(Diagrams or text description of components and data flow)

Data Models

// Example interfaces or schemas

Component Interfaces

(Key method signatures and contracts)

Error Handling

(Strategy for failures)

Security Considerations

(Auth, data protection, no secrets in code)

Requirements

Format: EARS (Easy Application Requirements Syntax)

Syntax:

- Ubiquitous: <system> shall <response>

- Event-Driven: WHEN <trigger> <optional 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>

Core Requirements

1. [REQ-001] ... 2. [REQ-002] ...

Properties (Invariants)

Universal statements that must always hold true.

1. [PROP-001] ...

Implementation Plan

Rules:

- Two-level hierarchy maximum (Task > Subtask).

- Sequential order (builds on previous).

- Traceability: Link back to Req IDs.

Phase 1: Core Foundation

• [ ] Task 1: [Task Name]
• [ ] 1.1: Implementation step...
• [ ] 1.2: Verification step...
• Traceability: Implements REQ-001

• [ ] Task 2: [Task Name]
• ...

Coding Standards

Purpose: Steer the AI on style, patterns, and forbidden practices.

General

• Language: [e.g. TypeScript / Python]
• Framework: [e.g. Node.js / React]

Patterns

• [Pattern 1]
• [Pattern 2]

Examples

(Provide good/bad examples here)