GitHub Spec Kit Mastery

Enable structured spec-driven development using GitHub's Spec Kit toolkit. Transform vague ideas into executable specifications, then generate implementations through AI coding agents.

Core Philosophy

Specifications are executable artifacts that generate code—not documentation that follows it. Code serves specifications, not vice versa. This inverts traditional development by making specs primary and implementations derived.

When to Use This Skill

Activate when user mentions:

• •"spec-driven development" or "specification-driven"
• •"speckit" or "spec kit"
• •Working with /speckit.* commands
• •Creating applications from specifications
• •Initializing spec-driven projects
• •Managing constitution, specifications, plans, or tasks

Prerequisites

Before starting, verify installation:

# Check if Spec Kit is installed
specify --version

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

Core Workflow

Phase 0: Project Initialization

Initialize Spec Kit in the project:

# New project
specify init <project-name> --ai claude

# Existing project
specify init . --ai claude

# Current directory, force overwrite
specify init --here --force --ai claude

Supported AI agents: claude, gemini, copilot, cursor-agent, windsurf, qwen-code

Phase 1: Constitution (/speckit.constitution)

Establish immutable architectural principles that govern all development.

Purpose: Define project-wide constraints, standards, and architectural decisions.

Key principles to include:

1. •Library-First Principle (features as reusable libraries)
2. •CLI Interface Mandate (text-based interfaces)
3. •Test-First Imperative (tests before implementation)
4. •Security Constitution (security constraints)
5. •Data Integrity Standards (data handling rules)
6. •Performance Baselines (non-functional requirements)
7. •Simplicity Gate (complexity limits)
8. •Anti-Abstraction Principle (direct framework usage)
9. •Integration-First Testing (real services, not mocks)

Output: Creates memory/constitution.md with project principles.

Phase 2: Specification (/speckit.specify)

Transform ideas into structured, executable specifications.

Key activities:

• •Define user stories and acceptance criteria
• •Specify feature requirements (WHAT and WHY, not HOW)
• •Mark uncertainties with [NEEDS CLARIFICATION] tags
• •Avoid implementation details (technology, architecture, APIs)

Best practices:

• •Focus on user needs, not technical solutions
• •Keep specifications abstract and stable
• •Force explicit reasoning for complexity
• •Document business justification, not code structure

Output: Creates memory/specs/SPEC-XXX-feature-name/ with:

• •specification.md - Feature requirements
• •acceptance-criteria.md - Success criteria
• •user-stories.md - User-facing scenarios

Phase 3: Planning (/speckit.plan)

Convert specifications into technical implementation strategies.

Key activities:

• •Choose technology stack with rationale
• •Design API contracts and data models
• •Define test scenarios
• •Create quickstart validation workflows

Outputs technical artifacts:

• •Architecture decisions with reasoning
• •API endpoint definitions
• •Database schemas
• •Integration test scenarios
• •Developer quickstart guides

Output: Creates memory/specs/SPEC-XXX-feature-name/plan.md

Phase 4: Task Generation (/speckit.tasks)

Break plans into executable, reviewable work items.

Key activities:

• •Derive tasks from contracts and entities
• •Identify parallelizable work (marked with [P])
• •Generate small, focused implementation units
• •Create task dependencies and ordering

Output: Creates memory/specs/SPEC-XXX-feature-name/tasks.md with numbered tasks.

Phase 5: Implementation (/speckit.implement)

Execute all tasks and build the feature according to plan.

Workflow:

1. •Read all specification artifacts (spec, plan, tasks)
2. •Implement tasks in order (parallelize [P] marked tasks)
3. •Follow constitution principles
4. •Run tests after each task
5. •Validate against acceptance criteria

Optional Enhancement Commands

/speckit.clarify - Resolve ambiguous specifications

• •Use when [NEEDS CLARIFICATION] tags appear
• •Prompts for specific details before proceeding

/speckit.analyze - Verify artifact consistency

• •Checks spec-plan-task alignment
• •Identifies contradictions or gaps

/speckit.checklist - Generate quality validation checklists

• •Creates comprehensive validation steps
• •Ensures requirements are testable and measurable

Workflow Patterns

0-to-1 Development (Greenfield)

specify init app --ai claude
→ /speckit.constitution
→ /speckit.specify
→ /speckit.plan
→ /speckit.tasks
→ /speckit.implement

Iterative Enhancement (Brownfield)

cd existing-project
specify init --here --ai claude
→ /speckit.specify (new feature)
→ /speckit.plan
→ /speckit.tasks
→ /speckit.implement

Creative Exploration

Generate multiple parallel implementations with different tech stacks:

→ /speckit.specify (once)
→ /speckit.plan (React version)
→ /speckit.plan (Vue version)
→ Compare and choose

Key Principles

DO:

• •Start with constitution to establish principles
• •Keep specifications abstract (user needs, not code)
• •Mark all uncertainties explicitly with [NEEDS CLARIFICATION]
• •Regenerate plans when requirements change
• •Follow the five-phase workflow in order
• •Use separate files for contracts, models, algorithms

DON'T:

• •Skip constitution phase on new projects
• •Include implementation details in specifications
• •Make assumptions—force clarification instead
• •Mix specifications and technical design
• •Manually edit generated task lists
• •Create deeply nested file references (max 1 level)

File Structure Reference

After initialization, projects contain:

project/
├── memory/
│   ├── constitution.md              # Architectural principles
│   └── specs/
│       └── SPEC-XXX-feature-name/
│           ├── specification.md      # Requirements
│           ├── plan.md              # Technical design
│           ├── tasks.md             # Work breakdown
│           ├── acceptance-criteria.md
│           └── user-stories.md
├── src/                             # Implementation code
└── tests/                           # Test suites

Supporting Resources

• •Detailed methodology: See references/spec-driven-methodology.md
• •Phase-by-phase guide: See references/workflow-guide.md
• •CLI command reference: See references/cli-reference.md
• •Writing specs: See references/best-practices.md
• •Constitution template: See assets/constitution-template.md
• •Quality checklist: See assets/specification-checklist.md

Common Issues

Spec Kit not found: Install with uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Commands not available: Reinitialize project with specify init --here --force --ai claude

Specifications too detailed: Remove implementation details, focus on user needs only

Unclear requirements: Use /speckit.clarify to resolve [NEEDS CLARIFICATION] tags

Plan-spec mismatch: Run /speckit.analyze to verify consistency

Official Documentation

• •GitHub Repository: https://github.com/github/spec-kit
• •Methodology Guide: https://github.com/github/spec-kit/blob/main/spec-driven.md
• •Official Blog: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/