Spec Kit — User Guide

1. Quick Start

Spec Kit is an open source toolkit for Spec-Driven Development (SDD) — a methodology that helps software teams build high-quality software faster by writing specifications before code. It provides the specify CLI, slash-command templates, extensions, presets, workflows, and integrations for 27+ popular AI coding agents.

Key features:

• Initialize SDD projects with a single command
• Integrations for Claude Code, GitHub Copilot, Gemini, Cursor, Windsurf, Forge, and 20+ more agents
• Slash commands that guide AI agents through specify → plan → tasks → implement
• Extension system for community-contributed commands and hooks
• Preset system for customizing templates with composition strategies (replace, prepend, append, wrap)
• Workflow engine for multi-step automation with review gates
• Cross-platform scripts (Bash and PowerShell)
• Git branching extension with sequential or timestamp numbering

Prerequisites: Python 3.11+, uv package manager, Git (optional but recommended)

Install and create your first project:

uv tool install specify-cli
specify init my-project --integration claude

███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝
╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝
███████║██║     ███████╗╚██████╗██║██║        ██║
╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝

GitHub Spec Kit - Spec-Driven Development Toolkit

○ Checking prerequisites...
● git                          (available)
● claude                       (available)
● Project structure            (created)
● Git repository               (initialized)
● Integration: claude          (installed)
● Git extension                (auto-installed)

What to try next: Run /speckit.specify in your AI agent to create your first specification, then follow the SDD workflow: specify → plan → tasks → implement.

Tip

You can also initialize in the current directory with specify init --here or specify init . — no need to create a new folder first.

2. Installation

System Requirements

Install Methods

uv (recommended)

uv tool install specify-cli

uvx (one-shot)

uvx specify-cli init my-project

pip

pip install specify-cli

Post-Install Verification

specify --version

specify 0.7.2

specify --help

Important

Spec Kit requires Python 3.11 or later. If you have multiple Python versions installed, ensure uv or pip is using the correct one. Run python --version to verify.

Self-Check and Self-Upgrade

Spec Kit includes built-in commands to verify your installation and upgrade to the latest version:

specify check

This validates that your project structure, integration files, and prerequisites are in order.

specify upgrade

Checks for a newer version on GitHub and provides upgrade instructions.

Warning

The --ai flag is deprecated and will be removed in version 1.0.0. Use --integration instead. For example, replace --ai claude with --integration claude.

3. Configuration

Spec Kit projects are configured through the .specify/ directory created during specify init. User-facing configuration is minimal by design — most behavior comes from your choice of integration, preset, and extensions.

Project Structure

After initialization, your project contains:

my-project/
├── .specify/
│   ├── memory/
│   │   └── constitution.md      # Project governing principles
│   ├── scripts/
│   │   └── bash/ (or powershell/)
│   │       ├── check-prerequisites.sh
│   │       ├── common.sh
│   │       ├── create-new-feature.sh
│   │       └── setup-plan.sh
│   ├── templates/
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   ├── tasks-template.md
│   │   ├── checklist-template.md
│   │   └── constitution-template.md
│   ├── extensions/
│   │   └── git/                 # Auto-installed if git is available
│   ├── init-options.json        # Records init flags for later use
│   └── speckit.manifest.json    # Tracks installed files
├── .claude/ (or .github/, .cursorrules/, etc.)
│   └── commands/                # Agent-specific slash commands
└── AGENTS.md (or CLAUDE.md, etc.)  # Agent context file

Environment Variables

Note

For the complete configuration reference — including extension config files, hook configuration, and catalog settings — see the Admin Guide.

4. Core Usage

The SDD Workflow

Spec Kit guides you through a structured development workflow using slash commands in your AI agent:

Tip

You don't have to use every step for every feature. The minimal workflow is: /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement.

Initializing a Project

New directory:

specify init my-feature --integration copilot

Current directory:

specify init --here --integration claude

With options:

specify init my-project \
  --integration copilot \
  --integration-options="--skills" \
  --script sh \
  --preset lean \
  --branch-numbering timestamp

Important

The --integration and --ai flags are mutually exclusive. Use --integration for all new projects — --ai is deprecated.

Supported Integrations

Spec Kit ships with built-in integrations for 27 AI coding agents:

Note

Use kiro as a shorthand alias for kiro-cli. The Generic integration requires --integration-options="--commands-dir <path>" to specify where command files should be placed.

Managing Integrations

# List installed and available integrations
specify integration list
specify integration list --catalog

# Install a new integration
specify integration install copilot

# Switch between integrations
specify integration switch gemini

# Uninstall an integration
specify integration uninstall copilot

# Upgrade an integration to latest version
specify integration upgrade
specify integration upgrade --force

Warning

Switching integrations removes the previous integration's files. Modified files are preserved, but unmodified files are deleted. Use --force to overwrite modified files during upgrade.

5. Common Tasks

Install and Use an Extension

Extensions add new slash commands and lifecycle hooks to your project.

1. Search the catalog:

   specify extension search "git"
   

2. Get extension details:

   specify extension info aide
   

3. Install:

   specify extension add aide
   

4. The extension's commands are now available as slash commands in your AI agent (e.g., /speckit.aide.vision).

5. Remove when no longer needed:

   specify extension remove aide
   

Extension management commands:

specify extension list                    # List installed extensions
specify extension list --available        # List all available extensions
specify extension search "workflow"       # Search by keyword
specify extension search --tag ci         # Search by tag
specify extension enable <id>             # Enable a disabled extension
specify extension disable <id>            # Disable without removing
specify extension set-priority <id> 10    # Change execution priority
specify extension update <id>             # Update to latest version

Install and Use a Preset

Presets customize the core Spec Kit templates and commands. They stack by priority and support composition strategies.

1. Search presets:

   specify preset search "lean"
   

2. Install a preset:

   specify preset add lean
   

3. Install from a URL:

   specify preset add fiction-book-writing --from https://github.com/adaumann/speckit-preset-fiction-book-writing/archive/refs/tags/v1.6.0.zip
   

4. Check which template a command resolves to:

   specify preset resolve speckit.specify
   

Preset management commands:

specify preset list                       # List installed presets
specify preset info <id>                  # Show preset details
specify preset remove <id>                # Remove a preset
specify preset enable <id>                # Enable a disabled preset
specify preset disable <id>               # Disable without removing
specify preset set-priority <id> 5        # Set priority (lower = higher priority)

Manage Preset Catalogs

specify preset catalog list               # List configured catalogs
specify preset catalog add <url>          # Add a custom catalog
specify preset catalog remove <name>      # Remove a catalog

Run a Workflow

Workflows automate multi-step SDD sequences with review gates.

# List available workflows
specify workflow list

# Run the built-in full SDD cycle
specify workflow run speckit --input spec="Build a login page" --input integration=claude

# Check workflow status
specify workflow status

# Resume a paused workflow
specify workflow resume <run-id>

The built-in speckit workflow runs: specify → (review gate) → plan → (review gate) → tasks → implement.

Create a Feature Branch

When the Git extension is installed (auto-installed by default), feature branching is automated:

# The /speckit.specify command automatically creates a feature branch
# Branch names follow the pattern: specify/NNN-feature-name
# Where NNN is sequential (001, 002, ...) or a timestamp

The Git extension also provides:

• /speckit.git.feature — Create a feature branch manually
• /speckit.git.validate — Validate branch naming conventions
• /speckit.git.remote — Detect Git remote URL
• /speckit.git.initialize — Initialize a Git repository
• /speckit.git.commit — Auto-commit after commands (configurable via git-config.yml)

Use the Lean Preset

The Lean preset strips the default templates down to minimal prompts:

specify init my-project --integration claude --preset lean

This replaces the default specify, plan, tasks, implement, and constitution commands with streamlined versions.

6. Troubleshooting

Error: specify init fails with "No matching release asset found for claude"

Cause: This occurred in older versions that downloaded assets from GitHub releases. The Claude CLI binary name resolution failed.

Solution: Upgrade to the latest version of spec-kit. All scaffolding now uses bundled assets — no network access is required during specify init.

uv tool install specify-cli --force

Prevention: Keep spec-kit up to date with specify upgrade.

Note

This was reported in GitHub issue #2185 and has been resolved.

Error: extension.yml fails to read UTF-8 encoded Chinese content on Windows

Cause: Windows file encoding issues with non-ASCII content in extension manifest files.

Solution: Ensure your extension YAML files are saved as UTF-8 without BOM. Check your editor's encoding settings.

Prevention: Use a UTF-8 capable editor and verify encoding before publishing extensions.

Note

Tracked in GitHub issue #2325.

Error: Custom branch from spec creation is not respected

Cause: The feature directory creation and subsequent steps may not honor a custom branch name set during /speckit.specify.

Solution: Manually create the feature branch before running /speckit.specify, or use the Git extension's /speckit.git.feature command.

Prevention: This is a known open issue (#2305). Check for updates.

Error: specify init --here --force does not update shared scripts or templates

Cause: In some versions, the --here --force combination didn't properly refresh .specify/scripts or .specify/templates files.

Solution: Run:

specify integration upgrade --force

Or remove and reinitialize:

rm -rf .specify/scripts .specify/templates
specify init --here --force

Prevention: Fixed in recent versions — upgrade spec-kit with uv tool install specify-cli --force.

Note

Reported in GitHub issue #2319.

Error: Integration install/switch leaves stale vendored scripts

Cause: When switching integrations, old shared scripts from the previous integration may remain in .specify/scripts/, causing conflicts with newer agents.

Solution: Run specify init --here --force to refresh shared infrastructure, or manually delete stale files from .specify/scripts/.

Prevention: This is tracked in GitHub issue #2293.

Warning

Always verify your .specify/scripts/ directory after switching integrations. Stale scripts can cause unexpected behavior in newer agent integrations.

Copilot automatic hooks cannot invoke sub-agents

Cause: VS Code's Copilot integration does not support automatic hook execution that spawns sub-agent processes.

Solution: Run hook commands manually when prompted by the extension system.

Prevention: Tracked in GitHub issue #2330. This is a limitation of the Copilot integration model.

.vscode/settings.json overwritten during upgrade

Cause: The specify init process merges VS Code settings, but earlier versions could overwrite customizations.

Solution: Spec Kit now performs a "polite deep merge" — new keys are added but existing keys are preserved. Comments and trailing commas in JSONC files are normalized during rewrite.

Prevention: Keep spec-kit updated. Back up .vscode/settings.json before running specify init --here --force.

Caution

When merging VS Code settings, JSONC comments and trailing commas are not preserved. The file is rewritten as standard JSON.

7. FAQ

Q: Can I use Spec Kit with an AI agent that isn't in the supported list?

Yes. Use the Generic integration: specify init my-project --integration generic --integration-options="--commands-dir .myagent/commands/". This creates standard Markdown command files in any directory you specify.

Q: How do I update Spec Kit to the latest version?

Run specify upgrade to check for updates, then uv tool install specify-cli --force to install the latest version.

Q: Can I use multiple integrations at the same time?

No. Only one integration is active at a time. Use specify integration switch <target> to change. Your spec artifacts (spec.md, plan.md, tasks.md) are integration-agnostic and survive switching.

Q: What's the difference between extensions and presets?

Extensions add new commands and hooks (new capabilities). Presets override existing templates and commands (customize behavior). Presets stack by priority and support composition strategies; extensions are independent plugins.

Q: How does preset priority work?

Lower numbers = higher priority. When multiple presets provide the same template, the highest-priority (lowest number) preset wins. Presets can also compose using prepend, append, and wrap strategies instead of replacing.

Q: Can I use Spec Kit offline?

Yes. All scaffolding uses bundled assets — specify init requires no network access. Extension and preset installation from catalogs requires internet, but you can install from local directories or ZIP files with --dev or --from <path>.

Q: How do I contribute an extension or preset to the community catalog?

Use the extension template (extensions/template/) or preset scaffold (presets/scaffold/) as a starting point. Publish to a GitHub repository and submit a PR to add your entry to extensions/catalog.community.json or presets/catalog.community.json.

Q: What happens to my files when I uninstall an integration?

Unmodified files are removed. Files you've edited are preserved. The .specify/ shared infrastructure (scripts, templates) is kept. Use --force to remove modified files too.

Q: Where are feature specs stored?

In a specs/ directory under your project, organized by feature branch. The exact path depends on your branch naming and the current Git branch.

Q: Does Spec Kit work on Windows?

Yes. Spec Kit supports both Bash (--script sh) and PowerShell (--script ps) scripts. On Windows, script execute permissions are a no-op. POSIX execute bits are set automatically on Linux/macOS.