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

CODEBLOCK0

Specify AI Agent

CODEBLOCK1

Script Type (Shell vs PowerShell)

Auto-selected by OS, or force explicitly:

CODEBLOCK2

Skip Tool Checks

CODEBLOCK3

The 6-Step Spec-Driven Process

Step 1: Initialize

Run specify init to create project structure with templates.

CODEBLOCK4

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:
CODEBLOCK5

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:
CODEBLOCK6

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:
CODEBLOCK7

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:
CODEBLOCK8

Output:

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

Step 6: Build

Execute the implementation plan.

Slash Command:
CODEBLOCK9

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:
CODEBLOCK10

To switch between specifications:
CODEBLOCK11

Context is automatically loaded when you run Spec Kit commands.

Development Phases

Phase 1: 0-to-1 (Greenfield)

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

Phase 2: Creative Exploration

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

Phase 3: Iterative Enhancement (Brownfield)

• - 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

CODEBLOCK12

Run CLI Directly

CODEBLOCK13

Editable Install

CODEBLOCK14

Test From Branch

CODEBLOCK15

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

CODEBLOCK16

Example Bad Spec

CODEBLOCK17

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: INLINECODE10

Script Type Issues

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

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

CODEBLOCK18

Brownfield Enhancement

CODEBLOCK19

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