Reference-don't-copy, agent adapter generation, and upward toolkit lookup

AGENTS.md

@@ -50,14 +50,31 @@ request reviews, post-merge synchronization, ADRs, quality scenarios, risks,
 traceability reviews, architecture documentation updates, and documentation
 validation/generation.
 
-If the architecture-knowledge-toolkit is not available on the local filesystem,
-use the public repository as the fallback source of truth:
-
-https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+Locate the toolkit in this order:
+
+1. `$ARCHITECTURE_KNOWLEDGE_TOOLKIT` if it is set.
+2. Otherwise the nearest local `architecture-knowledge-toolkit` checkout found by
+   searching upward from the consuming 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; the consuming project may live outside the toolkit's parent
+   folder.
+3. Otherwise a project-local recorded toolkit reference such as a submodule,
+   vendored copy, or pinned path.
+4. Otherwise the public repository as the fallback source of truth:
+   https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
 
 Prefer a stable toolkit reference, such as a release tag or commit SHA, when a
 target project records a long-lived dependency on the public repository.
 
+Reference, don't copy. Do not copy this toolkit's `skills/**/SKILL.md`,
+`features/`, or contract text into a consuming project; resolve them from the
+toolkit through the lookup order above. Only executable tooling that must run in
+the target project — metamodel schemas, templates, and validator/generator
+scripts — is copied or vendored and kept in sync. A project's local skills and
+contracts extend the toolkit or explicitly override a specific rule; they never
+silently duplicate it. See "Consuming This Toolkit From a Project" in `README.md`.
+
 Do not copy all toolkit rules into global agent installations. Global agent
 instructions should only tell agents how to discover and apply this toolkit.
 

README.md

@@ -82,6 +82,69 @@ Use the general contract as the maintained source for rules that also help
 humans and deterministic tools. Put only runtime-specific AI details below
 `adapters/`.
 
+## Consuming This Toolkit From a Project
+
+A project that uses this toolkit for architecture work should treat the toolkit
+as the single source of truth and keep only its own delta locally. The guiding
+rule is **reference, don't copy**.
+
+### Reference, don't copy
+
+Do **not** copy this toolkit's `skills/**/SKILL.md`, `features/`, or architecture
+contract text into the consuming repository. Copies drift; the toolkit is still
+evolving, and duplicated guidance across projects becomes stale the moment the
+toolkit changes. Instead, point agents at the canonical toolkit sources through
+the lookup order in the project's `AGENTS.md`.
+
+### What a project copies vs. references
+
+- **Copied / vendored into the project** — executable tooling that must run in
+  the project's own build and CI: metamodel schemas (`metamodel/`), AsciiDoc
+  templates (`templates/`), validator/generator scripts (`scripts/`), and the
+  generic agent adapter generator from `templates/scripts/`. Keep these in sync
+  with the toolkit; do not fork their behavior silently. The `bootstrap-project`
+  skill copies them when a project has none. Do not copy the toolkit's own
+  `scripts/build-agent-adapters.js`; it is wired to the toolkit itself. Use the
+  parameterizable `templates/scripts/build-agent-adapters.js` instead.
+- **Referenced, never copied** — the architecture *guidance*: toolkit
+  `skills/**/SKILL.md`, `features/`, and the toolkit's own contract text. Agents
+  resolve these from the toolkit at need.
+
+### Local skills and contracts extend, they do not duplicate
+
+A consuming project may add its own `skills/**/SKILL.md` and task contracts for
+work the toolkit does not cover (for example project-specific content
+workflows). Such local skills **extend** the toolkit: their body should read the
+toolkit baseline first, then add only the project-specific steps. A local rule
+that **overrides** a toolkit rule is allowed only when the project deliberately
+narrows it, and it must say so explicitly. Local skills and contracts must never
+silently re-state toolkit rules.
+
+### Wiring in the consuming project
+
+1. Record the toolkit lookup order in the project `AGENTS.md`:
+   `$ARCHITECTURE_KNOWLEDGE_TOOLKIT` if set; otherwise the nearest
+   `architecture-knowledge-toolkit` found by searching upward from the project
+   directory (`../architecture-knowledge-toolkit`, then the same directory name
+   in each parent directory up to the filesystem root — do not assume it is a
+   direct sibling); otherwise a pinned/vendored reference; otherwise the public
+   repository.
+2. Prefer a stable toolkit reference — a release tag or commit SHA — for any
+   long-lived dependency, so architecture guidance is reproducible.
+3. Copy the generic generator from `templates/scripts/` and run
+   `node scripts/build-agent-adapters.js` to generate thin agent adapters under
+   `adapters/` that only route agents to the canonical toolkit skills and the
+   project's `general-semantic-contracts.md`; do not embed toolkit rules in them.
+   The generator derives the project name (from `AGENT_ADAPTER_PROJECT`, an
+   `adapters/agent-adapters.config.json` `project` field, or the repository
+   directory name) and auto-detects whether to list local skills or route to the
+   toolkit. Run `node scripts/check-agent-adapters.js` in CI to fail on stale
+   adapters.
+
+A project that has **no** local architecture skills of its own (for example a
+tooling repository) still references the toolkit for all architecture and SDLC
+work and generates adapters that route to it.
+
 ## Relationship Strategy
 
 **Authoritative Outgoing Relations Only.**
@@ -215,7 +278,8 @@ Local equivalent (without docs-toolbox):
 ```sh
 ruby -Itest test/validate_metamodel_test.rb       # validator + generator units
 ruby -Itest test/validate_metamodel_cli_test.rb   # validator CLI behaviour
-node --test test/build-agent-adapters.test.mjs    # adapter generator
+node --test test/build-agent-adapters.test.mjs \
+  test/build-agent-adapters-template.test.mjs     # adapter generator + template
 ```
 
 The container-based render scripts (`build.sh` itself and
@@ -268,7 +332,7 @@ example to pin a digest) with `DOCS_TOOLBOX_IMAGE`.
 | `generate` | Validate, then generate derived fragments/indexes | `ruby scripts/validate-metamodel.rb --generate` |
 | `test` | Run all tests (Ruby units, Ruby CLI, JS adapter) | see [Tests](#tests) |
 | `test-ruby` | Ruby validator/generator unit and CLI tests | `ruby -Itest test/validate_metamodel_test.rb` and `ruby -Itest test/validate_metamodel_cli_test.rb` |
-| `test-js` | JS adapter generator tests | `node --test test/build-agent-adapters.test.mjs` |
+| `test-js` | JS adapter generator tests | `node --test test/build-agent-adapters.test.mjs test/build-agent-adapters-template.test.mjs` |
 | `adapters` | Regenerate agent adapters from skills | `node scripts/build-agent-adapters.js` |
 | `check-adapters` | Fail if the generated adapters are stale | `node scripts/check-agent-adapters.js` |
 | `build` | Generate fragments and render architecture HTML | see below |

build.sh

@@ -78,7 +78,7 @@ run_local_test_ruby() {
 }
 
 run_local_test_js() {
-  node --test test/build-agent-adapters.test.mjs
+  node --test test/build-agent-adapters.test.mjs test/build-agent-adapters-template.test.mjs
 }
 
 run_local_test() {

example/.github/copilot-instructions.md

@@ -0,0 +1,18 @@
+# Repository Instructions For GitHub Copilot
+
+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.
+
+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:
+
+https://github.com/docs-as-code-toolkit/architecture-knowledge-toolkit
+
+Do not duplicate architecture, ADR, quality scenario, risk, traceability,
+metadata, arc42, or SDLC rules here. Add durable rules to the canonical toolkit
+source instead.

example/AGENTS.md

@@ -54,3 +54,29 @@ Before architecture or SDLC workflow work:
 - 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 example; 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 example has no local architecture skills of its own. It references the
+toolkit for all architecture and SDLC work. If a project-specific skill is ever
+added, it extends the toolkit or explicitly overrides a specific rule; it never
+silently duplicates toolkit rules.
+
+## Agent Adapters
+
+The thin routing wrappers under `adapters/` (`adapters/codex/AGENTS.md`,
+`adapters/vibe/AGENTS.md`, `adapters/github-copilot/copilot-instructions.md`, and
+`adapters/cursor/rules/example.mdc`) are generated by
+`scripts/build-agent-adapters.js`. Do not edit them by hand; change the generator
+and run `node scripts/build-agent-adapters.js`. Verify with
+`node scripts/check-agent-adapters.js`. Keep `.github/copilot-instructions.md`
+as an entry point only that points to
+`adapters/github-copilot/copilot-instructions.md`.

example/README.md

@@ -17,14 +17,49 @@ metamodel schemas, validation, and reproducible generated fragments.
 - Product clarification artifacts under `src/docs/canvas/`,
   `src/docs/doc-002-vision-mission.adoc`, `src/docs/doc-004-roadmap.adoc`, and
   `src/docs/doc-005-questions-and-answers.adoc`.
-- `AGENTS.md` as the example project's local agent adapter, delegating missing
+- `AGENTS.md` as the example project's local agent contract, delegating missing
   architecture and SDLC guidance to the toolkit.
+- `.github/copilot-instructions.md` as a thin GitHub Copilot entry point.
+- Thin, generated agent adapters under `adapters/` (Codex, Vibe, GitHub Copilot,
+  Cursor) that route agents to the toolkit.
 - Copied toolkit templates under `templates/`.
 - Copied metamodel schemas under `metamodel/`.
-- Copied validation and generator script under `scripts/`.
+- Copied validation/generator script and the agent adapter generator under
+  `scripts/`.
 
 Generated files live below `generated/` directories and are not primary editing
-surfaces. Edit source artifacts and regenerate.
+surfaces. The `adapters/` files are likewise generated. Edit source artifacts or
+the generators and regenerate.
+
+## Reference, Don't Copy
+
+This example follows **reference, don't copy**. It does not copy the toolkit's
+`skills/**/SKILL.md`, `features/`, or contract text; it references them through
+the lookup order in `AGENTS.md`. Only executable tooling that must run here —
+metamodel schemas, templates, and validator/generator scripts — is copied and
+kept in sync with the toolkit. The example has no local skills of its own; a
+real project adds local skills only to *extend* the toolkit or to *explicitly
+override* a specific rule.
+
+## Agent Adapters
+
+The per-agent files under `adapters/` are generated. `scripts/build-agent-adapters.js`
+here is a verbatim copy of the toolkit's generic generator template
+(`templates/scripts/build-agent-adapters.js`) — not the toolkit's own
+`scripts/build-agent-adapters.js`, which is wired to the toolkit itself.
+
+```sh
+node scripts/build-agent-adapters.js       # regenerate the adapters
+node scripts/check-agent-adapters.js       # fail if they are stale
+```
+
+The generic generator derives the project name (here `example`, from the
+repository directory name; override with `AGENT_ADAPTER_PROJECT` or an
+`adapters/agent-adapters.config.json` `project` field) and names the Cursor rule
+`adapters/cursor/rules/example.mdc`. Because this example has no local skills,
+the adapters route agents to the toolkit; a project with local skills would have
+them listed automatically. Keep `.github/copilot-instructions.md` as an entry
+point that points to `adapters/github-copilot/copilot-instructions.md`.
 
 ## Validate And Generate
 
@@ -56,7 +91,10 @@ for a new project.
 Use project-local contracts and skills first. If they do not cover this task,
 locate toolkit guidance in this order:
 1. If ARCHITECTURE_KNOWLEDGE_TOOLKIT is set, use that path.
-2. Otherwise check ../architecture-knowledge-toolkit.
+2. Otherwise search upward from the project directory for a local
+   architecture-knowledge-toolkit checkout: check ../architecture-knowledge-toolkit,
+   then the same directory name in each parent directory up to the filesystem
+   root.
 3. Otherwise check any project-local recorded toolkit reference, such as a
    submodule, vendored copy, or pinned path.
 4. Otherwise use
@@ -73,6 +111,15 @@ Create the initial architecture documentation in the toolkit structure:
   .github/copilot-instructions.md, and general-semantic-contracts.md so that
   future architecture and SDLC work delegates missing method guidance to the
   architecture-knowledge-toolkit;
+- reference the toolkit's skills, features, and contract text through the lookup
+  order above instead of copying them; copy only executable tooling that must
+  run here (metamodel schemas, templates, validators, generators, and the generic
+  agent adapter generator from templates/scripts/build-agent-adapters.js and
+  templates/scripts/check-agent-adapters.js -- not the toolkit's own
+  generator, which is wired to the toolkit);
+- generate thin agent adapters under adapters/ that route agents to the toolkit
+  and general-semantic-contracts.md, and keep .github/copilot-instructions.md as
+  an entry point to adapters/github-copilot/copilot-instructions.md;
 - product canvases, vision/mission, roadmap, and Q&A;
 - an assembled architecture entry point and all arc42 chapter source files;
 - proposed ADRs with Pugh matrices where decisions are already visible;
@@ -101,7 +148,10 @@ project artifacts into the toolkit architecture documentation structure.
 Use project-local contracts and skills first. If they do not cover this task,
 locate toolkit guidance in this order:
 1. If ARCHITECTURE_KNOWLEDGE_TOOLKIT is set, use that path.
-2. Otherwise check ../architecture-knowledge-toolkit.
+2. Otherwise search upward from the project directory for a local
+   architecture-knowledge-toolkit checkout: check ../architecture-knowledge-toolkit,
+   then the same directory name in each parent directory up to the filesystem
+   root.
 3. Otherwise check any project-local recorded toolkit reference, such as a
    submodule, vendored copy, or pinned path.
 4. Otherwise use
@@ -118,6 +168,19 @@ Migrate or adapt the documentation to the toolkit structure:
   .github/copilot-instructions.md, and general-semantic-contracts.md so that
   future architecture and SDLC work delegates missing method guidance to the
   architecture-knowledge-toolkit;
+- reference the toolkit's skills, features, and contract text through the lookup
+  order above instead of copying them; copy only executable tooling that must
+  run here (metamodel schemas, templates, validators, generators, and the generic
+  agent adapter generator from templates/scripts/build-agent-adapters.js and
+  templates/scripts/check-agent-adapters.js -- not the toolkit's own
+  generator, which is wired to the toolkit);
+- generate thin agent adapters under adapters/ that route agents to the toolkit
+  and general-semantic-contracts.md, keep .github/copilot-instructions.md as an
+  entry point to adapters/github-copilot/copilot-instructions.md, and migrate any
+  existing hand-written per-agent files into generated adapters;
+- if the repository already has local skills or contracts, keep only the parts
+  that extend the toolkit or explicitly override a specific rule, and drop
+  silent duplicates of toolkit rules;
 - preserve existing useful claims only when supported by repository evidence;
 - convert generic architecture.adoc or Markdown ADRs into toolkit AsciiDoc
   source artifacts where appropriate;

example/adapters/codex/AGENTS.md

@@ -0,0 +1,30 @@
+<!-- GENERATED FILE: edit the canonical skills or scripts/build-agent-adapters.js, then regenerate. -->
+# Codex Adapter
+
+This is a thin Codex-specific wrapper for the example repository.
+example 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 AI-assisted 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 a local toolkit checkout when present (see the lookup order in
+`AGENTS.md`); 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, local `skills/`, and repository-root
+`general-semantic-contracts.md`.

example/adapters/cursor/rules/example.mdc

@@ -0,0 +1,34 @@
+---
+description: example adapter
+alwaysApply: true
+---
+<!-- GENERATED FILE: edit the canonical skills or scripts/build-agent-adapters.js, then regenerate. -->
+# Cursor Rule
+
+This is a thin Cursor-specific wrapper for the example repository.
+example 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 AI-assisted 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 a local toolkit checkout when present (see the lookup order in
+`AGENTS.md`); 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, local `skills/`, and repository-root
+`general-semantic-contracts.md`.