spec-kit Documentation

1. Project Overview & Quickstart (github/spec-kit) Copy Chapter

File: README.md Copy Chapter

Table of Contents Copy Chapter

• 🤔 What is Spec-Driven Development?
• ⚡ Get Started
• 📽️ Video Overview
• 🌍 Community
• 🤖 Supported AI Coding Agent Integrations
• 🔧 Specify CLI Reference
• 🧩 Making Spec Kit Your Own: Extensions & Presets
• 📦 Bundles: Role-Based Setups
• 📚 Core Philosophy
• 🌟 Development Phases
• 🎯 Experimental Goals
• 🔧 Prerequisites
• 📖 Learn More
• 💬 Support
• 🙏 Acknowledgements
• 📄 License

🤔 What is Spec-Driven Development? Copy Chapter

Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them.

⚡ Get Started Copy Chapter

1. Install Specify CLI Copy Section

Requires uv (install uv). Replace vX.Y.Z with the latest release tag from Releases — keep the leading v (for example, v0.12.11, not 0.12.11):

uv tool install specify-cli --from git+https://github.com/github/[email protected]

Prefer installing from PyPI? The specify-cli package is also published there:

uv tool install specify-cli

See the Installation Guide for alternative methods, verification, upgrade, and troubleshooting.

2. Initialize a project Copy Section

specify init my-project --integration copilot
cd my-project

To check for updates or upgrade the installed CLI, use the self-management commands. See the Upgrade Guide for detailed scenarios and customization options.

# Check whether a newer release is available (read-only — does not modify anything)
specify self check

# Preview what would run, without actually upgrading
specify self upgrade --dry-run

# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
specify self upgrade

# Or pin a specific release tag (replace vX.Y.Z[suffix] with your desired release tag)
specify self upgrade --tag vX.Y.Z[suffix]

Bare specify self upgrade executes immediately, matching the no-prompt behavior of commands like pip install -U and npm update. For uv tool installs, it runs uv tool install specify-cli --force --from <git ref> under the hood so pinned release tags work, including dev, alpha/beta/rc, or build metadata suffixes. uvx (ephemeral) runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set SPECIFY_UPGRADE_TIMEOUT_SECS to cap how long the installer subprocess may run (default: no timeout — interrupt with Ctrl+C if needed).

3. Establish project principles Copy Section

Launch your coding agent in the project directory. Most agents expose spec-kit as /speckit.* slash commands; Codex CLI and Command Code in skills mode use $speckit-* instead; GitHub Copilot CLI uses /agents to select the agent or address it directly in a prompt.

Use the /speckit.constitution command to create your project's governing principles and development guidelines that will guide all subsequent development.

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

4. Create the spec Copy Section

Use the /speckit.specify command to describe what you want to build. Focus on the what and why, not the tech stack.

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

5. Create a technical implementation plan Copy Section

Use the /speckit.plan command to provide your tech stack and architecture choices.

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

6. Break down into tasks Copy Section

Use /speckit.tasks to create an actionable task list from your implementation plan.

/speckit.tasks

7. Execute implementation Copy Section

Use /speckit.implement to execute all tasks and build your feature according to the plan.

/speckit.implement

For detailed step-by-step instructions, see our comprehensive guide.

📽️ Video Overview Copy Chapter

Want to see Spec Kit in action? Watch our video overview!

🌍 Community Copy Chapter

Explore community-contributed resources on the Spec Kit docs site:

• Extensions — commands, hooks, and capabilities
• Presets — template and terminology overrides
• Bundles — role and team stacks composed from existing components
• Walkthroughs — end-to-end SDD scenarios
• Friends — projects that extend or build on Spec Kit

[!NOTE]
Community contributions are independently created and maintained by their respective authors. Review source code before installation and use at your own discretion.

Want to contribute? See the Extension Publishing Guide, the Presets Publishing Guide, or the Community Bundles guide.

🤖 Supported AI Coding Agent Integrations Copy Chapter

Spec Kit works with 30+ AI coding agents — both CLI tools and IDE-based assistants. See the full list with notes and usage details in the Supported AI Coding Agent Integrations guide.

Run specify integration list to see all available integrations in your installed version.

Available Slash Commands Copy Chapter

After running specify init, your AI coding agent will have access to these slash commands for structured development. For integrations that support skills mode, passing --integration <agent> --integration-options="--skills" installs agent skills instead of slash-command prompt files.

Core Commands Copy Section

Essential commands for the Spec-Driven Development workflow:

Optional Commands Copy Section

Additional commands for enhanced quality and validation:

🔧 Specify CLI Reference Copy Chapter

For full command details, options, and examples, see the CLI Reference.

🧩 Making Spec Kit Your Own: Extensions & Presets Copy Chapter

Spec Kit can be tailored to your needs through two complementary systems — extensions and presets — plus project-local overrides for one-off adjustments:

• Templates are resolved at runtime — Spec Kit walks the stack top-down and uses the first match.
• Project-local overrides (.specify/templates/overrides/) let you make one-off adjustments for a single project without creating a full preset.
• Extension/preset commands are applied at install time — when you run specify extension add or specify preset add, command files are written into agent directories (e.g., .claude/commands/).
• If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically.
• If no overrides or customizations exist, Spec Kit uses its core defaults.

Extensions — Add New Capabilities Copy Section

Use extensions when you need functionality that goes beyond Spec Kit's core. Extensions introduce new commands and templates — for example, adding domain-specific workflows that are not covered by the built-in SDD commands, integrating with external tools, or adding entirely new development phases. They expand what Spec Kit can do.

# Search available extensions
specify extension search

# Install an extension
specify extension add <extension-name>

For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics.

See the Extensions reference for the full command guide. Browse the community extensions for what's available.

Presets — Customize Existing Workflows Copy Section

Use presets when you want to change how Spec Kit works without adding new capabilities. Presets override the templates and commands that ship with the core and with installed extensions — for example, enforcing a compliance-oriented spec format, using domain-specific terminology, or applying organizational standards to plans and tasks. They customize the artifacts and instructions that Spec Kit and its extensions produce.

# Search available presets
specify preset search

# Install a preset
specify preset add

For example, presets could restructure spec templates to require regulatory traceability, adapt the workflow to fit the methodology you use (e.g., Agile, Kanban, Waterfall, jobs-to-be-done, or domain-driven design), add mandatory security review gates to plans, enforce test-first task ordering, or localize the entire workflow to a different language. The pirate-speak demo shows just how deep the customization can go. Multiple presets can be stacked with priority ordering.

See the Presets reference for the full command guide, including resolution order and priority stacking.

📦 Bundles: Role-Based Setups Copy Chapter

Extensions and presets are individual building blocks. A bundle packages a
curated set of them — extensions, presets, steps, and workflows — into a single,
versioned, role-oriented setup so a whole team persona (product manager, business
analyst, security researcher, developer, …) can be provisioned with one command.

A bundle is described by a hand-written bundle.yml manifest. It pins each
component to a version and, optionally, targets a specific integration; a bundle
with no integration is agnostic and inherits whatever integration the
project already uses.

# Discover bundles in the active catalog stack
specify bundle search [<query>]

# Inspect the exact component set a bundle will add (equals what install does)
specify bundle info 

# Install a bundle's full component set in one operation
specify bundle install 

# See what's installed, then update or remove non-destructively
specify bundle list
specify bundle update      # or --all
specify bundle remove      # removes only this bundle's components

Bundles resolve from a priority-ordered catalog stack (project > user >
built-in). Each source carries an install policy: install-allowed sources can
be installed from, while discovery-only sources are visible in search/info
but refuse installation. Manage the stack with specify bundle catalog list|add|remove.

Authors validate and package bundles locally. Distribution is hosting the built
artifact and adding a catalog source; community bundle submissions use the
Bundle Submission
issue template so required component catalogs and install evidence can be reviewed:

specify bundle validate --path ./my-bundle      # structural + reference checks
specify bundle build --path ./my-bundle         # produce a versioned .zip artifact

Four ready-to-read example bundle manifests live under
examples/bundles/ (product manager, business analyst,
security researcher, developer). These are bundle packaging examples, not
filled generated feature specs; for end-to-end community examples, see the
community walkthroughs.

Key guarantees: info shows exactly what install adds (transparency);
installs are idempotent and confined to the project root; remove never touches
components another installed bundle still needs; and all consume/author commands
work offline against local or pinned sources.

When to Use Which Copy Section

📚 Core Philosophy Copy Chapter

Spec-Driven Development is a structured process that emphasizes:

• Intent-driven development where specifications define the "what" before the "how"
• Rich specification creation using guardrails and organizational principles
• Multi-step refinement rather than one-shot code generation from prompts
• Heavy reliance on advanced AI model capabilities for specification interpretation

🌟 Development Phases Copy Chapter

For existing projects, keep Spec Kit tooling updates separate from feature
artifact evolution: refresh managed project files when upgrading, and update
specs/ artifacts when intended behavior changes. The
Evolving Specs guide describes the
recommended brownfield loop.

🎯 Experimental Goals Copy Chapter

Our research and experimentation focus on:

Technology independence Copy Section

• Create applications using diverse technology stacks
• Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks

Enterprise constraints Copy Section

• Demonstrate mission-critical application development
• Incorporate organizational constraints (cloud providers, tech stacks, engineering practices)
• Support enterprise design systems and compliance requirements

User-centric development Copy Section

• Build applications for different user cohorts and preferences
• Support various development approaches (from vibe-coding to AI-native development)

Creative & iterative processes Copy Section

• Validate the concept of parallel implementation exploration
• Provide robust iterative feature development workflows
• Extend processes to handle upgrades and modernization tasks

🔧 Prerequisites Copy Chapter

• Linux/macOS/Windows
• Supported AI coding agent.
• uv for package management (recommended) or pipx for persistent installation
• Python 3.11+
• Git

If you encounter issues with an agent, please open an issue so we can refine the integration.

📖 Learn More Copy Chapter

• Complete Spec-Driven Development Methodology - Deep dive into the full process
• Quick Start Guide - Step-by-step implementation walkthrough

💬 Support Copy Chapter

For support, please open a GitHub issue. We welcome bug reports, feature requests, and questions about using Spec-Driven Development.

🙏 Acknowledgements Copy Chapter

This project is heavily influenced by and based on the work and research of John Lam.

📄 License Copy Chapter

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.

File: docs/index.md Copy Chapter

GitHub Spec Kit

Spec-Driven Development or your own process — step by step or as an automated workflow.

Spec Kit is an extensible, intent-driven harness that pushes any coding agent beyond code, guiding it across your SDLC or any business process. Use it for Spec-Driven Development (SDD), where you describe what to build and refine it through structured phases. Run it step by step, automate it end to end, or shape a process of your own, keeping intent at the center.

Install Spec Kit 
Quick Start

Spec-driven by default Copy Section

The core SDD process ships ready to use: Spec → Plan → Tasks → Implement.

Define what to build before building it. Rich templates, quality checklists, and cross-artifact analysis come out of the box. Each phase produces a Markdown artifact that feeds the next — giving your AI coding agent structured context instead of ad-hoc prompts.

Walk through the workflow →

Use any coding agent Copy Section

35 integrations — Copilot, Gemini, Codex, Kilo Code, Zed, Claude, Forge, Kiro, and more. Switch freely between agents with a single command. No lock-in.

Run specify init with your agent of choice and Spec Kit sets up the right command files and directory structures automatically. If your agent isn't listed, the generic integration is an escape hatch for any tool.

See all integrations →

Make it your own Copy Section

138 community extensions (70+ authors), 25 presets, and growing. Tune the core process with presets, extend it with extensions, orchestrate it with workflows, and package it all up as bundles you can share — or replace the process entirely. The process itself lives in these building blocks, so you're never locked to SDD, or even to software.

Including entirely different processes:

• AIDE — 7-step AI-driven engineering lifecycle
• Canon — baseline-driven workflows (spec-first, code-first, spec-drift)
• Product Forge — product-management-oriented SDD
• FX→.NET — end-to-end .NET Framework migration across 7 phases
• MAQA — multi-agent orchestration with quality assurance gates
• Fiction Book Writing — novels and long-form fiction, from story bible to submission

Presets →  
Extensions →  
Workflows →  
Bundles →

Integrate into your organization Copy Section

Works offline, behind firewalls, and on Windows, macOS, and Linux. Host your own catalogs to curate what integrations, extensions, presets, workflows, and bundles your organization discovers and recommends.

Community extensions like CI Guard and Architecture Guard add compliance gates and governance that fit the way your team already works.

Enterprise / Air-Gapped →  
Reference →

Built by the community Copy Chapter

240+ contributors power the Spec Kit ecosystem — from core integrations to entirely new processes. Anyone can create and publish an extension, preset, or workflow.

121K+
GitHub stars


240+
Contributors


35
Integrations


138
Extensions


25
Presets


6
Friends projects

Presets · Walkthroughs · Friends

Explore the docs Copy Chapter

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

Ready to start? Follow the Quick Start Guide.

Last updated: July 16, 2026

File: docs/installation.md Copy Chapter

Installation Guide

Prerequisites Copy Chapter

• Linux/macOS (or Windows; PowerShell scripts now supported without WSL)
• AI coding agent: Claude Code, GitHub Copilot, CodeBuddy CLI, Gemini CLI, Pi Coding Agent, or Oh My Pi
• uv for package management (recommended) or pipx for persistent installation
• Python 3.11+
• Git (optional — required only when the git extension is enabled)

Installation Copy Chapter

[!IMPORTANT]
Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the github/spec-kit GitHub repository (source installs) and the specify-cli package on PyPI. Either route is supported for normal installs — use the commands shown below. After installing, run specify version as a local version/runtime sanity check. It confirms that the specify command is available and reports its version, but it does not prove whether the executable came from PyPI or GitHub. For offline or air-gapped environments, locally built wheels created from this repository are also valid.

Spec Kit supports two install routes:

1. Install from source (GitHub) — the recommended route, pinned to a release tag.
2. Install from PyPI — install the published specify-cli package with your usual Python tooling.

Install from Source — Persistent Installation (Recommended) Copy Section

Install once and use everywhere. Replace vX.Y.Z with a release tag from Releases — keep the leading v (for example, v0.12.11, not 0.12.11):

[!NOTE]
The command below requires uv. If you see command not found: uv, install uv first.

uv tool install specify-cli --from git+https://github.com/github/[email protected]

Then initialize a project:

specify init  --integration copilot

Install from PyPI Copy Section

Spec Kit is also published to PyPI as specify-cli, so you can install it with your preferred Python package manager without referencing the Git URL:

# Using uv (recommended)
uv tool install specify-cli

# Or using pipx
pipx install specify-cli

# Or using pip
pip install specify-cli

To install a specific release, pin the version — for example uv tool install specify-cli==0.12.11. See the PyPI installation guide for details, including how to upgrade and how to install from a custom or private package index.

One-time Usage Copy Section

Run directly without installing — see the One-time usage (uvx) guide.

Alternative Package Managers Copy Section

• PyPI — see the PyPI installation guide
• pipx — see the pipx installation guide
• Enterprise / Air-Gapped — see the air-gapped installation guide

Specify Integration Copy Section

Interactive terminals prompt you to choose a coding agent integration during initialization. Non-interactive sessions, such as CI or piped runs, default to GitHub Copilot unless you pass --integration.

You can proactively specify your coding agent integration during initialization:

specify init  --integration claude
specify init  --integration gemini
specify init  --integration copilot
specify init  --integration codebuddy
specify init  --integration pi
specify init  --integration omp

Specify Script Type (Shell, PowerShell, or Python) Copy Section

Automation scripts are available as Bash (.sh), PowerShell (.ps1), and Python (.py) variants.

Auto behavior:

• Windows default: ps
• Other OS default: sh
• Interactive mode: you'll be prompted unless you pass --script

Force a specific script type:

specify init  --script sh
specify init  --script ps
specify init  --script py

Ignore Agent Tools Check Copy Section

If you prefer to get the templates without checking for the right tools:

specify init  --integration claude --ignore-agent-tools

Verification Copy Chapter

After installation, run the following command as a local version/runtime check:

specify version

This confirms that the specify command is available and reporting the expected version. It does not prove whether that executable came from PyPI or GitHub.

Stay current: Run specify self check periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the Upgrade Guide.

After initialization, you should see the following commands available in your coding agent:

• /speckit.specify - Create specifications
• /speckit.plan - Generate implementation plans
• /speckit.tasks - Break down into actionable tasks
• /speckit.implement - Execute implementation tasks
• /speckit.analyze - Validate cross-artifact consistency
• /speckit.clarify - Identify and resolve ambiguities
• /speckit.checklist - Generate quality checklists
• /speckit.constitution - Create or update project principles
• /speckit.converge - Assess codebase against artifacts and append remaining tasks
• /speckit.taskstoissues - Convert tasks to issues

Scripts are installed into a variant subdirectory matching the chosen script type:

• .specify/scripts/bash/ — contains .sh scripts (default on Linux/macOS)
• .specify/scripts/powershell/ — contains .ps1 scripts (default on Windows)
• .specify/scripts/python/ — contains .py scripts (chosen with --script py; also installs the platform shell fallback)

Troubleshooting Copy Chapter

Enterprise / Air-Gapped Installation Copy Section

If your environment blocks access to PyPI or GitHub, see the Enterprise / Air-Gapped Installation guide for step-by-step instructions on creating portable wheel bundles.

Git Credential Manager on Linux Copy Section

If you're having issues with Git authentication on Linux, see the Air-Gapped Installation guide for Git Credential Manager setup instructions.

File: docs/local-development.md Copy Chapter

Local Development Guide

This guide shows how to iterate on the specify CLI locally without publishing a release or committing to main first.

Scripts are available as Bash (.sh), PowerShell (.ps1), and Python (.py) variants. Interactive specify init prompts you to choose one; non-interactive runs default to a shell variant for your OS. Pass --script sh|ps|py to select explicitly.

1. Clone and Switch Branches Copy Chapter

git clone https://github.com/github/spec-kit.git
cd spec-kit
# Work on a feature branch
git checkout -b your-feature-branch

2. Run the CLI Directly (Fastest Feedback) Copy Chapter

You can execute the CLI via the module entrypoint without installing anything:

# From repo root
python -m src.specify_cli --help
python -m src.specify_cli init demo-project --integration claude --ignore-agent-tools --script sh

If you prefer invoking the script file style (uses shebang):

python src/specify_cli/__init__.py init demo-project --script ps

3. Use Editable Install (Isolated Environment) Copy Chapter

Create an isolated environment using uv so dependencies resolve exactly like end users get them:

# Create & activate virtual env (uv auto-manages .venv)
uv venv
source .venv/bin/activate  # or on Windows PowerShell: .venv\Scripts\Activate.ps1

# Install project in editable mode
uv pip install -e .

# Now 'specify' entrypoint is available
specify --help

Re-running after code edits requires no reinstall because of editable mode.

4. Invoke with uvx Directly From Git (Current Branch) Copy Chapter

uvx can run from a local path (or a Git ref) to simulate user flows:

uvx --from . specify init demo-uvx --integration copilot --ignore-agent-tools --script sh

You can also point uvx at a specific branch without merging:

# Push your working branch first
git push origin your-feature-branch
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps

4a. Absolute Path uvx (Run From Anywhere) Copy Section

If you're in another directory, use an absolute path instead of .:

uvx --from /mnt/c/GitHub/spec-kit specify --help
uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --integration copilot --ignore-agent-tools --script sh

Set an environment variable for convenience:

export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
uvx --from "$SPEC_KIT_SRC" specify init demo-env --integration copilot --ignore-agent-tools --script ps

(Optional) Define a shell function:

specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
# Then
specify-dev --help

5. Testing Script Permission Logic Copy Chapter

After running an init, check that shell scripts are executable on POSIX systems:

ls -l scripts | grep .sh
# Expect owner execute bit (e.g. -rwxr-xr-x)

On Windows you will instead use the .ps1 scripts (no chmod needed).

6. Scaffold a Built-In Integration Copy Chapter

Use the integration scaffold command to create the initial Python package and
test skeleton for a new built-in integration:

specify integration scaffold my-agent --type markdown
specify integration scaffold my-agent --type toml
specify integration scaffold my-agent --type yaml
specify integration scaffold my-agent --type skills

Hyphenated keys are converted to Python-safe package names, for example
my-agent creates src/specify_cli/integrations/my_agent/ and
tests/integrations/test_integration_my_agent.py.

The scaffold does not register the integration automatically. Review the
generated metadata, then add the import and _register() call in
src/specify_cli/integrations/__init__.py.

7. Run Lint / Basic Checks Copy Chapter

CI enforces ruff check src tests (see .github/workflows/test.yml), so run it locally before pushing:

uvx ruff check src tests

You can also quickly sanity check importability:

python -c "import specify_cli; print('Import OK')"

8. Build a Wheel Locally (Optional) Copy Chapter

Validate packaging before publishing:

uv build
ls dist/

Install the built artifact into a fresh throwaway environment if needed.

9. Using a Temporary Workspace Copy Chapter

When testing init --here in a dirty directory, create a temp workspace:

mkdir /tmp/spec-test && cd /tmp/spec-test
python -m src.specify_cli init --here --integration claude --ignore-agent-tools --script sh  # if repo copied here

Or copy only the modified CLI portion if you want a lighter sandbox.

10. Debug Network / TLS Issues Copy Chapter

Deprecated: The --skip-tls flag is a no-op and has no effect.
It was previously used to bypass TLS validation during local testing.
If you encounter TLS errors (e.g., on a corporate network), configure your
environment's certificate store or proxy instead.

For example, set SSL_CERT_FILE or configure HTTPS_PROXY / HTTP_PROXY.

11. Rapid Edit Loop Summary Copy Chapter

12. Cleaning Up Copy Chapter

Remove build artifacts / virtual env quickly:

rm -rf .venv dist build *.egg-info

13. Common Issues Copy Chapter

14. Next Steps Copy Chapter

• Update docs and run through Quick Start using your modified CLI
• Open a PR when satisfied
• (Optional) Tag a release once changes land in main

File: docs/quickstart.md Copy Chapter

Quick Start Guide

This guide will help you get started with Spec-Driven Development using Spec Kit. Throughout, we illustrate each step with a running example: Taskify, a small team productivity platform.

[!NOTE]
Automation scripts are provided as Bash (.sh), PowerShell (.ps1), and Python (.py) variants. Interactive specify init prompts you to choose one; non-interactive runs default to a shell variant for your OS. Pass --script sh|ps|py to select explicitly.

Commands are shown here in /speckit.* form, but the exact invocation depends on your agent. Some skills-based agents use $speckit-* (e.g. Codex, ZCode) or /skill:speckit-* (e.g. Kimi). Use whichever form your agent exposes — the steps are otherwise identical.

Recommended Process Copy Chapter

[!TIP]
Context Awareness: Spec Kit tracks the active feature by the feature directory recorded in .specify/feature.json (overridable with the SPECIFY_FEATURE_DIRECTORY environment variable). Commands resolve the feature from that state, not from the checked-out Git branch — no Git required. The opt-in git extension adds numbered feature branches (e.g. 001-feature-name) for organizing work in version control, but the active feature is still whichever directory that state points to; git checkout alone does not change it. To point commands at a different feature, update .specify/feature.json (or set SPECIFY_FEATURE_DIRECTORY).

After installing Spec Kit, each command below is a step in the process. Two paths are common:

Shorter path — for smaller features:

1. /speckit.specify
2. /speckit.plan
3. /speckit.tasks
4. /speckit.implement
5. /speckit.converge

Full path — for production features, adding /speckit.clarify, /speckit.checklist, and /speckit.analyze as quality gates:

1. /speckit.constitution
2. /speckit.specify
3. /speckit.clarify
4. /speckit.plan
5. /speckit.checklist
6. /speckit.tasks
7. /speckit.analyze
8. /speckit.implement
9. /speckit.converge

Install Specify Copy Section

In your terminal, install the CLI from PyPI (requires uv), then initialize your project:

uv tool install specify-cli
specify init taskify   # or: specify init .   to use the current directory

init lets you pick your coding agent interactively, or pass it explicitly with --integration (e.g. --integration copilot).

[!NOTE]
Prefer pipx, one-time uvx runs, a pinned release, or an offline/air-gapped setup? See the Installation Guide for all supported methods.

Step 1: `/speckit.constitution` — set the ground rules Copy Section

Establishes the project's guiding principles, which every later step is evaluated against. Run it once up front, passing your principles as arguments.

/speckit.constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.

Step 2: `/speckit.specify` — describe what to build Copy Section

Creates the feature specification from a natural-language description. Focus on the what and why, not the tech stack.

/speckit.specify Develop Taskify, a team productivity platform where predefined users create projects, assign tasks, comment, and move tasks across Kanban columns (To Do, In Progress, In Review, Done). Five users (one product manager, four engineers), three sample projects, no login for this first phase.

Step 3: `/speckit.clarify` — resolve ambiguities Copy Section

Asks targeted questions about anything underspecified and folds your answers back into the spec, so you're not planning on top of ambiguity. Run it before planning, optionally with a focus area.

/speckit.clarify Focus on task card behavior — status changes, comment permissions, and user assignment.

Step 4: `/speckit.plan` — choose the tech stack Copy Section

Generates the design artifacts from the spec. This is where implementation detail belongs — provide your tech stack and architecture.

/speckit.plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications.

Step 5: `/speckit.checklist` — validate the spec Copy Section

Generates a custom quality checklist — "unit tests for your requirements" — to confirm the spec is complete, clear, and consistent before you break the work down. These custom checklists are reviewer-owned requirements-quality review artifacts: mark an item [x] only when the reviewer determines that requirement-quality criterion is satisfied. Checked custom items do not mean implementation work is complete.

/speckit.checklist

Step 6: `/speckit.tasks` — break the work down Copy Section

Generates an actionable, dependency-ordered tasks.md from the design artifacts.

/speckit.tasks

Step 7: `/speckit.analyze` — check consistency Copy Section

Reports conflicts, gaps, and ambiguities across spec.md, plan.md, and tasks.md. It's read-only — if it flags issues, fix them at the source and re-run before implementing.

/speckit.analyze

Step 8: `/speckit.implement` — build it Copy Section

Executes the tasks in tasks.md in dependency order. Before implementation, it reads checklist checkbox state as a gate and asks before proceeding if any checklist items are unchecked; it does not change any checklist files or markers. The built-in checklists/requirements.md checklist is maintained by /speckit.specify and /speckit.clarify, while custom checklists remain reviewer-owned. Run it once to build everything, or scope it to one phase at a time for large features.

/speckit.implement

Step 9: `/speckit.converge` — verify completeness Copy Section

Checks the codebase against the spec, plan, and tasks. If it finds gaps, it appends new tasks to tasks.md; run /speckit.implement and converge again until it reports converged. Otherwise you're done — proceed to review or open a PR.

/speckit.converge

[!TIP]
For a full reference on each command — arguments, output, phased implementation, and how they interact — see Agentic SDD.

Key Principles Copy Chapter

• Be explicit about what you're building and why
• Don't focus on tech stack during specification phase
• Iterate and refine your specifications before implementation
• Validate requirements and plans before coding begins
• Let the coding agent handle the implementation details

Next Steps Copy Chapter

• See the Agentic SDD reference for full detail on every command
• Read the complete methodology for in-depth guidance
• Compare the core templates with
  community walkthroughs to see how Spec-Driven Development is used in real projects
• Explore the source code on GitHub

File: docs/README.md Copy Chapter

Documentation

This folder contains the documentation source files for Spec Kit, built using DocFX.

Building Locally Copy Chapter

To build the documentation locally:

1. Install DocFX:

   bash Copy

   dotnet tool install -g docfx

2. Build the documentation:

   bash Copy

   cd docs
   docfx docfx.json --serve

3. Open your browser to http://localhost:8080 to view the documentation.

Structure Copy Chapter

• docfx.json - DocFX configuration file
• index.md - Main documentation homepage
• toc.yml - Table of contents configuration
• installation.md - Installation guide
• quickstart.md - Quick start guide
• _site/ - Generated documentation output (ignored by git)

Deployment Copy Chapter

Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the main branch. The workflow is defined in .github/workflows/docs.yml.

File: docs/upgrade.md Copy Chapter

Upgrade Guide

You have Spec Kit installed and want to upgrade to the latest version to get new features, bug fixes, or updated slash commands. This guide covers both upgrading the CLI tool and updating your project files.

Quick Reference Copy Chapter

Part 1: Upgrade the CLI Tool Copy Chapter

The CLI tool (specify) is separate from your project files. Upgrade it to get the latest features and bug fixes.

Recommended: `specify self upgrade` Copy Section

The CLI ships with two self-management commands that handle the common case automatically:

# Check whether a newer release is available (read-only — does not modify anything)
specify self check

# Preview what would run, without actually upgrading
specify self upgrade --dry-run

# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
specify self upgrade

# Or pin a specific release tag (replace vX.Y.Z[suffix] with the tag you want)
specify self upgrade --tag vX.Y.Z[suffix]

Bare specify self upgrade executes immediately, matching the no-prompt behavior of commands like pip install -U and npm update. The CLI classifies your runtime into one of: uv tool, pipx, uvx (ephemeral), source checkout, or unsupported. Only uv tool and pipx are upgraded automatically; for uv tool installs, it runs uv tool install specify-cli --force --from <git ref> under the hood so pinned release tags work. The other paths print path-specific guidance and exit 0 without touching anything.

Pinned tags must start with vMAJOR.MINOR.PATCH. Optional suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms such as v1.0.0-rc1, v0.8.0.dev0, v0.8.0+build.42, or the combination v1.0.0-rc1+build.42; branch names, hash refs, latest, and bare versions without v are rejected.

Set SPECIFY_UPGRADE_TIMEOUT_SECS to cap how long the installer subprocess may run (default: no timeout — interrupt with Ctrl+C if needed). If that internal timeout fires, specify self upgrade exits 124 and reports that it timed out while waiting for the installer subprocess, including the configured timeout and manual retry command. A real installer exit code 124 is propagated with Upgrade failed. Installer exit code: 124., so scripts should treat exit 124 as ambiguous and inspect the message when they need to distinguish the two cases.

If your installed CLI is older than the release that introduced specify self upgrade, use the manual equivalents below. These commands are also useful when you want explicit control over the installer command.

If you installed with `uv tool install` Copy Section

Upgrade to a specific release (check Releases for the latest tag):

uv tool install specify-cli --force --from git+https://github.com/github/[email protected]

If you use one-shot `uvx` commands Copy Section

Specify the desired release tag:

uvx --from git+https://github.com/github/[email protected] specify init --here --integration copilot

uvx runs a temporary copy of Spec Kit for that single command. It does not update a persistent specify installed with uv tool install, pipx, or another tool manager. If a newer feature works through uvx but your local specify still reports an older version, upgrade the persistent CLI with the command that matches your install method.

If you installed with `pipx` Copy Section

Upgrade to a specific release:

pipx install --force git+https://github.com/github/[email protected]

Verify the upgrade Copy Section

# Confirms the CLI is working and shows installed tools
specify check

# Confirms the installed version against the latest GitHub release
specify self check

specify check shows the surrounding tool environment; specify self check is read-only and tells you whether you're now on the latest release (Up to date: X.Y.Z) or if a newer one became available between releases.

Part 2: Updating Project Files Copy Chapter

When Spec Kit releases new features (like new slash commands, updated templates, or extension changes), you need to refresh the Spec Kit files that were installed into your project.

What gets updated? Copy Section

For existing Spec Kit projects, use the manifest-aware upgrade path first:

• ✅ Integration command/skill files (.claude/skills/, .github/prompts/, .agents/skills/, etc.)
• ✅ Managed shared scripts and templates (.specify/scripts/, .specify/templates/) when they are unchanged from the previous managed copy
• ✅ Installed extensions when you run specify extension update

The integration upgrade command uses the install manifest to detect local edits. If a managed integration file was modified after install, the command stops and asks you to inspect the change or rerun with --force.

What stays safe? Copy Section

These files are never touched by the manifest-aware integration/extension upgrade path:

• ✅ Your specifications (specs/001-my-feature/spec.md, etc.) - CONFIRMED SAFE
• ✅ Your implementation plans (specs/001-my-feature/plan.md, tasks.md, etc.) - CONFIRMED SAFE
• ✅ Your constitution (.specify/memory/constitution.md) when using specify integration upgrade
• ✅ Your source code - CONFIRMED SAFE
• ✅ Your git history - CONFIRMED SAFE

The specs/ directory is completely excluded from template packages and will never be modified during upgrades.

1. Check installed integrations Copy Section

Run this inside your project directory:

specify integration status

This reports the default integration, all installed integrations, and any modified or missing managed files. You can also inspect .specify/integration.json; installed integrations are listed under installed_integrations.

2. Upgrade each installed integration Copy Section

Run this inside your project directory:

specify integration upgrade <key>

Replace <key> with an installed integration key such as copilot, claude, or codex. In projects with multiple installed integrations, run the command once per installed key.

Example:

specify integration upgrade claude
specify integration upgrade codex

See the integration reference for options such as --script, --integration-options, and --force.

3. Update installed extensions Copy Section

Run:

specify extension update

With no extension argument, this updates all installed extensions. Use specify extension update <extension-id-or-name> to update only one extension. See the extensions reference for details.

Fallback: re-run init Copy Section

If a project predates manifests, has missing integration metadata, or needs a broader recovery, you can still re-run init:

specify init --here --force --integration <your-agent>

Use this as an escape hatch rather than the default project-file upgrade path. It refreshes the selected integration and shared project scaffolding, but it does not use the same per-integration manifest checks before overwriting files.

⚠️ Important Warnings Copy Chapter

1. Constitution file and memory customizations Copy Section

specify integration upgrade <key> does not update .specify/memory/constitution.md.

The fallback specify init --here --force --integration <your-agent> path also preserves an existing .specify/memory/constitution.md; if the file is missing, init creates it from the current constitution template. You do not need a constitution backup/restore step for the manifest-aware upgrade path.

As with any broad fallback refresh, commit or back up local customizations before using init --here --force so you can review the resulting diff.

2. Custom integration, script, or template modifications Copy Section

specify integration upgrade <key> blocks when manifest-tracked integration files were modified locally, unless you pass --force.

Shared scripts and templates are refreshed when they still match the previously recorded managed copy. Local customizations are preserved unless you explicitly use a force/refresh option that overwrites them. If you customized files in .specify/scripts/ or .specify/templates/, commit or back them up first:

# Back up custom templates and scripts
cp -r .specify/templates .specify/templates-backup
cp -r .specify/scripts .specify/scripts-backup

# After upgrade, merge your changes back manually

3. Duplicate slash commands (IDE-based agents) Copy Section

Some IDE-based agents (like Kilo Code, Cline) may show duplicate slash commands after upgrading—both old and new versions appear.

Solution: Manually delete the old command files from your agent's folder.

Example for Kilo Code:

# List current and legacy Kilo command folders
ls -la .kilo/commands/
ls -la .kilocode/workflows/

# Delete old versions (example filenames - yours may differ)
rm .kilocode/workflows/speckit.specify-old.md
rm .kilocode/workflows/speckit.plan-v1.md

Restart your IDE to refresh the command list.

Behavior change: `/constitution` no longer propagates into templates Copy Chapter

The /constitution command (#3790) is scoped to
its own artifact. It updates
.specify/memory/constitution.md and writes a Sync Impact Report, and no longer edits
plan-template.md, spec-template.md, tasks-template.md, installed command files, or
guidance docs.

Why Copy Section

Spec Kit uses runtime resolution: plan, tasks, and analyze read
.specify/memory/constitution.md live on every run, and analyze is the dedicated drift
checker. The governed templates carry a pointer, not a copy — plan-template.md ships
[Gates determined based on constitution file], and /plan fills that section from the live
constitution each run. Propagation duplicated the single source of truth and fought the
preset/override composition system (a replace preset shadows an edited core template).

More broadly, presets and extensions — not in-place file edits — are how Spec Kit now governs
shared assets. Composing policy through the resolution stack keeps it centrally owned, versioned,
and auditable across repositories, instead of frozen into per-repo copies no core team can see.

Is this a breaking change for existing projects? Copy Section

No — your workflow keeps working. You would only notice a difference if you relied on
/constitution editing those files in place. The templates are scaffolds, not authorities. When you
run /plan, it copies the template into a per-feature plan.md and re-derives the Constitution
Check from the live constitution; /analyze validates against it. Even if a previous
/constitution run materialized concrete gate text into .specify/templates/plan-template.md,
the live constitution remains the source of truth at runtime.

On a non-forced upgrade, a materialized template is preserved (its hash diverges from the
recorded managed copy, so the refresh treats it as a customization and does not overwrite it).
Nothing regresses.

Optional cleanup — return to the runtime pointer Copy Section

A frozen, pre-filled Constitution Check is a slightly misleading scaffold and can bias the first
/plan pass. To move fully back to runtime resolution, reset the section body in
.specify/templates/plan-template.md to the pointer:

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

[Gates determined based on constitution file]

Leave the rest of the file untouched. This is cleanup, not a required migration.

Keeping the old behavior (opt-in) Copy Section

If your team treats the materialized templates as reviewed, committed artifacts and wants
/constitution to keep propagating, install the bundled constitution-sync preset:

specify preset add constitution-sync

It wraps the core /constitution command and re-adds the propagation pass. It does not edit
versioned preset- or extension-provided templates or command files (those are owned by their
packages and are recomposed on reconciliation). Note that this edit-in-place propagation model
conflicts with the composition model used by the rest of the SDD commands when they are
preset/extension-managed — see the "Interaction with the resolution stack" section in
presets/constitution-sync/README.md for the tradeoffs and when to prefer the default instead.

Common Scenarios Copy Chapter

Scenario 1: "I just want new slash commands" Copy Section

# Upgrade CLI (auto-detects uv tool vs pipx install)
specify self upgrade

# Inspect installed integrations
specify integration status

# Update project files to get new commands
specify integration upgrade <key>
specify extension update

Scenario 2: "I customized templates and constitution" Copy Section

# 1. Commit or back up customizations
git status
cp -r .specify/templates /tmp/templates-backup

# 2. Upgrade CLI
specify self upgrade

# 3. Use the manifest-aware project update first
specify integration upgrade <key>
specify extension update

# 4. If the upgrade reports modified managed files, inspect the diff before using --force

Scenario 3: "I see duplicate slash commands in my IDE" Copy Section

This happens with IDE-based agents (Kilo Code, Cline, etc.).

# For Kilo Code, inspect both current and legacy command folders
ls -la .kilo/commands/
ls -la .kilocode/workflows/

# Delete old command files
rm .kilocode/workflows/speckit.old-command-name.md

# Restart your IDE

Scenario 4: "I don't want the git extension" Copy Section

The git extension is now opt-in, so upgrades do not install it unless you add it explicitly.

# Upgrade CLI
specify self upgrade

# Refresh integration files and installed extensions
specify integration upgrade <key>
specify extension update

# The git extension is not added unless you run `specify extension add git`

If you later decide you want the git extension's commands and hooks, install it explicitly:

specify extension add git

Projects that do not use Git can still work with Spec Kit by setting SPECIFY_FEATURE_DIRECTORY to the feature directory path before planning commands:

# Bash/Zsh
export SPECIFY_FEATURE_DIRECTORY="specs/001-my-feature"

# PowerShell
$env:SPECIFY_FEATURE_DIRECTORY = "specs/001-my-feature"

Alternatively, run the /speckit.specify command which creates .specify/feature.json automatically.

Troubleshooting Copy Chapter

"Slash commands not showing up after upgrade" Copy Section

Cause: Agent didn't reload the command files.

Fix:

1. Restart your IDE/editor completely (not just reload window)

2. For CLI-based agents, verify files exist:

   bash Copy

   ls -la .claude/skills/        # Claude Code
   ls -la .gemini/commands/      # Gemini
   ls -la .cursor/skills/      # Cursor
   ls -la .pi/prompts/           # Pi Coding Agent
   ls -la .omp/commands/         # Oh My Pi

3. Check agent-specific setup:

   • Codex requires CODEX_HOME environment variable
   • Some agents need workspace restart or cache clearing

"Will init overwrite my constitution customizations?" Copy Section

Current specify init --here --force preserves an existing .specify/memory/constitution.md; it creates the file from the template only when it is missing.

If you previously lost constitution changes through an older workflow or manual replacement, restore from git or backup:

# If you committed the customized constitution
git restore .specify/memory/constitution.md

# If you backed up manually
cp /tmp/constitution-backup.md .specify/memory/constitution.md

Prevention: Use specify integration upgrade <key> for routine project-file updates. If you need the fallback specify init --here --force path, commit first so you can review the full diff afterward.

"Warning: Current directory is not empty" Copy Section

Full warning message:

Warning: Current directory is not empty (25 items)
Template files will be merged with existing content and may overwrite existing files
Do you want to continue? [y/N]

What this means:

This warning appears when you run specify init --here (or specify init .) in a directory that already has files. It's telling you:

1. The directory has existing content - In the example, 25 files/folders
2. Files will be merged - New template files will be added alongside your existing files
3. Some files may be overwritten - If you already have Spec Kit files (.claude/, .specify/, etc.), they'll be replaced with the new versions

What gets overwritten:

Only Spec Kit infrastructure files:

• Agent command/skill files (.claude/skills/, .github/prompts/, etc.)
• Scripts in .specify/scripts/
• Templates in .specify/templates/
• Missing memory files such as .specify/memory/constitution.md may be created from templates; an existing constitution is preserved

What stays untouched:

• Your specs/ directory (specifications, plans, tasks)
• Your source code files
• Your .git/ directory and git history
• Any other files not part of Spec Kit templates

How to respond:

• Type y and press Enter - Proceed with the merge when using the fallback init path

• Type n and press Enter - Cancel the operation

• Use --force flag - Skip this confirmation entirely:

  bash Copy

  specify init --here --force --integration copilot

When you see this warning:

• ✅ Expected when using the fallback init path in an existing Spec Kit project
• ✅ Expected when adding Spec Kit to an existing codebase
• ⚠️ Unexpected if you thought you were creating a new project in an empty directory

Prevention tip: Before using the fallback init path, commit your current work so any refreshed files are easy to review or restore.

"CLI upgrade doesn't seem to work" Copy Section

If a command behaves like an older Spec Kit version, first ask the CLI itself:

# Read-only — prints "Up to date: X.Y.Z" or "Update available: X.Y.Z → vY.Z.W"
specify self check

# Preview the install method, current version, and target tag the upgrade would use
specify self upgrade --dry-run

specify check is an offline environment scan; specify self check is the CLI version lookup.

If self check shows the wrong version, verify the installation:

# Check installed tools
uv tool list

# Should show specify-cli

# Verify path
which specify

# Should point to the uv tool installation directory

If not found, reinstall:

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

"Do I need to run specify every time I open my project?" Copy Section

Short answer: No, you only run specify init once per project, or later as a fallback recovery path.

Explanation:

The specify CLI tool is used for:

• Initial setup: specify init to bootstrap Spec Kit in your project
• Routine project-file upgrades: specify integration upgrade <key> and specify extension update
• Fallback recovery: specify init --here --force when integration metadata is missing or the manifest-aware path cannot be used
• Diagnostics: specify check to verify tool installation

Once you've run specify init, the slash commands (like /speckit.specify, /speckit.plan, etc.) are permanently installed in your project's agent folder (.claude/, .github/prompts/, .pi/prompts/, .omp/commands/, etc.). Your AI coding agent reads these command files directly—no need to run specify again.

If your agent isn't recognizing slash commands:

1. Verify command files exist:

   bash Copy

   # For GitHub Copilot
   ls -la .github/prompts/
   
   # For Claude
   ls -la .claude/skills/
   
   # For Pi
   ls -la .pi/prompts/
   
   # For Oh My Pi
   ls -la .omp/commands/

2. Restart your IDE/editor completely (not just reload window)

3. Check you're in the correct directory where you ran specify init

4. For some agents, you may need to reload the workspace or clear cache

Related issue: If Copilot can't open local files or uses PowerShell commands unexpectedly, this is typically an IDE context issue, not related to specify. Try:

• Restarting VS Code
• Checking file permissions
• Ensuring the workspace folder is properly opened

Version Compatibility Copy Chapter

Spec Kit follows semantic versioning for major releases. The CLI and project files are designed to be compatible within the same major version.

Best practice: Keep both CLI and project files in sync by upgrading both together during major version changes.

Next Steps Copy Chapter

After upgrading:

• Test new slash commands: Run /speckit.constitution or another command to verify everything works
• Review release notes: Check GitHub Releases for new features and breaking changes
• Update workflows: If new commands were added, update your team's development workflows
• Check documentation: Visit github.io/spec-kit for updated guides

2. Official Technical Reference & Guides (github/docs) Copy Chapter

GitHub Docs

Welcome to GitHub Docs! GitHub’s documentation is open source, meaning anyone from inside or outside the company can contribute. For full contributing guidelines, visit our contributing guide.

Quick links by contributor type Copy Chapter

• Hubbers (GitHub employees): See CONTRIBUTING.md in the docs-content repository for GitHub-specific processes.

• Open source contributors: See CONTRIBUTING.md in the docs repository for a quick-start summary.

How we sync changes across Docs repositories Copy Chapter

There are two GitHub Docs repositories:

• github/docs (public): Open to external contributions

• github/docs-internal (private): For GitHub employee contributions.

The two repositories sync frequently. Content changes in one are reflected in the other. Hubbers might prefer to post in docs when working with a customer, but docs has limitations on the types of contributions it accepts to safeguard the site and our workflows. Internal contributions should usually go to docs-internal.

Important: The docs repository accepts contributions to content files (.md files in /content and select /data sections like reusables only). Infrastructure files, workflows, and site-building code are not open for external modification.

New to contributing Copy Chapter

Here are some resources to help you get started with open source contributions:

• Finding ways to contribute to open source on GitHub
• Set up Git
• GitHub flow
• Collaborating with pull requests

License Copy Chapter

This project is dual-licensed under:

• Creative Commons Attribution 4.0 - for documentation and content in the assets, content, and data folders (see LICENSE)
• MIT License - for code (see LICENSE-CODE)