# 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:**

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

```text
███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝
╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝
███████║██║     ███████╗╚██████╗██║██║        ██║
╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝

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

| Requirement | Minimum | Notes |
|---|---|---|
| Python | 3.11+ | Required for the CLI |
| `uv` | Latest | Recommended package manager |
| Git | Any recent | Optional; needed for branching features |
| AI agent CLI | Varies | At least one supported agent (Claude Code, Copilot, etc.) |

### Install Methods

=== "uv (recommended)"
    ```bash
    uv tool install specify-cli
    ```

=== "uvx (one-shot)"
    ```bash
    uvx specify-cli init my-project
    ```

=== "pip"
    ```bash
    pip install specify-cli
    ```

### Post-Install Verification

```bash
specify --version
```

```text
specify 0.7.2
```

```bash
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:

```bash
specify check
```

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

```bash
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:

```text
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

| Variable | Purpose |
|---|---|
| `SPECKIT_CATALOG_URL` | Override the default extension catalog URL |
| `SPECKIT_PRESET_CATALOG_URL` | Override the default preset catalog URL |

> [!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:

| Step | Command | What It Does |
|---|---|---|
| 1. Constitution | `/speckit.constitution` | Set up project governing principles and guidelines |
| 2. Specify | `/speckit.specify` | Create a feature specification from a natural language description |
| 3. Clarify | `/speckit.clarify` | Structured clarification of underspecified requirements |
| 4. Plan | `/speckit.plan` | Generate a technical implementation plan from the spec |
| 5. Tasks | `/speckit.tasks` | Break the plan into actionable task items |
| 6. Implement | `/speckit.implement` | Execute all tasks to build the feature |
| 7. Analyze | `/speckit.analyze` | Cross-artifact consistency analysis |
| 8. Checklist | `/speckit.checklist` | Generate quality validation checklists |
| 9. Tasks to Issues | `/speckit.taskstoissues` | Convert tasks into GitHub issues |

> [!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:**

```bash
specify init my-feature --integration copilot
```

**Current directory:**

```bash
specify init --here --integration claude
```

**With options:**

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

| Flag | Description |
|---|---|
| `--integration <name>` | AI agent integration to use (see supported list below) |
| `--integration-options` | Options for the integration (e.g., `"--skills"`, `"--commands-dir .myagent/"`) |
| `--script sh\|ps` | Script type: `sh` (Bash) or `ps` (PowerShell) |
| `--preset <id>` | Install a preset during initialization |
| `--branch-numbering` | `sequential` (001, 002, …) or `timestamp` (YYYYMMDD-HHMMSS) |
| `--here` | Initialize in current directory |
| `--force` | Overwrite existing files when using `--here` |
| `--no-git` | Skip git repository initialization |
| `--ai-skills` | Install commands as agent skills (requires `--ai`) |
| `--offline` | Deprecated (no-op); all scaffolding now uses bundled assets |

> [!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:

| Integration | Key | Format | Type |
|---|---|---|---|
| Claude Code | `claude` | Skills | CLI |
| GitHub Copilot | `copilot` | Markdown / Skills | IDE |
| Gemini CLI | `gemini` | TOML | CLI |
| Cursor | `cursor-agent` | Skills | IDE |
| Windsurf | `windsurf` | Markdown | IDE |
| Forge | `forge` | Markdown | CLI |
| Codex CLI | `codex` | Skills | CLI |
| Kiro CLI | `kiro-cli` | Markdown | CLI |
| Goose | `goose` | YAML | CLI |
| Tabnine CLI | `tabnine` | TOML | CLI |
| Roo Code | `roo` | Markdown | IDE |
| Kilo Code | `kilocode` | Markdown | IDE |
| Amp | `amp` | Markdown | CLI |
| Qwen Code | `qwen` | Markdown | CLI |
| opencode | `opencode` | Markdown | CLI |
| Junie | `junie` | Markdown | CLI |
| Auggie CLI | `auggie` | Markdown | CLI |
| SHAI | `shai` | Markdown | CLI |
| Trae | `trae` | Skills | IDE |
| IBM Bob | `bob` | Markdown | IDE |
| CodeBuddy | `codebuddy` | Markdown | CLI |
| Qoder CLI | `qodercli` | Markdown | CLI |
| Kimi Code | `kimi` | Skills | CLI |
| Pi Coding Agent | `pi` | Markdown | CLI |
| iFlow CLI | `iflow` | Markdown | CLI |
| Mistral Vibe | `vibe` | Markdown | CLI |
| Antigravity | `agy` | Skills | IDE |
| Generic | `generic` | Markdown | Any |

> [!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

```bash
# 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:

   ```bash
   specify extension search "git"
   ```

2. Get extension details:

   ```bash
   specify extension info aide
   ```

3. Install:

   ```bash
   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:

   ```bash
   specify extension remove aide
   ```

**Extension management commands:**

```bash
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:

   ```bash
   specify preset search "lean"
   ```

2. Install a preset:

   ```bash
   specify preset add lean
   ```

3. Install from a URL:

   ```bash
   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:

   ```bash
   specify preset resolve speckit.specify
   ```

**Preset management commands:**

```bash
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

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

```bash
# 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:

```bash
# 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:

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

```bash
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:

```bash
specify integration upgrade --force
```

Or remove and reinitialize:

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

---

_Generated May 2026 from github/spec-kit at 6bf4ebb. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._