From d09a16569d34b8d33898d0305fc16a9e79ce3031 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 20 Oct 2026 13:25:17 -0500 Subject: [PATCH 1/3] docs: organize agent-specific integration documentation Consolidate integration documentation under docs/integrations with per-agent guides, shared references, updated navigation, and a concise mixed-agent team scenario. Require agent-specific documentation updates alongside user-visible integration changes. Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 4 +- README.ja.md | 4 +- README.ko.md | 4 +- README.md | 10 +- README.zh-CN.md | 4 +- design/integration.md | 28 +- docs/README.md | 5 + docs/docfx.json | 1 + docs/guides/assessment.md | 2 +- docs/guides/bugfix.md | 2 +- docs/guides/customization.md | 5 +- docs/guides/existing-projects.md | 2 +- docs/index.md | 2 +- docs/installation.md | 4 +- docs/integrations/agy.md | 42 ++ docs/integrations/alquimia.md | 33 + docs/integrations/amp.md | 31 + docs/integrations/auggie.md | 30 + docs/integrations/bob.md | 59 ++ .../README.md => docs/integrations/catalog.md | 79 +-- docs/integrations/claude.md | 71 +++ docs/integrations/cli.md | 539 ++++++++++++++++ docs/integrations/cline.md | 34 + docs/integrations/codebuddy.md | 30 + docs/integrations/codex.md | 38 ++ docs/integrations/command-code.md | 32 + docs/integrations/contributing.md | 123 ++++ docs/integrations/copilot.md | 72 +++ docs/integrations/cursor-agent.md | 37 ++ docs/integrations/devin.md | 35 ++ docs/integrations/docker-agent.md | 65 ++ docs/integrations/droid.md | 35 ++ docs/integrations/dsh.md | 31 + docs/integrations/firebender.md | 30 + docs/integrations/forge.md | 36 ++ docs/integrations/gemini.md | 34 + docs/integrations/generic.md | 57 ++ docs/integrations/goose.md | 38 ++ docs/integrations/grok.md | 31 + docs/integrations/hermes.md | 47 ++ docs/integrations/index.md | 146 +++++ docs/integrations/junie.md | 34 + docs/integrations/kilocode.md | 38 ++ docs/integrations/kimi.md | 61 ++ docs/integrations/kiro-cli.md | 39 ++ docs/integrations/lingma.md | 32 + docs/integrations/mcode.md | 37 ++ docs/integrations/muse.md | 34 + docs/integrations/none.md | 43 ++ docs/integrations/omp.md | 31 + docs/integrations/opencode.md | 39 ++ docs/integrations/pi.md | 35 ++ docs/integrations/qodercli.md | 36 ++ docs/integrations/qwen.md | 33 + docs/integrations/rovodev.md | 39 ++ docs/integrations/shai.md | 33 + docs/integrations/tabnine.md | 34 + docs/integrations/trae.md | 32 + docs/integrations/vibe.md | 43 ++ docs/integrations/zcode.md | 33 + docs/integrations/zed.md | 32 + docs/local-development.md | 23 +- docs/quickstart.md | 2 +- docs/reference/agentic-assessment.md | 2 +- docs/reference/agentic-bugfix.md | 2 +- docs/reference/agentic-sdd.md | 2 +- docs/reference/catalogs.md | 6 +- docs/reference/core.md | 2 +- docs/reference/integrations.md | 582 ------------------ docs/reference/overview.md | 6 +- docs/toc.yml | 103 +++- docs/upgrade.md | 2 +- extensions/github/README.md | 4 +- integrations/CONTRIBUTING.md | 191 ------ 74 files changed, 2687 insertions(+), 890 deletions(-) create mode 100644 docs/integrations/agy.md create mode 100644 docs/integrations/alquimia.md create mode 100644 docs/integrations/amp.md create mode 100644 docs/integrations/auggie.md create mode 100644 docs/integrations/bob.md rename integrations/README.md => docs/integrations/catalog.md (64%) create mode 100644 docs/integrations/claude.md create mode 100644 docs/integrations/cli.md create mode 100644 docs/integrations/cline.md create mode 100644 docs/integrations/codebuddy.md create mode 100644 docs/integrations/codex.md create mode 100644 docs/integrations/command-code.md create mode 100644 docs/integrations/contributing.md create mode 100644 docs/integrations/copilot.md create mode 100644 docs/integrations/cursor-agent.md create mode 100644 docs/integrations/devin.md create mode 100644 docs/integrations/docker-agent.md create mode 100644 docs/integrations/droid.md create mode 100644 docs/integrations/dsh.md create mode 100644 docs/integrations/firebender.md create mode 100644 docs/integrations/forge.md create mode 100644 docs/integrations/gemini.md create mode 100644 docs/integrations/generic.md create mode 100644 docs/integrations/goose.md create mode 100644 docs/integrations/grok.md create mode 100644 docs/integrations/hermes.md create mode 100644 docs/integrations/index.md create mode 100644 docs/integrations/junie.md create mode 100644 docs/integrations/kilocode.md create mode 100644 docs/integrations/kimi.md create mode 100644 docs/integrations/kiro-cli.md create mode 100644 docs/integrations/lingma.md create mode 100644 docs/integrations/mcode.md create mode 100644 docs/integrations/muse.md create mode 100644 docs/integrations/none.md create mode 100644 docs/integrations/omp.md create mode 100644 docs/integrations/opencode.md create mode 100644 docs/integrations/pi.md create mode 100644 docs/integrations/qodercli.md create mode 100644 docs/integrations/qwen.md create mode 100644 docs/integrations/rovodev.md create mode 100644 docs/integrations/shai.md create mode 100644 docs/integrations/tabnine.md create mode 100644 docs/integrations/trae.md create mode 100644 docs/integrations/vibe.md create mode 100644 docs/integrations/zcode.md create mode 100644 docs/integrations/zed.md delete mode 100644 docs/reference/integrations.md delete mode 100644 integrations/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 346fb24f35..912152f3cf 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](https://github.github.io/spec-kit/reference/integrations.html) +1. Have an [AI coding agent available](https://github.github.io/spec-kit/integrations/index.html)
💡 Hint if you are using VSCode or GitHub Codespaces as your IDE @@ -172,7 +172,7 @@ its pinned archive URL and preferably its SHA-256 in a catalog. Registering a catalog only enables discovery/download; importing executable adapter code requires the user's trust decision and an install-enabled source. Follow the [integration API and lifecycle design](design/integration.md#external-adapter-package-contract) -and [integration catalog contribution guide](integrations/CONTRIBUTING.md). +and [integration catalog contribution guide](docs/integrations/contributing.md). Add public-path positive and negative tests rather than injecting test classes directly into the registry; include fresh-process loading and rollback evidence. diff --git a/README.ja.md b/README.ja.md index dcefab4d04..798a3cc19d 100644 --- a/README.ja.md +++ b/README.ja.md @@ -46,11 +46,11 @@ cd my-project -この例では **GitHub Copilotのデフォルトのスキルモード** を使用しています。他の対応エージェントを使う場合は、`copilot` をお使いのエージェントの[連携キー](https://github.github.io/spec-kit/reference/integrations.html)に置き換えてください。 +この例では **GitHub Copilotのデフォルトのスキルモード** を使用しています。他の対応エージェントを使う場合は、`copilot` をお使いのエージェントの[連携キー](https://github.github.io/spec-kit/integrations/index.html)に置き換えてください。 すでにコードがありますか？[既存プロジェクト向けガイド](https://github.github.io/spec-kit/guides/existing-projects.html)を参照してください。バージョン固定でのインストール、その他のインストーラー、CI、トラブルシューティングについては[インストールガイド](https://github.github.io/spec-kit/installation.html)を、既存のインストールを更新する場合は[アップグレードガイド](https://github.github.io/spec-kit/upgrade.html)を参照してください。 -ここから**プロジェクトディレクトリでコーディングエージェントを起動し**、下記のいずれかのプロセスを選んでください。各 `/speckit-*` **スキルはエージェントのチャット内で**、1つずつ呼び出し、結果を確認してから次に進んでください。これらはターミナルコマンドではなく、エージェントのスキルです。エージェントやモードによっては、[異なる呼び出し方](https://github.github.io/spec-kit/reference/integrations.html#command-invocation)を使う場合があります。 +ここから**プロジェクトディレクトリでコーディングエージェントを起動し**、下記のいずれかのプロセスを選んでください。各 `/speckit-*` **スキルはエージェントのチャット内で**、1つずつ呼び出し、結果を確認してから次に進んでください。これらはターミナルコマンドではなく、エージェントのスキルです。エージェントやモードによっては、[異なる呼び出し方](https://github.github.io/spec-kit/integrations/cli.html#command-invocation)を使う場合があります。 diff --git a/README.ko.md b/README.ko.md index c83658e705..f2969eeb5e 100644 --- a/README.ko.md +++ b/README.ko.md @@ -51,7 +51,7 @@ cd my-project 예시는 **GitHub Copilot의 기본 스킬 모드**를 기준으로 합니다. 지원되는 다른 에이전트를 쓰려면 -`copilot`을 해당 에이전트의 [통합 키](https://github.github.io/spec-kit/reference/integrations.html)로 바꾸세요. +`copilot`을 해당 에이전트의 [통합 키](https://github.github.io/spec-kit/integrations/index.html)로 바꾸세요. 이미 코드가 있나요? [기존 프로젝트 가이드](https://github.github.io/spec-kit/guides/existing-projects.html)를 따르세요. 특정 버전 고정, 다른 설치 방법, CI, 문제 해결은 @@ -61,7 +61,7 @@ cd my-project 이제 **프로젝트 디렉터리에서 코딩 에이전트를 실행**하고 아래 프로세스 중 하나를 고르세요. 각 `/speckit-*` **스킬은 에이전트 채팅에서** 한 번에 하나씩 호출하고, 결과를 검토한 뒤 다음으로 넘어가세요. 이들은 터미널 명령어가 아니라 에이전트 스킬입니다. 에이전트나 모드에 따라 -[호출 문법이 다를 수 있습니다](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). +[호출 문법이 다를 수 있습니다](https://github.github.io/spec-kit/integrations/cli.html#command-invocation). diff --git a/README.md b/README.md index 3f50156526..0d6d47f276 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Spec Kit combines ready-to-use processes with composable mechanisms: | Capability | Spec Kit mechanism | | --- | --- | -| Connect to or switch between coding agents | [Integration](https://github.github.io/spec-kit/reference/integrations.html) | +| Connect to or switch between coding agents | [Integration](https://github.github.io/spec-kit/integrations/index.html) | | Add a command, quality gate, or complete process | [Extension](https://github.github.io/spec-kit/reference/extensions.html) | | Connect a process to an external tool or service | [Extension](https://github.github.io/spec-kit/reference/extensions.html) | | React to coding-agent lifecycle events | [Extension runtime event](https://github.github.io/spec-kit/reference/extensions.html#extension-runtime-events) | @@ -91,7 +91,7 @@ For other setups: - [Installation](https://github.github.io/spec-kit/installation.html) for pinned releases, other installers, CI, and troubleshooting. - [Existing projects](https://github.github.io/spec-kit/guides/existing-projects.html) to start with code you already have. -- [Other agents](https://github.github.io/spec-kit/reference/integrations.html) for integration keys and [invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). +- [Other agents](https://github.github.io/spec-kit/integrations/index.html) for integration keys and [invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation). - [Upgrade](https://github.github.io/spec-kit/upgrade.html) to update an existing installation. @@ -107,7 +107,7 @@ repeat the remaining steps for each feature. Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing. This example uses GitHub Copilot's default skills syntax. For another agent, -use its [equivalent invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). +use its [equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation). ```text /speckit-constitution Create principles focused on code quality, testing, and maintainability. @@ -142,7 +142,7 @@ Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing. This example uses GitHub Copilot's default skills syntax. For another agent, -use its [equivalent invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). +use its [equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation). ```text /speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash @@ -174,7 +174,7 @@ Run these skills in your agent's chat, not your terminal, one at a time, reviewing each result before continuing. This example uses GitHub Copilot's default skills syntax. For another agent, -use its [equivalent invocation syntax](https://github.github.io/spec-kit/reference/integrations.html#command-invocation). +use its [equivalent invocation syntax](https://github.github.io/spec-kit/integrations/cli.html#command-invocation). ```text /speckit-assess-intake "Let users work offline and sync when they reconnect." slug=offline-mode diff --git a/README.zh-CN.md b/README.zh-CN.md index 35bdc34194..cda32cb4be 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -55,7 +55,7 @@ CLI 只需安装一次，项目只需初始化一次；以下三种流程共用 示例采用 **GitHub Copilot 默认的技能（skills）模式**。 如需使用其他助手，将 `copilot` 替换为对应的 -[集成标识](https://github.github.io/spec-kit/reference/integrations.html)。 +[集成标识](https://github.github.io/spec-kit/integrations/index.html)。 已有代码？请参阅[现有项目指南](https://github.github.io/spec-kit/guides/existing-projects.html)。 锁定版本、其他安装方式、CI 与故障排查见[安装指南](https://github.github.io/spec-kit/installation.html)； @@ -63,7 +63,7 @@ CLI 只需安装一次，项目只需初始化一次；以下三种流程共用 现在，在**项目目录中启动编码助手**，选择以下一种流程。 在**助手的聊天界面中逐个调用 `/speckit-*` 技能**，检查结果后再继续。 -这些是助手技能，不是终端命令。其他助手或模式可能采用[不同的调用语法](https://github.github.io/spec-kit/reference/integrations.html#command-invocation)。 +这些是助手技能，不是终端命令。其他助手或模式可能采用[不同的调用语法](https://github.github.io/spec-kit/integrations/cli.html#command-invocation)。 diff --git a/design/integration.md b/design/integration.md index 02d83b9428..5f692c2410 100644 --- a/design/integration.md +++ b/design/integration.md @@ -1,6 +1,6 @@ # Agent Integration Design -Integrations adapt the shared Spec Kit workflows to an AI coding agent. Their +Integrations adapt the shared Spec Kit processes to an AI coding agent. Their **availability** (built-in, generic, or catalog-only) is separate from their **output format** (commands, recipes, skills, or a custom layout). The Python integration registry owns installation behavior; catalogs provide discovery, @@ -67,7 +67,7 @@ agent's configured root. `command_filename()` and `setup()` are override points when the native layout demands them. Keep mode selection, invocation spelling, and registration in sync. Agent-specific layouts and options belong in the integration code and -the [supported-integrations reference](../docs/reference/integrations.md). +the agent's [integration guide](../docs/integrations/index.md). Core templates that call scripts declare `sh`, `ps`, and `py` commands in `scripts:` frontmatter; template processing replaces `{SCRIPT}` with the @@ -368,8 +368,8 @@ warns that manual cleanup may be needed. A newly trusted replacement still renders its declared destination under normal `upgrade --force` semantics; old-only destinations are not deleted using unverified project metadata. -See the [catalog contract](../integrations/README.md) and -[user reference](../docs/reference/integrations.md) for public commands. +See the [catalog contract](../docs/integrations/catalog.md) and +[user reference](../docs/integrations/cli.md) for public commands. ## Ownership and lifecycle @@ -398,6 +398,11 @@ PR may also include registry wiring, catalog metadata, integration-specific tests, documentation, and agent-specific devcontainer tooling outside that package. File location alone does not determine whether a separate PR is needed. +Every user-visible, agent-specific integration change MUST update +`docs/integrations/.md` in the same change. Document behavior shared across +integrations in the [shared CLI reference](../docs/integrations/cli.md), +not in individual agent pages. + If delivery requires changes to shared runtime behavior, integration base classes, rendering, lifecycle management, CLI behavior, or core templates or scripts, it requires **at least two PRs**: a separate prerequisite PR for the @@ -413,17 +418,16 @@ they have merged. See the ## Adding an agent -1. Run `specify integration scaffold my-agent --type markdown` from this - repository (`toml`, `yaml`, and `skills` are also supported), or start with - a custom class only when necessary. -2. Review the generated `config` and `registrar_config`; register the class - alphabetically and add a matching entry to `integrations/catalog.json`. +1. Create the integration subpackage and class using the smallest matching + format base. Define `config` and `registrar_config` for the agent's actual + output layout. +2. Register the class alphabetically and add a matching entry to + `integrations/catalog.json`. 3. Add focused coverage in `tests/integrations/test_integration_.py` for metadata, generated output, installation, and uninstall (including preservation of edited files where applicable). 4. Exercise `specify init my-project --integration ` and the install/uninstall - lifecycle; update the [supported agents](../docs/reference/integrations.md) + lifecycle; update the [supported agents](../docs/integrations/index.md) and devcontainer setup if the agent needs additional tooling. -The scaffold creates a package and test skeleton, **not** registry or catalog -entries. Prefer existing bases and shared processing over copied setup loops. +Prefer existing bases and shared processing over copied setup loops. diff --git a/docs/README.md b/docs/README.md index cd5d6db910..2a6f109899 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,6 +33,11 @@ To build the documentation locally: - `guides/assessment.md` - Idea assessment walkthrough - `guides/customization.md` - Choosing and combining customization building blocks - `reference/catalogs.md` - Catalog discovery, trust, private sources, and precedence +- `integrations/index.md` - Integration directory and shared setup guidance +- `integrations/cli.md` - Shared integration management CLI reference +- `integrations/.md` - Agent-specific setup, invocation, options, and limitations +- `integrations/catalog.md` - Catalog schema and external adapter metadata +- `integrations/contributing.md` - Integration and catalog contribution guide - `reference/agentic-*.md` - Detailed process command references - `_site/` - Generated documentation output (ignored by git) diff --git a/docs/docfx.json b/docs/docfx.json index 77a7653dd7..69e0078e61 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -8,6 +8,7 @@ "community/*.md", "concepts/*.md", "guides/*.md", + "integrations/*.md", "reference/*.md", "install/*.md" ] diff --git a/docs/guides/assessment.md b/docs/guides/assessment.md index 171de767e7..c0dd50455b 100644 --- a/docs/guides/assessment.md +++ b/docs/guides/assessment.md @@ -22,7 +22,7 @@ specify extension add assess Then launch your coding agent in that directory. The examples below use GitHub Copilot's default skills mode (`--integration copilot`). Other agents use their own -[command invocation syntax](../reference/integrations.md#command-invocation). +[command invocation syntax](../integrations/cli.md#command-invocation). Invoke each `/speckit-assess-*` skill separately in your agent's chat, reviewing the artifact before moving on. These are agent skills, not terminal commands; the terminal command above only installs the extension. diff --git a/docs/guides/bugfix.md b/docs/guides/bugfix.md index b1f0effff3..9bb7655569 100644 --- a/docs/guides/bugfix.md +++ b/docs/guides/bugfix.md @@ -23,7 +23,7 @@ specify extension add bug Then launch your coding agent in that directory. The examples below use GitHub Copilot's default skills mode (`--integration copilot`). Other agents expose the same steps using their own -[command invocation syntax](../reference/integrations.md#command-invocation). +[command invocation syntax](../integrations/cli.md#command-invocation). Invoke each `/speckit-bug-*` skill separately in your agent's chat and review its output before continuing. These are agent skills, not terminal commands; the terminal command above only installs the extension. diff --git a/docs/guides/customization.md b/docs/guides/customization.md index 297143731f..f2ab8f53cd 100644 --- a/docs/guides/customization.md +++ b/docs/guides/customization.md @@ -21,8 +21,9 @@ organization, or bring a different process entirely. Integrations determine how commands and skills are delivered to your coding agent; they are distinct from extensions that connect to external tools or -services. See the [integration reference](../reference/integrations.md) for -supported agents, installation, and scaffolding a new adapter. +services. See the [integration guides](../integrations/index.md) for supported +agents and setup, or [contributing integrations](../integrations/contributing.md) +to develop an adapter. Workflow step packages extend the step types available to workflows. See [custom step packages](../reference/workflows.md#custom-step-packages) for diff --git a/docs/guides/existing-projects.md b/docs/guides/existing-projects.md index 9736557316..8fcd140e7c 100644 --- a/docs/guides/existing-projects.md +++ b/docs/guides/existing-projects.md @@ -9,7 +9,7 @@ and use the workflow for the next bounded change. Before initialization, commit or stash existing work and create a branch for the adoption. This makes every generated file visible in a normal code review. -Choose the [integration key](../reference/integrations.md) for the coding agent +Choose the [integration key](../integrations/index.md) for the coding agent you use. Then run the command from the repository root: ```bash diff --git a/docs/index.md b/docs/index.md index f3207ae3d1..9e07cf7da0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -57,7 +57,7 @@ Define what to build before building it. Rich templates, quality checklists, and 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 → +See all integrations → diff --git a/docs/installation.md b/docs/installation.md index 3abd5919a0..1226e01dc6 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -81,8 +81,8 @@ specify init --integration omp The README examples use GitHub Copilot's default skills mode. To use another supported agent, replace `copilot` with its -[integration key](reference/integrations.md). See -[Command Invocation](reference/integrations.md#command-invocation) for the +[integration key](integrations/index.md). See +[Command Invocation](integrations/cli.md#command-invocation) for the syntax used by each agent and mode. ### Specify Script Type (Shell, PowerShell, or Python) diff --git a/docs/integrations/agy.md b/docs/integrations/agy.md new file mode 100644 index 0000000000..8fb913c3b6 --- /dev/null +++ b/docs/integrations/agy.md @@ -0,0 +1,42 @@ +# Antigravity + +Install [Antigravity](https://antigravity.google/) before setup. +The integration key is `agy`. The skills layout requires Antigravity CLI +v1.0.0 or newer, or Antigravity IDE v2.0.0 or newer. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration agy +``` + +For an existing Spec Kit project, use `specify integration install agy`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.agents/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. +This directory is shared with other integrations, so do not assume their +generated skills can coexist without overlap. + +## Headless Permissions + +Automatic tool approval is disabled by default. In headless non-interactive +runs, explicitly enable `--dangerously-skip-permissions` by setting +`SPECKIT_AGY_ALLOW_ALL_TOOLS=1` or +`SPECKIT_INTEGRATION_AGY_ALLOW_ALL_TOOLS=1` only if you intend to authorize +tool actions without interactive approval. + +## Workflow Dispatch + +Workflow steps use `agy --print `. Spec Kit supplies `--add-dir` +with the project root so skills remain discoverable, forwards a configured +`--model`, and requests `--output-format json` for structured output. +There are no integration-specific setup options. diff --git a/docs/integrations/alquimia.md b/docs/integrations/alquimia.md new file mode 100644 index 0000000000..184a360c12 --- /dev/null +++ b/docs/integrations/alquimia.md @@ -0,0 +1,33 @@ +# Alquimia AI + +Install the [Alquimia AI CLI](https://docs.alquimia.ai) before setup. +The integration key is `alquimia`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration alquimia +``` + +For an existing Spec Kit project, use `specify integration install alquimia`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.alquimia/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +Generated skills are both user- and model-invocable; supported core skills also +receive inline argument hints. + +## Workflow Dispatch + +Workflow command and prompt steps use `alquimia -p `, with `--model` +when configured and `--output-format json` when structured output is requested. +There are no integration-specific setup options. diff --git a/docs/integrations/amp.md b/docs/integrations/amp.md new file mode 100644 index 0000000000..ef38ee10c1 --- /dev/null +++ b/docs/integrations/amp.md @@ -0,0 +1,31 @@ +# Amp + +Install the [Amp CLI](https://ampcode.com/) before setup. +The integration key is `amp`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration amp +``` + +For an existing Spec Kit project, use `specify integration install amp`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.agents/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Workflow Dispatch + +Workflow steps use `amp --execute `, adding `--stream-json` when +structured output is requested. The integration does not forward the workflow +`model` setting: Amp's `--mode` selects an agent mode, not a model. +There are no integration-specific setup options. diff --git a/docs/integrations/auggie.md b/docs/integrations/auggie.md new file mode 100644 index 0000000000..6f62d20b24 --- /dev/null +++ b/docs/integrations/auggie.md @@ -0,0 +1,30 @@ +# Auggie CLI + +Install [Auggie CLI](https://docs.augmentcode.com/cli/overview) before setup. +The integration key is `auggie`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration auggie +``` + +For an existing Spec Kit project, use `specify integration install auggie`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.augment/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Workflow Dispatch + +Workflow steps use `auggie -p `, with `--model` when configured and +`--output-format json` when structured output is requested. +There are no integration-specific setup options. diff --git a/docs/integrations/bob.md b/docs/integrations/bob.md new file mode 100644 index 0000000000..494a10652d --- /dev/null +++ b/docs/integrations/bob.md @@ -0,0 +1,59 @@ +# IBM Bob + +Install [IBM Bob](https://www.ibm.com/products/bob) before setup. +The integration key is `bob`; no separate CLI is required. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration bob +``` + +For an existing Spec Kit project, use `specify integration install bob`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Default Skills Layout + +Skills are installed as `.bob/skills/speckit-/SKILL.md`. +Bob's skills are intent-activated: ask Bob to use the `speckit-specify` skill, +or `speckit-bug-assess` for the installed bug extension. Spec Kit renders +`/speckit-` references for skills-mode command dispatch, but that does +not mean each skill is a separately registered IDE slash command. + +## Legacy Commands and Migration + +Pass `--integration-options="--legacy-commands"` to scaffold the deprecated Bob +1.x layout (`.bob/commands/*.md`) instead. This flag will be removed in a future +release. + +Existing legacy installations can migrate with: + +```bash +specify integration upgrade bob --integration-options="--skills" +``` + +This converts the installation to the skills layout and removes the old +command files. If preset overrides are installed, migration is rejected because +preset artifacts cannot yet be reconciled across a layout change. Remove the +presets, migrate, then reinstall them. + +`--skills` and `--legacy-commands` are mutually exclusive. Without an explicit +selector, managed legacy command files keep an existing installation in legacy +mode unless managed Spec Kit skills are present. Merely creating an unrelated +`.bob/skills/` directory does not migrate it. Legacy command references retain +the dotted `/speckit.` form. + +## Workflow Permissions + +Workflow dispatch additionally requires the `bob` CLI, even though IDE setup +does not. It uses `bob run --trust --accept-license` with a positional prompt, +selecting `-f pretty` for streamed output or `-f json` for captured output. +The trust and license flags apply to this non-interactive invocation. + +The adapter does not forward the workflow `model` setting; Bob selects its +model through `session.model` in its own settings. diff --git a/integrations/README.md b/docs/integrations/catalog.md similarity index 64% rename from integrations/README.md rename to docs/integrations/catalog.md index f6aec129ca..473f8efd19 100644 --- a/integrations/README.md +++ b/docs/integrations/catalog.md @@ -4,11 +4,11 @@ The integration catalog enables discovery, versioning, and distribution of AI ag ## Catalog Files -### Built-In Catalog (`catalog.json`) +### Built-In Catalog (`integrations/catalog.json`) Contains integrations that ship with Spec Kit. These are maintained by the core team and always installable. -### Community Catalog (`catalog.community.json`) +### Community Catalog (`integrations/catalog.community.json`) Community-contributed integrations. The default community source is discovery-only: listing an adapter is neither installation permission nor a @@ -16,13 +16,18 @@ code audit. Review external code before using an install-enabled catalog. ## Catalog Configuration -The catalog stack is resolved in this order (first match wins): +The first configured layer replaces lower layers. Within that layer, lower +numeric priority wins: 1. **Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs with a single URL 2. **Project config** — `.specify/integration-catalogs.yml` in the project root 3. **User config** — `~/.specify/integration-catalogs.yml` in the user home directory 4. **Built-in defaults** — `catalog.json` + `catalog.community.json` +Adding the first project catalog replaces the default sources unless you also +list them in the project file. See [Catalogs](../reference/catalogs.md) +for shared discovery, trust, and private-source guidance. + Example `integration-catalogs.yml`: ```yaml @@ -35,32 +40,9 @@ catalogs: ## CLI Commands -```bash -# List built-in and trusted installed integrations -specify integration list - -# Browse full catalog (built-in + community) -specify integration list --catalog - -# Install an integration -specify integration install copilot - -# Register a reviewed private catalog and install its external adapter -specify integration catalog add https://example.com/catalog.json --name samples -specify integration install sample-agent - -# Non-interactive install, after reviewing and trusting the adapter -specify integration install sample-agent --trust-integration - -# Make an installed adapter the default -specify integration use sample-agent - -# Upgrade the current integration (diff-aware) -specify integration upgrade - -# Upgrade with force (overwrite modified files) -specify integration upgrade --force -``` +Browse with `specify integration list --catalog`, `search`, and `info`. +See the CLI reference for [catalog management](cli.md#catalog-management) +and [external adapter installation](cli.md#catalog-installed-external-adapters). ## Integration Descriptor (`integration.yml`) @@ -85,7 +67,7 @@ requires: `requires.tools` is optional; omit it for adapters with no required executable. Optional legacy `provides` metadata remains valid but does not supply host -commands. See [integration design](../design/integration.md#external-adapter-package-contract) +commands. See [integration design](https://github.com/github/spec-kit/blob/main/design/integration.md#external-adapter-package-contract) for class metadata, runtime methods, tools, and storage requirements. ## Catalog Schema @@ -110,7 +92,7 @@ Both catalog files follow the same JSON schema: } ``` -### Required Fields +### Top-Level Fields | Field | Type | Description | |-------|------|-------------| @@ -133,12 +115,15 @@ Both catalog files follow the same JSON schema: | `download_url` | string | External installs | Pinned ZIP, tar.gz, or tgz archive URL; HTTPS or loopback HTTP | | `sha256` | string | No | 64-character hexadecimal SHA-256 of the archive | | `requires` | object | No | Must match descriptor requirements when supplied | +| `releases` | object | No | [Historical version metadata](cli.md#historical-integration-metadata); not installable releases | The map key and any declared `id` must match `integration.id`. Name, version, description, and optional author/repository/license metadata must match the descriptor. Built-in entries need no download fields because their implementations ship with the CLI. +## Installation Policy and Storage + Registering a catalog with `integration catalog add` creates an install-enabled project source. Set `install_allowed: false` in its configuration to permit discovery only. This policy cannot be overridden with `--trust-integration` or @@ -149,26 +134,18 @@ Authenticated GitHub assets use the existing Spec Kit authentication providers. Installed code is stored in `.specify/integrations/packages//` with provenance and hashes in `packages.json`; both are excluded by the managed `.specify/.gitignore`. Execution consent is stored separately in -`~/.specify/integration-trust.json`, bound to the canonical project root, -integration ID, and verified package digest. Project metadata cannot grant -consent. Copying a project or changing users requires a new local decision: -review the package and run -`specify integration upgrade sample-agent --force --trust-integration` -from an install-enabled catalog. -Generated files have a separate -hash-tracked `.manifest.json`; new CLI processes load the trusted package -without fetching the catalog. An upgrade fetches the catalog's current version -and checks its descriptor again. Do not edit installed package code in place: -publish a new archive/version and upgrade instead. -Catalog management/discovery and `integration info` remain metadata-only and do -not import adapters. Forced upgrade/uninstall can recover damaged installed code -using user-local registrar and generated-path ownership records, without -bypassing source policy or trust. Edited project cleanup claims are rejected. -Without local ownership proof, old-only generated files are preserved with a -manual-cleanup warning; trusted replacement setup still targets its declared -destination. Concurrent dispatch pins each project's adapter and verified -imports independently. +`~/.specify/integration-trust.json`, bound to the project, integration ID, and +verified package digest. Generated files have their own hash-tracked +`.manifest.json`. + +Do not edit installed package code in place: publish a new archive/version and +upgrade instead. See the CLI reference for +[trust and reauthorization](cli.md#catalog-installed-external-adapters) and +[upgrade and recovery](cli.md#upgrade-an-integration). ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add integrations to the community catalog. +See the [contribution guide](contributing.md) for adding built-in integrations +or submitting external integration catalog entries. For agent-specific setup, +start with the [integration directory](index.md). Shared user-facing commands +are documented in the [integration management reference](cli.md). diff --git a/docs/integrations/claude.md b/docs/integrations/claude.md new file mode 100644 index 0000000000..5f0fa5eacc --- /dev/null +++ b/docs/integrations/claude.md @@ -0,0 +1,71 @@ +# Claude Code + +Install [Claude Code](https://www.anthropic.com/claude-code) before setup. +The integration key is `claude`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration claude +``` + +For an existing Spec Kit project, use `specify integration install claude`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.claude/skills/speckit-/SKILL.md`. +Invoke them in Claude's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +## User-Invocable-Only Skills + +By default every Spec Kit skill installed for Claude Code is model-invocable, so +its description is always in Claude's context and counts toward the +skill-listing budget. In projects with many skills this can push other skills +out of the listing. To make the core Spec Kit command skills user-invocable +only: + +```bash +specify init my-project --integration claude --integration-options="--no-model-invocation" +``` + +This writes `disable-model-invocation: true` into the core command skills. +Claude can run them only when the user invokes `/speckit-`, and their +descriptions stay out of its context. + +- Extension skills stay model-invocable, because mandatory extension hooks rely + on the model invoking them. If an extension's mandatory hook runs a core + command (its `command:` is a core `speckit.`), leave this option off: + the model cannot run that hook while the core skill is user-invocable only. +- The option is stored with the integration's other options and reapplied by + `specify integration upgrade claude`. Passing `--integration-options` to + `upgrade` replaces all stored options, so repeat any you want to keep (for + example `--integration-options="--events false --no-model-invocation"`); + `--integration-options=""` clears them. Re-running `specify init` likewise + stores only the options passed to it. +- Core command skills that a preset overrides, or stops overriding, are reverted + to the default by commands that re-register preset skills without reinstalling + Claude: commands that install, remove or update presets (including `specify + bundle` commands that carry presets), `specify integration use claude`, and + `specify integration switch claude` when Claude is installed but not the + default. To reapply the option, run `specify integration upgrade claude + --force` while Claude is the default integration (`--force` is needed because + those commands modify installed skill files, and it overwrites local edits to + Spec Kit-managed files). + +## Runtime Events and Workflow Dispatch + +The integration supports native events through `.claude/settings.json`. +Use `--integration-options="--events false"` to disable Spec Kit event handlers; +combine it with `--no-model-invocation` if both settings are wanted. +See [runtime events](cli.md#runtime-events). + +Workflow steps use `claude -p `, with `--model` when configured and +`--output-format json` when structured output is requested. This adapter does +not add a permission-bypass flag itself. diff --git a/docs/integrations/cli.md b/docs/integrations/cli.md new file mode 100644 index 0000000000..0815a10282 --- /dev/null +++ b/docs/integrations/cli.md @@ -0,0 +1,539 @@ +# Integration CLI Reference + +This reference documents shared `specify integration` commands, catalog +management, and lifecycle behavior. For agent-specific setup, installed paths, +options, and limitations, start with the [integration guides](index.md). + +Run these commands inside a project initialized with `specify init`. +For a new project, use `specify init --integration `. + +## Supported AI Coding Agents + +The [integration directory](index.md#choose-an-integration) +lists supported agents and their exact keys, with a dedicated guide for each +integration. Run `specify integration list` to inspect local availability. + +## Command Invocation + +Invoke Spec Kit's process steps inside your coding agent, not in the terminal. +In GitHub Copilot's default mode, these are skills you invoke in the agent's +chat. CLI installation and setup commands are separate terminal operations. +The steps are the same across integrations, but their spelling depends on the +agent and its installed mode: + +| Integration or mode | SDD example | Extension example | +| --- | --- | --- | +| GitHub Copilot, default skills mode | `/speckit-specify` | `/speckit-bug-assess` | +| Dotted slash-command notation used in the references | `/speckit.specify` | `/speckit.bug.assess` | +| Codex, Command Code, ZCode skills | `$speckit-specify` | `$speckit-bug-assess` | +| Kimi skills | `/skill:speckit-specify` | `/skill:speckit-bug-assess` | + +Use the form exposed by your agent. See the +[GitHub Copilot guide](copilot.md) for its skills and commands +layouts, or choose another agent from the [integration directory](index.md). + +## List Available Integrations + +```bash +specify integration list +``` + +| Option | Description | +| ----------- | ----------------------------------------------------------------------------------------------------------------------- | +| `--catalog` | Also browse the catalog, including external integrations not installed in this project. | + +Shows built-in and trusted installed external integrations, their setup +requirements, and their multi-install safety declarations. Installed +integrations and the default are marked separately. + +## Search Available Integrations + +```bash +specify integration search [query] +``` + +| Option | Description | +| ---------- | ------------------ | +| `--tag` | Filter by tag | +| `--author` | Filter by author | + +Searches the active catalog stack. Without a query, lists all available integrations. + +## Integration Info + +```bash +specify integration info +specify integration info --versions +``` + +Shows an integration's catalog metadata, source catalog, and whether it is active. +`--versions` lists the advertised current and historical versions from the +winning catalog, with the current release first and older releases in descending +version order. Discovery-only sources are labeled as such. + +## Install an Integration + +```bash +specify integration install +``` + +| Option | Description | +| ------------------------ | ------------------------------------------------------------------------ | +| `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | +| `--force` | Opt in to installing alongside integrations that are not declared multi-install safe | +| `--integration-options` | Integration-specific options (e.g. `--integration-options="--commands-dir .myagent/cmds"`) | +| `--trust-integration` | After reviewing the code, pre-authorize an external adapter's Python execution without the interactive trust prompt | + +Installs the integration into the current project. Multi-install proceeds +automatically only when all involved integrations are declared safe. Otherwise, +use `switch` to replace the default or `--force` to opt in to multi-install. +Failed setup triggers rollback. + +**Catalog history is metadata only.** `integration install` still resolves +registered built-in implementations directly, or the current external adapter +release from an install-enabled catalog, not historical catalog records. +There is no `integration install --version`. The default community catalog +remains discovery-only. + +Installing an additional integration does not change the default integration. Use `specify integration use ` to change the default. + +Extensions and presets follow the default integration only. Use `use ` or +`switch ` to activate another integration and register their commands for it. + +### Catalog-installed external adapters + +Register a reviewed catalog in the initialized project, then install its adapter: + +```bash +specify integration catalog add https://example.com/catalog.json --name samples +specify integration install sample-agent +specify integration use sample-agent +``` + +Installation prompts for trust **before** downloading/importing Python. For +automation, explicitly authorize code you have reviewed: + +```bash +specify integration install sample-agent --trust-integration +specify integration upgrade sample-agent --trust-integration +``` + +The source must have `install_allowed: true`. The default community catalog is +discovery-only; neither `--force` nor the trust flag bypasses that policy. +Catalog listing/search/info do not import catalog code. See the +[catalog schema](catalog.md#catalog-schema) for required metadata and supported +archive URLs. +Search advertises `specify integration install ` for install-enabled sources; +discovery-only results do not advertise installation. + +`specify check` probes an external adapter's required descriptor tools rather +than its catalog ID. With no required tools declared, CLI adapters are checked +using their runtime executable; optional tools do not produce missing-tool +errors. These checks do not run the executable or invoke generic version probes. + +Installed adapter code persists separately from generated agent files. New CLI +processes load the trusted package without consulting the catalog. Missing, +modified, or incompatible code is an error, not a silent fallback. Upgrade +fetches the catalog's current version; uninstall removes the package while +preserving modified generated files by default. +Metadata-only `workflow status` and `workflow info` remain available without +loading adapter code, including when an installed adapter is damaged. Workflow +execution and resume still report adapter-loading failures explicitly. + +Execution consent is user-local and bound to the project, integration, and +verified package contents. Copying project metadata does not transfer consent. +After copying a project or changing users, review the adapter and reauthorize +from an install-enabled catalog: + +```bash +specify integration upgrade sample-agent --force --trust-integration +``` + +Forced uninstall also works when package code is untrusted or its entire +directory is missing; it does not import that code. + +For initialization, a project/user catalog or `SPECKIT_INTEGRATION_CATALOG_URL` +can supply an external adapter: + +```bash +specify init my-project --integration sample-agent --trust-integration +``` + +Review the [external adapter API](https://github.com/github/spec-kit/blob/main/design/integration.md#external-adapter-package-contract) +before publishing a package. No pip installation or source-registry edit is +needed for adapters using the host API and standard library. + +If your CLI rejects multi-install, check `specify version` and follow the +[upgrade guide](../upgrade.md). A one-shot `uvx` invocation does not update the +persistent `specify` executable on your `PATH`. + +## Uninstall an Integration + +```bash +specify integration uninstall [] +``` + +| Option | Description | +| --------- | --------------------------------------------------- | +| `--force` | Remove files even if they have been modified | + +Removes the specified integration, or the default if no key is given. +Manifest-tracked generated files use content hashes for cleanup: + +- **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 modified tracked files too. + +These are the rules for manifest-tracked generated files. Integration-specific +cleanup can differ: [Hermes global skills](hermes.md#global-ownership-and-removal) +and [Kimi legacy skills](kimi.md#legacy-cleanup-on-uninstall) +can be removed without modified-file protection. Check the agent guide before +uninstalling or switching away. + +Uninstall also removes the integration's registered extension and preset +artifacts; the extensions and presets themselves stay installed. Removing the +default selects a remaining integration and registers enabled contributions for +it. Removing the last integration does not install `none` automatically. + +## Switch to a Different Integration + +```bash +specify integration switch +``` + +| Option | Description | +| ------------------------ | ------------------------------------------------------------------------ | +| `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | +| `--force` | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default | +| `--refresh-shared-infra` | Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved) | +| `--integration-options` | Options for the target integration when it is not already installed | +| `--trust-integration` | Authorize downloading and executing a reviewed external adapter without the interactive trust prompt | + +- **Target not installed:** removes the current default, installs the target, + and makes it the default. Other installed integrations remain. +- **Target already installed:** changes the default without removing any + integrations, like `use`. To change its setup options, run + `upgrade --integration-options ...` first, then `use `; + `switch` rejects setup options for installed targets. + +Both paths register enabled extensions and presets for the new default. +See the option table for the different meanings of `--force`. + +When switching to an external adapter that must be downloaded and installed, +use `--trust-integration` only after reviewing its code: + +```bash +specify integration switch sample-agent --trust-integration +``` + +Switching to an already-installed adapter still validates its existing trust. +The flag does not bypass that validation or a catalog's discovery-only policy. +See [catalog-installed external adapters](#catalog-installed-external-adapters) +for the trust requirements. + +## Use an Installed Integration + +```bash +specify integration use +``` + +| Option | Description | +| --------- | --------------------------------------------------- | +| `--force` | Overwrite managed shared templates while changing the default | + +Sets the default integration without uninstalling any other installed integrations. This also refreshes managed shared templates so command references match the new default integration's invocation style. Modified or untracked shared templates are preserved unless `--force` is used. + +It also registers enabled extension and preset commands or skills for the new +default, including contributions installed while another integration was active. + +## Upgrade an Integration + +```bash +specify integration upgrade [] +``` + +| Option | Description | +| ------------------------ | ------------------------------------------------------------------------ | +| `--force` | Overwrite files even if they have been modified | +| `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | +| `--integration-options` | Options for the integration | +| `--trust-integration` | Authorize downloading/importing the reviewed replacement external adapter | + +Reinstalls an installed integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the default integration; if a key is provided, it must be one of the installed integrations. 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. Shared templates stay aligned with the default integration even when upgrading a non-default integration. + +Enabled extensions and presets are re-registered only when upgrading the currently active (default) integration. A non-default upgrade still refreshes that integration's core commands, but does not re-register its extension or preset layers — `use`/`switch` that integration afterward to rescaffold them. + +If the generated-file manifest is missing, upgrade reports that there is nothing +to upgrade and leaves the installed adapter package, generated files, and local +recovery ownership unchanged, including with `--force`. Replacement code is +persisted only after the upgrade regenerates the managed files successfully. + +If an upgrade would change an integration between command and skills layouts while preset artifacts are registered for it, the upgrade is rejected before changing files. Remove the affected presets, run the layout-changing upgrade, then reinstall them. + +For external adapters, forced upgrade or uninstall can recover damaged or +unloadable packages using user-local ownership records. Without that proof, +old-only generated files are preserved with a manual-cleanup warning. Recovery +preserves shared event dispatchers and partially owned settings; a trusted +replacement may still overwrite its declared destinations under `upgrade --force`. +Recovery does not bypass catalog policy or replacement-package trust. + +Failed operations roll back their own changes, not unrelated user files or +workflow progress. Conflicting concurrent edits are reported with recovery +snapshots retained. Adapter authors should follow the +[storage, loading, and lifecycle contract](https://github.com/github/spec-kit/blob/main/design/integration.md#storage-loading-and-lifecycle) +for ownership, journaling, and recovery requirements. + +## Report Integration Status + +```bash +specify integration status +specify integration status --json +``` + +Reports the current project's integration status without changing files. The +status report includes the default integration, installed integrations, +multi-install safety, missing managed files, modified managed files, invalid +manifest paths, shared Spec Kit infrastructure health, unchecked manifests, and +the target integration for default-sensitive shared templates. The JSON form is +intended for CI and coding agents that need stable machine-readable status data; +it also reports the raw recorded integrations and the integration manifests that +were checked when state repair heuristics differ from the recorded file. +The command exits 0 when the report status is `ok` or `warning`; it exits 1 +only when the report status is `error`. In JSON output, `multi_install_safe` +is `null` when no installed integration set can be evaluated, such as when the +integration state is missing, unreadable, lacks a valid recorded integration +list, or records no installed integrations. + +## Catalog Management + +Integration catalogs control where the discovery commands (`search` and `info`) look for integrations. Catalogs are checked in priority order. + +Catalog management, `integration list --catalog`, and `integration info` do not +execute adapter code. Ordinary integration listing, setup, selection, status, +registration, and workflow dispatch load trusted installed implementations. + +### List Catalogs + +```bash +specify integration catalog list +``` + +Shows the active catalog sources. Project-level sources (when configured) are removable by index; otherwise the active sources are shown as non-removable. + +### Add a Catalog + +```bash +specify integration catalog add +``` + +| Option | Description | +| --------------- | ----------------------------- | +| `--name ` | Optional name for the catalog | + +Adds a custom catalog URL to the project's `.specify/integration-catalogs.yml`. The URL must use HTTPS (except `http://localhost`, `http://127.0.0.1`, or `http://[::1]` for local testing). + +Re-adding the same URL with the same name succeeds without changing the configuration; a different name is rejected. + +### Remove a Catalog + +```bash +specify integration catalog remove +``` + +Removes a project catalog source by its 0-based index in `catalog list`. + +### Catalog Resolution Order + +The first configured layer replaces lower layers. Within that layer, lower +numeric priority wins: + +1. **Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs +2. **Project config** — `.specify/integration-catalogs.yml` +3. **User config** — `~/.specify/integration-catalogs.yml` +4. **Built-in defaults** — official catalog + community catalog + +### Historical Integration Metadata + +An integration entry may retain the existing top-level fields for its advertised +current release and add a `releases` mapping of historical version to metadata. +Single-version entries remain valid without a `releases` key. For example: + +```json +{ + "id": "my-agent", + "name": "My Agent", + "version": "2.0.0", + "description": "Current release", + "releases": { + "1.0.0": { + "description": "Historical release", + "repository": "https://example.com/my-agent/v1", + "requires": {"speckit_version": ">=0.7"} + } + } +} +``` + +The top-level fields retain their original meaning for older clients and for +unqualified `search`, `info`, `list --catalog`, and `install` commands. Historical +records may contain `name`, `description`, `author`, `repository`, `license`, +`tags` (a list of strings), and `requires` (a mapping). Shared identity, name, +author, and source policy are retained; current-only metadata such as +description, repository, tags, and requirements is **not** inherited by an +older release unless explicitly supplied in its record. Release records cannot +override `id`, `version`, `releases`, or source policy, and cannot advertise +download URLs or archives. + +For programmatic metadata lookup, +`IntegrationCatalog.get_integration_info(id, version="1.0.0")` selects the +exact historical record from the winning source, or returns `None` if that +version is missing. `get_integration_versions(id)` returns the versions +advertised by that same source. PEP 440-equivalent spellings (such as `v1.0` +and `1.0.0`) match the same release while retaining its catalog spelling. +The current release must not be repeated in `releases`; malformed records and +duplicate equivalent versions are rejected. An absent version never falls +through to a lower-priority source or silently selects current. These lookups +do not install an integration. + +## Integration-Specific Options + +Pass agent-specific setup options through `--integration-options`. Their +semantics, examples, and migration caveats live in the relevant agent guide: + +| Integration | Guide | +| --- | --- | +| Generic | [Output directory and skills mode](generic.md#output-options-and-invocation) | +| GitHub Copilot | [Skills and commands layouts](copilot.md#commands-layout) | +| IBM Bob | [Legacy commands and migration](bob.md#legacy-commands-and-migration) | +| Kimi Code | [Legacy migration](kimi.md#legacy-migration) | + +Other agent-specific details are listed in the +[integration directory](index.md). + +## Runtime Events + +Event-capable integrations accept `--events true|false` through the setup +`--integration-options` string; the default is enabled. Handler definitions +come from integration defaults, installed extensions, and +`.specify/integration-events.yml`. Enabling events does not create handlers +where none are configured, and an integration emits only the native events +it supports. + +To configure project overrides, create `.specify/integration-events.yml`. +Replace `` with your integration key and the example command with an +installed, script-backed Spec Kit command: + +```yaml +integrations: + : + events: + post_tool_use: + - command: speckit.my-extension.check + matcher: "*" + timeout: 60 +``` + +Each event accepts a handler mapping or a list of handlers. A handler requires +a non-empty `command` string; `matcher` is an optional native filter string, +and `timeout` is an optional positive integer in seconds. + +Integration defaults and extension handlers accumulate. A valid project override +**replaces the entire event map for that integration**, not just the events +listed in the override. Set `events: {}` under the integration key to disable +all its handlers. If the override cannot be read or parsed, or an event fails +validation, Spec Kit warns and retains the defaults and extension handlers. +`--events false` takes precedence over all these sources. + +With events enabled, apply configuration changes using +`specify integration upgrade `. + +For an event-capable integration, disable Spec Kit event handlers during an upgrade: + +```bash +specify integration upgrade --integration-options="--events false" +``` + +Supplying `--integration-options` replaces stored setup options, so repeat other +options you want to keep. A disabled event set removes previously installed +Spec Kit hooks rather than merely stopping new hook generation. +Agent-specific guides identify native event configuration paths and +limitations. These runtime events are distinct from extension command hooks. + +## Workflow CLI Dispatch + +The agent guides distinguish IDE setup from workflow CLI support. Some IDE +integrations can dispatch workflow steps if their separate CLI is available; +others explicitly do not support command/prompt dispatch. Adapter support means +Spec Kit can construct the invocation, not that every vendor CLI release has +been exercised against it. + +CLI-capable adapters support +`SPECKIT_INTEGRATION__EXECUTABLE` for executable selection and +`SPECKIT_INTEGRATION__EXTRA_ARGS` for additional CLI arguments, where +`` is uppercase with hyphens replaced by underscores. Extra arguments are +parsed using POSIX shell quoting. Placement and duplicate-flag behavior differ +by adapter; see the agent guide, especially for Docker Agent and Goose. + +Setup `--integration-options` are separate from workflow +[`integration_args` and `integration_options`](../reference/workflows.md#per-step-integration-configuration). +Adapters reject non-empty per-step configuration unless they implement it; +Docker Agent currently exposes structured agent/safety configuration. +Headless approval flags, model forwarding, and structured-output support are +also adapter-specific, not universal guarantees. + +## GitHub Issue Creation + +The deprecated `speckit.taskstoissues` command still runs with a warning but +will be removed in a future minor release. Install the opt-in GitHub extension +with `specify extension add github` and use `speckit.github.taskstoissues` +instead. See the [extension's migration guide](https://github.com/github/spec-kit/blob/main/extensions/github/README.md#migrating-from-the-core-taskstoissues-command) +for invocation syntax and migration details; the core command does not install +the extension automatically. + +## FAQ + +### Can I install multiple integrations in the same project? + +Yes, but it is intended for team portability rather than the default setup. Multiple integrations are allowed automatically only when the installed integration and the new integration are declared multi-install safe by Spec Kit. For other combinations, pass `--force` to acknowledge that multiple agents may see unrelated agent-specific instructions or commands. + +Spec Kit tracks one default integration in `.specify/integration.json` with `default_integration`, all installed integrations with `installed_integrations`, per-integration runtime settings with `integration_settings`, and a dedicated `integration_state_schema` for future state migrations. The legacy `integration` field remains as an alias for the default integration. + +### Which integrations are multi-install safe? + +For integrations that generate agent files, safety requires static, unique +output paths, stable command invocation settings, and a separate manifest whose +managed files do not overlap another safe integration. Registry tests enforce +those invariants. Shared Spec Kit templates remain aligned to the single default. + +Run `specify integration list` to inspect each integration's declaration. +Each integration's guide documents its safety status and installed command +directories. + +Integrations that share a command directory with another integration, require dynamic install paths such as `--commands-dir`, or merge shared tool settings are not declared safe by default. They can still be installed alongside another integration with `--force`. + +### What happens to my changes when I uninstall or switch? + +Manifest-tracked files you've modified are preserved automatically. Only +unmodified tracked files (matching their original SHA-256 hash) are removed. +Use `--force` to override this. See +[uninstall](#uninstall-an-integration) for integration-specific cleanup exceptions. + +### How do I know which key to use? + +Run `specify integration list` to see all available integrations with their keys, +or check the [integration directory](index.md#choose-an-integration). + +### Do I need the AI coding agent installed to use an integration? + +CLI-based integrations require the tool to be installed. IDE-based integrations +work through the IDE itself and may not require a separate CLI for setup. +Workflow dispatch can have additional CLI requirements; see your integration's +guide. `specify integration list` shows each integration's setup requirements. + +### When should I use `upgrade` vs `switch`? + +Use `upgrade` when you've upgraded Spec Kit and want to refresh an installed integration's managed files. Use `switch` when you want to replace the current default with another integration; if the target is already installed, `switch` behaves like `use`. + +### Do extensions and presets I install apply to every installed integration? + +No. Extensions (`specify extension add`) and presets (`specify preset add`) register their command overrides for the currently active (default) integration only, even if other integrations are installed. A non-default integration does not receive those artifacts until it becomes the default: `specify integration use ` (or `switch `) rescaffolds every enabled extension and preset for the newly active integration. `specify integration upgrade` follows the same rule — it only re-registers extensions and presets when upgrading the active integration. diff --git a/docs/integrations/cline.md b/docs/integrations/cline.md new file mode 100644 index 0000000000..1c948b8b95 --- /dev/null +++ b/docs/integrations/cline.md @@ -0,0 +1,34 @@ +# Cline + +Install [Cline](https://github.com/cline/cline) in your IDE before setup. +The integration key is `cline`; no separate CLI is required. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration cline +``` + +For an existing Spec Kit project, use `specify integration install cline`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown workflows are installed under `.clinerules/workflows/`, using +hyphenated filenames such as `speckit-specify.md`. +Invoke them in Cline's chat as `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension, not dotted commands. + +Handoff references and extension/preset command content are also normalized +to hyphenated command names. + +## Workflow Limitation + +This integration does not support CLI dispatch for workflow command or prompt +steps. It installs IDE workflows only and has no integration-specific setup +options. diff --git a/docs/integrations/codebuddy.md b/docs/integrations/codebuddy.md new file mode 100644 index 0000000000..e5dcd1d8e9 --- /dev/null +++ b/docs/integrations/codebuddy.md @@ -0,0 +1,30 @@ +# CodeBuddy CLI + +Install [CodeBuddy CLI](https://www.codebuddy.cn/docs/cli/installation) before setup. +The integration key is `codebuddy`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration codebuddy +``` + +For an existing Spec Kit project, use `specify integration install codebuddy`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.codebuddy/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Workflow Dispatch + +Workflow steps use `codebuddy -p `, with `--model` when configured and +`--output-format json` when structured output is requested. +There are no integration-specific setup options. diff --git a/docs/integrations/codex.md b/docs/integrations/codex.md new file mode 100644 index 0000000000..d37b6901f5 --- /dev/null +++ b/docs/integrations/codex.md @@ -0,0 +1,38 @@ +# Codex CLI + +Install [Codex CLI](https://github.com/openai/codex) before setup. +The integration key is `codex`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration codex +``` + +For an existing Spec Kit project, use `specify integration install codex`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.agents/skills/speckit-/SKILL.md`. +Invoke them in Codex's chat with a dollar prefix, for example `$speckit-specify` +or `$speckit-bug-assess` for the installed bug extension. +Other integrations also target `.agents/skills/`; review +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project) +before installing another agent that shares this directory. + +## Options and Workflow Dispatch + +`--integration-options="--skills"` explicitly selects the skills layout, which +is already the only supported layout for this integration. Native events use +`.codex/config.toml`; `--events false` disables Spec Kit event handlers. +See [runtime events](cli.md#runtime-events). + +Workflow steps use `codex exec `, with `--model` when configured and +`--json` when structured output is requested. Codex dev-mode registration writes +skill files rather than symlinking them. diff --git a/docs/integrations/command-code.md b/docs/integrations/command-code.md new file mode 100644 index 0000000000..ef30f15988 --- /dev/null +++ b/docs/integrations/command-code.md @@ -0,0 +1,32 @@ +# Command Code + +Install [Command Code](https://commandcode.ai/docs) before setup. +The integration key is `command-code`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration command-code +``` + +For an existing Spec Kit project, use `specify integration install command-code`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.commandcode/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat with a dollar prefix, for example +`$speckit-specify` or `$speckit-bug-assess` for the installed bug extension. + +## Options and Workflow Dispatch + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. + +Workflow steps use `command-code -p `, with `--model` when configured +and `--output-format json` when structured output is requested. diff --git a/docs/integrations/contributing.md b/docs/integrations/contributing.md new file mode 100644 index 0000000000..bbb8124081 --- /dev/null +++ b/docs/integrations/contributing.md @@ -0,0 +1,123 @@ +# Contributing Integrations + +This guide covers built-in integrations, external adapter development, and +community catalog submissions. + +Start with the [agent integration design](https://github.com/github/spec-kit/blob/main/design/integration.md) +for implementation contracts, ownership, and delivery requirements. + +## Adding a Built-In Integration + +Built-in integrations are maintained by the Spec Kit core team and ship with the CLI. + +For checkout setup, see [local development](../local-development.md). Follow the +[contributor testing guidance](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#testing-deterministic-behavior) +and [validation flow](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#recommended-validation-flow), +then the [integration PR requirements](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md#integration-pull-requests). + +### Checklist + +1. **Create the integration subpackage** under `src/specify_cli/integrations//` + using the integration key with hyphens replaced by underscores for ``. +2. **Implement the integration class** following [Adding an agent](https://github.com/github/spec-kit/blob/main/design/integration.md#adding-an-agent). +3. **Register the integration** in `src/specify_cli/integrations/__init__.py`. +4. **Add tests** under `tests/integrations/test_integration_.py`. +5. **Add a catalog entry** in `integrations/catalog.json`. +6. **Update documentation:** add `docs/integrations/.md` and link it from + the [integration index](index.md) and [navigation](../toc.yml). + Update the [catalog reference](catalog.md) if needed and + [integration design](https://github.com/github/spec-kit/blob/main/design/integration.md) + if the contract changes. + +Use the [catalog schema](catalog.md#catalog-schema) for the built-in entry format. + +## Developing an External Adapter + +Implement and package your adapter using the +[external adapter contract](https://github.com/github/spec-kit/blob/main/design/integration.md#external-adapter-package-contract). +The [descriptor reference](catalog.md#integration-descriptor-integrationyml) +documents package metadata; the [catalog schema](catalog.md#catalog-schema) +documents published entries. + +For local installation and trust decisions, follow +[catalog-installed external adapters](cli.md#catalog-installed-external-adapters). +See [upgrading an integration](cli.md#upgrade-an-integration) for update behavior. + +### Validate Your Adapter + +Test your package through the public path: register a local loopback test +catalog, install its neutral adapter, start a fresh CLI process, register +extension/preset contributions, and exercise command/prompt workflow dispatch +with a harmless process double. + +Cover the [lifecycle contract](https://github.com/github/spec-kit/blob/main/design/integration.md#storage-loading-and-lifecycle), +including: + +- Invalid metadata/classes, trust denial, unsafe archives, setup errors, and + upgrade/uninstall failures. +- Package code kept separate from generated-file manifests; rollback and + cleanup that preserve modified files, unrelated user files, independent + workflow progress, and concurrent edits. +- Metadata-only commands without import side effects; forced recovery of + damaged packages using local ownership proof, and manual-cleanup warnings + when that proof is absent. +- Symlinked write destinations, reserved roots, unsafe legacy paths, and + case-insensitive overlap between primary and legacy output paths. +- Overlapping project dispatch and lazy relative imports that retain the + correct adapter without serializing independent agent processes. +- For event-capable adapters, event-only extension add/remove and enable/disable + in fresh CLI processes, including explicit errors when installed code cannot load. + +## Submitting to the Community Catalog + +External developers can list integrations in `integrations/catalog.community.json` +for discovery. Catalog maintainers review listing metadata, not adapter +implementations; users must vet the code. A listing does not grant installation +permission. + +### Prerequisites + +1. **Working external adapter** — packaged and validated as described above. +2. **Public repository** — hosted on GitHub or similar. +3. **Documentation** — README with usage instructions. +4. **License** — open source license file. + +Prepare your entry using the [catalog schema](catalog.md#catalog-schema). +Metadata must match the packaged descriptor. Publish a pinned archive URL; +an archive SHA-256 digest is recommended. + +### Submission + +1. **Fork** the [spec-kit repository](https://github.com/github/spec-kit) +2. **Add your entry** under the `integrations` key in `integrations/catalog.community.json`: + + ```json + { + "schema_version": "1.0", + "integrations": { + "sample-agent": { + "id": "sample-agent", + "name": "Sample Agent", + "version": "1.0.0", + "description": "Adapter for Sample Agent", + "author": "your-name", + "repository": "https://github.com/your-name/speckit-sample-agent", + "download_url": "https://github.com/your-name/speckit-sample-agent/releases/download/v1.0.0/sample-agent.zip", + "tags": ["cli"] + } + } + } + ``` + +3. **Open a pull request** with: + - Your catalog entry + - Link to your integration repository + - Confirmation that `integration.yml` is valid + +### Version Updates + +To update your integration version in the catalog: + +1. Release a new version of your integration +2. Open a PR updating the version, pinned archive URL, and digest (if provided) +3. Ensure backward compatibility or document breaking changes diff --git a/docs/integrations/copilot.md b/docs/integrations/copilot.md new file mode 100644 index 0000000000..c0d5a53833 --- /dev/null +++ b/docs/integrations/copilot.md @@ -0,0 +1,72 @@ +# GitHub Copilot + +Set up [GitHub Copilot](https://code.visualstudio.com/) in your editor, or use +Copilot CLI. The integration key is `copilot`; a CLI is not required for IDE setup. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration copilot +``` + +For an existing Spec Kit project, use `specify integration install copilot`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Default Skills Layout + +Skills are installed as `.github/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat as `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. These are agent skills, +not terminal commands. + +## Commands Layout + +To opt into the supported commands layout: + +```bash +specify init my-project --integration copilot --integration-options="--commands" +``` + +This installs `.agent.md` files under `.github/agents/`, companion `.prompt.md` +files under `.github/prompts/`, and merges `.vscode/settings.json`. +In this layout, Copilot CLI can select an agent through `/agents` or address +it directly in a prompt. + +Use `--integration-options="--skills"` to explicitly select the default skills +layout when migrating an existing commands installation with +`specify integration upgrade copilot`. See the +[shared upgrade rules](cli.md#upgrade-an-integration), +including the restriction on changing layouts while preset artifacts are +registered. + +`--skills` and `--commands` are mutually exclusive. Without an explicit layout +flag, existing managed command installations retain their layout on upgrade or +activation; a fresh installation defaults to skills. + +The commands layout adds only missing VS Code settings and subkeys. Existing +values remain unchanged. If an existing settings file is JSONC or otherwise +cannot be parsed as a JSON object, the merge is skipped with a warning and +manual instructions. An existing merged settings file is retained on uninstall; +a newly created settings file is manifest-tracked. + +## Runtime Events and Workflow Permissions + +Native events use `.github/hooks/speckit.json`. +`--integration-options="--events false"` disables Spec Kit event handlers. +See [runtime events](cli.md#runtime-events). + +Workflow steps require Copilot CLI separately from the IDE setup. In skills +mode, command steps pass `/speckit-` in the prompt. In commands mode, +they select `--agent speckit.` and pass the user's arguments as the +prompt rather than treating agent files as slash commands. + +Headless dispatch adds `--yolo` by default, allowing tools, paths, and URLs +without interactive approval. Set `SPECKIT_COPILOT_ALLOW_ALL_TOOLS=0` to stop +Spec Kit from adding this flag. The deprecated `SPECKIT_ALLOW_ALL_TOOLS` is +accepted only as a fallback. A configured `--model` and requested +`--output-format json` are forwarded. diff --git a/docs/integrations/cursor-agent.md b/docs/integrations/cursor-agent.md new file mode 100644 index 0000000000..f255a77557 --- /dev/null +++ b/docs/integrations/cursor-agent.md @@ -0,0 +1,37 @@ +# Cursor + +Install [Cursor](https://cursor.sh/) before setup. +The integration key is `cursor-agent`; no separate CLI is required for IDE setup. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration cursor-agent +``` + +For an existing Spec Kit project, use `specify integration install cursor-agent`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.cursor/skills/speckit-/SKILL.md`. +Invoke them in Cursor's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +## Options and Workflow Permissions + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. Native events use +`.cursor/hooks.json`; `--events false` disables Spec Kit event handlers. +See [runtime events](cli.md#runtime-events). + +Workflow command and prompt steps additionally require the `cursor-agent` CLI. +Dispatch uses `-p --trust --approve-mcps --force`: these flags bypass workspace +trust prompts and approve MCP loading and tool actions. Run workflows only in +a project where you intend to grant those permissions. A configured `--model` +and requested `--output-format json` are forwarded. diff --git a/docs/integrations/devin.md b/docs/integrations/devin.md new file mode 100644 index 0000000000..ee346f38ce --- /dev/null +++ b/docs/integrations/devin.md @@ -0,0 +1,35 @@ +# Devin for Terminal + +Install [Devin for Terminal](https://cli.devin.ai/docs) before setup. +The integration key is `devin`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration devin +``` + +For an existing Spec Kit project, use `specify integration install devin`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.devin/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +## Options and Workflow Dispatch + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. Native events use +`.devin/hooks.v1.json`; `--events false` disables Spec Kit event handlers. +See [runtime events](cli.md#runtime-events). + +Workflow steps use `devin -p ` and forward a configured `--model`. +Devin's adapter returns plain-text stdout even when structured output is +requested; it does not add a JSON-output flag. diff --git a/docs/integrations/docker-agent.md b/docs/integrations/docker-agent.md new file mode 100644 index 0000000000..86cebdad9f --- /dev/null +++ b/docs/integrations/docker-agent.md @@ -0,0 +1,65 @@ +# Docker Agent + +Install [Docker Agent](https://docs.docker.com/ai/docker-agent/) before setup. +The integration key is `docker-agent`. Spec Kit detects either the standalone +`docker-agent` binary or the Docker CLI plugin (`docker agent`). + +## Multi-Install Safety + +This integration is not declared multi-install safe because its skills directory +is shared with other integrations. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration docker-agent +``` + +For an existing Spec Kit project, use `specify integration install docker-agent`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills and Agent Configuration + +Skills are installed as `.agents/skills/speckit-/SKILL.md`, the same +directory used by Codex and Zed. In the selected agent YAML, enable local skills +with `skills: true` and provide filesystem read access. Invoke the skills in the +agent's chat as `/speckit-specify` or `/speckit-bug-assess` for the installed bug +extension. + +The optional `--integration-options="--skills"` setup flag restates the +default; this integration always scaffolds skills. Spec Kit does not edit the +selected agent YAML or expose its hooks through Spec Kit's native-event system. + +## Workflow Configuration + +Workflow dispatch requires an agent configuration reference. Prefer the command +step's structured runtime fields: + +```yaml +- id: specify + type: command + command: speckit.specify + integration: docker-agent + integration_args: + - ./agent.yaml + integration_options: + agent: root + safety: balanced + input: + args: "Describe the feature" +``` + +`integration_args` accepts at most one non-empty reference, which must not start +with `-`; Docker Agent validates the referenced local file or registry entry. +Supported `integration_options` are `agent` and `safety`; safety must be +`strict`, `balanced`, `restricted`, or `autonomous`. Set a model using the +step's top-level `model`, not `integration_options.model`. Unknown or malformed +runtime options fail explicitly. + +The legacy `SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS=./agent.yaml` environment +variable remains supported when no per-step reference is supplied. A per-step +reference overrides the entire legacy value, including any flags it contains. +Dispatch uses `run --exec`, adds requested `--json` and `--model` flags, and +places the prompt after `--` so prompt text cannot become CLI options. +See [per-step integration configuration](../reference/workflows.md#per-step-integration-configuration). diff --git a/docs/integrations/droid.md b/docs/integrations/droid.md new file mode 100644 index 0000000000..59461ed698 --- /dev/null +++ b/docs/integrations/droid.md @@ -0,0 +1,35 @@ +# Factory Droid + +Install [Factory Droid](https://docs.factory.ai/cli/getting-started/overview) before setup. +The integration key is `droid`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration droid +``` + +For an existing Spec Kit project, use `specify integration install droid`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.factory/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +Generated skills are both user- and model-invocable. + +## Workflow Dispatch + +Workflow steps use `droid exec `, forwarding `--model` and requesting +`--output-format json` when appropriate. Spec Kit does not add a +permission-bypass flag. Operators can explicitly configure permission flags +through `SPECKIT_INTEGRATION_DROID_EXTRA_ARGS`; those arguments follow Spec +Kit's model/output flags and may override them under duplicate-flag parsing. +There are no integration-specific setup options. diff --git a/docs/integrations/dsh.md b/docs/integrations/dsh.md new file mode 100644 index 0000000000..01561c08bd --- /dev/null +++ b/docs/integrations/dsh.md @@ -0,0 +1,31 @@ +# DeepSeek Harness + +Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) before setup. +The integration key is `dsh`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration dsh +``` + +For an existing Spec Kit project, use `specify integration install dsh`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.dsh/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +## Workflow Dispatch + +Workflow steps use `dsh --profile headless `. The adapter ignores +the workflow `model` and structured-output requests: the headless profile +returns the last assistant message as plain text. +There are no integration-specific setup options. diff --git a/docs/integrations/firebender.md b/docs/integrations/firebender.md new file mode 100644 index 0000000000..cd4a6fad8d --- /dev/null +++ b/docs/integrations/firebender.md @@ -0,0 +1,30 @@ +# Firebender + +Install [Firebender](https://firebender.com/) in Android Studio or IntelliJ +before setup. The integration key is `firebender`; no separate CLI is required. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration firebender +``` + +For an existing Spec Kit project, use `specify integration install firebender`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Commands are installed as `.firebender/commands/speckit..mdc`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Workflow Limitation + +This integration does not support CLI dispatch for workflow command or prompt +steps. It installs IDE commands only and has no integration-specific setup +options. diff --git a/docs/integrations/forge.md b/docs/integrations/forge.md new file mode 100644 index 0000000000..9240135e91 --- /dev/null +++ b/docs/integrations/forge.md @@ -0,0 +1,36 @@ +# Forge + +Install [Forge](https://forgecode.dev/) before setup. +The integration key is `forge`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration forge +``` + +For an existing Spec Kit project, use `specify integration install forge`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.forge/commands/`, using dotted +filenames such as `speckit.specify.md`. Their frontmatter command names are +hyphenated, such as `speckit-specify`; filenames and invocation names differ. +Invoke them in the agent's chat as `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension, not dotted commands. + +Forge templates use `{{parameters}}` for arguments. Spec Kit strips incompatible +`handoffs` frontmatter during core setup. + +## Workflow Dispatch + +Workflow steps use `forge -p `. The adapter does not forward a configured +`model` or add a structured-output flag. Select the model in Forge's own +configuration, for example with `forge config set model`. +There are no integration-specific setup options. diff --git a/docs/integrations/gemini.md b/docs/integrations/gemini.md new file mode 100644 index 0000000000..81c9923242 --- /dev/null +++ b/docs/integrations/gemini.md @@ -0,0 +1,34 @@ +# Gemini CLI + +Install [Gemini CLI](https://github.com/google-gemini/gemini-cli) before setup. +The integration key is `gemini`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration gemini +``` + +For an existing Spec Kit project, use `specify integration install gemini`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +TOML commands are installed as `.gemini/commands/speckit..toml`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Runtime Events and Workflow Dispatch + +Native events use `.gemini/settings.json`. The integration maps prompt-submit +and stop events to `BeforeAgent` and `AfterAgent`, and converts hook timeouts +to milliseconds. `--integration-options="--events false"` disables Spec Kit +event handlers. See [runtime events](cli.md#runtime-events). + +Workflow steps use `gemini -p `, with `-m` when a model is configured +and `--output-format json` when structured output is requested. diff --git a/docs/integrations/generic.md b/docs/integrations/generic.md new file mode 100644 index 0000000000..c37ed772e1 --- /dev/null +++ b/docs/integrations/generic.md @@ -0,0 +1,57 @@ +# Generic: Bring Your Own Agent + +Use the `generic` integration for an AI coding agent not covered by a built-in +integration. Supply a project-local output directory with `--commands-dir`. +Spec Kit does not require a particular agent CLI for this integration. + +## Multi-Install Safety + +This integration is not declared multi-install safe because it uses dynamic +output paths. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration generic --integration-options="--commands-dir .myagent/cmds" +``` + +For an existing Spec Kit project: + +```bash +specify integration install generic --integration-options="--commands-dir .myagent/cmds" +``` + +See [integration management](cli.md) for activation, upgrades, and removal. + +## Output Options and Invocation + +| Option | Description | +| --- | --- | +| `--commands-dir ` | Required. Project-local output directory for commands or skills. | +| `--skills` | Write `speckit-/SKILL.md` directories instead of flat `speckit..md` files. | + +Default command references use `/speckit.specify` and `/speckit.bug.assess`. +Skills mode changes command references and next-step guidance to +`/speckit-specify` and `/speckit-bug-assess`: + +```bash +specify integration install generic --integration-options="--commands-dir .myagent/skills --skills" +``` + +Your agent must support the selected file layout and invocation style; Spec Kit +does not add native command discovery to the agent. + +## Extensions + +Once `generic` is the active integration, `specify extension add` registers +extension commands in its configured `--commands-dir`, as command files or +skills according to `--skills`. `specify extension remove` removes unchanged +extension-owned artifacts while leaving core commands, user files, and edited +extension files intact. + +## Workflow Limitation + +The generic integration does not support CLI dispatch for workflow command or +prompt steps. Selecting an output directory does not configure an executable +or teach Spec Kit how to invoke an arbitrary agent CLI. diff --git a/docs/integrations/goose.md b/docs/integrations/goose.md new file mode 100644 index 0000000000..47280cdd6d --- /dev/null +++ b/docs/integrations/goose.md @@ -0,0 +1,38 @@ +# Goose + +Install [Goose](https://goose-docs.ai/) before setup. +The integration key is `goose`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration goose +``` + +For an existing Spec Kit project, use `specify integration install goose`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Recipes + +Goose uses YAML recipes installed as `.goose/recipes/speckit..yaml`. +Spec Kit workflow dispatch translates `/speckit.` invocations into +recipe execution, passing trailing arguments as the recipe's `args` parameter. +Use Goose's recipe interface for interactive execution rather than assuming +the recipes are skills. + +## Workflow Dispatch + +Dispatch uses `goose run --recipe ` for `/speckit.` prompts, +and `goose run -t ` for other prompt text, including non-Spec-Kit +slash commands. A configured `--model` and requested `--output-format json` +are forwarded. + +Avoid repeating single-value flags such as `--model`, `--recipe`, or +`--output-format` in `SPECKIT_INTEGRATION_GOOSE_EXTRA_ARGS`; Goose rejects +duplicate occurrences rather than using the last value. +There are no integration-specific setup options. diff --git a/docs/integrations/grok.md b/docs/integrations/grok.md new file mode 100644 index 0000000000..4e3c8a8585 --- /dev/null +++ b/docs/integrations/grok.md @@ -0,0 +1,31 @@ +# Grok Build + +Install [Grok Build](https://docs.x.ai/build/overview) before setup. +The integration key is `grok`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration grok +``` + +For an existing Spec Kit project, use `specify integration install grok`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.grok/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +## Workflow Permissions + +Workflow steps use `grok -p --always-approve`, which automatically +approves tool executions. Run workflows only where that permission is intended. +A configured `--model` and requested `--output-format json` are forwarded. +There are no integration-specific setup options. diff --git a/docs/integrations/hermes.md b/docs/integrations/hermes.md new file mode 100644 index 0000000000..ec90f4aadd --- /dev/null +++ b/docs/integrations/hermes.md @@ -0,0 +1,47 @@ +# Hermes + +Install [Hermes Agent](https://github.com/NousResearch/hermes-agent) before setup. +The integration key is `hermes`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. Its skills are shared across +projects in the same user's home directory. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration hermes +``` + +For an existing Spec Kit project, use `specify integration install hermes`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Unlike project-local skills integrations, Hermes installs skills globally as +`~/.hermes/skills/speckit-/SKILL.md`. +Invoke them in Hermes's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +An empty project-local `.hermes/skills/` marker enables integration detection; +the generated core skill files themselves are not copied into the project. +The optional `--integration-options="--skills"` flag restates the default. + +## Global Ownership and Removal + +Setup can replace another project's global Spec Kit skill files. + +**Uninstall removes every global `speckit-*` skill directory, even if edited +and even without `--force`.** These global files are not protected by the +project-local manifest's modified-file checks. Back up customizations before +uninstalling or switching away from Hermes. An empty project-local marker is +also removed; non-Spec-Kit global skills remain. + +## Workflow Dispatch + +Workflow steps use `hermes chat -Q`. Slash-prefixed prompts select a skill with +`-s`; remaining text is passed with `-q`. Other prompts use `-q` directly. +The adapter forwards a configured model with `-m` and requests `--json` for +structured output. diff --git a/docs/integrations/index.md b/docs/integrations/index.md new file mode 100644 index 0000000000..a457670826 --- /dev/null +++ b/docs/integrations/index.md @@ -0,0 +1,146 @@ +# Integrations + +Integrations connect Spec Kit to your AI coding agent through commands, skills, +or recipes. Use [none](none.md) for shared scaffolding without an agent. +Choose an integration below for prerequisites, setup, invocation syntax, +and integration-specific options or limitations. + +## Set Up Your Agent + +See the [installation guide](../installation.md) for CLI prerequisites and +installation, and the [SDD quickstart](../quickstart.md) for your first process. + +For a new project: + +```bash +specify init my-project --integration +``` + +Invoke process commands inside your coding agent, not in the terminal. +The documentation commonly uses `/speckit.*` notation, but your agent may use +hyphenated skills, `$` skills, or another native form. See your integration's +page and the [command invocation comparison](cli.md#command-invocation). + +## Adding Another Agent + +In an initialized project, use +[`specify integration install `](cli.md#install-an-integration). +Check the agent's guide for its multi-install safety status and follow the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +Installing another integration does not change the default. Use +[`specify integration use `](cli.md#use-an-installed-integration) +to activate it. + +## Removing an Agent + +Use [`specify integration uninstall `](cli.md#uninstall-an-integration) +to remove an agent's Spec Kit integration, not the agent application itself. +See the uninstall reference for modified-file handling and cleanup exceptions. + +To replace an integration instead, use +[`specify integration switch `](cli.md#switch-to-a-different-integration). + +## Working in a Team + +Mixed-agent teams can start from an agent-neutral project: + +```bash +specify init my-project --integration none +``` + +Each developer switches to their chosen agent in their local checkout: + +```bash +specify integration switch +``` + +After development, switch back before staging the commit: + +```bash +specify integration switch none +``` + +> [!IMPORTANT] +> Do not manually edit Spec Kit-generated agent commands or skills. Maintain +> customizations in reviewed [presets](../reference/presets.md) or +> [project-local overrides](../guides/customization.md#project-local-overrides-and-resolution). +> Before committing, use +> [`specify integration status`](cli.md#report-integration-status) to verify +> that `none` is the only installed and default integration. Review the Git diff +> and any retained agent files. + +Teams can add CI checks for the committed baseline and optional pre-commit +checks of staged files. + +## Choose an Integration + +Use the exact key shown below with `--integration `. CLI-based integrations +require the agent's CLI to be installed; IDE-based integrations run through the +agent's chat window in your IDE. Each page links to the agent's installation documentation. + +| Integration | Key | +| --- | --- | +| [Alquimia AI](alquimia.md) | `alquimia` | +| [Amp](amp.md) | `amp` | +| [Antigravity](agy.md) | `agy` | +| [Auggie CLI](auggie.md) | `auggie` | +| [Claude Code](claude.md) | `claude` | +| [Cline](cline.md) | `cline` | +| [CodeBuddy CLI](codebuddy.md) | `codebuddy` | +| [Codex CLI](codex.md) | `codex` | +| [Command Code](command-code.md) | `command-code` | +| [Cursor](cursor-agent.md) | `cursor-agent` | +| [DeepSeek Harness](dsh.md) | `dsh` | +| [Devin for Terminal](devin.md) | `devin` | +| [Docker Agent](docker-agent.md) | `docker-agent` | +| [Factory Droid](droid.md) | `droid` | +| [Firebender](firebender.md) | `firebender` | +| [Forge](forge.md) | `forge` | +| [Gemini CLI](gemini.md) | `gemini` | +| [GitHub Copilot](copilot.md) | `copilot` | +| [Goose](goose.md) | `goose` | +| [Grok Build](grok.md) | `grok` | +| [Hermes](hermes.md) | `hermes` | +| [IBM Bob](bob.md) | `bob` | +| [Junie](junie.md) | `junie` | +| [Kilo Code](kilocode.md) | `kilocode` | +| [Kimi Code](kimi.md) | `kimi` | +| [Kiro CLI](kiro-cli.md) | `kiro-cli` | +| [Lingma](lingma.md) | `lingma` | +| [MiniMax Code](mcode.md) | `mcode` | +| [Mistral Vibe](vibe.md) | `vibe` | +| [Muse Code](muse.md) | `muse` | +| [None: shared scaffolding only](none.md) | `none` | +| [Oh My Pi](omp.md) | `omp` | +| [opencode](opencode.md) | `opencode` | +| [Pi Coding Agent](pi.md) | `pi` | +| [Qoder CLI](qodercli.md) | `qodercli` | +| [Qwen Code](qwen.md) | `qwen` | +| [RovoDev](rovodev.md) | `rovodev` | +| [SHAI (OVHcloud)](shai.md) | `shai` | +| [Tabnine CLI](tabnine.md) | `tabnine` | +| [Trae](trae.md) | `trae` | +| [ZCode](zcode.md) | `zcode` | +| [Zed](zed.md) | `zed` | +| [Generic: bring your own agent](generic.md) | `generic` | + +## Shared Management and External Integrations + +The [integration CLI reference](cli.md) documents shared +installation, upgrade, removal, status, catalogs, and default-selection behavior. +Those rules apply across integrations rather than being repeated on each page. +The individual guides also identify whether workflow CLI dispatch is supported; +an IDE setup that needs no CLI does not imply that workflow steps can run +without one. + +For agents not listed here, use the [generic integration](generic.md) or +[discover an external adapter](cli.md#search-available-integrations). +Review external adapter code before authorizing its execution. Catalog discovery +is not a security endorsement; the default community catalog is discovery-only. +See [catalog-installed external adapters](cli.md#catalog-installed-external-adapters) +for trust and installation requirements. + +The [catalog reference](catalog.md) describes descriptor and catalog metadata. +See [contributing integrations](contributing.md) to develop a built-in +integration or publish an external adapter. diff --git a/docs/integrations/junie.md b/docs/integrations/junie.md new file mode 100644 index 0000000000..5a0d141b97 --- /dev/null +++ b/docs/integrations/junie.md @@ -0,0 +1,34 @@ +# Junie + +Install [Junie](https://junie.jetbrains.com/) before setup. +The integration key is `junie`; Specify checks for its CLI. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration junie +``` + +For an existing Spec Kit project, use `specify integration install junie`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.junie/commands/`, using hyphenated +filenames such as `speckit-specify.md`. +Invoke them in Junie's chat as `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension, not dotted commands. + +Handoff references and extension/preset command content are also normalized to +hyphenated names. + +## Workflow Dispatch + +Workflow steps use `junie -p `, with `--model` when configured and +`--output-format json` when structured output is requested. +There are no integration-specific setup options. diff --git a/docs/integrations/kilocode.md b/docs/integrations/kilocode.md new file mode 100644 index 0000000000..8ffc4029b1 --- /dev/null +++ b/docs/integrations/kilocode.md @@ -0,0 +1,38 @@ +# Kilo Code + +Install [Kilo Code](https://github.com/Kilo-Org/kilocode) in your IDE before setup. +The integration key is `kilocode`; no separate CLI is required. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration kilocode +``` + +For an existing Spec Kit project, use `specify integration install kilocode`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.kilo/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +Legacy `.kilocode/workflows/` installations remain supported as a registration +fallback. + +Upgrade migrates manifest-tracked core commands to `.kilo/commands/`. If preset +command overrides affect the legacy directory, the upgrade is refused before +changing files; remove the presets, upgrade, then reinstall them. An unreadable +preset registry also blocks that migration. + +## Workflow Limitation + +This integration does not support CLI dispatch for workflow command or prompt +steps. It installs IDE commands only and has no integration-specific setup +options. diff --git a/docs/integrations/kimi.md b/docs/integrations/kimi.md new file mode 100644 index 0000000000..9cf3809228 --- /dev/null +++ b/docs/integrations/kimi.md @@ -0,0 +1,61 @@ +# Kimi Code + +Install [Kimi Code](https://code.kimi.com/) before setup. +The integration key is `kimi`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration kimi +``` + +For an existing Spec Kit project, use `specify integration install kimi`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.kimi-code/skills/speckit-/SKILL.md`. +Invoke them in Kimi's chat using the skill-colon prefix, for example +`/skill:speckit-specify` or `/skill:speckit-bug-assess` for the installed bug +extension. + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. + +## Legacy Migration + +Pass `--integration-options="--migrate-legacy"` when upgrading an old +installation to move skills from `.kimi/skills/` to `.kimi-code/skills/`. +Migration also converts dotted skill names such as `speckit.xxx` to hyphenated +names such as `speckit-xxx`: + +```bash +specify integration upgrade kimi --integration-options="--migrate-legacy" +``` + +Setup writes the new skills first. A legacy directory is moved only if its +new target does not exist. If a target already exists, the old directory is +removed only when both `SKILL.md` files are byte-identical and the legacy +directory has no additional files. Differing legacy content and extra user +files are retained for manual reconciliation. Symlinked legacy paths are +skipped; symlinked destination components are rejected. + +## Legacy Cleanup on Uninstall + +Normal manifest-tracked files use the shared modified-file protection. In +addition, teardown removes legacy `.kimi/skills/speckit-*` and `speckit.*` +directories identified by generated `metadata.author` and `metadata.source`. +That legacy cleanup does not compare recorded hashes or require `--force`; +back up edited legacy skills and additional files inside those directories +before uninstalling. + +## Workflow Dispatch + +Workflow steps use `kimi -p ` with `/skill:speckit-` +invocations and forward a configured `--model`. Structured-output requests use +`--output-format stream-json` (JSONL events), not the unsupported `json` value. diff --git a/docs/integrations/kiro-cli.md b/docs/integrations/kiro-cli.md new file mode 100644 index 0000000000..17c4b3da90 --- /dev/null +++ b/docs/integrations/kiro-cli.md @@ -0,0 +1,39 @@ +# Kiro CLI + +Install [Kiro CLI](https://kiro.dev/docs/cli/) before setup. +The integration key is `kiro-cli`. The executable compatibility check also +accepts `kiro`, but `kiro` is not a registered integration key. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration kiro-cli +``` + +For an existing Spec Kit project, use `specify integration install kiro-cli`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Prompts + +Markdown prompts are installed under `.kiro/prompts/`. +Spec Kit uses dotted names such as `speckit.specify`; use Kiro's +[prompt interface](https://kiro.dev/docs/cli/chat/manage-prompts/) to select them. + +Kiro CLI does not substitute `$ARGUMENTS` in file-based prompts. Spec Kit +therefore renders a prose fallback instructing the model to take the argument +from the conversation. See +[github/spec-kit#1926](https://github.com/github/spec-kit/issues/1926). + +## Workflow Dispatch + +Workflow steps use the `kiro-cli` executable with `-p `, forwarding +`--model` and requesting `--output-format json` when appropriate. +Tool detection also recognizes the `kiro` executable, but the adapter's default +dispatch executable remains `kiro-cli`. If only `kiro` is available, set +`SPECKIT_INTEGRATION_KIRO_CLI_EXECUTABLE` to its path for workflow dispatch. +There are no integration-specific setup options. diff --git a/docs/integrations/lingma.md b/docs/integrations/lingma.md new file mode 100644 index 0000000000..f4ce74dbbb --- /dev/null +++ b/docs/integrations/lingma.md @@ -0,0 +1,32 @@ +# Lingma + +Install [Lingma](https://lingma.aliyun.com/) in your IDE before setup. +The integration key is `lingma`; no separate CLI is required. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration lingma +``` + +For an existing Spec Kit project, use `specify integration install lingma`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed automatically as `.lingma/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. + +## Workflow Limitation + +This integration does not support CLI dispatch for workflow command or prompt +steps; its supported path is the IDE skills interface. diff --git a/docs/integrations/mcode.md b/docs/integrations/mcode.md new file mode 100644 index 0000000000..e094a2b885 --- /dev/null +++ b/docs/integrations/mcode.md @@ -0,0 +1,37 @@ +# MiniMax Code + +Install [MiniMax Code](https://github.com/MiniMax-AI/minimax-code) before setup. +The integration key is `mcode`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration mcode +``` + +For an existing Spec Kit project, use `specify integration install mcode`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.minimax/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. + +## Headless Permissions + +Headless workflow dispatch uses `--permission full` so tool actions are not +blocked by headless permission gating. Set +`SPECKIT_INTEGRATION_MCODE_EXTRA_ARGS="--permission smart"` to use MiniMax +Code's stricter policy. + +Dispatch uses `mcode exec `. A configured `--model` and requested +`--output-format json` are forwarded. diff --git a/docs/integrations/muse.md b/docs/integrations/muse.md new file mode 100644 index 0000000000..9739e4624a --- /dev/null +++ b/docs/integrations/muse.md @@ -0,0 +1,34 @@ +# Muse Code + +Install [Muse Code](https://dev.meta.ai/docs/muse-code) before setup. +The integration key is `muse`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration muse +``` + +For an existing Spec Kit project, use `specify integration install muse`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.agents/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. +This directory is shared with other integrations, so do not assume their +generated skills can coexist without overlap. + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. + +## Workflow Dispatch + +Workflow steps use `muse exec `, with `--model` when configured and +`--json` when structured output is requested. diff --git a/docs/integrations/none.md b/docs/integrations/none.md new file mode 100644 index 0000000000..c39c2b17b5 --- /dev/null +++ b/docs/integrations/none.md @@ -0,0 +1,43 @@ +# None: Shared Scaffolding Only + +Use the `none` integration for an agent-neutral project. It installs shared +`.specify/` scaffolding without agent-specific commands, skills, settings, or +hooks. No coding agent is required. + +## Multi-Install Safety + +This integration is declared multi-install safe because it generates no +agent-specific files. Other installed integrations must also be declared safe +to coexist without `--force`. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration none +``` + +To replace the current default integration in an existing project: + +```bash +specify integration switch none +``` + +If `none` is already installed, `switch` only selects it as the default; +it does not remove other integrations. See +[integration management](cli.md) for installation, activation, and cleanup. + +## Shared Files and Removal + +Templates, scripts, constitution, bundled workflows, and project metadata remain +available under `.specify/`. The integration's generated-file manifest is empty; +uninstalling `none` does not remove shared scaffolding or unowned files. + +For an optional mixed-agent team approach, see +[Working in a Team](index.md#working-in-a-team). + +## Workflow Limitation + +This integration cannot dispatch workflow command or prompt steps. Switch to +an agent integration that supports CLI dispatch to run those steps. +There are no integration-specific setup options. diff --git a/docs/integrations/omp.md b/docs/integrations/omp.md new file mode 100644 index 0000000000..b32a3fc6f4 --- /dev/null +++ b/docs/integrations/omp.md @@ -0,0 +1,31 @@ +# Oh My Pi + +Install [Oh My Pi](https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent) before setup. +The integration key is `omp`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration omp +``` + +For an existing Spec Kit project, use `specify integration install omp`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown slash commands are installed under `.omp/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Workflow Dispatch + +Workflow steps use `omp --print `; `--print` enables one-shot mode +and the prompt is positional. The adapter forwards a configured `--model` and +uses `--mode json`, not `--output-format`, for structured output. +There are no integration-specific setup options. diff --git a/docs/integrations/opencode.md b/docs/integrations/opencode.md new file mode 100644 index 0000000000..4453b31c3a --- /dev/null +++ b/docs/integrations/opencode.md @@ -0,0 +1,39 @@ +# opencode + +Install [opencode](https://opencode.ai/) before setup. +The integration key is `opencode`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration opencode +``` + +For an existing Spec Kit project, use `specify integration install opencode`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.opencode/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +Legacy `.opencode/command/` installations remain a registration fallback when +the canonical directory does not exist. + +## Runtime Events and Workflow Dispatch + +Native events use `.opencode/plugin/speckit-events.ts` rather than a JSON hook +map; Spec Kit merges its plugin reference into `opencode.json`. +`--integration-options="--events false"` disables Spec Kit event handlers. +See [runtime events](cli.md#runtime-events). + +Workflow steps use `opencode run`. Slash-prefixed prompts become +`--command ` with the remaining text as the message; other prompts are +passed as message text. The adapter forwards a configured model with `-m` and +requests `--format json` for structured output. diff --git a/docs/integrations/pi.md b/docs/integrations/pi.md new file mode 100644 index 0000000000..92dad03b8f --- /dev/null +++ b/docs/integrations/pi.md @@ -0,0 +1,35 @@ +# Pi Coding Agent + +Install [Pi Coding Agent](https://pi.dev) before setup. +The integration key is `pi`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration pi +``` + +For an existing Spec Kit project, use `specify integration install pi`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Prompts + +Markdown prompts are installed under `.pi/prompts/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Workflow Dispatch and Tooling + +Workflow steps use `pi -p `, with `--model` when configured and +`--output-format json` when structured output is requested. +There are no integration-specific setup options. + +This integration scaffolds prompt files; it does not install or configure MCP +servers. Commands requiring GitHub tools need that tooling configured in Pi +separately. See +[Pi extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions). diff --git a/docs/integrations/qodercli.md b/docs/integrations/qodercli.md new file mode 100644 index 0000000000..33fb8fd984 --- /dev/null +++ b/docs/integrations/qodercli.md @@ -0,0 +1,36 @@ +# Qoder CLI + +Install [Qoder CLI](https://qoder.com/cli) before setup. +The integration key is `qodercli`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration qodercli +``` + +For an existing Spec Kit project, use `specify integration install qodercli`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.qoder/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +The skills layout replaces legacy `.qoder/commands/` scanning. When enabled +extensions are re-registered, old flat extension command files are retired +only after their replacement skill files exist. Back up edits to those legacy +extension commands before re-registration: that retirement does not compare +their content hashes. + +## Workflow Dispatch + +Workflow steps use `qodercli -p `, with `--model` when configured and +`--output-format json` when structured output is requested. +There are no integration-specific setup options; skills mode is unconditional. diff --git a/docs/integrations/qwen.md b/docs/integrations/qwen.md new file mode 100644 index 0000000000..91fa80d0a5 --- /dev/null +++ b/docs/integrations/qwen.md @@ -0,0 +1,33 @@ +# Qwen Code + +Install [Qwen Code](https://github.com/QwenLM/qwen-code) before setup. +The integration key is `qwen`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration qwen +``` + +For an existing Spec Kit project, use `specify integration install qwen`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.qwen/commands/`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Runtime Events and Workflow Dispatch + +Native events use `.qwen/settings.json`, with hook timeouts converted to +milliseconds. `--integration-options="--events false"` disables Spec Kit event +handlers. See [runtime events](cli.md#runtime-events). + +Workflow steps use `qwen -p `, with `--model` when configured and +`--output-format json` when structured output is requested. diff --git a/docs/integrations/rovodev.md b/docs/integrations/rovodev.md new file mode 100644 index 0000000000..9875ded4ad --- /dev/null +++ b/docs/integrations/rovodev.md @@ -0,0 +1,39 @@ +# RovoDev + +Install [RovoDev](https://www.atlassian.com/software/rovo-dev) before setup. +The integration key is `rovodev`; runtime dispatch uses `acli rovodev`. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration rovodev +``` + +For an existing Spec Kit project, use `specify integration install rovodev`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills and Prompts + +The integration generates `.rovodev/skills/`, prompt wrappers under +`.rovodev/prompts/`, and `.rovodev/prompts.yml`. +Skills use the `speckit-/SKILL.md` layout. Invoke them in the agent's +chat as `/speckit-specify` or `/speckit-bug-assess` for the installed bug extension. + +Prompt wrappers contain `use skill $ARGUMENTS`. Setup merges manifest +entries by name: generated entries replace matching entries while unmatched +user entries retain their ordering. The merged `prompts.yml` is tracked as a +whole file: if unchanged since setup it is removed on uninstall, even when it +contains previously merged user entries. Back up that manifest if needed. + +## Workflow Dispatch + +Workflow steps use `acli rovodev run `. The executable override +`SPECKIT_INTEGRATION_ROVODEV_EXECUTABLE` replaces `acli`, not the `rovodev` +subcommand. Structured-output requests add `--output-schema` with a result +object schema. The workflow `model` setting is not forwarded. +There are no integration-specific setup options; skills mode is unconditional. diff --git a/docs/integrations/shai.md b/docs/integrations/shai.md new file mode 100644 index 0000000000..b363575556 --- /dev/null +++ b/docs/integrations/shai.md @@ -0,0 +1,33 @@ +# SHAI (OVHcloud) + +Install [SHAI](https://github.com/ovh/shai) before setup. +The integration key is `shai`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration shai +``` + +For an existing Spec Kit project, use `specify integration install shai`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +Markdown commands are installed under `.shai/commands/`, using dotted names +such as `speckit.specify.md`. + +## Workflow Limitation + +Workflow `command` and `prompt` steps cannot run through SHAI. Its CLI accepts +prompt text as arguments, on stdin, or through `shai agent`, but hands it to +its auto-fix agent and never loads `.shai/commands/`, so those steps fail. + +The adapter explicitly declines CLI dispatch rather than reporting success +without running the installed command. There are no integration-specific +setup options. diff --git a/docs/integrations/tabnine.md b/docs/integrations/tabnine.md new file mode 100644 index 0000000000..48612f7f86 --- /dev/null +++ b/docs/integrations/tabnine.md @@ -0,0 +1,34 @@ +# Tabnine CLI + +Install [Tabnine CLI](https://docs.tabnine.com/main/getting-started/tabnine-cli) before setup. +The integration key is `tabnine`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration tabnine +``` + +For an existing Spec Kit project, use `specify integration install tabnine`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Commands + +TOML commands are installed as `.tabnine/agent/commands/speckit..toml`. +Invoke them in the agent's chat using dotted notation, for example +`/speckit.specify` or `/speckit.bug.assess` for the installed bug extension. + +## Runtime Events and Workflow Dispatch + +Native events use `.tabnine/agent/settings.json`, mapping prompt-submit and stop +events to `BeforeAgent` and `AfterAgent`. Hook timeouts are converted to +milliseconds. `--integration-options="--events false"` disables Spec Kit event +handlers. See [runtime events](cli.md#runtime-events). + +Workflow steps use `tabnine -p `, with `-m` when a model is configured +and `--output-format json` when structured output is requested. diff --git a/docs/integrations/trae.md b/docs/integrations/trae.md new file mode 100644 index 0000000000..365c380f2c --- /dev/null +++ b/docs/integrations/trae.md @@ -0,0 +1,32 @@ +# Trae + +Install [Trae](https://www.trae.ai/) in your IDE before setup. +The integration key is `trae`; no separate CLI is required. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration trae +``` + +For an existing Spec Kit project, use `specify integration install trae`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed automatically as `.trae/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills, not legacy command files. + +## Workflow Limitation + +This integration does not support CLI dispatch for workflow command or prompt +steps; its supported path is the IDE skills interface. diff --git a/docs/integrations/vibe.md b/docs/integrations/vibe.md new file mode 100644 index 0000000000..c359bd54e5 --- /dev/null +++ b/docs/integrations/vibe.md @@ -0,0 +1,43 @@ +# Mistral Vibe + +Install [Mistral Vibe](https://github.com/mistralai/mistral-vibe) before setup. +The integration key is `vibe`. The skills layout requires Mistral Vibe +v2.0.0 or newer. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration vibe +``` + +For an existing Spec Kit project, use `specify integration install vibe`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.vibe/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. + +Generated skills are both user- and model-invocable. The optional +`--integration-options="--skills"` flag restates the default. + +## Runtime Events + +Native events use `.vibe/hooks.toml`. Vibe supports only `pre_tool_use`, +`post_tool_use`, and `stop`, mapped to `pre_tool`, `post_tool`, and `post_agent`. +Session-start, session-end, and prompt-submit events are not emitted for Vibe; +unsupported handlers are skipped with a warning. +`--integration-options="--events false"` disables Spec Kit event handlers. +See [runtime events](cli.md#runtime-events). + +## Workflow Dispatch + +Workflow steps use `vibe -p ` and request `--output json` for structured +output. The adapter ignores the workflow `model` setting. Select the model with +Vibe's `active_model` configuration or `VIBE_ACTIVE_MODEL` instead. diff --git a/docs/integrations/zcode.md b/docs/integrations/zcode.md new file mode 100644 index 0000000000..403f3db6c5 --- /dev/null +++ b/docs/integrations/zcode.md @@ -0,0 +1,33 @@ +# ZCode + +Install [ZCode](https://zcode.z.ai/) before setup. +The integration key is `zcode`. + +## Multi-Install Safety + +This integration is declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration zcode +``` + +For an existing Spec Kit project, use `specify integration install zcode`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.zcode/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat with a dollar prefix, for example +`$speckit-specify` or `$speckit-bug-assess` for the installed bug extension. + +The optional `--integration-options="--skills"` flag restates the default; +this integration always scaffolds skills. + +## Workflow Dispatch + +Workflow steps use `zcode -p ` and request `--output-format json` for +structured output. The adapter ignores the workflow `model` setting because +ZCode has no per-invocation model flag; select the model in-session with `/model`. diff --git a/docs/integrations/zed.md b/docs/integrations/zed.md new file mode 100644 index 0000000000..bbcd73988e --- /dev/null +++ b/docs/integrations/zed.md @@ -0,0 +1,32 @@ +# Zed + +Install [Zed](https://zed.dev/) before setup. +The integration key is `zed`; no separate CLI is required. + +## Multi-Install Safety + +This integration is not declared multi-install safe. See the +[shared multi-install rules](cli.md#can-i-install-multiple-integrations-in-the-same-project). + +## Setup + +```bash +specify init my-project --integration zed +``` + +For an existing Spec Kit project, use `specify integration install zed`. +See [integration management](cli.md) for activation, upgrades, and removal. + +## Installed Skills + +Skills are installed as `.agents/skills/speckit-/SKILL.md`. +Invoke them in the agent's chat, for example `/speckit-specify` or +`/speckit-bug-assess` for the installed bug extension. +This directory is shared with other integrations, so do not assume their +generated skills can coexist without overlap. + +## Workflow Limitation + +This integration does not support CLI dispatch for workflow command or prompt +steps. It installs editor skills only and has no integration-specific setup +options; a `--skills` flag is not needed or declared. diff --git a/docs/local-development.md b/docs/local-development.md index 243771614c..26981f89d2 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -102,25 +102,12 @@ ls -l scripts | grep .sh On Windows you will instead use the `.ps1` scripts (no chmod needed). -## 6. Scaffold a Built-In Integration +## 6. Develop 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`. +Follow the [agent integration design](https://github.com/github/spec-kit/blob/main/design/integration.md#adding-an-agent) +for implementation contracts, registration, and behavioral coverage. See +[contributing integrations](integrations/contributing.md) for catalog entries +and submission guidance. ## 7. Run Lint / Basic Checks diff --git a/docs/quickstart.md b/docs/quickstart.md index b477655c0d..2e494bfaf3 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -14,7 +14,7 @@ These are independent processes, not prerequisites for this guide. The process steps here use GitHub Copilot's default skills mode (`/speckit-*`). For other agents or modes, see -[Command invocation](reference/integrations.md#command-invocation). +[Command invocation](integrations/cli.md#command-invocation). Invoke each `/speckit-*` skill separately in your agent's chat and review the result before moving to the next step. These are agent skills, not terminal commands; only CLI installation and project setup use the terminal. diff --git a/docs/reference/agentic-assessment.md b/docs/reference/agentic-assessment.md index d5d48515c5..c65dd54f6b 100644 --- a/docs/reference/agentic-assessment.md +++ b/docs/reference/agentic-assessment.md @@ -14,7 +14,7 @@ specify extension add assess Commands below use `/speckit.assess.*` notation. GitHub Copilot's default skills mode uses `/speckit-assess-*`; other integrations may use a different prefix. -See [Command invocation](integrations.md#command-invocation). +See [Command invocation](../integrations/cli.md#command-invocation). ## Commands and artifacts diff --git a/docs/reference/agentic-bugfix.md b/docs/reference/agentic-bugfix.md index 00df953364..319bb889cd 100644 --- a/docs/reference/agentic-bugfix.md +++ b/docs/reference/agentic-bugfix.md @@ -8,7 +8,7 @@ rather than repairing broken behavior, see [Idea Assessment](agentic-assessment.md). > [!NOTE] -> Commands are written in `/speckit.bug.*` form throughout this page. GitHub Copilot's default skills mode uses `/speckit-bug-*`; some other agents use `$speckit-bug-*` (e.g. Codex, ZCode) or `/skill:speckit-bug-*` (e.g. Kimi). See [Command invocation](integrations.md#command-invocation). +> Commands are written in `/speckit.bug.*` form throughout this page. GitHub Copilot's default skills mode uses `/speckit-bug-*`; some other agents use `$speckit-bug-*` (e.g. Codex, ZCode) or `/skill:speckit-bug-*` (e.g. Kimi). See [Command invocation](../integrations/cli.md#command-invocation). The bug extension is a bundled, opt-in extension. Install it before using these commands: diff --git a/docs/reference/agentic-sdd.md b/docs/reference/agentic-sdd.md index ea60858f30..bef8b1c09d 100644 --- a/docs/reference/agentic-sdd.md +++ b/docs/reference/agentic-sdd.md @@ -9,7 +9,7 @@ For evaluating an idea before committing to a specification, see independent of the SDD process. > [!NOTE] -> Commands are written in `/speckit.*` form throughout this page. GitHub Copilot's default skills mode uses `/speckit-*`; some other agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). See [Command invocation](integrations.md#command-invocation). +> Commands are written in `/speckit.*` form throughout this page. GitHub Copilot's default skills mode uses `/speckit-*`; some other agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). See [Command invocation](../integrations/cli.md#command-invocation). ```text /speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge diff --git a/docs/reference/catalogs.md b/docs/reference/catalogs.md index 959fc1e56e..fc48aeb3c0 100644 --- a/docs/reference/catalogs.md +++ b/docs/reference/catalogs.md @@ -53,7 +53,7 @@ project: | Component type | List active catalogs | Detailed reference | | --- | --- | --- | -| Integrations | `specify integration catalog list` | [Integrations](integrations.md#catalog-management) | +| Integrations | `specify integration catalog list` | [Integrations](../integrations/cli.md#catalog-management) | | Extensions | `specify extension catalog list` | [Extensions](extensions.md#catalog-management) | | Presets | `specify preset catalog list` | [Presets](presets.md#catalog-management) | | Workflows | `specify workflow catalog list` | [Workflows](workflows.md#catalog-management) | @@ -138,7 +138,7 @@ Use the component-specific publishing guidance when authoring catalog entries: | Component type | Publishing guidance | | --- | --- | -| Integrations | [Integration catalog contributions](https://github.com/github/spec-kit/blob/main/integrations/CONTRIBUTING.md) | +| Integrations | [Integration catalog contributions](../integrations/contributing.md) | | Extensions | [Extension Publishing Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md) | | Presets | [Preset Publishing Guide](https://github.com/github/spec-kit/blob/main/presets/PUBLISHING.md) | | Workflows | [Workflow Publishing Guide](https://github.com/github/spec-kit/blob/main/workflows/PUBLISHING.md) | @@ -174,7 +174,7 @@ for installing the CLI offline. External integration adapters have no direct or local installation route. Installing one requires both an install-allowed integration catalog and its referenced archive to remain reachable. See -[Catalog-installed external adapters](integrations.md#catalog-installed-external-adapters). +[Catalog-installed external adapters](../integrations/cli.md#catalog-installed-external-adapters). Catalog metadata alone is not enough for offline installation: every selected release artifact and any bundle-provided dependency must also be reachable or diff --git a/docs/reference/core.md b/docs/reference/core.md index 5e0b80a1d7..82f976e3ed 100644 --- a/docs/reference/core.md +++ b/docs/reference/core.md @@ -10,7 +10,7 @@ specify init [] | Option | Description | | ------------------------ | ------------------------------------------------------------------------ | -| `--integration ` | AI coding agent integration to use (e.g. `copilot`, `claude`, `gemini`). See the [Integrations reference](integrations.md) for all available keys | +| `--integration ` | AI coding agent integration to use (e.g. `copilot`, `claude`, `gemini`). See the [integration directory](../integrations/index.md) for all available keys | | `--integration-options` | Options for the integration (e.g. `--integration-options="--commands-dir .myagent/cmds"`) | | `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | | `--here` | Initialize in the current directory instead of creating a new one | diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md deleted file mode 100644 index af0dbccdcf..0000000000 --- a/docs/reference/integrations.md +++ /dev/null @@ -1,582 +0,0 @@ -# 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 and directory structures for your chosen AI coding agent — so you can start using Spec-Driven Development immediately, regardless of which tool you prefer. - -For shared scaffolding without agent-specific files, use -`specify init my-project --integration none`. Normal `.specify/` metadata remains. -Use `specify integration switch ` to replace it, or -`specify integration install ` followed by `specify integration use ` -to keep both installed. The other integration must also be multi-install safe. - -## Supported AI Coding Agents - -| Agent | Key | Notes | -| ------------------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| [Alquimia AI](https://docs.alquimia.ai) | `alquimia` | Skills-based integration; installs skills into `.alquimia/skills` and invokes them as `/speckit-` | -| [Amp](https://ampcode.com/) | `amp` | | -| [Antigravity (agy)](https://antigravity.google/) | `agy` | Skills-based integration; installs skills into `.agents/skills/` and invokes them as `/speckit-`. In headless non-interactive runs, automatic tool approval via `--dangerously-skip-permissions` can be enabled by setting `SPECKIT_AGY_ALLOW_ALL_TOOLS=1` or `SPECKIT_INTEGRATION_AGY_ALLOW_ALL_TOOLS=1`. | -| [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`. Pass `--integration-options="--no-model-invocation"` to make the core command skills user-invocable only (see [Claude: user-invocable-only skills](#claude-user-invocable-only-skills)). | -| [Cline](https://github.com/cline/cline) | `cline` | IDE-based agent | -| [CodeBuddy CLI](https://www.codebuddy.cn/docs/cli/installation) | `codebuddy` | | -| [Codex CLI](https://github.com/openai/codex) | `codex` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `$speckit-` | -| [Command Code](https://commandcode.ai/docs) | `command-code` | Skills-based integration; installs skills into `.commandcode/skills/` and invokes them as `$speckit-` | -| [Cursor](https://cursor.sh/) | `cursor-agent` | | -| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh` | Skills-based integration; installs skills into `.dsh/skills` and invokes them as `/speckit-` | -| [Devin for Terminal](https://cli.devin.ai/docs) | `devin` | Skills-based integration; installs skills into `.devin/skills/` and invokes them as `/speckit-` | -| [Docker Agent](https://docs.docker.com/ai/docker-agent/) | `docker-agent` | Skills-based integration; installs skills into `.agents/skills/` (the same directory used by Codex and Zed). In the selected agent YAML, enable local skills with `skills: true` and provide filesystem read access. Detects either the standalone `docker-agent` binary or the Docker CLI plugin (`docker agent`). Configure workflow dispatch with `SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS=./agent.yaml`; the Spec Kit prompt is appended after these arguments. Not multi-install safe by default because the skills directory is shared. | -| [Factory Droid](https://docs.factory.ai/cli/getting-started/overview) | `droid` | Skills-based integration; installs skills into `.factory/skills/` and invokes them as `/speckit-` | -| [Firebender](https://firebender.com/) | `firebender` | IDE-based agent for Android Studio / IntelliJ | -| [Forge](https://forgecode.dev/) | `forge` | | -| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | | -| [GitHub Copilot](https://code.visualstudio.com/) | `copilot` | Skills-based by default; installs `speckit-/SKILL.md` under `.github/skills/`. Pass `--integration-options="--commands"` to use the supported commands layout: `.agent.md` files under `.github/agents/`, companion `.prompt.md` files under `.github/prompts/`, and a `.vscode/settings.json` merge. | -| [Goose](https://goose-docs.ai/) | `goose` | Uses YAML recipe format in `.goose/recipes/` | -| [Grok Build](https://docs.x.ai/build/overview) | `grok` | Skills-based integration; installs skills into `.grok/skills` and invokes them as `/speckit-` | -| [Hermes](https://github.com/NousResearch/hermes-agent) | `hermes` | Skills-based integration; installs skills globally into `~/.hermes/skills/` | -| [IBM Bob](https://www.ibm.com/products/bob) | `bob` | Skills-based integration by default; installs skills as `speckit-/SKILL.md` under `.bob/skills/` and invokes them as `/speckit-`. Pass `--integration-options="--legacy-commands"` to scaffold the deprecated Bob 1.x layout (`.bob/commands/*.md`) instead; that flag will be removed in a future release. Existing legacy installs can migrate with `specify integration upgrade bob --integration-options="--skills"`, which converts them to the skills layout and removes the old command files. If preset overrides are installed, the migration is rejected with an actionable error (preset artifacts cannot yet be reconciled across a layout change) — remove the preset(s), migrate, then reinstall them. | -| [Junie](https://junie.jetbrains.com/) | `junie` | | -| [Kilo Code](https://github.com/Kilo-Org/kilocode) | `kilocode` | Installs commands into `.kilo/commands`; legacy `.kilocode/workflows` installs remain supported as a registration fallback | -| [Kimi Code](https://code.kimi.com/) | `kimi` | Skills-based integration; installs into `.kimi-code/skills/`. `--migrate-legacy` moves old `.kimi/skills/` installs to the new paths | -| [Kiro CLI](https://kiro.dev/docs/cli/) | `kiro-cli` | Kiro CLI does not substitute `$ARGUMENTS` in file-based prompts, so Spec Kit ships a prose fallback at render time (see [Manage prompts](https://kiro.dev/docs/cli/chat/manage-prompts/) and issue [#1926](https://github.com/github/spec-kit/issues/1926)). Alias: `--integration kiro` | -| [Lingma](https://lingma.aliyun.com/) | `lingma` | Skills-based integration; skills are installed automatically | -| [MiniMax Code](https://github.com/MiniMax-AI/minimax-code) | `mcode` | Skills-based integration; installs skills into `.minimax/skills` and invokes them as `/speckit-`. Headless workflow dispatch uses `--permission full` so tool actions are not blocked by headless permission gating; set `SPECKIT_INTEGRATION_MCODE_EXTRA_ARGS="--permission smart"` to use MiniMax Code's stricter policy. | -| [Mistral Vibe](https://github.com/mistralai/mistral-vibe) | `vibe` | | -| [Muse Code](https://dev.meta.ai/docs/muse-code) | `muse` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `/speckit-` | -| [Oh My Pi](https://www.npmjs.com/package/@oh-my-pi/pi-coding-agent) | `omp` | Installs slash commands into `.omp/commands` | -| [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` | | -| [RovoDev](https://www.atlassian.com/software/rovo-dev) | `rovodev` | Generates `.rovodev/skills/`, prompt wrappers, and `prompts.yml`; runtime dispatch uses `acli rovodev` | -| [SHAI (OVHcloud)](https://github.com/ovh/shai) | `shai` | Workflow `command` and `prompt` steps can't run through SHAI: its CLI accepts prompt text (as arguments, on stdin, or through `shai agent`), but hands it to its auto-fix agent and never loads `.shai/commands`, so those steps fail | -| [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 | -| [ZCode](https://zcode.z.ai/) | `zcode` | Skills-based integration; installs skills into `.zcode/skills/` and invokes them as `$speckit-` | -| [Zed](https://zed.dev/) | `zed` | Skills-based integration; installs skills into `.agents/skills` and invokes them as `/speckit-` | -| Generic | `generic` | Bring your own agent — use `--integration generic --integration-options="--commands-dir "` for AI coding agents not listed above; add `--skills` for the `speckit-/SKILL.md` layout | - -## Command Invocation - -Invoke Spec Kit's process steps inside your coding agent, not in the terminal. -In GitHub Copilot's default mode, these are skills you invoke in the agent's -chat. CLI installation and setup commands are separate terminal operations. -The steps are the same across integrations, but their spelling depends on the -agent and its installed mode: - -| Integration or mode | SDD example | Extension example | -| --- | --- | --- | -| GitHub Copilot, default skills mode | `/speckit-specify` | `/speckit-bug-assess` | -| Dotted slash-command notation used in the references | `/speckit.specify` | `/speckit.bug.assess` | -| Codex, Command Code, ZCode skills | `$speckit-specify` | `$speckit-bug-assess` | -| Kimi skills | `/skill:speckit-specify` | `/skill:speckit-bug-assess` | - -Use the form exposed by your agent. Copilot's default skills are installed under -`.github/skills/`; its opt-in commands layout is selected with -`--integration-options="--commands"`. In that layout, Copilot CLI can select an -agent through `/agents` or address it directly in a prompt. - -## List Available Integrations - -```bash -specify integration list -``` - -| Option | Description | -| ----------- | ----------------------------------------------------------------------------------------------------------------------- | -| `--catalog` | Also browse the catalog, including external integrations not installed in this project. | - -Shows built-in and trusted installed external integrations, which one is -currently installed, and whether each requires a CLI tool or is IDE-based. -When multiple integrations are installed, the list marks the default integration separately from the other installed integrations. -The list also shows whether each integration is declared multi-install safe. - -## Search Available Integrations - -```bash -specify integration search [query] -``` - -| Option | Description | -| ---------- | ------------------ | -| `--tag` | Filter by tag | -| `--author` | Filter by author | - -Searches the active catalog stack for integrations matching the query. Without a query, lists all available integrations. Must be run inside a Spec Kit project. - -## Integration Info - -```bash -specify integration info -specify integration info --versions -``` - -Shows catalog details for a single integration, including its description, author, license, tags, source catalog, repository (when available), and whether it is currently active. Must be run inside a Spec Kit project. -`--versions` lists the advertised current and historical versions from the -winning catalog, with the current release first and older releases in descending -version order. Discovery-only sources are labeled as such. - -## Install an Integration - -```bash -specify integration install -``` - -| Option | Description | -| ------------------------ | ------------------------------------------------------------------------ | -| `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | -| `--force` | Opt in to installing alongside integrations that are not declared multi-install safe | -| `--integration-options` | Integration-specific options (e.g. `--integration-options="--commands-dir .myagent/cmds"`) | -| `--trust-integration` | After reviewing the code, pre-authorize an external adapter's Python execution without the interactive trust prompt | - -Installs the specified integration into the current project. If another integration is already installed, the command only proceeds automatically when all involved integrations are declared multi-install safe. Otherwise, use `switch` to replace the default integration or pass `--force` to explicitly opt in to multi-install. If the installation fails partway through, it automatically rolls back to a clean state. - -**Catalog history is metadata only.** `integration install` still resolves -registered built-in implementations directly, or the current external adapter -release from an install-enabled catalog, not historical catalog records. -There is no `integration install --version`. The default community catalog -remains discovery-only. - -Installing an additional integration does not change the default integration. Use `specify integration use ` to change the default. - -Installed extensions and presets are not registered for a non-default integration at install time — they follow the currently active (default) integration only. `specify integration use ` (or `switch `) is what rescaffolds them for the newly active integration. - -> **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. - -### Catalog-installed external adapters - -Register a reviewed catalog in the initialized project, then install its adapter: - -```bash -specify integration catalog add https://example.com/catalog.json --name samples -specify integration install sample-agent -specify integration use sample-agent -``` - -Installation prompts for trust **before** downloading/importing Python. For -automation, explicitly authorize code you have reviewed: - -```bash -specify integration install sample-agent --trust-integration -specify integration upgrade sample-agent --trust-integration -``` - -The source must have `install_allowed: true`. The default community catalog is -discovery-only; neither `--force` nor the trust flag bypasses that policy. -Catalog listing/search/info do not import catalog code. Required external entry -fields are a map key matching the descriptor ID, name, version, description, -and an archive `download_url`; an optional explicit `id` must match the map key; -an archive `sha256` digest is recommended. Downloads support ZIP, tar.gz, and tgz, -HTTPS or loopback HTTP, and the existing authenticated GitHub asset flow. -See the [catalog schema](../../integrations/README.md#catalog-schema). -Search advertises `specify integration install ` for install-enabled sources; -discovery-only results do not advertise installation. - -`specify check` probes an external adapter's required descriptor tools rather -than its catalog ID. With no required tools declared, CLI adapters are checked -using their runtime executable; optional tools do not produce missing-tool -errors. These checks do not run the executable or invoke generic version probes. - -A package contains root `integration.yml` and `__init__.py`, not a copied -inventory of Spec Kit's commands. The host renders shared templates through the -adapter and registers installed extension/preset contributions for the default -integration. Code persists under `.specify/integrations/packages//`, -separately from generated agent files and their manifests. New CLI processes -load the trusted package without consulting the catalog. Missing, modified, or -incompatible code is an error, not a silent fallback. Upgrade installs the -catalog's current adapter version; uninstall removes its persisted code while -preserving modified generated files by default. -Metadata-only `workflow status` and `workflow info` remain available without -loading adapter code, including when an installed adapter is damaged. Workflow -execution and resume still report adapter-loading failures explicitly. - -Execution consent is stored in `~/.specify/integration-trust.json`, bound to -the canonical project root, integration ID, and complete verified package -digest. It is checked before loading, even when adapter configuration is -cached. A project's `packages.json` is provenance, not permission; copying -it cannot transfer consent. The managed `.specify/.gitignore` excludes -`integrations/packages/` and `integrations/packages.json`. -Trust-registry updates that would exceed the 1 MiB read limit fail explicitly -before replacing the existing store; previously granted packages remain usable. -After copying a project or changing users, review the adapter and reauthorize -from an install-enabled catalog: - -```bash -specify integration upgrade sample-agent --force --trust-integration -``` - -Forced uninstall also works when package code is untrusted or its entire -directory is missing; it does not import that code. - -For initialization, a project/user catalog or `SPECKIT_INTEGRATION_CATALOG_URL` -can supply an external adapter: - -```bash -specify init my-project --integration sample-agent --trust-integration -``` - -Review the [external adapter API](../../design/integration.md#external-adapter-package-contract) -before publishing a package. No pip installation or source-registry edit is -needed for adapters using the host API and standard library. - -**Version note:** Controlled multi-install support was introduced in Spec Kit 0.8.5. If `specify integration install ` says another integration is already installed and only suggests `switch` or `uninstall`, check your local CLI with `specify version` and upgrade it. Running a one-shot command such as `uvx --from git+https://github.com/github/spec-kit.git specify ...` uses a temporary copy for that command only; it does not update the persistent `specify` executable on your `PATH`. - -## 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. - -Uninstall also removes the extension and preset artifacts registered for the integration. The extensions and presets themselves stay installed. If you uninstall the default integration while other integrations remain, one of them becomes the default, and Spec Kit registers the enabled extensions and presets for it, as `use` does. - -## Switch to a Different Integration - -```bash -specify integration switch -``` - -| Option | Description | -| ------------------------ | ------------------------------------------------------------------------ | -| `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | -| `--force` | Force removal of modified files during uninstall; when the target is already installed, overwrite managed shared templates while changing the default | -| `--refresh-shared-infra` | Also overwrite shared infrastructure files even if you customized them (otherwise customizations are preserved) | -| `--integration-options` | Options for the target integration when it is not already installed | - -If the target integration is not already installed, equivalent to running `uninstall` followed by `install` in a single step. In this mode, `--force` controls whether modified files from the removed integration are deleted. If the target integration is already installed, `switch` only changes the default integration, like `use`; in this mode, `--force` controls whether managed shared templates are overwritten while the default changes. `--integration-options` is rejected for already-installed targets because changing integration options requires reinstalling managed files; run `upgrade --integration-options ...` first, then `use `. Like `use`, `switch` rescaffolds installed extensions and presets for the target integration once it becomes the default. - -## Use an Installed Integration - -```bash -specify integration use -``` - -| Option | Description | -| --------- | --------------------------------------------------- | -| `--force` | Overwrite managed shared templates while changing the default | - -Sets the default integration without uninstalling any other installed integrations. This also refreshes managed shared templates so command references match the new default integration's invocation style. Modified or untracked shared templates are preserved unless `--force` is used. - -`use` is also the activation point for installed extensions and presets: it re-registers every enabled extension's and preset's command overrides (and skills, for skills-mode agents) for the newly active integration, so artifacts installed while a different integration was active are rescaffolded here rather than at install time. - -## Upgrade an Integration - -```bash -specify integration upgrade [] -``` - -| Option | Description | -| ------------------------ | ------------------------------------------------------------------------ | -| `--force` | Overwrite files even if they have been modified | -| `--script sh\|ps\|py` | Script type: `sh` (bash/zsh), `ps` (PowerShell), or `py` (Python) | -| `--integration-options` | Options for the integration | -| `--trust-integration` | Authorize downloading/importing the reviewed replacement external adapter | - -Reinstalls an installed integration with updated templates and commands (e.g., after upgrading Spec Kit). Defaults to the default integration; if a key is provided, it must be one of the installed integrations. 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. Shared templates stay aligned with the default integration even when upgrading a non-default integration. - -Enabled extensions and presets are re-registered only when upgrading the currently active (default) integration. A non-default upgrade still refreshes that integration's core commands, but does not re-register its extension or preset layers — `use`/`switch` that integration afterward to rescaffold them. - -If the generated-file manifest is missing, upgrade reports that there is nothing -to upgrade and leaves the installed adapter package, generated files, and local -recovery ownership unchanged, including with `--force`. Replacement code is -persisted only after the upgrade regenerates the managed files successfully. - -If an upgrade would change an integration between command and skills layouts while preset artifacts are registered for it, the upgrade is rejected before changing files. Remove the affected presets, run the layout-changing upgrade, then reinstall them. - -For external adapters, `upgrade --force` and `uninstall --force` can also recover -missing, modified, incompatible, or import-failing installed code using validated -user-local registrar/path ownership metadata, rejecting edited project cleanup -claims and overlap with another integration's root. Without local ownership -proof, old-only generated files are preserved with a manual-cleanup warning. -Shared event dispatchers and partially owned native settings are preserved -during damaged-adapter fallback cleanup, even with `--force`. Recovery uses -the user-local ownership modes, not editable project claims. Successful event -refreshes keep that local record current; older records without modes preserve -unproven files rather than risking user-data deletion. -A trusted replacement can still overwrite files at its declared destination -under `upgrade --force`. Recovery is reported explicitly and does not bypass source policy -or the replacement package's trust decision. Failed lifecycle operations restore -only operation-owned changes. Independent workflow progress and unowned user -files are preserved; conflicting concurrent managed-file edits are reported with -retained recovery snapshots. -Rollback snapshots are lazy and bounded to 128 MiB of file content and 4,096 -entries per operation; an oversized snapshot refuses the affected mutation. -No-op operations do not copy agent directories or the installed package store. -Custom adapters must journal writes to existing files through the host's -before-write helpers or `IntegrationManifest.record_file()`. Recording a new -or unchanged file afterward remains supported; an unobserved overwrite is -reported as unrecoverable rather than deleting the resulting file. -Host writes reject symlinked destinations and ancestors before writing; forced -removal of an owned leaf symlink unlinks only the link. Concurrent workflow -dispatch pins the requested project's adapter and verified imports until the -dispatch finishes, without serializing independent agent processes. - -## Report Integration Status - -```bash -specify integration status -specify integration status --json -``` - -Reports the current project's integration status without changing files. The -status report includes the default integration, installed integrations, -multi-install safety, missing managed files, modified managed files, invalid -manifest paths, shared Spec Kit infrastructure health, unchecked manifests, and -the target integration for default-sensitive shared templates. The JSON form is -intended for CI and coding agents that need stable machine-readable status data; -it also reports the raw recorded integrations and the integration manifests that -were checked when state repair heuristics differ from the recorded file. -The command exits 0 when the report status is `ok` or `warning`; it exits 1 -only when the report status is `error`. In JSON output, `multi_install_safe` -is `null` when no installed integration set can be evaluated, such as when the -integration state is missing, unreadable, lacks a valid recorded integration -list, or records no installed integrations. - -## Catalog Management - -Integration catalogs control where the discovery commands (`search` and `info`) look for integrations. Catalogs are checked in priority order. - -Catalog management, `integration list --catalog`, and `integration info` do not -execute adapter code. Ordinary integration listing, setup, selection, status, -registration, and workflow dispatch load trusted installed implementations. - -### List Catalogs - -```bash -specify integration catalog list -``` - -Shows the active catalog sources. Project-level sources (when configured) are removable by index; otherwise the active sources are shown as non-removable. - -### Add a Catalog - -```bash -specify integration catalog add -``` - -| Option | Description | -| --------------- | ----------------------------- | -| `--name ` | Optional name for the catalog | - -Adds a custom catalog URL to the project's `.specify/integration-catalogs.yml`. The URL must use HTTPS (except `http://localhost`, `http://127.0.0.1`, or `http://[::1]` for local testing). - -Re-adding the same URL with the same name succeeds without changing the configuration; a different name is rejected. - -### Remove a Catalog - -```bash -specify integration catalog remove -``` - -Removes a project catalog source by its 0-based index in `catalog list`. - -### Catalog Resolution Order - -Catalogs are resolved in this order (first match wins): - -1. **Environment variable** — `SPECKIT_INTEGRATION_CATALOG_URL` overrides all catalogs -2. **Project config** — `.specify/integration-catalogs.yml` -3. **User config** — `~/.specify/integration-catalogs.yml` -4. **Built-in defaults** — official catalog + community catalog - -### Historical Integration Metadata - -An integration entry may retain the existing top-level fields for its advertised -current release and add a `releases` mapping of historical version to metadata. -Single-version entries remain valid without a `releases` key. For example: - -```json -{ - "schema_version": "1.0", - "integrations": { - "my-agent": { - "id": "my-agent", - "name": "My Agent", - "author": "example", - "version": "2.0.0", - "description": "Current release", - "repository": "https://example.com/my-agent/current", - "releases": { - "1.0.0": { - "description": "Historical release", - "repository": "https://example.com/my-agent/v1", - "requires": {"speckit_version": ">=0.7"} - } - } - } - } -} -``` - -The top-level fields retain their original meaning for older clients and for -unqualified `search`, `info`, `list --catalog`, and `install` commands. Historical -records may contain `name`, `description`, `author`, `repository`, `license`, -`tags` (a list of strings), and `requires` (a mapping). Shared identity, name, -author, and source policy are retained; current-only metadata such as -description, repository, tags, and requirements is **not** inherited by an -older release unless explicitly supplied in its record. Release records cannot -override `id`, `version`, `releases`, or source policy, and cannot advertise -download URLs or archives. - -For programmatic metadata lookup, -`IntegrationCatalog.get_integration_info(id, version="1.0.0")` selects the -exact historical record from the winning source, or returns `None` if that -version is missing. `get_integration_versions(id)` returns the versions -advertised by that same source. PEP 440-equivalent spellings (such as `v1.0` -and `1.0.0`) match the same release while retaining its catalog spelling. -The current release must not be repeated in `releases`; malformed records and -duplicate equivalent versions are rejected. An absent version never falls -through to a lower-priority source or silently selects current. These lookups -do not install an integration. - -## Integration-Specific Options - -Some integrations accept additional options via `--integration-options`: - -| Integration | Option | Description | -| ----------- | ------------------- | -------------------------------------------------------------- | -| `generic` | `--commands-dir` | Required. Directory for command files | -| `generic` | `--skills` | Render commands and installed extension invocations as `speckit-/SKILL.md` directories under `--commands-dir` instead of flat `speckit..md` files. Command references and next-step guidance switch to `/speckit-`. | -| `kimi` | `--migrate-legacy` | Migrate legacy `.kimi/skills/` installs to `.kimi-code/skills/` (including dotted→hyphenated skill naming, e.g. `speckit.xxx` → `speckit-xxx`) | -| `copilot` | `--commands` | Scaffold `.github/agents/*.agent.md` commands with `.github/prompts/*.prompt.md` companions and merge `.vscode/settings.json` instead of using the default skills layout. | -| `copilot` | `--skills` | Force the default skills layout, overriding an existing commands layout during an explicit migration. | -| `claude` | `--no-model-invocation` | Write `disable-model-invocation: true` into the core Spec Kit command skills so Claude Code runs them only when invoked as `/speckit-` and keeps their descriptions out of its context. See [Claude: user-invocable-only skills](#claude-user-invocable-only-skills). | - -Example: - -```bash -specify integration install generic --integration-options="--commands-dir .myagent/cmds" -specify integration install generic --integration-options="--commands-dir .myagent/skills --skills" -``` - -Once `generic` is the active integration, `specify extension add` registers -extension commands in its configured `--commands-dir` (as command files or -skills according to `--skills`). `specify extension remove` removes unchanged -extension-owned artifacts while leaving core commands, user files, and edited -extension files intact. The deprecated core `speckit.taskstoissues` command -remains available, warns on invocation, and will be removed in a future minor -release. To migrate, run `specify extension add github` and use the recommended -`/speckit.github.taskstoissues` command for dot-command integrations. Slash-hyphen -integrations use `/speckit-github-taskstoissues`; Codex, ZCode, and Command Code -skills use `$speckit-github-taskstoissues`; Kimi uses -`/skill:speckit-github-taskstoissues`. The core command continues its existing -workflow and does not install or enable the extension automatically. - -### Claude: user-invocable-only skills - -By default every Spec Kit skill installed for Claude Code is model-invocable, so -its description is always in Claude's context and counts toward the -skill-listing budget. In projects with many skills this can push other skills -out of the listing. To make the core Spec Kit command skills user-invocable -only: - -```bash -specify init my-project --integration claude --integration-options="--no-model-invocation" -``` - -- Extension skills stay model-invocable, because mandatory extension hooks rely - on the model invoking them. If an extension's mandatory hook runs a core - command (its `command:` is a core `speckit.`), leave this option off: - the model cannot run that hook while the core skill is user-invocable only. -- The option is stored with the integration's other options and reapplied by - `specify integration upgrade claude`. Passing `--integration-options` to - `upgrade` replaces all stored options, so repeat any you want to keep (for - example `--integration-options="--events false --no-model-invocation"`); - `--integration-options=""` clears them. Re-running `specify init` likewise - stores only the options passed to it. -- Core command skills that a preset overrides, or stops overriding, are reverted - to the default by commands that re-register preset skills without reinstalling - Claude: commands that install, remove or update presets (including `specify - bundle` commands that carry presets), `specify integration use claude`, and - `specify integration switch claude` when Claude is installed but not the - default. To reapply the option, run `specify integration upgrade claude - --force` while Claude is the default integration (`--force` is needed because - those commands modify installed skill files, and it overwrites local edits to - Spec Kit-managed files). - -## Scaffold a New Integration - -```bash -specify integration scaffold -``` - -Creates a minimal built-in integration package and a matching test skeleton in the Spec Kit repository, then prints the next steps for wiring it up. Run this command from the Spec Kit repository root. The `` must be lowercase kebab-case (for example, `my-agent`). - -| Option | Description | -| -------- | ---------------------------------------------------------------- | -| `--type` | Scaffold template to use: `markdown` (default), `skills`, `toml`, or `yaml` | - -## FAQ - -### Can I install multiple integrations in the same project? - -Yes, but it is intended for team portability rather than the default workflow. Multiple integrations are allowed automatically only when the installed integration and the new integration are declared multi-install safe by Spec Kit. For other combinations, pass `--force` to acknowledge that multiple agents may see unrelated agent-specific instructions or commands. - -Spec Kit tracks one default integration in `.specify/integration.json` with `default_integration`, all installed integrations with `installed_integrations`, per-integration runtime settings with `integration_settings`, and a dedicated `integration_state_schema` for future state migrations. The legacy `integration` field remains as an alias for the default integration. - -### Which integrations are multi-install safe? - -An integration is multi-install safe when it uses a static, unique agent root and command directory, stable command invocation settings, and a separate install manifest whose managed files do not overlap another safe integration. Registry tests enforce those path and manifest invariants. Shared Spec Kit templates remain aligned to the single default integration. - -The Command directory column below lists the directory each integration installs its commands or skills into. Context-file targeting is a separate concern from integration multi-install safety: `multi_install_safe` is an integration declaration about command/skill paths, whereas the optional agent-context extension manages a per-agent context file (for example `AGENTS.md` or `CLAUDE.md`) and can even synchronize several anchors at once via its `context_files` setting. Multiple agents mapping to the same context file is expected there and does not affect whether an integration is multi-install safe; see the agent-context extension for details. - -The currently declared multi-install safe integrations are: - -| Key | Command directory | -| --- | ----------------- | -| `alquimia` | `.alquimia/skills` | -| `auggie` | `.augment/commands` | -| `claude` | `.claude/skills` | -| `cline` | `.clinerules/workflows` | -| `codebuddy` | `.codebuddy/commands` | -| `codex` | `.agents/skills` | -| `command-code` | `.commandcode/skills` | -| `cursor-agent` | `.cursor/skills` | -| `droid` | `.factory/skills` | -| `firebender` | `.firebender/commands` | -| `gemini` | `.gemini/commands` | -| `grok` | `.grok/skills` | -| `junie` | `.junie/commands` | -| `kilocode` | `.kilo/commands` | -| `kiro-cli` | `.kiro/prompts` | -| `lingma` | `.lingma/skills` | -| `mcode` | `.minimax/skills` | -| `omp` | `.omp/commands` | -| `opencode` | `.opencode/commands` | -| `pi` | `.pi/prompts` | -| `qodercli` | `.qoder/skills` | -| `qwen` | `.qwen/commands` | -| `shai` | `.shai/commands` | -| `tabnine` | `.tabnine/agent/commands` | -| `trae` | `.trae/skills` | -| `zcode` | `.zcode/skills` | - -Integrations that share a command directory with another integration, require dynamic install paths such as `--commands-dir`, or merge shared tool settings are not declared safe by default. They can still be installed alongside another integration with `--force`. - -### What happens to my changes when I uninstall or switch? - -Files you've modified are preserved automatically. Only unmodified files (matching their original SHA-256 hash) are removed. Use `--force` to override this. - -### How do I know which key to use? - -Run `specify integration list` to see all available integrations with their keys, or check the [Supported AI Coding Agents](#supported-ai-coding-agents) table above. - -### Do I need the AI coding agent installed to use an integration? - -CLI-based integrations (like Claude Code, Gemini CLI) require the tool to be installed. IDE-based integrations (like Cursor) work through the IDE itself. Some agents like GitHub Copilot support both IDE and CLI usage. `specify integration list` shows which type each integration is. - -### When should I use `upgrade` vs `switch`? - -Use `upgrade` when you've upgraded Spec Kit and want to refresh an installed integration's managed files. Use `switch` when you want to replace the current default with another integration; if the target is already installed, `switch` behaves like `use`. - -### Do extensions and presets I install apply to every installed integration? - -No. Extensions (`specify extension add`) and presets (`specify preset add`) register their command overrides for the currently active (default) integration only, even if other integrations are installed. A non-default integration does not receive those artifacts until it becomes the default: `specify integration use ` (or `switch `) rescaffolds every enabled extension and preset for the newly active integration. `specify integration upgrade` follows the same rule — it only re-registers extensions and presets when upgrading the active integration. diff --git a/docs/reference/overview.md b/docs/reference/overview.md index b246bba018..d10ffc3251 100644 --- a/docs/reference/overview.md +++ b/docs/reference/overview.md @@ -19,7 +19,9 @@ clients through a local stdio server. Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files and directory structures for a specific agent. Only one integration is active per project at a time, and you can switch between them at any point. -[Integrations reference →](integrations.md) +[Agent-specific setup guides →](../integrations/index.md) + +[Integration management reference →](../integrations/cli.md) ## Catalogs @@ -65,7 +67,7 @@ Bundles compose existing extensions, presets, workflows, and steps into a single The sections above cover primitives managed by the `specify` CLI. The following are independent processes your coding agent runs, not terminal commands. The references use `/speckit.*` notation; see -[Command invocation](integrations.md#command-invocation) for your agent's syntax. +[Command invocation](../integrations/cli.md#command-invocation) for your agent's syntax. For guided examples, start with [SDD](../quickstart.md), [bug fixing](../guides/bugfix.md), or [idea assessment](../guides/assessment.md). diff --git a/docs/toc.yml b/docs/toc.yml index a374ffd6d2..31c89f0339 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -36,6 +36,105 @@ - name: Enterprise / Air-Gapped href: install/air-gapped.md +# Agent integrations +- name: Integrations + href: integrations/index.md + items: + - name: Overview + href: integrations/index.md + - name: CLI Reference + href: integrations/cli.md + - name: Alquimia AI + href: integrations/alquimia.md + - name: Amp + href: integrations/amp.md + - name: Antigravity + href: integrations/agy.md + - name: Auggie CLI + href: integrations/auggie.md + - name: Claude Code + href: integrations/claude.md + - name: Cline + href: integrations/cline.md + - name: CodeBuddy CLI + href: integrations/codebuddy.md + - name: Codex CLI + href: integrations/codex.md + - name: Command Code + href: integrations/command-code.md + - name: Cursor + href: integrations/cursor-agent.md + - name: DeepSeek Harness + href: integrations/dsh.md + - name: Devin for Terminal + href: integrations/devin.md + - name: Docker Agent + href: integrations/docker-agent.md + - name: Factory Droid + href: integrations/droid.md + - name: Firebender + href: integrations/firebender.md + - name: Forge + href: integrations/forge.md + - name: Gemini CLI + href: integrations/gemini.md + - name: GitHub Copilot + href: integrations/copilot.md + - name: Goose + href: integrations/goose.md + - name: Grok Build + href: integrations/grok.md + - name: Hermes + href: integrations/hermes.md + - name: IBM Bob + href: integrations/bob.md + - name: Junie + href: integrations/junie.md + - name: Kilo Code + href: integrations/kilocode.md + - name: Kimi Code + href: integrations/kimi.md + - name: Kiro CLI + href: integrations/kiro-cli.md + - name: Lingma + href: integrations/lingma.md + - name: MiniMax Code + href: integrations/mcode.md + - name: Mistral Vibe + href: integrations/vibe.md + - name: Muse Code + href: integrations/muse.md + - name: None (shared scaffolding only) + href: integrations/none.md + - name: Oh My Pi + href: integrations/omp.md + - name: opencode + href: integrations/opencode.md + - name: Pi Coding Agent + href: integrations/pi.md + - name: Qoder CLI + href: integrations/qodercli.md + - name: Qwen Code + href: integrations/qwen.md + - name: RovoDev + href: integrations/rovodev.md + - name: SHAI (OVHcloud) + href: integrations/shai.md + - name: Tabnine CLI + href: integrations/tabnine.md + - name: Trae + href: integrations/trae.md + - name: ZCode + href: integrations/zcode.md + - name: Zed + href: integrations/zed.md + - name: Generic (bring your own agent) + href: integrations/generic.md + - name: Catalogs and External Adapters + href: integrations/catalog.md + - name: Contributing Integrations + href: integrations/contributing.md + # Reference - name: Reference items: @@ -45,8 +144,8 @@ href: reference/core.md - name: MCP Server href: reference/mcp.md - - name: Integrations - href: reference/integrations.md + - name: Integration Management + href: integrations/cli.md - name: Catalogs href: reference/catalogs.md - name: Extensions diff --git a/docs/upgrade.md b/docs/upgrade.md index 45e664c0a4..943d9f41a1 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -144,7 +144,7 @@ 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`. +See the [integration reference](integrations/cli.md#upgrade-an-integration) for options such as `--script`, `--integration-options`, and `--force`. ### 3. Update installed extensions diff --git a/extensions/github/README.md b/extensions/github/README.md index 8aaf46a5c3..f6debdc5d4 100644 --- a/extensions/github/README.md +++ b/extensions/github/README.md @@ -26,7 +26,7 @@ its configured `--commands-dir` in both commands and skills layouts. Installing `speckit-github-taskstoissues/SKILL.md` in skills mode. The core `speckit.taskstoissues` command is deprecated but remains available during migration. Use this extension's recommended command instead. See -[integration-specific options](../../docs/reference/integrations.md#integration-specific-options). +[integration-specific options](../../docs/integrations/cli.md#integration-specific-options). ## Removal @@ -96,7 +96,7 @@ specify integration upgrade Replace `` with the installed integration key, or omit it to upgrade the default integration. This refreshes the core command with the deprecation warning. If locally modified files block the upgrade, inspect those changes -before deciding whether to overwrite them. See [Upgrade an Integration](../../docs/reference/integrations.md#upgrade-an-integration). +before deciding whether to overwrite them. See [Upgrade an Integration](../../docs/integrations/cli.md#upgrade-an-integration). To migrate, install the extension and use the namespaced command instead: diff --git a/integrations/CONTRIBUTING.md b/integrations/CONTRIBUTING.md deleted file mode 100644 index cb3087be5a..0000000000 --- a/integrations/CONTRIBUTING.md +++ /dev/null @@ -1,191 +0,0 @@ -# Contributing to the Integration Catalog - -This guide covers adding integrations to both the **built-in** and **community** catalogs. - -## Adding a Built-In Integration - -Built-in integrations are maintained by the Spec Kit core team and ship with the CLI. - -### Checklist - -1. **Create the integration subpackage** under `src/specify_cli/integrations//` - — `` matches the integration key when it contains no hyphens (e.g., `gemini`), or replaces hyphens with underscores when it does (e.g., key `cursor-agent` → directory `cursor_agent/`, key `kiro-cli` → directory `kiro_cli/`). Python package names cannot use hyphens. -2. **Implement the integration class** using the appropriate base class from [integration design](../design/integration.md) -3. **Register the integration** in `src/specify_cli/integrations/__init__.py` -4. **Add tests** under `tests/integrations/test_integration_.py` -5. **Add a catalog entry** in `integrations/catalog.json` -6. **Update documentation** in [integration design](../design/integration.md), [supported integrations](../docs/reference/integrations.md), and this catalog's README as needed - -### Catalog Entry Format - -Add your integration under the top-level `integrations` key in `integrations/catalog.json`: - -```json -{ - "schema_version": "1.0", - "integrations": { - "my-agent": { - "id": "my-agent", - "name": "My Agent", - "version": "1.0.0", - "description": "Integration for My Agent", - "author": "spec-kit-core", - "repository": "https://github.com/github/spec-kit", - "tags": ["cli"] - } - } -} -``` - -## Adding a Community Integration - -Community integrations are contributed by external developers and listed in `integrations/catalog.community.json` for discovery. - -### Prerequisites - -1. **Working external integration** — distribute a standalone ZIP or tar.gz - with root `integration.yml` and `__init__.py`; a discovery-only community - listing does not grant installation permission -2. **Public repository** — hosted on GitHub or similar -3. **`integration.yml` descriptor** — valid descriptor file (see below) -4. **Documentation** — README with usage instructions -5. **License** — open source license file - -### `integration.yml` Descriptor - -Every community integration must include an `integration.yml`: - -```yaml -schema_version: "1.0" -integration: - id: "sample-agent" - name: "Sample Agent" - version: "1.0.0" - description: "Adapter for Sample Agent" - author: "your-name" - repository: "https://github.com/your-name/speckit-sample-agent" - license: "MIT" -requires: - speckit_version: ">=1.1.2.dev0" - tools: - - name: "sample-agent" - required: true -``` - -The root module exports exactly one adapter subclass, whose `key` and -`config.name` match the descriptor. Prefer `SkillsIntegration`, -`MarkdownIntegration`, `TomlIntegration`, or `YamlIntegration` to render the -host templates. Do not duplicate or enumerate Spec Kit's core commands. -Additional relative-import helper modules are allowed; external packages using -only the host API and standard library require neither pip installation nor -changes to the source registry. See the complete -[external adapter contract](../design/integration.md#external-adapter-package-contract). - -### Descriptor Validation Rules - -| Field | Rule | -|-------|------| -| `schema_version` | Must be `"1.0"` | -| `integration.id` | External package IDs start with a lowercase letter/digit, then lowercase alphanumeric + hyphens (`^[a-z0-9][a-z0-9-]*$`); built-in and Windows device names are reserved | -| `integration.version` | Valid PEP 440 version (parsed with `packaging.version.Version()`) | -| `requires.speckit_version` | Required valid PEP 440 constraint, enforced during install and load | -| `requires.tools` | Optional list; required executables are checked on PATH; version detection belongs to the adapter | -| `provides` | Optional legacy metadata; an adapter need not provide commands or scripts | -| `provides.commands[].name` | String identifier | -| `provides.commands[].file` | Relative path to template file | - -Publish a pinned archive `download_url`, preferably with a hexadecimal archive -`sha256` digest. The catalog's ID/name/version/description and any optional -descriptor metadata or requirements must match `integration.yml`. -Never rely on importing a catalog to register your class: discovery does not -execute code. Installation from an install-enabled source requires an explicit -trust decision before import. Catalog maintainers review listing metadata, not -adapter implementations; users must vet the code. -Consent is user-local in `~/.specify/integration-trust.json`, bound to the -canonical project root, adapter ID, and verified package digest. Do not ship a -trust registry or rely on project metadata to authorize execution. A copied -project must reauthorize through a reviewed, install-enabled catalog using -`specify integration upgrade sample-agent --force --trust-integration`. - -### Submitting to the Community Catalog - -1. **Fork** the [spec-kit repository](https://github.com/github/spec-kit) -2. **Add your entry** under the `integrations` key in `integrations/catalog.community.json`: - - ```json - { - "schema_version": "1.0", - "integrations": { - "sample-agent": { - "id": "sample-agent", - "name": "Sample Agent", - "version": "1.0.0", - "description": "Adapter for Sample Agent", - "author": "your-name", - "repository": "https://github.com/your-name/speckit-sample-agent", - "download_url": "https://github.com/your-name/speckit-sample-agent/releases/download/v1.0.0/sample-agent.zip", - "tags": ["cli"] - } - } - } - ``` - -3. **Open a pull request** with: - - Your catalog entry - - Link to your integration repository - - Confirmation that `integration.yml` is valid - -### Version Updates - -To update your integration version in the catalog: - -1. Release a new version of your integration -2. Open a PR updating the version, pinned archive URL, and digest (if provided) -3. Ensure backward compatibility or document breaking changes - -## Upgrade Workflow - -The `specify integration upgrade` command supports diff-aware upgrades: - -1. **Hash comparison** — the manifest records SHA-256 hashes of all installed files -2. **Modified file detection** — files changed since installation are flagged -3. **Safe default** — the upgrade blocks if any installed files were modified since installation -4. **Forced reinstall** — passing `--force` overwrites modified files with the latest version - -```bash -# Upgrade current integration (blocks if files are modified) -specify integration upgrade - -# Force upgrade (overwrites modified files) -specify integration upgrade --force - -# Upgrade a reviewed external adapter without a trust prompt -specify integration upgrade sample-agent --trust-integration -``` - -Test your package through the public path: register a local loopback test -catalog, install its neutral adapter, start a fresh CLI process, register -extension/preset contributions, and exercise command/prompt workflow dispatch -with a harmless process double. Include failures for invalid metadata/classes, -trust denial, unsafe archives, setup errors, and upgrades/uninstall. Keep -package code separate from generated-file manifests and verify rollback and -modified-file preservation. - -Use manifest/base-class write helpers so failed lifecycle operations can restore -only the files your adapter changed. Legacy `record_existing()` writes are -covered within the adapter's declared output root; writes elsewhere must use -`record_file()` or host write helpers. Do not claim unrelated user files. Test -metadata-only commands without import side effects, forced recovery of damaged -installed packages, and rollback that preserves independent workflow progress -and concurrent user edits. -Host helpers reject symlinked write destinations; owned leaf links may be -unlinked without following them. Exercise overlapping project dispatch and lazy -relative imports: the host pins the correct adapter for each dispatch without -serializing independent agent processes. Forced recovery uses user-local -registrar/path ownership, not editable project metadata. Without that proof, -old-only artifacts are preserved with an explicit manual-cleanup warning. -Validate optional legacy destinations as canonical project-relative paths; they -cannot use reserved roots, symlinked directories, or home-relative syntax. -Primary and legacy output overlap is checked case-insensitively on all platforms. -For event-capable adapters, test event-only extension add/remove and enable/disable -in fresh CLI processes, including explicit errors when installed code cannot load. From 9610548e9eb18eabc906e1488de322ccdf93c16c Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 20 Oct 2026 13:32:30 -0500 Subject: [PATCH 2/3] fix(ci): align integration docs with lint and version checks Remove the obsolete integration README lint glob and bump the bundled GitHub extension to ship its updated documentation links. Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/lint.yml | 1 - extensions/catalog.json | 2 +- extensions/github/extension.yml | 2 +- tests/extensions/github/test_github_extension.py | 2 +- 4 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index b3ad19d31e..f9a4e4e4e0 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -23,7 +23,6 @@ jobs: SECURITY.md SUPPORT.md spec-driven.md - integrations/*.md presets/*.md workflows/*.md steps: diff --git a/extensions/catalog.json b/extensions/catalog.json index 30e6dd92ac..c20cec03e6 100644 --- a/extensions/catalog.json +++ b/extensions/catalog.json @@ -66,7 +66,7 @@ "github": { "name": "GitHub Integration", "id": "github", - "version": "1.0.2", + "version": "1.0.3", "description": "GitHub platform integration for Spec Kit - create GitHub issues from a feature's task list", "author": "spec-kit-core", "repository": "https://github.com/github/spec-kit", diff --git a/extensions/github/extension.yml b/extensions/github/extension.yml index c6df8f19a1..158824e823 100644 --- a/extensions/github/extension.yml +++ b/extensions/github/extension.yml @@ -3,7 +3,7 @@ schema_version: "1.0" extension: id: github name: "GitHub Integration" - version: "1.0.2" + version: "1.0.3" description: "GitHub platform integration for Spec Kit - create GitHub issues from a feature's task list" author: spec-kit-core repository: https://github.com/github/spec-kit diff --git a/tests/extensions/github/test_github_extension.py b/tests/extensions/github/test_github_extension.py index 7d348d20f2..5b8adc5047 100644 --- a/tests/extensions/github/test_github_extension.py +++ b/tests/extensions/github/test_github_extension.py @@ -158,7 +158,7 @@ def test_manifest_validates(self): m = ExtensionManifest(EXT_DIR / "extension.yml") assert m.id == "github" - assert m.version == "1.0.2" + assert m.version == "1.0.3" assert [c["name"] for c in m.commands] == [COMMAND_NAME] def test_manifest_command_files_exist(self): From 06d76140629da2dcbb0eddbae12b02320901bb61 Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 20 Oct 2026 14:07:38 -0500 Subject: [PATCH 3/3] docs: restore integration descriptor validation requirements Document required descriptor fields, external ID restrictions, PEP 440 versions, and mandatory host version specifiers. Assisted-by: GitHub Copilot (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/integrations/catalog.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/integrations/catalog.md b/docs/integrations/catalog.md index 473f8efd19..823c4a22cf 100644 --- a/docs/integrations/catalog.md +++ b/docs/integrations/catalog.md @@ -65,6 +65,16 @@ requires: required: true ``` +Required descriptor fields: + +| Field | Validation | +|-------|------------| +| `schema_version` | Must be the string `"1.0"` | +| `integration.id` | External IDs must match `^[a-z0-9][a-z0-9-]*$`. Names `con`, `prn`, `aux`, `nul`, `com1` through `com9`, and `lpt1` through `lpt9` are reserved | +| `integration.name`, `integration.description` | Must be strings | +| `integration.version` | Must be a PEP 440 version string | +| `requires.speckit_version` | Mandatory, non-empty PEP 440 version specifier string | + `requires.tools` is optional; omit it for adapters with no required executable. Optional legacy `provides` metadata remains valid but does not supply host commands. See [integration design](https://github.com/github/spec-kit/blob/main/design/integration.md#external-adapter-package-contract)