mnriem · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
@@ -23,7 +23,6 @@ jobs:
         SECURITY.md
         SUPPORT.md
         spec-driven.md
-        integrations/*.md
         presets/*.md
         workflows/*.md
     steps:

@@ -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)
 
 <details>
 <summary><b>💡 Hint if you are using <code>VSCode</code> or <code>GitHub Codespaces</code> as your IDE</b></summary>
@@ -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.
 

@@ -46,11 +46,11 @@ cd my-project
 
 <a id="-対応しているaiコーディングエージェント"></a>
 
-この例では **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)を使う場合があります。
 
 <a id="-仕様駆動開発とは"></a>
 <a id="sdd-クイックスタート"></a>

@@ -51,7 +51,7 @@ cd my-project
 <a id="-supported-ai-coding-agent-integrations"></a>
 
 예시는 **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).
 
 <a id="-what-is-spec-driven-development"></a>
 <a id="sdd-quickstart"></a>

@@ -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.
 
 <a id="-what-is-spec-driven-development"></a>
@@ -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

@@ -55,15 +55,15 @@ 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)；
 更新已安装的 CLI 和项目文件见[升级指南](https://github.github.io/spec-kit/upgrade.html)。
 
 现在，在**项目目录中启动编码助手**，选择以下一种流程。
 在**助手的聊天界面中逐个调用 `/speckit-*` 技能**，检查结果后再继续。
-这些是助手技能，不是终端命令。其他助手或模式可能采用[不同的调用语法](https://github.github.io/spec-kit/reference/integrations.html#command-invocation)。
+这些是助手技能，不是终端命令。其他助手或模式可能采用[不同的调用语法](https://github.github.io/spec-kit/integrations/cli.html#command-invocation)。
 
 <a id="-什么是规范驱动开发"></a>
 <a id="3-确立项目准则"></a>

@@ -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/<key>.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_<package_dir>.py`
    for metadata, generated output, installation, and uninstall (including
    preservation of edited files where applicable).
 4. Exercise `specify init my-project --integration <key>` 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.
@@ -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/<key>.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)
 

@@ -8,6 +8,7 @@
           "community/*.md",
           "concepts/*.md",
           "guides/*.md",
+          "integrations/*.md",
           "reference/*.md",
           "install/*.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.

@@ -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.

@@ -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

@@ -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

@@ -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.
 
-<a href="reference/integrations.md" class="pillar-link">See all integrations →</a>
+<a href="integrations/index.md" class="pillar-link">See all integrations →</a>
 
 </div>
 

@@ -81,8 +81,8 @@ specify init <project_name> --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)

@@ -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-<command>/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 <prompt>`. 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.
-Original file line number
+Diff line change
@@ Expand Up @@
     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.
-    <a href="reference/integrations.md" class="pillar-link">See all integrations →</a>
+    <a href="integrations/index.md" class="pillar-link">See all integrations →</a>
     </div>
@@ Expand Down @@