refactor(skills): retrofit the corpus to the ADR-0020 context contract (#129)

Retrofits all 39 skills to ADR-0020's description/body context contract, then fixes what six rounds of independent review found in that retrofit — including four ways the hot gate itself failed open.

Closes #99, #107, #108, #110, #111, #114, #115, #120.

## The retrofit (waves 1-5)

| | Start | Now |
|---|---|---|
| Description FAILs (>400 chars) | 26 | **0** |
| Body FAILs (>900 words, body-only) | 9 | **0** |
| Dangling routing targets | 2 | **0** |
| `Kyberforge.CompositionNote` | 10 | **0** |
| Preload tax | 21,005 chars | **~10,500** |

Under the 12,000-char success criterion. Per-wave detail is on #99.

## The review fixes

**The gate failed open four ways, three of them found after the retrofit shipped.** An unrecognised follower token made a dangling target vanish. A skill directory with no `SKILL.md` resolved as a valid target, so a commit could be green locally and red in a fresh clone — three existing fixtures were relying on that, one of which made the install-leak A/B pass vacuously. Then the free-standing `/name` sweep turned out to be gated on the sentence carrying a boundary marker, so route notation in any other sentence was invisible — not an ERROR, not a SUGGESTION, not an INFO — which left the documented "`/name` always blocks" promise false from a second direction. All four fixed and pinned.

**Two checks were silently not running.** `validate-provenance.sh` checks 7-8 were dead across nine skills. Waking them exposed a deeper problem: they assume `Research doc:` names a source index, but 30 of 121 entries point at topic content documents, so every new check-7 INFO was a false positive and check 8 was saved from a false-FAIL flood only by an *unannounced* skip. Checks 7/8 are now scoped to source indexes and every skip announces itself (#121).

**The retrofit's own anti-goal, four times.** ADR-0020 warns that a blunt gate gets satisfied by deleting content rather than relocating it. `diagnose` and `skill-audit` relocated prose and then read it unconditionally; `prototype` and `vale-config` deleted rules outright that survived nowhere. All four addressed.

## Verification

- `bash tests/run-tests.sh --strict` — 24 suites, 0 skipped, 0 failed
- `bash tests/run-bats.sh` — 325 tests, 0 failures
- `pre-commit run --all-files` — 17/17
- `pre-commit run --hook-stage pre-push --all-files` — 16/16, with `apm marketplace check` and `apm pack --check-clean` run against the remote, not skipped
- `scripts/skill-size-check.sh` over all 39 skills — rc 0, 0 ERROR/FAIL, SUGGESTION-only
- Preload tax measured at **10,498 chars**, max description 390 — both inside budget
- Every new test proven non-vacuous by a deliberate mutation of the behaviour it covers

**Per-commit sync, stated accurately:** the ten commits from the latest review round each pass `check-plugin-content-sync` in isolation, verified by checking each out in a detached worktree with a clean between. The earlier gitea window (`dfacf05..bedbd1d`, nine commits) does **not** — its mirror was regenerated in one batch at `bbc7300`. An earlier revision of this description claimed the property held for every commit; it does not, and a bisect through that window lands on a red commit. **Squash-merge** to collapse it, or accept that this range is not bisectable.

## Version bump

Six plugins and the catalog take a **patch**, not a minor. The branch is **89 commits — 40 `fix` / 30 `refactor` / 12 `docs` / 5 `chore` / 2 `test` — zero `feat`, zero `!`, zero `BREAKING CHANGE`** — and adds no skill, agent, command or hook. (Two earlier revisions of this section cited a stale histogram, most recently 78 commits; the figures above are measured at HEAD.) Both rules this repo ships (`forge/references/version-bump.md`, landing in this PR, and `git-commits/references/conventional-commits-spec.md`) make that a patch, and the catalog set is unchanged at 7 entries.

Not settled by that: four published files were removed from the installed tree, three moved, and `caveman` gained `disable-model-invocation`, retiring its old triggers. Under a strict reading those are major-class and currently ship under `refactor:` with no marker. Whether the deployed skill surface is a public contract is written down nowhere — worth deciding, but it outlives this PR.

## Deliberately not in scope

#112 (cherry-pick ownership, now resolved in favour of `git-commits`), #113 (`rtk git` normalisation), #116 (research fan-out), #101 (audit-skill merge), #122 (non-spec skill-root files), #123 (no PRD producer) stay open. #117 is the one worth reading: the contract's remedy is to move prose into `references/`, which is exactly where neither the size gate nor Vale looks — and the blind spot is wider than #117 currently records, since there is no root `.vale.ini` at all, so every ADR, `CONTEXT.md` and `README.md` is unlinted too.

That blind spot let this branch carry two `level: error` `Kyberforge.SentenceOpenerThereIs` violations into `references/` files it created — `provider-adapter-author/references/provider-matrix.md:31` and `agent-audit/references/finding-criteria.md:95`. Both are reworded in `afadaae`, confirmed by routing each file through the audit's own `vale-wrap.sh` (1 error each before, 0 after). Five further occurrences sit in `references/` files already on `main`; those are the pre-existing corpus and stay with #117, which is the real fix.

Also unfixed and not this PR's: `apm install` appends a duplicate `SessionStart` entry to `.claude/settings.json`, so a fresh clone cannot get pre-push green without an edit AGENTS.md warns against. Reproduces identically on `main`.

Co-authored-by: Defame1297 <gitea@rkdr.net>
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/129
Co-authored-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
Co-committed-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "holocron",
   "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "owner": {
     "name": "Defame1297",
     "email": "defame1297@rkdr.net",
@@ -11,35 +11,35 @@
     {
       "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
-      "version": "1.6.0",
+      "version": "1.6.1",
       "category": "Developer Tools",
       "source": "./plugins/kyberforge"
     },
     {
       "name": "bin",
       "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
-      "version": "1.1.5",
+      "version": "1.1.6",
       "category": "Utilities",
       "source": "./plugins/bin"
     },
     {
       "name": "git",
       "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
-      "version": "1.3.5",
+      "version": "1.3.6",
       "category": "Version Control",
       "source": "./plugins/git"
     },
     {
       "name": "gitea",
       "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
-      "version": "1.3.6",
+      "version": "1.3.7",
       "category": "Version Control",
       "source": "./plugins/gitea"
     },
     {
       "name": "core",
       "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
-      "version": "1.1.1",
+      "version": "1.1.2",
       "category": "Productivity",
       "source": "./plugins/core"
     },
@@ -59,7 +59,7 @@
     {
       "name": "lint",
       "description": "Skills and agents for configuring and running linters.",
-      "version": "1.1.6",
+      "version": "1.1.7",
       "category": "Developer Tools",
       "source": "./plugins/lint"
     }

.github/plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "holocron",
   "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "owner": {
     "name": "Defame1297",
     "email": "defame1297@rkdr.net",
@@ -11,35 +11,35 @@
     {
       "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
-      "version": "1.6.0",
+      "version": "1.6.1",
       "category": "Developer Tools",
       "source": "./plugins/kyberforge"
     },
     {
       "name": "bin",
       "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
-      "version": "1.1.5",
+      "version": "1.1.6",
       "category": "Utilities",
       "source": "./plugins/bin"
     },
     {
       "name": "git",
       "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
-      "version": "1.3.5",
+      "version": "1.3.6",
       "category": "Version Control",
       "source": "./plugins/git"
     },
     {
       "name": "gitea",
       "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
-      "version": "1.3.6",
+      "version": "1.3.7",
       "category": "Version Control",
       "source": "./plugins/gitea"
     },
     {
       "name": "core",
       "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
-      "version": "1.1.1",
+      "version": "1.1.2",
       "category": "Productivity",
       "source": "./plugins/core"
     },
@@ -59,7 +59,7 @@
     {
       "name": "lint",
       "description": "Skills and agents for configuring and running linters.",
-      "version": "1.1.6",
+      "version": "1.1.7",
       "category": "Developer Tools",
       "source": "./plugins/lint"
     }

AGENTS.md

@@ -36,7 +36,7 @@ Fall back to raw shell only when no skill covers it.
 - **Do not add repo-owned keys to `.claude/settings.json`.** apm treats it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. The `SessionStart` entry already in it is exactly that: kyberforge authors it in `plugins/kyberforge/.apm/hooks/hooks.json` and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes in `.pre-commit-config.yaml`.
 - **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook runs `apm outdated` at startup and `apm update --yes` when something is behind, which rewrites the lock. Commit or discard it deliberately.
 - **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs.
-- **The ADR-0020 skill gates ship hot, with no baseline.** 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the `Kyberforge.CompositionNote` Vale rule fires 10 errors across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Editing any of those skills *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. `skill-size-check` will not warn you about the Vale half, so check both: `pre-commit run --all-files`.
+- **The ADR-0020 skill gates ship hot, with no baseline — and the corpus is now clean.** All 39 skills clear both FAIL tiers: no description over 400 characters, no body over 900 words (counted body-only). Retrofitted plugin by plugin under #99 (see `docs/spec/gates.md`). Because nothing is grandfathered, the gates now bite on first commit — a new skill, or an edit that pushes a description past 400, is blocked until it complies. **No routing target dangles**, and `tests/test-adr0020-targets.sh` pins that set as empty, so a new boundary clause naming a non-existent skill fails the suite rather than joining a backlog. Two blind spots survive: `skill-size-check` does not cover the Vale half, so `Kyberforge.CompositionNote` fires nowhere today but any new description can reintroduce it; and no `references/` file is linted by anything, so prose relocated out of a body to satisfy the word gate lands outside the prose gate. It has two independent causes and closing either alone changes nothing — `docs/spec/gates.md` has both, issue #117 tracks it. Check both gates: `pre-commit run --all-files`.
 - **Run `bash tests/run-tests.sh --strict` before considering any change done.** Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
 - **Before pushing, rehearse the gate locally:** `pre-commit run --hook-stage pre-push --all-files`. It runs the 14 pre-push hooks this repo authors itself plus pre-commit's 2 `meta` hooks, so it prints 16; `check-release-needed` passes without checking anything, because it needs a real push to `main`. `docs/spec/gates.md` reconciles both.
 - **Pushing without a network** needs `SKIP=apm-marketplace-check,apm-pack-check-clean git push` — those two resolve a remote marketplace entry via `git ls-remote`. Skip only those two; the rest are real local checks, and adding one to `SKIP` disarms it silently.

CONTEXT.md

@@ -16,8 +16,12 @@ decisions.
 
 **Preload tax**:
 The always-on context cost of every installed skill's `name` and `description`, charged from the
-first token of every session whether the skill is invoked or not. Measurement method and current
+first token of every session whether the skill is invoked or not. Measurement method: ADR-0020. Its
-figure: ADR-0020.
+**23,427 characters is the pre-retrofit baseline, not a current reading** — measured at the decision
+commit, before #99. Across the same 39 skills it is **10,478 characters** (~2,620 tokens) as of
+2026-09-01. Both figures move with the corpus, so re-derive rather than quote either: sum
+`len(name) + len(description)` over the frontmatter of every `plugins/*/.apm/skills/*/SKILL.md`,
+folding block scalars as `scripts/skill-size-check.sh` does.
 _Avoid_: context cost, token overhead
 
 **Skill context contract**:
@@ -26,6 +30,14 @@ trigger clause, at most one capability clause, and a boundary clause, and nothin
 and the target-resolution walk: `docs/spec/gates.md`.
 _Avoid_: skill budget, size limit
 
+**Routing target**:
+The skill or agent name a boundary clause sends work to. It **resolves** when a skill or agent of
+that name is reachable from the file being checked, and **dangles** when none is — a route the router
+cannot take. Dangling is a blocking ERROR in route notation (`/name`, `→ name`) and a SUGGESTION for
+a bare name nothing else in the sentence corroborates. Verdicts and the resolution walk:
+`docs/spec/gates.md`.
+_Avoid_: route, pointer, cross-reference
+
 **Dispatch body**:
 The body pattern a skill with two or more mutually exclusive flows must use — the body carries only
 the dispatch table and the gates common to every branch, and each flow lives in its own
@@ -35,7 +47,9 @@ _Avoid_: router body, thin body
 **Hand-invoked skill**:
 A skill reached only by typing its slash command, declared `disable-model-invocation: true`. The host
 withholds it from the model-visible listing entirely, so it pays no preload tax and its description
-becomes human-facing text. Exemplar: `zoom-out`.
+becomes human-facing text. The flag also hard-blocks the Skill tool, so **no other skill can route to
+a hand-invoked skill** — a `` Call `x` `` step in another skill's body stops working the moment `x`
+takes the flag. Check inbound routes before declaring one. Exemplar: `zoom-out`.
 _Avoid_: manual skill, disabled skill
 
 **Delegation discipline**:

apm.lock.yaml

@@ -1,12 +1,12 @@
 lockfile_version: '1'
-generated_at: '2026-08-17T06:44:18.931217+00:00'
+generated_at: '2026-08-30T11:38:46.419301+00:00'
 apm_version: 0.28.0
 dependencies:
 - repo_url: Defame1297/holocron
   name: bin
   host: git.dev.rkdr.net
-  resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
+  resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
-  version: 1.1.3
+  version: 1.1.5
   virtual_path: plugins/bin
   is_virtual: true
   package_type: marketplace_plugin
@@ -81,13 +81,13 @@ dependencies:
     .claude/skills/triage/SKILL.md: sha256:b819f0285e4e5814ac6472d0217f07dc9f23d2fdae3ebb0dd31d98360d8ac029
     .claude/skills/write-docs/SKILL.md: sha256:0d06d0f6836a67532497ea61bd5a1294a8d80f529bf1ffb5c4b1fdc72e9cb51a
     .claude/skills/zoom-out/SKILL.md: sha256:2a6894c7f9b1c9c55f451c625a834c4f377e217b623a85280e55db5fe9cacf48
-  content_hash: sha256:7acfaa806ae8379fe6351441ce8f973ac3ff8a02deb4a5e145968203d1176ef8
+  content_hash: sha256:d7cca4972651b241a5450679289fdb6f0e3a37aef9dff0498cb4b3340b048781
   declared_license: MIT
   exec_status: gated_pending_approval
 - repo_url: Defame1297/holocron
   name: core
   host: git.dev.rkdr.net
-  resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
+  resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
   version: 1.1.1
   virtual_path: plugins/core
   is_virtual: true
@@ -134,8 +134,8 @@ dependencies:
 - repo_url: Defame1297/holocron
   name: git
   host: git.dev.rkdr.net
-  resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
+  resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
-  version: 1.3.3
+  version: 1.3.5
   virtual_path: plugins/git
   is_virtual: true
   package_type: marketplace_plugin
@@ -236,13 +236,13 @@ dependencies:
     .claude/skills/pc-run/references/README.md: sha256:ad42b9013dbd44b8c4515c15317c5e9e6b235bc656ad5a03e037eb4bc6f8782c
     .claude/skills/pc-run/references/failure-patterns.md: sha256:59d913c001483c3770d269fdf5e83cf1d7578e0ae879928a1404bf93bb395994
     .claude/skills/pc-run/references/sources.md: sha256:7ca8b7106e7ee5c2c7d1fbd3dc9e0d2a89c18eba79145cbab55bc8e39eef9087
-  content_hash: sha256:6d0c8fcec32d8fb8321b539cc567c4241342cfa33e5d0b6f66697d2f8b784fdd
+  content_hash: sha256:8c47bd35572c331f1a1b61a8be159d9690a1bf286958a85826fde01939e3007b
   declared_license: MIT
 - repo_url: Defame1297/holocron
   name: gitea
   host: git.dev.rkdr.net
-  resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
+  resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
-  version: 1.3.4
+  version: 1.3.6
   virtual_path: plugins/gitea
   is_virtual: true
   package_type: marketplace_plugin
@@ -313,10 +313,10 @@ dependencies:
     .claude/skills/gitea-labels-milestones/references/labels.md: sha256:be8ff5ce4dbfb31dd2bdcc425a769dca94887c5c8acd47c78e1e21ccfc24dcba
     .claude/skills/gitea-labels-milestones/references/milestones.md: sha256:ff1f1b0c8ecb6967c940d1ca8bebf2a2c7995414936f8ac7f5ff23d1dc01ac3f
     .claude/skills/gitea-labels-milestones/references/sources.md: sha256:a1a1d3381dfb0dc8f331be0b3ab49f28e94b992fb4809ca09be91ce33047dd1e
-    .claude/skills/gitea-prs/README.md: sha256:0346388f642641c56cef82ba1ee576a187d048eee66fab839a17417c81122cbc
+    .claude/skills/gitea-prs/README.md: sha256:31b6ad46379feee8ac7d837030f93ec04be20b7d11021b295dc6d27b4340a05b
     .claude/skills/gitea-prs/SKILL.md: sha256:bf70832f3d97064c9816d680390da84c256a971d7804317e1814b4ee6a622b4d
     .claude/skills/gitea-prs/references/merging.md: sha256:5f8b55b1a729f122ee265fb5da69369fc27434a13dd02fc112801f945d2c9d19
-    .claude/skills/gitea-prs/references/pull-requests.md: sha256:631874a7cddfcf678a2beffa5578fa7848bcef36be1251fa13fb0ccc543bcaf7
+    .claude/skills/gitea-prs/references/pull-requests.md: sha256:d6cefd0cf270f8d844536311e67bfa45cd07f024aa0a649de1938af306ae7109
     .claude/skills/gitea-prs/references/reviews.md: sha256:1089cf45a75a562bbb29de6538848c4f4bd627d5a7e36bf9b2ab6496f45f962b
     .claude/skills/gitea-prs/references/sources.md: sha256:ac48a3018443b56acb5c3d55d6c04e62103f5bac71b8185e2bd085fb7e165431
     .claude/skills/gitea-releases/README.md: sha256:102625066c34c7b5a16e25b7506a87f876e9b123b334f5ffba73ab1523a57ed7
@@ -327,12 +327,12 @@ dependencies:
     .claude/skills/gitea-workflow/README.md: sha256:338f79d0b3c25741848fce841a5094ef27cbc7e4a6228404557b2d9594df68fa
     .claude/skills/gitea-workflow/SKILL.md: sha256:a8266ceb335c56eb68cc09b3f81690c52c4dada9f25b48c3a46ac46b0ad3b761
     .claude/skills/gitea-workflow/references/sources.md: sha256:171d3a5a36cb9d637302516501a1e9fc7a4bd058968dc9244412c335aa2de68b
-  content_hash: sha256:8149467df78678963dbb140aa254f606a53491f3cb7e5d97a1211be426e7892e
+  content_hash: sha256:16d5b4462c3f4a506c1c74172d4d67bf0dacc4218676de4e8dfe551b2f31a3f8
   declared_license: MIT
 - repo_url: Defame1297/holocron
   name: kyberforge
   host: git.dev.rkdr.net
-  resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
+  resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
   version: 1.6.0
   virtual_path: plugins/kyberforge
   is_virtual: true
@@ -530,7 +530,7 @@ dependencies:
 - repo_url: Defame1297/holocron
   name: lint
   host: git.dev.rkdr.net
-  resolved_commit: 9385c77ac71a67db2b8fe9c3783af9e0fbbf2eae
+  resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
   version: 1.1.6
   virtual_path: plugins/lint
   is_virtual: true
@@ -1873,7 +1873,7 @@ deployments:
   owners:
   - git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
   active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
-  content_hash: sha256:0346388f642641c56cef82ba1ee576a187d048eee66fab839a17417c81122cbc
+  content_hash: sha256:31b6ad46379feee8ac7d837030f93ec04be20b7d11021b295dc6d27b4340a05b
 - kind: project-relative
   target: claude
   value: .claude/skills/gitea-prs/SKILL.md
@@ -1900,7 +1900,7 @@ deployments:
   owners:
   - git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
   active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
-  content_hash: sha256:631874a7cddfcf678a2beffa5578fa7848bcef36be1251fa13fb0ccc543bcaf7
+  content_hash: sha256:d6cefd0cf270f8d844536311e67bfa45cd07f024aa0a649de1938af306ae7109
 - kind: project-relative
   target: claude
   value: .claude/skills/gitea-prs/references/reviews.md

apm.yml

@@ -1,5 +1,5 @@
 name: holocron
-version: 0.4.5
+version: 0.4.6
 description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
 license: MIT
 
@@ -42,7 +42,7 @@ dependencies:
 # after a kyberforge release, check this first.
 executables:
   allow:
-    kyberforge#1.6.0:
+    kyberforge#1.6.1:
       hooks: true
       bin: true
 
@@ -52,7 +52,7 @@ marketplace:
   # top-level apm.yml description:/version: above are NOT inherited into the
   # compiled output despite being used elsewhere (e.g. by `apm audit`).
   description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
-  version: 0.4.5
+  version: 0.4.6
   owner:
     name: Defame1297
     email: defame1297@rkdr.net
@@ -79,31 +79,31 @@ marketplace:
     - name: kyberforge
       description: Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.
       source: ./plugins/kyberforge
-      version: 1.6.0
+      version: 1.6.1
       category: Developer Tools
 
     - name: bin
       description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
       source: ./plugins/bin
-      version: 1.1.5
+      version: 1.1.6
       category: Utilities
 
     - name: git
       description: Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.
       source: ./plugins/git
-      version: 1.3.5
+      version: 1.3.6
       category: Version Control
 
     - name: gitea
       description: Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.
       source: ./plugins/gitea
-      version: 1.3.6
+      version: 1.3.7
       category: Version Control
 
     - name: core
       description: Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
       source: ./plugins/core
-      version: 1.1.1
+      version: 1.1.2
       category: Productivity
 
     - name: mattpocock-skills
@@ -115,5 +115,5 @@ marketplace:
     - name: lint
       description: Skills and agents for configuring and running linters.
       source: ./plugins/lint
-      version: 1.1.6
+      version: 1.1.7
       category: Developer Tools

docs/adr/0020-skill-description-and-body-context-contract.md

@@ -127,8 +127,15 @@ clause**, and a **boundary clause**. Capability enumeration, output-format detai
   gate shipping hot with no baseline cannot give two answers. Under the walk-up those four resolve
   because sibling plugins are in the universe — no plugin here declares a cross-plugin apm
   dependency, and none needs to. Verified: a tree holding only `plugins/` and the root `apm.yml`,
-  with no `.claude/` or `.agents/` anywhere, now produces findings identical to the working tree —
+  with no `.claude/` or `.agents/` anywhere, produced findings identical to the working tree. The
-  26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs.
+  figures that reproduction recorded — 26 description FAILs, 9 body FAILs, 2 dangling targets, 0
+  missing references, 58 SUGGESTIONs — are the **pre-retrofit** corpus as it stood when the
+  experiment ran, kept here as the evidence for the install-independence claim, not as a current
+  reading. *Amended 2026-09-01: the #99 retrofit took the first three to zero. Measured at that
+  date over the same install-free tree: 0 description FAILs, 0 body FAILs, 0 dangling targets, 0
+  missing references, 29 SUGGESTIONs.* What the experiment establishes is that the two trees agree,
+  not what either measured; re-derive rather than quote —
+  `bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md`.
 - **The universe is the apm marketplace, and nothing else.** A routing target resolves to a skill or
   an agent, or it does not resolve. Host built-ins are deliberately outside it: `/compact`, `/clear`
   and `/init` are Claude Code slash commands with no counterpart in Copilot CLI or Codex, so a
@@ -185,8 +192,11 @@ becomes the system prompt of a fresh context. The rationale for the 900-word FAI
 That exemption is expressed in `agent-audit/scripts/validate.sh`, which has no body constant, and in
 the `files:` pattern of the `skill-size-check` pre-commit hook, which is `SKILL.md`-only. It is *not*
 expressed in `scripts/skill-size-check.sh` itself, which measures whatever path it is handed —
-running it directly over `plugins/*/.apm/agents/*.agent.md` today reports 900-word body FAILs on
+running it directly over `plugins/*/.apm/agents/*.agent.md` exits 1 with 900-word body FAILs on
-`git-orchestrate` (933), `gitea-orchestrate` (1,199) and `apm-orchestrate` (1,080). Agents escape by
+`git-orchestrate` and `gitea-orchestrate`. *Amended 2026-09-01: this sentence named a third agent,
+`apm-orchestrate`, at 1,080 words. It is 876 today — a SUGGESTION, not a FAIL. Counts are
+deliberately no longer pinned here: agent bodies are edited like any other file and a figure in this
+paragraph goes stale the moment one is trimmed. Run the command.* Agents escape by
 file pattern, not by the script knowing the difference. Anyone widening that pattern to cover agents
 would silently enforce a gate this ADR declines to set.
 
@@ -203,8 +213,14 @@ with no trigger list.
 
 Verified end-to-end rather than assumed: `plugins/bin/.apm/skills/zoom-out/SKILL.md:4` carries the
 flag, apm passes it through verbatim to both `.claude/skills/zoom-out/SKILL.md:4` and the flat mirror
-at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` is the one installed skill absent from
+at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` was — at the time of that check, when it
-the model-visible skill listing in a live session. It remains invocable as `/zoom-out`.
+was the only carrier — the one installed skill absent from the model-visible skill listing in a live
+session. It remains invocable as `/zoom-out`. `caveman` has since taken the flag as well, so the
+corpus now has **two** carriers. Do not read a carrier list off this page; re-derive it:
+
+```
+grep -l '^disable-model-invocation: true' plugins/*/.apm/skills/*/SKILL.md
+```
 
 ### Merging siblings
 
@@ -219,10 +235,13 @@ rather than the core job.
 skills still exist separately, and this change made the split deeper rather than shallower: retrofit
 to the dispatch pattern took `skill-audit` from 3 reference files to 7 and `agent-audit` from 4 to 8,
 and their two same-named `references/description-quality.md` files now differ on 100 of ~120 lines
-after normalising `skill`/`agent`, where before they were closer. The merge stays the decision; it
+after normalising `skill`/`agent`, where before they were closer. It has kept deepening since: the
-reopens ADR-0008 (agent-audit's single-file invocation contract) and touches every call site in
+#99 retrofit added `finding-criteria.md` to `skill-audit`, drawing it level with `agent-audit`. Both
-`skill-author`, `agent-author` and `forge`, which is why it is its own change and not a rider on
+figures move with the next retrofit, so measure rather than quote —
-this one. Recorded here rather than dropped, so the gap between the rule and the tree is deliberate
+`ls plugins/kyberforge/.apm/skills/<name>/references/ | grep -c '\.md$'`. The merge stays the
+decision; it reopens ADR-0008 (agent-audit's single-file invocation contract) and touches every call
+site in `skill-author`, `agent-author` and `forge`, which is why it is its own change and not a rider
+on this one. Recorded here rather than dropped, so the gap between the rule and the tree is deliberate
 and dated instead of discovered later.
 
 ### Enforcement and rollout
@@ -233,11 +252,13 @@ which tier each rule is in, because the failure this ADR is most exposed to is a
 
 | Check | Applies to | Tier | Home |
 |---|---|---|---|
-| description characters (250 SUGGESTION / 400 FAIL) | skills, agents | deterministic | `scripts/skill-size-check.sh`; constants mirrored in `skill-audit/scripts/validate.sh` and `agent-audit/scripts/validate.sh` |
+| description characters (250 SUGGESTION † / 400 FAIL) | skills, agents | deterministic | `scripts/skill-size-check.sh`; constants mirrored in `skill-audit/scripts/validate.sh` and `agent-audit/scripts/validate.sh` |
 | body-only words (600 SUGGESTION / 900 FAIL) | skills | deterministic | `skill-size-check.sh`, `skill-audit/scripts/validate.sh` |
 | description present and non-empty (ERROR) | skills, agents | deterministic | same |
-| boundary target resolves to a real skill or agent (ERROR when written as `/name` or `-> name`, or when its own sentence names another target that resolves; SUGGESTION otherwise) | skills, agents | deterministic | same |
+| boundary target resolves to a real skill or agent — **three** verdicts, not two (ERROR when written in route notation — `/name`, or any arrow form; or when a *terminal* bare name's own sentence names another target that resolves. SUGGESTION otherwise. INFO, "DID NOT RUN", exit 0, when no skill universe could be determined for the path at all — no authoring root above it, no apm package root, no declared apm dependencies, no deployed `.claude/` or `.agents/` tree: the targets are named and left unchecked) | skills, agents | deterministic | same |
-| boundary clause absent (SUGGESTION) | skills, agents | deterministic | same |
+| boundary clause absent — `absent` (SUGGESTION) † | skills, agents | deterministic | same |
+| an arrow clause is present but no target can be read out of it — `unparsed` (SUGGESTION) † | skills, agents | deterministic | same |
+| one arrow clause naming two or more targets, of which only the first is resolved (SUGGESTION, issue #107) † | skills, agents | deterministic | same |
 | Gotchas entry count over five (SUGGESTION) | skills | deterministic | same |
 | Gotchas over 25% of the body (SUGGESTION) | skills | deterministic | same |
 | every `references/<file>.md` a body names exists (ERROR) | skills | deterministic | same |
@@ -254,6 +275,21 @@ that guessed at them would be a worse gate than no gate, because it would be bel
 enforced, they are reviewed, and this table exists so that distinction is written down rather than
 inferred from whether a validator happens to have been written yet.
 
+**† These four, and only these four, are lifted for a hand-invoked file** — one whose frontmatter
+carries `disable-model-invocation: true`, read as a boolean by `hand_invoked()` in all three scripts.
+No validator knew the field existed (issue **#108**), so every routing SUGGESTION above fired on
+exactly the shape the *Invocation as a design axis* section mandates, and the boundary-clause
+remedy — "so the router knows where NOT to send this skill" — was addressed to a router that cannot
+see the skill at all. An author who took the advice made the file worse.
+
+What does **not** lift is the point of the carve-out. Both body word tiers stand: the body is still
+loaded on invocation and still competes with the caller's live conversation. The 400-character
+description FAIL stands: that description is not preloaded, but it is the one line a user reads when
+choosing from the `/` menu, and the ceiling is an outlier stop rather than a routing-quality budget —
+which is exactly why the 250-character *target* is the tier that lifts. And a target the description
+does happen to name is still resolved and can still dangle as a blocking ERROR. Mechanics, and the
+reason the field is read as a boolean rather than as a mention of the key: `docs/spec/gates.md`.
+
 Two of the deterministic rows are tuned for **false positives over recall**, and what they decline to
 see is part of the contract. On target extraction: a bare hyphenated name counts only inside a
 boundary sentence, and a single-word name is never matchable bare — `research`, `triage`, `forge`,
@@ -264,7 +300,8 @@ raise an error: one followed by an ordinary lowercase noun is a compound **modif
 confirm-only — it still resolves and still counts as a route when the name exists, but it can never
 dangle. Only a *terminal* target can. The compressed arrow form `→ <name>` is exempt from that
 follower test and is always error-eligible, because nothing reads as a compound modifier after an
-arrow; a `/slash` target reached through a route verb is **not** exempt and takes the same test. The
+arrow; a `/slash` target reached through a route verb is **not** exempt and takes the same test.
+*Amended 2026-08-31 — the `/slash` half is reversed: it is exempt too. See the amendment below.* The
 simpler rule — "only marked targets may dangle" — was available and would have been wrong here: both
 live true positives are bare, `research`'s "(use neuledge-context)" and the `gitea-labels-` /
 `milestones` fold. On the body-shape checks: a `## Gotchas` heading must *end* in "gotchas", not
@@ -296,6 +333,46 @@ Three pre-existing contradictions are fixed in the same change, because they are
 - `description-quality.md:45-50` has no FAIL condition for internal-mechanics content, which is why
   `skill-author/SKILL.md:102` never bit.
 
+## Amendment (2026-08-31): route notation short-circuits the follower test, `/name` included
+
+The Enforcement section above exempts the arrow form from the follower test and then withholds the
+same exemption from `/name`: "a `/slash` target reached through a route verb is **not** exempt and
+takes the same test." That half is reversed. **Both spellings of route notation are exempt, and the
+exemption is decided before the follower test rather than weighed against it.**
+
+Three things make the original call wrong rather than merely strict.
+
+**It contradicted the promise the same paragraph makes.** Route notation is offered to an author as
+the way to get a target checked unconditionally — the SUGGESTION text on an unpromoted target says
+so in as many words: "write it as `/name` or `-> name` and it will be checked properly." Under the
+original rule that was true of one of the two spellings. `-> name` reached `_add()` with
+`strict=True` from both its call sites; `/name` did not, so it fell through to `_terminal()` and any
+follower outside `FOLLOWER_OK` demoted it. `Do not use for Y — use /no-such-skill afterwards.` exited
+0 — and, before the companion visibility fix, in total silence.
+
+**The follower test's own justification does not reach `/name`.** That test exists for *prose*: a
+bare hyphenated token followed by an ordinary lowercase noun is a compound modifier, "pre-commit
+hooks" and "pull-request template". A leading slash is Claude Code's invocation syntax and occurs in
+no English compound, so there is no attributive reading to protect. The exemption was withheld from
+the one shape the rule it protects against cannot describe.
+
+**`FOLLOWER_OK` is a closed whitelist of roughly eighty words, and a closed list is the wrong thing
+to hang a blocking gate on.** Leaving `/name` under it made *whether a commit is blocked* depend on
+whether someone had thought to enumerate the next word — the gate failing open on its own
+unfamiliarity. The bare-target path keeps the follower test precisely because it needs a brake it can
+justify; the notation path asked for one and was given the same brake by accident.
+
+What is unchanged: the **corroboration** branch. A *bare* terminal name still earns its blocking
+ERROR only from a resolving sibling in the same sentence, and a compound modifier still cannot
+dangle at all. The conservative tuning that decision rests on is untouched — this amendment moves one
+explicitly-marked spelling out from under it, not the prose path.
+
+Verified on fixtures inside a synthetic plugin tree: `… Do not use for Y — use /no-such-skill
+afterwards.` exits 1, while the same sentence with the bare `no-such-skill` exits 0 at SUGGESTION,
+and rises to a blocking ERROR the moment a resolving sibling joins it. The reasoning is recorded at
+the point of enforcement in `_add()`'s docstring in `scripts/skill-size-check.sh` and its two
+mirrored copies, and the verdict table in `docs/spec/gates.md` states the corrected shape.
+
 ## Consequences
 
 **Editing any non-compliant skill now requires retrofitting it first.** At decision time, 30 of 39
@@ -311,10 +388,17 @@ carries is the ordinary one for hot gates: a gate expensive enough to be inconve
 with `SKIP=` and loses its authority.
 
 **A second hot gate ships alongside it, and it is easy to miss.** `Kyberforge.CompositionNote` is
-`level: error` like every other rule in that style, so `pre-commit run --all-files` is red on 10
+`level: error` like every other rule in that style, so at decision time `pre-commit run --all-files`
-alerts across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`
+was red on 10 alerts across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and
-independently of anything `skill-size-check` reports. Someone scoping the #99 retrofit off the size
+`gitea-workflow` independently of anything `skill-size-check` reports. Someone scoping the #99
-findings alone will fix those and still be blocked. The two gates want fixing together.
+retrofit off the size findings alone would have fixed those and still been blocked. The two gates
+wanted fixing together, and were. *Amended 2026-09-01: that figure is historical. The Vale prefilter
+over the same 39 files now reports 0 errors, 0 warnings and 0 suggestions, so
+`Kyberforge.CompositionNote` fires nowhere in the corpus today. The rule is still hot and still
+independent of `skill-size-check`, so a new description can reintroduce it; `skill-size-check` does
+not cover the Vale half, and no `references/` file is linted by anything (`docs/spec/gates.md` has
+both causes, issue #117 tracks them). Re-derive rather than quote —*
+`bash plugins/kyberforge/.apm/skills/skill-audit/scripts/vale-wrap.sh plugins/*/.apm/skills/*/SKILL.md`.
 
 **A ceiling does not produce an average.** If every author writes to the 400-character FAIL, the
 preload lands at 39 × 400 = 15,600 chars — a 33% cut off 23,427, not the ~50% intended. Writing to
@@ -342,8 +426,8 @@ and `git-*` families — where every sibling shares a keyword and boundary claus
 — are the ones most likely to sit at the FAIL tier permanently. If the retrofit shows that family
 routing degrades, the tier is the first thing to revisit.
 
-**Four broken routing targets were found; two are fixed here and two are live.** Tracked as issue
+**Four broken routing targets were found; two were fixed here and two shortly after.** Tracked as
-#100.
+issue #100.
 
 - `skill-audit` routed to `/skill-improve` twice in its description plus `README.md:10`, and no such
   skill exists — the real target is `skill-author`. **Fixed here**, as a side effect of retrofitting
@@ -353,14 +437,24 @@ routing degrades, the tier is the first thing to revisit.
   detectable by the resolvable-target check and never will be: "examine agent files manually" names
   no target, and a check that resolves names cannot see a name that is absent. A misroute to nowhere
   is a review finding, not a gate finding.
-- `research` routes to `neuledge-context`, which exists only inside that string. **Live.**
+- `research` routes to `neuledge-context`, which exists only inside that string. Was **live**;
+  **fixed under #99** — the retrofitted description names no such target.
 - `gitea-issues` carries the literal string `gitea-labels- milestones` in its folded description, a
-  stray space introduced by YAML wrapping mid-token, breaking the skill name in preloaded text.
+  stray space introduced by YAML wrapping mid-token, breaking the skill name in preloaded text. Was
-  **Live** — the check reports it as a dangling `gitea-labels`.
+  **live**, reported as a dangling `gitea-labels`; **fixed under #99** — the name now folds intact.
 
-So the check fires on 3 of the 4 against the base commit and on 2 at the tip of this change, and
+So the check fired on 3 of the 4 against the base commit and on 2 at the tip of the change that
-`tests/test-skill-size-check.sh` probes exactly those three by name rather than asserting a count, so
+carried this ADR. **The corpus dangling set is now empty**, and that is asserted rather than
-it degrades to SKIP as #100 lands rather than going stale.
+observed: `tests/test-adr0020-targets.sh` pins the set as empty, so a new boundary clause naming a
+non-existent skill fails the suite instead of joining a backlog. `tests/test-skill-size-check.sh`
+probed the three original names rather than asserting a count; as each was retrofitted its probe was
+**removed, not skipped**, because a `pass "SKIP: …"` branch is an assertion-free result counted in
+the totals and makes the suite look one test stronger than it is. That file's commentary survives the
+probes and states the rule. Re-derive the current set — never read it off this page:
+
+```
+bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep 'does not resolve'
+```
 
 **Duplication between `skill-author` and `agent-author` survives un-gated.** The merge rule
 deliberately excludes the author pair, so the commit-verification argument in four near-copies, the

docs/spec/gates.md

@@ -98,11 +98,57 @@ loudly (`Error: jq is required but not installed`).
 ## Skill and agent context gates (ADR-0020)
 
 The `skill-size-check` pre-commit hook, scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$`,
-runs `scripts/skill-size-check.sh`. That scope means it never lints the
+runs `scripts/skill-size-check.sh`. It is also shipped to external repos as
-`plugins/kyberforge/docs/research/examples/` reference skills. It is also shipped to external repos
+`kyberforge-skill-size-check` (see
-as `kyberforge-skill-size-check` (see
 [External consumers](#external-consumers-the-root-pre-commit-hooksyaml)).
 
+**Two things fall outside that scope, both deliberately.** The `[^/]+/SKILL\.md$` tail admits only a
+`SKILL.md` sitting directly in a skill directory under `.apm/skills/`:
+
+- the `plugins/kyberforge/docs/research/examples/` reference skills, which are vendored upstream
+  corpus and not this repo's to gate;
+- `plugins/kyberforge/.apm/skills/skill-author/assets/templates/SKILL.md` — inside `.apm/skills/`,
+  but two directories deeper. It is the `FILL IN:` scaffold `skill-author` copies, so its
+  `description: >` is a comment block rather than a description and every ADR-0020 measurement over
+  it would be meaningless. A reader adjusting the pattern needs to know it is there.
+
+Everything else it matches exactly, with nothing over- or under-caught. Re-derive both halves:
+
+```
+git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'          # the real skills
+git ls-files | grep -E '^plugins/[^/]+/\.apm/skills/.*SKILL\.md$' \
+             | grep -vE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'          # the scaffold only
+```
+
+The first count equals the number of skill directories (`ls -d plugins/*/.apm/skills/*/ | wc -l`);
+the second returns exactly the template. The remaining unmatched `SKILL.md` files in the tree are the
+generated flat mirror, which is excluded by the `.apm/` segment on purpose — a mirror edit is drift,
+not an authoring change.
+
+### `skill-frontmatter`, the other hook on that scope
+
+A second `repo: local` pre-commit hook, `skill-frontmatter`, runs on the **same** `files:` pattern at
+the same stage. It is a short shell loop: for each file, `grep -q "^name:"` and
+`grep -q "^description:"`, failing with "missing required frontmatter fields" if either is absent.
+
+**It overlaps ADR-0020's "description present and non-empty" FAIL, and the overlap is not clean.**
+The ADR (`:95-101`) requires that question be decided on the **YAML-folded value** and nowhere else,
+precisely because a line regex gets it wrong in both directions. Measured on fixtures:
+
+| Frontmatter | `skill-frontmatter` | `skill-size-check` |
+|---|---|---|
+| `description:` with no value, then `model: sonnet` | passes — the key is on a line | ERROR, "missing or empty" |
+| `"description": …` (quoted key, valid YAML) | **fails** — `^description:` does not match | passes, description read normally |
+
+So the grep is not a second opinion on presence. It is blind to the shape ADR-0020 was written
+against, and it is the only one of the two that objects to a quoted key. Neither disagreement is
+currently live in the corpus, and the honest reading is that presence is `skill-size-check`'s
+question — the grep's contribution to it is noise on one shape and silence on the other.
+
+What the grep does add is the `name:` key, which **no** ADR-0020 check reads: a `SKILL.md` with no
+`name:` passes `skill-size-check` at exit 0. That is its real and only unique coverage, and the
+reason not to fold it into the size gate on the grounds of redundancy.
+
 ### Two independent gate families, neither replaced the other
 
 **Family 1 — agentskills.io spec backstop** (unchanged, conformance not quality):
@@ -141,7 +187,7 @@ A boundary-clause target that resolves to no skill or agent has **three** possib
 | Verdict | When |
 |---|---|
 | **SUGGESTION** — the default | the target does not resolve and neither promotion condition below holds |
-| **blocking ERROR** | the target is **terminal** (not a compound modifier) **and** either written in route notation (`/name` for any name; `-> name` only when the name is hyphenated — see the gap below) **or** corroborated by another target in the same sentence that *does* resolve |
+| **blocking ERROR** | the target is written in **route notation** — `/name` for any name, or any arrow form (a bare `-> name` only when the name is hyphenated, a backticked `` -> `name` `` for any — see the gap below); **or** it is a bare **terminal** name (not a compound modifier) **corroborated** by another target in the same sentence that *does* resolve |
 | **INFO, "DID NOT RUN"** | no skill universe could be determined for the path at all — the targets are named and left unchecked, exit 0 |
 
 The default is deliberately soft because a hyphenated word in a boundary clause is as likely to be a
@@ -149,14 +195,36 @@ tool, a file format or an English compound as a route: "pre-commit hooks" is pro
 never reaches the check at all, being a compound modifier rather than a terminal name. The
 SUGGESTION text says how to opt in — write it as `/name` or `-> name` and it gets checked properly.
 
-**Known gap: the arrow form only works for hyphenated names.** Target extraction is built on
+**The two promotion conditions are not symmetric, and the order matters.** `_add()` decides
-`NAME_HYPH` (`scripts/skill-size-check.sh:543`), which requires at least one hyphen, and
+**notation first**: when the name is written `/name`, or reached through any arrow form, the target
-`ARROW_BOUNDARY` (`:561`) inherits that. So `-> gitea-prs` is extracted and checked, while
+is marked error-eligible there and the terminal test is never run. Terminality gates only the *bare*
-`-> triage` is not extracted at all — no ERROR, no SUGGESTION, exit 0. The unicode arrow `→` is not
+path — a name in prose earns its error from corroboration, and a compound modifier can never dangle.
-recognised in either case. This makes the SUGGESTION's own advice unsafe for a single-word skill:
+Reading the row as "terminal AND (notation OR corroborated)" gets the notation half backwards: it
-taking it silences the finding rather than checking it. `/name` has no such restriction and is the
+predicts that `` … Do not use for Y — use /no-such-skill afterwards. `` is a SUGGESTION, because
-form to prefer. Tracked as a defect; `tests/test-adr0020-targets.sh` has one arrow case and its
+`afterwards` is a follower outside `FOLLOWER_OK`. It exits 1. That was the defect — `-> name` reached
-target happens to be hyphenated, so nothing currently covers this.
+`_add()` with `strict=True` from both its call sites and `/name` did not, so the one spelling
+ADR-0020 offers an author who wants a route checked unconditionally was the one spelling a stray
+follower could silence.
+
+**Known gap: a BARE arrow target must be hyphenated.** Target extraction is built on `NAME_HYPH` in
+`scripts/skill-size-check.sh`, which requires at least one hyphen, and `ARROW_BOUNDARY` inherits
+that. So `Not X -> gitea-prs` is extracted and checked, while `Not X -> triage` yields no target.
+The exclusion is deliberate, not an oversight: `research`, `triage`, `forge`, `prototype` and `tdd`
+are all real skill names *and* ordinary English, so a bare single-word rule would flag most of the
+corpus. The marked spellings carry no such restriction — `` `triage` `` and `/triage` are both
+extracted — and are the forms to prefer. **Both arrow spellings are recognised:** `ARROW_MARKED`,
+`ARROW_BOUNDARY` and `BOUNDARY_ARROW` are each built from `(?:->|→)`, so the unicode arrow `→`
+behaves exactly like `->` in every case below. Cite these constants by symbol name, never by line
+number: the script moves often enough that a pinned line lands a reader in an unrelated comment
+block and reads as plausible.
+
+**The gap is no longer silent.** It used to be exactly that — no ERROR, no SUGGESTION, exit 0 — which
+made the dangling-target SUGGESTION's own advice unsafe for a single-word skill: taking it silenced
+the finding instead of checking it. `boundary_clause_status()` now separates the case out and
+reports it as `unparsed` (see below), naming the parse failure and the two spellings that fix it.
+The target is still not *resolved*; the author is now told so rather than left with a green gate.
+`tests/test-adr0020-targets.sh` covers both directions (`arrow-single-word-target` and the silent
+control `arrow-single-word-marked`).
 
 Corroboration is what makes the soft default safe: a sentence whose *other* target resolves is
 demonstrably a routing sentence, so a sibling that does not resolve is a typo rather than a noun, and
@@ -200,17 +268,109 @@ through `.claude/skills/` alone, so **the same commit measured 2 dangling target
 machine and 6 on a fresh clone**. A gate shipping hot with no baseline cannot give two answers.
 
 Verified fixed: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no
-`.claude/` or `.agents/` anywhere, produces findings identical to the working tree — **26 description
+`.claude/` or `.agents/` anywhere, produced findings identical to the working tree. The figures that
-FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs**.
+reproduction recorded — 26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references
+— are the pre-retrofit corpus as it stood when the experiment was run, kept here as the evidence for
+the install-independence claim. They are not current: the retrofit under #99 took the first three to
+zero. What the experiment establishes is that the two trees agree, not what either measured.
+
+### Boundary-clause detection: three outcomes, not two
+
+`boundary_clause_status()` returns one of three values, and the two findings get separate messages:
+
+| Status | When | Reported as |
+|---|---|---|
+| `present` | a prose marker (`do not`, `instead`, `rather than`, `not for`) or an arrow clause was found | nothing |
+| `absent` | neither was found | SUGGESTION: add a boundary clause, in either form |
+| `unparsed` | an arrow clause was found and **no target could be read out of it** | SUGGESTION: the clause is present — this is a *parse* failure, not a missing clause |
+
+The third had to be split out. Collapsing it into `absent` is a **wrong** finding, not a strict one:
+it sends the author to add a clause that is already there. Three of them instead reworded a correct
+clause until the regex accepted it, one stripping the very filename that discriminates the skill
+from its neighbour (**#110**).
+
+`unparsed` is narrow and certain on purpose. It fires only on the arrow form, which *always* names a
+target, so zero targets means the name is written in a shape the extractor cannot see — in practice
+a bare single-word target, per the known gap above, and the message says to write it `` `name` `` or
+`/name`. A **prose** clause yielding no target is not reported at all: "Do not use for anything else"
+is a complete and legitimate boundary clause that names nowhere to go.
+
+**One arrow, one target.** An arrow clause naming two or more targets draws its own SUGGESTION,
+quoting both names and asking for a split, because only the first is ever resolved: the conjunction
+continuation (`CONT_MARKED` / `CONT_ANY`) is wired to the prose route verbs and never to arrows. So
+`Not X -> a or b` resolved `a`, left `b` resolved by nothing and reported by nothing, and then let
+the audit print "1 of 1 boundary target(s) resolve" on a clause naming two — a gate under-reporting
+its own coverage, which is the one failure mode ADR-0020 says a gate must not have (**#107**). The
+clause is **rejected rather than the arrow scan extended**: extending it would widen the resolver's
+deliberately conservative false-positive tuning across every arrow in the corpus, where splitting
+costs the author one full stop. The convention is one arrow per target — `Not X -> a. Not Y -> b.` —
+already what every retrofitted `gitea-*` skill does in practice, now stated in
+`skill-author`'s `references/contract.md` instead of being folklore.
+
+**Dotted filenames in a boundary clause now parse.** `CLAUSE_BODY` — what may sit between `Not` and
+the arrow — used to be `[^.;]`, a class that cannot cross a `.`, so every clause naming a dotted
+filename between the two (`AGENTS.md`, `.vale.ini`, `.pre-commit-config.yaml`) was invisible to both
+`BOUNDARY_ARROW` and `ARROW_BOUNDARY`. The two resulting failures were different sizes (**#110**):
+
+- with a **backticked** target the clause was *misdiagnosed*. The backtick sweep still extracted the
+  target, so the route was checked, but the gate reported "no boundary clause" on a clause that was
+  present and working. That is the misdiagnosis the three rewordings above came from.
+- with a **bare** target the clause was *unchecked*. `ARROW_BOUNDARY` is the only extractor for a
+  bare arrow target, so `Not AGENTS.md -> no-such-skill` produced no target, no dangling report and
+  no missing-clause SUGGESTION. Silence, not noise — the worse of the two.
+
+`CLAUSE_BODY` is now `(?:[^.;]|\.(?=\S))`: a dot inside a filename is followed by a non-space, a
+sentence-ending dot by whitespace or end of string, so the class crosses `AGENTS.md` and still stops
+at a real sentence end. **Read the second bullet forward as well as back:** a bare target sitting
+after a dotted filename is now extracted, resolved, and a blocking ERROR when it dangles, where the
+same clause used to pass unchecked in silence.
 
 ### SUGGESTION-only checks
 
-Three more, deterministic to measure but judgment to act on:
+Deterministic to measure, judgment to act on:
 
-- a description with **no boundary clause at all**;
+- a description with **no boundary clause at all** (`absent`);
+- an **arrow clause whose target could not be read** (`unparsed`);
+- an **arrow clause naming more than one target**;
 - a `## Gotchas` section with **more than five entries**;
 - a `## Gotchas` section over **25% of the body**.
 
+### Hand-invoked skills are exempt from the routing rules, and only those
+
+A skill or agent whose frontmatter carries `disable-model-invocation: true` skips three checks:
+
+- the boundary-clause check, `absent` and `unparsed` alike;
+- the multi-target arrow check;
+- the 250-character description **target** (`hand_invoked()` in `scripts/skill-size-check.sh`).
+
+It keeps the 400-character description FAIL and **both** body word tiers, and if its description
+does happen to name a target, that target is still resolved and can still dangle.
+
+Why the exemption is right: `disable-model-invocation: true` removes the skill from the
+model-visible listing entirely — it is not preloaded, and the Skill tool refuses to call it — so its
+description is never matched against user intent. ADR-0020 and `skill-author`'s contract therefore
+give such a skill **one plain human-facing sentence**: no trigger list, no boundary clause. No
+validator knew the field existed (**#108**), so the boundary-clause SUGGESTION fired on exactly the
+shape the contract mandates, and its remedy — "so the router knows where NOT to send this skill" —
+was addressed to a router that cannot see the skill at all. An author who followed the advice made
+the file worse. There is no router to inform.
+
+The half that does **not** lift is the point. The body is still loaded on invocation and still
+competes with the caller's live conversation, so neither body tier moves. The 400-character ceiling
+stands too: a hand-invoked description is not preloaded, but it is still the one line the user reads
+when choosing from the `/` menu, and that ceiling is an outlier stop rather than a routing-quality
+budget — which is precisely why the 250-character target is the tier that lifts.
+
+The field is read as a **boolean**, not as a mention of the key. PyYAML already resolves the
+unquoted YAML 1.1 booleans, so the extra handling catches a quoted `"true"`, which a host reads as
+truthy; `disable-model-invocation: false` is the model-invoked case written out longhand and buys
+nothing. A frontmatter parse failure returns false rather than raising — the flag is a *modifier* on
+other checks, and `description_value()` on the same text already reports the broken frontmatter, so
+raising here would diagnose one file twice two different ways.
+
+`caveman` and `zoom-out` are the two carriers here. `tests/test-skill-size-check.sh` pins both
+halves — what the carve-out lifts, each with a flag-removed control, and what it must not.
+
 ### `verbose: true` is load-bearing
 
 The hook is declared `verbose: true` so the SUGGESTION tier is audible. pre-commit prints nothing at
@@ -281,8 +441,10 @@ script.** `scripts/skill-size-check.sh` applies its body gate to whatever path i
 bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md
 ```
 
-exits 1 today with 900-word body FAILs on `git-orchestrate` (933), `gitea-orchestrate` (1,199) and
+exits 1 today with 900-word body FAILs on `git-orchestrate` and `gitea-orchestrate`. (Counts are
-`apm-orchestrate` (1,080). Agent files escape only because the hook definitions filter on `SKILL.md`
+deliberately not pinned here — agent bodies are edited like any other file, and a figure in this
+paragraph goes stale the moment one is trimmed. Run the command.) Agent files escape only because
+the hook definitions filter on `SKILL.md`
 — a file-pattern accident that happens to implement the design, not the design itself. **Do not
 "extend" that hook's `files:` pattern to cover agents** on the assumption that the script already
 knows the difference; doing so silently enforces a gate ADR-0020 declines to set.
@@ -292,20 +454,39 @@ knows the difference; doing so silently enforces a gate ADR-0020 declines to set
 **The ADR-0020 gates ship hot, with no baseline file.** A shrinking baseline recording each
 non-compliant skill's current numbers was considered and rejected in favour of hot gates.
 
-Two independent hot gates are currently red, and the first will not warn you about the second.
+**The corpus is now clean on both gates.** Issue **#99** retrofitted all 39 skills plugin by plugin;
+`kyberforge` was the last wave, after which the corpus was swept as a whole rather than per plugin.
+Each sweep is followed by an **independent review round**: a fresh agent with no memory of the
+retrofit re-measures the corpus and files what it finds, and the round repeats until one lands no
+findings. The rounds are recorded as comments on **#99** — read the current state off that thread,
+which is why no round count is pinned here.
 
 | Gate | Current findings |
 |---|---|
-| `skill-size-check` | **26 of 39** descriptions and **9 of 39** bodies exceed their FAIL tier; 2 dangling targets; 58 SUGGESTIONs |
+| `skill-size-check` | **0 of 39** descriptions and **0 of 39** bodies exceed their FAIL tier; 0 dangling targets; SUGGESTIONs outstanding (count not pinned — see below) |
-| `Kyberforge.CompositionNote` (Vale) | **10 errors across four skills**: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-workflow` |
+| `Kyberforge.CompositionNote` (Vale) | **0 errors** — the four `gitea-*` carriers were all retrofitted |
+
+**The SUGGESTION count is deliberately not recorded here.** It moves with every skill edit *and*
+with every change to the gate's own tiering, so any figure written down is stale by the next commit.
+Measure it instead:
+
+```
+bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep -c '^SUGGESTION'
+pre-commit run skill-size-check --all-files    # same findings, via the hook
+```
+
+A non-zero count is the expected steady state, not a regression. SUGGESTIONs exit 0 and block
+nothing; only the two FAIL tiers, the dangling-target ERROR and the missing-`references/` ERROR do.
+Read the count as a work queue, and the FAIL columns above as the gate.
 
 `Kyberforge.CompositionNote` is the ADR-0020 Vale rule banning composition and architecture prose
-from a description. Every Vale rule here is `level: error` with no ignorable tier, so touching any of
+from a description. Every Vale rule here is `level: error` with no ignorable tier, so a description
-those four skills means fixing its prose findings as well as its size findings.
+that reintroduces one blocks the commit even though no skill carries one today.
 
-Consequence: editing a non-compliant skill *for any reason* means retrofitting it to the contract
+Because nothing is grandfathered, the gates now bite on **first commit**: a new skill, or an edit
-first — a one-line fix to `gitea-prs` cannot be committed until that skill complies. This is
+that pushes a description past 400 characters or a body past 900 words, is blocked until it
-deliberate; it guarantees convergence and avoids a half-state. Tracked as Gitea issue **#99**.
+complies. That is the steady state the retrofit was for — it is no longer true that an unrelated
+one-line fix to a skill requires retrofitting that skill first.
 
 Check where a skill stands before starting, and check **both** gates:
 
@@ -434,6 +615,35 @@ passing one explicit file per invocation. The two manifests scope **differently
 Narrowing a `.vale.ini` glob to a `plugins/`-shaped path to "tighten" it breaks the consumer case,
 and `check-vale-style-sync`'s probe set is built to catch exactly that.
 
+### The blind spot: `references/` is unlinted, for two independent reasons
+
+Every `references/*.md` file in the corpus is outside the prose gate. Count them with
+`git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/references/.*\.md$'` rather than reading
+a figure here; it moves with every retrofit. This is the gap that matters most, because the context
+contract's own remedy for an over-long body is to move prose **into** `references/` — the gate pushes
+text across its own boundary and then stops watching it.
+
+**Closing either cause alone changes nothing.** There are two, and they are independent:
+
+| Cause | Where | Effect on a `references/` file |
+|---|---|---|
+| the `Kyberforge` style is scoped `[**/SKILL.md]` | `skill-audit/assets/vale/.vale.ini` | matches no section, so Vale lints 0 files and exits 0 |
+| the hook's `files:` regex is `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` | `vale-audit-prefilter-skill` in `.pre-commit-config.yaml` | the file is never handed to Vale at all |
+
+Verified both ways. Handing skill-audit's `vale-wrap.sh` a reference file directly — bypassing
+pre-commit entirely, so only the style scope is in play — prints `0 errors … in 0 files` and exits 0,
+where the same wrapper on a `SKILL.md` reports `in 1 file`. And the hook's `files:` regex, applied to
+`git ls-files`, selects only the skill-directory `SKILL.md` files scoped at the top of this page, so
+pre-commit never hands Vale a reference file to begin with. Widening the glob to `[**/*.md]` would
+still lint nothing through the hook; widening the hook's `files:` alone would hand Vale files its own
+config declines to match, which is the [0-file NOT RUN](#a-0-file-vale-run-is-not-run) shape — a
+green run that measured nothing. **Issue #117** records the style-scope half; the hook half has to
+land in the same change or the fix is cosmetic.
+
+The consumer manifest is a third axis and does not rescue this either: `.pre-commit-hooks.yaml`'s
+`(^|/)SKILL\.md$` is layout-agnostic but still filename-shaped, so an external repo running
+`kyberforge-vale-audit-skill` has the same gap.
+
 ### `vale-wrap.sh`, never bare `vale`
 
 Both audit skills' Step 1 and both pre-commit hooks call **each copy's own**

plugins/bin/.apm/skills/caveman/README.md

@@ -0,0 +1,29 @@
+# caveman
+
+Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact.
+
+## What it does
+
+Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns.
+
+It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`.
+
+That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs.
+
+## Usage
+
+```text
+/caveman
+```
+
+Then keep working normally. To leave the mode, say "stop caveman" or "normal mode".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception |

plugins/bin/.apm/skills/caveman/SKILL.md

@@ -1,17 +1,16 @@
 ---
 name: caveman
+disable-model-invocation: true
 description: >
-  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  Ultra-compressed output mode that drops articles, filler and pleasantries while
-  filler, articles, and pleasantries while keeping full technical accuracy.
+  keeping technical substance exact, cutting token usage by roughly 75%.
-  Use when user says "caveman mode", "talk like caveman", "use caveman",
-  "less tokens", "be brief", or invokes /caveman.
 ---
 
 Respond terse like smart caveman. All technical substance stay. Only fluff die.
 
 ## Persistence
 
-ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+ACTIVE EVERY RESPONSE once user type `/caveman`. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
 
 ## Rules
 

plugins/bin/.apm/skills/diagnose/README.md

@@ -0,0 +1,35 @@
+# diagnose
+
+A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up.
+
+## What it does
+
+Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind.
+
+The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural.
+
+Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs.
+
+## Conditional reading
+
+Neither reference file is read on every run; `SKILL.md` names the condition for each.
+
+- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent.
+- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all.
+
+## Usage
+
+```text
+/diagnose
+```
+
+Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The six phases and their gates — what must be true before each one ends |
+| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction |
+| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists |
+| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse |

plugins/bin/.apm/skills/diagnose/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: diagnose
-description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+description: >
+  Use when the user says "diagnose this" or "debug this", reports something
+  broken, throwing, or failing, or says something got slow. Not filing or
+  triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
 ---
 
 # Diagnose
@@ -15,40 +18,11 @@ When exploring the codebase, use the project's domain glossary to get a clear me
 
 Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
 
-### Ways to construct one — try them in roughly this order
+**If you do not yet have such a signal, read `references/feedback-loops.md`** — ten ways to build one ordered by cost, and what to ask the user for when the bug resists reproduction entirely.
 
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+**If you do have one, it is probably not sharp enough yet.** Make it faster and more deterministic, and make it assert on the exact symptom rather than "didn't crash" — a 30-second flaky loop is barely better than no loop. If it stays slow or intermittent after that, read that file's "Iterate on the loop itself" and "Intermittent bugs" sections.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
 
-Build the right feedback loop, and the bug is 90% fixed.
+Do not proceed to Phase 2 until you have a loop you believe in. If you cannot build one, stop and say so explicitly, listing what you tried — never hypothesise without a signal.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-Do not proceed to Phase 2 until you have a loop you believe in.
 
 ## Phase 2 — Reproduce
 
@@ -57,7 +31,7 @@ Run the loop. Watch the bug appear.
 Confirm:
 
 - [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] The failure is reproducible across multiple runs. If it is intermittent, `references/feedback-loops.md` defines the rate high enough to debug against — go back to Phase 1 and raise it.
 - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
 
 Do not proceed until you reproduce the bug.
@@ -90,19 +64,17 @@ Tool preference:
 
 ## Phase 5 — Fix + regression test
 
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+Write the regression test **before the fix** — but only at a **correct seam**: one where the test exercises the real bug pattern as it occurs at the call site. If the available seam looks too shallow, or you cannot tell whether it is, read `references/regression-seams.md`.
 
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+**If no correct seam exists, that itself is the finding.** Note it and carry it into Phase 6 — the architecture is preventing the bug from being locked down.
 
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+At a correct seam:
 
-If a correct seam exists:
+1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
-
-1. Turn the minimised repro into a failing test at that seam.
 2. Watch it fail.
 3. Apply the fix.
 4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+5. Re-run the Phase 1 feedback loop against the original, un-narrowed scenario.
 
 ## Phase 6 — Cleanup + post-mortem
 

plugins/bin/.apm/skills/diagnose/references/feedback-loops.md

@@ -0,0 +1,40 @@
+# Constructing and sharpening a feedback loop
+
+A feedback loop is a fast, deterministic, agent-runnable pass/fail signal for the bug. Build the right one and the bug is 90% fixed. This file covers the whole arc: building a loop, sharpening one you already have, and escalating when the bug resists reproduction.
+
+## Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `assets/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+## Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+## Intermittent bugs — raise the reproduction rate
+
+If the loop only sometimes fails, the goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+## When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for:
+
+- access to whatever environment reproduces it,
+- a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or
+- permission to add temporary production instrumentation.
+
+Do **not** proceed to hypothesise without a loop. A hypothesis you cannot falsify against a signal is a guess, and the fix that follows it is unverifiable.

plugins/bin/.apm/skills/diagnose/references/regression-seams.md

@@ -0,0 +1,24 @@
+# Judging a regression-test seam
+
+Read this when Phase 5 leaves you unsure whether the seam available for the regression test is the correct one — either because the obvious seam looks shallow, or because there appears to be no seam at all.
+
+## What makes a seam correct
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site: the same entry point, the same participants, the same ordering, and the same state the real caller holds when it goes wrong.
+
+## Seams that are too shallow
+
+- A single-caller test when the bug only appears with multiple callers.
+- A unit test that cannot replicate the chain of calls that triggered the bug.
+- A test that reproduces the symptom by construction — asserting on a value the test itself set — rather than by driving the code path that produces it.
+- A test that mocks out the collaborator the bug actually lives in.
+
+A regression test at a shallow seam gives false confidence. It passes forever, including after a change reintroduces the bug at the real call site, and it will be read by the next maintainer as proof the bug is locked down.
+
+## When there is no correct seam
+
+Do not force one, and do not settle for a shallow seam to have something green. Instead:
+
+1. Apply the fix and verify it against the Phase 1 loop directly.
+2. Write down which seams you considered and why each was too shallow.
+3. Carry that into Phase 6's "what would have prevented this bug" question. A missing seam is an architecture finding — tangled callers, hidden coupling, or a module with no testable boundary — and the handoff is the `improve-codebase-architecture` skill, with those specifics attached.

plugins/bin/.apm/skills/grill-me/README.md

@@ -0,0 +1,27 @@
+# grill-me
+
+Interview the user relentlessly about a plan or design until the decision tree is fully resolved.
+
+## What it does
+
+Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it.
+
+## Composition
+
+This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet.
+
+`triage` composes the documented variant, not this one, when an issue needs fleshing out.
+
+## Usage
+
+```text
+/grill-me
+```
+
+Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule |

plugins/bin/.apm/skills/grill-me/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: grill-me
-description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+description: >
+  Use when the user says "grill me" or wants a plan or design stress-tested by
+  relentless interview — one question at a time, down each branch of the
+  decision tree. Not a plan to challenge against `CONTEXT.md` and ADRs ->
+  `grill-with-docs`.
 ---
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

plugins/bin/.apm/skills/grill-with-docs/README.md

@@ -0,0 +1,37 @@
+# grill-with-docs
+
+The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land.
+
+## What it does
+
+Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways:
+
+- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed.
+- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
+- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins.
+- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does.
+- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
+
+Files are created lazily — only when there is something real to write.
+
+ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
+
+## Composition
+
+`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it.
+
+## Usage
+
+```text
+/grill-with-docs
+```
+
+Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test |
+| `CONTEXT-FORMAT.md` | Skill-root document, cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
+| `ADR-FORMAT.md` | Skill-root document, cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template |

plugins/bin/.apm/skills/grill-with-docs/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+description: >
+  Use when a plan should be stress-tested against the project's domain model —
+  the interview challenges terms against `CONTEXT.md` and writes decisions into
+  it and into ADRs as they land. Not a plain interview -> `grill-me`.
 ---
 
 <what-to-do>

plugins/bin/.apm/skills/improve-codebase-architecture/README.md

@@ -0,0 +1,36 @@
+# improve-codebase-architecture
+
+Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.
+
+## What it does
+
+Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages:
+
+1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep.
+2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one.
+3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise.
+
+The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `LANGUAGE.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler".
+
+ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such.
+
+## Composition
+
+`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly.
+
+## Usage
+
+```text
+/improve-codebase-architecture
+```
+
+Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Condensed glossary, key principles, and the three-stage process |
+| `LANGUAGE.md` | Skill-root document, cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
+| `INTERFACE-DESIGN.md` | Skill-root document, read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints |
+| `DEEPENING.md` | Skill-root document, cited from `INTERFACE-DESIGN.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy |

plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: improve-codebase-architecture
-description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+description: >
+  Use when the user wants to improve architecture, find refactoring
+  opportunities, consolidate tightly-coupled modules, or make a codebase more
+  testable and AI-navigable — deepening opportunities that turn shallow modules
+  into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a
+  failure -> `diagnose`.
 ---
 
 # Improve Codebase Architecture
@@ -9,7 +14,7 @@ Surface architectural friction and propose **deepening opportunities** — refac
 
 ## Glossary
 
-Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary."
 
 - **Module** — anything with an interface and an implementation (function, class, package, slice).
 - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
@@ -20,12 +25,14 @@ Use these terms exactly in every suggestion. Consistent language is the point
 - **Leverage** — what callers get from depth.
 - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
 
-Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+Key principles:
 
 - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.**
 - **One adapter = hypothetical seam. Two adapters = real seam.**
 
+If a term or principle above is ambiguous in the case in front of you, or you need the definitions and the principles the two lists leave out, read `LANGUAGE.md`.
+
 This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
 
 ## Process
@@ -53,7 +60,7 @@ Present a numbered list of deepening opportunities. For each candidate:
 - **Solution** — plain English description of what would change
 - **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
 
-**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+**Use CONTEXT.md vocabulary for the domain, and the architecture glossary above for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
 **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
 
@@ -65,7 +72,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
 
 Side effects happen inline as decisions crystallize:
 
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `ADR-FORMAT.md`.
-- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+- **Want to explore alternative interfaces for the deepened module?** Read `INTERFACE-DESIGN.md`.

plugins/bin/.apm/skills/prototype/README.md

@@ -0,0 +1,32 @@
+# prototype
+
+Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations.
+
+## What it does
+
+Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else:
+
+- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper.
+- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param.
+
+The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing.
+
+Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted.
+
+## Usage
+
+```text
+/prototype
+```
+
+State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The branch dispatch table and the rules that apply to both branches |
+| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app |
+| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations |
+
+Each reference is self-contained — a run reads one of the two, never both.

plugins/bin/.apm/skills/prototype/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: prototype
-description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+description: >
+  Use when the user wants a throwaway prototype to answer a design question about
+  a data model, state machine or business logic, or to mock up a UI in several
+  variations. Not production code -> `tdd`. Not talking a design through ->
+  `grill-me`.
 ---
 
 # Prototype
@@ -9,10 +13,12 @@ A prototype is **throwaway code that answers a question**. The question decides
 
 ## Pick a branch
 
-Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+| Question being answered | Build | Reference |
+|---|---|---|
+| "Does this logic / state model feel right?" | A tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper | `references/logic.md` |
+| "What should this look like?" | Several radically different UI variations on one route, switchable via a URL search param and a floating bottom bar | `references/ui.md` |
 
-- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+Resolve the row from the user's prompt, the surrounding code, or by asking if the user is around, then read only that reference — each is self-contained.
-- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
 
 The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
 

plugins/bin/.apm/skills/prototype/references/logic.md

@@ -9,7 +9,7 @@ A tiny interactive terminal app that lets the user drive a state model by hand.
 - "I want to feel out what the API should look like before writing it."
 - Anything where the user wants to **press buttons and watch state change**.
 
-If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+If the question is "what should this look like" — wrong branch. Read `references/ui.md`.
 
 ## Process
 

plugins/bin/.apm/skills/prototype/references/ui.md

@@ -2,7 +2,7 @@
 
 Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
 
-If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+If the question is about logic/state rather than what something looks like — wrong branch. Read `references/logic.md`.
 
 ## When this is the right shape
 

plugins/bin/.apm/skills/research/META.md

@@ -1,15 +0,0 @@
-```yaml
-version: "1.1"
-updated: 2026-06-21
-
-when: >-
-  Invoked when the user wants to gather structured reference documentation for a
-  tool, library, or API from MCP documentation indexes or web sources. Typically
-  run before writing a new skill that wraps an external tool, or any time
-  reference files are needed for a topic. Triggered explicitly
-  ("/research <topic> <path>") or implicitly when the user asks to look up,
-  gather, or pull docs for a topic before implementing something.
-
-references:
-  - .agents/skills/context7-mcp/SKILL.md  # context7-mcp — MCP source channel integrated at step 2
-```

plugins/bin/.apm/skills/research/README.md

@@ -0,0 +1,31 @@
+# research
+
+Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
+
+## What it does
+
+Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record.
+
+Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched.
+
+The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
+
+## Composition
+
+Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred.
+
+## Usage
+
+```text
+/research
+```
+
+Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The four gotchas and the six research steps |
+| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule |
+| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body |

plugins/bin/.apm/skills/research/SKILL.md

@@ -1,97 +1,78 @@
 ---
 name: research
 description: >-
-  Use when the user wants to research a topic and generate structured reference
+  Use when the user wants a tool, library, or API researched from canonical
-  markdown files. Handles: finding canonical docs for a tool/library/API via
+  documentation into structured per-topic reference markdown files. Not
-  Context7 MCP or web sources, reading and deepening into linked pages,
+  documentation written from existing code or specs -> `write-docs`. Not a bug
-  organizing extracted content into topic files (overview, installation,
+  or incident -> `diagnose`.
-  configuration, cli-reference, api-reference, examples, troubleshooting). Do
-  NOT use when the user wants to write documentation from existing code or specs
-  (use write-docs), install or manage the neuledge-context MCP server (use
-  neuledge-context), or research a bug/incident (use diagnose).
 metadata:
   category: research
 allowed-tools:
-  - WebSearch
+  - Grep
-  - WebFetch
+  - Glob
   - Read
   - Write
+  - WebSearch
+  - WebFetch
   - mcp__context7__resolve-library-id
   - mcp__context7__query-docs
 model: sonnet
 ---
 
-<requirements>
+## Gotchas
 
-## Required inputs
+- Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask.
+- Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for.
+- Never write an empty topic file. A stub `troubleshooting.md` reads downstream as researched and closed.
+- A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph.
 
-- **Topic** — the subject to research (tool, library, API, concept); inferred from user description if clear, ask if ambiguous
+## Step 1 — Scope against the working directory
-- **Output path** — directory where reference files will be written; must be provided explicitly — do not infer or default
-- **Starting URLs** — optional; if provided, skip discovery websearch and read these first
 
-## Constraints
+Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented.
 
-- Never write files outside the explicitly provided output path
+The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`,
-- Skip any default topic file if no relevant content is found for it — do not create empty files
+`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists.
-- Create additional topic files beyond the default list when content warrants it (e.g. `webhooks.md`, `rate-limits.md`)
+If what belongs in one of them is unclear, or the topic needs a file outside that set, read
-- Subagents handle parallel source reading and link deepening — the orchestrator writes all files; subagents return summaries only, never write directly
+`references/topics.md` for the per-topic coverage table and the custom-topic naming rule.
-- Context7 MCP calls (`resolve-library-id`, `query-docs`) are made only by the orchestrator at step 2 — subagents must not call them
-- `sources.md` is always written, even if only one source was read
-- Each topic file must have frontmatter with `topic` and `source_keys`; body is prose only — no inline URLs
-- Source keys in `sources.md` must be kebab-case slugs: derived from the source domain or page title for web sources; for Context7 sources use `context7-<library-slug>` (e.g. `context7-vercel-next-js`)
-- Default topic list and file format spec live in `references/` sub-files — read them at step 1
 
-</requirements>
+## Step 2 — Resolve against Context7
 
-<steps>
+If the topic is a library, framework, or API and the user gave no starting URLs, call `resolve-library-id` with the topic name and the user's full question — match quality depends on the question, not the bare name — then `query-docs` once per default topic area. Record each response as a source with slug `context7-<library-slug>`, and mark which topic areas it covered — those skip the web reads at step 4.
 
-## Process
+If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt.
 
-1. **Scan codebase.** Search the working directory for existing usage of the topic — imports, config files, version pins, existing reference files. Use findings to narrow research scope (e.g. target the version already in use, skip topics already documented). Read `references/topics.md` for the default topic list and `references/file-format.md` for the output file format spec.
+## Step 3 — Discover sources
 
-2. **Try Context7.** If the topic is a library, framework, or API and no starting URLs were provided, call `resolve-library-id` with the topic name and the user's question. If a match resolves, call `query-docs` once per default topic area (see `references/topics.md`). Treat each response as a source summary with slug `context7-<library-slug>` (e.g. `context7-vercel-next-js`). A topic area has sufficient content when the Context7 response contains at least one substantive paragraph — not a "no results" message, redirect notice, or header-only boilerplate. Mark covered topic areas — skip their subagent web reads in step 4. If the library does not resolve, or starting URLs were provided (explicit source choice by the user), skip this step entirely.
+If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4.
 
-3. **Discover sources.** For topics not covered by Context7 (or when no starting URLs were provided and Context7 did not resolve), websearch for canonical documentation (prefer `llms.txt`, developer docs, official API references over tutorials or blog posts). Collect 3–5 candidate URLs before reading any.
+Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — `llms.txt`, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them.
 
-4. **Read sources in parallel.** Spawn one subagent per source URL. Each subagent fetches the page, extracts relevant content, identifies links worth deepening, and returns a structured summary (content by topic area + links to follow). Subagents do not write files.
+If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials.
 
-5. **Deepen.** For each subagent that returned links worth following, spawn child subagents per branch. Continue until content becomes repetitive or out of scope. Cap at ~10 additional pages total across all branches.
+## Step 4 — Read the sources
 
-6. **Consolidate.** Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.
+`WebFetch` each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one.
 
-7. **Write topic files.** For each topic with content, write `<output-path>/<topic>.md` using the format in `references/file-format.md`. Orchestrator writes all files — never delegate file writing to a subagent.
+## Step 5 — Deepen
 
-8. **Write `sources.md`.** Write `<output-path>/sources.md` mapping each source slug to its URL (use `context7:<library-id>` as the URL for Context7 sources), description, and list of topic files it contributed to. Include sources that yielded no content, marked `no content extracted`.
+`WebFetch` the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality.
 
-## Output format
+## Step 6 — Write
 
-- `<output-path>/<topic>.md` per topic with content — formatted per `references/file-format.md`
+Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path:
-- `<output-path>/sources.md` — always produced; maps slug → URL, description, contributing files
 
-</steps>
+- `<topic>.md` for each topic area that has content, default or custom. Frontmatter carries `topic:` (the filename without `.md`) and `source_keys:` (kebab-case slugs matching `sources.md`); the body is prose in `##` sections, with no inline URLs.
+- `sources.md`, always, one `##` section per source — including sources that yielded nothing — with exactly these four fields:
 
-<checks>
+  ```markdown
+  - **URL:** <full URL>
+  - **Description:** <one-line summary>
+  - **Contributing files:** <topic files this source contributed to>
+  - **Status:** `extracted` | `no content extracted`
+  ```
 
-## Failure handling
+Spell those four field names exactly as given. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing.
 
-- Output path not provided — stop and ask; do not infer or default
+Read `references/file-format.md` when the four fields above do not settle the case: what a slug should be, the `context7-<library-slug>` slug and `context7:<library-id>` URL convention for a Context7 source, or what belongs in a topic body versus a verbatim copy of the source.
-- No sources found after websearch — report what was searched, ask user to provide starting URLs
-- Subagent returns no usable content — skip that source, log in `sources.md` as `no content extracted`
-- All topic files would be empty — stop, report what was searched, do not write any files
 
-## Self-check
+If no topic area has content, write nothing at all, `sources.md` included, and report what was searched.
-
-- [ ] Codebase scanned before any websearch was performed
-- [ ] Output path was explicitly provided — not inferred
-- [ ] `references/topics.md` and `references/file-format.md` read at step 1
-- [ ] Context7 resolution attempted before websearch when topic is a library/framework/API
-- [ ] Context7 calls made only at orchestrator step 2 — no subagent called `resolve-library-id` or `query-docs`
-- [ ] Context7 sources recorded in `sources.md` with `context7:<library-id>` as URL
-- [ ] No topic file written without content
-- [ ] `sources.md` written with all sources read (including those with no content extracted)
-- [ ] All file writes performed by the orchestrator, not subagents
-- [ ] Each topic file has `topic` and `source_keys` frontmatter fields
-- [ ] All source keys in topic files have a matching entry in `sources.md`
-- [ ] No files written outside the provided output path
-
-</checks>

plugins/bin/.apm/skills/tdd/README.md

@@ -0,0 +1,32 @@
+# tdd
+
+Test-driven development as a strict red-green-refactor loop, one behaviour at a time.
+
+## What it does
+
+Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed.
+
+The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you.
+
+The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden.
+
+Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected.
+
+## Usage
+
+```text
+/tdd
+```
+
+Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist |
+| `tests.md` | Skill-root document, cited from Philosophy: worked good and bad test examples |
+| `mocking.md` | Skill-root document, cited from Philosophy: mock at system boundaries only, and what not to mock |
+| `deep-modules.md` | Skill-root document, cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
+| `interface-design.md` | Skill-root document, cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
+| `refactoring.md` | Skill-root document, cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession |

plugins/bin/.apm/skills/tdd/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tdd
-description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+description: >
+  Use when the user wants a feature built or a bug fixed test-first, in a strict
+  red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
+  bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
 ---
 
 # Test-Driven Development
@@ -13,7 +16,7 @@ description: Test-driven development with red-green-refactor loop. Use when user
 
 **Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
 
-See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `tests.md`. If a test needs a collaborator faked, read `mocking.md` before reaching for a mock.
 
 ## Anti-Pattern: Horizontal Slices
 

plugins/bin/.apm/skills/triage/AGENT-BRIEF.md

@@ -1,6 +1,6 @@
 # Writing Agent Briefs
 
-An agent brief is a structured comment posted on a GitHub issue when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
+An agent brief is a structured comment posted on an issue in the issue tracker when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
 
 ## Principles
 
@@ -27,7 +27,7 @@ Describe **what** the system should do, not **how** to implement it. The agent w
 
 The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
 
-- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
+- **Good:** "Querying the issue tracker for the `needs-triage` label returns issues that have been through initial classification"
 - **Bad:** "Triage should work correctly"
 
 ### Explicit scope boundaries

plugins/bin/.apm/skills/triage/README.md

@@ -0,0 +1,35 @@
+# triage
+
+Move issues on the project issue tracker through a small state machine of triage roles.
+
+## What it does
+
+Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.
+
+A run does one of three things depending on what the maintainer asks for:
+
+- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes.
+- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome.
+- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.
+
+Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at.
+
+## Composition
+
+`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging.
+
+## Usage
+
+```text
+/triage
+```
+
+Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session |
+| `AGENT-BRIEF.md` | Skill-root document, cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers |
+| `OUT-OF-SCOPE.md` | Skill-root document, cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests |

plugins/bin/.apm/skills/triage/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: triage
-description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
+description: >
+  Use when the user wants an issue created, triaged, or moved through the
+  tracker's triage states, or an issue prepared for an AFK agent. Not debugging
+  the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
 ---
 
 # Triage
@@ -35,7 +38,7 @@ Five **state** roles:
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+These are canonical role names — the actual label strings used in the issue tracker may differ. Resolve each canonical name against the tracker's live label set before applying it, using whichever tracker skill this install provides. If a name has no counterpart there, report the gap and ask the maintainer for the mapping — never substitute a guess.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 

plugins/bin/.apm/skills/write-docs/README.md

@@ -0,0 +1,30 @@
+# write-docs
+
+Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
+
+## What it does
+
+Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
+
+The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
+
+- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
+- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
+- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
+- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
+
+Summary and overview sections are written last, once the detail sections are stable.
+
+## Usage
+
+```text
+/write-docs
+```
+
+Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |

plugins/bin/.apm/skills/write-docs/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: write-docs
-description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills.
+description: >
+  Use when the user wants technical documentation produced or updated from code
+  or spec, every claim traced to a source — "write docs for X", "document this
+  module", "create docs for this feature", "write a README for this". Not an ADR
+  or other decision record -> `grill-with-docs`. Not an external tool researched
+  from its docs -> `research`.
 version: "1.0"
 updated: 2026-05-17
 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
@@ -35,7 +40,8 @@ You are a technical writer that produces documentation by reading code and spec
 - User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
 
 **Do not use when:**
-- User wants a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me`
+- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs
+- User wants a PRD → no skill in this set produces one; say so rather than redirecting
 - User wants to document a skill file (skill files are self-describing)
 - User wants marketing or blog copy
 - Documentation requires tacit organisational knowledge that cannot be read from code or spec
@@ -88,7 +94,7 @@ You are a technical writer that produces documentation by reading code and spec
 - Stage skipped without a logged reason → flag and require the one-sentence log before continuing
 - Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation
 - Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete
-- Requested output is a PRD, decision doc, or architecture proposal → redirect to `to-prd`, `grill-me`, or `grill-with-docs`
+- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting
 
 ## Self-check
 

plugins/bin/.apm/skills/zoom-out/README.md

@@ -0,0 +1,25 @@
+# zoom-out
+
+Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code.
+
+## What it does
+
+A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it.
+
+## Usage
+
+```text
+/zoom-out
+```
+
+Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — a single instruction, no supporting files |

plugins/bin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bin",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
   "author": {
     "name": "Defame1297",

plugins/bin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bin",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
   "author": {
     "name": "Defame1297",

plugins/bin/apm.yml

@@ -1,5 +1,5 @@
 name: bin
-version: 1.1.5
+version: 1.1.6
 description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
 author:
   name: Defame1297

plugins/bin/evals/research/research/eval.yaml

@@ -26,11 +26,6 @@ trigger_tests:
     query: "Research why these integration tests are failing"
     should_trigger: false
 
-  - id: negative-neuledge
-    name: "Negative — MCP server setup goes to neuledge-context"
-    query: "Install the neuledge context server and set it up"
-    should_trigger: false
-
   - id: negative-context7-direct-question
     name: "Negative — direct doc question goes to context7-mcp, not research"
     query: "What are the Next.js middleware options?"

plugins/bin/skills/caveman/README.md

@@ -0,0 +1,29 @@
+# caveman
+
+Ultra-compressed output mode: drop articles, filler and pleasantries, keep the technical substance exact.
+
+## What it does
+
+Switches the agent into a terse register — no articles, no hedging, no pleasantries, fragments allowed, arrows for causality — while leaving technical terms, code blocks and quoted error strings untouched. The mode is *sticky*: once turned on it stays on for every subsequent response until the user says "stop caveman" or "normal mode", rather than decaying back to normal prose after a few turns.
+
+It carries one built-in escape hatch. Security warnings, confirmations for irreversible actions, multi-step sequences where fragment order could be misread, and any request to clarify are answered in normal prose, then the compressed register resumes.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`. This is the single most important thing to know about this skill: **the model cannot route to it.** No other skill can hand off to it, and no phrasing in a user's request will cause it to be selected automatically. The only way in is the human typing `/caveman`.
+
+That is deliberate — output style is the user's choice, not an inference the router should make on their behalf. It is also why the description reads as one plain human-facing sentence rather than carrying the trigger phrasing and boundary clause a routable skill needs.
+
+## Usage
+
+```text
+/caveman
+```
+
+Then keep working normally. To leave the mode, say "stop caveman" or "normal mode".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — persistence rule, compression rules, worked examples, and the auto-clarity exception |

plugins/bin/skills/caveman/SKILL.md

@@ -1,17 +1,16 @@
 ---
 name: caveman
+disable-model-invocation: true
 description: >
-  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  Ultra-compressed output mode that drops articles, filler and pleasantries while
-  filler, articles, and pleasantries while keeping full technical accuracy.
+  keeping technical substance exact, cutting token usage by roughly 75%.
-  Use when user says "caveman mode", "talk like caveman", "use caveman",
-  "less tokens", "be brief", or invokes /caveman.
 ---
 
 Respond terse like smart caveman. All technical substance stay. Only fluff die.
 
 ## Persistence
 
-ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+ACTIVE EVERY RESPONSE once user type `/caveman`. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
 
 ## Rules
 

plugins/bin/skills/diagnose/README.md

@@ -0,0 +1,35 @@
+# diagnose
+
+A six-phase discipline for hard bugs and performance regressions: feedback loop → reproduce → hypothesise → instrument → fix with a regression test → clean up.
+
+## What it does
+
+Imposes an order of operations on debugging so the agent cannot skip to guessing. The load-bearing phase is the first one: build a fast, deterministic, agent-runnable pass/fail signal for the bug. Everything downstream — bisection, hypothesis testing, instrumentation — just consumes that signal, so the skill refuses to advance to Phase 2 without one, and says so explicitly rather than hypothesising blind.
+
+The remaining phases each carry a constraint worth knowing about: hypotheses are generated 3–5 at a time and must be falsifiable, so the first plausible idea cannot anchor the whole investigation; every debug log is tagged with a unique prefix (`[DEBUG-a4f2]`) so cleanup is a single grep; the regression test is written before the fix and only at a seam that exercises the real bug pattern; and the run closes by asking what would have prevented the bug, handing off to `improve-codebase-architecture` when the answer is architectural.
+
+Performance regressions take a branch of their own inside Phase 4 — baseline measurement and bisection, not logs.
+
+## Conditional reading
+
+Neither reference file is read on every run; `SKILL.md` names the condition for each.
+
+- `references/feedback-loops.md` is read when Phase 1 has no signal yet, or when the loop you have is slow or intermittent.
+- `references/regression-seams.md` is read when Phase 5 leaves you unsure whether the available seam is deep enough — or whether one exists at all.
+
+## Usage
+
+```text
+/diagnose
+```
+
+Describe the bug or the regression. For filing and triaging a reported bug rather than diagnosing it, use `triage`; for test-first feature work, use `tdd`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The six phases and their gates — what must be true before each one ends |
+| `references/feedback-loops.md` | Loaded when Phase 1 has no loop or the loop is too weak: ten ways to construct one ordered by cost, how to sharpen an existing loop, handling intermittent bugs, and what to ask the user for when the bug resists reproduction |
+| `references/regression-seams.md` | Loaded when Phase 5 is unsure about the seam: what makes a seam correct, the four shapes of a too-shallow seam, and what to do when no correct seam exists |
+| `assets/hitl-loop.template.sh` | Copy-and-edit bash template for the last-resort human-in-the-loop feedback loop, cited by `references/feedback-loops.md`. Provides `step` and `capture` helpers and prints captured values as `KEY=VALUE` for the agent to parse |

plugins/bin/skills/diagnose/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: diagnose
-description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+description: >
+  Use when the user says "diagnose this" or "debug this", reports something
+  broken, throwing, or failing, or says something got slow. Not filing or
+  triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
 ---
 
 # Diagnose
@@ -15,40 +18,11 @@ When exploring the codebase, use the project's domain glossary to get a clear me
 
 Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
 
-### Ways to construct one — try them in roughly this order
+**If you do not yet have such a signal, read `references/feedback-loops.md`** — ten ways to build one ordered by cost, and what to ask the user for when the bug resists reproduction entirely.
 
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+**If you do have one, it is probably not sharp enough yet.** Make it faster and more deterministic, and make it assert on the exact symptom rather than "didn't crash" — a 30-second flaky loop is barely better than no loop. If it stays slow or intermittent after that, read that file's "Iterate on the loop itself" and "Intermittent bugs" sections.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
 
-Build the right feedback loop, and the bug is 90% fixed.
+Do not proceed to Phase 2 until you have a loop you believe in. If you cannot build one, stop and say so explicitly, listing what you tried — never hypothesise without a signal.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-Do not proceed to Phase 2 until you have a loop you believe in.
 
 ## Phase 2 — Reproduce
 
@@ -57,7 +31,7 @@ Run the loop. Watch the bug appear.
 Confirm:
 
 - [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] The failure is reproducible across multiple runs. If it is intermittent, `references/feedback-loops.md` defines the rate high enough to debug against — go back to Phase 1 and raise it.
 - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
 
 Do not proceed until you reproduce the bug.
@@ -90,19 +64,17 @@ Tool preference:
 
 ## Phase 5 — Fix + regression test
 
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+Write the regression test **before the fix** — but only at a **correct seam**: one where the test exercises the real bug pattern as it occurs at the call site. If the available seam looks too shallow, or you cannot tell whether it is, read `references/regression-seams.md`.
 
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+**If no correct seam exists, that itself is the finding.** Note it and carry it into Phase 6 — the architecture is preventing the bug from being locked down.
 
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+At a correct seam:
 
-If a correct seam exists:
+1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
-
-1. Turn the minimised repro into a failing test at that seam.
 2. Watch it fail.
 3. Apply the fix.
 4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+5. Re-run the Phase 1 feedback loop against the original, un-narrowed scenario.
 
 ## Phase 6 — Cleanup + post-mortem
 

plugins/bin/skills/diagnose/references/feedback-loops.md

@@ -0,0 +1,40 @@
+# Constructing and sharpening a feedback loop
+
+A feedback loop is a fast, deterministic, agent-runnable pass/fail signal for the bug. Build the right one and the bug is 90% fixed. This file covers the whole arc: building a loop, sharpening one you already have, and escalating when the bug resists reproduction.
+
+## Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `assets/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+## Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+## Intermittent bugs — raise the reproduction rate
+
+If the loop only sometimes fails, the goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+## When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for:
+
+- access to whatever environment reproduces it,
+- a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or
+- permission to add temporary production instrumentation.
+
+Do **not** proceed to hypothesise without a loop. A hypothesis you cannot falsify against a signal is a guess, and the fix that follows it is unverifiable.

plugins/bin/skills/diagnose/references/regression-seams.md

@@ -0,0 +1,24 @@
+# Judging a regression-test seam
+
+Read this when Phase 5 leaves you unsure whether the seam available for the regression test is the correct one — either because the obvious seam looks shallow, or because there appears to be no seam at all.
+
+## What makes a seam correct
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site: the same entry point, the same participants, the same ordering, and the same state the real caller holds when it goes wrong.
+
+## Seams that are too shallow
+
+- A single-caller test when the bug only appears with multiple callers.
+- A unit test that cannot replicate the chain of calls that triggered the bug.
+- A test that reproduces the symptom by construction — asserting on a value the test itself set — rather than by driving the code path that produces it.
+- A test that mocks out the collaborator the bug actually lives in.
+
+A regression test at a shallow seam gives false confidence. It passes forever, including after a change reintroduces the bug at the real call site, and it will be read by the next maintainer as proof the bug is locked down.
+
+## When there is no correct seam
+
+Do not force one, and do not settle for a shallow seam to have something green. Instead:
+
+1. Apply the fix and verify it against the Phase 1 loop directly.
+2. Write down which seams you considered and why each was too shallow.
+3. Carry that into Phase 6's "what would have prevented this bug" question. A missing seam is an architecture finding — tangled callers, hidden coupling, or a module with no testable boundary — and the handoff is the `improve-codebase-architecture` skill, with those specifics attached.

plugins/bin/skills/grill-me/README.md

@@ -0,0 +1,27 @@
+# grill-me
+
+Interview the user relentlessly about a plan or design until the decision tree is fully resolved.
+
+## What it does
+
+Turns the agent into an interviewer rather than an implementer. It walks the design tree branch by branch, resolving dependencies between decisions one at a time, and offers its own recommended answer alongside each question so the user has something concrete to push against. Two rules give it its shape: **one question at a time**, and **never ask what the codebase can answer** — if a question is settleable by reading the code, the agent goes and reads the code instead of spending the user's attention on it.
+
+## Composition
+
+This is the plain grilling loop, with no documentation side effects. The sibling `grill-with-docs` skill runs the same interview but additionally challenges answers against the project's `CONTEXT.md` glossary and existing ADRs, and writes decisions back into those files as they crystallise. Reach for that one when the project has a domain model worth defending; reach for this one when it does not, or when nothing should be written down yet.
+
+`triage` composes the documented variant, not this one, when an issue needs fleshing out.
+
+## Usage
+
+```text
+/grill-me
+```
+
+Describe the plan or design to be stress-tested. Expect questions one at a time, each with a recommended answer.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — the interview instruction, the one-question-at-a-time rule, and the explore-instead-of-asking rule |

plugins/bin/skills/grill-me/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: grill-me
-description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+description: >
+  Use when the user says "grill me" or wants a plan or design stress-tested by
+  relentless interview — one question at a time, down each branch of the
+  decision tree. Not a plan to challenge against `CONTEXT.md` and ADRs ->
+  `grill-with-docs`.
 ---
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

plugins/bin/skills/grill-with-docs/README.md

@@ -0,0 +1,37 @@
+# grill-with-docs
+
+The grilling interview, run against the project's domain model — and writing decisions back into `CONTEXT.md` and ADRs as they land.
+
+## What it does
+
+Runs the same relentless one-question-at-a-time interview as `grill-me`, with the project's own documentation as an active participant. During codebase exploration it also locates the domain documentation — a root `CONTEXT.md` and `docs/adr/`, or a `CONTEXT-MAP.md` pointing at per-context glossaries and ADR directories in a multi-context repo — and then uses it five ways:
+
+- **Challenges terms against the glossary.** When the user's usage conflicts with what `CONTEXT.md` already defines, that is raised immediately rather than absorbed.
+- **Sharpens fuzzy language** by proposing a precise canonical term ("you're saying 'account' — do you mean the Customer or the User?").
+- **Stress-tests domain relationships with concrete scenarios**, inventing edge cases that force the user to be precise about where one concept ends and the next begins.
+- **Cross-references claims against the code**, and surfaces contradictions between what the user says happens and what the code does.
+- **Updates `CONTEXT.md` inline**, the moment a term is resolved, rather than batching changes to the end of the session where they get lost.
+
+Files are created lazily — only when there is something real to write.
+
+ADRs are offered *sparingly*, and only when all three tests pass: the decision is hard to reverse, it would surprise a future reader without the context, and it was a genuine trade-off with real alternatives. Missing any one of the three means no ADR.
+
+## Composition
+
+`grill-me` is the same interview without the documentation side effects — use it when there is no domain model to defend or nothing should be written down yet. `triage` composes this skill (not `grill-me`) at step 4 when an issue needs fleshing out. `improve-codebase-architecture` runs its own grilling loop and borrows this skill's `CONTEXT.md` and ADR discipline for the decisions that come out of it.
+
+## Usage
+
+```text
+/grill-with-docs
+```
+
+Describe the plan or design. Expect questions one at a time, each with a recommended answer, and expect `CONTEXT.md` to be edited during the session rather than after it.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The interview instruction plus the domain-awareness rules: file layout discovery, the five during-session behaviours, and the three-part ADR test |
+| `CONTEXT-FORMAT.md` | Skill-root document, cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
+| `ADR-FORMAT.md` | Skill-root document, cited when an ADR is offered: `docs/adr/` naming, sequential numbering, and the ADR template |

plugins/bin/skills/grill-with-docs/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+description: >
+  Use when a plan should be stress-tested against the project's domain model —
+  the interview challenges terms against `CONTEXT.md` and writes decisions into
+  it and into ADRs as they land. Not a plain interview -> `grill-me`.
 ---
 
 <what-to-do>

plugins/bin/skills/improve-codebase-architecture/README.md

@@ -0,0 +1,36 @@
+# improve-codebase-architecture
+
+Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones.
+
+## What it does
+
+Looks for places where a codebase is hard to understand, hard to test, or hard for an agent to navigate, and proposes refactors that concentrate behaviour behind smaller interfaces. It runs in three stages:
+
+1. **Explore.** Reads the domain glossary and any ADRs in the area first, then walks the codebase with an `Explore` sub-agent — organically, noting friction rather than applying fixed heuristics. The **deletion test** is the filter: imagine deleting the module; if complexity vanishes it was a pass-through, if complexity reappears across N callers it was earning its keep.
+2. **Present candidates.** A numbered list, each with files, problem, solution and benefits — benefits stated in terms of *locality* and *leverage* and of how tests would improve. No interfaces are proposed yet; the user picks one.
+3. **Grilling loop.** Walks the design tree for the chosen candidate, with documentation side effects landing inline as decisions crystallise.
+
+The skill is opinionated about vocabulary, and that is the point: **module, interface, implementation, depth, seam, adapter, leverage, locality**, used exactly, with no drift into "component", "service", "API" or "boundary". Domain nouns come from `CONTEXT.md`, architecture nouns from `LANGUAGE.md` — so a proposal reads as "the Order intake module", never "the FooBarHandler".
+
+ADRs are treated as decisions not to be re-litigated. A candidate that contradicts one is surfaced only when the friction is real enough to warrant reopening it, and is marked as such.
+
+## Composition
+
+`diagnose` hands off here when a bug's post-mortem concludes that no correct test seam exists, or that callers are tangled — the recommendation is made after the fix is in, not before. The grilling loop follows `grill-with-docs`'s discipline for `CONTEXT.md` entries and ADR offers, and `SKILL.md` names that skill's format documents directly.
+
+## Usage
+
+```text
+/improve-codebase-architecture
+```
+
+Point at a codebase or an area of one. Expect a numbered candidate list and a "which of these would you like to explore?" before any interface design happens.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Condensed glossary, key principles, and the three-stage process |
+| `LANGUAGE.md` | Skill-root document, cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
+| `INTERFACE-DESIGN.md` | Skill-root document, read at stage 3 when the user wants alternative interfaces explored: the parallel sub-agent "Design It Twice" pattern, framing the problem space, and the per-agent design constraints |
+| `DEEPENING.md` | Skill-root document, cited from `INTERFACE-DESIGN.md`: how to deepen a cluster of shallow modules safely, the four dependency categories (in-process, local-substitutable, remote-but-owned, true external), seam discipline, and the replace-don't-layer testing strategy |

plugins/bin/skills/improve-codebase-architecture/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: improve-codebase-architecture
-description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
+description: >
+  Use when the user wants to improve architecture, find refactoring
+  opportunities, consolidate tightly-coupled modules, or make a codebase more
+  testable and AI-navigable — deepening opportunities that turn shallow modules
+  into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a
+  failure -> `diagnose`.
 ---
 
 # Improve Codebase Architecture
@@ -9,7 +14,7 @@ Surface architectural friction and propose **deepening opportunities** — refac
 
 ## Glossary
 
-Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary."
 
 - **Module** — anything with an interface and an implementation (function, class, package, slice).
 - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
@@ -20,12 +25,14 @@ Use these terms exactly in every suggestion. Consistent language is the point
 - **Leverage** — what callers get from depth.
 - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
 
-Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+Key principles:
 
 - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.**
 - **One adapter = hypothetical seam. Two adapters = real seam.**
 
+If a term or principle above is ambiguous in the case in front of you, or you need the definitions and the principles the two lists leave out, read `LANGUAGE.md`.
+
 This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
 
 ## Process
@@ -53,7 +60,7 @@ Present a numbered list of deepening opportunities. For each candidate:
 - **Solution** — plain English description of what would change
 - **Benefits** — explained in terms of locality and leverage, and also in how tests would improve
 
-**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+**Use CONTEXT.md vocabulary for the domain, and the architecture glossary above for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
 **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
 
@@ -65,7 +72,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
 
 Side effects happen inline as decisions crystallize:
 
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `ADR-FORMAT.md`.
-- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+- **Want to explore alternative interfaces for the deepened module?** Read `INTERFACE-DESIGN.md`.

plugins/bin/skills/prototype/README.md

@@ -0,0 +1,32 @@
+# prototype
+
+Build a throwaway prototype that answers one design question — either a runnable terminal app or several UI variations.
+
+## What it does
+
+Treats a prototype as **throwaway code that answers a question**, and lets the question decide the artifact. `SKILL.md` opens with a two-row dispatch table and the run resolves exactly one row before doing anything else:
+
+- *"Does this logic / state model feel right?"* → a tiny interactive terminal app that pushes the state machine through the cases that are hard to reason about on paper.
+- *"What should this look like?"* → several radically different UI variations on one route, switchable from a floating bottom bar via a URL search param.
+
+The two branches produce fundamentally different artifacts, so picking wrong wastes the whole prototype. When the question is genuinely ambiguous and the user is unreachable, the skill defaults on the shape of the surrounding code (backend module → logic, page or component → UI) and states the assumption at the top of the prototype rather than silently choosing.
+
+Six rules apply to both branches: throwaway and visibly named as such, one command to run, no persistence by default, no polish, surface the full state after every action or variant switch, and delete or absorb the prototype when it is done. The *answer* is the only durable output — the skill captures it in a commit message, ADR, issue or `NOTES.md` before the code is deleted.
+
+## Usage
+
+```text
+/prototype
+```
+
+State the design question. For production code, use `tdd`; for talking a design through without building anything, use `grill-me`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The branch dispatch table and the rules that apply to both branches |
+| `references/logic.md` | The logic branch, read only when that row is selected: when it is the right shape, and how to build the interactive terminal app |
+| `references/ui.md` | The UI branch, read only when that row is selected: when it is the right shape, and how to build and switch between the variations |
+
+Each reference is self-contained — a run reads one of the two, never both.

plugins/bin/skills/prototype/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: prototype
-description: Build a throwaway prototype to flush out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".
+description: >
+  Use when the user wants a throwaway prototype to answer a design question about
+  a data model, state machine or business logic, or to mock up a UI in several
+  variations. Not production code -> `tdd`. Not talking a design through ->
+  `grill-me`.
 ---
 
 # Prototype
@@ -9,10 +13,12 @@ A prototype is **throwaway code that answers a question**. The question decides
 
 ## Pick a branch
 
-Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+| Question being answered | Build | Reference |
+|---|---|---|
+| "Does this logic / state model feel right?" | A tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper | `references/logic.md` |
+| "What should this look like?" | Several radically different UI variations on one route, switchable via a URL search param and a floating bottom bar | `references/ui.md` |
 
-- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+Resolve the row from the user's prompt, the surrounding code, or by asking if the user is around, then read only that reference — each is self-contained.
-- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
 
 The two branches produce fundamentally different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
 

plugins/bin/skills/prototype/references/logic.md

@@ -9,7 +9,7 @@ A tiny interactive terminal app that lets the user drive a state model by hand.
 - "I want to feel out what the API should look like before writing it."
 - Anything where the user wants to **press buttons and watch state change**.
 
-If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+If the question is "what should this look like" — wrong branch. Read `references/ui.md`.
 
 ## Process
 

plugins/bin/skills/prototype/references/ui.md

@@ -2,7 +2,7 @@
 
 Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
 
-If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+If the question is about logic/state rather than what something looks like — wrong branch. Read `references/logic.md`.
 
 ## When this is the right shape
 

plugins/bin/skills/research/META.md

@@ -1,15 +0,0 @@
-```yaml
-version: "1.1"
-updated: 2026-06-21
-
-when: >-
-  Invoked when the user wants to gather structured reference documentation for a
-  tool, library, or API from MCP documentation indexes or web sources. Typically
-  run before writing a new skill that wraps an external tool, or any time
-  reference files are needed for a topic. Triggered explicitly
-  ("/research <topic> <path>") or implicitly when the user asks to look up,
-  gather, or pull docs for a topic before implementing something.
-
-references:
-  - .agents/skills/context7-mcp/SKILL.md  # context7-mcp — MCP source channel integrated at step 2
-```

plugins/bin/skills/research/README.md

@@ -0,0 +1,31 @@
+# research
+
+Research a tool, library or API from canonical documentation into a directory of structured per-topic reference files.
+
+## What it does
+
+Runs a six-step pipeline: scope against the working directory (what version is actually in use, what is already documented), resolve the topic through Context7, websearch for canonical docs covering whatever Context7 missed, read those sources, deepen one level into the links worth following, then write one markdown file per topic area plus a `sources.md` provenance record.
+
+Four gotchas at the top of `SKILL.md` shape the whole run, and each exists because of a specific failure: the output path is never inferred (a guessed destination scatters a directory's worth of files through someone's source tree); nothing is written outside that path; no empty topic file is ever written (a stub `troubleshooting.md` reads downstream as researched and closed); and a Context7 "no results", redirect or header-only response does not count as coverage. If no topic area has content, the run writes nothing at all — `sources.md` included — and reports what it searched.
+
+The frontmatter pins `model: sonnet` and a closed `allowed-tools` list. Notably it grants no subagent tool, so every `WebFetch` is serial and each fetched page lands in the run's own context — which is why steps 4 and 5 insist on reducing each page to notes before fetching the next, and cap deepening at roughly ten extra pages.
+
+## Composition
+
+Both reference files are read on condition, never on every run — `SKILL.md` inlines the minimum each step needs (the seven default topic areas at step 1, the four `sources.md` field names and the topic-file frontmatter keys at step 6) and sends the run to the reference only for what it does not carry. Those four field names are matched literally by the downstream provenance validator, so prose written in their place parses as nothing and the check passes having verified nothing — which is why they are inlined rather than deferred.
+
+## Usage
+
+```text
+/research
+```
+
+Name the topic and the output path — the skill will stop and ask if the path is missing. Supplying starting URLs is treated as a deliberate source choice and skips Context7 resolution and discovery. For documentation derived from existing code or specs, use `write-docs`; for a bug or incident, use `diagnose`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The four gotchas and the six research steps |
+| `references/topics.md` | Read at Step 1 only when what belongs in a default topic is unclear or a custom topic is needed: the per-topic coverage table and the custom-topic naming rule |
+| `references/file-format.md` | Read at Step 6 only when the inlined field names do not settle the case: slug derivation, the Context7 slug and URL convention, and what belongs in a topic body |

plugins/bin/skills/research/SKILL.md

@@ -1,97 +1,78 @@
 ---
 name: research
 description: >-
-  Use when the user wants to research a topic and generate structured reference
+  Use when the user wants a tool, library, or API researched from canonical
-  markdown files. Handles: finding canonical docs for a tool/library/API via
+  documentation into structured per-topic reference markdown files. Not
-  Context7 MCP or web sources, reading and deepening into linked pages,
+  documentation written from existing code or specs -> `write-docs`. Not a bug
-  organizing extracted content into topic files (overview, installation,
+  or incident -> `diagnose`.
-  configuration, cli-reference, api-reference, examples, troubleshooting). Do
-  NOT use when the user wants to write documentation from existing code or specs
-  (use write-docs), install or manage the neuledge-context MCP server (use
-  neuledge-context), or research a bug/incident (use diagnose).
 metadata:
   category: research
 allowed-tools:
-  - WebSearch
+  - Grep
-  - WebFetch
+  - Glob
   - Read
   - Write
+  - WebSearch
+  - WebFetch
   - mcp__context7__resolve-library-id
   - mcp__context7__query-docs
 model: sonnet
 ---
 
-<requirements>
+## Gotchas
 
-## Required inputs
+- Never infer the output path. A run writes a directory's worth of files, and a guessed destination scatters them through someone's source tree. If the user named no path, stop and ask.
+- Write nothing outside the given output path. A file placed beside the agreed directory is one the user never asked for and will not think to look for.
+- Never write an empty topic file. A stub `troubleshooting.md` reads downstream as researched and closed.
+- A Context7 response that is a "no results" message, a redirect notice, or header-only boilerplate is not coverage. A topic area counts as covered only when the response carries at least one substantive paragraph.
 
-- **Topic** — the subject to research (tool, library, API, concept); inferred from user description if clear, ask if ambiguous
+## Step 1 — Scope against the working directory
-- **Output path** — directory where reference files will be written; must be provided explicitly — do not infer or default
-- **Starting URLs** — optional; if provided, skip discovery websearch and read these first
 
-## Constraints
+Search for existing use of the topic — imports, config files, version pins, reference files already written — and narrow the research to what is missing: the version actually in use, the topics not yet documented.
 
-- Never write files outside the explicitly provided output path
+The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`,
-- Skip any default topic file if no relevant content is found for it — do not create empty files
+`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists.
-- Create additional topic files beyond the default list when content warrants it (e.g. `webhooks.md`, `rate-limits.md`)
+If what belongs in one of them is unclear, or the topic needs a file outside that set, read
-- Subagents handle parallel source reading and link deepening — the orchestrator writes all files; subagents return summaries only, never write directly
+`references/topics.md` for the per-topic coverage table and the custom-topic naming rule.
-- Context7 MCP calls (`resolve-library-id`, `query-docs`) are made only by the orchestrator at step 2 — subagents must not call them
-- `sources.md` is always written, even if only one source was read
-- Each topic file must have frontmatter with `topic` and `source_keys`; body is prose only — no inline URLs
-- Source keys in `sources.md` must be kebab-case slugs: derived from the source domain or page title for web sources; for Context7 sources use `context7-<library-slug>` (e.g. `context7-vercel-next-js`)
-- Default topic list and file format spec live in `references/` sub-files — read them at step 1
 
-</requirements>
+## Step 2 — Resolve against Context7
 
-<steps>
+If the topic is a library, framework, or API and the user gave no starting URLs, call `resolve-library-id` with the topic name and the user's full question — match quality depends on the question, not the bare name — then `query-docs` once per default topic area. Record each response as a source with slug `context7-<library-slug>`, and mark which topic areas it covered — those skip the web reads at step 4.
 
-## Process
+If the library does not resolve, or the user gave starting URLs, go to step 3. Explicit URLs are a source choice; do not second-guess them with a resolution attempt.
 
-1. **Scan codebase.** Search the working directory for existing usage of the topic — imports, config files, version pins, existing reference files. Use findings to narrow research scope (e.g. target the version already in use, skip topics already documented). Read `references/topics.md` for the default topic list and `references/file-format.md` for the output file format spec.
+## Step 3 — Discover sources
 
-2. **Try Context7.** If the topic is a library, framework, or API and no starting URLs were provided, call `resolve-library-id` with the topic name and the user's question. If a match resolves, call `query-docs` once per default topic area (see `references/topics.md`). Treat each response as a source summary with slug `context7-<library-slug>` (e.g. `context7-vercel-next-js`). A topic area has sufficient content when the Context7 response contains at least one substantive paragraph — not a "no results" message, redirect notice, or header-only boilerplate. Mark covered topic areas — skip their subagent web reads in step 4. If the library does not resolve, or starting URLs were provided (explicit source choice by the user), skip this step entirely.
+If the user gave starting URLs, skip discovery: those URLs are the source list and go straight to step 4.
 
-3. **Discover sources.** For topics not covered by Context7 (or when no starting URLs were provided and Context7 did not resolve), websearch for canonical documentation (prefer `llms.txt`, developer docs, official API references over tutorials or blog posts). Collect 3–5 candidate URLs before reading any.
+Otherwise, for every topic area Context7 did not cover, websearch for canonical documentation — `llms.txt`, official developer docs, and API references ahead of tutorials or blog posts. Collect three to five candidate URLs before reading any of them.
 
-4. **Read sources in parallel.** Spawn one subagent per source URL. Each subagent fetches the page, extracts relevant content, identifies links worth deepening, and returns a structured summary (content by topic area + links to follow). Subagents do not write files.
+If nothing usable comes back, stop and report what was searched, then ask for starting URLs rather than settling for tutorials.
 
-5. **Deepen.** For each subagent that returned links worth following, spawn child subagents per branch. Continue until content becomes repetitive or out of scope. Cap at ~10 additional pages total across all branches.
+## Step 4 — Read the sources
 
-6. **Consolidate.** Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.
+`WebFetch` each URL in turn. No subagent tool is granted here, so the reads are serial and every fetched page lands in this context: reduce each page to notes by topic area, plus the links worth deepening, before fetching the next one.
 
-7. **Write topic files.** For each topic with content, write `<output-path>/<topic>.md` using the format in `references/file-format.md`. Orchestrator writes all files — never delegate file writing to a subagent.
+## Step 5 — Deepen
 
-8. **Write `sources.md`.** Write `<output-path>/sources.md` mapping each source slug to its URL (use `context7:<library-id>` as the URL for Context7 sources), description, and list of topic files it contributed to. Include sources that yielded no content, marked `no content extracted`.
+`WebFetch` the links worth following, still one at a time and still reducing each page to notes. Stop a branch once its content turns repetitive or leaves the topic, and cap the whole step at roughly ten additional pages — serial reads make that cap a real budget, not a formality.
 
-## Output format
+## Step 6 — Write
 
-- `<output-path>/<topic>.md` per topic with content — formatted per `references/file-format.md`
+Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path:
-- `<output-path>/sources.md` — always produced; maps slug → URL, description, contributing files
 
-</steps>
+- `<topic>.md` for each topic area that has content, default or custom. Frontmatter carries `topic:` (the filename without `.md`) and `source_keys:` (kebab-case slugs matching `sources.md`); the body is prose in `##` sections, with no inline URLs.
+- `sources.md`, always, one `##` section per source — including sources that yielded nothing — with exactly these four fields:
 
-<checks>
+  ```markdown
+  - **URL:** <full URL>
+  - **Description:** <one-line summary>
+  - **Contributing files:** <topic files this source contributed to>
+  - **Status:** `extracted` | `no content extracted`
+  ```
 
-## Failure handling
+Spell those four field names exactly as given. The downstream provenance validator matches them literally; prose in their place parses as nothing, and the check passes having verified nothing.
 
-- Output path not provided — stop and ask; do not infer or default
+Read `references/file-format.md` when the four fields above do not settle the case: what a slug should be, the `context7-<library-slug>` slug and `context7:<library-id>` URL convention for a Context7 source, or what belongs in a topic body versus a verbatim copy of the source.
-- No sources found after websearch — report what was searched, ask user to provide starting URLs
-- Subagent returns no usable content — skip that source, log in `sources.md` as `no content extracted`
-- All topic files would be empty — stop, report what was searched, do not write any files
 
-## Self-check
+If no topic area has content, write nothing at all, `sources.md` included, and report what was searched.
-
-- [ ] Codebase scanned before any websearch was performed
-- [ ] Output path was explicitly provided — not inferred
-- [ ] `references/topics.md` and `references/file-format.md` read at step 1
-- [ ] Context7 resolution attempted before websearch when topic is a library/framework/API
-- [ ] Context7 calls made only at orchestrator step 2 — no subagent called `resolve-library-id` or `query-docs`
-- [ ] Context7 sources recorded in `sources.md` with `context7:<library-id>` as URL
-- [ ] No topic file written without content
-- [ ] `sources.md` written with all sources read (including those with no content extracted)
-- [ ] All file writes performed by the orchestrator, not subagents
-- [ ] Each topic file has `topic` and `source_keys` frontmatter fields
-- [ ] All source keys in topic files have a matching entry in `sources.md`
-- [ ] No files written outside the provided output path
-
-</checks>

plugins/bin/skills/tdd/README.md

@@ -0,0 +1,32 @@
+# tdd
+
+Test-driven development as a strict red-green-refactor loop, one behaviour at a time.
+
+## What it does
+
+Two convictions drive this skill. The first is about what a test is for: tests verify behaviour through public interfaces, not implementation details. A good test reads like a specification ("user can checkout with valid cart") and survives refactors because it does not care about internal structure. The warning sign for a bad one is precise — the test breaks when you refactor but behaviour has not changed.
+
+The second is an explicit anti-pattern: **do not write all the tests first, then all the implementation.** Horizontal slicing treats RED as "write every test" and GREEN as "write every implementation", and it produces tests of *imagined* behaviour — tests of the shape of things, insensitive to real change, committed to before the implementation was understood. The correct shape is vertical: one test → one implementation → repeat, each cycle informed by what the last one taught you.
+
+The workflow is four stages: plan (confirm the interface and which behaviours matter, with the user — you cannot test everything), fire a tracer bullet (one test proving the path works end to end), loop incrementally one behaviour at a time, then refactor once everything is green. Refactoring while RED is forbidden.
+
+Codebase exploration uses the project's domain glossary, so test names and interface vocabulary match the project's language, and ADRs in the area are respected.
+
+## Usage
+
+```text
+/tdd
+```
+
+Describe the feature or bug. Expect the skill to ask what the public interface should look like and which behaviours matter most before any code is written. For diagnosing an existing bug rather than building test-first, use `diagnose`; for throwaway exploratory code, use `prototype`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Philosophy, the horizontal-slicing anti-pattern, the four-stage workflow, and the per-cycle checklist |
+| `tests.md` | Skill-root document, cited from Philosophy: worked good and bad test examples |
+| `mocking.md` | Skill-root document, cited from Philosophy: mock at system boundaries only, and what not to mock |
+| `deep-modules.md` | Skill-root document, cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
+| `interface-design.md` | Skill-root document, cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
+| `refactoring.md` | Skill-root document, cited from stage 4: the refactor-candidate checklist — duplication, long methods, shallow modules, feature envy, primitive obsession |

plugins/bin/skills/tdd/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tdd
-description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+description: >
+  Use when the user wants a feature built or a bug fixed test-first, in a strict
+  red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
+  bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
 ---
 
 # Test-Driven Development
@@ -13,7 +16,7 @@ description: Test-driven development with red-green-refactor loop. Use when user
 
 **Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
 
-See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `tests.md`. If a test needs a collaborator faked, read `mocking.md` before reaching for a mock.
 
 ## Anti-Pattern: Horizontal Slices
 

plugins/bin/skills/triage/AGENT-BRIEF.md

@@ -1,6 +1,6 @@
 # Writing Agent Briefs
 
-An agent brief is a structured comment posted on a GitHub issue when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
+An agent brief is a structured comment posted on an issue in the issue tracker when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original issue body and discussion are context — the agent brief is the contract.
 
 ## Principles
 
@@ -27,7 +27,7 @@ Describe **what** the system should do, not **how** to implement it. The agent w
 
 The agent needs to know when it's done. Every agent brief must have concrete, testable acceptance criteria. Each criterion should be independently verifiable.
 
-- **Good:** "Running `gh issue list --label needs-triage` returns issues that have been through initial classification"
+- **Good:** "Querying the issue tracker for the `needs-triage` label returns issues that have been through initial classification"
 - **Bad:** "Triage should work correctly"
 
 ### Explicit scope boundaries

plugins/bin/skills/triage/README.md

@@ -0,0 +1,35 @@
+# triage
+
+Move issues on the project issue tracker through a small state machine of triage roles.
+
+## What it does
+
+Gives issue triage an explicit state model and a fixed set of moves. Every issue carries exactly one **category** role (`bug`, `enhancement`) and one **state** role (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`); conflicting state roles are flagged to the maintainer before anything else happens. Unlabeled issues normally enter at `needs-triage`; `needs-info` returns there once the reporter replies. The maintainer can override at any point, and unusual transitions are questioned rather than executed silently.
+
+A run does one of three things depending on what the maintainer asks for:
+
+- **Show what needs attention** — three buckets, oldest first: unlabeled, `needs-triage`, and `needs-info` with reporter activity since the last triage notes.
+- **Triage a specific issue** — gather context (including prior triage notes, so resolved questions are not re-asked, and `.out-of-scope/` records that resemble the issue), recommend a category and state with reasoning, attempt reproduction for bugs *before* any grilling, run a `grill-with-docs` session if the issue needs fleshing out, then apply the outcome.
+- **Quick state override** — "move #42 to ready-for-agent" is trusted and applied directly, skipping grilling, after confirming the exact changes.
+
+Two hard rules: every comment or issue the skill posts during triage must open with the AI-generated disclaimer, and the canonical role names above are *not* necessarily the label strings in the tracker — each is resolved against the tracker's live label set before it is applied, and a name with no counterpart there is reported to the maintainer as a gap rather than guessed at.
+
+## Composition
+
+`grill-with-docs` is invoked at step 4 when an issue needs fleshing out; whatever that session establishes is carried into the triage notes so the work is not lost. The reverse direction also exists: `diagnose` names this skill as the place to send a *reported* bug that needs filing rather than debugging.
+
+## Usage
+
+```text
+/triage
+```
+
+Then describe what you want in natural language — "show me anything that needs my attention", "let's look at #42", "move #42 to ready-for-agent", "what's ready for agents to pick up?".
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The roles and state machine, the three invocation modes, the needs-info template, and how to resume a prior session |
+| `AGENT-BRIEF.md` | Skill-root document, cited when an issue moves to `ready-for-agent` (and reused for `ready-for-human`): how to write a brief that stays durable for weeks while the codebase moves under it — describe interfaces and behavioural contracts, not line numbers |
+| `OUT-OF-SCOPE.md` | Skill-root document, cited when an enhancement is closed `wontfix` and when checking for prior rejections: how the `.out-of-scope/` knowledge base is laid out and what it is for — institutional memory, and deduplication against re-litigated requests |

plugins/bin/skills/triage/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: triage
-description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
+description: >
+  Use when the user wants an issue created, triaged, or moved through the
+  tracker's triage states, or an issue prepared for an AFK agent. Not debugging
+  the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
 ---
 
 # Triage
@@ -35,7 +38,7 @@ Five **state** roles:
 
 Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
 
-These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
+These are canonical role names — the actual label strings used in the issue tracker may differ. Resolve each canonical name against the tracker's live label set before applying it, using whichever tracker skill this install provides. If a name has no counterpart there, report the gap and ask the maintainer for the mapping — never substitute a guess.
 
 State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
 

plugins/bin/skills/write-docs/README.md

@@ -0,0 +1,30 @@
+# write-docs
+
+Produce technical documentation derived from code and spec, one section at a time, with a confirmation gate on every section.
+
+## What it does
+
+Casts the agent as a technical writer with one non-negotiable constraint: **every claim must be traceable to a source file line, a spec section, or an explicit user statement.** Nothing is invented, and behaviour that genuinely cannot be documented from the available sources is marked out-of-scope rather than explained away.
+
+The process is eight steps — identify scope, read and extract, gap check, draft section by section, confirmation gate, delta summary, reader testing, finalise — and several of them are deliberately gated on the human:
+
+- Files are read only after the user approves them by name. The skill may propose candidates; it waits.
+- The **gap check** presents what the code does say and asks the user to fill only what it does not: caller intent, error-handling rationale, non-obvious side effects.
+- No section is finalised until the full revised text has been shown. The skill never gates on output the user has not seen, and never reprints the whole document — all edits are surgical.
+- **Reader testing** predicts 5–10 questions a target reader would ask, then spawns a sub-agent that receives only the finished doc and the questions — no source files. If the doc cannot answer them, neither can the sub-agent, and the run loops back to drafting.
+
+Summary and overview sections are written last, once the detail sections are stable.
+
+## Usage
+
+```text
+/write-docs
+```
+
+Name the files or modules to document, the target audience (developer / user / contributor / internal), and the documentation type (reference, guide, README section, inline comment, changelog entry). For a PRD, ADR or decision doc, use `grill-me` or `grill-with-docs` instead — those have dedicated handling.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — role, use/do-not-use boundaries, required inputs, constraints, the eight-step process, output format, failure handling, and a nine-item self-check |

plugins/bin/skills/write-docs/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: write-docs
-description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills.
+description: >
+  Use when the user wants technical documentation produced or updated from code
+  or spec, every claim traced to a source — "write docs for X", "document this
+  module", "create docs for this feature", "write a README for this". Not an ADR
+  or other decision record -> `grill-with-docs`. Not an external tool researched
+  from its docs -> `research`.
 version: "1.0"
 updated: 2026-05-17
 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
@@ -35,7 +40,8 @@ You are a technical writer that produces documentation by reading code and spec
 - User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
 
 **Do not use when:**
-- User wants a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me`
+- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs
+- User wants a PRD → no skill in this set produces one; say so rather than redirecting
 - User wants to document a skill file (skill files are self-describing)
 - User wants marketing or blog copy
 - Documentation requires tacit organisational knowledge that cannot be read from code or spec
@@ -88,7 +94,7 @@ You are a technical writer that produces documentation by reading code and spec
 - Stage skipped without a logged reason → flag and require the one-sentence log before continuing
 - Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation
 - Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete
-- Requested output is a PRD, decision doc, or architecture proposal → redirect to `to-prd`, `grill-me`, or `grill-with-docs`
+- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting
 
 ## Self-check
 

plugins/bin/skills/zoom-out/README.md

@@ -0,0 +1,25 @@
+# zoom-out
+
+Ask the agent to go up a layer of abstraction and map the modules and callers around unfamiliar code.
+
+## What it does
+
+A single-purpose prompt for the moment you land in a part of the codebase you do not know. Instead of answering at the level of the file in front of it, the agent climbs one layer and produces a map of the relevant modules and their callers — and names them using the project's own domain glossary vocabulary, so the map lines up with the language the rest of the repo already uses.
+
+## Hand-invoked only
+
+`SKILL.md` sets `disable-model-invocation: true`, so the router never selects this skill on its own and no other skill can hand off to it. It runs when the human asks for it. That also means its description is written as one plain human-facing sentence — it carries no trigger phrasing or boundary clause, because nothing routes on it.
+
+## Usage
+
+```text
+/zoom-out
+```
+
+Best used with the unfamiliar code already in context — the skill widens the view around what you are looking at rather than picking a starting point for you.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | The whole skill — a single instruction, no supporting files |

plugins/core/.apm/skills/agentsmd-audit/README.md

@@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any
 
 Provide the path to the repo root to audit when invoking.
 
+Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
+hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.
+
 ## Files
 
 | File | Purpose |
@@ -30,6 +33,6 @@ Provide the path to the repo root to audit when invoking.
 | `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
 
 Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
-not present in an installed plugin: `scripts/sync-plugin-content.sh` strips `<category>/<name>/tests`
+not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
-when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
-discover (ADR-0017). Run them from a repo checkout, not from an install.
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/core/.apm/skills/agentsmd-audit/SKILL.md

@@ -1,20 +1,11 @@
 ---
 name: agentsmd-audit
 description: >
-  Use when the user wants to review a repo's AGENTS.md file, says "audit this
+  Use when the user wants a repo's AGENTS.md audited for secrets, structure
-  AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to
+  and drift — "is this AGENTS.md safe to commit" — or after a hand-edit
-  know if AGENTS.md is safe to commit — even if they don't use the word
+  outside `agentsmd-author`.
-  "audit". Also invoke proactively after agentsmd-author creates or updates
+  Not converting a provider file -> `provider-adapter-author`.
-  AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a
+  Not writing AGENTS.md -> `agentsmd-author`.
-  target repo's AGENTS.md file(s) — root and any nested monorepo files — for
-  embedded secrets/credentials, structural completeness against the
-  agents.md common-sections checklist, and drift (referenced commands or
-  paths that no longer resolve against the repo). Produces a compact
-  findings report (findings only, no PASS noise) with Why and Fix per
-  finding. Do not use to audit CLAUDE.md, .cursor/rules, or other
-  provider-specific adapter files — that's provider-adapter-author's
-  self-contained concern. Do not use to fix or write AGENTS.md content — use
-  agentsmd-author instead.
 allowed-tools: Bash Read
 metadata:
   category: docs
@@ -23,14 +14,13 @@ metadata:
     - context7-websites-agents-md
     - context7-agentsmd-agents-md
     - governance-secrets-hard-prohibition
-  version: "0.1.1"
+  version: "0.1.2"
 ---
 
 ## Gotchas
 
 - Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found.
-- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's.
+- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
-- A missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
 - Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report.
 
 ## Step 1 — Run the validators
@@ -41,7 +31,7 @@ bash scripts/validate-structure.sh <repo-root>
 bash scripts/validate-drift.sh <repo-root>
 ```
 
-Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand.
+Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL` lines, plus `INFO`/`SUGGESTION` where applicable, with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
 
 ## Step 2 — Report
 
@@ -53,16 +43,4 @@ Checked: secrets · structure · drift
 
 Then output only findings that were found, in this order within a repo: `### Secrets`, `### Structure`, `### Drift`. Omit a dimension heading entirely if it produced nothing — its absence confirms it passed. Report each finding verbatim as emitted by the scripts (they already carry file:line, Why/Fix or Note).
 
-Close with a result block:
+Close with a `## Result` block holding one line: `PASS`, `PASS (N suggestions)`, or `FAIL (N fails · M suggestions)`, each optionally followed by ` · P info`. Omit the suggestion count when there are none, and omit `· P info` when there are none. INFO and SUGGESTION findings are observational — they never flip PASS to FAIL. Do not fix anything — this skill reports and proposes only. Point the user to `agentsmd-author` to apply fixes.
-
-```text
-## Result
-
-PASS
-PASS · P info
-PASS (N suggestions) · P info
-FAIL (N fails)
-FAIL (N fails) · P info
-```
-
-INFO and SUGGESTION findings are observational — they never flip PASS to FAIL. Do not fix anything — this skill reports and proposes only. Point the user to `agentsmd-author` to apply fixes.

plugins/core/.apm/skills/agentsmd-author/SKILL.md

@@ -1,20 +1,10 @@
 ---
 name: agentsmd-author
 description: >
-  Use when the user wants to create or update a repo's AGENTS.md file
+  Use when the user wants a repo's AGENTS.md written or updated, root or
-  ("write an AGENTS.md for this repo", "add setup/test instructions for
+  nested, including "document this for AI coding tools". Writes only verified
-  agents", "update AGENTS.md", "give this package its own AGENTS.md") — even
+  conventions. Not review-only -> `agentsmd-audit`. Not converting CLAUDE.md ->
-  if they don't name the file explicitly, e.g. "document this for AI coding
+  `provider-adapter-author`.
-  tools" or "make sure agents know how to run tests here". Writes/updates
-  AGENTS.md by exploring the target repo for real build, test, lint, and
-  style conventions — never invents commands. Supports nested monorepo
-  placement (a subdirectory can get its own AGENTS.md following
-  nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
-  inline, and calls provider-adapter-author when an existing provider file
-  (CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
-  an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
-  not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
-  provider-adapter-author instead.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: docs
@@ -22,16 +12,13 @@ metadata:
     - agents-md-official
     - context7-websites-agents-md
     - context7-agentsmd-agents-md
-  version: "0.1.1"
+  version: "0.1.2"
 ---
 
 ## Gotchas
 
 - Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
-- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one.
+- Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
-- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
-- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
-- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
 
 ## Step 1 — Explore the target repo
 
@@ -40,17 +27,17 @@ Before writing anything, gather real facts: package manager and scripts (`packag
 ## Step 2 — Decide placement
 
 - No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions.
-- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Don't repeat root-level content — the nearest-file-wins rule means the nested file is read alone, not merged with the root.
+- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Convenience is not a reason to create one — without a distinct stack you are duplicating content the root already covers. **Don't repeat root-level content** in a nested file: the nearest-file-wins rule means it is read alone, never merged back with the root.
 - Otherwise → update the existing file(s) in place.
 
 ## Step 3 — Write or update
 
-Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
+AGENTS.md has no required schema. Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists, because a thin accurate file beats a padded generic one. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
 
 ## Step 4 — Check for an existing provider file
 
-Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists and now duplicates content the AGENTS.md you just wrote/updated already owns, invoke the `provider-adapter-author` skill on it to reconcile — don't rewrite it yourself.
+Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists, invoke the `provider-adapter-author` skill on it to reconcile — whether it duplicates content the AGENTS.md you just wrote/updated now owns, or is merely stale or missing a pointer to it. Never edit it yourself in either case.
 
 ## Step 5 — Audit and report
 
-Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.
+Invoke the `agentsmd-audit` skill on the target repo root — its validators take a `<repo-root>` and walk the tree for every AGENTS.md themselves; there is no per-file entry point. This closeout is mandatory, not optional, even when the change looks trivial — never sign the work off on your own judgment. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.

plugins/core/.apm/skills/provider-adapter-author/README.md

@@ -23,6 +23,7 @@ Provide the path to the provider-specific file to convert (and the target repo r
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically |
 | `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
 | `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
 | `scripts/README.md` | Directory documentation for `scripts/` |
@@ -30,6 +31,6 @@ Provide the path to the provider-specific file to convert (and the target repo r
 | `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
 
 Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
-but are not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
 `<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
 plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/core/.apm/skills/provider-adapter-author/SKILL.md

@@ -1,43 +1,41 @@
 ---
 name: provider-adapter-author
 description: >
-  Use when the user wants to convert a provider-specific AI instruction file
+  Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions)
-  (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) into a
+  duplicating the repo's AGENTS.md should be cut to a thin adapter — "make
-  thin adapter that defers to a repo's AGENTS.md — e.g. "reduce duplication
+  CLAUDE.md just import AGENTS.md".
-  between CLAUDE.md and AGENTS.md", "make CLAUDE.md just import AGENTS.md"
+  Not writing the AGENTS file -> `agentsmd-author`.
-  — even if the pattern isn't named explicitly. Also invoke when
+  Not auditing the AGENTS file -> `agentsmd-audit`.
-  agentsmd-author detects an existing provider file overlapping with
-  AGENTS.md it just wrote. Detects redundant content in a provider file
-  relative to AGENTS.md and rewrites it down to a minimal reference (an
-  `@AGENTS.md`-style import where supported, or a text pointer otherwise)
-  plus genuinely provider-specific additions. Self-validates via a bundled
-  deterministic script before finishing. Do not use to write or audit
-  AGENTS.md itself — use agentsmd-author or agentsmd-audit.
 allowed-tools: Bash Read Edit Write
 metadata:
   category: docs
   source_keys:
     - adr-0002-0003-two-tier-claude-md
-  version: "0.1.0"
+  version: "0.1.1"
 ---
 
 ## Gotchas
 
-- Not every provider supports cross-file imports. Claude Code does — a `CLAUDE.md` can consist of nothing but one or more `@path` lines (e.g. `@AGENTS.md`), with no other content required. Cursor's `.cursor/rules/*.mdc` and GitHub Copilot's `copilot-instructions.md` have no native import mechanism as of current tooling — for those, "thin" means a short text pointer to AGENTS.md plus only what that tool actually needs, not a literal import line. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for these providers.
+- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers.
-- This skill never creates or edits `AGENTS.md` itself. If the target repo has no `AGENTS.md` yet, stop and point the user to `agentsmd-author` first — there's nothing to adapt to.
+
-- Only strip content from the provider file that's genuinely redundant with AGENTS.md. Provider-specific material (IDE settings, tool-only syntax, model-specific instructions) stays — the goal is thin, not empty.
+- Works standalone or composed-into by `agentsmd-author` — behave identically either way; do not assume a caller skill exists. Detect the provider file, confirm `AGENTS.md`, and run the closeout validator yourself in both cases (`references/provider-matrix.md`).
-- Works standalone or composed-into by `agentsmd-author` — behave identically either way; don't assume a caller skill exists.
 
 ## Step 1 — Detect
 
-Look for known provider instruction files in the target repo: `CLAUDE.md` (repo root, and any deployed copies), `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and similar tool-specific files. Confirm `AGENTS.md` exists at the repo root — if not, stop and tell the user to run `agentsmd-author` first.
+Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case.
+
+Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to.
 
 ## Step 2 — Diff and rewrite
 
 Read the provider file and `AGENTS.md` side by side. Separate the provider file's content into two buckets: lines that restate what `AGENTS.md` already owns (universal rules, conventions, project overview) versus lines that are genuinely provider-specific (tool syntax, IDE behavior, model-specific instructions). Rewrite the provider file:
 
-- **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import line, keep the provider-specific bucket below it.
+- **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import on a line of its own, keep the provider-specific bucket below it. An import folded into a sentence is not the thin-adapter shape and `scripts/validate-adapter.sh` will not credit it — nor one inside a code fence, an indented block, or an HTML comment, nor one whose path does not resolve to a real, non-empty file on disk.
-- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short pointer sentence mentioning `AGENTS.md`, keep the provider-specific bucket.
+- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short sentence pointing at `AGENTS.md` ("See AGENTS.md at the repo root for ..."), keep the provider-specific bucket. A bare or negated mention is not a pointer and will not be credited.
+
+The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like.
+
+Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty.
 
 ## Step 3 — Self-validate
 
@@ -47,7 +45,7 @@ Run the bundled check before finishing — this is the skill's own closeout gate
 bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
 ```
 
-Fix any `FAIL` and re-run until it exits `0`.
+Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. Exits `2` and `3` are not `FAIL`s and nothing was graded under either, so neither is a reason to touch the adapter: `2` means the invocation or the input is wrong (a bad, missing, or extra argument, an unknown option, or a file that is not UTF-8), and `3` means a named file exists but could not be read.
 
 ## Step 4 — Report
 

plugins/core/.apm/skills/provider-adapter-author/references/provider-matrix.md

@@ -0,0 +1,32 @@
+---
+source_keys:
+  - adr-0002-0003-two-tier-claude-md
+---
+
+# Known provider instruction files
+
+Which files to look for when detecting a provider-specific instruction file, whether each provider
+resolves a cross-file import, and what a thin adapter therefore looks like for it.
+
+| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag |
+|---|---|---|---|---|
+| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none |
+| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` |
+| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` |
+| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` |
+
+A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's
+own documentation before emitting an `@`-style line; an unresolved import reads as literal text and
+silently drops every rule the adapter was supposed to defer to.
+
+Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts
+independently against the same `AGENTS.md`.
+
+## Standalone and composed runs behave identically
+
+This skill is reached two ways: invoked directly by a user, and composed into by `agentsmd-author`
+once it has written or updated the repo's `AGENTS.md`. Behave identically either way — do not
+assume a caller skill exists. Detect the provider file yourself, confirm `AGENTS.md` yourself, and
+run the closeout validator yourself, rather than treating any step as already done by the caller or
+as something the caller will do afterwards. No handshake exists to rely on, and no state is
+passed in beyond the file paths.

plugins/core/.apm/skills/provider-adapter-author/references/sources.md

@@ -5,5 +5,5 @@
 - **URL:** (in-repo precedent — not an external source or plugin research corpus entry)
 - **Description:** This repo's own two-tier CLAUDE.md/AGENTS.md pattern: AGENTS.md is the provider-agnostic source of always-on rules; provider-specific files (CLAUDE.md) become thin adapters that import it (`@AGENTS.md` plus provider-specific additions). Grounds this skill's entire adapter-conversion design — the "thin adapter" shape, the `@`-import convention, and the size/duplication expectations enforced by `scripts/validate-adapter.sh`.
 - **Research doc:** docs/adr/0002-two-tier-claude-md.md, docs/adr/0003-agents-md-provider-agnostic-entry-point.md, providers/claude-code/CLAUDE.md (in-repo ADRs and a live example, not a plugin research corpus entry; referenced here since this skill's design is modeled directly on an existing implementation rather than external research)
-- **Contributing files:** SKILL.md
+- **Contributing files:** SKILL.md, references/provider-matrix.md
 - **Status:** `extracted`

plugins/core/.apm/skills/provider-adapter-author/scripts/README.md

@@ -4,6 +4,25 @@ Deterministic self-check this skill shells out to instead of relying on LLM judg
 
 | File | Purpose |
 |------|---------|
-| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
+| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a working reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
 
-Takes `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags. Prints `FAIL` findings to stdout and exits non-zero on any failure.
+Takes exactly `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags (also accepted as `--max-lines=N`). A third positional argument or an unknown option is an error, not something quietly ignored.
+
+## What counts as a reference to AGENTS.md
+
+Both modes require the named path to be a real path segment ending in `AGENTS.md` — `AGENTS.md` or `…/AGENTS.md`, not `NOTAGENTS.md` — that resolves on disk, relative to the adapter file, to a non-empty file. An adapter deferring to a path that is not there defers to nothing, so the check has to touch the disk rather than pattern-match the line.
+
+A reference only counts where something would actually resolve it. A line inside a fenced code block, an indented code block, or an HTML comment is not credited in either mode: Claude Code resolves an import in none of those, so a fenced `@AGENTS.md` is the silent-drop failure this gate exists to catch, not a pass.
+
+Default mode wants a real import: `@AGENTS.md` alone on its own line, indented no more than three spaces. `--no-import-syntax` wants a prose pointer that reads as one — the sentence naming `AGENTS.md` must carry a deference cue (see, read, refer to, documented in, conventions, …) and must not be negated. `Do NOT read AGENTS.md; it is obsolete.` and `We deleted AGENTS.md last year.` name the file while pointing the reader away from it, and neither is a pointer.
+
+## Exit codes
+
+The distinction matters because the skill's closeout tells the agent to fix any non-zero exit by editing the provider file. That is right for exactly one of these.
+
+| Code | Meaning | What to do |
+|------|---------|------------|
+| `0` | Passes every check | Nothing |
+| `1` | One or more `FAIL` findings printed to stdout — empty adapter, no working reference to AGENTS.md, excessive duplication, or not thin | Edit the provider file |
+| `2` | Usage or input error: a bad, missing, or extra argument, an unknown option, a path that is not a file, or a file that is not UTF-8. Nothing was graded, so there is no `FAIL` line | Fix the invocation or the file's encoding — do not edit the adapter |
+| `3` | A named input file exists but could not be read (permissions, I/O error). Nothing was graded and the adapter's contents are unknown | Fix the file's readability — do not edit the adapter |

plugins/core/.apm/skills/provider-adapter-author/scripts/validate-adapter.sh

@@ -14,27 +14,85 @@ Arguments:
   adapter-file     Path to the provider-specific file to check.
   agents-md-file   Path to the AGENTS.md file it should defer to.
 
+  Exactly two positional arguments are accepted. Extra ones are rejected
+  rather than ignored: a third path silently graded nothing but the first
+  two, so a typo'd invocation passed against the wrong file.
+
 Options:
   --no-import-syntax  The target provider has no native cross-file import
-                       mechanism. Accept a plain-text pointer mention of
+                       mechanism. Require a plain-text pointer line naming
-                       "AGENTS.md" instead of requiring an @import-style line.
+                       "AGENTS.md" instead of an @import-style line; an
+                       @AGENTS.md line alone does not satisfy it, because
+                       such a provider never resolves it. Without this flag
+                       an actual @import line is required, and naming
+                       AGENTS.md in prose alone does not satisfy it.
   --max-lines N        Max non-blank lines allowed in the adapter file before
-                       it's considered no longer "thin". Default: 60.
+                       it's considered no longer "thin". Must be a
+                       non-negative integer. Default: 60.
   --help, -h           Show this help and exit 0.
+  --                   End of options; every later argument is positional.
+
+Both flags also accept the --flag=value form (--max-lines=40). An unknown
+option is reported as an unknown option, not as a missing file.
+
+What counts as a reference:
+
+  In both modes the named path must be a real path segment ending in
+  AGENTS.md ("AGENTS.md" or ".../AGENTS.md" — not NOTAGENTS.md), and it must
+  resolve on disk, relative to the adapter file, to a non-empty file. An
+  adapter deferring to a path that is not there defers to nothing.
+
+  A mention inside a fenced code block, an indented code block, or an HTML
+  comment is not credited in either mode. Nothing resolves those, so an
+  adapter whose only "import" is fenced silently defers to nothing.
+
+  With --no-import-syntax the pointer must read as a pointer: the sentence
+  naming AGENTS.md has to carry a deference cue (see, read, refer to,
+  documented in, conventions, ...) and must not be a negation ("do not read
+  AGENTS.md", "we deleted AGENTS.md"). A bare mention is not a pointer.
 
 Exit codes:
   0  Adapter file passes all checks
   1  One or more checks failed (empty file, no reference to AGENTS.md,
      excessive duplication, or file too long)
+  2  Usage or input error — a bad, missing, or extra argument, an unknown
+     option, a path that is not a file, or a file that is not UTF-8. Nothing
+     was graded, so there is no FAIL line and no adapter edit to make: fix
+     the invocation or the file's encoding and re-run. Kept distinct from 1
+     because the skill's own closeout tells the agent to fix every non-zero
+     exit by editing the provider file, which for a mistyped flag edits the
+     wrong file forever.
+  3  A named input file exists but could not be read (permissions, a
+     directory swapped in mid-run, I/O error). Also not a FAIL: nothing was
+     graded and the adapter's contents are unknown, so editing it is
+     guesswork. Fix the file's readability and re-run.
 EOF
 }
 
 NO_IMPORT_SYNTAX=0
 MAX_LINES=60
 ARGS=()
+END_OF_OPTS=0
+
+require_int() {
+  # $1 = the value to validate
+  if [[ ! "$1" =~ ^[0-9]+$ ]]; then
+    echo "Error: --max-lines expects a non-negative integer, got '$1'." >&2
+    exit 2
+  fi
+}
 
 while [[ $# -gt 0 ]]; do
+  if [[ $END_OF_OPTS -eq 1 ]]; then
+    ARGS+=("$1")
+    shift
+    continue
+  fi
   case "$1" in
+    --)
+      END_OF_OPTS=1
+      shift
+      ;;
     --help|-h)
       usage
       exit 0
@@ -43,10 +101,38 @@ while [[ $# -gt 0 ]]; do
       NO_IMPORT_SYNTAX=1
       shift
       ;;
+    --no-import-syntax=*)
+      echo "Error: --no-import-syntax is a flag and takes no value (got '$1')." >&2
+      exit 2
+      ;;
     --max-lines)
-      MAX_LINES="${2:-}"
+      if [[ $# -lt 2 ]]; then
+        echo "Error: --max-lines requires a value (a non-negative integer)." >&2
+        exit 2
+      fi
+      MAX_LINES="$2"
+      require_int "$MAX_LINES"
       shift 2
       ;;
+    --max-lines=*)
+      MAX_LINES="${1#--max-lines=}"
+      if [[ -z "$MAX_LINES" ]]; then
+        echo "Error: --max-lines requires a value (a non-negative integer)." >&2
+        exit 2
+      fi
+      require_int "$MAX_LINES"
+      shift
+      ;;
+    -*)
+      # Reported as an unknown option rather than falling through to the
+      # positional bucket, where it used to surface as "'--bogus' is not a
+      # file" — the right exit code attached to a diagnostic that sends the
+      # reader looking for a path they never typed.
+      echo "Error: unknown option '$1'." >&2
+      echo "" >&2
+      usage >&2
+      exit 2
+      ;;
     *)
       ARGS+=("$1")
       shift
@@ -58,7 +144,14 @@ if [[ ${#ARGS[@]} -lt 2 ]]; then
   echo "Error: adapter-file and agents-md-file are required." >&2
   echo "" >&2
   usage >&2
-  exit 1
+  exit 2
+fi
+
+if [[ ${#ARGS[@]} -gt 2 ]]; then
+  echo "Error: expected exactly 2 positional arguments (adapter-file and agents-md-file), got ${#ARGS[@]}: ${ARGS[*]}." >&2
+  echo "" >&2
+  usage >&2
+  exit 2
 fi
 
 python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
@@ -70,17 +163,80 @@ adapter_path, agents_md_path, no_import_syntax, max_lines = sys.argv[1:5]
 no_import_syntax = no_import_syntax == "1"
 max_lines = int(max_lines)
 
+EXIT_FAIL = 1
+EXIT_USAGE = 2
+EXIT_UNREADABLE = 3
+
 if not os.path.isfile(adapter_path):
     print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
-    sys.exit(1)
+    sys.exit(EXIT_USAGE)
 if not os.path.isfile(agents_md_path):
     print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
-    sys.exit(1)
+    sys.exit(EXIT_USAGE)
 
-with open(adapter_path, encoding="utf-8", errors="replace") as f:
+
-    adapter_content = f.read()
+def read_text(path):
-with open(agents_md_path, encoding="utf-8", errors="replace") as f:
+    r"""File contents as text, UTF-8, every BOM stripped.
-    agents_md_content = f.read()
+
+    The BOM strip is not cosmetic. IMPORT_RE anchors on `^ {0,3}@`, and a BOM
+    is not whitespace in Python, so a CLAUDE.md saved by an editor that emits
+    one had its first line — the `@AGENTS.md` import, which is the whole
+    adapter — silently treated as prose. The check then said "no reference to
+    AGENTS.md" and told the author to add the line already sitting in front of
+    them. Same class of silent BOM miss recorded in scripts/skill-size-check.sh;
+    strip it at the reader so no later check has to know about it.
+
+    Every U+FEFF goes, not just one at offset 0. Stripping exactly the first
+    one left the mirror-image false FAIL for a doubled BOM (two concatenated
+    files, or a tool that re-adds one) and for a BOM mid-file at the head of
+    the import line. U+FEFF has no meaning as a character in a markdown
+    instruction file, so removing all of them cannot lose signal.
+
+    Decoding is strict, not errors="replace". Replacement mangles the file and
+    the checks then grade the mangling: a UTF-16 adapter whose first line is
+    `@AGENTS.md` decoded to interleaved NULs and failed as "no reference",
+    which is a true FAIL for a false reason and points the fix at the wrong
+    thing. But strict UTF-8 alone does not catch it — BOM-less UTF-16LE/BE and
+    UTF-32LE are *valid* UTF-8, because NUL is a legal code point, so they
+    decoded clean and produced exactly that false diagnosis anyway. The NUL
+    byte is the complete signal and is checked first: no plausible markdown
+    adapter contains one, and every UTF-16/32 encoding of ASCII is full of
+    them. A file this gate cannot read gets an encoding diagnostic and exit 2,
+    the same policy the ADR-0020 validators' read_text() uses.
+
+    A file that exists but cannot be read at all is neither a pass nor a FAIL —
+    nothing was graded — so it exits 3 rather than 1. Exit 1 sends the skill's
+    closeout into "fix the FAIL by editing the provider file", which for a file
+    it cannot open is an instruction to edit blind.
+    """
+    try:
+        with open(path, "rb") as fh:
+            raw = fh.read()
+    except OSError as exc:
+        print(f"Error: '{path}' exists but could not be read ({exc.strerror}). "
+              "Nothing was checked — fix whatever is blocking the read "
+              "(permissions, ownership, the underlying device) and re-run; do "
+              "not edit the adapter on the strength of this.", file=sys.stderr)
+        sys.exit(EXIT_UNREADABLE)
+    if b"\x00" in raw:
+        print(f"Error: '{path}' is not valid UTF-8 — it contains NUL bytes, so "
+              "it is almost certainly UTF-16 or UTF-32 (with or without a BOM). "
+              "Re-save it as UTF-8; this check does not guess at other "
+              "encodings.", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        print(f"Error: '{path}' is not valid UTF-8 ({exc.reason} at byte "
+              f"{exc.start}) — re-save it as UTF-8; this check does not guess "
+              "at other encodings.", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    return text.replace("\ufeff", "")
+
+
+adapter_content = read_text(adapter_path)
+agents_md_content = read_text(agents_md_path)
+adapter_dir = os.path.dirname(os.path.abspath(adapter_path))
 
 has_fail = False
 
@@ -89,30 +245,229 @@ if not adapter_content.strip():
     print("      Why: An empty adapter carries no reference to AGENTS.md and no provider-specific content.")
     print("      Fix: Add at least an import (or text pointer) to AGENTS.md.")
     print()
-    sys.exit(1)
+    sys.exit(EXIT_FAIL)
 
-IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
+
-lines = adapter_content.splitlines()
+# --- Inert regions -----------------------------------------------------------
-import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
+#
+# A reference only counts where something would actually resolve it. Fenced
+# code blocks, indented code blocks and HTML comments are shown to the reader
+# (or hidden from them) as literal text; Claude Code resolves an @import in
+# none of them. Without this, a ```-fenced `@AGENTS.md` — the exact
+# copy-the-example-into-the-file mistake this gate exists to catch — exited 0
+# with the adapter deferring to nothing.
+#
+# Indented code blocks are handled by IMPORT_RE's `^ {0,3}` instead of by the
+# mask: four leading spaces is what opens an indented code block in CommonMark,
+# so an import has to sit within three. The mask deliberately does not apply
+# that rule to prose pointers, where four-space indentation is ordinary list
+# continuation rather than code.
+FENCE_RE = re.compile(r'^( {0,3})(`{3,}|~{3,})(.*)$')
+COMMENT_RE = re.compile(r'<!--.*?(?:-->|\Z)', re.DOTALL)
+
+
+def line_offsets(text):
+    """[(char offset, line without its terminator)] over `text`."""
+    out = []
+    off = 0
+    for raw in text.splitlines(keepends=True):
+        out.append((off, raw.rstrip("\r\n")))
+        off += len(raw)
+    return out
+
+
+def build_inert_mask(text, offsets):
+    """Per-character flags: 1 where a reference would never be resolved."""
+    mask = bytearray(len(text))
+    fence = None  # (fence char, opening run length)
+    for start, line in offsets:
+        m = FENCE_RE.match(line)
+        if fence is None:
+            if m:
+                fence = (m.group(2)[0], len(m.group(2)))
+                for i in range(start, start + len(line)):
+                    mask[i] = 1
+            continue
+        for i in range(start, start + len(line)):
+            mask[i] = 1
+        if (m and m.group(2)[0] == fence[0]
+                and len(m.group(2)) >= fence[1]
+                and not m.group(3).strip()):
+            fence = None
+    for m in COMMENT_RE.finditer(text):
+        if m.start() < len(mask) and mask[m.start()]:
+            continue  # a literal "<!--" printed inside a fence opens nothing
+        for i in range(m.start(), min(m.end(), len(mask))):
+            mask[i] = 1
+    return mask
+
+
+# --- Reference shapes --------------------------------------------------------
+#
+# `\S*AGENTS\.md` had no path-separator boundary, so `@NOTAGENTS.md` and
+# `@zzzAGENTS.md` counted as imports of AGENTS.md. The matched path must end in
+# AGENTS.md as a whole segment.
+IMPORT_RE = re.compile(r'^ {0,3}@(?P<path>\S+?)\s*$')
+# A mention in prose: an optional relative path, then AGENTS.md, with no
+# identifier character glued to the front (so NOTAGENTS.md does not match) and
+# nothing glued to the back.
+MENTION_RE = re.compile(r'(?<![0-9A-Za-z_.\-/])((?:[\w.\-~]+/)*AGENTS\.md)(?![0-9A-Za-z])')
+
+# A pointer has to read as a pointer. `"AGENTS.md" in ln` passed
+# "Do NOT read AGENTS.md; it is obsolete." and "We deleted AGENTS.md last
+# year." — both of which point the reader away from the file. Require a
+# deference cue in the naming sentence, and reject a negated one.
+DIRECTIVE_RE = re.compile(
+    r'\b(see|read|refer|refers|referring|consult|consults|follow|follows|'
+    r'defer|defers|deferring|described|documented|documents|covered|covers|'
+    r'found|listed|specified|defined|governed|per|use|uses|using|apply|obey|'
+    r'start|check|live|lives|contains|holds|carries|inherit|inherits|import|'
+    r'imports|conventions|instructions|guidelines|guidance|rules|standards|'
+    r'reference|setup)\b', re.I)
+NEGATION_RE = re.compile(
+    r"(\bnot\b|n't\b|\bnever\b|\bno longer\b|\bdeleted\b|\bremoved\b|"
+    r"\bobsolete\b|\bdeprecated\b|\bignore\b|\bignores\b|\bignoring\b|"
+    r"\bdisregard\b|\bsuperseded\b|\bgone\b|\bunused\b|\bstale\b)", re.I)
+SENTENCE_SPLIT_RE = re.compile(r'(?<=[.;:!?])\s+')
+
+
+def sentence_around(line, index):
+    """(sentence of `line` containing character `index`, its start offset)."""
+    bounds = [0]
+    for m in SENTENCE_SPLIT_RE.finditer(line):
+        bounds.append(m.end())
+    bounds.append(len(line) + 1)
+    for i in range(len(bounds) - 1):
+        if bounds[i] <= index < bounds[i + 1]:
+            return line[bounds[i]:bounds[i + 1]], bounds[i]
+    return line, 0
+
+
+def reads_as_pointer(line, match):
+    """Does the sentence naming AGENTS.md actually point the reader at it?
+
+    The matched path is blanked out before the cues are applied. It is a
+    filename, not prose, and leaving it in let its own characters vote: the
+    perfectly ordinary `docs/does/not/exist/AGENTS.md` tripped the negation
+    cue on the `not` path segment, so a pointer got rejected for the wrong
+    reason and the near-miss line then reported the wrong diagnosis.
+    """
+    sentence, sentence_start = sentence_around(line, match.start())
+    rel_start = match.start() - sentence_start
+    rel_end = match.end() - sentence_start
+    probe = sentence[:rel_start] + " AGENTS.md " + sentence[rel_end:]
+    if NEGATION_RE.search(probe):
+        return False
+    return bool(DIRECTIVE_RE.search(probe))
+
+
+def resolve(raw_path):
+    """An import/pointer path resolved the way the provider would resolve it."""
+    p = os.path.expanduser(raw_path)
+    if not os.path.isabs(p):
+        p = os.path.join(adapter_dir, p)
+    return os.path.normpath(p)
+
+
+def target_problem(raw_path):
+    """None if `raw_path` names a real, non-empty file; else why not."""
+    resolved = resolve(raw_path)
+    if not os.path.isfile(resolved):
+        return f"'{raw_path}' resolves to {resolved}, which does not exist"
+    try:
+        if os.path.getsize(resolved) == 0:
+            return f"'{raw_path}' resolves to {resolved}, which is empty"
+        with open(resolved, "rb") as fh:
+            if not fh.read().strip():
+                return f"'{raw_path}' resolves to {resolved}, which is blank"
+    except OSError as exc:
+        return f"'{raw_path}' resolves to {resolved}, which cannot be read ({exc.strerror})"
+    return None
+
+
+def names_agents_md(path):
+    return path == "AGENTS.md" or path.endswith("/AGENTS.md")
+
+
+offsets = line_offsets(adapter_content)
+lines = [line for _, line in offsets]
+mask = build_inert_mask(adapter_content, offsets)
+
+
+def is_inert(abs_index):
+    return abs_index < len(mask) and bool(mask[abs_index])
+
+
+# Lines shaped like an @AGENTS.md import, whether or not the target resolves.
+# Used to exclude them from the duplication denominator and from the prose
+# pointer scan, both of which only care about the shape.
+import_shaped_lines = set()
+# (line, raw path) for every import whose target actually resolves.
+live_imports = []
+# Diagnostics for imports that are the right shape but resolve to nothing.
+dead_imports = []
+# Imports that exist only inside a fence or an HTML comment.
+inert_imports = []
+
+for start, line in offsets:
+    m = IMPORT_RE.match(line)
+    if not m or not names_agents_md(m.group("path")):
+        continue
+    at_index = start + line.index("@")
+    if is_inert(at_index):
+        inert_imports.append(line.strip())
+        continue
+    import_shaped_lines.add(line)
+    problem = target_problem(m.group("path"))
+    if problem:
+        dead_imports.append(problem)
+    else:
+        live_imports.append(line)
+
+live_pointers = []
+dead_pointers = []
+inert_pointers = []
+mention_only = []
+
+for start, line in offsets:
+    if line in import_shaped_lines:
+        continue
+    for m in MENTION_RE.finditer(line):
+        if is_inert(start + m.start()):
+            inert_pointers.append(line.strip())
+            continue
+        if not reads_as_pointer(line, m):
+            mention_only.append(sentence_around(line, m.start())[0].strip())
+            continue
+        problem = target_problem(m.group(1))
+        if problem:
+            dead_pointers.append(problem)
+        else:
+            live_pointers.append(line)
 
 if no_import_syntax:
-    has_reference = "AGENTS.md" in adapter_content
+    has_reference = bool(live_pointers)
+    near_misses = dead_pointers + [f"{d} (inside a code fence or HTML comment)" for d in inert_pointers]
+    near_misses += [f"'{s}' names AGENTS.md but does not point at it" for s in mention_only]
 else:
-    has_reference = bool(import_lines) or "AGENTS.md" in adapter_content
+    has_reference = bool(live_imports)
+    near_misses = dead_imports + [f"'{d}' is inside a code fence or HTML comment, where no import is resolved" for d in inert_imports]
 
 if not has_reference:
     has_fail = True
     print(f"FAIL  Adapter has no reference to AGENTS.md — {adapter_path}")
     if no_import_syntax:
-        print("      Why: This provider has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.")
+        print("      Why: This provider resolves no cross-file import, so the adapter must point at AGENTS.md in prose; an `@AGENTS.md` line here is inert text. The pointer has to read as a pointer and name a file that is really there — a bare or negated mention (\"we deleted AGENTS.md\") defers nothing, and neither does a mention buried in a code fence or an HTML comment.")
-        print("      Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
+        print("      Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\", outside any fence, naming a path that exists relative to this file.")
     else:
-        print("      Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.")
+        print("      Why: A thin adapter must import AGENTS.md with an `@AGENTS.md` line of its own, indented no more than three spaces, and the path must resolve to a real non-empty file. Naming the file mid-sentence or inside backticks is prose this check will not credit; putting the line inside a ``` fence, an indented code block, or an HTML comment is worse, because nothing resolves it and it looks right.")
-        print("      Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.")
+        print("      Fix: Put `@AGENTS.md` (or the equivalent relative path) alone on its own line at the top level of the file, or pass --no-import-syntax if this provider resolves no imports.")
+    for miss in near_misses:
+        print(f"      Near miss: {miss}")
     print()
 
 # --- Duplication check ---
-non_import_lines = [ln for ln in lines if not IMPORT_RE.match(ln)]
+non_import_lines = [ln for ln in lines if ln not in import_shaped_lines]
 adapter_lines = [ln.strip() for ln in non_import_lines if ln.strip()]
 agents_lines = {ln.strip() for ln in agents_md_content.splitlines() if ln.strip()}
 
@@ -132,10 +487,10 @@ if non_blank_count > max_lines:
     has_fail = True
     print(f"FAIL  Adapter is not thin — {adapter_path}")
     print(f"      Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
-    print("      Fix: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.")
+    print("      Fix: Delete the lines already covered by AGENTS.md; keep only genuinely provider-specific additions here.")
     print()
 
 if has_fail:
-    sys.exit(1)
+    sys.exit(EXIT_FAIL)
 sys.exit(0)
 PYTHON

plugins/core/.apm/skills/provider-adapter-author/tests/validate-adapter.bats

@@ -115,6 +115,51 @@ EOF
     assert_output --partial "no reference"
 }
 
+@test "the two --no-import-syntax branches disagree: a text-pointer-only adapter fails in default mode" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+See AGENTS.md at the repo root for setup, style, and testing conventions.
+
+## Copilot-specific
+Prefer inline suggestions over chat for one-line edits.
+EOF
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure
+    assert_output --partial "no reference"
+
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+@test "with --no-import-syntax, an inert @AGENTS.md line alone is not a prose pointer" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+@AGENTS.md
+
+## Copilot-specific
+Prefer inline suggestions over chat for one-line edits.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure
+    assert_output --partial "no reference"
+}
+
+@test "--max-lines as the final argument reports a real error instead of failing silently" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD" --max-lines
+    assert_failure 2
+    assert_output --partial "--max-lines requires a value"
+}
+
+@test "--max-lines rejects a non-numeric value with a real error" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" --max-lines abc "$ADAPTER" "$AGENTS_MD"
+    assert_failure 2
+    assert_output --partial "non-negative integer"
+}
+
 @test "--help exits 0 and documents usage" {
     run bash "$SCRIPT" --help
     assert_success
@@ -123,6 +168,352 @@ EOF
 
 @test "fails with a clear error when the adapter file argument is missing" {
     run bash "$SCRIPT"
-    assert_failure
+    assert_failure 2
     assert_output --partial "required"
 }
+
+@test "a UTF-8 BOM before the @import line does not hide it" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    python3 -c "import sys; open(sys.argv[1], 'w', encoding='utf-8-sig').write('@AGENTS.md\n')" "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+@test "a usage error exits 2, a genuine finding exits 1" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+
+    run bash "$SCRIPT" --max-lines -3 "$ADAPTER" "$AGENTS_MD"
+    assert_failure 2
+    refute_output --partial "FAIL"
+
+    : > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "FAIL"
+}
+
+@test "a non-UTF-8 adapter is reported as an encoding error, not as a missing reference" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write('@AGENTS.md\n'.encode('utf-16'))" "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 2
+    assert_output --partial "not valid UTF-8"
+    refute_output --partial "no reference"
+}
+
+@test "an @AGENTS.md folded into a sentence fails, and the message says the import needs its own line" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    cat > "$ADAPTER" <<'EOF'
+See @AGENTS.md for shared conventions.
+EOF
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+    assert_output --partial "line of its own"
+}
+
+# --- Q1: a reference only counts where something would resolve it -------------
+
+@test "an @AGENTS.md inside a backtick code fence is not credited as an import" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    cat > "$ADAPTER" <<'EOF'
+# Claude notes
+
+Put this at the top of the file:
+
+```
+@AGENTS.md
+```
+EOF
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "an @AGENTS.md inside a tilde code fence is not credited as an import" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    cat > "$ADAPTER" <<'EOF'
+~~~
+@AGENTS.md
+~~~
+EOF
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "an @AGENTS.md in a four-space indented code block is not credited as an import" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    cat > "$ADAPTER" <<'EOF'
+# Claude notes
+
+    @AGENTS.md
+EOF
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "an @AGENTS.md inside a multi-line HTML comment is not credited as an import" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    cat > "$ADAPTER" <<'EOF'
+# Claude notes
+
+<!--
+@AGENTS.md
+-->
+EOF
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "an @AGENTS.md indented up to three spaces is still credited" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    printf '   @AGENTS.md\n' > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+# --- Q2: encodings that decode as valid UTF-8 but are not UTF-8 ---------------
+
+@test "a BOM-less UTF-16LE adapter is an encoding error, not a missing reference" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write('@AGENTS.md\n'.encode('utf-16-le'))" "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 2
+    assert_output --partial "not valid UTF-8"
+    refute_output --partial "no reference"
+}
+
+@test "a BOM-less UTF-32LE adapter is an encoding error, not a missing reference" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write('@AGENTS.md\n'.encode('utf-32-le'))" "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 2
+    assert_output --partial "not valid UTF-8"
+    refute_output --partial "no reference"
+}
+
+@test "a doubled UTF-8 BOM does not hide the @import line" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write(('@AGENTS.md\n').encode('utf-8'))" "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+@test "a BOM in front of a mid-file @import line does not hide it" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    python3 -c "import sys; open(sys.argv[1], 'wb').write(('# Claude notes\n\n@AGENTS.md\n').encode('utf-8'))" "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+# --- Q3: a file that exists but cannot be read is not a FAIL -----------------
+
+@test "an adapter that exists but cannot be read exits 3 with a diagnostic and no FAIL" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+    chmod 000 "$ADAPTER"
+    # chmod is not enough under a uid that bypasses it (root in CI containers).
+    # /proc/self/mem is a regular file whose read returns EIO for every uid, so
+    # it exercises the same branch where chmod cannot.
+    if cat "$ADAPTER" >/dev/null 2>&1; then
+        if [ -e /proc/self/mem ]; then
+            ADAPTER=/proc/self/mem
+        else
+            chmod 644 "$TMPDIR/CLAUDE.md"
+            skip "no way to make a readable-by-stat, unreadable-by-open file here"
+        fi
+    fi
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    chmod 644 "$TMPDIR/CLAUDE.md"
+    assert_failure 3
+    assert_output --partial "could not be read"
+    refute_output --partial "FAIL"
+}
+
+# --- Q4: the reference has to name, and resolve to, a real AGENTS.md ---------
+
+@test "an @import naming a path that does not exist is not credited" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@docs/does/not/exist/AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+    assert_output --partial "does not exist"
+}
+
+@test "@NOTAGENTS.md and @zzzAGENTS.md are not imports of AGENTS.md" {
+    # The decoys are real files, so the on-disk resolution check cannot be what
+    # rejects them. Only the path-segment boundary can — without the fixtures
+    # this test passes against a substring match and proves nothing.
+    cp "$AGENTS_MD" "$TMPDIR/NOTAGENTS.md"
+    cp "$AGENTS_MD" "$TMPDIR/zzzAGENTS.md"
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@NOTAGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+
+    echo "@zzzAGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "an @import resolving to a zero-byte AGENTS.md is not credited" {
+    SUB="$TMPDIR/empty"
+    mkdir -p "$SUB"
+    : > "$SUB/AGENTS.md"
+    ADAPTER="$SUB/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+    assert_output --partial "empty"
+}
+
+@test "an @import naming a real relative path to AGENTS.md is credited" {
+    mkdir -p "$TMPDIR/docs"
+    cp "$AGENTS_MD" "$TMPDIR/docs/AGENTS.md"
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@docs/AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+# --- Q5: --no-import-syntax needs a pointer, not a mention -------------------
+
+@test "with --no-import-syntax, a negated mention of AGENTS.md is not a pointer" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+Do NOT read AGENTS.md; it is obsolete.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "with --no-import-syntax, a past-tense mention of a deleted AGENTS.md is not a pointer" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+We deleted AGENTS.md last year.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "with --no-import-syntax, a pointer inside a code fence is not credited" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+Example of what to write:
+
+```
+See AGENTS.md at the repo root for shared conventions.
+```
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "with --no-import-syntax, a pointer inside an HTML comment is not credited" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+# Copilot instructions
+
+<!-- See AGENTS.md at the repo root for shared conventions. -->
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "with --no-import-syntax, a name merely ending in AGENTS.md is not a pointer to it" {
+    # Real decoy files, so the on-disk resolution check cannot be what rejects
+    # these — only the token boundary in the mention pattern can. zzzAGENTS.md
+    # is the load-bearing case: dropping the boundary from NOTAGENTS.md leaves
+    # the fragment "NOT" behind, which the negation cue then rejects for an
+    # unrelated reason, so that case alone would prove nothing.
+    cp "$AGENTS_MD" "$TMPDIR/zzzAGENTS.md"
+    cp "$AGENTS_MD" "$TMPDIR/NOTAGENTS.md"
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+See zzzAGENTS.md at the repo root for shared conventions.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+
+    cat > "$ADAPTER" <<'EOF'
+See NOTAGENTS.md at the repo root for shared conventions.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}
+
+@test "with --no-import-syntax, a pointer naming a path that does not exist is not credited" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+See docs/does/not/exist/AGENTS.md for shared conventions.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+    assert_output --partial "does not exist"
+}
+
+# --- argument handling -------------------------------------------------------
+
+@test "a third positional argument is rejected instead of silently ignored" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD" "$TMPDIR/also-not-graded.md"
+    assert_failure 2
+    assert_output --partial "exactly 2 positional arguments"
+    # The usage text this prints mentions the word FAIL, so refute the shape of
+    # a real finding line rather than the bare word.
+    refute_output --partial "FAIL  Adapter"
+}
+
+@test "an unknown option is reported as an unknown option, not as a missing file" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    echo "@AGENTS.md" > "$ADAPTER"
+    run bash "$SCRIPT" --bogus "$ADAPTER" "$AGENTS_MD"
+    assert_failure 2
+    assert_output --partial "unknown option '--bogus'"
+    refute_output --partial "'--bogus' is not a file"
+    refute_output --partial "FAIL  Adapter"
+}
+
+@test "--max-lines=N is accepted in the equals form" {
+    ADAPTER="$TMPDIR/CLAUDE.md"
+    {
+        echo "@AGENTS.md"
+        for i in $(seq 1 10); do echo "Provider-specific line $i unrelated to AGENTS.md content."; done
+    } > "$ADAPTER"
+    run bash "$SCRIPT" --max-lines=5 "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "thin"
+
+    run bash "$SCRIPT" --max-lines=40 "$ADAPTER" "$AGENTS_MD"
+    assert_success
+}
+
+@test "with --no-import-syntax, a bare mention with no deference cue is not a pointer" {
+    ADAPTER="$TMPDIR/copilot-instructions.md"
+    cat > "$ADAPTER" <<'EOF'
+# Copilot instructions
+
+This repo also has an AGENTS.md.
+
+Prefer inline suggestions over chat for one-line edits.
+EOF
+    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
+    assert_failure 1
+    assert_output --partial "no reference"
+}

plugins/core/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "core",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
   "author": {
     "name": "Defame1297",

plugins/core/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "core",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
   "author": {
     "name": "Defame1297",

plugins/core/apm.yml

@@ -1,5 +1,5 @@
 name: core
-version: 1.1.1
+version: 1.1.2
 description: Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
 author:
   name: Defame1297

plugins/core/skills/agentsmd-audit/README.md

@@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any
 
 Provide the path to the repo root to audit when invoking.
 
+Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a
+hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit.
+
 ## Files
 
 | File | Purpose |
@@ -30,6 +33,6 @@ Provide the path to the repo root to audit when invoking.
 | `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
 
 Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
-not present in an installed plugin: `scripts/sync-plugin-content.sh` strips `<category>/<name>/tests`
+not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
-when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to
+`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
-discover (ADR-0017). Run them from a repo checkout, not from an install.
+plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/core/skills/agentsmd-audit/SKILL.md

@@ -1,20 +1,11 @@
 ---
 name: agentsmd-audit
 description: >
-  Use when the user wants to review a repo's AGENTS.md file, says "audit this
+  Use when the user wants a repo's AGENTS.md audited for secrets, structure
-  AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to
+  and drift — "is this AGENTS.md safe to commit" — or after a hand-edit
-  know if AGENTS.md is safe to commit — even if they don't use the word
+  outside `agentsmd-author`.
-  "audit". Also invoke proactively after agentsmd-author creates or updates
+  Not converting a provider file -> `provider-adapter-author`.
-  AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a
+  Not writing AGENTS.md -> `agentsmd-author`.
-  target repo's AGENTS.md file(s) — root and any nested monorepo files — for
-  embedded secrets/credentials, structural completeness against the
-  agents.md common-sections checklist, and drift (referenced commands or
-  paths that no longer resolve against the repo). Produces a compact
-  findings report (findings only, no PASS noise) with Why and Fix per
-  finding. Do not use to audit CLAUDE.md, .cursor/rules, or other
-  provider-specific adapter files — that's provider-adapter-author's
-  self-contained concern. Do not use to fix or write AGENTS.md content — use
-  agentsmd-author instead.
 allowed-tools: Bash Read
 metadata:
   category: docs
@@ -23,14 +14,13 @@ metadata:
     - context7-websites-agents-md
     - context7-agentsmd-agents-md
     - governance-secrets-hard-prohibition
-  version: "0.1.1"
+  version: "0.1.2"
 ---
 
 ## Gotchas
 
 - Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found.
-- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's.
+- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
-- A missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
 - Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report.
 
 ## Step 1 — Run the validators
@@ -41,7 +31,7 @@ bash scripts/validate-structure.sh <repo-root>
 bash scripts/validate-drift.sh <repo-root>
 ```
 
-Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand.
+Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL` lines, plus `INFO`/`SUGGESTION` where applicable, with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference.
 
 ## Step 2 — Report
 
@@ -53,16 +43,4 @@ Checked: secrets · structure · drift
 
 Then output only findings that were found, in this order within a repo: `### Secrets`, `### Structure`, `### Drift`. Omit a dimension heading entirely if it produced nothing — its absence confirms it passed. Report each finding verbatim as emitted by the scripts (they already carry file:line, Why/Fix or Note).
 
-Close with a result block:
+Close with a `## Result` block holding one line: `PASS`, `PASS (N suggestions)`, or `FAIL (N fails · M suggestions)`, each optionally followed by ` · P info`. Omit the suggestion count when there are none, and omit `· P info` when there are none. INFO and SUGGESTION findings are observational — they never flip PASS to FAIL. Do not fix anything — this skill reports and proposes only. Point the user to `agentsmd-author` to apply fixes.
-
-```text
-## Result
-
-PASS
-PASS · P info
-PASS (N suggestions) · P info
-FAIL (N fails)
-FAIL (N fails) · P info
-```
-
-INFO and SUGGESTION findings are observational — they never flip PASS to FAIL. Do not fix anything — this skill reports and proposes only. Point the user to `agentsmd-author` to apply fixes.

plugins/core/skills/agentsmd-author/SKILL.md

@@ -1,20 +1,10 @@
 ---
 name: agentsmd-author
 description: >
-  Use when the user wants to create or update a repo's AGENTS.md file
+  Use when the user wants a repo's AGENTS.md written or updated, root or
-  ("write an AGENTS.md for this repo", "add setup/test instructions for
+  nested, including "document this for AI coding tools". Writes only verified
-  agents", "update AGENTS.md", "give this package its own AGENTS.md") — even
+  conventions. Not review-only -> `agentsmd-audit`. Not converting CLAUDE.md ->
-  if they don't name the file explicitly, e.g. "document this for AI coding
+  `provider-adapter-author`.
-  tools" or "make sure agents know how to run tests here". Writes/updates
-  AGENTS.md by exploring the target repo for real build, test, lint, and
-  style conventions — never invents commands. Supports nested monorepo
-  placement (a subdirectory can get its own AGENTS.md following
-  nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
-  inline, and calls provider-adapter-author when an existing provider file
-  (CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
-  an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
-  not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
-  provider-adapter-author instead.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: docs
@@ -22,16 +12,13 @@ metadata:
     - agents-md-official
     - context7-websites-agents-md
     - context7-agentsmd-agents-md
-  version: "0.1.1"
+  version: "0.1.2"
 ---
 
 ## Gotchas
 
 - Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
-- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one.
+- Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
-- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
-- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
-- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
 
 ## Step 1 — Explore the target repo
 
@@ -40,17 +27,17 @@ Before writing anything, gather real facts: package manager and scripts (`packag
 ## Step 2 — Decide placement
 
 - No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions.
-- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Don't repeat root-level content — the nearest-file-wins rule means the nested file is read alone, not merged with the root.
+- A subdirectory has materially different build/test tooling or conventions than the root → create or update a nested `AGENTS.md` there, scoped to what's different. Convenience is not a reason to create one — without a distinct stack you are duplicating content the root already covers. **Don't repeat root-level content** in a nested file: the nearest-file-wins rule means it is read alone, never merged back with the root.
 - Otherwise → update the existing file(s) in place.
 
 ## Step 3 — Write or update
 
-Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
+AGENTS.md has no required schema. Use only sections that reflect something real about the repo — never fill in every common-sections-checklist heading just because it exists, because a thin accurate file beats a padded generic one. Read `references/content-guide.md` for section-by-section guidance, a worked example, and what separates useful content from generic padding, before writing.
 
 ## Step 4 — Check for an existing provider file
 
-Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists and now duplicates content the AGENTS.md you just wrote/updated already owns, invoke the `provider-adapter-author` skill on it to reconcile — don't rewrite it yourself.
+Look for `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, or similar in the target repo. If one exists, invoke the `provider-adapter-author` skill on it to reconcile — whether it duplicates content the AGENTS.md you just wrote/updated now owns, or is merely stale or missing a pointer to it. Never edit it yourself in either case.
 
 ## Step 5 — Audit and report
 
-Invoke the `agentsmd-audit` skill directly on the AGENTS.md file(s) you just wrote or updated. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.
+Invoke the `agentsmd-audit` skill on the target repo root — its validators take a `<repo-root>` and walk the tree for every AGENTS.md themselves; there is no per-file entry point. This closeout is mandatory, not optional, even when the change looks trivial — never sign the work off on your own judgment. Resolve any FAIL findings before considering the work done — re-invoke this skill's own writing steps to fix them, then re-run the audit, same as any other close-the-loop check. Report what was created/changed, whether a provider file was reconciled, and the audit's final result.

plugins/core/skills/provider-adapter-author/README.md

@@ -23,6 +23,7 @@ Provide the path to the provider-specific file to convert (and the target repo r
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/provider-matrix.md` | Loaded at Step 1 before searching, unless the target is already a known root `CLAUDE.md`: known files per provider, which ones resolve a cross-file import, the validator flag each needs, and the rule that a standalone run and a run composed into by `agentsmd-author` behave identically |
 | `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
 | `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
 | `scripts/README.md` | Directory documentation for `scripts/` |
@@ -30,6 +31,6 @@ Provide the path to the provider-specific file to convert (and the target repo r
 | `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
 
 Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
-but are not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
+but are not present in an installed plugin: the repo's `scripts/sync-plugin-content.sh` strips
 `<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
 plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

plugins/core/skills/provider-adapter-author/SKILL.md

@@ -1,43 +1,41 @@
 ---
 name: provider-adapter-author
 description: >
-  Use when the user wants to convert a provider-specific AI instruction file
+  Use when a provider file (CLAUDE.md, .cursor rules, copilot-instructions)
-  (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) into a
+  duplicating the repo's AGENTS.md should be cut to a thin adapter — "make
-  thin adapter that defers to a repo's AGENTS.md — e.g. "reduce duplication
+  CLAUDE.md just import AGENTS.md".
-  between CLAUDE.md and AGENTS.md", "make CLAUDE.md just import AGENTS.md"
+  Not writing the AGENTS file -> `agentsmd-author`.
-  — even if the pattern isn't named explicitly. Also invoke when
+  Not auditing the AGENTS file -> `agentsmd-audit`.
-  agentsmd-author detects an existing provider file overlapping with
-  AGENTS.md it just wrote. Detects redundant content in a provider file
-  relative to AGENTS.md and rewrites it down to a minimal reference (an
-  `@AGENTS.md`-style import where supported, or a text pointer otherwise)
-  plus genuinely provider-specific additions. Self-validates via a bundled
-  deterministic script before finishing. Do not use to write or audit
-  AGENTS.md itself — use agentsmd-author or agentsmd-audit.
 allowed-tools: Bash Read Edit Write
 metadata:
   category: docs
   source_keys:
     - adr-0002-0003-two-tier-claude-md
-  version: "0.1.0"
+  version: "0.1.1"
 ---
 
 ## Gotchas
 
-- Not every provider supports cross-file imports. Claude Code does — a `CLAUDE.md` can consist of nothing but one or more `@path` lines (e.g. `@AGENTS.md`), with no other content required. Cursor's `.cursor/rules/*.mdc` and GitHub Copilot's `copilot-instructions.md` have no native import mechanism as of current tooling — for those, "thin" means a short text pointer to AGENTS.md plus only what that tool actually needs, not a literal import line. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for these providers.
+- Assume a provider has no cross-file import mechanism until you have confirmed it has one. Claude Code is the exception, not the rule: a `CLAUDE.md` may consist of nothing but `@path` lines, while the same `@AGENTS.md` line in a Cursor rule or a Copilot instructions file is inert text no tool resolves. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for those providers.
-- This skill never creates or edits `AGENTS.md` itself. If the target repo has no `AGENTS.md` yet, stop and point the user to `agentsmd-author` first — there's nothing to adapt to.
+
-- Only strip content from the provider file that's genuinely redundant with AGENTS.md. Provider-specific material (IDE settings, tool-only syntax, model-specific instructions) stays — the goal is thin, not empty.
+- Works standalone or composed-into by `agentsmd-author` — behave identically either way; do not assume a caller skill exists. Detect the provider file, confirm `AGENTS.md`, and run the closeout validator yourself in both cases (`references/provider-matrix.md`).
-- Works standalone or composed-into by `agentsmd-author` — behave identically either way; don't assume a caller skill exists.
 
 ## Step 1 — Detect
 
-Look for known provider instruction files in the target repo: `CLAUDE.md` (repo root, and any deployed copies), `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and similar tool-specific files. Confirm `AGENTS.md` exists at the repo root — if not, stop and tell the user to run `agentsmd-author` first.
+Find the provider instruction file to convert. Before searching, read `references/provider-matrix.md` — skip it only when the target is already a known root `CLAUDE.md`, which is the common case.
+
+Then confirm `AGENTS.md` exists at the repo root. If it does not, stop and tell the user to run `agentsmd-author` first — there is nothing to adapt to.
 
 ## Step 2 — Diff and rewrite
 
 Read the provider file and `AGENTS.md` side by side. Separate the provider file's content into two buckets: lines that restate what `AGENTS.md` already owns (universal rules, conventions, project overview) versus lines that are genuinely provider-specific (tool syntax, IDE behavior, model-specific instructions). Rewrite the provider file:
 
-- **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import line, keep the provider-specific bucket below it.
+- **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import on a line of its own, keep the provider-specific bucket below it. An import folded into a sentence is not the thin-adapter shape and `scripts/validate-adapter.sh` will not credit it — nor one inside a code fence, an indented block, or an HTML comment, nor one whose path does not resolve to a real, non-empty file on disk.
-- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short pointer sentence mentioning `AGENTS.md`, keep the provider-specific bucket.
+- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short sentence pointing at `AGENTS.md` ("See AGENTS.md at the repo root for ..."), keep the provider-specific bucket. A bare or negated mention is not a pointer and will not be credited.
+
+The provider file is the only file this skill ever writes. Never create or edit `AGENTS.md` — not in this step, not in any step, whatever the payoff looks like.
+
+Strip only what is genuinely redundant. Provider-specific material stays even when it is short — the goal is thin, not empty.
 
 ## Step 3 — Self-validate
 
@@ -47,7 +45,7 @@ Run the bundled check before finishing — this is the skill's own closeout gate
 bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
 ```
 
-Fix any `FAIL` and re-run until it exits `0`.
+Fix any `FAIL` by editing the provider file, and re-run until it exits `0`. Exits `2` and `3` are not `FAIL`s and nothing was graded under either, so neither is a reason to touch the adapter: `2` means the invocation or the input is wrong (a bad, missing, or extra argument, an unknown option, or a file that is not UTF-8), and `3` means a named file exists but could not be read.
 
 ## Step 4 — Report
 

plugins/core/skills/provider-adapter-author/references/provider-matrix.md

@@ -0,0 +1,32 @@
+---
+source_keys:
+  - adr-0002-0003-two-tier-claude-md
+---
+
+# Known provider instruction files
+
+Which files to look for when detecting a provider-specific instruction file, whether each provider
+resolves a cross-file import, and what a thin adapter therefore looks like for it.
+
+| Provider | File(s) | Import syntax | Thin adapter shape | Validator flag |
+|---|---|---|---|---|
+| Claude Code | `CLAUDE.md` at the repo root, plus any deployed copies | Yes — `@path` lines, e.g. `@AGENTS.md` | One or more `@` import lines; no other content is required | none |
+| Cursor | `.cursor/rules/*.mdc` | No | A short sentence pointing at `AGENTS.md`, plus the rule's own frontmatter and provider-specific body | `--no-import-syntax` |
+| GitHub Copilot | `.github/copilot-instructions.md` | No | A short sentence pointing at `AGENTS.md`, plus Copilot-only instructions | `--no-import-syntax` |
+| Anything else | tool-specific instruction file at whatever path the tool documents | Assume no | Text pointer, as above | `--no-import-syntax` |
+
+A provider not listed here is not evidence it has an import mechanism. Confirm against that tool's
+own documentation before emitting an `@`-style line; an unresolved import reads as literal text and
+silently drops every rule the adapter was supposed to defer to.
+
+Detection is a search, not a lookup: a repo may hold more than one of these, and each one converts
+independently against the same `AGENTS.md`.
+
+## Standalone and composed runs behave identically
+
+This skill is reached two ways: invoked directly by a user, and composed into by `agentsmd-author`
+once it has written or updated the repo's `AGENTS.md`. Behave identically either way — do not
+assume a caller skill exists. Detect the provider file yourself, confirm `AGENTS.md` yourself, and
+run the closeout validator yourself, rather than treating any step as already done by the caller or
+as something the caller will do afterwards. No handshake exists to rely on, and no state is
+passed in beyond the file paths.

plugins/core/skills/provider-adapter-author/references/sources.md

@@ -5,5 +5,5 @@
 - **URL:** (in-repo precedent — not an external source or plugin research corpus entry)
 - **Description:** This repo's own two-tier CLAUDE.md/AGENTS.md pattern: AGENTS.md is the provider-agnostic source of always-on rules; provider-specific files (CLAUDE.md) become thin adapters that import it (`@AGENTS.md` plus provider-specific additions). Grounds this skill's entire adapter-conversion design — the "thin adapter" shape, the `@`-import convention, and the size/duplication expectations enforced by `scripts/validate-adapter.sh`.
 - **Research doc:** docs/adr/0002-two-tier-claude-md.md, docs/adr/0003-agents-md-provider-agnostic-entry-point.md, providers/claude-code/CLAUDE.md (in-repo ADRs and a live example, not a plugin research corpus entry; referenced here since this skill's design is modeled directly on an existing implementation rather than external research)
-- **Contributing files:** SKILL.md
+- **Contributing files:** SKILL.md, references/provider-matrix.md
 - **Status:** `extracted`

plugins/core/skills/provider-adapter-author/scripts/README.md

@@ -4,6 +4,25 @@ Deterministic self-check this skill shells out to instead of relying on LLM judg
 
 | File | Purpose |
 |------|---------|
-| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
+| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a working reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
 
-Takes `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags. Prints `FAIL` findings to stdout and exits non-zero on any failure.
+Takes exactly `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags (also accepted as `--max-lines=N`). A third positional argument or an unknown option is an error, not something quietly ignored.
+
+## What counts as a reference to AGENTS.md
+
+Both modes require the named path to be a real path segment ending in `AGENTS.md` — `AGENTS.md` or `…/AGENTS.md`, not `NOTAGENTS.md` — that resolves on disk, relative to the adapter file, to a non-empty file. An adapter deferring to a path that is not there defers to nothing, so the check has to touch the disk rather than pattern-match the line.
+
+A reference only counts where something would actually resolve it. A line inside a fenced code block, an indented code block, or an HTML comment is not credited in either mode: Claude Code resolves an import in none of those, so a fenced `@AGENTS.md` is the silent-drop failure this gate exists to catch, not a pass.
+
+Default mode wants a real import: `@AGENTS.md` alone on its own line, indented no more than three spaces. `--no-import-syntax` wants a prose pointer that reads as one — the sentence naming `AGENTS.md` must carry a deference cue (see, read, refer to, documented in, conventions, …) and must not be negated. `Do NOT read AGENTS.md; it is obsolete.` and `We deleted AGENTS.md last year.` name the file while pointing the reader away from it, and neither is a pointer.
+
+## Exit codes
+
+The distinction matters because the skill's closeout tells the agent to fix any non-zero exit by editing the provider file. That is right for exactly one of these.
+
+| Code | Meaning | What to do |
+|------|---------|------------|
+| `0` | Passes every check | Nothing |
+| `1` | One or more `FAIL` findings printed to stdout — empty adapter, no working reference to AGENTS.md, excessive duplication, or not thin | Edit the provider file |
+| `2` | Usage or input error: a bad, missing, or extra argument, an unknown option, a path that is not a file, or a file that is not UTF-8. Nothing was graded, so there is no `FAIL` line | Fix the invocation or the file's encoding — do not edit the adapter |
+| `3` | A named input file exists but could not be read (permissions, I/O error). Nothing was graded and the adapter's contents are unknown | Fix the file's readability — do not edit the adapter |

plugins/core/skills/provider-adapter-author/scripts/validate-adapter.sh

@@ -14,27 +14,85 @@ Arguments:
   adapter-file     Path to the provider-specific file to check.
   agents-md-file   Path to the AGENTS.md file it should defer to.
 
+  Exactly two positional arguments are accepted. Extra ones are rejected
+  rather than ignored: a third path silently graded nothing but the first
+  two, so a typo'd invocation passed against the wrong file.
+
 Options:
   --no-import-syntax  The target provider has no native cross-file import
-                       mechanism. Accept a plain-text pointer mention of
+                       mechanism. Require a plain-text pointer line naming
-                       "AGENTS.md" instead of requiring an @import-style line.
+                       "AGENTS.md" instead of an @import-style line; an
+                       @AGENTS.md line alone does not satisfy it, because
+                       such a provider never resolves it. Without this flag
+                       an actual @import line is required, and naming
+                       AGENTS.md in prose alone does not satisfy it.
   --max-lines N        Max non-blank lines allowed in the adapter file before
-                       it's considered no longer "thin". Default: 60.
+                       it's considered no longer "thin". Must be a
+                       non-negative integer. Default: 60.
   --help, -h           Show this help and exit 0.
+  --                   End of options; every later argument is positional.
+
+Both flags also accept the --flag=value form (--max-lines=40). An unknown
+option is reported as an unknown option, not as a missing file.
+
+What counts as a reference:
+
+  In both modes the named path must be a real path segment ending in
+  AGENTS.md ("AGENTS.md" or ".../AGENTS.md" — not NOTAGENTS.md), and it must
+  resolve on disk, relative to the adapter file, to a non-empty file. An
+  adapter deferring to a path that is not there defers to nothing.
+
+  A mention inside a fenced code block, an indented code block, or an HTML
+  comment is not credited in either mode. Nothing resolves those, so an
+  adapter whose only "import" is fenced silently defers to nothing.
+
+  With --no-import-syntax the pointer must read as a pointer: the sentence
+  naming AGENTS.md has to carry a deference cue (see, read, refer to,
+  documented in, conventions, ...) and must not be a negation ("do not read
+  AGENTS.md", "we deleted AGENTS.md"). A bare mention is not a pointer.
 
 Exit codes:
   0  Adapter file passes all checks
   1  One or more checks failed (empty file, no reference to AGENTS.md,
      excessive duplication, or file too long)
+  2  Usage or input error — a bad, missing, or extra argument, an unknown
+     option, a path that is not a file, or a file that is not UTF-8. Nothing
+     was graded, so there is no FAIL line and no adapter edit to make: fix
+     the invocation or the file's encoding and re-run. Kept distinct from 1
+     because the skill's own closeout tells the agent to fix every non-zero
+     exit by editing the provider file, which for a mistyped flag edits the
+     wrong file forever.
+  3  A named input file exists but could not be read (permissions, a
+     directory swapped in mid-run, I/O error). Also not a FAIL: nothing was
+     graded and the adapter's contents are unknown, so editing it is
+     guesswork. Fix the file's readability and re-run.
 EOF
 }
 
 NO_IMPORT_SYNTAX=0
 MAX_LINES=60
 ARGS=()
+END_OF_OPTS=0
+
+require_int() {
+  # $1 = the value to validate
+  if [[ ! "$1" =~ ^[0-9]+$ ]]; then
+    echo "Error: --max-lines expects a non-negative integer, got '$1'." >&2
+    exit 2
+  fi
+}
 
 while [[ $# -gt 0 ]]; do
+  if [[ $END_OF_OPTS -eq 1 ]]; then
+    ARGS+=("$1")
+    shift
+    continue
+  fi
   case "$1" in
+    --)
+      END_OF_OPTS=1
+      shift
+      ;;
     --help|-h)
       usage
       exit 0
@@ -43,10 +101,38 @@ while [[ $# -gt 0 ]]; do
       NO_IMPORT_SYNTAX=1
       shift
       ;;
+    --no-import-syntax=*)
+      echo "Error: --no-import-syntax is a flag and takes no value (got '$1')." >&2
+      exit 2
+      ;;
     --max-lines)
-      MAX_LINES="${2:-}"
+      if [[ $# -lt 2 ]]; then
+        echo "Error: --max-lines requires a value (a non-negative integer)." >&2
+        exit 2
+      fi
+      MAX_LINES="$2"
+      require_int "$MAX_LINES"
       shift 2
       ;;
+    --max-lines=*)
+      MAX_LINES="${1#--max-lines=}"
+      if [[ -z "$MAX_LINES" ]]; then
+        echo "Error: --max-lines requires a value (a non-negative integer)." >&2
+        exit 2
+      fi
+      require_int "$MAX_LINES"
+      shift
+      ;;
+    -*)
+      # Reported as an unknown option rather than falling through to the
+      # positional bucket, where it used to surface as "'--bogus' is not a
+      # file" — the right exit code attached to a diagnostic that sends the
+      # reader looking for a path they never typed.
+      echo "Error: unknown option '$1'." >&2
+      echo "" >&2
+      usage >&2
+      exit 2
+      ;;
     *)
       ARGS+=("$1")
       shift
@@ -58,7 +144,14 @@ if [[ ${#ARGS[@]} -lt 2 ]]; then
   echo "Error: adapter-file and agents-md-file are required." >&2
   echo "" >&2
   usage >&2
-  exit 1
+  exit 2
+fi
+
+if [[ ${#ARGS[@]} -gt 2 ]]; then
+  echo "Error: expected exactly 2 positional arguments (adapter-file and agents-md-file), got ${#ARGS[@]}: ${ARGS[*]}." >&2
+  echo "" >&2
+  usage >&2
+  exit 2
 fi
 
 python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
@@ -70,17 +163,80 @@ adapter_path, agents_md_path, no_import_syntax, max_lines = sys.argv[1:5]
 no_import_syntax = no_import_syntax == "1"
 max_lines = int(max_lines)
 
+EXIT_FAIL = 1
+EXIT_USAGE = 2
+EXIT_UNREADABLE = 3
+
 if not os.path.isfile(adapter_path):
     print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
-    sys.exit(1)
+    sys.exit(EXIT_USAGE)
 if not os.path.isfile(agents_md_path):
     print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
-    sys.exit(1)
+    sys.exit(EXIT_USAGE)
 
-with open(adapter_path, encoding="utf-8", errors="replace") as f:
+
-    adapter_content = f.read()
+def read_text(path):
-with open(agents_md_path, encoding="utf-8", errors="replace") as f:
+    r"""File contents as text, UTF-8, every BOM stripped.
-    agents_md_content = f.read()
+
+    The BOM strip is not cosmetic. IMPORT_RE anchors on `^ {0,3}@`, and a BOM
+    is not whitespace in Python, so a CLAUDE.md saved by an editor that emits
+    one had its first line — the `@AGENTS.md` import, which is the whole
+    adapter — silently treated as prose. The check then said "no reference to
+    AGENTS.md" and told the author to add the line already sitting in front of
+    them. Same class of silent BOM miss recorded in scripts/skill-size-check.sh;
+    strip it at the reader so no later check has to know about it.
+
+    Every U+FEFF goes, not just one at offset 0. Stripping exactly the first
+    one left the mirror-image false FAIL for a doubled BOM (two concatenated
+    files, or a tool that re-adds one) and for a BOM mid-file at the head of
+    the import line. U+FEFF has no meaning as a character in a markdown
+    instruction file, so removing all of them cannot lose signal.
+
+    Decoding is strict, not errors="replace". Replacement mangles the file and
+    the checks then grade the mangling: a UTF-16 adapter whose first line is
+    `@AGENTS.md` decoded to interleaved NULs and failed as "no reference",
+    which is a true FAIL for a false reason and points the fix at the wrong
+    thing. But strict UTF-8 alone does not catch it — BOM-less UTF-16LE/BE and
+    UTF-32LE are *valid* UTF-8, because NUL is a legal code point, so they
+    decoded clean and produced exactly that false diagnosis anyway. The NUL
+    byte is the complete signal and is checked first: no plausible markdown
+    adapter contains one, and every UTF-16/32 encoding of ASCII is full of
+    them. A file this gate cannot read gets an encoding diagnostic and exit 2,
+    the same policy the ADR-0020 validators' read_text() uses.
+
+    A file that exists but cannot be read at all is neither a pass nor a FAIL —
+    nothing was graded — so it exits 3 rather than 1. Exit 1 sends the skill's
+    closeout into "fix the FAIL by editing the provider file", which for a file
+    it cannot open is an instruction to edit blind.
+    """
+    try:
+        with open(path, "rb") as fh:
+            raw = fh.read()
+    except OSError as exc:
+        print(f"Error: '{path}' exists but could not be read ({exc.strerror}). "
+              "Nothing was checked — fix whatever is blocking the read "
+              "(permissions, ownership, the underlying device) and re-run; do "
+              "not edit the adapter on the strength of this.", file=sys.stderr)
+        sys.exit(EXIT_UNREADABLE)
+    if b"\x00" in raw:
+        print(f"Error: '{path}' is not valid UTF-8 — it contains NUL bytes, so "
+              "it is almost certainly UTF-16 or UTF-32 (with or without a BOM). "
+              "Re-save it as UTF-8; this check does not guess at other "
+              "encodings.", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        print(f"Error: '{path}' is not valid UTF-8 ({exc.reason} at byte "
+              f"{exc.start}) — re-save it as UTF-8; this check does not guess "
+              "at other encodings.", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    return text.replace("\ufeff", "")
+
+
+adapter_content = read_text(adapter_path)
+agents_md_content = read_text(agents_md_path)
+adapter_dir = os.path.dirname(os.path.abspath(adapter_path))
 
 has_fail = False
 
@@ -89,30 +245,229 @@ if not adapter_content.strip():
     print("      Why: An empty adapter carries no reference to AGENTS.md and no provider-specific content.")
     print("      Fix: Add at least an import (or text pointer) to AGENTS.md.")
     print()
-    sys.exit(1)
+    sys.exit(EXIT_FAIL)
 
-IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
+
-lines = adapter_content.splitlines()
+# --- Inert regions -----------------------------------------------------------
-import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
+#
+# A reference only counts where something would actually resolve it. Fenced
+# code blocks, indented code blocks and HTML comments are shown to the reader
+# (or hidden from them) as literal text; Claude Code resolves an @import in
+# none of them. Without this, a ```-fenced `@AGENTS.md` — the exact
+# copy-the-example-into-the-file mistake this gate exists to catch — exited 0
+# with the adapter deferring to nothing.
+#
+# Indented code blocks are handled by IMPORT_RE's `^ {0,3}` instead of by the
+# mask: four leading spaces is what opens an indented code block in CommonMark,
+# so an import has to sit within three. The mask deliberately does not apply
+# that rule to prose pointers, where four-space indentation is ordinary list
+# continuation rather than code.
+FENCE_RE = re.compile(r'^( {0,3})(`{3,}|~{3,})(.*)$')
+COMMENT_RE = re.compile(r'<!--.*?(?:-->|\Z)', re.DOTALL)
+
+
+def line_offsets(text):
+    """[(char offset, line without its terminator)] over `text`."""
+    out = []
+    off = 0
+    for raw in text.splitlines(keepends=True):
+        out.append((off, raw.rstrip("\r\n")))
+        off += len(raw)
+    return out
+
+
+def build_inert_mask(text, offsets):
+    """Per-character flags: 1 where a reference would never be resolved."""
+    mask = bytearray(len(text))
+    fence = None  # (fence char, opening run length)
+    for start, line in offsets:
+        m = FENCE_RE.match(line)
+        if fence is None:
+            if m:
+                fence = (m.group(2)[0], len(m.group(2)))
+                for i in range(start, start + len(line)):
+                    mask[i] = 1
+            continue
+        for i in range(start, start + len(line)):
+            mask[i] = 1
+        if (m and m.group(2)[0] == fence[0]
+                and len(m.group(2)) >= fence[1]
+                and not m.group(3).strip()):
+            fence = None
+    for m in COMMENT_RE.finditer(text):
+        if m.start() < len(mask) and mask[m.start()]:
+            continue  # a literal "<!--" printed inside a fence opens nothing
+        for i in range(m.start(), min(m.end(), len(mask))):
+            mask[i] = 1
+    return mask
+
+
+# --- Reference shapes --------------------------------------------------------
+#
+# `\S*AGENTS\.md` had no path-separator boundary, so `@NOTAGENTS.md` and
+# `@zzzAGENTS.md` counted as imports of AGENTS.md. The matched path must end in
+# AGENTS.md as a whole segment.
+IMPORT_RE = re.compile(r'^ {0,3}@(?P<path>\S+?)\s*$')
+# A mention in prose: an optional relative path, then AGENTS.md, with no
+# identifier character glued to the front (so NOTAGENTS.md does not match) and
+# nothing glued to the back.
+MENTION_RE = re.compile(r'(?<![0-9A-Za-z_.\-/])((?:[\w.\-~]+/)*AGENTS\.md)(?![0-9A-Za-z])')
+
+# A pointer has to read as a pointer. `"AGENTS.md" in ln` passed
+# "Do NOT read AGENTS.md; it is obsolete." and "We deleted AGENTS.md last
+# year." — both of which point the reader away from the file. Require a
+# deference cue in the naming sentence, and reject a negated one.
+DIRECTIVE_RE = re.compile(
+    r'\b(see|read|refer|refers|referring|consult|consults|follow|follows|'
+    r'defer|defers|deferring|described|documented|documents|covered|covers|'
+    r'found|listed|specified|defined|governed|per|use|uses|using|apply|obey|'
+    r'start|check|live|lives|contains|holds|carries|inherit|inherits|import|'
+    r'imports|conventions|instructions|guidelines|guidance|rules|standards|'
+    r'reference|setup)\b', re.I)
+NEGATION_RE = re.compile(
+    r"(\bnot\b|n't\b|\bnever\b|\bno longer\b|\bdeleted\b|\bremoved\b|"
+    r"\bobsolete\b|\bdeprecated\b|\bignore\b|\bignores\b|\bignoring\b|"
+    r"\bdisregard\b|\bsuperseded\b|\bgone\b|\bunused\b|\bstale\b)", re.I)
+SENTENCE_SPLIT_RE = re.compile(r'(?<=[.;:!?])\s+')
+
+
+def sentence_around(line, index):
+    """(sentence of `line` containing character `index`, its start offset)."""
+    bounds = [0]
+    for m in SENTENCE_SPLIT_RE.finditer(line):
+        bounds.append(m.end())
+    bounds.append(len(line) + 1)
+    for i in range(len(bounds) - 1):
+        if bounds[i] <= index < bounds[i + 1]:
+            return line[bounds[i]:bounds[i + 1]], bounds[i]
+    return line, 0
+
+
+def reads_as_pointer(line, match):
+    """Does the sentence naming AGENTS.md actually point the reader at it?
+
+    The matched path is blanked out before the cues are applied. It is a
+    filename, not prose, and leaving it in let its own characters vote: the
+    perfectly ordinary `docs/does/not/exist/AGENTS.md` tripped the negation
+    cue on the `not` path segment, so a pointer got rejected for the wrong
+    reason and the near-miss line then reported the wrong diagnosis.
+    """
+    sentence, sentence_start = sentence_around(line, match.start())
+    rel_start = match.start() - sentence_start
+    rel_end = match.end() - sentence_start
+    probe = sentence[:rel_start] + " AGENTS.md " + sentence[rel_end:]
+    if NEGATION_RE.search(probe):
+        return False
+    return bool(DIRECTIVE_RE.search(probe))
+
+
+def resolve(raw_path):
+    """An import/pointer path resolved the way the provider would resolve it."""
+    p = os.path.expanduser(raw_path)
+    if not os.path.isabs(p):
+        p = os.path.join(adapter_dir, p)
+    return os.path.normpath(p)
+
+
+def target_problem(raw_path):
+    """None if `raw_path` names a real, non-empty file; else why not."""
+    resolved = resolve(raw_path)
+    if not os.path.isfile(resolved):
+        return f"'{raw_path}' resolves to {resolved}, which does not exist"
+    try:
+        if os.path.getsize(resolved) == 0:
+            return f"'{raw_path}' resolves to {resolved}, which is empty"
+        with open(resolved, "rb") as fh:
+            if not fh.read().strip():
+                return f"'{raw_path}' resolves to {resolved}, which is blank"
+    except OSError as exc:
+        return f"'{raw_path}' resolves to {resolved}, which cannot be read ({exc.strerror})"
+    return None
+
+
+def names_agents_md(path):
+    return path == "AGENTS.md" or path.endswith("/AGENTS.md")
+
+
+offsets = line_offsets(adapter_content)
+lines = [line for _, line in offsets]
+mask = build_inert_mask(adapter_content, offsets)
+
+
+def is_inert(abs_index):
+    return abs_index < len(mask) and bool(mask[abs_index])
+
+
+# Lines shaped like an @AGENTS.md import, whether or not the target resolves.
+# Used to exclude them from the duplication denominator and from the prose
+# pointer scan, both of which only care about the shape.
+import_shaped_lines = set()
+# (line, raw path) for every import whose target actually resolves.
+live_imports = []
+# Diagnostics for imports that are the right shape but resolve to nothing.
+dead_imports = []
+# Imports that exist only inside a fence or an HTML comment.
+inert_imports = []
+
+for start, line in offsets:
+    m = IMPORT_RE.match(line)
+    if not m or not names_agents_md(m.group("path")):
+        continue
+    at_index = start + line.index("@")
+    if is_inert(at_index):
+        inert_imports.append(line.strip())
+        continue
+    import_shaped_lines.add(line)
+    problem = target_problem(m.group("path"))
+    if problem:
+        dead_imports.append(problem)
+    else:
+        live_imports.append(line)
+
+live_pointers = []
+dead_pointers = []
+inert_pointers = []
+mention_only = []
+
+for start, line in offsets:
+    if line in import_shaped_lines:
+        continue
+    for m in MENTION_RE.finditer(line):
+        if is_inert(start + m.start()):
+            inert_pointers.append(line.strip())
+            continue
+        if not reads_as_pointer(line, m):
+            mention_only.append(sentence_around(line, m.start())[0].strip())
+            continue
+        problem = target_problem(m.group(1))
+        if problem:
+            dead_pointers.append(problem)
+        else:
+            live_pointers.append(line)
 
 if no_import_syntax:
-    has_reference = "AGENTS.md" in adapter_content
+    has_reference = bool(live_pointers)
+    near_misses = dead_pointers + [f"{d} (inside a code fence or HTML comment)" for d in inert_pointers]
+    near_misses += [f"'{s}' names AGENTS.md but does not point at it" for s in mention_only]
 else:
-    has_reference = bool(import_lines) or "AGENTS.md" in adapter_content
+    has_reference = bool(live_imports)
+    near_misses = dead_imports + [f"'{d}' is inside a code fence or HTML comment, where no import is resolved" for d in inert_imports]
 
 if not has_reference:
     has_fail = True
     print(f"FAIL  Adapter has no reference to AGENTS.md — {adapter_path}")
     if no_import_syntax:
-        print("      Why: This provider has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.")
+        print("      Why: This provider resolves no cross-file import, so the adapter must point at AGENTS.md in prose; an `@AGENTS.md` line here is inert text. The pointer has to read as a pointer and name a file that is really there — a bare or negated mention (\"we deleted AGENTS.md\") defers nothing, and neither does a mention buried in a code fence or an HTML comment.")
-        print("      Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
+        print("      Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\", outside any fence, naming a path that exists relative to this file.")
     else:
-        print("      Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.")
+        print("      Why: A thin adapter must import AGENTS.md with an `@AGENTS.md` line of its own, indented no more than three spaces, and the path must resolve to a real non-empty file. Naming the file mid-sentence or inside backticks is prose this check will not credit; putting the line inside a ``` fence, an indented code block, or an HTML comment is worse, because nothing resolves it and it looks right.")
-        print("      Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.")
+        print("      Fix: Put `@AGENTS.md` (or the equivalent relative path) alone on its own line at the top level of the file, or pass --no-import-syntax if this provider resolves no imports.")
+    for miss in near_misses:
+        print(f"      Near miss: {miss}")
     print()
 
 # --- Duplication check ---
-non_import_lines = [ln for ln in lines if not IMPORT_RE.match(ln)]
+non_import_lines = [ln for ln in lines if ln not in import_shaped_lines]
 adapter_lines = [ln.strip() for ln in non_import_lines if ln.strip()]
 agents_lines = {ln.strip() for ln in agents_md_content.splitlines() if ln.strip()}
 
@@ -132,10 +487,10 @@ if non_blank_count > max_lines:
     has_fail = True
     print(f"FAIL  Adapter is not thin — {adapter_path}")
     print(f"      Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
-    print("      Fix: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.")
+    print("      Fix: Delete the lines already covered by AGENTS.md; keep only genuinely provider-specific additions here.")
     print()
 
 if has_fail:
-    sys.exit(1)
+    sys.exit(EXIT_FAIL)
 sys.exit(0)
 PYTHON

plugins/git/.apm/agents/git-orchestrate.agent.md

@@ -16,7 +16,7 @@ You are the orchestrator for the git plugin—a composable workflow dispatcher d
 
 You act on the caller's real branch and session context (you explicitly carry forward `current_branch`), not a disposable copy — you do not run in an isolated worktree.
 
-**Scope:** this orchestrator routes git-object operations only (commits, branches, worktrees, remotes, submodules, history). `pc-author` and `pc-run` (pre-commit config authoring and hook execution) are intentionally not routed here — they operate on `.pre-commit-config.yaml` and hook installation, not git objects. `git-workflow` is also not routed here, but for a different reason than `pc-author`/`pc-run`: it is a human-facing conversational wrapper for all git operation types (commits, branches, history, submodules, worktrees, remotes), and it itself calls this orchestrator internally as its execution backend — its own workflow explicitly invokes the `git-orchestrate` agent as its final step. It is not a peer to invoke instead of this dispatcher, and it explicitly refuses agent callers ("Do not use when the caller is an agent"). Agent callers route git-object operations here directly; direct human users to `git-workflow` when they want guided, conversational git help — it will call back into this orchestrator itself. Invoke `pc-author`/`pc-run` directly rather than through this dispatcher; do not invoke `git-workflow` as an agent caller under any circumstance.
+**Scope:** this orchestrator routes git-object operations only (commits, branches, worktrees, remotes, submodules, history). `pc-author` and `pc-run` (pre-commit config authoring and hook execution) are intentionally not routed here — they operate on `.pre-commit-config.yaml` and hook installation, not git objects. `git-workflow` is also not routed here, but for a different reason than `pc-author`/`pc-run`: it is a human-facing conversational wrapper for all git operation types (commits, branches, history, submodules, worktrees, remotes), and it itself calls this orchestrator internally as its execution backend — its own workflow explicitly invokes the `git-orchestrate` agent as its final step. It is not a peer to invoke instead of this dispatcher, and its own boundary clause sends agent callers here ("Not an agent caller -> `git-orchestrate`"). Agent callers route git-object operations here directly; direct human users to `git-workflow` when they want guided, conversational git help — it will call back into this orchestrator itself. Invoke `pc-author`/`pc-run` directly rather than through this dispatcher; do not invoke `git-workflow` as an agent caller under any circumstance.
 
 ## Hard rules
 

plugins/git/.apm/skills/git-branches/README.md

@@ -1,6 +1,6 @@
 # git-branches
 
-Manage the full lifecycle of git branches — create, switch, delete, rename, and track feature/hotfix/release branches under GitHub Flow or Gitflow.
+Manage the full lifecycle of git branches — create, switch, delete, rename, track, merge, and compare feature/hotfix/release branches under GitHub Flow or Gitflow.
 
 ## What it does
 
@@ -12,11 +12,23 @@ This skill handles branch operations within the git workflow suite. It creates b
 /git-branches
 ```
 
-Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, or track. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
+Describe your branch task: create a feature/hotfix/release branch, switch, delete, rename, track, merge, or compare two branches. The skill will determine the branching pattern (GitHub Flow or Gitflow) from config or repo state and handle safety checks for destructive operations.
 
 ## Files
 
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/branch-patterns.md` | Loaded when a branch's base, name prefix, or merge rule depends on GitHub Flow vs. Gitflow |
+| `references/branch-operations.md` | Loaded when running a create/switch/delete/rename/track/list/stash action, or resolving `get-intent` |
+| `references/merging.md` | Loaded when merging one branch into another or resolving merge conflicts |
+| `references/comparing-branches.md` | Loaded when comparing two branches or finding where they diverged |
+| `references/orchestrator-contract.md` | Loaded when `git-orchestrate` or another calling agent supplies a structured request rather than prose |
 | `references/sources.md` | Research sources backing the branching/gitflow guidance |
+
+## Composition
+
+`git-orchestrate` calls this skill for the branch step of a multi-step workflow and parses its
+structured result. Revert is `git-history`'s; commit authoring, rebase, reset and cherry-pick are
+`git-commits`'; deleting a remote branch is `git-remotes`'; branch operations against a
+Gitea-hosted remote are `gitea-branches`'.

plugins/git/.apm/skills/git-branches/SKILL.md

@@ -2,13 +2,11 @@
 name: git-branches
 
 description: >
-  Use when managing the full lifecycle of git branches: create feature/hotfix/release branches
+  Use when creating, switching, deleting, renaming, tracking, merging, or comparing
-  (gitflow, GitHub Flow, or custom patterns from config), switch, delete, rename, and track branches,
+  local git branches under GitHub Flow or Gitflow.
-  or retrieve branch intent metadata. Handles branch protection safety checks and returns structured
+  Not writing or rewriting commits -> `git-commits`.
-  results for agent composition. Use even if the user doesn't explicitly mention branch names — they
+  Not history inspection -> `git-history`.
-  may be asking about "fixing something" or "shipping a feature", which implicitly requires branch
+  Not a Gitea remote's branches -> `gitea-branches`.
-  management. Do not use when the user needs only commit operations (use git-commits) or history
-  inspection (use git-history).
 
 metadata:
   category: git
@@ -21,92 +19,57 @@ metadata:
 
 ## Gotchas
 
-- **Branches are cheap; deletion is cheap but risky.** Deleting one requires checking if commits on it are reachable elsewhere; always confirm before deleting, as it may lose unmerged work.
+- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
-- **Uncommitted changes can block branch switches.** `git switch` aborts if local modifications conflict with the target branch. Offer to stash changes before switching when this happens, don't force a checkout.
+- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` and `git tag --list <name>`; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
-- **Tracking relationships matter for coordination.** Agents pushing on behalf of users should always set tracking (`-u origin <branch>`) so later pushes/pulls know the target. Without it, commands fail or target the wrong remote branch.
+- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead.
-- **Gitflow vs. GitHub Flow are not compatible.** Gitflow requires `develop` and `release/*` branches with `--no-ff` merges; GitHub Flow uses only `main` and feature branches with fast-forward. Read the repo's config or ask the orchestrator which pattern to use — don't guess.
-- **Naming collisions with tags.** A branch and tag can have the same name. Prefer `git switch` over `git checkout` for branch operations — verify which ref you're targeting with `git branch --list <name>` / `git tag --list <name>` if the name could be ambiguous, and disambiguate explicitly with `refs/heads/<name>` (branch) or `refs/tags/<name>` (tag) where a command accepts either.
-- **Never force-push `main` or `master`.** This is a hard refusal, not a confirmation gate — it applies even if the caller passes `confirm: true`. Deleting or renaming `main`/`master` in a way that would require a force-push to reconcile the remote (e.g. force-deleting and recreating it, or renaming it out from under in-flight work) must be rejected outright; explain why and suggest a non-destructive alternative (e.g. a new branch) instead of proceeding.
 
-## Branch Patterns
+## Step 1 — Determine the branching pattern
 
-Default to **GitHub Flow** (simpler, modern, CI/CD-friendly). Fall back to **Gitflow** only if the repo's config specifies it or the branch structure shows it in use (presence of `develop` or release branches).
+Read `branching_pattern` from the git plugin config (`.claude/plugins/git/config.json`; the plugin root's `config.example.json` shows the shape). Default: `github-flow`. With no config, infer Gitflow from the presence of a `develop` or `release/*` branch, and GitHub Flow otherwise.
 
-**GitHub Flow:**
+The two patterns are not mixable, and the wrong merge rule silently damages history. If the action touches a base branch, a name prefix, or a merge rule, read `references/branch-patterns.md`.
-- Base: `main`
-- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
-- Merge: fast-forward when possible (preserves linear history)
-- Delete after merge
 
-**Gitflow:**
+## Step 2 — Dispatch on the action
-- Base: `main` (production) + `develop` (integration)
-- Feature branches: `feature/<feature-name>` (from `develop`)
-- Release branches: `release/X.Y.Z` (from `develop`, merged to `main` + `develop`)
-- Hotfix branches: `hotfix/X.Y.Z` (from `main`, merged to `main` + `develop`)
-- Merge: always use `--no-ff` to preserve branch structure
 
-## Workflow
+| Action | Reference |
+|---|---|
+| create, switch, delete, rename, track, list, get-intent, stash | `references/branch-operations.md` |
+| merge a branch, resolve merge conflicts | `references/merging.md` |
+| compare two branches, find their divergence | `references/comparing-branches.md` |
 
-- [ ] **Determine pattern:** Check git plugin config (`.claude/plugins/git/config.json`, if present — see `config.example.json` in the plugin root for the expected shape) for `branching_pattern` (default: `github-flow`). If not set, inspect repo for `develop` branch or `release/*` branches; if present, assume Gitflow.
+Load only the file the action needs. A destructive action still passes Step 3 first.
-- [ ] **Create branch:** Use `git switch -c <branch> <base>`. Base defaults to config's `base_branch` (usually `main` or `develop`). Include intent metadata in branch name or return as structured result (e.g., `{ "branch": "feature/x", "intent": "implement feature X" }`).
-- [ ] **Track remote:** If pushing, always use `git push -u origin <branch>` to establish tracking.
-- [ ] **Safety checks before destructive ops:** Before delete/force-push/rebase with history loss, check: (1) Is this branch tracking a remote? Warn if yes. (2) Are there unpushed commits? Warn if yes. (3) Does the orchestrator call include `confirm: true`? Fail if not. For humans, prompt interactively.
-- [ ] **Return structured results:** Always return branch operations as JSON or structured text: `{ "action": "create", "branch": "feature/x", "base": "main", "tracking": "origin/feature/x", "intent": "implement feature X" }`. Agents need to parse this for subsequent operations.
-- [ ] **Retrieve intent (`get-intent`):** Git has no native field for free-text branch metadata — this skill doesn't persist it. On `create`, the `intent` value is only ever returned in the structured result; the caller (orchestrator or agent) is responsible for storing it if it needs to be looked up later. On `get-intent`, either parse it back out of the branch name convention (`feature/<intent-slug>`) or return `{ "intent": null }` if the caller never persisted the original create-time value — don't fabricate an intent.
 
-### Command mapping for each action
+## Step 3 — Gate destructive operations
 
-- **delete:** `git branch -d <branch>` refuses if the branch has unmerged commits — prefer this by default. `git branch -D <branch>` forces deletion and discards unmerged work; only use it after the safety checks above pass and `confirm: true` is set. For a remote branch: `git push origin --delete <branch>`.
+Before any delete or force-delete that loses history:
-- **rename:** `git branch -m <old> <new>`.
-- **list:** `git branch` (local only), `git branch -a` (all local + remote-tracking), `git branch -r` (remote-tracking only), `git branch --merged`/`--no-merged` (filter by merge status into current branch).
-- **get-intent:** No git command — see Workflow step "Retrieve intent" for how this is resolved.
-- **track (existing branch):** `git branch --set-upstream-to=origin/<branch>` sets tracking without a push; `git branch -vv` shows tracking state for all local branches.
-- **switch (existing branch):** `git switch <branch>` — switches to an existing local branch (aborts on conflicting local changes, see Gotchas). `git switch -` switches back to the previously checked-out branch.
 
-## Merging
+- [ ] Does the branch track a remote? Warn if so.
+- [ ] Are there unpushed commits on it? Warn if so.
+- [ ] Did the caller pass `confirm: true`? Fail if not — for a human caller, prompt interactively instead of failing.
 
-Scope: fast-forward/merge-commit mechanics and conflict resolution only. Rebase, cherry-pick, and revert belong to `git-history`.
+These gates are passable. The `main`/`master` refusal in Gotchas is not.
 
-- **Fast-forward:** `git merge <branch>` — advances the pointer with no merge commit if the target hasn't diverged.
+## Step 4 — Set tracking
-- **True merge:** `git merge --no-ff <branch>` — forces a merge commit even when fast-forward is possible; required by Gitflow on all supporting-branch merges.
-- **Squash merge:** `git merge --squash <branch>` stages the combined diff without committing; follow with a manual `git commit`.
-- **Octopus merge:** `git merge branch-a branch-b branch-c` merges more than two branches at once; fails outright on any conflict, so use sequential two-way merges if conflicts are expected.
 
-**Conflict resolution:** when Git can't auto-merge, it inserts conflict markers and stops. Run `git status` to find conflicted files, edit them to resolve the markers, then `git add <file>` and `git merge --continue`. `git merge --abort` reverts to the pre-merge state. `git mergetool` opens the configured merge tool; `git diff --diff-filter=U` shows only conflicted files.
+A new branch's first push must be `git push -u origin <branch>`. The push itself is `git-remotes`' — every remote-side gate lives there, which is why Step 2's remote-delete row hands off the same way — but the upstream requirement originates here, so carry it in the handoff. Without an upstream, later pushes and pulls either fail or silently target the wrong remote branch, and the caller has no way to tell which happened.
 
-## Comparing Branches
+## Step 5 — Return a structured result
 
-- `git log main..feature` — commits in `feature` not in `main`.
+Return every operation in this shape rather than prose, including failures — a calling agent chains its next operation on the result and cannot parse a sentence.
-- `git log feature..main` — commits in `main` not in `feature` (reverse direction).
-- `git log --left-right main...feature` — both diverging sets (symmetric diff).
-- `git diff main...feature` — diff from the common ancestor to `feature`'s tip.
-- `git merge-base main feature` — print the common ancestor commit.
 
-## Integration with Orchestrator
-
-When invoked by `git-orchestrate`, accept requests in the form:
-```json
-{
-  "action": "create|switch|delete|rename|track|list|get-intent",
-  "branch": "<branch-name>",
-  "base": "<base-branch (optional, defaults to config)>",
-  "intent": "<human-readable intent (optional)>",
-  "confirm": "<true for destructive ops, omit for read ops>"
-}
-```
-
-Return results as:
 ```json
 {
   "success": true,
-  "action": "create|switch|...",
+  "action": "create|switch|delete|rename|track|list|get-intent",
   "branch": "<name>",
   "message": "descriptive message",
   "intent": "<intent if tracked>",
-  "tracking": "origin/<branch (if set)>",
+  "tracking": "origin/<branch, if set>",
   "error": "<error message if success=false>",
   "suggestion": "<recovery suggestion if applicable>"
 }
 ```
 
-If error is due to uncommitted changes, include `{ "suggestion": "stash changes and retry" }` so the orchestrator can offer automatic recovery.
+When the failure is uncommitted local changes, set `"suggestion": "stash changes and retry"` so the caller can offer recovery rather than surfacing a dead end.
+
+When a calling agent supplies a structured request rather than prose, read `references/orchestrator-contract.md` for the request schema.

plugins/git/.apm/skills/git-branches/references/branch-operations.md

@@ -0,0 +1,56 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Per-action command mapping
+
+One command per action. Where two forms exist, the first is the default and the second the escape
+hatch.
+
+- **create** — `git switch -c <branch> <base>`. Base comes from the config's `base_branch`
+  (`main` under GitHub Flow, usually `develop` under Gitflow).
+- **switch** — `git switch <branch>` moves to an existing local branch; it aborts rather than
+  clobbering conflicting local changes. `git switch -` returns to the previous branch.
+- **delete (local)** — `git branch -d <branch>` refuses when the branch holds unmerged commits,
+  which is why it is the default. `git branch -D <branch>` forces the deletion and discards that
+  work — only after the destructive-operation gates pass and `confirm: true` is set.
+- **delete (remote)** — not this skill's. Deleting a remote branch is a push, and every remote-side
+  gate lives in `git-remotes`; hand it there rather than running the push from here. Its
+  `references/push.md` carries the command and the refspec form.
+- **rename** — `git branch -m <old> <new>`.
+- **list** — `git branch` (local), `-a` (local plus remote-tracking), `-r` (remote-tracking only),
+  `--merged` / `--no-merged` (filter by merge status into the current branch).
+- **track** — `git branch --set-upstream-to=origin/<branch>` sets an upstream without pushing.
+  `git branch -vv` shows the tracking state of every local branch.
+
+## get-intent
+
+Git has no native field for free-text branch metadata, and this skill does not persist any. On
+`create`, the `intent` value is only returned in the structured result — the caller decides
+whether to store it.
+
+On `get-intent`, either parse the intent back out of the branch-name convention
+(`feature/<intent-slug>`) or return `{ "intent": null }` when the caller never persisted the
+create-time value. Never fabricate an intent: a downstream commit message built on a guessed
+intent is worse than one built on none.
+
+## Stashing work in progress
+
+A switch aborts rather than clobbering conflicting local changes (see Gotchas). Stash is the way
+past it: it shelves the working tree and index so the branch pointer can move.
+
+- **save** — `git stash push -m "<message>"`. Add `-u` to include untracked files; verified on Git
+  2.39.5, a plain `push` leaves them in place, and a plain `push` with *only* untracked changes
+  reports `No local changes to save` and stashes nothing. Bare `git stash` is `push` with no message.
+- **restore** — `git stash pop` applies the newest entry and deletes it. `git stash apply stash@{n}`
+  applies without deleting, for replaying one shelf onto more than one branch.
+- **list** — `git stash list`; `git stash show -p stash@{n}` prints that entry's diff.
+- **drop** — `git stash drop stash@{n}` deletes one entry. `git stash clear` deletes all of them
+  and nothing recovers them — confirm before running it.
+- **branch from a stash** — `git stash branch <branch> stash@{n}` creates a branch at the commit the
+  stash was taken from and pops it there. Use it when the stash no longer applies to the current tip.
+
+**A conflicting `pop` keeps the entry.** Verified on 2.39.5: it exits 1, writes conflict markers,
+prints "The stash entry is kept in case you need it again", and `git stash list` still shows it.
+Resolve, `git add`, then `git stash drop` the entry by hand — otherwise it silently accumulates.

plugins/git/.apm/skills/git-branches/references/branch-patterns.md

@@ -0,0 +1,31 @@
+---
+source_keys:
+  - nvie-gitflow-post
+  - atlassian-gitflow-tutorial
+  - gitflow-cheatsheet
+---
+
+# Branch patterns
+
+Which pattern is in play decides the base branch, the branch name prefix, and whether merges are
+allowed to fast-forward. Default to GitHub Flow — simpler, and what CI/CD-oriented repos expect.
+Fall back to Gitflow only when the config says so or the repo already carries `develop` or
+`release/*` branches.
+
+## GitHub Flow
+
+- Base: `main`
+- Feature branches: `feature/<feature-name>` or `fix/<bug-name>`
+- Merge: fast-forward where possible, to keep history linear
+- Delete the branch after merge
+
+## Gitflow
+
+- Base: `main` (production) plus `develop` (integration)
+- Feature branches: `feature/<feature-name>`, cut from `develop`
+- Release branches: `release/X.Y.Z`, cut from `develop`, merged to both `main` and `develop`
+- Hotfix branches: `hotfix/X.Y.Z`, cut from `main`, merged to both `main` and `develop`
+- Merge: always `--no-ff`, so the branch structure survives in the history
+
+The two are not mixable. A `--no-ff` merge into a GitHub Flow repo leaves merge commits nobody
+expects; a fast-forward merge of a Gitflow release branch erases the release boundary.

plugins/git/.apm/skills/git-branches/references/comparing-branches.md

@@ -0,0 +1,16 @@
+---
+source_keys:
+  - context7-git-htmldocs
+---
+
+# Comparing two branches
+
+The two-dot and three-dot forms mean different things and are easy to swap by accident — check the
+direction before reporting a result.
+
+- `git log main..feature` — commits on `feature` that are not on `main`.
+- `git log feature..main` — the reverse direction: commits on `main` not on `feature`.
+- `git log --left-right main...feature` — both diverging sets at once (symmetric difference).
+- `git diff main...feature` — the diff from the common ancestor to `feature`'s tip, which is what
+  a reviewer sees, rather than the diff between the two tips.
+- `git merge-base main feature` — print the common ancestor commit.

plugins/git/.apm/skills/git-branches/references/merging.md

@@ -0,0 +1,30 @@
+---
+source_keys:
+  - context7-git-htmldocs
+  - atlassian-gitflow-tutorial
+---
+
+# Merging one branch into another
+
+Scope is fast-forward and merge-commit mechanics plus conflict resolution. Rebase and cherry-pick
+belong to `git-commits`; revert to `git-history`.
+
+- **Fast-forward** — `git merge <branch>` advances the pointer with no merge commit when the
+  target has not diverged.
+- **True merge** — `git merge --no-ff <branch>` forces a merge commit even when a fast-forward is
+  possible. Gitflow requires it on every supporting-branch merge.
+- **Squash merge** — `git merge --squash <branch>` stages the combined diff without committing.
+  Follow it with a `git commit`.
+- **Octopus merge** — `git merge branch-a branch-b branch-c` merges more than two branches at
+  once, but fails outright on any conflict. Use sequential two-way merges when conflicts are
+  likely.
+
+## Conflict resolution
+
+When Git cannot auto-merge it writes conflict markers and stops mid-merge. Run `git status` to
+list the conflicted files, edit each to resolve its markers, then `git add <file>` and
+`git merge --continue`.
+
+- `git merge --abort` restores the pre-merge state.
+- `git mergetool` opens the configured merge tool.
+- `git diff --diff-filter=U` shows only the still-conflicted files.

plugins/git/.apm/skills/git-branches/references/orchestrator-contract.md

@@ -0,0 +1,20 @@
+---
+source_keys: []
+---
+
+# Orchestrator request contract
+
+`git-orchestrate` and other calling agents send this shape. The result shape they parse back is in
+`SKILL.md` Step 5, because every run emits one.
+
+Request:
+
+```json
+{
+  "action": "create|switch|delete|rename|track|list|get-intent",
+  "branch": "<branch-name>",
+  "base": "<base branch, optional, defaults to config>",
+  "intent": "<human-readable intent, optional>",
+  "confirm": "<true for destructive ops, omit for read ops>"
+}
+```

plugins/git/.apm/skills/git-branches/references/sources.md

@@ -12,7 +12,8 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — Gitflow vs. GitHub Flow structure and defaults)
+- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
+- references/branch-patterns.md (Gitflow vs. GitHub Flow structure, defaults, and why the two are not mixable)
 
 ## atlassian-gitflow-tutorial
 
@@ -23,7 +24,9 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — Gitflow branch types, base/merge targets, `--no-ff` requirement)
+- SKILL.md (Gitflow vs. GitHub Flow inference and the not-mixable rule)
+- references/branch-patterns.md (Gitflow branch types, base/merge targets, `--no-ff` requirement)
+- references/merging.md (`--no-ff` requirement on Gitflow supporting-branch merges)
 
 ## gitflow-cheatsheet
 
@@ -34,7 +37,7 @@
 - **Research doc:** plugins/git/docs/research/docs/git/gitflow.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Branch Patterns — feature/release/hotfix naming conventions)
+- references/branch-patterns.md (feature/release/hotfix naming conventions)
 
 ## context7-git-htmldocs
 
@@ -45,4 +48,7 @@
 - **Research doc:** plugins/git/docs/research/docs/git/branching-merging.md (whole-document reference)
 
 **Contributing files:**
-- SKILL.md (Command mapping, Merging, Comparing Branches — `git switch`/`git branch`/`git merge`/`git log`/`git diff`/`git merge-base` command vocabulary and flags)
+- SKILL.md (Gotchas — `git switch` abort-on-conflict behaviour, branch/tag name ambiguity)
+- references/branch-operations.md (`git switch`/`git branch` command vocabulary and flags)
+- references/merging.md (`git merge` strategies and conflict-resolution commands)
+- references/comparing-branches.md (`git log`/`git diff`/`git merge-base` range syntax)

plugins/git/.apm/skills/git-commits/README.md

@@ -16,9 +16,16 @@ Describe your commit task: create a new commit, amend, squash, or cherry-pick. T
 
 ## Files
 
-| File | Purpose |
+| File | Loaded when |
-|------|---------|
+|------|-------------|
-| `SKILL.md` | Skill instructions for agents |
+| `SKILL.md` | Always — gotchas, the flow dispatch table, the gates common to every flow, and the output shape |
-| `references/conventional-commits-spec.md` | Full Conventional Commits specification |
+| `references/create-commit.md` | Composing a new commit from staged changes |
-| `references/commit-template.md` | Why / Implementation Notes / Impact body structure and full trailer list |
+| `references/rewrite-history.md` | Amending, squashing, or folding a `fixup!`/`squash!` commit into an earlier one |
+| `references/cherry-pick.md` | Replaying an existing commit onto the current branch |
+| `references/conventional-commits-spec.md` | A type, footer, or breaking-change edge case is not obvious — full spec, 11-type set, commitlint constraint table |
+| `references/commit-template.md` | Writing a body for a non-trivial commit — Why / Implementation Notes / Impact structure and the full trailer list |
 | `references/sources.md` | Research sources and provenance |
+
+## Composition
+
+Part of the git plugin's domain suite. This skill owns commit authoring and history-rewriting operations only; `git-history` inspects history, `git-branches` owns branch lifecycle, and `git-workflow` is the conversational entry point that routes between them.