docs(gitea): add .env.example template for the gitea MCP server env vars

The README documented exporting GITEA_ACCESS_TOKEN and GITEA_HOST directly
but gave no discoverable template, and the repo has an established
per-plugin example-file convention (plugins/git/config.example.json) this
skipped. Adds plugins/gitea/.env.example with placeholder values and points
the README at it instead of duplicating the instructions inline.

Verified plugins/gitea/.env.example is trackable, not swallowed by
.gitignore's .env.* exclusion: the !.env.example allowlist line is
unanchored and matches at any depth. Also verified apm has no dotenv
auto-load anywhere in its source, so the file's instructions say to source
it explicitly rather than implying it's picked up automatically.

Full pre-push gate green, all 16 hooks. Test suite green, 26 suites.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EmiHiknxqtZPEBnW7ujgNz

.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.2",
+  "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.2",
       "category": "Developer Tools",
       "source": "./plugins/kyberforge"
     },
     {
       "name": "bin",
-      "description": "A place for things to be binned",
-      "version": "1.1.3",
+      "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.7",
       "category": "Utilities",
       "source": "./plugins/bin"
     },
     {
       "name": "git",
-      "description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.",
-      "version": "1.3.3",
+      "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.7",
       "category": "Version Control",
       "source": "./plugins/git"
     },
     {
       "name": "gitea",
-      "description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.",
-      "version": "1.3.4",
+      "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.8",
       "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.2",
+  "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.2",
       "category": "Developer Tools",
       "source": "./plugins/kyberforge"
     },
     {
       "name": "bin",
-      "description": "A place for things to be binned",
-      "version": "1.1.3",
+      "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.7",
       "category": "Utilities",
       "source": "./plugins/bin"
     },
     {
       "name": "git",
-      "description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.",
-      "version": "1.3.3",
+      "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.7",
       "category": "Version Control",
       "source": "./plugins/git"
     },
     {
       "name": "gitea",
-      "description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.",
-      "version": "1.3.4",
+      "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.8",
       "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"
     }

.pre-commit-config.yaml

@@ -207,7 +207,7 @@ repos:
         # pre-commit prints nothing at all for a passing hook, so without this
         # the opt-out reinstated exactly the silent vacuous pass the script was
         # written to kill, one level up -- the run showed a bare `Passed` and
-        # AGENTS.md's instruction to read that summary line was impossible to
+        # the documented instruction to read that summary line was impossible to
         # follow in the one situation the opt-out exists for. The script's clean
         # output is a single line, so this costs one line per push.
 
@@ -254,17 +254,79 @@ repos:
         entry: bash
         language: system
         files: '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'
+        # Pinned by tests/test-skill-frontmatter.sh, which drives this exact
+        # `bash -c <script> <arg0> <files...>` call shape rather than a copy of
+        # the script -- the bug below was invisible to any test that did not.
         args:
           - -c
           - |
+            # Every check reads the FRONTMATTER only, never the whole file. A
+            # `metadata:` / `name:` / `description:` line inside a body code
+            # fence is documentation (skill-author quotes exactly such a block)
+            # and used to satisfy these greps.
             for f in "$@"; do
-              if [[ -f "$f" ]]; then
-                if ! grep -q "^name:" "$f" || ! grep -q "^description:" "$f"; then
-                  echo "ERROR: $f is missing required frontmatter fields (name: and description:)"
-                  exit 1
-                fi
+              [[ -f "$f" ]] || continue
+
+              fm="$(awk '
+                { sub(/\r$/, "") }
+                NR == 1 { sub(/^\357\273\277/, "") }
+                !opened && /^[[:blank:]]*$/ { next }
+                !opened {
+                  if ($0 ~ /^---[[:blank:]]*$/) { opened = 1; next }
+                  exit
+                }
+                /^---[[:blank:]]*$/ { closed = 1; exit }
+                { print }
+                END { if (!opened || !closed) exit 3 }
+              ' "$f")" || {
+                echo "ERROR: $f has no closing YAML frontmatter block (expected --- ... --- at the top of the file)"
+                exit 1
+              }
+
+              missing=""
+              printf '%s\n' "$fm" | grep -q "^name:" || missing="${missing}name: "
+              printf '%s\n' "$fm" | grep -q "^description:" || missing="${missing}description: "
+
+              # Scoped to the `metadata:` block and stopped at the next
+              # top-level key, so a `version:` under a following `source:` list
+              # cannot stand in for it; the `^  version:` anchor is exact, so a
+              # deeper-nested `    version:` cannot either. No line budget, so a
+              # long `metadata:` block does not hide the key.
+              ver="$(printf '%s\n' "$fm" | awk '
+                /^metadata:/ { inm = 1; next }
+                inm && /^[A-Za-z]/ { exit }
+                inm && /^  version:/ {
+                  v = $0
+                  sub(/^  version:[[:blank:]]*/, "", v)
+                  sub(/[[:blank:]]+#.*$/, "", v)
+                  sub(/[[:blank:]]+$/, "", v)
+                  print "found:" v
+                  exit
+                }
+              ')"
+              [[ -n "$ver" ]] || missing="${missing}metadata.version "
+
+              if [[ -n "$missing" ]]; then
+                echo "ERROR: $f is missing required frontmatter fields (${missing})"
+                exit 1
+              fi
+
+              raw="${ver#found:}"
+              v="$raw"
+              case "$v" in
+                \"*\") v="${v#\"}"; v="${v%\"}" ;;
+                \'*\') v="${v#\'}"; v="${v%\'}" ;;
+              esac
+              if [[ ! "$v" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+                echo "ERROR: $f has a malformed frontmatter metadata.version (${raw:-<empty>}) -- expected a three-part semver, e.g. \"1.0.0\""
+                exit 1
               fi
             done
+          # arg0 for `bash -c`. WITHOUT it pre-commit's first filename lands in
+          # $0 and is dropped from "$@" -- so a single-file commit, the normal
+          # case, ran the loop zero times and reported Passed having checked
+          # nothing. Do not remove; tests/test-skill-frontmatter.sh pins it.
+          - skill-frontmatter
 
       - id: skill-size-check
         stages: ['pre-commit']
@@ -284,6 +346,21 @@ repos:
         # records for Vale warnings. Costs nothing on a clean file: the script
         # prints only findings.
 
+      - id: check-rtk-prefix
+        stages: ['pre-commit']
+        name: ADR-0023 rtk prefix on executable git commands
+        description: Enforce ADR-0023 clause 1 -- an executable, instructed git command in a shell code fence or a dispatch-table Run cell is written `rtk git`. Clauses 2 and 3 are not machine-decidable; a deliberately bare command opts out with the literal string ADR-0023 on its own line
+        entry: scripts/check-rtk-prefix.sh
+        language: script
+        files: '^plugins/[^/]+/\.apm/(skills/.*\.md|agents/.*\.agent\.md)$'
+        # README.md is excluded on purpose, not by oversight. A skill-directory
+        # README is consumer-facing prose that no agent ever loads, and the
+        # `git clone` lines in the seven tests/README.md files are setup
+        # instructions for a third party who has no rtk installed. Prefixing
+        # those would be actively wrong -- see ADR-0023's consumer section.
+        exclude: '(^|/)README\.md$'
+        pass_filenames: true
+
       - id: vale-audit-prefilter-skill
         stages: ['pre-commit']
         name: Vale audit prefilter (SKILL.md)

AGENTS.md

@@ -1,29 +1,27 @@
 # Working in this repo
 
-This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments.
+The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
+
+This file carries only what applies to **every** session. Setup, prerequisites, and test commands are in `README.md`; the reasoning behind each enforcement gate is in `docs/spec/gates.md`.
 
 ## Structure
 
-- `plugins/` — installable plugin units; each is an apm package (`apm.yml` + `.apm/`) carrying skills, agents, hooks, MCP servers, and bundled assets. This repo consumes them through **apm**, not Claude Code's native plugin install: root `apm.yml` declares all six as `dependencies.apm` git+path entries against the holocron remote, and `apm install` deploys them into `.claude/skills/` and `.claude/agents/` (both gitignored). External consumers can still install natively via `claude plugin install <name>@holocron` — the marketplace manifests are unchanged
-- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`)
+- `plugins/` — six installable plugin units, each an apm package (`apm.yml` + `.apm/`). Root `apm.yml` declares all six as `dependencies.apm`; `apm install` deploys them into `.claude/skills/` and `.claude/agents/`, both gitignored install output.
+- `providers/claude-code/` — Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh`.
 
 ## Edit `.apm/`, never the flat mirror
 
-Inside a plugin, `plugins/<name>/.apm/` is the **only** hand-edited source for **plugin content** — the skills, agents, commands, instructions, extensions and hooks a host discovers. Everything in a plugin root that mirrors an `.apm/` primitive, plus both `plugin.json` manifests, is generated:
+`plugins/<name>/.apm/` is the only hand-edited source for plugin content. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `plugins/<name>/hooks/hooks.json`, and both `plugin.json` manifests are generated — nothing marks them as generated, so check the path before you edit. An edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
 
-- `scripts/sync-plugin-content.sh` generates the flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories and the merged `plugins/<name>/hooks/hooks.json` (ADR-0017)
-- `apm pack` generates both per-plugin manifests — `plugins/<name>/.claude-plugin/plugin.json` and `plugins/<name>/.github/plugin/plugin.json` — and **two of the three** root marketplace manifests: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file) (ADR-0015)
-- `scripts/sync-marketplace-mirror.sh` generates the third, `.github/plugin/marketplace.json` — Copilot CLI's legacy manifest path. **No apm output profile targets it**: apm ships exactly two marketplace output profiles, `claude` and `codex` (documented in `plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`). The mirror is a byte-identical copy of `.claude-plugin/marketplace.json`, gated by the `check-marketplace-mirror-sync` pre-push hook. Do not expect `apm pack` to refresh it — that assumption is exactly the drift this pair exists to prevent
+Not everything in a plugin root is generated. `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` and per-plugin extras are hand-authored there with no `.apm/` source — edit those in place. The rule is per-path, not per-directory. But a file placed *inside* a mirrored directory is deleted on the next sync (`sync_dir` runs `rm -rf` before every copy), so plugin-root documentation goes in `docs/`, never in `hooks/` or `skills/`.
 
-**A plugin root is not wholly generated.** Material that is not an `.apm/` primitive is hand-authored there and no compiler touches it: `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, plus per-plugin extras like `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/`. Edit those in place — they have no `.apm/` source, and looking for one wastes a search. The rule is per-path, not per-directory: `plugins/<name>/skills/` is generated, `plugins/<name>/docs/` is not. `docs/spec/architecture.md` carries the same carve-out.
+`.mcp.json` is hand-authored but it is **not** outside apm. MCP is a first-class apm primitive, and a plugin's `.mcp.json` is how this repo declares one: apm reads the `mcpServers` pointer in the generated `.github/plugin/plugin.json`, resolves it to `.mcp.json`, and injects the result into that package's `dependencies.mcp` when a consumer installs it. Declare MCP servers there and **never** in the plugin's own `apm.yml` — that arms a per-package gate this repo cannot satisfy (`LESSONS.md`, 2026-09-12).
 
-One qualification: "hand-authored, untouched" holds only at the plugin *root*. A file placed **inside** a mirrored directory is destroyed — `sync_dir` runs `rm -rf "$dst"` before every copy, so a `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted on the next sync whether or not `.apm/` has a counterpart. Put root-level plugin documentation in `docs/`, never in a mirrored directory.
-
-Nothing labels a generated file as generated — `plugins/kyberforge/skills/forge/SKILL.md` is byte-identical to its `.apm/` original, with no marker in either. Check the path before you edit. An edit to the mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook, which is the earliest anyone finds out. Details in `docs/spec/architecture.md`.
+Full model: `docs/spec/architecture.md`.
 
 ## Prefer plugin skills over raw shell
 
-This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint tooling directly, check whether an installed skill already owns the operation — it usually does:
+This repo dogfoods its own plugins. Before shelling out, check whether a skill already owns the operation — it usually does:
 
 - Commits, branches, history, worktrees, remotes → `git-commits`, `git-branches`, `git-history`, `git-worktrees`, `git-remotes`
 - Pre-commit hook install/config/troubleshooting → `pc-run` / `pc-author`
@@ -31,40 +29,29 @@ This repo dogfoods its own plugins. Before shelling out to git, gitea, or lint t
 - Vale prose linting → `vale-config` / `vale-run`
 - This repo's own AGENTS.md → `agentsmd-author` / `agentsmd-audit`
 
-Use the bare, **unnamespaced** names above. Under the old `claude plugin install` these were `git:git-commits`, `kyberforge:skill-audit`, and so on; `apm install` deploys each skill to `.claude/skills/<name>/` as a plain project skill, which has no plugin prefix to carry. The `<plugin>:` form has not stopped resolving here, though — `~/.claude.json` still enables `core`, `git`, `gitea`, `kyberforge`, and `lint` at **user** scope, and ADR-0018 left those native installs in place on purpose, converting them being a separate decision with a blast radius beyond this repo. Every skill is therefore live under both names right now, and a working `gitea:gitea-prs` is the user-scope copy answering — not evidence that the apm install or this file is broken, and not something to "fix". Prefer the bare name anyway: apm deploys it, an external consumer installing holocron through apm gets it, and it is the form that survives those user-scope installs eventually being converted. The namespaced form also still resolves in any project that installs holocron natively, so a skill body written for both audiences should name the bare skill. Same for agents: `git-orchestrate`, not `git:git-orchestrate`.
+Use the bare, **unnamespaced** names. That is what `apm install` deploys and the only form this repo's own install produces — a project skill has no plugin to prefix (ADR-0018). Whether the `<plugin>:` form (`gitea:gitea-prs`) also resolves depends on native plugin installs at user scope, outside this repo; write the bare name either way.
 
 Fall back to raw shell only when no skill covers it.
 
-## Setup and testing
+## Session rules
 
-- Run `apm install` to deploy this repo's own skills and agents into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, not authoring source — `plugins/<name>/.apm/` remains the only place to edit. The six dependencies in root `apm.yml` resolve from the holocron **remote**, unpinned against the default branch, so a `.apm/` edit is not visible to the running session until it is pushed and `apm update` re-runs (`apm install` deploys from `apm.lock.yaml` and does not re-resolve refs). Needs the network, and needs `apm_modules/` (which it materializes) left gitignored. `apm install` also configures the `obsidian` MCP server into the repo's `.mcp.json`, carried over from `plugins/bin/.mcp.json`.
-- Do not add repo-owned keys to `.claude/settings.json`. apm treats that file as its own deployed artifact: `apm audit --ci` replays the install into a scratch tree and diffs, so anything apm would not have written there — an `enabledPlugins` block, a real `hooks` entry — is permanent drift that fails the `apm-audit-ci` pre-push hook. Its committed content is whatever apm last wrote, which today is the merged `SessionStart` entry for kyberforge's `check-apm-current.sh` — apm's own output, and it belongs in the commit (ADR-0019). What does not change is that nothing repo-authored goes in the file. A hook you want in this repo is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written here. The file is also **excluded from `pretty-format-json`** in `.pre-commit-config.yaml` — the sixth and last alternation in that `exclude:` pattern, and the only one there for a reason other than "generated manifest". Mind which number you are quoting: six alternations, expanding to sixteen real files (3 root marketplace manifests, 2 per plugin × 6 plugins, plus this one). `pretty-format-json --autofix` sorts object keys while apm emits insertion order, so leaving the file in that hook's scope rewrites apm's output on the way into every commit and `apm audit --ci` then reports permanent drift on a file with an empty `git diff`. Do not tidy it out of that list; it is load-bearing (see `LESSONS.md`, 2026-08-14). Machine-specific settings go in the gitignored `.claude/settings.local.json`, which apm does not deploy and the replay does not compare; shared enforcement belongs in `.pre-commit-config.yaml`.
-- Keeping the install current is automatic but not free. Because the six dependencies are unpinned, deployed skills go stale whenever anyone merges. kyberforge ships a `SessionStart` hook that runs `apm outdated` at startup (~0.7s) and, when something is behind, runs `apm update --yes` and asks the host to re-scan skills (~10.4s). That rewrites `apm.lock.yaml`, so an unexplained modification to it after opening a session is expected, not a bug — commit or discard it deliberately. Note `apm install` alone will **not** pick up remote changes; it deploys from the lock. `apm update` is the command that re-resolves refs.
-- Install git hooks via `pc-run`, wiring all three stages — this repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits) and `pre-push` (the 14-hook gate described below).
-- Install the `apm` CLI — four pre-push hooks shell out to it: `apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). `apm-marketplace-check` and `apm-pack-check-clean` are bare `apm …` hook entries and `apm-audit-ci` is a `bash -c` loop calling `apm` once per package, so without it the push dies with an unhelpful "command not found". Use `apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`.
-- Install `jq` — required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push. These at least fail loudly (`Error: jq is required but not installed`).
-- Install `python3` — required by `scripts/skill-size-check.sh`, the `skill-size-check` pre-commit hook. It measures the *folded* `description` value: most descriptions here are `>`-block scalars, so a regex over the raw lines measures indentation and newlines instead of the value. Missing it fails the hook with an install pointer rather than skipping the ADR-0020 checks, which would be a vacuous green. In practice it is already present — pre-commit is itself a Python application. **PyYAML is a hard requirement too**, not an optional accelerator: the hand-rolled fallback frontmatter reader has been removed, because a reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured, which is the exact vacuous-green failure the `python3` check exists to avoid. `pip install pyyaml` if the hook reports it missing.
-- That hook enforces **two independent gate families** over `plugins/*/.apm/skills/*/SKILL.md`, and neither replaced the other. The agentskills.io spec backstop is unchanged: 500 lines and 2,770 words, counted over the **whole file including frontmatter**. ADR-0020 adds a context budget measured differently — `description` 250 chars SUGGESTION / 400 FAIL (it is preloaded into every session whether the skill fires or not), **body-only** word count 600 SUGGESTION / 900 FAIL (everything after the frontmatter's closing `---`), a missing, valueless or `null` `description:` (a hard FAIL, not a skip — a gate that declines to measure the one preloaded field reports green), every boundary-clause routing target resolving to a real skill or agent, and every `references/<file>.md` a body names actually existing. Target resolution walks up **from the file being checked** to an authoring root — the nearest ancestor holding `plugins/*/.apm/{skills,agents}`, falling back to the nearest `.git`, in two passes so a nested `.git` cannot beat a real monorepo root. The universe is then every skill and agent under `<root>/plugins/*/`, plus the checked file's own apm package and whatever that package declares in its own `apm.yml` `dependencies.apm`; the **root** manifest's `dependencies:` block is not read, and no plugin here declares a cross-plugin apm dependency. Deployed `.claude/`/`.agents/` trees are consulted only when the walk found no plugin monorepo root — whether it landed on a bare `.git` ancestor or on nothing at all (the consumer case). The gate keys on which of the two passes matched, not on whether the root contributed any new name: a single-plugin monorepo re-collects its own package and adds nothing, so a name-count test reads zero there and would drag the deployed trees back into the universe. That matters because those trees are gitignored `apm install` output: resolution used to reach the four cross-plugin `gitea-*` → `git-*` targets through `.claude/skills/` alone, so the same commit measured 2 dangling targets on a developer machine and 6 on a fresh clone. It no longer does — verified by running the hook over a tree holding only `plugins/` and the root `apm.yml`, which reports findings identical to the working tree (26 description / 9 body / 2 dangling / 0 missing references / 58 SUGGESTIONs). Three further checks are SUGGESTION-only: a description with no boundary clause at all, a `## Gotchas` section with more than five entries, and a `## Gotchas` section over 25% of the body. A file can sit well inside one family and fail the other. The hook is `verbose: true` so the SUGGESTION tier is audible — pre-commit prints nothing at all for a passing hook, and a SUGGESTION deliberately does not fail. `skill-audit`'s `validate.sh` holds a second copy of the four ADR-0020 constants; `tests/test-skill-size-check.sh` asserts the copies agree.
-- **Those ADR-0020 gates ship hot, with no baseline file.** 26 of 39 descriptions and 9 of 39 bodies currently exceed their FAIL tier, so editing one of those skills *for any reason* means retrofitting it to the contract first — a one-line fix to `gitea-prs` cannot be committed until that skill complies. This is deliberate, and the retrofit is tracked as Gitea issue #99. Check where a skill stands before starting: `pre-commit run skill-size-check --all-files`.
-- **A second gate ships hot alongside it, and `skill-size-check` will not warn you about it.** `Kyberforge.CompositionNote` — the ADR-0020 Vale rule banning composition and architecture prose from a description — currently fires **10 errors across four skills**: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Every Vale rule here is `level: error` with no ignorable tier, so touching any of those four means fixing its prose findings as well as its size findings. Scoping a retrofit off `skill-size-check` output alone will leave you blocked at the second gate. Check both: `pre-commit run --all-files`.
-- Install the `vale` binary — required by the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks. Their `files:` patterns are `.apm/`-scoped: `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` and `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$`. Only the authoring source triggers them — a `SKILL.md` in the generated mirror matches neither pattern, so prose findings surface only when you edit the file you are supposed to be editing. Without the binary the hooks fail with a bare "command not found" and no install pointer. `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or see https://vale.sh/docs/vale-cli/installation/. No `vale sync` needed — the `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (see ADR-0014).
-- `vale` is also a **pre-push** dependency, not only pre-commit. `check-vale-style-sync` runs six glob-coverage probes by invoking `vale --config` — they are the only assertions in it that catch a `.vale.ini` glob typo, the failure mode where every text-level check stays clean while vale lints zero files. Missing `vale` is therefore a hard failure there. The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and it is **not** `SKIP=`: the hook still runs and still asserts everything verifiable from file text, but the six probes do not, and its summary says so explicitly — `Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified`. Use it only on a machine that genuinely cannot install `vale`, and read that summary line as "the glob axis was not checked", not as a pass.
-- Run `bash tests/run-tests.sh` before considering any change done — it runs every `test-*.sh` script in the repo plus the bats suite (`--bats-only` for just bats). First run auto-initializes the bats submodules; no manual `git submodule update` needed.
-- A suite that exits 77 because a dependency is missing is reported as SKIPPED, and does **not** fail an ad-hoc run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent), where a skip **does** fail the push: at pre-push a skip means one of the dependencies above is absent on this machine, so the gate would otherwise report success having run fewer suites than it appears to. Without vale, for instance, three suites skip (`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh`) and the strict failure names each one and what to install.
-- `tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats` file deleted from the worktree but still tracked in the index fails the run rather than silently shrinking the suite. Remove one with `git rm` (or stage the deletion) when the removal is intentional; an untracked new `.bats` file is picked up and needs no ceremony. Both discovery walks (`tests/run-bats.sh` and `tests/run-tests.sh`) exclude `apm_modules/`: `apm install` materializes a full copy of every plugin there, and running a dependency's copy of a `.bats` file breaks its relative path to the bats helpers — 167 spurious failures before the exclusion landed.
-- Pushing runs 14 repo-defined pre-push hooks, not just the test suite — `run-tests` and `check-manifests`, plus generated-content drift gates (`check-plugin-content-sync`, `check-marketplace-mirror-sync`, `check-vale-style-sync`, `check-scope-walkup-sync`, `check-executables-allow-sync`), artifact validators (`check-apm-agents-valid`, which runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md`), apm's own gates (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`), host validators (`validate-plugins`, `validate-marketplace`, both needing the `claude` CLI), and `check-release-needed`. `check-executables-allow-sync` is the odd one in that first group — it guards a silent failure rather than drift in generated text. apm gates a package's `hooks/` and `bin/` on an exact `<package>#<version>` lookup in root `apm.yml`'s `executables.allow`, with no wildcard and no version-less form, so bumping `plugins/kyberforge/apm.yml`'s `version:` without bumping the key errors nowhere: the entry simply stops matching, kyberforge's `SessionStart` hook stops deploying, and the install goes quietly stale — the failure ADR-0019 records as live. Run `pre-commit run --hook-stage pre-push --all-files` locally — one command, the whole gate. That command reports **16**, not 14: pre-commit's own `meta` hooks, `check-hooks-apply` and `check-useless-excludes`, declare no `stages:` and so run at every stage including this one.
-- `apm-audit-ci` runs `apm audit --ci` once per manifest — the root one and each of the six plugin packages — because the root-only invocation audits the marketplace manifest and **nothing else**, and `apm-pack-check-clean` does not parse plugin `dependencies:` blocks either (verified: a malformed one passes `apm pack --check-versions --check-clean --dry-run` and fails `apm audit --ci` in that package's directory). It verifies two things and claims no more: each `apm.yml` parses as a valid APM manifest, and any package declaring dependencies has a consistent `apm.lock.yaml`. It does **not** enforce an org policy — apm discovers one from the git remote and only understands github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints `No org policy found at unknown; enforcement skipped`. Do **not** "fix" that with `policy.fetch_failure_default: block` in `apm.yml`: it was tested and rejected, because with no reachable policy source it makes the hook exit 1 on every push forever.
-- `check-apm-agents-valid` derives its expected agent-file set from `git ls-files` (same pattern as `tests/run-bats.sh`), so an agent file deleted from the worktree but still tracked fails the run, and discovering zero agent files is an error rather than a pass. An untracked new agent file is still validated — the derivation is one-directional on purpose, so uncommitted work is not blocked but also cannot bypass the gate. Agents take the ADR-0020 description gates (`agent-audit`'s `validate.sh` holds its own copy of those two constants) and, deliberately, **no** body word gate: an agent body becomes the system prompt of a fresh context rather than competing with the caller's live conversation, so the 900-word FAIL does not transfer. A bats test pins that absence in `agent-audit`'s validator — adding a body gate there contradicts the ADR rather than fixing an inconsistency. Be precise about the scope of that guarantee, though: it holds for the **validator**, not for the shared script. `scripts/skill-size-check.sh` applies its body gate to whatever path it is handed, and `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 `apm-orchestrate` (1,080). 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.
-- **Two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s `marketplace.packages[]` contains exactly one remote entry (`mattpocock-skills`, `source: mattpocock/skills`), and resolving it needs a `git ls-remote`. `apm-marketplace-check` resolves every entry and is `always_run`, so it fails with `No cached refs (offline)`. `apm-pack-check-clean` (`apm pack --check-versions --check-clean --dry-run`) re-resolves the same entry and fails with `Error: Git network timeout during ls-remote`. Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes. `--offline` rescues neither. To push without a network, skip both using pre-commit's own mechanism: `SKIP=apm-marketplace-check,apm-pack-check-clean git push`. Skip those two alone — verified under `unshare -rn`, the other twelve pre-push hooks pass offline because they are real local checks (`check-executables-allow-sync` landed after that run, but reads two local manifests and makes no network call), and adding one of them to `SKIP` disarms it silently. `apm-audit-ci` calls `apm` too but stays local: its org-policy discovery resolves nothing on this remote before any network call, so it does not join the pair above.
-- Author commits with `git-commits` — it validates Conventional Commits (enforced at `commit-msg`) for you.
+- **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.
+- **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.
+- **This repo and Gitea are the only source of truth.** All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check `docs/adr/` for an existing decision.
 
 ## Key documents
 
-Read CONTEXT.md at the start of every session in this repo.
+Read `CONTEXT.md` at the start of every session — it is this repo's domain glossary, and the terms it defines are used unglossed everywhere else. It is not exhaustive: terms it does not carry are defined at their point of use, mostly in `docs/spec/`.
 
 Read these on demand:
 
-- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model
+- `README.md` — prerequisites, install, and test commands
+- `docs/VISION.md` — the phased roadmap and where this is going; read when a decision turns on product direction
+- `LESSONS.md` — patterns that went wrong once; read before repeating a class of change that has burned the repo before
+- `docs/spec/gates.md` — what each pre-commit and pre-push hook enforces and why; read when a gate fails or before changing hook config
+- `docs/spec/architecture.md` — directory structure, install pipeline, provider model
 - `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes
 - `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
 - `docs/research/ai-coding-factory/ai-coding-factory-principles.md` — factory design rationale; read when implementing, auditing, or reviewing skills or factory structure

CONTEXT.md

@@ -1,106 +1,240 @@
 ---
 name: AI Development Repo
-description: Domain language and decisions for the global AI development config repository
+description: The domain language of the global AI development config repository
 ---
 
-# Context
+# AI Development Repo
 
-## Principles
+The bounded context of this repo is **how agent instructions are authored, packaged, distributed, and
+kept small**. Terms here name concepts specific to that problem. Mechanics live elsewhere:
+`docs/spec/architecture.md` for structure, `docs/spec/gates.md` for enforcement, `docs/adr/` for
+decisions.
 
-### CLAUDE.md index model
-`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `~/.agents/AGENTS.md` via `@~/.agents/AGENTS.md` and appends Claude Code-specific additions (`@import` for governance.md, content index). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0003.
+## Language
 
-### Instruction file format
-`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
+### Context cost
 
-### Repo/gitea as source of truth
-All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, and `docs/VISION.md`. Everything needed to orient is here.
+**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: ADR-0020. Its
+**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
 
-Before answering any design or architecture question, check for existing decisions: `docs/adr/` (hard architectural decisions).
+**Skill context contract**:
+The ADR-0020 authoring rules that hold the preload tax and body size down — a description carries a
+trigger clause, at most one capability clause, and a boundary clause, and nothing else. Thresholds
+and the target-resolution walk: `docs/spec/gates.md`.
+_Avoid_: skill budget, size limit
 
-## Glossary
+**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
 
-### Management Application
-A separate product (separate repo) for browsing, editing, and configuring AI development configs through a proper product UI. Git is the persistence layer, invisible to the user. The app is repo-agnostic — it works with any git repo that follows these conventions. This repo is the canonical default content (the official starter). See `docs/VISION.md` for the phased roadmap.
+**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
+self-contained `references/` file. Exemplar: `apm-workflow`.
+_Avoid_: router body, thin body
 
-### Skills
-Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Authored at `plugins/<plugin-name>/.apm/skills/<skill-name>/SKILL.md` and reaching a host by one of two install paths: `apm install`, which deploys the skill directory to `.claude/skills/<skill-name>/` (this repo's own path — see "apm-consumed install"), or `claude plugin install <name>@<marketplace>`, which caches the whole plugin (still supported for external consumers). Skills are self-contained — they cannot reference files outside the plugin directory after install-time caching. The two paths name skills differently: apm deploys a plain project skill (`skill-audit`), a plugin install namespaces it (`kyberforge:skill-audit`).
+**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. 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
 
-### Preload tax
-The always-on context cost of every installed skill's `name` + `description`, which sit in the agent's context from the first token of every session whether or not the skill is invoked. Measured 2026-08-14 against base commit `f9b919d` at 23,427 chars (~5,900 tokens) across 39 skills, plus 1,325 chars for 4 agents. Method, so it can be re-run: sum `len(name) + len(description)` over each `plugins/*/.apm/skills/*/SKILL.md` frontmatter with `>` block scalars folded to the value the host loads, at ~4 characters per token. Non-routing frontmatter (`metadata.source_keys`, `category`, `version`) is **not** part of it — the model-visible skill listing carries only `name` and `description`, which supersedes `LESSONS.md:63` on this host. Bodies are not part of it either; they are charged on invocation.
+**Delegation discipline**:
+The agent-side counterpart to the dispatch body. A plugin-scope agent is a single `.agent.md` file
+with no sibling `references/` directory, so it cannot disclose to itself — it can only delegate to
+skills. Its characteristic defect is therefore restatement, not length.
+_Avoid_: agent hygiene
 
-### Skill context contract
-The authoring rules that hold the preload tax and body size down, set by ADR-0020. A description carries a trigger clause, at most one capability clause, and a boundary clause of the form `Not <thing> → <skill-name>` naming a resolvable target — nothing else. "Resolvable" is decided by walking up *from the file being checked* to an **authoring root** — the nearest ancestor holding `plugins/*/.apm/{skills,agents}`, falling back to the nearest `.git`, in two passes so a nested `.git` cannot outrank a real monorepo root. The universe is then every skill and agent under `<root>/plugins/*/` (sibling plugins resolve against each other, which is what a monorepo means), plus the checked file's own apm package and that package's own declared `dependencies.apm`. The **root** manifest's dependency list is never consulted, and no plugin here declares a cross-plugin apm dependency. Deployed `.claude/`/`.agents/` trees count only when there is no authoring root at all — the consumer case. The property this buys is that one commit gets one verdict: those trees are gitignored `apm install` output, so resolving through them made the same commit report 2 dangling targets on a developer machine and 6 on a fresh clone, which a gate shipping hot with no baseline cannot do. A `${BASH_SOURCE}`-relative repo root is the other half of the same defect and is gone — it leaked this repo's 39-skill universe into consumer repos running the hook through pre-commit. A *missing* boundary clause is a SUGGESTION rather than a failure, for skills and agents alike — some skills genuinely have no near-miss sibling. A *missing or empty description* is the opposite: a hard FAIL in all three validators, because a gate that merely declines to measure the one preloaded field reports green. Capability enumeration, output formats, and composition notes ("composes X rather than duplicating Y") belong in the body or `README.md`; a description that summarises workflow is a correctness hazard, not just a cost, because agents act on it instead of reading the body. Sizes are two-tier and sit *below* the agentskills.io spec limits, which stay unchanged as conformance backstops: description 250 SUGGESTION / 400 FAIL (spec 1,024); body 600 SUGGESTION / 900 FAIL (spec 2,770 words / 500 lines). Conflating the quality gate with the spec ceiling is what let `skill-author` and `agent-author` grow to within twelve words of 2,770.
+### Distribution
 
-### 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 self-contained `references/` file. Named for `apm-workflow` (421-word body, 3,006 words of references), which arrived at it independently and is the repo's exemplar. Its absence was the characteristic defect at the time ADR-0020 was written: `skill-author` inlined both its create and improve flows, and `agent-author` carried 50-60 lines marked inapplicable by their own headers on any single run. Both were retrofitted to dispatch tables in the change that carries the ADR — `skill-author` went 2,623 body words to 595 and `agent-author` 2,582 to 616 — so they are now worked examples of the pattern rather than counter-examples of it. The 39-skill corpus at large is not: 9 bodies still exceed the 900-word FAIL (issue #99).
+**Skill**:
+A reusable slash command defined as a `SKILL.md` file following the
+[Agent Skills open standard](https://agentskills.io), authored at
+`plugins/<plugin>/.apm/skills/<skill>/SKILL.md`.
+_Avoid_: command, prompt, macro
 
-### Hand-invoked skill
-A skill reached only by typing its slash command, declared with `disable-model-invocation: true`. The host withholds it from the model-visible skill listing entirely, so it pays no preload tax and its `description` becomes human-facing text rather than a trigger list. `zoom-out` is the worked example: apm passes the flag through verbatim to both install paths, and the skill is absent from the router while `/zoom-out` still works. Choosing model-invoked vs. hand-invoked is the first question `skill-author` asks, because it determines whether a description needs triggers at all.
+**Plugin**:
+The deployable unit — one or more skills, agents, hooks, commands, and MCP servers bundled into a
+single installable directory under `plugins/<name>/`, compiled from that plugin's `.apm/` source.
+_Avoid_: package, bundle, module
 
-### Delegation discipline
-The agent-side counterpart to the dispatch body. A plugin-scope agent is a single `.apm/agents/<name>.agent.md` file with no sibling `references/` directory, so it cannot disclose to itself — it can only delegate to skills. Its characteristic defect is therefore restatement, not length: an agent body that spells out a procedure a skill it can invoke already owns creates a second copy that drifts. `agent-audit` fails that, with the fix being "invoke `<skill>` instead". Agents take the same description gates as skills but no body word gate — a skill body competes with the caller's live conversation, an agent body becomes the system prompt of a fresh context.
+**apm package**:
+The unit apm builds and installs — `plugins/<name>/apm.yml` plus the hand-authored
+`plugins/<name>/.apm/` tree it compiles from (ADR-0015).
+_Avoid_: plugin directory, source tree
 
-### Plugin
-The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. In this repo, plugins live under `plugins/<name>/`, each with its own `apm.yml` + `.apm/{skills,agents,hooks,...}` — this is the authoring source of truth for the plugin's content (ADR-0015). Two categories of tracked output are compiled from that source, never hand-edited: `.claude-plugin/plugin.json` (Claude Code) and `.github/plugin/plugin.json` (Copilot CLI) via `apm pack`/`apm compile`; and, alongside them, a flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/` directory mirror at the plugin root plus a merged hooks file at `hooks/hooks.json`, generated by `scripts/sync-plugin-content.sh` — Claude Code's and Copilot's installers convention-scan only these flat paths (`hooks/hooks.json` is the convention path for hooks specifically; a root-level `hooks.json` is scanned by nothing and is deleted as stale by a sync — see ADR-0017's 2026-08-14 amendment) and have no awareness of `.apm/` nesting at all, so this mirror is what actually makes `.apm/` content discoverable at install time (ADR-0017). Plugins are copied to a cache on install — they cannot reference files outside their own directory. Install a plugin with `claude plugin install <name>@<marketplace>`, or consume it as an apm dependency (see "apm-consumed install").
+**Content mirror**:
+The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and
+merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that
+plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017).
+_Avoid_: generated copy, duplicate tree
 
-### Plugin marketplace
-A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) is **compiled output** of `apm pack`, generated from the root `apm.yml`'s `marketplace:` block (owner, build/output config, versioning strategy, and the `packages:` list of installable plugins) — it is not hand-edited. See ADR-0015. `.github/plugin/marketplace.json` is Copilot CLI's legacy manifest path; apm has no output profile for it (only `claude` and `codex`, and `codex`'s is a differently-shaped file at `.agents/plugins/marketplace.json`), so `scripts/sync-marketplace-mirror.sh` keeps it byte-identical to `.claude-plugin/marketplace.json`, checked at pre-push. Each listed package's `source:` still points at that plugin's own `plugins/<name>/` root, not at an `apm pack` build artifact — which is why that root also carries the flat `agents/`/`skills/`/`commands/`/`hooks/hooks.json` content mirror described under "Plugin" (ADR-0017): without it, an install from this marketplace finds a valid manifest but no discoverable content.
+**Output profile**:
+An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
+(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
+`.agents/plugins/marketplace.json`), and none for `.github/plugin/marketplace.json` (Copilot CLI's
+legacy path), which a sync script mirrors instead. Mechanics: `docs/spec/architecture.md`.
+_Avoid_: build target, export format
 
-### apm-consumed install
-How this repo installs its own plugins, as of 2026-08-14: not `claude plugin install <name>@holocron`, but six `dependencies.apm` entries in the root `apm.yml`, each a `git:`/`path:` object against the holocron remote, deployed by `apm install` into `.claude/skills/` and `.claude/agents/`. Project scope only — apm installs nothing at user scope, so the switch is contained to this repo and any other repo opts in by declaring its own dependencies. The git+path object form is deliberate over the shorter `<name>@holocron` marketplace alias: an alias must first be registered with `apm marketplace add`, which writes to `~/.apm/marketplaces.json` (user scope, outside the repo), whereas the object form needs nothing beyond the committed manifest and so survives a fresh clone.
+**Plugin marketplace**:
+A Git repository carrying a `marketplace.json` manifest that lists installable plugins. There is no
+backend, registry, or SaaS — the Git repo is the marketplace.
+_Avoid_: registry, store, catalogue
 
-Four consequences, each load-bearing:
-- **Skills gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also answers to `git-commits`. The `<plugin>:` form has not stopped resolving here: `~/.claude.json` still enables `core`, `git`, `gitea`, `kyberforge`, and `lint` at user scope, which ADR-0018 left in place deliberately — converting them is a separate decision with a blast radius beyond this repo. Until it is taken, every skill is live under two names, which is the same "present twice under two names" outcome ADR-0018's own "Alternatives considered" rejected for *keeping both install paths* — reached here by leaving user scope alone rather than by adopting it as the install model. Write the bare name regardless: apm deploys it, and a repo consuming holocron through apm gets only that form. The namespaced form still resolves wherever holocron is installed natively, so cross-audience skill bodies should use the bare name.
-- **apm owns `.claude/settings.json`.** `apm audit --ci` (an `apm-audit-ci` pre-push hook) replays the install into a scratch tree and diffs it against the worktree, so any key apm would not have written is permanent drift. Committed content is exactly `{"hooks": {}}`; repo-owned settings have nowhere to live in that file.
-- **Install output is gitignored.** `.claude/skills/`, `.claude/agents/`, and `apm_modules/` are all regenerated by `apm install`. `apm.lock.yaml` and the generated `.mcp.json` are committed. Committing the deployed skills would add a third mirror of the same content to the two ADR-0017 already governs.
-- **Test discovery must skip `apm_modules/`.** It holds a full copy of every plugin, `.bats` files included; both `tests/run-bats.sh` and `tests/run-tests.sh` exclude it.
+**holocron**:
+This repository, in its role as a plugin marketplace and as the remote the six plugin dependencies
+resolve against.
+_Avoid_: the marketplace, upstream
 
-Dependencies are unpinned against the default branch, matching the `autoUpdate: true` the native marketplace install had. The practical cost is a round trip: an edit to `plugins/<name>/.apm/` is invisible locally until it is pushed and `apm install` re-runs, because the dependency resolves from the remote rather than from the working tree beside it.
+**apm-consumed install**:
+How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root
+`apm.yml` deployed by `apm install`, rather than `claude plugin install <name>@holocron`. Its
+consequences: ADR-0018.
+_Avoid_: apm install, dependency install
 
-### HITL (human-in-the-loop)
-Agent pauses before a consequential action; human approves before execution. Required for irreversible or high-stakes actions (architecture changes, production deployments, security configuration). The agent drafts the change plan and waits — it does not proceed autonomously. Contrast with HOTL.
+**Provenance chain**:
+The three-stage traceability record linking a skill back to its research inputs: `/research` produces
+topic docs and a `sources.md`; the author skill records which sources informed which files in
+`references/sources.md` and `source_keys` frontmatter; `skill-audit` validates the chain is complete
+and internally consistent.
+_Avoid_: sources, citations, attribution
 
-### HOTL (human-on-the-loop)
-Agent acts; human monitors and can intervene after the fact. Acceptable for low-stakes, bounded, reversible actions where the cost of pausing for approval exceeds the blast radius of an error. The distinction between HITL and HOTL must be explicit and documented — defaulting to HOTL for convenience is not acceptable.
+### Governance
 
-### Sycophancy
-The failure mode where RLHF-trained models prioritise approval over accuracy. Treated as a first-class reliability risk: models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Designing against sycophancy is an explicit obligation, not a quality-of-life concern. Countermeasures: explicit pushback resistance instructions, prompting for dissent, cross-validating against independent sources. Never interpret AI agreement as AI accuracy.
+**HITL** (human-in-the-loop):
+The agent pauses before a consequential action and a human approves before execution. Required for
+irreversible or high-stakes actions — architecture changes, production deployments, security
+configuration.
+_Avoid_: manual approval, gated action
 
-### AGENTS.md
-The provider-agnostic always-on instruction entry point. Two files:
-- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules); imported by repo `CLAUDE.md` via `@AGENTS.md`.
-- **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects; deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`.
+**HOTL** (human-on-the-loop):
+The agent acts and a human monitors, able to intervene after the fact. Acceptable only for
+low-stakes, bounded, reversible actions where the cost of pausing exceeds the blast radius of an
+error.
+_Avoid_: autonomous, unsupervised
 
-Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0003.
+**Sycophancy**:
+The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct
+answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a
+first-class reliability risk, not a quality-of-life concern.
+_Avoid_: agreeableness, people-pleasing
 
-### Skill composition
-A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `apm-workflow`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` had no audit counterpart and got no recheck; their terminal check was `claude plugin validate`. Both were deprecated per ADR-0015, superseded by `apm-workflow`, and deleted entirely once issue #90 landed.
+### Documents
 
-### Provider-agnostic issue tracker
-Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0007). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it).
+**AGENTS.md**:
+The provider-agnostic always-on instruction file, in plain markdown with no provider-specific syntax
+(ADR-0003). Two exist: repo-level, and the global `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`.
+_Avoid_: instructions file, system prompt
 
-### Provenance chain
-The three-stage traceability record linking a skill back to its research inputs: (1) `/research` produces topic docs and a `sources.md` in `plugins/<plugin>/docs/research/docs/<topic>/`; (2) `/skill-author` reads those docs and records which sources informed which skill files in `references/sources.md` (including a `Research doc:` back-pointer to the upstream research file) and `source_keys` frontmatter on `SKILL.md` and `references/*.md`; (3) `skill-audit` validates the chain is complete and internally consistent via `validate-provenance.sh`. A skill with research input but no `references/sources.md`, or with `source_keys` that don't match `references/sources.md` slugs, has a broken provenance chain.
+**Thin adapter**:
+A provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`)
+that imports its `AGENTS.md` and adds only that provider's syntax, carrying no original always-on
+content of its own (ADR-0002, ADR-0003).
+_Avoid_: wrapper, shim, provider file
 
-### Bidirectional reference principle
-Files that reference other files should declare those references explicitly. The referencing file carries the forward reference (e.g. content index in `CLAUDE.md`, `references:` in frontmatter). The referenced file carries a `when:` field describing when it is loaded. Both sides should agree — divergence signals staleness. The reverse map ("what files reference this file?") is derived by a reference scanner script, not maintained manually. This principle applies to instruction files, skills, and workflow documents.
+**LESSONS.md**:
+The long-loop feedback log for patterns observed across sessions, at the repo root.
+_Avoid_: changelog, retro, postmortem
 
-### agentsmd-author / agentsmd-audit
-A skill pair in the `core` plugin for writing, updating, and reviewing a repo's `AGENTS.md` file(s) — the generic open-standard file (see the `AGENTS.md` entry above), including this repo's own. `agentsmd-author` creates/updates AGENTS.md content, supports nested monorepo placement (per the standard's nearest-file-wins precedence), and closes out by invoking `agentsmd-audit` inline. `agentsmd-audit` runs a single combined pass checking three mandatory baselines: secrets/credentials (governance.md hard prohibition — AGENTS.md is committed content), structural completeness (common-sections checklist from the agents.md spec), and accuracy/drift (do referenced commands and paths actually resolve against the repo). `agentsmd-audit` never inspects provider adapter files (see `provider-adapter-author`) — its scope is AGENTS.md content only. Chosen over folding this into `kyberforge` because kyberforge's scope is meta-tooling for the holocron marketplace itself, not generic target-repo documentation; `core` is the intended home for cross-cutting, repo-agnostic utility skills.
+**Management Application**:
+A separate product in a separate repo for browsing, editing, and configuring AI development configs
+through a product UI, with Git as an invisible persistence layer. Repo-agnostic; this repo is its
+canonical default content. Roadmap: `docs/VISION.md`.
+_Avoid_: the UI, the dashboard, the app
 
-### provider-adapter-author
-A companion skill (`core` plugin) that detects a target repo's provider-specific instruction file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) and, where it duplicates content AGENTS.md should own, converts it into a thin adapter that imports AGENTS.md — mirroring this repo's own ADR-0002/ADR-0003 two-tier adapter pattern. Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`: checks for an import reference, no duplicated headings, size threshold) rather than a separate paired audit skill — the check is mechanical, so a script suffices per governance.md's "prefer deterministic code for repeatable tasks." `agentsmd-author` calls this skill via skill composition when it detects an existing provider file with overlapping content.
+### Quality
 
-### lint plugin
-A standalone, repo-agnostic plugin (`plugins/lint/`) for configuring and running linters — not scoped to kyberforge's own meta-tooling. First linter is Vale (prose style linting), split into two skills per the git/gitea per-concern pattern: `vale-config` (setup — `.vale.ini`, `StylesPath`, styles) and `vale-run` (invoke Vale, interpret/report findings). A `lint-runner` agent composes these for isolated-context lint sweeps; it is report-only **by instruction, not by capability** — its body states "You never edit files" and "Do not edit, fix, or rewrite any flagged content", but nothing enforces that. It previously carried `tools: Bash, Read, Grep, Glob`, which withheld `Edit` outright; plugin-scope APM agents cannot express a `tools:` field at all (ADR-0016 — `apm compile` copies frontmatter verbatim to both Claude Code and Copilot, whose `tools:` vocabularies are incompatible, so a value correct for one harness is wrong for the other), so `plugins/lint/.apm/agents/lint-runner.agent.md` now declares only `name`/`description`/`source_keys` and inherits every tool, `Edit` included. ADR-0016 accepted this loss of enforcement knowingly; the restriction survives as prose the agent is expected to follow. Vale's research docs (`docs/research/docs/vale/`) moved from `plugins/kyberforge/` to `plugins/lint/` to keep the provenance chain same-plugin.
+**Skill composition**:
+A skill calling another skill by name to delegate a sub-task — the caller owns the orchestration
+decision ("when to do X"), the callee owns the mechanics ("how to do X").
+_Avoid_: chaining, nesting, sub-skill
 
-### Vale audit prefilter (skill-audit / agent-audit)
-Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension (ADR motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it doesn't live in `plugins/lint/` — but per ADR-0014 it also doesn't live at the repo root anymore. Two copies live inside `plugins/kyberforge/`, one per skill, since a plugin's cache-install only copies each skill's own files (no cross-skill sharing): `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/` is canonical (`.vale.ini` plus a custom `Kyberforge` style covering description-opener banning ("This skill/agent..."), vague-capability wording ("helps with", "utilize", ...), and generic "see references/ for details" padding — and a `KyberforgeCopilot` style scoped only to `.agent.md` files for the Copilot-only "Use proactively has no effect" check), and `plugins/kyberforge/.apm/skills/skill-audit/assets/vale/` is a smaller duplicate (`Kyberforge` only, scoped to `SKILL.md`) kept in sync by `scripts/check-vale-style-sync.sh` (pre-push). A root-level `.pre-commit-hooks.yaml` exposes both copies (plus `skill-size-check`) so any external repo can enforce the same rules via `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml` — pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the `kyberforge` plugin is installed at all, and the same mechanism covers CI (`pre-commit run --all-files`). This repo's own `vale-audit-prefilter-skill`/`-agent` pre-commit hooks consume the identical plugin-bundled copies via `repo: local` (not a third root copy, and not a pinned self-reference — a pinned self-reference would lint working-tree edits against the last tagged release rather than the change being made). Every rule is `level: error` and every alert is a FAIL — no ignorable tier, same as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on `error` alerts alone, so `warning`/`suggestion` rules exit 0 and pre-commit swallows the output of a passing hook, leaving them invisible and blocking nothing. `MinAlertLevel` and `--minAlertLevel` are correspondingly absent from `.vale.ini` and the hook, being no-ops under this model. Vale covers the pattern-matchable sub-checks named in issue #84 (imperative opener, vague filler, `Use proactively`, generic reference-pointer padding) plus, per ADR-0013, one body-wide prose-pattern check ("There is/are" sentence openers) — everything else about body discipline (defaults-vs-menus, why-rationale, non-pattern-matchable judgment calls), near-miss exclusion strength, and control calibration stays LLM judgment.
+**Vale audit prefilter**:
+The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Description dimension,
+so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`.
+_Avoid_: linting, style check
 
-Both skills' Step 1, and the `vale-audit-prefilter-skill`/`-agent` pre-commit hooks, call each copy's own `scripts/vale-wrap.sh` rather than `vale` directly — a workaround for a confirmed Vale 3.15.2 limitation (see `vale-config`'s Gotchas): `text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions. Verified by reproduction, not assumed: `>` folded scalars, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars all yield 0 alerts and exit 0 on a deliberately-bad fixture, while a `|` literal block spanning the same 2+ lines lints normally (alerts fire, exit 1). The wrapper flattens those three broken forms to one physical line in a scratch copy (padding with blank lines so every other line number is unchanged) before handing off to real `vale`; `|` literal blocks and single-line descriptions pass through untouched, already linting correctly. The plain and quoted forms previously passed silently — unflattened and unmatched — so a bad description in either sailed through the prefilter. Handed no `--config` at all, the wrapper falls back to its own sibling `assets/vale/.vale.ini`, located from `${BASH_SOURCE[0]}` rather than from the cwd — which is why both manifests' `entry:` is now the bare script path with no argument after it. pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`), so every later argument resolves against the *consuming* repo's root: a `--config` in `.pre-commit-hooks.yaml` pointed at a path no consumer has and hard-failed every external run with `E100 [--config] Runtime error`. `.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical — the local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was* this repo, and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. An explicit `--config` still wins, in all three argv forms (`--config X`, `--config=/abs`, `--config=rel`), and a relative one still resolves against the caller's cwd, matching bare `vale`, not the repo root. Both audit skills' Step 1 now passes no `--config` either: it resolves the script relative to the skill's own directory so the call works from an installed plugin cache, but a relative `--config` alongside it would still resolve against the cwd, yielding `E100 Runtime error ... does not exist` and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. `tests/test-vale-wrap.sh` regression-tests this against skill-audit's copy specifically (its fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has that glob section). Each `.vale.ini`'s section globs are path-agnostic (`[**/SKILL.md]` for skill-audit's copy; `[**/agents/*.md]`/`[**/*.agent.md]` for agent-audit's) and do no scoping on their own: Vale's `*` crosses `/`. Scoping comes from each pre-commit hook's own `files:` regex and from the audit skills passing one explicit file per invocation. The two manifests scope differently on purpose: this repo's `.pre-commit-config.yaml` pins its own layout — `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` for `-skill`, `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` for `-agent` — while the shipped `.pre-commit-hooks.yaml` stays layout-agnostic for external consumers whose skills live anywhere, using `(^|/)SKILL\.md$` and `(^|/)agents/[^/]+\.md$|\.agent\.md$`. Both manifests split the prefilter into two hooks precisely because one combined hook pointed at only one copy would silently 0-file-skip the other file type. A `SKILL.md` outside `plugins/` (e.g. project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted normally — the globs constrain filename shape, not location. Vale reports 0 files only when the path it is handed matches no glob section at all: a differently-named file, or a directory argument holding nothing that matches. That run prints `✔ 0 errors ... in 0 files.` and exits 0, indistinguishable from a clean pass, so both audits treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment.
+**Authoring root**:
+The directory a gate resolves against — the nearest ancestor of the file being checked holding
+`plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding
+`.git`. The walk: `docs/spec/gates.md`.
+_Avoid_: repo root, project root
 
-This scope expands per ADR-0013: one cherry-picked low-noise `write-good`/`alex` rule landed in `styles/Kyberforge`, `Kyberforge.SentenceOpenerThereIs` (22 held-out hits, both in-corpus hits clean rewrites, zero suppressions). A second, `Kyberforge.VagueQualifier`, was cherry-picked and then deleted: 2 hits across the skill/agent corpus as it stood at the time of that measurement (2026-08-08, before the `.apm/` restructure), one marginal and one an unfixable false positive (`caveman/SKILL.md` quotes `of course` as an example of filler — a mention, not a use) that forced the repo's only Vale suppression comments. A third, `Kyberforge.CompositionNote`, landed with ADR-0020 and bans architecture and composition prose from a description; it is `level: error` like the rest, and it currently fires 10 times across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`, so `pre-commit run --all-files` is red on prose as well as on size until issue #99 lands. Also new is a sibling pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), which carries **two independent gate families that must not be conflated** (see "Skill context contract"). The agentskills.io spec backstop is `MAX_LINES=500` and `MAX_WORDS=2770`, both inclusive and both counting the **whole file including frontmatter** (2,770 is a word-count proxy for the 5,000-token limit, calibrated to the densest prose measured in this repo — 1.81 tokens per word — so even a worst-case `SKILL.md` at the ceiling stays under 5,000 tokens; it is not a percentile of the corpus). ADR-0020 adds a context budget measured differently: description characters 250 SUGGESTION / 400 FAIL, **body-only** words 600 SUGGESTION / 900 FAIL, plus deterministic checks that every boundary routing target resolves, that a body's named `references/<file>.md` all exist, and — SUGGESTION-tier — that a boundary clause is present at all, that `## Gotchas` holds at most five entries, and that it stays under 25% of the body. `skill-audit/scripts/validate.sh` and `agent-audit/scripts/validate.sh` hold their own copies of the shared constants and `tests/test-skill-size-check.sh` asserts the copies agree, so a `SKILL.md` can no longer pass its own audit yet be blocked by the commit hook. Agents take the description gates and no body word gate. `python3` **and PyYAML** are hard requirements — the earlier hand-rolled frontmatter fallback is gone, because a fallback that silently mis-parses a scalar shape reports a vacuous pass. Scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` only, same as `vale-audit-prefilter-skill`, so it never lints `docs/research/examples/` reference skills. It's also exposed in the root-level `.pre-commit-hooks.yaml` as `kyberforge-skill-size-check` — it has no external asset dependency, so it needed no relocation, only exposure to external consumers. File scope (`SKILL.md` + agent files) and enforcement model (rules land directly in `styles/Kyberforge`, blocking immediately, no trial tier) stay unchanged; governance.md/CONTROLS.md were evaluated and excluded as rule sources (nothing prose-pattern-matchable to mine). House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block — Vale skips code spans and fences, so no suppression is needed; inline `<!-- vale Rule = NO -->` (HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown) is the fallback only where backticking is impossible.
+**Near-miss**:
+A query that shares keywords with this skill but needs a different one — and, by extension, the
+sibling that would wrongly answer it; boundary clauses exist to exclude genuine near-misses rather
+than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`.
+_Avoid_: overlap, similar skill
 
-### LESSONS.md
-Long-loop feedback log for patterns observed across sessions. Three or more entries on the same pattern graduate to the relevant standing file (e.g. a coding convention, a governance rule). Updated by the session-handoff skill or directly by the human. Lives at the repo root.
+**Vacuous green**:
+A check that reports success because it measured nothing — zero files scanned, an unparsed value read
+as empty, a conditional branch that never armed.
+_Avoid_: false pass, clean run
+
+**Issue**:
+The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker
+(ADR-0007), but skills say "linked issue" generically rather than naming a provider.
+_Avoid_: ticket, card, task
+
+## Relationships
+
+- A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**;
+  **holocron** is this repo wearing that hat.
+- Every model-invocable **Skill** pays the **Preload tax**. A **Hand-invoked skill** does not — which
+  is the first question to settle when authoring one.
+- The **Skill context contract** bounds both the **Preload tax** (description) and the body.
+  A **Dispatch body** is how a skill stays inside it; **Delegation discipline** is how an agent does.
+- **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates
+  nothing.
+- **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact
+  type to the matching author skill — an already-specified fix (file, line, and change known) calls
+  that author skill directly, because each routing hop re-derives instructions from a shorter brief
+  and has been observed to drop hard constraints handed down the chain.
+- **HITL** and **HOTL** are exclusive per action class, and the choice must be explicit and
+  documented. **Sycophancy** is why HOTL is not the safe default.
+- A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken.
+- **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern
+  into the relevant standing document.
+
+## Example dialogue
+
+> **Dev:** "This one only fires when someone types the slash command. Does its description still need
+> trigger words?"
+> **Maintainer:** "No — that's a **hand-invoked skill**. The host withholds it from the model-visible
+> listing, so it pays no **preload tax** at all and the description is human-facing text."
+> **Dev:** "Then the body can be as long as it needs to be?"
+> **Maintainer:** "Different budget. The **skill context contract** gates the body whether or not the
+> skill is model-invoked — the description competes with every other skill's description, the body
+> competes with the caller's live conversation. Four mutually exclusive flows means a **dispatch
+> body**: table in `SKILL.md`, one `references/` file per flow."
+> **Dev:** "And if I split it into an agent instead?"
+> **Maintainer:** "Then you're in **delegation discipline** territory. An agent has no `references/`
+> to disclose to, so the failure mode flips — it stops being length and starts being restatement of
+> a procedure some skill already owns."
+
+## Flagged ambiguities
+
+- "skill" was used for both the authored `SKILL.md` under `plugins/<name>/.apm/skills/` and the
+  deployed copy under `.claude/skills/` — resolved: the authoring source is the **Skill**; the
+  deployed copy is gitignored `apm install` output and is never edited.
+- Skills can answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), depending on
+  whether a native install exists at user scope alongside the apm one (ADR-0018) — resolved: write
+  the bare name, which is the only form `apm install` produces.
+- "context" means both the model's live token window (the **Preload tax** sense) and the bounded
+  domain this file describes — resolved: unqualified "context" in this repo means the token window.
+- "audit" was used for both an author skill's inline closeout and `forge`'s independent
+  clean-context recheck — resolved: these are two distinct layers, kept separate precisely because
+  an audit running in the same context as the work it checks shares that work's blind spots.

LESSONS.md

@@ -1,8 +1,8 @@
 # Lessons
 
-Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule.
+Patterns observed during development of this repo. Three or more entries on the same pattern → promote to `docs/spec/architecture.md` (or the relevant instruction file) as a standing rule.
 
-**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
+**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `docs/spec/architecture.md` for structural and domain-level principles — `CONTEXT.md` is not a destination, its `## Principles` section was deleted and what was there now sits under that file's "AGENTS.md pattern" and "Reference conventions" headings — `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
 
 **Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
 
@@ -10,6 +10,14 @@ Patterns observed during development of this repo. Three or more entries on the
 
 ---
 
+## 2026-09-12 — "Not an `.apm/` primitive" was read as "not an apm primitive", and the review that followed was wrong
+
+`AGENTS.md` and `docs/spec/architecture.md` both listed `.mcp.json` alongside `README.md`, `docs/` and `bin/` as plugin-root material "hand-authored with no `.apm/` source". That is literally true — nothing under `.apm/` produces MCP config — but it reads as "apm has no MCP concept", and a review of PR #132 drew exactly that conclusion and recommended moving the declaration into the plugin's `apm.yml` under `dependencies.mcp`. The recommendation was wrong twice over. It arms `lockfile-exists` in the per-package `apm audit --ci` that the `apm-audit-ci` hook runs in every `plugins/*/`, which then demands the package's whole deployed tree inside the package directory: 93 missing files and 79 drifted paths on `plugins/gitea`. And it was unnecessary, because the `.mcp.json` route already reaches `dependencies.mcp` through the `mcpServers` pointer in the generated Copilot manifest, env references intact.
+
+Two process lessons, not one. First, when a doc says a file is not a primitive **of a specific subsystem**, say which subsystem and what the file actually is instead — the negative claim alone invites the wrong generalisation. Second, the three scratch installs that produced the wrong conclusion all used local `./path` dependencies, where apm skips the plugin-normalisation step that injects `.mcp.json`. The repo consumes its plugins as `git:` + `path:` objects. A scratch test that does not reproduce the real dependency form can invert the result, so reproduce the form, not just the shape.
+
+---
+
 ## 2026-05-17 — Workflow documents should prescribe sub-agent usage, not just allow it
 
 When writing workflow documents (like `docs/notes/skill-implementation-workflow.md`), the natural tendency is to describe steps at a high level and leave sub-agent usage as an implementation detail. But if the workflow doesn't explicitly prescribe "spawn a sub-agent here," practitioners default to doing everything in the main context — accumulating token cost and losing the isolation benefit. Fix: make sub-agent usage a named step in the workflow, specifying what the agent receives, what it returns, and why it's isolated. This makes the workflow reproducible rather than dependent on the practitioner remembering to use agents.
@@ -26,7 +34,7 @@ Issue files frequently referenced "the workflow defined in `docs/notes/skill-imp
 
 The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context.
 
-**Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read CONTEXT.md at the start of every session in this repo," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change.
+**Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read `CONTEXT.md` at the start of every session," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change.
 
 ## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity
 
@@ -60,29 +68,21 @@ write-eval's process requires presenting the full test plan and waiting for user
 
 The write-skill authoring standard required 8 body sections including Role and When/When not. These were assumed to be agentskills.io requirements. Checking the actual spec revealed the body has no format restrictions at all — recommended sections are step-by-step instructions, examples, and edge cases. Role and When/When not were added by convention without verifying the standard. Fix: before encoding any requirement as part of an authoring standard, check the upstream spec directly. The agentskills.io spec also confirmed that negative triggers belong in the description field — not in a separate body section — which eliminates a persistent duplication pattern across all skills.
 
-## 2026-05-18 — Provenance fields in frontmatter are loaded on every skill scan
-
-Fields like `source:`, `references:`, `version:`, `updated:`, and `when:` in SKILL.md frontmatter are loaded at agent startup alongside `name` and `description` for every installed skill. None of these are used for routing or runtime execution — they are audit and upgrade-cycle records. Loading them at startup violates progressive disclosure and wastes tokens proportional to the number of installed skills. Fix: move all non-routing frontmatter to a separate `META.md` file in the skill directory. Frontmatter keeps only `name`, `description`, `metadata.category`, and `allowed-tools` (when applicable) — the four fields the spec actually uses for routing and discovery.
-
 ## 2026-05-18 — Copy-fill is more deterministic than generate for structured skill artifacts
 
-When a skill produces a structured artifact like SKILL.md, the natural approach is to generate it from internalized rules in the Process section. But this means section structure is only as reliable as the agent's instruction-following under token pressure. Copy-fill (copy the template to the target path, then fill in content) separates structure from content: the template mechanically enforces section order and presence, freeing the Process section to focus only on sequencing constraints (what order to decide things) rather than also policing structure. Side benefit: the template is a human-usable artifact that can be adopted independently of the skill. Fix applied in write-skill refactor: SKILL-TEMPLATE.md and META-TEMPLATE.md are the authoritative structure sources; the Process section no longer contains a body structure constraint — the template handles it.
+When a skill produces a structured artifact like SKILL.md, the natural approach is to generate it from internalized rules in the Process section. But this means section structure is only as reliable as the agent's instruction-following under token pressure. Copy-fill (copy the template to the target path, then fill in content) separates structure from content: the template mechanically enforces section order and presence, freeing the Process section to focus only on sequencing constraints (what order to decide things) rather than also policing structure. Side benefit: the template is a human-usable artifact that can be adopted independently of the skill. Fix applied in write-skill refactor: SKILL-TEMPLATE.md is the authoritative structure source; the Process section no longer contains a body structure constraint — the template handles it.
 
 ## 2026-05-17 — HITL gap: agent delegates confirmation to permission system
 
 The agent-level HITL rule ("require explicit confirmation before irreversible shared-state operations") is being bypassed: the agent calls the tool and lets the permission dialog catch it. This means the rule is not firing in agent reasoning — it's the permission system acting as a safety net. If a user selects "don't ask again," the net disappears. Fix: the HITL rule needs to be framed as "do not call the tool" rather than "ask before proceeding" — the agent must ask first, then act only after explicit confirmation.
 
-## 2026-05-26 — META-TEMPLATE uses YAML comments; META.md output retains them
-
-META-TEMPLATE.md uses YAML `#` comments to explain fields inline. SKILL-TEMPLATE.md uses HTML comments inside XML tags, which the agent strips on fill. The structural difference means SKILL.md output is clean but META.md output retains the explanatory `#` lines — an inconsistency. Fix (deferred): restructure META-TEMPLATE.md so all explanatory guidance is prose above the code block (markdown, never copied into the output YAML), and the code block itself uses `<placeholder>` syntax with no `#` comment lines. This makes META.md fill behaviour deterministic for the same reason SKILL.md fill is: `<...>` markers are unambiguously replaceable; prose above the block is not part of the template. Do not apply until the human/copy-fill tradeoff is resolved — see 2026-05-26 session discussion.
-
 ## 2026-05-26 — Overlap checks must scan the deployed directory, not just the source repo
 
 `write-a-skill` existed only in `~/.agents/skills/` (installed from a pre-refactor source) and was invisible during a repo-level scan of `.agents/skills/`. Governance reviews and overlap checks that only look at the source repo will miss skills added by install.sh from other sources or prior runs. Fix: overlap checks must scan the deployed `~/.agents/skills/` directory, not just the repo's `.agents/skills/`.
 
-## 2026-05-26 — `model:` field belongs in SKILL.md frontmatter, not META.md
+## 2026-05-26 — `model:` field belongs in SKILL.md frontmatter, not a sidecar file
 
-Claude Code supports `model:` as a provider extension in SKILL.md frontmatter — it overrides the session model for the skill's turn and reverts after. Attempting to put it in META.md was wrong: META.md is provenance/audit metadata, not runtime config. The boundary: if a field affects agent behaviour at invocation time, it belongs in SKILL.md frontmatter; if it serves upgrade reviews and audit trails, it belongs in META.md.
+Claude Code supports `model:` as a provider extension in SKILL.md frontmatter — it overrides the session model for the skill's turn and reverts after. Attempting to move it out to a provenance sidecar was wrong: a sidecar is audit metadata, not runtime config. The boundary: if a field affects agent behaviour at invocation time, it belongs in SKILL.md frontmatter.
 
 ## 2026-05-26 — Research agents present synthesis as spec fact
 
@@ -126,7 +126,7 @@ Two forks independently fixed `references/sources.md` with different approaches
 
 ## 2026-06-28 — Implementation agents must invoke /skill-author, not write skill files directly
 
-When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in META.md. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/.apm/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run.
+When briefing an agent to implement a new skill, the instinct is to tell it to write the SKILL.md and supporting files directly. This bypasses Step 5 of the skill-author process (provenance), which requires reading all research `sources.md` files and recording every `extracted` slug in the skill's own `references/sources.md`. The `validate-provenance.sh` script catches the gap — but only after the commit, requiring a fix round. This pattern recurred twice in one session (plugin-author and marketplace-author initial implementation, then again in the first round of fix agents). Fix: briefs for implementation agents must explicitly say "invoke `/skill-author` (read and follow `plugins/kyberforge/.apm/skills/skill-author/SKILL.md`)" — not "write the skill files." Invoking the skill is the only reliable way to ensure all process gates, including provenance, run.
 
 ## 2026-07-05 — Repo root is a bare checkout; work happens in worktrees only
 

README.md

@@ -0,0 +1,142 @@
+# holocron
+
+The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments.
+
+Content ships as six installable plugins, each an apm (Agent Package Manager) package. This repo consumes its own plugins through apm, so the working copy runs the same released content every other consumer gets.
+
+## Repo layout
+
+| Path | What it holds |
+| --- | --- |
+| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets |
+| `providers/claude-code/` | Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh` |
+| `core/` | Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/` |
+| `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes |
+| `scripts/` | Install, sync, and check scripts used by the git hooks |
+| `tests/` | `run-tests.sh`, `run-bats.sh`, the `test-*.sh` suites, and the bats submodules |
+
+The six plugins:
+
+- **kyberforge** — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace
+- **git** — conventional commits, branches, history, submodules, worktrees, remotes, pre-commit hook authoring and running (`pc-author` / `pc-run`), and an interactive router (`git-workflow`)
+- **gitea** — issues, pull requests, labels, milestones, releases, branches, files, and an interactive router (`gitea-workflow`)
+- **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it
+- **lint** — configuring and running linters
+- **bin** — cross-cutting workflow skills not yet split into a focused plugin: research, documentation, TDD, prototyping, triage, diagnosis, architecture review, requirement grilling, compressed output (`caveman`), and re-orienting mid-task (`zoom-out`)
+
+## Prerequisites
+
+Install all of these before setting up. Each one is a hard dependency of a git hook or a script — several fail with an unhelpful "command not found" if missing.
+
+| Tool | Why | Install |
+| --- | --- | --- |
+| `apm` CLI | Four pre-push hooks shell out to it (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` via `scripts/sync-plugin-content.sh`) | The `apm-install` skill, or `curl -sSL https://aka.ms/apm-unix \| sh`. Verify with `apm --version` |
+| `jq` | Required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push | Your package manager |
+| `python3` + PyYAML | Required by `scripts/skill-size-check.sh` (the `skill-size-check` pre-commit hook), which reads folded YAML frontmatter | `python3` is usually present — pre-commit is itself a Python application. `pip install pyyaml` if the hook reports PyYAML missing |
+| `vale` | Required by the `vale-audit-prefilter-skill` / `-agent` pre-commit hooks and the `check-vale-style-sync` pre-push hook | `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or https://vale.sh/docs/vale-cli/installation/ |
+| `claude` CLI | Required by the `validate-plugins` and `validate-marketplace` pre-push hooks | Claude Code |
+| `go` toolchain | The gitea MCP server runs as `go run gitea.com/gitea/gitea-mcp@v1.7.0`, resolved from `PATH`. Without it the server fails to start and every `gitea-*` skill loses its tools | https://go.dev/dl/ — verify with `go version` |
+
+The gitea MCP server additionally needs two environment variables in the shell that launches your agent — referenced as `${GITEA_ACCESS_TOKEN}` and `${GITEA_HOST}` in `plugins/gitea/.mcp.json`, with apm passing those references through to the deployed config unexpanded so the values are resolved at server startup and never committed. Copy `plugins/gitea/.env.example` to `.env` at the repo root, fill in real values, then export it — nothing in this repo auto-loads a `.env` file:
+
+```bash
+cp plugins/gitea/.env.example .env
+$EDITOR .env
+set -a; source .env; set +a
+```
+
+Generate the token in Gitea under Settings, Applications. Scope it to the repositories you want the agent to reach. If the server starts but every call returns an authorization error, that token is the first thing to check.
+
+Two notes worth reading before you skip one:
+
+- **PyYAML is a hard requirement, not an optional accelerator.** The hand-rolled fallback frontmatter reader was removed deliberately: a reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured.
+- **No `vale sync` is needed.** The `Kyberforge` styles are committed under `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded packages (ADR-0014).
+
+## Setup
+
+Run these in order, from the repo root.
+
+```bash
+# 1. Deploy this repo's own skills and agents
+apm install
+
+# 2. Install the git hooks — all three stages
+pre-commit install -t pre-commit -t commit-msg -t pre-push
+```
+
+**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`.
+
+**Git hooks** must be wired for **all three stages**. This repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain `pre-commit install` silently skips `commit-msg` (Conventional Commits) and `pre-push` (the full gate) — the `-t` flags above are not optional. The `pc-run` skill handles this and the troubleshooting around it, if you would rather not remember the flags.
+
+## Keeping the install current
+
+The six dependencies in root `apm.yml` are unpinned against the default branch, so deployed skills go stale whenever anyone merges. kyberforge ships a `SessionStart` hook that runs `apm outdated` at startup (~0.7s) and, when something is behind, runs `apm update --yes` and asks the host to re-scan skills (~10.4s).
+
+That rewrites `apm.lock.yaml` — an unexplained modification to it after opening a session is expected, not a bug. Commit or discard it deliberately.
+
+Note the difference between the two commands:
+
+- `apm install` deploys from `apm.lock.yaml`. It does **not** pick up remote changes.
+- `apm update` re-resolves refs. This is the command that pulls in a merged `.apm/` edit.
+
+## Running tests
+
+```bash
+bash tests/run-tests.sh              # every test-*.sh script plus the bats suite
+bash tests/run-tests.sh --bats-only  # just bats
+```
+
+The first run auto-initializes the bats submodules; no manual `git submodule update` needed.
+
+A suite that exits 77 because a dependency is missing is reported as SKIPPED and does **not** fail an ad-hoc run. It *does* fail under `--strict` (equivalently `RUN_TESTS_STRICT=1`), which is how the pre-push hook invokes it — at pre-push, a skip means one of the prerequisites above is absent on this machine, and the gate would otherwise report success having run fewer suites than it appears to. The strict failure names each skipped suite and what to install.
+
+## Before pushing
+
+Run the pre-push gate locally in one command:
+
+```bash
+pre-commit run --hook-stage pre-push --all-files
+```
+
+One caveat: `check-release-needed` is a silent no-op under this invocation. It exits 0 unless
+`PRE_COMMIT_REMOTE_BRANCH` is `refs/heads/main`, and pre-commit exports that only from the real
+pre-push git hook during an actual `git push` — so the hook reports `Passed` having checked nothing.
+Every other pre-push hook does run.
+
+See [`docs/spec/gates.md`](docs/spec/gates.md) for what each hook enforces and why.
+
+**Offline?** Exactly two pre-push hooks need the network, because root `apm.yml`'s marketplace contains one remote package entry that must be resolved with `git ls-remote`:
+
+```bash
+SKIP=apm-marketplace-check,apm-pack-check-clean git push
+```
+
+Skip **only** those two. The remaining pre-push hooks are real local checks and pass offline; adding one of them to `SKIP` disarms it silently.
+
+## Editing plugin content
+
+`plugins/<name>/.apm/` is the only hand-edited source for plugin content — skills, agents, commands, instructions, extensions, and hooks. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `hooks/hooks.json`, and every `plugin.json` / `marketplace.json` manifest are generated. Nothing labels a generated file as generated, so check the path before you edit; an edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
+
+Hand-authored material that is *not* an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` — lives at the plugin **root** and is untouched. Never place such a file inside a mirrored directory: the sync removes the destination before every copy, so it is deleted with no drift report.
+
+Full detail in [`docs/spec/architecture.md`](docs/spec/architecture.md).
+
+## For external consumers
+
+Install a plugin natively from the marketplace manifests:
+
+```bash
+claude plugin install <name>@holocron
+```
+
+Or consume the packages through apm, the way this repo does — declare them as `dependencies.apm` git+path entries against the holocron remote and run `apm install`.
+
+## Where to go next
+
+- [`AGENTS.md`](AGENTS.md) — the rules for AI agents working in this repo
+- [`CONTEXT.md`](CONTEXT.md) — domain language; read at the start of every session here
+- [`docs/spec/architecture.md`](docs/spec/architecture.md) — directory structure, install pipeline, provider model
+- [`docs/spec/gates.md`](docs/spec/gates.md) — the enforcement gates in depth
+- [`docs/adr/`](docs/adr/) — architectural decisions; read before proposing structural changes
+- [`docs/VISION.md`](docs/VISION.md) — where this is going
+- [`LESSONS.md`](LESSONS.md) — things that went wrong once and should not again

apm.yml

@@ -1,5 +1,5 @@
 name: holocron
-version: 0.4.2
+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.2:
       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.2
+  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.2
       category: Developer Tools
 
     - name: bin
-      description: A place for things to be binned
+      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.3
+      version: 1.1.7
       category: Utilities
 
     - name: git
-      description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.
+      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.3
+      version: 1.3.7
       category: Version Control
 
     - name: gitea
-      description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.
+      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.4
+      version: 1.3.8
       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/0007-gitea-canonical-issue-tracker.md

@@ -18,4 +18,4 @@ Three alternatives were rejected. Keeping the file-based fallback adds code comp
 
 The file-based model also had a structural weakness: issues in `docs/issues/` were invisible from the Gitea UI, making it impossible to track work, assign milestones, or filter by label without opening the repo locally. Gitea provides all of that natively.
 
-The "Provider-agnostic issue tracker" glossary entry in CONTEXT.md is updated in the same workstream to remove the file-based phase framing. The `providers/gitea/` adapter path described in ADR-0011 was never implemented — Gitea integration runs entirely via MCP, not a provider adapter.
+The "Provider-agnostic issue tracker" glossary entry in CONTEXT.md is updated in the same workstream to remove the file-based phase framing. (Amended 2026-08-17: the CONTEXT.md trim renamed that entry to **Issue**; it still records Gitea as this repo's canonical tracker and still tells skills to say "linked issue" generically.) The `providers/gitea/` adapter path described in ADR-0011 was never implemented — Gitea integration runs entirely via MCP, not a provider adapter.

docs/adr/0013-vale-harness-scope-and-rule-sources.md

@@ -9,6 +9,12 @@ deferred PR #85 review item to broaden that coverage, retroactively captures #84
 (since it was never recorded as a decision in its own right), and layers the expansion on top
 without reversing or weakening the original four rules.
 
+**2026-08-17 amendment.** The CONTEXT.md section named above no longer holds that documentation.
+CONTEXT.md was cut back to a glossary and the prefilter's mechanics — the two-copy style layout,
+`vale-wrap.sh`, the `--config` argv defect, the rule inventory, and the 0-files-means-NOT-RUN
+fallback — moved to `docs/spec/gates.md`. Read that file, not CONTEXT.md, for the harness itself;
+this ADR still owns the scope decision.
+
 **File scope stays the same.** `SKILL.md` plus agent files (`**/agents/*.md`,
 `**/*.agent.md`) only — matching the existing prefilter's globs. Skill-level
 `README.md` files and `plugin.json` manifests are not added: README.md files are navigational, not

docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md

@@ -56,6 +56,10 @@ new hand-maintained manifest format.
   that work through to merge.
 - `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries were rewritten in issue #90 to
   describe the compiled-output model directly, rather than carrying a forward-pointer to this ADR.
+  Superseded 2026-08-17: CONTEXT.md was cut back to one-line definitions, and the compiled-output
+  model is now described in `docs/spec/architecture.md`. The same trim deleted the "lint plugin"
+  entry cited under Considered options below; that pointer now reads `docs/spec/architecture.md`'s
+  plugin scope table, which carries the repo-agnostic-versus-marketplace-specific argument.
 
 ## Considered options
 
@@ -66,7 +70,7 @@ maintenance in place unchanged.
 
 **New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge`
 specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific
-(see `CONTEXT.md`'s "lint plugin" entry) — the same argument applies to a generic `apm` CLI
+(see `docs/spec/architecture.md`'s plugin scope table) — the same argument applies to a generic `apm` CLI
 wrapper. The shipped `apm-install`/`apm-workflow` skills are, in fact, generic, repo-agnostic APM
 CLI documentation with no holocron-specific content, so a standalone `plugins/apm/` would have
 been a defensible split on artifact content alone. Rejected anyway, in favor of `kyberforge`,

docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md

@@ -329,7 +329,9 @@ mirror does carry, and is reported.
   stands; this ADR fixes the second, previously-unverified half.
 - `CONTEXT.md`'s "Plugin" and "Plugin marketplace" glossary entries are updated to describe the
   flat mirror as a second compiled-output category, alongside the existing
-  `.claude-plugin/plugin.json`/`marketplace.json` description.
+  `.claude-plugin/plugin.json`/`marketplace.json` description. Superseded 2026-08-17: CONTEXT.md was
+  cut back to one-line definitions and no longer describes either compiled-output category;
+  `docs/spec/architecture.md` is where the mirror is documented.
 - A future apm release that ships a native `.apm/`-aware plugin.json compiler (closing this gap
   upstream) would let `sync-plugin-content.sh` and its drift gate be deleted outright — nothing in
   this ADR's decision depends on the flat mirror existing beyond satisfying the current installer's

docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md

@@ -59,7 +59,9 @@ answers to `git-commits` and `kyberforge:skill-audit` to `skill-audit`. This is
 a project skill has no plugin to prefix. `AGENTS.md` and `CONTEXT.md` are updated to name the bare
 form, which is what apm deploys and the only form a repo consuming holocron through apm gets.
 
-**Correction (2026-08-14): the namespaced form did not stop resolving.** An earlier revision of
+**Correction (2026-08-14): the namespaced form did not stop resolving.** *Superseded by the
+2026-08-17 correction below: the machine state this cites is no longer present. Both are kept
+because the pair is the finding — read neither as current.* An earlier revision of
 this consequence said every `<plugin>:<skill>` reference "was stale the moment the switch landed",
 and `AGENTS.md`/`CONTEXT.md` were written to match. That contradicts the "User scope is untouched,
 deliberately" consequence below, and the contradiction resolves against it: `~/.claude.json` still
@@ -72,6 +74,20 @@ survives those user-scope installs eventually being converted, and the namespace
 resolves for anyone installing holocron natively, so skill bodies written for both audiences
 should name the bare skill.
 
+**Correction (2026-08-17): the evidence under the correction above is gone, and the claim goes with
+it — not to its opposite.** Observed on this machine: `~/.claude/plugins/installed_plugins.json` is
+`{"version": 2, "plugins": {}}`; there is no `enabledPlugins` key anywhere in `~/.claude.json`
+(`grep -c enabledPlugins` returns 0); `~/.apm/marketplaces.json` is `{"marketplaces": []}`. The
+`holocron` entry in `~/.claude/plugins/known_marketplaces.json` survives, but a registered
+marketplace is not an installed plugin. So the user-scope installs the 2026-08-14 correction cited
+are not there, and neither is the state the *original* consequence described before it. The claim
+about the namespaced form has now been written twice off two different observations of the same
+machine, and this ADR has already reversed itself once on it. That is the finding: the fact is
+machine state, not a property of this decision, and it changes without any commit. No instruction
+file — `AGENTS.md`, `CONTEXT.md`, or a skill body — should assert either way whether
+`<plugin>:<skill>` resolves. The rule that survives every observation is the one that was always the
+actionable half: write the bare name, because it is the only form `apm install` produces.
+
 **apm owns `.claude/settings.json`.** (ADR-0019 supersedes the "exactly `{"hooks": {}}`" claim
 below — once a package ships a hook, apm merges it into that file and the merged entry is apm's own
 output. The rule that nothing repo-authored goes in the file is unchanged.) `apm audit --ci` replays the install into a scratch tree and
@@ -117,10 +133,11 @@ pinned `resolved_commit` in `apm.lock.yaml` and does not re-resolve refs (`apm i
 documents this explicitly — "does NOT refresh refs; use 'apm update' for that"). Running it after a
 merge redeploys the same content and reports success.
 
-**User scope is untouched, deliberately.** `bin@holocron`, `gitea@holocron`, and a stale
-`hello-world@holocron` remain natively installed at user scope, and every project other than this
-one still resolves its skills that way. Converting them is a separate decision with a blast radius
-beyond this repo.
+**User scope is untouched, deliberately.** This decision changed project scope only; whatever is
+natively installed at user scope was left alone, and converting it is a separate decision with a
+blast radius beyond this repo. The specific inventory this paragraph used to name
+(`bin@holocron`, `gitea@holocron`, a stale `hello-world@holocron`) is machine state and is stale —
+see the 2026-08-17 correction above. The decision recorded here is unaffected by what that state is.
 
 ## Alternatives considered
 

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 —
-  26 description FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs.
+  with no `.claude/` or `.agents/` anywhere, produced findings identical to the working tree. The
+  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
-`git-orchestrate` (933), `gitea-orchestrate` (1,199) and `apm-orchestrate` (1,080). Agents escape by
+running it directly over `plugins/*/.apm/agents/*.agent.md` exits 1 with 900-word body FAILs on
+`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
-the model-visible skill listing in a live session. It remains invocable as `/zoom-out`.
+at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` was — at the time of that check, when it
+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
-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
+after normalising `skill`/`agent`, where before they were closer. It has kept deepening since: the
+#99 retrofit added `finding-criteria.md` to `skill-audit`, drawing it level with `agent-audit`. Both
+figures move with the next retrofit, so measure rather than quote —
+`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 clause absent (SUGGESTION) | 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 — `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
-alerts across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`
-independently of anything `skill-size-check` reports. Someone scoping the #99 retrofit off the size
-findings alone will fix those and still be blocked. The two gates want fixing together.
+`level: error` like every other rule in that style, so at decision time `pre-commit run --all-files`
+was red on 10 alerts across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and
+`gitea-workflow` independently of anything `skill-size-check` reports. Someone scoping the #99
+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
-#100.
+**Four broken routing targets were found; two were fixed here and two shortly after.** Tracked as
+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.
-  **Live** — the check reports it as a dangling `gitea-labels`.
+  stray space introduced by YAML wrapping mid-token, breaking the skill name in preloaded text. Was
+  **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
-`tests/test-skill-size-check.sh` probes exactly those three by name rather than asserting a count, so
-it degrades to SKIP as #100 lands rather than going stale.
+So the check fired on 3 of the 4 against the base commit and on 2 at the tip of the change that
+carried this ADR. **The corpus dangling set is now empty**, and that is asserted rather than
+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/adr/0021-plugin-descriptions-state-a-domain-boundary.md

@@ -0,0 +1,227 @@
+# A plugin's published description states its domain boundary and never enumerates its skills
+
+Three of this repo's six plugins publish a `description` that lists the skills they ship. That style
+has now failed three times in four days, the third time inside the correction for the second. It is
+enforced by nothing, it obliges a marketplace release on every skill addition, and it was never
+applied to the other three plugins. This ADR retires it: a published description says what the
+plugin is *for*, and the inventory lives where an inventory can be read off the tree.
+
+**Status: accepted (2026-08-17).**
+
+## Context
+
+A plugin's published description is one string authored twice — in `plugins/<name>/apm.yml` and in
+the matching `marketplace.packages[]` entry of the root `apm.yml` — and compiled into four generated
+files per plugin edit: the plugin's `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`,
+plus the repo-wide `.claude-plugin/marketplace.json` and its `.github/plugin/marketplace.json`
+mirror. (`.agents/plugins/marketplace.json`, apm's codex profile, carries no per-package
+`description` or `version` at all and is unaffected.) It is the only text a consumer sees in a marketplace listing before
+installing. It is **not** a SKILL.md `description`: it is never preloaded into an agent's context and
+routes nothing at runtime. ADR-0020 governs that other artifact; this one governs this one. The
+overlap is a finding, not a scope: ADR-0020 established that capability enumeration in a description
+is "a correctness hazard, not only a token cost". The hazard at this layer is different — staleness
+in published metadata rather than an agent shortcutting the body — but the enumeration is the same
+construct and it fails the same way.
+
+Measured at `de84d1b`, the branch tip before this change. Each figure is reproducible from the tree:
+skill counts are `ls plugins/<name>/.apm/skills/ | wc -l`, description text is
+`plugins/<name>/apm.yml`.
+
+| Plugin | Style | Skills | Items enumerated | Skills named | Unnamed |
+|---|---|---|---|---|---|
+| `bin` | enumeration | 11 | 8 | 9 | `caveman`, `zoom-out` |
+| `git` | enumeration | 9 | 8 | 8 | `git-workflow` |
+| `gitea` | enumeration | 7 | 7 | 6 | `gitea-workflow` |
+| `core` | boundary | 3 | — | — | — |
+| `kyberforge` | boundary | 7 | — | — | — |
+| `lint` | boundary | 2 | — | — | — |
+
+Three failures, in order.
+
+**`bb9158d` (2026-08-14) — `core`'s description described `bin`.** The text it deleted read
+"Cross-cutting utility skills for everyday AI-assisted coding — triage, diagnosis, architecture
+review, and session navigation." All four items are real skills and not one of them is `core`'s:
+they are `bin`'s `triage`, `diagnose`, `improve-codebase-architecture` and `zoom-out`. `core` ships
+`agentsmd-author`, `agentsmd-audit` and `provider-adapter-author`, and the published description
+named none of them.
+
+This is the failure the whole style was later adopted against, and it is worth being exact about
+what it was, because the record has been read the other way twice since. It was **wrong content**,
+not an incomplete list. The description was a syntactically perfect, complete, four-item enumeration
+of a real skill set; it just belonged to a different plugin. Enumerating harder could not have caught
+it, and a gate that asked "does every enumerated item exist as a skill?" would have passed it — all
+four did exist. `bb9158d`'s own fix went the other direction: it replaced the enumeration with a
+domain boundary, and `core` has needed no correction since. The precedent set by that commit was
+therefore *boundary*, and the two commits below cite it while doing the opposite.
+
+**`65bac15` (2026-08-17) — `git` advertised `gitea`'s domain, `gitea` advertised a skill that does
+not exist.** `git` read "conventional commits, branch management, pull requests, and feature flow";
+pull requests reach the forge over HTTP and are `gitea`'s, which is the exact boundary
+`docs/spec/architecture.md` draws between the two plugins. `gitea` read "issues, pull requests,
+milestones, releases, and wikis"; `grep -ri wiki plugins/gitea/.apm/` returns nothing and no wiki
+skill has ever existed. Both were repaired by re-enumerating.
+
+**`de84d1b` (2026-08-17) — the re-enumeration was itself incomplete.** `bin`'s "A place for things to
+be binned" was replaced with an eight-item list over eleven skills; `caveman` and `zoom-out` are
+absent. `zoom-out` is the same skill `bb9158d` had called "session navigation" three days earlier
+while deleting it from the wrong plugin's description — named when it was in the wrong place,
+unnamed once it was in the right one. And the miss is not confined to `bin`: `git-workflow` is
+unnamed in `git`'s corrected description, though `65bac15`'s own commit message states it was added
+("omitting pc-author/pc-run, git-submodules and git-workflow"), and `gitea-workflow` is unnamed in
+`gitea`'s. Across the three plugins, 23 of 27 skills are named at the third attempt.
+
+**Nothing checks any of this.** `scripts/check-manifests.sh` does not contain the string
+`description`. The three ADR-0020 validators (`scripts/skill-size-check.sh` and skill-audit's and
+agent-audit's `validate.sh`) gate on SKILL.md and agent frontmatter; they do open `apm.yml`, but only
+to read `dependencies.apm` when resolving the boundary-target universe — none of them reads the
+`description:` key, and their hook globs match `SKILL.md` and `*.agent.md` only. `apm audit --ci`,
+`apm pack --check-clean` and `scripts/sync-plugin-content.sh --check --all` all compare compiled
+output against `apm.yml`, so their entire job is to propagate whatever the description says into
+those four files byte-for-byte and confirm they match. The `wiki` claim passed every one of the fourteen pre-push hooks, every day it
+was published.
+
+**And the obligation is unbounded.** Under enumeration, adding one skill to `bin`, `git` or `gitea`
+means editing two copies of a prose string on top of the version bumps and regeneration any skill
+addition already owes under this repo's release policy
+(`plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`). The bumps are not the
+marginal cost — the prose edit is, and it is the half nothing checks. A skill *rename* triggers the
+same, for a string no consumer can tell went stale. 27 of the repo's 39 skills sat behind
+a description carrying that obligation; the other 12 did not, and their three plugins have generated
+no defect of this class.
+
+### Scope
+
+This decision covers the six plugins this repo authors. The root marketplace also lists
+`mattpocock-skills`, a third-party package whose description is not this repo's to write; its entry
+is out of scope and is left as published upstream.
+
+## Decision
+
+**A plugin's published `description` states the plugin's domain boundary. It does not enumerate the
+skills the plugin ships, by name or by paraphrase.**
+
+- The boundary answers "what kind of work belongs to this plugin, and where is its edge against its
+  nearest sibling" — the question a consumer deciding whether to install is actually asking. It is
+  stable under skill addition, rename and removal, which is the entire point: an artifact that does
+  not change when the tree changes cannot go stale against it.
+- **The boundary must cover everything the plugin actually ships.** A boundary drawn narrower than
+  the contents is the same defect as an incomplete enumeration, one level up, and it is the specific
+  risk in this change. `git` carries `pc-author` and `pc-run`, which are not git operations at all;
+  "Skills for working with Git" silently drops them, so the boundary names the pre-commit hooks
+  explicitly rather than trusting a reader to file them under Git.
+- The two copies — package `apm.yml` and the root `marketplace.packages[]` entry — stay identical.
+  This is already the rule in practice and both prior corrections state why: the root entry is what
+  reaches the compiled marketplace, so fixing only the package manifest leaves it half-propagated.
+- The three descriptions, rewritten here, with `core`/`kyberforge`/`lint` shown for register:
+
+  | Plugin | Published description | Chars |
+  |---|---|---|
+  | `bin` | 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. | 152 |
+  | `git` | 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. | 146 |
+  | `gitea` | 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. | 134 |
+  | `core` | *(unchanged)* Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it. | 101 |
+  | `kyberforge` | *(unchanged)* Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace. | 105 |
+  | `lint` | *(unchanged)* Skills and agents for configuring and running linters. | 54 |
+
+- **No gate is added.** This is a deliberate omission and the reasoning is below, not an item left
+  for later.
+
+### Why no gate
+
+The check enumeration would need — "every skill directory appears in the description" — was writable
+in principle and was never written, including by the two commits that corrected an enumeration by
+enumerating again and had every reason to. It is also only half a check: it
+catches a skill missing from the list, and it cannot catch `wiki`, because "this noun does not name
+any skill" requires a vocabulary of permissible non-skill nouns that no one is going to maintain.
+Under a boundary there is no correspondence left to check, which is the property being bought.
+
+What survives un-gated is `bb9158d`'s actual failure: a boundary that is simply wrong about its
+plugin. That was never machine-checkable in either style — the text was a well-formed description of
+a real plugin — and it is caught by the same review that has to happen when a published,
+consumer-facing string is edited at all. A gate that would catch it needs a declared per-plugin
+skill-to-boundary mapping for the description to be checked against, which is a second artifact
+requiring exactly the per-skill maintenance this ADR exists to delete, relocated one file over.
+
+Two cheap partial gates were considered and rejected in the same breath. Forbidding a comma-separated
+run of three or more noun phrases is a prose heuristic that fires on `lint`'s perfectly good
+"configuring and running linters" class of sentence. Forbidding any string matching a skill directory
+name under `plugins/<name>/.apm/skills/` bans legitimate boundary vocabulary — `git-branches` exists,
+and a `git` boundary has every right to say "branches". Both would be believed, and both would be
+wrong, which ADR-0020 already records as worse than no gate.
+
+## Considered options
+
+**Keep enumeration and gate it.** The only option that makes the current style safe. Rejected on the
+three grounds above: the check is one-directional, it cannot see an invented capability, and it makes
+a marketplace release the consequence of adding a directory. It also hard-couples published consumer
+copy to internal directory names, so a skill rename becomes a version bump on the plugin and on the
+marketplace.
+
+**Enumerate consistently across all six plugins**, on the grounds that the real defect is the split
+style. Rejected: it takes an obligation that has produced three failures on three plugins and applies
+it to six. The measured outcome of the most recent attempt to enumerate carefully, with the defect
+fresh and two prior commits as precedent, is four skills unnamed.
+
+**Cap the description length**, mirroring ADR-0020's 250/400-character tiers, on the theory that a
+short description has no room to enumerate. Rejected because length does not measure correspondence:
+`gitea`'s failing description was 96 characters and asserted a skill that has never existed, while
+`bin`'s 176-character enumeration is under the same cap. All six descriptions here, before and after,
+sit inside ADR-0020's tiers; the tier would have been silent through all three failures.
+
+**Delete the description to a bare name.** Rejected: apm's Claude marketplace mapper emits
+`description` into `marketplace.json`, and it is the only prose a consumer sees before installing.
+
+**Point the description at the plugin's `README.md`.** Rejected: a marketplace listing renders a
+string, not a link — and the README's own plugin list carries the same enumeration with the same
+staleness, so this relocates the defect rather than fixing it.
+
+## Consequences
+
+**Three descriptions are rewritten and the compiled output regenerated.** Eight generated files
+change: `plugins/{bin,git,gitea}/.claude-plugin/plugin.json`,
+`plugins/{bin,git,gitea}/.github/plugin/plugin.json`, `.claude-plugin/marketplace.json` and its
+byte-identical `.github/plugin/marketplace.json` mirror. `.agents/plugins/marketplace.json` (the
+codex profile) is unchanged and correctly so — it carries no per-package `description` or `version`
+field at all, only `name`, `source`, `policy` and `category`.
+
+**Version bumps, all PATCH under the `per_package` strategy:** `bin` 1.1.4 → 1.1.5, `git` 1.3.4 →
+1.3.5, `gitea` 1.3.5 → 1.3.6, `marketplace.version` 0.4.4 → 0.4.5.
+
+**The root `apm.yml` top-level `version:` is restored to lockstep with `marketplace.version`,
+0.4.2 → 0.4.5.** These two fields have moved together in every commit that has ever touched root
+`apm.yml` — 0.3.2, 0.3.3, 0.3.4, 0.4.0, 0.4.1, 0.4.2 in both — until `65bac15` and
+`de84d1b` on this branch bumped `marketplace.version` to 0.4.3 and then 0.4.4 while leaving the
+top-level field at 0.4.2. Lockstep is not folklore: it is stated at
+`plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md`. This is a defect, not a
+style: `apm.yml`'s comment inside the marketplace block records that the top-level `version:` is not inherited into the compiled output
+"despite being used elsewhere (e.g. by `apm audit`)", so the field is live and was silently two
+releases behind what the marketplace published. Closed here rather than tracked, because the
+correction is one line and the drift is three days old.
+
+**`docs/spec/architecture.md`'s plugin table is unchanged and stays a routing table.** It answers
+"where does a new skill go" for someone working *inside* this repo; the published description answers
+"should I install this" for someone outside it. The two now read similarly, and that is not
+duplication to collapse — they have different readers and different lifecycles, and the table already
+says so in its own preamble ("These are routing boundaries, not inventories"). One caveat for whoever
+next edits that page: its closing sentence sends a reader to the published description "for what a
+consumer actually gets", which was true against an enumeration and is now a pointer to a second
+boundary statement. Neither artifact carries an inventory after this change, so that sentence was
+rewritten in the same branch to point at `plugins/<name>/.apm/skills/` and `README.md` instead.
+
+**`README.md`'s plugin bullet list becomes the only place an inventory lives, and it still
+enumerates.** That is deliberate, but it makes the list load-bearing in a way it was not before, so
+its `bin`, `git` and `gitea` bullets were completed in the same branch to name every skill those
+plugins ship. This ADR does not otherwise extend to it: a README is a hand-read document where a
+list of what you get is the useful thing, it is not compiled into four files, and a stale line in it
+costs a reader a moment rather than misrepresenting a published package. The tradeoff that makes
+enumeration wrong in a marketplace manifest is precisely the one that makes it fine there.
+
+**Nothing in the ADR-0020 gate set changes.** Its character and word tiers, its Vale rules and its
+three validators all read `SKILL.md` and `*.agent.md` frontmatter; none of them opens an `apm.yml`.
+The two contracts are adjacent and independent, and a future author retrofitting a skill under
+issue #99 is not touched by this ADR.
+
+**The failure mode this leaves open is a wrong boundary, and it is un-gated by design.** If a fourth
+failure of this class occurs it will be a description that describes the wrong plugin — `bb9158d`'s
+shape, the one enumeration never addressed. That is the trigger to revisit, and the thing to build
+then is a declared skill-to-boundary mapping, not a return to enumeration.

docs/adr/0022-skill-metadata-version-is-mandatory.md

@@ -0,0 +1,78 @@
+# Every skill's `metadata.version` is mandatory, not a per-plugin option
+
+**Status: accepted (2026-09-07).**
+
+## Context
+
+`metadata.version` is optional SKILL.md frontmatter (`create.md`'s "Optional frontmatter" list:
+"uncomment and fill in, or remove entirely"). `skill-author`'s own bump logic was written
+conditionally — "with `metadata.version` present, bump the minor version on create... and the
+patch version on improve" — which only makes sense if presence is a real per-skill choice.
+
+Adoption never followed a rule; it followed the plugin. Of 39 skills, 12 carry a version:
+
+| Plugin | Has it | Total |
+|---|---|---|
+| `core` | 3 | 3 |
+| `gitea` | 6 | 7 |
+| `lint` | 2 | 2 |
+| `git` | 1 | 9 |
+| `bin` | 0 | 11 |
+| `kyberforge` | 0 | 7 |
+
+`core`, `gitea` and `lint` are consistent adopters (`gitea-files` the one gap); `bin` and
+`kyberforge` are consistent non-adopters; `git` has one outlier (`git-commits`, versioned for no
+plugin-specific reason found on inspection — no comment, no cross-reference, nothing distinguishing
+it from its eight siblings). Issue #127 raised this as an undocumented split: two house norms
+coexisting with no stated rule for which applies where, the same class of defect as an unstated
+`rtk`/bare-`git` convention (#113) found in the same audit pass.
+
+## Decision
+
+**Every skill's frontmatter carries `metadata.version`.** It is no longer optional, and no longer a
+per-plugin choice.
+
+- **The 27 skills that never carried one are seeded at `1.0.0`**, not `0.1.0`. `0.1.0` is
+  `skill-author`'s existing new-skill starting point, chosen for a skill with no revision history to
+  its name yet. These 27 have all been through the ADR-0020 retrofit and repeated audit passes
+  without ever tracking a version; crediting them with `0.1.0` would understate that, and there is
+  no real history to justify seeding higher than a first stable release. `1.0.0` marks "versioned as
+  of this retrofit," `0.1.0` keeps meaning "created and never yet revised."
+- **New skills still start at `0.1.0`.** `skill-author`'s create/improve bump convention is
+  unchanged; only the presence of the field stops being conditional.
+- **The one outlier in the other direction, `git-commits`, keeps its existing value** (`0.1.3`) —
+  it already had real tracked history under the old conditional rule, and this decision does not
+  reset skills that were already compliant.
+- **`bin/write-docs`'s top-level `version:` moves into `metadata:`, normalized to `1.0.0`.** It is
+  the one skill that carried a version outside the `metadata:` block, which is why the table above
+  counts `bin` as 0 — a top-level `version:` is not `metadata.version`, and nothing reads it. #127
+  raised it alongside the split because "does a skill carry a version" and "where does it live" are
+  the same question. Its value (`1.0`) is not semver and carries no more real history than the 27
+  unversioned skills, so it is relocated and reset to the same `1.0.0` seed rather than preserved
+  like `git-commits`'s tracked `0.1.3`.
+- **`skill-frontmatter`'s pre-commit hook gains the check.** It already fails a SKILL.md missing
+  `name:` or `description:`; a missing `metadata.version` is now the same class of failure, not a
+  style nit an audit might or might not catch.
+
+## Considered options
+
+**Leave it per-plugin, document the split.** This was the initial framing of #127 and is coherent —
+`core`/`gitea`/`lint` keep it, `bin`/`kyberforge` don't, two outliers get normalized to match their
+plugin. Rejected on reconsideration: a rule that says "some plugins track this and some don't" is
+strictly harder to state, audit and onboard against than "every skill does," for a field whose entire
+job is answering "did this change since I last read it" — a question with the same shape everywhere
+it's asked, not one that varies by plugin domain.
+
+**Drop the field corpus-wide.** Rejected: `skill-author` already depends on it to decide whether a
+create/improve pass owes a bump, so the 12 skills carrying it are not tracking dead weight — removing
+it discards real revision signal for no gain.
+
+## Consequences
+
+27 SKILL.md files gain `metadata.version: "1.0.0"`, and a 28th — `bin/write-docs` — reaches the same
+value by relocating its top-level `version: "1.0"` into `metadata:`. `skill-author`'s `create.md`
+moves the field from "Optional frontmatter" to the required list, citing this ADR. `skill-author`'s
+own SKILL.md drops the "with `metadata.version` present" conditional in its bump-rule line, since
+presence is no longer in question. `.pre-commit-config.yaml`'s `skill-frontmatter` hook is extended
+to require the field, closing the gap #113 and #118 both named in the same audit pass: a stated rule
+with nothing enforcing it drifts the same way an unstated one does.

docs/adr/0023-rtk-prefix-marks-executable-commands-only.md

@@ -0,0 +1,168 @@
+# The `rtk` prefix marks executable commands only, and is repo-wide
+
+**Status: accepted (2026-09-08).**
+
+## Context
+
+`CLAUDE.md` states the org convention as a golden rule: "Always prefix commands with `rtk`. If RTK
+has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always
+safe to use." Issue #113 observed that the rule had never been written down for skill *prose*, where
+a `git <subcommand>` mention can be either an instruction to execute or a reference to the concept,
+and that the corpus had drifted into carrying both spellings with no stated rule. PR #130 swept the
+`git` plugin and recorded a two-way split in `plugins/git/README.md`.
+
+Review found two defects in that sweep, and both are in the premise rather than the execution.
+
+**RTK is not output-transparent.** `rtk git --help` enumerates twelve filtered subcommands — `diff`,
+`log`, `status`, `show`, `add`, `commit`, `push`, `pull`, `branch`, `fetch`, `stash`, `worktree`.
+Everything else is a true passthrough. Inside that set the filter is not a formatting preference; it
+changes what the command *reports*. Measured against rtk 0.42.4:
+
+| Command | What rtk does to it |
+|---|---|
+| `worktree list --porcelain -z` | discards both flags; no NUL separators, no `locked`/`lock_reason` field at all |
+| `worktree list -v` | abbreviates `/root/…` to `~/…`, collapses column alignment |
+| `branch --list <name>` | emits a phantom `* ` line even on no match |
+| `diff --name-only` / `--name-status` | appends a blank line and a `Changes:` trailer |
+| `diff --word-diff[=color\|=porcelain]` | emits no `[-removed-] {+added+}` markers; substitutes a diffstat |
+| `log -L` | truncates each diff body line at ~72 characters with an ellipsis |
+| `stash pop` (on conflict) | prints only `FAILED: git stash pop`, swallowing `CONFLICT`, `Unmerged paths` and the retained-entry notice |
+| `stash list` (empty) | prints `No stashes` where git prints nothing |
+
+Every one of those falsified a skill that was written against the bare output. `git-worktrees`'s
+Step 2 required `locked` and `lock_reason` from a command whose rtk rendering has never carried
+them; `git-log-format.md` documented `[-removed-] {+added+}` markers beside a command that no longer
+produces them. The two-way split could not see any of this, because both halves of it are about what
+a *sentence* is doing and none of it is about what the *command* does.
+
+**The rule is not `git`-plugin-scoped.** `plugins/git/README.md` claimed the `gitea-*` skills
+"contain no `git`/`rtk` mentions at all". Five `gitea-*` SKILL.md files run `git remote get-url
+origin` in a fenced ```bash Step block — the README's own canonical example of "executable,
+instructed" — plus `git branch --show-current` in a reference file and three `git remote -v` in
+`gitea-orchestrate.agent.md`. A convention stated inside one plugin's README is invisible from the
+plugin next door, which is how those eight sites stayed bare through the sweep that existed to find
+them.
+
+## Decision
+
+**One rule, three clauses, repo-wide** — every `plugins/*/.apm/skills/**` and
+`plugins/*/.apm/agents/**` file, not the `git` plugin alone.
+
+1. **Executable and instructed → `rtk git`.** Anything telling the agent to run a command now: an
+   imperative step, a dispatch-table "Run" cell, a fenced code-block procedure.
+   `rtk git push -u origin <branch>`.
+2. **Illustrative or referential → bare `git`.** Naming a flag's behaviour, quoting a doc's own
+   heading, describing a command in the abstract, warning against an anti-pattern. "`git switch`
+   refuses rather than clobbering conflicting local edits."
+3. **Machine-parsed or interactive → bare `git`, and say why inline.** A command whose output the
+   skill parses, where rtk is in the filtered set above; or a command that hands control to an
+   interactive child process.
+
+Clause 3 is the new one and it looks arbitrary without the table in Context, which is why the
+measurements are recorded here rather than left in a PR thread. It is applied per subcommand and per
+flag, not per skill: `tag --list` stays prefixed because rtk passes it through byte-identically,
+while `branch --list` two words away goes bare because it does not. `git remote get-url origin`,
+`git remote -v`, `git branch --show-current`, `git log --oneline -1` and `git add -u` were all
+re-measured as byte-identical passthroughs and are therefore prefixed, parsing notwithstanding.
+
+Two consequences of that per-subcommand basis are worth stating, because both are load-bearing and
+neither is comfortable:
+
+- **rtk's filtered set is a moving target.** `git rebase` and `git mergetool` are passthroughs on
+  0.42.4 — verified under `script(1)`, both inherit a real TTY, contradicting an earlier report that
+  they did not. They stay bare anyway, on the interactive limb: a token filter has nothing to offer a
+  command that hands control to an editor, and the prefix would only buy exposure to whatever a later
+  rtk version decides to do with those subcommands. The same reasoning makes the *inner* call in
+  `` `rtk git remote add origin-push $(git config remote.origin.url)` `` bare while the outer stays
+  prefixed — `config` passes through cleanly today, but its stdout becomes a remote URL that is then
+  force-pushed to, and that is not a blast radius to lend to a future filter change.
+- **`branch --show-current` sits on the sharp edge.** It is in the filtered set, it is parsed, and it
+  is prefixed — on a measurement, in a subcommand whose sibling `--list` is exactly the defect clause
+  3 exists for. If rtk's `branch` filter is ever extended, that is the first site to break. It is
+  called out rather than hedged, because a rule whose exceptions are unrecorded is the state this ADR
+  is replacing.
+
+**A clause-3 site says so inline, in a few words.** "bare, not `rtk`: rtk prints a phantom `* ` line
+even on no match". Without it the next sweep re-prefixes the command, which is how #113 recurs.
+
+**The rule lives here, and `docs/spec/gates.md` carries the gate.** `plugins/git/README.md` is
+reduced to a pointer. It had also cited `git-workflow/references/hard-rules.md` as a place the rule
+was written down; that file contains no occurrence of "rtk", and the citation is removed rather than
+repaired.
+
+**Clause 1 is enforced by a `check-rtk-prefix` pre-commit hook; clauses 2 and 3 are not enforceable
+and are not gated.** The hook checks the two places a `git` mention is unambiguously an instruction —
+a line in a shell-tagged code fence, and the opening backticked span of a "Run" column cell — and a
+deliberately-bare command opts out with the literal string `ADR-0023` on its own line. Its coverage
+limits are recorded in `docs/spec/gates.md`, not smoothed over.
+
+## Considered options
+
+**Add `compatibility:` frontmatter to every skill.** These six plugins are installable by third
+parties, and a consumer who installs `git` from the marketplace has no `rtk` on their PATH. Every
+prefixed command in the corpus is a plain `git` invocation with a word in front of it, so the prefix
+is *droppable*: delete `rtk ` and the command is correct. A `compatibility:` line per skill would
+state that in a machine-readable field. Rejected on cost. It is 39 lines of frontmatter restating one
+sentence, it is preloaded into every agent's context every session under ADR-0020's budget — the
+field is not free the way a line in a doc is — and it has no consumer: nothing reads
+`compatibility:`, so the field would be a comment with a colon in it. The consumer situation is
+documented here and in `plugins/git/README.md` instead, which is where a human installing a plugin
+actually looks. The same two-line note is owed to the other five plugin READMEs and is not yet
+written.
+
+**Move rtk to the execution layer entirely.** Skills instruct bare `git` throughout; `CLAUDE.md`'s
+session rule handles prefixing at the point of execution. This is the strongest rejected option and
+it deserves the space: it closes the consumer gap and all eight output defects at once, because the
+executing agent knows what it is about to parse and the skill does not have to predict it. It also
+removes clause 3 entirely — there is nothing to except. Rejected because the prefix is lost wherever
+an agent copies a command literally, which is the common case for a fenced procedure block and the
+whole reason dispatch tables exist. The org convention's value is that the prefix is *already there*
+in the text the agent lifts; a rule that relies on the agent remembering to add it is the rule that
+produced the drift in the first place. Worth revisiting if rtk ever ships a shell shim, which would
+make the execution layer transparent and this trade different.
+
+**Keep the two-way split and fix the eight sites by hand.** Rejected: the split has no vocabulary for
+"this command is executable, instructed, and must still be bare", so the eight sites would be
+unexplained exceptions and the next sweep re-prefixes them. That is the failure this ADR exists to
+stop, not a smaller version of it.
+
+**Gate clauses 2 and 3 as well.** Rejected as undecidable. "Run `git switch <branch>`" and "`git
+switch` refuses rather than clobbering local edits" are the same token sequence; separating them is a
+judgement about what a sentence is doing. A gate that guessed would fire on correct content, and a
+gate that fires on correct content gets added to `SKIP`, which disarms clause 1 along with it.
+
+## The boundary the rule does not decide
+
+Two shapes in the corpus resisted the two-way split. The three-clause rule resolves one and does not
+resolve the other; both are recorded so an author meeting a third one knows which kind it is.
+
+**`git-worktrees/SKILL.md`'s tracking row carries both spellings in one Run cell** — `rtk git
+worktree add --track -b <branch> <path> <remote>/<branch>` — always correct. `git worktree add
+<path> <branch>` expands to exactly this. **Resolved: the clauses apply per mention, not per row,
+per cell or per file.** The first is the instruction (clause 1), the second names what the first
+expands to (clause 2), and one table cell can hold one of each. The rule needed no change; the
+*gate* did, and it checks only a Run cell's opening span for exactly this reason.
+
+**`git-submodules/references/setup-and-update.md:80` has a git command inside a quoted argument to
+another command** — `rtk git submodule foreach 'git pull origin main || :'`. **Not resolved: all
+three clauses describe a command the reading agent executes, and the inner `git pull` is not one.**
+It is the literal text of an argument that `git submodule foreach` hands to a subshell running inside
+each submodule's own working tree, where the local convention does not reach. The file already gets
+this right and already justifies it in prose two lines below ("the git calls in it are the
+submodule's own — that is the one place a bare `git` is correct"). **An author meeting this shape
+should do the same: leave the inner command bare and justify it inline.** It is deliberately not
+promoted to a fourth clause on one instance. The gate does not decide it either — it happens to pass
+this line, because the segment containing the inner command begins with `rtk`, and that is an
+accident of the split rather than an understanding of quoting.
+
+## Consequences
+
+Eleven sites in `plugins/git/.apm/skills/**` revert to bare `git` under clause 3, each carrying a
+short inline reason. Eight sites across `plugins/gitea/.apm/skills/**` and
+`plugins/gitea/.apm/agents/gitea-orchestrate.agent.md` gain the prefix under clause 1, and one in
+`pc-run/SKILL.md` that the #130 sweep's grep missed because the backtick opens with `SKIP=` rather
+than `git `. `plugins/git/README.md`'s Conventions section becomes a pointer here, minus a paragraph
+that was false about the `gitea-*` skills and a citation to a file that does not carry the rule.
+A `check-rtk-prefix` pre-commit hook and `tests/test-check-rtk-prefix.sh` land with it; the test runs
+the gate against the pre-sweep corpus on `main` and asserts it fails there, because a gate that only
+passes on the fixed tree proves nothing about the drift it was written for.

docs/notes/factory-integration-decisions.md

@@ -53,8 +53,7 @@ All skills — new and rebuilt — must follow this standard:
 - `name:` — matches directory name
 - `description:` — trigger-tested before writing the body (explicit, implicit, negative cases)
 - `metadata: category:` — from the category table above
-
-`version:`, `updated:`, `when:`, `source:`, and `references:` are provenance/audit fields — they live in `META.md` alongside the SKILL.md (not in frontmatter). See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.
+- `metadata: version:` — mandatory for every skill (ADR-0022)
 
 **Body required sections:**
 - Constraints (highest-ROI element — prevents overengineering)

docs/notes/skill-implementation-workflow.md

@@ -103,21 +103,21 @@ Do not write the SKILL.md until the human has confirmed every section. The synth
 **c. SKILL.md** (sub-agent)
 Once all sections are confirmed, spawn a write agent to produce the SKILL.md using `write-skill` (or hand-write for bootstrap skills). The agent receives: trigger description, per-section decisions from step b, upstream content to incorporate, authoring standard (see below).
 
-**c. META.md — `source:` and `references:` fields**
-Populate `META.md` after upstream review. Two distinct fields:
-- `source:` — upstream provenance tracking (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
-- `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research.
+**d. Provenance — source and reference records**
+Record provenance after upstream review. Two distinct kinds:
+- Upstream provenance (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
+- General citations (research papers, documentation, standard specifications). Present only if the skill cites external research.
 
-Both fields live in `META.md` alongside the SKILL.md — not in frontmatter. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the full schema.
+Both are recorded in the skill's own `references/sources.md`, keyed by the `source_keys:` its SKILL.md and reference files declare. `validate-provenance.sh` checks that chain.
 
-**d. eval.yaml** (sub-agent)
+**e. eval.yaml** (sub-agent)
 Invoke `write-eval` in two steps to preserve its confirmation gate:
 1. Sub-agent proposes test cases and returns the plan to the main conversation.
 2. Human confirms the plan; then sub-agent writes the file.
 
 Do not pass pre-designed test cases directly to a write agent — that collapses the plan-then-confirm gate into a single step, bypassing write-eval's own constraint. Co-located at `.agents/evals/<category>/<skill-name>/eval.yaml`. Must contain all five required test types (see Eval schema below).
 
-**e. HITL behavioral test**
+**f. HITL behavioral test**
 Human opens a fresh Claude session, invokes the skill with its trigger phrase, and verifies output. Do not batch more than 2–3 skills before running behavioral tests — output volume must stay within genuine human review capacity. An approval that cannot be meaningfully evaluated is not an approval.
 
 ### Step 6 — Session handoff
@@ -157,12 +157,11 @@ name: skill-name
 description: <trigger description — routing only; written and tested first; max 1024 chars>
 metadata:
   category: <design|factory|implement|test|review|deploy|operate|cross-cutting|iac>
+  version: <semver — mandatory for every skill; see ADR-0022>
 # allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
 ---
 ```
 
-Frontmatter contains only these fields. `version`, `updated`, `when`, `source`, and `references` are provenance/audit fields — they are not used for routing or runtime execution. They live in `META.md` alongside the SKILL.md, loaded only when needed. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.
-
 ### Body sections
 
 Use `.agents/skills/write-skill/SKILL-TEMPLATE.md` as the authoritative structure reference. The template defines the required sections, correct order, XML grouping, and placeholder comments for each section.
@@ -230,6 +229,6 @@ Upstream review happens per-skill during step 2, not once at chunk start.
 
 ## Open decisions carried forward
 
-- **Bidirectional reference convention** — Chunk 4 (reference scanner tooling; reverse map "what files point to X?"). The `when:` field itself is resolved — it lives in `META.md` alongside every skill.
+- **Bidirectional reference convention** — Chunk 4 (reference scanner tooling; reverse map "what files point to X?").
 - **PRD/issue template scope** — refined during `write-prd` (0020) and `write-issue-spec` (0019) implementation
 - **Merging `zoom-out` into architect role** — revisit at Chunk 5 grill

docs/spec/architecture.md

@@ -21,11 +21,26 @@ project repo (local overrides)
 
 Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately — in this repo by `apm install` against the `dependencies.apm` entries in the root `apm.yml`, which lands them in `.claude/skills/` and `.claude/agents/` (ADR-0018); elsewhere by `claude plugin install <name>@holocron`.
 
-`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
+`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance) and carries nothing else — the content index of on-demand instruction files sits in `core/AGENTS.md`, deployed to `~/.agents/AGENTS.md` and imported by it. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
 
 ## Plugin model
 
-Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
+Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
+
+Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`.
+
+The second boundary worth stating is `git` vs `gitea`, because both own things called branches and both touch pull requests: `git` is whatever works over the git wire protocol against a local clone, `gitea` is whatever goes through the forge's HTTP API. That is why `git-branches` and `gitea-branches` both exist and are not duplicates.
+
+These are routing boundaries, not inventories — they answer "where does a new skill go", so they deliberately do not enumerate what each plugin ships today. The plugin's published `description` in its `apm.yml` states the same boundary for a consumer deciding whether to install (ADR-0021); neither carries an inventory. For what a plugin ships today, read `plugins/<name>/.apm/skills/` or the plugin list in `README.md`.
+
+| Plugin | Scope |
+|---|---|
+| `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it |
+| `git` | Git operations and git hook tooling — anything driven over the git wire protocol against a local clone, plus the pre-commit hooks that guard it |
+| `gitea` | Anything reached through the Gitea HTTP API rather than the git wire protocol — the forge's own objects |
+| `kyberforge` | Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling |
+| `lint` | Configuring and running linters against a target repo; repo-agnostic, first linter is Vale |
+| `bin` | Unsorted skills that have not earned a home yet |
 
 Two compilers produce the plugin roots you see in the tree:
 
@@ -34,12 +49,21 @@ Two compilers produce the plugin roots you see in the tree:
 
 `.apm/` is the sole hand-edited authoring source for plugin content. An edit made in the flat mirror is discarded by the next sync and is reported as drift by the `check-plugin-content-sync` pre-push hook. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json`, and per-plugin extras such as `plugins/git/config.example.json`, `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root** and is untouched by either compiler.
 
+`.mcp.json` is the one entry in that list that is still load-bearing for apm rather than merely ignored by it. MCP is a first-class apm primitive — `dependencies.mcp` sits beside `dependencies.apm` in the manifest schema, and apm tracks deployed servers in `apm.lock.yaml` under `mcp_servers`, `mcp_configs` and `mcp_config_provenance`. A plugin reaches that primitive indirectly. `apm pack` writes the string `".mcp.json"` into the generated `.github/plugin/plugin.json` as its `mcpServers` value, and on install apm resolves the plugin manifest in the order `plugin.json`, `.github/plugin/plugin.json`, `.claude-plugin/plugin.json` — so the Copilot manifest wins, the pointer is followed, and `.mcp.json` is injected into the package's `dependencies.mcp` with any `${VAR}` env references intact. Verified against the real remote: a git-sourced install of `plugins/gitea` deploys the gitea server with both env references unexpanded.
+
+Two consequences follow, and both have bitten already:
+
+- **Do not declare `dependencies.mcp` in a plugin's own `apm.yml`.** It is the schema-correct place and it breaks the build. The `apm-audit-ci` pre-push hook runs `apm audit --ci` inside every `plugins/*/`, so a declared dependency arms `lockfile-exists` there, which then demands an `apm.lock.yaml` in the package plus every file of that package's own deployed tree present inside the package directory. Measured on `plugins/gitea`: 93 missing deployed files and 79 drifted paths.
+- **`.claude-plugin/plugin.json` carries an env-stripped copy.** `apm pack` inlines `.mcp.json` there, and its sanitiser drops `env` and `headers` blocks unconditionally at any depth, `${VAR}` indirection included. That copy is inert under apm, which never reaches it, but a native Claude Code plugin install reads exactly that file and would launch the server with no credentials. Anything installed natively rather than through apm needs its MCP env supplied by the host.
+
 That immunity is positional, not by filename. Anything placed *inside* a mirrored directory is destroyed regardless of what it is: `sync_dir` runs `rm -rf "$dst"` before every copy, and `sync_hooks_json` does the same to `hooks/`. A hand-written `README.md` under `plugins/<name>/hooks/` or `plugins/<name>/skills/` is deleted by the next sync with no drift report, because a file with no `.apm/` counterpart is simply absent from the regenerated tree. This has already cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`. Plugin-root documentation belongs in `docs/`.
 
 ## Governance layer
 
 `core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins.
 
+Those on-demand files are plain markdown — no frontmatter, no schema. The agent decides when to read each one from task context and the content index label alone. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice; it is a deliberate deferral, not an oversight to close.
+
 The governance layer has two phases:
 - **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
 - **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
@@ -57,10 +81,14 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
 
 `CONTEXT.md` is therefore **not** always-loaded. `AGENTS.md` instructs agents to read it at session start, which is a behavioural instruction, not an `@import` guarantee — `LESSONS.md`'s 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change.
 
+## Reference conventions
+
+The stated convention is that files referencing other files declare those references explicitly: the referencing file carries the forward reference (the content index in `core/AGENTS.md`, `references:` in frontmatter), the referenced file carries a `when:` field describing when it is loaded, and divergence between the two signals staleness. It is aspirational, not a description of the repo today — no file under `core/instructions/` carries frontmatter at all, `when:` appears in exactly one of the 39 `SKILL.md` sources under `plugins/*/.apm/skills/`, and the reference scanner script meant to derive the reverse map ("what files reference this file?") does not exist; `docs/notes/skill-implementation-workflow.md` still lists it as unbuilt work. Treat it as intent for instruction files, skills, and workflow documents, not as a rule the repo enforces.
+
 ## Provider model
 
 `core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
 
 ## Architectural decisions
 
-Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds 19 numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that `.claude/settings.json`'s committed content is exactly `{"hooks": {}}`) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots).
+Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that `.claude/settings.json`'s committed content is exactly `{"hooks": {}}`) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots).

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,18 @@
 ---
 name: caveman
+disable-model-invocation: true
 description: >
-  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
-  filler, articles, and pleasantries while keeping full technical accuracy.
-  Use when user says "caveman mode", "talk like caveman", "use caveman",
-  "less tokens", "be brief", or invokes /caveman.
+  Ultra-compressed output mode that drops articles, filler and pleasantries while
+  keeping technical substance exact, cutting token usage by roughly 75%.
+metadata:
+  version: "1.0.0"
 ---
 
 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Diagnose
@@ -15,40 +20,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.
-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.
+**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.
 
-Build the right feedback loop, and the bug is 90% fixed.
-
-### 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.
+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.
 
 ## Phase 2 — Reproduce
 
@@ -57,7 +33,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 +66,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 minimised repro into a failing test at that seam.
+1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
 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,12 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 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 |
+| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
+| `references/adr-format.md` | 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 <what-to-do>
@@ -71,7 +76,7 @@ When the user states how something works, check whether the code agrees. If you
 
 ### Update CONTEXT.md inline
 
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](references/context-format.md).
 
 Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
 
@@ -83,6 +88,6 @@ Only offer to create an ADR when all three are true:
 2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
 
-If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+If any of the three is missing, skip the ADR. Use the format in [adr-format.md](references/adr-format.md).
 
 </supporting-info>

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 `references/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 |
+| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
+| `references/interface-design.md` | 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 |
+| `references/deepening.md` | Cited from `references/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,13 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Improve Codebase Architecture
@@ -9,7 +16,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 +27,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 `references/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 +62,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 +74,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 `references/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).
-- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.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 `references/adr-format.md`.
+- **Want to explore alternative interfaces for the deepened module?** Read `references/interface-design.md`.

plugins/bin/.apm/skills/improve-codebase-architecture/references/deepening.md

@@ -1,6 +1,6 @@
 # Deepening
 
-How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**.
 
 ## Dependency categories
 

plugins/bin/.apm/skills/improve-codebase-architecture/references/interface-design.md

@@ -2,7 +2,7 @@
 
 When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
 
-Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+Uses the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
 
 ## Process
 
@@ -11,7 +11,7 @@ Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**,
 Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
 
 - The constraints any new interface would need to satisfy
-- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- The dependencies it would rely on, and which category they fall into (see [deepening.md](deepening.md))
 - A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
 
 Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
@@ -20,21 +20,21 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th
 
 Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
 
-Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [deepening.md](deepening.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
 
 - Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
 - Agent 2: "Maximise flexibility — support many use cases and extension."
 - Agent 3: "Optimise for the most common caller — make the default case trivial."
 - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
 
-Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+Include both [language.md](language.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
 
 Each sub-agent outputs:
 
 1. Interface (types, methods, params — plus invariants, ordering, error modes)
 2. Usage example showing how callers use it
 3. What the implementation hides behind the seam
-4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+4. Dependency strategy and adapters (see [deepening.md](deepening.md))
 5. Trade-offs — where leverage is high, where it's thin
 
 ### 3. Present and compare

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,12 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Prototype
@@ -9,10 +15,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.
-- **"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.
+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.
 
 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,79 @@
 ---
 name: research
 description: >-
-  Use when the user wants to research a topic and generate structured reference
-  markdown files. Handles: finding canonical docs for a tool/library/API via
-  Context7 MCP or web sources, reading and deepening into linked pages,
-  organizing extracted content into topic files (overview, installation,
-  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).
+  Use when the user wants a tool, library, or API researched from canonical
+  documentation into structured per-topic reference markdown files. Not
+  documentation written from existing code or specs -> `write-docs`. Not a bug
+  or incident -> `diagnose`.
 metadata:
+  version: "1.0.0"
   category: research
 allowed-tools:
-  - WebSearch
-  - WebFetch
+  - Grep
+  - 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
-- **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
+## Step 1 — Scope against the working directory
 
-## 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
-- Skip any default topic file if no relevant content is found for it — do not create empty files
-- Create additional topic files beyond the default list when content warrants it (e.g. `webhooks.md`, `rate-limits.md`)
-- Subagents handle parallel source reading and link deepening — the orchestrator writes all files; subagents return summaries only, never write directly
-- 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
+The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`,
+`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists.
+If what belongs in one of them is unclear, or the topic needs a file outside that set, read
+`references/topics.md` for the per-topic coverage table and the custom-topic naming rule.
 
-</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`
-- `<output-path>/sources.md` — always produced; maps slug → URL, description, contributing files
+Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path:
 
-</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
-- 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
+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.
 
-## Self-check
-
-- [ ] 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>
+If no topic area has content, write nothing at all, `sources.md` included, and report what was searched.

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 |
+| `references/tests.md` | Cited from Philosophy: worked good and bad test examples |
+| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock |
+| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
+| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
+| `references/refactoring.md` | 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Test-Driven Development
@@ -13,7 +18,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 `references/tests.md`. If a test needs a collaborator faked, read `references/mocking.md` before reaching for a mock.
 
 ## Anti-Pattern: Horizontal Slices
 
@@ -50,8 +55,8 @@ Before writing any code:
 
 - [ ] Confirm with user what interface changes are needed
 - [ ] Confirm with user which behaviors to test (prioritize)
-- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
-- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] Identify opportunities for [deep modules](references/deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](references/interface-design.md)
 - [ ] List the behaviors to test (not implementation steps)
 - [ ] Get user approval on the plan
 
@@ -88,7 +93,7 @@ Rules:
 
 ### 4. Refactor
 
-After all tests pass, look for [refactor candidates](refactoring.md):
+After all tests pass, look for [refactor candidates](references/refactoring.md):
 
 - [ ] Extract duplication
 - [ ] Deepen modules (move complexity behind simple interfaces)

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 |
+| `references/agent-brief.md` | 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 |
+| `references/out-of-scope.md` | 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Triage
@@ -15,8 +20,8 @@ Every comment or issue posted to the issue tracker during triage **must** start
 
 ## Reference docs
 
-- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
-- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
+- [agent-brief.md](references/agent-brief.md) — how to write durable agent briefs
+- [out-of-scope.md](references/out-of-scope.md) — how the `.out-of-scope/` knowledge base works
 
 ## Roles
 
@@ -35,7 +40,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.
 
@@ -69,11 +74,11 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
 4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session.
 
 5. **Apply the outcome:**
-   - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
+   - `ready-for-agent` — post an agent brief comment ([agent-brief.md](references/agent-brief.md)).
    - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
    - `needs-info` — post triage notes (template below).
    - `wontfix` (bug) — polite explanation, then close.
-   - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
+   - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([out-of-scope.md](references/out-of-scope.md)).
    - `needs-triage` — apply the role. Optional comment if there's partial progress.
 
 ## Quick state override

plugins/bin/.apm/skills/triage/references/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/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,10 +1,15 @@
 ---
 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.
-version: "1.0"
+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`.
 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
 metadata:
+  version: "1.0.0"
   category: implement
 source:
   - repo: anthropics/skills
@@ -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/.apm/skills/zoom-out/SKILL.md

@@ -2,6 +2,8 @@
 name: zoom-out
 description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
 disable-model-invocation: true
+metadata:
+  version: "1.0.0"
 ---
 
 I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.

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

@@ -1,7 +1,7 @@
 {
   "name": "bin",
-  "version": "1.1.3",
-  "description": "A place for things to be binned",
+  "version": "1.1.7",
+  "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",
     "email": "defame1297@rkdr.net",

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

@@ -1,7 +1,7 @@
 {
   "name": "bin",
-  "version": "1.1.3",
-  "description": "A place for things to be binned",
+  "version": "1.1.7",
+  "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",
     "email": "defame1297@rkdr.net",

plugins/bin/apm.yml

@@ -1,6 +1,6 @@
 name: bin
-version: 1.1.3
-description: A place for things to be binned
+version: 1.1.7
+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
   email: defame1297@rkdr.net

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,18 @@
 ---
 name: caveman
+disable-model-invocation: true
 description: >
-  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
-  filler, articles, and pleasantries while keeping full technical accuracy.
-  Use when user says "caveman mode", "talk like caveman", "use caveman",
-  "less tokens", "be brief", or invokes /caveman.
+  Ultra-compressed output mode that drops articles, filler and pleasantries while
+  keeping technical substance exact, cutting token usage by roughly 75%.
+metadata:
+  version: "1.0.0"
 ---
 
 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Diagnose
@@ -15,40 +20,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.
-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.
+**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.
 
-Build the right feedback loop, and the bug is 90% fixed.
-
-### 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.
+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.
 
 ## Phase 2 — Reproduce
 
@@ -57,7 +33,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 +66,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 minimised repro into a failing test at that seam.
+1. Turn the Phase 1 loop into a failing test at that seam, narrowed to the symptom captured in Phase 2.
 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,12 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 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 |
+| `references/context-format.md` | Cited when a term is resolved: the structure of a `CONTEXT.md` and how to write a Language entry |
+| `references/adr-format.md` | 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 <what-to-do>
@@ -71,7 +76,7 @@ When the user states how something works, check whether the code agrees. If you
 
 ### Update CONTEXT.md inline
 
-When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](references/context-format.md).
 
 Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
 
@@ -83,6 +88,6 @@ Only offer to create an ADR when all three are true:
 2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
 
-If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+If any of the three is missing, skip the ADR. Use the format in [adr-format.md](references/adr-format.md).
 
 </supporting-info>

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 `references/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 |
+| `references/language.md` | Cited throughout `SKILL.md`: full definitions of every term, the words each one replaces, and the full principle list |
+| `references/interface-design.md` | 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 |
+| `references/deepening.md` | Cited from `references/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,13 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Improve Codebase Architecture
@@ -9,7 +16,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 +27,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 `references/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 +62,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 +74,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 `references/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).
-- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.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 `references/adr-format.md`.
+- **Want to explore alternative interfaces for the deepened module?** Read `references/interface-design.md`.

plugins/bin/skills/improve-codebase-architecture/references/deepening.md

@@ -1,6 +1,6 @@
 # Deepening
 
-How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**.
 
 ## Dependency categories
 

plugins/bin/skills/improve-codebase-architecture/references/interface-design.md

@@ -2,7 +2,7 @@
 
 When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
 
-Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+Uses the vocabulary in [language.md](language.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
 
 ## Process
 
@@ -11,7 +11,7 @@ Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**,
 Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
 
 - The constraints any new interface would need to satisfy
-- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- The dependencies it would rely on, and which category they fall into (see [deepening.md](deepening.md))
 - A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
 
 Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
@@ -20,21 +20,21 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th
 
 Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
 
-Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [deepening.md](deepening.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
 
 - Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
 - Agent 2: "Maximise flexibility — support many use cases and extension."
 - Agent 3: "Optimise for the most common caller — make the default case trivial."
 - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
 
-Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+Include both [language.md](language.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
 
 Each sub-agent outputs:
 
 1. Interface (types, methods, params — plus invariants, ordering, error modes)
 2. Usage example showing how callers use it
 3. What the implementation hides behind the seam
-4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+4. Dependency strategy and adapters (see [deepening.md](deepening.md))
 5. Trade-offs — where leverage is high, where it's thin
 
 ### 3. Present and compare

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,12 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Prototype
@@ -9,10 +15,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.
-- **"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.
+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.
 
 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,79 @@
 ---
 name: research
 description: >-
-  Use when the user wants to research a topic and generate structured reference
-  markdown files. Handles: finding canonical docs for a tool/library/API via
-  Context7 MCP or web sources, reading and deepening into linked pages,
-  organizing extracted content into topic files (overview, installation,
-  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).
+  Use when the user wants a tool, library, or API researched from canonical
+  documentation into structured per-topic reference markdown files. Not
+  documentation written from existing code or specs -> `write-docs`. Not a bug
+  or incident -> `diagnose`.
 metadata:
+  version: "1.0.0"
   category: research
 allowed-tools:
-  - WebSearch
-  - WebFetch
+  - Grep
+  - 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
-- **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
+## Step 1 — Scope against the working directory
 
-## 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
-- Skip any default topic file if no relevant content is found for it — do not create empty files
-- Create additional topic files beyond the default list when content warrants it (e.g. `webhooks.md`, `rate-limits.md`)
-- Subagents handle parallel source reading and link deepening — the orchestrator writes all files; subagents return summaries only, never write directly
-- 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
+The default topic areas are `overview`, `installation`, `configuration`, `cli-reference`,
+`api-reference`, `examples` and `troubleshooting` — one file each, and only where content exists.
+If what belongs in one of them is unclear, or the topic needs a file outside that set, read
+`references/topics.md` for the per-topic coverage table and the custom-topic naming rule.
 
-</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`
-- `<output-path>/sources.md` — always produced; maps slug → URL, description, contributing files
+Merge every set of notes, Context7 and web alike, by topic area, then write, in the output path:
 
-</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
-- 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
+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.
 
-## Self-check
-
-- [ ] 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>
+If no topic area has content, write nothing at all, `sources.md` included, and report what was searched.

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 |
+| `references/tests.md` | Cited from Philosophy: worked good and bad test examples |
+| `references/mocking.md` | Cited from Philosophy: mock at system boundaries only, and what not to mock |
+| `references/deep-modules.md` | Cited from stage 1: what a deep module is (small interface, large implementation) and why it is the design to aim for |
+| `references/interface-design.md` | Cited from stage 1: designing interfaces for testability, starting with accepting dependencies rather than creating them |
+| `references/refactoring.md` | 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Test-Driven Development
@@ -13,7 +18,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 `references/tests.md`. If a test needs a collaborator faked, read `references/mocking.md` before reaching for a mock.
 
 ## Anti-Pattern: Horizontal Slices
 
@@ -50,8 +55,8 @@ Before writing any code:
 
 - [ ] Confirm with user what interface changes are needed
 - [ ] Confirm with user which behaviors to test (prioritize)
-- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
-- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] Identify opportunities for [deep modules](references/deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](references/interface-design.md)
 - [ ] List the behaviors to test (not implementation steps)
 - [ ] Get user approval on the plan
 
@@ -88,7 +93,7 @@ Rules:
 
 ### 4. Refactor
 
-After all tests pass, look for [refactor candidates](refactoring.md):
+After all tests pass, look for [refactor candidates](references/refactoring.md):
 
 - [ ] Extract duplication
 - [ ] Deepen modules (move complexity behind simple interfaces)

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 |
+| `references/agent-brief.md` | 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 |
+| `references/out-of-scope.md` | 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,11 @@
 ---
 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`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Triage
@@ -15,8 +20,8 @@ Every comment or issue posted to the issue tracker during triage **must** start
 
 ## Reference docs
 
-- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
-- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
+- [agent-brief.md](references/agent-brief.md) — how to write durable agent briefs
+- [out-of-scope.md](references/out-of-scope.md) — how the `.out-of-scope/` knowledge base works
 
 ## Roles
 
@@ -35,7 +40,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.
 
@@ -69,11 +74,11 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
 4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session.
 
 5. **Apply the outcome:**
-   - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
+   - `ready-for-agent` — post an agent brief comment ([agent-brief.md](references/agent-brief.md)).
    - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
    - `needs-info` — post triage notes (template below).
    - `wontfix` (bug) — polite explanation, then close.
-   - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
+   - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([out-of-scope.md](references/out-of-scope.md)).
    - `needs-triage` — apply the role. Optional comment if there's partial progress.
 
 ## Quick state override