fix(tests): exclude .claude/worktrees/ from test-file discovery

find-based discovery in run-bats.sh and run-tests.sh picked up test
files nested inside on-disk git worktree checkouts under
.claude/worktrees/ (untracked, created by background agent isolation),
whose submodule-based test_helper isn't initialized there — causing
spurious pre-push failures unrelated to any real change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.agents/plugins/marketplace.json

@@ -1,95 +0,0 @@
-{
-  "name": "holocron",
-  "interface": {
-    "displayName": "holocron"
-  },
-  "plugins": [
-    {
-      "name": "kyberforge",
-      "source": {
-        "source": "local",
-        "path": "./plugins/kyberforge"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Developer Tools"
-    },
-    {
-      "name": "bin",
-      "source": {
-        "source": "local",
-        "path": "./plugins/bin"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Utilities"
-    },
-    {
-      "name": "git",
-      "source": {
-        "source": "local",
-        "path": "./plugins/git"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Version Control"
-    },
-    {
-      "name": "gitea",
-      "source": {
-        "source": "local",
-        "path": "./plugins/gitea"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Version Control"
-    },
-    {
-      "name": "core",
-      "source": {
-        "source": "local",
-        "path": "./plugins/core"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    },
-    {
-      "name": "mattpocock-skills",
-      "source": {
-        "source": "url",
-        "url": "mattpocock/skills",
-        "ref": "v1.2.3",
-        "sha": "835450ef244ab7335f75d95b83e7d979eae22a6d",
-        "tag_pattern": "v{version}"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Productivity"
-    },
-    {
-      "name": "lint",
-      "source": {
-        "source": "local",
-        "path": "./plugins/lint"
-      },
-      "policy": {
-        "installation": "AVAILABLE",
-        "authentication": "ON_INSTALL"
-      },
-      "category": "Developer Tools"
-    }
-  ]
-}

.claude-plugin/marketplace.json

@@ -1,67 +1,44 @@
 {
+  "description": "AI development skills for Claude Code and GitHub Copilot CLI \u2014 factory, design, implement, review, and cross-cutting workflows.",
   "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",
   "owner": {
-    "name": "Defame1297",
     "email": "defame1297@rkdr.net",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
+    "name": "Defame1297"
   },
   "plugins": [
     {
-      "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
-      "version": "1.6.0",
-      "category": "Developer Tools",
+      "name": "kyberforge",
       "source": "./plugins/kyberforge"
     },
     {
-      "name": "bin",
       "description": "A place for things to be binned",
-      "version": "1.1.3",
-      "category": "Utilities",
+      "name": "bin",
       "source": "./plugins/bin"
     },
     {
+      "description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.",
       "name": "git",
-      "description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.",
-      "version": "1.3.3",
-      "category": "Version Control",
       "source": "./plugins/git"
     },
     {
+      "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.",
       "name": "gitea",
-      "description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.",
-      "version": "1.3.4",
-      "category": "Version Control",
       "source": "./plugins/gitea"
     },
     {
+      "description": "Cross-cutting utility skills for everyday AI-assisted coding \u2014 triage, diagnosis, architecture review, and session navigation.",
       "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",
-      "category": "Productivity",
       "source": "./plugins/core"
     },
     {
+      "description": "Skills for Real Engineers \u2014 planning, TDD, architecture, and debugging workflows from Matt Pocock's .claude directory.",
       "name": "mattpocock-skills",
-      "description": "Skills for Real Engineers — planning, TDD, architecture, and debugging workflows from Matt Pocock's .claude directory.",
-      "version": "1.2.3",
-      "category": "Productivity",
       "source": {
-        "source": "github",
         "repo": "mattpocock/skills",
-        "ref": "v1.2.3",
-        "sha": "835450ef244ab7335f75d95b83e7d979eae22a6d",
-        "tag_pattern": "v{version}"
+        "source": "github"
       }
-    },
-    {
-      "name": "lint",
-      "description": "Skills and agents for configuring and running linters.",
-      "version": "1.1.6",
-      "category": "Developer Tools",
-      "source": "./plugins/lint"
     }
-  ]
+  ],
+  "version": "0.2.0"
 }

.claude/settings.json

@@ -1,16 +1,11 @@
 {
+  "enabledPlugins": {
+    "bin@holocron": true,
+    "core@holocron": true,
+    "git@holocron": true,
+    "kyberforge@holocron": true
+  },
   "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"${CLAUDE_PROJECT_DIR}/.claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh\"",
-            "timeout": 380
-          }
-        ]
-      }
-    ]
+    "PreToolUse": []
   }
 }

.github/plugin/marketplace.json

@@ -1,67 +1,44 @@
 {
+  "description": "AI development skills for Claude Code and GitHub Copilot CLI \u2014 factory, design, implement, review, and cross-cutting workflows.",
   "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",
   "owner": {
-    "name": "Defame1297",
     "email": "defame1297@rkdr.net",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
+    "name": "Defame1297"
   },
   "plugins": [
     {
-      "name": "kyberforge",
       "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
-      "version": "1.6.0",
-      "category": "Developer Tools",
+      "name": "kyberforge",
       "source": "./plugins/kyberforge"
     },
     {
-      "name": "bin",
       "description": "A place for things to be binned",
-      "version": "1.1.3",
-      "category": "Utilities",
+      "name": "bin",
       "source": "./plugins/bin"
     },
     {
+      "description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.",
       "name": "git",
-      "description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.",
-      "version": "1.3.3",
-      "category": "Version Control",
       "source": "./plugins/git"
     },
     {
+      "description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.",
       "name": "gitea",
-      "description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.",
-      "version": "1.3.4",
-      "category": "Version Control",
       "source": "./plugins/gitea"
     },
     {
+      "description": "Cross-cutting utility skills for everyday AI-assisted coding \u2014 triage, diagnosis, architecture review, and session navigation.",
       "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",
-      "category": "Productivity",
       "source": "./plugins/core"
     },
     {
+      "description": "Skills for Real Engineers \u2014 planning, TDD, architecture, and debugging workflows from Matt Pocock's .claude directory.",
       "name": "mattpocock-skills",
-      "description": "Skills for Real Engineers — planning, TDD, architecture, and debugging workflows from Matt Pocock's .claude directory.",
-      "version": "1.2.3",
-      "category": "Productivity",
       "source": {
-        "source": "github",
         "repo": "mattpocock/skills",
-        "ref": "v1.2.3",
-        "sha": "835450ef244ab7335f75d95b83e7d979eae22a6d",
-        "tag_pattern": "v{version}"
+        "source": "github"
       }
-    },
-    {
-      "name": "lint",
-      "description": "Skills and agents for configuring and running linters.",
-      "version": "1.1.6",
-      "category": "Developer Tools",
-      "source": "./plugins/lint"
     }
-  ]
+  ],
+  "version": "0.2.0"
 }

.gitignore

@@ -24,31 +24,3 @@ node_modules/
 
 # Claude Code local settings (machine-specific)
 .claude/settings.local.json
-
-# APM dependencies
-apm_modules/
-
-# APM install output — deployed copies of released plugin content, regenerated
-# by `apm install`. The authoring source is plugins/<name>/.apm/; committing a
-# deployed copy would add a third mirror of the same skills to drift against.
-.claude/skills/
-.claude/agents/
-
-# APM hook deployment output — `apm install` copies each package's referenced
-# hook scripts here and tracks its own settings.json entries in the sidecar.
-# Regenerated on every install; the authoring source is
-# plugins/<name>/.apm/hooks/ (ADR-0019).
-.claude/hooks/
-.claude/apm-hooks.json
-
-# `apm pack` bundle output. The pre-push gate runs pack with --dry-run, so this
-# only appears after a bare `apm pack` during a release; it is not repo content.
-build/
-
-# `apm pack`'s manifest for the *root* package. Emitted beside the marketplace
-# manifest by a bare `apm pack`, and never tracked on any branch — the repo's
-# own paths hide it, since sync-plugin-content.sh redirects `apm pack -o` to a
-# scratch tree and the apm-pack-check-clean pre-push hook runs --dry-run. Scoped
-# to the file, not the directory: the sibling .claude-plugin/marketplace.json is
-# compiled output that IS committed and must stay tracked.
-/.claude-plugin/plugin.json

.mcp.json

@@ -1,12 +0,0 @@
-{
-  "mcpServers": {
-    "obsidian": {
-      "args": [
-        "@bitbonsai/mcpvault@0.15.0",
-        "docs/"
-      ],
-      "command": "npx",
-      "type": "stdio"
-    }
-  }
-}

.pre-commit-config.yaml

@@ -28,29 +28,6 @@ repos:
       - id: pretty-format-json
         stages: ['pre-commit']
         args: [--autofix]
-        # Every generated manifest lives at a KNOWN path, so every alternative is
-        # root-anchored and spells that path out. This was five `(^|/)`
-        # any-depth alternatives plus one `^` root-only one -- a mixture with no
-        # rationale, under which a fixture or vendored tree containing
-        # `.../.claude-plugin/plugin.json` would have been silently excluded from
-        # formatting while an equivalent `.../.agents/plugins/marketplace.json`
-        # would not. All fifteen real files (3 root marketplace manifests, 2 per
-        # plugin x 6 plugins) match; anything else is hand-authored and gets
-        # formatted.
-        #
-        # `.claude/settings.json` is the sixteenth, and it is excluded for a
-        # different reason: apm OWNS that file (ADR-0018, ADR-0019), and
-        # `apm audit --ci` replays the install into a scratch tree and diffs
-        # the result byte-for-byte. `pretty-format-json` sorts object keys
-        # unless `--no-sort-keys` is passed, while apm's hook integrator emits
-        # insertion order (`matcher` before `hooks`, `type` before `command`).
-        # Formatting the file therefore rewrites apm's output into a form apm
-        # would never produce, and the `apm-audit-ci` pre-push hook reports it
-        # as permanent drift on a file with no git diff -- exactly what
-        # happened when the SessionStart hook first landed in 2e395a4.
-        # Re-running `apm install` fixes the file; leaving it in scope here
-        # would re-break it on the very commit that carries the fix.
-        exclude: '^(\.claude-plugin/marketplace\.json|\.agents/plugins/marketplace\.json|\.github/plugin/marketplace\.json|plugins/[^/]+/\.claude-plugin/plugin\.json|plugins/[^/]+/\.github/plugin/plugin\.json|\.claude/settings\.json)$'
       - id: check-yaml
         stages: ['pre-commit']
       - id: trailing-whitespace
@@ -68,8 +45,8 @@ repos:
     hooks:
       - id: run-tests
         name: Run test suite
-        description: Run all test-*.sh files and bats suite. --strict because a suite that exits 77 (SKIPPED) at pre-push means a documented dependency is missing on this machine, and pre-commit prints nothing for a passing hook -- without it the gate went green having verified 15 of 17 suites on a vale-less PATH, with the skip list swallowed. Ad-hoc `bash tests/run-tests.sh` still skips gracefully.
-        entry: bash tests/run-tests.sh --strict
+        description: Run all test-*.sh files and bats suite
+        entry: bash tests/run-tests.sh
         language: system
         stages: [pre-push]
         pass_filenames: false
@@ -84,151 +61,6 @@ repos:
         pass_filenames: false
         always_run: true
 
-      - id: check-plugin-content-sync
-        name: Check plugin content sync
-        description: Verify each plugin's flat skills/agents/commands/hooks/hooks.json mirror is in sync with .apm/ -- Claude Code has no .apm/ awareness so this compiled mirror must stay current (see issue #90)
-        entry: bash scripts/sync-plugin-content.sh --check --all
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
-      - id: check-marketplace-mirror-sync
-        name: Check marketplace mirror sync
-        description: Verify .github/plugin/marketplace.json (Copilot CLI's legacy manifest path) is byte-identical to .claude-plugin/marketplace.json -- apm has no output profile for this path, so it must be kept in sync explicitly (see issue #90)
-        entry: bash scripts/sync-marketplace-mirror.sh --check
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
-      - id: check-executables-allow-sync
-        name: Check executables allow key sync
-        description: Verify root apm.yml's executables.allow key names kyberforge's actual version -- apm matches that key by exact "<package>#<version>" lookup, so a version bump on one side alone silently stops deploying kyberforge's hooks/ and bin/ and lets the apm install go stale (see ADR-0019)
-        entry: bash scripts/check-executables-allow-sync.sh
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
-      - id: apm-marketplace-check
-        name: apm marketplace check
-        description: Validate every marketplace.packages[] entry resolves, including network reachability of remote refs -- catches stale/unreachable remote package references that check-manifests.sh deliberately skips (local-source checks only)
-        entry: apm marketplace check
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
-      - id: apm-audit-ci
-        name: apm audit --ci
-        description: Run apm's producer-side CI gate over the root manifest AND each of the six plugin packages. Verifies exactly two things per manifest -- apm.yml parses as a valid APM manifest (manifest-parse), and, if it declares dependencies, apm.lock.yaml exists and is consistent (lockfile-exists). It does NOT enforce an org policy and does NOT scan for hidden Unicode; see the comment below for why. Reference:plugins/kyberforge/.apm/skills/apm-workflow/references/audit.md
-        entry: bash -c 'for d in . plugins/*/; do (cd "$d" && apm audit --ci) || { echo "apm audit --ci failed in $d" >&2; exit 1; }; done'
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-        # The description above deliberately claims less than this hook's old one
-        # did ("lockfile/policy/hidden-content integrity"), because two of those
-        # three were never happening:
-        #
-        # * POLICY. `apm audit --ci` discovers an org policy from the git remote,
-        #   and apm's discovery only understands github.com and Azure DevOps.
-        #   This repo's remote is a self-hosted Gitea, so discovery resolves
-        #   nothing and the run prints `No org policy found at unknown;
-        #   enforcement skipped`. apm's own message suggests
-        #   `policy.fetch_failure_default=block` in apm.yml "to fail closed" --
-        #   that was tried on a scratch copy and REJECTED: it does not make the
-        #   check meaningful, it makes it permanently red. `apm audit --ci` then
-        #   exits 1 with `No org policy found at unknown
-        #   (policy.fetch_failure_default=block)` on every push, because there is
-        #   no org policy to find and no supported way for this remote to serve
-        #   one. A gate that can never go green is not a gate. Revisit if this
-        #   repo ever gains a policy source apm can actually reach.
-        # * HIDDEN CONTENT. The hidden-Unicode scan is plain `apm audit`, not
-        #   `apm audit --ci` (the two are different modes, and --ci refuses to
-        #   combine with --file/--strip/--dry-run/PACKAGE). Plain `apm audit`
-        #   here reports `No apm.lock.yaml found -- nothing to scan` and exits 0,
-        #   so adding it would buy a second vacuous check, not coverage.
-        #
-        # What IS left is worth keeping, and is now run against seven manifests
-        # instead of one. lockfile-exists is conditional -- it is vacuous while
-        # every apm.yml declares `dependencies: {apm: [], mcp: []}`, and it arms
-        # itself the moment one does not (verified: adding a git dependency to
-        # plugins/lint/apm.yml fails with `apm.yml declares dependencies but
-        # apm.lock.yaml is absent`). manifest-parse is unconditional and fires on
-        # any malformed manifest (verified: a dependency entry missing its
-        # git/path/registry field fails with `Cannot parse apm.yml`). Running the
-        # six plugin packages is what makes either reachable for them at all --
-        # the root-only invocation audits the marketplace manifest and nothing
-        # else. Costs ~0.5s per package, needs no network (checked under
-        # `unshare -rn`), so this does NOT join apm-marketplace-check and
-        # apm-pack-check-clean on the offline SKIP= list.
-
-      - id: check-apm-agents-valid
-        name: Validate real APM agent files
-        description: Run agent-audit's validate.sh over every plugins/*/.apm/agents/*.agent.md file in this repo -- the artifacts it governs, not fixtures
-        entry: bash scripts/check-apm-agents-valid.sh
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-        # validate.sh was previously exercised only by check-scope-walkup-sync,
-        # and only against synthetic mktemp fixtures -- it had never run against
-        # the four agent files it governs. That is how ADR-0016 could be amended
-        # to bless a `disallowedTools` frontmatter field while validate.sh's
-        # allowlist still rejected it: the spec and its enforcer disagreed and
-        # every gate stayed green. The expected file set is derived from
-        # `git ls-files` (the pattern tests/run-bats.sh established) rather than
-        # a hardcoded count, and discovering zero files is an error, not a pass.
-        # Needs no network.
-
-      - id: apm-pack-check-clean
-        name: apm pack --check-clean
-        description: Release gate -- verify .claude-plugin/marketplace.json still matches what apm.yml + .apm/ would currently generate, and that per-package versions agree with the per_package versioning strategy. Closes issue #90's deferred item 3 (a check-clean-equivalent gate) using apm's own flag instead of custom drift logic.
-        entry: apm pack --check-versions --check-clean --dry-run
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
-      - id: check-vale-style-sync
-        name: Check Vale style copies are in sync
-        description: Diff skill-audit's Vale copy against agent-audit's canonical copy
-        entry: bash scripts/check-vale-style-sync.sh
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-        # verbose so the DOWNGRADED run is audible. This hook can pass while
-        # having verified strictly less than its name claims:
-        # CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1 skips all six glob probes
-        # and says so on a `passed (text-level only, vale unavailable)` line.
-        # 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
-        # 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.
-
-      - id: check-scope-walkup-sync
-        name: Check scope walk-up implementations agree
-        description: Behaviorally cross-check validate.sh, validate-provenance.sh, new-agent.sh, and new-skill.sh's independent $HOME/.git/apm.yml walk-up ports against each other
-        entry: bash scripts/check-scope-walkup-sync.sh
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
-      - id: check-release-needed
-        name: Check a release tag covers .pre-commit-hooks.yaml's paths
-        description: On push to main only, fail if files exposed via .pre-commit-hooks.yaml changed since the last tag
-        entry: bash scripts/check-release-needed.sh
-        language: system
-        stages: [pre-push]
-        pass_filenames: false
-        always_run: true
-
       - id: validate-plugins
         name: Validate plugins
         description: Run claude plugin validate --strict on every plugin directory
@@ -253,7 +85,7 @@ repos:
         description: Ensure SKILL.md files have required frontmatter fields
         entry: bash
         language: system
-        files: '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'
+        files: 'SKILL\.md$'
         args:
           - -c
           - |
@@ -266,42 +98,6 @@ repos:
               fi
             done
 
-      - id: skill-size-check
-        stages: ['pre-commit']
-        name: SKILL.md size and context-budget ceilings
-        description: Enforce agentskills.io's 500-line/2,770-whole-file-word spec ceilings AND ADR-0020's context budget -- description 250 chars SUGGESTION / 400 FAIL, body-only 600 words SUGGESTION / 900 FAIL, and every boundary-clause routing target resolving to a real skill or agent under plugins/*/.apm/
-        entry: scripts/skill-size-check.sh
-        language: script
-        files: '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'
-        pass_filenames: true
-        verbose: true
-        # verbose so the SUGGESTION tier is audible. ADR-0020 depends on it:
-        # "A ceiling does not produce an average ... The halving depends
-        # entirely on the 250-character SUGGESTION tier being visible and
-        # respected." pre-commit prints nothing at all for a passing hook, and
-        # a SUGGESTION deliberately does not fail, so without verbose every
-        # suggestion would be swallowed -- the exact invisibility ADR-0013
-        # records for Vale warnings. Costs nothing on a clean file: the script
-        # prints only findings.
-
-      - id: vale-audit-prefilter-skill
-        stages: ['pre-commit']
-        name: Vale audit prefilter (SKILL.md)
-        description: Run Vale against SKILL.md files as a deterministic prefilter for skill-audit, via skill-audit's own bundled copy
-        entry: plugins/kyberforge/.apm/skills/skill-audit/scripts/vale-wrap.sh
-        language: script
-        files: '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'
-        pass_filenames: true
-
-      - id: vale-audit-prefilter-agent
-        stages: ['pre-commit']
-        name: Vale audit prefilter (agent files)
-        description: Run Vale against agent markdown files as a deterministic prefilter for agent-audit, via agent-audit's own bundled copy
-        entry: plugins/kyberforge/.apm/skills/agent-audit/scripts/vale-wrap.sh
-        language: script
-        files: '^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$'
-        pass_filenames: true
-
   - repo: meta
     hooks:
       - id: check-hooks-apply

.pre-commit-hooks.yaml

@@ -1,23 +0,0 @@
--   id: kyberforge-vale-audit-skill
-    name: Kyberforge Vale prose audit (SKILL.md)
-    description: Deterministic prose-pattern prefilter for kyberforge's skill-audit, via its own bundled Vale config/styles
-    entry: plugins/kyberforge/.apm/skills/skill-audit/scripts/vale-wrap.sh
-    language: script
-    files: '(^|/)SKILL\.md$'
-
--   id: kyberforge-vale-audit-agent
-    name: Kyberforge Vale prose audit (agent files)
-    description: Deterministic prose-pattern prefilter for kyberforge's agent-audit, via its own bundled Vale config/styles
-    entry: plugins/kyberforge/.apm/skills/agent-audit/scripts/vale-wrap.sh
-    language: script
-    files: '(^|/)agents/[^/]+\.md$|\.agent\.md$'
-
--   id: kyberforge-skill-size-check
-    name: SKILL.md size and context-budget ceilings
-    description: Enforce agentskills.io's 500-line/2,770-whole-file-word spec ceilings plus ADR-0020's context budget (description 250 chars SUGGESTION / 400 FAIL, body-only 600 words SUGGESTION / 900 FAIL, resolvable boundary-clause routing targets)
-    entry: scripts/skill-size-check.sh
-    language: script
-    files: '(^|/)SKILL\.md$'
-    # verbose so the SUGGESTION tier reaches a human -- pre-commit prints
-    # nothing for a passing hook, and a SUGGESTION deliberately does not fail.
-    verbose: true

AGENTS.md

@@ -1,72 +1,33 @@
 # 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.
+This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
 
 ## 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
+- `plugins/` — installable plugin units; each is self-contained (skills, agents, hooks, MCP servers, bundled assets); install separately via `claude plugin install <name>@holocron`
 - `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `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:
-
-- `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
-
-**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.
-
-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`.
-
-## 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:
-
-- 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`
-- Issues, PRs, labels, milestones → `gitea-issues`, `gitea-prs`, `gitea-labels-milestones`; also `gitea-branches`, `gitea-files`, `gitea-releases`, or `gitea-workflow` when the domain is ambiguous
-- 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`.
-
-Fall back to raw shell only when no skill covers it.
-
-## Setup and testing
-
-- 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.
-
 ## Key documents
 
 Read CONTEXT.md at the start of every session in this repo.
 
 Read these on demand:
 
+- `docs/VISION.md` — purpose, goals, and long-term Management Application vision
 - `docs/spec/architecture.md` — current 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
 - `docs/notes/factory-integration-decisions.md` — decisions from the factory integration grill; read when making skill authoring or factory design decisions
 - Governance rules are always in effect — `core/instructions/governance.md` (agent rules); `docs/research/governance_principles/CONTROLS.md`
+
+## Working context
+
+This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them.
+
+## Subagent orchestration
+
+- **Forks stop when their assigned task is done.** A `fork` inherits the coordinator's full context, including visibility into any shared TaskList. That visibility is not license to keep going: once a fork's assigned task is reported complete, it must stop rather than autonomously picking up further items from the list. Forks that keep pulling work race against the coordinator's own orchestration and can duplicate or conflict with tasks the coordinator has separately delegated.
+- **Don't hand a fork a TaskList that includes governance-gated actions** (push, publish, merge) unless you are prepared for it to act on those items without a fresh confirmation round. A fork acting on its own initiative is not party to any pending human confirmation the coordinator is mid-flow on, so it can bypass a gate that was meant to hold.
+- **`TaskGet`/`TaskUpdate`/`TaskList` only work for forks.** Fresh (non-fork) subagents cannot discover or call these tools. When delegating to a fresh subagent, the coordinator owns all task-list bookkeeping itself — claim and complete the entry on the agent's behalf — rather than instructing the fresh agent to self-claim or self-complete.
+- **Worktree/branch cleanup is part of closing out the PR, not a separate step.** When a coordinator creates a worktree (`Agent(isolation: "worktree")` or `git worktree add` directly) to land a PR, merging that PR is not the end of the task. Immediately after verifying the merge: run `git worktree remove --force --force <path>` (the double `-f` is required whenever the worktree initialized submodules to run tests — assume it did, this repo has several), then `git branch -d` both the feature branch and any `worktree-agent-<id>` isolation branch the `Agent` tool auto-created for that worktree — `git worktree remove` deletes neither branch on its own. Do this without waiting for the user to notice stale branches/worktrees and ask.

CONTEXT.md

@@ -8,7 +8,7 @@ description: Domain language and decisions for the global AI development config
 ## Principles
 
 ### 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.
+`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-0012.
 
 ### 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.
@@ -24,39 +24,13 @@ Before answering any design or architecture question, check for existing decisio
 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.
 
 ### 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`).
-
-### 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.
-
-### 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.
-
-### 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).
-
-### 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.
-
-### 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.
+Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Deployed via plugin — `plugins/<plugin-name>/skills/<skill-name>/SKILL.md`, available after the plugin is installed (`claude plugin install <name>@<marketplace>`). Skills are self-contained — they cannot reference files outside the plugin directory after install-time caching.
 
 ### 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").
+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. Each plugin has two manifests: `.claude-plugin/plugin.json` (Claude Code) and `plugin.json` at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under `plugins/<name>/`. Install a plugin with `claude plugin install <name>@<marketplace>`.
 
 ### 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.
-
-### 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.
-
-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.
-
-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.
+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 lives at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) and is mirrored to `.github/plugin/marketplace.json`.
 
 ### 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.
@@ -72,13 +46,13 @@ 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`.
 
-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.
+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-0012.
 
 ### 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.
+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). `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` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`.
 
 ### 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).
+Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it).
 
 ### 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.
@@ -86,21 +60,5 @@ The three-stage traceability record linking a skill back to its research inputs:
 ### 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.
 
-### 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.
-
-### 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.
-
-### 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.
-
-### 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.
-
-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.
-
-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.
-
 ### 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.

LESSONS.md

@@ -2,7 +2,7 @@
 
 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.
 
-**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: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/git.md` for git conventions, or `core/instructions/testing.md` for testing conventions. 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.
 
@@ -26,8 +26,6 @@ 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.
-
 ## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity
 
 Behavioral tests (2026-05-17) showed three communication/behavior rules failing: exploratory question format (gave verbose multi-bullet answer instead of 2-3 sentences), file edit intent (asked for clarification instead of stating intent and proceeding), and push confirmation (went straight to tool call instead of asking first). All three rules are present in `providers/claude-code/CLAUDE.md` as one-liner statements. The RLHF-trained defaults (thorough answers, risk-averse clarification seeking, fast execution) consistently outcompete thin rules. Fix: rewrite failing rules with specificity, a counter-example, and a boundary statement — not just a single-line imperative.
@@ -126,7 +124,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 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/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
 
@@ -139,125 +137,3 @@ After a PR merge (with Gitea's default auto-delete-branch behavior), `git branch
 ## 2026-05-18 — Planning meta-commentary does not belong in deployed artifacts
 
 During write-skill refactor, an "open thread" note (about a deferred research step) was written directly into the SKILL.md Process section. The user caught it. The rule it violated: a deployed artifact (SKILL.md, a runtime file loaded by agents) must not contain planning meta-commentary — deferred items, open threads, and implementation notes belong in the issue file, which is the planning artifact. The skill body should contain only content relevant to runtime execution. If a decision is deferred, record it in the issue and leave no trace in the skill. The distinction: issue = planning record; skill = executable instruction.
-
-## 2026-08-08 — A clean linter result can mean "nothing was checked"
-
-Three separate times in one PR (#85), a check reported success because it had silently not run. (1) Vale's `text.frontmatter.description` scope stops matching once the value is a multi-line YAML block scalar — the style most skills here use — so a repo-wide sweep returned 0 alerts across 49 files and was read as a clean repo. (2) Five of six rules were `level: warning`, but Vale's exit code keys on `error` alone and pre-commit hides output from passing hooks, so those rules were invisible and blocked nothing for two review rounds while the ADR described them as "enforcing immediately." (3) `.vale.ini`'s globs matched no file outside `plugins/`, so Vale printed "0 files" and exited 0, which both audit skills read as "no findings" and used to skip their own judgment passes. Each time the green result was worse than no check at all, because it was cited as positive evidence of cleanliness. Fix: for any new check, prove it fails before trusting that it passes — run it against a deliberately-bad fixture, confirm the failure, then run the real corpus. Where a check can scan zero inputs, assert on the input count, not just the exit code. **[graduated → core/instructions/testing.md]** (4th instance below, kept for audit trail).
-
-**5th instance (2026-08-09, PR #85 round 6):** `tests/test-vale-hooks-consumer.sh` asserted `grep -c "VagueWording" >= 2` across the *combined* output of both shipped Vale hooks, and the SKILL.md fixture alone raised two alerts — so one working hook satisfied the threshold and the agent hook could be disabled entirely (glob retargeted to match nothing) while the suite still reported `3 passed` under the message "both hooks flatten and flag". The `Skipped` guard did not catch it: the hook still *matched* the file, Vale simply linted nothing, reported `0 errors in 1 file`, and exited 0, which pre-commit renders as `Passed`. The general shape: **an assertion that aggregates over N subjects proves nothing about any individual subject** — a total is satisfiable by a proper subset. Fix: attribute each signal to its source before asserting (alerts are now filed by path, with a distinct trigger token per fixture so one hook's alert cannot be credited to another), and assert per subject. Corollary technique, now standing practice for any check whose failure mode is silence: run the mutation sweep in *reverse* as well — neuter each assertion in turn and confirm exactly one test case fails. Applied to `check-vale-style-sync.sh` it exposed two assertions bound to no failing case at all, one of them masked by a stronger check that ran first.
-
-**4th instance (2026-08-09, ADR-0014):** splitting the single root `.vale.ini` into two skill-scoped copies (skill-audit: `SKILL.md` only; agent-audit: agent files only) meant a single retargeted pre-commit hook pointed at agent-audit's copy alone would have silently scanned 0 `SKILL.md` files and exited 0 — caught only because the full corpus was dry-run against both the old and new config and the outputs diffed before the old config was deleted, not because any test asserted on file counts. Standing practice going forward: when a Vale (or any linter) config that serves multiple file-glob scopes is split or moved, dry-run the full corpus through both the old and new config and diff the outputs before removing the superseded source — a hook silently scanning 0 files looks identical to a clean pass.
-
-## 2026-08-08 — One signal, two consumers, no named distinction
-
-Vale's output fed two consumers with different contracts: the audit skills read severity *strings* to grade a report (`error`→FAIL, `warning`→SUGGESTION), while the pre-commit hook read the process *exit code* to allow or block a commit. Severities were tuned for the first consumer; the second silently inherited whatever exit code that produced, which was always 0. CONTEXT.md described both as a single mechanism under one heading, which is precisely why the divergence went unnoticed — there was no vocabulary in which "the gate" and "the prefilter" were different things that could disagree. Fix: when one output feeds two consumers, name them separately in the domain language and state each contract explicitly. If they cannot be given independent contracts, collapse them into one — which is what happened here: every rule became `level: error`, so the gate and the audit now share a single verdict with nothing to keep in sync.
-
-## 2026-08-08 — Measure a rule's false-positive rate at the severity you will ship it at
-
-`Kyberforge.VagueQualifier` was cherry-picked from `write-good` after being trialled as "low-noise against this repo's corpus" — but the trial ran at `level: warning`, where a false positive costs nothing because nobody ever sees it. Shipped at `error`, the same false positive costs a blocked commit and a permanent suppression comment. Re-measured at the severity it actually shipped at, the rule scored one marginal true positive and one unfixable false positive across 41 files (`caveman/SKILL.md` *quotes* filler words as its subject matter — a mention, not a use), and was deleted. Fix: trial conditions must match shipping conditions. A noise measurement taken where false positives are free does not transfer to a context where they are expensive, and "low-noise" is not a property of a rule alone — it is a property of the rule at a severity.
-
-## 2026-08-09 — Exercising a config's "local" mode proves nothing about the mode that ships
-
-The root `.pre-commit-hooks.yaml` shipped Vale hooks whose `entry:` carried a `--config <repo-relative-path>` argument. 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: each external consumer hard-failed with `E100 [--config] Runtime error ... does not exist`, and two of the three hooks ADR-0014 promised were unusable. The defect survived three review rounds of PR #85 and a green `pre-commit run --all-files` every time, because this repo consumes the same hooks through `repo: local`, where the clone prefix, the cwd, and the repo root are one directory — the byte-identical `entry:` string worked locally for a reason that exists only locally. Nothing under `tests/` exercised the manifest as a hook repo at all. The sharp part: the local run was not weaker evidence of the same thing, it was evidence of a different thing, and the two were indistinguishable by reading either file. Fix: when a config has a local mode whose resolution semantics differ from the shipped mode, test the shipped mode against a real consumer — `tests/test-vale-hooks-consumer.sh` stands up a `file://` clone of this repo and runs the hooks from it — and then delete the divergence rather than living with it: `vale-wrap.sh` now self-locates its config from `${BASH_SOURCE[0]}`, and the local and shipped `entry:` lines are identical, so the local run no longer exercises a path no consumer takes.
-
-## 2026-08-09 — Deleting a token from a shared artifact breaks whatever parses it, silently
-
-Dropping the `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `scripts/check-release-needed.sh` derived its release-relevant path list by scanning those same `entry:` lines for `--config` and taking the target's `dirname` — that parse was the only thing giving the bundled `.vale.ini` and its sibling `styles/` tree release coverage. With the token gone the loop simply never fired: no error, no failing test, no warning, just a path list that shrank from six entries to four and lost both `assets/vale/` trees. Consequence: a change to a Vale *rule* could land on `main` without demanding a release tag, leaving external consumers pinned to an old `rev:` with stale rules — the exact drift the gate exists to prevent. It surfaced only because the agent making the change reported it as a suspected side effect of its own edit, and was confirmed by diffing the derived path list before and after. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* the artifact, not just everything that consumes its documented purpose. The smell to watch for is a loop that builds a list, where an empty or short list is indistinguishable from a correct one — assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less.
-
-## 2026-08-09 — A documented impossibility is a claim, not a constraint
-
-`vale-wrap.sh` flattens multi-line YAML `description:` scalars so Vale's `text.frontmatter.description` scope keeps matching. Its last-resort branch rewrote ASCII `'` to U+2019, justified at the emission site and in review as "the single combination no YAML scalar can carry verbatim" — an accepted-by-design residual, documented and test-covered, which is exactly why nobody retested it. The claim was false: a `|-` literal block with one indented content line carries `'`, `"`, `\` and `: ` verbatim, keeps the scope alive, and the wrapper's own header docstring already said literal blocks were unaffected. The cost of the unexamined claim was a silent underlint on 12 of 54 in-scope files — any rule whose token contained an apostrophe simply never fired, and the covering test (case 20) pinned only "the scope stays alive", so it passed either way. Fix: when a residual is accepted because something is "impossible", write down the specific claim in a falsifiable form and test *that*, not the workaround built on top of it. The tell here was that the residual and its justification were documented in the same breath by the same author — documentation records a belief, and a belief adjacent to a workaround is the one most worth attacking. Related: an assertion written to cover an accepted residual tends to assert the residual's *presence* rather than the behaviour it costs; case 20b asserted the scope survived flattening, never that a rule matching the rewritten characters still fired.
-
-## 2026-08-14 — A fix handed down with authority is the least-reviewed code in the change
-
-Across one review round, four fixes specified by the orchestrating reviewer were wrong, and every one would have shipped a guard that looked correct and caught nothing — the same defect class the guard was written to close. `nproc([[:space:]]|$)` does not match `$(nproc)`, the only spelling that occurs in real code. `grep -E ... | grep -Evq ...` under `set -o pipefail` returns 141 because `-q` exits on first match and SIGPIPEs the upstream, and 141 as an `if` condition reads as "no findings" — worse, it is *size-dependent*, so on the real 4-line `.vale.ini` the broken form behaves correctly and only fails once the input grows. `FUNCNAME` and `BASH_ARGC` were proposed as never-empty shell arrays to exempt from an unguarded-expansion scan; both are empty in reachable states (outside a function; `BASH_ARGC` measured 1 at top level and 0 inside a function), so exempting them suppresses a real bash 3.2 abort. `sed 's/#.*//'` as a comment-stripper truncates at the `#` in `${var#prefix}` — a form this repo actually uses at `check-manifests.sh:58` — reintroducing the exact blind spot being fixed. Each was caught only because the implementing agent re-derived the fix and measured, rather than applying what it was told; each had survived being written down confidently in a numbered finding with a reproduction attached. The asymmetry is the point: a finding arrives with evidence and gets scrutinised, while the fix beside it arrives with the same authority and gets implemented. Fix: state a proposed fix as a hypothesis with its own falsifiable check, and require the implementer to verify the fix mechanism independently of the defect reproduction — the two are different claims. The tell is a fix whose correctness depends on a regex boundary, a shell exit-status rule, or an "always/never" property of a builtin: measure it at the size, scope, and spelling it will actually meet, because the small case and the shipped case can disagree.
-
-## 2026-08-14 — Every assertion needs a revert it provably fails against [graduation candidate]
-
-Mutation testing a review round's own fixes found repeatedly that a passing test was pinning nothing. Deleting `sync_dir`'s stale-directory wipe, its check-mode stale branch, or three of five `MIRROR_DIRS` entries each left the suite at 18/18 green; so did replacing the hooks trailing-newline normalisation with plain `cp`. A pair of concurrency assertions written to guard a reentrancy defect caught it 0 times in 10 runs against the deliberately broken script — and one of them was structurally incapable of ever catching it, because the broken code wrote to the system temp dir while the assertion inspected `$TMPDIR`. A fixture-leak fix ran green with and without the fix, verified only by external observation. Two manifest fixtures passed with the canonicalisation they claimed to cover deleted, rescued by an unrelated name-matching axis. In each case the test named the right behaviour in its description and asserted something adjacent to it. The cheap discipline that finds all of these: for every assertion, construct the revert it is supposed to catch and confirm it fails — and when an assertion survives every revert you can think of, that is not reassurance, it is the finding (one test only revealed itself as decoration once a sixth, differently-targeted revert was built for it). Fix: treat "which revert does this fail against?" as a required answer at the time an assertion is written, and record it where the assertion lives, since a test's own description is exactly the artifact that made the gap invisible.
-
-Graduation candidate: this overlaps 2026-08-09's "an assertion written to cover an accepted residual tends to assert the residual's presence rather than the behaviour it costs" and the same date's "assert on the expected members, so a derivation whose input vanished fails loudly instead of quietly covering less." Three entries circling one pattern — human review for promotion to `core/instructions/testing.md`.
-
-## 2026-08-14 — Vale's `existence` extension concatenates `raw:` entries, it does not alternate them
-
-A new `Kyberforge.CompositionNote` rule was first written with seven `raw:` entries, one per banned
-phrasing. Vale loaded it without a diagnostic and it matched **zero of 43 files** — an outcome
-indistinguishable from a clean corpus, and the exact shape of 2026-08-08's "a clean linter result can
-mean nothing was checked". The cause is that `existence` joins multiple `raw:` entries into one
-pattern rather than OR-ing them, so the rule was searching for all seven phrases concatenated. Every
-pre-existing rule in this style has exactly one `raw:` entry, so nothing in the repo demonstrated the
-difference, and the multi-entry form looks natural beside them. `tokens:` is the alternated form,
-which is why `VagueWording` uses it. Fix: a new Vale rule is not landed until it has been shown to
-*fire* — the standing revert-check applies to linter rules as much as to tests, and the revert here
-is the broken multi-`raw:` form, which `tests/test-vale-hooks-consumer.sh` now fails against.
-
-## 2026-08-14 — Un-anchoring a description rule to reach mid-sentence text is unshippable
-
-Widening `DescriptionOpener` to catch `gitea-workflow`'s mid-description "This is the human-facing
-entry point…" looked like a one-character change. Both that skill and `gitea-labels-milestones`
-*open* with "Use when…" and satisfy the opener rule; the offending clause sits at character 377 and
-300 of the folded value respectively, so the rule was never violated and never silently passed — it
-simply had no jurisdiction, which is a different defect and takes a different fix.
-Under `scope: text.frontmatter.description`, `^`
-anchors to the start of the whole description value — and `vale-wrap.sh` has already flattened that
-value to one physical line, so `(?m)` changes nothing. Un-anchoring is therefore the only route to
-mid-description text, and measured across the corpus it scores 5 hits and 5 false positives: skills
-legitimately quote user phrasings (`says "audit this skill"`) and write boundary clauses (`do not use
-this skill to manage label definitions`). That is the `Kyberforge.VagueQualifier` deletion repeating.
-Fix: keep the opener rule opener-anchored and give mid-description prose its own rule with its own
-token list. A rule's scope anchor is part of its contract, not an implementation detail to relax when
-a new case does not fit.
-
-## 2026-08-14 — A formatter in the commit path manufactures drift on a file with a clean git diff
-
-`apm audit --ci` failed on `.claude/settings.json` while `git diff` on that file was empty — the worst
-possible pairing of signals, because the file matched HEAD exactly and every instinct says "nothing
-changed here". The content was identical to apm's output to the byte; only the JSON key order
-differed. `pretty-format-json --autofix` sorts object keys unless `--no-sort-keys` is passed, and its
-`exclude:` listed fifteen generated manifests but not this file, so from the commit that first wrote
-a hook entry there onward, apm's insertion-ordered output was silently re-sorted on the way in. apm
-then replayed the install, produced its own order, and reported drift against a file no human had
-touched.
-
-The provenance matters as much as the mechanism, and the first account of this entry got it wrong in
-both directions. `git log --format='%h %ad %s' --date=iso` puts the introducing commit `2e395a4` at
-2026-08-14 18:47 and the fix `7607522` at 21:54 — roughly three hours, not "weeks". And `2e395a4` is
-the **first commit of the `refactor/trim-skills-agents-context` branch**, eleven minutes after the
-base merge `f9b919d`; `git branch -a --contains 2e395a4` returns only that branch and its own
-`remotes/origin/` tracking copy — two lines naming one branch, and `main` is not among them. So
-this was not a latent defect inherited from `main`, it was manufactured inside the same PR that
-diagnosed it, and the fixing commit's own message calling it "pre-existing … red at HEAD before
-ADR-0020 work began" is the mis-attribution rather than the record. Two cheap commands would have
-settled it before either sentence was written.
-
-Three general points. First, a tool-owned generated file that passes through an autofixing formatter
-is drifted by construction, and the diff that would reveal it never appears in `git diff` — it only
-exists between the formatter's input and its output, which nothing stores. Second, the fix is
-self-undoing unless the exclude lands in the same commit: correcting the file alone means the hook
-re-breaks it as it is staged. Third — the one this entry had to learn twice — "pre-existing" is a
-claim about history, and history is queryable; a defect found while working on a branch feels
-inherited, and the feeling is not evidence. A three-hour-old self-inflicted bug and a months-old
-inherited one call for different responses, and writing the wrong one down converts a process failure
-into a story about someone else's neglect. Fix: when a tool declares ownership of a path, add that
-path to every autofixing hook's `exclude` at the moment ownership is declared, not when the drift is
-noticed — and before describing any defect as pre-existing, run `git log -S` or
-`git branch --contains` on the commit that introduced it. This repo gates marketplace-mirror,
-plugin-content and vale-style drift deterministically and has no equivalent gate asserting tool-owned
-paths stay out of formatter scope — `.claude/settings.json` was the sixteenth exclude and nothing
-prevents a seventeenth.
-
-## 2026-08-16 — A rule reversed inside a retrofit leaves no trace unless someone writes it down
-
-`skill-author/SKILL.md:204` on `main` said "Keep reference chains one level deep — a reference file
-that references another reference file is rarely loaded correctly." The ADR-0020 retrofit replaced it
-with "Two hops from `SKILL.md`, never three" in `references/create.md` and `references/retrofit.md`,
-which permits exactly the chain the old rule banned. The looser rule is the right one and the
-retrofit could not have shipped without it: dispatch pushes each flow into its own file, so the
-shipped structure is `SKILL.md` → `improve.md` → `retrofit.md`, and a one-level ceiling would have
-made the mandatory dispatch pattern illegal. But ADR-0020 says nothing about chain depth, so the
-reversal was carried entirely by the diff — the new text asserts the new rule with no sign that a
-contradicting rule ever existed, and a reader who remembers the old one has no way to tell whether it
-was overturned or overlooked. Fix: when a change inverts a standing authoring rule rather than
-tightening or restating it, record the inversion where the rule's rationale lives — the ADR if the
-ADR is the reason, here otherwise. A rule that quietly flips is indistinguishable from a rule that
-was forgotten, and the second reading is the one that gets it re-added later.

apm.yml

@@ -1,119 +0,0 @@
-name: holocron
-version: 0.4.2
-description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
-license: MIT
-
-# Consumer side: this repo installs its own published plugins from the holocron
-# remote, so the working copy runs the same released content every other
-# consumer gets. Addressed as git+path objects rather than <name>@holocron
-# marketplace aliases — an alias needs a `apm marketplace add` registration in
-# ~/.apm/marketplaces.json (user scope, outside this repo), the object form
-# needs nothing beyond this manifest.
-# Unpinned (default branch) on purpose: parity with the Claude Code plugin
-# install this replaced, which ran autoUpdate against main. Add `ref: <tag>`
-# per entry to pin.
-targets:
-  - claude
-dependencies:
-  apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/bin
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/core
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/git
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/gitea
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/kyberforge
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/lint
-  mcp: []
-
-# Turns apm's executable-trust gate ON. Without this block the gate is disabled
-# and every hook, bin and MCP primitive a dependency ships deploys silently —
-# verified: `apm approve --list` reports "Executable-trust gate disabled -- all
-# executables deploy" until an `executables:` block exists.
-#
-# kyberforge ships the SessionStart hook that keeps this install level with the
-# remote (ADR-0019). The key is version-pinned by apm's own design, so a
-# kyberforge version bump makes this entry stop matching and the hook stops
-# deploying until the version here is bumped too. If skills silently go stale
-# after a kyberforge release, check this first.
-executables:
-  allow:
-    kyberforge#1.6.0:
-      hooks: true
-      bin: true
-
-marketplace:
-  # apm's Claude marketplace mapper only emits description:/version: into the
-  # compiled marketplace.json when set explicitly here (an override) — the
-  # 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
-  owner:
-    name: Defame1297
-    email: defame1297@rkdr.net
-    url: https://git.dev.rkdr.net/Defame1297/
-
-  # Default tag pattern used to resolve version ranges for each package.
-  build:
-    tagPattern: "v{version}"
-
-  # Output targets (map form). Each output writes to its profile default
-  # path; add 'path:' under a key to override.
-  # 'codex' requires every package below to declare 'category:' (satisfied).
-  outputs:
-    claude: {}
-    codex: {}
-
-  # CI tip: build one or all formats with a machine-readable manifest:
-  #   apm pack --marketplace=claude,codex --json | jq -r '.marketplace.outputs[].path'
-
-  versioning:
-    strategy: per_package
-
-  packages:
-    - 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
-      category: Developer Tools
-
-    - name: bin
-      description: A place for things to be binned
-      source: ./plugins/bin
-      version: 1.1.3
-      category: Utilities
-
-    - name: git
-      description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.
-      source: ./plugins/git
-      version: 1.3.3
-      category: Version Control
-
-    - name: gitea
-      description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.
-      source: ./plugins/gitea
-      version: 1.3.4
-      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
-      category: Productivity
-
-    - name: mattpocock-skills
-      description: Skills for Real Engineers — planning, TDD, architecture, and debugging workflows from Matt Pocock's .claude directory.
-      source: mattpocock/skills
-      version: "1.2.3"
-      category: Productivity
-
-    - name: lint
-      description: Skills and agents for configuring and running linters.
-      source: ./plugins/lint
-      version: 1.1.6
-      category: Developer Tools

core/AGENTS.md

@@ -23,4 +23,3 @@ Read these files on demand:
 
 - **Coding conventions** (`~/.claude/core/instructions/coding.md`) — when writing, editing, or reviewing code
 - **Testing conventions** (`~/.claude/core/instructions/testing.md`) — when writing or running tests
-- **Subagent orchestration** (`~/.claude/core/instructions/subagent-orchestration.md`) — when spawning or coordinating subagents/forks

core/instructions/subagent-orchestration.md

@@ -1,6 +0,0 @@
-# Subagent orchestration
-
-- A fork stops when its assigned task is done. It inherits the coordinator's full context, including any shared TaskList — that visibility is not license to keep pulling further items after its assigned task is reported complete; doing so races the coordinator's own orchestration and can duplicate or conflict with separately-delegated work.
-- Don't hand a fork a TaskList containing governance-gated actions (push, publish, merge) unless prepared for it to act on those without a fresh confirmation round. A fork acting on its own initiative is not party to any pending human confirmation the coordinator is mid-flow on.
-- `TaskGet`/`TaskUpdate`/`TaskList` only work for forks. Fresh (non-fork) subagents cannot discover or call these tools — when delegating to a fresh subagent, the coordinator owns all task-list bookkeeping itself.
-- `Agent(isolation: "worktree")` may fork from `main`, not the branch the coordinator was on. Verify and self-correct (`git merge --ff-only <target-branch>` or reset onto `origin/<target-branch>`) before editing. When removing such a worktree afterward, use `git worktree remove --force --force <path>` if the repo has submodules (double `-f` required), then `git branch -d` both the feature branch and the auto-created `worktree-agent-<id>` isolation branch.

core/instructions/testing.md

@@ -4,4 +4,3 @@
 - Automate everything automatable. Manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment.
 - Test observable end-state, not implementation internals. Tests must survive refactoring.
 - No test is better than a wrong test. A passing mock that masks a real failure is actively harmful.
-- A clean result can mean nothing ran. Before trusting a new check, prove it fails against a deliberately-bad fixture, then run it against the real target. Where a check can scan zero inputs, assert on the input count, not just the exit code — a zero-file run and a real clean pass look identical otherwise.

docs/adr/0001-skills-in-agents-dir.md

@@ -1,16 +1,5 @@
 # Skills are distributed via plugins, not monolithic repo deployment
 
-**Superseded by:** ADR-0015 (Microsoft APM replaces the hand-authored plugin/marketplace model
-as this repo's authoring source of truth) and, for plugin-scope agent files specifically,
-ADR-0016 (plugin-scope `.apm/agents/*.agent.md` drops provider-specific fields). Since issue
-#90's conversion executed, plugin content is authored under `plugins/<name>/apm.yml` +
-`.apm/{skills,agents,hooks}/` — not the flat `skills/`/`agents/` layout this ADR describes —
-and `.claude-plugin/plugin.json`/`.github/plugin/plugin.json` are compiled output of `apm pack`,
-not hand-authored. This ADR's content is kept below as the historical record of the
-pre-APM decision; it is no longer the current model.
-
----
-
 Skills (slash commands) are authored and distributed as part of **plugins** — each plugin contains its own `skills/` directory alongside agents and other artifacts. Plugins are installed via `claude plugin install <name>@holocron` rather than deployed from the repo's local tree. This decision decouples skill authoring cadence from core provider deployments and allows independent versioning per plugin.
 
 ## Context

docs/adr/0005-agent-author-dual-provider-scaffold.md

@@ -44,8 +44,3 @@ separate single-provider skill, adding complexity with no benefit.
 file now lives at `<plugin-root>/sources.md`, outside the `agents/` directory, because
 `claude plugin validate --strict` auto-discovers every `.md` under `agents/` as an agent
 requiring frontmatter. See ADR-0010 for the empirical finding and rationale.
-
-**Update (ADR-0016):** the plugin-scope clause above is superseded. Plugin scope is no longer
-detected via `plugin.json`, and no longer produces a Claude+Copilot file pair — a directory
-containing `apm.yml` now gets a single vendor-neutral `.apm/agents/<name>.agent.md` file with
-no provider-specific fields. Project scope and user scope are unaffected. See ADR-0016.

docs/adr/0006-plugin-version-parity.md

@@ -1,18 +1,5 @@
 # version field is present in both plugin manifests
 
-**Moot as of ADR-0015.** This ADR addressed drift risk between two independently
-*hand-maintained* manifests. Since issue #90's conversion executed, `.claude-plugin/plugin.json`
-and `.github/plugin/plugin.json` are both **compiled output** of `apm pack`, generated in the
-same pass from a single `apm.yml` per plugin — there is no longer a second hand-authored file
-that could drift out of parity. The invariant this ADR required (`version` present and
-identical in both manifests) still holds in the compiled output, but structurally, not because
-a skill enforces it: both files are derived from the same `apm.yml` `version:` field, so
-divergence is no longer possible by construction. `plugin-author`, the skill that enforced this
-invariant, is deleted per ADR-0015 rather than adapted. Kept below as the historical record of
-the pre-APM decision.
-
----
-
 Each plugin has two manifests: `plugin.json` (Copilot CLI) and `.claude-plugin/plugin.json` (Claude Code). Both tools support a `version` field. Prior to this decision, only the CC manifest carried `version`; the Copilot manifest omitted it.
 
 We now require `version` in both manifests, always identical. A reader of `plugin.json` alone should be able to determine the plugin version without consulting the CC manifest. The `plugin-author` skill enforces this invariant on every create, update, and release operation.

docs/adr/0007-gitea-canonical-issue-tracker.md

@@ -2,8 +2,6 @@
 
 **Supersedes:** ADR-0011 (provider-agnostic issue tracker with file-based default — archived during refactoring)
 
-> **Note on the ADR-0011 number.** Every "ADR-0011" on this page means the *archived* provider-agnostic issue tracker ADR, which no longer exists in `docs/adr/` — it was removed when it was superseded, and the number 0011 was later reused for an unrelated decision, `docs/adr/0011-gitea-skill-deep-modules.md` (the gitea skill's split into deep modules). That file is not the ADR referenced below. The number is not renumbered here: these ADRs are a published record and renumbering would break every citation that already points at either one. The archived text is recoverable from git history.
-
 ADR-0011 established a provider-agnostic model with `docs/issues/NNNN-<slug>.md` as the file-based default, switching to Gitea MCP at runtime when available. The interim model was justified because Gitea would not be configured until after Chunk 3, and the repo needed to work before then.
 
 Gitea is now configured and in active use. The condition in ADR-0011 has been met. This ADR supersedes it.

docs/adr/0008-agent-audit-single-file-invocation.md

@@ -14,9 +14,3 @@
 - Scope detection walks up from the input file: first directory containing `plugin.json` → plugin scope; first directory containing `.git` without `plugin.json` → project scope; path under `~` with neither → user scope.
 - At user scope the derivation crosses filesystem locations (`~/.claude/agents/` ↔ `~/.copilot/agents/`); the script must handle the home directory case explicitly.
 - The invocation signature is the public contract. Changing it is a breaking change to any caller — treat it as such.
-
-**Update (ADR-0016):** the plugin-scope clause above is superseded. Plugin scope is no longer
-detected via `plugin.json`, and there is no counterpart to derive — a directory containing
-`apm.yml` produces a single `.apm/agents/<name>.agent.md` file, and `agent-audit` validates it
-directly with no pair-consistency check. Project scope and user scope keep the pair-derivation
-mechanism described above unchanged. See ADR-0016.

docs/adr/0010-agent-sources-relocated-outside-agents-dir.md

@@ -5,21 +5,6 @@ claim that "both files share a single `agents/sources.md` for provenance." The r
 ADR-0005 (dual-provider generation, scope detection, single-root script interface) is
 unaffected and remains in force.
 
-**Path update per ADR-0016:** at plugin scope, agent files no longer live at
-`<plugin-root>/agents/<name>.md`. The authoring source is now
-`<plugin-root>/.apm/agents/<name>.agent.md` — a single vendor-neutral file (no dual Claude/
-Copilot pair) compiled to both targets via `apm pack`. See ADR-0016 for why (the field-dropping
-rationale, `tools:` incompatibility, the compiled-output mechanics) — not restated here. This
-ADR's own conclusion is unaffected by that move: the provenance file still belongs at
-`<plugin-root>/sources.md`, outside any directory `claude plugin validate --strict`
-auto-scans, and `.apm/agents/` is, if anything, further removed from plugin-root than the old
-flat `agents/` directory was, so the reasoning below still holds. References below to
-`<plugin-root>/agents/` describe the pre-APM layout in effect when this decision was made.
-**Scope boundary (per ADR-0016):** this path change is plugin scope only. Project scope
-(`.claude/agents/` + `.github/agents/`) and user scope (`~/.claude/agents/` +
-`~/.copilot/agents/`) are unaffected — they are not APM packages and keep the dual-file
-Claude+Copilot pair model this ADR originally described.
-
 `claude plugin validate --strict` auto-discovers every `.md` file directly under a plugin's
 `agents/` directory and treats it as an agent definition requiring YAML frontmatter (`name`,
 `description`, etc.). A flat provenance file at `agents/sources.md` — no frontmatter, by

docs/adr/0012-agentsmd-tooling-in-core-plugin.md

@@ -1,16 +0,0 @@
-# AGENTS.md tooling lives in `core`, split into three skills
-
-`kyberforge` is scoped to meta-tooling for building and maintaining the holocron marketplace itself (skills, agents, plugins, marketplace entries) — not to generic capabilities for an arbitrary target repo. Authoring and reviewing a target repo's `AGENTS.md` file is repo-agnostic documentation tooling, closer in kind to `bin:write-docs` or `bin:init` than to `skill-author`/`plugin-author`. Research for this topic was initially placed under `plugins/kyberforge/docs/research/docs/agentsmd/` but has moved to `plugins/core/docs/research/docs/agentsmd/` to keep the provenance chain consistent with the plugin the resulting skills live in.
-
-## Decision
-
-Three skills in the `core` plugin (`core`'s first active skills):
-
-- **`agentsmd-author`** — creates/updates a target repo's `AGENTS.md`, including nested monorepo placement (nearest-file-wins). Closes out by invoking `agentsmd-audit` inline, mirroring the `skill-author`/`skill-audit` pattern. When it detects an existing provider-specific file (`CLAUDE.md`, etc.) with content that duplicates what AGENTS.md should own, it calls `provider-adapter-author` via skill composition.
-- **`agentsmd-audit`** — a single combined pass checking three mandatory baselines against `AGENTS.md` only: secrets/credentials (governance.md hard prohibition), structural completeness (common-sections checklist from the agents.md spec), and accuracy/drift (do referenced commands/paths resolve against the repo). Never inspects provider adapter files.
-- **`provider-adapter-author`** — detects and converts a provider-specific instruction file into a thin adapter that imports `AGENTS.md` (mirroring this repo's own two-tier `CLAUDE.md` pattern). Self-validates via its own bundled deterministic script (`scripts/validate-adapter.sh`) rather than a separate paired audit skill, since the check (import present, no duplicated headings, size threshold) is mechanical.
-
-## Consequences
-
-- `core`'s plugin.json/README will list real skills for the first time.
-- `plugins/kyberforge/docs/research/docs/agentsmd/` moves to `plugins/core/docs/research/docs/agentsmd/` before authoring begins.

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

@@ -1,121 +0,0 @@
-# Vale audit prefilter expands into a plugin-content harness, scoped to prose-pattern rules only
-
-Issue #84 wired Vale as a deterministic prefilter for `skill-audit`/`agent-audit`, scoped to
-exactly four pattern-matchable checks (imperative description opener, vague capability wording,
-generic reference-pointer padding, Copilot's dead `Use proactively` phrasing), documented only in
-CONTEXT.md's "Vale audit prefilter" section — never its own ADR — and explicitly excluding body
-discipline, near-miss exclusion strength, and control calibration as non-goals. This ADR records a
-deferred PR #85 review item to broaden that coverage, retroactively captures #84's own rationale
-(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.
-
-**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
-spec-governed content, and `plugin.json` is JSON, not prose Vale can meaningfully lint.
-
-**Rule categories are prose-pattern-matchable only.** Structural, schema, and security concerns
-stay out of this Vale-based harness because this repo already has dedicated tools for them:
-`skill-frontmatter` (required frontmatter fields), `validate-plugins`/`validate-marketplace`
-(`claude plugin validate --strict`, schema), and `gitleaks`/`detect-private-key` (secrets).
-Duplicating those concerns as Vale rules would fight tools that already own them better.
-
-**Governance docs are excluded as a rule source.** `docs/research/governance_principles/CONTROLS.md`
-and `governance.md` were investigated and found to contribute nothing minable: CONTROLS.md is
-org/CI-infrastructure controls (secret scanning, dependency/license scanning, agent permission
-scoping, audit logging, human approval gates, periodic reviews) — none of it is a prose pattern
-expressible as a Vale rule against SKILL.md/agent-file text, and what it does cover is either
-already handled elsewhere (gitleaks) or genuinely out of scope for a plugin-content prose harness
-(dependency/license scanning is a code-dependency concern, not skill authoring).
-
-**Spec-derived custom rules stay mostly as-is.** Re-reading agentskills.io's
-`optimizing-descriptions.md` and `skill-authoring.md`, plus `claude-code-plugins/agent-definition.md`
-and `github-copilot-plugins/agent-definition.md`, found that the existing four Kyberforge rules
-already cover the pattern-matchable surface those specs describe. The remaining spec guidance —
-calibrating control vs. giving freedom, avoiding menus of options, coherent skill scope, moderate
-detail level — is semantic judgment, already `skill-audit`'s job via LLM review, not new lintable
-rules. One confirmation surfaced: Claude Code's `Use proactively` phrasing is meaningful for `.md`
-agent files (it triggers auto-invocation), unlike Copilot's `.agent.md` files where it's dead
-phrasing — so `KyberforgeCopilot/ProactivePhrase`'s existing `.agent.md`-only scope is correct and
-must not be extended to `.md` files.
-
-**`write-good`/`alex` are trialed, not adopted wholesale.** These built-in/third-party Vale
-packages are tuned for general blog-style prose (passive voice, weasel words, wordy phrases) and
-are expected to be noisy against this repo's terse, imperative instruction-file corpus. Only
-individual rules proven low-noise against the existing corpus get cherry-picked into
-`styles/Kyberforge`; the packages are never referenced wholesale in `BasedOnStyles`.
-
-**A new non-Vale check closes a real gap.** `skill-authoring.md` states `SKILL.md` should stay
-under 500 lines / 5,000 tokens — currently unenforced anywhere in this repo. This is a whole-file
-length ceiling, not a text pattern, so it isn't a Vale rule — it becomes a new deterministic script
-and pre-commit hook, sibling to the existing `skill-frontmatter` hook.
-
-**Rules land directly in `styles/Kyberforge`, enforcing immediately.** No trial/report-only tier
-is introduced (see Considered Options). "Enforcing immediately" holds only because every rule in
-both styles is `level: error`: Vale's exit code keys on `error`-level alerts alone, so a
-`warning`- or `suggestion`-level rule prints an alert and still exits 0, and pre-commit suppresses
-output from hooks that pass — such a rule is invisible and blocks nothing. Every Vale alert is
-therefore a FAIL, in the audit skills and in the blocking pre-commit hook alike, with no ignorable
-tier; that matches every other gate in this repo (shellcheck, the test suite,
-conventional-pre-commit). The implementation pass finalizes the cherry-picked
-`write-good`/`alex` rules and any new spec-derived rule wording, runs the full set against the
-existing SKILL.md/agent-file corpus, fixes any resulting violations across that corpus, and lands
-the rule changes and the corpus fixes as one atomic commit — the same enforcement model as the
-original four rules, never a partial or opt-in state.
-
-## Considered options
-
-**Phased rollout via a separate trial style + config (rejected).** A `styles/KyberforgeTrial/`
-directory plus a parallel `.vale.trial.ini` (mirroring the root config's globs but with
-`BasedOnStyles = Kyberforge, KyberforgeTrial`) would let new rules be swept report-only via
-`lint-runner`/`vale-run` before promotion into the enforcing `styles/Kyberforge` + root
-`.vale.ini`. This was considered because `BasedOnStyles = Kyberforge` activates every rule file
-under that directory automatically — there's no partial/opt-in application within a style, so a
-rule dropped straight into `styles/Kyberforge` goes live in the blocking pre-commit hook
-immediately. Rejected in favor of finalizing rules directly and fixing violations via subagent
-before committing: simpler, no new trial-config machinery to build or maintain — at the cost of no
-standing report-only tier for future candidate rules. Note that the first implementation shipped
-graded severities (`error`/`warning`/`suggestion`) and thereby recreated the rejected option by
-accident: the five non-`error` rules never affected an exit code and never surfaced output through
-a passing pre-commit hook, so they were a report-only tier that reported to nobody. Flattening
-every rule to `level: error` is what actually implements this decision.
-
-## Consequences
-
-- `styles/Kyberforge/` gained one new rule file, cherry-picked from `write-good`/`alex` as
-  low-noise against this repo's corpus: `SentenceOpenerThereIs.yml` (22 hits across 273 held-out
-  markdown files; both in-corpus hits were clean rewrites, needing no suppression).
-- A second candidate, `VagueQualifier.yml`, was cherry-picked and then dropped. Against the 41
-  skill/agent files it hit twice: one marginal real finding (`prototype/SKILL.md`, "very different"
-  → "fundamentally different") and one false positive (`caveman/SKILL.md`, which *quotes* `of
-  course` as an example of filler — a mention, not a use) that no rewrite could clear, forcing the
-  repo's only Vale suppression comments. Of its 15 held-out hits, 9 were in `docs/research/examples/`
-  (out-of-scope upstream material) and the remaining 6 were the word "very" in two idioms in a
-  single research doc, each already adjacent to the hard number carrying the fact. One marginal
-  catch does not pay for a permanent suppression, so the rule is deleted and this ADR's
-  "cherry-picked rules" is one rule, not two.
-- A new pre-commit hook, `skill-size-check` (`scripts/skill-size-check.sh`), enforces the
-  500-line/5,000-token `SKILL.md` ceiling, sibling to `skill-frontmatter`. Both halves of that
-  ceiling are blocking gates, not just the line count: `MAX_LINES=500`, and `MAX_WORDS=2770` as a
-  word-count proxy for the 5,000-token limit (calibrated to the densest prose this repo measured,
-  1.81 tokens per word, so a worst-case `SKILL.md` at the ceiling still lands under 5,000 tokens —
-  `wc -w` is not BPE tokenization). Either one exceeded fails the hook. Both are
-  inclusive: a file at exactly 500 lines or exactly 2,770 words passes, and only one past a ceiling
-  fails. `skill-audit/scripts/validate.sh` enforces the same pair on the same inclusive terms, so
-  the audit and the commit hook cannot disagree about whether a given `SKILL.md` is over size.
-- `styles/KyberforgeTrial/` and `.vale.trial.ini` were deliberately not created — noted here so a
-  future reader doesn't wonder if a trial tier was forgotten.
-- The styles-portability question — whether `styles/` and `.vale.ini` should move into
-  `plugins/lint/` so the prefilter also works for repos that install `kyberforge@holocron` as an
-  external plugin, rather than living at this repo's root — was deliberately deferred, not fixed,
-  in this pass. This repo-root placement remains intentional: this ADR's "File scope stays the
-  same" framing is specific to Kyberforge's own authoring conventions in this repo, not a generic
-  `lint`-plugin feature. Portability is a known limitation, tracked for a separate future session,
-  not silently forgotten.
-
-**What this ADR's implementation pass did:** synced and trialed `write-good`/`alex` against the
-existing SKILL.md/agent-file corpus, cherry-picked the one low-noise rule above into
-`styles/Kyberforge`, wrote `scripts/skill-size-check.sh` and its pre-commit hook, fixed the
-resulting corpus violations, and landed the rule changes and corpus fixes as one atomic commit —
-matching the enforcement model described above (no partial or opt-in state), with every rule at
-`level: error` so that model is real rather than nominal.

docs/adr/0014-vale-prefilter-ships-from-the-plugin.md

@@ -1,193 +0,0 @@
-# Kyberforge's Vale prefilter ships from the plugin, with `.pre-commit-hooks.yaml` for external git-hook/CI enforcement
-
-**Resolves:** ADR-0013's deferred "styles-portability" consequence — `.vale.ini`/`styles/` moving
-out of the repo root was deliberately deferred there, not fixed. ADR-0013's other content
-(rule scope, `level: error` model, `SentenceOpenerThereIs`/`VagueQualifier` trial outcomes) is
-unaffected and remains in force.
-
-`skill-audit`/`agent-audit`'s Step 1 called
-`"$(git rev-parse --show-toplevel)/scripts/vale-wrap.sh" --config "$(git rev-parse --show-toplevel)/.vale.ini"`
-— which resolves to whichever repo the skill happens to be running in. Inside `ai-development`
-that's this repo; in any external repo that installs `kyberforge@holocron` as a plugin, it's that
-repo's own root, which has no `.vale.ini` or `vale-wrap.sh`. The prefilter silently fell back to
-full LLM judgment every time outside this repo — the exact gap ADR-0013 named and deferred.
-
-## Decision
-
-**Runtime (a live Claude Code session):** the Vale config, styles, and wrapper script move into
-the plugin itself, following the no-cross-skill-path rule already established in
-`skill-author/references/deployment-modes.md` (a plugin's cache-install only copies each skill's
-own files; there is no plugin-level shared directory). `agent-audit` needs both `Kyberforge` and
-`KyberforgeCopilot` (it lints `.agent.md` files), so `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/`
-is the canonical, superset copy. `skill-audit` needs a second, smaller copy
-(`plugins/kyberforge/.apm/skills/skill-audit/assets/vale/`, `Kyberforge` only) since it cannot
-reference agent-audit's copy across the skill boundary. Both skills' Step 1 now resolve
-`scripts/vale-wrap.sh`/`assets/vale/.vale.ini` relative to their own directory, the same way
-`scripts/validate.sh <skill-dir>` already does — no new resolution mechanism, just applying the
-existing one consistently.
-
-**git hooks / CI outside a Claude Code session** have no plugin cache and no
-`${CLAUDE_PLUGIN_ROOT}` — a CI runner in particular is guaranteed not to have one. The mechanism
-that works there for any consumer, with or without Claude Code installed, is pre-commit's own
-hook-repo protocol: this repo now ships a root-level `.pre-commit-hooks.yaml` exposing
-`kyberforge-vale-audit-skill`, `kyberforge-vale-audit-agent`, and `kyberforge-skill-size-check`.
-Any external repo adds `repo: <this-repo-url>, rev: <tag>` to its own `.pre-commit-config.yaml`
-and gets all three, fully decoupled from Claude Code. CI is the identical `pre-commit run
---all-files` call, so the same manifest covers "possibly CI" from the original ask.
-
-**This repo's own dev-time gate** consumes the same plugin-bundled copies instead of a third
-root-level copy — per explicit instruction, this repo should be set up like any other consumer
-would be, not dogfood a special root-only path. The existing `repo: local` hook is retargeted
-(not removed): `entry:` now points at `plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/scripts/vale-wrap.sh`.
-`repo: local` is kept rather than switching to a pinned self-reference
-(`repo: <own-url>, rev: <tag>`) — a pinned self-reference would lint working-tree edits against
-the *last tagged release*, not the change actually being made, which is wrong for the repo that
-*is* the source of the hook. This mirrors standard practice among hook-author repos (pre-commit's
-own `pre-commit-hooks`, `shellcheck-py`): `repo: local` for self-consumption, `.pre-commit-hooks.yaml`
-for everyone else, same underlying files and commands either way.
-
-**One hook per file-scope, not one combined hook.** The old root `.vale.ini` had both the
-`[**/SKILL.md]` and `[**/agents/*.md]`/`[**/*.agent.md]` glob sections in a single file, so one
-pre-commit hook covered both. Splitting the config into two skill-scoped copies means a single
-hook entry pointed at only one copy would silently 0-file-skip the other file type. Both the
-local `.pre-commit-config.yaml` hooks and the external-facing `.pre-commit-hooks.yaml` therefore
-define separate `-skill`/`-agent` hook IDs, each with a `files:` regex matching exactly what its
-target copy's glob covers. (Confirmed empirically before deleting the root files: retargeting a
-single hook at agent-audit's copy silently scanned 0 SKILL.md files.)
-
-**The hook `entry:` is the wrapper alone; the wrapper self-locates its config.** pre-commit
-prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]), *cmd[1:])`);
-every later argument is handed to the process untouched and so resolves against the *consuming*
-repo's root. A `--config plugins/kyberforge/.apm/skills/…/assets/vale/.vale.ini` in
-`.pre-commit-hooks.yaml` therefore named a path no consumer has, and every external run died with
-`E100 [--config] Runtime error`. The external-consumer contract this ADR exists to establish
-cannot be expressed as a `--config` argument at all — the config path has to be derived inside
-the process, from the script's own location. `vale-wrap.sh` accordingly defaults to its sibling
-`assets/vale/.vale.ini`, resolved from `${BASH_SOURCE[0]}`, whenever no `--config` is supplied;
-an explicit `--config` from any other caller still wins and still resolves against the caller's
-cwd. Both audit skills' Step 1 passes no `--config` either, for the same reason and one more: a
-relative `--config assets/vale/.vale.ini` resolves against the cwd, not against the skill
-directory the wrapper path was resolved from, so it yields `E100 Runtime error … does not exist`
-and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades
-to full LLM judgment, the exact failure the self-location exists to prevent. Both `SKILL.md` Step
-1 sections say so explicitly ("Pass no `--config`"), and both manifests now carry the identical
-argument-free `entry:`. Keeping them identical is part of the
-decision: the local `repo: local` hook resolved its `--config` correctly only because the
-consuming repo *was* this repo, and that one difference is why three review rounds exercised a
-code path no external consumer ever takes.
-
-**Vale's `StylesPath` resolves relative to the `.vale.ini` file's own location**, confirmed
-against `docs.vale.sh/keys/stylespath` — so a config path into the plugin finds that ini's
-sibling `styles/` regardless of the caller's cwd, whether it arrives as an explicit `--config` or
-as the wrapper's self-located default. No extra path-juggling is needed beyond `vale-wrap.sh`'s
-cwd-relative `--config`/path-argument handling and that fallback.
-
-**A sync-check catches drift between the two copies.** `scripts/check-vale-style-sync.sh` diffs
-`scripts/vale-wrap.sh` and `assets/vale/styles/Kyberforge/` between skill-audit and agent-audit
-(not `.vale.ini` — those legitimately differ, scoped to different glob sections), wired at
-`pre-push` alongside `check-manifests`. `.vale.ini` itself isn't diffed since divergence there is
-by design.
-
-**External `.pre-commit-hooks.yaml` consumers pin `rev:` to a tag, not a commit SHA.** This repo
-had no tags before this change; going forward, a `vX.Y.Z` tag is cut whenever hook-relevant files
-change, matching how every other `repo:` entry in this repo's own `.pre-commit-config.yaml`
-already pins (`v2.4.0`, `v8.21.2`, ...).
-
-## Considered options
-
-**Keep a third root-level copy, dogfooded specially (rejected).** Simpler in that this repo's own
-hook wouldn't need retargeting at all. Rejected on explicit instruction: this repo should consume
-the same portability path an external repo would, not carve out a special root-only case that
-never gets exercised the way external consumers exercise it.
-
-**Publish styles as a hosted Vale package via `Packages = <zip-url>` (deferred, not rejected).**
-Vale supports fetching a style from a direct `.zip` URL via `vale sync`, fully decoupled from
-Claude Code and from pre-commit's hook-repo protocol — usable by any repo, even ones that never
-install `kyberforge` at all. This is a larger, separate investment (a release/versioning pipeline
-for the package itself) not required to satisfy the current ask; noted here so a future reader
-doesn't wonder if it was overlooked.
-
-## Consequences
-
-- Root `.vale.ini`, `styles/`, `scripts/vale-wrap.sh` are deleted. Two copies remain:
-  `plugins/kyberforge/.apm/skills/agent-audit/assets/vale/` (canonical, superset) and
-  `plugins/kyberforge/.apm/skills/skill-audit/assets/vale/` (subset, `Kyberforge` only).
-- `plugins/kyberforge`'s `plugin.json` and `.claude-plugin/plugin.json` both patch-bump for every
-  shipped content change (per ADR-0006's version-parity invariant): `1.2.5` for the relocation
-  itself, `1.2.6` for the self-locating `vale-wrap.sh` that followed.
-- **`.pre-commit-hooks.yaml` entries are a bare script path and nothing else — a constraint, not a
-  house style, and it binds every future hook here, not just the Vale two.** Since pre-commit
-  rewrites only `entry[0]` into the hook-repo clone, no argument token in any entry can reference
-  a file this repo ships: a relative path resolves against the *consuming* repo and hard-fails,
-  and the absolute path is unknowable at author time. A hook that needs one of its own bundled
-  files must have the script self-locate it from `$0`/`${BASH_SOURCE[0]}`, exactly as
-  `vale-wrap.sh` now does for `.vale.ini`. Anything else rediscovers this as another `E100`.
-  `.pre-commit-config.yaml` stays byte-identical to the shipped manifest on those `entry:` lines
-  so the local gate keeps exercising the same resolution path a consumer does.
-- `tests/test-vale-wrap.sh` now exercises skill-audit's copy specifically — its fixtures are all
-  `SKILL.md`-shaped, and only skill-audit's `.vale.ini` has the matching glob section.
-- The first `vX.Y.Z` tag is cut once this change and its tests pass, giving external
-  `.pre-commit-hooks.yaml` consumers something to pin.
-- **Cutting the tag is not left to memory.** `scripts/check-release-needed.sh`, wired at
-  `pre-push`, hard-fails — but only when `PRE_COMMIT_REMOTE_BRANCH` (set by pre-commit's
-  `hook-impl` for pre-push hooks) is `refs/heads/main` — if any path `.pre-commit-hooks.yaml`
-  exposes changed since the last tag reachable from `HEAD`. It is a silent no-op on every other
-  branch: hard-failing on feature-branch pushes mid-review would force a premature tag on a
-  commit that might not survive a squash-merge, the exact problem `repo: local` (above) already
-  avoids for this repo's own dev-time gate. A tag not existing at all is also a hard fail on
-  `main`, covering the very first release. This is deterministic tooling, not a standing
-  instruction to remember — consistent with `check-manifests.sh`/`check-vale-style-sync.sh`
-  already using the same pre-push, main-agnostic-elsewhere pattern.
-- **Known limitation, not yet closed:** `check-release-needed.sh` only fires when a human runs
-  `git push` locally with pre-commit's hooks installed — `PRE_COMMIT_REMOTE_BRANCH` is set by
-  pre-commit's client-side `hook-impl` script parsing `git push`'s stdin protocol. A PR merged
-  through Gitea's merge button (server-side, no local push) or a CI runner invoking
-  `pre-commit run --hook-stage pre-push` directly never sets it, so the gate silently doesn't run
-  in either path. This repo has no CI workflow yet (`has_actions` is enabled but unused), so
-  closing this gap needs a server-side job re-running the same script on merge to `main` — deferred
-  as a separate piece of infrastructure, not fixed here. `RELEASE_PATHS` is derived from
-  `.pre-commit-hooks.yaml`'s own `entry:` lines rather than hand-maintained, so at least the set of
-  paths it checks can't drift from the manifest on its own.
-- **Dropping `--config` moved the release gate's path derivation too.** `check-release-needed.sh`
-  used to reach each hook's bundled assets through the `dirname` of its `--config` target. With
-  no `--config` token left, that loop went dead and silently dropped both `assets/vale/` trees
-  from release coverage — a Vale *rule* change could then land on `main` without demanding a tag,
-  leaving consumers pinned to an old `rev:` running stale rules while the gate stayed green. The
-  script now derives the bundle's `assets/` tree from `tokens[0]` instead (double-`dirname`,
-  guarded on the candidate existing and on not resolving to `.`), which is the only derivation
-  compatible with the argument-free `entry:` contract above.
-- **Accepted residual in the release gate (closed — see the update below):** deleting a hook's
-  *entire* `assets/` tree is not flagged — the derived candidate path stops existing, so the guard
-  drops it before it reaches the pathspec. Deleting individual files inside a surviving tree is
-  flagged, and tested.
-
-**Update (commit `14c2c91`):** the accepted residual above no longer holds and is recorded here
-only as the state at the time this ADR was written. `check-release-needed.sh` no longer derives
-release-relevant paths from the worktree alone. It runs `collect_release_paths` twice — once over
-the worktree's `.pre-commit-hooks.yaml`, once over the manifest read back from `$LAST_TAG` via
-`git cat-file -p "$LAST_TAG:$HOOKS_MANIFEST"` — and unions the two path sets, so a path the tag
-exposed stays in the pathspec even after the worktree's `-d` guard drops it. Wholesale deletion of
-a hook's bundled `assets/` tree is therefore flagged, and `tests/test-check-release-needed.sh`
-(case 12) asserts exit 1 for exactly that case. The union does not over-fire: any manifest edit
-that makes the two disagree already touches `$HOOKS_MANIFEST`, itself a release-relevant path. An
-unreadable tagged tree (shallow clone, truncated fetch) fails closed rather than silently degrading
-to worktree-only derivation; a manifest simply absent at the tag — legitimate, it was added since —
-does not.
-
-**Update — the flattener rewrites no characters.** This ADR never recorded it as a decision, but
-`vale-wrap.sh`'s flattener carried a lossy last-resort branch: when a description needed quoting
-*and* held an ASCII apostrophe *and* held a double quote or backslash, it substituted U+2019 (`’`)
-for every `'` before writing the scratch copy, on the stated rationale that no verbatim YAML scalar
-could carry that combination. The rationale was wrong. A `|-` literal block with a single indented
-content line carries `'`, `"`, `\` and `: ` byte for byte — a block scalar's body has no escape
-syntax at all — and vale's `text.frontmatter.description` scope still matches and fires rules on it
-(verified against vale 3.15.2; it is the same property that makes the `|` blocks in the wrapper's
-header safe to leave unflattened). The branch fired on 12 of the 54 in-scope files in this repo,
-silently disabling every rule whose token contains an apostrophe on each of them. The flattener now
-emits that literal block instead, so its output is verbatim in all four forms and no Vale rule can
-be silently disabled by the prefilter. The `|-` form is two physical lines where the three inline
-forms are one, so the blank-line pad that preserves later line numbers drops by one — reachable
-only when the original span is already two or more lines, so the pad count stays non-negative.
-`tests/test-vale-wrap.sh` case 20 asserts an apostrophe-bearing token actually fires on a flattened
-description in all three apostrophe-carrying branches, and case 20b pins the pad arithmetic against
-a body line's true line number.

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

@@ -1,176 +0,0 @@
-# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth
-
-**Status: executed (2026-08-12, issue #90).** All six plugins now carry `apm.yml` + `.apm/` as
-their authoring source; `.claude-plugin/marketplace.json` and every plugin's `plugin.json` are
-`apm pack`-compiled output. **Supersedes ADR-0001** ("Skills are distributed via plugins... each
-plugin contains its own `skills/` directory") — in effect.
-
-This repo replaces its hand-maintained Claude Code plugin/marketplace authoring model
-(`.claude-plugin/marketplace.json` + per-plugin `plugin.json`) with Microsoft APM (`apm.yml` +
-`.apm/`) as the authoring source of truth — an outright replacement of the authoring layer, not an
-additive overlay. This ADR records the decision from a `grill-with-docs` session on issue #88.
-
-## Context
-
-Every plugin under `plugins/<name>/` currently ships two hand-maintained manifests
-(`.claude-plugin/plugin.json` for Claude Code, root `plugin.json` for Copilot CLI) plus a
-hand-maintained root `.claude-plugin/marketplace.json` listing all plugins. Adding a provider means
-hand-authoring a third manifest shape; keeping the two existing ones in parity is itself a tracked
-concern (ADR-0006).
-
-Research on Microsoft APM (`plugins/kyberforge/docs/research/docs/microsoft-apm/`) found that its
-documented "monorepo-hybrid" repo shape maps directly onto this repo's existing `plugins/<name>/`
-layout: each plugin becomes its own `apm.yml` + `.apm/{skills,agents,hooks,prompts,instructions}/`
-package, listed from a root `apm.yml`'s `marketplace:` block. `apm compile`/`apm pack` generate
-per-target output — including a `.claude-plugin/marketplace.json` — from that vendor-neutral
-`.apm/` tree, so provider manifests become compiled artifacts instead of hand-authored files, and
-new providers (Copilot, Gemini, Codex — all supported by `apm runtime setup`) no longer require a
-new hand-maintained manifest format.
-
-## Decision
-
-- **The `plugins/<name>/` monorepo-hybrid directory layout survives.** `.claude-plugin/marketplace.json`
-  and per-provider `plugin.json` files become **compiled output** via `apm compile`/`apm pack`,
-  generated from `apm.yml` + `.apm/` per plugin, extensible to other `apm runtime`-supported
-  providers without hand-maintaining a separate manifest per provider.
-- **This supersedes ADR-0001** ("Skills are distributed via plugins... each plugin
-  contains its own `skills/` directory"). Executed in issue #90: skills and agents physically moved
-  to `plugins/<name>/.apm/skills/` and `plugins/<name>/.apm/agents/*.agent.md`.
-- New operational tooling — `apm-install` (skill), `apm-workflow` (skill), `apm-orchestrate`
-  (agent) — lands in `kyberforge`, tracked in issue #88
-  (https://git.dev.rkdr.net/Defame1297/holocron/issues/88).
-- Adapting `skill-author`/`agent-author`'s routing to author `.apm/`-native content (retargeting to
-  `.apm/skills/`, `.apm/agents/` paths — the content these two skills author is still meaningful
-  post-conversion) is deferred to issue #89
-  (https://git.dev.rkdr.net/Defame1297/holocron/issues/89). `forge` is out of scope for #89 — it
-  stays untouched by this whole conversion effort and keeps routing to whatever the live author
-  skills are at the time.
-- **`plugin-author`/`marketplace-author` are not adapted — they are superseded and deleted.**
-  Unlike `skill-author`/`agent-author`, nothing in these two skills carries forward as authoring
-  routing: `apm compile`/`apm pack` will generate `.claude-plugin/marketplace.json` and
-  per-provider `plugin.json` directly from `apm.yml` + `.apm/`, so `apm-install`/`apm-workflow`/
-  `apm-orchestrate` (issue #88, already landed on this branch) fully replace what these two skills
-  did. `plugin-author`/`marketplace-author` were deleted in issue #90's execution.
-- Translating the existing plugins into `apm.yml` + `.apm/` and running the real conversion was
-  executed under issue #90 (https://git.dev.rkdr.net/Defame1297/holocron/issues/90), which tracks
-  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.
-
-## Considered options
-
-**Additive/compile-layer only, no `apm.yml` (rejected).** Keep `plugin.json`/`marketplace.json`
-hand-authored and bolt APM on top as an optional extra. Rejected: doesn't achieve the multi-provider
-compile-reuse goal APM's package model provides, and leaves the existing dual-manifest hand
-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
-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`,
-because holocron is currently the only repo that needs this tooling — standing up a separate
-plugin for a single consumer isn't worth it yet. Accepted as an explicit tradeoff (same pattern
-as ADR-0011's `gitea-workflow` naming tradeoff) — worth revisiting if this tooling is ever reused
-outside holocron's own conversion.
-
-## Content migration out of `plugin-author`/`marketplace-author`
-
-A content audit of `plugin-author`/`marketplace-author` (same `grill-with-docs` session as this
-correction) sorted what they document into three buckets:
-
-- **Claude Code platform constraints — carried forward.** Facts that stay true regardless of
-  authoring model (reserved plugin-name prefixes; the `agents/`-directory stray-`.md`-file
-  validator gotcha, ADR-0010; `claude plugin validate` as a required terminal check) have been
-  added into `apm-workflow`'s reference docs, since compiled output still has to satisfy these
-  constraints post-conversion.
-- **Dual-manifest artifacts — obsolete, not carried forward.** Conventions that existed only
-  because of hand-authored dual manifests (ADR-0006's version-parity/patch-bump rule, the
-  CC-vs-Copilot field-placement split, dual-file mirroring) are obsolete under `apm.yml`'s
-  single-manifest model and were deliberately dropped.
-- **Holocron policy choice — resolved in #90.** `marketplace-author`'s catalog-version convention
-  (minor bump for package add/remove, patch bump for field-only updates) isn't an APM mechanic —
-  `apm` doesn't enforce it, and has no native version-bump automation at all — so rather than
-  building a new script, the convention is now documented as guidance inside `apm-workflow`'s
-  reference docs (`references/marketplace.md` for the root catalog version rule,
-  `references/configure.md` for the per-package version-bump-on-content-edit rule), applied
-  manually by whoever edits `apm.yml`.
-
-## Consequences
-
-- ADR-0001 is superseded (issue #90).
-- ADR-0006 (plugin-version-parity) is moot (issue #90): `plugin.json`/`marketplace.json` are now
-  compiled output of a single `apm.yml`, so there's no second hand-authored file left to keep in
-  parity, and `plugin-author` — the skill that enforced ADR-0006 — was deleted rather than adapted
-  (see "Content migration" above).
-- ADR-0010 (agent sources relocated outside agents dir) was updated (issue #90) for agents now
-  living at `plugins/<name>/.apm/agents/*.agent.md` — the directory path changed; the pre-existing
-  `.agent.md` extension convention (ADR-0005/ADR-0010) and project/user scope are unaffected, per
-  ADR-0016.
-- ADR-0014 (Vale prefilter ships from the plugin) had its hardcoded `plugins/<name>/skills/...`
-  paths (the Vale prefilter is skill-scoped only; ADR-0014 never referenced a
-  `plugins/<name>/agents/...` path) updated for the `.apm/` nesting as part of issue #90's
-  execution.
-- `kyberforge` gained three new artifacts (issue #88) before any conversion of existing content
-  happened, then lost two (`plugin-author`/`marketplace-author`, deleted once issue #90 verified
-  parity) — net version bump 1.3.1 → 1.4.0. The root marketplace catalog bumped 0.3.1 → 0.3.2 to
-  match.
-- ADR-0016 (a narrower decision discovered while designing issue #89) turned out to gate how
-  issue #90 had to re-author plugin-scope agents: `.apm/agents/*.agent.md` compiles verbatim to
-  both Claude and Copilot, so those files carry only the fields in the `apm-agent-allowlist` section
-  of `plugins/kyberforge/.apm/skills/agent-audit/references/field-inventory.md` (as amended
-  2026-08-14: `name`/`description`/`model`/`source_keys`/`disallowedTools`) — existing dual-file
-  `<name>.md`+`<name>.agent.md` pairs could not be raw-moved, only re-authored.
-- Two follow-up issues tracked the remaining work: #89 (`skill-author`/`agent-author` routing
-  adaptation — closed, merged in #93) and #90 (the actual repo conversion, which also deleted
-  `plugin-author`/`marketplace-author` — tracked through to merge; treat #90's own state as the
-  authority on whether it has landed, not this line).
-- **`displayName` is gone from all six compiled `plugin.json` files — accepted, not overlooked.**
-  `apm.yml` has no key that compiles to it: `synthesize_plugin_json_from_apm_yml`
-  (`apm_cli/deps/plugin_parser.py`) emits only `name`, `version`, `description`, `author`,
-  `license`, `homepage`, `repository` and `keywords`, and nothing in `plugin_manifest.py` adds
-  `displayName` afterwards. So every `plugins/<name>/.claude-plugin/plugin.json` now carries
-  `author`/`description`/`homepage`/`keywords`/`license`/`name`/`repository`/`version` (plus
-  `mcpServers` for `bin`) and no `displayName`. The field is optional —
-  `plugins/kyberforge/docs/research/docs/claude-code-plugins/api-reference.md:14` lists
-  `displayName` as `Required: No`, "Human-readable name shown in plugin manager" — which is why
-  `claude plugin validate --strict` still passes on all six. The visible cost is that the plugin
-  manager falls back to the bare `name` as each plugin's label. Accepted as the price of `apm.yml`
-  being the single authoring source: re-injecting `displayName` post-compile would mean a second
-  `reinject_*` workaround of the kind ADR-0017's amendment reserves for fields apm strips on a
-  factually wrong premise, and apm's premise here is simply that the key does not exist in its
-  schema.
-- **`owner.email` was dropped by mistake and has been restored (2026-08-14).** An earlier revision
-  of this ADR listed `owner.email` alongside `displayName` as a field `apm.yml` "has no key that
-  compiles to." That was wrong. `apm_cli/marketplace/yml_schema.py:186` defines
-  `_AUTHOR_OBJECT_KEYS = frozenset({"name", "email", "url"})`, and an `email:` under root
-  `apm.yml`'s `marketplace.owner` block was empirically confirmed to compile straight through into
-  `.claude-plugin/marketplace.json`'s `owner`. The key is declared in root `apm.yml` again and the
-  compiled `owner` block is `{name, email, url}`. Only `displayName` is a genuine schema gap; this
-  one was a documentation error that removed working configuration.
-- **`mattpocock-skills` is pinned to an exact version, and the pin is advanced by hand.**
-  Pre-conversion the entry was `{"repo": "mattpocock/skills", "source": "github"}` — an unpinned
-  reference that tracked the upstream default branch, so consumers got whatever was on it at
-  install time. The conversion first replaced that with `version: "^1.2.0"`, which was still not a
-  pin: a caret range has nothing to freeze it, because there is no lockfile for
-  `marketplace.packages[]`. `apm pack` re-resolved the range against upstream on **every** run, so
-  an upstream `v1.2.4` would immediately invalidate the committed `ref`/`sha` and fail
-  `apm-pack-check-clean` with exit 4 — blocking every push in the repo, triggered by a third party
-  at an unrelated moment, with no local change to explain it. Root `apm.yml` therefore declares an
-  exact `version: "1.2.3"`, which `apm pack` freezes into `.claude-plugin/marketplace.json` as
-  `ref: v1.2.3` + an explicit `sha`. Two consequences, both intended: the committed ref/sha is
-  genuinely reproducible and cannot move under the repo, and picking up a new upstream release is a
-  deliberate act — a human edits the `version:` string in root `apm.yml` and re-runs `apm pack`.
-  apm has no version-bump automation (established under "Versioning" in issue #90's plan), so an
-  ageing pin is the accepted cost of a push gate that only fires on this repo's own changes.
-  Note the pin does not make the entry offline-resolvable: an exact version still requires a
-  `git ls-remote`, which is why two pre-push hooks need the network (see `AGENTS.md`).
-- **Caveat on "Status: executed" above:** issue #90's own execution comment flagged, before merge,
-  that Claude Code's ability to actually load content out of `.apm/` was unverified — that caveat
-  turned out to be a real defect, not a formality: the native installer has zero awareness of
-  `.apm/` and reported `Skills (0) Agents (0) Hooks (0)` on every plugin installed from this
-  marketplace. The manifest-compilation deliverable this ADR describes was genuinely complete;
-  runtime discoverability was not. Fixed in ADR-0017 (a second, compiled flat-directory content
-  mirror at each plugin root, generated by `scripts/sync-plugin-content.sh`) — see that ADR for
-  the root cause and the fix.

docs/adr/0016-apm-agent-primitive-drops-provider-specific-fields.md

@@ -1,174 +0,0 @@
-# Plugin-scope agent-author omits `tools:` and all Claude-only fields from `.apm/agents/*.agent.md`
-
-This ADR is a narrower, downstream consequence discovered while designing issue #89's
-implementation under ADR-0015's broader direction (Microsoft APM replaces hand-authored
-plugin/marketplace authoring). It does not restate ADR-0015's rationale — see that ADR for
-the parent decision.
-
-## Context
-
-APM's agent primitive (`.apm/agents/<name>.agent.md`) has no per-target integrator in
-`apm compile` — confirmed via APM's own Python source (`integration/targets.py` and related
-files, cited in `plugins/kyberforge/docs/research/docs/microsoft-apm/agent-primitive-schema.md`).
-Compilation does a naive verbatim copy of the whole frontmatter and body to both the Claude
-Code and Copilot CLI targets. This is unlike:
-
-- The **skill** primitive, which is also a straight copy (confirmed in the same research doc)
-  but has no field semantics to conflict — `SKILL.md`'s content is target-agnostic already.
-- The **prompt**, **instructions**, and **hooks** primitives, which each get real per-target
-  reconstruction through a dedicated integrator (field allowlisting, key renaming, dropped-field
-  warnings).
-
-Because the agent primitive ships the same frontmatter unchanged to both harnesses, two
-concrete incompatibilities surface:
-
-1. **`tools:`** — Claude Code expects tool names drawn from its own vocabulary, as a
-   comma-separated string or a YAML list (`agent-definition.md:37`); Copilot CLI expects a list
-   drawn from a different alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`). The
-   incompatibility is the vocabulary, not the punctuation: a value correct for one harness names
-   tools the other does not have.
-2. **Claude-only knobs with no Copilot equivalent** — `isolation`, `maxTurns`, `effort`,
-   `memory`, `permissionMode`. Writing any of these means Copilot's copy carries frontmatter
-   keys it doesn't recognize at all. Whether Copilot's agent loader ignores unknown keys or
-   errors on them is unconfirmed by research. *(Still unconfirmed as of the 2026-08-14 amendment
-   below, which admits `disallowedTools` as an explicitly accepted risk rather than by resolving
-   this question.)*
-
-## Decision
-
-At **plugin scope only** (destination package has an `apm.yml` at its root — an APM producer
-package compiled via `apm compile`), `.apm/agents/<name>.agent.md` carries only `name`,
-`description`, `model`, and the prose body. No `tools:` field, no Claude-only fields, at all.
-
-*(Narrowed by the 2026-08-14 amendment below: `disallowedTools` is admitted as a fifth allowed
-field. `tools:` and every other Claude-only knob remain excluded on the reasoning given here.)*
-
-Absent `tools:` means inherit-all-tools on both harnesses — the one value that is never wrong
-on either target, unlike a present, harness-specific value that is guaranteed wrong on at least
-one of them.
-
-`agent-audit`, at plugin scope, is intended to flag — as a **SUGGESTION**, not a FAIL, since
-this is an upstream schema limitation rather than an authoring mistake — any agent whose
-description or body implies a need for tool restriction or a Claude-only behavior the
-frontmatter can no longer express. This would give visibility into the gap without pretending
-the schema can do something it can't. **Not yet implemented**: `check_apm_agent_file()` in
-`validate.sh` currently validates only the field allowlist, `name`, `description`, and
-body-emptiness/length — it has no heuristic for this case. Tracked as follow-up work.
-
-### Scope boundary
-
-This decision applies to **plugin-scope `agent-author` only**. Project scope (`.claude/agents/`
-+ `.github/agents/`) and user scope (`~/.claude/agents/` + `~/.copilot/agents/`) are not APM
-packages — neither goes through `apm compile` — so both keep today's dual-file Claude+Copilot
-pair model exactly as ADR-0005 and ADR-0008 already describe. Those two ADRs remain fully
-authoritative for project and user scope; only their plugin-scope clauses are affected by this
-ADR (see the update notes appended to each).
-
-## Considered options
-
-**Pick one harness's vocabulary and accept breakage on the other (rejected).** E.g. always
-write Claude's space-separated `tools:` string. Rejected because it ships a value that is
-silently wrong (or possibly a hard error) on Copilot, and which harness "wins" would be an
-arbitrary, undocumented asymmetry.
-
-**Same as above, but `agent-audit` flags the cross-harness breakage as a tracked finding
-(rejected).** Rejected for the same core reason — it still ships a wrong value to a real
-harness. Tracking the breakage doesn't prevent it, and the chosen decision already gets
-equivalent visibility (a SUGGESTION finding) without ever shipping the wrong value in the first
-place.
-
-## Amendment (2026-08-14): the write fence comes back as a denylist
-
-The decision above generalised from `tools:` to "no tool restriction at all". That over-reached.
-The unportability argument is specific to the **allowlist**: Claude Code reads `tools:` as a
-delimited string of its own tool names, Copilot CLI reads it as a list drawn from its
-alias vocabulary (`execute`/`read`/`edit`/`search`/`agent`/`web`), so one value is wrong on one
-harness. That reasoning stands, and `tools:` stays out of every plugin-scope agent.
-
-A **denylist** has no such conflict. The evidence for that splits three ways, and this amendment
-states which part is which rather than asserting the whole as settled.
-
-**Confirmed — Claude Code honours it for plugin subagents.**
-`plugins/kyberforge/docs/research/docs/claude-code-plugins/agent-definition.md:39` documents
-`disallowedTools` as a "Denylist applied before `tools`… Takes precedence over `tools`", and — the
-part that matters here — it is **not** in that document's plugin-subagent ignore list. Line 99
-names exactly three fields plugin agents silently ignore: `hooks`, `mcpServers`, `permissionMode`.
-`disallowedTools` is absent from that list. Claude Code is also the harness where the fence is
-actually wanted, so the field earns its place on this evidence alone.
-
-**Inferred — the field is very likely inert on Copilot CLI, but by analogy, not by documentation.**
-`plugins/kyberforge/docs/research/docs/github-copilot-plugins/troubleshooting.md:50` and `:53`
-record Copilot *silently ignoring* two agent frontmatter fields it does not process (`mcp-servers`
-and `metadata` outside the cloud runtime) rather than erroring on them. That is a documented
-tolerance for *known-but-unprocessed* keys, which is adjacent to, not identical to, tolerance for
-an *unknown* key. No stronger evidence exists: a sweep of the vendored Copilot corpus
-(`agent-definition.md`, `api-reference.md`, `troubleshooting.md`, `configuration.md`) documents
-unknown-key handling nowhere.
-
-**Unverified — Copilot's loader behaviour on an unrecognised key.** Context item 2 above says this
-is unconfirmed by research and that remains true; nothing found since changes it. An earlier
-revision of this amendment claimed "an unrecognised frontmatter key is inert" as settled fact and
-attributed it to apm's verbatim-copy behaviour. That attribution was a non-sequitur — verbatim copy
-describes what *apm* does at compile time and says nothing about what *Copilot* does at load time —
-and the claim contradicted this ADR's own Context section.
-
-**So this is an accepted risk, stated as one.** Blast radius if the inference is wrong and Copilot
-errors on the key: the three affected plugin-scope agents fail to load under Copilot CLI. It is
-loud, not silent; it is confined to three agents in three plugins; no other primitive and no Claude
-Code path is affected; and the remedy is a one-line frontmatter deletion. What the denylist shape
-*does* rule out categorically — independent of loader behaviour — is the failure mode that motivated
-dropping `tools:` in the first place: a denied name the other harness does not recognise denies
-nothing, so a mis-shaped value can never grant or misroute a capability. The risk is a load failure,
-never a silent over-grant. That asymmetry is why the same verbatim copy that makes `tools:`
-unshippable makes `disallowedTools` worth shipping.
-
-So the read-only orchestrator agents regain their write fence: `gitea-orchestrate`,
-`apm-orchestrate` and `lint-runner` each carry `disallowedTools: Edit, Write, NotebookEdit` plus
-explicit prose in the body stating the agent does not edit files. `git-orchestrate` is deliberately
-excluded — it legitimately declared `edit` before the conversion and still needs to write.
-
-**Residual — the fence is partial, and the prose is doing more of the work than the field is.**
-`disallowedTools: Edit, Write, NotebookEdit` denies exactly those three tools. It does not deny
-`Bash`, and at plugin scope these agents carry no `tools:` and therefore inherit it, so
-`bash -c 'echo … > f'` remains unfenced by frontmatter. Only the body prose covers that path. This
-is not a regression introduced here — the pre-conversion `tools:` allowlists also granted `Bash`,
-so the shell route was open then too — but the ADR should not credit the mechanism with more than
-it delivers. Closing it would need a `disallowedTools` entry for `Bash`, which these agents cannot
-take because they legitimately shell out.
-
-Net position: the allowlist stays dropped for the reason originally given, and the denylist is
-admitted as the portable-by-construction half of what was lost. It restores a real, Claude-Code-
-confirmed write fence against the tool-call path, not a complete write sandbox. The consequence
-below is narrowed accordingly.
-
-Enforcement follows the decision: `agent-audit`'s plugin-scope validator reads its allowlist as
-data from the `apm-agent-allowlist` section of
-`plugins/kyberforge/.apm/skills/agent-audit/references/field-inventory.md`, and that line now reads
-`name description model source_keys disallowedTools`. `disallowedTools` also stays in that file's
-`claude-code-only-fields` list, which is not a contradiction — that list governs whether a field
-may cross the CC/Copilot boundary in a real project/user-scope *pair*, a different question from
-whether a field is safe under verbatim copy in a single vendor-neutral file.
-
-## Consequences
-
-- Every plugin-scope APM agent loses per-agent tool *allowlisting* and any Claude-only capability
-  (isolation, maxTurns, effort, memory, permissionMode) until APM ships a real per-target
-  integrator for the agent primitive. This is a known, accepted regression, not an oversight.
-  Tool **denial** is not part of that loss — see the 2026-08-14 amendment above.
-- **ADR-0005 is partially superseded** — its plugin-scope clause ("directory containing
-  `plugin.json` is plugin scope → both files land in `<root>/agents/`") no longer applies.
-  Plugin scope is now "directory containing `apm.yml` → single vendor-neutral file lands in
-  `<root>/.apm/agents/`." Project and user scope, and the rest of ADR-0005, are unaffected.
-- **ADR-0008 is partially superseded** — its counterpart-derivation/pair-validation mechanism
-  no longer applies at plugin scope; `agent-audit` takes the single file directly there. Project
-  and user scope, where a real pair still exists, are unaffected.
-- **ADR-0009 is not superseded.** The mechanism it established — `agent-audit` reading field
-  lists from `references/field-inventory.md` rather than hardcoding them, with a `source_keys`
-  provenance chain — survives and is reused. Only the *content shape* changes for plugin scope:
-  `field-inventory.md` shifts from two side-by-side CC-only/Copilot-only blocklists to one
-  vendor-neutral allowlist for plugin-scope agents, while continuing to serve its original
-  two-blocklist role for project/user-scope validation. That file's `apm-agent-allowlist` section
-  is the authoritative list and is read as data by `validate.sh`; as amended on 2026-08-14 it holds
-  `name`/`description`/`model`/`source_keys`/`disallowedTools` — `source_keys` for provenance
-  tracking, validated separately by `validate-provenance.sh` against `sources.md` rather than being
-  a provider-specific field, and `disallowedTools` per the amendment above.

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

@@ -1,346 +0,0 @@
-# Plugin roots gain a compiled flat-directory mirror of `.apm/` content so Claude Code can discover it
-
-This ADR is a follow-on correction to ADR-0015 (Microsoft APM replaces hand-authored
-plugin/marketplace authoring), discovered during issue #90's post-execution review. It does not
-restate ADR-0015's rationale for adopting `.apm/` as the authoring source of truth — see that ADR
-for the parent decision. It resolves the one question ADR-0015's own execution flagged as open but
-did not block on: whether Claude Code's installer can actually load content out of `.apm/`. It
-could not.
-
-**Status: executed (2026-08-13, issue #90).** `scripts/sync-plugin-content.sh` has been run
-against all 6 plugins; flat `agents/`, `skills/`, `commands/` (etc., wherever `.apm/` populates
-them), and a merged hooks file now exist at each plugin root as tracked, generated files. The
-merged hooks file lands at `hooks/hooks.json`, not at the plugin root itself — see the second
-amendment below, which corrects the path this ADR originally recorded.
-
-## Context
-
-ADR-0015's execution comment on issue #90 (2026-08-12) flagged, before merge: "it's currently
-unverified whether Claude Code can actually discover any skill/agent content in these plugins...
-This needs to be checked... before treating this conversion as functionally complete, not just
-manifest-complete." That caveat did not block ADR-0015 from shipping "Status: executed" — the
-manifest-compilation deliverable (`.claude-plugin/marketplace.json`/`plugin.json` generated from
-`apm.yml` + `.apm/`) was genuinely complete, and every automated gate (`apm audit --ci`,
-`claude plugin validate --strict` ×6, `apm marketplace check`) passed clean — so the ADR merged
-with the caveat noted but unresolved.
-
-The caveat turned out to be a real defect, not a formality. `claude plugin install` against all
-three plugins tested (`git@holocron`, `gitea@holocron`, `kyberforge@holocron`) reported
-`Skills (0) Agents (0) Hooks (0)`. Root cause, confirmed two independent ways:
-
-1. **Claude Code's installer scans flat convention directories only.** `strings` on the installed
-   `claude` binary finds zero references to `.apm/` or `apm.yml` anywhere. The installed plugin
-   cache (`~/.claude/plugins/cache/holocron/kyberforge/1.3.1/`) mirrors the pre-conversion flat
-   `skills/`/`agents/`/`hooks/` layout verbatim — that is what the installer actually copies and
-   reads. `plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md`'s own
-   "Plugin Directory Layout" table documents the same flat convention (`skills/<name>/SKILL.md`,
-   `agents/`, `hooks/hooks.json`, all "at the plugin root, not inside `.claude-plugin/`") — this
-   was accurate before ADR-0015 and never stopped being accurate; ADR-0015 moved plugin content
-   without adding a bridge to it.
-2. **apm's own manifest compiler has no `.apm/` → host-path bridge, by design.**
-   `apm_cli/core/plugin_manifest.py`'s `build_plugin_manifest` docstring states directly:
-   "Convention directories (`agents/`, `skills/`, `commands/`) are auto-discovered by the host, so
-   they are never listed explicitly in the manifest." apm's Claude/Copilot compiler assumes plugin
-   content already lives in those flat root-level directories; it has no model of `.apm/` nesting
-   being host-visible at all, so it never emits anything that would point a host at `.apm/`.
-
-Separately, `apm_cli/bundle/plugin_exporter.py`'s `export_plugin_bundle` (the engine behind
-`apm pack --format plugin`) *does* implement the correct mapping — `.apm/agents` → `agents/`,
-`.apm/skills` → `skills/` (subdirs preserved), `.apm/prompts` + `.apm/commands` → `commands/`
-(`*.prompt.md` renamed to `*.md`), `.apm/instructions` → `instructions/`, `.apm/extensions` →
-`extensions/`, and `.apm/hooks/*.json` merged into one `hooks.json`. But it was only ever wired to
-produce a distributable bundle under `build/<name>-<version>/` — a path nothing in root
-`apm.yml`'s per-package `marketplace.packages[].source:` fields (e.g. `./plugins/bin`) or
-`marketplace.json`'s equivalent points at. The correct mapping existed in apm's own codebase the
-whole time; it was simply never connected to the path this repo's marketplace actually installs
-plugins from.
-
-## Decision
-
-Each plugin root gains a second, generated content category, produced by
-`scripts/sync-plugin-content.sh` (wraps `apm pack --format plugin`, copies the resulting bundle's
-`agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged hooks file back to
-the plugin root — the hooks file to `hooks/hooks.json`, per the second amendment below) — same
-governance status as `.claude-plugin/plugin.json`/`marketplace.json`:
-**compiled output of `.apm/`, never hand-edited.**
-
-- `.apm/` remains the sole hand-edited authoring source, unchanged from ADR-0015.
-- The flat mirror is what Claude Code's (and Copilot's) installer actually convention-scans at
-  install time — it exists purely to satisfy the host's discovery contract, a contract apm's own
-  manifest compiler deliberately does not bridge.
-- `plugin.json`/`apm.lock.yaml`/`.mcp.json` from the bundle are excluded from the copy:
-  `plugin.json` is already correctly generated by a separate, already-verified apm code path
-  (`build_plugin_manifest`, run in the same `apm pack` invocation); `.mcp.json` is hand-authored
-  at the plugin root per ADR-0015 and is not an `.apm/` primitive.
-- Dev-fixture `tests/` directories are excluded too — they are dev-time fixtures no plugin host
-  ever needs to discover, and several reference their own repo root through a hardcoded relative
-  walk-up sized for `.apm/`-nested depth, so a copy one directory level shallower breaks the
-  duplicate and double-runs the original under repo-wide bats discovery. The exclusion is
-  **depth-scoped to `<category>/<name>/tests`**, deliberately: a skill may legitimately ship a
-  directory literally named `tests` as a template asset it scaffolds *from*
-  (`skills/skill-author/assets/templates/tests`, at depth 4). A depth-agnostic `-name tests`
-  matched that too and stripped it, making the mirrored `new-skill.sh` die mid-run on
-  `sed: can't read .../tests/README.md` — the scaffolder seds its way through the template tree
-  file by file. Scaffolding assets survive; fixtures do not.
-- Drift is enforced by a pre-push gate (`scripts/sync-plugin-content.sh --check --all`, wired into
-  `.pre-commit-config.yaml` as hook id `check-plugin-content-sync` by a parallel workstream on
-  issue #90) — the same enforcement model `check-manifests.sh` already applies to the other
-  compiled-output category. `--check` alone is not the gate: the script requires either `--all` or
-  an explicit list of plugin directories, and run bare it prints usage and exits 1. `--all` derives
-  its work list from `marketplace.json`, a generated file, so it asserts its own coverage against
-  that list: it fails if it verified fewer plugins than the marketplace declares, not merely if it
-  verified none. A listed plugin whose `.apm/` has gone missing is skipped by the per-plugin sync
-  and would otherwise let the gate report success over a shrinking work list.
-- Verified two ways before landing: `claude plugin validate --strict` passes on all 6 real
-  (non-scratch) plugin directories, and a live behavioral test
-  (`claude --plugin-dir plugins/kyberforge -p "list your skills and agents"`) against the real
-  committed directory confirms `kyberforge:*` skills and the `kyberforge:apm-orchestrate` agent
-  are now actually discovered — they were not, before this fix.
-- The stale root-level `plugins/<name>/plugin.json` files (a near-duplicate of
-  `.claude-plugin/plugin.json` that nothing read or wrote, flagged separately in issue #90's
-  review) were deleted across all 6 plugins as part of the same cleanup.
-
-## Considered options
-
-**Patch `plugin.json`'s content-pointer fields to point directly at `.apm/` paths (rejected).**
-Claude Code's manifest schema documents these as legitimate override fields that accept custom
-paths — `plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md` shows a real
-example (`"skills": "./custom/skills/"`, `"agents": ["./custom/agents/reviewer.md"]`), so the host
-side of this would work. Rejected because apm never emits such a pointer and would have to be
-worked around on every run to make it do so.
-
-Be precise about the mechanism, because an earlier revision of this ADR overstated it. apm 0.28.0's
-`build_plugin_manifest` (`apm_cli/core/plugin_manifest.py`) does carry a strip loop, but its field
-list is `("agents", "skills", "commands", "instructions")` — `hooks` is **not** in it, and
-`instructions` **is**, which this ADR previously did not mention. More to the point, that loop can
-never fire: the manifest it operates on comes from `synthesize_plugin_json_from_apm_yml`
-(`apm_cli/deps/plugin_parser.py`), which only ever emits `name`, `version`, `description`,
-`author`, `license`, `homepage`, `repository` and `keywords`. The pointer fields are absent from
-apm's output because `apm.yml` has no schema for them, not because apm actively removes them — the
-`pop` loop is defensive dead code against a manifest shape apm does not produce.
-
-The rejection is unaffected by that correction, only its framing. Honoring this option would still
-mean post-processing apm's compiled output on every `apm pack` run to add fields apm's schema has
-no way to express, rather than reusing `plugin_exporter.py`'s bundle-export mapping, which already
-does the right thing and only needed its output redirected to a path the installer reads. What it
-is *not* is a fight against a load-bearing apm code path — the honest statement is that apm has no
-input for these fields, and inventing one downstream is a workaround this ADR did not need.
-
-**Point `marketplace.json`'s `source:` at `apm pack`'s `build/<name>-<version>/` output directly
-(rejected).** Would reuse the bundle exporter's correct mapping without adding a new script.
-Rejected: `build/` is a version-suffixed, regenerate-on-every-pack directory — pointing the
-marketplace at it would mean either committing a moving-target build artifact to version control
-(defeating the point of it being generated) or requiring every consumer's marketplace to run
-`apm pack` before install, a build step Claude Code's installer has no hook for — it clones/fetches
-source and scans directories; it does not execute a package manager's build command first.
-Copying the relevant subset back to the stable `plugins/<name>/` path — where `marketplace.json`
-already points — needed no change to the marketplace source model at all.
-
-## Amendment (2026-08-13, revised 2026-08-14): Copilot's `plugin.json` gets an `mcpServers` *path*
-
-PR #95's review (a follow-on to this same issue #90 workstream) found a second field apm's
-compiler drops for the Copilot ecosystem: `build_plugin_manifest` runs
-`manifest.pop("mcpServers", None)` on every Copilot-ecosystem `plugin.json`, its docstring stating
-the field is "not part of the Copilot plugin manifest schema." That claim is contradicted by this
-repo's own researched documentation —
-`plugins/kyberforge/docs/research/docs/github-copilot-plugins/configuration.md:49` documents
-`mcpServers` as a valid, optional `plugin.json` field, typed **"string or object — MCP server
-config path or inline definitions."**
-
-This is not the same situation "Considered options" above rejected. There, apm emits no pointer
-because its schema has no input for one and the host auto-discovers the directories anyway, so
-nothing is missing. Here a field Copilot actually reads is actively removed on a premise that is
-wrong against documented Copilot behavior, and there is no auto-discovery mechanism that makes it
-redundant. Shipping the manifest as apm produces it would ship a manifest known to be incomplete.
-
-`scripts/sync-plugin-content.sh`'s `reinject_mcp_servers()`, called from `sync_one()`, therefore
-sets `mcpServers` on `.github/plugin/plugin.json` after `apm pack` runs — to the **string
-`".mcp.json"`**, the path form of the documented type, not the resolved server objects. Only when
-the plugin's `.mcp.json` declares at least one server, matching apm's own Claude-ecosystem builder,
-which omits the field entirely rather than emitting `mcpServers: {}`.
-
-**The payload is a path because an inlined object is a credential-leak path.** The original
-implementation copied `.mcp.json`'s resolved `mcpServers` object into the manifest with `jq`. That
-route bypasses apm's own `_sanitize_mcp_servers()` (`apm_cli/core/plugin_manifest.py`), which
-strips credential keys and redacts secret values out of `.mcp.json` precisely because — in its own
-words — "copying them verbatim into a committed `plugin.json` would exfiltrate them into the
-distributed artefact." Today's `.mcp.json` files here carry no `env` block, so nothing leaked; the
-first one that did would have written a live token into a tracked, published manifest, with the
-sanitizer sitting one code path away and never invoked. A path reference cannot carry a secret at
-all: the manifest names a file, and resolution happens in the host at load time. This also matches
-apm's documented posture for MCP secrets — `microsoft-apm/configuration.md:96-98` requires `${VAR}`
-indirection so secrets are "never committed to the manifest."
-
-**Both modes re-inject**, not just real syncs: real mode writes into the plugin root directly,
-`--check` into its throwaway copy first, so the manifest diff compares against the same content a
-real sync would actually produce (see the script's own header). A check-mode re-injection is what
-keeps `--check` from reporting permanent phantom drift on every plugin that ships an `.mcp.json`.
-
-This remains scoped to one field found to be incorrectly dropped. It does not reopen the
-content-pointer option rejected above: those fields stay absent because apm has no schema input for
-them and the host needs no pointer, which is a different situation from a documented field being
-actively removed.
-
-Consequence: if a future apm release corrects the Copilot `mcpServers` omission, `reinject_mcp_servers()`
-and its call site become dead code and should be deleted — nothing else in this ADR depends on the
-reinjection existing beyond working around this specific upstream gap.
-
-Line numbers are deliberately omitted above. An earlier revision of this amendment cited
-`reinject_mcp_servers()` at line 190 and its call site at line 269; both had already moved by the
-next review round of the same PR, and moved again with the edits recorded in the amendment below.
-A function name is stable enough to grep for; a line number in an ADR is stale by the next commit.
-
-## Amendment (2026-08-14): the merged hooks file lands at `hooks/hooks.json`, not the plugin root
-
-As originally executed, `sync-plugin-content.sh` wrote the merged hooks file to
-`plugins/<name>/hooks.json`. That path is scanned by nothing. Claude Code convention-scans
-`hooks/hooks.json`, and the "Plugin Directory Layout" table this ADR's own root-cause analysis
-quotes above says so:
-`plugins/kyberforge/docs/research/docs/claude-code-plugins/configuration.md:100` is the row naming
-`hooks/hooks.json`, six lines below the table's preamble at `:94` — "All content directories must
-be at the plugin root, not inside `.claude-plugin/`". The two are not the same line; an earlier
-revision of this amendment said they were. The implementation read the preamble's "at the plugin
-root" and dropped the file there, without reading the row that names the path. So this ADR shipped
-with the contract quoted correctly in its diagnosis and violated in its output — the flat mirror
-bridged skills and agents into discovery and left hooks exactly as undiscoverable as before the
-fix.
-
-The merged file therefore moves to `plugins/<name>/hooks/hooks.json`. A root-level `hooks.json`
-left over from a prior sync is stale output: a real sync deletes it, `--check` reports it as
-drift. The real sync produced exactly these working-tree changes — `plugins/kyberforge/hooks.json`
-and `plugins/lint/hooks.json` deleted, `plugins/kyberforge/hooks/hooks.json` and
-`plugins/lint/hooks/hooks.json` created. Only those two plugins have an `.apm/hooks/` tree, so
-only those two grow a mirrored hooks file at all.
-
-This does **not** reopen the "patch `plugin.json` pointer fields" option rejected above. The move
-needs no `hooks` pointer in `plugin.json`: `hooks/hooks.json` *is* the convention path, so the
-host finds it by auto-discovery, exactly as it finds `skills/` and `agents/`. The rejection stands
-for the reason it was made, once stated accurately — apm emits no pointer field for any of these,
-because `apm.yml` has no key that produces one, and none is needed when content sits at the
-convention path. (`hooks` was never in `build_plugin_manifest`'s strip list at all; see the
-corrected mechanism note under "Considered options".) Writing to the convention path is what makes
-the no-pointer premise true here rather than something to work around.
-
-Read "the host finds it by auto-discovery" above as **Claude Code**, not both hosts. Copilot has no
-default for `hooks` and so discovers none — a real gap, examined and deliberately left open in the
-next amendment.
-
-## Amendment (2026-08-14): no `hooks` pointer is re-injected for Copilot — the gap stays documented
-
-PR #95's review found a third field, and it looks like the `mcpServers` amendment's exact twin:
-`plugins/kyberforge/docs/research/docs/github-copilot-plugins/configuration.md:47` types `hooks` as
-a `plugin.json` field, **"string or object"**, with **no default** — so Copilot has no convention
-path to scan — and `jq 'has("hooks")'` returns `false` for all six `plugins/*/.github/plugin/plugin.json`.
-Copilot therefore resolves **zero hooks from every plugin in this repo**. The facts are not in
-dispute; the remedy is.
-
-State the mechanism correctly first, because it differs from `mcpServers` and the amendment above
-depends on that distinction. `mcpServers` is *actively removed* — `build_plugin_manifest` runs
-`manifest.pop("mcpServers", None)` on every Copilot manifest. `hooks` was **never in that strip
-list** (its field list is `("agents", "skills", "commands", "instructions")`, and the loop is dead
-code besides — see "Considered options"). This is an absence apm never fills, not a removal to
-reverse.
-
-**Decision: do not re-inject. Document the gap.** The `mcpServers` exception was granted on three
-conditions, and `hooks` meets only two of them:
-
-1. *A documented host schema field.* Met — `hooks` is in Copilot's own field table.
-2. *apm has no input that produces it.* Met — `apm.yml` has no key for it.
-3. *The payload is correct for the host regardless of content.* **Not met**, and this is the whole
-   difference. `.mcp.json` is one host-agnostic format that both ecosystems read, so the string
-   `".mcp.json"` is a true statement about the file no matter what is in it. Hooks have no such
-   shared format: Claude Code reads
-   `{"hooks": {"PreToolUse": [{"matcher": ..., "hooks": [...]}]}}` while Copilot requires
-   `{"version": 1, "hooks": {"sessionStart": [{"type": "command", "bash": ..., "powershell": ...}]}}`
-   — a mandatory `version`, lowercase and differently-named lifecycle events, and per-shell script
-   keys. apm's exporter merges `.apm/hooks/*.json` into **exactly one** `hooks.json` with no
-   per-target shaping (`_collect_hooks_from_apm`, `apm_cli/bundle/plugin_exporter.py`), and that one
-   file also sits at Claude Code's convention path, where Claude Code will read it whatever it
-   contains. So there is exactly one file and two incompatible readers of it.
-
-A `hooks` pointer would therefore assert that a Claude-shaped file is Copilot-shaped. That trades an
-*incomplete* manifest for a *wrong* one, which is the opposite of the `mcpServers` amendment's
-reasoning ("shipping the manifest as apm produces it would ship a manifest known to be incomplete").
-
-The "it changes nothing today, so it is zero-risk and correct-by-construction for the first real
-hook" argument does not survive the same check, in both halves. It is not inert today: both
-`hooks/hooks.json` files are `{"hooks": {}}`, which lacks the `version: 1` Copilot's schema
-requires, so a pointer would name a file invalid against the schema it is being pointed at from —
-a change from "declares no hooks" to "declares hooks, at an invalid file". And it is not
-correct-by-construction later: whoever writes the first real hook writes it in one of the two
-shapes, and the pointer is wrong in the Claude-shaped case (the case that actually happens, since
-Claude Code auto-discovers the same file and is what these hooks are authored against) while the
-Copilot-shaped case breaks Claude Code instead. No content makes both readers correct.
-
-What would change this decision is upstream, not local: apm emitting a per-target hooks file (at
-which point a pointer names a file genuinely shaped for its reader), or the two hook schemas
-converging. Until then the honest artifact is a documented gap, recorded for authors in
-`plugins/kyberforge/docs/hooks.md` and pinned by a test asserting the Copilot manifest carries no
-`hooks` key — so that adding one is a deliberate act that has to confront the schema mismatch,
-rather than a plausible-looking one-liner nobody re-derives.
-
-This does not weaken the `mcpServers` amendment. That exception was narrow on purpose, and this is
-what its third condition was for.
-
-## Amendment (2026-08-14): symlinks under `.apm/` are dropped, and are now reported
-
-apm's bundle exporter filters symlinks out of the bundle entirely — `f.is_file() and not
-f.is_symlink()` in `_collect_flat` and `_collect_recursive`, and the same test in
-`_collect_hooks_from_apm` (`apm_cli/bundle/plugin_exporter.py`). It emits no warning. A symlink
-placed under a plugin's `.apm/` therefore never reaches the mirror, and until now nothing said so.
-
-This was **silent content loss, not drift**, and that distinction is why no existing gate caught it.
-Every other check in `sync-plugin-content.sh` compares the live mirror against a freshly synced
-copy — and both sides are built from that same bundle. The symlink is absent from both, they agree,
-and `--check` exits 0. There is no mismatch to detect, only an absence with nothing left to
-mismatch against. Reproduced on a fixture: `ln -s real.md link.md` under `.apm/skills/hello/`
-produced a mirror with no `link.md` and a `--check` at exit 0.
-
-`check_apm_symlinks()` therefore reads the `.apm/` **source** tree directly — the only place the
-loss is visible — and reports each symlink in both modes, failing the run. It is reported rather
-than resolved: dereferencing and copying the target would make a real sync emit content the bundle
-does not contain, which is precisely the "reimplement apm's mapping outside apm" this ADR rejects.
-Telling the author is the in-contract half.
-
-The scan covers only the `.apm/` directories apm's exporter actually reads
-(`agents`, `skills`, `prompts`, `commands`, `instructions`, `extensions`, `hooks`), and carves out
-`<category>/<name>/tests` to match the mirror's own exclusion — that subtree is not mirrored whether
-or not it holds a symlink, so nothing is lost there. The carve-out is depth-scoped for the same
-reason the `tests/` exclusion is: a symlink under `assets/templates/tests` sits in content the
-mirror does carry, and is reported.
-
-## Consequences
-
-- Git now tracks real, visible duplication: `.apm/skills/<name>/SKILL.md` and
-  `skills/<name>/SKILL.md` both exist and must match, likewise `.apm/agents/*.agent.md` vs.
-  `agents/*.agent.md`, and `.apm/hooks/*.json` vs. the merged `hooks/hooks.json` (see the
-  2026-08-14 amendment above for that path). This is an accepted
-  tradeoff of bridging a gap apm itself doesn't close, not a bug — `.apm/` stays the single
-  hand-edited source, and the drift gate (`check-plugin-content-sync`) is what keeps the mirror
-  honest rather than trusting authors to remember to regenerate it by hand.
-- `scripts/check-manifests.sh`'s existing blind spot (flagged in the same issue #90 review round:
-  it validated `plugin.json` fields that ADR-0015 already stopped populating, so a plugin shipping
-  zero content could pass it silently) is fixed as part of the same workstream: those field checks
-  are removed (nothing to check — the fields are correctly absent by design), and the
-  content-presence question they were standing in for is now answered by
-  `check-plugin-content-sync`, not re-implemented inside `check-manifests.sh`.
-- ADR-0015's "Status: executed" now carries a pointer to this ADR (see that ADR's Consequences)
-  rather than being rewritten — the manifest-compilation half of its execution was correct and
-  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.
-- 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
-  convention-scan contract.
-- **Reproduction note (2026-08-13):** the live behavioral test cited in "Decision" above
-  (`claude --plugin-dir plugins/kyberforge -p "list your skills and agents"`) is only a clean
-  kyberforge-only signal when run from a working directory outside this repo. Run literally as
-  written, from this repo's root, this repo's own project-level `.claude/settings.json` sets
-  `enabledPlugins` to true for all 6 holocron plugins (kyberforge, git, gitea, core, lint, bin), so
-  Claude Code loads all 6 plugins' skills/agents, not just kyberforge's — conflating kyberforge's
-  discoverability with the other 5 plugins' already-enabled content. To isolate the signal, run
-  from a neutral cwd outside `/root/ai-development` with an absolute `--plugin-dir` path, e.g.
-  `cd /some/neutral/dir && claude --plugin-dir /root/ai-development/plugins/kyberforge -p "list your skills and agents"`.
-- Reference: issue #90 (https://git.dev.rkdr.net/Defame1297/holocron/issues/90).

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

@@ -1,132 +0,0 @@
-# This repo installs its own plugins through apm, not Claude Code's native plugin install
-
-ADR-0015 moved plugin **authoring** to apm; ADR-0017 added the flat content mirror that keeps the
-authored `.apm/` tree discoverable by hosts that install natively. Both are about producing the
-marketplace. This ADR is about consuming it: how the plugins get onto the machine this repo is
-worked on.
-
-**Status: executed (2026-08-14).** All six packages are installed into `/root/ai-development` by
-`apm install`; the six native project-scope installs (`claude plugin uninstall <name>@holocron
---scope project`) are gone and `.claude/settings.json`'s `enabledPlugins` block is empty.
-
-## Context
-
-Until now the repo consumed its own output the same way any user would: `claude plugin install
-<name>@holocron`, six plugins enabled per-project in `.claude/settings.json`, the `holocron`
-marketplace registered in `~/.claude/plugins/known_marketplaces.json` with `autoUpdate: true`.
-That worked. It also meant the repo's dogfooding stopped one layer short of the tooling it
-publishes: `kyberforge` ships `apm-workflow` and `apm-install` skills describing an install path
-the repo itself did not take.
-
-apm supports both scopes. `apm install --global` deploys to `~/.claude/`; plain `apm install`
-deploys to the project. Global was rejected deliberately — the switch should be provable in one
-repo before it changes how every other project on the machine resolves its skills.
-
-## Decision
-
-Root `apm.yml` declares all six packages under `dependencies.apm`, each as a `git:`/`path:` object
-against the holocron remote:
-
-```yaml
-dependencies:
-  apm:
-    - git: git@git.dev.rkdr.net:Defame1297/holocron.git
-      path: plugins/core
-```
-
-`apm install` deploys them to `.claude/skills/<name>/` and `.claude/agents/<name>.md`.
-
-Three sub-decisions inside that:
-
-- **Object form over the `<name>@holocron` marketplace alias.** The alias is shorter and apm
-  resolves it correctly (verified end-to-end against this remote), but it first requires
-  `apm marketplace add`, which writes to `~/.apm/marketplaces.json` — user scope, outside the
-  repo, and absent on a fresh clone. The object form needs nothing beyond the committed manifest.
-- **Remote source over local path.** apm accepts `path: /root/ai-development/plugins/<name>` as a
-  local dependency, which would make the working tree live instantly. Rejected: it erases the
-  distinction between editing a skill and shipping one, which is the entire point of having a
-  marketplace. The remote form keeps the repo running the same released content every other
-  consumer gets.
-- **Unpinned against the default branch.** Parity with the `autoUpdate: true` the native install
-  had. apm warns on every install (`6 dependencies unpinned`); accepted knowingly. Pinning is a
-  per-entry `ref:` away once the repo tags releases per package — today `git tag` lists one tag
-  total, so there is nothing meaningful to pin to.
-
-## Consequences
-
-**Skills gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also
-answers to `git-commits` and `kyberforge:skill-audit` to `skill-audit`. This is not configurable —
-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
-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
-enables `core`, `git`, `gitea`, `kyberforge` and `lint` at user scope, so both names are live at
-once and a working `gitea:gitea-prs` is the user-scope copy answering. That doubling is the same
-"present twice under two names" outcome the "Keeping both install paths" alternative was rejected
-for — reached by leaving user scope alone rather than by adopting it, which is why it is a
-consequence to record rather than a decision to revisit. Prefer the bare name regardless: it
-survives those user-scope installs eventually being converted, and the namespaced form still
-resolves for anyone installing holocron natively, so skill bodies written for both audiences
-should name the bare skill.
-
-**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
-diffs it against the worktree. apm's hook integrator writes that file, so the replay expects
-exactly what apm would have written — `{"hooks": {}}` — and any repo-owned key in it is permanent
-drift that fails the `apm-audit-ci` pre-push hook. Verified both directions: with the pre-existing
-`enabledPlugins` block present, `1 of 10 check(s) failed`; reduced to `{"hooks": {}}`,
-`All 10 check(s) passed`. Nothing was lost in that reduction — `enabledPlugins` was empty after the
-native uninstall and the only `hooks` entry was an empty `PreToolUse: []` — but it does mean the
-file is no longer available for repo-owned settings. Machine-specific settings go in the gitignored
-`.claude/settings.local.json`, which apm does not deploy; shared enforcement belongs in
-`.pre-commit-config.yaml`, where this repo already keeps it.
-
-**`apm_modules/` breaks naive tree walks.** apm materializes a full copy of every dependency there
-— including this repo's own plugins, `.bats` files and all. The dependency copies resolve their
-bats helpers relative to their own root, not this repo's, so `tests/run-tests.sh` went from 167
-tests passing to `334 tests, 167 failures` on the first install. Both discovery walks
-(`tests/run-bats.sh`, `tests/run-tests.sh`) now exclude `apm_modules/`, on the find side and on the
-`git ls-files` side that derives the expected set. Any future script that walks the repo tree needs
-the same exclusion.
-
-**Install output is gitignored; the lockfile is not.** `.claude/skills/`, `.claude/agents/`, and
-`apm_modules/` are regenerated by `apm install`. Committing the deployed skills would add a third
-mirror of content ADR-0017 already governs two copies of. `apm.lock.yaml` is committed — it is what
-makes the install reproducible, and `apm audit --ci` checks it.
-
-**MCP survived the switch; hooks were never at risk.** apm read `plugins/bin/.mcp.json` as a
-self-defined direct-dependency MCP server and configured `obsidian` into the repo's `.mcp.json`
-unprompted. The `gitea` and `context7` servers were never plugin-provided — they live in
-`~/.claude.json` and are untouched. Every plugin's `.apm/hooks/hooks.json` is `{"hooks": {}}`, so
-apm's "contributed no entries to claude settings; skipped" warning on `kyberforge` and `lint` is
-accurate and harmless.
-
-**A `.apm/` edit now needs a round trip.** The dependency resolves from the remote, so an edit is
-invisible to the running session until it is pushed and the install is refreshed. Under the native
-install with `autoUpdate` the shape was the same; it was more noticeable here at first because the
-refresh is a manual step where marketplace auto-update was not — ADR-0019 automates it at
-`SessionStart`.
-
-**Correction (2026-08-14): the refresh command is `apm update`, not `apm install`.** An earlier
-revision of this paragraph named `apm install`, which is wrong: `apm install` deploys from the
-pinned `resolved_commit` in `apm.lock.yaml` and does not re-resolve refs (`apm install --force`
-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.
-
-## Alternatives considered
-
-- **`apm install --global`.** Verified working in an isolated `HOME`: user-scope deploys land in
-  `~/.claude/skills/` and `~/.claude/agents/`, and it is the only scope where a plugin's `bin/`
-  executables deploy (moot here — every `bin/` in this repo is empty but for a README). Deferred,
-  not rejected: it changes skill resolution for every project on the machine at once.
-- **Keeping both install paths.** Rejected: the same skill would be present twice under two names,
-  and `.claude/settings.json` cannot hold `enabledPlugins` without failing `apm audit --ci`.

docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md

@@ -1,167 +0,0 @@
-# A SessionStart hook keeps the apm install current, replacing a git hook that never ran
-
-ADR-0018 switched this repo to consuming its own plugins through `apm install`, with the six
-packages declared as unpinned git refs against the holocron remote's default branch. That decision
-left a hole it named but did not fill: the deployed content goes stale the moment anyone merges,
-and nothing detects it.
-
-**Status: accepted (2026-08-14).**
-
-## Context
-
-The pre-existing answer was `scripts/git-hooks/post-push`, which pulled the marketplace clone and
-ran `claude plugin update kyberforge`. Issue #78 filed it as a bug — the hook updated `kyberforge`
-but not `gitea`, so gitea skills stayed pinned at a pre-refactor version after #67 merged.
-
-The issue's premise was wrong in a way nobody had noticed for six weeks. **Git has no client-side
-`post-push` hook.** `githooks(5)` does not list one, and git 2.39.5 does not invoke one.
-`scripts/install.sh` copies every file in `scripts/git-hooks/` into `.git/hooks/`, so
-`.git/hooks/post-push` existed on disk and looked installed. It had never fired. The hook did not
-skip `gitea`; it skipped everything. Both tests that appeared to cover it — `test-post-push.sh` and
-`test-git-hooks-install.sh` — asserted only that the script behaved correctly when invoked directly
-and that install.sh copied the file. Neither asserted that git ever runs it.
-
-That also makes the original framing wrong. Refreshing on push assumes the person who pushes is the
-person who goes stale, which is backwards: your install goes stale when *someone else* merges, and a
-push of your own is neither necessary nor sufficient for it to have happened.
-
-## Decision
-
-A `SessionStart` hook, shipped in `plugins/kyberforge/.apm/hooks/`, checks whether the install is
-behind and refreshes it in place.
-
-`SessionStart` is the correct trigger because the thing that goes stale is the skill content a
-*session* loads, and that is the moment the staleness does damage. It also enables two things a git
-hook structurally cannot do: `additionalContext` puts the notice into the agent's context rather
-than terminal scrollback nobody reads, and `reloadSkills: true` makes the host re-scan the skill
-directories after the hook returns, so a refresh lands in the running session without a restart.
-
-apm's own lifecycle events (`pre-/post-install`, `pre-/post-update`, `pre-/post-uninstall`) were
-rejected: they fire around apm operations already chosen, so they can announce a refresh but never
-detect that one is needed.
-
-Three sub-decisions:
-
-- **Refresh automatically rather than report.** The hook runs `apm update --yes` and asks for a skill
-  reload. The rejected alternative was to report and let a human run it. Auto-refresh costs a
-  rewritten `apm.lock.yaml` — a committed file — appearing as an unexplained modification in the
-  working tree, on any branch, at any time. The emitted notice says so explicitly for that reason.
-- **`plugins/kyberforge/.apm/hooks/`, not `.claude/settings.json`.** ADR-0018 established that apm
-  owns `.claude/settings.json` and that any repo-authored key in it is permanent `apm audit --ci`
-  drift. A hook shipped in a package is written into that file by apm itself, so it is apm's output
-  and does not drift. `.claude/settings.local.json` also works but is gitignored and machine-local,
-  which fails the requirement that this travel with the repo.
-- **`startup` matcher only.** `resume`, `clear`, `compact` and `fork` would re-run the check on every
-  compaction, and a compaction is not an event after which the remote can have moved.
-
-The executable-trust gate is switched on at the same time. Root `apm.yml` gains an `executables:`
-block allowing kyberforge's hooks and bin.
-
-## Consequences
-
-**The gate is off until something turns it on, and this repo had it off.** `apm approve --list`
-reports `Executable-trust gate disabled -- all executables deploy` until an `executables:` block
-exists in `apm.yml`. Any hook, bin, or MCP primitive a dependency shipped would have deployed with
-no prompt and no record. The block added here closes that for this repo; every other apm project on
-this machine still has it open.
-
-**The allow key is version-pinned, and that is a live failure mode.** apm writes
-`kyberforge#1.5.0`, not `kyberforge` — and the release that ships this hook proved the point
-immediately, since bumping kyberforge to 1.5.0 required editing the key in the same commit. A
-kyberforge version bump makes the entry stop matching, the
-gate blocks the hook, and the install silently stops refreshing — the exact failure this ADR exists
-to end, reintroduced through the mechanism meant to secure it.
-
-Matching is an exact dictionary lookup on the composed `name#version` string
-(`apm_cli/security/executables.py`, `is_package_approved`), so there is no wildcard or
-version-less key that would sidestep this — the key has to be edited on every bump, and the
-question is only what catches a missed edit. A comment in the `executables:` block is not enough:
-this repo gates generated-content drift, marketplace mirror drift and vale style drift
-deterministically, and a silent-staleness failure is strictly worse than any of them. So
-`scripts/check-executables-allow-sync.sh` runs at pre-push, parsing `version:` out of
-`plugins/kyberforge/apm.yml` and asserting root `apm.yml` carries the matching
-`kyberforge#<version>` key. The comment stays as the human-facing pointer; the hook is what
-actually holds. It parses with PyYAML where importable and falls back to a two-shape scan
-otherwise, so a missing pip package cannot become the thing that blocks every push.
-
-**Trust is keyed on the version, not on the content.** `kyberforge#1.5.0` approves whatever
-`check-apm-current.sh` contains at the moment it is fetched, not the bytes that were reviewed when
-the key was written. Because the dependency is unpinned against the default branch and the hook
-runs `apm update --yes` unattended, an edit to that script landing on `main` deploys and executes
-on every contributor's machine at their next session start, with no second approval prompt and no
-diff shown. The trust gate constrains *which package* may ship an executable; it does not constrain
-what that executable does between version bumps. That is an accepted property of this design rather
-than an oversight — the remote is self-hosted, push access to `main` is already sufficient to
-change any skill body an agent will follow — but it is the reason the gate should not be read as a
-supply-chain control. Pinning each dependency to a `ref:` is what would make it one, and ADR-0018
-defers that until per-package release tags exist.
-
-**A referenced hook script must be addressed at its `.apm/` path.** apm resolves
-`${CLAUDE_PLUGIN_ROOT}/...` against the installed package root, and `apm pack` keeps only `*.json`
-from `.apm/hooks/` when it builds the flat mirror. So `${CLAUDE_PLUGIN_ROOT}/hooks/check-apm-current.sh`
-resolves to the mirror, where the script does not exist — verified, apm reports
-`Hook script not found` and deploys a hook pointing at nothing. The working reference is
-`${CLAUDE_PLUGIN_ROOT}/.apm/hooks/check-apm-current.sh`. The script cannot simply be placed in
-`plugins/kyberforge/hooks/` either: that directory is `rm -rf`'d by every content sync (ADR-0017).
-A test pins the reference.
-
-**Session startup gets slower when the install is stale.** Measured: ~0.7 s for the `apm outdated`
-check when everything is current, ~10.4 s when six packages are behind and the refresh runs. The
-hook declares `timeout: 380` to cover a cold multi-package fetch. That number is not free-standing:
-the script imposes its own `timeout 60` on `apm outdated` and `timeout 300` on `apm update`, so the
-host-side timeout has to exceed their sum or the host kills the hook mid-update and leaves
-`.claude/skills/` half-deployed with no notice emitted. An earlier revision declared `320`, which
-was below the 360 s the script can legitimately take. A test asserts the invariant rather than the
-literal — it parses every `timeout N` out of the script, sums them, and requires the `hooks.json`
-value to be larger — so changing either side without the other fails the suite.
-
-**Reading a human-readable CLI for a control decision cost a silent failure, again.** `apm outdated`
-has no `--json` or other machine-readable flag (confirmed against 0.28.0), so the hook must match
-its prose. The first attempt matched `outdated dependencies found` — plural only. apm emits
-`1 outdated dependency found` in the singular when exactly one package is behind
-(`apm_cli/commands/outdated.py`), so a single stale package was invisible: the hook exited 0
-silently and no refresh ran. With six packages merging independently, one-behind is the ordinary
-case rather than an edge, which means the mechanism failed most often in exactly the situation it
-exists for. The match is now `outdated dependenc(y|ies) found`.
-
-The deeper lesson is the one `post-push` already taught and this repeated: every assertion about the
-hook mocked `apm`, so the suite was green while the hook could not detect the common case. Mocks
-verify the code against its author's belief about the interface, never the interface. The suite now
-carries one probe that stages a genuinely outdated dependency against a local git remote — offline,
-via `url.<path>.insteadOf`, so the twelve-hooks-pass-under-`unshare -rn` property survives — runs
-the real `apm outdated`, and replays its genuine output through the real hook. Reverting the grep
-to plural-only fails it.
-
-**The hook cannot install itself.** Dependencies resolve from the remote, so the hook does not
-deploy until this change is merged and `apm update` has run once against the new default branch.
-Until then the repo has the mechanism in source and not in effect.
-
-**`.claude/settings.json` stops being `{"hooks": {}}`.** apm merges the hook into it and tracks
-ownership in a `.claude/apm-hooks.json` sidecar, with the script copied to
-`.claude/hooks/<pkg>/`. The sidecar and the script directory are gitignored install output; the
-settings file remains committed, now with apm-generated content in it. ADR-0018's statement that the
-committed content is exactly `{"hooks": {}}` is superseded on that point only — the rule it was
-protecting, that nothing repo-authored goes in that file, is unchanged.
-
-**Native consumers are protected by a guard, not by the gate.** A host installing holocron through
-`claude plugin install` auto-discovers `hooks/hooks.json` and does not consult apm's trust gate at
-all. The script therefore exits silently when there is no `apm.lock.yaml` in the working directory,
-which is what makes it inert in a repo that does not consume packages through apm. Copilot CLI sees
-no hook at all, for the reasons already documented in `plugins/kyberforge/docs/hooks.md`.
-
-**`scripts/git-hooks/` is now empty.** `post-push` and `test-post-push.sh` are deleted.
-`install.sh`'s copy block is generic and is kept; `test-git-hooks-install.sh` now synthesizes its
-own fixture hook instead of depending on a real one existing, so the mechanism stays tested and can
-be used again if a hook git actually invokes is ever wanted.
-
-## Alternatives considered
-
-- **A `post-merge` git hook.** Real, unlike `post-push`, and verified to fire on both a
-  fast-forward `git pull` and a `git pull --rebase`. Rejected as the primary mechanism because a
-  pull is the wrong signal, and because it cannot reload skills in a running session. It remains
-  the only option for a project that consumes apm packages without a Claude-family host.
-- **Reporting instead of refreshing.** See the sub-decision above.
-- **A seventh plugin holding only this hook**, to avoid shipping it to external kyberforge
-  consumers. Rejected as disproportionate: the `apm.lock.yaml` guard already makes the hook inert
-  for anyone not consuming through apm, and a package exists to be maintained, versioned, and
-  registered in the marketplace.

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

@@ -1,419 +0,0 @@
-# Skills and agents are authored against a context budget, not a spec ceiling
-
-Every installed skill's `name` and `description` sits in every agent's context from the first token
-of every session, whether or not the skill is ever invoked. Across this repo's 39 skills that is
-23,427 characters — roughly 5,900 tokens — and the authoring rules that produced it optimised for
-triggering reliability with no counter-pressure on size. This ADR sets the budget, the shape, and the
-gates that hold them.
-
-**Status: accepted (2026-08-14).**
-
-## Context
-
-Every `file:line` citation in this ADR is against the base commit the decision was taken on,
-`f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0`, not against current `HEAD`. The change that carries this
-ADR rewrites several of the cited files, so a citation resolved against the worktree will land on
-unrelated text. Use `git show f9b919d:<path>` to follow one.
-
-Measured before any change, at that commit. Method, so the figures are reproducible: sum
-`len(name) + len(description)` over the frontmatter of every `plugins/*/.apm/skills/*/SKILL.md`,
-folding `>` block scalars to the value the host actually loads (most descriptions here are folded
-scalars, so counting raw lines measures indentation instead); tokens at the standard
-~4-characters-per-token approximation `scripts/skill-size-check.sh` uses. Word counts are
-whitespace-separated tokens, and are stated as **body-only** or **whole-file** every time, never bare.
-
-| | |
-|---|---|
-| 39 skill `name` + `description` | 23,427 chars, ~5,900 tokens, **preloaded every session** |
-| 4 agent `name` + `description` | 1,325 chars, ~330 tokens, preloaded every session |
-| skill bodies (body-only words) | median 684, mean 815, p90 1,349 |
-| skill files (whole-file words) | median 816, mean 927, p90 1,526 |
-| `MAX_WORDS` gate (`skill-audit/scripts/validate.sh:147`) | **2,770** whole-file — a density proxy, not a percentile |
-
-That last row is worth stating plainly, because it is the first thing this ADR is about. 2,770 is not
-derived from the corpus distribution at all: per the derivation comment in
-`scripts/skill-size-check.sh`, it is 2,770 words at the densest observed 7.22 chars/word ≈ 20,000
-chars ≈ the agentskills.io ~5,000-token ceiling. Neither percentile reaches it — 2× the body-only p90
-is 2,698 and 2× the whole-file p90 is 3,052 — and reading it as "2× p90" would pair a whole-file gate
-against a body-only distribution, which is exactly the conflation this ADR exists to stop.
-
-Three findings drove this, none of which is "the descriptions drifted".
-
-**The rules mandate the bloat.** `skill-author/SKILL.md:104` requires indirect triggers ("even if the
-user doesn't mention X explicitly") and `skill-audit/references/description-quality.md:21` requires
-authors to "err toward being pushy". Both are enforced. The one rule that would delete the waste —
-`skill-author/SKILL.md:102`, "not the skill's internal mechanics" — is judgment-only and is absent
-from the FAIL conditions at `description-quality.md:45-50`. The enforced rules inflate; the deflating
-rule does not bite. The result is measurable: `gitea-files` spends 147 chars listing six verbs, then
-301 chars re-quoting the same six as user phrasings, in the same order. `apm-workflow` does the same
-with six capability clusters. Across the twelve longest descriptions, 30.7% is capability
-enumeration and 11.6% is composition or implementation detail that cannot affect a routing decision.
-
-**Capability enumeration in a description is a correctness hazard, not only a token cost.**
-`plugins/kyberforge/docs/research/examples/skill-write/writing-skills/SKILL.md:154-158` reports a
-measured failure: "when
-a description summarizes the skill's workflow, an agent may follow the description instead of reading
-the full skill content. A description saying 'code review between tasks' caused an agent to do ONE
-review, even though the skill's flowchart clearly showed TWO reviews." `git-commits` is exactly that
-shape — 74% of its description is capability enumeration, including a rules table (`header max 100
-chars, lowercase subject, no trailing periods, 11 standard types`) an agent can act on without ever
-loading the body.
-
-**The upstream sources cannot settle this.** The four skill-writing references under
-`plugins/kyberforge/docs/research/examples/skill-write/` disagree on what a description contains —
-when-only (`writing-skills/SKILL.md:99`), what-and-when (`skill-creator/SKILL.md:67`,
-`writing-skills/anthropic-best-practices.md:187`), triggers-only
-(`writing-great-skills/SKILL.md:28`), and what-plus-when-plus-negative
-(`write-skill/SKILL-TEMPLATE.md:5-6`). Those four paths are relative to that directory.
-`writing-skills` and the Anthropic document it bundles contradict each other inside one skill
-directory. They also disagree on whether
-500 lines is binding, on the inline-versus-bundle threshold, and on the TOC threshold (>100 lines vs
->300 lines). "Grounded in the research" is therefore not available as a tiebreaker; a house choice is
-required and this is it.
-
-A fourth observation shaped the body half. The best progressive-disclosure ratio in the repo belongs
-to `apm-workflow` — a 421-word body dispatching to 3,006 words of references — and the worst two
-belong to the skills that define the house standard: `skill-author` (2,623-word body / 1,247 words of
-references) and `agent-author` (2,582 / 1,664). Measured the other way, whole-file, those two are
-2,760 and 2,758 words — ten and twelve words under the 2,770 gate their own plugin enforces. A
-ceiling that nothing approaches is not a constraint; a ceiling that two files have grown into is a
-target. The two numbers for one file are the point: 2,623 and 2,760 describe the same `skill-author`,
-and only one of them is what either gate measures.
-
-## Decision
-
-### Descriptions
-
-A description carries three things and nothing else: a **trigger clause**, at most one **capability
-clause**, and a **boundary clause**. Capability enumeration, output-format detail, composition notes
-("composes X rather than duplicating Y"), and implementation detail move to the body or to
-`README.md`.
-
-- **250 characters SUGGESTION, 400 FAIL.** The agentskills.io 1,024-character limit remains as an
-  unchanged spec backstop. The SUGGESTION tier is what moves the average; the FAIL tier only stops
-  outliers.
-- **A missing, valueless or `null` `description:` is a hard FAIL** in all three validators. That
-  reads as a trivial precondition and is not: a `description:` line with no value followed by
-  `model: sonnet` let a line regex capture the *next* key, which looked non-empty, so the "missing or
-  empty" branch never fired and every gate below it then early-returned on the genuinely empty folded
-  value — exit 0, zero output, on a blocking pre-push gate. Presence is decided on the YAML-folded
-  value and nowhere else. The field this contract is entirely about is the one field a gate must
-  never fail to notice is absent.
-- **Boundary clauses compress** to `Not <thing> → <skill-name>.` and must name a target that
-  resolves to a real skill or agent. Resolution walks up **from the file being checked** to an
-  *authoring root* — the nearest ancestor holding `plugins/*/.apm/skills` or `plugins/*/.apm/agents`,
-  falling back to the nearest ancestor holding `.git`. Two passes rather than one interleaved walk,
-  so a nested `.git` (a submodule, a sub-package worktree) cannot beat a real monorepo root further
-  up. When an authoring root is found the universe is every skill and agent under
-  `<root>/plugins/*/`, plus the target's own apm package and the packages that package declares in
-  its own `apm.yml` `dependencies.apm`. Sibling plugins resolve against each other, which is what a
-  monorepo means. 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. That is
-  the consumer case, where there is no monorepo to read. The condition is which of the two passes
-  matched, never a name-count delta: a single-plugin monorepo re-collects its own package and adds
-  no new name, so a delta test reads zero there and would pull the deployed trees back in. What the
-  resolver must never do is
-  derive the universe from its own location: a `${BASH_SOURCE}`-relative repo root leaked this repo's
-  39-skill universe into every consumer repo running the hook through pre-commit, so a consumer skill
-  routing to `skill-audit` resolved against a plugin it had never installed. Checked
-  deterministically. A description carrying **no** boundary clause at all is a SUGGESTION, for skills
-  and agents alike: most descriptions want one, some genuinely have no near-miss sibling to exclude,
-  and that judgment is not a script's to make.
-- **The verdict must not depend on whether `apm install` has been run.** Deployed trees are
-  gitignored install output, present only on a machine that has run it. Four cross-plugin targets
-  here (`gitea-branches` → `git-branches`, `gitea-branches` → `git-history`, `gitea-issues` →
-  `git-branches`, `gitea-workflow` → `git-workflow`) once resolved through `.claude/skills/` alone,
-  so the same commit measured 2 dangling targets on a developer machine and 6 on a fresh clone. A
-  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.
-- **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
-  vendor-neutral `.apm/` description routing to one is a portability defect and the hard FAIL is a
-  true positive, not a false one. An allowlist of known built-ins was **rejected**: it answers a
-  different question ("does this exist on *some* host?"), it cannot answer that portably from a
-  single source file, and it goes stale the next time a host ships a command — reintroducing the
-  same-commit-two-verdicts failure the bullet above exists to close. An author who needs to mention
-  one writes it un-slashed (``the `compact` built-in``), which is not route notation and makes no
-  routing claim.
-- **Blocking is scoped to a sentence, which makes sentence boundaries load-bearing.** A prose-form
-  target earns a hard error only when its own sentence names another target that *resolves*; route
-  notation (`/name`, `→ name`) is exempt and always blocks. So the splitter is part of the contract,
-  not a detail of it. `e.g. "…"` is not a sentence end, and a sentence opening with a code span or a
-  lowercase skill name is a start; getting either wrong moves targets between the two tiers in
-  opposite directions — a stranded corroborator silently demotes a real finding to SUGGESTION, and a
-  missed boundary lets one sentence vouch for a target it never stood beside, producing a hard FAIL
-  with no escape hatch.
-- **The blanket pushiness rules are deleted.** `skill-author/SKILL.md:104` and
-  `description-quality.md:21` are replaced by a conditional: add an indirect trigger only where the
-  user's natural phrasing genuinely omits the domain word — true for the `gitea-*` family, false for
-  `git-commits`. Stating the same trigger twice in two registers is a FAIL.
-
-### Bodies
-
-The body carries the **decision procedure only**: ordered steps, decision branches, gates, and which
-reference to load when. Lookup tables, spec restatements, output schemas, templates, and rationale
-prose move to `references/` behind an explicit "read X when Y" trigger.
-
-- **600 words SUGGESTION, 900 FAIL, counted body-only** — everything after the closing `---` of the
-  frontmatter. The 2,770-word / 500-line spec backstop is unchanged, keeps its existing meaning
-  (conformance, not quality), and keeps counting the **whole file including frontmatter**. These are
-  two different gates measuring two different things, and conflating them is what produced the
-  current state.
-- **Dispatch is mandatory at two or more mutually exclusive flows.** The body carries the dispatch
-  table and the gates that apply to every branch; each flow lives in its own self-contained
-  `references/` file. This is `apm-workflow/SKILL.md:33-41` promoted from accident to rule. "Two
-  mutually exclusive flows" is not decidable from file text, so this rule is auditor judgment — see
-  Enforcement below for what that means and does not mean.
-- **Every `references/<file>.md` a body names must exist.** A dispatch table pointing at a file that
-  was never written is a silently dead branch. Checked deterministically.
-- **Gotchas are constrained.** A Gotcha must state a fact that contradicts a reasonable default —
-  something the agent gets wrong by acting sensibly. More than five entries is a SUGGESTION, as is a
-  Gotchas section exceeding 25% of the body; both are countable and both are checked
-  deterministically. A Gotcha that paraphrases a step in the body below it is a FAIL, but a FAIL an
-  auditor issues, not a script — semantic equivalence is not pattern-matchable.
-
-### Agents
-
-Agents take the same description gates — they are preloaded identically — and **no body word gate**.
-A skill body is loaded into the caller's context, competing with the live conversation; an agent body
-becomes the system prompt of a fresh context. The rationale for the 900-word FAIL does not transfer.
-
-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
-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.
-
-A plugin-scope agent is a single file with no sibling `references/` directory, so it cannot disclose
-to itself — it can only delegate to skills. `agent-audit` therefore gains a **delegation check**: an
-agent body that restates a procedure owned by a skill it can invoke is a FAIL, with the fix being
-"invoke `<skill>` instead". Length falls out of delegation rather than being gated directly.
-
-### Invocation as a design axis
-
-`skill-author` asks whether a skill is model-invoked or hand-invoked before writing a description. A
-hand-invoked skill sets `disable-model-invocation: true` and carries one plain human-facing sentence
-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`.
-
-### Merging siblings
-
-Two skills that share substantial content, name each other as near-misses, and differ only in the
-type of input they take should be **one skill with a dispatch table**. This catches `skill-audit` +
-`agent-audit` and is scoped to them; the author pair is explicitly excluded, because
-`skill-author` and `agent-author` emit genuinely different artifacts (a skill directory versus a
-one-or-two-file agent pair, per ADR-0005 and ADR-0016) and their overlap is in the improve flow
-rather than the core job.
-
-**DEFERRED — not implemented in the change that carries this ADR. Tracked as issue #101.** Both
-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
-and dated instead of discovered later.
-
-### Enforcement and rollout
-
-Gates land where the existing gates already live — no new layer. The table below is exhaustive about
-which tier each rule is in, because the failure this ADR is most exposed to is a rule filed under
-"Enforcement" that no validator implements:
-
-| 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` |
-| 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 |
-| 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 |
-| description opener, composition notes in a description | skills, agents | prose pattern | `plugins/kyberforge/.apm/skills/*/assets/vale/styles/Kyberforge/` |
-| a Gotcha paraphrasing a body step | skills | **auditor judgment** | `references/body-discipline.md` |
-| dispatch at two or more mutually exclusive flows | skills | **auditor judgment** | `references/body-discipline.md` |
-| delegation: an agent body restating a skill's procedure | agents | **auditor judgment** | `agent-audit` |
-| capability enumeration, restatement, trigger quality | skills, agents | **auditor judgment** | `references/description-quality.md` |
-
-The rows in bold are stated as FAILs in the Decision above and are FAILs an *auditor* issues. None of
-them is countable: "does this Gotcha paraphrase step 4", "are these two flows mutually exclusive" and
-"does this agent body restate what `git-commits` already owns" are semantic questions, and a script
-that guessed at them would be a worse gate than no gate, because it would be believed. They are not
-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.
-
-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`,
-`prototype` and `tdd` are all real skill names *and* ordinary English, so it must be written
-`` `forge` `` or `/forge` to be seen at all. Grammar then decides whether a recognised target may
-raise an error: one followed by an ordinary lowercase noun is a compound **modifier**, not a route
-("use pre-commit hooks instead of ad-hoc scripts", "invoke the pull-request template"), so it is
-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
-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
-merely contain the word, so `## Gotcha handling` and `## Why gotchas matter` are prose sections and
-are skipped; fenced code blocks are masked out of heading detection and entry counting, so a fenced
-example list is not mistaken for the section; and a `references/` pointer named on a line
-that also says the file is gone ("removed", "deprecated", "no longer") is read as a historical
-mention rather than a dead dispatch entry. Note the 25% fraction is deliberately *not* fence-masked
-on either side — fenced lines are real body words, and the fraction is measured against the whole
-body.
-
-**The deterministic tier blocks immediately, with no baseline file.**
-
-Three pre-existing contradictions are fixed in the same change, because they are the contract:
-
-- `skill-audit/SKILL.md:58` asks whether the description opens with an action verb ("Audits…",
-  "Reviews…"), while `:56` defers the same question to `Kyberforge.DescriptionOpener` and
-  `skill-author/SKILL.md:101` requires an imperative "Use when…" opener. The criterion is
-  unsatisfiable against the house's own skills, both of which open with "Use when".
-- `DescriptionOpener.yml` is anchored to `^This (skill|agent)\b`, which misses a plain `This …`
-  opener; it is widened here to `^This\b`. The anchor itself stays. Composition prose that sits
-  *mid*-description — `gitea-workflow`'s "This is the human-facing entry point…" at character 377,
-  `gitea-labels-milestones`'s "This is a cross-cutting shared skill…" at character 300 — was never in
-  the opener rule's scope and correctly is not: under `scope: text.frontmatter.description` the `^`
-  anchors to the start of the whole folded value, and un-anchoring to reach mid-description text was
-  measured at 5 hits and 5 false positives and rejected (`LESSONS.md`, 2026-08-14). The real gap is
-  that no rule covered that text at all, which a new token-list rule, `Kyberforge.CompositionNote`,
-  closes: 10 alerts across four `gitea-*` skills, 0 false positives.
-- `description-quality.md:45-50` has no FAIL condition for internal-mechanics content, which is why
-  `skill-author/SKILL.md:102` never bit.
-
-## Consequences
-
-**Editing any non-compliant skill now requires retrofitting it first.** At decision time, 30 of 39
-descriptions exceeded 400 characters and 13 of 39 bodies exceeded 900 words — the latter counted
-body-only, which is what the new gate measures; the pre-existing 2,770-word gate counts the whole
-file including frontmatter, and the two must not be conflated. The change that carries this ADR also
-retrofits kyberforge's own four author/audit skills, so the figures on landing are **26 and 9**.
-With the gate hot and no baseline, a one-line
-fix to `gitea-prs` cannot be committed until that skill meets the contract. This is deliberate — it
-guarantees convergence and avoids a half-state — but it means the retrofit is lazy and *mandatory*
-rather than deferred. Issue #99 tracks it and should be prioritised accordingly, and the risk it
-carries is the ordinary one for hot gates: a gate expensive enough to be inconvenient gets bypassed
-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.
-
-**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
-the 250-character SUGGESTION instead lands at 9,750, a 58% cut. The halving depends entirely on the
-250-character SUGGESTION tier being visible and respected. That tier works here in a way it does not
-elsewhere in this repo: `skill-audit` already reports `PASS (N suggestions)` as a first-class
-outcome. This is explicitly **not** the failure ADR-0013 records — Vale warnings are invisible
-because vale's exit code keys on `error` alone, but these gates live in `validate.sh` and
-`skill-audit`, where a SUGGESTION reaches the report. Realistic landing is somewhere in that 33-58%
-band, not a guaranteed 50%.
-
-**A word gate cannot detect the defect it is standing in for.** `git-commits` carries twelve Gotchas
-of which four restate steps in its own Workflow (`:32` ≡ step 9, `:33` ≡ step 9, `:36` ≡ step 2,
-`:31` ≡ the description). Its body is 1,102 words and its whole file 1,217, so it does fail the
-900-word body FAIL — but for its length, not for the restatement. The four duplicated Gotchas are 114
-words between them; delete every one and the file still fails, while a skill 250 words shorter with
-the identical defect passes clean. The two properties are uncorrelated, which is why the counts are a
-backstop to the dispatch rule and the Gotchas constraint — both of which are auditor judgment for the
-semantic half, per the Enforcement table — and not a substitute for them. Reading the word gate as
-the mechanism is the specific mistake this paragraph exists to prevent.
-
-**Some skills legitimately need more description budget than others.** A tiered limit keyed to
-sibling density was considered and rejected as too clever; the flat 250/400 pair means the `gitea-*`
-and `git-*` families — where every sibling shares a keyword and boundary clauses do real routing work
-— 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.
-
-- `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
-  kyberforge's own skills.
-- `agent-author` said "Do not use for read-only review — examine agent files manually", routing away
-  from `agent-audit`, the correct sibling. **Fixed here**, same way. Note this one was never
-  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.**
-- `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`.
-
-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.
-
-**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
-root-cause grouping rule in four copies, and the wholesale clone of the "Improving an existing X"
-flow all remain. Cache isolation makes them structurally unavoidable
-(`skill-audit/SKILL.md:95` forbids cross-skill references; `LESSONS.md:107` records why), so the
-options are a sync gate or continued drift. This is an input to issue #101, which carries both halves
-of the kyberforge duplication problem — the deferred audit-pair merge and this — not a solved
-problem.
-
-**Provenance frontmatter is explicitly out of scope.** `LESSONS.md:63` asserts that non-routing
-frontmatter (`source_keys`, `category`, `version`) is loaded at agent startup, which would make the
-7,352 characters of it across the corpus a third again on top of the description tax. Measured
-against a live session on this Claude Code version, it is not: the model-visible skill listing
-contains only `name` and `description`. That is host-observed rather than spec-guaranteed and says
-nothing about Copilot CLI, but it is sufficient to establish that cutting `source_keys` would break
-the ADR-0009 provenance machinery for no runtime gain. The metadata was added deliberately and stays.
-
-## Alternatives considered
-
-Upstream citations below are relative to
-`plugins/kyberforge/docs/research/examples/skill-write/`, as in Context above.
-
-- **Keep pushiness, raise the budget to ~500 chars.** Undertriggering is the worse failure mode — a
-  skill that never fires is worth nothing regardless of cost — and `skill-creator/SKILL.md:67`
-  explicitly recommends being "pushy" against an observed undertriggering tendency. Rejected because
-  that claim is an unmeasured assertion about an older model, and because the correctness hazard in
-  `writing-skills/SKILL.md:154-158` cuts the other way: a fat description is not merely expensive, it is a
-  shortcut agents take instead of reading the body. Would have landed a 35% cut.
-- **A trigger-eval loop to set lengths empirically.** `skill-creator/SKILL.md:337-404` specifies 20
-  queries per skill, 8-10 positive and 8-10 near-miss, with a 60/40 train/test split selecting on
-  test score. This is the rigorous answer and the repo has deliberately never built it. Rejected
-  because it blocks the context cut behind a substantial new subsystem.
-- **A repo-level aggregate preload budget** (≤12,000 chars across all skills, checked at pre-push).
-  The only option that measures the actual goal rather than a proxy. Rejected because it makes one
-  skill's edit fail on account of another skill's growth, and because it is meaningless for an
-  external consumer installing a subset of the plugins.
-- **500-word body FAIL, matching `writing-skills/SKILL.md:217-221`.** Best-grounded in upstream and
-  would align this repo with the tightest source. Rejected because it fails 28 of 39 skills body-only
-  (35 of 39 measured whole-file), and a blunt gate gets satisfied by deleting content rather than
-  relocating it.
-- **A shrinking baseline file** recording each non-compliant skill's current numbers, failing only on
-  growth. Would have made the retrofit a visible burn-down instead of a wall. Rejected in favour of
-  hot gates.
-- **A sync gate over the duplicated spans** instead of a merge rule — generalising
-  `scripts/check-vale-style-sync.sh` to cover shared prose so duplication persists but drift cannot.
-  Rejected for the audit pair in favour of merging, which removes the duplication rather than
-  policing it, and removes a mutually-excluding near-miss pair from the router at the same time. It
-  remains the only available answer for the author pair.
-- **Merging `skill-author` + `agent-author` as well**, taking kyberforge from seven skills to five.
-  Largest cut available. Rejected because it reopens ADR-0005, ADR-0008 and ADR-0016 together, and a
-  merged author skill would carry both the skill-directory scaffold and the dual-provider agent
-  scaffold behind one dispatch.
-- **Demoting Gotchas** to the end of the body or into `references/gotchas.md`, removing its
-  position-based exemption from the dispatch rule. Maximum saving on the largest body construct
-  (6,830 words, 21% of all body text). Rejected because a gotcha read after the mistake is worthless.

docs/spec/architecture.md

@@ -19,22 +19,13 @@ project repo (local overrides)
 - **Executables** (`DEPLOY_EXECUTABLES`): `providers/claude-code/statusline-command.sh` → `~/.claude/statusline-command.sh` (with `+x`)
 - **Directories** (`DEPLOY_DIRS`): `core/` → `~/.claude/core/` (destination fully replaced on each deploy)
 
-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`.
+Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately via `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.
 
 ## 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.
-
-Two compilers produce the plugin roots you see in the tree:
-
-- **`apm pack` compiles the manifests** (ADR-0015). Per plugin: `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`, both generated from `plugins/<name>/apm.yml`. Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) and `.agents/plugins/marketplace.json` (its `codex` profile, a differently-shaped file). Those two are the only marketplace outputs apm has profiles for — the third root manifest, `.github/plugin/marketplace.json` (Copilot CLI's legacy path), is a byte-identical mirror of the Claude one maintained by `scripts/sync-marketplace-mirror.sh` and gated by the `check-marketplace-mirror-sync` pre-push hook.
-- **`scripts/sync-plugin-content.sh` compiles the content mirror** (ADR-0017). It wraps `apm pack --format plugin` and copies the resulting bundle's flat `agents/`, `skills/`, `commands/`, `instructions/`, `extensions/`, and merged `hooks/hooks.json` back to the plugin root. Claude Code's installer convention-scans those flat paths and has no `.apm/` awareness whatsoever, so the mirror exists solely to satisfy the host's discovery contract.
-
-`.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.
-
-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/`.
+Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`. Each plugin has a `plugin.json` manifest and is installed independently via `claude plugin install`.
 
 ## Governance layer
 
@@ -46,16 +37,14 @@ The governance layer has two phases:
 
 ## AGENTS.md pattern
 
-This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0003):
+This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012):
 
 - **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`.
 
 Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content.
 
-This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for working in this repo. It imports `AGENTS.md` and nothing else; there is no `@CONTEXT.md` import. It is not import-only either: below the import sits a fenced `<!-- rtk-instructions v2 -->` … `<!-- /rtk-instructions -->` block carrying the RTK command-prefix convention, which is tool-specific content with no `AGENTS.md` source. This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/`.
-
-`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.
+This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for working in this repo. It imports `AGENTS.md` and `CONTEXT.md`, nothing more. This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/`.
 
 ## Provider model
 
@@ -63,4 +52,4 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
 
 ## 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/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure.

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

@@ -1,49 +0,0 @@
----
-name: caveman
-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.
----
-
-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".
-
-## Rules
-
-Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
-
-Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
-
-Pattern: `[thing] [action] [reason]. [next step].`
-
-Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
-Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
-
-### Examples
-
-**"Why React component re-render?"**
-
-> Inline obj prop -> new ref -> re-render. `useMemo`.
-
-**"Explain database connection pooling."**
-
-> Pool = reuse DB conn. Skip handshake -> fast under load.
-
-## Auto-Clarity Exception
-
-Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
-
-Example -- destructive op:
-
-> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
->
-> ```sql
-> DROP TABLE users;
-> ```
->
-> Caveman resume. Verify backup exist first.

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

@@ -1,117 +0,0 @@
----
-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.
----
-
-# Diagnose
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### 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 `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-Do not proceed to Phase 2 until you have a loop you believe in.
-
-## Phase 2 — Reproduce
-
-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).
-- [ ] 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.
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
-
-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. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
-## Phase 6 — Cleanup + post-mortem
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

plugins/bin/.apm/skills/diagnose/scripts/hitl-loop.template.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

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

@@ -1,10 +0,0 @@
----
-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".
----
-
-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.
-
-Ask the questions one at a time.
-
-If a question can be answered by exploring the codebase, explore the codebase instead.

plugins/bin/.apm/skills/grill-with-docs/ADR-FORMAT.md

@@ -1,47 +0,0 @@
-# ADR Format
-
-ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
-
-Create the `docs/adr/` directory lazily — only when the first ADR is needed.
-
-## Template
-
-```md
-# {Short title of the decision}
-
-{1-3 sentences: what's the context, what did we decide, and why.}
-```
-
-That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
-
-## Optional sections
-
-Only include these when they add genuine value. Most ADRs won't need them.
-
-- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
-- **Considered Options** — only when the rejected alternatives are worth remembering
-- **Consequences** — only when non-obvious downstream effects need to be called out
-
-## Numbering
-
-Scan `docs/adr/` for the highest existing number and increment by one.
-
-## When to offer an ADR
-
-All three of these must be true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-2. **Surprising without context** — a future reader will look at the code and wonder "why on earth 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 a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
-
-### What qualifies
-
-- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
-- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
-- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
-- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
-- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
-- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
-- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

plugins/bin/.apm/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -1,77 +0,0 @@
-# CONTEXT.md Format
-
-## Structure
-
-```md
-# {Context Name}
-
-{One or two sentence description of what this context is and why it exists.}
-
-## Language
-
-**Order**:
-{A concise description of the term}
-_Avoid_: Purchase, transaction
-
-**Invoice**:
-A request for payment sent to a customer after delivery.
-_Avoid_: Bill, payment request
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
-
-## Relationships
-
-- An **Order** produces one or more **Invoices**
-- An **Invoice** belongs to exactly one **Customer**
-
-## Example dialogue
-
-> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
-> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
-
-## Flagged ambiguities
-
-- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
-```
-
-## Rules
-
-- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
-- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
-- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
-- **Show relationships.** Use bold term names and express cardinality where obvious.
-- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
-- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
-
-## Single vs multi-context repos
-
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
-
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
-
-The skill infers which structure applies:
-
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
-
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

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

@@ -1,88 +0,0 @@
----
-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.
----
-
-<what-to-do>
-
-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.
-
-Ask the questions one at a time, waiting for feedback on each question before continuing.
-
-If a question can be answered by exploring the codebase, explore the codebase instead.
-
-</what-to-do>
-
-<supporting-info>
-
-## Domain awareness
-
-During codebase exploration, also look for existing documentation:
-
-### File structure
-
-Most repos have a single context:
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
-
-## During the session
-
-### Challenge against the glossary
-
-When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
-### Sharpen fuzzy language
-
-When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
-
-### Discuss concrete scenarios
-
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
-
-### Cross-reference with code
-
-When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
-
-### 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).
-
-Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
-
-### Offer ADRs sparingly
-
-Only offer to create an ADR when all three are true:
-
-1. **Hard to reverse** — the cost of changing your mind later is meaningful
-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).
-
-</supporting-info>

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

@@ -1,37 +0,0 @@
-# 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**.
-
-## Dependency categories
-
-When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
-
-### 1. In-process
-
-Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
-
-### 2. Local-substitutable
-
-Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
-
-### 3. Remote but owned (Ports & Adapters)
-
-Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
-
-Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
-
-### 4. True external (Mock)
-
-Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
-
-## Seam discipline
-
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
-- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
-
-## Testing strategy: replace, don't layer
-
-- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
-- Write new tests at the deepened module's interface. The **interface is the test surface**.
-- Tests assert on observable outcomes through the interface, not internal state.
-- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

plugins/bin/.apm/skills/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -1,44 +0,0 @@
-# Interface Design
-
-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**.
-
-## Process
-
-### 1. Frame the problem space
-
-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))
-- 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.
-
-### 2. Spawn sub-agents
-
-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:
-
-- 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.
-
-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))
-5. Trade-offs — where leverage is high, where it's thin
-
-### 3. Present and compare
-
-Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
-
-After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

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

@@ -1,53 +0,0 @@
-# Language
-
-Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
-
-## Terms
-
-**Module**
-Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
-_Avoid_: unit, component, service.
-
-**Interface**
-Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
-_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
-
-**Implementation**
-What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
-
-**Depth**
-Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
-
-**Seam** _(from Michael Feathers)_
-A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
-_Avoid_: boundary (overloaded with DDD's bounded context).
-
-**Adapter**
-A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
-
-**Leverage**
-What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
-
-**Locality**
-What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
-
-## Principles
-
-- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
-- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
-- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
-
-## Relationships
-
-- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
-- **Depth** is a property of a **Module**, measured against its **Interface**.
-- A **Seam** is where a **Module**'s **Interface** lives.
-- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
-- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
-
-## Rejected framings
-
-- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
-- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
-- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

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

@@ -1,71 +0,0 @@
----
-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.
----
-
-# Improve Codebase Architecture
-
-Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
-
-## 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).
-
-- **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.
-- **Implementation** — the code inside.
-- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
-- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
-- **Adapter** — a concrete thing satisfying an interface at a seam.
-- **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):
-
-- **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.**
-
-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
-
-### 1. Explore
-
-Read the project's domain glossary and any ADRs in the area you're touching first.
-
-Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
-
-- Where does understanding one concept require bouncing between many small modules?
-- Where are modules **shallow** — interface nearly as complex as the implementation?
-- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
-- Where do tightly-coupled modules leak across their seams?
-- Which parts of the codebase are untested, or hard to test through their current interface?
-
-Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
-
-### 2. Present candidates
-
-Present a numbered list of deepening opportunities. For each candidate:
-
-- **Files** — which files/modules are involved
-- **Problem** — why the current architecture is causing friction
-- **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."
-
-**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.
-
-Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
-
-### 3. Grilling loop
-
-Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
-
-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.
-- **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).

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

@@ -1,79 +0,0 @@
-# Logic Prototype
-
-A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
-
-## When this is the right shape
-
-- "I'm not sure if this state machine handles the edge case where X then Y."
-- "Does this data model actually let me represent the case where..."
-- "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).
-
-## Process
-
-### 1. State the question
-
-Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
-
-### 2. Pick the language
-
-Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
-
-Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
-
-### 3. Isolate the logic in a portable module
-
-Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
-
-The right shape depends on the question:
-
-- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
-- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
-- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
-- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
-
-Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
-
-This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
-
-### 4. Build the smallest TUI that exposes the state
-
-Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
-
-Each frame has two parts, in this order:
-
-1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
-2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
-
-Behaviour:
-
-1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
-2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
-3. **Re-render** the full frame after every action — don't append, replace.
-4. **Loop until quit.**
-
-The whole frame should fit on one screen.
-
-### 5. Make it runnable in one command
-
-Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
-
-If the host project has no task runner, just put the command at the top of the prototype's README.
-
-### 6. Hand it over
-
-Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
-
-### 7. Capture the answer
-
-When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
-
-## Anti-patterns
-
-- **Don't add tests.** A prototype that needs tests is no longer a prototype.
-- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
-- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
-- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
-- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

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

@@ -1,30 +0,0 @@
----
-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".
----
-
-# Prototype
-
-A prototype is **throwaway code that answers a question**. The question decides the shape.
-
-## 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:
-
-- **"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.
-
-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.
-
-## Rules that apply to both
-
-1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
-2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
-3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
-4. **Skip the polish.** No tests, no error handling beyond what makes the prototype *runnable*, no abstractions. The point is to learn something fast and then delete it.
-5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
-6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
-
-## When done
-
-The *answer* is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

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

@@ -1,112 +0,0 @@
-# UI Prototype
-
-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).
-
-## When this is the right shape
-
-- "What should this page look like?"
-- "I want to see a few options for this dashboard before committing."
-- "Try a different layout for the settings screen."
-- Any time the user would otherwise spend a day picking between three vague mockups in their head.
-
-## Two sub-shapes — strongly prefer sub-shape A
-
-A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
-
-### Sub-shape A — adjustment to an existing page (preferred)
-
-The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
-
-If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
-
-### Sub-shape B — a new page (last resort)
-
-Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
-
-Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
-
-Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
-
-In both sub-shapes the floating bottom bar is identical.
-
-## Process
-
-### 1. State the question and pick N
-
-Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
-
-Write down the plan in one line, in the prototype's location or a top-of-file comment:
-
-> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
-
-This works whether the user is here to push back or not.
-
-### 2. Generate radically different variants
-
-Draft each variant. Hold each one to:
-
-- The page's purpose and the data it has access to.
-- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
-- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
-
-Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
-
-### 3. Wire them together
-
-Create a single switcher component on the route:
-
-```tsx
-// pseudo-code — adapt to the project's framework
-const variant = searchParams.get('variant') ?? 'A';
-return (
-  <>
-    {variant === 'A' && <VariantA {...data} />}
-    {variant === 'B' && <VariantB {...data} />}
-    {variant === 'C' && <VariantC {...data} />}
-    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
-  </>
-);
-```
-
-For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
-
-For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
-
-### 4. Build the floating switcher
-
-A small fixed-position bar at the bottom-centre of the screen with three pieces:
-
-- **Left arrow** — cycles to the previous variant (wraps around).
-- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
-- **Right arrow** — cycles forward (wraps around).
-
-Behaviour:
-
-- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
-- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
-- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
-- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
-
-Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
-
-### 5. Hand it over
-
-Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
-
-### 6. Capture the answer and clean up
-
-Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
-
-- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
-- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
-
-Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
-
-## Anti-patterns
-
-- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
-- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
-- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
-- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

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

@@ -1,97 +0,0 @@
----
-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).
-metadata:
-  category: research
-allowed-tools:
-  - WebSearch
-  - WebFetch
-  - Read
-  - Write
-  - mcp__context7__resolve-library-id
-  - mcp__context7__query-docs
-model: sonnet
----
-
-<requirements>
-
-## Required inputs
-
-- **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
-
-## Constraints
-
-- 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
-
-</requirements>
-
-<steps>
-
-## Process
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-6. **Consolidate.** Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.
-
-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.
-
-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`.
-
-## Output format
-
-- `<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
-
-</steps>
-
-<checks>
-
-## Failure handling
-
-- 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
-
-## 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>

plugins/bin/.apm/skills/research/references/file-format.md

@@ -1,39 +0,0 @@
-# Reference file format
-
-Every topic file follows this structure.
-
-## Frontmatter
-
-```yaml
----
-topic: <topic-slug>          # matches the filename without .md (e.g. "api-reference")
-source_keys:                 # kebab-case slugs of sources that contributed; must match sources.md entries
-  - <slug>
-  - <slug>
----
-```
-
-## Body
-
-Plain prose organized into markdown sections (`##`, `###`). Extract the content most relevant to skill authoring or implementation — not a verbatim copy of the source. Focus on:
-- Decisions that affect how to call the API or tool
-- Options, flags, or parameters with non-obvious behavior
-- Constraints, rate limits, or gotchas
-- Canonical patterns the skill should follow
-
-No inline URLs in the body — all source traceability lives in `sources.md` via `source_keys`.
-
-## sources.md format
-
-```markdown
-# Sources
-
-## <slug>
-
-- **URL:** <full URL>
-- **Description:** <one-line summary of what this source covers>
-- **Contributing files:** <comma-separated list of topic files this source contributed to>
-- **Status:** `extracted` | `no content extracted`
-```
-
-Use one `##` section per source. Slugs are kebab-case derived from the domain or page title (e.g. `stripe-api-docs`, `openai-python-sdk-readme`). For Context7 sources, use the slug `context7-<library-slug>` (e.g. `context7-vercel-next-js`) and set **URL** to `context7:<library-id>` (e.g. `context7:/vercel/next.js`).

plugins/bin/.apm/skills/research/references/topics.md

@@ -1,17 +0,0 @@
-# Default topic list
-
-Create one file per topic when relevant content is found. Skip topics with no content. Add custom topics when content warrants it.
-
-| File | Covers |
-|---|---|
-| `overview.md` | What it is, key concepts, mental model, architecture summary |
-| `installation.md` | Setup, dependencies, prerequisites, version requirements |
-| `configuration.md` | Config files, options, environment variables, defaults |
-| `cli-reference.md` | Commands, subcommands, flags, exit codes |
-| `api-reference.md` | Endpoints, SDK methods, types, request/response shapes |
-| `examples.md` | Common usage patterns, recipes, quickstart walkthroughs |
-| `troubleshooting.md` | Known issues, error codes, gotchas, workarounds |
-
-## Custom topics
-
-Create additional topic files when content doesn't fit the defaults. Examples: `webhooks.md`, `rate-limits.md`, `authentication.md`, `migrations.md`, `security.md`. Use kebab-case filenames.

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

@@ -1,109 +0,0 @@
----
-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.
----
-
-# Test-Driven Development
-
-## Philosophy
-
-**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
-
-**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
-
-**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.
-
-## Anti-Pattern: Horizontal Slices
-
-**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
-
-This produces **crap tests**:
-
-- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
-- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
-- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
-- You outrun your headlights, committing to test structure before understanding the implementation
-
-**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
-
-```
-WRONG (horizontal):
-  RED:   test1, test2, test3, test4, test5
-  GREEN: impl1, impl2, impl3, impl4, impl5
-
-RIGHT (vertical):
-  RED→GREEN: test1→impl1
-  RED→GREEN: test2→impl2
-  RED→GREEN: test3→impl3
-  ...
-```
-
-## Workflow
-
-### 1. Planning
-
-When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
-
-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)
-- [ ] List the behaviors to test (not implementation steps)
-- [ ] Get user approval on the plan
-
-Ask: "What should the public interface look like? Which behaviors are most important to test?"
-
-**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
-
-### 2. Tracer Bullet
-
-Write ONE test that confirms ONE thing about the system:
-
-```
-RED:   Write test for first behavior → test fails
-GREEN: Write minimal code to pass → test passes
-```
-
-This is your tracer bullet - proves the path works end-to-end.
-
-### 3. Incremental Loop
-
-For each remaining behavior:
-
-```
-RED:   Write next test → fails
-GREEN: Minimal code to pass → passes
-```
-
-Rules:
-
-- One test at a time
-- Only enough code to pass current test
-- Don't anticipate future tests
-- Keep tests focused on observable behavior
-
-### 4. Refactor
-
-After all tests pass, look for [refactor candidates](refactoring.md):
-
-- [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
-- [ ] Apply SOLID principles where natural
-- [ ] Consider what new code reveals about existing code
-- [ ] Run tests after each refactor step
-
-**Never refactor while RED.** Get to GREEN first.
-
-## Checklist Per Cycle
-
-```
-[ ] Test describes behavior, not implementation
-[ ] Test uses public interface only
-[ ] Test would survive internal refactor
-[ ] Code is minimal for this test
-[ ] No speculative features added
-```

plugins/bin/.apm/skills/tdd/deep-modules.md

@@ -1,33 +0,0 @@
-# Deep Modules
-
-From "A Philosophy of Software Design":
-
-**Deep module** = small interface + lots of implementation
-
-```
-┌─────────────────────┐
-│   Small Interface   │  ← Few methods, simple params
-├─────────────────────┤
-│                     │
-│                     │
-│  Deep Implementation│  ← Complex logic hidden
-│                     │
-│                     │
-└─────────────────────┘
-```
-
-**Shallow module** = large interface + little implementation (avoid)
-
-```
-┌─────────────────────────────────┐
-│       Large Interface           │  ← Many methods, complex params
-├─────────────────────────────────┤
-│  Thin Implementation            │  ← Just passes through
-└─────────────────────────────────┘
-```
-
-When designing interfaces, ask:
-
-- Can I reduce the number of methods?
-- Can I simplify the parameters?
-- Can I hide more complexity inside?

plugins/bin/.apm/skills/tdd/interface-design.md

@@ -1,31 +0,0 @@
-# Interface Design for Testability
-
-Good interfaces make testing natural:
-
-1. **Accept dependencies, don't create them**
-
-   ```typescript
-   // Testable
-   function processOrder(order, paymentGateway) {}
-
-   // Hard to test
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **Return results, don't produce side effects**
-
-   ```typescript
-   // Testable
-   function calculateDiscount(cart): Discount {}
-
-   // Hard to test
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **Small surface area**
-   - Fewer methods = fewer tests needed
-   - Fewer params = simpler test setup

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

@@ -1,59 +0,0 @@
-# When to Mock
-
-Mock at **system boundaries** only:
-
-- External APIs (payment, email, etc.)
-- Databases (sometimes - prefer test DB)
-- Time/randomness
-- File system (sometimes)
-
-Don't mock:
-
-- Your own classes/modules
-- Internal collaborators
-- Anything you control
-
-## Designing for Mockability
-
-At system boundaries, design interfaces that are easy to mock:
-
-**1. Use dependency injection**
-
-Pass external dependencies in rather than creating them internally:
-
-```typescript
-// Easy to mock
-function processPayment(order, paymentClient) {
-  return paymentClient.charge(order.total);
-}
-
-// Hard to mock
-function processPayment(order) {
-  const client = new StripeClient(process.env.STRIPE_KEY);
-  return client.charge(order.total);
-}
-```
-
-**2. Prefer SDK-style interfaces over generic fetchers**
-
-Create specific functions for each external operation instead of one generic function with conditional logic:
-
-```typescript
-// GOOD: Each function is independently mockable
-const api = {
-  getUser: (id) => fetch(`/users/${id}`),
-  getOrders: (userId) => fetch(`/users/${userId}/orders`),
-  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
-};
-
-// BAD: Mocking requires conditional logic inside the mock
-const api = {
-  fetch: (endpoint, options) => fetch(endpoint, options),
-};
-```
-
-The SDK approach means:
-- Each mock returns one specific shape
-- No conditional logic in test setup
-- Easier to see which endpoints a test exercises
-- Type safety per endpoint

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

@@ -1,10 +0,0 @@
-# Refactor Candidates
-
-After TDD cycle, look for:
-
-- **Duplication** → Extract function/class
-- **Long methods** → Break into private helpers (keep tests on public interface)
-- **Shallow modules** → Combine or deepen
-- **Feature envy** → Move logic to where data lives
-- **Primitive obsession** → Introduce value objects
-- **Existing code** the new code reveals as problematic

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

@@ -1,61 +0,0 @@
-# Good and Bad Tests
-
-## Good Tests
-
-**Integration-style**: Test through real interfaces, not mocks of internal parts.
-
-```typescript
-// GOOD: Tests observable behavior
-test("user can checkout with valid cart", async () => {
-  const cart = createCart();
-  cart.add(product);
-  const result = await checkout(cart, paymentMethod);
-  expect(result.status).toBe("confirmed");
-});
-```
-
-Characteristics:
-
-- Tests behavior users/callers care about
-- Uses public API only
-- Survives internal refactors
-- Describes WHAT, not HOW
-- One logical assertion per test
-
-## Bad Tests
-
-**Implementation-detail tests**: Coupled to internal structure.
-
-```typescript
-// BAD: Tests implementation details
-test("checkout calls paymentService.process", async () => {
-  const mockPayment = jest.mock(paymentService);
-  await checkout(cart, payment);
-  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
-});
-```
-
-Red flags:
-
-- Mocking internal collaborators
-- Testing private methods
-- Asserting on call counts/order
-- Test breaks when refactoring without behavior change
-- Test name describes HOW not WHAT
-- Verifying through external means instead of interface
-
-```typescript
-// BAD: Bypasses interface to verify
-test("createUser saves to database", async () => {
-  await createUser({ name: "Alice" });
-  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
-  expect(row).toBeDefined();
-});
-
-// GOOD: Verifies through interface
-test("createUser makes user retrievable", async () => {
-  const user = await createUser({ name: "Alice" });
-  const retrieved = await getUser(user.id);
-  expect(retrieved.name).toBe("Alice");
-});
-```

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

@@ -1,168 +0,0 @@
-# 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.
-
-## Principles
-
-### Durability over precision
-
-The issue may sit in `ready-for-agent` for days or weeks. The codebase will change in the meantime. Write the brief so it stays useful even as files are renamed, moved, or refactored.
-
-- **Do** describe interfaces, types, and behavioral contracts
-- **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
-- **Don't** reference file paths — they go stale
-- **Don't** reference line numbers
-- **Don't** assume the current implementation structure will remain the same
-
-### Behavioral, not procedural
-
-Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make its own implementation decisions.
-
-- **Good:** "The `SkillConfig` type should accept an optional `schedule` field of type `CronExpression`"
-- **Bad:** "Open src/types/skill.ts and add a schedule field on line 42"
-- **Good:** "When a user runs `/triage` with no arguments, they should see a summary of issues needing attention"
-- **Bad:** "Add a switch statement in the main handler function"
-
-### Complete acceptance criteria
-
-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"
-- **Bad:** "Triage should work correctly"
-
-### Explicit scope boundaries
-
-State what is out of scope. This prevents the agent from gold-plating or making assumptions about adjacent features.
-
-## Template
-
-```markdown
-## Agent Brief
-
-**Category:** bug / enhancement
-**Summary:** one-line description of what needs to happen
-
-**Current behavior:**
-Describe what happens now. For bugs, this is the broken behavior.
-For enhancements, this is the status quo the feature builds on.
-
-**Desired behavior:**
-Describe what should happen after the agent's work is complete.
-Be specific about edge cases and error conditions.
-
-**Key interfaces:**
-- `TypeName` — what needs to change and why
-- `functionName()` return type — what it currently returns vs what it should return
-- Config shape — any new configuration options needed
-
-**Acceptance criteria:**
-- [ ] Specific, testable criterion 1
-- [ ] Specific, testable criterion 2
-- [ ] Specific, testable criterion 3
-
-**Out of scope:**
-- Thing that should NOT be changed or addressed in this issue
-- Adjacent feature that might seem related but is separate
-```
-
-## Examples
-
-### Good agent brief (bug)
-
-```markdown
-## Agent Brief
-
-**Category:** bug
-**Summary:** Skill description truncation drops mid-word, producing broken output
-
-**Current behavior:**
-When a skill description exceeds 1024 characters, it is truncated at exactly
-1024 characters regardless of word boundaries. This produces descriptions
-that end mid-word (e.g. "Use when the user wants to confi").
-
-**Desired behavior:**
-Truncation should break at the last word boundary before 1024 characters
-and append "..." to indicate truncation.
-
-**Key interfaces:**
-- The `SkillMetadata` type's `description` field — no type change needed,
-  but the validation/processing logic that populates it needs to respect
-  word boundaries
-- Any function that reads SKILL.md frontmatter and extracts the description
-
-**Acceptance criteria:**
-- [ ] Descriptions under 1024 chars are unchanged
-- [ ] Descriptions over 1024 chars are truncated at the last word boundary
-      before 1024 chars
-- [ ] Truncated descriptions end with "..."
-- [ ] The total length including "..." does not exceed 1024 chars
-
-**Out of scope:**
-- Changing the 1024 char limit itself
-- Multi-line description support
-```
-
-### Good agent brief (enhancement)
-
-```markdown
-## Agent Brief
-
-**Category:** enhancement
-**Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
-
-**Current behavior:**
-When a feature request is rejected, the issue is closed with a `wontfix` label
-and a comment. There is no persistent record of the decision or reasoning.
-Future similar requests require the maintainer to recall or search for the
-prior discussion.
-
-**Desired behavior:**
-Rejected feature requests should be documented in `.out-of-scope/<concept>.md`
-files that capture the decision, reasoning, and links to all issues that
-requested the feature. When triaging new issues, these files should be
-checked for matches.
-
-**Key interfaces:**
-- Markdown file format in `.out-of-scope/` — each file should have a
-  `# Concept Name` heading, a `**Decision:**` line, a `**Reason:**` line,
-  and a `**Prior requests:**` list with issue links
-- The triage workflow should read all `.out-of-scope/*.md` files early
-  and match incoming issues against them by concept similarity
-
-**Acceptance criteria:**
-- [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
-- [ ] The file includes the decision, reasoning, and link to the closed issue
-- [ ] If a matching `.out-of-scope/` file already exists, the new issue is
-      appended to its "Prior requests" list rather than creating a duplicate
-- [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
-      when a new issue matches a prior rejection
-
-**Out of scope:**
-- Automated matching (human confirms the match)
-- Reopening previously rejected features
-- Bug reports (only enhancement rejections go to `.out-of-scope/`)
-```
-
-### Bad agent brief
-
-```markdown
-## Agent Brief
-
-**Summary:** Fix the triage bug
-
-**What to do:**
-The triage thing is broken. Look at the main file and fix it.
-The function around line 150 has the issue.
-
-**Files to change:**
-- src/triage/handler.ts (line 150)
-- src/types.ts (line 42)
-```
-
-This is bad because:
-- No category
-- Vague description ("the triage thing is broken")
-- References file paths and line numbers that will go stale
-- No acceptance criteria
-- No scope boundaries
-- No description of current vs desired behavior

plugins/bin/.apm/skills/triage/OUT-OF-SCOPE.md

@@ -1,101 +0,0 @@
-# Out-of-Scope Knowledge Base
-
-The `.out-of-scope/` directory in a repo stores persistent records of rejected feature requests. It serves two purposes:
-
-1. **Institutional memory** — why a feature was rejected, so the reasoning isn't lost when the issue is closed
-2. **Deduplication** — when a new issue comes in that matches a prior rejection, the skill can surface the previous decision instead of re-litigating it
-
-## Directory structure
-
-```
-.out-of-scope/
-├── dark-mode.md
-├── plugin-system.md
-└── graphql-api.md
-```
-
-One file per **concept**, not per issue. Multiple issues requesting the same thing are grouped under one file.
-
-## File format
-
-The file should be written in a relaxed, readable style — more like a short design document than a database entry. Use paragraphs, code samples, and examples to make the reasoning clear and useful to someone encountering it for the first time.
-
-```markdown
-# Dark Mode
-
-This project does not support dark mode or user-facing theming.
-
-## Why this is out of scope
-
-The rendering pipeline assumes a single color palette defined in
-`ThemeConfig`. Supporting multiple themes would require:
-
-- A theme context provider wrapping the entire component tree
-- Per-component theme-aware style resolution
-- A persistence layer for user theme preferences
-
-This is a significant architectural change that doesn't align with the
-project's focus on content authoring. Theming is a concern for downstream
-consumers who embed or redistribute the output.
-
-```ts
-// The current ThemeConfig interface is not designed for runtime switching:
-interface ThemeConfig {
-  colors: ColorPalette; // single palette, resolved at build time
-  fonts: FontStack;
-}
-```
-
-## Prior requests
-
-- #42 — "Add dark mode support"
-- #87 — "Night theme for accessibility"
-- #134 — "Dark theme option"
-```
-
-### Naming the file
-
-Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file.
-
-### Writing the reason
-
-The reason should be substantive — not "we don't want this" but why. Good reasons reference:
-
-- Project scope or philosophy ("This project focuses on X; theming is a downstream concern")
-- Technical constraints ("Supporting this would require Y, which conflicts with our Z architecture")
-- Strategic decisions ("We chose to use A instead of B because...")
-
-The reason should be durable. Avoid referencing temporary circumstances ("we're too busy right now") — those aren't real rejections, they're deferrals.
-
-## When to check `.out-of-scope/`
-
-During triage (Step 1: Gather context), read all files in `.out-of-scope/`. When evaluating a new issue:
-
-- Check if the request matches an existing out-of-scope concept
-- Matching is by concept similarity, not keyword — "night theme" matches `dark-mode.md`
-- If there's a match, surface it to the maintainer: "This is similar to `.out-of-scope/dark-mode.md` — we rejected this before because [reason]. Do you still feel the same way?"
-
-The maintainer may:
-
-- **Confirm** — the new issue gets added to the existing file's "Prior requests" list, then closed
-- **Reconsider** — the out-of-scope file gets deleted or updated, and the issue proceeds through normal triage
-- **Disagree** — the issues are related but distinct, proceed with normal triage
-
-## When to write to `.out-of-scope/`
-
-Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow:
-
-1. Maintainer decides a feature request is out of scope
-2. Check if a matching `.out-of-scope/` file already exists
-3. If yes: append the new issue to the "Prior requests" list
-4. If no: create a new file with the concept name, decision, reason, and first prior request
-5. Post a comment on the issue explaining the decision and mentioning the `.out-of-scope/` file
-6. Close the issue with the `wontfix` label
-
-## Updating or removing out-of-scope files
-
-If the maintainer changes their mind about a previously rejected concept:
-
-- Delete the `.out-of-scope/` file
-- The skill does not need to reopen old issues — they're historical records
-- The new issue that triggered the reconsideration proceeds through normal triage

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

@@ -1,103 +0,0 @@
----
-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.
----
-
-# Triage
-
-Move issues on the project issue tracker through a small state machine of triage roles.
-
-Every comment or issue posted to the issue tracker during triage **must** start with this disclaimer:
-
-```
-> *This was generated by AI during triage.*
-```
-
-## 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
-
-## Roles
-
-Two **category** roles:
-
-- `bug` — something is broken
-- `enhancement` — new feature or improvement
-
-Five **state** roles:
-
-- `needs-triage` — maintainer needs to evaluate
-- `needs-info` — waiting on reporter for more information
-- `ready-for-agent` — fully specified, ready for an AFK agent
-- `ready-for-human` — needs human implementation
-- `wontfix` — will not be actioned
-
-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.
-
-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.
-
-## Invocation
-
-The maintainer invokes `/triage` and describes what they want in natural language. Interpret the request and act. Examples:
-
-- "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?"
-
-## Show what needs attention
-
-Query the issue tracker and present three buckets, oldest first:
-
-1. **Unlabeled** — never triaged.
-2. **`needs-triage`** — evaluation in progress.
-3. **`needs-info` with reporter activity since the last triage notes** — needs re-evaluation.
-
-Show counts and a one-line summary per issue. Let the maintainer pick.
-
-## Triage a specific issue
-
-1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
-
-2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.
-
-3. **Reproduce (bugs only).** Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. Report what happened — successful repro with code path, failed repro, or insufficient detail (a strong `needs-info` signal). A confirmed repro makes a much stronger agent brief.
-
-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-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)).
-   - `needs-triage` — apply the role. Optional comment if there's partial progress.
-
-## Quick state override
-
-If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
-
-## Needs-info template
-
-```markdown
-## Triage Notes
-
-**What we've established so far:**
-
-- point 1
-- point 2
-
-**What we still need from you (@reporter):**
-
-- question 1
-- question 2
-```
-
-Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
-
-## Resuming a previous session
-
-If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.

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

@@ -1,103 +0,0 @@
----
-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"
-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:
-  category: implement
-source:
-  - repo: anthropics/skills
-    commit: f458cee31a7577a47ba0c9a101976fa599385174
-    files:
-      - skills/doc-coauthoring/SKILL.md  # Reader Testing stage, surgical-edit constraint, gap-check step
-    updated: 2026-05-17
-  - repo: mattpocock/skills
-    commit: e74f0061bb67222181640effa98c675bdb2fdaa7
-    files:
-      - skills/productivity/write-a-skill/SKILL.md  # trigger pattern, review checklist items
-    updated: 2026-05-17
-  - repo: bmad-code-org/BMAD-METHOD
-    commit: 71136bc6af77cbf507d3768494311d5b6ca95cc5
-    files:
-      - src/core-skills/bmad-advanced-elicitation/SKILL.md  # confirmation gate before applying changes
-    updated: 2026-05-17
----
-
-## Role
-
-You are a technical writer that produces documentation by reading code and spec — you derive every claim from a source file or explicit user input and never invent behaviour.
-
-## When to use / When not to use
-
-**Use when:**
-- User wants to document a module, class, function, feature, CLI flag, API endpoint, config file, or README section
-- 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 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
-
-## Required inputs
-
-- Specific file(s) or module(s) to document, or enough description to propose candidates
-- Target audience: developer / user / contributor / internal
-- Documentation type: reference, guide, README section, inline comment, changelog entry
-
-## Constraints
-
-- Every claim must be traceable to a source file line, spec section, or explicit user statement — never invent behaviour
-- User must approve specific files before the skill reads them; skill may propose candidates but waits for approval
-- Stage skipping is allowed only with an explicit user request and a one-sentence logged reason
-- Show the full revised section before each confirmation gate — never gate on output the user has not seen
-- Never reprint the whole document; all edits are surgical
-- Produce a one-line delta summary after each refinement round
-- Reader Testing sub-agent receives only the finished doc and the question list — no source files
-- Write summary and overview sections last, after all detail sections are stable
-
-## Process
-
-1. **Identify scope.** User names specific files or sections. If not provided, propose candidates based on the description — wait for explicit approval before reading.
-
-2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, non-obvious invariants. Note what the code does NOT explain (caller intent, error handling rationale, non-obvious side effects).
-
-3. **Gap check.** Present extracted behaviour to the user. Ask them to fill only the gaps — what the code does not explain. Log any explicitly deferred gaps. If the user requests to skip this step, log the reason and proceed.
-
-4. **Draft section by section.** For each section: state the proposed content and its source (code line / spec section / user input). Show; confirm before moving to the next section.
-
-5. **Confirmation gate.** Before finalising any section, show the full revised section. Wait for explicit confirmation or correction — never apply changes the user has not seen.
-
-6. **Delta summary.** After each round of revisions: "Round N: changed [sections], added [X], removed [Y]."
-
-7. **Reader Testing.** Predict 5–10 questions a target reader would ask. Spawn a scoped sub-agent that receives only the finished doc and the questions — no source files. Report its answers. If any answers fail, loop back to step 4.
-
-8. **Finalise.** Write summary and overview sections last. Prompt the user to review the complete document before committing.
-
-## Output format
-
-- Markdown artifact with section headers; produced one section at a time — never as a single large dump
-- Delta summary after each refinement round: "Round N: [what changed]"
-- Reader Testing report: numbered question list with sub-agent answers
-- Final doc at the user-specified or conventionally appropriate path
-
-## Failure handling
-
-- Files not named and description too vague to propose candidates → ask for specific names before reading
-- 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`
-
-## Self-check
-
-- [ ] All claims traceable to a source file or explicit user input
-- [ ] No invented behaviour — unverifiable claims removed
-- [ ] User approved specific files before reading
-- [ ] Any stage skips logged with reason
-- [ ] Full revised section shown before each confirmation gate
-- [ ] Delta summary produced after each refinement round
-- [ ] Reader Testing completed with scoped sub-agent (doc + questions only)
-- [ ] Summary/overview written last
-- [ ] User prompted to review before committing

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

@@ -1,7 +0,0 @@
----
-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
----
-
-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,30 +1,12 @@
 {
-  "name": "bin",
-  "version": "1.1.3",
-  "description": "A place for things to be binned",
   "author": {
     "name": "Defame1297",
-    "email": "defame1297@rkdr.net",
     "url": "https://git.dev.rkdr.net/Defame1297/"
   },
+  "description": "A place for things to be binned",
+  "displayName": "bin",
+  "keywords": [],
   "license": "MIT",
-  "homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
-  "repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
-  "keywords": [
-    "utility",
-    "diagnostics",
-    "prototyping",
-    "tdd",
-    "research"
-  ],
-  "mcpServers": {
-    "obsidian": {
-      "args": [
-        "@bitbonsai/mcpvault@0.15.0",
-        "docs/"
-      ],
-      "command": "npx",
-      "type": "stdio"
-    }
-  }
+  "name": "bin",
+  "version": "1.0.5"
 }

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

@@ -1,21 +0,0 @@
-{
-  "name": "bin",
-  "version": "1.1.3",
-  "description": "A place for things to be binned",
-  "author": {
-    "name": "Defame1297",
-    "email": "defame1297@rkdr.net",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
-  },
-  "license": "MIT",
-  "homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
-  "repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin",
-  "keywords": [
-    "utility",
-    "diagnostics",
-    "prototyping",
-    "tdd",
-    "research"
-  ],
-  "mcpServers": ".mcp.json"
-}

plugins/bin/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "obsidian": {
       "args": [
-        "@bitbonsai/mcpvault@0.15.0",
+        "@bitbonsai/mcpvault@latest",
         "docs/"
       ],
       "command": "npx",

plugins/bin/README.md

@@ -30,14 +30,10 @@ copilot plugin install ./plugins/bin
 
 ## Contents
 
-| Component | Path | Description |
-|---|---|---|
-| Skills | `.apm/skills/` → `skills/` | Slash commands available after install |
-| MCP servers | `.mcp.json` | The `obsidian` server (`npx @bitbonsai/mcpvault@0.15.0 docs/`), hand-authored at the plugin root |
-
-`.apm/` is the authoring source; `skills/` is the generated mirror plugin hosts scan (ADR-0017). This plugin ships no agents. It is the only plugin here with a non-empty `.mcp.json`, which is why its compiled manifests are the only ones carrying an `mcpServers` block.
-
-The two compiled manifests get that block by different routes. `.claude-plugin/plugin.json` gets it from apm itself: `build_plugin_manifest`'s Claude branch calls `collect_mcp_servers`, which reads `.mcp.json`, sanitizes it, and inlines the resulting server objects. `.github/plugin/plugin.json` gets nothing from apm — the Copilot branch drops the field — so `scripts/sync-plugin-content.sh`'s `reinject_mcp_servers()` puts it back, as the **string `".mcp.json"`** rather than the resolved objects. Copilot's manifest schema types the field as "string or object — MCP server config path or inline definitions", and a path reference cannot carry a credential into a committed manifest. See ADR-0017's `mcpServers` amendment.
+| Component   | Path                                                 | Description                                                   |
+| -------------| ------------------------------------------------------| ---------------------------------------------------------------|
+| Skills      | `skills/`                                            | Slash commands available after install                        |
+| Agents      | `agents/`                                            | Role-based agents (`.md` for Claude, `.agent.md` for Copilot) |
 
 ## Author
 

plugins/bin/apm.yml

@@ -1,35 +0,0 @@
-name: bin
-version: 1.1.3
-description: A place for things to be binned
-author:
-  name: Defame1297
-  email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
-license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/bin
-keywords:
-  - utility
-  - diagnostics
-  - prototyping
-  - tdd
-  - research
-
-# Constrains what .apm/ may contain: instructions, skill, hybrid, or prompts
-type: skill
-
-# Which agent platforms to deploy to.
-# Resolution order: --target flag > this field > auto-detect from filesystem.
-# Accepted values: agent-skills, antigravity, claude, codex, copilot, cursor, gemini, grok-build, kiro, opencode, windsurf
-targets:
-  - claude
-  - copilot
-  - codex
-
-dependencies:
-  apm: []
-  mcp: []
-includes: auto
-devDependencies:
-  apm: []
-scripts: {}

plugins/bin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "A place for things to be binned",
+  "keywords": [],
+  "license": "MIT",
+  "mcpServers": ".mcp.json",
+  "name": "bin",
+  "skills": [
+    "skills/"
+  ],
+  "version": "1.0.5"
+}

plugins/bin/skills/gitea/README.md

@@ -0,0 +1,38 @@
+# gitea
+
+Dispatch skill for managing a Gitea repo — issues, PRs, milestones, labels, and branches — from within Claude Code.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Skill definition — dispatch table, gotchas, execution steps |
+| `references/token-access.md` | Token scope inventory — what works vs. what needs additional scopes |
+
+## Usage
+
+```
+/gitea                          # status: open issues + open PRs
+/gitea issue                    # create issue from conversation context
+/gitea issue <N>                # get issue details
+/gitea issue close <N>          # close issue
+/gitea issue comment <N>        # add comment from conversation context
+/gitea label <N> Kind/Bug       # apply labels by name (resolves IDs automatically)
+/gitea milestone                # list milestones
+/gitea milestone create <title> # create milestone
+/gitea pr                       # create PR from current branch → main
+/gitea pr <N>                   # get PR status and diff summary
+/gitea pr merge <N>             # squash-merge PR, delete branch
+/gitea branch                   # list branches
+/gitea branch create <name>     # create branch from current branch
+```
+
+## Requirements
+
+- Gitea MCP server configured in `~/.claude.json` with `write:issue` and `write:repository` token scopes
+- `git remote origin` pointing to the Gitea instance (used to derive owner/repo at runtime)
+
+## Scope (v1)
+
+In scope: issues, milestones, labels, PRs, branches, status.
+Out of scope: releases, CI/Actions, wiki, file operations, notifications, packages, time tracking.

plugins/bin/skills/gitea/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: gitea
+description: >
+  Use when the user wants to interact with Gitea — create or update issues,
+  open or merge pull requests, manage labels and milestones, list branches,
+  or check repo status. Always use this skill to interact with the GiteaMCP, never use GiteaMCP directly.
+  Triggers on: "create an issue", "open a PR", "what's
+  open", "label this issue", "create a milestone", "merge the PR", "list
+  branches", "close this issue" — even when the user doesn't say "Gitea"
+  explicitly. Owner and repo are derived automatically from the git remote;
+  no config required. Do not use for releases, CI/Actions, wiki, file
+  operations, notifications, or package management — those are out of scope.
+compatibility: Requires Gitea MCP server configured in ~/.claude.json with write:issue and write:repository token scopes. Requires git remote "origin" pointing to the Gitea instance.
+allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__issue_write mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__list_branches mcp__gitea__create_branch
+metadata:
+  category: integration
+---
+
+## Gotchas
+
+- **Label writes take IDs, reads return names.** `issue_write` (add_labels, replace_labels) requires `labels: [3, 7]` (numeric IDs). Issue and PR responses return `labels: ["bug", "enhancement"]` (name strings). These are never interchangeable. Always call `label_read method: "list_repo_labels"` first and resolve names → IDs before any label write.
+- **Issues and PRs share a number space.** `#5` might be an issue or a PR — there is only one counter per repo. `list_issues` returns issues only — it has no `type` parameter. Use `list_pull_requests` separately for PRs. Check `is_pull` on a single-item `issue_read` response to determine whether a number refers to an issue or PR.
+- **Milestone write takes ID, not title.** `issue_write` takes `milestone: <numeric id>`. The title is not accepted. In `issue_read` responses the milestone is `{id, title}`, but in `pull_request_read` responses it's a bare title string — you cannot recover the ID from a PR response. Call `milestone_read method: "list"` and match by title if you need the ID from a PR context.
+- **`get_me` is unavailable** with the current token (`write:issue, write:repository` only — `read:user` is missing). Owner and repo must always be derived from the git remote, never from `get_me` or `list_my_repos`.
+- **Merging a PR does not itself close linked issues — but a commit message landing on the default branch can.** Gitea has no GitHub-style "merge triggers close" event. It does, however, parse closing keywords (`Fixes #N`, `Closes #N`) in commit messages pushed to the default branch. A regular (non-squash) merge preserves each original commit message, so if any of those commits says `Fixes #N`, the issue auto-closes at merge time — confirmed empirically (PR #64 auto-closed #63 this way, before any explicit `issue_write` call was made). This skill's own `pr merge` dispatch defaults to `merge_style: "squash"` (Step 3), which rewrites history into one commit — whether the keyword survives depends on what message that squash commit ends up with, so squash-merged PRs are the case most likely to still need an explicit close. Always call `issue_read method: "get"` to check current state before manually closing after a merge — closing an already-closed issue is a harmless no-op, but don't assume a manual close is always needed.
+- **Pagination is manual.** List tools return one page at a time — no auto-pagination. When building complete datasets (e.g. all labels for name→ID mapping), iterate `page: 1, 2, ...` until result count < `per_page`.
+- **`pull_request_read method: "get"` returns `review_scomments`, not `review_comments`.** This is a source-level typo in gitea-mcp v1.3.0. Do not access `review_comments` — it will always be undefined. Use `review_scomments`.
+- **Cross-repo fork PRs require `head` as `"fork-owner:branch-name"`.** A bare branch name causes Gitea to search the base repo and return 422. The `pr create` dispatch assumes same-repo PRs (bare branch name). For fork-based PRs, pass `head` explicitly in the `owner:branch` format.
+- **`draft: true` on PR create prepends `WIP:` to the title.** There is no first-class draft field — Gitea implements draft PRs via title prefix. To un-draft, call `pull_request_write method: "update"` and pass the title without the `WIP:` prefix. This differs from GitHub's draft PR model.
+- **HTTP 404 may mean 403.** Gitea hides permission errors as not-found to avoid leaking resource existence. If a tool call returns 404 unexpectedly, check `references/token-access.md` before assuming the resource does not exist.
+
+## Step 1 — Resolve owner and repo
+
+Before any tool call, extract `owner` and `repo` from the git remote:
+
+```bash
+git remote get-url origin
+```
+
+If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
+
+## Step 2 — Dispatch
+
+Route on the first argument:
+
+| Invocation | Action |
+|---|---|
+| `/gitea` (no args) | **Status** — list open issues + open PRs |
+| `/gitea issue` | Create issue from conversation context |
+| `/gitea issue <N>` | Get issue details |
+| `/gitea issue close <N>` | Close issue |
+| `/gitea issue comment <N>` | Add comment from conversation context |
+| `/gitea label <N> <names...>` | Apply named labels to issue/PR |
+| `/gitea milestone` | List milestones |
+| `/gitea milestone create <title>` | Create milestone |
+| `/gitea pr` | Create PR from current branch → main |
+| `/gitea pr <N>` | Get PR status and diff summary |
+| `/gitea pr merge <N>` | Merge PR (squash, delete branch) |
+| `/gitea branch` | List branches |
+| `/gitea branch create <name>` | Create branch from current branch |
+
+## Step 3 — Execute
+
+### Status (default)
+
+Call `list_issues state: "open"` and `list_pull_requests state: "open"` in parallel. `list_issues` does not accept a `type` parameter — it returns issues only. `list_pull_requests` returns PRs. Report as two sections.
+
+### issue (create)
+
+Extract title and body from conversation context. Use the most recent task, bug description, grill output, or explicit statement. If no body text is available from context, fall back to empty string. Fire immediately — no confirmation step.
+
+**Label inference (do this before the create call):**
+1. Call `label_read method: "list_repo_labels"` to get all available labels with their IDs.
+2. From conversation context, infer which labels apply:
+   - Issue type → `Kind/*`: bug reports → `Kind/Bug`; new capabilities → `Kind/Feature`; improvements → `Kind/Enhancement`; docs → `Kind/Documentation`; security → `Kind/Security`
+   - Urgency signals → `Priority/*`: "blocking", "critical", "urgent" → `Priority/Critical`; "soon", "high priority" → `Priority/High`; default → `Priority/Medium`
+   - Explicit blocking → `Status/Blocked`
+3. Resolve inferred label names to IDs from the label list. **Labels require numeric IDs — never pass name strings to `issue_write`.** If no labels can be confidently inferred, omit the `labels` parameter entirely rather than guessing.
+
+Set `ref` to the current branch name (`git branch --show-current`) if a branch is already checked out for this work.
+
+Call `issue_write method: "create" title: <extracted> body: <extracted or ""> labels: [<inferred IDs or omit>] ref: <current-branch-if-applicable>`.
+
+### issue <N>
+
+Call `issue_read method: "get" issue_number: <N>`. If the response includes `is_pull: true`, the number refers to a PR — report it as such and offer `pr <N>` for a full PR summary.
+
+### issue close <N>
+
+Call `issue_write method: "update" issue_number: <N> state: "closed"`. There is no `method: "close"` — using a non-existent method will error.
+
+### issue comment <N>
+
+Extract the comment body from conversation context (same sourcing as issue create). Call `issue_write method: "add_comment" issue_number: <N> body: <extracted>`.
+
+### label <N> <names...>
+
+1. Call `label_read method: "list_repo_labels"` — paginate until complete if > 30 labels.
+2. Match each provided name (case-insensitive) against the label list → collect IDs.
+3. Call `issue_write method: "add_labels" issue_number: <N> labels: [<matched IDs>]`.
+4. Report applied labels and warn on any names that did not match, listing available labels.
+
+Do not fail the operation because of unmatched names — apply what matches.
+
+### milestone
+
+Call `milestone_read method: "list"`. Report each milestone as: id, title, state (open/closed), open issue count, closed issue count.
+
+### pr (create)
+
+1. `git branch --show-current` → head branch.
+2. Title: extract from conversation context; fall back to the last commit message (`git log -1 --pretty=%s`).
+3. Body: extract from conversation; fall back to empty.
+4. Call `pull_request_write method: "create" head: <branch> base: "main" title: <derived in step 2> body: <derived in step 3>`.
+
+Note: this dispatch assumes a same-repo PR (bare branch name for `head`). For cross-repo fork PRs, `head` must be `"fork-owner:branch-name"` — see Gotchas.
+
+### pr <N>
+
+Call `pull_request_read method: "get"` and `pull_request_read method: "get_status"` in parallel (both take `pull_number: <N>`). Report: title, state, draft/merged flag, head → base, labels, CI status from get_status. Note: `milestone` in PR responses is a bare title string, not an object — you cannot extract a milestone ID from it.
+
+### pr merge <N>
+
+First call `pull_request_read method: "get_status" pull_number: <N>`. If CI status is failing, report it and warn the user — but do not block the merge unless they say to stop.
+
+Then call `pull_request_write method: "merge" pull_number: <N> merge_style: "squash" delete_branch: true`. To use a different merge style, the user must specify it explicitly.
+
+Squashing rewrites history into one commit — whether a linked issue's closing keyword survives depends on what message that squash commit ends up with. After merging, call `issue_read method: "get"` on any issue referenced by the PR to check whether it auto-closed before deciding whether to close it explicitly (see the auto-close gotcha above).
+
+### milestone create <title>
+
+Call `milestone_write method: "create" title: <title>`. Report the created milestone ID — it will be needed for assigning issues.
+
+### branch
+
+Call `list_branches`. Report each branch as: name, protected (bool).
+
+### branch create <name>
+
+Get the current local branch: `git branch --show-current`. Call `create_branch branch: <name> old_branch: <current-branch>`. This forks the new branch from where you are, not from the repo's default branch. If the user specifies a different base explicitly, use that instead.
+
+## Step 4 — Report
+
+For reads: display results as a compact table or numbered list — include number, title, labels, and milestone for issues/PRs.
+
+For writes: confirm what was created/updated with the Gitea issue/PR number and URL if returned.
+
+For errors: surface the HTTP code and message. 404 from some endpoints may actually mean insufficient token scope (Gitea hides 403 as 404 to avoid leaking resource existence).
+
+If label resolution fails partially, always report which names were applied and which were skipped.
+
+If token scope issues are suspected, read `references/token-access.md` for the full scope inventory.

plugins/bin/skills/prototype/SKILL.md

@@ -14,7 +14,7 @@ Identify which question is being answered — from the user's prompt, the surrou
 - **"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.
 
-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.
+The two branches produce very 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.
 
 ## Rules that apply to both
 

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

@@ -1,35 +0,0 @@
-# agentsmd-audit
-
-Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
-
-## What it does
-
-Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
-
-## Usage
-
-```
-/agentsmd-audit
-```
-
-Provide the path to the repo root to audit when invoking.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Skill instructions for agents |
-| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
-| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
-| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
-| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
-| `scripts/README.md` | Directory documentation for `scripts/` |
-| `tests/README.md` | (source-only) Bats test dependency and run instructions |
-| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
-| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
-| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
-
-Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
-not present in an installed plugin: `scripts/sync-plugin-content.sh` strips `<category>/<name>/tests`
-when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to
-discover (ADR-0017). Run them from a repo checkout, not from an install.

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

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

plugins/core/.apm/skills/agentsmd-audit/references/sources.md

@@ -1,33 +0,0 @@
-# Sources
-
-## agents-md-official
-
-- **URL:** https://agents.md/
-- **Description:** Official agents.md website — format spec, common-sections checklist, precedence rules (nearest-file-wins, no merge across files), monorepo nesting patterns
-- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
-- **Contributing files:** SKILL.md
-- **Status:** `extracted`
-
-## context7-websites-agents-md
-
-- **URL:** context7:/websites/agents_md
-- **Description:** Context7 index of the official agents.md website — overview, governance, cross-tool compatibility, configuration examples
-- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
-- **Contributing files:** SKILL.md
-- **Status:** `extracted`
-
-## context7-agentsmd-agents-md
-
-- **URL:** context7:/agentsmd/agents.md
-- **Description:** Context7 index of the agentsmd/agents.md repository — format spec, nested monorepo patterns, file structure examples
-- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
-- **Contributing files:** SKILL.md
-- **Status:** `extracted`
-
-## governance-secrets-hard-prohibition
-
-- **URL:** (org convention — not a plugin research corpus entry)
-- **Description:** Hard prohibition on placing secrets, API keys, tokens, or credentials in code, config, prompts, or any output. Grounds the secrets/credentials check in `scripts/validate-secrets.sh` and Step 1 of SKILL.md — AGENTS.md is committed content, so an embedded real secret is a hard-prohibition violation, not a style nit.
-- **Research doc:** core/instructions/governance.md (org convention file, not a plugin research corpus entry; content is inlined here since plugins must be self-contained and this file may not exist wherever the plugin is installed)
-- **Contributing files:** SKILL.md
-- **Status:** `extracted`

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

@@ -1,11 +0,0 @@
-# scripts/
-
-Deterministic validators this skill shells out to instead of relying on LLM judgment for mechanical checks.
-
-| File | Purpose |
-|------|---------|
-| `validate-secrets.sh` | Scans every AGENTS.md file (root + nested) for embedded secrets, API keys, tokens, and connection strings |
-| `validate-structure.sh` | Checks for empty/placeholder content, the common-sections checklist, and nested-vs-root duplication |
-| `validate-drift.sh` | Resolves referenced npm/make commands and file paths against the actual repo state |
-
-All three take a single `<repo-root>` argument, print `FAIL`/`INFO`/`SUGGESTION` findings to stdout, and exit non-zero only on FAIL.

plugins/core/.apm/skills/agentsmd-audit/scripts/validate-drift.sh

@@ -1,137 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<EOF
-Usage: validate-drift.sh <repo-root>
-
-Check every AGENTS.md file in a repo (root and nested) for drift: package
-manager scripts and file paths referenced in the text that no longer exist
-in the repo. Catches the failure mode that matters most in practice — an
-agent running a documented command that was renamed or deleted.
-
-Arguments:
-  repo-root  Path to the repository root to scan.
-
-Exit codes:
-  0  No FAIL findings (INFO may still be printed, e.g. no package.json found)
-  1  One or more FAIL findings
-EOF
-}
-
-if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
-  usage
-  exit 0
-fi
-
-if [[ $# -lt 1 ]]; then
-  echo "Error: repo-root is required." >&2
-  echo "" >&2
-  usage >&2
-  exit 1
-fi
-
-python3 -u - "$1" <<'PYTHON'
-import sys
-import os
-import re
-import json
-
-repo_root = os.path.abspath(sys.argv[1])
-if not os.path.isdir(repo_root):
-    print(f"Error: '{repo_root}' is not a directory.", file=sys.stderr)
-    sys.exit(1)
-
-EXCLUDE_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build"}
-
-def find_agents_md(root):
-    results = []
-    for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS and not d.startswith(".")]
-        for fname in filenames:
-            if fname == "AGENTS.md":
-                results.append(os.path.join(dirpath, fname))
-    return sorted(results)
-
-def load_package_scripts(root):
-    pkg_path = os.path.join(root, "package.json")
-    if not os.path.isfile(pkg_path):
-        return None
-    try:
-        with open(pkg_path, encoding="utf-8") as f:
-            data = json.load(f)
-    except (json.JSONDecodeError, OSError):
-        return None
-    return set(data.get("scripts", {}).keys())
-
-def load_make_targets(root):
-    make_path = os.path.join(root, "Makefile")
-    if not os.path.isfile(make_path):
-        return None
-    with open(make_path, encoding="utf-8", errors="replace") as f:
-        content = f.read()
-    return set(re.findall(r'(?m)^([a-zA-Z0-9_-]+)\s*:(?!=)', content))
-
-NPM_RUN_RE = re.compile(r'\b(?:npm|pnpm|yarn)\s+run\s+([a-zA-Z0-9:_-]+)')
-MAKE_RE = re.compile(r'\bmake\s+([a-zA-Z0-9_-]+)')
-
-# Backticked relative file paths, e.g. `scripts/bootstrap.sh`, `src/index.ts`.
-# Requires a path separator and file extension to avoid matching bare commands/words.
-PATH_RE = re.compile(r'`([A-Za-z0-9_.\-]+(?:/[A-Za-z0-9_.\-]+)+\.[A-Za-z0-9]+)`')
-
-has_fail = False
-
-package_scripts = load_package_scripts(repo_root)
-make_targets = load_make_targets(repo_root)
-
-for fpath in find_agents_md(repo_root):
-    rel = os.path.relpath(fpath, repo_root)
-    with open(fpath, encoding="utf-8", errors="replace") as f:
-        content = f.read()
-
-    for m in NPM_RUN_RE.finditer(content):
-        script_name = m.group(1)
-        if package_scripts is None:
-            print(f"INFO  Cannot verify referenced script '{script_name}' — {rel}")
-            print(f"      Note: AGENTS.md references an npm/pnpm/yarn script, but no package.json was found at the repo root to check it against.")
-            print()
-        elif script_name not in package_scripts:
-            has_fail = True
-            print(f"FAIL  Referenced script '{script_name}' not found in package.json — {rel}")
-            print(f"      Why: AGENTS.md tells agents to run '{script_name}', but package.json has no matching \"scripts\" entry — the command will fail.")
-            print(f"      Fix: Update AGENTS.md to reference an existing script, or add '{script_name}' to package.json's scripts.")
-            print()
-
-    for m in MAKE_RE.finditer(content):
-        target_name = m.group(1)
-        if make_targets is None:
-            print(f"INFO  Cannot verify referenced make target '{target_name}' — {rel}")
-            print(f"      Note: AGENTS.md references a make target, but no Makefile was found at the repo root to check it against.")
-            print()
-        elif target_name not in make_targets:
-            has_fail = True
-            print(f"FAIL  Referenced make target '{target_name}' not found in Makefile — {rel}")
-            print(f"      Why: AGENTS.md tells agents to run 'make {target_name}', but the Makefile has no matching target — the command will fail.")
-            print(f"      Fix: Update AGENTS.md to reference an existing target, or add '{target_name}' to the Makefile.")
-            print()
-
-    file_dir = os.path.dirname(fpath)
-    for m in PATH_RE.finditer(content):
-        candidate = m.group(1)
-        resolved = (
-            os.path.isfile(os.path.join(repo_root, candidate))
-            or os.path.isfile(os.path.join(file_dir, candidate))
-            or os.path.isdir(os.path.join(repo_root, candidate))
-            or os.path.isdir(os.path.join(file_dir, candidate))
-        )
-        if not resolved:
-            has_fail = True
-            print(f"FAIL  Referenced path '{candidate}' does not exist — {rel}")
-            print(f"      Why: AGENTS.md points agents to '{candidate}', but it isn't present in the repo (checked relative to repo root and to the AGENTS.md's own directory).")
-            print(f"      Fix: Update AGENTS.md to reference the correct path, or restore/create '{candidate}'.")
-            print()
-
-if has_fail:
-    sys.exit(1)
-sys.exit(0)
-PYTHON

plugins/core/.apm/skills/agentsmd-audit/scripts/validate-secrets.sh

@@ -1,120 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<EOF
-Usage: validate-secrets.sh <repo-root>
-
-Scan every AGENTS.md file in a repo (root and nested) for embedded secrets,
-API keys, tokens, or connection strings. AGENTS.md is committed content —
-real credentials in it are a hard-prohibition violation, not a style nit.
-Placeholders (<your-key>, \$ENV_VAR, YOUR_TOKEN_HERE, example.com, etc.) are
-not flagged.
-
-Arguments:
-  repo-root  Path to the repository root to scan.
-
-Exit codes:
-  0  No findings
-  1  One or more FAIL findings
-EOF
-}
-
-if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
-  usage
-  exit 0
-fi
-
-if [[ $# -lt 1 ]]; then
-  echo "Error: repo-root is required." >&2
-  echo "" >&2
-  usage >&2
-  exit 1
-fi
-
-python3 -u - "$1" <<'PYTHON'
-import sys
-import os
-import re
-
-repo_root = os.path.abspath(sys.argv[1])
-if not os.path.isdir(repo_root):
-    print(f"Error: '{repo_root}' is not a directory.", file=sys.stderr)
-    sys.exit(1)
-
-EXCLUDE_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build"}
-
-def find_agents_md(root):
-    results = []
-    for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS and not d.startswith(".")]
-        for fname in filenames:
-            if fname == "AGENTS.md":
-                results.append(os.path.join(dirpath, fname))
-    return sorted(results)
-
-PLACEHOLDER_RE = re.compile(
-    r'(?i)(your[_-]|my[_-]|example|xxx+|placeholder|changeme|<[^>]+>|\$\{|\$[A-Z_][A-Z0-9_]*|\.\.\.|redacted)'
-)
-
-PATTERNS = [
-    ("AWS access key ID", re.compile(r'AKIA[0-9A-Z]{16}')),
-    ("Private key block", re.compile(r'-----BEGIN [A-Z ]*PRIVATE KEY-----')),
-    ("GitHub token", re.compile(r'gh[pousr]_[A-Za-z0-9]{36,}')),
-    ("Slack token", re.compile(r'xox[baprs]-[A-Za-z0-9-]{10,}')),
-    ("GitLab token", re.compile(r'glpat-[A-Za-z0-9_-]{20,}')),
-    ("Generic API-style secret token", re.compile(r'\bsk-[A-Za-z0-9]{20,}\b')),
-    (
-        "Credential-bearing connection string",
-        re.compile(r'[a-zA-Z][a-zA-Z0-9+.-]*://[^:@/\s]+:[^@/\s]+@[^\s\'"]+'),
-    ),
-    (
-        "Assigned secret/password/token literal",
-        re.compile(
-            r'(?i)\b(api[_-]?key|secret|token|password|passwd|pwd|access[_-]?key)\b'
-            r'\s*[:=]\s*[\'"]?([A-Za-z0-9+/_.\-]{12,})[\'"]?'
-        ),
-    ),
-]
-
-findings = []
-
-def emit_fail(desc, fpath, lineno, why, fix):
-    findings.append((desc, fpath, lineno, why, fix))
-
-for fpath in find_agents_md(repo_root):
-    rel = os.path.relpath(fpath, repo_root)
-    with open(fpath, encoding="utf-8", errors="replace") as f:
-        lines = f.readlines()
-    for i, line in enumerate(lines, start=1):
-        for label, pattern in PATTERNS:
-            m = pattern.search(line)
-            if not m:
-                continue
-            # Scope the placeholder allowlist to the matched secret-candidate
-            # substring only. Checking the whole line would let an unrelated
-            # placeholder-looking token elsewhere on the line (e.g. in a
-            # trailing comment) suppress detection of a real credential.
-            value = m.group(0)
-            if PLACEHOLDER_RE.search(value):
-                continue
-            emit_fail(
-                f"Possible {label}",
-                f"{rel}:{i}",
-                i,
-                "AGENTS.md is committed content; this line matches a real-looking credential pattern rather than a placeholder.",
-                "Remove the embedded credential and replace it with an environment variable reference or placeholder (e.g. $API_KEY, <your-token>).",
-            )
-            break
-
-if not findings:
-    sys.exit(0)
-
-for desc, fpath, _lineno, why, fix in findings:
-    print(f"FAIL  {desc} — {fpath}")
-    print(f"      Why: {why}")
-    print(f"      Fix: {fix}")
-    print()
-
-sys.exit(1)
-PYTHON

plugins/core/.apm/skills/agentsmd-audit/scripts/validate-structure.sh

@@ -1,118 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<EOF
-Usage: validate-structure.sh <repo-root>
-
-Check every AGENTS.md file in a repo (root and nested) for structural
-completeness against the agents.md spec's common-sections checklist
-(setup/build, code style, testing, security, commit/PR conventions).
-Missing individual sections are informational (not every repo needs every
-section) — only an empty or entirely unfilled file is a hard failure.
-
-Arguments:
-  repo-root  Path to the repository root to scan.
-
-Exit codes:
-  0  No FAIL findings (INFO/SUGGESTION may still be printed)
-  1  One or more FAIL findings
-EOF
-}
-
-if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
-  usage
-  exit 0
-fi
-
-if [[ $# -lt 1 ]]; then
-  echo "Error: repo-root is required." >&2
-  echo "" >&2
-  usage >&2
-  exit 1
-fi
-
-python3 -u - "$1" <<'PYTHON'
-import sys
-import os
-import re
-
-PLACEHOLDER_RE = re.compile(r'(?i)FILL IN:|TODO:\s*write|lorem ipsum')
-
-COMMON_SECTIONS = [
-    ("setup/build commands", re.compile(r'(?im)^#{1,3}\s*(setup|install|build|getting started)')),
-    ("code style", re.compile(r'(?im)^#{1,3}\s*(code style|style guide|conventions)')),
-    ("testing instructions", re.compile(r'(?im)^#{1,3}\s*(test|testing)')),
-    ("security considerations", re.compile(r'(?im)^#{1,3}\s*security')),
-    ("commit/PR conventions", re.compile(r'(?im)^#{1,3}\s*(commit|pr|pull request)')),
-]
-
-repo_root = os.path.abspath(sys.argv[1])
-if not os.path.isdir(repo_root):
-    print(f"Error: '{repo_root}' is not a directory.", file=sys.stderr)
-    sys.exit(1)
-
-EXCLUDE_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "dist", "build"}
-
-def find_agents_md(root):
-    results = []
-    for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS and not d.startswith(".")]
-        for fname in filenames:
-            if fname == "AGENTS.md":
-                results.append(os.path.join(dirpath, fname))
-    return sorted(results)
-
-has_fail = False
-file_contents = {}  # rel path -> content, for the duplication pass below
-
-for fpath in find_agents_md(repo_root):
-    rel = os.path.relpath(fpath, repo_root)
-    with open(fpath, encoding="utf-8", errors="replace") as f:
-        content = f.read()
-    file_contents[rel] = content
-
-    if not content.strip():
-        has_fail = True
-        print(f"FAIL  AGENTS.md is empty — {rel}")
-        print("      Why: An empty file provides no instructions and gives agents nothing to act on.")
-        print("      Fix: Add at least a project overview and setup/test commands, per the agents.md common-sections checklist.")
-        print()
-        continue
-
-    if PLACEHOLDER_RE.search(content):
-        has_fail = True
-        print(f"FAIL  Unfilled placeholder content — {rel}")
-        print("      Why: A 'FILL IN:' or template stub left in place means the file has no repo-specific instructions yet.")
-        print("      Fix: Replace the placeholder with real, repo-specific content.")
-        print()
-        continue
-
-    for label, pattern in COMMON_SECTIONS:
-        if not pattern.search(content):
-            print(f"INFO  No {label} section — {rel}")
-            print(f"      Note: The agents.md common-sections checklist includes {label}; not every repo needs every section, but confirm this omission is deliberate.")
-            print()
-
-# --- Nested-vs-root duplication check ---
-root_content = file_contents.get("AGENTS.md")
-if root_content:
-    root_lines = {ln.strip() for ln in root_content.splitlines() if ln.strip()}
-    for rel, content in file_contents.items():
-        if rel == "AGENTS.md":
-            continue
-        nested_lines = [ln.strip() for ln in content.splitlines() if ln.strip()]
-        if not nested_lines:
-            continue
-        overlap = sum(1 for ln in nested_lines if ln in root_lines)
-        ratio = overlap / len(nested_lines)
-        if ratio >= 0.7:
-            print(f"SUGGESTION  Nested AGENTS.md largely duplicates the root file — {rel}")
-            print(f"      Why: {ratio:.0%} of this file's content lines already appear in the root AGENTS.md; per the spec's nearest-file-wins precedence, nested files don't inherit from the root, but they also shouldn't just restate it.")
-            print(f"      Fix: Trim {rel} down to only what's specific to this package/directory.")
-            print()
-
-if has_fail:
-    sys.exit(1)
-sys.exit(0)
-PYTHON

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

@@ -1,30 +0,0 @@
-# tests/
-
-Test files for scripts bundled with this skill.
-
-## Dependencies
-
-Tests require [bats-support](https://github.com/bats-core/bats-support) and
-[bats-assert](https://github.com/bats-core/bats-assert). The test files load
-helpers from the repo root's `tests/test_helper/`.
-
-From the repo root:
-
-```bash
-git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support
-git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
-```
-
-Run all tests for this skill (from the repo root):
-
-```bash
-bats plugins/core/.apm/skills/agentsmd-audit/tests/
-```
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `validate-secrets.bats` | Bats test suite for `scripts/validate-secrets.sh` |
-| `validate-structure.bats` | Bats test suite for `scripts/validate-structure.sh` |
-| `validate-drift.bats` | Bats test suite for `scripts/validate-drift.sh` |

plugins/core/.apm/skills/agentsmd-audit/tests/validate-drift.bats

@@ -1,105 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-    REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../../" && pwd)"
-    load "$REPO_ROOT/tests/test_helper/bats-support/load"
-    load "$REPO_ROOT/tests/test_helper/bats-assert/load"
-
-    SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-drift.sh"
-    TMPDIR="$(mktemp -d)"
-}
-
-teardown() {
-    rm -rf "$TMPDIR"
-}
-
-@test "fails when AGENTS.md references a stale npm script" {
-    cat > "$TMPDIR/package.json" <<'EOF'
-{
-  "scripts": {
-    "test": "jest"
-  }
-}
-EOF
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Testing
-- Run `pnpm run e2e` before committing.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "e2e"
-}
-
-@test "passes when the referenced npm script exists" {
-    cat > "$TMPDIR/package.json" <<'EOF'
-{
-  "scripts": {
-    "test": "jest"
-  }
-}
-EOF
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Testing
-- Run `npm run test` before committing.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_success
-}
-
-@test "fails when AGENTS.md references a stale make target" {
-    cat > "$TMPDIR/Makefile" <<'EOF'
-build:
-	echo building
-EOF
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-Run `make deploy` to ship.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "deploy"
-}
-
-@test "emits INFO instead of FAIL when there is no package.json to verify an npm script against" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Testing
-Run `pnpm run e2e` before committing.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_success
-    assert_output --partial "INFO"
-    assert_output --partial "e2e"
-}
-
-@test "fails when a referenced file path does not exist" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-See `scripts/bootstrap.sh` for environment setup.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "scripts/bootstrap.sh"
-}
-
-@test "passes when the referenced file path exists" {
-    mkdir -p "$TMPDIR/scripts"
-    : > "$TMPDIR/scripts/bootstrap.sh"
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-See `scripts/bootstrap.sh` for environment setup.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_success
-}

plugins/core/.apm/skills/agentsmd-audit/tests/validate-secrets.bats

@@ -1,81 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-    REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../../" && pwd)"
-    load "$REPO_ROOT/tests/test_helper/bats-support/load"
-    load "$REPO_ROOT/tests/test_helper/bats-assert/load"
-
-    SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-secrets.sh"
-    TMPDIR="$(mktemp -d)"
-}
-
-teardown() {
-    rm -rf "$TMPDIR"
-}
-
-@test "passes on AGENTS.md with no secrets, only placeholders" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-- Set `export API_KEY=$API_KEY`
-- Token: <your-token-here>
-- DB: postgres://user:changeme@localhost/db
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_success
-    assert_output ""
-}
-
-@test "fails on a real-looking AWS access key" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-- AWS_ACCESS_KEY_ID=AKIAABCDEFGHIJKLMNOP # gitleaks:allow (synthetic fixture — this test verifies validate-secrets.sh catches exactly this pattern)
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "AWS access key ID"
-    assert_output --partial "AGENTS.md:4"
-}
-
-@test "fails on a credential-bearing connection string" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-- DB: postgres://svc_user:h8x2Klm9pQrT@db.internal:5432/prod
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "connection string"
-}
-
-@test "still catches a real secret when a placeholder token sits elsewhere on the same line" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-- AWS_ACCESS_KEY_ID=AKIAABCDEFGHIJKLMNOP # see your-token-here for an example, gitleaks:allow (synthetic fixture — this test verifies the placeholder allowlist is scoped to the matched value, not the whole line)
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "AWS access key ID"
-    assert_output --partial "AGENTS.md:4"
-}
-
-@test "detects secrets in a nested AGENTS.md, not just root" {
-    mkdir -p "$TMPDIR/packages/api"
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-Clean root file.
-EOF
-    cat > "$TMPDIR/packages/api/AGENTS.md" <<'EOF'
-# API package
-- token: ghp_1234567890abcdefghijklmnopqrstuvwxyz01 # gitleaks:allow (synthetic fixture)
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "packages/api/AGENTS.md"
-}

plugins/core/.apm/skills/agentsmd-audit/tests/validate-structure.bats

@@ -1,76 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-    REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../../" && pwd)"
-    load "$REPO_ROOT/tests/test_helper/bats-support/load"
-    load "$REPO_ROOT/tests/test_helper/bats-assert/load"
-
-    SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-structure.sh"
-    TMPDIR="$(mktemp -d)"
-}
-
-teardown() {
-    rm -rf "$TMPDIR"
-}
-
-@test "fails on an empty AGENTS.md" {
-    : > "$TMPDIR/AGENTS.md"
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "empty"
-}
-
-@test "fails on an unfilled placeholder AGENTS.md" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup
-FILL IN: describe setup commands here.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_failure
-    assert_output --partial "placeholder"
-}
-
-@test "passes with INFO on real content missing an optional section" {
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup commands
-- Install deps: `pnpm install`
-- Run tests: `pnpm test`
-
-## Code style
-- TypeScript strict mode, single quotes, no semicolons.
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_success
-    assert_output --partial "INFO"
-    assert_output --partial "security"
-}
-
-@test "suggests trimming a nested AGENTS.md that duplicates the root file" {
-    mkdir -p "$TMPDIR/packages/api"
-    cat > "$TMPDIR/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup commands
-- Install deps: `pnpm install`
-- Run tests: `pnpm test`
-- Lint: `pnpm lint`
-- Build: `pnpm build`
-EOF
-    cat > "$TMPDIR/packages/api/AGENTS.md" <<'EOF'
-# AGENTS.md
-
-## Setup commands
-- Install deps: `pnpm install`
-- Run tests: `pnpm test`
-- Lint: `pnpm lint`
-- Build: `pnpm build`
-EOF
-    run bash "$SCRIPT" "$TMPDIR"
-    assert_success
-    assert_output --partial "SUGGESTION"
-    assert_output --partial "packages/api/AGENTS.md"
-}

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

@@ -1,27 +0,0 @@
-# agentsmd-author
-
-Create or update a target repo's AGENTS.md file(s) by exploring the repo for real conventions.
-
-## What it does
-
-Explores a target repo (package manager scripts, Makefile/task runner, CI config, linter config, existing docs) and writes or updates `AGENTS.md` with only verified commands and conventions — never invented ones. Supports nested monorepo placement, following the agents.md standard's nearest-file-wins precedence. Closes every run by invoking `agentsmd-audit` inline, and hands off to `provider-adapter-author` when an existing provider-specific file (CLAUDE.md, etc.) now duplicates content AGENTS.md owns.
-
-## Before you start
-
-The `agentsmd-audit` skill must be available (co-installed in the `core` plugin) — this skill invokes it as a mandatory closeout step.
-
-## Usage
-
-```
-/agentsmd-author
-```
-
-Provide the target repo root (defaults to the current directory) and, if relevant, which subdirectory should get a nested AGENTS.md.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Skill instructions for agents |
-| `references/content-guide.md` | Section-by-section AGENTS.md content guidance, a worked example, and monorepo/nested-file precedence rules |
-| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |

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

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

plugins/core/.apm/skills/agentsmd-author/references/content-guide.md

@@ -1,118 +0,0 @@
----
-source_keys:
-  - agents-md-official
-  - context7-websites-agents-md
-  - context7-agentsmd-agents-md
----
-
-# What good AGENTS.md content looks like
-
-AGENTS.md has no required schema — there's no field to fill in, only sections that either
-earn their place or don't. Agents treat this file as a set of live directives, not
-documentation: they will actually run the commands it lists and fix failures before
-finishing a task. That means a wrong or stale line is worse than a missing one. Verify
-every command against something real in the repo before writing it down.
-
-## Section-by-section guidance
-
-**Setup / build commands** — the install and dev-server commands, exactly as they appear
-in `package.json` scripts, a `Makefile`, or a `Cargo.toml`/`pyproject.toml` equivalent. One
-line per command, each with a one-clause note on what it does if the name alone isn't
-obvious. Skip this section if there's genuinely nothing beyond "clone and run" — don't pad
-it with a restated `git clone`.
-
-**Code style** — only conventions that aren't already enforced by a linter/formatter config
-the agent will pick up on its own (a `.eslintrc`, `rustfmt.toml`, etc. speaks for itself).
-Write down the conventions that live only in people's heads: naming patterns, module
-boundaries, patterns to avoid, anything a linter can't catch. If the repo has no
-undocumented conventions beyond what tooling enforces, skip this section.
-
-**Testing instructions** — the exact command(s) to run the suite, where to find
-per-package or per-workflow test configuration (e.g. `.github/workflows/`), and any
-non-obvious requirement (a service that must be running, an env var that must be set).
-State plainly that the agent should run tests before considering a change done and fix
-failures — don't leave this implicit.
-
-**Security considerations** — only repo-specific hazards: a data-handling boundary, a
-credential pattern to never hardcode, a destructive command that needs a confirmation
-step. Do not restate general security advice ("don't commit secrets") that any agent
-already assumes — that's padding, not a directive.
-
-**Commit / PR conventions** — the title/format convention if one exists (e.g. a
-Conventional Commits type prefix, a ticket-number requirement), and any check that must
-pass before a PR is opened (lint, test, type-check). Point at the real command, not
-"make sure it passes."
-
-**Dev environment tips** — the handful of things that save real time and are easy to miss:
-how to jump to a specific package in a monorepo without `ls`-ing around, how to register a
-new package so the toolchain sees it, where to look up a canonical name/id. This section
-is for genuine friction points observed in this repo, not generic advice.
-
-## What separates useful content from padding
-
-A useful section names a real file, command, or path that exists in this repo right now.
-A padded section could be pasted into any repo unchanged and still "make sense" — that's
-the tell. If a sentence would read the same in a different codebase, it doesn't belong.
-Prefer four accurate lines over twelve generic ones.
-
-## Worked example (minimal project)
-
-```markdown
-# AGENTS.md
-
-## Setup commands
-- Install deps: `pnpm install`
-- Start dev server: `pnpm dev`
-- Run tests: `pnpm test`
-
-## Code style
-- TypeScript strict mode
-- Single quotes, no semicolons
-- Use functional patterns where possible
-
-## Dev environment tips
-- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
-- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
-- Check the `name` field inside each package's `package.json` to confirm the right name.
-
-## Testing instructions
-- Find the CI plan in the `.github/workflows` folder.
-- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
-- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
-- Fix any test or type errors until the whole suite is green.
-- Add or update tests for the code you change, even if nobody asked.
-
-## PR instructions
-- Title format: [<project_name>] <Title>
-- Always run `pnpm lint` and `pnpm test` before committing.
-```
-
-Every line above names a real command or path — that's the standard to hold this repo's
-version to, not the specific tooling shown (a Python/Cargo/Go repo's AGENTS.md should look
-nothing like this one in its specifics, only in how concrete each line is).
-
-## Monorepo / nested placement
-
-```
-my-monorepo/
-├── AGENTS.md              # Root-level: applies to the whole repo
-├── packages/
-│   ├── api/
-│   │   └── AGENTS.md      # API-specific instructions; overrides root for this package
-│   ├── web/
-│   │   └── AGENTS.md      # Web app-specific instructions
-│   └── shared/
-│       └── AGENTS.md      # Shared library instructions
-```
-
-Precedence rule: the file nearest the edited path wins. Nested files are **not** merged
-with the root file — an agent editing inside `packages/api/` reads only
-`packages/api/AGENTS.md`, never the root file in addition. Consequences:
-
-- A nested file must stand alone. Don't write "also see the root file" — write what the
-  agent needs, full stop.
-- Don't duplicate root content in a nested file "just in case." If a nested file repeats
-  root-level setup instructions verbatim, that's a sign it shouldn't exist as a separate
-  file at all — the subtree isn't actually different enough to warrant one.
-- Only create a nested file when the subtree has a genuinely different stack, build tool,
-  or convention than the root (see `SKILL.md` Step 2 for the placement decision itself).

plugins/core/.apm/skills/agentsmd-author/references/sources.md

@@ -1,25 +0,0 @@
-# Sources
-
-## agents-md-official
-
-- **URL:** https://agents.md/
-- **Description:** Official agents.md website — format spec, common-sections checklist, precedence rules (nearest-file-wins, no merge across files), monorepo nesting patterns
-- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
-- **Contributing files:** SKILL.md, references/content-guide.md
-- **Status:** `extracted`
-
-## context7-websites-agents-md
-
-- **URL:** context7:/websites/agents_md
-- **Description:** Context7 index of the official agents.md website — overview, governance, cross-tool compatibility, configuration examples
-- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
-- **Contributing files:** SKILL.md, references/content-guide.md
-- **Status:** `extracted`
-
-## context7-agentsmd-agents-md
-
-- **URL:** context7:/agentsmd/agents.md
-- **Description:** Context7 index of the agentsmd/agents.md repository — format spec, nested monorepo patterns, file structure examples
-- **Research doc:** plugins/core/docs/research/docs/agentsmd/sources.md
-- **Contributing files:** SKILL.md, references/content-guide.md
-- **Status:** `extracted`

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

@@ -1,35 +0,0 @@
-# provider-adapter-author
-
-Convert a target repo's provider-specific instruction file (CLAUDE.md, .cursor/rules, copilot-instructions.md, etc.) into a thin adapter over AGENTS.md.
-
-## What it does
-
-Detects a provider-specific AI instruction file in a target repo, diffs it against the repo's `AGENTS.md`, and rewrites it down to a minimal reference — an `@AGENTS.md`-style import for providers that support one, or a text pointer for those that don't — plus only genuinely provider-specific additions. Self-validates its own output with a bundled deterministic script (no LLM judgment, no separate audit skill) before finishing.
-
-## Before you start
-
-The target repo must already have an `AGENTS.md`. If it doesn't, run `agentsmd-author` first — this skill never creates or edits `AGENTS.md` itself.
-
-## Usage
-
-```
-/provider-adapter-author
-```
-
-Provide the path to the provider-specific file to convert (and the target repo root, if not inferable). Can be invoked directly, or composed into by `agentsmd-author` when it detects an existing provider file with content overlapping AGENTS.md.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Skill instructions for agents |
-| `references/sources.md` | Provenance record — the in-repo ADR precedent this skill's design is modeled on |
-| `scripts/validate-adapter.sh` | Self-check gate: reference to AGENTS.md present, no excessive duplication, adapter stays thin |
-| `scripts/README.md` | Directory documentation for `scripts/` |
-| `tests/README.md` | (source-only) Bats test dependency and run instructions |
-| `tests/validate-adapter.bats` | (source-only) Bats test suite for `scripts/validate-adapter.sh` |
-
-Rows marked **(source-only)** exist in the authoring source (`.apm/skills/provider-adapter-author/`)
-but are not present in an installed plugin: `scripts/sync-plugin-content.sh` strips
-`<category>/<name>/tests` when it generates the flat mirror, because these are dev-time fixtures no
-plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install.

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

@@ -1,54 +0,0 @@
----
-name: provider-adapter-author
-description: >
-  Use when the user wants to convert a provider-specific AI instruction file
-  (CLAUDE.md, .cursor/rules/*.mdc, copilot-instructions.md, etc.) into a
-  thin adapter that defers to a repo's AGENTS.md — e.g. "reduce duplication
-  between CLAUDE.md and AGENTS.md", "make CLAUDE.md just import AGENTS.md"
-  — even if the pattern isn't named explicitly. Also invoke when
-  agentsmd-author detects an existing provider file overlapping with
-  AGENTS.md it just wrote. Detects redundant content in a provider file
-  relative to AGENTS.md and rewrites it down to a minimal reference (an
-  `@AGENTS.md`-style import where supported, or a text pointer otherwise)
-  plus genuinely provider-specific additions. Self-validates via a bundled
-  deterministic script before finishing. Do not use to write or audit
-  AGENTS.md itself — use agentsmd-author or agentsmd-audit.
-allowed-tools: Bash Read Edit Write
-metadata:
-  category: docs
-  source_keys:
-    - adr-0002-0003-two-tier-claude-md
-  version: "0.1.0"
----
-
-## Gotchas
-
-- Not every provider supports cross-file imports. Claude Code does — a `CLAUDE.md` can consist of nothing but one or more `@path` lines (e.g. `@AGENTS.md`), with no other content required. Cursor's `.cursor/rules/*.mdc` and GitHub Copilot's `copilot-instructions.md` have no native import mechanism as of current tooling — for those, "thin" means a short text pointer to AGENTS.md plus only what that tool actually needs, not a literal import line. Pass `--no-import-syntax` to `scripts/validate-adapter.sh` for these providers.
-- This skill never creates or edits `AGENTS.md` itself. If the target repo has no `AGENTS.md` yet, stop and point the user to `agentsmd-author` first — there's nothing to adapt to.
-- Only strip content from the provider file that's genuinely redundant with AGENTS.md. Provider-specific material (IDE settings, tool-only syntax, model-specific instructions) stays — the goal is thin, not empty.
-- Works standalone or composed-into by `agentsmd-author` — behave identically either way; don't assume a caller skill exists.
-
-## Step 1 — Detect
-
-Look for known provider instruction files in the target repo: `CLAUDE.md` (repo root, and any deployed copies), `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, and similar tool-specific files. Confirm `AGENTS.md` exists at the repo root — if not, stop and tell the user to run `agentsmd-author` first.
-
-## Step 2 — Diff and rewrite
-
-Read the provider file and `AGENTS.md` side by side. Separate the provider file's content into two buckets: lines that restate what `AGENTS.md` already owns (universal rules, conventions, project overview) versus lines that are genuinely provider-specific (tool syntax, IDE behavior, model-specific instructions). Rewrite the provider file:
-
-- **Providers with import syntax** (Claude Code): replace the redundant bucket with an `@AGENTS.md` (or correct relative path) import line, keep the provider-specific bucket below it.
-- **Providers without import syntax** (Cursor, Copilot, etc.): replace the redundant bucket with a short pointer sentence mentioning `AGENTS.md`, keep the provider-specific bucket.
-
-## Step 3 — Self-validate
-
-Run the bundled check before finishing — this is the skill's own closeout gate; there is no separate paired audit skill for this concern:
-
-```bash
-bash scripts/validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
-```
-
-Fix any `FAIL` and re-run until it exits `0`.
-
-## Step 4 — Report
-
-State which file was converted, what was removed versus kept, and the validator's final result.

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

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

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

@@ -1,9 +0,0 @@
-# scripts/
-
-Deterministic self-check this skill shells out to instead of relying on LLM judgment for a mechanical check.
-
-| File | Purpose |
-|------|---------|
-| `validate-adapter.sh` | Checks a rewritten provider file (CLAUDE.md, etc.) has a reference to AGENTS.md, doesn't duplicate its content, and stays under a thin-file line threshold |
-
-Takes `<adapter-file> <agents-md-file>`, with optional `--no-import-syntax` and `--max-lines N` flags. Prints `FAIL` findings to stdout and exits non-zero on any failure.

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

@@ -1,141 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-usage() {
-  cat <<EOF
-Usage: validate-adapter.sh [--no-import-syntax] [--max-lines N] <adapter-file> <agents-md-file>
-
-Self-check gate for provider-adapter-author. Checks that a rewritten
-provider-specific instruction file (CLAUDE.md, .cursor/rules/*.mdc,
-copilot-instructions.md, etc.) is actually a thin adapter over AGENTS.md,
-not a duplicate copy of it.
-
-Arguments:
-  adapter-file     Path to the provider-specific file to check.
-  agents-md-file   Path to the AGENTS.md file it should defer to.
-
-Options:
-  --no-import-syntax  The target provider has no native cross-file import
-                       mechanism. Accept a plain-text pointer mention of
-                       "AGENTS.md" instead of requiring an @import-style line.
-  --max-lines N        Max non-blank lines allowed in the adapter file before
-                       it's considered no longer "thin". Default: 60.
-  --help, -h           Show this help and exit 0.
-
-Exit codes:
-  0  Adapter file passes all checks
-  1  One or more checks failed (empty file, no reference to AGENTS.md,
-     excessive duplication, or file too long)
-EOF
-}
-
-NO_IMPORT_SYNTAX=0
-MAX_LINES=60
-ARGS=()
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    --no-import-syntax)
-      NO_IMPORT_SYNTAX=1
-      shift
-      ;;
-    --max-lines)
-      MAX_LINES="${2:-}"
-      shift 2
-      ;;
-    *)
-      ARGS+=("$1")
-      shift
-      ;;
-  esac
-done
-
-if [[ ${#ARGS[@]} -lt 2 ]]; then
-  echo "Error: adapter-file and agents-md-file are required." >&2
-  echo "" >&2
-  usage >&2
-  exit 1
-fi
-
-python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
-import sys
-import os
-import re
-
-adapter_path, agents_md_path, no_import_syntax, max_lines = sys.argv[1:5]
-no_import_syntax = no_import_syntax == "1"
-max_lines = int(max_lines)
-
-if not os.path.isfile(adapter_path):
-    print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
-    sys.exit(1)
-if not os.path.isfile(agents_md_path):
-    print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
-    sys.exit(1)
-
-with open(adapter_path, encoding="utf-8", errors="replace") as f:
-    adapter_content = f.read()
-with open(agents_md_path, encoding="utf-8", errors="replace") as f:
-    agents_md_content = f.read()
-
-has_fail = False
-
-if not adapter_content.strip():
-    print(f"FAIL  Adapter file is empty — {adapter_path}")
-    print("      Why: An empty adapter carries no reference to AGENTS.md and no provider-specific content.")
-    print("      Fix: Add at least an import (or text pointer) to AGENTS.md.")
-    print()
-    sys.exit(1)
-
-IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
-lines = adapter_content.splitlines()
-import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
-
-if no_import_syntax:
-    has_reference = "AGENTS.md" in adapter_content
-else:
-    has_reference = bool(import_lines) or "AGENTS.md" in adapter_content
-
-if not has_reference:
-    has_fail = True
-    print(f"FAIL  Adapter has no reference to AGENTS.md — {adapter_path}")
-    if no_import_syntax:
-        print("      Why: This provider has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.")
-        print("      Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
-    else:
-        print("      Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.")
-        print("      Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.")
-    print()
-
-# --- Duplication check ---
-non_import_lines = [ln for ln in lines if not IMPORT_RE.match(ln)]
-adapter_lines = [ln.strip() for ln in non_import_lines if ln.strip()]
-agents_lines = {ln.strip() for ln in agents_md_content.splitlines() if ln.strip()}
-
-if adapter_lines:
-    overlap = sum(1 for ln in adapter_lines if ln in agents_lines)
-    ratio = overlap / len(adapter_lines)
-    if ratio > 0.3:
-        has_fail = True
-        print(f"FAIL  Adapter duplicates AGENTS.md content — {adapter_path}")
-        print(f"      Why: {ratio:.0%} of the adapter's non-import lines already appear verbatim in AGENTS.md. A thin adapter should import shared content, not restate it.")
-        print("      Fix: Remove the duplicated lines and rely on the AGENTS.md import (or pointer) instead.")
-        print()
-
-# --- Size check ---
-non_blank_count = len([ln for ln in lines if ln.strip()])
-if non_blank_count > max_lines:
-    has_fail = True
-    print(f"FAIL  Adapter is not thin — {adapter_path}")
-    print(f"      Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
-    print("      Fix: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.")
-    print()
-
-if has_fail:
-    sys.exit(1)
-sys.exit(0)
-PYTHON

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

@@ -1,28 +0,0 @@
-# tests/
-
-Test files for scripts bundled with this skill.
-
-## Dependencies
-
-Tests require [bats-support](https://github.com/bats-core/bats-support) and
-[bats-assert](https://github.com/bats-core/bats-assert). The test files load
-helpers from the repo root's `tests/test_helper/`.
-
-From the repo root:
-
-```bash
-git clone https://github.com/bats-core/bats-support tests/test_helper/bats-support
-git clone https://github.com/bats-core/bats-assert tests/test_helper/bats-assert
-```
-
-Run all tests for this skill (from the repo root):
-
-```bash
-bats plugins/core/.apm/skills/provider-adapter-author/tests/
-```
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `validate-adapter.bats` | Bats test suite for `scripts/validate-adapter.sh` |

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

@@ -1,128 +0,0 @@
-#!/usr/bin/env bats
-
-setup() {
-    REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../../../../../../" && pwd)"
-    load "$REPO_ROOT/tests/test_helper/bats-support/load"
-    load "$REPO_ROOT/tests/test_helper/bats-assert/load"
-
-    SCRIPT="$(cd "$BATS_TEST_DIRNAME/../scripts" && pwd)/validate-adapter.sh"
-    TMPDIR="$(mktemp -d)"
-    AGENTS_MD="$TMPDIR/AGENTS.md"
-    cat > "$AGENTS_MD" <<'EOF'
-# AGENTS.md
-
-## Setup commands
-- Install deps: `pnpm install`
-- Run tests: `pnpm test`
-
-## Code style
-- TypeScript strict mode, single quotes, no semicolons.
-EOF
-}
-
-teardown() {
-    rm -rf "$TMPDIR"
-}
-
-@test "fails when the adapter file is empty" {
-    ADAPTER="$TMPDIR/CLAUDE.md"
-    : > "$ADAPTER"
-    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
-    assert_failure
-    assert_output --partial "empty"
-}
-
-@test "fails when the adapter has no reference to AGENTS.md" {
-    ADAPTER="$TMPDIR/CLAUDE.md"
-    cat > "$ADAPTER" <<'EOF'
-# Claude-specific notes
-Use the internal linter before committing.
-EOF
-    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
-    assert_failure
-    assert_output --partial "no reference"
-}
-
-@test "passes a thin adapter with an @import line and provider-specific additions" {
-    ADAPTER="$TMPDIR/CLAUDE.md"
-    cat > "$ADAPTER" <<'EOF'
-@AGENTS.md
-@core/instructions/governance.md
-EOF
-    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
-    assert_success
-}
-
-@test "fails when the adapter duplicates most of AGENTS.md's content" {
-    ADAPTER="$TMPDIR/CLAUDE.md"
-    cat > "$ADAPTER" <<'EOF'
-@AGENTS.md
-
-## Setup commands
-- Install deps: `pnpm install`
-- Run tests: `pnpm test`
-
-## Code style
-- TypeScript strict mode, single quotes, no semicolons.
-EOF
-    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
-    assert_failure
-    assert_output --partial "duplicat"
-}
-
-@test "fails when the adapter exceeds the max line threshold" {
-    ADAPTER="$TMPDIR/CLAUDE.md"
-    {
-        echo "@AGENTS.md"
-        for i in $(seq 1 80); do echo "Provider-specific line $i unrelated to AGENTS.md content."; done
-    } > "$ADAPTER"
-    run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
-    assert_failure
-    assert_output --partial "thin"
-}
-
-@test "allows a custom --max-lines threshold" {
-    ADAPTER="$TMPDIR/CLAUDE.md"
-    {
-        echo "@AGENTS.md"
-        for i in $(seq 1 10); do echo "Provider-specific line $i unrelated to AGENTS.md content."; done
-    } > "$ADAPTER"
-    run bash "$SCRIPT" --max-lines 5 "$ADAPTER" "$AGENTS_MD"
-    assert_failure
-    assert_output --partial "thin"
-}
-
-@test "with --no-import-syntax, a text pointer to AGENTS.md is accepted instead of an @import line" {
-    ADAPTER="$TMPDIR/copilot-instructions.md"
-    cat > "$ADAPTER" <<'EOF'
-See AGENTS.md at the repo root for setup, style, and testing conventions.
-
-## Copilot-specific
-Prefer inline suggestions over chat for one-line edits.
-EOF
-    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
-    assert_success
-}
-
-@test "with --no-import-syntax, still fails if there is no mention of AGENTS.md at all" {
-    ADAPTER="$TMPDIR/copilot-instructions.md"
-    cat > "$ADAPTER" <<'EOF'
-## Copilot-specific
-Prefer inline suggestions over chat for one-line edits.
-EOF
-    run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
-    assert_failure
-    assert_output --partial "no reference"
-}
-
-@test "--help exits 0 and documents usage" {
-    run bash "$SCRIPT" --help
-    assert_success
-    assert_output --partial "Usage:"
-}
-
-@test "fails with a clear error when the adapter file argument is missing" {
-    run bash "$SCRIPT"
-    assert_failure
-    assert_output --partial "required"
-}

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

@@ -1,20 +1,18 @@
 {
-  "name": "core",
-  "version": "1.1.1",
-  "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
   "author": {
     "name": "Defame1297",
-    "email": "defame1297@rkdr.net",
     "url": "https://git.dev.rkdr.net/Defame1297/"
   },
-  "license": "MIT",
-  "homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
-  "repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
+  "description": "Cross-cutting utility skills for everyday AI-assisted coding \u2014 triage, diagnosis, architecture review, and session navigation.",
+  "displayName": "Core",
   "keywords": [
-    "agents-md",
-    "documentation",
-    "audit",
-    "provider-adapter",
-    "governance"
-  ]
+    "cross-cutting",
+    "triage",
+    "diagnose",
+    "architecture",
+    "debug"
+  ],
+  "license": "MIT",
+  "name": "core",
+  "version": "1.0.0"
 }

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

@@ -1,20 +0,0 @@
-{
-  "name": "core",
-  "version": "1.1.1",
-  "description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.",
-  "author": {
-    "name": "Defame1297",
-    "email": "defame1297@rkdr.net",
-    "url": "https://git.dev.rkdr.net/Defame1297/"
-  },
-  "license": "MIT",
-  "homepage": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
-  "repository": "https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core",
-  "keywords": [
-    "agents-md",
-    "documentation",
-    "audit",
-    "provider-adapter",
-    "governance"
-  ]
-}

plugins/core/README.md

@@ -1,49 +0,0 @@
-# core
-
-Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
-
-## Install
-
-**Claude Code:**
-
-```bash
-claude plugin marketplace add <owner>/<repo>
-claude plugin install core@<marketplace-name>
-```
-
-**GitHub Copilot CLI:**
-
-```bash
-copilot plugin marketplace add <owner>/<repo>
-copilot plugin install core
-```
-
-**Local (development):**
-
-```bash
-# Claude Code
-claude --plugin-dir ./plugins/core
-
-# GitHub Copilot CLI
-copilot plugin install ./plugins/core
-```
-
-## Contents
-
-| Component | Path | Description |
-|---|---|---|
-| Skills | `.apm/skills/` → `skills/` | Slash commands available after install |
-
-`.apm/` is the authoring source; `skills/` is the generated mirror plugin hosts scan (ADR-0017).
-
-## Skills
-
-| Skill | Description |
-|---|---|
-| `agentsmd-author` | Create or update a repo's AGENTS.md by exploring real build/test/lint conventions; supports nested monorepo placement and hands off to agentsmd-audit and provider-adapter-author |
-| `agentsmd-audit` | Audit a repo's AGENTS.md for embedded secrets, structural completeness, and drift; produces a findings report |
-| `provider-adapter-author` | Convert a provider-specific instruction file (CLAUDE.md, `.cursor/rules/*.mdc`, copilot-instructions.md, etc.) into a thin adapter that defers to AGENTS.md |
-
-## Author
-
-Defame1297

plugins/core/apm.yml

@@ -1,35 +0,0 @@
-name: core
-version: 1.1.1
-description: Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
-author:
-  name: Defame1297
-  email: defame1297@rkdr.net
-  url: https://git.dev.rkdr.net/Defame1297/
-license: MIT
-homepage: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core
-repository: https://git.dev.rkdr.net/Defame1297/holocron/src/branch/main/plugins/core
-keywords:
-  - agents-md
-  - documentation
-  - audit
-  - provider-adapter
-  - governance
-
-# Constrains what .apm/ may contain: instructions, skill, hybrid, or prompts
-type: skill
-
-targets:
-  - claude
-  - copilot
-  - codex
-
-# "auto" publishes the authoritative local source layout, or list explicit
-# repo paths to define the complete publication set.
-includes: auto
-
-dependencies:
-  apm: []
-  mcp: []
-devDependencies:
-  apm: []
-scripts: {}

plugins/core/hooks.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

plugins/core/plugin.json

@@ -0,0 +1,19 @@
+{
+  "author": {
+    "email": "defame1297@rkdr.net",
+    "name": "Defame1297"
+  },
+  "description": "Cross-cutting utility skills for everyday AI-assisted coding \u2014 triage, diagnosis, architecture review, and session navigation.",
+  "hooks": "hooks.json",
+  "keywords": [
+    "cross-cutting",
+    "triage",
+    "diagnose",
+    "architecture",
+    "debug"
+  ],
+  "license": "MIT",
+  "mcpServers": ".mcp.json",
+  "name": "core",
+  "version": "1.0.0"
+}

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

@@ -1,35 +0,0 @@
-# agentsmd-audit
-
-Audit a target repo's AGENTS.md file(s) for embedded secrets, structural completeness, and drift.
-
-## What it does
-
-Runs a single combined pass across every AGENTS.md file in a repo (root and any nested monorepo files): flags embedded secrets/credentials, checks structure against the agents.md common-sections checklist, and resolves referenced commands/paths against the actual repo to catch stale documentation. Outputs a compact findings report — findings only, grouped by dimension, each with Why and Fix. Never inspects provider-specific adapter files (CLAUDE.md, etc.) and never writes or fixes anything.
-
-## Usage
-
-```
-/agentsmd-audit
-```
-
-Provide the path to the repo root to audit when invoking.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | Skill instructions for agents |
-| `scripts/validate-secrets.sh` | Scans AGENTS.md files for embedded secrets, API keys, tokens, connection strings |
-| `scripts/validate-structure.sh` | Checks for empty/placeholder content, common-sections checklist, nested-vs-root duplication |
-| `scripts/validate-drift.sh` | Resolves referenced npm/make commands and file paths against the repo |
-| `references/sources.md` | Provenance record — sources that informed this skill and which files each contributed to |
-| `scripts/README.md` | Directory documentation for `scripts/` |
-| `tests/README.md` | (source-only) Bats test dependency and run instructions |
-| `tests/validate-secrets.bats` | (source-only) Bats test suite for `scripts/validate-secrets.sh` |
-| `tests/validate-structure.bats` | (source-only) Bats test suite for `scripts/validate-structure.sh` |
-| `tests/validate-drift.bats` | (source-only) Bats test suite for `scripts/validate-drift.sh` |
-
-Rows marked **(source-only)** exist in the authoring source (`.apm/skills/agentsmd-audit/`) but are
-not present in an installed plugin: `scripts/sync-plugin-content.sh` strips `<category>/<name>/tests`
-when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to
-discover (ADR-0017). Run them from a repo checkout, not from an install.