spec-kit

name	spec-kit
description	Spec-Driven Development toolkit for structured software development. Generates specifications, plans, and implementations using AI agents through a phased workflow.
homepage	https://github.com/github/spec-kit
metadata	{"clawdbot":{"emoji":"💫","requires":{"bins":["uv","python3","git"]},"install":[{"id":"uv-tool","kind":"shell","command":"uv tool install specify-cli --from git+https://github.com/github/spec-kit.git","label":"Install Spec Kit via uv"}]}}

Spec Kit - Spec-Driven Development

A toolkit for building high-quality software faster through structured, AI-assisted specification-driven development.

Core Philosophy

Spec-Driven Development flips traditional software development:

• Specifications become executable - they directly generate working implementations
• Focus on what and why before how
• Multi-step refinement instead of one-shot code generation
• AI agents interpret and execute structured workflows

Prerequisites

• uv (package manager): brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
• Python 3.11+: python3 --version
• Git: git --version
• Supported AI Agent: Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, etc.

Installation

Persistent Installation (Recommended)

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

One-time Usage

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Upgrade

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

Workflow Overview

6-Phase Development Process

Phase	Command	Purpose
1. Constitution	/speckit.constitution	Establish project principles and governance
2. Specification	/speckit.specify	Define what to build (requirements, user stories)
3. Planning	/speckit.plan	Define how to build (tech stack, architecture)
4. Task Breakdown	/speckit.tasks	Generate actionable task lists
5. Analysis (Optional)	/speckit.analyze	Validate consistency and coverage
6. Implementation	/speckit.implement	Execute tasks and build the feature

Optional Commands:

• /speckit.clarify - Clarify underspecified areas (run before /speckit.plan)
• /speckit.checklist - Generate quality validation checklists

Usage Guide

Step 1: Initialize Project

# Create new project
specify init my-project --ai claude

# Initialize in current directory
specify init . --ai claude
# or
specify init --here --ai claude

# Force merge into non-empty directory
specify init . --force --ai claude

# Check installed tools
specify check

Step 2: Establish Project Principles

Launch your AI agent in the project directory and create governing principles:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. Include governance for technical decisions and implementation choices.

Output: .specify/memory/constitution.md

Step 3: Create Specification

Describe what you want to build (focus on requirements, not tech stack):

/speckit.specify Build a photo album organizer. Albums are grouped by date and can be re-organized via drag-and-drop. Albums are never nested. Within each album, photos are displayed in a tile interface with preview thumbnails.

Output: .specify/specs/001-feature-name/spec.md

Important: Be explicit about:

• What you're building and why
• User workflows and requirements
• Constraints and business rules

Step 4: Clarify Requirements (Recommended)

Before planning, clarify any underspecified areas:

/speckit.clarify

The agent will ask structured questions and record answers in a Clarifications section.

Alternatively, refine manually:

For each project, create 5-15 tasks randomly distributed across different completion states. Ensure at least one task exists in each stage.

Validate the Review & Acceptance Checklist:

Read the review and acceptance checklist. Check off each item that meets criteria. Leave unchecked if requirements are not met.

Step 5: Generate Technical Plan

Specify how to build (tech stack, architecture):

/speckit.plan Use Vite with minimal libraries. Use vanilla HTML, CSS, and JavaScript. Images are stored locally, metadata in SQLite. No external uploads.

Output: Implementation details in .specify/specs/001-feature-name/:

• plan.md - Overall implementation plan
• data-model.md - Database schema
• contracts/api-spec.json - API contracts
• research.md - Tech stack research

Validate the plan:

Audit the implementation plan and detail files. Verify there's a clear sequence of tasks. Cross-reference core implementation steps with implementation details. Check for over-engineering or missing pieces.

Step 6: Generate Task Breakdown

Break the plan into actionable tasks:

/speckit.tasks

Output: .specify/specs/001-feature-name/tasks.md

Task breakdown includes:

• Tasks organized by user story
• Dependency ordering (e.g., models → services → endpoints)
• Parallel execution markers [P] for concurrent tasks
• File paths for each task
• Test-driven development structure
• Checkpoint validations per phase

Step 7: Implement

Execute the implementation plan:

/speckit.implement

What it does:

• Validates prerequisites (constitution, spec, plan, tasks)
• Parses task breakdown from tasks.md
• Executes tasks in dependency order
• Respects parallel execution markers
• Follows TDD approach
• Provides progress updates

Important: The AI agent will execute local CLI commands (npm, dotnet, python, etc.). Ensure required tools are installed.

After implementation:

• Test the application thoroughly
• Check for runtime errors (browser console, server logs)
• Copy errors back to the AI agent for resolution

CLI Reference

Commands

specify init <project-name>     # Initialize new project
specify check                    # Check for required tools

Options

Option	Description
--ai <agent>	AI assistant: claude, gemini, copilot, cursor-agent, windsurf, etc.
--here	Initialize in current directory
--force	Force merge/overwrite (skip confirmation)
--no-git	Skip git repository initialization
--ignore-agent-tools	Skip AI agent tool checks
--script <type>	Script variant: sh (bash/zsh) or ps (PowerShell)
--debug	Enable detailed debug output
--github-token <token>	GitHub token for API requests (or use GH_TOKEN env var)

Environment Variables

Variable	Description
SPECIFY_FEATURE	Override feature detection for non-Git repos. Set to feature dir name (e.g., 001-photo-albums)

Note: Must be set in the agent's context before using /speckit.plan or follow-up commands.

Supported AI Agents

Agent	Status	Notes
Claude Code	✅
Cursor	✅
Windsurf	✅
GitHub Copilot	✅
Gemini CLI	✅
Qoder CLI	✅
Amp	✅
Roo Code	✅
Jules	✅
Amazon Q Developer CLI	⚠️	Does not support custom arguments for slash commands

Project Structure

After initialization:

project-root/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Project governance
│   ├── scripts/
│   │   ├── create-new-feature.sh
│   │   ├── setup-plan.sh
│   │   └── update-claude-md.sh
│   ├── specs/
│   │   └── 001-feature-name/
│   │       ├── spec.md              # Requirements & user stories
│   │       ├── plan.md              # Implementation plan
│   │       ├── tasks.md             # Task breakdown
│   │       ├── data-model.md        # Database schema
│   │       ├── research.md          # Tech stack research
│   │       └── contracts/
│   │           └── api-spec.json    # API contracts
│   └── templates/
│       ├── spec-template.md
│       ├── plan-template.md
│       └── tasks-template.md

Best Practices

1. Constitution First

Always start with /speckit.constitution. It guides all subsequent decisions.

2. Separate Concerns

• Specification: Focus on what and why, not how
• Planning: Tech stack and architecture come after requirements

3. Clarify Before Planning

Run /speckit.clarify before /speckit.plan to reduce rework downstream.

4. Validate Everything

• After /speckit.specify: Validate acceptance checklist
• After /speckit.plan: Audit for over-engineering, missing steps
• After /speckit.tasks: Run /speckit.analyze for consistency

5. Iterative Refinement

Don't treat the first attempt as final. Refine specs, plans, and tasks through dialogue with the AI agent.

6. Test Runtime Behavior

AI-generated code may compile but fail at runtime. Always test in the browser/environment and report errors back to the agent.

Development Phases

Phase	Focus	Key Activities
0-to-1 (Greenfield)	Generate from scratch	Start with requirements → spec → plan → build
Creative Exploration	Parallel implementations	Explore diverse solutions, UX patterns, tech stacks
Iterative Enhancement (Brownfield)	Modernization	Add features, modernize legacy, adapt processes

Experimental Goals

• Technology Independence: Validate that Spec-Driven Development works across any stack
• Enterprise Constraints: Support compliance, design systems, cloud providers
• User-Centric Development: Build for different cohorts and preferences
• Creative & Iterative Processes: Parallel explorations, robust iteration, upgrades

Troubleshooting

Git Credential Manager on Linux

If Git authentication fails on Linux:

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager
rm gcm-linux_amd64.2.6.1.deb

Agent Not Finding Commands

If /speckit.* commands aren't available:

1. Ensure you ran specify init in the project directory
2. Check that your AI agent supports custom slash commands
3. Verify .specify/ directory exists with CLAUDE.md (or equivalent for your agent)

Tasks Not Executing

If /speckit.implement fails:

• Check that prerequisites are met (constitution.md, spec.md, plan.md, tasks.md)
• Ensure required tools are installed locally (npm, python, dotnet, etc.)
• Review error logs and provide them to the AI agent for debugging

Resources

• GitHub Repository: https://github.com/github/spec-kit
• Documentation: https://github.github.io/spec-kit/
• Methodology Deep Dive: https://github.com/github/spec-kit/blob/main/spec-driven.md
• Video Overview: https://www.youtube.com/watch?v=a9eR1xsfvHg

License

MIT License - See LICENSE