Add thin toolkit-routing agent adapters

.github/copilot-instructions.md

@@ -1,21 +1,18 @@
 # Repository Instructions For GitHub Copilot
 
-Follow the project `AGENTS.md`.
+This file is a GitHub Copilot entry point only. Keep GitHub Copilot-specific
+integration guidance under `adapters/github-copilot/` and keep reusable
+architecture and SDLC semantics in the architecture-knowledge-toolkit.
 
-This project uses architecture-knowledge-toolkit for architecture documentation,
-ADRs, quality scenarios, risks, traceability metadata, templates, validators,
-generated include fragments, and SDLC task workflows that are not described more
-specifically in this repository.
+Follow repository-root `adapters/github-copilot/copilot-instructions.md`, then
+the contract hierarchy in repository-root `AGENTS.md` and
+`general-semantic-contracts.md`.
 
-Use the toolkit repository as source of truth when local toolkit files are missing:
+Use the toolkit repository as source of truth when local toolkit files are
+missing:
 
 https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
 
-For architecture-related or SDLC workflow changes:
-
-- prefer small, reviewable changes
-- preserve stable IDs
-- keep AI-generated or AI-modified architecture content in `draft` or `proposed` state unless reviewed
-- do not manually maintain generated fragments
-- consult the relevant toolkit skill before issue slicing, issue implementation, commit message, pull request review, post-merge synchronization, ADR, quality scenario, risk, or traceability-review work when local instructions are missing
-- do not introduce Copilot-specific rules into engine-independent toolkit files
+Do not duplicate architecture, ADR, quality scenario, risk, traceability,
+metadata, arc42, or SDLC rules here. Add durable rules to the canonical toolkit
+source instead.

.github/workflows/architecture-docs.yml

@@ -24,6 +24,12 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Check agent adapters
+        run: ./build.sh check-adapters
+
+      - name: Test agent adapter generator
+        run: ./build.sh test
+
       - name: Build architecture HTML
         run: ./build.sh build
 

AGENTS.md

@@ -23,8 +23,12 @@ https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
 
 Preferred local lookup order:
 
-1. `$ARCHITECTURE_KNOWLEDGE_TOOLKIT`
-2. `../architecture-knowledge-toolkit`
+1. `$ARCHITECTURE_KNOWLEDGE_TOOLKIT` if it is set
+2. otherwise the nearest local `architecture-knowledge-toolkit` checkout found by
+   searching upward from this project directory:
+   `../architecture-knowledge-toolkit`, then the same directory name in each
+   parent directory up to the filesystem root (do not assume the toolkit is a
+   direct sibling; this project may live outside the toolkit's parent folder)
 3. project-local recorded toolkit reference, submodule, vendored copy, or pinned path
 4. the public repository above, preferably at a stable release tag or commit SHA
 
@@ -38,3 +42,30 @@ Before architecture or SDLC workflow work:
 - set `reviewed: false` unless human acceptance is already recorded
 - do not manually maintain generated fragments when a generator exists
 - copy missing toolkit templates, schemas, validators, and generator scripts from the toolkit instead of inventing alternatives
+
+## Reference, Don't Copy
+
+Treat the architecture-knowledge-toolkit as the single source of truth for
+architecture skills, contracts, and features. Do not copy toolkit
+`skills/**/SKILL.md`, `features/`, or contract text into this repository;
+resolve them from the toolkit through the lookup order above. Only executable
+tooling that must run here — metamodel schemas under `metamodel/`, templates
+under `templates/`, and validator/generator scripts under `scripts/` — is copied
+or vendored and kept in sync with the toolkit.
+
+This repository has no local architecture skills of its own. It references the
+toolkit for all architecture and SDLC work and generates thin adapters that
+route agents to it. If a project-specific skill is ever added, it must extend
+the toolkit or explicitly override a specific rule, never silently duplicate it.
+
+## Agent Adapters
+
+This repository keeps no local agent skills; it routes agents to the
+architecture-knowledge-toolkit. The thin routing wrappers under `adapters/`
+(`adapters/codex/AGENTS.md`, `adapters/vibe/AGENTS.md`,
+`adapters/github-copilot/copilot-instructions.md`, and
+`adapters/cursor/rules/docs-toolbox.mdc`) are generated by
+`scripts/build-agent-adapters.js`. Do not edit them by hand; change the
+generator and run `./build.sh adapters`. CI runs `./build.sh check-adapters`
+to fail on stale adapters. Keep `.github/copilot-instructions.md` as an entry
+point only that points back to `adapters/github-copilot/copilot-instructions.md`.

README.md

@@ -193,6 +193,15 @@ image from the current Dockerfile if that exact image does not exist.
 ./build.sh build
 ```
 
+It also generates the thin agent adapters that route AI agents (Codex, Vibe,
+GitHub Copilot, Cursor) to the architecture-knowledge-toolkit:
+
+```bash
+./build.sh adapters         # regenerate adapters under adapters/
+./build.sh check-adapters   # fail if the generated adapters are stale
+./build.sh test             # run the adapter generator behaviour tests
+```
+
 ### GitHub Actions (example)
 
 ```yaml

adapters/codex/AGENTS.md

@@ -0,0 +1,29 @@
+<!-- GENERATED FILE: edit scripts/build-agent-adapters.js (and skills/**/SKILL.md if present), then regenerate. -->
+# Codex Adapter
+
+This is a thin Codex-specific wrapper for the docs-toolbox
+repository. docs-toolbox keeps no local agent skills of its own; architecture and
+software-development-lifecycle semantics are delegated to the
+architecture-knowledge-toolkit.
+
+When Codex performs architecture-sensitive or SDLC work in this
+repository:
+
+1. Read repository-root `AGENTS.md`.
+2. Read repository-root `general-semantic-contracts.md`.
+3. Follow the toolkit lookup order in `AGENTS.md`, then read the relevant
+   canonical `skills/**/SKILL.md` from the architecture-knowledge-toolkit.
+4. Treat this adapter as routing guidance only.
+
+## Toolkit Source Of Truth
+
+Prefer local toolkit files when present; otherwise use the public repository:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+## Adapter Boundary
+
+Do not duplicate architecture, ADR, quality scenario, risk, traceability,
+metadata, or arc42 rules here. Agent-specific files may only wrap, point to, or
+invoke the canonical toolkit sources and repository-root
+`general-semantic-contracts.md`.

adapters/cursor/rules/docs-toolbox.mdc

@@ -0,0 +1,33 @@
+---
+description: docs-toolbox adapter
+alwaysApply: true
+---
+<!-- GENERATED FILE: edit scripts/build-agent-adapters.js (and skills/**/SKILL.md if present), then regenerate. -->
+# Cursor Rule
+
+This is a thin Cursor-specific wrapper for the docs-toolbox
+repository. docs-toolbox keeps no local agent skills of its own; architecture and
+software-development-lifecycle semantics are delegated to the
+architecture-knowledge-toolkit.
+
+When Cursor performs architecture-sensitive or SDLC work in this
+repository:
+
+1. Read repository-root `AGENTS.md`.
+2. Read repository-root `general-semantic-contracts.md`.
+3. Follow the toolkit lookup order in `AGENTS.md`, then read the relevant
+   canonical `skills/**/SKILL.md` from the architecture-knowledge-toolkit.
+4. Treat this adapter as routing guidance only.
+
+## Toolkit Source Of Truth
+
+Prefer local toolkit files when present; otherwise use the public repository:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+## Adapter Boundary
+
+Do not duplicate architecture, ADR, quality scenario, risk, traceability,
+metadata, or arc42 rules here. Agent-specific files may only wrap, point to, or
+invoke the canonical toolkit sources and repository-root
+`general-semantic-contracts.md`.

adapters/github-copilot/copilot-instructions.md

@@ -0,0 +1,29 @@
+<!-- GENERATED FILE: edit scripts/build-agent-adapters.js (and skills/**/SKILL.md if present), then regenerate. -->
+# GitHub Copilot Adapter
+
+This is a thin GitHub Copilot-specific wrapper for the docs-toolbox
+repository. docs-toolbox keeps no local agent skills of its own; architecture and
+software-development-lifecycle semantics are delegated to the
+architecture-knowledge-toolkit.
+
+When GitHub Copilot performs architecture-sensitive or SDLC work in this
+repository:
+
+1. Read repository-root `AGENTS.md`.
+2. Read repository-root `general-semantic-contracts.md`.
+3. Follow the toolkit lookup order in `AGENTS.md`, then read the relevant
+   canonical `skills/**/SKILL.md` from the architecture-knowledge-toolkit.
+4. Treat this adapter as routing guidance only.
+
+## Toolkit Source Of Truth
+
+Prefer local toolkit files when present; otherwise use the public repository:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+## Adapter Boundary
+
+Do not duplicate architecture, ADR, quality scenario, risk, traceability,
+metadata, or arc42 rules here. Agent-specific files may only wrap, point to, or
+invoke the canonical toolkit sources and repository-root
+`general-semantic-contracts.md`.

adapters/vibe/AGENTS.md

@@ -0,0 +1,29 @@
+<!-- GENERATED FILE: edit scripts/build-agent-adapters.js (and skills/**/SKILL.md if present), then regenerate. -->
+# Vibe Adapter
+
+This is a thin Vibe-specific wrapper for the docs-toolbox
+repository. docs-toolbox keeps no local agent skills of its own; architecture and
+software-development-lifecycle semantics are delegated to the
+architecture-knowledge-toolkit.
+
+When Vibe performs architecture-sensitive or SDLC work in this
+repository:
+
+1. Read repository-root `AGENTS.md`.
+2. Read repository-root `general-semantic-contracts.md`.
+3. Follow the toolkit lookup order in `AGENTS.md`, then read the relevant
+   canonical `skills/**/SKILL.md` from the architecture-knowledge-toolkit.
+4. Treat this adapter as routing guidance only.
+
+## Toolkit Source Of Truth
+
+Prefer local toolkit files when present; otherwise use the public repository:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+## Adapter Boundary
+
+Do not duplicate architecture, ADR, quality scenario, risk, traceability,
+metadata, or arc42 rules here. Agent-specific files may only wrap, point to, or
+invoke the canonical toolkit sources and repository-root
+`general-semantic-contracts.md`.

build.sh

@@ -8,12 +8,15 @@ SOURCE_DOC="${SOURCE_DOC:-src/docs/doc-001-arc42.adoc}"
 
 usage() {
   cat <<'USAGE'
-Usage: ./build.sh [build|validate|clean]
+Usage: ./build.sh [build|validate|adapters|check-adapters|test|clean]
 
 Commands:
-  build      Validate, generate architecture fragments, and render HTML.
-  validate   Validate and generate architecture documentation metadata.
-  clean      Remove local architecture build output.
+  build          Validate, generate architecture fragments, and render HTML.
+  validate       Validate and generate architecture documentation metadata.
+  adapters       Regenerate the thin agent adapters under adapters/.
+  check-adapters Fail if the generated agent adapters are out of date.
+  test           Run the agent adapter generator behaviour tests.
+  clean          Remove local architecture build output.
 
 The script prefers a published docs-toolbox image tagged with the local
 Dockerfile hash (df-<hash>). If that image is not available, it builds a local
@@ -43,6 +46,18 @@ run_validate() {
   ruby scripts/validate-metamodel.rb --generate
 }
 
+run_adapters() {
+  node scripts/build-agent-adapters.js
+}
+
+run_check_adapters() {
+  node scripts/check-agent-adapters.js
+}
+
+run_test() {
+  node --test test/build-agent-adapters.test.mjs
+}
+
 run_build() {
   run_validate
   mkdir -p "$BUILD_DIR"
@@ -67,6 +82,15 @@ run_local() {
     validate)
       run_validate
       ;;
+    adapters)
+      run_adapters
+      ;;
+    check-adapters)
+      run_check_adapters
+      ;;
+    test)
+      run_test
+      ;;
     clean)
       rm -rf "$BUILD_DIR"
       echo "Removed $BUILD_DIR"
@@ -115,7 +139,7 @@ if [ "${DOCS_TOOLBOX_IN_CONTAINER:-}" = "1" ]; then
 fi
 
 case "$COMMAND" in
-  build|validate)
+  build|validate|adapters|check-adapters|test)
     ENGINE="$(find_engine)"
     if [ -n "$ENGINE" ]; then
       run_in_container "$ENGINE"

general-semantic-contracts.md

@@ -9,20 +9,28 @@ instructions, workflow definitions, source code, tests, and reviewed
 architecture records are evidence. AI-created architecture content is draft or
 proposed until reviewed by the accountable owner.
 
-For missing guidance, use the toolkit lookup order in `AGENTS.md`. Do not copy
-the full toolkit rule set into this repository; keep this file as the local
-semantic entry point and let the toolkit remain the maintained source.
+For missing guidance, use the toolkit lookup order in `AGENTS.md`. Reference,
+don't copy: do not copy toolkit `skills/**/SKILL.md`, `features/`, or contract
+text into this repository. Only executable tooling that must run here — metamodel
+schemas, templates, and validator/generator scripts — is copied or vendored and
+kept in sync with the toolkit. Keep this file as the local semantic entry point
+and let the toolkit remain the maintained source.
 
 Project-local facts currently supported by repository evidence:
 
 - The product is a Docker image named `docs-toolbox`.
 - The image supports reproducible Docs-as-Code pipelines locally and in CI.
 - The Dockerfile uses `openjdk:22-jdk-slim`.
-- The image installs Asciidoctor, Pandoc, Graphviz, unzip, curl, and Python 3.
+- The image installs Asciidoctor, Pandoc, Graphviz, unzip, curl, Python 3, and Node.js (with npm).
 - GitHub Actions builds and pushes multi-platform images to GHCR.
 - Tags include a Dockerfile hash tag and, for Git-tagged commits, the Git tag and `latest`.
 - The project is MIT licensed.
 
 Architecture documentation in this repository is under `src/docs/` and follows
 the toolkit metamodel. Generated files under `generated/` directories are
 derived output and must not be edited manually.
+
+Agent adapters under `adapters/` are thin, toolkit-routing wrappers generated by
+`scripts/build-agent-adapters.js`. They are derived output: do not edit them by
+hand. Regenerate with `./build.sh adapters` and verify with
+`./build.sh check-adapters`.