Sdd

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](references/greenfield.md) for the complete 6-step process

Is this an existing codebase (brownfield)?

→ See [Brownfield Workflow](references/brownfield.md) for reverse-engineering and integration guidance

Need installation help?

→ See [Installation Guide](references/sdd_install.md) 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:

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](references/greenfield.md)

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](references/brownfield.md)

Creative Exploration

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

→ [Greenfield Workflow](references/greenfield.md) - 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](references/sdd_install.md): Installation methods, troubleshooting, environment variables
• [Greenfield Workflow](references/greenfield.md): Complete 6-step workflow for new projects
• [Brownfield Workflow](references/brownfield.md): 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)

Spec-Driven Development (SDD) Skill

A comprehensive Claude Code skill for guiding users through GitHub's Spec-Kit and the Spec-Driven Development methodology.

What is Spec-Driven Development?

Spec-Driven Development flips traditional software development on its head. Instead of treating specifications as temporary scaffolding, SDD makes them executable - they directly generate working implementations rather than just guiding them.

What's New in v2.1.0

🎯 Enhanced Explanations & Summaries

• 10-Point Summary Template: Structured summaries after every SDD command showing key decisions, what was generated, items to review, watch-outs, and next steps
• Rationale for Decisions: Every major decision includes "why" it was made
• No More Black Boxes: Clear explanations eliminate the mystery of what was just generated

📊 Feature Status Tracking

• Automatic Progress Tracking: See exactly where each feature is (Specified, Planned, Tasked, In Progress, Complete)
• Hybrid Status Display: Brief status line in every summary + detailed dashboard on demand
• Dependency Visualization: See what features depend on what, and what's blocking progress
• Progress Percentages: Automatic calculation based on workflow completion (20%, 40%, 60%, 80%, 100%)

💬 Natural Language Feature Management

• Add Features: Just say "Add a feature for email notifications"
• Reorder Features: "Move user-notifications before profile-management"
• Remove Features: "We don't need reporting anymore"
• Show Status: "Show me all features" or "What's blocking admin-dashboard?"
• Check Dependencies: "Can we start profile-management yet?"

📁 Brownfield Support

Comprehensive support for existing codebases! Reverse-engineer existing projects into SDD format, generate constitutions from existing code, and integrate new features into legacy systems.

Quick Start

To use this skill, simply mention any of these trigger words in your conversation with Claude:

General SDD:

• "spec-driven development", "sdd", "speckit"
• "specify cli", "/speckit"
• "executable specifications"

For New Projects (Greenfield):

• "new project", "from scratch"
• "specify init"

For Existing Projects (Brownfield):

• "brownfield", "existing codebase"
• "legacy code", "modernization"
• "reverse engineer", "codebase analysis"

For Feature Management:

• "feature status", "track features"
• "add feature", "move feature"
• "show features", "feature progress"

What This Skill Provides

1. Installation Guidance

• Persistent installation (recommended) using uv tool install
• One-time usage with uvx
• Installation verification with specify check
• Troubleshooting for common issues

2. Complete Workflow Support

Greenfield Workflow (New Projects - 6 steps): 1. Initialize Project: specify init 2. Establish Principles: /speckit.constitution 3. Create Specification: /speckit.specify 4. Technical Planning: /speckit.plan 5. Task Breakdown: /speckit.tasks 6. Implementation: /speckit.implement

Brownfield Workflow (Existing Projects - 7 steps): 1. Analyze Codebase: /speckit.brownfield 2. Initialize SDD: specify init --here --force 3. Generate Constitution: /speckit.analyze-codebase 4. Choose Strategy: /speckit.reverse-engineer 5. Document Features: (optional, based on strategy) 6. Specify New Feature: /speckit.specify 7. Integration Planning: /speckit.integration-plan

3. Feature Status Tracking & Management

• Automatic Progress Tracking: Tracks each feature through Specified (20%) → Planned (40%) → Tasked (60%) → In Progress (80%) → Complete (100%)
• Natural Language Commands: "Add feature for X", "Move feature Y before Z", "Show feature status"
• Dependency Management: Automatic dependency tracking and blocking detection
• Status Dashboard: Brief status in every summary + detailed dashboard on demand (/speckit.status or option [D])

4. Optional Enhancement Commands

• /speckit.clarify - Clarify underspecified areas
• /speckit.analyze - Consistency & coverage analysis
• /speckit.checklist - Generate quality validation checklists

5. Validation Commands (Brownfield)

• /speckit.validate-reverse-engineering - Verify reverse-engineering accuracy
• /speckit.coverage-check - Check documentation coverage
• /speckit.validate-constitution - Validate constitution consistency
• /speckit.trace [feature] - Spec-to-code traceability

5. Development Phase Support

• Greenfield (0-to-1): Build new projects from scratch
• Brownfield (Existing): Reverse-engineer and enhance existing codebases
• Creative Exploration: Try multiple tech stacks in parallel
• Legacy Modernization: Systematically upgrade old systems

6. Best Practices

• For new users: Start small, follow the sequence
• For experienced users: Parallel exploration, custom checklists
• For enterprise teams: Establish constitution early, version control everything

Artifacts Generated

After running SDD commands, expect these artifacts:

project-name/
├── .speckit/
│   ├── constitution.md      # Project principles
│   ├── features/
│   │   └── 001-feature-name/
│   │       ├── specify.md    # Requirements
│   │       ├── plan.md       # Technical plan
│   │       ├── tasks.md      # Task breakdown
│   │       └── checklist.md  # Quality gates
│   └── .claude/
│       └── commands/         # Slash commands
└── [application code]

Supported AI Agents

Works with Claude Code, GitHub Copilot, Cursor, Windsurf, Gemini CLI, and many others (see skill.md for full list).

Prerequisites

Users need:

• uv for package management
• Python 3.11+
• Git
• A supported AI coding agent

Example Usage

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

# Initialize project
specify init my-app --ai claude

# Then in the AI agent:
/speckit.constitution Create principles for production-ready web apps...
/speckit.specify Build a task management app with drag-and-drop...
/speckit.plan Use React with TypeScript, Vite, and Tailwind CSS...
/speckit.tasks
/speckit.implement

Files in This Skill

• SKILL.md: Modern skill with YAML frontmatter and lean orchestration (v2.1.0)
• README.md: This file - quick reference
• CLAUDE.md: Repository guidance for AI agents
• references/: Detailed workflow documentation
• sdd_install.md: Installation and setup guide
• greenfield.md: Complete greenfield workflow with enhanced summaries (6 steps)
• brownfield.md: Complete brownfield workflow with enhanced summaries (7 steps)
• feature_management.md: Comprehensive feature management guide (NEW in v2.1.0)

Resources

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

Philosophy

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.

---

Maintained by: Based on GitHub Spec-Kit by Den Delimarsky (@localden) and John Lam (@jflam) License: MIT

Brownfield Workflow: Bringing SDD to Existing Codebases

Note: All summarization sections in this guide should use the 10-point summary template from SKILL.md, with feature status tracking when applicable.

When to Use Brownfield Workflow

Use this workflow when:

• Adding features to an existing codebase
• Modernizing or refactoring legacy systems
• Adopting SDD methodology in an ongoing project
• Reverse-engineering existing code into SDD format
• Migrating from traditional development to spec-driven development

For new projects from scratch, see Greenfield Workflow.

Core Concepts

Brownfield Philosophy

Brownfield SDD respects and builds upon existing code:

• Analyze first: Understand current architecture before making changes
• Respect patterns: Constitution should acknowledge existing design decisions
• Incremental adoption: Start small, prove value, expand usage
• Integration-aware: New features must mesh with existing code

Analysis Depth Options

Choose the appropriate analysis depth based on your needs:

• Surface Level (~5-10 minutes)
• File structure and directory organization
• Dependencies and tech stack
• Basic code patterns (naming, file organization)
• Use when: Quick bootstrap to start adding features

• Moderate Depth (~20-40 minutes) - DEFAULT
• Architecture and design patterns
• API contracts and interfaces
• Data models and schemas
• Business logic organization
• Configuration and environment setup
• Use when: Most brownfield scenarios

• Deep Analysis (~1-3 hours)
• Complete system comprehension
• Edge cases and error handling
• Technical debt documentation
• Implicit requirements discovery
• Decision rationale and history
• Use when: Legacy modernization, major refactoring, compliance requirements

The 7-Step Brownfield Workflow

Workflow Overview: 1. Analyze Existing Codebase 2. Initialize SDD in Existing Project 3. Generate Constitution from Analysis 4. Choose Artifact Generation Strategy 5. Document Existing Features

• 5a. Validate Reverse-Engineering (Optional)

6. Specify New Feature 7. Integration-Aware Implementation

Step 1: Analyze Existing Codebase

Command:

/speckit.brownfield

Purpose: Initialize brownfield workflow and analyze existing code

Example prompt to give user:

/speckit.brownfield Analyze this codebase at moderate depth, focusing on:
- Current architecture and design patterns
- Technology stack and dependencies
- API structure and data models
- Coding standards and conventions

For different depths:

# Surface analysis
/speckit.brownfield Perform a surface-level analysis of this codebase

# Deep analysis
/speckit.brownfield Perform a deep analysis including technical debt,
edge cases, and architectural decision rationale

What this produces:

• Codebase analysis report
• Identified patterns and conventions
• Tech stack inventory
• Architecture overview

After this step - Summarize the analysis report:

Use the 10-point summary template from SKILL.md to present the codebase analysis.

Example enhanced summary:

## ✅ Brownfield Analysis Completed - Here's What Just Happened

### 🎯 Key Decisions Made
1. **Microservices architecture identified (5 services)** - Rationale: Modular design allows independent feature development
2. **TypeScript with strict mode across codebase** - Rationale: Strong type safety culture; maintain this in new features
3. **Event-driven communication via RabbitMQ** - Rationale: Async messaging pattern; new features should follow this pattern

### 📋 What Was Generated
- Codebase analysis report: Architecture patterns, tech stack, coding standards, technical debt assessment

### 🔍 Important Items to Review
1. **65% test coverage (target: 80%)** - New features should increase coverage; plan for testing investment
2. **Some services lack error handling** - When adding features, prioritize services with weak error handling
3. **API documentation needs updates** - Document new endpoints comprehensively as part of feature work

### ⚠️ Watch Out For
- **Redux state management complexity** - How to avoid: Consider simpler state solutions for new features or plan Redux refactor
- **RabbitMQ dependency** - How to avoid: Ensure local RabbitMQ setup for development; document in constitution

### 🔄 What This Enables Next
- **Option 1:** Run `specify init --here --force` to set up SDD - Best if: Analysis looks complete
- **Option 2:** Deep dive into specific services - Best if: Need more architectural details
- **Option 3:** Analyze dependencies and integration points - Best if: Planning complex feature integration

📊 **Feature Status:** Analyzing existing codebase (No SDD features yet)
   Progress: Analysis complete → Next: Initialize SDD infrastructure

**Your options:** [A] Initialize SDD [B] Deep dive specific areas [C] Analyze dependencies [D] Adjust analysis depth

Step 2: Initialize SDD in Existing Project

Command:

specify init --here --ai claude
# or for non-empty directories
specify init --here --force --ai claude

Purpose: Set up SDD infrastructure without disrupting existing code

What happens:

• Creates .speckit/ directory structure
• Installs slash commands in .claude/commands/
• Preserves all existing code and configuration
• Initializes Git tracking if not already present

Step 3: Generate Constitution from Analysis

Command:

/speckit.analyze-codebase

Purpose: Create constitution that reflects existing architecture and principles

Approach: Hybrid (automated + interactive) 1. AI analyzes code and proposes principles 2. User reviews and refines proposed constitution 3. AI generates final constitution.md

Example interaction:

AI: Based on my analysis, I observe these patterns:
- RESTful API design with Express.js
- PostgreSQL with Sequelize ORM
- JWT authentication
- MVC architecture
- React frontend with Redux

Should the constitution include these as established patterns? [Y/n]

User: Yes, but we're planning to migrate from Redux to Zustand

AI: Understood. I'll document Redux as current state with Zustand as future direction.

Example prompt to give user:

/speckit.analyze-codebase Generate a constitution that:
- Documents existing architecture patterns
- Acknowledges current tech stack
- Maintains consistency with existing code style
- Notes any planned migrations or changes

After this step - Summarize constitution.md:

Read .speckit/constitution.md and present a summary highlighting:

• Core architectural principles derived from existing code
• Established patterns and conventions
• Technology constraints and standards
• Future direction or planned migrations

Example summary:

## Constitution Generated from Existing Code ✓

I've created constitution.md based on the existing codebase patterns:

**Architectural Principles:**
- Microservices: Each service owns its domain and database
- API-first: All inter-service communication via RESTful APIs
- Event-driven: Async operations via RabbitMQ message queues
- Stateless services: Session state in Redis, not in-memory

**Technology Standards:**
- TypeScript with strict mode for type safety
- Express.js for API servers
- PostgreSQL for relational data, Redis for caching
- Docker containers, Kubernetes orchestration

**Coding Conventions:**
- Repository pattern for data access
- Service layer for business logic
- Controller layer for API endpoints
- DTOs for request/response validation (Joi schemas)

**Testing Standards:**
- Minimum 80% code coverage (current: 65%)
- Unit tests with Jest
- Integration tests for API endpoints
- E2E tests for critical user flows

**Planned Evolution:**
- Migrate from Redux to Zustand (frontend state management)
- Adopt OpenAPI 3.0 for API documentation
- Implement distributed tracing (Jaeger)

**Next Step:** Choose artifact generation strategy (Step 4)

Would you like to:
A) Proceed to choose documentation strategy
B) Refine any principles
C) Add additional constraints

Step 4: Choose Artifact Generation Strategy

Interactive decision point - Ask user which approach:

Option A: Constitution Only

Generate constitution.md only, use for new features going forward

Best for: Teams wanting to adopt SDD for future work only

Option B: Constitution + Baseline Specs

Generate constitution.md and high-level specs for existing major features

Best for: Documentation backfill while starting new SDD work

Option C: Full Artifact Suite

Generate constitution, specifications, and technical plans for all existing features

Best for: Complete SDD adoption, compliance documentation, legacy modernization

Option D: Mixed Approach (Recommended)

- Constitution for all code
- Full specs for 2-3 core features
- Baseline specs for remaining features

Best for: Balanced documentation without overwhelming effort

Command after user chooses:

/speckit.reverse-engineer [option-chosen]

Example prompts:

# Constitution only
/speckit.reverse-engineer constitution-only

# Mixed approach
/speckit.reverse-engineer mixed --core-features authentication,user-management,api-gateway

Step 5: Document Existing Features (Optional)

If user chose Options B, C, or D in Step 4:

Command:

/speckit.reverse-engineer

Purpose: Generate SDD artifacts for existing features

Example prompt to give user:

/speckit.reverse-engineer Document the authentication system:
- User registration and login flows
- JWT token management
- Password reset functionality
- OAuth integration

What this produces:

.speckit/
└── features/
    └── existing/
        ├── 001-authentication/
        │   ├── specify.md      # Reverse-engineered requirements
        │   └── plan.md         # Current implementation details
        ├── 002-user-management/
        └── 003-api-gateway/

After this step - Summarize reverse-engineered specs:

Read the generated specs for documented features and present a summary highlighting:

• Features that were documented
• Key functionality captured
• Integration points identified
• Any gaps or areas needing clarification

Example summary:

## Existing Features Documented ✓

I've reverse-engineered specifications for 3 core features:

**1. Authentication System (001-authentication/):**
- User registration with email verification
- Login with JWT tokens (15-minute access, 7-day refresh)
- Password reset via email
- OAuth providers: Google, GitHub
- Rate limiting: 5 failed attempts = 15-minute lockout

**2. User Management (002-user-management/):**
- CRUD operations for user profiles
- Role-based access control (User, Admin, Super Admin)
- User search and filtering
- Bulk operations (export, deactivate)
- Admin endpoints for user impersonation

**3. API Gateway (003-api-gateway/):**
- Request routing to microservices
- Authentication middleware
- Rate limiting (100 req/minute per user)
- Request/response logging
- Error handling and retry logic

**Integration Points Identified:**
- All features use shared PostgreSQL database
- Redis for session storage and rate limiting
- RabbitMQ for async notifications
- Shared authentication middleware

**Gaps to Address:**
- Payment processing workflow incomplete (45% documented)
- Background job system not yet documented
- Admin dashboard missing specifications

**Next Step:** Optionally validate reverse-engineering with `/speckit.validate-reverse-engineering`, then proceed to Step 6 to specify your new feature

Would you like to:
A) Validate the reverse-engineering accuracy
B) Document additional existing features
C) Proceed to specify new feature (Step 6)

Step 5a: Validate Reverse-Engineering (Optional but Recommended)

Note: Validation commands are proposed enhancements to spec-kit. If commands are not yet available, you can perform manual validation by reviewing generated specs against actual code, using code search to verify completeness, cross-checking constitution principles with actual patterns, or creating custom validation scripts.

When to use: After documenting existing features, before adding new features

Purpose: Verify that reverse-engineering work is accurate, complete, and traceable

This optional step allows you to request validation of the reverse-engineering work to ensure quality before proceeding with new feature development.

Reverse-Engineering Accuracy Validation

Command:

/speckit.validate-reverse-engineering

Purpose: Verify that generated specs match actual code behavior and implementation

Example prompt to give user:

/speckit.validate-reverse-engineering Check:
- Do API specs match actual endpoints and contracts?
- Are data models accurately documented?
- Do workflows reflect actual business logic?
- Are technical plans consistent with implementation?

What this validates:

• Generated specifications describe actual code behavior
• All public APIs are accurately documented
• Data models match actual database schemas
• Architecture diagrams reflect actual structure
• Feature boundaries are correctly identified
• Business logic workflows are accurate

Example validation report:

✓ Authentication API: 12/12 endpoints documented accurately
✗ User Management: Missing 3 admin endpoints
✓ Data Models: 8/8 models match database schema
⚠ Payment Processing: Workflow partially documented (60% coverage)

Issues Found:
1. Admin endpoints not documented in user-management specs
2. Payment refund workflow missing from specifications
3. Database migration history not captured

Recommendations:
- Run /speckit.reverse-engineer for admin endpoints
- Document payment refund process
- Add migration history to technical plan

Coverage and Completeness Check

Command:

/speckit.coverage-check

Purpose: Report documentation coverage and identify gaps

Example prompt to give user:

/speckit.coverage-check Report:
- Percentage of codebase documented
- Undocumented features and modules
- Files without corresponding specs
- API endpoint coverage

What this reports:

• Percentage of codebase with SDD documentation
• List of undocumented features and components
• Source files without corresponding specs
• Gaps in API documentation
• Database tables/models not documented
• Configuration and infrastructure coverage

Example coverage report:

Overall Coverage: 68%

Feature Coverage:
✓ Authentication: 100% (fully documented)
✓ User Management: 90% (admin section partial)
✗ Payment Processing: 45% (significant gaps)
✗ Reporting: 0% (not documented)
✓ API Gateway: 85% (rate limiting not documented)

File Coverage:
- Documented: 45 files
- Undocumented: 21 files
- Total: 66 files

Undocumented Features:
1. Reporting system (src/reports/)
2. Background job processing (src/jobs/)
3. Email templates (src/templates/email/)
4. Admin dashboard (src/admin/)

Priority: Document payment processing and reporting next

Constitution Consistency Validation

Command:

/speckit.validate-constitution

Purpose: Verify that constitution principles match actual code patterns

Example prompt to give user:

/speckit.validate-constitution Check for:
- Stated patterns vs actual code patterns
- Tech stack completeness
- Contradictions between principles and code
- Coding standards accuracy

What this validates:

• Stated design patterns match actual usage
• Technology stack inventory is complete and accurate
• No contradictions between constitution principles and code
• Coding standards reflect actual conventions
• Architecture principles match implementation
• Documented dependencies are current

Example validation report:

Constitution Accuracy: 85%

✓ Design Patterns:
  - MVC architecture: Correctly identified
  - Repository pattern: Correctly documented

✗ Technology Stack Issues:
  - Constitution says "Redux" but code uses Zustand
  - Missing dependency: bull (job queue)
  - Outdated: PostgreSQL 12 (actually using 14)

✓ Coding Standards:
  - ESLint rules match actual .eslintrc
  - Naming conventions accurate

⚠ Architecture Principles:
  - Constitution mentions "microservices" but codebase is monolithic
  - Claims "stateless API" but sessions are used

Recommendations:
- Update constitution to reflect Zustand usage
- Add bull to tech stack inventory
- Clarify architecture: monolithic with service-oriented design
- Document session usage or migrate to stateless auth

Spec-to-Code Traceability

Command:

/speckit.trace [feature-name]

Purpose: Map specifications to source code bidirectionally

Example prompt to give user:

/speckit.trace authentication

/speckit.trace Show mapping between payment specs and implementation

What this shows:

• Which source files implement each feature
• Which specs describe each code module
• Bidirectional navigation (spec → code, code → spec)
• Orphaned specs (documented but not implemented)
• Orphaned code (implemented but not documented)

Example traceability report:

Feature: Authentication

Specifications:
- .speckit/features/existing/001-authentication/specify.md
- .speckit/features/existing/001-authentication/plan.md

Implementation Files:
✓ src/auth/login.ts (documented)
✓ src/auth/register.ts (documented)
✓ src/auth/jwt.ts (documented)
✓ src/auth/password-reset.ts (documented)
✗ src/auth/oauth-providers.ts (NOT in specs)
✓ src/middleware/auth-middleware.ts (documented)

Database Models:
✓ src/models/User.ts (documented)
✓ src/models/Session.ts (documented)

API Routes:
✓ POST /api/auth/login (documented)
✓ POST /api/auth/register (documented)
✓ POST /api/auth/logout (documented)
✓ POST /api/auth/reset-password (documented)
✗ GET /api/auth/oauth/:provider (NOT in specs)

Issues:
- OAuth integration implemented but not documented
- Consider adding to specifications or marking as deprecated

Traceability Score: 85% (11/13 components mapped)

Validation Workflow Example

Complete validation workflow after reverse-engineering:

# Step 1: Validate accuracy of reverse-engineering
/speckit.validate-reverse-engineering

# Review validation report - found 3 missing admin endpoints
# and incomplete payment workflow

# Step 2: Check coverage metrics
/speckit.coverage-check

# Coverage is 68% - reporting system and background jobs not documented
# Decision: Document payment processing now, defer reporting for later

# Step 3: Fill identified gaps
/speckit.reverse-engineer Document payment processing including:
- Payment refund workflow
- Admin endpoints for user management

# Step 4: Validate constitution accuracy
/speckit.validate-constitution

# Found tech stack mismatch (Redux vs Zustand)
# Update constitution.md manually to reflect actual tech stack

# Step 5: Check traceability for critical features
/speckit.trace authentication
/speckit.trace payment-processing

# OAuth integration not documented - add to specs
/speckit.reverse-engineer Document OAuth integration in authentication

# Step 6: Final validation
/speckit.validate-reverse-engineering
# All critical features now validated ✓

# Step 7: Generate validation report for team
/speckit.validation-report

When to Skip Validation

You can skip validation if:

• Using "constitution-only" strategy (no features to validate)
• Adding small feature to well-understood codebase
• Time-constrained and willing to accept risk
• Plan to validate incrementally as you work

When Validation is Critical

Always validate if:

• Using "full artifact suite" strategy
• Working on regulated/compliance-required system
• Large or unfamiliar codebase
• Multiple team members will rely on specs
• High risk of integration issues

Step 6: Specify New Feature (Standard SDD)

Command:

/speckit.specify

Purpose: Define new feature to add to existing codebase

Example prompt to give user:

/speckit.specify Add a user notification system that:
- Sends email and in-app notifications
- Allows users to configure notification preferences
- Integrates with existing authentication
- Supports notification templates

After this step - Summarize specify.md:

Follow the same summarization approach as greenfield (see Greenfield Workflow Step 3). Highlight:

• Main functional requirements for the new feature
• User stories specific to this feature
• Success criteria
• Integration requirements with existing systems

Example summary:

## New Feature Specification Created ✓

I've generated specify.md for the notification system:

**Core Features:**
- Email notifications via existing SMTP service
- In-app notification center with real-time updates
- User preference management (per-notification-type settings)
- Template-based notifications with variable substitution

**Integration Requirements:**
- Must use existing authentication/authorization
- Leverage current PostgreSQL database
- Integrate with RabbitMQ for async delivery
- Reuse existing email service configuration

**Success Criteria:**
- Notifications delivered within 5 seconds
- Support 10,000 concurrent users
- 99.9% delivery success rate
- GDPR-compliant preference storage

**Next Step:** Run `/speckit.integration-plan` to plan integration with existing code

Would you like to:
A) Proceed to integration planning
B) Refine requirements
C) Add more integration constraints

Step 7: Integration-Aware Implementation

Step 7a: Integration Planning

Command:

/speckit.integration-plan

Purpose: Plan how new feature integrates with existing code

Example prompt to give user:

/speckit.integration-plan How should the notification system integrate with:
- Existing user authentication
- Current database schema
- Email service configuration
- Frontend routing and components

What this produces:

• Integration points identified
• Required modifications to existing code
• Dependency analysis
• Migration strategy if needed

After this step - Summarize integration-plan:

Present a summary highlighting:

• Key integration points with existing systems
• Modifications required to existing code
• Dependencies and sequencing
• Risks and mitigation strategies

Example summary:

## Integration Plan Created ✓

I've created an integration plan for the notification system:

**Integration Points:**
1. **Authentication:** Reuse JWT middleware for API authentication
2. **Database:** Add `notifications` and `notification_preferences` tables to existing PostgreSQL
3. **Message Queue:** Create new RabbitMQ exchange `notifications` with routing keys
4. **Email Service:** Use existing `EmailService` class, extend with template support

**Required Modifications to Existing Code:**
1. **User Model:** Add `notification_preferences` relationship (non-breaking)
2. **Auth Middleware:** No changes needed (reuse as-is)
3. **Email Service:** Extend with `sendTemplatedEmail()` method
4. **Frontend:** Add NotificationCenter component, integrate with existing layout

**Task Sequencing:**
- Phase 1: Database migrations and models (2 days)
- Phase 2: Backend notification service (3 days)
- Phase 3: RabbitMQ integration (2 days)
- Phase 4: Frontend components (3 days)
- Phase 5: Testing and integration (2 days)

**Dependencies:**
- Must complete database migrations before backend service
- Email template service before notification delivery
- Backend API before frontend components

**Risks & Mitigation:**
- **Risk:** RabbitMQ queue overload during high traffic
  **Mitigation:** Implement rate limiting and queue monitoring
- **Risk:** Email service rate limits
  **Mitigation:** Batch emails, implement retry logic
- **Risk:** Database schema conflicts
  **Mitigation:** Review schema with DBA, use Sequelize migrations

**Next Step:** Run `/speckit.tasks` to break down into actionable tasks

Would you like to:
A) Proceed to task breakdown
B) Adjust integration approach
C) Address specific risks first

Step 7b: Create Tasks

Command:

/speckit.tasks

Purpose: Break down implementation considering integration

Enhanced for brownfield: Tasks include integration steps

After this step - Summarize tasks.md:

Follow the same summarization approach as greenfield (see Greenfield Workflow Step 5). Additionally highlight:

• Tasks that modify existing code (mark clearly)
• Integration-specific tasks
• Testing requirements for integration points

Step 7c: Execute Implementation

Command:

/speckit.implement

Purpose: Build the feature with integration awareness

Brownfield-Specific Commands

/speckit.brownfield

Initializes brownfield analysis workflow

Usage:

/speckit.brownfield [surface|moderate|deep]

Examples:

/speckit.brownfield
/speckit.brownfield deep
/speckit.brownfield Analyze this Express.js API focusing on routing patterns

/speckit.analyze-codebase

Deep dive analysis and constitution generation

Usage:

/speckit.analyze-codebase [focus-areas]

Examples:

/speckit.analyze-codebase
/speckit.analyze-codebase Focus on API design and data models
/speckit.analyze-codebase Include security patterns and authentication flows

/speckit.reverse-engineer

Generate SDD artifacts from existing code

Usage:

/speckit.reverse-engineer [strategy] [options]

Strategies:

• constitution-only: Just generate constitution.md
• baseline: Constitution + high-level feature specs
• full: Complete artifact suite
• mixed: Constitution + full specs for selected features

Examples:

/speckit.reverse-engineer constitution-only
/speckit.reverse-engineer mixed --core-features auth,payments
/speckit.reverse-engineer full

/speckit.integration-plan

Plan new feature integration with existing code

Usage:

/speckit.integration-plan [context]

Examples:

/speckit.integration-plan
/speckit.integration-plan Consider backward compatibility requirements
/speckit.integration-plan Minimize changes to existing database schema

Artifact Generation Strategies Explained

Constitution Only

.speckit/
└── constitution.md           # Existing patterns & principles

Pros:

• Quick setup
• Minimal documentation burden
• Focus on new work

Cons:

• No documentation for existing features
• Historical context not captured

Best for: Small teams, simple codebases, new feature focus

Constitution + Feature Specs

.speckit/
├── constitution.md
└── features/
    └── existing/
        ├── 001-auth/
        │   └── specify.md        # High-level overview
        └── 002-api/
            └── specify.md

Pros:

• Documents what exists
• Moderate effort
• Provides context for new work

Cons:

• Less detail than full suite
• No implementation plans

Best for: Medium-sized teams, moderate complexity, documentation backfill

Full Artifact Suite

.speckit/
├── constitution.md
└── features/
    └── existing/
        ├── 001-auth/
        │   ├── specify.md        # Detailed requirements
        │   ├── plan.md           # Implementation details
        │   └── architecture.md   # Design decisions
        └── 002-api/
            └── ...

Pros:

• Complete documentation
• Deep understanding captured
• Compliance-ready
• Excellent for onboarding

Cons:

• Significant time investment
• Can be overwhelming

Best for: Large teams, complex systems, regulated industries, legacy modernization

Baseline for New Work (Mixed)

.speckit/
├── constitution.md           # All existing code
└── features/
    ├── existing/
    │   └── 001-core-auth/    # Full specs for 2-3 key features
    │       ├── specify.md
    │       ├── plan.md
    │       └── architecture.md
    └── new/
        └── 001-notifications/ # Standard SDD for new work

Pros:

• Balanced approach
• Key features documented deeply
• Manageable scope
• Supports both existing and new

Cons:

• Requires choosing what to document
• Inconsistent depth

Best for: Most brownfield scenarios, pragmatic teams

Best Practices for Brownfield

1. Start Small, Prove Value

# Don't try to document everything at once
# Pick one new feature to add using SDD
specify init --here --ai claude
/speckit.brownfield surface
/speckit.analyze-codebase
/speckit.specify Add password strength indicator
/speckit.integration-plan
/speckit.tasks
/speckit.implement

2. Respect Existing Patterns

Your constitution should acknowledge current architecture:

## Existing Architecture Principles
- RESTful API design with Express.js (maintain)
- PostgreSQL with Sequelize ORM (maintain)
- JWT authentication (maintain)
- React frontend with Redux (migrating to Zustand)

## New Feature Guidelines
- Follow existing REST conventions
- Integrate with current auth system
- Use Sequelize for data access
- Prefer Zustand for new state management

3. Incremental Constitution Evolution

## Constitution Version History

### v1.0 - Initial (2024-01-15)
- Documented existing patterns
- Established code quality baselines

### v1.1 - First New Feature (2024-02-01)
- Added notification system principles
- Defined event-driven patterns

### v1.2 - Tech Stack Evolution (2024-03-15)
- Documented Redux → Zustand migration
- Updated state management guidelines

4. Integration Testing Focus

Brownfield implementations need extra testing:

## Integration Test Requirements
- Verify compatibility with existing auth
- Test database migration rollback
- Validate API backward compatibility
- Check frontend routing integration

5. Validate Before Building

Before adding new features, validate your reverse-engineering work:

# After reverse-engineering existing features
/speckit.validate-reverse-engineering
# Review report, identify inaccuracies

/speckit.coverage-check
# Check coverage percentage, find gaps

/speckit.validate-constitution
# Ensure constitution matches reality

/speckit.trace authentication
# Verify traceability for critical features

# Fix any identified issues before proceeding
/speckit.reverse-engineer --fill-gaps [missed-features]

Benefits:

• Catch documentation errors early
• Ensure specs match reality
• Build confidence in SDD artifacts
• Prevent integration issues later

6. Document Technical Debt

Use SDD to track and plan debt reduction:

## Known Technical Debt
- Auth system lacks rate limiting → Plan in 002-security-hardening
- Database queries not optimized → Address in 003-performance
- No input validation on older endpoints → Fix in 004-validation

Common Brownfield Scenarios

Scenario 1: Adding Feature to Production App

# Setup
cd existing-app
specify init --here --force --ai claude

# Workflow
/speckit.brownfield moderate
/speckit.analyze-codebase Focus on payment processing and user auth
/speckit.reverse-engineer constitution-only
/speckit.specify Add subscription management feature
/speckit.integration-plan Consider existing payment gateway integration
/speckit.tasks
/speckit.implement

Scenario 2: Legacy System Modernization

# Setup
cd legacy-system
specify init --here --ai claude

# Workflow
/speckit.brownfield deep --include-tech-debt
/speckit.analyze-codebase Document all major subsystems
/speckit.reverse-engineer full
# Review all generated specs
/speckit.specify Modernize authentication to OAuth 2.0
/speckit.integration-plan Migration strategy with zero downtime
/speckit.tasks
/speckit.implement

Scenario 3: Microservice Extraction

# Setup
cd monolith
specify init --here --ai claude

# Workflow
/speckit.brownfield moderate
/speckit.analyze-codebase Focus on notification subsystem
/speckit.reverse-engineer mixed --core-features notifications
/speckit.specify Extract notifications as independent microservice
/speckit.integration-plan API contracts and message queues
/speckit.tasks Include data migration and API versioning
/speckit.implement

Scenario 4: Compliance Documentation

# Setup (existing compliant system needs documentation)
cd production-app
specify init --here --ai claude

# Workflow
/speckit.brownfield deep
/speckit.analyze-codebase Include security controls and data handling
/speckit.reverse-engineer full --compliance-mode
# Generate comprehensive documentation for audit

Brownfield Troubleshooting

Issue: Constitution Conflicts with Existing Code

Problem: Generated constitution suggests patterns that don't match existing code

Solution: 1. Use /speckit.analyze-codebase with more specific guidance 2. Manually review and edit constitution.md 3. Add "Existing Patterns" vs "New Patterns" sections 4. Document migration path if changing patterns

Example Fix:

## Current State (Maintain)
- Class-based React components
- Redux for state management

## Future Direction (New Features)
- Functional components with hooks
- Zustand for state management

## Migration Strategy
- Maintain existing code as-is
- New features use modern patterns
- Refactor opportunistically

Issue: Too Many Features to Document

Problem: Large codebase with dozens of features, overwhelming to document all

Solution: 1. Use constitution-only strategy initially 2. Document features incrementally as you touch them 3. Prioritize: core features → frequently changed → rarely touched

Example Approach:

# Start minimal
/speckit.reverse-engineer constitution-only

# Add core features only
/speckit.reverse-engineer Document just authentication and payment processing

# Add more as you go
# When working on user-profile feature next month:
/speckit.reverse-engineer Document user profile management

Issue: Integration Points Not Clear

Problem: /speckit.integration-plan doesn't identify all integration points

Solution: 1. Run deeper analysis: /speckit.brownfield deep 2. Explicitly list integration concerns in prompt 3. Review generated plan and add missing points manually

Example:

/speckit.integration-plan Consider:
- Database schema changes (users table, notifications table)
- Existing API routes (/api/users)
- Authentication middleware
- Frontend routing (React Router)
- Email service configuration
- Background job processing

Issue: Existing Code Quality Issues

Problem: Existing code has quality issues, constitution documents them

Solution: 1. Use constitution to document current state honestly 2. Add "Quality Improvement Plan" section 3. Address issues incrementally with new features

Example Constitution Section:

## Current Code Quality Issues
- Inconsistent error handling
- Missing input validation in older endpoints
- No automated testing for legacy features

## Quality Improvement Plan
- New features: 100% test coverage required
- When modifying existing code: Add tests for modified functions
- Quarterly: Address one legacy area with full testing

## New Feature Standards
- Full unit and integration test coverage
- Input validation on all endpoints
- Consistent error handling with error codes

Issue: Validation Reveals Inaccuracies

Problem: /speckit.validate-reverse-engineering shows specs don't match actual code

Solution: 1. Review validation report for specific discrepancies 2. Re-run /speckit.reverse-engineer with more specific guidance 3. Manually edit specs in .speckit/features/existing/ 4. Re-validate until accuracy is acceptable

Example:

# Initial validation shows issues
/speckit.validate-reverse-engineering
# Report: "User Management: Missing 3 admin endpoints"

# Fix the gap
/speckit.reverse-engineer Document admin endpoints in user management:
- POST /api/admin/users/:id/suspend
- POST /api/admin/users/:id/restore
- DELETE /api/admin/users/:id/permanent-delete

# Re-validate
/speckit.validate-reverse-engineering
# Report: "User Management: All endpoints documented ✓"

Issue: Low Coverage Percentage

Problem: /speckit.coverage-check shows <50% coverage

Solution: 1. Decide on target coverage based on strategy (constitution-only vs full) 2. Use /speckit.reverse-engineer --fill-gaps for priority features 3. Document incrementally as you work on each area 4. Focus on documenting features you'll be modifying

Example:

# Check coverage
/speckit.coverage-check
# Report: "Overall Coverage: 45%"

# Decide on strategy
# Option A: Acceptable for constitution-only approach
# Option B: Need higher coverage for full artifact suite

# Fill gaps for features you'll work on
/speckit.reverse-engineer --fill-gaps payment-processing,reporting
/speckit.coverage-check
# Report: "Overall Coverage: 68%"

Issue: Constitution Validation Fails

Problem: /speckit.validate-constitution shows contradictions between principles and code

Solution: 1. Review validation report for specific conflicts 2. Decide: Update constitution or plan to change code 3. Document migration path if planning to change code 4. Re-validate after updates

Example:

# Validate constitution
/speckit.validate-constitution
# Report: "Constitution says 'Redux' but code uses Zustand"

# Fix: Update constitution to match reality
# Edit .speckit/constitution.md:
# Change: "Redux for state management"
# To: "Zustand for state management (migrated from Redux in v2.0)"

# Re-validate
/speckit.validate-constitution
# Report: "Constitution Accuracy: 95% ✓"

Issue: Traceability Gaps

Problem: /speckit.trace shows orphaned code or orphaned specs

Solution: 1. For orphaned code (implemented but not documented):

• Document with /speckit.reverse-engineer
• Or mark as deprecated if planned for removal

2. For orphaned specs (documented but not implemented):

• Remove from specs if feature was removed
• Or flag as planned future implementation

Example:

# Check traceability
/speckit.trace authentication
# Report: "OAuth integration implemented but not documented"

# Fix: Document the orphaned code
/speckit.reverse-engineer Document OAuth integration in authentication

# Or if OAuth should be removed:
# Update specs to mark OAuth as deprecated
# Add to technical debt list

Command Reference for Brownfield

Next Steps After Brownfield Setup

1. Validate Setup: Review generated constitution and artifacts 2. Add First Feature: Use standard SDD workflow for new feature 3. Iterate Constitution: Refine principles as you learn 4. Expand Documentation: Gradually document more existing features 5. Team Adoption: Share workflows with team members 6. Measure Impact: Track time saved, bugs reduced, onboarding speed

Feature Management Guide

Complete guide to managing features in Spec-Driven Development projects using natural language commands and automated tracking.

Overview

Claude automatically tracks feature status and provides natural language feature management for both greenfield and brownfield projects. This eliminates manual tracking and makes it easy to add, reorder, and monitor features throughout development.

Natural Language Commands

Adding Features

Just describe what you want:

"Add a new feature for user notifications"
"We need email integration"
"Let's add an admin dashboard"
"I want to build a reporting module"

Claude will: 1. Detect the feature request 2. Ask clarifying questions:

• What's the priority? (High/Medium/Low)
• What features does this depend on?
• Brief description of the feature?

3. Create a feature entry 4. Show updated feature status dashboard

Example interaction:

User: "Add a feature for user notifications"

Claude: I'll add "user-notifications" as a new feature. Let me ask a few questions:

1. **Priority**: High, Medium, or Low?
2. **Dependencies**: Does this depend on any existing features? (e.g., user-authentication)
3. **Brief description**: What should this feature do?

[User answers...]

Claude:
✅ Feature added: user-notifications

📊 Updated Feature List:
1. user-authentication (In Progress - 80%)
2. profile-management (Pending)
3. user-notifications (Pending) ← NEW
4. admin-dashboard (Pending)

Would you like to start specifying this feature now, or continue with the current feature?

Reordering Features

Natural commands:

"Move user-notifications before profile-management"
"Let's do admin-dashboard first"
"Swap the order of reporting and analytics"
"Prioritize email integration"

Example interaction:

User: "Let's do user-notifications before profile-management"

Claude:
Current order:
1. user-authentication (In Progress)
2. profile-management (Pending)
3. user-notifications (Pending)
4. admin-dashboard (Pending)

Proposed new order:
1. user-authentication (In Progress)
2. user-notifications (Pending) ← MOVED UP
3. profile-management (Pending)
4. admin-dashboard (Pending)

This will also update dependencies if needed.
Is this correct? (yes/no)

[User: yes]

Claude:
✅ Feature order updated!

📊 Feature Status: user-authentication (In Progress - 80%) → Next: user-notifications

Removing Features

Natural commands:

"Remove the reporting feature"
"Delete admin-dashboard from the list"
"We don't need email integration anymore"

Example interaction:

User: "Remove the reporting feature"

Claude:
⚠️  Warning: This will remove 'reporting' feature from the project.

**Impact Analysis:**
- Features depending on this: None
- Progress lost: 0% (not started)
- Artifacts to remove: None (not yet created)

Are you sure you want to remove this feature? (yes/no)

[User: yes]

Claude:
✅ Feature 'reporting' removed.

📊 Updated Feature List:
1. user-authentication (Complete - 100%)
2. profile-management (In Progress - 60%)
3. admin-dashboard (Pending)

Showing Feature Status

Natural commands:

"Show feature status"
"What's the current progress?"
"List all features"
"Show me the feature dashboard"

Displays full dashboard:

📊 Project Feature Status Dashboard

🎯 CURRENT FEATURE
├─ profile-management (Planning - 40% complete)
│  ├─ ✅ Requirements specified
│  ├─ 🔄 Implementation plan in progress
│  ├─ ⏸️  Tasks not started
│  └─ ⏸️  Implementation not started
│  Blockers: None
│  Dependencies: user-authentication ✅

✅ COMPLETED FEATURES (2)
├─ database-setup (100% complete)
└─ user-authentication (100% complete)

📋 UPCOMING FEATURES (2)
├─ user-notifications (depends on: user-authentication ✅)
└─ admin-dashboard (depends on: user-authentication ✅, profile-management ⏸️)

⚠️  BLOCKED FEATURES (0)

**Overall Progress:** 2 of 5 features complete (40%)

Querying Dependencies

Natural commands:

"What features depend on user-authentication?"
"What does profile-management depend on?"
"Show me the dependency tree"
"Can we start admin-dashboard yet?"

Example interaction:

User: "What features depend on user-authentication?"

Claude:
📊 user-authentication Dependencies

**Features that depend on user-authentication:**
├─ profile-management (⏸️ Pending)
├─ user-notifications (⏸️ Pending)
└─ admin-dashboard (⏸️ Pending)

**Status:** user-authentication is ✅ Complete
**Impact:** 3 features are now unblocked and ready to start

Would you like to start one of these features now?

Feature Status Tracking

Progress Stages

Each feature automatically tracks its progress through the SDD workflow:

Status Indicators

• ✅ Complete: Feature finished and tested
• 🔄 In Progress: Currently being worked on
• ⏸️ Pending: Not started, waiting
• ⚠️ Blocked: Cannot proceed due to dependencies or issues

Brief Status Line

After every SDD command, Claude shows a brief status line:

📊 **Feature Status:** profile-management (Planning) → Next: user-notifications
   Progress: [●●○○○] 40% | Completed: 2 of 5 features | Dependencies: user-authentication ✅

Components:

• Current feature and its stage
• Next feature in queue
• Progress bar visual (●○)
• Completion ratio (N of Total)
• Dependencies with status indicators

Dependency Management

Declaring Dependencies

Natural language:

"Profile-management depends on user-authentication"
"Admin-dashboard needs both user-auth and profile-management"
"User-notifications requires user-authentication"

Claude automatically: 1. Records the dependency relationship 2. Updates the dependency tree 3. Checks for circular dependencies 4. Calculates which features are blocked

Checking Dependencies

Before starting a feature:

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

   All dependencies satisfied! Ready to proceed.

If dependencies not met:

📊 Can we start admin-dashboard?
   Checking dependencies...
   ✅ user-authentication (complete)
   ⏸️ profile-management (in progress - 60%)

   ⚠️  Not all dependencies satisfied.
   Blocked by: profile-management (needs 40% more progress)

   Estimated wait: Complete profile-management first

Circular Dependency Detection

Claude automatically detects circular dependencies:

⚠️  Warning: Circular dependency detected!

feature-A depends on feature-B
feature-B depends on feature-C
feature-C depends on feature-A

**How to resolve:**
1. Remove one of the dependencies
2. Extract shared functionality into a new base feature
3. Reconsider the feature boundaries

Would you like help resolving this?

Multi-Feature Project Structure

File Organization

.speckit/
├── constitution.md           # Project-wide principles
├── features/
│   ├── 001-database-setup/
│   │   ├── specify.md        # ✅ Complete
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   └── implementation/   # Code generated
│   ├── 002-user-auth/
│   │   ├── specify.md        # ✅ Complete
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   └── implementation/
│   ├── 003-profile-mgmt/
│   │   ├── specify.md        # 🔄 In Progress
│   │   ├── plan.md
│   │   └── tasks.md          # ⏸️ Not started
│   ├── 004-user-notifications/
│   │   └── specify.md        # ⏸️ Pending
│   └── 005-admin-dashboard/
│       └── (empty)           # ⏸️ Not started
└── .claude/commands/         # SDD slash commands

Feature Naming Convention

Recommended pattern:

• 001-feature-name (numbered for ordering)
• user-authentication (descriptive, lowercase, hyphenated)
• admin-dashboard (clear, concise)

Avoid:

• Single words without context (auth, admin)
• Vague names (feature1, module)
• Inconsistent casing (UserAuth, user_auth)

Advanced Feature Operations

Bulk Operations

Adding multiple features at once:

User: "Add these features: user-notifications, email-integration, admin-dashboard, reporting"

Claude:
I'll add 4 new features. For each, I'll need some details:

**1. user-notifications**
   - Priority? (High/Medium/Low)
   - Dependencies?
   - Brief description?

[Repeat for each feature...]

Claude:
✅ Added 4 features:
1. user-notifications (High priority, depends on: user-auth)
2. email-integration (Medium priority, depends on: user-auth)
3. admin-dashboard (High priority, depends on: user-auth, profile-mgmt)
4. reporting (Low priority, depends on: admin-dashboard)

📊 Total features: 7 (3 complete, 1 in progress, 3 pending)

Feature Templates

For common feature types, Claude can use templates:

User: "Add a CRUD feature for products"

Claude:
I'll create a CRUD feature using the standard template:

**Features to add:**
1. product-list (display all products)
2. product-create (create new product)
3. product-edit (update existing product)
4. product-delete (remove product)

Or would you prefer a single "product-management" feature with all CRUD operations?

**Choose:**
A) 4 separate features (more granular tracking)
B) 1 combined feature (simpler, faster)

Feature Merging

Combining related features:

User: "Merge user-notifications and email-integration into one feature"

Claude:
I'll merge these features:

**Current:**
- user-notifications (Specified - 20%)
- email-integration (Pending - 0%)

**Merged feature:**
- user-communication (combines both)
  - Inherits progress from user-notifications (20%)
  - Includes email integration requirements
  - Dependencies: user-authentication ✅

**Artifacts to merge:**
- Combine specify.md files
- Update dependencies

Proceed with merge? (yes/no)

Greenfield vs Brownfield Differences

Greenfield Feature Management

Starting fresh:

• All features tracked from the beginning
• Clear dependency tree from design
• Progressive addition as project evolves
• No legacy features to document

Example workflow:

1. Initialize project
2. Create constitution
3. Specify first feature → Feature tracking begins
4. Add more features as needed
5. Track all features through completion

Brownfield Feature Management

Working with existing code:

• Existing features: Discovered through reverse-engineering
• New features: Added via SDD workflow
• Mixed tracking: Both documented and new features
• Integration awareness: New features must integrate with existing

Example workflow:

1. Analyze existing codebase
2. Reverse-engineer major features (optional)
3. Add new feature → Track alongside existing
4. Show integration impact on status
5. Track dependencies on existing features

Status display for brownfield:

📊 Project Feature Status Dashboard

📚 EXISTING FEATURES (Documented)
├─ user-authentication (Existing - documented)
├─ profile-management (Existing - documented)
└─ basic-reporting (Existing - not documented)

🎯 CURRENT SDD FEATURE
├─ advanced-analytics (Planning - 40% complete)
│  Dependencies: basic-reporting (existing ✅)

📋 UPCOMING SDD FEATURES (2)
├─ email-notifications (depends on: user-authentication existing ✅)
└─ admin-dashboard (depends on: advanced-analytics ⏸️)

Best Practices

1. Clear Naming

✅ Good:

• user-authentication
• email-notifications
• advanced-reporting

❌ Avoid:

• auth
• emails
• reports

2. Granularity

Too granular:

- login-form
- login-validation
- login-error-handling
- login-success-redirect

Better:

- user-authentication (includes all login functionality)

Too coarse:

- user-module (authentication, profile, preferences, notifications)

Better:

- user-authentication
- user-profile
- user-preferences
- user-notifications

3. Dependency Management

Declare early:

When specifying: "This depends on user-auth"
Not later: "Oh, we need user-auth first"

Keep shallow:

✅ Feature A → Feature B → Feature C (3 levels)
❌ Feature A → B → C → D → E → F (6 levels)

4. Progress Updates

Let Claude track automatically:

• Don't manually update progress
• Trust the artifact detection
• Inform Claude when features complete

Example:

User: "We finished implementing user-auth"

Claude:
✅ Updating user-authentication to 100% complete!

Running final checks:
- ✅ specify.md exists
- ✅ plan.md exists
- ✅ tasks.md exists
- ✅ Implementation complete
- 🔄 Checking tests...

Tests passing? (yes/no)

[User: yes]

Claude:
✅ user-authentication marked as COMPLETE!

📊 Features: 3 of 7 complete (43%)
🎯 Next feature: profile-management

Ready to start profile-management? (yes/no)

Troubleshooting

Feature Not Tracked

Problem: Claude doesn't recognize a feature

Solution:

User: "Why isn't email-integration showing in the status?"

Claude:
Let me check the feature list...

I don't see "email-integration" in the tracked features.

**Possible reasons:**
1. Feature was never added
2. Feature was removed
3. Feature has a different name

Would you like to:
A) Add "email-integration" as a new feature
B) Show me all tracked features
C) Search for similar feature names

Dependency Confusion

Problem: Unclear what depends on what

Solution:

User: "What's blocking admin-dashboard?"

Claude:
📊 admin-dashboard Dependency Analysis

**Required dependencies:**
├─ user-authentication ✅ (complete)
├─ profile-management ⏸️ (in progress - 60%)
└─ reporting ⏸️ (pending - not started)

**Blocking status:**
⚠️  Blocked by 2 features:
1. profile-management (needs 40% more)
2. reporting (not started)

**Recommendation:**
Complete profile-management, then start reporting before admin-dashboard.

Estimated time to unblock: [Based on current velocity]

Lost Progress

Problem: Feature showing incorrect progress

Solution:

User: "User-auth shows 40% but we finished it"

Claude:
Let me verify user-authentication status...

**Artifact check:**
- ✅ specify.md exists
- ✅ plan.md exists
- ✅ tasks.md exists
- ❌ Implementation not detected

**Issue:** Implementation not marked complete

**To fix:**
1. Confirm implementation is done
2. Confirm tests pass
3. I'll update status to 100%

Is implementation complete with passing tests? (yes/no)

[User: yes]

Claude:
✅ Updated user-authentication to 100% complete!

Feature Management Reference

Quick Command Reference

Detection Patterns

Claude automatically detects these patterns:

• Add: "add", "create", "new feature", "build", "implement"
• Move: "move", "reorder", "prioritize", "before", "after", "first"
• Remove: "remove", "delete", "drop", "cancel"
• Status: "show", "list", "status", "progress", "dashboard"
• Dependencies: "depends", "requires", "needs", "blocks", "blocked by"
• Complete: "finished", "done", "completed", "ready"

Integration with SDD Workflow

Feature management is automatically integrated with all SDD commands:

/speckit.specify → Asks about features, tracks new feature
/speckit.plan → Shows feature status, updates progress to 40%
/speckit.tasks → Updates progress to 60%
/speckit.implement → Updates progress to 80%
[Tests pass] → Updates progress to 100%, shows next feature

Every command includes a brief status line in its summary, and users can request full status anytime with option [D] or by asking "show feature status".

---

For more information, see:

• SKILL.md - Main skill file with feature tracking section
• Greenfield Workflow - Feature management for new projects
• Brownfield Workflow - Feature management for existing codebases

Greenfield Workflow: Building from Scratch with SDD

When to Use Greenfield Workflow

Use this workflow when:

• Starting a brand new project (0-to-1 development)
• Building a proof-of-concept or prototype
• Creating a new microservice or application component
• No existing codebase exists yet

For existing codebases, see Brownfield Workflow.

The 6-Step Greenfield Workflow

Step 1: Initialize Project

# Basic initialization
specify init my-project

# With specific AI assistant
specify init my-project --ai claude
specify init my-project --ai cursor-agent
specify init my-project --ai windsurf
specify init my-project --ai copilot

# Initialize in current directory
specify init . --ai claude
# or
specify init --here --ai claude

# With PowerShell scripts (Windows/cross-platform)
specify init my-project --ai copilot --script ps

# Skip git initialization
specify init my-project --ai gemini --no-git

# Debug mode
specify init my-project --ai claude --debug

# With GitHub token (corporate environments)
specify init my-project --ai claude --github-token ghp_your_token_here

Step 2: Establish Project Principles

Launch AI assistant in project directory and use:

/speckit.constitution

Purpose: Create project's governing principles and development guidelines

Example prompt to give user:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

After this step - Summarize constitution.md:

Read .speckit/constitution.md and use the 10-point summary template from SKILL.md:

Example enhanced summary:

## ✅ Constitution Completed - Here's What Just Happened

### 🎯 Key Decisions Made
1. **Testing requirement: 80%+ code coverage** - Rationale: Ensures reliability and reduces production bugs
2. **TypeScript for all code** - Rationale: Type safety catches errors at compile-time, improves maintainability
3. **Performance target: <3s page load, 60fps** - Rationale: Industry standards for good user experience

### 📋 What Was Generated
- `.speckit/constitution.md`: Complete project principles covering quality, UX, performance, and coding standards

### 🔍 Important Items to Review
1. **80%+ test coverage requirement** - Verify this is achievable for your team's velocity and timeline
2. **WCAG 2.1 AA accessibility** - Confirm you have the expertise or resources for accessibility compliance
3. **TypeScript mandate** - Ensure team is comfortable with TypeScript or plan for learning curve

### ⚠️ Watch Out For
- **Functional programming preference** - How to avoid: May require team training if team is more OOP-oriented
- **Comprehensive JSDoc requirement** - How to avoid: This adds documentation overhead; ensure team buy-in

### 🔄 What This Enables Next
- **Option 1:** Run `/speckit.specify` to define feature requirements - Best if: Principles look good
- **Option 2:** Modify constitution.md - Best if: You need to adjust standards or add principles

📊 **Feature Status:** Initializing project (Constitution created)
   Progress: [●○○○○] 0% features (no features specified yet)

**Your options:** [A] Proceed to specification [B] Adjust principles [C] Explain testing requirements [D] Show full status

Step 3: Create the Specification

/speckit.specify

Purpose: Describe what to build - focus on WHAT and WHY, not tech stack

Example prompt to give user:

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

After this step - Summarize specify.md:

Read .speckit/features/[feature-number]/specify.md and use the 10-point summary template from SKILL.md.

Also ask: "Do you have multiple features to implement, or is this a single-feature project?" This helps establish feature tracking.

Example enhanced summary:

## ✅ Specify Completed - Here's What Just Happened

### 🎯 Key Decisions Made
1. **Drag-and-drop interface for album organization** - Rationale: Natural, intuitive interaction for visual content organization
2. **Local-only storage (no cloud)** - Rationale: Privacy-first approach, no server costs, works offline
3. **SQLite for metadata** - Rationale: Lightweight, serverless, perfect for local desktop apps

### 📋 What Was Generated
- `.speckit/features/001-photo-album-manager/specify.md`: 3 core features, 5 user stories, 4 success criteria, 3 edge cases

### 🔍 Important Items to Review
1. **2-second load time for 1000 photos** - Verify this is achievable with thumbnails and lazy loading; may need caching strategy
2. **HEIC format support** - Check if browser/platform supports HEIC natively or if conversion library needed
3. **Keyboard navigation requirement** - Review specific keyboard shortcuts needed for accessibility compliance

### ⚠️ Watch Out For
- **No nested albums constraint** - How to avoid: Make sure UI clearly communicates this limitation to users
- **100+ photo drag-and-drop performance** - How to avoid: May need virtual scrolling or batching for large selections

### 🔄 What This Enables Next
- **Option 1:** Run `/speckit.plan` to design technical architecture - Best if: Requirements are clear
- **Option 2:** Run `/speckit.clarify` to explore edge cases - Best if: You want to refine edge case handling first
- **Option 3:** Modify specify.md - Best if: Requirements need adjustment

📊 **Feature Status:** photo-album-manager (Specified) → Next: (ask user if more features planned)
   Progress: [●○○○○] 20% | Completed: 0 of 1 features | Dependencies: None

**Your options:** [A] Proceed to planning [B] Modify requirements [C] Clarify edge cases [D] Show full status

**Do you have multiple features planned?** If yes, tell me what other features you're considering so I can track them.

Step 4: Create Technical Implementation Plan

/speckit.plan

Purpose: Provide tech stack and architecture choices

Example prompt to give user:

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

After this step - Summarize plan.md:

Read .speckit/features/[feature-number]/plan.md and use the 10-point summary template from SKILL.md.

Example enhanced summary:

## ✅ Plan Completed - Here's What Just Happened

### 🎯 Key Decisions Made
1. **Vite + Vanilla JavaScript** - Rationale: Fast dev experience without framework lock-in; keeps bundle small
2. **sql.js for SQLite in browser** - Rationale: Client-side database without server; full SQL capabilities
3. **Web Workers for image processing** - Rationale: Prevents UI blocking when generating thumbnails for large albums

### 📋 What Was Generated
- `.speckit/features/001-photo-album-manager/plan.md`: Complete technical architecture with 5 implementation phases, 3 key dependencies

### 🔍 Important Items to Review
1. **sql.js browser compatibility** - Verify it works in target browsers (especially Safari); may need fallback to IndexedDB
2. **Web Worker browser support** - Check that all target browsers support Workers; have fallback for older browsers
3. **10-day implementation timeline** - Validate this is realistic for your team; includes buffer time?

### ⚠️ Watch Out For
- **sharp library is Node.js only** - How to avoid: Use browser-native Canvas API or WebAssembly solution like @squoosh/lib
- **Service Worker requires HTTPS** - How to avoid: Plan for HTTPS in local dev (Vite supports this) and production

### 🔄 What This Enables Next
- **Option 1:** Run `/speckit.tasks` to break down into actionable tasks - Best if: Architecture is solid
- **Option 2:** Modify plan.md - Best if: You want to adjust tech stack or dependencies
- **Option 3:** Run `/speckit.analyze` to check consistency - Best if: Want to validate against constitution

📊 **Feature Status:** photo-album-manager (Planned) → Next: (same feature continues to tasks)
   Progress: [●●○○○] 40% | Completed: 0 of 1 features | Dependencies: None

**Your options:** [A] Proceed to tasks [B] Adjust architecture [C] Analyze consistency [D] Show full status

Step 5: Break Down into Tasks

/speckit.tasks

Purpose: Create actionable task list from implementation plan

After this step - Summarize tasks.md:

Read .speckit/features/[feature-number]/tasks.md and use the 10-point summary template from SKILL.md.

Example enhanced summary:

## ✅ Tasks Completed - Here's What Just Happened

### 🎯 Key Decisions Made
1. **18 tasks organized into 5 categories** - Rationale: Logical grouping by technical domain for clear separation of concerns
2. **Database setup as early critical path** - Rationale: Many features depend on database; completing early unblocks parallel work
3. **High complexity tasks: 3 (Database integration, DnD state, Image caching)** - Rationale: These require careful architecture and testing

### 📋 What Was Generated
- `.speckit/features/001-photo-album-manager/tasks.md`: 18 actionable tasks across UI, DnD, Database, Image handling, Testing

### 🔍 Important Items to Review
1. **10-day timeline estimate** - Realistic for team? Includes testing time? May need buffer for unknowns
2. **Critical path dependencies** - Database must complete first; this could block progress if delayed
3. **Testing tasks at the end** - Consider moving some testing earlier (TDD approach) for better quality

### ⚠️ Watch Out For
- **3 high-complexity tasks** - How to avoid: Allocate senior developers; consider pairing or extra time estimates
- **All UI before DnD** - How to avoid: This sequential approach may delay integration; consider overlapping if possible

### 🔄 What This Enables Next
- **Option 1:** Run `/speckit.implement` to start implementation - Best if: Tasks are clear and prioritized
- **Option 2:** Reorder tasks - Best if: You want to adjust priorities or dependencies
- **Option 3:** Run `/speckit.checklist` for quality verification - Best if: Want comprehensive testing criteria
- **Option 4:** Run `/speckit.analyze` - Best if: Want to validate task coverage against requirements

📊 **Feature Status:** photo-album-manager (Tasked - ready for implementation) → Next: Implementation
   Progress: [●●●○○] 60% | Completed: 0 of 1 features | Dependencies: None

**Your options:** [A] Start implementation [B] Reorder tasks [C] Generate checklist [D] Show full status

Step 6: Execute Implementation

/speckit.implement

Purpose: Execute all tasks and build the feature

Optional Enhancement Commands

Use these for additional quality and validation:

Clarify Underspecified Areas

/speckit.clarify

When to use: After /speckit.specify, before /speckit.plan Purpose: Identify and clarify ambiguous requirements

Analyze Consistency & Coverage

/speckit.analyze

When to use: After /speckit.tasks, before /speckit.implement Purpose: Cross-artifact consistency and coverage analysis

Generate Quality Checklists

/speckit.checklist

Purpose: Create custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English")

Managing Multiple Features

Adding New Features

When working with multiple features in a greenfield project, Claude automatically tracks feature status and helps you manage them.

Natural Language Commands:

"Add a new feature for user notifications"
"Let's work on email integration next"
"Move the admin dashboard feature before reporting"
"Show me all planned features"
"What features depend on user-authentication?"

Claude will: 1. Detect your feature management request 2. Ask clarifying questions (priority, dependencies, description) 3. Update the feature list 4. Show updated feature status dashboard

Feature Status Tracking

After establishing multiple features (typically after first /speckit.specify), Claude tracks:

• Current feature being worked on
• Completed features (100% through workflow)
• Upcoming features (not yet started)
• Dependencies between features
• Progress for each feature (Specified, Planned, Tasked, In Progress, Complete)

Example status display:

📊 Project Feature Status Dashboard

🎯 CURRENT FEATURE
├─ user-authentication (Planning - 40% complete)
│  ├─ ✅ Requirements specified
│  ├─ 🔄 Implementation plan in progress
│  ├─ ⏸️  Tasks not started
│  └─ ⏸️  Implementation not started
│  Dependencies: database-setup ✅

✅ COMPLETED FEATURES (1)
└─ database-setup (100% complete)

📋 UPCOMING FEATURES (2)
├─ profile-management (depends on: user-authentication)
└─ admin-dashboard (depends on: user-authentication, profile-management)

Reordering Features

User request: "Let's do profile-management before admin-dashboard"

Claude response:

Current order:
1. user-authentication (In Progress)
2. admin-dashboard (Pending)
3. profile-management (Pending)

Proposed new order:
1. user-authentication (In Progress)
2. profile-management (Pending)
3. admin-dashboard (Pending - will update dependency)

Is this correct? (yes/no)

Feature Dependencies

Claude automatically tracks dependencies when you mention them:

"User authentication depends on database-setup"
"Profile management needs user-authentication first"

Dependency checking:

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

   All dependencies satisfied! Ready to proceed.

For complete feature management capabilities, see Feature Management Guide.

Artifacts Generated

After running SDD commands, the following artifacts are created:

Project Structure

project-name/
├── .speckit/
│   ├── constitution.md      # Project principles
│   ├── features/
│   │   └── 001-feature-name/
│   │       ├── specify.md    # Requirements & user stories
│   │       ├── plan.md       # Technical implementation plan
│   │       ├── tasks.md      # Actionable task list
│   │       └── checklist.md  # Quality validation checklist
│   └── .claude/
│       └── commands/         # Slash command definitions
└── [your application code]

Key Artifacts to Reference

1. constitution.md: Project-wide principles and guidelines 2. specify.md: Requirements and user stories for current feature 3. plan.md: Technical implementation plan with architecture decisions 4. tasks.md: Task breakdown for implementation 5. checklist.md: Quality validation criteria

Workflow Best Practices

For Users New to SDD

1. Start small: Begin with a simple feature to learn the workflow 2. Follow the sequence: Don't skip steps (constitution → specify → plan → tasks → implement) 3. Be specific in specify: The more detailed your requirements, the better the output 4. Review artifacts: After each step, review the generated artifacts before proceeding 5. Use clarify: Don't hesitate to use /speckit.clarify if requirements are unclear

For Experienced Users

1. Parallel exploration: Use creative exploration phase for multiple implementation approaches 2. Custom checklists: Define project-specific quality gates with /speckit.checklist 3. Analyze before implement: Always run /speckit.analyze to catch issues early 4. Iterate on constitution: Refine project principles as you learn

For Enterprise Teams

1. Establish constitution early: Include organizational constraints, compliance requirements, design systems 2. Version control everything: All .speckit/ artifacts should be in Git 3. Use feature branches: Let Git branches drive feature detection 4. Document tech stack constraints: Be explicit in /speckit.plan about approved technologies

Advanced Usage Patterns

Multi-Stack Exploration

For creative exploration of different tech stacks:

# Create multiple feature branches
git checkout -b feature-001-react
/speckit.plan Use React with TypeScript...
/speckit.tasks
/speckit.implement

git checkout -b feature-001-vue
/speckit.plan Use Vue 3 with Composition API...
/speckit.tasks
/speckit.implement

Corporate/Enterprise Setup

# Initialize with corporate GitHub token
specify init my-project --ai claude --github-token $GITHUB_TOKEN

# Constitution with enterprise constraints
/speckit.constitution
- Must use approved cloud providers (AWS, Azure)
- Follow internal design system
- Comply with SOC2 requirements
- Use approved open source licenses only

Command Reference

Example: Complete Greenfield Workflow

# Step 1: Install and initialize
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init photo-organizer --ai claude

# Step 2: In your AI agent
/speckit.constitution Create principles focused on:
- Simple, intuitive user interfaces
- Data privacy (no cloud uploads)
- Fast, responsive performance
- Minimal dependencies

# Step 3: Specify the feature
/speckit.specify Build a photo organization app with drag-and-drop albums,
date-based grouping, and tile-based photo previews within albums

# Step 4: Technical planning
/speckit.plan Use Vite, vanilla JS, HTML5 drag-and-drop API,
and SQLite for local storage

# Step 5: Break down tasks
/speckit.tasks

# Step 6: Implement
/speckit.implement

Next Steps

After completing greenfield implementation:

• Run tests and validation
• Review generated code against constitution
• Iterate with additional features following the same workflow
• Consider using /speckit.checklist to define quality standards for future work

SDD Installation & Setup Guide

Installation Methods

Method 1: Persistent Installation (Recommended)

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

Benefits:

• Tool stays installed and available in PATH
• Better tool management: uv tool list, uv tool upgrade, uv tool uninstall
• Cleaner shell configuration

Usage after installation:

specify init <PROJECT_NAME>
specify check

Upgrade:

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

Method 2: One-time Usage

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

Verify Installation

specify check

This checks for:

• git
• AI coding agents (claude, gemini, copilot, cursor, windsurf, etc.)
• Other required tools

Prerequisites

• Linux/macOS/Windows
• Supported AI coding agent
• uv for package management
• Python 3.11+
• Git

Environment Variables

SPECIFY_FEATURE

Purpose: Override feature detection for non-Git repositories

Usage:

export SPECIFY_FEATURE=001-photo-albums

When needed: Working on a specific feature when not using Git branches

Important: Must be set in the context of the agent before using /speckit.plan or follow-up commands

Troubleshooting

Git Credential Manager on Linux

If having Git authentication issues on Linux:

#!/usr/bin/env bash
set -e
echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

Common Issues

Issue: "specify: command not found"

• Solution: Ensure uv is installed and PATH is configured correctly
• Check: Run uv tool list to verify installation

Issue: Slash commands not available in AI agent

• Solution: Ensure you ran specify init in the project directory
• Check: Look for .claude/commands/ directory with command definitions

Issue: Feature detection not working

• Solution: Either use Git branches or set SPECIFY_FEATURE environment variable
• Check: Verify you're on the correct Git branch or the env var is set in agent context

Issue: AI agent not generating expected artifacts

• Solution: Ensure you're following the workflow sequence in order
• Check: Review previous artifacts for completeness before proceeding

Initialization Options

Basic Initialization

# Basic initialization
specify init my-project

# With specific AI assistant
specify init my-project --ai claude
specify init my-project --ai cursor-agent
specify init my-project --ai windsurf
specify init my-project --ai copilot

# Initialize in current directory
specify init . --ai claude
# or
specify init --here --ai claude

# Force merge into non-empty directory
specify init . --force --ai claude

# With PowerShell scripts (Windows/cross-platform)
specify init my-project --ai copilot --script ps

# Skip git initialization
specify init my-project --ai gemini --no-git

# Debug mode
specify init my-project --ai claude --debug

# With GitHub token (corporate environments)
specify init my-project --ai claude --github-token ghp_your_token_here

Resources

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