π« 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.mdindex 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 locall1. Install [Python 3.11+](https://www.python.org/downloads/)1. Install [uv](https://docs.astral.sh/uv/) for package management1. 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.mdindex 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.mdnew file mode 100644index 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.ymlindex 18650cb57..53d3c1088 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -12,6 +12,12 @@- name: Upgradehref: upgrade.md+# Reference+- name: Reference+ items:+ - name: Integrations+ href: integrations.md+# Development workflows- name: Developmentitems:diff --git a/docs/upgrade.md b/docs/upgrade.mdindex 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:**