Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: consolidate integration documentation into docs/integrations.md (#2241)

Manfred Riem530d1ce514be
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4ce19657e..c44063b16 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,7 +11,7 @@ These are one time installations required to be able to test your changes locall
1. Install [Python 3.11+](https://www.python.org/downloads/)
1. Install [uv](https://docs.astral.sh/uv/) for package management
1. Install [Git](https://git-scm.com/downloads)
-1. Have an [AI coding agent available](README.md#-supported-ai-agents)
+1. Have an [AI coding agent available](README.md#-supported-ai-coding-agent-integrations)
<details>
<summary><b>πŸ’‘ Hint if you are using <code>VSCode</code> or <code>GitHub Codespaces</code> as your IDE</b></summary>
diff --git a/README.md b/README.md
index b48c82949..101ffe555 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@
- [🎨 Community Presets](#-community-presets)
- [🚢 Community Walkthroughs](#-community-walkthroughs)
- [πŸ› οΈ Community Friends](#️-community-friends)
-- [πŸ€– Supported AI Agents](#-supported-ai-agents)
+- [πŸ€– 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)
- [πŸ“š Core Philosophy](#-core-philosophy)
@@ -314,38 +314,11 @@ Community projects that extend, visualize, or build on Spec Kit:
- **[SpecKit Companion](https://marketplace.visualstudio.com/items?itemName=alfredoperez.speckit-companion)** β€” A VS Code extension that brings a visual GUI to Spec Kit. Browse specs in a rich markdown viewer with clickable file references, create specifications with image attachments, comment and refine each step inline (GitHub-style review), track your progress through the SDD workflow with a visual phase stepper, and manage steering documents like constitutions and templates.
-## πŸ€– Supported AI Agents
-| Agent | Support | Notes |
-| ------------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| [Qoder CLI](https://qoder.com/cli) | βœ… | |
-| [Kiro CLI](https://kiro.dev/docs/cli/) | βœ… | Use `--ai kiro-cli` (alias: `--ai kiro`) |
-| [Amp](https://ampcode.com/) | βœ… | |
-| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | βœ… | |
-| [Claude Code](https://www.anthropic.com/claude-code) | βœ… | Installs skills in `.claude/skills`; invoke spec-kit as `/speckit-constitution`, `/speckit-plan`, etc. |
-| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | βœ… | |
-| [Codex CLI](https://github.com/openai/codex) | βœ… | Requires `--ai-skills`. Codex recommends [skills](https://developers.openai.com/codex/skills) and treats [custom prompts](https://developers.openai.com/codex/custom-prompts) as deprecated. Spec-kit installs Codex skills into `.agents/skills` and invokes them as `$speckit-<command>`. |
-| [Cursor](https://cursor.sh/) | βœ… | |
-| [Forge](https://forgecode.dev/) | βœ… | CLI tool: `forge` |
-| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | βœ… | |
-| [Goose](https://block.github.io/goose/) | βœ… | Uses YAML recipe format in `.goose/recipes/` with slash command support |
-| [GitHub Copilot](https://code.visualstudio.com/) | βœ… | |
-| [IBM Bob](https://www.ibm.com/products/bob) | βœ… | IDE-based agent with slash command support |
-| [Jules](https://jules.google.com/) | βœ… | |
-| [Kilo Code](https://github.com/Kilo-Org/kilocode) | βœ… | |
-| [opencode](https://opencode.ai/) | βœ… | |
-| [Pi Coding Agent](https://pi.dev) | βœ… | Pi doesn't have MCP support out of the box, so `taskstoissues` won't work as intended. MCP support can be added via [extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions) |
-| [Qwen Code](https://github.com/QwenLM/qwen-code) | βœ… | |
-| [Roo Code](https://roocode.com/) | βœ… | |
-| [SHAI (OVHcloud)](https://github.com/ovh/shai) | βœ… | |
-| [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli) | βœ… | |
-| [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | βœ… | |
-| [Kimi Code](https://code.kimi.com/) | βœ… | |
-| [iFlow CLI](https://docs.iflow.cn/en/cli/quickstart) | βœ… | |
-| [Windsurf](https://windsurf.com/) | βœ… | |
-| [Junie](https://junie.jetbrains.com/) | βœ… | |
-| [Antigravity (agy)](https://antigravity.google/) | βœ… | Requires `--ai-skills` |
-| [Trae](https://www.trae.ai/) | βœ… | |
-| Generic | βœ… | Bring your own agent β€” use `--ai generic --ai-commands-dir <path>` for unsupported agents |
+## πŸ€– 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](docs/integrations.md) guide.
+
+Run `specify integration list` to see all available integrations in your installed version.
## Available Slash Commands
@@ -611,7 +584,7 @@ Our research and experimentation focus on:
## πŸ”§ Prerequisites
- **Linux/macOS/Windows**
-- [Supported](#-supported-ai-agents) AI coding agent.
+- [Supported](#-supported-ai-coding-agent-integrations) AI coding agent.
- [uv](https://docs.astral.sh/uv/) for package management
- [Python 3.11+](https://www.python.org/downloads/)
- [Git](https://git-scm.com/downloads)
diff --git a/docs/integrations.md b/docs/integrations.md
new file mode 100644
index 000000000..35a0b09e1
--- /dev/null
+++ b/docs/integrations.md
@@ -0,0 +1,118 @@
+# Supported AI Coding Agent Integrations
+
+The Specify CLI supports a wide range of AI coding agents. When you run `specify init`, the CLI sets up the appropriate command files, context rules, and directory structures for your chosen AI coding agent β€” so you can start using Spec-Driven Development immediately, regardless of which tool you prefer.
+
+## Supported AI Coding Agents
+
+| Agent | Key | Notes |
+| ------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| [Amp](https://ampcode.com/) | `amp` | |
+| [Antigravity (agy)](https://antigravity.google/) | `agy` | Skills-based integration; skills are installed automatically |
+| [Auggie CLI](https://docs.augmentcode.com/cli/overview) | `auggie` | |
+| [Claude Code](https://www.anthropic.com/claude-code) | `claude` | Skills-based integration; installs skills in `.claude/skills` |
+| [CodeBuddy CLI](https://www.codebuddy.ai/cli) | `codebuddy` | |
+| [Codex CLI](https://github.com/openai/codex) | `codex` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `$speckit-<command>` |
+| [Cursor](https://cursor.sh/) | `cursor-agent` | |
+| [Forge](https://forgecode.dev/) | `forge` | |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | |
+| [GitHub Copilot](https://code.visualstudio.com/) | `copilot` | |
+| [Goose](https://block.github.io/goose/) | `goose` | Uses YAML recipe format in `.goose/recipes/` |
+| [IBM Bob](https://www.ibm.com/products/bob) | `bob` | IDE-based agent |
+| [iFlow CLI](https://docs.iflow.cn/en/cli/quickstart) | `iflow` | |
+| [Junie](https://junie.jetbrains.com/) | `junie` | |
+| [Kilo Code](https://github.com/Kilo-Org/kilocode) | `kilocode` | |
+| [Kimi Code](https://code.kimi.com/) | `kimi` | Skills-based integration; supports `--migrate-legacy` for dotted→hyphenated directory migration |
+| [Kiro CLI](https://kiro.dev/docs/cli/) | `kiro-cli` | Alias: `--integration kiro` |
+| [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | `vibe` | |
+| [opencode](https://opencode.ai/) | `opencode` | |
+| [Pi Coding Agent](https://pi.dev) | `pi` | Pi doesn't have MCP support out of the box, so `taskstoissues` won't work as intended. MCP support can be added via [extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions) |
+| [Qoder CLI](https://qoder.com/cli) | `qodercli` | |
+| [Qwen Code](https://github.com/QwenLM/qwen-code) | `qwen` | |
+| [Roo Code](https://roocode.com/) | `roo` | |
+| [SHAI (OVHcloud)](https://github.com/ovh/shai) | `shai` | |
+| [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli) | `tabnine` | |
+| [Trae](https://www.trae.ai/) | `trae` | Skills-based integration; skills are installed automatically |
+| [Windsurf](https://windsurf.com/) | `windsurf` | |
+| Generic | `generic` | Bring your own agent β€” use `--integration generic --integration-options="--commands-dir <path>"` for AI coding agents not listed above |
+
+## List Available Integrations
+
+```bash
+specify integration list
+```
+
+Shows all available integrations, which one is currently installed, and whether each requires a CLI tool or is IDE-based.
+
+## Install an Integration
+
+```bash
+specify integration install <key>
+```
+
+| Option | Description |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) |
+| `--integration-options` | Integration-specific options (e.g. `--integration-options="--commands-dir .myagent/cmds"`) |
+
+Installs the specified integration into the current project. Fails if another integration is already installed β€” use `switch` instead. If the installation fails partway through, it automatically rolls back to a clean state.
+
+> **Note:** All integration management commands require a project already initialized with `specify init`. To start a new project with a specific agent, use `specify init <project> --integration <key>` instead.
+
+## Uninstall an Integration
+
+```bash
+specify integration uninstall [<key>]
+```
+
+| Option | Description |
+| --------- | --------------------------------------------------- |
+| `--force` | Remove files even if they have been modified |
+
+Uninstalls the current integration (or the specified one). Spec Kit tracks every file created during install along with a SHA-256 hash of the original content:
+
+- **Unmodified files** are removed automatically.
+- **Modified files** (where you've made manual edits) are preserved so your customizations are not lost.
+- Use `--force` to remove all integration files regardless of modifications.
+
+## Switch to a Different Integration
+
+```bash
+specify integration switch <key>
+```
+
+| Option | Description |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) |
+| `--force` | Force removal of modified files during uninstall |
+| `--integration-options` | Options for the target integration |
+
+Equivalent to running `uninstall` followed by `install` in a single step.
+
+## Upgrade an Integration
+
+```bash
+specify integration upgrade [<key>]
+```
+
+| Option | Description |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `--force` | Overwrite files even if they have been modified |
+| `--script sh\|ps` | Script type: `sh` (bash/zsh) or `ps` (PowerShell) |
+| `--integration-options` | Options for the integration |
+
+Reinstalls the current integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the currently installed integration; if a key is provided, it must match the installed one β€” otherwise the command fails and suggests using `switch` instead. Detects locally modified files and blocks the upgrade unless `--force` is used. Stale files from the previous install that are no longer needed are removed automatically.
+
+## Integration-Specific Options
+
+Some integrations accept additional options via `--integration-options`:
+
+| Integration | Option | Description |
+| ----------- | ------------------- | -------------------------------------------------------------- |
+| `generic` | `--commands-dir` | Required. Directory for command files |
+| `kimi` | `--migrate-legacy` | Migrate legacy dotted skill directories to hyphenated format |
+
+Example:
+
+```bash
+specify integration install generic --integration-options="--commands-dir .myagent/cmds"
+```
diff --git a/docs/toc.yml b/docs/toc.yml
index 18650cb57..53d3c1088 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -12,6 +12,12 @@
- name: Upgrade
href: upgrade.md
+# Reference
+- name: Reference
+ items:
+ - name: Integrations
+ href: integrations.md
+
# Development workflows
- name: Development
items:
diff --git a/docs/upgrade.md b/docs/upgrade.md
index aecbb7879..e08c0b93e 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -76,7 +76,7 @@ Run this inside your project directory:
specify init --here --force --ai <your-agent>
```
-Replace `<your-agent>` with your AI assistant. Refer to this list of [Supported AI Agents](../README.md#-supported-ai-agents)
+Replace `<your-agent>` with your AI coding agent. Refer to this list of [Supported AI Coding Agent Integrations](integrations.md)
**Example:**
@@ -401,7 +401,7 @@ The `specify` CLI tool is used for:
- **Upgrades:** `specify init --here --force` to update templates and commands
- **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/`, etc.). Your AI assistant reads these command files directlyβ€”no need to run `specify` again.
+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/`, etc.). Your AI coding agent reads these command files directlyβ€”no need to run `specify` again.
**If your agent isn't recognizing slash commands:**