logoChakra

Spec Kit

Spec Kit Developer Documentation

Spec Kit Developer Documentation

A complete developer guide for using Spec Kit and the GitHub Spec Kit repository for Spec-Driven Development (SDD). This document explains the workflow, modes, commands, architecture, extensions, integrations, and practical implementation patterns.

Table of Contents

  1. Introduction
  2. What is Spec-Driven Development?
  3. Core Philosophy
  4. Installation
  5. Project Structure
  6. Workflow Overview
  7. Core Modes & Commands
  8. Artifact Lifecycle
  9. AI Agent Integrations
  10. Extensions System
  11. Presets System
  12. CLI Reference
  13. Typical Development Flow
  14. Example End-to-End Workflow
  15. Best Practices
  16. Enterprise Usage
  17. Troubleshooting
  18. Advanced Patterns
  19. Recommended Team Workflow
  20. Conclusion

Introduction

Spec Kit is an open-source toolkit for AI-assisted software engineering using a methodology called Spec-Driven Development (SDD).

Instead of prompting AI agents ad hoc, Spec Kit structures development into formal stages:

Specification → Planning → Tasks → Implementation

Each stage produces markdown artifacts that become context for the next stage.

Official resources:

What is Spec-Driven Development?

Spec-Driven Development (SDD) shifts software development from:

Prompt → Generate Code

to:

Intent → Specification → Plan → Tasks → Implementation

The specification becomes the primary artifact.

Instead of AI generating code directly from a loose prompt:

  • Requirements are formalized
  • Constraints are clarified
  • Architecture is planned
  • Tasks are generated systematically
  • AI executes implementation against the plan

This improves:

  • Consistency
  • Predictability
  • Traceability
  • Maintainability
  • Team collaboration
  • AI output quality

Core Philosophy

Spec Kit promotes several foundational principles.

3.1 Define “What” Before “How”

Focus on:

  • user behavior
  • product goals
  • acceptance criteria
  • workflows

Avoid premature implementation details.

3.2 Specifications are Executable

Specifications are not documentation only.

They drive:

  • planning
  • architecture
  • task generation
  • implementation
  • testing
  • validation

3.3 Multi-Step AI Refinement

Spec Kit discourages one-shot prompting.

Instead:

Clarify → Plan → Analyze → Implement

This reduces hallucinations and architectural drift.

3.4 Structured Context

Markdown artifacts become reusable structured context for AI agents.

Examples:

  • spec.md
  • plan.md
  • tasks.md
  • constitution.md

Installation

4.1 Requirements

Required:

  • Python 3.8+
  • Git 2.20+
  • AI coding agent
  • Internet access

Recommended:

  • uv
  • VS Code / Cursor
  • Claude / Copilot / Gemini / Codex

4.2 Install via uv

Recommended installation:

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

Verify:

specify --version

4.3 One-Time Execution

Without installation:

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

4.4 Initialize a Project

Claude integration:

specify init my-project --integration claude

Copilot integration:

specify init my-project --integration copilot

Cursor integration:

specify init my-project --integration cursor

Project Structure

Typical initialized structure:

my-project/
├── .specify/
│   ├── templates/
│   ├── extensions/
│   ├── presets/
│   ├── overrides/
│   └── artifacts/
├── specs/
├── plans/
├── tasks/
├── .claude/
├── .github/
└── README.md

Workflow Overview

Core lifecycle:

1. Constitution
2. Specify
3. Clarify
4. Plan
5. Tasks
6. Analyze
7. Implement

Core Modes & Commands

Spec Kit exposes slash commands inside AI coding agents.

7.1 Constitution Mode

Command:

/speckit.constitution

Purpose:

Defines project-wide engineering principles.

Examples:

  • coding standards
  • testing rules
  • UX principles
  • architecture constraints
  • security requirements

Example:

/speckit.constitution
Focus on accessibility, test coverage, modular architecture, and API consistency.

Output artifact:

constitution.md

7.2 Specify Mode

Command:

/speckit.specify

Purpose:

Defines requirements and user stories.

Focus on:

  • business intent
  • workflows
  • acceptance criteria
  • user outcomes

Avoid:

  • implementation details
  • libraries
  • frameworks

Example:

/speckit.specify
Build a Kanban project management platform with realtime collaboration and role-based access.

Output artifact:

spec.md

7.3 Clarify Mode

Command:

/speckit.clarify

Purpose:

Finds ambiguity and missing requirements.

The AI asks targeted questions such as:

  • authentication method?
  • scalability expectations?
  • offline support?
  • mobile support?
  • permission models?

Benefits:

  • removes ambiguity
  • improves planning quality
  • reduces implementation drift

Output:

Updated spec.md

7.4 Plan Mode

Command:

/speckit.plan

Purpose:

Defines architecture and implementation strategy.

Typical content:

  • frameworks
  • database choice
  • deployment model
  • API architecture
  • state management
  • testing strategy

Example:

/speckit.plan
Use Next.js App Router, PostgreSQL, Prisma, Redis, and WebSockets.

Output artifact:

plan.md

7.5 Tasks Mode

Command:

/speckit.tasks

Purpose:

Breaks the plan into executable implementation tasks.

Generates:

  • task hierarchy
  • dependencies
  • implementation order
  • testing requirements

Output artifact:

tasks.md

Example task:

- [ ] Create Prisma schema
- [ ] Implement authentication middleware
- [ ] Add Kanban drag-and-drop support

7.6 Analyze Mode

Command:

/speckit.analyze

Purpose:

Performs consistency checks across artifacts.

Checks:

  • missing requirements
  • uncovered tasks
  • contradictory plans
  • incomplete acceptance criteria

Usually executed before implementation.

7.7 Implement Mode

Command:

/speckit.implement

Purpose:

Executes generated tasks.

The AI agent:

  • writes code
  • creates files
  • updates configs
  • implements features
  • follows spec constraints

This is the final execution phase.

Artifact Lifecycle

Spec Kit uses chained markdown artifacts.

Lifecycle Diagram

constitution.md
        ↓
spec.md
        ↓
plan.md
        ↓
tasks.md
        ↓
implementation

Each artifact becomes structured context for later phases.

AI Agent Integrations

Spec Kit supports 30+ AI coding agents.

Supported integrations include:

AgentSupport
Claude CodeFull
GitHub CopilotFull
CursorFull
Gemini CLIFull
WindsurfFull
Codex CLIPartial
Qwen CodeFull
Roo CodeFull

List integrations:

specify integration list

Extensions System

Extensions add new capabilities to Spec Kit.

Install:

specify extension add <extension-name>

Search:

specify extension search

10.1 Extension Categories

CategoryPurpose
processWorkflow orchestration
codeValidation & review
docsDocumentation tooling
visibilityReporting & analytics
integrationExternal systems

10.2 Popular Extensions

Architecture Guard

Detects architecture drift.

QA Testing

Maps implementation against acceptance criteria.

Spec Validate

Adds gated review workflows.

Security Review

Performs AI-assisted security audits.

Worktree Isolation

Creates isolated Git worktrees for parallel AI agents.

Presets System

Presets customize Spec Kit behavior.

Examples:

  • Product Forge
  • TinySpec
  • Canon
  • AIDE Workflow

Install:

specify preset add <preset-name>

CLI Reference

Initialize

specify init my-project

Current Directory

specify init --here

Skip Git

specify init my-project --no-git

Debug Mode

specify init my-project --debug

Check Environment

specify check

Extensions

specify extension search
specify extension add spec-kit-review

Typical Development Flow

Example workflow:

1. Create constitution
2. Write specification
3. Clarify ambiguities
4. Generate implementation plan
5. Generate tasks
6. Analyze coverage
7. Implement tasks
8. Review implementation

Example End-to-End Workflow

Step 1 — Constitution

/speckit.constitution
Prioritize accessibility, performance, testing, and clean architecture.

Step 2 — Specify

/speckit.specify
Build a collaborative markdown note-taking platform with realtime sync.

Step 3 — Clarify

/speckit.clarify

AI asks questions about:

  • sync model
  • auth
  • collaboration
  • offline support

Step 4 — Plan

/speckit.plan
Use Next.js, Supabase, and TipTap editor.

Step 5 — Tasks

/speckit.tasks

Generated tasks:

- Configure Supabase auth
- Create collaborative editor
- Implement websocket sync
- Add optimistic UI updates

Step 6 — Analyze

/speckit.analyze

Step 7 — Implement

/speckit.implement

Best Practices

Keep Specifications Human-Readable

Good specs are:

  • concise
  • explicit
  • testable
  • user-focused

Avoid Premature Technical Decisions

Do not overload spec.md with implementation details.

Architecture belongs in plan.md.

Use Clarify Aggressively

Most AI implementation failures come from ambiguous requirements.

Treat Tasks as Source of Truth

Implementation should follow generated tasks closely.

Run Analyze Before Implement

This catches:

  • missing requirements
  • conflicting assumptions
  • uncovered edge cases

Enterprise Usage

Spec Kit supports:

  • offline environments
  • air-gapped infrastructure
  • custom extension catalogs
  • internal presets
  • governance enforcement

Useful enterprise extensions:

  • Architecture Guard
  • Plan Review Gate
  • Security Review
  • CI Guard
  • Spec Validate

Troubleshooting

Slash Commands Missing

Re-run initialization:

specify init --integration claude

Git Issues

Configure credential manager:

git config --global credential.helper manager

Extension Conflicts

Remove extension:

specify extension remove <name>

Broken Templates

Check override priority:

.specify/templates/overrides/

Advanced Patterns

18.1 Multi-Agent Development

Use worktree extensions for parallel agents:

Frontend Agent
Backend Agent
Testing Agent
Security Agent

18.2 Continuous Validation

Add gates:

spec → review → plan → validation → implementation

18.3 Spec Drift Prevention

Use:

  • Spec Sync
  • Reconcile
  • Retrospective

to keep implementation aligned.

18.4 Spec-to-Issue Automation

Convert tasks into GitHub issues:

/speckit.taskstoissues

Recommended Team Workflow

Small Teams

Recommended flow:

Specify → Plan → Tasks → Implement

Minimal extensions.

Medium Teams

Recommended additions:

  • Clarify
  • Analyze
  • QA
  • Review

Enterprise Teams

Recommended additions:

  • Architecture Guard
  • Security Review
  • Spec Validate
  • CI Gates
  • Worktree Isolation

Conclusion

Spec Kit transforms AI-assisted development from unstructured prompting into a disciplined engineering workflow.

Key benefits:

  • predictable AI execution
  • structured engineering process
  • improved maintainability
  • reusable project context
  • better collaboration
  • scalable AI workflows

Core process:

Constitution
    ↓
Specify
    ↓
Clarify
    ↓
Plan
    ↓
Tasks
    ↓
Analyze
    ↓
Implement

Useful links:

Last updated on

Snippets

Tanstack Start Snippets

Vibe Coding

Setup VS Code for Vibe Coding

On this page

Spec Kit Developer DocumentationTable of Contents1Introduction2What is Spec-Driven Development?3Core Philosophy3.1 Define “What” Before “How”3.2 Specifications are Executable3.3 Multi-Step AI Refinement3.4 Structured Context4Installation4.1 Requirements4.2 Install via uv4.3 One-Time Execution4.4 Initialize a Project5Project Structure6Workflow Overview7Core Modes & Commands7.1 Constitution Mode7.2 Specify Mode7.3 Clarify Mode7.4 Plan Mode7.5 Tasks Mode7.6 Analyze Mode7.7 Implement Mode1Artifact LifecycleLifecycle Diagram2AI Agent Integrations3Extensions System10.1 Extension Categories10.2 Popular ExtensionsArchitecture GuardQA TestingSpec ValidateSecurity ReviewWorktree Isolation1Presets System2CLI ReferenceInitializeCurrent DirectorySkip GitDebug ModeCheck EnvironmentExtensions3Typical Development Flow4Example End-to-End WorkflowStep 1 — ConstitutionStep 2 — SpecifyStep 3 — ClarifyStep 4 — PlanStep 5 — TasksStep 6 — AnalyzeStep 7 — Implement5Best PracticesKeep Specifications Human-ReadableAvoid Premature Technical DecisionsUse Clarify AggressivelyTreat Tasks as Source of TruthRun Analyze Before Implement6Enterprise Usage7TroubleshootingSlash Commands MissingGit IssuesExtension ConflictsBroken Templates8Advanced Patterns18.1 Multi-Agent Development18.2 Continuous Validation18.3 Spec Drift Prevention18.4 Spec-to-Issue Automation1Recommended Team WorkflowSmall TeamsMedium TeamsEnterprise Teams2Conclusion