Specification-Driven Development (SDD)

Overview

SDD reverses traditional development: specifications become the source of truth, and code becomes their generated expression. This skill provides the workflow, templates, and validation tools for specification-driven development.

Core Workflow

1. Create Feature Specification (/speckit.specify)

Generate a complete, structured feature specification:

/speckit.specify [feature description]

This command:

• Scans existing specs to determine next feature number (001, 002, etc.)
• Creates a semantic branch name from the description
• Generates spec from template at specs/[branch-name]/spec.md
• Creates proper directory structure
• Marks ambiguities with [NEEDS CLARIFICATION] tags

Template location: Use assets/spec-template.md as the base structure.

Key principles:

• Focus on WHAT and WHY, not HOW
• Include user stories with acceptance criteria
• Mark all ambiguities explicitly
• No technical implementation details at this stage

2. Generate Implementation Plan (/speckit.plan)

Create a comprehensive technical plan from the specification:

/speckit.plan [technical approach notes]

This command:

• Reads the feature specification
• Applies constitutional principles (see references/constitution.md)
• Generates technical architecture and implementation details
• Creates supporting documents (data-model.md, contracts/, research.md)
• Includes quickstart validation scenarios

Template location: Use assets/plan-template.md as the base structure.

Constitutional gates enforced:

• Library-First Principle (Article I)
• CLI Interface Mandate (Article II)
• Test-First Imperative (Article III)
• Simplicity Gates (Article VII)
• Anti-Abstraction Gates (Article VIII)
• Integration-First Testing (Article IX)

3. Generate Executable Tasks (/speckit.tasks)

Derive actionable tasks from the implementation plan:

/speckit.tasks

This command:

• Reads plan.md and supporting documents
• Converts contracts, entities, and scenarios into tasks
• Marks parallelizable tasks with [P]
• Outputs tasks.md ready for execution

Input files analyzed:

• plan.md (required)
• data-model.md (if exists)
• contracts/ (if exists)
• research.md (if exists)

File Structure

A complete SDD feature creates:

specs/
└── [branch-name]/
    ├── spec.md           # Feature specification (WHAT/WHY)
    ├── plan.md           # Implementation plan (HOW)
    ├── data-model.md     # Entity schemas
    ├── contracts/        # API contracts, WebSocket events
    ├── research.md       # Technical research and comparisons
    ├── quickstart.md     # Key validation scenarios
    └── tasks.md          # Executable task list

Constitutional Principles

The SDD workflow enforces nine architectural principles. Before generating any implementation plan, read references/constitution.md to understand:

1. Article I: Library-First Principle - Every feature starts as a standalone library
2. Article II: CLI Interface Mandate - All functionality must be CLI-accessible
3. Article III: Test-First Imperative - No code without approved tests
4. Article VII: Simplicity - Maximize simplicity, ≤3 projects initially
5. Article VIII: Anti-Abstraction - Trust frameworks, avoid premature abstraction
6. Article IX: Integration-First - Test with real services, not mocks

Validation

Before code generation, validate specifications using:

python scripts/validate_spec.py specs/[branch-name]/

This checks for:

• Remaining [NEEDS CLARIFICATION] tags
• Missing required sections
• Testability of acceptance criteria
• Constitutional compliance in plans

Templates and Assets

• assets/spec-template.md - Feature specification template
• assets/plan-template.md - Implementation plan template
• references/constitution.md - Full constitutional articles with examples

Best Practices

Specification Phase:

• Start with user intent, not technical solutions
• Mark every ambiguity explicitly
• Include measurable acceptance criteria
• Avoid implementation details

Planning Phase:

• Reference constitution gates before generating plans
• Document technical choices with rationale
• Create contracts before implementation
• Define test scenarios from acceptance criteria

Task Generation:

• Ensure tasks map to specific contracts or entities
• Mark truly parallelizable work
• Include both implementation and test tasks
• Sequence dependencies clearly

Example: Real-Time Chat Feature

# Step 1: Create specification
/speckit.specify Real-time chat system with message history and user online status

# Creates: specs/003-chat-system/spec.md
# Includes: User stories, acceptance criteria, non-functional requirements

# Step 2: Generate plan
/speckit.plan Using WebSocket for real-time messaging, PostgreSQL for history, Redis for presence

# Creates: specs/003-chat-system/plan.md, data-model.md, contracts/, research.md, quickstart.md

# Step 3: Generate tasks
/speckit.tasks

# Creates: specs/003-chat-system/tasks.md with concrete, executable tasks

Progressive Disclosure

For detailed examples and patterns, see:

• references/constitution.md - Complete constitutional framework
• assets/spec-template.md - Full specification structure
• assets/plan-template.md - Full implementation plan structure

Read these files as needed during the workflow to ensure compliance and quality.