Spec Kit

Spec Kit — Spec-Driven Development

Build high-quality software faster using Spec-Driven Development (SDD). Specifications become executable artifacts that generate working implementations, not just documentation.

Homepage: https://github.github.com/spec-kit/
GitHub: https://github.com/github/spec-kit

What is Spec-Driven Development?

SDD flips traditional software development:

Core Philosophy:

• Intent-driven development
• Rich specifications with guardrails
• Heavy reliance on AI model capabilities
• Technology-independent process

Prerequisites

• OS: Linux, macOS, Windows (PowerShell supported)
• AI Agent: Claude Code, GitHub Copilot, Gemini CLI, or Codebuddy CLI
• Package Manager: uv
• Python: 3.11+
• Git: Any recent version

Installation & Setup

Initialize a New Project

# Create new project directory
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# Initialize in current directory
uvx --from git+https://github.com/github/spec-kit.git specify init .
uvx --from git+https://github.com/github/spec-kit.git specify init --here

Specify AI Agent

# Proactively set AI agent during init
uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai claude
uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai gemini
uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai copilot
uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai codebuddy

Script Type (Shell vs PowerShell)

Auto-selected by OS, or force explicitly:

# Force PowerShell (Windows)
uvx --from git+https://github.com/github/spec-kit.git specify init <project> --script ps

# Force POSIX shell (Linux/macOS)
uvx --from git+https://github.com/github/spec-kit.git specify init <project> --script sh

Skip Tool Checks

uvx --from git+https://github.com/github/spec-kit.git specify init <project> --ai claude --ignore-agent-tools

The 6-Step Spec-Driven Process

Step 1: Initialize

Run specify init to create project structure with templates.

uvx --from git+https://github.com/github/spec-kit.git specify init my-app --ai claude

Creates:

• .speckit/ directory with configuration
• Agent-specific templates
• Git repository structure

Step 2: Define Constitution

Establish core rules and principles for your project.

Slash Command:

/speckit.constitution This project follows a "Library-First" approach. 
All features must be implemented as standalone libraries first. 
We use TDD strictly. We prefer functional programming patterns.

Purpose: Sets guardrails and organizational principles that all specs must follow.

Step 3: Create Specification

Describe what you want to build, not how.

Slash Command:

/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.

Best Practices:

• Focus on user scenarios and behaviors
• Avoid tech stack details (AI picks appropriate tech)
• Describe UI/UX in plain language
• Include constraints and business rules

Step 4: Refine (Clarify)

Identify and resolve ambiguities in your specification.

Slash Command:

/speckit.clarify Focus on security implications and edge cases

What it does:

• Detects vague or ambiguous requirements
• Asks clarifying questions
• Suggests concrete implementations
• Updates spec with resolved details

Step 5: Plan

Generate detailed implementation plan from specification.

Slash Command:

/speckit.plan

Output:

• Architecture decisions
• File structure
• Implementation steps
• Testing strategy
• Dependencies to install

Step 6: Build

Execute the implementation plan.

Slash Command:

/speckit.build

Features:

• Generates code based on spec + plan
• Creates files incrementally
• Runs tests as specified
• Commits progress to Git

Context Awareness: Git Branch-Based

Spec Kit automatically detects the active feature based on your current Git branch.

Naming Convention:

001-feature-name
002-user-authentication
003-photo-album-grid

To switch between specifications:

git checkout 001-feature-name    # Work on feature 1
git checkout 002-user-auth       # Work on feature 2

Context is automatically loaded when you run Spec Kit commands.

Development Phases

Phase 1: 0-to-1 (Greenfield)

Focus: Generate from scratch

• Start with high-level requirements
• Generate specifications
• Plan implementation steps
• Build production-ready applications

Phase 2: Creative Exploration

Focus: Parallel implementations

• Explore diverse solutions
• Support multiple technology stacks
• Experiment with UX patterns
• Compare approaches

Phase 3: Iterative Enhancement (Brownfield)

Focus: Modernization

• Add features iteratively
• Modernize legacy systems
• Adapt existing processes
• Refactor with specs

All Slash Commands Reference

Enterprise Features

Organizational Constraints

• Cloud Providers: Target specific platforms (AWS, Azure, GCP)
• Tech Stacks: Enforce approved technologies
• Design Systems: Integrate enterprise UI libraries
• Compliance: Meet security/regulatory requirements

Technology Independence

Spec Kit works with:

• Any programming language
• Any framework
• Any architecture pattern
• Any deployment target

Local Development (Contributing)

Clone and Setup

git clone https://github.com/github/spec-kit.git
cd spec-kit

Run CLI Directly

# Fastest feedback - no install needed
python -m src.specify_cli --help
python -m src.specify_cli init demo-project --ai claude --script sh

Editable Install

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
uv pip install -e .
specify --help

Test From Branch

# Push branch first
git push origin your-feature-branch

# Test via uvx
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch \
  specify init demo-branch-test --script ps

Best Practices

Specification Writing

✅ DO:

• Describe user scenarios
• Include business rules
• Mention constraints
• Use plain language
• Focus on behavior, not implementation

❌ DON'T:

• Specify tech stack (let AI choose)
• Write implementation details
• Use jargon without context
• Make assumptions unstated

Example Good Spec

/speckit.specify Build a task management app where:
- Users can create projects with color-coded labels
- Tasks have priorities (High/Medium/Low) with visual indicators
- Drag-and-drop to reorder tasks within a project
- Tasks can be assigned to multiple users
- Due dates trigger notifications 24h before
- Completed tasks archive automatically after 7 days
- Mobile-responsive with touch-friendly interactions

Example Bad Spec

/speckit.specify Build a React app with Redux for state management.
Use Material-UI for components. Store data in PostgreSQL.

Troubleshooting

Command Not Found

Problem: AI agent doesn't recognize /speckit.* commands
Solution: Re-run specify init in the project directory

Wrong Context Loaded

Problem: Working on wrong specification
Solution: Check current branch with git branch and switch: git checkout <branch>

Script Type Issues

Problem: PowerShell scripts on macOS or vice versa
Solution: Force script type: --script sh or --script ps

Agent Tool Missing

Problem: Spec Kit complains about missing AI agent tools
Solution: Use --ignore-agent-tools flag during init

Workflow Examples

New Feature Workflow

# 1. Create feature branch
git checkout -b 004-dark-mode

# 2. In AI agent chat:
/speckit.specify Add dark mode toggle to the application. 
System should detect OS preference but allow manual override. 
Store preference in localStorage.

# 3. Clarify ambiguities:
/speckit.clarify Focus on accessibility (WCAG contrast)

# 4. Generate plan:
/speckit.plan

# 5. Build:
/speckit.build

# 6. Commit and PR
git add .
git commit -m "feat: add dark mode toggle"

Brownfield Enhancement

# 1. Switch to existing feature
git checkout 002-user-auth

# 2. Enhance spec:
/speckit.specify Add OAuth2 login with Google and GitHub providers

# 3. Plan the enhancement:
/speckit.plan

# 4. Build iteratively:
/speckit.build

Resources

• Documentation: https://github.github.com/spec-kit/
• GitHub Repo: https://github.com/github/spec-kit
• Contributing: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md
• Support: https://github.com/github/spec-kit/blob/main/SUPPORT.md

Key Principles Summary

1. Intent over Implementation — Describe what, not how
2. Specifications are Assets — Treat them as primary deliverables
3. Multi-step Refinement — Iterate: Constitute → Specify → Clarify → Plan → Build
4. Context-Aware — Git branches maintain feature context
5. Technology Agnostic — Process works with any stack

Last updated: 2026-02-28