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.

Acceptance Criteria: Gherkin Format (Required)

Every user story in every spec.md (or specify.md) MUST carry Gherkin-style acceptance criteria, in addition to its prose description. This applies to greenfield and brownfield alike, to every user story, and whether the artifact was produced by /speckit.specify or authored by hand for a repo that doesn't use the CLI-generated template. Prose says what the story is about; Gherkin scenarios say exactly how to verify it — that's what makes a spec executable rather than descriptive.

Format — a fenced gherkin block directly under each user story, 1–4 scenarios: the happy path first, then the edge/negative cases that matter for that story (not every edge case in the spec — those belong in the spec's own Edge Cases section; only the ones specific to this story).

Scenario: <short, specific name — not "happy path">
  Given <the precondition / starting state>
  When <the single action the actor takes>
  Then <the observable, testable outcome>
  And <additional outcome, if needed>

Scenario: <the edge/negative case for this story>
  Given <precondition>
  When <action>
  Then <outcome — what should NOT happen is a valid Then>

Writing rules:

One When per scenario. Multiple actions means multiple scenarios — this keeps each scenario mapping to one test.
Then must be observable, not internal: "the user sees a confirmation toast," not "the state updates correctly." If you can't say how someone would check it, it's not ready.
Reuse the spec's own vocabulary. Given/When/Then steps should read using the same nouns as the user story and functional requirements (asset names, deal types, field names) — not paraphrased.
Don't restate the functional requirements as Gherkin. Acceptance criteria verify the story; FRs are traced separately. Overlap is fine, duplication of every FR as a scenario is not.
Number scenarios for traceability when a story has more than one: Scenario: AC-1 — ..., Scenario: AC-2 — ... (optional for single-scenario stories).

When summarizing (the 10-point template, "What Was Generated"), report the scenario count alongside user-story/success-criteria counts, e.g. "5 user stories (11 Gherkin scenarios), 8 success criteria." If a user story is missing acceptance criteria, flag it under "🔍 Important Items to Review" before moving to /speckit.plan — plans built on stories with no acceptance criteria tend to under-specify tests.

Behavioural ACs: only for LLM-in-the-loop stories

Gherkin assumes one run decides pass/fail. That breaks when a model's output decides the outcome: one green run of a non-deterministic story proves almost nothing. For those stories, add a Behavioural ACs block under the Gherkin block.

Generate it only when the story's observable outcome depends on a model's output. Examples: a prompt, system prompt, mission, skill file or tool description changes; a model picks the action, judges or settles something, or writes the user-facing text; the model or its parameters change. Do not generate it for deterministic code, UI rendering of stored data, plumbing, or a story where a model call is present but its output isn't asserted. When in doubt, ask one question; don't add the block speculatively. A spec with no LLM-in-the-loop stories has no Behavioural ACs at all, and no empty placeholder either.

Format: one block per qualifying story, directly after its Gherkin.

**Behavioural ACs** (LLM-in-the-loop: <what the model decides>)
- **Cases:** <N> cases at `<path to case set>`, from <real failures / traces / transcripts>; synthetic inputs only to fill gaps, never synthetic expected outputs
- **Runs:** k = <k> per case (≈ 3 / expected failure rate; 20–30 if unknown)
- **Pass bar:** <metric> ≥ <threshold> over k, beats baseline by more than the noise (paired comparison against the current version)
- **Grader:** code check | LLM judge (binary, one per failure mode) | human; a judge also names its validation: TPR/TNR ≥ 0.9 (0.8 floor) on held-out human labels, or "UNVALIDATED" said plainly
- **Command:** `<one command that runs it and prints pass rate, cost and latency>`

Rules:

Only a real model run counts. A mock, a keyword simulation or a predicted score is not a result. If it can't run (cost, keys), say the story is UNEVALUATED. Don't fake a number.
Prefer a code grader. Use a judge only for what code can't check.
Gherkin still applies. The Gherkin scenarios cover the deterministic shell (artifacts written, guards held). The Behavioural ACs cover the model's behaviour.
plan.md carries the eval: the case-set location, the run command, the cost per run, and when it runs (per PR, or pre-merge only if it's expensive).

When summarizing, count them separately, e.g. "5 user stories (11 Gherkin scenarios, 2 with Behavioural ACs)". Flag under "Important Items to Review" any LLM-in-the-loop story that lacks the block, and any judge marked UNVALIDATED.

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

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
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 (with their Gherkin acceptance criteria), 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
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
Include Feature Status (Hybrid Approach)
- Brief status line in every summary
- Detailed status on demand with /speckit.status
- See "Feature Status Tracking" section below
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

Authentication: JWT tokens - Rationale: Stateless architecture, horizontally scalable, industry standard
Password requirements: 12+ characters with complexity - Rationale: Balances security (NIST guidelines) with usability
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 (12 Gherkin acceptance-criteria scenarios), 8 success criteria, 3 edge cases

🔍 Important Items to Review

Password reset flow - Verify email requirements match your infrastructure (SMTP server, templates)
Multi-factor authentication - Currently marked as "future enhancement"; may need to be in MVP
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:

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

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

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

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

Identifies current feature order
Proposes moving profile-management to top priority
Adjusts dependencies if needed
Updates artifacts
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

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

When User Wants to Start a New Project

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

When User Has an Existing Codebase

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

When User Wants to Add a Feature

To greenfield project:

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

To brownfield/existing project:

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

When User Encounters Issues

Installation issues → Installation Guide troubleshooting section
Workflow issues → Check appropriate workflow guide:
- Greenfield troubleshooting
- Brownfield troubleshooting
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 # 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)

Ask in your favorite AI

Documentation