## 1. Project Overview & Quickstart (github/spec-kit) ## File: README.md --- ## Table of Contents - [πŸ€” What is Spec-Driven Development?](#-what-is-spec-driven-development) - [⚑ Get Started](#-get-started) - [πŸ“½οΈ Video Overview](#️-video-overview) - [🌍 Community](#-community) - [πŸ€– Supported AI Coding Agent Integrations](#-supported-ai-coding-agent-integrations) - [πŸ”§ Specify CLI Reference](#-specify-cli-reference) - [🧩 Making Spec Kit Your Own: Extensions & Presets](#-making-spec-kit-your-own-extensions--presets) - [πŸ“¦ Bundles: Role-Based Setups](#-bundles-role-based-setups) - [πŸ“š Core Philosophy](#-core-philosophy) - [🌟 Development Phases](#-development-phases) - [🎯 Experimental Goals](#-experimental-goals) - [πŸ”§ Prerequisites](#-prerequisites) - [πŸ“– Learn More](#-learn-more) - [πŸ’¬ Support](#-support) - [πŸ™ Acknowledgements](#-acknowledgements) - [πŸ“„ License](#-license) ## πŸ€” What is Spec-Driven Development? 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 ### 1. Install Specify CLI Requires **[uv](https://docs.astral.sh/uv/)** ([install uv](./docs/install/uv.md)). Replace `vX.Y.Z` with the latest release tag from [Releases](https://github.com/github/spec-kit/releases) β€” keep the leading `v` (for example, `v0.12.11`, not `0.12.11`): ```bash uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z ``` Prefer installing from PyPI? The `specify-cli` package is also published there: ```bash uv tool install specify-cli ``` See the [Installation Guide](./docs/installation.md) for alternative methods, verification, upgrade, and troubleshooting. ### 2. Initialize a project ```bash 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](./docs/upgrade.md) for detailed scenarios and customization options. ```bash # 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 ` 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 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. ```bash /speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements ``` ### 4. Create the spec Use the **`/speckit.specify`** command to describe what you want to build. Focus on the **what** and **why**, not the tech stack. ```bash /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 Use the **`/speckit.plan`** command to provide your tech stack and architecture choices. ```bash /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 Use **`/speckit.tasks`** to create an actionable task list from your implementation plan. ```bash /speckit.tasks ``` ### 7. Execute implementation Use **`/speckit.implement`** to execute all tasks and build your feature according to the plan. ```bash /speckit.implement ``` For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md). ## πŸ“½οΈ Video Overview Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)! [](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) ## 🌍 Community Explore community-contributed resources on the [Spec Kit docs site](https://github.github.io/spec-kit/): - [Extensions](https://github.github.io/spec-kit/community/extensions.html) β€” commands, hooks, and capabilities - [Presets](https://github.github.io/spec-kit/community/presets.html) β€” template and terminology overrides - [Bundles](https://github.github.io/spec-kit/community/bundles.html) β€” role and team stacks composed from existing components - [Walkthroughs](https://github.github.io/spec-kit/community/walkthroughs.html) β€” end-to-end SDD scenarios - [Friends](https://github.github.io/spec-kit/community/friends.html) β€” 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](extensions/EXTENSION-PUBLISHING-GUIDE.md), the [Presets Publishing Guide](presets/PUBLISHING.md), or the [Community Bundles guide](docs/community/bundles.md). ## πŸ€– Supported AI Coding Agent Integrations 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](https://github.github.io/spec-kit/reference/integrations.html) guide. Run `specify integration list` to see all available integrations in your installed version. ## Available Slash Commands 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 --integration-options="--skills"` installs agent skills instead of slash-command prompt files. ### Core Commands Essential commands for the Spec-Driven Development workflow: | Command | Agent Skill | Description | | ------------------------ | ---------------------- | -------------------------------------------------------------------------- | | `/speckit.constitution` | `speckit-constitution` | Create or update project governing principles and development guidelines | | `/speckit.specify` | `speckit-specify` | Define what you want to build (requirements and user stories) | | `/speckit.plan` | `speckit-plan` | Create technical implementation plans with your chosen tech stack | | `/speckit.tasks` | `speckit-tasks` | Generate actionable task lists for implementation | | `/speckit.taskstoissues` | `speckit-taskstoissues`| Convert generated task lists into GitHub issues for tracking and execution | | `/speckit.implement` | `speckit-implement` | Execute all tasks to build the feature according to the plan | | `/speckit.converge` | `speckit-converge` | Assess the codebase against spec/plan/tasks and append remaining work as new tasks | ### Optional Commands Additional commands for enhanced quality and validation: | Command | Agent Skill | Description | | -------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `/speckit.clarify` | `speckit-clarify` | Clarify underspecified areas (recommended before `/speckit.plan`; formerly `/quizme`) | | `/speckit.analyze` | `speckit-analyze` | Cross-artifact consistency & coverage analysis (run after `/speckit.tasks`, before `/speckit.implement`) | | `/speckit.checklist` | `speckit-checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") | ## πŸ”§ Specify CLI Reference For full command details, options, and examples, see the [CLI Reference](https://github.github.io/spec-kit/reference/overview.html). ## 🧩 Making Spec Kit Your Own: Extensions & Presets Spec Kit can be tailored to your needs through two complementary systems β€” **extensions** and **presets** β€” plus project-local overrides for one-off adjustments: | Priority | Component Type | Location | | -------: | ------------------------------------------------- | -------------------------------- | | ⬆ 1 | Project-Local Overrides | `.specify/templates/overrides/` | | 2 | Presets β€” Customize core & extensions | `.specify/presets/templates/` | | 3 | Extensions β€” Add new capabilities | `.specify/extensions/templates/` | | ⬇ 4 | Spec Kit Core β€” Built-in SDD commands & templates | `.specify/templates/` | - **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 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*. ```bash # Search available extensions specify extension search # Install an extension specify extension add ``` For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics. See the [Extensions reference](https://github.github.io/spec-kit/reference/extensions.html) for the full command guide. Browse the [community extensions](https://github.github.io/spec-kit/community/extensions.html) for what's available. ### Presets β€” Customize Existing Workflows 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. ```bash # 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](https://github.com/mnriem/spec-kit-pirate-speak-preset-demo) shows just how deep the customization can go. Multiple presets can be stacked with priority ordering. See the [Presets reference](https://github.github.io/spec-kit/reference/presets.html) for the full command guide, including resolution order and priority stacking. ## πŸ“¦ Bundles: Role-Based Setups 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. ```bash # Discover bundles in the active catalog stack specify bundle search [] # 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](https://github.com/github/spec-kit/issues/new?template=bundle_submission.yml) issue template so required component catalogs and install evidence can be reviewed: ```bash 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/`](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](https://github.github.io/spec-kit/community/walkthroughs.html). 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 | Goal | Use | | --- | --- | | Add a brand-new command or workflow | Extension | | Customize the format of specs, plans, or tasks | Preset | | Integrate an external tool or service | Extension | | Enforce organizational or regulatory standards | Preset | | Ship reusable domain-specific templates | Either β€” presets for template overrides, extensions for templates bundled with new commands | | Provision a complete role-based setup in one command | Bundle | ## πŸ“š Core Philosophy 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 | Phase | Focus | Key Activities | | ---------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **0-to-1 Development** ("Greenfield") | Generate from scratch |
  • Start with high-level requirements
  • Generate specifications
  • Plan implementation steps
  • Build production-ready applications
    • | | **Creative Exploration** | Parallel implementations |
  • Explore diverse solutions
  • Support multiple technology stacks & architectures
  • Experiment with UX patterns
    • | | **Iterative Enhancement** ("Brownfield") | Brownfield modernization |
  • Add features iteratively
  • Modernize legacy systems
  • Adapt processes
    • | 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](./docs/guides/evolving-specs.md) describes the recommended brownfield loop. ## 🎯 Experimental Goals Our research and experimentation focus on: ### Technology independence - 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 - Demonstrate mission-critical application development - Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) - Support enterprise design systems and compliance requirements ### User-centric development - Build applications for different user cohorts and preferences - Support various development approaches (from vibe-coding to AI-native development) ### Creative & iterative processes - Validate the concept of parallel implementation exploration - Provide robust iterative feature development workflows - Extend processes to handle upgrades and modernization tasks ## πŸ”§ Prerequisites - **Linux/macOS/Windows** - [Supported](#-supported-ai-coding-agent-integrations) AI coding agent. - [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation - [Python 3.11+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) If you encounter issues with an agent, please open an issue so we can refine the integration. ## πŸ“– Learn More - **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process - **[Quick Start Guide](https://github.github.io/spec-kit/quickstart.html)** - Step-by-step implementation walkthrough --- ## πŸ’¬ Support For support, please open a [GitHub issue](https://github.com/github/spec-kit/issues/new). We welcome bug reports, feature requests, and questions about using Spec-Driven Development. ## πŸ™ Acknowledgements This project is heavily influenced by and based on the work and research of [John Lam](https://github.com/jflam). ## πŸ“„ License This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. --- ## File: docs/index.md # 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](concepts/sdd.md) (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](installation.md)  [Quick Start](quickstart.md) --- ### Spec-driven by default 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 β†’](quickstart.md) ### Use any coding agent 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 β†’](reference/integrations.md) ### Make it your own 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 β†’](reference/presets.md)   [Extensions β†’](reference/extensions.md)   [Workflows β†’](reference/workflows.md)   [Bundles β†’](reference/bundles.md) ### Integrate into your organization 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 β†’](install/air-gapped.md)   [Reference β†’](reference/overview.md) --- ## Built by the community **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](community/presets.md) Β· [Walkthroughs](community/walkthroughs.md) Β· [Friends](community/friends.md) --- ## Explore the docs **Getting Started** Install, configure, and run your first SDD workflow **Reference** Core commands, integrations, extensions, presets, and workflows **Community** Extensions, presets, walkthroughs, and friend projects **Development** Contribute to Spec Kit **What is SDD?** The philosophy behind Spec-Driven Development --- ```bash uv tool install specify-cli specify init my-project --integration copilot ``` Ready to start? Follow the [Quick Start Guide](quickstart.md). Last updated: July 16, 2026 --- ## File: docs/installation.md # Installation Guide ## Prerequisites - **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL) - AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [CodeBuddy CLI](https://www.codebuddy.cn/docs/cli/installation), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Pi Coding Agent](https://pi.dev), or [Oh My Pi](https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent) - [uv](https://docs.astral.sh/uv/) for package management (recommended) or [pipx](https://pipx.pypa.io/) for persistent installation - [Python 3.11+](https://www.python.org/downloads/) - [Git](https://git-scm.com/downloads) _(optional β€” required only when the git extension is enabled)_ ## Installation > [!IMPORTANT] > Spec Kit is distributed through two official channels, both published and maintained by the Spec Kit maintainers: the [github/spec-kit](https://github.com/github/spec-kit) GitHub repository (source installs) and the [`specify-cli`](https://pypi.org/project/specify-cli/) package on [PyPI](https://pypi.org/project/specify-cli/). 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) Install once and use everywhere. Replace `vX.Y.Z` with a release tag from [Releases](https://github.com/github/spec-kit/releases) β€” keep the leading `v` (for example, `v0.12.11`, not `0.12.11`): > [!NOTE] > The command below requires **[uv](https://docs.astral.sh/uv/)**. If you see `command not found: uv`, [install uv first](./install/uv.md). ```bash uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z ``` Then initialize a project: ```bash specify init --integration copilot ``` ### Install from PyPI Spec Kit is also published to PyPI as [`specify-cli`](https://pypi.org/project/specify-cli/), so you can install it with your preferred Python package manager without referencing the Git URL: ```bash # 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](install/pypi.md) for details, including how to upgrade and how to [install from a custom or private package index](install/pypi.md#install-from-a-custom-or-private-package-index). ### One-time Usage Run directly without installing β€” see the [One-time usage (uvx)](install/one-time.md) guide. ### Alternative Package Managers - **PyPI** β€” see the [PyPI installation guide](install/pypi.md) - **pipx** β€” see the [pipx installation guide](install/pipx.md) - **Enterprise / Air-Gapped** β€” see the [air-gapped installation guide](install/air-gapped.md) ### Specify Integration 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: ```bash 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) 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: ```bash specify init --script sh specify init --script ps specify init --script py ``` ### Ignore Agent Tools Check If you prefer to get the templates without checking for the right tools: ```bash specify init --integration claude --ignore-agent-tools ``` ## Verification After installation, run the following command as a local version/runtime check: ```bash 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](./upgrade.md). 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 ### Enterprise / Air-Gapped Installation If your environment blocks access to PyPI or GitHub, see the [Enterprise / Air-Gapped Installation](install/air-gapped.md) guide for step-by-step instructions on creating portable wheel bundles. ### Git Credential Manager on Linux If you're having issues with Git authentication on Linux, see the [Air-Gapped Installation guide](install/air-gapped.md#git-credential-manager-on-linux) for Git Credential Manager setup instructions. --- ## File: docs/local-development.md # 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 ```bash 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) You can execute the CLI via the module entrypoint without installing anything: ```bash # 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): ```bash python src/specify_cli/__init__.py init demo-project --script ps ``` ## 3. Use Editable Install (Isolated Environment) Create an isolated environment using `uv` so dependencies resolve exactly like end users get them: ```bash # 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) `uvx` can run from a local path (or a Git ref) to simulate user flows: ```bash uvx --from . specify init demo-uvx --integration copilot --ignore-agent-tools --script sh ``` You can also point uvx at a specific branch without merging: ```bash # 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) If you're in another directory, use an absolute path instead of `.`: ```bash 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: ```bash 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: ```bash specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; } # Then specify-dev --help ``` ## 5. Testing Script Permission Logic After running an `init`, check that shell scripts are executable on POSIX systems: ```bash 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 Use the integration scaffold command to create the initial Python package and test skeleton for a new built-in integration: ```bash 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 CI enforces `ruff check src tests` (see `.github/workflows/test.yml`), so run it locally before pushing: ```bash uvx ruff check src tests ``` You can also quickly sanity check importability: ```bash python -c "import specify_cli; print('Import OK')" ``` ## 8. Build a Wheel Locally (Optional) Validate packaging before publishing: ```bash uv build ls dist/ ``` Install the built artifact into a fresh throwaway environment if needed. ## 9. Using a Temporary Workspace When testing `init --here` in a dirty directory, create a temp workspace: ```bash 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 > **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 | Action | Command | |--------|---------| | Run CLI directly | `python -m src.specify_cli --help` | | Editable install | `uv pip install -e .` then `specify ...` | | Local uvx run (repo root) | `uvx --from . specify ...` | | Local uvx run (abs path) | `uvx --from /mnt/c/GitHub/spec-kit specify ...` | | Git branch uvx | `uvx --from git+URL@branch specify ...` | | Build wheel | `uv build` | ## 12. Cleaning Up Remove build artifacts / virtual env quickly: ```bash rm -rf .venv dist build *.egg-info ``` ## 13. Common Issues | Symptom | Fix | |---------|-----| | `ModuleNotFoundError: typer` | Run `uv pip install -e .` | | Scripts not executable (Linux) | Re-run init or `chmod +x scripts/*.sh` | | Git commands unavailable | Install the git extension with `specify extension add git` | | Wrong script type downloaded | Pass `--script sh`, `--script ps`, or `--script py` explicitly | | TLS errors on corporate network | Configure your environment's certificate store or proxy. The `--skip-tls` flag is deprecated and has no effect. | ## 14. Next Steps - 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 # 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 > [!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 **In your terminal**, install the CLI from PyPI (requires [uv](install/uv.md)), then initialize your project: ```bash 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](installation.md) for all supported methods. ### Step 1: `/speckit.constitution` β€” set the ground rules Establishes the project's guiding principles, which every later step is evaluated against. Run it once up front, passing your principles as arguments. ```text /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 Creates the feature specification from a natural-language description. Focus on the **what** and **why**, not the tech stack. ```text /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 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. ```text /speckit.clarify Focus on task card behavior β€” status changes, comment permissions, and user assignment. ``` ### Step 4: `/speckit.plan` β€” choose the tech stack Generates the design artifacts from the spec. This is where implementation detail belongs β€” provide your tech stack and architecture. ```text /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 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. ```text /speckit.checklist ``` ### Step 6: `/speckit.tasks` β€” break the work down Generates an actionable, dependency-ordered `tasks.md` from the design artifacts. ```text /speckit.tasks ``` ### Step 7: `/speckit.analyze` β€” check consistency 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. ```text /speckit.analyze ``` ### Step 8: `/speckit.implement` β€” build it 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. ```text /speckit.implement ``` ### Step 9: `/speckit.converge` β€” verify completeness 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. ```text /speckit.converge ``` > [!TIP] > For a full reference on each command β€” arguments, output, phased implementation, and how they interact β€” see [Agentic SDD](reference/agentic-sdd.md). ## Key Principles - **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 - See the [Agentic SDD](reference/agentic-sdd.md) reference for full detail on every command - Read the [complete methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md) for in-depth guidance - Compare the [core templates](https://github.com/github/spec-kit/tree/main/templates) with [community walkthroughs](community/walkthroughs.md) to see how Spec-Driven Development is used in real projects - Explore the [source code on GitHub](https://github.com/github/spec-kit) --- ## File: docs/README.md # Documentation This folder contains the documentation source files for Spec Kit, built using [DocFX](https://dotnet.github.io/docfx/). ## Building Locally To build the documentation locally: 1. Install DocFX: ```bash dotnet tool install -g docfx ``` 2. Build the documentation: ```bash cd docs docfx docfx.json --serve ``` 3. Open your browser to `http://localhost:8080` to view the documentation. ## Structure - `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 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 # 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 | What to Upgrade | Command | When to Use | |----------------|---------|-------------| | **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. | | **CLI Tool β€” pin a version** | `specify self upgrade --tag vX.Y.Z[suffix]` | Upgrade to a specific release tag instead of the latest stable. Suffixes are limited to dev, alpha/beta/rc, and/or build metadata forms. | | **CLI Tool β€” manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. | | **CLI Tool β€” manual fallback (pipx)** | `pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z` | Same as above, for pipx installs. | | **Project Files** | Run `specify integration upgrade `, then `specify extension update` | Refresh installed integration files and extensions in your project | | **Both** | Run CLI upgrade, then project update | Recommended for major version updates | --- ## Part 1: Upgrade the CLI Tool The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes. ### Recommended: `specify self upgrade` The CLI ships with two self-management commands that handle the common case automatically: ```bash # 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 ` 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` Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag): ```bash uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z ``` ### If you use one-shot `uvx` commands Specify the desired release tag: ```bash uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z 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` Upgrade to a specific release: ```bash pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z ``` ### Verify the upgrade ```bash # 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 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? 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? 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 Run this inside your project directory: ```bash 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 Run this inside your project directory: ```bash specify integration upgrade ``` Replace `` 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:** ```bash specify integration upgrade claude specify integration upgrade codex ``` See the [integration reference](reference/integrations.md#upgrade-an-integration) for options such as `--script`, `--integration-options`, and `--force`. ### 3. Update installed extensions Run: ```bash specify extension update ``` With no extension argument, this updates all installed extensions. Use `specify extension update ` to update only one extension. See the [extensions reference](reference/extensions.md#update-extensions) for details. ### Fallback: re-run init If a project predates manifests, has missing integration metadata, or needs a broader recovery, you can still re-run init: ```bash specify init --here --force --integration ``` 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 ### 1. Constitution file and memory customizations `specify integration upgrade ` does not update `.specify/memory/constitution.md`. The fallback `specify init --here --force --integration ` 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 `specify integration upgrade ` 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: ```bash # 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) 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:** ```bash # 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 The `/constitution` command ([#3790](https://github.com/github/spec-kit/pull/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 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? **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 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: ```text ## 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) If your team treats the materialized templates as **reviewed, committed artifacts** and wants `/constitution` to keep propagating, install the bundled **`constitution-sync`** preset: ```bash 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 ### Scenario 1: "I just want new slash commands" ```bash # 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 specify extension update ``` ### Scenario 2: "I customized templates and constitution" ```bash # 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 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" This happens with IDE-based agents (Kilo Code, Cline, etc.). ```bash # 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" The git extension is now opt-in, so upgrades do not install it unless you add it explicitly. ```bash # Upgrade CLI specify self upgrade # Refresh integration files and installed extensions specify integration upgrade 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: ```bash 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 # 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 ### "Slash commands not showing up after upgrade" **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 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?" 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: ```bash # 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 ` 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" **Full warning message:** ```text 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 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" If a command behaves like an older Spec Kit version, first ask the CLI itself: ```bash # 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: ```bash # 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: ```bash 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?" **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 ` 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 # 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 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 After upgrading: - **Test new slash commands:** Run `/speckit.constitution` or another command to verify everything works - **Review release notes:** Check [GitHub Releases](https://github.com/github/spec-kit/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](https://github.github.io/spec-kit/) for updated guides ## 2. Official Technical Reference & Guides (github/docs) # 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](https://docs.github.com/en/contributing). ## Quick links by contributor type * **Hubbers (GitHub employees):** See [CONTRIBUTING.md](https://github.com/github/docs-content/blob/main/CONTRIBUTING.md) in the `docs-content` repository for GitHub-specific processes. * **Open source contributors:** See [CONTRIBUTING.md](https://github.com/github/docs/blob/main/.github/CONTRIBUTING.md) in the `docs` repository for a quick-start summary. ## How we sync changes across Docs repositories 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 Here are some resources to help you get started with open source contributions: * [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) * [Set up Git](https://docs.github.com/en/get-started/git-basics/set-up-git) * [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) * [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) ## License This project is dual-licensed under: * **Creative Commons Attribution 4.0** - for documentation and content in the assets, content, and data folders (see [LICENSE](LICENSE)) * **MIT License** - for code (see [LICENSE-CODE](LICENSE-CODE))