Spec-Driven Development (SDD) Skill

Guide users through GitHub's Spec-Kit for Spec-Driven Development - a methodology that flips traditional software development by making specifications executable and directly generating working implementations.

Core Philosophy

Spec-Driven Development emphasizes:

• Intent-driven development: Define the "what" before the "how"
• Rich specification creation: Use guardrails and organizational principles
• Multi-step refinement: Not one-shot code generation
• AI-native: Heavy reliance on advanced AI capabilities

Remember: This is AI-native development. Specifications aren't just documentation - they're executable artifacts that directly drive implementation. The AI agent uses them to generate working code that matches the intent defined in the specs.

Quick Decision Tree

Is this a new project (greenfield)?

→ See Greenfield Workflow for the complete 6-step process

Is this an existing codebase (brownfield)?

→ See Brownfield Workflow for reverse-engineering and integration guidance

Need installation help?

→ See Installation Guide for setup and troubleshooting

Installation Quick Start

Recommended (Persistent):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

One-time Usage:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Verify:

specify check

For detailed installation options, troubleshooting, and environment variables, see Installation Guide.

Supported AI Agents

Works with:

• ✅ Claude Code
• ✅ GitHub Copilot
• ✅ Gemini CLI
• ✅ Cursor
• ✅ Qwen Code
• ✅ opencode
• ✅ Windsurf
• ✅ Kilo Code
• ✅ Auggie CLI
• ✅ CodeBuddy CLI
• ✅ Roo Code
• ✅ Codex CLI
• ✅ Amp
• ⚠️ Amazon Q Developer CLI (doesn't support custom arguments for slash commands)

Artifact Summarization and Feedback Loop

CRITICAL WORKFLOW: After any SDD command generates or modifies artifacts, automatically follow this feedback loop to keep the user engaged:

After Each Command Completes

1. Detect Artifact Changes

   • Identify which artifacts were created or modified:
     • constitution.md (project principles)
     • spec.md (requirements specification)
     • plan.md (technical implementation plan)
     • tasks.md (actionable task breakdown)
     • Analysis reports from brownfield workflows

2. Read and Summarize

   • Read the relevant artifact(s)
   • Extract key information:
     • For constitution.md: Core principles, coding standards, constraints
     • For spec.md: Main requirements, user stories, success criteria
     • For plan.md: Tech stack choices, architecture decisions, milestones
     • For tasks.md: Number of tasks, major task categories, dependencies
     • For analysis reports: Current patterns, tech debt, integration points

3. Present Structured Summary (Use 10-Point Template Below)

   • Show what was generated and why
   • Highlight the most important decisions with rationale
   • Include quality indicators and watch-outs
   • Keep summary focused and actionable
   • Use clear headings for each section

4. Include Feature Status (Hybrid Approach)

   • Brief status line in every summary
   • Detailed status on demand with /speckit.status
   • See "Feature Status Tracking" section below

5. Offer Feedback Options

   • Option A: "Looks good, proceed to next step"
   • Option B: "I'd like to modify [specific section]"
   • Option C: "Regenerate with these changes: [user input]"
   • Option D: "Explain why [specific decision] was made"

10-Point Summary Template

Use this structured format after ANY SDD command completes:

## ✅ [Command Name] Completed - Here's What Just Happened

### 🎯 Key Decisions Made (Top 3)
1. [Decision] - **Rationale:** [Why this was chosen]
2. [Decision] - **Rationale:** [Why this was chosen]
3. [Decision] - **Rationale:** [Why this was chosen]

### 📋 What Was Generated
- [Artifact 1]: [Brief description of content]
- [Artifact 2]: [Brief description of content]

### 🔍 Important Items to Review (Top 3)
1. [Critical item to check and why it matters]
2. [Important detail to verify and potential impact]
3. [Edge case to consider and how it affects the design]

### ⚠️ Watch Out For (Top 2)
- [Potential issue or gotcha] - **How to avoid:** [Guidance]
- [Common mistake] - **How to avoid:** [Guidance]

### 🔄 What This Enables Next (2 Options)
- **Option 1:** [Next step] - Best if: [Condition]
- **Option 2:** [Alternative step] - Best if: [Condition]

📊 **Feature Status:** [Current Feature Name] ([Stage]) → Next: [Next Feature]
   Progress: [●●●○○] [X]% | Completed: [N] of [Total] features | Dependencies: [Status]

**Your options:** [A] Proceed [B] Modify [C] Explain more [D] Show full status

Example: Enhanced Summarization After `/speckit.specify`

```

✅ Specify Completed - Here's What Just Happened

🎯 Key Decisions Made

1. Authentication: JWT tokens - Rationale: Stateless architecture, horizontally scalable, industry standard
2. Password requirements: 12+ characters with complexity - Rationale: Balances security (NIST guidelines) with usability
3. Session timeout: 24 hours - Rationale: Standard for web apps, balances security vs user convenience

📋 What Was Generated

• `.speckit/features/user-auth/specify.md`: Complete requirements with 5 user stories, 8 success criteria, 3 edge cases

🔍 Important Items to Review

1. Password reset flow - Verify email requirements match your infrastructure (SMTP server, templates)
2. Multi-factor authentication - Currently marked as "future enhancement"; may need to be in MVP
3. Rate limiting - Set at 5 login attempts per 15 min; consider if this fits your security policy

⚠️ Watch Out For

• Email service dependency not specified - How to avoid: Add email service to plan.md dependencies
• GDPR compliance for user data - How to avoid: Review data retention and user deletion requirements

🔄 What This Enables Next

• Option 1: Run `/speckit.plan` to design technical implementation - Best if: Requirements look good
• Option 2: Modify specify.md - Best if: You need to adjust requirements or add features

📊 Feature Status: user-authentication (Specified) → Next: profile-management Progress: [●●○○○] 40% | Completed: 1 of 5 features | Dependencies: database-setup ✅

Your options: [A] Proceed to planning [B] Modify requirements [C] Explain JWT choice [D] Show full status ```

When to Skip Summarization

Only skip the summarization step when:

• User explicitly requests "skip summaries" or "run all steps automatically"
• Re-running a command without artifact changes
• Command fails or produces errors (troubleshoot instead)

Benefits of This Workflow

• Eliminates "black box" feeling: Clear explanations of what was generated and why
• Enables early feedback: Catch misunderstandings before implementation
• Maintains agility: Quick review with structured format, not lengthy approval processes
• Builds trust: User sees the AI's reasoning and decisions with rationale
• Provides context: Feature status keeps users oriented in the overall project

Feature Status Tracking

Hybrid Approach

After every SDD command, include a brief feature status line in the summary. Provide detailed status on demand with /speckit.status.

Brief Status Line Format

Include this at the end of every summary:

📊 **Feature Status:** [Current Feature Name] ([Stage]) → Next: [Next Feature Name]
   Progress: [●●●○○] [X]% | Completed: [N] of [Total] features | Dependencies: [Dep] ✅/⏸️

Stage values:

• Specifying (20% complete)
• Planning (40% complete)
• Tasking (60% complete)
• In Progress (80% complete)
• Complete (100% complete)

Progress indicator:

• Use filled circles (●) for completed stages
• Use empty circles (○) for pending stages
• Calculate percentage based on stage

Detailed Status Dashboard

When user requests full status (option D) or runs /speckit.status, show:

📊 Project Feature Status Dashboard

🎯 CURRENT FEATURE
├─ [feature-name] ([Stage] - [X]% complete)
│  ├─ ✅ Requirements specified
│  ├─ 🔄 Implementation plan in progress
│  ├─ ⏸️  Tasks not started
│  └─ ⏸️  Implementation not started
│  Blockers: [None | Description]
│  Dependencies: [feature-name] ✅

✅ COMPLETED FEATURES ([N])
├─ [feature-1] (100% complete)
└─ [feature-2] (100% complete)

📋 UPCOMING FEATURES ([N])
├─ [feature-3] (depends on: [current-feature])
└─ [feature-4] (depends on: [feature-3])

⚠️  BLOCKED FEATURES ([N])
[List any features that are blocked with reasons]

Natural Language Feature Management

Claude should automatically detect and handle natural language feature management requests:

User says: "Move feature XYZ before ABC" Claude does:

1. Reads current feature list from .speckit/features/
2. Shows current order with numbers
3. Proposes new order
4. Asks for confirmation
5. Updates feature priority/order in constitution or plan
6. Shows updated status dashboard

User says: "Add a new feature for email notifications" Claude does:

1. Detects new feature request
2. Asks clarifying questions (priority, dependencies, description)
3. Generates feature spec outline
4. Inserts into feature list at appropriate position
5. Shows updated status dashboard

User says: "Let's do profile-management first" Claude does:

1. Identifies current feature order
2. Proposes moving profile-management to top priority
3. Adjusts dependencies if needed
4. Updates artifacts
5. Shows updated status

Detection patterns:

• "Move [feature] before/after [other]" → Reorder
• "Add [feature]" → New feature
• "Let's do [feature] first" → Move to top priority
• "Skip [feature] for now" → Mark as deferred
• "We finished [feature]" → Update status to complete
• "What features depend on [feature]?" → Show dependency tree
• "Show feature status" → Display full dashboard

Quick Feature Operations

Guide users through these operations when requested:

Add Feature:

User: "Add a feature for admin dashboard"
Claude:
1. What's the priority? (High/Medium/Low)
2. What features does this depend on? (user-auth, profile-management, etc.)
3. Brief description?
[Creates outline, shows updated status]

Reorder Features:

User: "Reorder features"
Claude:
Current order:
1. user-authentication
2. profile-management
3. admin-dashboard
4. email-notifications
5. reporting

How would you like to reorder? (provide new numbers or describe changes)
[Updates order, shows new status]

Remove Feature:

User: "Remove the reporting feature"
Claude:
⚠️  Warning: This will remove 'reporting' feature.
Dependencies affected: None
Are you sure? (yes/no)
[If yes: removes, updates status]

Progress Calculation

Automatically calculate progress based on SDD workflow completion:

Stage	Progress	Indicators
Specified	20%	specify.md exists
Planned	40%	plan.md exists
Tasked	60%	tasks.md exists
In Progress	80%	Implementation started (code files modified)
Complete	100%	Implementation complete, tests pass

Dependency Tracking

Track and visualize dependencies:

Show dependencies:

user-authentication
├─ Depends on: database-setup ✅
└─ Blocks: profile-management ⏸️, admin-dashboard ⏸️

Check if ready:

📊 Can we start profile-management?
   Checking dependencies...
   ✅ user-authentication (complete)
   ✅ database-setup (complete)

   All dependencies satisfied! Ready to proceed.

Detect circular dependencies:

⚠️  Warning: Circular dependency detected
   feature-A depends on feature-B
   feature-B depends on feature-C
   feature-C depends on feature-A

   Please resolve this before proceeding.

Integration with Workflows

For Greenfield Projects:

• After /speckit.specify, ask if there are multiple features
• If yes, list them and track progress through each
• Show status after each command

For Brownfield Projects:

• After /speckit.reverse-engineer, create feature list from discovered functionality
• Track new features separately from existing documented features
• Show integration impact on status

For complete feature management guidance, see Feature Management Guide.

How to Use This Skill

When User Asks About SDD

1. Explain core philosophy: Executable specifications, intent-driven, AI-native
2. Verify prerequisites: `uv`, Python 3.11+, Git, AI agent
3. Determine project type: New (greenfield) vs existing (brownfield)
4. Guide to appropriate workflow:
   • Greenfield → Greenfield Workflow
   • Brownfield → Brownfield Workflow

When User Wants to Start a New Project

1. Guide installation → Installation Guide
2. Initialize project: ```bash specify init my-project --ai claude ```
3. Follow greenfield workflow → Greenfield Workflow
4. After each step: Summarize artifacts and get user feedback

When User Has an Existing Codebase

1. Check for `.speckit/` directory
2. If missing → Guide through Brownfield Workflow:
   • Analyze existing code
   • Generate constitution from existing patterns
   • Choose artifact generation strategy
   • Add new features with SDD
3. If present → Determine next step based on current progress
4. After each step: Summarize artifacts and get user feedback

When User Wants to Add a Feature

To greenfield project:

1. Navigate to Greenfield Workflow
2. Follow steps 3-6 (specify → plan → tasks → implement)
3. Summarize each artifact before proceeding

To brownfield/existing project:

1. Navigate to Brownfield Workflow
2. Follow steps 6-7 (specify → integration planning → tasks → implement)
3. Summarize each artifact before proceeding

When User Encounters Issues

1. Installation issues → Installation Guide troubleshooting section
2. Workflow issues → Check appropriate workflow guide:
   • Greenfield troubleshooting
   • Brownfield troubleshooting
3. Feature detection → Set `SPECIFY_FEATURE` environment variable (see Installation Guide)

Workflow Overview

Greenfield (New Projects)

``` specify init → /speckit.constitution → [SUMMARIZE] → /speckit.specify → [SUMMARIZE] → /speckit.plan → [SUMMARIZE] → /speckit.tasks → [SUMMARIZE] → /speckit.implement ```

Full details: Greenfield Workflow

Brownfield (Existing Projects)

``` specify init --here → /speckit.brownfield → [SUMMARIZE] → /speckit.analyze-codebase → [SUMMARIZE] → /speckit.reverse-engineer → [SUMMARIZE] → /speckit.specify → [SUMMARIZE] → /speckit.integration-plan → [SUMMARIZE] → /speckit.tasks → [SUMMARIZE] → /speckit.implement ```

Full details: Brownfield Workflow

Development Phases Supported

0-to-1 Development ("Greenfield")

Start with high-level requirements, generate specifications from scratch, plan implementation steps, build production-ready applications.

→ Greenfield Workflow

Iterative Enhancement ("Brownfield")

Add features iteratively to existing codebases, modernize legacy systems, adapt processes for evolving requirements, reverse-engineer existing code into SDD format.

→ Brownfield Workflow

Creative Exploration

Explore diverse solutions in parallel, support multiple technology stacks & architectures, experiment with UX patterns.

→ Greenfield Workflow - Multi-Stack Exploration section

Key Commands Reference

Installation & Setup

```bash specify init <project> # New project specify init --here --force # Existing project specify check # Verify installation ```

Greenfield Workflow

``` /speckit.constitution # Project principles → SUMMARIZE /speckit.specify # Define requirements → SUMMARIZE /speckit.plan # Technical planning → SUMMARIZE /speckit.tasks # Break down tasks → SUMMARIZE /speckit.implement # Execute ```

Brownfield Workflow

``` /speckit.brownfield # Analyze existing code → SUMMARIZE /speckit.analyze-codebase # Deep analysis & constitution → SUMMARIZE /speckit.reverse-engineer # Document existing features → SUMMARIZE /speckit.integration-plan # Plan new feature integration → SUMMARIZE ```

Optional Enhancement Commands

``` /speckit.clarify # Clarify ambiguous requirements /speckit.analyze # Cross-artifact consistency check /speckit.checklist # Generate quality checklists ```

Analysis Scripts

The SDD skill includes analysis scripts for deep quality validation and progress tracking:

`scripts/phase_summary.sh`

Generates a comprehensive progress report across all phases in a tasks.md file:

• Shows completion percentage for each phase
• Lists pending tasks per phase
• Highlights simplified/modified tasks
• Provides overall progress statistics
• Supports any SDD feature's tasks.md file

Usage: ```bash ~/.claude/skills/sdd/scripts/phase_summary.sh specs/003-keyboard-shortcuts/tasks.md ```

Output: Markdown-formatted phase-by-phase progress report with:

• Phase-by-phase completion percentages
• Pending task lists (up to 5 per phase)
• Simplified task warnings
• Overall feature progress summary

When to Use:

• Check progress on any SDD feature
• Get quick overview of what's complete vs pending
• Identify phases that need attention
• Generate status reports for stakeholders

`scripts/analyze-requirements.py`

Analyzes requirement coverage across spec.md and tasks.md:

• Maps functional requirements (FR-001, FR-002, etc.) to implementation tasks
• Identifies uncovered requirements (gaps in task coverage)
• Flags vague requirements lacking measurable criteria
• Calculates coverage percentage

Usage: ```bash python3 ~/.claude/skills/sdd/scripts/analyze-requirements.py ```

Output: JSON with coverage metrics, uncovered requirements, vague requirements

`scripts/analyze-success-criteria.py`

Analyzes success criteria verification coverage:

• Maps success criteria (SC-001, SC-002, etc.) to verification tasks
• Validates measurability of each criterion
• Identifies criteria without verification tasks
• Groups by metric type (performance, accessibility, usability)

Usage: ```bash python3 ~/.claude/skills/sdd/scripts/analyze-success-criteria.py ```

Output: JSON with coverage summary, verification task mapping

`scripts/analyze-edge-cases.py`

Analyzes edge case coverage across specifications:

• Maps edge cases to explicit task coverage
• Identifies implicitly covered cases (handled by general logic)
• Flags uncovered edge cases requiring attention
• Categorizes coverage type (EXPLICIT, IMPLICIT, UNCOVERED)

Usage: ```bash python3 ~/.claude/skills/sdd/scripts/analyze-edge-cases.py ```

Output: JSON with coverage breakdown, uncovered edge case details

When to Use: These scripts are automatically invoked during `/speckit.analyze` to provide deep consistency validation. They help identify:

• Requirements without task coverage
• Success criteria without verification
• Edge cases that need test coverage
• Ambiguous requirements needing clarification

Validation Commands (Brownfield)

``` /speckit.validate-reverse-engineering # Verify spec accuracy /speckit.coverage-check # Check documentation coverage /speckit.validate-constitution # Verify constitution consistency /speckit.trace [feature] # Map specs to code ```

Detailed Documentation

• Installation Guide: Installation methods, troubleshooting, environment variables
• Greenfield Workflow: Complete 6-step workflow for new projects
• Brownfield Workflow: Complete 7-step workflow for existing codebases

Integration with Other Skills

This skill works well with:

• project-memory: Document SDD decisions and patterns
• design-doc-mermaid: Visualize architecture from plan.md
• github-workflows: Automate SDD artifact validation
• code-quality-reviewer: Review generated implementation

Resources

• GitHub Spec-Kit Repository: https://github.com/github/spec-kit
• Issues/Support: https://github.com/github/spec-kit/issues
• License: MIT

Maintainers

• Den Delimarsky (@localden)
• John Lam (@jflam)