spec-driven-development

What this skill does

# Spec-Driven Development (SDD)

This skill implements GitHub's SpecKit methodology for structured, AI-assisted software development. SpecKit transforms
specifications into executable artifacts through a systematic, phase-based approach with built-in quality gates and
multi-agent coordination.

## Core Philosophy

**"Specifications become executable, directly generating working implementations rather than just guiding them."**

## When to Use This Skill

- Starting new projects that require structured development
- Coordinating multiple AI agents or developers on complex features
- Ensuring consistent quality through constitutional governance
- Breaking down complex features into manageable, parallel work
- Preventing premature implementation before clear specifications
- Enterprise projects with strict governance requirements
- Teams needing real-time visibility across multiple features

## The 7-Phase Workflow

### Phase 0: Project Initialization

**Purpose:** Create project structure and configure development environment

**Artifacts:**

- `.specify/` directory structure
- Git repository
- Automation scripts
- Templates

**Key Actions:**

- Set up directory structure
- Initialize version control
- Configure AI agent preferences
- Generate script variants (bash/powershell)

### Phase 1: Constitution

**Purpose:** Establish project governance and development principles

**Artifact:** `memory/constitution.md`

**Core Principles:**

1. **Library-First Principle:** Every feature starts as a standalone library
2. **CLI Interface Mandate:** All libraries must have text-based interfaces
3. **Test-First Imperative:** Tests must precede implementation
4. **Simplicity and Anti-Abstraction:** Minimize complexity
5. **Integration-First Testing:** Prioritize realistic testing environments

**Versioning:** Semantic versioning (MAJOR.MINOR.PATCH)

- MAJOR: Backward-incompatible governance changes
- MINOR: New principles or material expansions
- PATCH: Minor clarifications or refinements

**Orchestration:** Interactive principle definition with validation across all artifacts

### Phase 2: Specification

**Purpose:** Create detailed feature specifications focused on WHAT and WHY, not HOW

**Artifact:** `specs/[feature]/spec.md`

**Required Sections:**

- Feature branch name (2-4 words)
- User scenarios (P1, P2, P3 prioritized)
- Acceptance scenarios (Given/When/Then format)
- Edge cases
- Functional requirements (FR-XXX)
- Key entities
- Success criteria (measurable, technology-agnostic)

**Key Constraints:**

- Focus on business value, not implementation
- Write for stakeholders, not developers
- Maximum 3 clarification markers for critical unknowns
- Each user story must be independently testable

**Quality Gates:**

- Content quality validation
- Requirement completeness check
- Feature readiness assessment
- Success criteria measurability

### Phase 3: Clarification

**Purpose:** Systematically identify and resolve ambiguities in specifications

**Artifact:** Updates `specs/[feature]/spec.md`

**Clarification Dimensions:**

- Functional scope
- Data model
- User experience (UX)
- Non-functional attributes (performance, security, etc.)
- Integration points

**Key Constraints:**

- Maximum 5 questions per session
- Multiple-choice or short-answer format
- Focus on high-impact, implementation-critical uncertainties
- One question at a time for iterative refinement

**Orchestration:** Interactive questioning workflow with incremental spec updates after each answer

### Phase 4: Planning

**Purpose:** Create technical implementation strategy and resolve technical unknowns

**Sub-Phases:**

**Phase 0 - Research:**

- Identify and research technical unknowns
- Output: `research.md` with all uncertainties resolved
- **Gate:** ERROR on unresolved clarifications

**Phase 1 - Design:**

- Create data models and API contracts
- Outputs: `data-model.md`, contract schemas, agent-specific context

**Artifacts:**

- `specs/[feature]/plan.md`
- `specs/[feature]/research.md`
- `specs/[feature]/data-model.md`
- `specs/[feature]/contracts/`

**Plan Sections:**

- Feature summary
- Technical context (language, dependencies, platform)
- Project structure
- Repository layout
- Complexity tracking for non-standard approaches

### Phase 5: Analysis

**Purpose:** Validate cross-artifact consistency before implementation

**Artifacts Analyzed:**

- `specs/[feature]/spec.md`
- `specs/[feature]/plan.md`
- `specs/[feature]/tasks.md`

**Detection Passes:**

1. Duplications
2. Ambiguities
3. Underspecified items
4. Constitution conflicts

**Output:** Analysis report with severity-ranked findings (max 50 high-signal issues)

**Key Constraints:**

- Read-only operation (cannot modify files)
- Must run after task breakdown
- Prioritizes constitution principles

### Phase 6: Task Breakdown

**Purpose:** Generate actionable, dependency-ordered task list from plan

**Artifact:** `specs/[feature]/tasks.md`

**Task Structure:**

- Checkbox for completion tracking
- Sequential Task ID
- Optional parallelization marker (`||`)
- Story label (P1, P2, P3 when applicable)
- Precise file path
- Clear description

**Phase Structure:**

1. **Phase 1:** Project Setup
2. **Phase 2:** Foundational Prerequisites (BLOCKING - must complete before user stories)
3. **Phase 3+:** User Story Implementation (priority order: P1 → P2 → P3)
4. **Final Phase:** Polish & Cross-Cutting Concerns

**Key Principles:**

- Tasks grouped by user story for independent implementation
- Each story independently testable and deliverable
- Clear dependency tracking
- Explicit parallelization markers
- No user story work until foundational phase complete

### Phase 7: Implementation

**Purpose:** Execute implementation phase-by-phase with built-in validation

**8-Stage Process:**

1. **Prerequisite Checking:** Validate project readiness
2. **Checklist Validation:** Count completed/incomplete items, require confirmation if incomplete
3. **Context Analysis:** Read required artifacts (tasks.md, plan.md) and optional ones
4. **Project Setup:** Create/verify ignore files for detected technologies
5. **Task Processing:** Parse tasks, extract phases, dependencies, execution flow
6. **Phased Implementation:** Execute tasks phase-by-phase following TDD
7. **Error Handling:** Report progress, handle failures, provide debugging context
8. **Final Validation:** Confirm completion, validate implementation, check test coverage

**Orchestration:** Systematic multi-stage execution with built-in checks and balances

## Orchestration & Parallel Execution

### Core Orchestration Philosophy

**Sequential phase progression with parallel execution within phases where dependencies allow.**

### Coordination Mechanisms

#### 1. Phase-Based Gates

- Each phase must complete and validate before next phase begins
- Gates block on errors or unresolved issues
- Implementation: Template validation, checklist requirements, constitution alignment checks

#### 2. Dependency Tracking

- Tasks marked with dependencies that must be resolved before execution
- Foundational phase blocks all user story work
- Tasks reference prerequisites explicitly

#### 3. Parallelization Markers

- Tasks explicitly marked for parallel execution when no dependencies exist
- Optional `||` marker in task format
- Indicates tasks can run concurrently

#### 4. User Story Grouping

- Tasks grouped by user story for independent, parallel implementation
- Each user story is independently testable and deliverable
- Enables multiple agents/developers to work simultaneously

#### 5. Constitutional Consistency

- All phases reference constitution to maintain consistent practices
- Constitution loaded and validated across all commands
- Ensures alignment across parallel work streams

### Parallel Execution Patterns

#### Pattern 1: User Story Parallelization

After foundational phase completes, user stories (P1, P2, P3) can be implemented in parallel by different agents

**Benefits:**

- Independen