spec-driven-development

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:

• Independent