docs: organize agent-specific integration documentation (#5034)

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

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

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

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: mnriem

.github/workflows/lint.yml

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

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

README.ja.md

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

README.ko.md

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

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

README.zh-CN.md

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

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

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/<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)
 

docs/docfx.json

@@ -8,6 +8,7 @@
           "community/*.md",
           "concepts/*.md",
           "guides/*.md",
+          "integrations/*.md",
           "reference/*.md",
           "install/*.md"
         ]

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.