Spec Kit (github/spec-kit)

Spec Kit

https://github.com/github/spec-kit
Admin
Spec Kit is a tool that enables Spec-Driven Development, allowing organizations to focus on product...

Tokens:90,975
Snippets:681
Trust Score:8.2
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Spec Kit

Spec Kit is an open-source toolkit for Spec-Driven Development (SDD), a methodology that inverts traditional software development by treating specifications as the primary artifact that generates code rather than merely guiding it. The toolkit provides a CLI (`specify`) and a collection of AI agent commands that work with various AI coding assistants including Claude Code, GitHub Copilot, Cursor, Gemini CLI, and 15+ other agents to transform feature descriptions into executable specifications, implementation plans, and task breakdowns.

The core philosophy centers on "intent-driven development" where developers focus on **what** users need and **why**, while AI agents handle the mechanical translation to implementation. Spec Kit enforces quality through structured templates, constitutional principles (project governance), and multi-step refinement rather than one-shot code generation. The extension system allows teams to add integrations (Jira, Linear, GitHub Issues) without bloating the core framework.

## CLI Commands

### Initialize Project

The `specify init` command creates a new Spec Kit project with the appropriate template for your chosen AI agent. It downloads templates from GitHub releases, initializes git repositories, and configures slash commands for your AI assistant.

```bash
# Create new project with Claude Code support
specify init my-project --ai claude

# Initialize in current directory with GitHub Copilot
specify init . --ai copilot

# Use --here flag alternative
specify init --here --ai cursor-agent

# Initialize with PowerShell scripts (Windows)
specify init my-project --ai gemini --script ps

# Skip git initialization
specify init my-project --ai codex --no-git

# Force initialization in non-empty directory
specify init . --force --ai claude

# Install agent skills alongside commands
specify init my-project --ai claude --ai-skills

# Check installed tools
specify check

# Show version information
specify version
```

### Check Prerequisites

Verifies that required tools are installed on the system, checking for git, AI agent CLIs (claude, gemini, cursor, etc.), and Visual Studio Code variants.

```bash
# Run system check
specify check

# Output example:
# ● Check Available Tools
# ├── ● git (available)
# ├── ● Claude Code (available)
# ├── ● Gemini CLI (not found)
# ├── ○ Cursor (IDE-based, no CLI check)
# └── ● Visual Studio Code (available)
```

## Slash Commands (AI Agent Commands)

### /speckit.constitution - Establish Project Principles

Creates or updates the project constitution containing non-negotiable development principles. The constitution acts as architectural DNA ensuring consistency across all generated code.

```bash
# In your AI agent (e.g., Claude Code)
/speckit.constitution Create principles focused on code quality, testing
standards, user experience consistency, and performance requirements

# The command:
# 1. Loads existing constitution from .specify/memory/constitution.md
# 2. Identifies placeholder tokens [PROJECT_NAME], [PRINCIPLE_1_NAME], etc.
# 3. Fills template with concrete values from user input
# 4. Validates semantic versioning for amendments
# 5. Propagates changes to dependent templates (plan, spec, tasks)
# 6. Outputs sync impact report and suggested commit message
```

### /speckit.specify - Create Feature Specification

Transforms a feature description into a complete specification with user stories, functional requirements, and acceptance criteria.

```bash
# Create specification for a new feature
/speckit.specify Build a real-time chat system with message history,
user presence indicators, and support for file attachments up to 10MB

# The command automatically:
# 1. Generates branch name: 003-realtime-chat-system
# 2. Creates specs/003-realtime-chat-system/spec.md
# 3. Extracts actors, actions, data, constraints
# 4. Marks ambiguous areas with [NEEDS CLARIFICATION: question]
# 5. Generates testable functional requirements
# 6. Creates quality checklist at checklists/requirements.md
# 7. Validates against quality criteria (max 3 clarification markers)
```

### /speckit.clarify - Refine Requirements

Identifies underspecified areas in the specification through targeted clarification questions. Run before `/speckit.plan` to reduce downstream rework.

```bash
# Start clarification workflow
/speckit.clarify

# The command:
# 1. Loads spec.md and performs ambiguity scan across 10 categories
# 2. Generates max 5 prioritized questions (Impact × Uncertainty)
# 3. Presents ONE question at a time with recommended answer
# 4. Records answers in ## Clarifications section
# 5. Updates relevant spec sections (requirements, data model, edge cases)
# 6. Saves atomically after each answer

# Example question format:
# **Recommended:** Option A - Session-based authentication provides
# simplest implementation for initial MVP.
#
# | Option | Description |
# |--------|-------------|
# | A | Session-based authentication |
# | B | JWT tokens with refresh |
# | C | OAuth2 with external providers |
# | Short | Provide a different short answer |
```

### /speckit.plan - Generate Implementation Plan

Creates a comprehensive technical implementation plan with architecture decisions, data models, and API contracts.

```bash
# Generate plan with tech stack preferences
/speckit.plan Use Next.js 14 with App Router, PostgreSQL for persistence,
Redis for real-time presence, and WebSocket for messaging

# The command:
# 1. Loads spec.md and constitution.md
# 2. Evaluates constitutional gates (Simplicity, Anti-Abstraction, Integration-First)
# 3. Phase 0: Generates research.md with technology decisions
# 4. Phase 1: Creates data-model.md, contracts/, quickstart.md
# 5. Updates agent context file (CLAUDE.md, .cursorrules, etc.)
# 6. Reports gate violations requiring justification

# Generated artifacts:
# specs/003-chat/plan.md          - Technical architecture
# specs/003-chat/research.md      - Technology decisions with rationale
# specs/003-chat/data-model.md    - Entity definitions
# specs/003-chat/contracts/       - API specifications
# specs/003-chat/quickstart.md    - Validation scenarios
```

### /speckit.tasks - Generate Task Breakdown

Creates an actionable task list organized by user story with dependencies and parallel execution markers.

```bash
# Generate tasks from implementation plan
/speckit.tasks

# Output: specs/003-chat/tasks.md with structure:
# Phase 1: Setup (project initialization)
# Phase 2: Foundational (blocking prerequisites)
# Phase 3+: User Stories (P1, P2, P3 in priority order)
# Final Phase: Polish & Cross-Cutting Concerns

# Task format (strict checklist):
# - [ ] T001 Create project structure per implementation plan
# - [ ] T005 [P] Implement auth middleware in src/middleware/auth.py
# - [ ] T012 [P] [US1] Create User model in src/models/user.py
# - [ ] T014 [US1] Implement UserService in src/services/user_service.py

# [P] = Parallelizable task
# [US1] = User Story 1 (from spec.md priorities)
```

### /speckit.analyze - Cross-Artifact Consistency Analysis

Performs read-only analysis across spec.md, plan.md, and tasks.md to identify inconsistencies before implementation.

```bash
# Run consistency analysis (after /speckit.tasks)
/speckit.analyze

# The command detects:
# - Duplicate requirements
# - Ambiguous adjectives lacking metrics ("fast", "scalable")
# - Underspecified requirements
# - Constitution alignment violations (CRITICAL severity)
# - Coverage gaps (requirements with zero tasks)
# - Terminology drift

# Output format:
# | ID | Category | Severity | Location(s) | Summary | Recommendation |
# |----|----------|----------|-------------|---------|----------------|
# | A1 | Duplication | HIGH | spec.md:L120 | Two similar requirements | Merge |
# | C1 | Constitution | CRITICAL | plan.md:L45 | Violates Article VII | Simplify |

# Coverage Summary Table:
# | Requirement Key | Has Task? | Task IDs | Notes |
```

### /speckit.implement - Execute Implementation

Executes all tasks from tasks.md following TDD approach and dependency ordering.

```bash
# Start implementation
/speckit.implement

# The command:
# 1. Validates checklists status (prompts if incomplete)
# 2. Creates/verifies ignore files (.gitignore, .dockerignore, etc.)
# 3. Parses task phases and dependencies
# 4. Executes phase-by-phase (Setup → Tests → Core → Integration → Polish)
# 5. Marks completed tasks as [X] in tasks.md
# 6. Reports progress and handles errors

# Checklist validation output:
# | Checklist | Total | Completed | Incomplete | Status |
# |-----------|-------|-----------|------------|--------|
# | ux.md     | 12    | 12        | 0          | ✓ PASS |
# | test.md   | 8     | 5         | 3          | ✗ FAIL |
```

### /speckit.checklist - Generate Quality Checklists

Creates custom quality checklists for validating requirements completeness.

```bash
# Generate checklist for specific domain
/speckit.checklist Create a security review checklist for authentication
and authorization requirements

# Output: specs/003-chat/checklists/security.md with validation items
```

## Extension System

### Install Extension from Catalog

Extensions add commands and hooks without modifying core functionality.

```bash
# Search for extensions
specify extension search jira

# Get detailed information
specify extension info jira

# Install from catalog
specify extension add jira

# Install from URL
specify extension add --from https://github.com/org/ext/archive/v1.0.0.zip

# Install from local directory (development)
specify extension add --dev /path/to/extension
```

### Manage Extensions

```bash
# List installed extensions
specify extension list

# Output:
# ✓ Jira Integration (v1.0.0)
#    Create Jira Epics, Stories, and Issues from spec-kit artifacts
#    Commands: 3 | Hooks: 1 | Status: Enabled

# Update extensions
specify extension update           # Update all
specify extension update jira      # Update specific

# Disable without removing
specify extension disable jira
specify extension enable jira

# Remove extension
specify extension remove jira
specify extension remove jira --keep-config  # Preserve config files
```

### Extension Configuration

Extensions use layered configuration with environment variable overrides.

```yaml
# .specify/extensions/jira/jira-config.yml
project:
  key: "MYPROJ"

defaults:
  epic:
    labels: ["spec-driven"]
  task:
    custom_fields:
      customfield_10002: 3  # Story points
```

```bash
# Environment variable override (highest priority)
export SPECKIT_JIRA_PROJECT_KEY="DEVTEST"

# Local config (gitignored) for machine-specific settings
# .specify/extensions/jira/jira-config.local.yml
```

## Python API

### ExtensionManifest

Loads and validates extension manifest files.

```python
from specify_cli.extensions import ExtensionManifest, ValidationError

try:
    manifest = ExtensionManifest(Path("extension.yml"))

    print(f"ID: {manifest.id}")              # 'jira'
    print(f"Name: {manifest.name}")          # 'Jira Integration'
    print(f"Version: {manifest.version}")    # '1.0.0'
    print(f"Commands: {len(manifest.commands)}")
    print(f"Hooks: {manifest.hooks}")
    print(f"Hash: {manifest.get_hash()}")    # SHA256 hash

except ValidationError as e:
    print(f"Invalid manifest: {e}")
```

### ExtensionManager

Manages extension lifecycle including installation and removal.

```python
from pathlib import Path
from specify_cli.extensions import ExtensionManager, CompatibilityError

project_root = Path.cwd()
manager = ExtensionManager(project_root)

# Install from local directory
manifest = manager.install_from_directory(
    source_dir=Path("/path/to/extension"),
    speckit_version="0.1.13",
    register_commands=True
)
print(f"Installed: {manifest.name} v{manifest.version}")

# Install from ZIP file
manifest = manager.install_from_zip(
    zip_path=Path("extension.zip"),
    speckit_version="0.1.13"
)

# List installed extensions
for ext in manager.list_installed():
    print(f"{ext['name']} v{ext['version']} - {ext['description']}")
    print(f"  Commands: {ext['command_count']}, Hooks: {ext['hook_count']}")
    print(f"  Enabled: {ext['enabled']}")

# Remove extension
success = manager.remove("jira", keep_config=False)

# Get specific extension
manifest = manager.get_extension("jira")
if manifest:
    print(f"Found: {manifest.name}")
```

### ExtensionCatalog

Fetches and searches the extension catalog.

```python
from specify_cli.extensions import ExtensionCatalog

catalog = ExtensionCatalog(project_root)

# Search extensions
results = catalog.search(
    query="issue",
    tag="atlassian",
    author="Stats Perform",
    verified_only=True
)

for ext in results:
    print(f"{ext['name']} v{ext['version']}")
    print(f"  {ext['description']}")
    print(f"  Tags: {ext.get('tags', [])}")
    print(f"  Verified: {ext.get('verified', False)}")

# Get specific extension info
ext_info = catalog.get_extension_info("jira")
if ext_info:
    print(f"Download URL: {ext_info.get('download_url')}")

# Download extension ZIP
zip_path = catalog.download_extension("jira")
print(f"Downloaded to: {zip_path}")

# Cache management
catalog.clear_cache()
is_valid = catalog.is_cache_valid()
```

### ConfigManager

Manages layered configuration for extensions.

```python
from specify_cli.extensions import ConfigManager

config = ConfigManager(project_root, "jira")

# Get merged configuration (defaults -> project -> local -> env)
full_config = config.get_config()
print(full_config)

# Get specific value by dot-notation path
url = config.get_value("connection.url")
timeout = config.get_value("connection.timeout", default=30)
project_key = config.get_value("project.key")

# Check if value exists
if config.has_value("defaults.epic.labels"):
    labels = config.get_value("defaults.epic.labels")
```

### HookExecutor

Manages extension hooks that execute at lifecycle events.

```python
from specify_cli.extensions import HookExecutor

executor = HookExecutor(project_root)

# Get hooks for an event
hooks = executor.get_hooks_for_event("after_tasks")

for hook in hooks:
    if executor.should_execute_hook(hook):
        print(f"Hook: {hook['command']}")
        print(f"  Extension: {hook['extension']}")
        print(f"  Optional: {hook['optional']}")
        print(f"  Prompt: {hook['prompt']}")

# Format hook message for AI agent display
message = executor.format_hook_message("after_tasks", hooks)
print(message)

# Check hooks (combined method for AI agents)
result = executor.check_hooks_for_event("after_tasks")
if result["has_hooks"]:
    print(result["message"])

# Enable/disable hooks for extension
executor.enable_hooks("jira")
executor.disable_hooks("jira")
```

### version_satisfies

Utility function for version compatibility checking.

```python
from specify_cli.extensions import version_satisfies

# Check if version satisfies specifier
satisfies = version_satisfies("1.2.3", ">=1.0.0,<2.0.0")  # True
satisfies = version_satisfies("2.0.0", ">=1.0.0,<2.0.0")  # False
satisfies = version_satisfies("0.5.0", ">=0.1.0")         # True
```

## Extension Manifest Schema

Extension manifest (extension.yml) defines commands, hooks, and requirements.

```yaml
schema_version: "1.0"

extension:
  id: "jira"                          # Lowercase, alphanumeric + hyphens
  name: "Jira Integration"
  version: "1.0.0"                    # Semantic version X.Y.Z
  description: "Create Jira issues from spec-kit artifacts"
  author: "Your Organization"
  repository: "https://github.com/org/spec-kit-jira"
  license: "MIT"
  homepage: "https://example.com/docs"

requires:
  speckit_version: ">=0.1.0,<2.0.0"   # Version specifier
  tools:
    - name: "atlassian-mcp-server"
      version: ">=1.0.0"
      required: true

provides:
  commands:
    - name: "speckit.jira.specstoissues"   # Pattern: speckit.{ext}.{cmd}
      file: "commands/specstoissues.md"
      description: "Create Jira hierarchy from spec and tasks"
      aliases: ["speckit.specstoissues"]
    - name: "speckit.jira.sync-status"
      file: "commands/sync-status.md"
      description: "Sync task completion to Jira"

  config:
    - name: "jira-config.yml"
      template: "config-template.yml"
      description: "Jira connection and project settings"
      required: true

hooks:
  after_tasks:
    command: "speckit.jira.specstoissues"
    optional: true
    prompt: "Create Jira issues from tasks?"
    description: "Automatically create Jira hierarchy after task generation"
    condition: "config.project.key is set"

tags:
  - "jira"
  - "atlassian"
  - "issue-tracking"

defaults:
  epic:
    labels: ["spec-driven"]
```

## Summary

Spec Kit enables teams to practice Spec-Driven Development by providing a structured workflow from feature description to implementation. The primary use cases include: (1) greenfield development where specifications generate initial project structure, data models, and task breakdowns; (2) iterative enhancement of existing projects with constitutional governance ensuring consistency; and (3) team collaboration through version-controlled specifications that serve as the single source of truth.

Integration patterns follow a clear progression: `/speckit.constitution` establishes project principles, `/speckit.specify` creates feature specifications, `/speckit.clarify` resolves ambiguities, `/speckit.plan` generates technical architecture, `/speckit.tasks` produces actionable breakdowns, and `/speckit.implement` executes the implementation. Extensions integrate external tools (Jira, Linear, GitHub) through hooks that execute after core commands, enabling automated issue creation, status synchronization, and custom workflows. The Python API provides programmatic access for building custom tooling, CI/CD integration, and extension development.