From 2f42be567389f5a781dddccf1b327d512b885909 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Thu, 16 Apr 2026 11:26:47 -0500 Subject: [PATCH] docs: consolidate integration documentation into docs/integrations.md - New docs/integrations.md: canonical reference for supported agents table (with keys), list/install/uninstall/switch/upgrade commands, file preservation behavior, and integration-specific options - README.md: replace inline agents table with summary + link to new page; normalize heading to 'Supported AI Coding Agent Integrations' - docs/toc.yml: add top-level 'Reference' section with Integrations page - docs/upgrade.md: fix broken cross-reference, update terminology - CONTRIBUTING.md: update anchor link to new heading --- CONTRIBUTING.md | 2 +- README.md | 41 +++------------ docs/integrations.md | 118 +++++++++++++++++++++++++++++++++++++++++++ docs/toc.yml | 6 +++ docs/upgrade.md | 4 +- 5 files changed, 134 insertions(+), 37 deletions(-) create mode 100644 docs/integrations.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ce19657ea..c44063b16f 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)
πŸ’‘ Hint if you are using VSCode or GitHub Codespaces as your IDE diff --git a/README.md b/README.md index b48c829491..101ffe5553 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-`. | -| [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 ` 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 0000000000..35a0b09e19 --- /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-` | +| [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 "` 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 +``` + +| 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 --integration ` instead. + +## Uninstall an Integration + +```bash +specify integration uninstall [] +``` + +| 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 +``` + +| 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 [] +``` + +| 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 18650cb571..53d3c10884 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 aecbb7879b..e08c0b93ed 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -76,7 +76,7 @@ Run this inside your project directory: specify init --here --force --ai ``` -Replace `` with your AI assistant. Refer to this list of [Supported AI Agents](../README.md#-supported-ai-agents) +Replace `` 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:**