Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Compare commits

base: Defame1297:v2.0.1
Branches Tags
Defame1297:main Defame1297:docs/onedev-migration-plan Defame1297:feat/66-wire-gitea-mcp-config
Defame1297:v2.0.1 Defame1297:v2.0.0 Defame1297:v1.0.0
...
compare: Defame1297:c96ca9ca0d571b22bb6abc9cbf2b54bcd54d9d96
Branches Tags
Defame1297:main Defame1297:docs/onedev-migration-plan Defame1297:feat/66-wire-gitea-mcp-config
Defame1297:v2.0.1 Defame1297:v2.0.0 Defame1297:v1.0.0

55 Commits
v2.0.1 ... c96ca9ca0d

Author SHA1 Message Date
Defame1297
c96ca9ca0d fix: remove the obsidian MCP server and the unreadable .mcp.json files 
718c79a deleted every per-plugin .claude-plugin/plugin.json, which
reclassified each package from a marketplace plugin to a plain apm
package. That silently broke MCP propagation: apm_cli/deps/plugin_parser.py
maps a plugin-root .mcp.json into .apm/.mcp.json, and that code path runs
only for marketplace plugins. With no manifest, apm never reads the file.

Reproduced on ref-pinned consumer clones: at the parent commit a consumer
receives the obsidian server, at HEAD it receives none, and on upgrade apm
prints "Removed stale MCP server 'obsidian' from .mcp.json". This repo
consumes its own plugins through apm (ADR-0018), so the tracked root
.mcp.json would have been rewritten to an empty server map on the next
lock re-resolve -- silent tool loss plus unexplained working-tree drift.

The server is removed entirely rather than relocated to .apm/. It was
already a standing question (SIMPLIFICATION-AUDIT finding 37, deferred on
2026-09-13 pending confirmation, now confirmed), and plugins/bin/apm.yml
declares dependencies.mcp: [] -- apm's supported mechanism was never used.
All seven .mcp.json files go; the root one is apm-generated output and is
now gitignored alongside the other install artifacts.

ADR-0011's deferred ".mcp.json wiring gap" is moot twice over -- the
install route it blocked no longer exists and neither does the file --
and ADR-0018 records why it lost its only worked example of MCP
propagation. apm.lock.yaml still carries the server; it clears on the
first apm update after this reaches the default branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-14 18:09:17 +00:00
Defame1297
061bb3d5b4 docs: correct the apm-only change after a five-agent review 
A five-agent review of 718c79a and d2480b8 found no skill, agent or hook
regressions (39 skills before and after) and confirmed both hook removals
are genuinely moot -- verified against the tree, not taken on the commit's
word. It did find one functional regression (fixed separately) and this
documentation drift.

Counting errors, all from a git pathspec `*` crossing `/`:
  - 17 .bats files shipped to consumers is really 10; 17 counted tracked
    paths merely containing /tests/, one of them a template asset
  - "roughly 88s off every push" is ~92.4s; 88 omitted validate-plugins
  - "roughly 70% of each plugin remains live" holds only for kyberforge;
    the real spread is 44.3% (bin) to 70.6%, now a table
  - the pre-push enforcement row was half-corrected: 33 entries stood
    unstruck (now 27) and 14 -> 11 switched counting basis mid-sentence
  - the root .claude-plugin/plugin.json was described as "kept"; it has
    never been tracked

gates.md said "Ten hooks" above a nine-row table (11 was decremented for
one removal, not two), and "both need the claude CLI" for one remaining
validator. Its pretty-format-json exclude rationale claimed six
alternations expanding to sixteen files in a passage headed "Mind which
number you are quoting" -- four alternations, two live files; the two
dead ones are dropped from the pattern. check-useless-excludes could not
catch this: it only flags an exclude matching nothing at all.

ADR-0024 cited ADR-0006 for a patch-bump rule it does not contain and
which ADR-0015 explicitly retired; stated apm's marketplace probe order
backwards (.claude-plugin/ is the last candidate, not the first, so the
earlier .github/plugin/ deletion only demoted resolution); undercounted
apm's skill-deploying targets as seven when there are fifteen; and never
recorded that validate-plugins was removed. The symlink hedge is resolved:
apm_cli/security/gate.py's ignore_non_content() drops symlinks silently on
deploy while apm_modules/ materialization dereferences them, so content
survives that far and vanishes at install. Accepted with no replacement
guard, per decision -- kyberforge/docs/hooks.md previously asserted a
guard that had been deleted with its script.

Four plugin READMEs still advertised `claude plugin install`; ADRs 0001,
0006, 0013, 0014, 0015 and 0019 described deleted machinery in the present
tense, 0019 most consequentially as the live justification for the
SessionStart hook's .apm/ path. CONTEXT.md's "apm package" entry forbade
"plugin" while using it in its own body, and "Output profile" lost the
antecedent for "one catalogue serves both".

run-tests.sh gains the .claude/skills/ exclusion run-bats.sh already had.
Latent today -- no test-*.sh lives under any .apm/skills/*/tests/ -- but
apm now deploys those directories, so one would be discovered twice.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-14 18:09:03 +00:00
Defame1297
d2480b8191 docs: record the apm-only decision and its carried-forward consequences 
Marks §8's install-path question answered and finding 7 superseded-then-done
(deleted rather than shrunk, since the mirror it guarded is gone). Corrects
two stale figures: the mirror was 213 files / 20,061 lines, not 263 / ~22,000,
and the pre-push stage now reports 11 hooks, not 14.

Adds §9 for what the decision carries forward rather than resolves: the two
accepted residuals, the self-containment negative result (findings 14/15 still
need skill merges, not file sharing), and the now-unreported symlink drop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-14 17:02:35 +00:00
Defame1297
718c79af70 chore: drop the flat content mirror and native install support (ADR-0024) 
apm becomes the only supported install path. The flat mirror at each plugin
root existed solely so Claude Code's native `claude plugin install` could
convention-scan plugin content (ADR-0017). With no native consumers, it cost
~20,000 tracked lines plus ~2,100 lines of sync tooling and ~88s of every
push to guard content apm never reads — and its only automated gate,
`claude plugin validate --strict`, passes on a plugin with zero content, so
it could not detect the defect ADR-0017 was created to fix.

Removes the mirror (213 files), the six per-plugin manifest pairs,
sync-plugin-content.sh, its 1,289-line test, the orphaned
marketplace-plugins.sh, and the check-plugin-content-sync and
validate-plugins pre-push hooks. The root `marketplace:` block and
.claude-plugin/ catalogue stay: apm's own marketplace consumers read that
same file, so `<name>@holocron` short names keep working.

tests/run-bats.sh now excludes .claude/skills/. apm installs from .apm/,
which carries the tests/ dirs the mirror stripped, so deployed .bats files
would otherwise be discovered and double-run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-14 16:59:42 +00:00
Defame1297
0dffff3c21 chore: drop redundant apm-marketplace-check and Copilot marketplace mirror (findings 1, 2) 
apm-marketplace-check checked network reachability of remote marketplace
refs, but finding 35 already removed the only remote package entry, so
every marketplace.packages[] source is local and the hook is pure
overlap with apm-pack-check-clean. apm-audit-ci was re-examined and kept
as-is -- its pre-commit-config.yaml comment already carries a dated,
verified justification the audit had missed.

check-marketplace-mirror-sync guarded .github/plugin/marketplace.json
against drift from .claude-plugin/marketplace.json. Verified against
current GitHub Copilot CLI docs: Copilot's marketplace discovery already
falls back through .github/plugin/marketplace.json to
.claude-plugin/marketplace.json, which this repo generates anyway -- the
dedicated mirror bought a discovery-order preference, not a capability.
Deleted the mirror file, its sync script, its test, and the hook.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-14 11:35:44 +00:00
Defame1297
afa7187d33 docs: dedupe .apm/-mirror and apm.lock/SessionStart restatements (finding 29) 
README and AGENTS.md each fully restated the "edit .apm/, never the
mirror" rule and the apm.lock/SessionStart mechanism instead of linking
to their canonical sources (architecture.md, ADR-0019).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-14 07:15:19 +00:00
Defame1297
e2e957efdd docs: record subagent outcomes for findings 2, 31, 38 
Three findings from the simplification audit were independently
re-verified before execution, corrected, then implemented by
subagents:

- Finding 2 (check-executables-allow-sync): the audit's "drop it"
  option was found unsafe (ADR-0019 calls this failure mode silent,
  not "visible and recoverable" as claimed); shrunk instead of
  deleted, 231 -> 222 lines.
- Finding 31 (CONTEXT.md): "most terms unused by skills" was found
  overstated (13 of 28 are model-facing must-keeps); cut only the
  9 confirmed true orphans, 28 -> 19 terms. Also de-referenced one
  dangling pointer to a deleted term in the Flagged-ambiguities
  section.
- Finding 38 (pc-author/pc-run): line count was found overstated
  (598 actual vs. 689 claimed); trimmed the two generic reference
  files by 60 lines while preserving house-specific content.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 21:03:58 +00:00
Defame1297
124ce6eaa9 docs(context): remove unreferenced glossary terms (finding 31) 
Corrected scope for audit finding 31: the audit's claim that most of
CONTEXT.md's 28 terms are unused was overstated (13 are must-keep,
referenced in model-facing skill references/*.md files). This cuts only
the 9 confirmed true orphans, independently re-verified by grep across
plugins/*/.apm/, docs/, scripts/, and tests/ with zero hits outside
CONTEXT.md (two had a single incidental ADR mention that doesn't
constitute a dependency): Content mirror, apm-consumed install, Vale
audit prefilter, Vacuous green, Management Application, Sycophancy,
HOTL, Preload tax, Skill context contract.

Term count: 28 -> 19. Also removed two Relationships bullets that
existed solely to relate now-deleted terms (Preload tax/Skill context
contract, and HITL/HOTL/Sycophancy), leaving HITL's own entry to stand
alone. The Preload tax entry's self-contradiction (quoting two dated
character counts immediately after saying not to quote either) is
moot since the whole entry is removed. Example dialogue and flagged
ambiguities sections left untouched per scope, including one now-stale
bold reference to "Preload tax" in flagged ambiguities.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 21:02:41 +00:00
Defame1297
1b01e25f3b refactor(hooks): shrink check-executables-allow-sync (finding 2) 
Trim the two comment blocks that re-derived ADR-0019's argument in full
(apm's exact-dict-lookup key matching, and why the PyYAML fallback is not
a hard requirement) down to a short summary plus a pointer at ADR-0019,
which already carries that reasoning verbatim. 231 -> 222 lines.

The hook is kept, not deleted, per the audit's own corrected scope: the
"or drop it" option in SIMPLIFICATION-AUDIT.md finding #2 is off the
table because ADR-0019's Consequences section and the script's own
header both call this failure mode silent, and the ADR says a
silent-staleness failure here is strictly worse than the duplication
this repo's other gates catch.

The dual-reader design (PyYAML preferred, hand-rolled shape-scan
fallback) is also kept as-is: it exists specifically so a missing
python3/PyYAML can't silently skip the check or block every push, which
is exactly the loud-failure guarantee this finding must not weaken. No
genuine redundancy was found in the parsing logic, the per-branch
Why/Fix error messages (each tied to a specific test), or the test
matrix (which verifies the two readers agree across every failure mode)
without cutting something load-bearing -- so those are untouched, and
tests/test-check-executables-allow-sync.sh needed no changes since
script behavior and output are byte-identical.

All 23 tests in tests/test-check-executables-allow-sync.sh pass, and
`pre-commit run check-executables-allow-sync --all-files --hook-stage
pre-push` passes against the real repo state.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 20:58:41 +00:00
Defame1297
a622200868 docs(pc-skills): trim generic pre-commit boilerplate (finding 38) 
Collapse the per-language hook tables in pc-author's hooks-by-language.md
into one shared-repo table plus an "other repos" table, dropping the
repeated repo/rev/rationale text that just restated what each hook does.
128 -> 92 lines. Kept both "Unverified — not in research corpus" flags
and the rev-freshness caveat.

Remove the generic SSH/proxy CI failure sections, the shellcheck SC-code
listing, and compress the generic validate-config schema-error bullets
in pc-run's failure-patterns.md, all of which just restated
pre-commit.com's own docs. 133 -> 109 lines. Kept the rtk-prefixed
re-stage/recommit fix (ADR-0023), the "do NOT reach for
`pre-commit install -f`" warning, and both gitleaks/shellcheck
not-sourced-from-corpus notes.

Combined cut: 60 lines. Flat mirrors regenerated via
scripts/sync-plugin-content.sh and verified byte-identical
(--check exits 0); no plugin.json drift.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 20:54:17 +00:00
Defame1297
af80d27b9b docs(adr): flag stale codex-profile mention in ADR-0021 context 
The Context section still described .agents/plugins/marketplace.json
(apm's codex profile) as an existing, unaffected generated file. It
was removed today in 568ca74; point to the removal instead of leaving
the text describing a file that no longer exists.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 20:30:30 +00:00
Defame1297
14f327409e docs: record subagent outcomes for findings 3, 8, 19, 35, 37 
Two landed (8 partial, 35 in full); three declined after investigation
found the audit's premise didn't hold on inspection of current code.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 10:18:01 +00:00
Defame1297
e21a5fb24c chore: merge dead-distribution-surface cleanup (finding 35) 
Removes the codex marketplace output profile and the mattpocock-skills
remote package entry per SIMPLIFICATION-AUDIT.md finding 35.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 10:17:03 +00:00
Defame1297
568ca749f0 chore: remove codex output profile and mattpocock-skills remote entry 
Neither has a real consumer: Codex is not a supported target, and
mattpocock-skills was the sole remote marketplace.packages[] entry
forcing apm-marketplace-check and apm-pack-check-clean to git
ls-remote on every push. Removing both drops .agents/plugins/marketplace.json
(the codex output artifact) and makes every pre-push hook resolve
fully offline. Updates README, AGENTS.md, gates.md, architecture.md,
and ADR-0015/ADR-0021 to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 10:16:02 +00:00
Defame1297
a35f5e889e docs(gates): trim two stale post-mortem passages from gates.md 
Cut the "Verified fixed" reproduction paragraph carrying explicitly
stale pre-retrofit figures, and condensed the "Current retrofit
status" section's issue-#99 process narrative to the current-state
facts and the commands to check them.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-13 10:13:57 +00:00
Defame1297
cc2553d5f6 docs: fix two more stale commit hashes in simplification audit 
Findings 13 and 21 cited b4c3d5e and 4bbd8a5, both dangling (not
reachable from HEAD) -- an amend after ace2d66 changed the hashes of
the underlying commits to 6cfc357 and f5e4d0d without updating the
self-reference. Corrected both.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 22:58:07 +00:00
Defame1297
60d3005e67 docs(git): remove stale check-manifests/skill-frontmatter examples 
f11b645 and bde9f7f swept check-manifests and skill-frontmatter
references left over from e647f14 and c8a7c9e, but missed two worked
examples in this vendored pre-commit research doc: a "Validate a
generated file" hook naming the deleted scripts/check-manifests.sh,
and a "SKILL.md frontmatter validation (inline bash, as used in this
repo)" example for the skill-frontmatter hook, folded into
skill-size-check.sh in c8a7c9e.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 22:56:43 +00:00
Defame1297
bde9f7fdd8 chore: fix stale skill-frontmatter and check-manifests references 
c8a7c9e folded the skill-frontmatter hook into skill-size-check but
left validate.sh's FAIL messages, skill-author's create.md, and the
skill template's frontmatter comment naming the deleted hook as the
enforcer -- misleading for anyone tracing a FAIL back to the gate that
raises it.

f11b645 swept check-manifests references but missed a hand-authored
"Local hooks in this repo" table in the git plugin's vendored
pre-commit research doc, which still listed both check-manifests and
skill-frontmatter as active hooks.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 22:13:10 +00:00
Defame1297
f11b6455ce chore: remove stale check-manifests references left by e647f14 
e647f14 deleted scripts/check-manifests.sh but missed three live files
that still named it: the apm-marketplace-check hook description in
.pre-commit-config.yaml, and comments in sync-plugin-content.sh and
lib/marketplace-plugins.sh explaining design decisions by pointing at
a script that no longer exists.

Also deletes list_marketplace_remote_plugin_names from
marketplace-plugins.sh — its only caller was check-manifests.sh, so
it's been dead code since that commit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 21:50:46 +00:00
Defame1297
ace2d66343 docs: fix stale commit hashes in simplification audit 
The Done blockquotes for findings 1, 4, and 6 cited a pre-amend hash
of their own commit (a commit can't know its final hash before it's
made). Point them at the actual final hashes: e647f14, c8a7c9e,
5f9f2b3.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 20:39:04 +00:00
Defame1297
5f9f2b33b0 chore: delete prose-grep governance/instructions tests 
test-governance-layer.sh and test-instructions-and-docs.sh (583 lines
combined) grep markdown files for expected phrases, including a
one-shot "issue 0015 refactor incomplete" assertion made permanent and
an assertion that docs/notes/ exists. Neither is referenced by any
other script or doc.

check-apm-agents-valid.sh is left untouched — it is tied to the
separate, out-of-scope skill-merge finding 14.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 20:01:18 +00:00
Defame1297
c8a7c9ea87 chore: fold skill-frontmatter into skill-size-check 
skill-frontmatter was a 62-line bash script inlined in
.pre-commit-config.yaml, re-parsing SKILL.md frontmatter with grep and
awk to check for name/description/metadata.version fields.
skill-size-check.sh already parses the same frontmatter block with
PyYAML for its ADR-0020 checks, so the two checks belonged in one
script.

Adds a ~20-line required-frontmatter check (name, description,
metadata.version as three-part semver) to scripts/skill-size-check.sh.
Removes the inline skill-frontmatter hook from .pre-commit-config.yaml
and deletes tests/test-skill-frontmatter.sh (366 lines). Removes the
79-line "the other hook on that scope" discussion from
docs/spec/gates.md and its now-dangling cross-reference, replacing
both with a one-line note of the fold, and updates the pre-push hook
counts there.

Updates fixture builders in test-skill-size-check.sh,
test-adr0020-body-checks.sh, test-adr0020-targets.sh,
test-adr0020-differential.sh, and test-vale-hooks-consumer.sh to carry
valid metadata.version so the new check doesn't spuriously fail
existing fixtures that predate it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 20:00:43 +00:00
Defame1297
e647f14535 chore: delete the check-manifests pre-commit hook 
Six pre-push hooks were validating overlapping sets of the same
manifests. check-manifests (marketplace.json/plugin.json path checks)
is redundant with validate-plugins (claude plugin validate) and
apm-pack-check-clean, which already cover the same ground.

Deletes the check-manifests hook entry, scripts/check-manifests.sh
(282 lines), and tests/test-check-manifests.sh (771 lines).
scripts/lib/marketplace-plugins.sh is kept — it is still sourced by
sync-plugin-content.sh. Updates the now-stale check-manifests.sh
mentions and hook counts in README.md and docs/spec/gates.md.

The apm-audit-ci and apm-marketplace-check hooks named in the same
finding are left untouched — the audit flags them as needing a
separate decision.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 19:59:33 +00:00
Defame1297
6cfc3577e2 docs: trim repeated boilerplate in git, gitea, and bin skills 
Finding 13: five blocks of near-identical wording were repeated across
skills within a plugin — the gitea "resolve owner and repo" step (5
skills), the 404-masks-403 note (6 files), the manual pagination
explanation (8 files), the git plugin's main/master force-push refusal
(7 files, some with multiple internal restatements), and the bin
skills' domain-glossary/ADR paragraph (5 skills). Tightened each
instance in place — same meaning, fewer words — rather than extracting
to a shared file, which ADR-0014's one-file-per-skill install
constraint rules out. Left the three git skills' structured-result
JSON shapes alone (coupled to the separate, out-of-scope git-orchestrate
merge candidate, finding 19).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 19:48:31 +00:00
Defame1297
f5e4d0d082 docs(git): delete unused git plugin config file and its read steps 
Finding 21: `config.example.json` (and the never-tracked
`.claude/plugins/git/config.json` it documented) was read by
git-orchestrate and git-branches but written by nothing, and the
default-inference fallback (GitHub Flow, with Gitflow inferred from a
`develop`/`release/*` branch) already covered the no-config case.
Removed the config-read step from both, updated git-workflow's
description of the orchestrator to match, dropped the now-dangling
`applied_config` field from git-orchestrate's output shape, and
deleted the config file and its stale example reference in
docs/spec/architecture.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 19:46:28 +00:00
Defame1297
198eafd790 docs: mark simplification-audit findings 10, 12, 30 resolved 
Checkbox and strikethrough findings 10, 12, and 30, each pointing at
the commit that implemented it (edcc57c, 629320b). Record the decision
on findings 9 and 26 (delete docs/research and docs/notes): declined,
those docs are kept on purpose as context for work sourced from them.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 18:38:40 +00:00
Defame1297
629320b8fd docs: trim stale entries from LESSONS.md 
Finding 30 of the simplification audit. 41 entries had grown to 255
lines; 10 described a write-skill / write-eval bootstrap workflow
whose skills no longer exist in this repo, and the longest entries ran
200-550 words of incident narrative for a one-line lesson.

Deleted the 10 stale entries. Kept 3 same-dated ones (RLHF defaults,
secrets-rule gap, HITL gap) whose content is unrelated to the defunct
workflow and still applies. Removed one open-work entry ("neither part
landed", about CONTEXT.md not being @import-ed at session start)
rather than filing it as a tracker issue -- not turned into an issue,
just dropped; the audit's own commit history and this repo's session
transcript carry the detail if it's wanted later. Compressed the
remaining 30 entries to roughly 60-90 words each.

255 -> 131 lines, 41 -> 30 entries.

Refs: SIMPLIFICATION-AUDIT.md finding 30

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 18:38:26 +00:00
Defame1297
edcc57c0d6 docs: trim skill READMEs and ADR/changelog narration 
Two related simplification-audit findings, bundled because they edit
some of the same skill-audit files and splitting would fragment
single-file diffs.

Finding 10: delete 48 per-skill/reference README.md files (they
restated SKILL.md in narrative form and no agent ever loads them) plus
2 scaffold templates. Drop the README criterion from skill-audit's
file-structure.md and finding-criteria.md, and the README-generation
step from skill-author's new-skill.sh; update new-skill.bats to match.
Plugin-root READMEs are kept intentionally, out of scope.

Finding 12: strip historical ADR-0020/ADR-0023 citations and
changelog-style narration from model-facing skill content across
kyberforge and git plugin skills. Delete skill-author's one-time
retrofit.md migration guide and its references. Some ADR-0023 tags
were not narration but check-rtk-prefix's required opt-out marker for
intentionally-bare git commands -- those were restored, not stripped.

Mirror re-synced and full pre-commit/pre-push suite verified green.

Refs: SIMPLIFICATION-AUDIT.md findings 10, 12

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
 2026-09-12 18:38:09 +00:00
Defame1297
9eb8bc7e48 docs: add simplification audit of hooks, tests, plugins, and prose 
Read-only analysis with 38 ranked findings, a measured pre-push baseline,
and open questions for the hand-off discussion. No repo changes proposed
are applied here.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EmiHiknxqtZPEBnW7ujgNz
 2026-09-10 20:13:16 +00:00
Defame1297
a712f2c186 Merge pull request 'docs: trim four duplicated session rules from AGENTS.md' (#134) from docs/trim-agents-md-session-rules into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/134
 2026-09-10 19:37:00 +00:00
Defame1297
2fb1036329 Merge branch 'main' into docs/trim-agents-md-session-rules 2026-09-10 19:36:34 +00:00
Defame1297
5d7c76d797 Merge pull request 'refactor(bin): move non-spec root files into references/ across four skills' (#133) from refactor/122-move-skill-root-files into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/133
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-09-10 19:36:16 +00:00
Defame1297
c613927fb4 docs: trim four duplicated session rules from AGENTS.md 
Removes the ADR-0020 gate summary, the strict test-suite rule, the
pre-push rehearsal rule, and the commit-authoring rule. Each is already
documented at its owning source: docs/spec/gates.md carries the gate
behaviour and both command invocations, README.md carries the pre-push
rehearsal, and the git plugin's own skills carry commit authoring.

AGENTS.md is meant to hold only what applies to every session, so
content with a canonical home elsewhere does not belong here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
 2026-09-10 19:35:01 +00:00
Defame1297
c75e4ef4f3 fix(bin): repoint improve-codebase-architecture README's LANGUAGE.md mention 
PR #133 renamed the skill's root-level LANGUAGE.md to references/language.md
but missed a prose mention (not a markdown link) in the overview paragraph.
Fix both the .apm/ source and its generated flat mirror.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
 2026-09-10 19:12:16 +00:00
Defame1297
4f49b2a249 refactor(bin): move non-spec root files into references/ across four skills 
grill-with-docs, improve-codebase-architecture, tdd, and triage kept
non-spec markdown files at their skill root, in violation of
skill-audit's file-structure.md rule (only SKILL.md/README.md belong
at the root; everything else lives in scripts/, references/, assets/
or tests/). A root-level file is invisible to the ADR-0020
dangling-reference gate, which only resolves unqualified
`references/...` pointers.

- Moved and renamed to lowercase-kebab-case under references/:
  grill-with-docs (ADR-FORMAT.md, CONTEXT-FORMAT.md),
  improve-codebase-architecture (DEEPENING.md, INTERFACE-DESIGN.md,
  LANGUAGE.md), tdd (five files, casing was already fine), triage
  (AGENT-BRIEF.md, OUT-OF-SCOPE.md).
- Updated every in-skill link to the new references/ paths, including
  link text that still showed the old uppercase filenames.
- Fixed improve-codebase-architecture/SKILL.md's cross-skill citation
  of grill-with-docs's two files to the sanctioned possessive form
  with the references/ segment included.
- Updated all four skills' README.md file tables to match.
- Regenerated the flat content mirror via
  scripts/sync-plugin-content.sh --all.

Fixes #122.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
 2026-09-09 19:59:02 +00:00
Defame1297
058fb5b748 Merge pull request 'fix(tests): pin test-check-rtk-prefix.sh's pre-#113 corpus to a fixed SHA' (#131) from fix/rtk-prefix-test-pinned-ref into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/131
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-09-09 19:43:05 +00:00
Defame1297
29eefe7f70 chore: refresh apm.lock.yaml to match the deployed install state 
The kyberforge SessionStart hook re-resolves dependencies against the
holocron remote on every session start, which routinely leaves
apm.lock.yaml behind the actually-deployed .claude/ content (documented
in AGENTS.md). That mismatch fails apm-audit-ci and apm-pack-check-clean
at the pre-push gate regardless of what's actually being pushed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
 2026-09-09 19:35:41 +00:00
Defame1297
6ba29b696c fix(tests): pin test-check-rtk-prefix.sh's pre-#113 corpus to a fixed SHA 
The "pre-#113 corpus on main trips the gate" case reconstructed the
historical (pre-sweep) corpus from the live `main` ref. `main` is the
moving integration branch, and the #113 fix (ed8c99e) landed back onto
it — so the moment that fix merged, `main` stopped containing the bare
`git remote get-url origin` drift the case exists to catch, and the
assertion "the gate should fail on this corpus" silently flipped to
false. This blocked `git push` on every branch via the run-tests
pre-push hook, unrelated to whatever was actually being pushed.

Pin to 598a7c3, the last commit before ed8c99e where
gitea-issues/SKILL.md still had the unprefixed call. A specific commit
SHA is immutable, unlike `main`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDj6F7SPXzh3FtPN78dZ88
 2026-09-09 19:23:38 +00:00
Defame1297
b7bec71b8f Merge pull request 'Close four small ADR-0020-retrofit follow-ups (#125, #127, #113, #118)' (#130) from fix/adr0020-followups into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/130
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-09-09 18:23:00 +00:00
Defame1297
0f2bb242ad chore(plugins): sync generated content mirrors 
Regenerates `plugins/*/skills`, `plugins/*/agents`, both per-plugin `plugin.json` manifests and the
two marketplace mirrors from `.apm/` per ADR-0017, via `scripts/sync-plugin-content.sh --all`.

The manifests matter beyond tidiness here: `plugin.json` carries the plugin version and wins over
the marketplace entry at install time (calculatePluginVersion precedence). Until this ran, the patch
bumps in the preceding commit were inert for anyone installing these plugins.

ADR: 0017
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-09 05:15:53 +00:00
Defame1297
a3e721e937 docs: retire the META.md guidance ADR-0022 overruled, bump touched plugins 
Why: ADR-0022 made `metadata.version` mandatory in SKILL.md frontmatter, but three documents still
instructed the opposite — that `version:`, `source:`, `references:` and `when:` belong in a separate
META.md. That recommendation was never implemented: META.md exists exactly once in this repo, inside
a vendored third-party research example, and all 39 skills now contradict it. A stale instruction
that outranks nothing is worse than no instruction, because an author following it undoes the ADR.

Implementation notes:
- Two LESSONS.md entries deleted outright — their entire payload was the rejected fix. Two kept and
  rewritten: the copy-fill entry loses only its META-TEMPLATE clause, and the `model:` entry keeps
  the provider-extension fact and the invocation-time boundary rule, which stand on their own.
- One factual error corrected in passing: the `extracted` slug entry claimed provenance is recorded
  in META.md. It lives in `references/sources.md` keyed by `source_keys:`, verified against
  validate-provenance.sh.
- Both docs/notes files gain `metadata.version` in their required-field lists. Deleting the stale
  paragraph while leaving those lists silent would have re-created the gap.
- `bin/write-docs` carried `metadata.version: "1.0"` — the only non-semver value in the corpus, and
  the result of relocating its old top-level `version:` without normalising it. Now `1.0.0`.
  ADR-0022 records the relocation it previously omitted, which issue #127 had asked it to decide.

Impact: patch bumps for the four plugins whose `.apm/` content changed — bin, git, gitea,
kyberforge. core and lint are untouched and stay put. Root apm.yml's `executables.allow` key and
marketplace package versions move in lockstep; the marketplace release version is unchanged.

Refs: #127
ADR: 0022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-09 05:15:41 +00:00
Defame1297
3811f5481b fix(kyberforge): unblock the scaffold and finish the #125 and ADR-0022 edits 
Three related half-applied changes from #130, each leaving the corpus in a state its own
documentation contradicts.

Why:
- `assets/templates/SKILL.md` shipped `metadata:` fully commented out, and `new-skill.sh` only
  substitutes SKILL_NAME. Every scaffolded skill therefore lacked the `metadata.version` ADR-0022
  made mandatory and was blocked at first commit by the very hook this PR added. The commented
  example also read `"1.0"` — neither the `0.1.0` new-skill seed nor valid semver.
- `agent-audit/references/scope-project-user.md` still joined `disable-model-invocation` and
  `user-invocable` with a slash — #125's defect verbatim — while pointing the reader at the file
  this PR had just corrected to say the opposite.
- ADR-0022 required the "when present" bump conditional dropped and `metadata.version` moved into
  create.md's required list. It was dropped from SKILL.md but left in README.md, and the field was
  edited in place under a heading that still authorises removing it entirely.

Implementation notes:
- The template emits `metadata: version: "0.1.0"` live, captioned as required, with the optional
  keys left commented. `new-skill.bats` gains a case asserting a live key and three-part semver, so
  this cannot regress.
- `description-quality.md` now asserts only what the vendored Copilot research supports: two fields
  with opposite defaults, and the retired `infer` replaced by the pair rather than by either alone.
  The unsupported negative it previously stated as fact is gone.
- The `1.0.0` retrofit seed is stated in improve.md and retrofit.md, which the retrofit flow
  actually reads — create.md, where it lived, is unreachable from that path. The compression item
  moved out of the file-churn checklist, whose preamble excluded the wording-only change it covers.
- Executable git commands in these three skills now carry the ADR-0023 rtk prefix.

Refs: #125, #127
ADR: 0022, 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-09 05:15:23 +00:00
Defame1297
175ea89c0a fix(skill-audit): make check 9 reachable, wrap-safe and never silently skipped 
Check 9 shipped in #130 to close #118, but three defects meant it could not do the job it was
added for.

Why:
- It is INFO-only, so it always exits 0 — and SKILL.md graded exit 0 "a genuine pass" and said the
  script "prints nothing on success". Every check-9 INFO was discarded before it reached a report,
  behind three further doors that only opened on a non-zero exit.
- `parse_field_raw()` matched `(.+)`, which does not span newlines, so only the first physical line
  of a wrapped value was compared. Rewriting only the continuation line of a wrapped Description
  from a hedge to a confident claim produced no finding at all — verbatim the regression #118 was
  filed about. The bullet branch had the same shape: a wrapped bullet broke the loop and dropped
  every later entry.
- A `git show` failure at the base ref was treated as "creation, nothing to flag" and skipped the
  whole skill with no output, collapsing "absent at that ref" with "not tracked under that name".
  A gitignored `.claude/skills/` copy reported clean while the authoring path reported four changed
  claims. The script's own usage text promises this is "never a silent skip".

Implementation notes:
- Exit-code guidance re-keyed on output as well as code: 0-and-silent passes, 0-with-output is
  INFO-only findings, 1 is FAILs, 2 never ran.
- `parse_field_raw()` is line-based and joins continuation lines; `normalize_field_text()`'s
  docstring is now true rather than aspirational. A reorder deliberately fires: the two fields share
  one parser, and order-insensitivity would mean splitting a prose Description on commas.
- The discarded `show_err` is now surfaced as one whole-check INFO naming both readings.
- `--base-ref=` given empty now beats the env var, as the usage text always claimed.

`validate.sh` gains an ADR-0022 `metadata.version` check at FAIL tier, because any lower tier lets
skill-author Step 4 report done on a file the commit gate then refuses. Its `read` heuristic now
skips here-doc bodies — reflowing the one offending line would have cleared the finding and left
the cause, since every usage() heredoc is one wrap from putting the English verb in column 0.

Impact: provenance tests 73 -> 82, validate tests 64 -> 72. Test 72 previously deleted origin/main
before asserting the override, so it proved the flag works with no default rather than that it beats
one; it now moves origin/main forward first.

Refs: #118
ADR: 0022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-09 05:15:05 +00:00
Defame1297
ed8c99efbd fix(git): stop prefixing rtk where it rewrites the output skills parse 
The #113 sweep rested on CLAUDE.md's premise that rtk either filters or passes through unchanged,
so prefixing is always safe. Measured against rtk 0.42.4, that premise is false for several of the
commands the sweep prefixed, and two skills were left giving wrong answers silently.

Why:
- `rtk git worktree list --porcelain -z` discards both flags and renders its own format. The
  `locked`/`lock_reason` fields git-worktrees Step 2 must emit are absent entirely, and paths under
  $HOME are abbreviated to `~/`.
- `rtk git branch --list <name>` prints a phantom `* ` line even when nothing matches, so
  git-branches' stated ambiguity test — "output from both means the name is ambiguous" — reported
  every name as ambiguous. `tag --list` is a clean passthrough, so only one half broke.
- `rtk git diff --name-only`/`--name-status` append a `Changes:` trailer to output documented as
  "one per line"; `--word-diff` emits none of the `[-removed-] {+added+}` markers its table
  describes; `rtk git log -L` truncates each line at ~72 chars, on the one command whose purpose is
  showing line content.
- `rtk git stash pop` prints only `FAILED: git stash pop`, swallowing the conflict diagnostic and
  retained-entry message the surrounding prose tells the agent to rely on.

Implementation notes:
- Eleven sites reverted to bare `git`, each carrying its reason inline so the next sweep does not
  undo it. `mergetool` and `rebase -i` are reverted on clause 3's interactive limb only: the TTY
  defect does not reproduce — rtk filters exactly twelve subcommands and execs the rest — and
  ADR-0023 records that measurement rather than a convenient one.
- ADR-0023 states the rule repo-wide with a third clause: a command whose output the skill parses,
  or which is interactive, stays bare. `plugins/git/README.md` is reduced to a pointer; its claim
  that gitea skills "contain no git/rtk mentions at all" was false, and its citation of
  `hard-rules.md` pointed at a file containing no occurrence of "rtk".
- Eight gitea sites swept, all verified byte-identical passthroughs first.
- `scripts/check-rtk-prefix.sh` gates clause 1. Run against main's pre-sweep corpus it reports 99
  findings including every gitea site, so it would have caught the drift #113 was filed about.

Impact: the gate covers clause 1 only, in shell-tagged fences and the opening span of Run cells.
Clause 2 is not gateable — "Run `git switch`" and "`git switch` refuses" are the same tokens — and
prose bullets are invisible to it. Both limits are recorded in gates.md rather than left implied.

Refs: #113
ADR: 0023
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-09 05:14:54 +00:00
Defame1297
a6eedacfd8 fix(skill-frontmatter): check every file, scope checks to frontmatter 
The hook is `entry: bash` with `args: ['-c', <script>]`. pre-commit appends filenames after the
script string, so the first becomes `$0` and never enters `"$@"` — on a single-file commit, the
common case, the loop body never ran and the hook reported Passed having measured nothing.
ADR-0022 leans on this hook as the enforcement for a mandatory `metadata.version`, so the vacuous
green was the whole gate.

Implementation notes:
- An arg0 placeholder absorbs `$0` so every filename lands in `"$@"`.
- Checks now run against the YAML frontmatter block only, extracted with awk. The old
  `grep -A10 "^metadata:"` matched a `metadata:` inside a body code fence, spanned past the block
  into a following `source:` entry's `version:`, accepted any indentation, and missed a `version:`
  more than ten lines in. An unreadable frontmatter block is now an error, never a pass.
- The value is asserted against three-part semver. `write-docs` carried "1.0" through the entire
  ADR-0022 retrofit undetected, which a presence-only check cannot catch.

Impact: `tests/test-skill-frontmatter.sh` is the first test this hook has ever had. It drives the
real `entry`/`args` composition read out of the config rather than a copy of the script, which is
the only shape that catches the arg0 bug; against the pre-fix hook it scores 7/20.

gates.md described the hook wrongly in both directions and is rewritten, with a carve-out
explaining why this one stays a shell parser next to the "python3 and PyYAML are hard
requirements" reasoning that argues otherwise.

Refs: #127
ADR: 0022
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-09 05:13:52 +00:00
Defame1297
4f4b55b0be chore: refresh apm.lock.yaml to match the deployed install state 
kyberforge's SessionStart hook updates this lockfile automatically
when apm reports the local install behind; it had drifted since
before this branch existed (generated_at predates 598a7c3). Re-ran
apm install to bring the local .claude/ deployment in line with what
the lockfile now expects -- apm audit --ci passes 10/10 clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-07 20:44:28 +00:00
Defame1297
af8b46cd57 chore(plugins): sync generated content mirrors 
Regenerate plugins/*/skills/ from plugins/*/.apm/ after the previous
four commits, via scripts/sync-plugin-content.sh --all. The mirror is
generated output (ADR-0017) that check-plugin-content-sync's pre-push
hook diffs against .apm/; nothing here is hand-edited.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-07 20:43:51 +00:00
Defame1297
09eea5e7ab fix(skill-audit): flag a changed provenance claim, not just its shape 
validate-provenance.sh checked that a sources.md entry was internally
consistent -- slugs resolve, Contributing files exist, back-references
match -- but never whether the asserted contribution was true. A
retrofit once turned an honest hedge into a false confident claim and
every existing check passed it silently.

A literal-filename cross-check (flag a description naming a .md file
absent from Contributing files) was tried and rejected: 3/95 flagged
against the real corpus, all three false positives, and it would not
have caught the actual bug -- the bad description never named a
literal filename. No bash script can verify semantic truth, so the fix
uses what git can reliably detect -- a changed field -- purely as a
trigger for what can verify semantics: the auditor reading the files.

New check 9 flags (INFO only, never FAIL) any Description or
Contributing-files text change against a base ref (default: merge-base
with origin/main, overridable via --base-ref). A slug absent at the
base ref is a creation, not a change, and is not flagged. skill-audit's
rubric now tells the auditor a check-9 INFO means open the named files
and verify by reading, not just relay it. skill-author's retrofit
checklist gained a matching authoring-time guardrail: don't upgrade a
hedge into a confident claim without re-reading the source first.

8 new bats tests (73 total, 0 failures).

Fixes: #118
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-07 20:37:03 +00:00
Defame1297
2c6ce438b6 refactor(git): normalize rtk-prefix usage, add metadata.version 
Two bundled fixes across the same nine skills, since both touch the
same files.

Issue #113: skill prose used rtk git and bare git inconsistently for
the same operations, with no stated rule for which applied where.
Executable instructed commands (a dispatch-table "Run" cell, a fenced
code-block procedure, an imperative step) now consistently use rtk
git; illustrative or referential mentions -- naming a flag's behavior,
quoting a doc heading, warning against an anti-pattern -- stay bare
git. Documented in the new plugins/git/README.md, scoped to this
plugin only: gitea-* skills talk to the server over MCP tools and
carry no git/rtk mentions at all.

Also the git-plugin slice of #127: metadata.version added to the
eight skills that lacked it. git-commits already had one and is
untouched.

Fixes: #113
Fixes: #127
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-07 20:36:49 +00:00
Defame1297
ffaa3afb41 fix(agent-audit): remove user-invocable as a hand-invoked marker 
disable-model-invocation and user-invocable are independent Copilot
fields: the first gates whether the runtime auto-selects an agent (i.e.
whether its description is a routing string), the second only gates
manual invocation. An agent can be disable-model-invocation: false plus
user-invocable: false and still be model-routed, so the old bullet
conflated two unrelated contracts under one trigger.

Fixes: #125
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-07 20:36:34 +00:00
Defame1297
60be7b3232 refactor(skills): mandate metadata.version on every skill's frontmatter 
Only 12 of 39 skills carried metadata.version, and adoption tracked
which plugin a skill lived in rather than any stated rule: core,
gitea and lint were consistent adopters, bin and kyberforge were
consistent non-adopters, git was split with one outlier. There was
no documented convention, and skill-author's own bump logic was
already written as if presence were conditional.

metadata.version is now required on every skill. The 19 skills here
that never carried one (bin, kyberforge, gitea-files) are seeded at
1.0.0, not 0.1.0 -- that value stays reserved for a skill's actual
creation point under skill-author's existing convention. The
skill-frontmatter pre-commit hook now fails a SKILL.md missing the
field, the same class of failure as a missing name/description.

Full rationale in the new ADR. The git-plugin skills that also need
this field follow in the next commit, bundled with issue #113's rtk
normalization since both touch the same files.

Refs: #127
ADR: 0022
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
 2026-09-07 20:36:24 +00:00
Claude Code AI - Gitea MCP
598a7c326a refactor(skills): retrofit the corpus to the ADR-0020 context contract (#129) 
Retrofits all 39 skills to ADR-0020's description/body context contract, then fixes what six rounds of independent review found in that retrofit — including four ways the hot gate itself failed open.

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

## The retrofit (waves 1-5)

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

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

## The review fixes

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

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

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

## Verification

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

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

## Version bump

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

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

## Deliberately not in scope

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

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

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

Co-authored-by: Defame1297 <gitea@rkdr.net>
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/129
Co-authored-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
Co-committed-by: Claude Code AI - Gitea MCP <claude@noreply.git.dev.rkdr.net>
 2026-09-01 13:47:46 +00:00
Defame1297
0e91a3ae66 Merge pull request 'fix(gitea): correct which pull_request_write params apply on create' (#106) from fix/gitea-prs-create-drops-params into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/106
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-08-17 20:33:56 +00:00
Defame1297
967d3ade25 fix(gitea): document the remaining create/update parameter asymmetries 
Follow-up to the review of #106, which found four parameter claims the
first pass left wrong or missing. All four verified against gitea-mcp
v1.6.0 source before changing anything.

`remove_deadline` is dropped on "create" like the others, but the new
Gotcha enumerated a closed list that omitted it — so the paragraph
contradicted its own opening sentence. The list is now open ("including")
and the parameter carries the same "update" only marker as its neighbours.

`base` is settable on "update": editPullRequestFn reads it and retargets
the PR onto a different base branch. The file documented it as required
for "create" and said nothing else, hiding a real capability. This one is
under-claiming rather than over-claiming, but a file whose subject is
which parameter applies to which method is the place to fix it.

applyDraftPrefix strips two prefixes, `WIP:` and `[WIP]`, matched with
strings.EqualFold, while only "WIP: " is ever added. The un-draft
correction said "the prefix" singular, which understates what a caller
can hand it.

README.md bundled `reviewers` and `milestone` into "creating and
updating". Capability prose rather than a parameter contract, so not
strictly false, but it is the same conflation that produced the original
bug and it is not behind any gate.

Not addressed here: SKILL.md's description still advertises updating
reviewers, its draft guidance still prescribes the manual workaround, and
its milestone-resolution instruction carries no method qualifier — so an
agent working from SKILL.md alone can still reach the failure mode. Those
edits trip skill-size-check and the Vale prefilter, pulling in the
ADR-0020 retrofit; tracked on #99 rather than done silently here.

Refs: #104
Refs: #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETxbGFetkbJQBHsx442Brt
 2026-08-17 17:29:06 +00:00
Defame1297
4c9d2d7751 fix(gitea): correct which pull_request_write params apply on create 
The gitea-prs reference documented `milestone` as "settable on both
"create" and "update"". It is not: `pull_request_write method: "create"`
accepts the parameter, returns no error or warning, and discards it.

Verified against the gitea-mcp v1.6.0 source rather than by observation
alone. `createPullRequestFn` builds its `CreatePullRequestOption` from
owner, repo, title, body, head, base, draft, labels and deadline only —
so the drop is not limited to `milestone` as issue #104 supposed.
`assignee`, `assignees`, `reviewers` and `team_reviewers` are discarded
on create too, and `reviewers`/`team_reviewers` are discarded on
"update" as well; they are only ever read by "add_reviewers" and
"remove_reviewers".

Two properties made the original error easy to make and hard to catch,
so both are now written down next to the correction: `labels` sits
beside `milestone`, reads identically, and does apply on create; and
`issue_write method: "create"` honours `assignees` and `milestone`, so
the asymmetry is specific to pull requests.

While in the file, corrected the adjacent draft gotcha. It prescribed
reconstructing the un-prefixed title by hand to un-draft a PR;
`applyDraftPrefix` shows "update" with `draft: false` and no `title`
fetches the stored title and strips the prefix server-side.

Impact: documentation only, no behaviour change. Callers following the
old text silently created PRs with no milestone, assignee or reviewer.
Confined to references/pull-requests.md, so the ADR-0020 skill gates do
not apply and gitea-prs needs no #99 retrofit first.

Fixes: #104
Refs: #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETxbGFetkbJQBHsx442Brt
 2026-08-17 16:58:56 +00:00
527 changed files with 12675 additions and 27588 deletions
Expand all files Collapse all files

95
.agents/plugins/marketplace.json
View File

@@ -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"
}
]
}

27
.claude-plugin/marketplace.json
View File

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

67
.github/plugin/marketplace.json vendored
View File

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

9
.gitignore vendored
View File

@@ -34,6 +34,11 @@ apm_modules/
.claude/skills/
.claude/agents/
# APM MCP deployment output — `apm install` writes the repo-root .mcp.json from
# the MCP servers its dependencies declare, and regenerates it on every install.
# It is apm's output, not repo content; nothing here is hand-authored.
/.mcp.json
# 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
@@ -47,8 +52,8 @@ 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
# own paths hide it, since the apm-pack-check-clean pre-push hook, the only
# thing that runs pack here, passes --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

12
.mcp.json
View File

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

106
.pre-commit-config.yaml
View File

@@ -32,14 +32,21 @@ repos:
# 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-plugin/marketplace.json` would have been silently excluded
# from formatting while an equivalent
# `.../.agents/plugins/marketplace.json` would not. Only the one root
# marketplace manifest matches now; anything else is hand-authored and
# gets formatted. The twelve per-plugin `plugin.json` alternatives were
# dropped with the plugin manifests themselves when native
# `claude plugin install` support was removed (ADR-0024) -- apm probes
# `apm.yml` and never reached them. The `.agents/plugins/` and
# `.github/plugin/` marketplace mirrors went the same way, and their
# alternations went with them: `check-useless-excludes` fails on a
# pattern that matches no file.
#
# `.claude/settings.json` is the sixteenth, and it is excluded for a
# different reason: apm OWNS that file (ADR-0018, ADR-0019), and
# `.claude/settings.json` is the second and last alternation, and it is
# the only one here for a reason other than "generated manifest":
# 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
@@ -50,7 +57,7 @@ repos:
# 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)$'
exclude: '^(\.claude-plugin/marketplace\.json|\.claude/settings\.json)$'
- id: check-yaml
stages: ['pre-commit']
- id: trailing-whitespace
@@ -75,33 +82,6 @@ repos:
pass_filenames: false
always_run: true
- id: check-manifests
name: Check plugin manifests
description: Validate marketplace.json and plugin.json paths
entry: bash scripts/check-manifests.sh
language: system
stages: [pre-push]
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)
@@ -111,15 +91,6 @@ repos:
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
@@ -162,8 +133,8 @@ repos:
# 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.
# `unshare -rn`) -- consistent with every other pre-push hook: none of
# them need the network (see README.md's "Offline?" section).
- id: check-apm-agents-valid
name: Validate real APM agent files
@@ -229,15 +200,6 @@ repos:
pass_filenames: false
always_run: true
- id: validate-plugins
name: Validate plugins
description: Run claude plugin validate --strict on every plugin directory
entry: bash -c 'for d in plugins/*/; do claude plugin validate --strict "$d" || exit 1; done'
language: system
stages: [pre-push]
pass_filenames: false
always_run: true
- id: validate-marketplace
name: Validate marketplace manifest
description: Run claude plugin validate --strict on the root marketplace manifest
@@ -247,25 +209,6 @@ repos:
pass_filenames: false
always_run: true
- id: skill-frontmatter
stages: ['pre-commit']
name: SKILL.md frontmatter validation
description: Ensure SKILL.md files have required frontmatter fields
entry: bash
language: system
files: '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'
args:
- -c
- |
for f in "$@"; do
if [[ -f "$f" ]]; then
if ! grep -q "^name:" "$f" || ! grep -q "^description:" "$f"; then
echo "ERROR: $f is missing required frontmatter fields (name: and description:)"
exit 1
fi
fi
done
- id: skill-size-check
stages: ['pre-commit']
name: SKILL.md size and context-budget ceilings
@@ -284,6 +227,21 @@ repos:
# records for Vale warnings. Costs nothing on a clean file: the script
# prints only findings.
- id: check-rtk-prefix
stages: ['pre-commit']
name: ADR-0023 rtk prefix on executable git commands
description: Enforce ADR-0023 clause 1 -- an executable, instructed git command in a shell code fence or a dispatch-table Run cell is written `rtk git`. Clauses 2 and 3 are not machine-decidable; a deliberately bare command opts out with the literal string ADR-0023 on its own line
entry: scripts/check-rtk-prefix.sh
language: script
files: '^plugins/[^/]+/\.apm/(skills/.*\.md|agents/.*\.agent\.md)$'
# README.md is excluded on purpose, not by oversight. A skill-directory
# README is consumer-facing prose that no agent ever loads, and the
# `git clone` lines in the seven tests/README.md files are setup
# instructions for a third party who has no rtk installed. Prefixing
# those would be actively wrong -- see ADR-0023's consumer section.
exclude: '(^|/)README\.md$'
pass_filenames: true
- id: vale-audit-prefilter-skill
stages: ['pre-commit']
name: Vale audit prefilter (SKILL.md)

16
AGENTS.md
View File

@@ -9,14 +9,6 @@ This file carries only what applies to **every** session. Setup, prerequisites,
- `plugins/` — six installable plugin units, each an apm package (`apm.yml` + `.apm/`). Root `apm.yml` declares all six as `dependencies.apm`; `apm install` deploys them into `.claude/skills/` and `.claude/agents/`, both gitignored install output.
- `providers/claude-code/` — Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh`.
## Edit `.apm/`, never the flat mirror
`plugins/<name>/.apm/` is the only hand-edited source for plugin content. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `plugins/<name>/hooks/hooks.json`, and both `plugin.json` manifests are generated — nothing marks them as generated, so check the path before you edit. An edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
Not everything in a plugin root is generated. `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` and per-plugin extras are hand-authored there with no `.apm/` source — edit those in place. The rule is per-path, not per-directory. But a file placed *inside* a mirrored directory is deleted on the next sync (`sync_dir` runs `rm -rf` before every copy), so plugin-root documentation goes in `docs/`, never in `hooks/` or `skills/`.
Full model: `docs/spec/architecture.md`.
## Prefer plugin skills over raw shell
This repo dogfoods its own plugins. Before shelling out, check whether a skill already owns the operation — it usually does:
@@ -34,13 +26,9 @@ Fall back to raw shell only when no skill covers it.
## Session rules
- **Do not add repo-owned keys to `.claude/settings.json`.** apm treats it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. The `SessionStart` entry already in it is exactly that: kyberforge authors it in `plugins/kyberforge/.apm/hooks/hooks.json` and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes in `.pre-commit-config.yaml`.
- **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook runs `apm outdated` at startup and `apm update --yes` when something is behind, which rewrites the lock. Commit or discard it deliberately.
- **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook keeps the install current on launch and rewrites the lock in the process (ADR-0019). Commit or discard it deliberately.
- **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs.
- **The ADR-0020 skill gates ship hot, with no baseline.** 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the `Kyberforge.CompositionNote` Vale rule fires 10 errors across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Editing any of those skills *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. `skill-size-check` will not warn you about the Vale half, so check both: `pre-commit run --all-files`.
- **Run `bash tests/run-tests.sh --strict` before considering any change done.** Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
- **Before pushing, rehearse the gate locally:** `pre-commit run --hook-stage pre-push --all-files`. It runs the 14 pre-push hooks this repo authors itself plus pre-commit's 2 `meta` hooks, so it prints 16; `check-release-needed` passes without checking anything, because it needs a real push to `main`. `docs/spec/gates.md` reconciles both.
- **Pushing without a network** needs `SKIP=apm-marketplace-check,apm-pack-check-clean git push` — those two resolve a remote marketplace entry via `git ls-remote`. Skip only those two; the rest are real local checks, and adding one to `SKIP` disarms it silently.
- **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces.
- **No pre-push hook needs the network.** Root `apm.yml`'s marketplace has no remote package entries, so every hook resolves locally.
- **This repo and Gitea are the only source of truth.** All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check `docs/adr/` for an existing decision.
## Key documents

102
CONTEXT.md
View File

@@ -14,17 +14,13 @@ decisions.
### Context cost
**Preload tax**:
The always-on context cost of every installed skill's `name` and `description`, charged from the
first token of every session whether the skill is invoked or not. Measurement method and current
figure: ADR-0020.
_Avoid_: context cost, token overhead
**Skill context contract**:
The ADR-0020 authoring rules that hold the preload tax and body size down — a description carries a
trigger clause, at most one capability clause, and a boundary clause, and nothing else. Thresholds
and the target-resolution walk: `docs/spec/gates.md`.
_Avoid_: skill budget, size limit
**Routing target**:
The skill or agent name a boundary clause sends work to. It **resolves** when a skill or agent of
that name is reachable from the file being checked, and **dangles** when none is — a route the router
cannot take. Dangling is a blocking ERROR in route notation (`/name`, `→ name`) and a SUGGESTION for
a bare name nothing else in the sentence corroborates. Verdicts and the resolution walk:
`docs/spec/gates.md`.
_Avoid_: route, pointer, cross-reference
**Dispatch body**:
The body pattern a skill with two or more mutually exclusive flows must use — the body carries only
@@ -35,7 +31,9 @@ _Avoid_: router body, thin body
**Hand-invoked skill**:
A skill reached only by typing its slash command, declared `disable-model-invocation: true`. The host
withholds it from the model-visible listing entirely, so it pays no preload tax and its description
becomes human-facing text. Exemplar: `zoom-out`.
becomes human-facing text. The flag also hard-blocks the Skill tool, so **no other skill can route to
a hand-invoked skill** — a `` Call `x` `` step in another skill's body stops working the moment `x`
takes the flag. Check inbound routes before declaring one. Exemplar: `zoom-out`.
_Avoid_: manual skill, disabled skill
**Delegation discipline**:
@@ -52,27 +50,18 @@ A reusable slash command defined as a `SKILL.md` file following the
`plugins/<plugin>/.apm/skills/<skill>/SKILL.md`.
_Avoid_: command, prompt, macro
**Plugin**:
The deployable unit — one or more skills, agents, hooks, commands, and MCP servers bundled into a
single installable directory under `plugins/<name>/`, compiled from that plugin's `.apm/` source.
_Avoid_: package, bundle, module
**apm package**:
The unit apm builds and installs — `plugins/<name>/apm.yml` plus the hand-authored
`plugins/<name>/.apm/` tree it compiles from (ADR-0015).
_Avoid_: plugin directory, source tree
**Content mirror**:
The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and
merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that
plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017).
_Avoid_: generated copy, duplicate tree
The deployable unit apm builds and installs — one or more skills, agents, hooks, commands, and MCP
servers under a single directory `plugins/<name>/`, consisting of that directory's `apm.yml` plus
the hand-authored `plugins/<name>/.apm/` tree it deploys from (ADR-0015).
_Avoid_: bundle, module, source tree; and bare "plugin" for the *installable artifact*, which since
ADR-0024 is an apm package and not a Claude Code plugin. "Plugin" stays correct as a modifier in the
repo's settled compounds — **Plugin marketplace**, "plugin units", `plugins/`.
**Output profile**:
An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
`.agents/plugins/marketplace.json`), and none for `.github/plugin/marketplace.json` (Copilot CLI's
legacy path), which a sync script mirrors instead. Mechanics: `docs/spec/architecture.md`.
A named ecosystem format `apm pack` can compile the marketplace manifest into, declared per profile
under root `apm.yml`'s `marketplace.outputs:`. apm defines `claude` and `codex`; each writes to its
own default path unless overridden. Mechanics: `docs/spec/architecture.md`.
_Avoid_: build target, export format
**Plugin marketplace**:
@@ -85,12 +74,6 @@ This repository, in its role as a plugin marketplace and as the remote the six p
resolve against.
_Avoid_: the marketplace, upstream
**apm-consumed install**:
How this repo installs its own plugins as of 2026-08-14 — six `dependencies.apm` entries in the root
`apm.yml` deployed by `apm install`, rather than `claude plugin install <name>@holocron`. Its
consequences: ADR-0018.
_Avoid_: apm install, dependency install
**Provenance chain**:
The three-stage traceability record linking a skill back to its research inputs: `/research` produces
topic docs and a `sources.md`; the author skill records which sources informed which files in
@@ -106,18 +89,6 @@ irreversible or high-stakes actions — architecture changes, production deploym
configuration.
_Avoid_: manual approval, gated action
**HOTL** (human-on-the-loop):
The agent acts and a human monitors, able to intervene after the fact. Acceptable only for
low-stakes, bounded, reversible actions where the cost of pausing exceeds the blast radius of an
error.
_Avoid_: autonomous, unsupervised
**Sycophancy**:
The failure mode where an RLHF-trained model prioritises approval over accuracy — changing a correct
answer to a wrong one under user pressure, then persisting in the wrong answer. Treated here as a
first-class reliability risk, not a quality-of-life concern.
_Avoid_: agreeableness, people-pleasing
### Documents
**AGENTS.md**:
@@ -135,12 +106,6 @@ _Avoid_: wrapper, shim, provider file
The long-loop feedback log for patterns observed across sessions, at the repo root.
_Avoid_: changelog, retro, postmortem
**Management Application**:
A separate product in a separate repo for browsing, editing, and configuring AI development configs
through a product UI, with Git as an invisible persistence layer. Repo-agnostic; this repo is its
canonical default content. Roadmap: `docs/VISION.md`.
_Avoid_: the UI, the dashboard, the app
### Quality
**Skill composition**:
@@ -148,11 +113,6 @@ A skill calling another skill by name to delegate a sub-task — the caller owns
decision ("when to do X"), the callee owns the mechanics ("how to do X").
_Avoid_: chaining, nesting, sub-skill
**Vale audit prefilter**:
The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Description dimension,
so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`.
_Avoid_: linting, style check
**Authoring root**:
The directory a gate resolves against — the nearest ancestor of the file being checked holding
`plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding
@@ -165,11 +125,6 @@ sibling that would wrongly answer it; boundary clauses exist to exclude genuine
than to enumerate siblings. Detail: `skill-audit/references/description-quality.md`.
_Avoid_: overlap, similar skill
**Vacuous green**:
A check that reports success because it measured nothing — zero files scanned, an unparsed value read
as empty, a conditional branch that never armed.
_Avoid_: false pass, clean run
**Issue**:
The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker
(ADR-0007), but skills say "linked issue" generically rather than naming a provider.
@@ -177,20 +132,14 @@ _Avoid_: ticket, card, task
## Relationships
- A **Plugin** bundles one or more **Skills** and agents; a **Plugin marketplace** lists **Plugins**;
**holocron** is this repo wearing that hat.
- Every model-invocable **Skill** pays the **Preload tax**. A **Hand-invoked skill** does not — which
is the first question to settle when authoring one.
- The **Skill context contract** bounds both the **Preload tax** (description) and the body.
A **Dispatch body** is how a skill stays inside it; **Delegation discipline** is how an agent does.
- An **apm package** bundles one or more **Skills** and agents; a **Plugin marketplace** lists
**apm packages**; **holocron** is this repo wearing that hat.
- **AGENTS.md** is the source of always-on rules; a **Thin adapter** imports it and originates
nothing.
- **Skill composition** is the caller/callee split. `forge` routes a genuinely *undecided* artifact
type to the matching author skill — an already-specified fix (file, line, and change known) calls
that author skill directly, because each routing hop re-derives instructions from a shorter brief
and has been observed to drop hard constraints handed down the chain.
- **HITL** and **HOTL** are exclusive per action class, and the choice must be explicit and
documented. **Sycophancy** is why HOTL is not the safe default.
- A **Skill** built on research carries a **Provenance chain**; `skill-audit` fails it when broken.
- **LESSONS.md** feeds the standing files: three or more entries on one pattern graduate the pattern
into the relevant standing document.
@@ -219,8 +168,13 @@ _Avoid_: ticket, card, task
- Skills can answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), depending on
whether a native install exists at user scope alongside the apm one (ADR-0018) — resolved: write
the bare name, which is the only form `apm install` produces.
- "context" means both the model's live token window (the **Preload tax** sense) and the bounded
domain this file describes — resolved: unqualified "context" in this repo means the token window.
- "plugin" was used both for the installable artifact under `plugins/<name>/` and as a modifier in
settled compounds (**Plugin marketplace**, "plugin units", the `plugins/` directory itself) —
resolved: the installable artifact is an **apm package**, because ADR-0024 ended native
`claude plugin install` support and it is no longer a Claude Code plugin in any operative sense;
the compounds keep the word and are not being renamed.
- "context" means both the model's live token window and the bounded domain this file describes —
resolved: unqualified "context" in this repo means the token window.
- "audit" was used for both an author skill's inline closeout and `forge`'s independent
clean-context recheck — resolved: these are two distinct layers, kept separate precisely because
an audit running in the same context as the work it checks shares that work's blind spots.

200
LESSONS.md
View File

@@ -10,254 +10,122 @@ Patterns observed during development of this repo. Three or more entries on the
---
## 2026-05-17 — Workflow documents should prescribe sub-agent usage, not just allow it
When writing workflow documents (like `docs/notes/skill-implementation-workflow.md`), the natural tendency is to describe steps at a high level and leave sub-agent usage as an implementation detail. But if the workflow doesn't explicitly prescribe "spawn a sub-agent here," practitioners default to doing everything in the main context — accumulating token cost and losing the isolation benefit. Fix: make sub-agent usage a named step in the workflow, specifying what the agent receives, what it returns, and why it's isolated. This makes the workflow reproducible rather than dependent on the practitioner remembering to use agents.
## 2026-05-17 — Conflict check before synthesis grill, not during
When combining upstream sources into a skill, conflicts with governing documents (AI constitution, factory principles) tend to surface in the middle of the synthesis grill — disrupting the combining discussion and requiring context switches. Fix: run a dedicated conflict-check step before the grill. A sub-agent reads the governing documents, checks the upstream content against them, and returns a numbered list of tensions. The grill then starts with those items as explicit agenda points, making it faster and more systematic. An empty conflict list is also valuable — it confirms the upstreams are clean before co-writing begins.
## 2026-05-17 — Cross-references to "produced by issue N" rot before the session ends
Issue files frequently referenced "the workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016)." Within the same session that closes issue 0016, that parenthetical is already stale — the document exists and is the authoritative reference. Fix: reference the document path directly, not the issue that produced it. The git history records the producing issue; cross-references should point to the artifact that persists.
## 2026-05-17 — "Read at session start" is a behavioral hope, not a guarantee
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," 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.
Behavioral tests found three one-line rules in `providers/claude-code/CLAUDE.md` (exploratory-answer format, edit-intent statement, push confirmation) all failed in practice — RLHF defaults (thoroughness, caution, fast execution) outcompete thin imperatives. Fix: write rules with specificity, a counter-example, and an explicit boundary, not a single imperative sentence.
## 2026-05-17 — Secrets rule gap: response text not covered
The secrets prohibition in `core/instructions/governance.md` fired correctly when asked to write a password to a file, but the agent then reproduced the literal credential in its response text (in a shell `export` example). The rule was interpreted as "don't write to files" not "don't output at all." Fix: the rule needs to explicitly state "never produce the credential value in any output" and give an example showing placeholder usage (`export DB_PASSWORD='<your-password>'`).
## 2026-05-17 — Synthesis grill and SKILL.md co-write are two separate conversations
The synthesis grill (step 4) answers schema-level questions: how to combine upstreams, which eval schema to use, merge behaviour. Step 5b is a different conversation: how upstream content maps to each SKILL.md body section, what options each section had, and which was chosen. Collapsing them — writing the SKILL.md immediately after the grill without a per-section walk-through — means the human never sees the upstream options for the body and has no opportunity to redirect before the file is written. Fix: step 5b is now a named gate in the workflow. Walk through every body section one at a time, cite the upstream source, present alternatives, get confirmation. Only then write. Applies to both hand-written (bootstrap) and write-skill-produced skills.
## 2026-05-17 — Skill-calls-skill composition must be a named process step
When a skill invokes another skill as part of its work (e.g. write-skill invoking write-eval to produce the eval), that call must be a numbered step in the Process section — not left as an implicit external workflow step. If it isn't named, practitioners either forget it or do it manually outside the skill, breaking the composition chain. The user caught this during the write-skill co-write; it was absent from the process despite being in the workflow doc. Fix: when designing any skill that composes another, list each composed call explicitly as a numbered step with a "do not mark complete until X exists" constraint.
## 2026-05-17 — AGPL-3.0 repos appear prominently in community skill search results
When searching GitHub for agent skill upstreams, AGPL-3.0 repos (e.g. dceoy/speckit-agent-skills) appear alongside permissive-licensed ones without obvious visual distinction. AGPL imposes copyleft obligations on adopted content. Always run a licence check (GitHub API `/license` endpoint) before extracting any content from a new upstream. An AGPL finding is a hard exclude — record the repo, SHA, and licence in source review notes so future sessions don't re-review it.
## 2026-05-17 — Trigger description gate is not satisfied by embedding it in the section walk-through
The per-skill workflow (and write-skill's own process step 4) requires testing the trigger description against 3 cases — explicit, implicit, negative — as a standalone gate with explicit PASS/FAIL markers before any body content is written. During write-docs (issue 0018 phase 2), the trigger description was included in the section walk-through (step 5b) rather than tested first as a named gate. The gate never had explicit pass/fail output, which means neither the human nor the agent confirmed the trigger was sound before section content was written. Fix: treat the trigger test as a numbered standalone step with per-case PASS/FAIL output before step 5b begins. A section walk-through that happens to include the description field is not a substitute.
## 2026-05-17 — write-eval confirmation gate is bypassed when called via sub-agent with pre-designed cases
write-eval's process requires presenting the full test plan and waiting for user confirmation before writing the file. When write-eval is invoked by passing pre-designed test cases directly to a write sub-agent, this gate is skipped — the file is written before the user sees the plan. This happened during write-docs (issue 0018 phase 2). Fix: when orchestrating write-eval as part of a larger workflow, split into two steps: (1) sub-agent proposes test cases and returns to the main conversation; (2) after user confirmation, sub-agent writes the file. Or: design cases in the main conversation, present them to the user, then spawn the write agent. The plan-then-write separation is the gate — collapsing it into a single sub-agent call silently removes it.
## 2026-05-18 — Skill body sections were cargo-culted, not spec-defined
The write-skill authoring standard required 8 body sections including Role and When/When not. These were assumed to be agentskills.io requirements. Checking the actual spec revealed the body has no format restrictions at all — recommended sections are step-by-step instructions, examples, and edge cases. Role and When/When not were added by convention without verifying the standard. Fix: before encoding any requirement as part of an authoring standard, check the upstream spec directly. The agentskills.io spec also confirmed that negative triggers belong in the description field — not in a separate body section — which eliminates a persistent duplication pattern across all skills.
## 2026-05-18 — Provenance fields in frontmatter are loaded on every skill scan
Fields like `source:`, `references:`, `version:`, `updated:`, and `when:` in SKILL.md frontmatter are loaded at agent startup alongside `name` and `description` for every installed skill. None of these are used for routing or runtime execution — they are audit and upgrade-cycle records. Loading them at startup violates progressive disclosure and wastes tokens proportional to the number of installed skills. Fix: move all non-routing frontmatter to a separate `META.md` file in the skill directory. Frontmatter keeps only `name`, `description`, `metadata.category`, and `allowed-tools` (when applicable) — the four fields the spec actually uses for routing and discovery.
## 2026-05-18 — Copy-fill is more deterministic than generate for structured skill artifacts
When a skill produces a structured artifact like SKILL.md, the natural approach is to generate it from internalized rules in the Process section. But this means section structure is only as reliable as the agent's instruction-following under token pressure. Copy-fill (copy the template to the target path, then fill in content) separates structure from content: the template mechanically enforces section order and presence, freeing the Process section to focus only on sequencing constraints (what order to decide things) rather than also policing structure. Side benefit: the template is a human-usable artifact that can be adopted independently of the skill. Fix applied in write-skill refactor: SKILL-TEMPLATE.md and META-TEMPLATE.md are the authoritative structure sources; the Process section no longer contains a body structure constraint — the template handles it.
The governance.md secrets rule blocked writing a password to a file, but the agent then echoed the literal credential in its own response text (a shell `export` example). The rule read as "don't write files," not "don't output at all." Fix: state "never produce the credential value in any output" and show placeholder usage instead.
## 2026-05-17 — HITL gap: agent delegates confirmation to permission system
The agent-level HITL rule ("require explicit confirmation before irreversible shared-state operations") is being bypassed: the agent calls the tool and lets the permission dialog catch it. This means the rule is not firing in agent reasoning — it's the permission system acting as a safety net. If a user selects "don't ask again," the net disappears. Fix: the HITL rule needs to be framed as "do not call the tool" rather than "ask before proceeding" — the agent must ask first, then act only after explicit confirmation.
## 2026-05-26 — META-TEMPLATE uses YAML comments; META.md output retains them
META-TEMPLATE.md uses YAML `#` comments to explain fields inline. SKILL-TEMPLATE.md uses HTML comments inside XML tags, which the agent strips on fill. The structural difference means SKILL.md output is clean but META.md output retains the explanatory `#` lines — an inconsistency. Fix (deferred): restructure META-TEMPLATE.md so all explanatory guidance is prose above the code block (markdown, never copied into the output YAML), and the code block itself uses `<placeholder>` syntax with no `#` comment lines. This makes META.md fill behaviour deterministic for the same reason SKILL.md fill is: `<...>` markers are unambiguously replaceable; prose above the block is not part of the template. Do not apply until the human/copy-fill tradeoff is resolved — see 2026-05-26 session discussion.
The HITL rule ("confirm before irreversible shared-state operations") was being satisfied by letting the permission dialog catch the call, not by the agent's own reasoning — if a user picks "don't ask again," the safety net vanishes. Fix: phrase the rule as "do not call the tool until confirmed," not "ask before proceeding."
## 2026-05-26 — Overlap checks must scan the deployed directory, not just the source repo
`write-a-skill` existed only in `~/.agents/skills/` (installed from a pre-refactor source) and was invisible during a repo-level scan of `.agents/skills/`. Governance reviews and overlap checks that only look at the source repo will miss skills added by install.sh from other sources or prior runs. Fix: overlap checks must scan the deployed `~/.agents/skills/` directory, not just the repo's `.agents/skills/`.
A skill installed only to `~/.agents/skills/` (not the repo's `.agents/skills/`) was invisible to a repo-level overlap scan. Skills added by `install.sh` or prior runs live in the deployed directory, not just the source. Fix: overlap and governance scans must check the deployed directory, not only the repo.
## 2026-05-26 — `model:` field belongs in SKILL.md frontmatter, not META.md
## 2026-05-26 — `model:` field belongs in SKILL.md frontmatter, not a sidecar file
Claude Code supports `model:` as a provider extension in SKILL.md frontmatter — it overrides the session model for the skill's turn and reverts after. Attempting to put it in META.md was wrong: META.md is provenance/audit metadata, not runtime config. The boundary: if a field affects agent behaviour at invocation time, it belongs in SKILL.md frontmatter; if it serves upgrade reviews and audit trails, it belongs in META.md.
`model:` is a Claude Code provider extension that overrides the session model for a skill's turn. Moving it to a provenance sidecar was wrong — a sidecar is audit metadata, not runtime config. Rule: if a field affects invocation-time behaviour, it belongs in SKILL.md frontmatter, not a sidecar.
## 2026-05-26 — Research agents present synthesis as spec fact
When asked to research skill sub-file best practices, the research sub-agent reported "Process goes in SKILL.md. Context goes in reference files" as if it were verbatim from the Claude Code docs or the Agent Skills spec. Checking agentskills.io directly showed the spec says: "There are no format restrictions" on the body. The principle is a reasonable synthesis, not a quoted rule — but it nearly landed in write-skill's constraints as authoritative spec language. Fix: always verify research agent claims against the primary source before encoding them as rules, especially for spec or documentation claims. Plausible synthesis is the hardest fabrication to catch because it's often correct in spirit.
A research sub-agent reported "Process goes in SKILL.md, context in reference files" as if quoted from the agentskills.io spec; the spec actually says there are no body format restrictions. Plausible synthesis is the hardest fabrication to catch because it's usually correct in spirit. Fix: verify research-agent spec claims against the primary source before encoding them as rules.
## 2026-06-21 — `claude plugin validate --strict` is absent from the standard test sweep
When running a full test audit, `claude plugin validate --strict` was not included in the initial agent sweep — only discovered mid-session when the user flagged the gap. The command catches warnings that normal mode tolerates (missing `version` fields, non-agent `.md` files in `agents/`) and will cause CI to fail when strict mode is enforced in Chunk 6. Fix: include `claude plugin validate --strict` on all plugin paths and marketplace manifests as a named step in any plugin audit. It belongs in the pre-push hook alongside `check-manifests.sh` — currently only `check-manifests.sh` runs there. See `tests/test-plugin-validate.sh` (pending, Gitea issue #2).
`claude plugin validate --strict` was left out of the standard plugin audit sweep and only discovered when the user flagged the gap. It catches warnings (missing `version` fields, stray non-agent `.md` files) that will fail CI once strict mode is enforced. Fix: run it on every plugin path and marketplace manifest as a named audit step.
## 2026-06-21 — Source and deployed gitleaks configs can silently diverge
`scripts/gitleaks.toml` (source, in git, deployed to repo root by `setup-gitleaks.sh`) and `.gitleaks.toml` (deployed root copy, read by the hook, also tracked in git) were found with different allowlist states — someone had updated the deployed file directly without updating the source. Running `setup-gitleaks.sh` again would overwrite the deployed file with the stale source, silently deleting the existing allowlist and re-exposing a known false positive as a blocking pre-commit failure. Fix: treat `scripts/gitleaks.toml` as the single source of truth; never edit `.gitleaks.toml` directly. When making allowlist changes, always update source and deployed copy together in the same commit. Longer-term fix: `setup-gitleaks.sh` should merge rather than overwrite, or detect divergence and warn when `.gitleaks.toml` is tracked in git.
`scripts/gitleaks.toml` (source) and `.gitleaks.toml` (deployed, hook-read) drifted after someone edited the deployed copy directly; rerunning `setup-gitleaks.sh` would have overwritten it, silently deleting the allowlist. Fix: treat the source as sole truth, never hand-edit the deployed copy, and update both together in the same commit.
## 2026-06-21 — `shellcheck` without `-x` blocks pre-commit on any script using `source` (LEGACY SHELL HOOKS)
## 2026-06-21 — `shellcheck` without `-x` blocks pre-commit on scripts using `source` (historical)
**Status:** Historical. Shell-hook-based pre-commit was replaced by pre-commit framework (Chunk 5, .pre-commit-config.yaml). Modern repos no longer affected. Documented for reference when supporting legacy repos.
The pre-commit hook ran `shellcheck "$f"` without `-x`. Without `-x`, shellcheck fires SC1091 for every `source` statement and exits non-zero, blocking the commit. This was a latent bug in legacy shell hooks, only triggered when `install.sh` (which sources `deploy-manifest.sh`) was staged for the first time. Compounding it: the `# shellcheck source=` directive in `install.sh` pointed to `deploy-manifest.sh` (bare filename, resolved from CWD = repo root) rather than `scripts/deploy-manifest.sh` (correct repo-root-relative path), so even with `-x` the file wasn't found on the first attempt.
**Lesson for future work:** When writing a `source=` directive, use a path that resolves correctly from the CWD where shellcheck will be invoked — verify with `shellcheck -x <file>` before committing. Pre-commit framework hooks include `-x` by default in the ecosystem's shellcheck integration.
Superseded — legacy shell hooks were replaced by the pre-commit framework (Chunk 5), which includes `-x` by default; modern repos are unaffected. Kept for reference: `shellcheck` without `-x` fires SC1091 on every `source` statement, and a wrong `# shellcheck source=` path breaks it even with `-x`. Verify with `shellcheck -x <file>` when supporting legacy scripts.
## 2026-06-22 — Plugin cache isolation rules out shared/ directories between skills
When two skills in the same plugin share a resource (e.g. validate.sh), the instinct is to put it in a shared/ directory and reference it with a relative path. This breaks silently after install: plugins are copied to a cache, and `../` paths across skill directories stop resolving. The correct pattern is duplication with clear ownership — one skill owns the canonical copy and the other delegates to it via a skill invocation (e.g. /skill-audit) rather than a file path. If delegation is not possible, duplicate the file and note the owning skill in a comment.
Skills sharing a resource (e.g. `validate.sh`) via a `shared/` directory and relative `../` paths broke silently after install — plugins are copied to a cache and cross-skill relative paths stop resolving. Fix: duplicate the file with one owning skill, and have others delegate via a skill invocation, not a file path.
## 2026-06-22 — Qualitative rubrics should be grounded in upstream spec docs, not derived from in-repo usage
## 2026-06-22 — Qualitative rubrics should be grounded in upstream spec docs, not in-repo usage
When skill-audit's qualitative checks for description quality and body discipline were first written, they were derived from skill-write's own authoring conventions — a circular dependency. Any drift in skill-write's conventions would silently propagate into the audit criteria. Fix: extract condensed reference files directly from the upstream spec (agentskills.io) and load them conditionally from the audit skill. The rubric is then grounded in the authoritative source and independent of in-repo convention drift.
`skill-audit`'s description and body-discipline rubrics were derived from `skill-write`'s own conventions — circular, so drift in one silently propagated to the other. Fix: extract condensed reference files directly from the upstream spec (agentskills.io) into the audit skill, so the rubric is independent of in-repo convention drift.
## 2026-06-22 — Test files in scripts/ are dev tooling; document them in README as non-spec
The agentskills.io spec defines scripts/ for bundled executable scripts — it says nothing about test infrastructure. Bats test files placed in scripts/ (or scripts/tests/) are invisible to auditors following the spec and create silent README drift if not documented. Fix: place test files directly in scripts/ (no subdirectory), add a row to the README file table for each with a "dev tooling, not shipped with the plugin" note, and don't nest them in a tests/ subdirectory since that creates a non-spec directory structure.
The agentskills.io spec defines `scripts/` for bundled executables, not test infrastructure — bats files placed there are invisible to spec-following auditors and cause README drift. Fix: place test files directly in `scripts/` (no subdirectory), and add a README row noting each as "dev tooling, not shipped."
## 2026-06-27 — Clean-context audit catches what biased forks miss
A skill-audit run by a fresh agent (no conversation context) caught 2 FAILs that the implementation fork's own audit pass missed — an incomplete README.md file table and `references/sources.md` paths invalid in the plugin cache. Forks that built the artifact are biased toward their own output: they know what was intended and fill in gaps silently. A fresh agent has no such priors and audits what is actually written. Fix: always run a clean-context audit as a named final step after implementation forks complete. It is not redundant with the in-process audit — it is a different check.
A fresh-context skill-audit caught two FAILs (an incomplete README table, invalid cache paths) that the implementing fork's own audit missed — the fork that built the artifact knows what was intended and fills gaps silently. Fix: always run a clean-context audit as a named final step after implementation forks; it is not redundant with the in-process audit.
## 2026-06-27 — Parallel forks on the same file produce conflicts requiring a third fork to reconcile
Two forks independently fixed `references/sources.md` with different approaches — one added a header comment, the other replaced the paths with relative references. Both were plausible; neither read the spec first. Reconciling required a third fork to read the authoritative source and revert to the correct format (repo-root-relative, per skill-author Step 5). Fix: when multiple forks are in scope for the same file, either (a) scope them to non-overlapping files explicitly, or (b) sequence them rather than parallelise. If a fix is spec-governed, always read the spec before applying it — the "obvious" fix is wrong as often as it is right.
Two forks independently "fixed" `references/sources.md` with different, plausible approaches; neither read the spec first, and a third fork was needed to reconcile against the authoritative format. Fix: scope forks to non-overlapping files or sequence them. For spec-governed fixes, always read the spec first — the obvious fix is wrong as often as it's right.
## 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.
Briefing an agent to "write the SKILL.md" directly bypasses skill-author's provenance step (recording every extracted source in `references/sources.md`), caught only by `validate-provenance.sh` after the commit — this recurred twice in one session. Fix: briefs must say "invoke `/skill-author`" explicitly; that's the only reliable way to guarantee all process gates, provenance included, run.
## 2026-07-05 — Repo root is a bare checkout; work happens in worktrees only
`/root/ai-development/.git` has `core.bare = true` — the root directory itself has no working tree. Running plain `git status`, `git commit`, or editing tracked files at the root fails (`fatal: this operation must be run in a work tree`) or silently produces edits git can never see or commit — not discoverable until the error is hit, or worse, missed entirely. All real work — including one-line docs fixes — requires `git worktree add <path> -b <branch> origin/main` first. Fresh worktrees also don't have submodules (`tests/bats`, `docs/wiki`, etc.) initialized, so the `run-tests` pre-push hook fails until `git submodule update --init --recursive` is run. Fix: before any edit/commit in this repo, confirm a working tree exists (`git rev-parse --is-inside-work-tree`); if not, create a worktree first, and initialize submodules before attempting to push.
This repo's root `.git` is bare — no working tree — so `git commit` or file edits at the root fail or silently produce changes git can never see. Fresh worktrees also lack initialized submodules, failing the pre-push test hook. Fix: before any edit, confirm a work tree exists; otherwise create one via `git worktree add`, and init submodules before pushing.
## 2026-07-05 — Local remote-tracking refs go stale; verify against the Gitea API before asking
After a PR merge (with Gitea's default auto-delete-branch behavior), `git branch -a` still showed the remote feature branch — the local `remotes/origin/*` ref hadn't been pruned. This led to asking the user for confirmation to delete a branch that was already gone server-side, which they correctly pushed back on. Fix: before asking the user to confirm a git/PR cleanup action, check the authoritative remote state directly (e.g. `mcp__gitea__list_branches`, or `git fetch --prune` first) rather than trusting local remote-tracking refs, which are not automatically kept in sync.
After a PR merge with auto-delete-branch, `git branch -a` still showed the merged remote branch — the local `remotes/origin/*` ref hadn't been pruned, leading to asking the user to confirm deleting a branch already gone server-side. Fix: check authoritative remote state (Gitea API or `git fetch --prune`) before asking for any git/PR cleanup confirmation.
## 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.
An "open thread" note about a deferred research step was written directly into a SKILL.md Process section during a refactor. Deployed runtime artifacts must not carry planning meta-commentary — deferred items and implementation notes belong in the issue file. Rule: issue = planning record; skill = executable instruction only.
## 2026-08-08 — A clean linter result can mean "nothing was checked"
## 2026-08-08 — A clean linter result can mean "nothing was checked" [graduated → core/instructions/testing.md]
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.
Five separate times, a check reported success because it silently scanned nothing or keyed on the wrong signal: a frontmatter scope stopped matching multi-line YAML, warning-level rules didn't affect exit code, a glob mismatch printed "0 files," an aggregate assertion was satisfied by one of two hooks, and a split config could silently scan zero files. Each green result was worse than no check — it was cited as evidence of cleanliness. Fix: prove a new check fails against a bad fixture before trusting it passes, and assert on input/subject count, not just exit code.
## 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.
Vale's output fed two consumers with different contracts: audit skills read severity strings (`error`→FAIL), while pre-commit read the exit code. Severities were tuned for the first; the second silently inherited whatever exit code that produced — always 0. Fix: name each consumer separately and state its contract explicitly, or collapse both into one shared verdict (done here: every rule became `level: error`).
## 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.
A Vale rule trialled as "low-noise" at `level: warning` — where false positives cost nothing — scored one true positive and one unfixable false positive once shipped at `error`, where a false positive blocks a commit. It was deleted. Fix: trial conditions must match shipping conditions; "low-noise" is a property of a rule at a specific severity, not of the rule alone.
## 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.
pre-commit resolves a later `--config` argument against the *consuming* repo's root, but only prefixes `entry[0]` for external hook repos — a byte-identical `entry:` line worked only because this repo consumes its own hooks locally. Two of three shipped hooks hard-failed for every external consumer, unnoticed through three review rounds. Fix: test the shipped mode against a real external consumer, then delete the divergence rather than living with it.
## 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.
Removing a `--config` argument from `.pre-commit-hooks.yaml` was the right fix, but `check-release-needed.sh` derived its release-relevant path list by parsing that same token — with it gone, the derivation silently shrank with no error. Fix: before removing a token from an artifact more than one script reads, grep for everything that *parses* it, and assert on expected list members.
## 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.
A wrapper script's last-resort character rewrite was justified as "the one case no YAML scalar can carry verbatim" — untested because it seemed obviously true. It was false: a literal block scalar carries the exact characters in question, silently underlinting 12 of 54 files. Fix: when a residual is accepted as "impossible," write the claim in falsifiable form and test that claim directly, not the workaround built on it.
## 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.
Four fixes specified by an orchestrating reviewer were all wrong — a regex that didn't match the real code shape, a pipefail exit code misread as "no findings," two "never-empty" shell arrays that were empty in reachable states, and a comment-stripping `sed` that truncated `${var#prefix}`. Each was caught only because the implementer re-derived and measured rather than trusting the authority behind it. Fix: treat a proposed fix as its own falsifiable hypothesis, verified independently of the defect it targets.
## 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`.
Mutation testing repeatedly found tests passing green with the behaviour they claimed to guard deleted — a stale-directory wipe, a reentrancy guard, a fixture-leak fix, canonicalization logic. Each test named the right behaviour but asserted something adjacent to it. Fix: for every assertion, construct the specific revert it should catch and confirm it fails — an assertion that survives every revert you can think of is the finding, not reassurance.
## 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.
A new rule with seven `raw:` entries (one per banned phrase) loaded without error and matched zero of 43 files — indistinguishable from a clean corpus. `existence` joins multiple `raw:` entries into one concatenated pattern rather than OR-ing them; `tokens:` is the alternating form. Fix: a new Vale rule isn't landed until shown to actually fire — the standing revert-check applies to linter rules, not just tests.
## 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.
Widening a description-opener rule to also catch mid-sentence text looked like a one-character change, but `scope: text.frontmatter.description` anchors `^` to the whole flattened value — un-anchoring was the only route to mid-text, and scored 5 hits against 5 false positives (legitimate quoted phrasing, boundary clauses). Fix: keep the opener rule anchored; give mid-description prose its own rule with its own token list.
## 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.
`apm audit --ci` failed on `.claude/settings.json` with an empty `git diff` — `pretty-format-json --autofix` silently re-sorts JSON keys, and this generated file was missing from its exclude list, so every commit re-sorted apm's insertion-ordered output before apm compared against it. Separately, a defect introduced 3 hours earlier on the same branch was first mis-described as "pre-existing," an unverified claim about history. Fix: add tool-owned paths to every autofixing hook's exclude the moment ownership is declared, and verify "pre-existing" claims with `git log -S` or `git branch --contains` before writing them down.
## 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.
A retrofit replaced "keep reference chains one level deep" with "two hops, never three" — the opposite rule, needed because the new dispatch pattern requires `SKILL.md` → `improve.md` → `retrofit.md`. The ADR never mentioned chain depth, so the reversal was carried entirely by the diff with no sign a contradicting rule ever existed. Fix: when a change inverts a standing rule, record the inversion where the rule's rationale lives, or it reads as forgotten rather than overturned.

35
README.md
View File

@@ -8,7 +8,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa
| Path | What it holds |
| --- | --- |
| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets |
| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, and bundled assets |
| `providers/claude-code/` | Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh` |
| `core/` | Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/` |
| `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes |
@@ -30,11 +30,10 @@ Install all of these before setting up. Each one is a hard dependency of a git h
| Tool | Why | Install |
| --- | --- | --- |
| `apm` CLI | Four pre-push hooks shell out to it (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` via `scripts/sync-plugin-content.sh`) | The `apm-install` skill, or `curl -sSL https://aka.ms/apm-unix \| sh`. Verify with `apm --version` |
| `jq` | Required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push | Your package manager |
| `apm` CLI | Two pre-push hooks shell out to it (`apm-audit-ci` and `apm-pack-check-clean`) | The `apm-install` skill, or `curl -sSL https://aka.ms/apm-unix \| sh`. Verify with `apm --version` |
| `python3` + PyYAML | Required by `scripts/skill-size-check.sh` (the `skill-size-check` pre-commit hook), which reads folded YAML frontmatter | `python3` is usually present — pre-commit is itself a Python application. `pip install pyyaml` if the hook reports PyYAML missing |
| `vale` | Required by the `vale-audit-prefilter-skill` / `-agent` pre-commit hooks and the `check-vale-style-sync` pre-push hook | `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or https://vale.sh/docs/vale-cli/installation/ |
| `claude` CLI | Required by the `validate-plugins` and `validate-marketplace` pre-push hooks | Claude Code |
| `claude` CLI | Required by the `validate-marketplace` pre-push hook | Claude Code |
Two notes worth reading before you skip one:
@@ -53,15 +52,13 @@ apm install
pre-commit install -t pre-commit -t commit-msg -t pre-push
```
**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`.
**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network and materializes `apm_modules/` (which stays gitignored).
**Git hooks** must be wired for **all three stages**. This repo's `.pre-commit-config.yaml` has no `default_install_hook_types`, so a plain `pre-commit install` silently skips `commit-msg` (Conventional Commits) and `pre-push` (the full gate) — the `-t` flags above are not optional. The `pc-run` skill handles this and the troubleshooting around it, if you would rather not remember the flags.
## Keeping the install current
The six dependencies in root `apm.yml` are unpinned against the default branch, so deployed skills go stale whenever anyone merges. kyberforge ships a `SessionStart` hook that runs `apm outdated` at startup (~0.7s) and, when something is behind, runs `apm update --yes` and asks the host to re-scan skills (~10.4s).
That rewrites `apm.lock.yaml` — an unexplained modification to it after opening a session is expected, not a bug. Commit or discard it deliberately.
The six dependencies in root `apm.yml` are unpinned against the default branch, so deployed skills go stale whenever anyone merges. kyberforge's `SessionStart` hook keeps the install current automatically on launch, rewriting `apm.lock.yaml` in the process — an unexplained modification to it after opening a session is expected, not a bug; commit or discard it deliberately. Mechanism and rationale: `docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md`.
Note the difference between the two commands:
@@ -94,31 +91,17 @@ Every other pre-push hook does run.
See [`docs/spec/gates.md`](docs/spec/gates.md) for what each hook enforces and why.
**Offline?** Exactly two pre-push hooks need the network, because root `apm.yml`'s marketplace contains one remote package entry that must be resolved with `git ls-remote`:
```bash
SKIP=apm-marketplace-check,apm-pack-check-clean git push
```
Skip **only** those two. The remaining pre-push hooks are real local checks and pass offline; adding one of them to `SKIP` disarms it silently.
**Offline?** No pre-push hook needs the network: root `apm.yml`'s marketplace has no remote package entries (the last one, `mattpocock-skills`, was removed), so `apm-pack-check-clean` resolves everything from local sources. All pre-push hooks pass offline.
## Editing plugin content
`plugins/<name>/.apm/` is the only hand-edited source for plugin content — skills, agents, commands, instructions, extensions, and hooks. The flat `plugins/<name>/{skills,agents,commands,instructions,extensions}/` directories, the merged `hooks/hooks.json`, and every `plugin.json` / `marketplace.json` manifest are generated. Nothing labels a generated file as generated, so check the path before you edit; an edit to the mirror is discarded by the next sync and reported as drift by the `check-plugin-content-sync` pre-push hook.
`plugins/<name>/.apm/` is the only hand-edited source for plugin content — the root `marketplace.json` manifest is generated by `apm pack`, and a hand-edit there is reported as drift by `apm-pack-check-clean`. Hand-authored material that is not an `.apm/` primitive (`README.md`, `docs/`, `bin/`, `sources.md`) lives at the plugin root instead.
Hand-authored material that is *not* an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, `.mcp.json` — lives at the plugin **root** and is untouched. Never place such a file inside a mirrored directory: the sync removes the destination before every copy, so it is deleted with no drift report.
Full detail in [`docs/spec/architecture.md`](docs/spec/architecture.md).
Full model, including what's exempt and why: [`docs/spec/architecture.md`](docs/spec/architecture.md).
## For external consumers
Install a plugin natively from the marketplace manifests:
```bash
claude plugin install <name>@holocron
```
Or consume the packages through apm, the way this repo does — declare them as `dependencies.apm` git+path entries against the holocron remote and run `apm install`.
Consume the packages through apm, the way this repo does — declare them as `dependencies.apm` git+path entries against the holocron remote and run `apm install`. apm is the only supported install path.
## Where to go next

247
SIMPLIFICATION-AUDIT.md Normal file
View File

@@ -0,0 +1,247 @@
# Simplification audit
Date: 2026-09-10. Read-only analysis; nothing has been changed. Purpose: a hand-off for deciding what to remove, merge, and shrink. Findings are ranked by payoff within each area; effort is S/M/L. Claims were independently re-verified against the repo by a clean reviewer; corrections have been applied.
Assumptions agreed before analysis: anything is on the table, Claude Code and Copilot CLI both stay supported, findings are ranked with effort.
Counting convention: line counts are hand-edited `.apm/` source unless marked "incl. mirror". Every `.apm/` file has a byte-identical generated copy at the plugin root, so plugin cuts count double in the repo total.
> **Superseded (2026-09-14):** the mirror is gone (commit `718c79a`, ADR-0024). "incl. mirror" totals below are historical. Measured against the 2026-09-10 baseline (`9eb8bc7`), what remains live varies by plugin — 44% to 71%, not a uniform ~70%:
>
> | Plugin | Baseline (incl. mirror) | Today | Live |
> |---|---|---|---|
> | kyberforge | 44,568 | 31,473 | 70.6% |
> | git | 9,889 | 6,050 | 61.2% |
> | gitea | 6,047 | 3,471 | 57.4% |
> | core | 3,873 | 2,360 | 60.9% |
> | lint | 1,558 | 923 | 59.2% |
> | bin | 4,704 | 2,083 | 44.3% |
>
> Across all six the baseline was 70,639 lines and 46,360 remain (65.6%). The mirror was 20,061 of those lines, so mirror deletion alone would have left ~71.6%; everything below that line is source the other findings cut, which is why bin — where findings 10, 12, and 13 landed hardest — is the outlier. (Counted as tracked lines under `plugins/<name>/` at `9eb8bc7` and in the current working tree.)
> **Reviewed (2026-09-14):** commits `718c79a` and `d2480b8` were put through a five-agent review. Result: **zero skill, agent or hook regressions** — 39 skills before and after, all gates passing, and both hook removals (`validate-plugins`, `check-plugin-content-sync`) genuinely moot rather than merely unenforced. One real functional regression was found — MCP propagation to consumers, broken by the same commit's manifest deletion; see finding 37 — along with the numeric and bookkeeping drift in this document's own 2026-09-14 notes, corrected in place above and below.
## 1. The shape of the problem
| Measure | Value |
| ---------------------------------------------------------------------------| -----------------------------------------------------------------------------------------|
| Tracked files / lines | 820 / 102,000 |
| Lines in `plugins/` | 70,600 (69% of repo) |
| Of which the 39 `SKILL.md` files a model actually loads | ~2,600 lines (under 4% of plugin lines) |
| Generated flat mirror files (byte copies of `.apm/`) | ~~263 files, ~22,000 lines~~ → 0 (deleted 2026-09-14, see below) |
| `docs/research/` vendored inside plugins | ~19,000 lines, nothing executable reads it |
| Repo-level `docs/research/` + `docs/notes/` | 4,500 lines, 47% of all prose words, 6 of 11 research files linked only from each other |
| Enforcement: hook entries in `.pre-commit-config.yaml` / pre-push hooks | 33 / 14 |
| Enforcement: `tests/*.sh` + runners + `scripts/` | 12,400 + 475 + 4,500 lines |
| Validator scripts inside kyberforge (+ their bats tests) | 6,800 + 5,300 lines |
| Preload tax (39 skill names + descriptions) | 10,987 chars, ~2,750 tokens per session |
| Commits since 2026-05-10 / share touching hook, test, gate, vale, or sync | 447 / ~25% |
> **Corrected then done (2026-09-14):** the mirror row's figure was wrong. The true mirror was **213 files / 20,061 lines**, not 263 / ~22,000 — the original count swept in files that were never mirror output. All 213 were deleted in commit `718c79a` on `docs/simplification-audit` (245 files changed, 298 insertions, 22,602 deletions across the whole change), so the row is now zero. The enforcement row is stale on **both** halves — it was correct at the 2026-09-10 baseline (`9eb8bc7`: 33 `- id:` entries, 14 repo-authored pre-push hooks), but `.pre-commit-config.yaml` today has **27 entries and 9 `stages: [pre-push]`**. Like for like that is 14 → 9 repo-authored pre-push hooks. The stage *reports* 11, because the 2 pre-commit `meta` hooks also run there — a different counting basis; see the corrected §3 target, which states it the same way.
The pattern across every area is the same: the payload (skill bodies, rules, decisions) is small and the scaffolding around it (mirrors, research dumps, sync gates, tests of tests, justification prose) is 10 to 30 times larger. A quarter of all commits have gone into maintaining the scaffolding.
## 2. Measured baseline: hooks and tests
Measured on this machine, clean tree, all hooks passing. `pre-commit run --all-files` per stage. Figures below are the 2026-09-10 measurement; rows struck through were deleted on 2026-09-14 (commit `718c79a`) and their times no longer apply.
| Gate | Wall time |
|---|---|
| **Full pre-push stage (everything below, sequential)** | **~5 min 10 s** |
| `run-tests` (26 bash suites + 351 bats tests) | 276 s |
| `apm-audit-ci` (7 manifests) | 12.2 s |
| ~~`validate-plugins` (6 × `claude plugin validate`)~~ deleted | ~~4.9 s~~ |
| ~~`check-plugin-content-sync`~~ deleted | ~~4.5 s~~ |
| `apm-pack-check-clean` | 3.1 s |
| Other 9 pre-push hooks combined | 7.6 s |
| **Full pre-commit stage, all files** | **18.2 s** |
`run-tests` is 90% of the wall time. Every push pays it in full: the runner has no change detection and the config sets `always_run: true`. `apm-audit-ci` is the second-slowest hook; per its own comment block its earlier description overclaimed, and what it verifies today is that seven manifests parse and the lockfile exists.
Where the 276 s goes (each suite run alone, sequential):
| Suite | Time | Note |
|---|---|---|
| ~~`test-sync-plugin-content.sh`~~ deleted | ~~83 s~~ | 14 temp trees, 2 `git init`, repeated `apm pack` |
| all 351 bats tests (10 files, kyberforge and core validators) | 64 s | mostly `validate.sh` / `validate-provenance.sh` fixtures |
| `test-adr0020-differential.sh` | 29 s | 12 assertions; re-runs two validators over the live corpus and a fixture tree |
| `test-check-vale-style-sync.sh` | 25 s | guards a byte-identical copy |
| `test-vale-wrap.sh` | 14 s | |
| `test-adr0020-frontmatter.sh` + `-targets.sh` | 25 s | |
| Remaining 20 suites | 36 s | 12 of them run in under 2 s each |
Five suites account for 215 s of 276 s. Three of those five (sync-plugin-content, vale-style-sync, adr0020-differential) test tooling that findings 2, 7, and 14 propose to delete or shrink, so the fastest path to a quick pre-push is removing the duplication those tests guard rather than optimising the tests.
> **Done (2026-09-14):** see commit `718c79a` on `docs/simplification-audit`. The three struck-through rows are gone: `test-sync-plugin-content.sh` (83 s, 1,289 lines, 92 cases), `check-plugin-content-sync` (4.5 s) and `validate-plugins` (4.9 s). Expected, not re-measured: roughly 92 s comes off every push (83 + 4.5 + 4.9 = 92.4 s) (~83 s of it out of `run-tests`, which loses its single slowest suite), on the arithmetic of the 2026-09-10 figures alone. The remaining rows have not been re-timed since, so treat every number in this section as the 2026-09-10 baseline minus those three, not as a fresh measurement.
## 3. Enforcement layer: hooks, tests, scripts
This is the area you named as hardest to understand and slowest. Root cause: most pre-push hooks exist to keep two copies of something in sync, or to re-validate what another hook already validates.
1. **Six hooks validate overlapping sets of the same manifests.** `check-manifests`, `validate-plugins`, `validate-marketplace`, `apm-pack-check-clean`, `apm-marketplace-check`, `apm-audit-ci`. Keep the two `claude plugin validate` hooks plus `apm-pack-check-clean`. ~~Delete `check-manifests` (282 lines + 771 test lines; its `lib/marketplace-plugins.sh` stays because `sync-plugin-content.sh` sources it).~~ `apm-audit-ci` spends 12 s confirming that manifests `apm pack` already parses do parse; drop or keep on that basis. Move the network-dependent `apm-marketplace-check` to a release checklist. Effort S.
> **Done (2026-09-12):** see commit `e647f14` on `docs/simplification-audit`. Deleted the `check-manifests` pre-commit hook entry, `scripts/check-manifests.sh` (282 lines), and `tests/test-check-manifests.sh` (771 lines); kept `scripts/lib/marketplace-plugins.sh`, still sourced by `sync-plugin-content.sh`. Updated the now-stale `check-manifests.sh` mentions in `README.md` and `docs/spec/gates.md` (hook table row and hook counts). The `apm-audit-ci` and `apm-marketplace-check` decisions in this finding remain open — out of scope for this change.
> **Grilled and closed (2026-09-14):** `apm-audit-ci` — already resolved before this audit was written: `.pre-commit-config.yaml`'s own comment block (added in commit `a155af6`, months before this audit) already rebuts the "overclaimed description" complaint and gives a dated, verified justification for what the hook still checks. Keep, no action. `apm-marketplace-check` — its stated purpose ("the only hook that checks remote package references rather than local-source paths") is void: finding 35 (commit `568ca74`) already removed the only remote package entry, so every `marketplace.packages[]` entry is now a local `./plugins/<name>` path and the hook is pure overlap with `apm-pack-check-clean`. Removed the hook entry, and corrected the now-stale "does NOT join apm-marketplace-check ... on the offline SKIP= list" comment on `apm-audit-ci` (there is no offline skip list any more — every pre-push hook already passes offline per `README.md`). Updated `README.md` (tool table, "Offline?" section) and `docs/spec/gates.md` (hook table, hook counts 13→11 self-authored / 15→13 total, the "Three of these shell out to apm" paragraph, and the "Pushing without a network" section) accordingly. Verified: `apm audit --ci` still passes per-plugin, and the pre-push hook count now matches `.pre-commit-config.yaml`.
2. **Four "keep two copies in sync" gates: 1,100 script lines + 1,600 test lines.** Each one is a symptom of duplication that could be removed instead of guarded:
- `check-vale-style-sync`: 413 lines + 798 test lines guarding a byte-identical 526-line `vale-wrap.sh` and style directory copied between skill-audit and agent-audit. About 350 of its lines run Vale glob probes against the hook file patterns. Disappears if the two audit skills merge (finding 14); the probes belong in `test-vale-wrap.sh`.
- `check-scope-walkup-sync`: 365 lines cross-checking four independent ports of the same package-root walk-up. Disappears if the ports share one script or the skills merge.
> **Grilled, held (2026-09-14):** both of the above are gated on findings 14/15 (merging skill-audit+agent-audit and skill-author+agent-author), deliberately held for a separate session rather than decided here. Correction for that session: the audit's §8 grouping is wrong — these merges don't need ADR-0012 revisited (that ADR governs the unrelated `core` plugin's three `agentsmd-*` skills). The actual constraint is ADR-0014 (no-cross-skill file sharing on plugin cache-install), and merging sidesteps it rather than requiring it be reversed. The open question for that session is a design one — a shared skill's `description` carrying both skill- and agent-audit trigger phrases — not an ADR supersession. ADR-0012 revisit is needed only for finding 24.
- [x] ~~`check-marketplace-mirror-sync`: guards `.github/plugin/marketplace.json`. The script header calls it Copilot's legacy convention path and says Copilot also accepts the Claude path; the vendored Copilot docs list it as primary. Verify against current Copilot CLI before deleting hook, script, test, and mirror file.~~
> **Grilled and done (2026-09-14):** verified against GitHub's current Copilot CLI plugin docs (not the vendored copy, which risked drift). Copilot CLI's marketplace discovery checks paths in order — `marketplace.json`, `.plugin/marketplace.json`, `.github/plugin/marketplace.json`, `.claude-plugin/marketplace.json` — falling through to whichever exists first. `.claude-plugin/marketplace.json` (apm's own `claude` output) already satisfies that chain's last step, so the dedicated `.github/plugin/marketplace.json` mirror bought Copilot users its *preferred* discovery path rather than a required one. Decided against reopening ADR-0018 (native install for both Claude Code and Copilot CLI stays supported) to justify this — the deletion holds either way, since Copilot's own fallback covers it. Deleted `.github/plugin/marketplace.json`, `scripts/sync-marketplace-mirror.sh` (81 lines), `tests/test-sync-marketplace-mirror.sh` (304 lines), and the `check-marketplace-mirror-sync` pre-push hook; removed the dangling references to the deleted script in `scripts/sync-plugin-content.sh` and `tests/test-sync-plugin-content.sh` (both had comments citing its reasoning by name), and updated `docs/spec/architecture.md`'s description of the marketplace-manifest compile step. `tests/test-sync-plugin-content.sh` (92 cases) still passes in full.
- [x] ~~`check-executables-allow-sync`: 474 lines to assert one string equals kyberforge's version. A six-line grep, or drop it (the failure mode is visible and recoverable).~~
> **Corrected then partially done (2026-09-13):** see commit `1b01e25` on `docs/simplification-audit`. Independent re-verification found "drop it" unsafe — ADR-0019's own Consequences section calls this failure mode *silent* and says a silent-staleness failure here is worse than the duplication the other gates catch, directly contradicting the finding's "visible and recoverable" claim. The hook stays. Shrunk `scripts/check-executables-allow-sync.sh` 231 → 222 lines by deduplicating two comment blocks that re-derived ADR-0019's own reasoning inline, replacing them with a pointer at the ADR. The dual-reader design (PyYAML plus a hand-rolled fallback, so a missing PyYAML can't silently skip the check) was found to be load-bearing, not redundant, and left intact; test file unchanged (behavior unaffected). All 23 test cases and the live pre-push hook run still pass.
Effort S each, M for the walk-up.
3. **Tests of the test harness: 1,090 lines testing 475 lines.** `test-run-tests.sh` and `test-run-bats.sh` defend "green either way" holes that exist only because the runners hand-roll TAP parsing and set-equality checks. Replace both runners with about 40 lines (`bats -r plugins` plus a parallel `find | xargs` over `test-*.sh`) and delete the meta-tests. `lib/batch-run.sh` stays; `sync-plugin-content.sh` sources it. Effort M.
> **Not proceeding (2026-09-13):** premise doesn't hold. A full read of both runners and both meta-tests found the "TAP-parsing/set-equality" logic is regression coverage for specific past incidents — a `BATS_FILE_FLOOR` hardcode once let deleted test files vanish silently ("155 tests, 0 failures" with 11 tests missing); a missing/broken `run-bats.sh` used to make the whole bats suite disappear with a green summary; a formatter change once reported "0 tests, 0 failures" as a pass. Replacing the runners as specified would delete exactly the guards against that failure class. No changes made. Re-scoping this would mean deciding, guard by guard, which are still worth keeping — a design decision, not a mechanical cleanup.
4. [x] ~~**`skill-frontmatter` is a 62-line bash script inlined in YAML** with its own 366-line test. `skill-size-check.sh` already parses the same frontmatter with PyYAML. Fold it in (about 15 Python lines), delete the inline hook, its test, and the 79 lines in `gates.md` arguing for the split. Effort S.~~
> **Done (2026-09-12):** see commit `c8a7c9e` on `docs/simplification-audit`. Added a ~20-line required-frontmatter check (`name`, `description`, `metadata.version` as three-part semver) to `scripts/skill-size-check.sh`, reusing the YAML mapping `description_value()` already parses. Removed the inline `skill-frontmatter` hook (~80 lines) from `.pre-commit-config.yaml` and deleted `tests/test-skill-frontmatter.sh` (366 lines). Removed the 79-line "the other hook on that scope" discussion from `docs/spec/gates.md` and its now-dangling cross-reference, replacing both with a one-line note of the fold; updated the pre-push hook counts there. Updated fixture builders in `tests/test-skill-size-check.sh`, `tests/test-adr0020-body-checks.sh`, `tests/test-adr0020-targets.sh`, `tests/test-adr0020-differential.sh`, and `tests/test-vale-hooks-consumer.sh` to carry valid `metadata.version` so the new check doesn't spuriously fail existing fixtures.
5. **`skill-size-check.sh` has six test files totalling 3,589 lines for one 1,497-line script**, split by ADR section rather than behaviour. `test-adr0020-differential.sh` is 452 lines for 12 assertions. Merge to two files. Effort M.
6. [x] ~~**Prose-grep tests.** `test-governance-layer.sh` and `test-instructions-and-docs.sh` (583 lines) grep markdown for phrases, including a one-shot "issue 0015 refactor incomplete" assertion made permanent and an assertion that `docs/notes/` exists. Delete both.~~ `check-apm-agents-valid.sh` (161 + 264 test lines) is a loop plus fail-closed guards around `validate.sh`; it folds into the merged audit skill's own tests (finding 14). Effort S.
> **Done (2026-09-12):** see commit `5f9f2b3` on `docs/simplification-audit`. Deleted `tests/test-governance-layer.sh` (270 lines) and `tests/test-instructions-and-docs.sh` (313 lines); no other file referenced either. `check-apm-agents-valid.sh` was left untouched — its fate is tied to the separate, out-of-scope skill-merge finding 14.
7. [x] ~~**`check-plugin-content-sync.sh` is 813 lines wrapping `apm pack`, with a 1,291-line test.** The mirror itself must stay (Claude Code marketplace installs need flat directories), and the script does real work a bare `git diff` would lose: it strips `tests/` from the mirror, regenerates both `plugin.json` files with `mcpServers` reinjected, and packs into a scratch copy so `--check` never mutates. Even so, 2,100 lines for that is disproportionate; target a third. Effort M.~~
> **Superseded then done (2026-09-14):** see commit `718c79a` on `docs/simplification-audit`. The recommendation ("target a third") is void, not met — the §8 question it depended on was settled the other way. Answering "apm-only" (ADR-0024) removed the mirror's reason to exist, and with the mirror gone the script guarded nothing, so the whole thing was deleted rather than shrunk: `scripts/sync-plugin-content.sh` (813 lines), `tests/test-sync-plugin-content.sh` (1,289 lines — the finding said 1,291), the `check-plugin-content-sync` pre-push hook, and `scripts/lib/marketplace-plugins.sh` (86 lines, whose only consumer was the sync script, and which finding 1 had explicitly kept alive for it). `validate-plugins` went with them, and the twelve per-plugin `plugin.json` manifests the script regenerated. The finding's own premise — "the mirror itself must stay" — is what turned out to be wrong.
8. **`docs/spec/gates.md` (1,048 lines) is roughly 15% "what is enforced" and 85% post-mortems** of defects already fixed and pinned by tests. The 60-line hook table is the useful part. Target 200 lines. The same applies to the 106 comment lines in `.pre-commit-config.yaml` and to `scripts/`, where 8 of 15 files are 40 to 60% comments. Effort M.
> **Partially done (2026-09-13):** see commit `a35f5e8` on `docs/simplification-audit`. The 85%-post-mortem characterization was stale — the file had already shrunk to 966 lines by other findings, and most of what remained is load-bearing "why this design" rationale cited by ADRs and tests, not dead incident narration. Cut only the two genuinely stale passages: a reproduction paragraph carrying explicitly outdated numbers, and a retrofit-process narrative superseded by current state — a 36-line cut, 966 → 930 as measured at commit `a35f5e8`. Those two figures describe that commit only, not the file: `718c79a` and later findings have edited `gates.md` again, so read its current length from the file rather than quoting a number here. `.pre-commit-config.yaml`'s comments were left untouched; on inspection they're compact constraint notes, not filler. Target of 200 lines not reached and not recommended — would require deleting content the file itself flags as load-bearing.
**Proposed target.** ~~Pre-push 14 hooks to 6: `run-tests`, `validate-plugins`, `validate-marketplace`, `apm-pack-check-clean`, `check-plugin-content-sync`, `check-release-needed`.~~
> **Corrected (2026-09-14):** two of the six named targets no longer exist — `validate-plugins` and `check-plugin-content-sync` were deleted in commit `718c79a` (finding 7, ADR-0024). Actual state today: **9 repo-authored pre-push hooks** — `run-tests`, `check-executables-allow-sync`, `apm-audit-ci`, `check-apm-agents-valid`, `apm-pack-check-clean`, `check-vale-style-sync`, `check-scope-walkup-sync`, `check-release-needed`, `validate-marketplace` — plus the 2 pre-commit `meta` hooks that also run at this stage, so 11 are reported at pre-push. `validate-marketplace` was kept: the root `marketplace:` block in `apm.yml` and the root `.claude-plugin/marketplace.json` stay, because apm's own marketplace consumers read that same catalogue and `<name>@holocron` short names depend on it. (That manifest is the only tracked file under `.claude-plugin/` — `git ls-files .claude-plugin` returns it alone. The sibling `.claude-plugin/plugin.json` is a local `apm pack` byproduct, has never been tracked on any branch, and is ignored at `.gitignore:59`; it was not "kept", because it was never there.)
Pre-commit stays roughly as is minus `skill-frontmatter`, and minus `check-ast` once finding 9 removes the only `.py` files. Tests 26 files to about 10 (12,400 to about 5,000 lines). Keep bats and its three submodules; the 351 bats tests ship inside plugins and are the right tool there. Do not port the bash suites to bats; delete them instead.
## 4. Plugins
The shared pattern: per-skill `README.md` files no model reads, a `docs/research/` dump per plugin, a `sources.md` provenance chain with its own validator, and reference files that restate man pages.
### 4.1 Cross-plugin (apply everywhere)
9. [ ] **Delete `docs/research/` from every plugin (~19,000 lines).** kyberforge's alone is 14,143 lines, 32% of the plugin, and about 8,900 of those are vendored third-party content (Anthropic `skill-creator` including a 1,325-line `viewer.html` and ten `.py` files, obra/superpowers, mattpocock). The rest is copied tool documentation. The gitea references explicitly say the research doc "has a known history of drifting from the deployed server". Every `apm.yml` uses `includes: auto`; whether the directory ships to consumers needs one check. Keep upstream URLs in one line per plugin README; git history keeps the rest. Check obra/superpowers licence if anything is retained. Goes together with finding 11: 32 `sources.md` files carry "Research doc" paths into these directories. Effort S.
> **Decision (2026-09-12):** Keep. `docs/research/` is retained on purpose — it's read by agents doing work sourced from those docs. Not proceeding.
10. [x] ~~**Delete per-skill `README.md` and `references/README.md` (48 files, 1,574 lines).** They restate the SKILL.md in narrative form. The pre-commit config itself notes a skill README "is consumer-facing prose that no agent ever loads". Keep one plugin-level README with one line per skill. Requires dropping the README criterion in `skill-audit/references/file-structure.md` and the README step in `new-skill.sh`. Effort S.~~
> **Done (2026-09-12):** see commit `edcc57c` on `docs/simplification-audit`. Deleted the 48 per-skill/reference READMEs plus 2 scaffold templates; dropped the README criterion from `skill-audit`'s `file-structure.md` and `finding-criteria.md` and the README-generation step from `new-skill.sh`; updated `new-skill.bats` to match. Plugin-root READMEs were kept, not part of this finding.
11. **Drop the provenance chain: `sources.md`, `source_keys` frontmatter, `validate-provenance.sh`.** 32 plugin and skill `sources.md` files (about 1,300 lines) plus 9 research indexes, 216 source files with `source_keys`, two copies of the validator (1,198 and 632 lines) with ten checks, and 125 bats tests exist to track which upstream informed which file. Git blame and a URL in the README do the same job. This is more code than the content it tracks. Effort M (touches skill-audit, both validator copies, two repo tests, and every skill's frontmatter).
12. [x] ~~**Strip ADR and changelog narration from model-facing files.** `ADR-0020` is cited in 3 of 7 kyberforge SKILL.md files and 16 references; ADR-0023 is cited inline 21 times in the git plugin. Examples: "was the old house rule and ADR-0020 deleted it", "were removed per ADR-0015 once issue #90 landed", "this file previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter". `skill-author/references/retrofit.md` (197 lines) is a one-time migration guide; it is loaded from `improve.md` and listed in `sources.md`, so remove those in the same change. These belong in git history or the ADR, not in context. Effort S.~~
> **Done (2026-09-12):** see commit `edcc57c` on `docs/simplification-audit`. Historical narration stripped from kyberforge (ADR-0020) and git (ADR-0023) skill content; `retrofit.md` deleted along with its load-step and `sources.md` entries. Caught in review: some `ADR-0023` tags were not narration but the `check-rtk-prefix` hook's required opt-out marker for intentionally-bare git commands — those 12 were restored, not left stripped.
13. [x] ~~**State repeated boilerplate once or delete it.** A near-identical "Resolve owner and repo" block in 5 of 7 gitea skills; 404-masks-403 in 6 files; manual pagination in 7; main/master refusal in 9 git files; the "use the project's domain glossary, respect ADRs" paragraph in 5 bin skills. Three git skills define three different structured-result JSON shapes whose only consumer is `git-orchestrate` (finding 19). Effort S.~~
> **Done (2026-09-12):** see commit `6cfc357`. Trimmed each repeated instance in place — same meaning, fewer words — rather than extracting to a shared file (blocked by the one-file-per-skill install constraint, ADR-0014): the "Resolve owner and repo" block across 5 `gitea-*` skills, the 404-masks-403 note across 6 gitea files, the manual-pagination explanation across 8 gitea files, the main/master force-push refusal across 7 git plugin files (some with multiple internal restatements), and the domain-glossary/ADR paragraph across 5 `bin` skills. This was a trim-in-place pass, not a merge: the cross-skill duplication itself remains and is coupled to the (out-of-scope) skill-merge findings 19/20. Left the three git skills' structured-result JSON shapes untouched, as directed. Verified no regressions with `scripts/skill-size-check.sh` (pre/post diff) and `claude plugin validate` on both plugins.
### 4.2 kyberforge (290 files, 44,568 lines incl. mirror; the 7 SKILL.md bodies are 333 lines, under 1%)
14. **Merge `skill-audit` + `agent-audit` into one `audit` skill (removes about 3,300 lines and two pre-push hooks).** `vale-wrap.sh` is byte-identical in both; five Vale rules byte-identical (agent-audit carries one extra, so it is the superset); `validate.sh` shares a 1,061-line boundary-target resolver block that diffs as zero lines; SKILL.md steps 1, 3, 4 and the gotchas are the same text. Each copy is hard-wired to one mode, so the merged script needs a path switch. The duplication exists because a plugin-cache install copies only each skill's own files (the rule ADR-0014 follows), so a script cannot be shared across skills; merging the skills is the only way to remove the copy. Effort M.
15. **Merge `skill-author` + `agent-author` likewise.** `contract.md` shares most of its Description section; `new-skill.sh` and `new-agent.sh` implement the same package-root walk-up with different mode names; step 1 dispatch tables and step 3 gates are near-identical. Keep the agent scope logic (plugin vs project/user) as its own reference. Effort M.
16. **Cut the validators by an order of magnitude.** `validate.sh` is 1,677 lines of bash with embedded Python, ported twice; `skill-size-check.sh` is 1,497. Target about 200 lines total: frontmatter present, size ceilings, boundary targets resolve. The 526-line `vale-wrap.sh` exists to work around folded `>` scalars in descriptions; writing descriptions as `|` literal blocks removes the folding problem, but the wrapper is also the exported hook entry in `.pre-commit-hooks.yaml` and carries the NOT RUN guard the audits depend on, so it shrinks rather than disappears. This is where the real complexity lives and is the item most worth discussing. Effort L.
17. **Fold `forge` and `apm-install`.** `forge` is a four-row routing table plus 207 lines of references explaining fork vs inline; it should be 25 lines with no references. `apm-install` (53 lines + 17-line sources) becomes a sixth dispatch row in `apm-workflow`. Effort S.
18. **Delete prose the model already knows.** "Valid characters: lowercase letters, numbers, hyphens"; what pipx does and PEP 668; "code blocks carry a language tag"; "data to stdout, diagnostics to stderr". Ironically `body-discipline.md` instructs auditors not to include "concepts the agent already knows". Effort S.
### 4.3 git and gitea (153 + 93 files, 9,889 + 6,047 lines incl. mirror; source 3,288 + 2,286)
19. **Delete the two router skills and two orchestrate agents (309 lines + 195 reference lines).** No skill invokes them as a step; they appear only in boundary clauses (`AGENTS.md`, `git-worktrees`, `gitea-issues`, `gitea-prs`) and as worked examples in agent-audit references, all of which must change in the same commit or `skill-size-check` fails on the dangling target. Claude Code already routes on descriptions. The chain today is `git-workflow` step 5 invokes `git-orchestrate`, whose step 5 invokes `git-commits`, which runs `rtk git commit`: three hops. Both agents exceed 900 words; ADR-0020 deliberately sets no agent body gate. Effort S.
> **Not proceeding (2026-09-13):** premise doesn't hold. There are no separate "router skills" — only two `.agent.md` files. `git-orchestrate` is not a dangling boundary-clause reference; it's `git-workflow` step 5's actual execution backend (documented both directions), so deleting it breaks `git-workflow`'s only execution path rather than tidying an orphan. `gitea-orchestrate` is intentional per ADR-0011 (agent-facing counterpart for agent callers) even though `gitea-workflow` doesn't call it. A third, undocumented instance of the same pattern (`apm-orchestrate`) exists and isn't addressed by this finding. The four boundary-clause locations named above don't actually reference either agent. No changes made. This needs the "short discussion" §7 bucket 2 implies, not a mechanical delete.
20. **Collapse git 7 skills to 1; gitea 7 to 2.** Git references are man-page restatement: `git-log-format.md` (242 lines listing `%H`, `%ar`), `conventional-commits-spec.md` (170 lines), `worktrees.md` (178), `merging.md` explaining fast-forward. Roughly 60% of the plugin is generic. The genuinely house-specific content fits in about 150 lines: the `rtk` rule and ADR-0023 exceptions, main/master refusal, `--no-verify`, the `-i --autosquash` 2.39.5 trap, `--force-with-lease --force-if-includes`, bisect exit codes, submodule push ordering, the detached-HEAD worktree trap. Gitea is more legitimately specific (MCP schema quirks: `tree_sha`, `withLines`, silent drops on PR create, `per_page` 20 vs 30, 404 means 403) and splits naturally into `gitea-tracker` (issues, PRs, labels, milestones) and `gitea-repo` (branches, files, releases). Risk: one description must carry all trigger phrases; keep a dispatch table at the top of the body. Keep `pc-author` and `pc-run` (finding 38). Effort M.
21. [x] ~~**Delete `config.example.json` / `.claude/plugins/git/config.json`.** Read by two steps, written by nothing. Default to GitHub Flow with the existing `develop` / `release/*` inference. Effort S.~~
> **Done (2026-09-12):** see commit `f5e4d0d`. Deleted `plugins/git/config.example.json` (the runtime `.claude/plugins/git/config.json` was never a tracked file). Removed the config-read step from `git-orchestrate`'s Process and from `git-branches`' Step 1, leaving the existing default-inference logic (GitHub Flow, with Gitflow inferred from a `develop`/`release/*` branch) as the sole path; updated `git-workflow`'s description of the orchestrator's behaviour to match. Dropped the now-dangling `applied_config` field from `git-orchestrate`'s output shape and the `config.example.json` example from `docs/spec/architecture.md`.
### 4.4 bin, core, lint (88 + 49 + 31 files incl. mirror)
22. **bin: strip generic process theatre.** `write-docs` is 109 lines, mostly form-filling sections plus a 15-line source provenance block; its rules fit in 25 lines. `tdd` is about 70% textbook (RED/GREEN diagram, "good tests are integration-style", five thin references restating textbook design advice). `diagnose` 40%, `prototype` 50% (pixel-level UI switcher spec), `grill-with-docs` 35%. Keep the opinionated parts: "no horizontal slicing", "no phase 2 without a loop", `[DEBUG-xxxx]` tags, "never infer the output path", the triage state machine. Effort M.
23. **bin: merge `grill-me` into `grill-with-docs`.** `grill-me` is 16 lines and a subset of the docs flow; `grill-with-docs` creates `CONTEXT.md` when missing, so the merged skill needs a no-write opt-out. `caveman` (50 lines) and `zoom-out` (9) are hand-invoked prompts rather than workflow skills; they are also the repo's `disable-model-invocation` exemplars in `CONTEXT.md`, `contract.md`, ADR-0020, ADR-0021, and `gates.md`, and `install.sh` has no path for `~/.claude/commands/`, so moving them means picking a new exemplar. `improve-codebase-architecture` defines its glossary twice (inline and in `language.md`; the README documents the split as intentional). Effort S.
24. **core: `provider-adapter-author` is a 1,200-line wrapper around one instruction** ("replace duplicated lines with `@AGENTS.md`, keep provider-specific lines"): a 496-line validator with a 519-line bats suite for a check that is a grep. `agentsmd-author` already calls `agentsmd-audit` as mandatory closeout, and both route to `provider-adapter-author` in boundary clauses that must change with it. Target: one `agentsmd` skill with an audit mode, adapter conversion as a step, validator about 40 lines. Needs an ADR-0012 revisit. Effort L.
25. **lint: delete the `lint-runner` agent.** Its body is "call `vale-run`, reformat output", which `--output=JSON` already gives; it exists for backends that do not exist. It is the example boundary clause in three `agent-author` templates and ADR-0016, so those need a new example. About 40% of `vale-config` is install tables and settings lists the model can fetch from vale.sh. Keep the house-verified matrices (`E100`/`E201`, `Packages` below glob, frontmatter, ignore paths). `lint/docs/research/docs/vale/` overlaps the skill's own references by about two thirds. Effort S.
## 5. Prose and docs (9,600 lines, 109,000 words outside plugins)
26. [ ] **Move or delete `docs/research/` and `docs/notes/` (4,500 lines, 47% of prose words).** Six of eleven research files are linked only from each other; they are self-described session audit trails, agendas, and a "temporary build reference". `docs/notes/factory-research-gaps-conflicts.md` says "Status: Superseded"; `factory-integration-decisions.md` says "Complete" and its decisions already live in ADRs, yet `AGENTS.md` tells every session to read it. `archive/team-self-organisation-sprint-brief.md` (3,400 words) is unrelated to this repo. Archive or delete; drop the three `AGENTS.md` pointers. Moving `CONTROLS.md` to `docs/spec/` means updating its literal path in nine or more files including the deployed `governance.md`. Effort S.
> **Decision (2026-09-12):** Keep. Same reasoning as finding 9 — these docs are intentional context for sourced work. Not proceeding.
27. **Four governance documents say one thing.** `core/instructions/governance.md` (949 words, always-on), `docs/ai-constitution.md` (2,906), `docs/wiki/HUMANS.md` (1,413), `CONTROLS.md` (1,224), with near-identical preambles and, in three of the four, a "what this file does not govern" block pointing at the others. The constitution repeats one of its own principle lead sentences. Keep `governance.md` as the operative file, trimmed to about 50 lines (drop the classification table that repeats the bullets above it, the footer, the non-governance block). Dedupe the constitution by about 20%. Effort M.
28. **ADRs: 2,740 lines, 72% in eight ADRs over 150 lines.** ADR-0020 is 513 lines with a 71-line measurement log as Context; ADR-0017 has 173 lines of amendments against 45 of decision. ADR-0001 is superseded and ADR-0006 moot, both keeping full text below the banner. ADR-0002 is three lines. Truncate superseded ones to the banner, fold amendments into the decision, cap Context at 20 lines, add a 25-line `docs/adr/README.md` index with status. The rules already live in `gates.md`; the ADRs need only decision and consequences. Effort M.
29. [x] ~~**The same facts are stated in full three or four times.** "Edit `.apm/`, never the mirror": README (2 paragraphs), AGENTS.md (2 paragraphs), architecture.md (2 paragraphs plus the lost-README anecdote), ADR-0017. The apm.lock / SessionStart story: README (11 lines), AGENTS.md, ADR-0018, ADR-0019, gates.md. The offline `SKIP=` command and the three-stage install each appear three times. Rule: README has the how-to, AGENTS.md has one-line rules with links, architecture.md has mechanics. Effort S.~~
> **Corrected then partially done (2026-09-14):** independent re-verification found the "edit `.apm/`, never the mirror" and apm.lock/SessionStart clusters confirmed but the third overstated — no file documents an offline `SKIP=` command (the one `SKIP=`-adjacent mention in `gates.md` explicitly says a *different* opt-out "is not `SKIP=`"), and "three-stage install" appears twice, not three times, with no restatement worth trimming. Trimmed the two confirmed clusters: README's "Editing plugin content" and AGENTS.md's "Edit `.apm/`, never the flat mirror" sections cut to the how-to/one-line-plus-link split the finding itself proposed, full mechanics (the `rm -rf` behavior and the `plugins/kyberforge/hooks/README.md` anecdote) staying solely in `docs/spec/architecture.md`. README's "Keeping the install current" and AGENTS.md's apm.lock bullet trimmed to drop the restated `apm outdated`/`apm update --yes` timing narrative, pointing to ADR-0019 as the canonical mechanism instead. No test greps the trimmed wording (checked).
30. [x] ~~**`LESSONS.md`: 41 entries, 2 graduated, about 12 stale.** Twelve entries from 2026-05-17 describe a write-skill / write-eval workflow whose skills no longer exist. One entry is open work labelled "Status: neither part landed". The longest eight are 200 to 550-word incident reports. Delete the stale entries, move open work to an issue, cap entries at about 60 words, target 100 lines. Effort S.~~
> **Done (2026-09-12):** see commit `629320b` on `docs/simplification-audit`. 255→131 lines, 41→30 entries. Kept 3 of the same-dated entries (RLHF defaults, secrets-rule gap, HITL gap) — judged unrelated to the defunct write-skill/write-eval workflow and still applicable, so 10 deleted rather than 12. The "neither part landed" open-work entry (CONTEXT.md not `@import`ed at session start) was removed rather than filed as an issue — full text preserved in this session's transcript if wanted later.
31. [x] ~~**`CONTEXT.md`: 28 terms, most used only by gates.md, scripts, or tests rather than by skills;** two (Preload tax, Skill context contract) are never used outside `CONTEXT.md` and ADR-0020. The preload-tax entry quotes two dated numbers then says not to quote them. The example dialogue and flagged-ambiguities sections are grill residue. Cut to about 20 one-line terms. Effort S.~~
> **Corrected then done (2026-09-13):** see commits `124ce6e` and follow-up on `docs/simplification-audit`. Independent re-verification found "most used only by gates.md/scripts/tests" overstated: 13 of 28 terms are actually referenced from model-facing `references/*.md` files skills load in normal use (Routing target, Hand-invoked skill, Dispatch body, Near-miss, Thin adapter, Provenance chain, Output profile, apm package, Plugin marketplace, HITL, Skill composition, Delegation discipline, holocron) and were kept untouched. Only the 9 terms confirmed as true orphans were removed after a fresh independent grep: Content mirror, apm-consumed install, Vale audit prefilter, Vacuous green, Management Application, Sycophancy, HOTL, Preload tax, Skill context contract — 28 → 19 terms. The preload-tax self-contradiction (quotes 23,427/10,478-char figures then says not to quote either) was confirmed verbatim and resolved by the entry's own deletion. The "example dialogue" and "flagged ambiguities" sections were found to be mandated by `grill-with-docs/references/context-format.md`'s template spec, not grill residue — left untouched, except one dangling bolded cross-reference to the now-deleted "Preload tax" term in a Flagged-ambiguities line, which was unbolded/de-referenced in place (the ambiguity resolution itself still holds without a defined glossary entry to point at).
32. **Structure is described three ways** (README layout table, architecture.md plugin table, AGENTS.md structure bullets), and `VISION.md` carries a 35-line stack spec for a product that lives in another repo. One layout table in README; architecture.md keeps mechanics only; VISION drops the stack detail. Effort S.
## 6. Distribution, versioning, and session startup
Not covered by the area audits above; found on a final sweep of the root config and install pipeline. The install pipeline itself (`scripts/install.sh` 55 lines, `deploy-manifest.sh` 24, statusline 109) is fine and needs nothing.
33. **Every plugin version lives in four places (five for kyberforge), plus one per skill.** `plugins/<name>/apm.yml`, two generated `plugin.json` files, the root `apm.yml` packages list, the `executables.allow` key (`kyberforge#1.6.2`), and a `metadata.version` in all 39 SKILL.md files (ADR-0022) that nothing consumes and that drifts freely (gitea skills sit at five different values). Repo tags (`v2.0.1`) follow a third scheme that the declared `tagPattern: v{version}` can never match under `per_package` versioning. ADR-0006, ADR-0022, `check-executables-allow-sync`, `skill-frontmatter`, and `apm pack --check-versions` all exist to police this. Proposal: one version per plugin in its `apm.yml`; drop `metadata.version` and ADR-0022; let `apm pack` derive the rest. Effort M.
> **Partially advanced (2026-09-14):** see commit `718c79a` on `docs/simplification-audit`. Two of the four locations per plugin are gone: the twelve generated `plugin.json` manifests (`plugins/*/.claude-plugin/` and `plugins/*/.github/plugin/`) were deleted with the mirror. ADR-0006 needed no action — it was already moot and governed only those two now-deleted manifests, so no version bumps were required by the change. **Not closed.** Still outstanding: `plugins/<name>/apm.yml`, the root `apm.yml` packages list, the `executables.allow` pin, and `metadata.version` in all 39 SKILL.md files (still unconsumed, still drifting), plus ADR-0022 and the `v{version}` `tagPattern` mismatch.
34. **The SessionStart hook auto-updates the install on every startup.** `check-apm-current.sh` runs `apm outdated` (network, 60 s timeout) and then `apm update --yes` (300 s timeout) at every session start, rewriting `apm.lock.yaml`. That is why the lock file is dirty at the start of this session and why `AGENTS.md` has to explain "commit or discard it deliberately". It is a 60-line script with a 368-line test, an ADR (0019), the `executables.allow` pin, and a sync hook behind it. For a repo that is its own source, the update belongs in `install.sh` or a manual `apm update`, not in session startup. Effort S to remove; the design question is whether auto-update at startup is wanted at all.
35. [x] ~~**Outputs and packages for consumers that do not exist.** The `codex` output profile generates `.agents/plugins/marketplace.json` (95 lines) although Codex is not a supported consumer. The `mattpocock-skills` remote package entry is the only reason `apm-marketplace-check` needs the network, and its pin is advanced by hand (ADR-0015). The `.github/plugin/marketplace.json` mirror is a legacy path (finding 2). Removing all three leaves one generated marketplace manifest (the per-plugin `plugin.json` pairs remain) and no network-dependent hook. Effort S.~~
> **Done (2026-09-13):** see commit `568ca74` on `docs/simplification-audit`. Removed the `codex` output profile from root `apm.yml` and its compiled `.agents/plugins/marketplace.json` (95 lines), and the `mattpocock-skills` remote package entry — the only remote marketplace entry, so `apm-marketplace-check` and `apm-pack-check-clean` no longer need network access at all. Updated `README.md`, `AGENTS.md`, `docs/spec/gates.md`, and `docs/spec/architecture.md` accordingly; added one-line superseded/updated notes to ADR-0015 and ADR-0021. Left `.github/plugin/marketplace.json` untouched — that's the Copilot legacy-path question in finding 2/§8, out of scope here; only re-ran the sync script to keep it consistent. `apm.lock.yaml` unaffected (`marketplace.packages[]` isn't part of the lockfile). Verified via `apm install`, `apm pack --marketplace=claude --check-versions`, and all four affected pre-push hooks.
36. **The release-tag mechanism guards an external contract with no known consumer.** `.pre-commit-hooks.yaml` exports three hooks for other repos to pin by `rev: <tag>`. `check-release-needed` (242 lines + 442 test), `test-vale-hooks-consumer` (270 lines), ADR-0014, and three tags exist to serve that. If no other repo pins these hooks today, the whole mechanism can be deferred until one does. Effort S.
37. [x] ~~**Two `.mcp.json` files declare an Obsidian vault server over `docs/`** (root and `plugins/bin/`; the other five plugin `.mcp.json` files are empty stubs), while `AGENTS.md` forbids using an external memory system for this repo. If the Obsidian tools are unused, drop both and the `reinject_mcp_servers` explanation in the bin README; the bin `plugin.json` pair regenerates. Effort S.~~
> **Not proceeding (2026-09-13):** premise doesn't hold. The server exposes the repo's own git-tracked `docs/` folder — not an external/off-repo store — so it isn't the "external memory system" AGENTS.md's rule targets. It was deliberately added and versioned (3 commits), is documented as current intended behavior in both READMEs, and ADR-0018 uses it as its only concrete worked example of apm's MCP-dependency propagation mechanism actually working. No skill invokes the Obsidian tools as a workflow step, but that alone doesn't make the config dead. No changes made; recommend a human confirm whether the vault tooling is still wanted before removing it.
> **Confirmed and done (2026-09-14):** the human confirmed the vault tooling is not wanted — remove it entirely. All seven `.mcp.json` files deleted (the six plugin-root files and the repo-root one), and the repo-root path added to `.gitignore` so a local `apm` run cannot recreate it as tracked content. The bin README's `reinject_mcp_servers` explanation goes with it; the `plugin.json` pair the finding expected to regenerate no longer exists (deleted in `718c79a`, finding 7).
>
> What made this urgent is the substantive discovery, not the tidying: **deleting the per-plugin `plugin.json` manifests in `718c79a` had already broken MCP propagation silently.** `apm_cli/deps/plugin_parser.py` maps a plugin-root `.mcp.json` → `.apm/.mcp.json`, and that code path runs only for *marketplace* plugins — with no manifest, apm never reads the file. `plugins/bin/apm.yml` declares `dependencies.mcp: []`, so the supported mechanism was never used either. Proved on ref-pinned consumer clones: at the parent commit a consumer gets an `obsidian` server, at HEAD it gets none, and on upgrade apm prints `Removed stale MCP server 'obsidian' from .mcp.json` — which would in time have stripped the server from this repo's own tracked `.mcp.json` once the lock re-resolved. Deleting the files makes the intent match the behaviour instead of leaving a config that silently does nothing.
38. [x] ~~**`pc-author` / `pc-run` (689 lines) carry generic pre-commit documentation.** `hooks-by-language.md` (128 lines) and `failure-patterns.md` (133) restate pre-commit.com. Keep the skills, trim to the house-specific rules. Effort S.~~
> **Corrected then done (2026-09-13):** see commit `a622200` on `docs/simplification-audit`. Independent re-verification found the 689-line figure overstated (actual combined size 598 lines) and the realistic cut smaller than a rewrite (~60-85 lines, concentrated in the two named reference files, not the SKILL.md files or the four short flow files, which are house-specific gates rather than restatement). Landed within that range: `hooks-by-language.md` 128 → 92 lines (collapsed six per-language tables repeating the same repo/rev/rationale into one shared-repo table plus a small other-repos table); `failure-patterns.md` 133 → 109 lines (removed generic SSH/proxy and shellcheck SC-code restatement, compressed generic schema-error bullets). Kept verbatim: both "Unverified — not in research corpus" flags, the rev-freshness caveat, the `rtk git add -u`/`rtk git commit` fix (ADR-0023), and the `pre-commit install -f` warning. Combined cut: 60 lines. Flat mirror regenerated and verified byte-identical.
## 7. Suggested order
1. Quick wins, all S, no design decisions needed: findings 9, 10, 26, 30, 31, 29, 12, 13, 1, 6, 4, 35, 37, 38, and the mirror-sync and executables-allow halves of 2. Removes roughly 25,000 to 30,000 lines and 6 hooks.
2. Structural changes that need a short discussion: 14, 15, 19, 20, 23, 25, 17, 3, 5, 7, 33, 34, 36.
3. The real complexity: 16 (validators), 11 (provenance), 24 (core), 8 and 28 (gates.md and ADRs).
Findings 9, 10, 11, and 12 are coupled through the provenance validator and the audit criteria; land them together or the audit gates start reporting the removals.
## 8. Questions to settle before starting
- [x] ~~**Native Claude Code marketplace install vs apm-only.** The flat mirror, `check-plugin-content-sync`, and ADR-0017 exist only for native `claude plugin install`. If apm install is the only supported path, the mirror and its 2,100 lines of tooling go away. Which install paths must work for consumers?~~
> **Answered (2026-09-14):** apm-only. See ADR-0024 (`docs/adr/0024-apm-is-the-only-supported-install-path.md`) and commit `718c79a` on `docs/simplification-audit`. Native `claude plugin install` support is dropped; the flat mirror, the twelve per-plugin manifests, `sync-plugin-content.sh`, its test suite, `lib/marketplace-plugins.sh`, and the `check-plugin-content-sync` and `validate-plugins` hooks are all deleted (245 files changed, −22,602 lines). ADR-0017 carries a superseded banner. Kept deliberately: the root `marketplace:` block and the root `.claude-plugin/marketplace.json`, which apm's own consumers read. (`marketplace.json` is the only tracked file under `.claude-plugin/`; the root `plugin.json` beside it is untracked local `apm pack` output, ignored at `.gitignore:59`.) This answer is what voided finding 7's recommendation and closed §3's `check-plugin-content-sync` target.
- **Copilot CLI legacy path.** Is `.github/plugin/marketplace.json` still read by any Copilot version you target? If not, finding 2c is a pure delete.
- **Provenance chain.** Is "which upstream informed this file" a requirement you still want, or was it a governance experiment? Finding 11 hinges on this.
- **ADR-0012 (three core skills) and the one-script-per-skill install constraint.** The merges in 14, 15, and 24 need the first revisited and are the only way around the second. Are you open to superseding ADR-0012?
- **Granularity of git/gitea skills.** One `git` skill vs seven trades routing precision for size. Is one broad description acceptable?
- **Auto-update at session start.** Do you want the install refreshed from the remote every time a session opens (finding 34), or is a manual `apm update` acceptable?
- **External hook consumers.** Does any other repo pin this repo's `.pre-commit-hooks.yaml` by tag today? If not, finding 36 defers the release mechanism entirely.
- [x] ~~**Obsidian MCP.** Are the Obsidian tools over `docs/` used by anyone? If not, finding 37 is a pure delete.~~
> **Answered (2026-09-14):** not used — remove entirely. All seven `.mcp.json` files are deleted and the repo-root path is gitignored; see finding 37, which also records the functional regression this uncovered (since `718c79a` deleted the per-plugin manifests, apm no longer propagated the server to consumers at all).
## 9. Carried forward from the apm-only decision (2026-09-14)
Recorded here so they are not rediscovered as defects. All follow from commit `718c79a` / ADR-0024.
**Two accepted residuals.**
- **Native install still half-works, and cannot be prevented.** apm reuses Claude's catalogue format by design, so a Claude Code user can still register holocron natively and will install six plugins containing zero skills. Accepted, not overlooked: no schema change closes this, because the format that makes it possible is the format apm's own consumers need.
- **Consumers now receive test fixtures.** apm installs from `.apm/`, which carries the `tests/` directories the mirror used to strip, so a consumer installing from this branch receives **10 `.bats` files across 6 skills**, plus those skills' 6 `tests/README.md` files — 16 files. (Repo-wide, 17 tracked paths contain `/tests/`: the 10 `.bats` and 7 `README.md`, one of which is a template asset under `skill-author/assets/templates/tests/` and is not a test fixture.) This is what consumers *receive*, not what this checkout shows: `.claude/skills/` here currently holds zero `.bats` files, because that deployed tree is stale and predates this branch. The mechanism was confirmed empirically on a ref-pinned consumer clone — the 16 files are absent at the parent commit and present at HEAD. Suppressing them means switching all six `apm.yml` files from `includes: auto` to explicit lists, where a wrong list silently drops content — worse failure mode than the noise. Deferred deliberately.
**Negative result — do not re-litigate.** Deleting native install does *not* relax the self-containment constraint. `plugins/kyberforge/.apm/skills/skill-author/references/deployment-modes.md`, sourced from the agentskills.io spec, states it independently for APM package mode: the spec defines no cross-skill sharing. So findings 14 and 15 still require *merging* skills; sharing one file between two skills remains impossible, and §8's "one-script-per-skill install constraint" bullet is unchanged by this decision.
**Accepted gap — symlinks under `.apm/`.** ADR-0017's `check_apm_symlinks()` was the only thing reporting that symlinks under `.apm/` do not survive to a consumer. It is gone, and no replacement guard is being added — the human decided to accept the gap.
The mechanism is not the bundle exporter, as ADR-0017 assumed; it is the **install** path, and it has since been verified. `apm_cli/security/gate.py`'s `ignore_non_content()` is a `shutil.copytree` ignore callback whose docstring says "Excludes symlinks (security)"; it is used at `apm_cli/integration/skill_integrator.py:424`, `:791` and `:1152`. Materialization into `apm_modules/` dereferences first, so symlinked content survives *there* and is dropped when skills are deployed out of it. ADR-0024 flagged the prediction as unverified; it holds, with that corrected attribution. No symlinks exist under any `.apm/` today, so nothing is broken now — but the next one added there will silently not reach consumers, and nothing will say so.

1142
apm.lock.yaml
View File

File diff suppressed because it is too large Load Diff

30
apm.yml
View File

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

7
docs/adr/0001-skills-in-agents-dir.md
View File

@@ -5,9 +5,10 @@ as this repo's authoring source of truth) and, for plugin-scope agent files spec
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.
and `.claude-plugin/plugin.json`/`.github/plugin/plugin.json` were compiled output of `apm pack`,
not hand-authored — and as of ADR-0024 (2026-09-14) both are deleted, along with native
`claude plugin install` support; `apm install` is the only route. This ADR's content is kept
below as the historical record of the pre-APM decision; it is no longer the current model.
---

5
docs/adr/0006-plugin-version-parity.md
View File

@@ -11,6 +11,11 @@ divergence is no longer possible by construction. `plugin-author`, the skill tha
invariant, is deleted per ADR-0015 rather than adapted. Kept below as the historical record of
the pre-APM decision.
**Fully void as of ADR-0024 (2026-09-14).** Both manifests are now deleted outright, so the two
files this ADR was about no longer exist in any form, compiled or hand-authored. `apm.yml`'s
`version:` is the only version field a plugin has. This ADR states no patch-bump rule and never
did — ADR-0015 retired that rule explicitly; do not cite this ADR as the source of one.
---
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.

8
docs/adr/0011-gitea-skill-deep-modules.md
View File

@@ -67,6 +67,14 @@ than being wired into the plugin manifest. This means the gitea plugin is not ye
standalone via `claude plugin install gitea@holocron` without manual MCP setup. A follow-up Gitea
issue tracks closing this gap.
**Correction (2026-09-14):** this gap is now closed by removal rather than by wiring. ADR-0024
made apm the only supported install path, so `claude plugin install gitea@holocron` is no longer
a route this repo supports, and the per-plugin manifests it needed are gone. Because apm reads a
plugin-root `.mcp.json` only on the marketplace-plugin code path, that file became unreadable;
every `plugins/*/.mcp.json` was deleted, including this one. A plugin that needs an MCP server
declares it in `dependencies.mcp` in its `apm.yml` — the supported mechanism, which this repo has
never used. The follow-up issue this paragraph anticipates is moot.
**Research backfill.** The existing research docs
(`plugins/gitea/docs/research/docs/gitea/`) are 100% code-derived from gitea-mcp source with zero
external/best-practice content (the original docs.gitea.com fetch timed out and was never

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

@@ -22,8 +22,10 @@ spec-governed content, and `plugin.json` is JSON, not prose Vale can meaningfull
**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`
`skill-frontmatter` (required frontmatter fields), `validate-marketplace`
(`claude plugin validate --strict`, schema), and `gitleaks`/`detect-private-key` (secrets).
(ADR-0024 removed the companion `validate-plugins` gate along with the per-plugin manifests it
checked; the argument here is unaffected.)
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`

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

@@ -115,6 +115,9 @@ doesn't wonder if it was overlooked.
- `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.
**Amended 2026-09-14 (ADR-0024):** a record of what was done then, not current practice. Both
manifests are deleted and `apm.yml`'s `version:` is a plugin's only version field; ADR-0015
retired the parity/patch-bump rule this bullet invokes.
- **`.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

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

@@ -169,7 +169,10 @@ correction) sorted what they document into three buckets:
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`).
`git ls-remote`, which is why two pre-push hooks needed the network (see `AGENTS.md`).
**Superseded 2026-09-13:** the `mattpocock-skills` entry has been removed from root `apm.yml`
entirely, along with the `codex` marketplace output profile. No pre-push hook needs the network
any longer.
- **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
@@ -177,4 +180,7 @@ correction) sorted what they document into three buckets:
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.
the root cause and the fix. **Superseded 2026-09-14:** ADR-0024 deleted that mirror and its
generator along with native `claude plugin install` support. The discoverability gap this
paragraph describes is therefore no longer bridged — it is no longer a gap this repo has, because
apm is now the only supported install path and apm reads `.apm/` directly.

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

@@ -1,5 +1,17 @@
# Plugin roots gain a compiled flat-directory mirror of `.apm/` content so Claude Code can discover it
**Superseded by:** ADR-0024 (apm is the only supported install path; the flat content mirror is
deleted). The mirror this ADR created — `plugins/<name>/{skills,agents,hooks}/` — has been deleted,
along with `scripts/sync-plugin-content.sh`, its test suite, and the `check-plugin-content-sync`
pre-push gate. Native `claude plugin install` is no longer a supported path, so the host discovery
contract this ADR bridged is no longer one this repo satisfies. The diagnosis below is still
accurate about how Claude Code's installer works; what changed is that nothing consumes it. The
`mcpServers`, `hooks`-pointer and `hooks/hooks.json` amendments below are moot with the artifacts
they governed; the symlink amendment's underlying gap is not — see ADR-0024's consequences. This
ADR's content is kept below as the historical record; it is no longer the current model.
---
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

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

@@ -5,6 +5,16 @@ authored `.apm/` tree discoverable by hosts that install natively. Both are abou
marketplace. This ADR is about consuming it: how the plugins get onto the machine this repo is
worked on.
**Correction (2026-09-14): the flat content mirror named above no longer exists.** ADR-0017 is
superseded by ADR-0024, and commit `718c79a` deleted the mirror
(`plugins/<name>/{skills,agents,hooks}/`) along with its generator, its test suite and its pre-push
gate; native `claude plugin install` is no longer a supported path, so there are no longer "hosts
that install natively" for it to serve. Nothing this ADR decides depends on the mirror — it appears
here only as the other half of "producing the marketplace", and once more under "Install output is
gitignored" below, where the two copies of plugin content ADR-0017 governed are now one, `.apm/`
itself, and committing the deployed skills would make a second rather than a third. Read both
mentions as historical.
**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.
@@ -121,6 +131,19 @@ unprompted. The `gitea` and `context7` servers were never plugin-provided — th
apm's "contributed no entries to claude settings; skipped" warning on `kyberforge` and `lint` is
accurate and harmless.
**Correction (2026-09-14): the MCP propagation above stopped operating, and the files it read are
deleted.** It ran on one code path only — `apm_cli/deps/plugin_parser.py` maps a plugin-root
`.mcp.json` onto `.apm/.mcp.json` for packages apm treats as *marketplace plugins*. Commit
`718c79a` (ADR-0024) deleted every `plugins/*/.claude-plugin/plugin.json` and
`plugins/*/.github/plugin/plugin.json`, so each package is now a plain apm package and that path no
longer runs. The supported declaration was never in use either: `plugins/bin/apm.yml` has
`dependencies.mcp: []`. That left the six plugin-root `.mcp.json` files dead config — five of them
empty stubs, only `plugins/bin`'s carrying the `obsidian` server — and all six are now deleted along
with the server itself, which is not wanted. The repo-root `.mcp.json` was apm's own generated
output that happened to be tracked; it is deleted and gitignored, on the same reasoning as
`.claude/skills/`. The rest of this paragraph is unaffected: `gitea` and `context7` were never
plugin-provided, and the hooks claim never depended on any of this.
**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

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

@@ -105,6 +105,15 @@ resolves to the mirror, where the script does not exist — verified, apm report
`plugins/kyberforge/hooks/` either: that directory is `rm -rf`'d by every content sync (ADR-0017).
A test pins the reference.
> **Amendment (2026-09-14) — the mirror half of that reasoning is gone; the conclusion is not.**
> ADR-0024 deleted the flat mirror and `scripts/sync-plugin-content.sh`, so neither the `apm pack`
> mirror-filtering behaviour nor the `rm -rf` content sync described above still happens. The
> reference must stay exactly as written, for the reason that survives independently: `.apm/` is the
> sole hand-edited authoring source (ADR-0015), it is what ships in the installed package root, and
> `plugins/kyberforge/hooks/` no longer exists at all — so `${CLAUDE_PLUGIN_ROOT}/hooks/...` still
> names a path with nothing at it, now because the directory is gone rather than because a sync
> emptied it. `tests/test-apm-current-hook.sh` still pins the literal string.
**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:

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

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

9
docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md
View File

@@ -14,8 +14,9 @@ A plugin's published description is one string authored twice — in `plugins/<n
the matching `marketplace.packages[]` entry of the root `apm.yml` — and compiled into four generated
files per plugin edit: the plugin's `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`,
plus the repo-wide `.claude-plugin/marketplace.json` and its `.github/plugin/marketplace.json`
mirror. (`.agents/plugins/marketplace.json`, apm's codex profile, carries no per-package
`description` or `version` at all and is unaffected.) It is the only text a consumer sees in a marketplace listing before
mirror. (`.agents/plugins/marketplace.json`, apm's codex profile, carried no per-package
`description` or `version` at all and was unaffected — that file and the profile producing it were
removed 2026-09-13; see the note below.) It is the only text a consumer sees in a marketplace listing before
installing. It is **not** a SKILL.md `description`: it is never preloaded into an agent's context and
routes nothing at runtime. ADR-0020 governs that other artifact; this one governs this one. The
overlap is a finding, not a scope: ADR-0020 established that capability enumeration in a description
@@ -95,6 +96,10 @@ This decision covers the six plugins this repo authors. The root marketplace als
`mattpocock-skills`, a third-party package whose description is not this repo's to write; its entry
is out of scope and is left as published upstream.
*(Note, 2026-09-13: `mattpocock-skills` has since been removed from the root marketplace. This
section's scope statement is retained as the reasoning behind the boundary; the entry it describes
no longer exists.)*
## Decision
**A plugin's published `description` states the plugin's domain boundary. It does not enumerate the

78
docs/adr/0022-skill-metadata-version-is-mandatory.md Normal file
View File

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

168
docs/adr/0023-rtk-prefix-marks-executable-commands-only.md Normal file
View File

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

259
docs/adr/0024-apm-is-the-only-supported-install-path.md Normal file
View File

@@ -0,0 +1,259 @@
# apm is the only supported install path; the flat content mirror is deleted
**Supersedes ADR-0017** (plugin roots gain a compiled flat-directory mirror of `.apm/` content so
Claude Code can discover it). ADR-0017's diagnosis was correct and is not in dispute: Claude Code's
native installer convention-scans flat `skills/`/`agents/`/`hooks/` directories at the plugin root
and has no model of `.apm/` at all, so without a mirror a natively-installed holocron plugin reports
`Skills (0) Agents (0) Hooks (0)`. What changes here is not the mechanism but the premise — that the
native install path is worth supporting. It is not, because nobody uses it.
**Status: accepted (2026-09-14).** The mirror, its generator, its test suite, its helper library and
its pre-push gate are removed. `.apm/` remains the sole hand-edited authoring source, unchanged from
ADR-0015. The root `marketplace:` block in `apm.yml` and the compiled
`.claude-plugin/marketplace.json` it produces are **kept** — see "Also delete the marketplace
catalogue" under considered options.
## Context
ADR-0018 moved this repo's own consumption of its own plugins onto `apm install`. From that point
the flat mirror had no consumer inside this repo: it existed entirely for a hypothetical third party
running `claude plugin install <name>@holocron`. No such consumer has ever been observed. The
marketplace is on a private Gitea instance, and the repo has no telemetry, no issue traffic and no
external clone record suggesting otherwise. The honest statement is that the native path has been
maintained for an audience of zero.
What that audience costs is measurable:
| Artifact | Size |
|---|---|
| Tracked mirror files under `plugins/*/{skills,agents,hooks}/` | 213 files, ~20,000 lines |
| `scripts/sync-plugin-content.sh` | 813 lines |
| `tests/test-sync-plugin-content.sh` | 1,289 lines, 92 cases, ~83 s |
| `scripts/lib/marketplace-plugins.sh` | helper, used only by the above |
| `check-plugin-content-sync` pre-push hook | ~4.5 s per push |
| `validate-plugins` pre-push hook | ~4.9 s per push (6 × `claude plugin validate --strict`) |
Roughly 22,000 lines of tracked content and tooling, and about 92 seconds on every push (83 + 4.5 +
4.9; the two hook timings are the 2026-09-10 baseline measurements recorded in
`SIMPLIFICATION-AUDIT.md`, not re-measured here). The test alone is close to 30% of `run-tests`'
wall time — the single largest item in it.
**The native path's automated gate does not gate anything.** ADR-0017 cites
`claude plugin validate --strict` passing on all six plugins as one of two verifications. That
verification was re-run this session against a plugin directory with **every content directory
deleted**, and it passed. `validate` reads the manifest; it never inspects content. It therefore
cannot detect the exact `Skills (0) Agents (0) Hooks (0)` defect ADR-0017 was written to fix. The
other half of ADR-0017's verification — the live behavioral test
(`claude --plugin-dir plugins/kyberforge -p "list your skills and agents"`) — is a manual step,
run by hand once in August 2026 and never since. So native-install correctness has been unguarded
for a month, and the drift gate that runs on every push guards only that the mirror matches `.apm/`,
not that the mirror works.
**Dropping native install does not reduce host coverage.** This is the fact that makes the decision
cheap rather than a trade. apm's skills convergence deploys skills to `.agents/skills/<name>/SKILL.md`,
the shared path read by Copilot, Cursor, Codex, Gemini, OpenCode and Windsurf, with Claude Code as
the special case at `.claude/skills/`. The mirror served two hosts (Claude Code and Copilot, the
latter only ever partially — see ADR-0017's own `hooks` amendment). apm serves eleven through those
two roots: ten targets resolve to `.agents/skills/` — the six named above plus `agent-skills`,
`antigravity`, `hermes` and `openclaw`, which are rooted there natively rather than by an explicit
`deploy_root` — and `claude` is the eleventh at `.claude/skills/`. Four further targets (`kiro`,
`grok-build`, `grok-cloud`, `copilot-cowork`) deploy skills under roots of their own, for fifteen in
total; counted from `apm_cli/integration/targets.py` this session. A consumer who installs holocron
through apm gets strictly more than one who installed it natively.
**Verified empirically, not reasoned about.** In a scratch clone with the mirror and the six
per-plugin manifest pairs deleted:
- `apm marketplace add` still registers all 6 packages. It detects
`.claude-plugin/marketplace.json` and reads the catalogue from there.
- `apm install` still deploys 40 `SKILL.md` files across 39 skill directories, 4 agents, and
kyberforge's `SessionStart` hook — identical to the baseline install from the unmodified tree.
- `apm pack --check-versions --check-clean --dry-run` exits 0 ("Version alignment OK",
"Marketplace working tree clean"), because it governs only the **root** `.claude-plugin/` outputs.
The six per-plugin `plugin.json` pairs were never apm-pack-governed: they were generated by
`apm pack --format plugin` invoked from inside `sync-plugin-content.sh`, so deleting the script
deletes their producer and nothing is left asserting they should exist.
**Source-level proof the per-plugin manifests are droppable.**
`apm_cli/deps/github_downloader_validation.py` probes package markers in a fixed order —
`apm.yml`, then `SKILL.md`, then `plugin.json`, then `.github/plugin/plugin.json`, then
`.claude-plugin/plugin.json` — and returns on the first hit. Every plugin here keeps its `apm.yml`,
which is the first probe, so no `plugin.json` path is ever reached. The per-plugin manifests are not
load-bearing for apm resolution; they were load-bearing only for the native installer.
## Decision
**apm is the only supported install path.** Concretely:
- Delete the flat mirror at every plugin root (`plugins/<name>/skills/`, `agents/`, `hooks/`) and
the six per-plugin manifest pairs (`.claude-plugin/plugin.json`, `.github/plugin/plugin.json`).
- Delete `scripts/sync-plugin-content.sh`, `tests/test-sync-plugin-content.sh`,
`scripts/lib/marketplace-plugins.sh`, and the `check-plugin-content-sync` pre-push hook.
- Delete the `validate-plugins` pre-push hook (`claude plugin validate --strict` over every plugin
directory). It is removed on the evidence above — it reads manifests only, so with the per-plugin
manifest pairs gone it has nothing left to read, and even while they existed it could not detect
the empty-content defect. `validate-marketplace`, which validates the one manifest this repo still
ships, is **kept**.
- **Keep** the root `marketplace:` block in `apm.yml` and the compiled
`.claude-plugin/marketplace.json`. apm's own marketplace consumers read that same file; removing
it would stop holocron being an apm marketplace at all.
The asymmetry between those last two bullets is the whole subtlety of this ADR, and it exists
because apm deliberately reuses Claude Code's catalogue format rather than inventing one. The
catalogue is shared between the two ecosystems; the per-plugin content contract is not. Deleting the
content is what ends native support; keeping the catalogue is what preserves apm support.
## Considered options
**Status quo — keep mirroring on every branch (rejected).** Pays ~22,000 tracked lines and ~92
seconds per push for a path with no users and no working gate. It is not free in author attention
either: ADR-0017 accrued four amendments in two days, every one of them about a detail of the
mirroring mechanism rather than about the content being mirrored.
**Generate the mirror only at release, from a tag or a release branch (rejected).** Technically
supported, and it is worth recording *why* it was rejected rather than leaving it to look like an
oversight. Claude Code marketplace entries accept ref-pinned git sources, and apm already emits that
exact shape: the `mattpocock-skills` entry removed from root `apm.yml` on 2026-09-13 compiled to
`{"source": "github", "repo": ..., "ref": "v1.2.3", "sha": ..., "tag_pattern": "v{version}"}` — a
`git-subdir` source pinned to a ref. So a release-only mirror would install correctly.
Rejected on three grounds, stacking:
1. It keeps the 813-line script and the 1,289-line test alive in full. It reduces how often they
run, not how much there is to maintain — and the maintenance, not the runtime, is what ADR-0017's
amendment history shows to be the real cost.
2. It requires per-package tagging discipline this repo does not practise. `git tag` lists
repo-level tags (`v1.0.0`, `v2.0.0`, `v2.0.1`) matching no package version under the
`per_package` versioning mode the six plugins use. The tagging convention that would make
ref-pinning meaningful would have to be invented first.
3. **There is no CI in this repo at all.** Every gate here is a git hook on a developer's machine.
A release-time regeneration step would therefore depend on a human remembering to run it, and its
failure mode is silent: a release tag whose tree contains a stale or absent mirror installs
natively and reports zero skills, which is precisely the ADR-0017 defect, reintroduced on the
release path where it is hardest to notice.
**Also delete the marketplace catalogue (proposed, then rejected on evidence).** The initial shape
of this decision deleted `.claude-plugin/marketplace.json` along with everything else, on the
reasoning that it is a Claude Code artifact. That is wrong. `apm marketplace add` probes
`_MARKETPLACE_PATHS` in `apm_cli/marketplace/client.py` — `marketplace.json`, then
`.github/plugin/marketplace.json`, then `.claude-plugin/marketplace.json`, first hit wins — and that
read is what makes holocron an apm marketplace and what gives consumers the `<name>@holocron`
short-name form. Deleting it would have broken apm consumers in order to remove a file whose format
Claude Code merely happens to share.
Note the probe order: `.claude-plugin/marketplace.json` is the **last** resort, not the first, and
the `.github/plugin/marketplace.json` this repo deleted earlier outranked it. That deletion was
still inconsequential, but for a reason that has to be established rather than assumed — dropping a
higher-priority candidate only demotes resolution to the next one, and a reviewer reproduced
`apm marketplace add` against the post-deletion tree: it registered, found all 6 plugins, and
resolved via `.claude-plugin/marketplace.json`. What would break is deleting the last candidate,
which is exactly what this option proposed.
**Declare holocron an apm marketplace as a new step (moot).** Considered as a follow-on to the
above, and found to be already done: the `marketplace:` block in root `apm.yml` *is* the
declaration, and `apm marketplace init` produces exactly that block. There is nothing to add.
## Consequences
**1. Native `claude plugin install` no longer works, and the failure is silent.** This is accepted,
not overlooked. Because apm reuses Claude Code's catalogue format by design — an APM-based
marketplace stays consumable by Claude Code's existing marketplace mechanism — a Claude Code user
can still register holocron natively, and will then install six plugins containing zero skills,
zero agents and zero hooks. No error is raised at any point; the manifests are valid and the
directories are simply empty. There is no schema change available that would prevent this, because
the catalogue format cannot express "this marketplace is not for you" — the compatibility is
structural, and it is the same compatibility that makes keeping the catalogue correct for apm. A
README note is the only available mitigation, and a note is not a gate.
**2. Consumers now receive dev-fixture files.** apm installs from `.apm/`, and `.apm/` contains the
per-skill `tests/` directories the mirror explicitly stripped (ADR-0017's depth-scoped
`<category>/<name>/tests` exclusion). 10 `.bats` files across 6 skills therefore now deploy into
every consumer's skill directories. Suppressing them would mean switching all six `apm.yml` files
from `includes: auto` to explicit include lists — and an explicit list that is wrong silently drops
content, which is the same failure class ADR-0017 was written to fix. Trading a cosmetic problem for
a correctness problem is a bad trade, so this is deferred deliberately rather than fixed in passing.
**3. `tests/run-bats.sh` must exclude `.claude/skills/`** from both its `find` walk and the
`git ls-files` set-equality check that derives the expected test list. Deployed `.bats` files are
now discoverable in the install output and would otherwise be found and double-run against a root
they do not belong to — exactly the `apm_modules/` problem ADR-0018 recorded, arriving by a second
route. Any future script that walks this repo's tree needs both exclusions.
**4. No version bumps.** There is no standing rule that would require one. The patch-bump-on-content-
change convention this repo once followed was ADR-0006's, and ADR-0015 explicitly retired it as a
dual-manifest artifact: "Conventions that existed only because of hand-authored dual manifests
(ADR-0006's version-parity/patch-bump rule …) are obsolete under `apm.yml`'s single-manifest model
and were deliberately dropped." ADR-0015 also records that apm "has no native version-bump
automation at all", so nothing mechanical demands one either. What remains is the substantive test,
and it is satisfied independently: nothing under `.apm/` is touched here, only compiled artifacts are
removed, so the content every apm consumer receives is byte-identical before and after. This also
avoids triggering the `executables.allow`
`kyberforge#<version>` pin cascade ADR-0019 describes, which would otherwise turn a cleanup into a
multi-file coordinated edit for no functional gain.
**5. Reintroduction recipe.** This is the insurance that made the decision acceptable, so it is
stated concretely rather than left as "it's in git". To restore native install support: recover
`scripts/sync-plugin-content.sh` from git history (`git log --diff-filter=D -- scripts/sync-plugin-content.sh`
finds the deleting commit; `git show <sha>^:scripts/sync-plugin-content.sh` recovers it) and re-run
it with `--all`; it regenerates both the mirror and the per-plugin manifest pairs, because
`apm pack --format plugin` produces them together. Separately, apm resolves a marketplace at a git
ref — default `main`, with `--ref` pinning — so a consumer who pins an older ref still gets a tree
containing the mirror and is unaffected until they move forward.
**6. A negative result, pinned so it is not re-litigated: this does not relax the self-containment
constraint.** The natural next thought is that with the native installer gone, the no-cross-skill-
file-sharing rule (the rule that forced ADR-0014's Vale config duplication) could be relaxed,
because that rule was read as a property of Claude Code's plugin cache-install. It is not.
`plugins/kyberforge/.apm/skills/skill-author/references/deployment-modes.md`, sourced from the
agentskills.io spec, states the constraint independently for **APM package mode**: file references
inside `.apm/skills/<name>/` must not reach outside that skill's own directory, and the spec defines
no cross-skill sharing mechanism. So cross-skill file sharing remains impossible under the only
install path that survives, and ADR-0014's duplication rationale stands unchanged.
**7. Three of ADR-0017's four amendments become moot, and one loses its enforcement.** Recorded
because each was a decision someone spent real effort on:
- The `mcpServers` re-injection amendment (2026-08-14) is moot. Its target was
`.github/plugin/plugin.json`, which no longer exists; `reinject_mcp_servers()` dies with the
script that called it. Its reasoning — a path string, never an inlined object, because inlining
bypasses apm's credential sanitizer — is worth carrying forward as a general rule if per-plugin
Copilot manifests ever return.
- The `hooks`-pointer amendment (2026-08-14) is moot in the same way, and its outcome was to change
nothing, so nothing is lost.
- The `hooks/hooks.json` path-correction amendment (2026-08-14) is moot: there is no mirrored hooks
file to place.
- The symlink amendment (2026-08-14) is **not** moot, and this is the one real regression.
`check_apm_symlinks()` read the `.apm/` source tree directly to report symlinks, because apm
filters them out silently and the resulting content loss is invisible to any mirror-versus-mirror
diff. That check dies with the script.
A previous revision of this ADR left open whether `apm install`'s own copy path drops symlinks the
way the bundle exporter does. It does, and the mechanism is now confirmed by reading the installed
apm source. Deployment filters them: `ignore_non_content()` in `apm_cli/security/gate.py` is a
`shutil.copytree` ignore callback whose docstring states "Excludes symlinks (security)", and
`apm_cli/integration/skill_integrator.py` passes it — or the equivalent `_build_copy_ignore()` —
to every `copytree` that materialises a skill (`:424`, `:791`, `:1152`), with further per-file
`is_symlink()` drops for `bin/` entries and the plugin manifest at `:1671` and `:1696`. None of
these log the skip. Materialization into `apm_modules/`, by contrast, **dereferences**: for git
sources `deps/github_downloader.py` copies the checkout out with `robust_copytree`/`robust_copy2`
and no symlink filter, and for local sources `install/phases/local_content.py`'s
`_copy_tree_dereferencing_validated()` resolves each in-package symlink and copies its content as
a real file (erroring on dangling, escaping or circular ones). So a symlink under `.apm/` survives
into `apm_modules/` as real content and is then silently dropped on deploy — the failure is at the
deploy step, not the fetch, which is why it would not show up in a cache inspection.
**This is accepted, and no replacement guard is added.** No symlink exists under any `.apm/`
today, and the mitigations available are worse than the exposure: a standalone repo-side checker
would be a new script to maintain for a condition that has never occurred, and it could only warn,
since the drop happens inside apm. The operative rule is therefore a convention rather than a
gate: do not introduce a symlink under any `plugins/*/.apm/` tree. If one is ever needed, the
filtering above is the reason it will not reach consumers, and closing the gap properly means an
upstream change in apm, not a local one.
**8. ADR-0017's own exit condition was different from this one, and that is worth noting.** Its
final consequence anticipated deletion, but conditioned it on an upstream fix: "a future apm release
that ships a native `.apm/`-aware plugin.json compiler ... would let `sync-plugin-content.sh` and
its drift gate be deleted outright." That release has not happened. The mirror is being deleted
because the path it bridges has no users, not because apm closed the gap — the gap is still open,
and a consumer who installs natively still hits it. ADR-0017's anticipated exit remains available
and unclaimed; this ADR takes a different one.

3
docs/notes/factory-integration-decisions.md
View File

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

19
docs/notes/skill-implementation-workflow.md
View File

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

15
docs/spec/architecture.md
View File

@@ -19,13 +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 — 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). A consuming repo installs them the same way — apm is the only supported install path.
`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance) and carries nothing else — the content index of on-demand instruction files sits in `core/AGENTS.md`, deployed to `~/.agents/AGENTS.md` and imported by it. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently via `apm install`, here and in any consuming repo (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no per-plugin `plugin.json` at all — apm reads `apm.yml`, and the repo's one generated manifest, `.claude-plugin/marketplace.json`, is compiled from that source.
Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`.
@@ -42,14 +42,15 @@ These are routing boundaries, not inventories — they answer "where does a new
| `lint` | Configuring and running linters against a target repo; repo-agnostic, first linter is Vale |
| `bin` | Unsorted skills that have not earned a home yet |
Two compilers produce the plugin roots you see in the tree:
One compiler produces the generated content 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 pack` compiles the marketplace manifest** (ADR-0015). Repo-wide, from the root `apm.yml`'s `marketplace:` block: `.claude-plugin/marketplace.json` (apm's `claude` output profile) — the only manifest this repo generates or ships. Copilot CLI checks for a marketplace manifest at several conventional paths, falling back through `.github/plugin/marketplace.json` to `.claude-plugin/marketplace.json` — since this repo already generates the latter, no dedicated Copilot-path mirror is maintained.
`.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.
apm is the only supported install path. A flat `skills/`, `agents/`, `hooks/` mirror used to be compiled to each plugin root so Claude Code's installer could convention-scan it, alongside a per-plugin `.claude-plugin/plugin.json` and `.github/plugin/plugin.json`; both are gone, together with native `claude plugin install` support. apm reads `plugins/<name>/apm.yml` and deploys from `.apm/` directly, and never probed those manifests.
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/`.
`.apm/` is the sole hand-edited authoring source for plugin content. Hand-authored material that is not an `.apm/` primitive — `README.md`, `docs/`, `bin/`, `sources.md`, and per-plugin extras such as `plugins/gitea/references/` and `plugins/bin/evals/` — lives at the plugin **root**. A hand-edit to the generated `.claude-plugin/marketplace.json` is reported as drift by the `apm-pack-check-clean` pre-push hook.
Plugin-root documentation belongs in `docs/`. That convention is older than the mirror's removal: a hand-written `README.md` placed inside a mirrored directory used to be destroyed by the next sync with no drift report, which cost the repo one document — `plugins/kyberforge/hooks/README.md`, since restored to `plugins/kyberforge/docs/hooks.md`.
## Governance layer

405
docs/spec/gates.md
View File

@@ -21,38 +21,35 @@ Install hooks via `pc-run`, wiring **all three stages**. This repo's `.pre-commi
`default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits)
and `pre-push` (everything below).
The pre-push command reports **16** hooks, not 14. The extra two are pre-commit's own `meta` hooks,
The pre-push command reports **11** hooks, not 9. The extra two are pre-commit's own `meta` hooks,
`check-hooks-apply` and `check-useless-excludes`: they declare no `stages:`, so they run at every
stage including this one. Both are declared in this repo's `.pre-commit-config.yaml` like everything
else — what separates them is `repo: meta` (pre-commit's own built-ins) from `repo: local`. Fourteen
else — what separates them is `repo: meta` (pre-commit's own built-ins) from `repo: local`. Nine
is the count of hooks this repo authors itself.
**The caveat: one of those 14 is a silent no-op under that invocation.**
**The caveat: one of those 9 is a silent no-op under that invocation.**
`check-release-needed` exits 0 immediately unless `PRE_COMMIT_REMOTE_BRANCH` equals
`refs/heads/main`, and pre-commit exports that variable only from the real pre-push git hook during
an actual `git push`. Running the stage by hand — or from a CI runner — therefore reports it
`Passed` having checked nothing. That is by design for feature branches — pushing WIP must not be
blocked on cutting a premature tag — but it means `--hook-stage pre-push --all-files` is a full
rehearsal of 13 hooks and a skip of the fourteenth. The script's own header records the same gap for
rehearsal of 8 hooks and a skip of the ninth. The script's own header records the same gap for
a PR merged through Gitea's merge button, where no local push happens at all.
## The pre-push gate
Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
Nine hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
**Core checks**
| Hook | Guards |
|---|---|
| `run-tests` | `bash tests/run-tests.sh --strict` — the whole suite, skips fatal (see [Tests](#tests)) |
| `check-manifests` | `marketplace.json` and `plugin.json` paths resolve (needs `jq`) |
**Generated-content drift gates**
| Hook | Guards |
|---|---|
| `check-plugin-content-sync` | each plugin's flat `skills/agents/commands/hooks` mirror matches `.apm/` (issue #90) |
| `check-marketplace-mirror-sync` | `.github/plugin/marketplace.json` is byte-identical to `.claude-plugin/marketplace.json` — no apm output profile targets that path |
| `check-vale-style-sync` | skill-audit's Vale copy matches agent-audit's canonical copy, plus six glob-coverage probes (see [Vale](#vale)) |
| `check-scope-walkup-sync` | `validate.sh`, `validate-provenance.sh`, `new-agent.sh` and `new-skill.sh`'s four independent `$HOME`/`.git`/`apm.yml` walk-up ports still agree behaviorally |
| `check-executables-allow-sync` | root `apm.yml`'s `executables.allow` key names kyberforge's actual version (see [apm gates](#apm-gates)) |
@@ -70,15 +67,13 @@ drift in generated text.
| Hook | Guards |
|---|---|
| `apm-marketplace-check` | every `marketplace.packages[]` entry resolves, including network reachability of remote refs |
| `apm-audit-ci` | `apm audit --ci` once per manifest — root plus each of the six plugin packages |
| `apm-pack-check-clean` | `apm pack --check-versions --check-clean --dry-run` — the compiled marketplace still matches what `apm.yml` + `.apm/` would generate, and per-package versions agree with the `per_package` strategy |
**Host validators** (both need the `claude` CLI on PATH)
**Host validators** (needs the `claude` CLI on PATH)
| Hook | Guards |
|---|---|
| `validate-plugins` | `claude plugin validate --strict` on every plugin directory |
| `validate-marketplace` | `claude plugin validate --strict` on the root marketplace manifest |
**Release**
@@ -87,21 +82,43 @@ drift in generated text.
|---|---|
| `check-release-needed` | on a real `git push` to `main` only — fails if files exposed via `.pre-commit-hooks.yaml` changed since the last tag. A no-op everywhere else, including under `pre-commit run --hook-stage pre-push` (see [the caveat above](#running-the-gates)) |
Four of these shell out to `apm`: `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`). The
first and third are bare `apm …` entries and the second is a `bash -c` loop calling `apm` once per
package, so without the CLI the push dies with an unhelpful "command not found". Install with
`apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`. `jq` is
needed by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh` — those at least fail
loudly (`Error: jq is required but not installed`).
Two of these shell out to `apm`: `apm-audit-ci` and `apm-pack-check-clean`. The second is a bare
`apm …` entry and the first is a `bash -c` loop calling `apm` once per package, so without the CLI
the push dies with an unhelpful "command not found". Install with `apm-install`, or
`curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`.
## Skill and agent context gates (ADR-0020)
The `skill-size-check` pre-commit hook, scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$`,
runs `scripts/skill-size-check.sh`. That scope means it never lints the
`plugins/kyberforge/docs/research/examples/` reference skills. It is also shipped to external repos
as `kyberforge-skill-size-check` (see
[External consumers](#external-consumers-the-root-pre-commit-hooksyaml)).
runs `scripts/skill-size-check.sh`. It is also shipped to external repos as
`kyberforge-skill-size-check` (see
[External consumers](#external-consumers-the-root-pre-commit-hooksyaml)). Besides the ADR-0020
gates below, it also asserts required frontmatter is present: `name`, a non-empty `description`, and
a `metadata.version` matching three-part semver (`1.0.0`) — folded in from a formerly standalone
`skill-frontmatter` hook that parsed the same fields with a shell script.
**Two things fall outside that scope, both deliberately.** The `[^/]+/SKILL\.md$` tail admits only a
`SKILL.md` sitting directly in a skill directory under `.apm/skills/`:
- the `plugins/kyberforge/docs/research/examples/` reference skills, which are vendored upstream
corpus and not this repo's to gate;
- `plugins/kyberforge/.apm/skills/skill-author/assets/templates/SKILL.md` — inside `.apm/skills/`,
but two directories deeper. It is the `FILL IN:` scaffold `skill-author` copies, so its
`description: >` is a comment block rather than a description and every ADR-0020 measurement over
it would be meaningless. A reader adjusting the pattern needs to know it is there.
Everything else it matches exactly, with nothing over- or under-caught. Re-derive both halves:
```
git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$' # the real skills
git ls-files | grep -E '^plugins/[^/]+/\.apm/skills/.*SKILL\.md$' \
| grep -vE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$' # the scaffold only
```
The first count equals the number of skill directories (`ls -d plugins/*/.apm/skills/*/ | wc -l`);
the second returns exactly the template. Every other tracked `SKILL.md` in the tree is one of the
four vendored `plugins/kyberforge/docs/research/examples/skill-write/` corpus files, excluded by the
`.apm/skills/` segment — the first of the two deliberate exclusions above.
### Two independent gate families, neither replaced the other
@@ -141,7 +158,7 @@ A boundary-clause target that resolves to no skill or agent has **three** possib
| Verdict | When |
|---|---|
| **SUGGESTION** — the default | the target does not resolve and neither promotion condition below holds |
| **blocking ERROR** | the target is **terminal** (not a compound modifier) **and** either written in route notation (`/name` for any name; `-> name` only when the name is hyphenated — see the gap below) **or** corroborated by another target in the same sentence that *does* resolve |
| **blocking ERROR** | the target is written in **route notation** — `/name` for any name, or any arrow form (a bare `-> name` only when the name is hyphenated, a backticked `` -> `name` `` for any — see the gap below); **or** it is a bare **terminal** name (not a compound modifier) **corroborated** by another target in the same sentence that *does* resolve |
| **INFO, "DID NOT RUN"** | no skill universe could be determined for the path at all — the targets are named and left unchecked, exit 0 |
The default is deliberately soft because a hyphenated word in a boundary clause is as likely to be a
@@ -149,14 +166,36 @@ tool, a file format or an English compound as a route: "pre-commit hooks" is pro
never reaches the check at all, being a compound modifier rather than a terminal name. The
SUGGESTION text says how to opt in — write it as `/name` or `-> name` and it gets checked properly.
**Known gap: the arrow form only works for hyphenated names.** Target extraction is built on
`NAME_HYPH` (`scripts/skill-size-check.sh:543`), which requires at least one hyphen, and
`ARROW_BOUNDARY` (`:561`) inherits that. So `-> gitea-prs` is extracted and checked, while
`-> triage` is not extracted at all — no ERROR, no SUGGESTION, exit 0. The unicode arrow `→` is not
recognised in either case. This makes the SUGGESTION's own advice unsafe for a single-word skill:
taking it silences the finding rather than checking it. `/name` has no such restriction and is the
form to prefer. Tracked as a defect; `tests/test-adr0020-targets.sh` has one arrow case and its
target happens to be hyphenated, so nothing currently covers this.
**The two promotion conditions are not symmetric, and the order matters.** `_add()` decides
**notation first**: when the name is written `/name`, or reached through any arrow form, the target
is marked error-eligible there and the terminal test is never run. Terminality gates only the *bare*
path — a name in prose earns its error from corroboration, and a compound modifier can never dangle.
Reading the row as "terminal AND (notation OR corroborated)" gets the notation half backwards: it
predicts that `` … Do not use for Y — use /no-such-skill afterwards. `` is a SUGGESTION, because
`afterwards` is a follower outside `FOLLOWER_OK`. It exits 1. That was the defect — `-> name` reached
`_add()` with `strict=True` from both its call sites and `/name` did not, so the one spelling
ADR-0020 offers an author who wants a route checked unconditionally was the one spelling a stray
follower could silence.
**Known gap: a BARE arrow target must be hyphenated.** Target extraction is built on `NAME_HYPH` in
`scripts/skill-size-check.sh`, which requires at least one hyphen, and `ARROW_BOUNDARY` inherits
that. So `Not X -> gitea-prs` is extracted and checked, while `Not X -> triage` yields no target.
The exclusion is deliberate, not an oversight: `research`, `triage`, `forge`, `prototype` and `tdd`
are all real skill names *and* ordinary English, so a bare single-word rule would flag most of the
corpus. The marked spellings carry no such restriction — `` `triage` `` and `/triage` are both
extracted — and are the forms to prefer. **Both arrow spellings are recognised:** `ARROW_MARKED`,
`ARROW_BOUNDARY` and `BOUNDARY_ARROW` are each built from `(?:->|→)`, so the unicode arrow `→`
behaves exactly like `->` in every case below. Cite these constants by symbol name, never by line
number: the script moves often enough that a pinned line lands a reader in an unrelated comment
block and reads as plausible.
**The gap is no longer silent.** It used to be exactly that — no ERROR, no SUGGESTION, exit 0 — which
made the dangling-target SUGGESTION's own advice unsafe for a single-word skill: taking it silenced
the finding instead of checking it. `boundary_clause_status()` now separates the case out and
reports it as `unparsed` (see below), naming the parse failure and the two spellings that fix it.
The target is still not *resolved*; the author is now told so rather than left with a green gate.
`tests/test-adr0020-targets.sh` covers both directions (`arrow-single-word-target` and the silent
control `arrow-single-word-marked`).
Corroboration is what makes the soft default safe: a sentence whose *other* target resolves is
demonstrably a routing sentence, so a sibling that does not resolve is a typo rather than a noun, and
@@ -199,18 +238,107 @@ run it. Four cross-plugin targets here (`gitea-branches` → `git-branches`, `gi
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.
Verified fixed: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no
`.claude/` or `.agents/` anywhere, produces findings identical to the working tree — **26 description
FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs**.
Verified: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no
`.claude/` or `.agents/` anywhere, produces findings identical to the working tree — confirming the
two trees agree on the current corpus, independent of what happens to be installed locally.
### Boundary-clause detection: three outcomes, not two
`boundary_clause_status()` returns one of three values, and the two findings get separate messages:
| Status | When | Reported as |
|---|---|---|
| `present` | a prose marker (`do not`, `instead`, `rather than`, `not for`) or an arrow clause was found | nothing |
| `absent` | neither was found | SUGGESTION: add a boundary clause, in either form |
| `unparsed` | an arrow clause was found and **no target could be read out of it** | SUGGESTION: the clause is present — this is a *parse* failure, not a missing clause |
The third had to be split out. Collapsing it into `absent` is a **wrong** finding, not a strict one:
it sends the author to add a clause that is already there. Three of them instead reworded a correct
clause until the regex accepted it, one stripping the very filename that discriminates the skill
from its neighbour (**#110**).
`unparsed` is narrow and certain on purpose. It fires only on the arrow form, which *always* names a
target, so zero targets means the name is written in a shape the extractor cannot see — in practice
a bare single-word target, per the known gap above, and the message says to write it `` `name` `` or
`/name`. A **prose** clause yielding no target is not reported at all: "Do not use for anything else"
is a complete and legitimate boundary clause that names nowhere to go.
**One arrow, one target.** An arrow clause naming two or more targets draws its own SUGGESTION,
quoting both names and asking for a split, because only the first is ever resolved: the conjunction
continuation (`CONT_MARKED` / `CONT_ANY`) is wired to the prose route verbs and never to arrows. So
`Not X -> a or b` resolved `a`, left `b` resolved by nothing and reported by nothing, and then let
the audit print "1 of 1 boundary target(s) resolve" on a clause naming two — a gate under-reporting
its own coverage, which is the one failure mode ADR-0020 says a gate must not have (**#107**). The
clause is **rejected rather than the arrow scan extended**: extending it would widen the resolver's
deliberately conservative false-positive tuning across every arrow in the corpus, where splitting
costs the author one full stop. The convention is one arrow per target — `Not X -> a. Not Y -> b.` —
already what every retrofitted `gitea-*` skill does in practice, now stated in
`skill-author`'s `references/contract.md` instead of being folklore.
**Dotted filenames in a boundary clause now parse.** `CLAUSE_BODY` — what may sit between `Not` and
the arrow — used to be `[^.;]`, a class that cannot cross a `.`, so every clause naming a dotted
filename between the two (`AGENTS.md`, `.vale.ini`, `.pre-commit-config.yaml`) was invisible to both
`BOUNDARY_ARROW` and `ARROW_BOUNDARY`. The two resulting failures were different sizes (**#110**):
- with a **backticked** target the clause was *misdiagnosed*. The backtick sweep still extracted the
target, so the route was checked, but the gate reported "no boundary clause" on a clause that was
present and working. That is the misdiagnosis the three rewordings above came from.
- with a **bare** target the clause was *unchecked*. `ARROW_BOUNDARY` is the only extractor for a
bare arrow target, so `Not AGENTS.md -> no-such-skill` produced no target, no dangling report and
no missing-clause SUGGESTION. Silence, not noise — the worse of the two.
`CLAUSE_BODY` is now `(?:[^.;]|\.(?=\S))`: a dot inside a filename is followed by a non-space, a
sentence-ending dot by whitespace or end of string, so the class crosses `AGENTS.md` and still stops
at a real sentence end. **Read the second bullet forward as well as back:** a bare target sitting
after a dotted filename is now extracted, resolved, and a blocking ERROR when it dangles, where the
same clause used to pass unchecked in silence.
### SUGGESTION-only checks
Three more, deterministic to measure but judgment to act on:
Deterministic to measure, judgment to act on:
- a description with **no boundary clause at all**;
- a description with **no boundary clause at all** (`absent`);
- an **arrow clause whose target could not be read** (`unparsed`);
- an **arrow clause naming more than one target**;
- a `## Gotchas` section with **more than five entries**;
- a `## Gotchas` section over **25% of the body**.
### Hand-invoked skills are exempt from the routing rules, and only those
A skill or agent whose frontmatter carries `disable-model-invocation: true` skips three checks:
- the boundary-clause check, `absent` and `unparsed` alike;
- the multi-target arrow check;
- the 250-character description **target** (`hand_invoked()` in `scripts/skill-size-check.sh`).
It keeps the 400-character description FAIL and **both** body word tiers, and if its description
does happen to name a target, that target is still resolved and can still dangle.
Why the exemption is right: `disable-model-invocation: true` removes the skill from the
model-visible listing entirely — it is not preloaded, and the Skill tool refuses to call it — so its
description is never matched against user intent. ADR-0020 and `skill-author`'s contract therefore
give such a skill **one plain human-facing sentence**: no trigger list, no boundary clause. No
validator knew the field existed (**#108**), so the boundary-clause SUGGESTION fired on exactly the
shape the contract mandates, and its remedy — "so the router knows where NOT to send this skill" —
was addressed to a router that cannot see the skill at all. An author who followed the advice made
the file worse. There is no router to inform.
The half that does **not** lift is the point. The body is still loaded on invocation and still
competes with the caller's live conversation, so neither body tier moves. The 400-character ceiling
stands too: a hand-invoked description is not preloaded, but it is still the one line the user reads
when choosing from the `/` menu, and that ceiling is an outlier stop rather than a routing-quality
budget — which is precisely why the 250-character target is the tier that lifts.
The field is read as a **boolean**, not as a mention of the key. PyYAML already resolves the
unquoted YAML 1.1 booleans, so the extra handling catches a quoted `"true"`, which a host reads as
truthy; `disable-model-invocation: false` is the model-invoked case written out longhand and buys
nothing. A frontmatter parse failure returns false rather than raising — the flag is a *modifier* on
other checks, and `description_value()` on the same text already reports the broken frontmatter, so
raising here would diagnose one file twice two different ways.
`caveman` and `zoom-out` are the two carriers here. `tests/test-skill-size-check.sh` pins both
halves — what the carve-out lifts, each with a flag-removed control, and what it must not.
### `verbose: true` is load-bearing
The hook is declared `verbose: true` so the SUGGESTION tier is audible. pre-commit prints nothing at
@@ -253,6 +381,10 @@ reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file
which is the exact vacuous-green failure the `python3` check exists to avoid. `pip install pyyaml`
(or `python3 -m pip install PyYAML`, or the distro's `python3-yaml`) if the hook reports it missing.
**Neither requirement generalises to every hook in this repo.** `check-rtk-prefix` needs `python3`
but **not** PyYAML: it reads the markdown body and never touches frontmatter, so it has no scalar to
fold.
## Agent files take the description gates, not the body gate
`check-apm-agents-valid` runs agent-audit's `validate.sh` over every real
@@ -281,40 +413,113 @@ script.** `scripts/skill-size-check.sh` applies its body gate to whatever path i
bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md
```
exits 1 today with 900-word body FAILs on `git-orchestrate` (933), `gitea-orchestrate` (1,199) and
`apm-orchestrate` (1,080). Agent files escape only because the hook definitions filter on `SKILL.md`
exits 1 today with 900-word body FAILs on `git-orchestrate` and `gitea-orchestrate`. (Counts are
deliberately not pinned here — agent bodies are edited like any other file, and a figure in this
paragraph goes stale the moment one is trimmed. Run the command.) Agent files escape only because
the hook definitions filter on `SKILL.md`
— a file-pattern accident that happens to implement the design, not the design itself. **Do not
"extend" that hook's `files:` pattern to cover agents** on the assumption that the script already
knows the difference; doing so silently enforces a gate ADR-0020 declines to set.
## Current retrofit status
**The ADR-0020 gates ship hot, with no baseline file.** A shrinking baseline recording each
non-compliant skill's current numbers was considered and rejected in favour of hot gates.
The ADR-0020 gates ship hot, with no baseline file — a shrinking baseline was considered and
rejected. The corpus is currently clean on both: 0 of 39 descriptions/bodies exceed their FAIL tier,
0 dangling targets, 0 `Kyberforge.CompositionNote` (Vale) errors. History: issue #99.
Two independent hot gates are currently red, and the first will not warn you about the second.
| Gate | Current findings |
|---|---|
| `skill-size-check` | **26 of 39** descriptions and **9 of 39** bodies exceed their FAIL tier; 2 dangling targets; 58 SUGGESTIONs |
| `Kyberforge.CompositionNote` (Vale) | **10 errors across four skills**: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-workflow` |
`Kyberforge.CompositionNote` is the ADR-0020 Vale rule banning composition and architecture prose
from a description. Every Vale rule here is `level: error` with no ignorable tier, so touching any of
those four skills means fixing its prose findings as well as its size findings.
Consequence: editing a non-compliant skill *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; it guarantees convergence and avoids a half-state. Tracked as Gitea issue **#99**.
Check where a skill stands before starting, and check **both** gates:
Nothing is grandfathered — a new skill, or an edit that crosses a FAIL tier, is blocked on first
commit. SUGGESTION counts are not pinned here; they move with every edit. Measure and check both
gates before starting work on a skill:
```
pre-commit run skill-size-check --all-files # size/context only
pre-commit run --all-files # size AND Vale
bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep -c '^SUGGESTION'
pre-commit run --all-files # size AND Vale — skill-size-check alone can pass while Vale still blocks
```
Scoping a retrofit off `skill-size-check` output alone leaves you blocked at the second gate.
## The `rtk` prefix gate (ADR-0023)
`check-rtk-prefix` is a `repo: local` pre-commit hook running `scripts/check-rtk-prefix.sh` over
`^plugins/[^/]+/\.apm/(skills/.*\.md|agents/.*\.agent\.md)$`, with `README.md` excluded. It enforces
**ADR-0023 clause 1 and nothing else**: an executable, instructed local git command in plugin skill
or agent content is written `rtk git`.
It is wider in file scope than the ADR-0020 hooks — every markdown file under a plugin's
`.apm/skills/` and `.apm/agents/`, not `SKILL.md` alone — because the rule it enforces is about
commands an agent runs, and most of those live in `references/`, which the ADR-0020 gates do not
reach ([the `references/` blind spot](#the-blind-spot-references-is-unlinted-for-two-independent-reasons)).
### What it can decide, and what it declines to
ADR-0023 has three clauses and only the first is a pattern:
| Clause | Rule | Gated |
|---|---|---|
| 1 | executable + instructed → `rtk git` | yes |
| 2 | illustrative / referential → bare `git` | no — undecidable |
| 3 | machine-parsed or interactive → bare `git` | no — opt-out marker |
Clause 2 is a judgement about what a sentence is *doing*. "Run `git switch <branch>`" and "`git
switch` refuses rather than clobbering local edits" are the same token sequence. A gate that guessed
would fire on correct prose, and **a gate that fires on correct content gets added to `SKIP`** —
which disarms clause 1 along with it. So the hook looks only at the two contexts where a `git`
mention is unambiguously an instruction to execute:
- a line inside a fenced code block whose info string names a shell — `bash`, `sh`, `shell`, `zsh`,
`console`, `shell-session`. Fences tagged `text`, `yaml`, `json`, or tagged with nothing, are **not**
checked;
- the **opening** backticked span of a "Run" column cell in a markdown dispatch table, and only the
opening span.
That last narrowing is not fussiness. A Run cell routinely carries a command followed by prose about
it, and the prose is clause 2. `git-worktrees/SKILL.md` has both shapes on adjacent rows — one cell
reading `` `rtk git worktree add --track …` `` — always correct. `` `git worktree add <path>
<branch>` `` expands to exactly this (instruction, then reference), and a `**Never** …` row whose Run
cell is entirely explanation containing a bare `git push`. Checking every backticked span flags both;
checking only a leading span flags neither, and still catches the ordinary
`` | List | `git worktree list -v` | `` case the gate exists for.
### The clause-3 opt-out
A command that is deliberately bare — because rtk rewrites the output the skill parses, or because
the command is interactive — is exempted by putting the literal string `ADR-0023` **on the same
line**: in a shell comment for a code line, in the cell text for a table row.
Per line, never per block. A fenced procedure routinely mixes `rtk git` steps with one deliberately
bare command (`git-remotes/references/push.md` does exactly that), and a block-level marker would
silently disarm every checked line around the marked one. The cost is a repeated `# bare per
ADR-0023` in the three blocks of `git-log-format.md` where every line is deliberately bare; that
repetition is the price of the marked line being the only line the marker speaks for.
The marker is a plain substring match, so a line that mentions `ADR-0023` for an unrelated reason is
also exempt. Accepted deliberately: the marker records an author's opt-out, it is not a security
boundary, and a stricter form would only move the same trust to a different string.
### What it deliberately does not cover
- **Clause 2.** Nothing checks that an illustrative mention stayed bare. A sweep that re-prefixes a
referential `git` passes this gate. The inline reasons ADR-0023 requires on clause-3 sites are the
only defence, and they are prose.
- **Prose bullets.** Most of `branch-operations.md`, `merging.md` and `rewrite-history.md` instruct
in list items, not fences. Those are clause-1 sites the gate cannot see, because it cannot
distinguish them from clause-2 mentions in the same list.
- **`README.md`, excluded by pattern.** A skill-directory README is consumer-facing prose no agent
loads, and the `git clone https://github.com/bats-core/…` lines in the seven `tests/README.md`
files are setup instructions for a third party who has no `rtk`. Prefixing those would be actively
wrong, not merely noisy — see ADR-0023's consumer section.
- **Quoting.** The line splitter breaks on `;`, `|`, `&&`, `||`, `$(` and backticks without tracking
quotes, so a git command inside a quoted argument is decided by accident.
`rtk git submodule foreach 'git pull origin main || :'` passes because the segment holding the
inner command begins with `rtk` — the right answer for the wrong reason. Write
`foreach 'git a; git b'` and the second inner command is a false positive needing the marker.
ADR-0023 records this shape as one the rule itself does not decide.
- **Non-git commands.** Only `git` is checked. `rtk` fronts `gh`, `docker`, `kubectl` and others; no
gate covers those, and the corpus does not currently instruct them.
`tests/test-check-rtk-prefix.sh` pins all of it, including the false-positive cases. Its first case
reconstructs the plugin corpus as it stood on `main` before the #113 sweep and asserts the gate
fails there with at least 20 findings, one of them the `gitea-*` `git remote get-url origin` drift
the sweep missed — a gate that only passes on the already-fixed tree proves nothing about the drift
it was written for.
## Vale
@@ -408,9 +613,11 @@ Two prefilter hooks, with `.apm/`-scoped `files:` patterns:
| `vale-audit-prefilter-skill` | `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` |
| `vale-audit-prefilter-agent` | `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` |
Only the **authoring source** triggers them. A `SKILL.md` in the generated flat 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.
Only the **authoring source** triggers them. The `skill-author` scaffold template and the four
vendored research-corpus `SKILL.md` files match neither pattern (see
[Skill and agent context gates](#skill-and-agent-context-gates-adr-0020), which uses the same scope
for `skill-size-check`), so prose findings surface only when you edit a file this repo actually
authors. Without the binary the hooks fail with a bare "command not found" and no install pointer.
**Two hooks, not one combined hook.** Both manifests split the prefilter in two precisely because a
single hook can point at only one copy, and that copy would silently 0-file-skip the other file
@@ -434,6 +641,35 @@ passing one explicit file per invocation. The two manifests scope **differently
Narrowing a `.vale.ini` glob to a `plugins/`-shaped path to "tighten" it breaks the consumer case,
and `check-vale-style-sync`'s probe set is built to catch exactly that.
### The blind spot: `references/` is unlinted, for two independent reasons
Every `references/*.md` file in the corpus is outside the prose gate. Count them with
`git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/references/.*\.md$'` rather than reading
a figure here; it moves with every retrofit. This is the gap that matters most, because the context
contract's own remedy for an over-long body is to move prose **into** `references/` — the gate pushes
text across its own boundary and then stops watching it.
**Closing either cause alone changes nothing.** There are two, and they are independent:
| Cause | Where | Effect on a `references/` file |
|---|---|---|
| the `Kyberforge` style is scoped `[**/SKILL.md]` | `skill-audit/assets/vale/.vale.ini` | matches no section, so Vale lints 0 files and exits 0 |
| the hook's `files:` regex is `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` | `vale-audit-prefilter-skill` in `.pre-commit-config.yaml` | the file is never handed to Vale at all |
Verified both ways. Handing skill-audit's `vale-wrap.sh` a reference file directly — bypassing
pre-commit entirely, so only the style scope is in play — prints `0 errors … in 0 files` and exits 0,
where the same wrapper on a `SKILL.md` reports `in 1 file`. And the hook's `files:` regex, applied to
`git ls-files`, selects only the skill-directory `SKILL.md` files scoped at the top of this page, so
pre-commit never hands Vale a reference file to begin with. Widening the glob to `[**/*.md]` would
still lint nothing through the hook; widening the hook's `files:` alone would hand Vale files its own
config declines to match, which is the [0-file NOT RUN](#a-0-file-vale-run-is-not-run) shape — a
green run that measured nothing. **Issue #117** records the style-scope half; the hook half has to
land in the same change or the fix is cosmetic.
The consumer manifest is a third axis and does not rescue this either: `.pre-commit-hooks.yaml`'s
`(^|/)SKILL\.md$` is layout-agnostic but still filename-shaped, so an external repo running
`kyberforge-vale-audit-skill` has the same gap.
### `vale-wrap.sh`, never bare `vale`
Both audit skills' Step 1 and both pre-commit hooks call **each copy's own**
@@ -630,10 +866,9 @@ does not deploy and the replay does not compare; shared enforcement belongs in
### Why it is excluded from `pretty-format-json`
It is the **sixth and last alternation** in that hook's `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.
It is the **second and last alternation** in that hook's `exclude:` pattern, and the only one there
for a reason other than "generated manifest". Mind which number you are quoting: **two alternations,
expanding to two real files** — `.claude-plugin/marketplace.json`, plus this one.
`pretty-format-json --autofix` sorts object keys unless `--no-sort-keys` is passed, while apm's hook
integrator emits insertion order (`matcher` before `hooks`, `type` before `command`). Leaving the
@@ -647,30 +882,11 @@ fix.
## Pushing without a network
Exactly **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`.
No pre-push hook needs the network. Every entry in root `apm.yml`'s `marketplace.packages[]`
resolves from a local `./plugins/<name>` path, so `apm-pack-check-clean` never calls `git ls-remote`.
| Hook | Offline failure |
|---|---|
| `apm-marketplace-check` (`always_run`, resolves every entry) | `No cached refs (offline)` |
| `apm-pack-check-clean` (re-resolves the same entry) | `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.) Adding any other hook 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.
`apm-audit-ci` calls `apm` too but was always local: its org-policy discovery resolves nothing on
this remote before any network call.
---
@@ -680,10 +896,13 @@ remote *before* any network call, so it does not join the pair above.
enforcement table (deterministic vs. auditor judgment), and every rejected alternative
- `docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md` — the `SessionStart` hook, the
executable-trust gate, and the version-pinned allow key
- `docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md`,
`docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md`,
`docs/adr/0014-vale-prefilter-ships-from-the-plugin.md` — plugin content sync, apm-generated
manifests, committed Vale styles
- `docs/adr/0024-apm-is-the-only-supported-install-path.md` — apm as the sole install path, and the
deletion of the flat content mirror and its `check-plugin-content-sync` gate. It supersedes
`docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md` (**superseded** — plugin
content sync, kept as the historical record)
- `docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md`,
`docs/adr/0014-vale-prefilter-ships-from-the-plugin.md` — apm-generated manifests, committed Vale
styles
- `docs/spec/architecture.md` — directory structure, install pipeline, what is generated and what is
hand-authored
- `.pre-commit-config.yaml` — the hooks themselves, with inline rationale comments

11
plugins/bin/.apm/skills/caveman/SKILL.md
View File

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

58
plugins/bin/.apm/skills/diagnose/SKILL.md
View File

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

0
plugins/bin/.apm/skills/diagnose/scripts/hitl-loop.template.sh → plugins/bin/.apm/skills/diagnose/assets/hitl-loop.template.sh
View File

40
plugins/bin/.apm/skills/diagnose/references/feedback-loops.md Normal file
View File

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

24
plugins/bin/.apm/skills/diagnose/references/regression-seams.md Normal file
View File

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

8
plugins/bin/.apm/skills/grill-me/SKILL.md
View File

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

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

@@ -1,6 +1,11 @@
---
name: grill-with-docs
description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
description: >
Use when a plan should be stress-tested against the project's domain model —
the interview challenges terms against `CONTEXT.md` and writes decisions into
it and into ADRs as they land. Not a plain interview -> `grill-me`.
metadata:
version: "1.0.0"
---
<what-to-do>
@@ -71,7 +76,7 @@ When the user states how something works, check whether the code agrees. If you
### Update CONTEXT.md inline
When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [context-format.md](references/context-format.md).
Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
@@ -83,6 +88,6 @@ Only offer to create an ADR when all three are true:
2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
If any of the three is missing, skip the ADR. Use the format in [adr-format.md](references/adr-format.md).
</supporting-info>

0
plugins/bin/.apm/skills/grill-with-docs/ADR-FORMAT.md → plugins/bin/.apm/skills/grill-with-docs/references/adr-format.md
View File

0
plugins/bin/.apm/skills/grill-with-docs/CONTEXT-FORMAT.md → plugins/bin/.apm/skills/grill-with-docs/references/context-format.md
View File

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

@@ -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.

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

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

2
plugins/bin/skills/improve-codebase-architecture/DEEPENING.md → plugins/bin/.apm/skills/improve-codebase-architecture/references/deepening.md
View File

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

10
plugins/bin/.apm/skills/improve-codebase-architecture/INTERFACE-DESIGN.md → plugins/bin/.apm/skills/improve-codebase-architecture/references/interface-design.md
View File

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

0
plugins/bin/.apm/skills/improve-codebase-architecture/LANGUAGE.md → plugins/bin/.apm/skills/improve-codebase-architecture/references/language.md
View File

16
plugins/bin/.apm/skills/prototype/SKILL.md
View File

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

2
plugins/bin/.apm/skills/prototype/LOGIC.md → plugins/bin/.apm/skills/prototype/references/logic.md
View File

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

2
plugins/bin/.apm/skills/prototype/UI.md → plugins/bin/.apm/skills/prototype/references/ui.md
View File

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

15
plugins/bin/.apm/skills/research/META.md
View File

@@ -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
```

106
plugins/bin/.apm/skills/research/SKILL.md
View File

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

17
plugins/bin/.apm/skills/tdd/SKILL.md
View File

@@ -1,6 +1,11 @@
---
name: tdd
description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
description: >
Use when the user wants a feature built or a bug fixed test-first, in a strict
red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
metadata:
version: "1.0.1"
---
# Test-Driven Development
@@ -13,7 +18,7 @@ description: Test-driven development with red-green-refactor loop. Use when user
**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
If you need worked examples of the difference — a behaviour-level test beside the implementation-coupled version of the same check — read `references/tests.md`. If a test needs a collaborator faked, read `references/mocking.md` before reaching for a mock.
## Anti-Pattern: Horizontal Slices
@@ -44,14 +49,14 @@ RIGHT (vertical):
### 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.
When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area.
Before writing any code:
- [ ] Confirm with user what interface changes are needed
- [ ] Confirm with user which behaviors to test (prioritize)
- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
- [ ] Design interfaces for [testability](interface-design.md)
- [ ] Identify opportunities for [deep modules](references/deep-modules.md) (small interface, deep implementation)
- [ ] Design interfaces for [testability](references/interface-design.md)
- [ ] List the behaviors to test (not implementation steps)
- [ ] Get user approval on the plan
@@ -88,7 +93,7 @@ Rules:
### 4. Refactor
After all tests pass, look for [refactor candidates](refactoring.md):
After all tests pass, look for [refactor candidates](references/refactoring.md):
- [ ] Extract duplication
- [ ] Deepen modules (move complexity behind simple interfaces)

0
plugins/bin/.apm/skills/tdd/deep-modules.md → plugins/bin/.apm/skills/tdd/references/deep-modules.md
View File

0
plugins/bin/.apm/skills/tdd/interface-design.md → plugins/bin/.apm/skills/tdd/references/interface-design.md
View File

0
plugins/bin/.apm/skills/tdd/mocking.md → plugins/bin/.apm/skills/tdd/references/mocking.md
View File

0
plugins/bin/.apm/skills/tdd/refactoring.md → plugins/bin/.apm/skills/tdd/references/refactoring.md
View File

0
plugins/bin/.apm/skills/tdd/tests.md → plugins/bin/.apm/skills/tdd/references/tests.md
View File

19
plugins/bin/.apm/skills/triage/SKILL.md
View File

@@ -1,6 +1,11 @@
---
name: triage
description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow.
description: >
Use when the user wants an issue created, triaged, or moved through the
tracker's triage states, or an issue prepared for an AFK agent. Not debugging
the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
metadata:
version: "1.0.1"
---
# Triage
@@ -15,8 +20,8 @@ Every comment or issue posted to the issue tracker during triage **must** start
## Reference docs
- [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
- [agent-brief.md](references/agent-brief.md) — how to write durable agent briefs
- [out-of-scope.md](references/out-of-scope.md) — how the `.out-of-scope/` knowledge base works
## Roles
@@ -35,7 +40,7 @@ Five **state** roles:
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
These are canonical role names — the actual label strings used in the issue tracker may differ. The mapping should have been provided to you - run `/setup-matt-pocock-skills` if not.
These are canonical role names — the actual label strings used in the issue tracker may differ. Resolve each canonical name against the tracker's live label set before applying it, using whichever tracker skill this install provides. If a name has no counterpart there, report the gap and ask the maintainer for the mapping — never substitute a guess.
State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
@@ -60,7 +65,7 @@ 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.
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 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.
@@ -69,11 +74,11 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session.
5. **Apply the outcome:**
- `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
- `ready-for-agent` — post an agent brief comment ([agent-brief.md](references/agent-brief.md)).
- `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
- `needs-info` — post triage notes (template below).
- `wontfix` (bug) — polite explanation, then close.
- `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
- `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([out-of-scope.md](references/out-of-scope.md)).
- `needs-triage` — apply the role. Optional comment if there's partial progress.
## Quick state override

4
plugins/bin/.apm/skills/triage/AGENT-BRIEF.md → plugins/bin/.apm/skills/triage/references/agent-brief.md
View File

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

0
plugins/bin/.apm/skills/triage/OUT-OF-SCOPE.md → plugins/bin/.apm/skills/triage/references/out-of-scope.md
View File

14
plugins/bin/.apm/skills/write-docs/SKILL.md
View File

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

4
plugins/bin/.apm/skills/zoom-out/SKILL.md
View File

@@ -2,6 +2,8 @@
name: zoom-out
description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
disable-model-invocation: true
metadata:
version: "1.0.1"
---
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.
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.

30
plugins/bin/.claude-plugin/plugin.json
View File

@@ -1,30 +0,0 @@
{
"name": "bin",
"version": "1.1.5",
"description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"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": {
"obsidian": {
"args": [
"@bitbonsai/mcpvault@0.15.0",
"docs/"
],
"command": "npx",
"type": "stdio"
}
}
}

21
plugins/bin/.github/plugin/plugin.json vendored
View File

@@ -1,21 +0,0 @@
{
"name": "bin",
"version": "1.1.5",
"description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
"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"
}

12
plugins/bin/.mcp.json
View File

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

32
plugins/bin/README.md
View File

@@ -4,40 +4,32 @@ A place for things to be binned
## Install
**Claude Code:**
apm is the only supported install path (ADR-0024). Declare this package in the consuming project's `apm.yml`:
```bash
claude plugin marketplace add <owner>/<repo>
claude plugin install bin@<marketplace-name>
```yaml
dependencies:
apm:
- git: git@git.dev.rkdr.net:Defame1297/holocron.git
path: plugins/bin
```
**GitHub Copilot CLI:**
Then:
```bash
copilot plugin marketplace add <owner>/<repo>
copilot plugin install bin
apm install
```
**Local (development):**
The entry above is unpinned and tracks the remote's default branch — add `ref: <tag>` to pin a release. Registering the catalogue instead (`apm marketplace add git@git.dev.rkdr.net:Defame1297/holocron.git --name holocron`) gets you the `bin@holocron` short name, but writes to `~/.apm/marketplaces.json` at user scope; the git+path object needs nothing beyond the manifest.
```bash
# Claude Code
claude --plugin-dir ./plugins/bin
# GitHub Copilot CLI
copilot plugin install ./plugins/bin
```
**Native plugin installs do not work.** This package ships no per-plugin manifest and no flat content directories, so a host that installs it natively gets zero skills — and Claude Code raises no error while doing it (ADR-0024).
## 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 |
| Skills | `.apm/skills/` | Slash commands available after install |
`.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.
`.apm/` is the authoring source and the only thing apm deploys (ADR-0024). This plugin ships no agents.
## Author

2
plugins/bin/apm.yml
View File

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

5
plugins/bin/evals/research/research/eval.yaml
View File

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

49
plugins/bin/skills/caveman/SKILL.md
View File

@@ -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.

117
plugins/bin/skills/diagnose/SKILL.md
View File

@@ -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.

41
plugins/bin/skills/diagnose/scripts/hitl-loop.template.sh
View File

@@ -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"

10
plugins/bin/skills/grill-me/SKILL.md
View File

@@ -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.

47
plugins/bin/skills/grill-with-docs/ADR-FORMAT.md
View File

@@ -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.

77
plugins/bin/skills/grill-with-docs/CONTEXT-FORMAT.md
View File

@@ -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.

88
plugins/bin/skills/grill-with-docs/SKILL.md
View File

@@ -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>

44
plugins/bin/skills/improve-codebase-architecture/INTERFACE-DESIGN.md
View File

@@ -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.

53
plugins/bin/skills/improve-codebase-architecture/LANGUAGE.md
View File

@@ -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**.

71
plugins/bin/skills/improve-codebase-architecture/SKILL.md
View File

@@ -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).

79
plugins/bin/skills/prototype/LOGIC.md
View File

@@ -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.

30
plugins/bin/skills/prototype/SKILL.md
View File

@@ -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.

112
plugins/bin/skills/prototype/UI.md
View File

@@ -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.

15
plugins/bin/skills/research/META.md
View File

@@ -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
```

97
plugins/bin/skills/research/SKILL.md
View File

@@ -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>

39
plugins/bin/skills/research/references/file-format.md
View File

@@ -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`).

17
plugins/bin/skills/research/references/topics.md
View File

@@ -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.

109
plugins/bin/skills/tdd/SKILL.md
View File

@@ -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
```

33
plugins/bin/skills/tdd/deep-modules.md
View File

@@ -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?

31
plugins/bin/skills/tdd/interface-design.md
View File

@@ -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

59
plugins/bin/skills/tdd/mocking.md
View File

@@ -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

10
plugins/bin/skills/tdd/refactoring.md
View File

@@ -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

61
plugins/bin/skills/tdd/tests.md
View File

@@ -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");
});
```

168
plugins/bin/skills/triage/AGENT-BRIEF.md
View File

@@ -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

101
plugins/bin/skills/triage/OUT-OF-SCOPE.md
View File

@@ -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

103
plugins/bin/skills/triage/SKILL.md
View File

@@ -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.

103
plugins/bin/skills/write-docs/SKILL.md
View File

@@ -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

7
plugins/bin/skills/zoom-out/SKILL.md
View File

@@ -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.

35
plugins/core/.apm/skills/agentsmd-audit/README.md
View File

@@ -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.

40
plugins/core/.apm/skills/agentsmd-audit/SKILL.md
View File

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

27
plugins/core/.apm/skills/agentsmd-author/README.md
View File

@@ -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 |

33
plugins/core/.apm/skills/agentsmd-author/SKILL.md
View File

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

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

@@ -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.

Some files were not shown because too many files have changed in this diff Show More