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

Compare commits

base: Defame1297:v2.0.0
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:971e148e19b5d8906d283d57b99c243837342733
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

98 Commits
v2.0.0 ... 971e148e19

Author SHA1 Message Date
Defame1297
971e148e19 docs: amend ADR-0020 and correct the gate reference to match what ships 
The ADR said a /slash target behind a route verb takes the follower test; the
implementation decides notation first and skips it. Recorded as a dated amendment
rather than a silent edit, per the ADR-0016/0017 convention.

Its Enforcement table called itself exhaustive 'because the failure this ADR is
most exposed to is a rule filed under Enforcement that no validator implements'.
Three shipped behaviours were missing, including the disable-model-invocation
carve-out that removes two rows. Also de-pins the 'zoom-out is the one carrier'
claim, which caveman falsified, and the stale dangling-target statuses.

gates.md's ERROR row made terminality a conjunct for route notation, telling an
author a form is safe that exits 1. It now documents the references/ Vale blind
spot and its two independent causes -- AGENTS.md trimmed to the operative rule
per the split gates.md itself states -- plus the undocumented skill-frontmatter
hook and the second scope exclusion. CONTEXT.md glosses 'routing target'.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:47:04 +00:00
Defame1297
4011d149bc fix(bin): put five skills' boundaries where the router can read them 
grill-me, grill-with-docs, improve-codebase-architecture, tdd and triage each had
their routing boundary written into README.md, which nothing loads at runtime,
while the gate still reported all five descriptions as boundary-less. The
boundaries move into the descriptions; write-docs' clause, which said 'those have
dedicated skills' without naming one, now names them.

research had moved its body out and then read both references unconditionally --
the anti-goal ADR-0020 names, where the word count moves and the per-run context
does not. Both loads are genuinely conditional now, with the topic list and the
four literal sources.md field names inlined, since the provenance validator
matches those literally.

Also restores the promote-the-prototype anti-pattern to prototype's ui.md, which
the gate does not measure, so deleting it bought nothing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:47:00 +00:00
Defame1297
ae791781c2 fix(git): restore router coverage and commands the retrofit dropped 
git-workflow calls itself a router but named two of the six domains it routes to;
the other four appeared nowhere in the file. All six are now named, with a
routing table in the always-loaded body.

git-submodules lost the foreach shell-variable semantics -- only the bare names
survived, though $sm_path and $displaypath differ solely by which directory you
are in. The table is back. Its relocated commands had also dropped the rtk git
prefix its own SKILL.md mandates; 24 of them are re-prefixed. The wider rtk
inconsistency across the plugin stays with #113.

Also restores git-commits' body and footers output fields, git-branches' tag/
branch detection commands, git-worktrees' git config --worktree, pc-run's
ambiguity fallback, git-remotes' git-history boundary, and git-history's pickaxe
triggers.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:46:35 +00:00
Defame1297
1a971ee003 fix(gitea): restore routing and sourcing content the retrofit dropped 
gitea-issues asserted flatly that a merge never closes an issue, contradicting
gitea-prs' references/merging.md, which documents that closing keywords in
commits landing on the default branch do close one. The qualifier that made the
claim true had been deleted; both sides now agree.

gitea-releases had lost an epistemic hedge and its verification step, leaving
conventions.md asserting unconfirmed tag auto-creation as fact. Nothing in the
research corpus sources it, so the hedge and the verify-afterward instruction are
back rather than upgraded.

Descriptions were cut 50-240 chars under the 400 budget and shed routing with
them: gitea-workflow's boundary named no target, gitea-prs lost the issue/PR
number-space directive the suite is built around at 163/400, gitea-releases lost
its boundary and every trigger. Restored, inside budget. Also restores
delete_branch's hard-refusal strength and gitea-files' Read/Write/Edit pointer.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:46:32 +00:00
Defame1297
a8cd5e881d fix(core): strip a BOM before the adapter import check, and split usage exits 
Narrowing has_reference to bool(import_lines) meant a UTF-8 BOM hid the import
line, since the BOM is not \s: a CLAUDE.md whose first line is @AGENTS.md failed
with 'no reference to AGENTS.md' and was told to add the line already in front of
it. Decoding is now strict too, so a non-UTF-8 adapter gets an encoding
diagnostic instead of being mangled and then graded on the mangling.

Usage errors move to exit 2. They shared exit 1 with real findings, while the
skill tells the agent to fix any non-zero exit by editing the provider file.

The whole-line import rule is kept deliberately -- accepting an inline @AGENTS.md
would also accept one inside backticks, which is the silent-drop failure the
validator exists to catch -- and the message now says so.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:46:07 +00:00
Defame1297
00daf285ec fix(kyberforge): tell an unparsable Contributing-files block from an explicit (none) 
parse_contributing_files documented that callers depend on None vs [], because a
parse failure returning [] would silently disable the check. Only check 8
honoured it; checks 4/5 (skill-audit) and 3/4 (agent-audit) used a truthiness
test, so an unreadable block disabled them without a word.

Two live corpus entries were skipping this way. A sweep of all 32 sources.md
found 134 entries, exactly 2 parsing to None, both in gitea-files: one heading
carried an inline parenthetical that defeated both regexes, and one (none) was
written without its leading bullet. Also pins EMPTY_SOURCE_KEYS_RE to the two
indents parse_source_keys actually reads.

agent-audit had no INFO tier at all, so it gains one rather than reporting a
check that could not run as a FAIL.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:46:05 +00:00
Defame1297
c232e69645 fix(gates): block a dangling /name route with no preceding verb 
The header promised explicit route notation always blocks. It did not: /name
reached extraction only behind a ROUTE_VERB, so a target with no verb before it
was never extracted at all -- exit 0, no output. Taking the SUGGESTION's own
advice ('write it as /name and it will be checked properly') was the one edit
that blinded the gate.

Adds two notation sweeps gated on BOUNDARY_MARKER and routed through _add, plus
a path guard so file paths and URLs are not read as routes. Also excises the
matched pointer span before the REFERENCE_PAST sweep, so a reference file can no
longer exempt itself by its own filename, and guards the agent branch with the
isfile test the skills branch already had.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EJJrm5YmacbwMdzZpXcoti
 2026-08-31 19:45:45 +00:00
Defame1297
5b80f305e9 test(kyberforge): pin the provenance checker's three new behaviours 
27a7669 changed validate-provenance.sh in three ways and tested none of
them: the bullet-form parser returning None rather than [] on unparsable
input, the source_keys: [] house-authored declaration, and the stripping
of section annotations off a Research doc path.

All three are checks that previously failed by staying silent, which is
the failure mode this repo keeps rediscovering. Shipping them untested
left nothing to catch a regression back to silence.

The 22 cases assert consequences rather than return values -- that check
8 runs on an unparsable block, that an unresolvable path emits an INFO
naming its slug -- and each was verified against a deliberate mutation
of the behaviour it covers.

Addresses #111.
 2026-08-31 08:28:25 +00:00
Defame1297
8599b4a058 chore(release): bump the marketplace version to 0.5.0 
0959291 bumped all six plugin versions for the ADR-0020 retrofit but left the
marketplace itself at 0.4.5, so consumers resolving against the marketplace
entry would see no change despite every packaged plugin having moved.
 2026-08-31 08:02:49 +00:00
Defame1297
ee248ff5a5 docs: describe the boundary check's new outcomes and de-pin stale counts 
The gate spec still described the routing-target check as pass/fail against a
single-arrow clause. It now documents the three outcomes, the hand-invocation
carve-out and the one-arrow rule, so a contributor hitting a SUGGESTION can
tell whether it is a real defect or accepted phrasing.

Both files cited skill counts and source line numbers that go stale on the
next edit and were already wrong; those citations are removed rather than
refreshed.
 2026-08-31 08:02:44 +00:00
Defame1297
131b89733b fix(apm-orchestrate): correct the marketplace add-package direction and trim duplication 
`apm marketplace package add` rejects a local path — it registers a remote
package reference — but the agent routed local-package registration to it, so
that dispatch could only fail. Local registration is a manifest edit and now
routes to `edit-config`.

The agent also carried its own copy of the `type:` guidance and a numbered
workflow that restated the dispatch procedure below it; both drift from
apm-workflow independently. `type:` correctness is delegated where it belongs,
and the description is rewritten to a trigger plus the apm-install boundary
rather than a restatement of the body.

Addresses #120.
 2026-08-31 08:02:38 +00:00
Defame1297
dac9cad912 refactor(kyberforge): move audit guidance out of the per-run rubric load 
skill-audit loaded roughly 4,268 words of rubric on every run, most of it
criteria for findings a clean skill never triggers. The auditing guidance moves
into finding-criteria.md, read only when a finding is actually raised, cutting
a clean audit to about 999 words. The named-skill exemption is replaced with
properties, so the rubric stops carrying a list that ages the moment a skill
is renamed.

apm-workflow's `type:` trap sat in one flow while biting several, so it is
promoted to a common gate reachable from all of them; its claim to be
self-contained was untrue once it started routing to apm-install. skill-author's
contract had drifted from body-discipline.md and is realigned, and agent-audit's
field inventory is brought in line with the same split.
 2026-08-31 08:02:19 +00:00
Defame1297
e869912374 docs(bin): give every bin skill a README 
The bin skills were the only plugin without per-skill READMEs, so a reader
had to open SKILL.md — an agent-facing contract, not an explainer — to learn
what a skill does and when it fires. Each README states purpose, triggers and
boundaries for a human audience, leaving SKILL.md free to stay terse.
 2026-08-31 08:02:09 +00:00
Defame1297
03abcffb77 refactor(bin): cut per-invocation load and repair broken skill references 
diagnose read its feedback-loops reference unconditionally, so every
invocation paid for guidance most runs never used; the read is conditional
again and the per-invocation cost drops from 1,278 to 831 words. Its HITL
template moves to assets/ because it is copied out, not read as reference.
prototype's two branch flows move into references/ for the same reason —
only one branch is ever taken.

research could not search the codebase it was asked to research without Grep
and Glob. caveman's description had grown into a paragraph where one sentence
carries the trigger. Four references pointed at things that do not exist: a
to-prd skill, a /setup-matt-pocock-skills command, two cross-skill ../ links
that only resolve in the source tree, and two places calling this project's
Gitea host GitHub.

Addresses #114.
 2026-08-31 08:02:03 +00:00
Defame1297
1c3af75642 fix(core): make --no-import-syntax actually change the adapter validation 
Both branches of the flag reduced to the same expression, so the option was
inert: a caller who asked for the no-import form got the import-form check
anyway and a passing result that meant nothing.

Two further defects in the same validator: --max-lines failed silently when
given a value it could not use, and the Fix text told the agent to edit
AGENTS.md when the offending content is the provider adapter's. The boundary
clauses now name the operation being routed rather than the file type, which
was ambiguous where both skills touch the same file.

Addresses #115.
 2026-08-31 08:01:45 +00:00
Defame1297
14af50bc07 fix(git): scope git-workflow's trigger to ambiguity rather than to its domains 
git-workflow's description enumerated the six domains it exists to route away
from, so it competed for selection with the very skills it should be handing
off to. It now triggers on the case it actually serves: an interactive request
whose domain is not yet clear.

Also clears frontmatter drift across the plugin and removes duplicated guidance
in pc-run that had diverged from its reference.
 2026-08-31 08:01:39 +00:00
Defame1297
8680adf4c0 fix(gitea): make gitea-releases executable and correct misleading domain claims 
gitea-releases was the weakest skill in the plugin: no allowed-tools, no
owner/repo resolution, and a checkbox list where a dispatch table belongs, so
an agent reaching it had to guess both its permissions and its inputs. The
id-vs-tag_name trap — deleting by tag name where the API wants the numeric id —
is restored as an explicit Gotcha because it destroys the wrong release
silently.

Elsewhere the `exclusive` flag was documented on the wrong side of the
read/write split, and label data from one instance was presented as though it
were universal, which invites an agent to assume a taxonomy that does not
exist on the target repo. rename_branch was missing from the branch surface.
Reference prose and fences are cleaned up in passing.
 2026-08-31 08:01:33 +00:00
Defame1297
b07d54ad7a fix(lint): correct four Vale behaviours the skills described wrongly 
Each of these would send a user down a path Vale does not support:

Core options placed under a glob header are not scoped to that glob — Vale
rejects them with E201, so the guidance to nest them produced a config that
will not load. The built-in `Vale` style is compiled in, but Vale still
requires StylesPath to exist on disk before it will run, so the "no StylesPath
needed" shortcut fails. The MDX guidance was inverted: under `[formats]
mdx = md` the mapping is what makes MDX lint at all, and it needs the mdx2vast
prerequisite that was never mentioned. And a spelling rule's `ignore` paths
resolve against StylesPath, not against the rule file's own directory, so the
documented relative paths silently matched nothing.
 2026-08-31 08:01:26 +00:00
Defame1297
27a76692b0 fix(kyberforge): stop the provenance checker skipping check 8 on unparsed input 
484357a taught the Contributing parser the bullet form, but a block it still
could not parse returned the same empty result as an explicit "(none)", so the
checker read "no contributing files" and skipped check 8 rather than reporting
that it could not tell. Checks 7 and 8 were consequently dead across the whole
git plugin without anything failing.

The parser now distinguishes "declared none" from "could not parse", which
wakes both checks. Because the parser is duplicated between the skill-audit and
agent-audit copies, it is fenced with BEGIN/END markers and a test hashes the
two regions so the copies cannot drift apart again silently.

Addresses #111.
 2026-08-31 08:01:18 +00:00
Defame1297
db5a426416 fix(gates): make the ADR-0020 boundary check parse what skills actually write 
The routing-target check understood only a single-arrow clause naming a bare
skill, so most real boundary prose was silently skipped rather than verified.
Two of those silences were fail-open: an unrecognised token following a target
dropped that target from the check entirely, and a skill directory with no
SKILL.md still resolved as a valid routing target, so a broken route passed.

Multi-target arrow clauses now draw a SUGGESTION instead of being ignored,
hand-invocation phrasing is carved out so it is not read as a route, and a
dotted filename parses into a new `unparsed` status rather than disappearing.
Three test fixtures had been relying on the SKILL.md-less directory resolving
as a target; they are corrected alongside the check.

Addresses #107, #108, #110.
 2026-08-31 08:01:07 +00:00
Defame1297
095929142f chore(release): bump all six plugin versions for the ADR-0020 retrofit 
No wave on this branch bumped a version across 56 commits, though
apm-workflow's own configure.md states the policy: bump a package's
apm.yml version: whenever anything reaching its compiled output changes.
All six local packages have substantive .apm/ edits here.

Minor rather than patch. The retrofit rewrote every skill description,
which is the routing surface a caller matches against, and redistributed
bodies into references/. Behaviour is preserved but discovery changes, so
this is more than a fix.

The same file is explicit that versions are per package — editing
plugins/foo/.apm/ never bumps plugins/bar — so this is six independent
bumps that happen to land together, not one release number. Under the
per_package strategy the catalog carries a second copy in
marketplace.packages[], and apm-marketplace-check fails the push when the
two disagree; it cannot see a bump skipped in both, which is the state the
branch was in.

executables.allow is version-pinned by apm's design and moves with
kyberforge, or the SessionStart hook silently stops deploying (ADR-0019).
The comment above that block predicted exactly this; the pre-push suite
caught it when the first bump orphaned the key.

Refs #99
 2026-08-30 21:00:58 +00:00
Defame1297
c7c9311d80 docs(gates): refresh the retrofit status to measured state 
docs/spec/gates.md still described both ADR-0020 gates as "currently red"
and tabled the pre-retrofit figures: 26 of 39 descriptions and 9 of 39
bodies over their FAIL tier, 2 dangling targets, 58 SUGGESTIONs, and 10
Kyberforge.CompositionNote errors across four gitea-* skills. Measured
now: 0, 0, 0, 33 and 0.

The branch correctly left ADR-0020 itself untouched, since it self-pins
every citation to base commit f9b919d. gates.md carries no such pin, and
AGENTS.md names it three times as the authoritative reasoning layer — so
the shallow doc and the deep doc it defers to asserted opposite facts
about the same two gates, with the stale one telling a reader that an
unrelated one-line fix to a skill is blocked pending a retrofit that is
already done.

Also corrects the apm-orchestrate agent body figure, which drifted from
1,080 to 1,113 across this branch. Its point is that the numbers are live
evidence for leaving that hook's files: pattern alone, so a reader who
re-measures and gets a third value loses the argument.

AGENTS.md gains the second cause of the references/ blind spot: besides
the Kyberforge style being scoped [**/SKILL.md], the
vale-audit-prefilter-skill hook filters on a SKILL.md-only files: pattern,
so widening .vale.ini alone would change nothing. It also no longer
implies the kyberforge wave was the end of the work.

Refs #99 #117
 2026-08-30 20:52:06 +00:00
Defame1297
484357a3b9 fix(gates): parse the bullet form of Contributing files 
validate-provenance.sh matched Contributing files only as a single inline
line beginning "- **Contributing files:**". Seven skills write it as a
bare "**Contributing files:**" heading above a bullet list, so
parse_contributing_files returned None and checks 4 (contributing file
exists) and 5 (bidirectional source_keys) silently verified nothing on
git-branches, git-remotes, git-submodules, git-workflow, git-worktrees,
gitea-files and gitea-releases.

Those are among the skills this branch changed most — git-branches alone
gained five reference files — and the retrofit's mandatory sources.md
collateral went in unchecked. Demonstrated rather than argued: planting a
nonexistent contributing path in git-remotes yields 0 findings under the
old parser and 1 FAIL under the new one.

Both forms are now accepted. The bullet form is parsed per bullet rather
than by splitting a joined value, because its per-file notes contain
commas that would otherwise be read as path separators. The return type
becomes a list of note-stripped paths, with "(none)" as an empty list and
an absent entry as None, so the two callers no longer re-split a string.

Applied to agent-audit's copy as well. No agent ships a sources.md today,
so it is latent there, but it is the same defect.

This is a third gate blind spot alongside #117 and #118, and was unfiled.
One real defect surfaced immediately and is fixed separately.

Refs #99
 2026-08-30 20:51:56 +00:00
Defame1297
164948a0bc fix(apm-workflow): type: selects processing, it does not validate content 
configure.md said apm.yml's `type:` field "constrains what .apm/ may
contain" and that changing it later "does not retroactively validate what
is already on disk" — both implying a validation step that does not exist.
Read against the installed apm-cli 0.28.0: PackageContentType controls how
a package is processed during install/compile, apm_package.py only
enum-checks the declared string, and validate_apm_package() branches on the
structural type derived from files on disk, never on the declared field.
There is no content-vs-type mismatch check anywhere.

The hazard is therefore the opposite of what the wording primed for:
silent omission. A package declaring type: instructions while shipping
.apm/skills/ installs no skill and compiles AGENTS.md only, exits 0, and
reports success having shipped none of its primitives. The rule is now to
verify deployed output rather than the exit code. apm-orchestrate carried
the same wording as a Hard Rule and is corrected in step; its separate
defects stay with #120.

Also refreshes the exemplar figures this branch had re-staled. 264a5db set
them to 3,222 words of references; 6cb47f8 then added 63 words and
invalidated them, and the correction above adds more. Re-measured after
all edits: body 237 and whole-file 304 both still hold, references total
3,416. body-discipline.md's "roughly 3,200" moves with it.

ADR-0020 is deliberately untouched — it self-pins its citations to
f9b919d — as is the git-commits negative example pinned to 5e23250.

Refs #99
 2026-08-30 20:51:45 +00:00
Defame1297
ca744d5d6c fix(vale-config): correct the missing-style failure mode 
Gotcha 1 said a style in BasedOnStyles that is not built-in and not
already under StylesPath "finds nothing until vale sync fetches it — a
clean run is not proof anything linted". Reproduced against vale 3.15.2:
that case is a hard `E100 [loadStyles] style '<name>' does not exist on
StylesPath`, exit 2. Nothing is linted and nothing is silent.

Worse, the same commit deleted the Gotcha that was the actual diagnostic —
that Packages and BasedOnStyles are separate keys and a style lints only
once it is in both. So the surviving rule sent a reader staring at E100 to
run `vale sync`, which fetches only what Packages declares and reports
"Synced 0 package(s)" against a BasedOnStyles-only name. The remediation
loop did not terminate. Reproduced end to end.

The genuinely silent case is the reverse — declared in Packages and
synced, but absent from BasedOnStyles — and it is now the one labelled as
such. Testing also turned up that StylesPath must exist as a directory
even when Vale is the only style (E201, exit 2), which was documented
nowhere.

references/configuration-reference.md gains a seven-row resolution matrix,
each row backed by a fixture. Its Frontmatter Scopes section claimed
provenance from the vale.sh research corpus, which contains no frontmatter
material at all; it is house-verified and now says so under its own slug.

Issue #99's wave-3 comment recorded this defect as found and repaired. It
was not — the file was byte-identical to the commit that introduced it, so
nothing here was treated as already correct.

Refs #99
 2026-08-30 20:51:32 +00:00
Defame1297
d2da45f78c fix(gitea-releases): restore the prerelease imperative to the create path 
The retrofit left only a descriptive sentence on the loaded path — "Gitea
never infers a prerelease from a -beta/-rc tag name" — and moved the
imperative into references/conventions.md behind a trigger listing semver
naming, release-notes sourcing and release-to-tag relationships. Draft and
prerelease are not in that list, and "cut a v2.0.0-beta.1" is exactly the
request where the caller does not raise the topic, so the rule was
unreachable from the flow that needs it.

Severity comes from the repair path: the MCP surface has create, get,
get_latest, list and delete only — there is no update or edit tool. A
release published without is_pre_release can only be corrected by
delete_release plus a fresh create, and get_latest_release points
consumers at the beta meanwhile. Neither SKILL.md nor call-signatures.md
said so anywhere.

The flags are now set explicitly on every create, the missing update tool
and its delete-and-recreate consequence are stated in the body, and the
semver pass-through rule stranded behind the same trigger is promoted
alongside it. call-signatures.md now cites the deployed tool description
as direct evidence that get_latest_release excludes drafts, while keeping
the prerelease half hedged — that remains unconfirmed.

Verified live against gitea-mcp v1.7.0, read-only calls.

Refs #99
 2026-08-30 20:51:22 +00:00
Defame1297
8982ac58b7 fix(gitea-labels-milestones): read exclusive per label, never infer it 
SKILL.md called `exclusive` "an org-labels-only flag" and concluded that
applying a Kind/*, Priority/* or Status/* label "must replace the one
already there, not stack on it". Live `list_repo_labels` on this repo
returns `exclusive` on every REPO label: all seven Kind/* plus
Compat/Breaking are false, while Priority/*, Reviewed/* and Status/* are
true. So the field is not org-only, and the replace rule would strip a
valid Kind/* label — a destructive write from a false premise.

The nuance kept: label_write's `exclusive` parameter genuinely is
annotated org-only, so that row was schema-accurate. The error was
generalising a write-parameter restriction into a claim about where the
field exists. The row is qualified rather than deleted.

The rule is now per-label: where exclusive is true the server drops the
sibling itself, so do not pre-remove; where it is false the label is
legitimately stackable.

Also fixes the org-label fallback, which treated any list_org_labels
failure as proof the owner is a user account with no org pool and said so
was "an answer, not an error to report". Under the token scopes this skill
declares the call fails with required=[read:organization] before any
org-vs-user determination is made, so a capability gap was being reported
as an absent label. Scope errors are now distinguished and reported.

Verified live against gitea-mcp v1.7.0, read-only calls.

Refs #99
 2026-08-30 20:51:12 +00:00
Defame1297
dd1981db80 fix(gitea-issues): list_issues does have type and milestones on v1.7.0 
SKILL.md's headline Gotcha said `list_issues` "has no `type` filter", and
references/issues.md stated in bold that neither `type` nor `milestones`
exists, "despite both appearing in api-reference.md". Both parameters are
present on the deployed gitea-mcp v1.7.0 and both work: `type: "issues"`
returns only issues, `type: "pulls"` only PRs, and `milestones` filters by
name. Unfiltered, the same window returns them interleaved, so the mixing
the Gotcha describes is real — only the stated remedy was wrong.

This mattered most in gitea-workflow's no-args check-in, which lists open
issues through this skill and so reported PRs under "Open Issues" while
the skill forbade the one-parameter fix. The list flow now passes
`type: "issues"`.

references/sources.md recorded the absence as a live-verification win over
stale research docs; it now records that the earlier check was superseded
by v1.7.0, since drift runs in both directions. gitea-prs cited the same
parameter as its canonical drift example and no longer does — no
replacement example was substituted, because the obvious candidate was not
verified in this pass.

Also defaults label writes to `add_labels`: `replace_labels` clears every
label not in the array, and per-label exclusivity makes blanket replacement
destructive for a non-exclusive scope.

Verified live against gitea-mcp v1.7.0, read-only calls.

Refs #99
 2026-08-30 20:51:02 +00:00
Defame1297
c5b207aee8 fix(git-branches): restore merging.md's provenance back-reference 
references/sources.md credits atlassian-gitflow-tutorial with contributing
the `--no-ff` requirement on Gitflow supporting-branch merges to
references/merging.md, and merging.md:14 does carry that claim — but the
file's own source_keys listed only context7-git-htmldocs, so the chain was
one-directional.

Surfaced by repairing validate-provenance.sh's Contributing-files parser
in the same series; this skill was one of seven whose sources.md the old
parser could not read, so checks 4 and 5 had never run against it.

Refs #99
 2026-08-30 20:50:51 +00:00
Defame1297
93d3263f8c fix(pc-run): rebind the clean gate and fixer-hook rule to every branch 
SKILL.md tells a dispatching agent to read the matching reference file
"and no other". The retrofit moved the `pre-commit clean` confirmation
gate out of the always-loaded body into references/clean.md, but
references/failure-patterns.md — loaded by the diagnosis route, not the
clean route — prescribes `pre-commit clean` with no gate at all. So "why
is this hook failing" could wipe the machine-wide cache at
~/.cache/pre-commit for every repo without asking.

The gate returns to the body, where every branch loads it, and is
restated at the point of use in failure-patterns.md. It is its own
section rather than a Gotchas bullet because folding it in pushed the
Gotchas ratio to 41%, whose only suggested remedy is moving it back to
references/ — the move that caused this.

The fixer-hook rule had the same shape: reachable only behind "if the
cause is not obvious from the output", which is false precisely when
pre-commit prints `- files were modified by this hook`. The fix
(`git add -u && git commit`) and the prohibition on `pre-commit install -f`
are now unconditional, and the two weakened pointers that stranded them
are restored.

Found by an independent review of this branch.

Refs #99
 2026-08-30 20:50:45 +00:00
Defame1297
ddf85518c7 fix(git-worktrees): correct the remote-tracking and repair claims 
The dispatch row "Create tracking a remote branch" prescribed
`git worktree add <path> <remote>/<branch>`. Per git-worktree(1) the
tracking DWIM fires only when <commit-ish> is a bare branch name that is
NOT found locally, no -b/-B/--detach is given, and exactly one remote has
a matching name; only then is it equivalent to
`git worktree add --track -b <branch> <path> <remote>/<branch>`.

An explicit <remote>/<branch> is found, so that precondition fails and no
branch is created: the result is a detached HEAD with no upstream. Commits
made in it become unreachable once the worktree is removed or HEAD moves,
and push needs an explicit refspec. Only the -d row was flagged detached.

The table now names --track -b as the always-correct form, keeps the bare
name shortcut with its precondition stated, and adds a Never row for the
<remote>/<branch> spelling. The single-remote and checkout.defaultRemote
preconditions move into the body, since a reader who trusts the table
never follows the reference pointer.

Also corrects `git worktree repair`: the no-argument form is the only
cwd-dependent one, and `repair <path>...` runs from any worktree. The
claim that running it from the wrong directory "reports nothing and fixes
nothing" has no basis in the manual and is removed.

Found by an independent review of this branch.

Refs #99
 2026-08-30 20:50:36 +00:00
Defame1297
6cb47f81f6 fix(apm-workflow): surface the registries precondition in compile/install 
SKILL.md says the apm experimental enable registries precondition
applies "anywhere — configure, install or publish," but only
configure.md actually carried it. compile.md's Publish flow and
install.md's dependency resolution can both hit a named registry and
silently no-op with no error if the precondition was never run, yet
neither file mentioned it — contradicting the skill's own promise that
each reference file is self-contained for its concern. Add a one-line
cross-reference to configure.md's Gotchas in each.

Found by an independent post-closure audit of #99 (agent-audit +
skill-audit re-run against every changed skill/agent).
 2026-08-30 19:31:21 +00:00
Defame1297
0c0df46ac9 fix(gitea-releases): hedge the unconfirmed tag-deletion direction 
The retrofit (dfacf05) collapsed a Gotcha into a bidirectional claim —
"deleting a tag never deletes the release wrapping it" — that
references/call-signatures.md never confirms; that file explicitly
marks the reverse direction unconfirmed and "the more dangerous
direction to get wrong." State only the confirmed direction (deleting
a release doesn't delete its tag) and flag the reverse as unconfirmed
with a verification step, on a destructive, irreversible operation.

Found by an independent post-closure audit of #99 (agent-audit +
skill-audit re-run against every changed skill/agent).
 2026-08-30 19:31:18 +00:00
Defame1297
59aaec4ed6 fix(gitea-branches): repoint dangling overview.md citation 
references/commits.md cited overview.md as the authority for a
scope-gating claim, but no such file exists in this skill's package —
the only overview.md is an external research doc not shipped with the
skill. Repoint to branches.md's own Token scope section, which states
and confirms the same principle, and drop the unverifiable
write:repository enumeration detail no file in this skill actually
makes.

Found by an independent post-closure audit of #99 (agent-audit +
skill-audit re-run against every changed skill/agent).
 2026-08-30 19:31:15 +00:00
Defame1297
92ba9abe7c fix(diagnose): restore skill-root-relative script path 
00c1e6b (the ADR-0020 retrofit of diagnose) moved a bullet referencing
scripts/hitl-loop.template.sh out of SKILL.md and into the new
references/feedback-loops.md, and in the move flipped the correct
skill-root-relative path into an incorrect parent-relative one
(../scripts/...) -- despite that commit's own message claiming to fix
"a script path that did not resolve." References in this skill are
written relative to the skill root regardless of which file carries
them, matching the convention used throughout SKILL.md.

Found via an independent post-closure audit of issue #99; validated
clean via skill-audit afterward.

Refs #99
 2026-08-30 17:45:56 +00:00
Defame1297
38efd2be67 fix(skills): collapse verb-enumerated descriptions to one capability clause 
An independent audit of the ADR-0020 retrofit (issue #99) found that
git-submodules, git-worktrees, and gitea-files each collapsed their
description length correctly during retrofit but left the capability
clause as a verb enumeration (e.g. "Create, list, lock, move, remove,
prune, or repair") instead of ADR-0020's required single clause. The
deterministic char-count gate can't catch this — it's a qualitative
rubric violation the retrofit commits' own messages never claimed to
address, only measurable length/word-count fixes.

Validated clean via skill-audit and skill-size-check after the fix;
boundary clauses and routing targets left untouched.

Refs #99
 2026-08-30 17:45:50 +00:00
Defame1297
bdff6fdb3c refactor(bin): make caveman hand-invoked only 
Sets `disable-model-invocation: true`, so the host withholds caveman from
the model-visible skill listing. It stops paying preload tax and can only
be reached by typing /caveman.

The reason is not the 287 characters. caveman's description was almost
entirely a trigger list -- "caveman mode", "talk like caveman", "less
tokens", "be brief" -- and "be brief" is a false-positive magnet: a user
asking for brevity wants short answers, not dropped articles and
`Respond terse like smart caveman`. Removing the skill from the router
deletes the bad trigger. User's call, made explicitly.

Safe to flag because the flag also hard-blocks the Skill tool, so any
inbound route from another skill would break. Re-checked all 39
descriptions and bodies after four waves of retrofit rewrites: every
mention of caveman is documentation, research notes or the lockfile.
Nothing routes to it.

The description is rewritten as human-facing text, since it is no longer
a routing surface -- it now says how to turn the mode on and off rather
than listing phrases for a reader that can no longer see it.

The two remaining SUGGESTIONs are #108: the boundary-clause check fires on
hand-invoked skills, which ADR-0020 contractually exempts. Advisory, and
not to be "fixed" in the skill.

Preload tax 10,002 -> 9,732 chars across 37 model-visible skills.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 17:04:45 +00:00
Defame1297
b25412bf39 docs: record that the ADR-0020 corpus is clean, and what the gates still miss 
Wave 4 closed the last three FAILs, so the session rule no longer describes
a grandfathered set: all 39 skills clear both tiers, 0 descriptions over 400
chars and 0 bodies over 900 words. Preload tax 21,033 -> 10,201 chars
(~2,550 tokens), under the 12,000 success criterion in #99.

The rule now says what that changes for the reader: nothing is grandfathered,
so the gates bite on first commit rather than waiting for a retrofit.

Also names the second blind spot, found this wave. The Kyberforge Vale style
is scoped [**/SKILL.md], so every references/ file is unlinted -- and the
contract's own remedy is to move prose into references/, which moves it out
of the prose gate's reach. forge's retrofit relocated ~900 words that way and
the moved prose carried a rule violation Vale would have caught in a SKILL.md.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:42:59 +00:00
Defame1297
79c60715dc fix(gates): restore byte-identity of the shared ADR-0020 boundary resolver 
915eb09 rewrote the bare-arrow carve-out comment in scripts/skill-size-check.sh
without pasting the block over the two other copies, so the resolver stood at
764 lines in the hook and 755 in both audit validators.
tests/test-adr0020-contract.sh exists to catch exactly this and did -- it was
the regression behind that suite's failure, and I reported the suite green
after 915eb09 without re-running it.

No behaviour changes: the drift was comment-only. Restoring identity keeps the
invariant the test enforces, which matters because the three copies are the
only thing making the hook and the two validators agree on what a boundary
target is.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:42:51 +00:00
Defame1297
264a5dbd67 docs(kyberforge): refresh the apm-workflow exemplar figures after its retrofit 
body-discipline.md and contract.md both cite apm-workflow by hard number
as the reference dispatch shape, and instruct authors to calibrate against
its body word count. The retrofit in 1e4aab5 moved every one of those
figures: body 421 -> 237, whole-file 554 -> 304, references 3,006 ->
3,222. Measured, not estimated.

The quoted closing line was stale too -- it now carries a continuation
clause, so it is quoted with an ellipsis rather than as a full sentence.

These are positive exemplars in live guidance, so they are refreshed
rather than pinned. That is the opposite treatment from the git-commits
negative example in the same file, which is pinned to 5e23250 precisely
so it keeps describing the pre-retrofit state. ADR-0020 carries the same
figures and is deliberately left alone: it self-pins every citation to
base commit f9b919d, and refreshing it would destroy the record of what
the decision was taken against.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:31:43 +00:00
Defame1297
aa982b9d26 refactor(kyberforge): retrofit apm-install to the ADR-0020 contract 
Description 514 -> 213 chars, Gotchas 5 entries/47% -> 2 entries/17%.
Body 350 -> 397 words: three Gotchas fold into the steps they gate, and
the repairs below add back what the fold dropped.

Cuts the second trigger register, the runtime enumeration (still named in
the body and README) and the enumeration inside the boundary clause.

Fixes four defects the first pass introduced:

- The mirror bullet claimed the piped one-liner "ignores" VERSION and
  GITHUB_URL. The installer reads both from the environment and its own
  usage header documents VERSION working through the pipe. The real
  constraint is that an air-gapped host cannot reach aka.ms, so the
  script must be on disk. Also corrects the variable names --
  APM_RELEASE_BASE_URL is the mirror base, GITHUB_URL is the Enterprise
  host.
- "If apm --version already answers, skip to Step 2" was unconditional on
  intent, so a pin or upgrade request routed past the only pin
  instruction in the skill. Now gated on intent.
- The PEP 668 rule was demoted to post-failure recovery, leaving a
  routing rule that sent a Debian box into a command that hard-fails.
  The prohibition is back on the pip bullet, before the choice.
- The apm-is-not-a-runtime Gotcha lost its operative clause. The two
  step headings cited as carrying it already existed pre-retrofit, so
  nothing had replaced it and nothing stated when Step 2 is required.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:31:33 +00:00
Defame1297
4aab9d327c refactor(kyberforge): retrofit forge to the ADR-0020 contract 
Description 648 -> 387 chars, body 1093 -> 541 words. This was the last
body FAIL in the 39-skill corpus.

The body was not trimmed to fit. forge routes four artifact types that a
single invocation classifies between, so the contract requires a dispatch
table plus the gates common to every route, with each route self-contained
in references/. Adds references/author-routes.md (skill and agent),
references/apm-routes.md (plugin and marketplace entry) and
references/version-bump.md. Skill and agent share one file: they differ on
one axis only, which audit skill verifies the result.

Fixes three defects the first pass introduced or relocated:

- references/apm-routes.md claimed `apm audit` "already runs inside
  apm-workflow's own flow" and told the agent to confirm it ran clean.
  apm-workflow dispatches audit as its own row; the configure and
  marketplace rows never reach it. That was the only completion check
  these routes had, and it could never be satisfied. Replaced with a
  manual read-back the agent performs itself.
- "Read only the reference file" forbade the multi-artifact case the same
  body documents two lines later, and ADR-0011 records eight artifacts
  authored in one pass.
- The announce gate became a closing gate, reachable only after the
  invocation it was meant to precede. Moved to the end of Step 2.

Also restores the artifact enumeration to the plugin row, normalises to
bare unnamespaced skill names per AGENTS.md, adds a dispatch fallback for
artifacts matching no row, and corrects three provenance entries -- one
asserted a contribution that did not happen.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:31:23 +00:00
Defame1297
1e4aab53a7 refactor(kyberforge): retrofit apm-workflow to the ADR-0020 contract 
Description 817 -> 324 chars, body 421 -> 237 words, Gotchas 6 -> 2.

The five capability clauses, the second trigger register and the prose
boundary form go; one trigger clause, the indirect trigger and one
boundary clause remain. Four of six Gotchas move into the flow file that
every branch needing them already loads.

Two stay in the always-loaded body because a dispatch body must carry the
gates common to every branch, not just the dispatch table: the MCP secret
indirection rule, and the `apm experimental enable registries`
precondition. The first pass moved registries into references/configure.md
alone, which stranded it -- references/compile.md documents publishing to a
registry and references/install.md resolves dependencies through one, and
neither points at configure.md. Declaring a registry without the
precondition is a silent no-op, so the failure had no signal.

Also drops an unsourced claim the compression pass introduced (that apm
checks `type:` going forward -- no source supports it), corrects the MCP
rationale to install *or* runtime per configuration.md:98, and repoints
two apm-orchestrate back-references that pointed at body Gotchas which had
moved.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
 2026-08-30 16:31:11 +00:00
Defame1297
915eb09ae2 docs(scripts): record that the bare-arrow carve-out is now unexercised 
The comment justified the ADR-0020 compressed-form gate with diagnose's
process chain 'fix -> regression-test', which without the gate read as a
route to a non-existent regression-test skill. Issue #99 cut that chain
when it retrofitted the description, so the gate now produces an
identical verdict corpus-wide whether it is applied or not.

Keeping the branch. It guards against prose no one has written yet, any
new process chain re-arms it, and the bare-arrow rule it sits on is the
sole extractor for three real targets in kyberforge's audit skills, all
written unbackticked. Unexercised is not the same as unnecessary — the
comment just needed to stop citing evidence that no longer exists.

Refs #99
 2026-08-30 15:51:43 +00:00
Defame1297
d8dfba958c docs(agents): correct the ADR-0020 gate counts after wave 3 
Three skills still exceed a FAIL tier, all in kyberforge, down from ten
descriptions and two bodies. No routing target dangles any more, and the
test suite now pins that set as empty rather than tracking a backlog.

Refs #99
 2026-08-30 15:07:17 +00:00
Defame1297
7e80c09b13 fix(kyberforge): a dispatch table satisfies the reference-wiring rule 
body-discipline.md required every reference load to use the literal
'If X, read references/file.md' form and called anything else a generic
pointer. ADR-0020's own cited dispatch exemplar, apm-workflow, uses a
bare table plus one closing line, so an author could not satisfy both --
and the rule reliably produced duplication in exactly the bodies the
contract exists to keep short.

Resolves #109 with its option 1: a table row already pairs a condition
with a target, so where a body dispatches, the table is the wiring. The
literal form is what a body needs when it loads a reference without a
table.

Two corrections to the issue as filed. There is no Vale conflict --
PaddingPhrase.yml only matches 'see references/ for more info' and never
fired on the exemplar, so this is a one-file prose fix and no rule
changes. And gitea-workflow carried the predicted duplication: a
three-row table restated underneath as three conditionals. Removed, body
227 -> 148 words.

Closes #109
 2026-08-30 15:07:16 +00:00
Defame1297
ff187ef9fc refactor(lint): retrofit vale-run to the ADR-0020 context contract 
Description 654 -> 294 chars, Gotchas 36% -> 19%. Body 698 -> 642 words:
up from the first pass, because a clean-context audit found four defects
whose fixes are net-additive text.

The suppression-markup warning covered only one of the two paths that
write it -- the list is case-based, so a recurring false positive goes
straight to step 3 and never read step 2's warning. Hoisted above both.

The CI-failure trigger, which the description advertises, had no path to
the file holding its answer: the negative diagnosis 'if the alerts are
warnings, Vale is not what failed the build' survived only in
troubleshooting.md, which no CI-entered invocation loads. An agent would
confidently prescribe --no-exit for a failure Vale never caused.

The description had lost every prose-domain word -- no 'prose', no
'linter' -- while vale-config kept all of them, so 'check prose style'
routed to the wrong skill of the pair.

Accepts two soft SUGGESTIONs rather than dropping restored content;
neither fails the gate.

Refs #99
 2026-08-30 15:07:16 +00:00
Defame1297
45cd26045a refactor(lint): retrofit vale-config to the ADR-0020 context contract 
Description 657 -> 244 chars, body 504 -> 342 words, Gotchas 50% -> 24%.
The 50% was the worst ratio in the corpus and a real inverted body, not
the denominator artefact the ratio usually flags: half the body was a
Gotchas section doing duty as reference material.

A clean-context audit caught the split leaving a false statement behind.
Gotcha 1's kernel lost the qualifier that only package styles need
fetching, so it asserted that any style vale sync has not fetched fails
-- contradicting the same file twice, since the built-in Vale style and
any committed custom style are never fetched. An agent adding a custom
style would have added a spurious Packages entry and broken vale sync
outright. The qualifier is restored in the body rather than behind a
fourth reference pointer.

Also corrects the moved fixture's framing, which tabulated a control row
under a heading claiming it came from a multi-line fixture.

Refs #99
 2026-08-30 15:07:15 +00:00
Defame1297
c59e4bf0c5 refactor(core): retrofit provider-adapter-author to the ADR-0020 contract 
Description 833 -> 239 chars, body 370 -> 387 words, Gotchas 41% -> 20%.
The file-type enumeration moves to a new references/provider-matrix.md;
the composition note was already in README.md.

Three defects a clean-context audit found, all fixed:

The 'never edits AGENTS.md' prohibition had become a justification clause
on the false branch of a conditional, so the common path never read a
sentence binding it. That matters because the bundled validator's own
remediation text tells the agent to move content into AGENTS.md, so a
size FAIL actively invited the prohibited edit. Restored as a standing
imperative, plus a counter at the step where the trap fires.

A Gotcha asserted that validate-adapter.sh fails without
--no-import-syntax. The flag is a no-op -- both branches reduce to the
same expression. Reverted to an instruction; the script defect is #115.

The boundary clauses used pronouns to dodge the #110 regex, and 'Not
auditing it' resolved to CLAUDE.md as readily as to AGENTS.md -- routing
'audit my CLAUDE.md' to a skill whose own description declines it.

Refs #99
 2026-08-30 15:06:50 +00:00
Defame1297
f0526b310d refactor(core): retrofit agentsmd-audit to the ADR-0020 context contract 
Description 944 -> 322 chars, Gotchas 36% -> 22%. The composition note
moves to README.md.

Restores the hand-edit trigger, which a clean-context audit found had no
other caller: agentsmd-author owns the post-authoring invocation, but a
hand-edit has no author skill in the loop, so nothing invoked the audit
at all. It survived only in README.md, which neither the router nor the
invoked agent loads. That is the path on which a human pastes a
credential into AGENTS.md.

The first pass dropped it against a measured budget of '~9 spare chars'.
The real cost was ~49, and 250 is the SUGGESTION tier, not a ceiling --
the gate fails at 400. Ships at 322 with one advisory line.

Names the three audit dimensions in the capability clause, recovering
routing for 'does my AGENTS.md leak credentials', and qualifies the
'is this AGENTS.md safe to commit' phrasing, whose pronoun had no
antecedent inside the quoted string.

Refs #99
 2026-08-30 15:06:49 +00:00
Defame1297
e42c055294 refactor(core): retrofit agentsmd-author to the ADR-0020 context contract 
Description 960 -> 244 chars, body 470 -> 452 words, Gotchas 36% -> 22%.
Both composition notes move to README.md, which already carried them.

Four of five Gotchas were paraphrases of the step below them and were
deleted with their force folded back into that step. A clean-context
audit overturned the fifth deletion: the provider-file prohibition was
strictly broader than Step 4, so it was never a paraphrase, and Step 4's
'don't rewrite it yourself' is attached to the if-duplicates branch. With
Write and Edit granted, a provider file that was merely stale had nothing
forbidding an edit. Restored as an unconditional Gotcha, read before any
step writes.

Also restores a concrete indirect trigger. The retrofit had replaced two
with the meta-statement 'even when they don't name the file', which
claims an indirect trigger exists rather than being one -- and users
asking to document a repo for AI tools have no reason to know the
filename.

Refs #99
 2026-08-30 15:06:48 +00:00
Defame1297
00c1e6b305 refactor(bin): retrofit diagnose to the ADR-0020 context contract 
Body 1126 -> 808 words, clearing the FAIL tier, and description 290 ->
220 chars. Phase 1's depth moves to references/feedback-loops.md; the
six-phase spine stays in the body, since a linear procedure is not a
dispatch case.

The description rewrite was not originally in scope, which was an error:
adding a mandatory boundary clause to a 290-char description cannot land
under 400. The dropped capability chain was also inaccurate -- it named
'minimise' as a phase that does not exist while omitting the one phase
the body calls 'This is the skill'.

A clean-context audit found no text lost but three reachability defects,
all fixed: content stranded behind an inverted trigger, Phase 2's
reproduction-rate threshold defined only in a file that path never
loaded, and a script path that did not resolve from the file carrying it.
The two reference files are merged into one, since the split is what
created the first two.

Refs #99
 2026-08-30 15:06:26 +00:00
Defame1297
f03bfa8d24 refactor(bin): retrofit prototype to the ADR-0020 context contract 
Description 426 -> 286 chars, with a boundary clause added. The body was
already compliant at 467 words and is untouched.

A clean-context audit caught the first pass trading away the LOGIC
branch's routing vocabulary for characters it did not need to save: both
'data model' and 'business logic' had gone, though LOGIC.md defines its
own scope with exactly those words. Restored, so 'does this data model
feel right?' routes here again.

Accepts 286 over the 250 target -- the hard tier is 400, and the
alternative was leaving half the dispatch reachable by one phrase.

Leaves LOGIC.md and UI.md at the skill root; moving them into references/
is tracked as #114.

Refs #99
 2026-08-30 15:06:25 +00:00
Defame1297
ee6b04061a refactor(bin): retrofit research to the ADR-0020 context contract 
Description 583 -> 231 chars and body 854 -> 519 words. Deletes the
neuledge-context boundary clause outright: commit 6146120 deleted that
skill and no skill has owned MCP-server installation since. That was the
last dangling routing target in the corpus.

Removes META.md, which file-structure.md:20 forbids at a skill root. Its
when: field duplicated the description and its references: entry pointed
at .agents/skills/context7-mcp/SKILL.md, which does not exist.

Restores two rules a clean-context audit found had lost their force: the
starting-URLs branch in step 3, which the retrofit had reduced to a
condition with no behaviour, and the references/file-format.md pointer at
step 6. The second matters downstream -- validate-provenance.sh parses
sources.md with anchored regexes and check 8 short-circuits silently when
the Status field is absent, so a sources.md written from step 6 alone
broke the provenance chain with no error anywhere.

Rewrites steps 4-5 as serial WebFetch reads. They mandated spawning
subagents that allowed-tools never granted; no tool was added because the
name differs across the three compile targets. Tracked as #116.

Updates the two test pins and the eval case that asserted the dead route.

Refs #99
 2026-08-30 15:06:23 +00:00
Defame1297
a2ebdafc5e fix(skill-audit): pin the stale worked example and state its reachability precondition 
The body-discipline rubric cited git-commits as it stood before the ADR-0020
retrofit -- twelve Gotchas, 387/1102 words, line numbers :31-:52. Every
figure was correct for that version and none survives in the current file,
so the example is now anchored to commit 5e23250 and marked not to be
refreshed against HEAD.

More than staleness: row four called the secrets Gotcha a paraphrase FAIL
because step 2 restated it. Wave 2 followed that reasoning, deleted the
always-loaded copy, and left the amend branch able to commit a credential
unchecked -- dispatch loads exactly one flow file. The paraphrase rule now
carries its missing precondition: delete a restating Gotcha only when the
surviving copy is reachable from every branch that needs it, and relocate
a multi-branch safety gate into the body rather than dropping it.
 2026-08-30 13:22:55 +00:00
Defame1297
afbeaff56b docs(agents): correct the ADR-0020 gate counts after the git retrofit 
Descriptions over the FAIL tier 19 -> 10, bodies 7 -> 2. This line is
always-loaded context, so a stale count misleads every session.
 2026-08-30 13:14:00 +00:00
Defame1297
3cd3f33706 refactor(pc-author): retrofit to the ADR-0020 context contract 
Description 475 -> 213 chars, body 680 -> 212 words. Create and modify
become self-contained flow files behind a dispatch table, since the two are
mutually exclusive on whether the config already exists.

Passed its clean-context audit with no must-fix findings.
 2026-08-30 13:10:53 +00:00
Defame1297
15ff7417b9 refactor(pc-run): retrofit to the ADR-0020 context contract 
Description 477 -> 211 chars, body 736 -> 367 words. Install, autoupdate,
and clean become flow files behind the Route table.

The audit found no route for 'hooks aren't running': the only pointer to
failure-patterns.md sat inside the failure path, but when hooks never fire
the manual run succeeds, so the request fell to the ambiguity default and
was masked. Restores the disclosure that install -f is not reversible by
uninstall.
 2026-08-30 13:10:53 +00:00
Defame1297
7cb8e95379 refactor(git-history): retrofit to the ADR-0020 context contract 
Description 450 -> 266 chars, body 1044 -> 462 words. The bisect procedure
moves to references/bisect.md.

The boundary clause read 'not writing or rewriting commits', which
disclaimed the cherry-pick and revert this skill's own Step 3 executes; it
now excludes authoring and rebasing only. Adds 'backport' so cherry-pick is
reachable by natural language at all, accepting 266 chars against a 250
soft target and a 400 ceiling.
 2026-08-30 13:10:53 +00:00
Defame1297
261e5b5491 refactor(git-submodules): retrofit to the ADR-0020 context contract 
Description 480 -> 248 chars, body 1011 -> 347 words. The single
submodules.md splits into setup-and-update, urls-and-config, and removal.

Restores three regressions the first pass introduced: 'repointing' as the
trigger for the URL branch, which had none while the boundary clause
steered those queries to git-remotes; clone and absorbgitdirs in the output
enum, which dispatch still routed to; and status --cached, the flag that
makes the pre-commit pointer gate verifiable.
 2026-08-30 13:10:53 +00:00
Defame1297
3c74beb280 refactor(git-workflow): retrofit to the ADR-0020 context contract 
Description 566 -> 249 chars, body 644 -> 398 words, Gotchas 12 -> 2. The
eight organisational hard rules move to references/hard-rules.md.

Its load trigger enumerates operations rather than rule topics: the first
draft keyed on 'commit message form', which left the atomicity and
working-state rules unreachable when a caller supplied a conventional
message. Also promotes the destructive-op confirmation ahead of the
orchestrator invocation, which it previously followed.
 2026-08-30 13:10:53 +00:00
Defame1297
38eb0745b7 refactor(git-remotes): retrofit to the ADR-0020 context contract 
Description 582 -> 237 chars, body 1217 -> 290 words. The single remotes.md
splits into config, fetch, push, and pull flow files.

Restores the confirm: true token to the force-push gate -- it is the git
plugin's cross-skill contract, gated on by git-orchestrate and git-branches.
Moves push.md's worked example off main, which the skill's own Step 1
refuses, and restores the never-bare---force directive.
 2026-08-30 13:10:53 +00:00
Defame1297
3dd5387671 refactor(git-worktrees): retrofit to the ADR-0020 context contract 
Description 592 -> 248 chars, body 756 -> 515 words, Gotchas 8 -> 4.

The audit found the dispatch table had no row for a worktree on an
existing local branch, so that request fell to the adjacent -B row, which
resets the branch to HEAD and discards its commits. Non-destructive create
is now the first row and -B names its own destructiveness. Adds the missing
lock/unlock row and repair's run-from constraint.
 2026-08-30 13:10:53 +00:00
Defame1297
0fde892f20 refactor(git-branches): retrofit to the ADR-0020 context contract 
Description 612 -> 273 chars, body 1124 -> 457 words. Branch patterns,
operations, merging, comparison, and the orchestrator contract move to
references/.

Corrects rebase routing in four places: this skill sent rebase to
git-history, which carries no rebase content and disclaims it. Rebase is
git-commits'; cherry-pick and revert stay git-history's. Drops a Step 3
gate on a rebase flow this skill does not have.
 2026-08-30 13:10:53 +00:00
Defame1297
f3b4860e14 refactor(git-commits): retrofit to the ADR-0020 context contract 
Description 724 -> 214 chars, body 1102 -> 343 words, Gotchas 12 -> 3.
Create, rewrite, and cherry-pick flows move to self-contained references/
files behind a dispatch table.

The audit caught that moving the secret scan into the create flow left the
amend/squash path with no check in its loaded context; it is now a gate
common to every flow. Also re-homes the interactive-rebase reflog warning
git-history dropped, since this skill owns rebase.
 2026-08-30 13:10:53 +00:00
Defame1297
bbc73008a3 chore(gitea): regenerate the flat content mirror after the ADR-0020 retrofit 
Generated output, not authored content: scripts/sync-plugin-content.sh --all.
Claude Code has no .apm/ awareness, so this compiled mirror must track .apm/ or
the check-plugin-content-sync pre-push hook reports drift.

Deferred to a single commit at the end of the wave on purpose. sync_dir runs
rm -rf before every copy, so running it while seven agents were editing the
same plugin would have raced them; agents were told not to sync for that reason.

Refs #99
 2026-08-30 12:42:20 +00:00
Defame1297
bedbd1d872 refactor(gitea-workflow): retrofit to the ADR-0020 context contract 
Description 1012 -> 347 chars, body 582 -> 170 words, Gotchas 3 entries -> 1 at
22.9% of body. Clears the description FAIL and all four Vale CompositionNote
errors -- the last carriers in the corpus, so that rule now fires nowhere.

Cut the 'human-facing entry point and router' architecture note, the /gitea
migration history and the six-skill composition list; all were already in the
README or the routing table.

Split three mutually exclusive flows into a dispatch table keyed on invocation
shape, each branch self-contained in references/: status-checkin.md,
number-resolution.md, skill-index.md. Report stays in the body as the gate
common to every branch; each branch's own format moved to its file. The old
Step 1-4 numbering presented three alternatives as a sequence.

The description grew from an intermediate 283 chars on purpose: that draft had
dropped flow 3's trigger entirely, leaving the domain-routing index -- a third
of the skill -- reachable only through a tail clause whose grammatical subject
was the request rather than the skill. Both gates were green over that.

Boundary clauses are one arrow per target, so both resolve (#107: the resolver
extracts only the first target per clause and reports 1 of 1 on a clause naming
two). The local-git exclusion keeps its wording but drops the route to
git-workflow, which would not resolve in a gitea-only install.

Known residual: the dispatch conditions are stated twice, as a table and as
literal conditionals. That is #109 -- body-discipline.md mandates the literal
form while the ADR's cited exemplar, apm-workflow, uses a bare table plus one
summary line. Fixing it here would settle that contradiction in a skill rather
than in the spec, so it rides with #109.

Refs #99, #107, #109
 2026-08-30 12:42:04 +00:00
Defame1297
b8c36c36f6 docs(agents): correct the ADR-0020 gate counts to measured state 
The bullet is always-loaded context, and all three of its numbers had gone
stale as the issue #99 retrofit landed. Measured now: 19 of 39 descriptions and
7 of 39 bodies over their FAIL tier, down from 26 and 9; one dangling routing
target left (research -> neuledge-context), down from two.

Kyberforge.CompositionNote fired 10 errors across four gitea-* skills and now
fires nowhere -- those four were the only carriers and all four have been
retrofitted. The 'check both gates' advice stays: skill-size-check still does
not cover the Vale half, and any new description can reintroduce the rule.

Refs #99
 2026-08-30 12:35:48 +00:00
Defame1297
23b843a311 test: drop the gitea-labels pin now the retrofit removed that target 
tests/test-adr0020-targets.sh pinned the corpus dangling set as exactly
{gitea-labels, neuledge-context} and tests/test-skill-size-check.sh probed both
individually. The gitea-issues retrofit cut the composition sentence whose
'>'-folded scalar produced 'gitea-labels- milestones', so that target no longer
exists and both suites went red.

EXPECTED_DANGLING is now {neuledge-context} and the gitea-issues probe is
removed rather than skipped, per the rule the probe file states about itself: a
probe whose fixture has been retrofitted is a pin that needs updating, not an
assertion-free pass counted in the totals.

The exact-set assertion stays. An empty expected set is still valid and still
pins that no new dangling target appeared -- which is what it becomes once
research is retrofitted. Both loops carry a shellcheck SC2043 waiver for the
same reason: one entry is the expected steady state, not bad quoting.

Refs #99
 2026-08-30 12:34:24 +00:00
Defame1297
37382cb72a refactor(gitea-labels-milestones): retrofit to the ADR-0020 context contract 
Description 835 -> 214 chars, body 669 -> 426 words, Gotchas 8 entries/63% of
body -> 3/20.4%. Clears the description FAIL, all three Vale CompositionNote
errors and both Gotchas suggestions. 63% was the worst Gotchas ratio in the
corpus.

Cut the composition sentence to README -- it changes no routing decision and an
agent picks this skill because the user asked about labels, not because two
other skills call it. Cut the capability enumeration; 'list, create, edit,
delete' decompose 'reading or writing' and add no trigger.

Boundary clauses are now one arrow per target. The resolver extracts only the
first name per arrow clause, so the previous '-> gitea-issues / gitea-prs' left
gitea-prs neither dangling nor checked while validate.sh reported 1 of 1. Now
2 of 2.

Makes org-scoped label resolution executable. The org label pool was reachable
in principle -- four *_org_label* methods, and a claim to own name-to-ID
resolution -- but list_org_labels takes org, and Step 1 derived only owner and
repo, so both resolution procedures stalled at the fallback. Fixed once at the
identity step rather than per-procedure. get_user_orgs is outside allowed-tools,
so the failing call is the discriminator: a failure means the owner is a user
account with no org pool, which is an answer, not an error.

Corrects a Gotcha that was false for create_repo_label/create_org_label and
collided with the literal tool name label_write. Same false claim removed from
README.

Refs #99
 2026-08-30 12:29:18 +00:00
Defame1297
78015893d4 refactor(gitea-issues): retrofit to the ADR-0020 context contract 
Description 827 -> 182 chars, body 902 -> 584 words, Gotchas 7 entries/43% of
body -> 4/23.1%. Clears both size FAILs, the dangling-target FAIL and the Vale
CompositionNote error.

The dangling 'gitea-labels' target is gone with the composition sentence that
carried it -- a YAML fold artifact, not a typo: the '>'-folded scalar joined
'gitea-labels-' and 'milestones' across a line break, leaving the name terminal
and danglable. Both boundary names now sit whole on one source line each, and
both resolve.

Cut the second trigger register, the seven-verb capability enumeration, the
issue_write implementation detail and a gitea-branches boundary that defended
nothing. Two Gotchas deleted as spec restatement carried in references/, one as
a paraphrase of the step below it.

Closes a capability hole rather than papering over it: gitea-labels-milestones
routes label application here and has no issue_write, but no dispatch row
existed for add/replace/remove/clear_labels or get_labels. Both rows added.
The label ID/name Gotcha is now stated per method -- issue_write takes IDs,
list_issues and search_issues filter by name, issue_read 'get' returns names
but 'get_labels' returns full objects with IDs.

Drops a stale quotation of gitea-labels-milestones' description from
references/enrichments.md; that string went with its composition note.

Refs #99
 2026-08-30 12:28:54 +00:00
Defame1297
0079f3508c fix(gitea-prs): correct reference drift against gitea-mcp v1.7.0 
The reference files were last verified against v1.3.0 -- references/sources.md
still said so. PR #106 re-verified the write side only, so three defects had
accumulated on the read/review side. All three reproduced against the deployed
server before being fixed; get_gitea_mcp_server_version reports v1.7.0.

- reviews.md forbade review_comments on the "get" response and directed callers
  to review_scomments, which does not exist. The upstream slim.go typo was
  corrected; a live pull_request_read on PR #106 returns "review_comments":1 and
  no review_scomments key. review_comments is an integer count, not comment
  objects -- distinct from the get_review_comments method. Also fixed in
  pull-requests.md's response-shape list.
- pull_request_review_write grants seven methods; only four were documented.
  reply_comment, resolve_thread, unresolve_thread and the comment_id parameter
  had zero mentions anywhere in the skill. Documented from the schema, in a
  Comment threads section kept outside the numbered review state machine --
  they are not lifecycle states.
- review_id was documented as required for get_review_comments. It is optional;
  omitting it lists every inline comment on the PR. Confirmed behaviourally:
  get_review without it errors, get_review_comments without it returns [].

sources.md now records v1.7.0 as the last-verified version, so the next reader
knows what these files were checked against.

Refs #99
 2026-08-30 12:21:11 +00:00
Defame1297
d578d6b2f2 refactor(gitea-prs): retrofit to the ADR-0020 context contract 
Description 709 -> 161 chars, body 683 -> 353 words, Gotchas 8 entries/56% of
body -> 2/24.9%. Clears the description FAIL and both Vale CompositionNote
errors.

Fixes the three stale claims recorded on issue #99, all re-verified against the
deployed gitea-mcp schema during review:

- The description no longer advertises 'reviewers' as an update capability.
  editPullRequestFn never reads reviewers or team_reviewers; only
  add_reviewers/remove_reviewers do.
- milestone is now marked honoured on "update" only, in the Gotcha, the body
  and the dispatch table's create row. On "create" the server discards it and
  omits the key from the response, so the drop is indistinguishable from never
  passing it -- and labels DOES apply on create, so labels landing is no
  evidence the milestone did. The old text told callers to resolve a milestone
  before any write, wasting the lookup on create.
- The superseded un-draft workaround is gone. "update" with draft:false and no
  title makes the server strip the prefix itself, including [WIP],
  case-insensitively -- carried by references/pull-requests.md, corrected in
  PR #106.

The 22-row tool/method table becomes a 5-row dispatch table; all 20 operations
it named remain reachable, including update_branch and the reviewer methods.

Refs #99
 2026-08-30 12:10:21 +00:00
Defame1297
d5954d3d99 refactor(gitea-files): retrofit to the ADR-0020 context contract 
Description 787 -> 263 chars, body 922 -> 302 words, Gotchas 9 entries/69% of
body -> 3/24.8%. Clears both size FAILs and both Gotchas suggestions.

Deleted the second trigger register outright -- ~300 chars re-quoting the same
six verbs as user phrasings, which ADR-0020 names this skill for specifically.

Split the body on the read/write boundary: one invocation cannot both read and
write, so a dispatch table is mandatory. Six operations collapse into two flow
files rather than six -- create/update/delete share one tool pair and one
SHA-first lifecycle whose preamble would otherwise be triplicated, and the three
read tools share ref selection plus a 'neither listing is a SHA source'
comparison that only exists between them.

references/examples.md removed; all eight of its content blocks and all nine
named parameters carry into references/writing.md, verified against git HEAD.
Two deltas are corrections: the repo tree is now ruled out as a SHA source, and
reusing a SHA captured earlier in the conversation is now forbidden.

Four Gotchas relocated to the flow file that needs them; two promoted to gates
(SHA-as-concurrency-token opens writing.md; owner/repo became ## Inputs).

Refs #99
 2026-08-30 12:09:52 +00:00
Defame1297
ee812699a4 refactor(gitea-branches): retrofit to the ADR-0020 context contract 
Description 688 -> 282 chars, body 435 -> 293 words, Gotchas 5 entries/54% of
body -> 3/23.5%. Clears the description FAIL and the Gotchas suggestion.

Cut the second trigger register (six re-quoted user phrasings) and the capability
enumeration; both moved to a new Boundaries section in the skill's own README.
Kept all three boundary clauses -- git-branches, git-history and gitea-prs each
defend a real activation steal, and gitea-prs is now the only guard on the
branch/PR collision in either direction since gitea-prs's own retrofit narrowed
its boundary to issues. Written as one arrow per target: the resolver extracts
only the first name per arrow clause, so conjoined targets go unchecked.

Two Gotchas deleted -- one paraphrased the step below it (its non-obvious half,
the get_me/list_my_repos token-scope block, was folded into that step), the other
is carried in full by references/branches.md:40-52.

Repoint two reference pointers the rename broke: branches.md and commits.md named
Gotchas by titles this retrofit changed. Now named by stable descriptors.

Refs #99
 2026-08-30 12:08:38 +00:00
Defame1297
dfacf051a8 refactor(gitea-releases): retrofit to the ADR-0020 context contract 
Description 500 -> 211 chars, body 676 -> 462 words, Gotchas 5 entries/41% of
body -> 3/21%. Clears the description FAIL and both Gotchas suggestions.

Cut the second trigger register (the re-quoted user phrasings), the doubled
capability enumeration across releases and tags, and the gitea-issues/gitea-prs
boundary, which defended against nothing -- neither was going to win a release
request. Kept the indirect trigger and the one real near-miss, gitea-branches.

Releases and tags are one flow, not two: 'delete the release and its tag' is a
single invocation that takes both branches, which disqualifies mutual
exclusivity, so no dispatch split. Two Gotchas moved to references/ behind
explicit triggers; one deleted as a paraphrase of the step below it.

Refs #99
 2026-08-30 12:06:37 +00:00
Defame1297
ef3e981eac docs(context): record that hand-invocation blocks skill-to-skill routing 
The Hand-invoked skill entry covered listing visibility and preload tax but not
invocability. Measured: disable-model-invocation: true hard-blocks the Skill
tool, not just the model-visible listing, so a `Call `x`` step in another
skill's body stops working the moment x takes the flag.

ADR-0020's 'Invocation as a design axis' verified only the visibility and slash
directions. Without this half, marking grill-with-docs hand-invoked -- one of
issue #99's four named candidates -- would silently break forge Step 1, which
calls it, plus three other inbound routes.

Refs #99
 2026-08-30 11:54:26 +00:00
Defame1297
5f984ce34a chore(apm): refresh lock after SessionStart update 
The SessionStart hook found six packages behind the remote default branch and
ran apm update. Committing the resulting lock separately so it does not sit in
the ADR-0020 retrofit diff.
 2026-08-30 11:54:18 +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
Defame1297
68e08c2413 Merge pull request 'docs: cut the every-session context set by 74%, and fix what the cut broke' (#105) from docs/slim-agents-md into main 
Reviewed-on: https://git.dev.rkdr.net/Defame1297/holocron/pulls/105
Reviewed-by: Defame1297 <gitea@rkdr.net>
 2026-08-17 14:08:23 +00:00
Defame1297
d42f6368fe fix(docs): correct claims the first fix round asserted without measuring 
Why: two blind verifiers re-ran the five preceding commits and found four
defects of the same class this branch exists to close -- a confidently stated
measured claim that does not survive re-measurement -- this time inside the
fixes themselves.

- AGENTS.md:41 still carried both phrasings c68e864 reports having corrected.
  `grep -rn repo-defined` returned exactly one hit repo-wide: that line, in the
  file every session preloads. 4d336bb edited the line directly above it.
- ADR-0021 asserted twice, in the section justifying that no gate is added,
  that the ADR-0020 validators "never open an apm.yml". All three open and
  yaml.safe_load it (skill-size-check.sh:342, both validate.sh). The conclusion
  survives -- none reads the description: key, and their globs are SKILL.md and
  *.agent.md only -- but the stated mechanism is falsified by one grep.
- architecture.md said the ADR directory holds 20 numbered ADRs; c7ba3d2 made
  it 21, and c68e864 audited that file for exactly this class of stale count.
  The number is dropped rather than corrected: `ls docs/adr/` is already the
  index, so a count in prose is a second thing to maintain.
- gates.md's new three-verdict table said `-> name` promotes an unresolved
  target to ERROR. Reproduced with fixtures: NAME_HYPH (skill-size-check.sh:543)
  requires a hyphen, so `-> gitea-prs` is checked and `-> triage` is not
  extracted at all, and the unicode arrow is never recognised. The SUGGESTION
  text advises that spelling, so taking its advice can silence the finding. The
  gap is now documented as a defect; nothing covers it, since the one arrow case
  in test-adr0020-targets.sh happens to use a hyphenated target.

Implementation notes:
- AGENTS.md:48's coverage claim is shrunk rather than chased. Restoring six
  glossary entries did not make it true: 12 more sampled terms are undefined,
  three of them (trigger/capability/boundary clause) used inside CONTEXT.md
  itself. It now says CONTEXT.md is the glossary and is not exhaustive.
- CONTEXT.md's output profile and near-miss entries are corrected against their
  sources. The first stated a false exclusion -- .github/plugin/plugin.json IS
  apm-generated; only the marketplace mirror has no profile. The second
  inverted its source's referent: description-quality.md defines a near-miss as
  a query, not a sibling skill.
- The strict-mode message named jq, which no suite guards on (`command -v jq`
  appears nowhere in tests/), while omitting python3/PyYAML, which three do.
- README's git and gitea bullets now name git-workflow and gitea-workflow.
  ADR-0021 leaves README the only inventory and architecture.md now points at
  it, so the two bullets that were short had to be completed.
- ADR-0018's 2026-08-14 correction is marked superseded in place. It asserted
  machine state in the present tense that its own 2026-08-17 note retracts.
- ADR-0021's remaining errors: six files -> four (measured from de84d1b), the
  wiki description's length 114 -> 96 chars, the codex self-contradiction, the
  cost argument overstating bumps already owed for any skill addition, and two
  claims about files this branch went on to edit.
- The "15 of 17 suites" figure is restored where I had removed it: it is a dated
  record of one incident, not a live count, and four sites now describe it the
  same way.

Impact: 16/16 pre-push hooks pass, suite 24 passed 0 skipped 0 failed. No
behaviour change; every edit is prose or a comment.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 13:18:55 +00:00
Defame1297
c68e864159 docs(spec): correct eight claims the trim carried into the new files 
Why: the relocation into gates.md and architecture.md moved text faster than it
verified it, and a review found eight assertions that do not survive contact
with the repo.

- gates.md cited docs/research/examples/, which does not exist; the tree is at
  plugins/kyberforge/docs/research/examples/. The same wrong string survives at
  ADR-0013:98, where it originated, and is tracked separately.
- gates.md's description-budget arithmetic was built on 23,427, a figure
  ADR-0020 measured at f9b919d and pins there, and compared a name-inclusive
  total against a description-only ceiling. Dropped rather than re-measured,
  following the precedent this branch set for CONTEXT.md's token figure: a
  second live copy is a second thing to go stale.
- gates.md listed "every boundary-clause routing target must resolve" as a hard
  FAIL. skill-size-check.sh emits unresolved targets as SUGGESTION by default,
  promotes to ERROR only when terminal and either route-notated or corroborated
  by a resolving target in the same sentence, and reports INFO DID NOT RUN when
  no universe resolves. Verified with five fixtures; replaced with a
  three-verdict table.
- gates.md and README called `pre-commit run --hook-stage pre-push --all-files`
  the whole push gate. check-release-needed.sh exits 0 unless
  PRE_COMMIT_REMOTE_BRANCH is refs/heads/main, which only the real git hook
  exports -- its own header comment titles this a "Known gap".
- "repo-defined" was loose: the two meta hooks are also declared here, and what
  separates them is repo: meta from repo: local.
- architecture.md claimed `when:` appears in two of 39 skill sources. Exactly
  one SKILL.md carries it; the second hit is a META.md. The likely origin is
  skill-implementation-workflow.md:233, which claims META.md sits alongside
  every skill when one exists in the whole tree.
- architecture.md said core/AGENTS.md is "deployed beside" CLAUDE.md.
  deploy-manifest.sh sends them to ~/.claude/ and ~/.agents/ respectively; the
  relation is import, not adjacency.
- gates.md's see-also cited ADRs as bare stems where its neighbours use paths.

Implementation notes: architecture.md's closing pointer sent readers to the
published description "for what a consumer actually gets", which was true
against an enumeration and is not after ADR-0021. It now names the boundary
relationship and points at the skills tree and README for an inventory. README's
bin bullet gains caveman and zoom-out, since ADR-0021 leaves it the only place
an inventory lives.

Impact: 16/16 pre-push hooks pass. Deliberately not fixed here and tracked
separately: the 12 pre-commit-stage hooks gates.md does not document, its own
SentenceOpenerThereIs violation, and README's missing scripts/install.sh step.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:29:16 +00:00
Defame1297
c7ba3d2ccf chore(apm): retire skill enumeration from published descriptions 
Why: enumerating a plugin's skills in its published description has now failed
three times in four days, the third time inside the correction for the second.

bb9158d (Aug 14) fixed core's description, which described bin's skills. That
failure was wrong content, not an incomplete list -- a syntactically perfect
four-item enumeration that belonged to a different plugin -- so enumerating
harder could not have caught it, and bb9158d's own fix replaced the enumeration
with a domain boundary. 65bac15 and de84d1b then cited that precedent while
doing the opposite, and the re-enumeration is itself incomplete: caveman and
zoom-out are unnamed in bin, git-workflow is unnamed in git despite 65bac15's
message claiming it was added, and gitea-workflow is unnamed in gitea. 23 of 27
skills named at the third attempt.

Nothing checks any of this. check-manifests.sh does not contain the string
"description"; apm audit --ci, apm pack --check-clean and
sync-plugin-content.sh --check all compare compiled output against apm.yml, so
their job is to propagate whatever it says byte-for-byte. The wiki claim passed
all fourteen pre-push hooks every day it was published. Enumeration also makes a
marketplace release the consequence of a directory appearing.

Implementation notes:
- ADR-0021 records the decision, the three failures, and why no gate is added:
  the check is one-directional, cannot see an invented capability, and a
  correspondence map would relocate the same per-skill maintenance one file over.
- bin 1.1.4 -> 1.1.5, git 1.3.4 -> 1.3.5, gitea 1.3.5 -> 1.3.6,
  marketplace.version 0.4.4 -> 0.4.5, all PATCH under per_package.
- apm.yml's top-level version: is restored to lockstep at 0.4.5. It has moved
  with marketplace.version in all eleven commits that ever touched the file
  until this branch left it at 0.4.2, and apm.yml's own comment records it as
  live and consumed by apm audit.
- git's boundary names the pre-commit hooks explicitly: pc-author and pc-run are
  not git operations, and a boundary drawn narrower than the contents is the
  same defect one level up.
- Regenerated with apm pack for the marketplace manifests and
  sync-plugin-content.sh --all for the per-plugin ones; both mirrors verified
  byte-identical.

Impact: consumer-facing. 16/16 pre-push hooks pass, suite green, generated diff
is 26 insertions and 26 deletions across 8 files with no incidental churn.

Refs: #105
ADR: 0021

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:28:55 +00:00
Defame1297
4d336bbf35 docs: stop the preloaded instruction set asserting machine state 
Why: four defects in the files every session pays for, all introduced or left
behind by the trim.

AGENTS.md told agents the `<plugin>:` form still resolves "because user-scope
native installs were left enabled on purpose", and that a working namespaced
call "is not something to fix". That premise is false on this machine:
installed_plugins.json is empty, no enabledPlugins key exists in ~/.claude.json,
and ~/.apm/marketplaces.json is empty. ADR-0018 already reversed itself once on
this exact claim (Correction 2026-08-14) using that same enablement as its
evidence, so flipping the assertion again would be the third revision in three.
Both files now assert nothing about install state at all, which removes the
flip-flop surface instead of re-aiming it.

The other three are guard-rails whose instruction survived the trim while the
caveat that made it safe did not:
- The run-tests.sh line omitted --strict, so it named the one invocation that
  reports SKIPPED rather than failed when a dependency is missing. gates.md
  records this gate going green having verified 15 of 17 suites on a vale-less
  PATH. .pre-commit-config.yaml:70 already uses --strict for that reason.
- The .claude/settings.json prohibition lost its ADR-0019 exception, so an agent
  applying it literally would strip apm's own merged SessionStart entry and
  create the drift the rule exists to prevent.
- LESSONS.md still routed graduated rules to CONTEXT.md's Principles section,
  which this branch deleted.

Implementation notes: the six terms the trim dropped while AGENTS.md still
claimed CONTEXT.md glosses everything -- authoring root, content mirror, apm
package, output profile, near-miss, vacuous green -- are restored as one-line
entries per CONTEXT-FORMAT.md, sourced from architecture.md, gates.md and
skill-audit's description-quality.md rather than reworded. ADR-0018 gets a third
dated note recording the observation and the fact that the state has now been
described two ways, and its stale user-scope inventory is replaced by a pointer
to it; the decision it records is untouched. LESSONS.md:3 carried the identical
stale claim as :5 and is fixed with it.

Impact: preloaded context is now free of assertions about machine state.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:28:30 +00:00
Defame1297
36596598ef fix(tests): point the strict-mode dependency citation at README.md 
Why: this branch moved the prerequisites list out of AGENTS.md into README.md
but left three references behind. The worst is run-tests.sh's --strict failure
message, which a developer is handed at the exact moment a push gate fails and
they need the dependency list: it named AGENTS.md, which no longer documents
vale, apm or jq anywhere. 56cc173 re-anchored this same class of citation in
.pre-commit-config.yaml, scripts/check-vale-style-sync.sh,
scripts/sync-marketplace-mirror.sh and tests/test-check-vale-style-sync.sh --
tests/run-tests.sh was missed, and it is the only one a human actually reads.

Implementation notes:
- run-tests.sh:262 (user-visible), run-tests.sh:16 (header rationale) and
  test-run-tests.sh:395 all now cite README.md's Prerequisites table, verified
  to name vale, apm, jq, python3/PyYAML and the claude CLI.
- Every assertion on this message greps for "a skip is a SETUP ERROR", which
  sits before the changed clause, so no test needed updating.
- test-vale-wrap.sh's bash 3.2 citation is corrected in the same pass: it
  credited LESSONS.md and the script headers, but LESSONS.md's only mention of
  3.2 is an aside inside an unrelated lesson, not a target declaration. It now
  cites scripts/lib/batch-run.sh and providers/claude-code/statusline-command.sh,
  which do declare it. The citation 56cc173 replaced was already false, so this
  finishes a half-fix rather than correcting a regression.

Impact: forced the strict-failure path with vale removed from PATH and confirmed
the corrected message printing -- 21 passed, 3 skipped, exit 1. Full suite with
vale present: 24 passed, 0 skipped, 0 failed.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:28:11 +00:00
Defame1297
b1ea14df3e fix(scripts): make the mirror DRIFT fix line safe to copy-paste 
Why: bd2bf66 restored the `apm pack` guard-rail by appending it to the `Fix:`
command after `--`, which made the printed line stop being runnable. Pasting it
ran the script with ~24 stray argv entries: `${1:-}` became `--`, so CHECK
stayed 0, no shift occurred, and `[[ $# -eq 0 ]] || usage` printed usage and
exited 1. The user got a usage error from the tool meant to fix their problem,
and the mirror stayed stale.

The unquoted backticks around `apm pack` were a second hazard in the same line:
the paste command-substituted a real `apm pack` run before this script was ever
reached, so the first error a user saw came from apm, not from here.

Implementation notes:
- The runnable command now stands alone on its own line, and the rationale
  follows as a separate `Note:` echo.
- Backticks downgraded to single quotes; a line printed next to a
  copy-pasteable command must not contain shell metacharacters.
- The guard-rail text is otherwise preserved verbatim. It exists because apm
  ships no output profile targeting this path, so `apm pack` does not refresh
  it, and expecting it to is the drift this hook prevents.

Impact: reproduced the break on a scratch copy, then verified the fix by pasting
the printed command verbatim — exit 0, mirror synced, re-check clean.
tests/test-sync-marketplace-mirror.sh asserts only exit codes and file contents,
so nothing pins this message and it could regress silently; tracked separately.

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
 2026-08-17 12:27:56 +00:00
Defame1297
de84d1b677 chore(apm): give bin a published description that describes it 
Why: bin's marketplace description read "A place for things to be binned" — a
routing boundary sitting in the enumeration slot, phrased as a joke. It is what
a consumer sees in the marketplace listing for a plugin shipping eleven
substantive skills: research, write-docs, tdd, prototype, triage, diagnose,
improve-codebase-architecture, grill-me, grill-with-docs, zoom-out and caveman.

This is the same category error b0ef503 fixed for git and gitea, and the same
text bb9158d moved out of core's description in August — "triage, diagnosis,
architecture review" left core precisely because those skills live in bin, so
bin is where it should have landed.

Implementation notes: bin 1.1.3 -> 1.1.4, marketplace 0.4.3 -> 0.4.4, PATCH for
metadata under the per_package strategy. README's bin line mirrors the new
description. architecture.md's routing boundary is deliberately left as
"unsorted skills that have not earned a home yet" — that is still true, and it
answers a different question than the listing does.

Impact: consumer-facing. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace, validate-plugins and
apm-audit-ci all pass.
 2026-08-17 10:33:25 +00:00
Defame1297
65bac15257 chore(apm): correct git and gitea published descriptions and regenerate 
Why: both plugins' published descriptions named capabilities that do not exist
and omitted ones that do. `gitea` advertised wikis — no wiki skill exists and
`grep -ri wiki plugins/gitea/.apm/` is empty — while omitting gitea-branches and
gitea-files. `git` advertised pull requests, which are gitea's, while omitting
pc-author/pc-run, git-submodules and git-workflow. These are compiled into
plugin.json and both marketplace.json files, so they are published metadata, not
internal notes.

This is the same defect bb9158d fixed on `core` in August, so the fix follows
that precedent exactly: correct the package apm.yml and the root marketplace
entry together — fixing only the package manifest leaves it half-propagated,
since the root entry is what reaches the compiled marketplace.

Implementation notes:
- git 1.3.3 -> 1.3.4, gitea 1.3.4 -> 1.3.5, marketplace 0.4.2 -> 0.4.3, all
  PATCH for metadata under the per_package strategy at apm.yml:76.
- Regenerated with `apm pack` for the two marketplace manifests and
  `scripts/sync-plugin-content.sh --all` for the four per-plugin plugin.json
  files; `apm pack` alone does not touch those. `scripts/sync-marketplace-mirror.sh`
  refreshed the Copilot legacy mirror, which no apm profile targets.
- README's gitea line mirrors the new published description. The routing
  boundaries in architecture.md deliberately do not, since they answer a
  different question.

Impact: consumer-facing. Anyone reading the marketplace now sees what these
plugins ship. apm-pack-check-clean, check-plugin-content-sync,
check-marketplace-mirror-sync, validate-marketplace and apm-audit-ci all pass.
 2026-08-17 10:13:31 +00:00
Defame1297
b0ef503485 docs: correct plugin scope, hook ordering and the setup gap 
Why: the review found architecture.md's plugin table and README's plugin list
were both written by enumerating what happened to be in each plugin, so both
went stale immediately — README credited `git` with pull requests it has no
skill for, and both omitted `pc-author`/`pc-run`. bb9158d fixed this same class
on `core` in August and it recurred here, so the fix is to stop enumerating in
the place whose job is routing.

Implementation notes:
- architecture.md's table now states routing boundaries only, with a note saying
  so and pointing at each plugin's published apm.yml description for the actual
  inventory. Two boundaries are named explicitly: `core` vs `kyberforge` (kept),
  and `git` vs `gitea` — wire protocol against a local clone versus the forge's
  HTTP API, which is why git-branches and gitea-branches are not duplicates.
- The `git` row is widened to cover git hook tooling rather than moving
  pc-author/pc-run elsewhere. pre-commit manages .git/hooks/, so the placement
  was always right and the row was simply under-described.
- README's setup block had a comment where step 2's command should be. It now
  carries `pre-commit install -t pre-commit -t commit-msg -t pre-push`, verified
  against the three stages in .pre-commit-config.yaml and the three hooks in
  .git/hooks/. pc-run is still named, as the option rather than the only path.
- README:11 said each plugin carries agents, hooks and MCP servers. Only
  kyberforge ships hooks and only bin ships an MCP server.
- gates.md:30 claimed its hook list was in config order; it is grouped by
  concern, which is the better layout, so the claim is corrected to match.

Impact: docs-only. gitea's published description is corrected separately, since
that regenerates consumer-facing manifests.
 2026-08-17 10:11:59 +00:00
Defame1297
bd2bf667c5 docs: restore two guard-rails the trim dropped 
Why: 1929ffd and b9c7762 preserved every constant, hook ID and error string,
but two don't-re-litigate notes were lost. Both were guard-rails — they fired
from preloaded context, before the mistake. Restoring the sentence to an
on-demand spec doc restores the text without restoring the function, since an
on-demand file is opened after a plan is formed, not before.

Implementation notes: placed by when each note must fire, not by what it is
about.
- "Do not expect `apm pack` to refresh the .github/plugin/marketplace.json
  mirror" now lives in the DRIFT failure message of the script and hook that
  already catch that exact mistake. It costs no preloaded tokens, fires at the
  moment of the error, and cannot be missed. No test asserts on that message;
  --check and shellcheck both pass.
- Plugin self-containment has no gate that fires on it, so it goes in
  architecture.md's Plugin model beside "self-contained plugin units", stated as
  the constraint it is rather than a description, with the two consequences that
  make it load-bearing: the duplicated Vale styles (ADR-0014) and ADR-0020's
  constants copied into three validators.

Impact: the every-session set is unchanged — neither note returns to AGENTS.md.
 2026-08-17 10:10:55 +00:00
Defame1297
ba7cec7672 docs(adr): amend ADR-0007 and ADR-0015 for the CONTEXT.md trim 
Why: b9c7762 gave dated amendments to ADR-0013, ADR-0015 and ADR-0017, but two
pointers were missed. ADR-0007 cited the "Provider-agnostic issue tracker"
glossary entry, which the trim renamed to "Issue". ADR-0015 cited the "lint
plugin" entry, which the trim deleted outright — and ADR-0015 was amended for
its other CONTEXT.md pointer in the same commit, so this one was missed inside
an already-edited file.

Implementation notes: ADR-0007 gets a dated parenthetical matching the pattern
the other three carry, confirming the entry survived under a new name rather
than being dropped. ADR-0015's Considered-options parenthetical is re-pointed
at docs/spec/architecture.md's plugin scope table, which now carries the
repo-agnostic-versus-marketplace-specific argument the deleted entry held, and
its existing 2026-08-17 supersession note is extended to record that second
redirect in one place.

Impact: all four ADRs that referenced moved CONTEXT.md content now say where the
content went. No decision is altered.
 2026-08-17 10:10:24 +00:00
Defame1297
56cc173f65 fix: re-anchor doc citations that the CONTEXT.md trim broke 
Why: eight comments and one status note cited CONTEXT.md or AGENTS.md text that
b9c7762 and 1929ffd moved or deleted. All are inert at runtime, but they are the
rationale comments that tell the next maintainer why an assertion exists, and
they now name a file that no longer explains it.

Implementation notes: re-anchored by what the citation is for, not uniformly.
- Four sites quoted facts ADR-0013 owns — every rule is `level: error` with no
  ignorable tier (ADR-0013:59-70), and KyberforgeCopilot's `.agent.md`-only
  scope (ADR-0013:43-46). These now cite ADR-0013. ADRs are append-only here;
  the spec docs are refactored, which is what caused this rot.
- Two sites quoted the glob location-independence property, which no ADR owns.
  The quote was already inline and carried the full rationale, so the citation
  added a rot surface and no information — dropped, statement kept.
- sync-marketplace-mirror.sh's header attributed the mirror-not-a-profile fact
  to CONTEXT.md; the parenthetical beside it already carries the evidence, so
  the attribution is dropped rather than re-pointed.
- .pre-commit-config.yaml cited an AGENTS.md instruction that no longer exists;
  generalised to "the documented instruction".
- LESSONS.md:29 misquoted AGENTS.md's current session-start line.

Also corrects a pre-existing misattribution at tests/test-vale-wrap.sh:454:
AGENTS.md has never named bash 3.2 as a repo target (`git log -S'3.2'` on it is
empty). LESSONS.md and the script headers do.

Impact: no behaviour change. test-check-vale-style-sync.sh and test-vale-wrap.sh
both pass (42 passed, 0 failed).
 2026-08-17 10:09:51 +00:00
Defame1297
b93af30750 docs: fix a wrong pointer and two stale claims in CONTEXT.md 
Why: CONTEXT.md is an instructed every-session read, so a wrong assertion in it
is cited downstream without being checked. The b9c7762 rewrite introduced one
broken pointer and carried over two claims that were already false.

Implementation notes:
- The Preload tax entry pointed at docs/spec/gates.md for the measurement
  method. gates.md has no such method — it uses the 23,427-char figure once, in
  passing, without deriving it. The method and the current figure both live in
  ADR-0020, which is where a dated measurement belongs: it is superseded there
  deliberately, and issue #99 tracks its drift.
- Dropped the "~5,900 tokens across 39 skills" measurement rather than
  re-measuring it. It was already wrong three days after being written (~5,340
  today) and it was the only live number in the file. Every sibling entry is one
  definitional sentence plus a pointer fragment; this one now matches, and
  CONTEXT-FORMAT.md:43 asks for exactly that.
- Dropped "Written by the session-handoff skill or directly by the human" from
  the LESSONS.md entry. No session-handoff skill exists — LESSONS.md:7 records
  it as planned work. Who writes a file is not its definition.

Impact: removes the only rot surface in the file and the only assertion in it
that names an artifact the repo does not have.

Refs: #99
 2026-08-17 10:06:26 +00:00
Defame1297
b9c7762463 docs: trim CONTEXT.md to a glossary and demote VISION.md 
Why: CONTEXT.md is an instructed every-session read at 33,799 bytes (~8,450
tokens), and CONTEXT.md:17 layered docs/VISION.md on top. After the AGENTS.md
trim, that left ~9,650 tokens of instructed reads sitting behind a file whose
own format contract — grill-with-docs/CONTEXT-FORMAT.md:43, "Keep definitions
tight. One sentence max." — it was not following. 22 glossary entries averaged
190 words; the top four were 55% of the file, and one ("Vale audit prefilter")
was 1,444 words of pre-commit forensics filed as a definition.

Implementation notes:
- CONTEXT.md rewritten to CONTEXT-FORMAT.md's prescribed template: ## Language
  (five clusters, 22 terms with _Avoid_ aliases), ## Relationships,
  ## Example dialogue, ## Flagged ambiguities. 33,799 -> 9,762 bytes.
- Vale prefilter forensics moved to docs/spec/gates.md under nine subsections:
  the two-copy style layout, vale-wrap.sh and the Vale 3.15.2
  text.frontmatter.description limitation, the --config argv defect (E100),
  glob scoping, the rule inventory, and 0-files-means-NOT-RUN.
- Instruction-file format and the bidirectional-reference principle moved to
  docs/spec/architecture.md, the latter flagged as aspirational: no instruction
  file carries a `when:` field, only 2 of 39 skills do, and the reference
  scanner script it names does not exist.
- Added a per-plugin scope table to architecture.md so "which plugin owns this
  skill" survives the trim, and corrected its claim that the content index
  lives in providers/claude-code/CLAUDE.md — that file is now two import lines
  and the index sits in core/AGENTS.md.
- "Repo and Gitea are the only source of truth" moved from CONTEXT.md's
  Principles into AGENTS.md session rules; it was operative guidance in a
  glossary. docs/VISION.md and LESSONS.md added to the on-demand list.
- The apm-consumed install entry (432 words) was deleted outright: all four
  consequences are already carried by README.md, ADR-0018, gates.md and
  AGENTS.md.
- ADR-0013, ADR-0015 and ADR-0017 each pointed at CONTEXT.md sections that
  moved; amended with dated supersession notes rather than left dangling.

Impact: the every-session set drops from ~15,700 to ~4,140 tokens across both
passes (-74%). The deleted "lint plugin" entry was also stale on a safety
claim — it said lint-runner inherits Edit, but ADR-0016 restored
`disallowedTools: Edit, Write, NotebookEdit` and CONTEXT.md was never updated.

Refs: #99
 2026-08-17 09:28:01 +00:00
Defame1297
1929ffd2da docs: slim AGENTS.md to per-session context only 
Why: AGENTS.md is preloaded into every session via CLAUDE.md's @AGENTS.md
import, so every word is a tax paid whether or not it is relevant. It had
grown to 3,371 words (~4,550 tokens), 75% of it a single "Setup and testing"
section that was mostly neither: roughly 1,600 words were gate forensics —
why a hook is shaped the way it is, what was tried and rejected, verification
numbers — and only ~390 words were genuine one-time setup.

Implementation notes: split three ways by audience rather than by heading.
One-time setup, prerequisites and test commands move to a new root README.md,
which did not previously exist. The gate forensics move to a new
docs/spec/gates.md, preserving every constant, hook ID, error string and
tried-and-rejected note (policy.fetch_failure_default, the removed fallback
frontmatter reader, extending skill-size-check's files: pattern to agents,
tidying .claude/settings.json out of the pretty-format-json exclude list) —
these exist to stop settled decisions being re-litigated, so none were
dropped. AGENTS.md keeps only what applies every session, at one clause of
rationale per rule. The .apm/-mirror section collapses to a pointer because
docs/spec/architecture.md already covers it in full. The hot ADR-0020 gate
counts stay in AGENTS.md deliberately: they block any skill edit today.

Also corrects docs/spec/architecture.md's stale claim of 19 ADRs; ADR-0020
landed without updating the count.

Impact: per-session preload drops from ~4,550 to ~1,116 tokens, a 75% cut.
agentsmd-audit passes: secrets clean, drift clean, 4 informational findings
for sections deliberately relocated to the README.
 2026-08-17 08:56:37 +00:00
Defame1297
123ece2fb3 chore(apm): refresh lock after SessionStart auto-update 
Why: kyberforge's SessionStart hook found six packages behind the holocron
default branch and ran `apm update --yes`, which re-resolved every unpinned
dependency ref and rewrote the lock. The dependencies are declared unpinned
against the default branch, so this churn is expected rather than a defect.

Impact: pins the deployed skill and agent set to the refs resolved this
session. No manifest or plugin content changed.
 2026-08-17 08:56:22 +00:00
409 changed files with 12699 additions and 4488 deletions
Expand all files Collapse all files

20
.claude-plugin/marketplace.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "holocron", "name": "holocron",
"description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
"version": "0.4.2", "version": "0.5.0",
"owner": { "owner": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",
@@ -11,35 +11,35 @@
{ {
"name": "kyberforge", "name": "kyberforge",
"description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.", "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
"version": "1.6.0", "version": "1.7.0",
"category": "Developer Tools", "category": "Developer Tools",
"source": "./plugins/kyberforge" "source": "./plugins/kyberforge"
}, },
{ {
"name": "bin", "name": "bin",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"version": "1.1.3", "version": "1.2.0",
"category": "Utilities", "category": "Utilities",
"source": "./plugins/bin" "source": "./plugins/bin"
}, },
{ {
"name": "git", "name": "git",
"description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.", "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"version": "1.3.3", "version": "1.4.0",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/git" "source": "./plugins/git"
}, },
{ {
"name": "gitea", "name": "gitea",
"description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
"version": "1.3.4", "version": "1.4.0",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/gitea" "source": "./plugins/gitea"
}, },
{ {
"name": "core", "name": "core",
"description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.", "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.2.0",
"category": "Productivity", "category": "Productivity",
"source": "./plugins/core" "source": "./plugins/core"
}, },
@@ -59,7 +59,7 @@
{ {
"name": "lint", "name": "lint",
"description": "Skills and agents for configuring and running linters.", "description": "Skills and agents for configuring and running linters.",
"version": "1.1.6", "version": "1.2.0",
"category": "Developer Tools", "category": "Developer Tools",
"source": "./plugins/lint" "source": "./plugins/lint"
} }

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

@@ -1,7 +1,7 @@
{ {
"name": "holocron", "name": "holocron",
"description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.", "description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
"version": "0.4.2", "version": "0.5.0",
"owner": { "owner": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",
@@ -11,35 +11,35 @@
{ {
"name": "kyberforge", "name": "kyberforge",
"description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.", "description": "Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.",
"version": "1.6.0", "version": "1.7.0",
"category": "Developer Tools", "category": "Developer Tools",
"source": "./plugins/kyberforge" "source": "./plugins/kyberforge"
}, },
{ {
"name": "bin", "name": "bin",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"version": "1.1.3", "version": "1.2.0",
"category": "Utilities", "category": "Utilities",
"source": "./plugins/bin" "source": "./plugins/bin"
}, },
{ {
"name": "git", "name": "git",
"description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.", "description": "Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.",
"version": "1.3.3", "version": "1.4.0",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/git" "source": "./plugins/git"
}, },
{ {
"name": "gitea", "name": "gitea",
"description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.",
"version": "1.3.4", "version": "1.4.0",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/gitea" "source": "./plugins/gitea"
}, },
{ {
"name": "core", "name": "core",
"description": "Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.", "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.2.0",
"category": "Productivity", "category": "Productivity",
"source": "./plugins/core" "source": "./plugins/core"
}, },
@@ -59,7 +59,7 @@
{ {
"name": "lint", "name": "lint",
"description": "Skills and agents for configuring and running linters.", "description": "Skills and agents for configuring and running linters.",
"version": "1.1.6", "version": "1.2.0",
"category": "Developer Tools", "category": "Developer Tools",
"source": "./plugins/lint" "source": "./plugins/lint"
} }

2
.pre-commit-config.yaml
View File

@@ -207,7 +207,7 @@ repos:
# pre-commit prints nothing at all for a passing hook, so without this # pre-commit prints nothing at all for a passing hook, so without this
# the opt-out reinstated exactly the silent vacuous pass the script was # the opt-out reinstated exactly the silent vacuous pass the script was
# written to kill, one level up -- the run showed a bare `Passed` and # written to kill, one level up -- the run showed a bare `Passed` and
# AGENTS.md's instruction to read that summary line was impossible to # the documented instruction to read that summary line was impossible to
# follow in the one situation the opt-out exists for. The script's clean # follow in the one situation the opt-out exists for. The script's clean
# output is a single line, so this costs one line per push. # output is a single line, so this costs one line per push.

63
AGENTS.md
View File

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

266
CONTEXT.md
View File

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

6
LESSONS.md
View File

@@ -1,8 +1,8 @@
# Lessons # Lessons
Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule. Patterns observed during development of this repo. Three or more entries on the same pattern → promote to `docs/spec/architecture.md` (or the relevant instruction file) as a standing rule.
**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail). **Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `docs/spec/architecture.md` for structural and domain-level principles — `CONTEXT.md` is not a destination, its `## Principles` section was deleted and what was there now sits under that file's "AGENTS.md pattern" and "Reference conventions" headings — `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
**Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly. **Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
@@ -26,7 +26,7 @@ Issue files frequently referenced "the workflow defined in `docs/notes/skill-imp
The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context. The repo CLAUDE.md instructs agents to read CONTEXT.md at session start, but agents skip this in practice — defaulting to reading only what's directly relevant to the immediate prompt (e.g. the skills folder). The governance.md works because `@import` is technically enforced by Claude Code. Fix: (1) add `@CONTEXT.md` to repo CLAUDE.md using `@import` to make it always-loaded; (2) add a "Key decisions" section to CONTEXT.md with one-line resolved-ADR summaries so locked choices are always in context.
**Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read CONTEXT.md at the start of every session in this repo," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change. **Status (2026-08-14): neither part landed.** Root `CLAUDE.md` imports `@AGENTS.md` only — no `@CONTEXT.md` — and `CONTEXT.md` has no "Key decisions" section. The behavioral hope this entry diagnosed is still the only mechanism in place: `AGENTS.md` carries the line "Read `CONTEXT.md` at the start of every session," which is loaded but is itself an instruction, not an import. The proposal above is open work, not a record of a completed change.
## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity ## 2026-05-17 — Instruction rules lose to RLHF defaults without specificity

131
README.md Normal file
View File

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

370
apm.lock.yaml
View File

@@ -1,12 +1,12 @@
lockfile_version: '1' lockfile_version: '1'
generated_at: '2026-08-14T21:26:25.156410+00:00' generated_at: '2026-08-30T11:38:46.419301+00:00'
apm_version: 0.28.0 apm_version: 0.28.0
dependencies: dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: bin name: bin
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.1.3 version: 1.1.5
virtual_path: plugins/bin virtual_path: plugins/bin
is_virtual: true is_virtual: true
package_type: marketplace_plugin package_type: marketplace_plugin
@@ -81,13 +81,13 @@ dependencies:
.claude/skills/triage/SKILL.md: sha256:b819f0285e4e5814ac6472d0217f07dc9f23d2fdae3ebb0dd31d98360d8ac029 .claude/skills/triage/SKILL.md: sha256:b819f0285e4e5814ac6472d0217f07dc9f23d2fdae3ebb0dd31d98360d8ac029
.claude/skills/write-docs/SKILL.md: sha256:0d06d0f6836a67532497ea61bd5a1294a8d80f529bf1ffb5c4b1fdc72e9cb51a .claude/skills/write-docs/SKILL.md: sha256:0d06d0f6836a67532497ea61bd5a1294a8d80f529bf1ffb5c4b1fdc72e9cb51a
.claude/skills/zoom-out/SKILL.md: sha256:2a6894c7f9b1c9c55f451c625a834c4f377e217b623a85280e55db5fe9cacf48 .claude/skills/zoom-out/SKILL.md: sha256:2a6894c7f9b1c9c55f451c625a834c4f377e217b623a85280e55db5fe9cacf48
content_hash: sha256:7acfaa806ae8379fe6351441ce8f973ac3ff8a02deb4a5e145968203d1176ef8 content_hash: sha256:d7cca4972651b241a5450679289fdb6f0e3a37aef9dff0498cb4b3340b048781
declared_license: MIT declared_license: MIT
exec_status: gated_pending_approval exec_status: gated_pending_approval
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: core name: core
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.1.1 version: 1.1.1
virtual_path: plugins/core virtual_path: plugins/core
is_virtual: true is_virtual: true
@@ -134,8 +134,8 @@ dependencies:
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: git name: git
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.3.3 version: 1.3.5
virtual_path: plugins/git virtual_path: plugins/git
is_virtual: true is_virtual: true
package_type: marketplace_plugin package_type: marketplace_plugin
@@ -236,13 +236,13 @@ dependencies:
.claude/skills/pc-run/references/README.md: sha256:ad42b9013dbd44b8c4515c15317c5e9e6b235bc656ad5a03e037eb4bc6f8782c .claude/skills/pc-run/references/README.md: sha256:ad42b9013dbd44b8c4515c15317c5e9e6b235bc656ad5a03e037eb4bc6f8782c
.claude/skills/pc-run/references/failure-patterns.md: sha256:59d913c001483c3770d269fdf5e83cf1d7578e0ae879928a1404bf93bb395994 .claude/skills/pc-run/references/failure-patterns.md: sha256:59d913c001483c3770d269fdf5e83cf1d7578e0ae879928a1404bf93bb395994
.claude/skills/pc-run/references/sources.md: sha256:7ca8b7106e7ee5c2c7d1fbd3dc9e0d2a89c18eba79145cbab55bc8e39eef9087 .claude/skills/pc-run/references/sources.md: sha256:7ca8b7106e7ee5c2c7d1fbd3dc9e0d2a89c18eba79145cbab55bc8e39eef9087
content_hash: sha256:6d0c8fcec32d8fb8321b539cc567c4241342cfa33e5d0b6f66697d2f8b784fdd content_hash: sha256:8c47bd35572c331f1a1b61a8be159d9690a1bf286958a85826fde01939e3007b
declared_license: MIT declared_license: MIT
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: gitea name: gitea
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.3.4 version: 1.3.6
virtual_path: plugins/gitea virtual_path: plugins/gitea
is_virtual: true is_virtual: true
package_type: marketplace_plugin package_type: marketplace_plugin
@@ -313,10 +313,10 @@ dependencies:
.claude/skills/gitea-labels-milestones/references/labels.md: sha256:be8ff5ce4dbfb31dd2bdcc425a769dca94887c5c8acd47c78e1e21ccfc24dcba .claude/skills/gitea-labels-milestones/references/labels.md: sha256:be8ff5ce4dbfb31dd2bdcc425a769dca94887c5c8acd47c78e1e21ccfc24dcba
.claude/skills/gitea-labels-milestones/references/milestones.md: sha256:ff1f1b0c8ecb6967c940d1ca8bebf2a2c7995414936f8ac7f5ff23d1dc01ac3f .claude/skills/gitea-labels-milestones/references/milestones.md: sha256:ff1f1b0c8ecb6967c940d1ca8bebf2a2c7995414936f8ac7f5ff23d1dc01ac3f
.claude/skills/gitea-labels-milestones/references/sources.md: sha256:a1a1d3381dfb0dc8f331be0b3ab49f28e94b992fb4809ca09be91ce33047dd1e .claude/skills/gitea-labels-milestones/references/sources.md: sha256:a1a1d3381dfb0dc8f331be0b3ab49f28e94b992fb4809ca09be91ce33047dd1e
.claude/skills/gitea-prs/README.md: sha256:0346388f642641c56cef82ba1ee576a187d048eee66fab839a17417c81122cbc .claude/skills/gitea-prs/README.md: sha256:31b6ad46379feee8ac7d837030f93ec04be20b7d11021b295dc6d27b4340a05b
.claude/skills/gitea-prs/SKILL.md: sha256:bf70832f3d97064c9816d680390da84c256a971d7804317e1814b4ee6a622b4d .claude/skills/gitea-prs/SKILL.md: sha256:bf70832f3d97064c9816d680390da84c256a971d7804317e1814b4ee6a622b4d
.claude/skills/gitea-prs/references/merging.md: sha256:5f8b55b1a729f122ee265fb5da69369fc27434a13dd02fc112801f945d2c9d19 .claude/skills/gitea-prs/references/merging.md: sha256:5f8b55b1a729f122ee265fb5da69369fc27434a13dd02fc112801f945d2c9d19
.claude/skills/gitea-prs/references/pull-requests.md: sha256:631874a7cddfcf678a2beffa5578fa7848bcef36be1251fa13fb0ccc543bcaf7 .claude/skills/gitea-prs/references/pull-requests.md: sha256:d6cefd0cf270f8d844536311e67bfa45cd07f024aa0a649de1938af306ae7109
.claude/skills/gitea-prs/references/reviews.md: sha256:1089cf45a75a562bbb29de6538848c4f4bd627d5a7e36bf9b2ab6496f45f962b .claude/skills/gitea-prs/references/reviews.md: sha256:1089cf45a75a562bbb29de6538848c4f4bd627d5a7e36bf9b2ab6496f45f962b
.claude/skills/gitea-prs/references/sources.md: sha256:ac48a3018443b56acb5c3d55d6c04e62103f5bac71b8185e2bd085fb7e165431 .claude/skills/gitea-prs/references/sources.md: sha256:ac48a3018443b56acb5c3d55d6c04e62103f5bac71b8185e2bd085fb7e165431
.claude/skills/gitea-releases/README.md: sha256:102625066c34c7b5a16e25b7506a87f876e9b123b334f5ffba73ab1523a57ed7 .claude/skills/gitea-releases/README.md: sha256:102625066c34c7b5a16e25b7506a87f876e9b123b334f5ffba73ab1523a57ed7
@@ -327,13 +327,13 @@ dependencies:
.claude/skills/gitea-workflow/README.md: sha256:338f79d0b3c25741848fce841a5094ef27cbc7e4a6228404557b2d9594df68fa .claude/skills/gitea-workflow/README.md: sha256:338f79d0b3c25741848fce841a5094ef27cbc7e4a6228404557b2d9594df68fa
.claude/skills/gitea-workflow/SKILL.md: sha256:a8266ceb335c56eb68cc09b3f81690c52c4dada9f25b48c3a46ac46b0ad3b761 .claude/skills/gitea-workflow/SKILL.md: sha256:a8266ceb335c56eb68cc09b3f81690c52c4dada9f25b48c3a46ac46b0ad3b761
.claude/skills/gitea-workflow/references/sources.md: sha256:171d3a5a36cb9d637302516501a1e9fc7a4bd058968dc9244412c335aa2de68b .claude/skills/gitea-workflow/references/sources.md: sha256:171d3a5a36cb9d637302516501a1e9fc7a4bd058968dc9244412c335aa2de68b
content_hash: sha256:8149467df78678963dbb140aa254f606a53491f3cb7e5d97a1211be426e7892e content_hash: sha256:16d5b4462c3f4a506c1c74172d4d67bf0dacc4218676de4e8dfe551b2f31a3f8
declared_license: MIT declared_license: MIT
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: kyberforge name: kyberforge
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.5.0 version: 1.6.0
virtual_path: plugins/kyberforge virtual_path: plugins/kyberforge
is_virtual: true is_virtual: true
package_type: marketplace_plugin package_type: marketplace_plugin
@@ -344,15 +344,20 @@ dependencies:
- .claude/skills/agent-audit/README.md - .claude/skills/agent-audit/README.md
- .claude/skills/agent-audit/SKILL.md - .claude/skills/agent-audit/SKILL.md
- .claude/skills/agent-audit/assets/vale/.vale.ini - .claude/skills/agent-audit/assets/vale/.vale.ini
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
- .claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml - .claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml
- .claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml - .claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml
- .claude/skills/agent-audit/references/README.md - .claude/skills/agent-audit/references/README.md
- .claude/skills/agent-audit/references/body-and-delegation.md
- .claude/skills/agent-audit/references/description-quality.md - .claude/skills/agent-audit/references/description-quality.md
- .claude/skills/agent-audit/references/field-inventory.md - .claude/skills/agent-audit/references/field-inventory.md
- .claude/skills/agent-audit/references/scope-plugin-apm.md
- .claude/skills/agent-audit/references/scope-project-user.md
- .claude/skills/agent-audit/references/sources.md - .claude/skills/agent-audit/references/sources.md
- .claude/skills/agent-audit/references/validation-scripts.md
- .claude/skills/agent-audit/scripts/README.md - .claude/skills/agent-audit/scripts/README.md
- .claude/skills/agent-audit/scripts/vale-wrap.sh - .claude/skills/agent-audit/scripts/vale-wrap.sh
- .claude/skills/agent-audit/scripts/validate-provenance.sh - .claude/skills/agent-audit/scripts/validate-provenance.sh
@@ -365,7 +370,12 @@ dependencies:
- .claude/skills/agent-author/assets/templates/claude-code.md - .claude/skills/agent-author/assets/templates/claude-code.md
- .claude/skills/agent-author/assets/templates/copilot.agent.md.template - .claude/skills/agent-author/assets/templates/copilot.agent.md.template
- .claude/skills/agent-author/references/README.md - .claude/skills/agent-author/references/README.md
- .claude/skills/agent-author/references/contract.md
- .claude/skills/agent-author/references/create.md
- .claude/skills/agent-author/references/deployment-modes.md - .claude/skills/agent-author/references/deployment-modes.md
- .claude/skills/agent-author/references/improve.md
- .claude/skills/agent-author/references/plugin-scope.md
- .claude/skills/agent-author/references/project-user-scope.md
- .claude/skills/agent-author/references/scripts.md - .claude/skills/agent-author/references/scripts.md
- .claude/skills/agent-author/references/sources.md - .claude/skills/agent-author/references/sources.md
- .claude/skills/agent-author/scripts/README.md - .claude/skills/agent-author/scripts/README.md
@@ -391,13 +401,18 @@ dependencies:
- .claude/skills/skill-audit/README.md - .claude/skills/skill-audit/README.md
- .claude/skills/skill-audit/SKILL.md - .claude/skills/skill-audit/SKILL.md
- .claude/skills/skill-audit/assets/vale/.vale.ini - .claude/skills/skill-audit/assets/vale/.vale.ini
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml
- .claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml - .claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml
- .claude/skills/skill-audit/references/body-discipline.md - .claude/skills/skill-audit/references/body-discipline.md
- .claude/skills/skill-audit/references/description-quality.md - .claude/skills/skill-audit/references/description-quality.md
- .claude/skills/skill-audit/references/file-structure.md
- .claude/skills/skill-audit/references/formatting-and-scripts.md
- .claude/skills/skill-audit/references/patterns.md
- .claude/skills/skill-audit/references/sources.md - .claude/skills/skill-audit/references/sources.md
- .claude/skills/skill-audit/references/validation-scripts.md
- .claude/skills/skill-audit/scripts/vale-wrap.sh - .claude/skills/skill-audit/scripts/vale-wrap.sh
- .claude/skills/skill-audit/scripts/validate-provenance.sh - .claude/skills/skill-audit/scripts/validate-provenance.sh
- .claude/skills/skill-audit/scripts/validate.sh - .claude/skills/skill-audit/scripts/validate.sh
@@ -411,41 +426,55 @@ dependencies:
- .claude/skills/skill-author/assets/templates/references/sources.md - .claude/skills/skill-author/assets/templates/references/sources.md
- .claude/skills/skill-author/assets/templates/scripts/README.md - .claude/skills/skill-author/assets/templates/scripts/README.md
- .claude/skills/skill-author/assets/templates/tests/README.md - .claude/skills/skill-author/assets/templates/tests/README.md
- .claude/skills/skill-author/references/contract.md
- .claude/skills/skill-author/references/create.md
- .claude/skills/skill-author/references/deployment-modes.md - .claude/skills/skill-author/references/deployment-modes.md
- .claude/skills/skill-author/references/improve.md
- .claude/skills/skill-author/references/retrofit.md
- .claude/skills/skill-author/references/scripts.md - .claude/skills/skill-author/references/scripts.md
- .claude/skills/skill-author/references/sources.md - .claude/skills/skill-author/references/sources.md
- .claude/skills/skill-author/scripts/new-skill.sh - .claude/skills/skill-author/scripts/new-skill.sh
deployed_file_hashes: deployed_file_hashes:
.claude/agents/apm-orchestrate.md: sha256:fbb78f7c8c58b018639e7a39f2f1b3ce2adcd6bed277b3c8f8cd70893698ec73 .claude/agents/apm-orchestrate.md: sha256:fbb78f7c8c58b018639e7a39f2f1b3ce2adcd6bed277b3c8f8cd70893698ec73
.claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh: sha256:96f44d63b5f4906ac1add5c32b718176ec10c8514615151d7303d9845c607b46 .claude/hooks/kyberforge/.apm/hooks/check-apm-current.sh: sha256:96f44d63b5f4906ac1add5c32b718176ec10c8514615151d7303d9845c607b46
.claude/skills/agent-audit/README.md: sha256:a3a63acb80981975330bd9a86d81c8f3e632f7f2d97ac99951710d035fb52953 .claude/skills/agent-audit/README.md: sha256:fafdb84bf258f6d606c97b785c7c378b5de805f0aa8a10d3cedefedb000e4230
.claude/skills/agent-audit/SKILL.md: sha256:080f391ea25de8afc5a20478cbd382a8d28fcf70a7be7f012033dacb6e9bfed3 .claude/skills/agent-audit/SKILL.md: sha256:a126a2a7b1b8c9f6b39272584e2f84577aeeb8c81707be6f151b3acbe35ecf51
.claude/skills/agent-audit/assets/vale/.vale.ini: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57 .claude/skills/agent-audit/assets/vale/.vale.ini: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/CompositionNote.yml: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629
.claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083 .claude/skills/agent-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083
.claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml: sha256:ba4f91479f66f9f03c74f791cbc6130b24bbc31a25f3897b424f72d02473b9b4 .claude/skills/agent-audit/assets/vale/styles/KyberforgeCopilot/ProactivePhrase.yml: sha256:ba4f91479f66f9f03c74f791cbc6130b24bbc31a25f3897b424f72d02473b9b4
.claude/skills/agent-audit/references/README.md: sha256:7664ae08efc8373c0b253c0a5c7a9cc930720c62abb8d31a81b2aedbd573dd30 .claude/skills/agent-audit/references/README.md: sha256:f6d777f7d3844d1be847f86f67b08c2db37b2d122e0bf1af92ef057bbfdd1004
.claude/skills/agent-audit/references/description-quality.md: sha256:79c62fd641d6785a3349d8ff1e207c64547ef9435d51e88518fc9fb5c2f4962e .claude/skills/agent-audit/references/body-and-delegation.md: sha256:788664bb75364354773bd9efd4a0f84a231009d3a8b080e2561fefff2aa95b69
.claude/skills/agent-audit/references/description-quality.md: sha256:15eea332149203ac18c6b3eee98f0078e8a764cdb91b3158590f45204cb3322a
.claude/skills/agent-audit/references/field-inventory.md: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae .claude/skills/agent-audit/references/field-inventory.md: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae
.claude/skills/agent-audit/references/sources.md: sha256:9e06addbfb1a58e4db23eaabe9fb13afe0fffa8419afa575525136cec189c558 .claude/skills/agent-audit/references/scope-plugin-apm.md: sha256:af32acf33aec0cd0a98022ee6796265066c693662e8874a8e4d7e03ce1657c88
.claude/skills/agent-audit/references/scope-project-user.md: sha256:9ea0d4014d78a6b02c760e42fb6cb72b3441ae6c93991fdeca666857bad05056
.claude/skills/agent-audit/references/sources.md: sha256:235de49e805d83ba19f8ecdc90da2f7d3b02c5f1c2fc54179d6bdd5bc398743e
.claude/skills/agent-audit/references/validation-scripts.md: sha256:7eb48ec40175d6cce2b3b9602c0d9e60d62bacca1df7cc120c138ea1ce328666
.claude/skills/agent-audit/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2 .claude/skills/agent-audit/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2
.claude/skills/agent-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995 .claude/skills/agent-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995
.claude/skills/agent-audit/scripts/validate-provenance.sh: sha256:0e1d2b3bb1abb9f302ed84a618246ebaa7d5f7fda727b290d323e70dcc26a323 .claude/skills/agent-audit/scripts/validate-provenance.sh: sha256:0e1d2b3bb1abb9f302ed84a618246ebaa7d5f7fda727b290d323e70dcc26a323
.claude/skills/agent-audit/scripts/validate.sh: sha256:29727875f419b8d3b6c76f157b7569adb4d2b9a88f01eeb2c09e04dfb8541cb3 .claude/skills/agent-audit/scripts/validate.sh: sha256:50c6d3875fd44901fba3fcb69256f616be19521ee8209b7132778c1d4a693a3f
.claude/skills/agent-author/README.md: sha256:015a6b030ff2aa913f982a223f8afad789edadc4e7148d3b1740a56b346c658d .claude/skills/agent-author/README.md: sha256:b2d14a3c8fc3ddc3935d0bd1765192b333b944baaf9bfa9a350bef0985890265
.claude/skills/agent-author/SKILL.md: sha256:39193473a9b1beacb4790cab4e5e31e01f7021a68a5c4cc16a606420bee65d6a .claude/skills/agent-author/SKILL.md: sha256:8fe96e4744378cd33876cf87a08a20af001898e89f0f27087044e1b87eac61f2
.claude/skills/agent-author/assets/README.md: sha256:a82665201ead91b7fa2b37629327ecb89ca785b7f2b261300c2dd816b4219bcd .claude/skills/agent-author/assets/README.md: sha256:730b2321b5f16dcc63fc5dc842618c116afc75217ae925057dafc490e7d57644
.claude/skills/agent-author/assets/templates/apm-agent.md: sha256:c2693395d7ec72645fc1b79c65039ddadc0077f5856de3277d600bde41f17e54 .claude/skills/agent-author/assets/templates/apm-agent.md: sha256:9b57e2b93a5705388351f14294d60833325d9596cf5294d22f4a586165fc35fa
.claude/skills/agent-author/assets/templates/claude-code.md: sha256:eef5ee46d93b6896e880b3c4aec1121c4077a2556c6d9f4a01b322afc7b63a7e .claude/skills/agent-author/assets/templates/claude-code.md: sha256:ea0bac6e8cd91c767c6114cbcf1ecd124d03abff06ba81696dac5115499c395a
.claude/skills/agent-author/assets/templates/copilot.agent.md.template: sha256:1e0c0445a8908148e69baeeb44316fb370aa483e17fcd63d7f1b2d3ad1927788 .claude/skills/agent-author/assets/templates/copilot.agent.md.template: sha256:ee8b7585c808c5ff4b715be74d9e4f8c5c17d13cd603a8727cd8ca1793d14760
.claude/skills/agent-author/references/README.md: sha256:bb4cf7a34c512da33f574b208756941f396f4a1e55daaed0fad22569a22af301 .claude/skills/agent-author/references/README.md: sha256:aca156b02a3f0b9fddde3cefdb24370e17cc5886dcd78adcb382699a5cc0bbaf
.claude/skills/agent-author/references/deployment-modes.md: sha256:6cd010455e10574566ebf7cfd0926217ae5812d56a62daf4bcdb325abf3b0421 .claude/skills/agent-author/references/contract.md: sha256:a96f0ef021a6629120e5af7c98fa483d31de92cea37f98b51528a28dee38e16a
.claude/skills/agent-author/references/create.md: sha256:e4a1b95970ec44d551a4b0598f2fe01463db13a6b118981d8cd03dfc7e24f451
.claude/skills/agent-author/references/deployment-modes.md: sha256:5675f8dcd1523269d5c65be5b0e06ff4d822b158050e2fdd72b54f605485ab1f
.claude/skills/agent-author/references/improve.md: sha256:f260e91f28bbd62093b53f4efc05821eff00d086f834ddb083b70dd77ddffcaa
.claude/skills/agent-author/references/plugin-scope.md: sha256:a20f8aff55c9d1c1ba5e21054b81da80618270b3b6ca5bfc37ae3c2089b4b916
.claude/skills/agent-author/references/project-user-scope.md: sha256:3f686736259402e38fed29f215b7aa5a9529fc9025005f82d0c3d439958e4e03
.claude/skills/agent-author/references/scripts.md: sha256:290f5d8ab0a4f2073e14f7139fd55ab40310137f08ca7a2d59ed35a53488a592 .claude/skills/agent-author/references/scripts.md: sha256:290f5d8ab0a4f2073e14f7139fd55ab40310137f08ca7a2d59ed35a53488a592
.claude/skills/agent-author/references/sources.md: sha256:56965f9b660fc9a32dd71ca1039b4c6b8f932420628ddfbf3a2525e7c3336ce4 .claude/skills/agent-author/references/sources.md: sha256:cac8baf85a6d958ed2f0f882446dc123d14082d5ca412c8edee12c6cd1b6fdc3
.claude/skills/agent-author/scripts/README.md: sha256:e8ea2f3391ca297afeda03911768000617a71df0cf9d673bbb260ee5bbfed7c2 .claude/skills/agent-author/scripts/README.md: sha256:e8ea2f3391ca297afeda03911768000617a71df0cf9d673bbb260ee5bbfed7c2
.claude/skills/agent-author/scripts/new-agent.sh: sha256:e917055957500a72c7f684810552ba8931781c90f96dedaabc07e899dae02a89 .claude/skills/agent-author/scripts/new-agent.sh: sha256:1c631f5178c6c0c397d7ceefb606892dd7e330cd1b22a03c1e4d11e85fbdb7de
.claude/skills/apm-install/README.md: sha256:d7bd79ee27997fffb5765c03358a700d8c00266ea120f6d067d74300d6c26eb0 .claude/skills/apm-install/README.md: sha256:d7bd79ee27997fffb5765c03358a700d8c00266ea120f6d067d74300d6c26eb0
.claude/skills/apm-install/SKILL.md: sha256:4c0db5454bcbf895a89e7405eeefb4521a2b23f2ff28aa96c82c59708d8819ee .claude/skills/apm-install/SKILL.md: sha256:4c0db5454bcbf895a89e7405eeefb4521a2b23f2ff28aa96c82c59708d8819ee
.claude/skills/apm-install/references/sources.md: sha256:b80245ff8ae179d458572cb9b03621d00bf7e2f052f0cd71b88112c0ea8a91ce .claude/skills/apm-install/references/sources.md: sha256:b80245ff8ae179d458572cb9b03621d00bf7e2f052f0cd71b88112c0ea8a91ce
@@ -460,39 +489,48 @@ dependencies:
.claude/skills/forge/README.md: sha256:2151b952f4438cd9212edd97de90eec06f027f01121b3badb9d32dc9c45320c4 .claude/skills/forge/README.md: sha256:2151b952f4438cd9212edd97de90eec06f027f01121b3badb9d32dc9c45320c4
.claude/skills/forge/SKILL.md: sha256:4de4c629cb4aec4c6cac5347163a86fe123299f131510dc43857597ded6ae497 .claude/skills/forge/SKILL.md: sha256:4de4c629cb4aec4c6cac5347163a86fe123299f131510dc43857597ded6ae497
.claude/skills/forge/references/sources.md: sha256:a7f614c0ab37aa403545e191722bca012836162dcab30ff8ac984cbb25ad68cd .claude/skills/forge/references/sources.md: sha256:a7f614c0ab37aa403545e191722bca012836162dcab30ff8ac984cbb25ad68cd
.claude/skills/skill-audit/README.md: sha256:9e3533c3c44cfd249cf02684ef43db822ed41382362e8ce71f1254d10711c8e0 .claude/skills/skill-audit/README.md: sha256:78bfcfb16bbeef814b83f37a4a5185886003f9442a6d0e7e94be56f54d18d7a5
.claude/skills/skill-audit/SKILL.md: sha256:dbe2adfd0101cf9d6b3c2c3c2aa3ae397c717f835c1059c0f1d805e9057dc397 .claude/skills/skill-audit/SKILL.md: sha256:57a9336d409c883dc9a78aa92a9f0075fac6f8e4aac6ee8fdab705055ef85162
.claude/skills/skill-audit/assets/vale/.vale.ini: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f .claude/skills/skill-audit/assets/vale/.vale.ini: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/CompositionNote.yml: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml: sha256:67b738f5c393a717bdf249fcd946eb7b0d258215bf2240d2be6902711b46d8e9
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/SentenceOpenerThereIs.yml: sha256:5dade0238d96730d24bb6e8dba003c3d94694bd9969687f461fe1fada3ca4629
.claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083 .claude/skills/skill-audit/assets/vale/styles/Kyberforge/VagueWording.yml: sha256:d4bf14d0bb2dcbe3a89b66b72a9c9c19d175060b5c4c978da3d67010f1a25083
.claude/skills/skill-audit/references/body-discipline.md: sha256:2295d2fc72fa529f3700c21fa93516ad186a7cc66d470370173ab1a784d03d31 .claude/skills/skill-audit/references/body-discipline.md: sha256:f8a27d7266f4453781712f0bead151580158581a445a641613203a67a1c337d7
.claude/skills/skill-audit/references/description-quality.md: sha256:ab077e71bbc6e9d8e2a1384bedaf613a4219f28bbe42eb9e89f933b579db6b33 .claude/skills/skill-audit/references/description-quality.md: sha256:2d37eccb4889cade6cbad0deaaed6d1f5fe4c3276c5438c244b2f87ae27bf432
.claude/skills/skill-audit/references/sources.md: sha256:cb65dd3cc411d7b264fab24de5cd2353dec8fbb7bbcfe2388535d963be240280 .claude/skills/skill-audit/references/file-structure.md: sha256:b24638bd639ef048da171f6dc711e345749cde3c70ec6ba1b7fcbd696b921841
.claude/skills/skill-audit/references/formatting-and-scripts.md: sha256:5c319866b2f22ba07789dae7b0813132f67196c508e8da23971307c2a9e57095
.claude/skills/skill-audit/references/patterns.md: sha256:4a942ab30b95dc0cbf0fbe7da3b91157f166bce80cbd17bcf60dc365ea9237af
.claude/skills/skill-audit/references/sources.md: sha256:1db16ea23884ac2db799b42d1284daaab4b24eb94f184a95fb67ddc280385934
.claude/skills/skill-audit/references/validation-scripts.md: sha256:44f3b82413b57f2b5671637bb449a4c01b6d5fcd9059245aaa38e45108adf480
.claude/skills/skill-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995 .claude/skills/skill-audit/scripts/vale-wrap.sh: sha256:c17673b3b0de1c1a49fcb73e2b695835a45014ec1c300a77a3ba7b3c7ce4c995
.claude/skills/skill-audit/scripts/validate-provenance.sh: sha256:015376c5ad1f6bb6b53549537317a55e3ac06cd4e347451dba85879a3928ccbe .claude/skills/skill-audit/scripts/validate-provenance.sh: sha256:015376c5ad1f6bb6b53549537317a55e3ac06cd4e347451dba85879a3928ccbe
.claude/skills/skill-audit/scripts/validate.sh: sha256:ebbef859276135b7fe4189b31396fd98e5d4019685d7cb55e39a10fac8ca546d .claude/skills/skill-audit/scripts/validate.sh: sha256:7ce27df82e4160c6296db6c8314865f022da5c4334151857570a86167c8d4e11
.claude/skills/skill-author/README.md: sha256:6c0b36f9b28a33de1646df45bd8e4d733ab3b26c0bdff49743962aa068085f6d .claude/skills/skill-author/README.md: sha256:d22035d302818e103486e447bd92d2da4c9b73da60f30157941710f32f400b89
.claude/skills/skill-author/SKILL.md: sha256:7b82d16fe0d61a71c5b59a244cf92b9b5fc2635916ad1572f4f5f6e37172bf09 .claude/skills/skill-author/SKILL.md: sha256:615a936580f44dd8e523496aadf88df6d512ac58369190b90407e8fca86e8345
.claude/skills/skill-author/assets/templates/README.md: sha256:f7e91356f4c85862f96a9f46a7a7ae8b5dc715c8174add5cf070166a8bae0658 .claude/skills/skill-author/assets/templates/README.md: sha256:f7e91356f4c85862f96a9f46a7a7ae8b5dc715c8174add5cf070166a8bae0658
.claude/skills/skill-author/assets/templates/SKILL.md: sha256:f05a127963874bfbbe4333c42c5208736d84d5bf12dd8478351f6853304cc9d1 .claude/skills/skill-author/assets/templates/SKILL.md: sha256:b20c65bd185b300de7e65d16decdf0ab4aaf6c094822c1f798b3c278d52abbff
.claude/skills/skill-author/assets/templates/assets/README.md: sha256:b72e51e643c45ded210a257e475d5661035d2aa5ed581e3294fd2aed00765c4b .claude/skills/skill-author/assets/templates/assets/README.md: sha256:b72e51e643c45ded210a257e475d5661035d2aa5ed581e3294fd2aed00765c4b
.claude/skills/skill-author/assets/templates/references/README.md: sha256:63754636f84a7841f31ab1f2854025ee449a29840ed6b9b51bcb1422ab5522d0 .claude/skills/skill-author/assets/templates/references/README.md: sha256:e2ef117972ab2625a456ed80ff085859666d145de4e270f383cde7c8e84ad60a
.claude/skills/skill-author/assets/templates/references/sources.md: sha256:fe126720ba890b98e829f2626e3f5a361a0c2ce47eda97bd3f7dc1812ddd62b7 .claude/skills/skill-author/assets/templates/references/sources.md: sha256:fe126720ba890b98e829f2626e3f5a361a0c2ce47eda97bd3f7dc1812ddd62b7
.claude/skills/skill-author/assets/templates/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2 .claude/skills/skill-author/assets/templates/scripts/README.md: sha256:ee427eed6a562a6e86898c69c35508c518d5b3c633ae803e587fbab37514f2b2
.claude/skills/skill-author/assets/templates/tests/README.md: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442 .claude/skills/skill-author/assets/templates/tests/README.md: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442
.claude/skills/skill-author/references/contract.md: sha256:d350721118a2bd57094fa9151f11b48a663a1c8a04e50fba71ff2baf64b7282f
.claude/skills/skill-author/references/create.md: sha256:0837a77ad6da7ae9894134d15eebd57950b8505e8bd2b32ee69f281d65a6abcb
.claude/skills/skill-author/references/deployment-modes.md: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759 .claude/skills/skill-author/references/deployment-modes.md: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759
.claude/skills/skill-author/references/improve.md: sha256:abe029587ce475fed165d8fcfa46ea1abe83f90727d093f8121a9a7a7daa5a3d
.claude/skills/skill-author/references/retrofit.md: sha256:6c8336caa717f2abd38cb1f9c776479c0e908f7dbf577021d3689b375287dc77
.claude/skills/skill-author/references/scripts.md: sha256:fe71da1fb3d947846ad1a37348f90866b0c4f7dbd81331cfe3300981656f6cc2 .claude/skills/skill-author/references/scripts.md: sha256:fe71da1fb3d947846ad1a37348f90866b0c4f7dbd81331cfe3300981656f6cc2
.claude/skills/skill-author/references/sources.md: sha256:27637acad4c0cdc7f1db15bc9cab339ebdac643e084642c58945ac2f81020c75 .claude/skills/skill-author/references/sources.md: sha256:652f7ce26c0d68a3ed11db09206bff20ba230ca8ff1fe71ae45b6f4505979327
.claude/skills/skill-author/scripts/new-skill.sh: sha256:46c6903404b9eabbd6c83892213fdabf9cad193be64613b8c1b84c8dc37e8eb2 .claude/skills/skill-author/scripts/new-skill.sh: sha256:c788b56f73ed4fd03edb179159361fe16e3afbf528a9895e9251909c5aa40a7f
content_hash: sha256:c89a45409fd3e06a6c63ca8a8f0f0d9c8e10bbded73fdef15dd482eebc6b6a78 content_hash: sha256:32185a11d3d859e5235de2c43065920ba8950c1684e6aec46f0f7170ff4a111e
declared_license: MIT declared_license: MIT
exec_status: deployed exec_status: deployed
- repo_url: Defame1297/holocron - repo_url: Defame1297/holocron
name: lint name: lint
host: git.dev.rkdr.net host: git.dev.rkdr.net
resolved_commit: f9b919d7e3bd5e6b51fbdf88b32ace0438b313e0 resolved_commit: 0e91a3ae66d1b0439b9c0ef4b6e88ca6f2659473
version: 1.1.6 version: 1.1.6
virtual_path: plugins/lint virtual_path: plugins/lint
is_virtual: true is_virtual: true
@@ -519,9 +557,8 @@ dependencies:
.claude/skills/vale-run/SKILL.md: sha256:16c42c97de14ef20296b9dfce46b0e2f9be6ad68751c35975251cecff80f79d9 .claude/skills/vale-run/SKILL.md: sha256:16c42c97de14ef20296b9dfce46b0e2f9be6ad68751c35975251cecff80f79d9
.claude/skills/vale-run/references/sources.md: sha256:1f46b727e5f3db09d6c8c01c8a615bad60ce2c5b3a01226e1a3fd3b933330bc7 .claude/skills/vale-run/references/sources.md: sha256:1f46b727e5f3db09d6c8c01c8a615bad60ce2c5b3a01226e1a3fd3b933330bc7
.claude/skills/vale-run/references/troubleshooting.md: sha256:b4c2bc67b413b102d9fe1cd7e5a248b19aba3dc3b60b4429e777977cf8021cd5 .claude/skills/vale-run/references/troubleshooting.md: sha256:b4c2bc67b413b102d9fe1cd7e5a248b19aba3dc3b60b4429e777977cf8021cd5
content_hash: sha256:7bc57b8852680bdcba32a6a6108b99ef6bcdf26eacfecd806c421ec5d1fd47d9 content_hash: sha256:f7915119bf5d349bb4dd26b7999278770dd2e0b38e4b4db57c0819a15cbf97a3
declared_license: MIT declared_license: MIT
exec_status: gated_pending_approval
deployments: deployments:
- kind: project-relative - kind: project-relative
target: claude target: claude
@@ -585,7 +622,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a3a63acb80981975330bd9a86d81c8f3e632f7f2d97ac99951710d035fb52953 content_hash: sha256:fafdb84bf258f6d606c97b785c7c378b5de805f0aa8a10d3cedefedb000e4230
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/SKILL.md value: .claude/skills/agent-audit/SKILL.md
@@ -594,7 +631,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:080f391ea25de8afc5a20478cbd382a8d28fcf70a7be7f012033dacb6e9bfed3 content_hash: sha256:a126a2a7b1b8c9f6b39272584e2f84577aeeb8c81707be6f151b3acbe35ecf51
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/assets/vale/.vale.ini value: .claude/skills/agent-audit/assets/vale/.vale.ini
@@ -604,6 +641,15 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57 content_hash: sha256:d643677585c603edcc8816b15d9c85c81b677ded02247b521ba8b88ae5bfdf57
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
@@ -612,7 +658,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 content_hash: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml value: .claude/skills/agent-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
@@ -657,7 +703,16 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:7664ae08efc8373c0b253c0a5c7a9cc930720c62abb8d31a81b2aedbd573dd30 content_hash: sha256:f6d777f7d3844d1be847f86f67b08c2db37b2d122e0bf1af92ef057bbfdd1004
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/body-and-delegation.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:788664bb75364354773bd9efd4a0f84a231009d3a8b080e2561fefff2aa95b69
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/references/description-quality.md value: .claude/skills/agent-audit/references/description-quality.md
@@ -666,7 +721,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:79c62fd641d6785a3349d8ff1e207c64547ef9435d51e88518fc9fb5c2f4962e content_hash: sha256:15eea332149203ac18c6b3eee98f0078e8a764cdb91b3158590f45204cb3322a
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/references/field-inventory.md value: .claude/skills/agent-audit/references/field-inventory.md
@@ -676,6 +731,24 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae content_hash: sha256:e9abd738c08890994441d215eba96f894e00992cb7bb5ce850796186050aa1ae
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/scope-plugin-apm.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:af32acf33aec0cd0a98022ee6796265066c693662e8874a8e4d7e03ce1657c88
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/scope-project-user.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:9ea0d4014d78a6b02c760e42fb6cb72b3441ae6c93991fdeca666857bad05056
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/references/sources.md value: .claude/skills/agent-audit/references/sources.md
@@ -684,7 +757,16 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:9e06addbfb1a58e4db23eaabe9fb13afe0fffa8419afa575525136cec189c558 content_hash: sha256:235de49e805d83ba19f8ecdc90da2f7d3b02c5f1c2fc54179d6bdd5bc398743e
- kind: project-relative
target: claude
value: .claude/skills/agent-audit/references/validation-scripts.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:7eb48ec40175d6cce2b3b9602c0d9e60d62bacca1df7cc120c138ea1ce328666
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-audit/scripts/README.md value: .claude/skills/agent-audit/scripts/README.md
@@ -720,7 +802,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:29727875f419b8d3b6c76f157b7569adb4d2b9a88f01eeb2c09e04dfb8541cb3 content_hash: sha256:50c6d3875fd44901fba3fcb69256f616be19521ee8209b7132778c1d4a693a3f
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author value: .claude/skills/agent-author
@@ -738,7 +820,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:015a6b030ff2aa913f982a223f8afad789edadc4e7148d3b1740a56b346c658d content_hash: sha256:b2d14a3c8fc3ddc3935d0bd1765192b333b944baaf9bfa9a350bef0985890265
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/SKILL.md value: .claude/skills/agent-author/SKILL.md
@@ -747,7 +829,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:39193473a9b1beacb4790cab4e5e31e01f7021a68a5c4cc16a606420bee65d6a content_hash: sha256:8fe96e4744378cd33876cf87a08a20af001898e89f0f27087044e1b87eac61f2
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/README.md value: .claude/skills/agent-author/assets/README.md
@@ -756,7 +838,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a82665201ead91b7fa2b37629327ecb89ca785b7f2b261300c2dd816b4219bcd content_hash: sha256:730b2321b5f16dcc63fc5dc842618c116afc75217ae925057dafc490e7d57644
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/templates/apm-agent.md value: .claude/skills/agent-author/assets/templates/apm-agent.md
@@ -765,7 +847,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:c2693395d7ec72645fc1b79c65039ddadc0077f5856de3277d600bde41f17e54 content_hash: sha256:9b57e2b93a5705388351f14294d60833325d9596cf5294d22f4a586165fc35fa
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/templates/claude-code.md value: .claude/skills/agent-author/assets/templates/claude-code.md
@@ -774,7 +856,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:eef5ee46d93b6896e880b3c4aec1121c4077a2556c6d9f4a01b322afc7b63a7e content_hash: sha256:ea0bac6e8cd91c767c6114cbcf1ecd124d03abff06ba81696dac5115499c395a
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/assets/templates/copilot.agent.md.template value: .claude/skills/agent-author/assets/templates/copilot.agent.md.template
@@ -783,7 +865,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:1e0c0445a8908148e69baeeb44316fb370aa483e17fcd63d7f1b2d3ad1927788 content_hash: sha256:ee8b7585c808c5ff4b715be74d9e4f8c5c17d13cd603a8727cd8ca1793d14760
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/references/README.md value: .claude/skills/agent-author/references/README.md
@@ -792,7 +874,25 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:bb4cf7a34c512da33f574b208756941f396f4a1e55daaed0fad22569a22af301 content_hash: sha256:aca156b02a3f0b9fddde3cefdb24370e17cc5886dcd78adcb382699a5cc0bbaf
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/contract.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a96f0ef021a6629120e5af7c98fa483d31de92cea37f98b51528a28dee38e16a
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/create.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e4a1b95970ec44d551a4b0598f2fe01463db13a6b118981d8cd03dfc7e24f451
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/references/deployment-modes.md value: .claude/skills/agent-author/references/deployment-modes.md
@@ -801,7 +901,34 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:6cd010455e10574566ebf7cfd0926217ae5812d56a62daf4bcdb325abf3b0421 content_hash: sha256:5675f8dcd1523269d5c65be5b0e06ff4d822b158050e2fdd72b54f605485ab1f
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/improve.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:f260e91f28bbd62093b53f4efc05821eff00d086f834ddb083b70dd77ddffcaa
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/plugin-scope.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a20f8aff55c9d1c1ba5e21054b81da80618270b3b6ca5bfc37ae3c2089b4b916
- kind: project-relative
target: claude
value: .claude/skills/agent-author/references/project-user-scope.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:3f686736259402e38fed29f215b7aa5a9529fc9025005f82d0c3d439958e4e03
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/references/scripts.md value: .claude/skills/agent-author/references/scripts.md
@@ -819,7 +946,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:56965f9b660fc9a32dd71ca1039b4c6b8f932420628ddfbf3a2525e7c3336ce4 content_hash: sha256:cac8baf85a6d958ed2f0f882446dc123d14082d5ca412c8edee12c6cd1b6fdc3
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agent-author/scripts/README.md value: .claude/skills/agent-author/scripts/README.md
@@ -837,7 +964,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e917055957500a72c7f684810552ba8931781c90f96dedaabc07e899dae02a89 content_hash: sha256:1c631f5178c6c0c397d7ceefb606892dd7e330cd1b22a03c1e4d11e85fbdb7de
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/agentsmd-audit value: .claude/skills/agentsmd-audit
@@ -1746,7 +1873,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/gitea - git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
content_hash: sha256:0346388f642641c56cef82ba1ee576a187d048eee66fab839a17417c81122cbc content_hash: sha256:31b6ad46379feee8ac7d837030f93ec04be20b7d11021b295dc6d27b4340a05b
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/gitea-prs/SKILL.md value: .claude/skills/gitea-prs/SKILL.md
@@ -1773,7 +1900,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/gitea - git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/gitea
content_hash: sha256:631874a7cddfcf678a2beffa5578fa7848bcef36be1251fa13fb0ccc543bcaf7 content_hash: sha256:d6cefd0cf270f8d844536311e67bfa45cd07f024aa0a649de1938af306ae7109
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/gitea-prs/references/reviews.md value: .claude/skills/gitea-prs/references/reviews.md
@@ -2241,7 +2368,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:9e3533c3c44cfd249cf02684ef43db822ed41382362e8ce71f1254d10711c8e0 content_hash: sha256:78bfcfb16bbeef814b83f37a4a5185886003f9442a6d0e7e94be56f54d18d7a5
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/SKILL.md value: .claude/skills/skill-audit/SKILL.md
@@ -2250,7 +2377,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:dbe2adfd0101cf9d6b3c2c3c2aa3ae397c717f835c1059c0f1d805e9057dc397 content_hash: sha256:57a9336d409c883dc9a78aa92a9f0075fac6f8e4aac6ee8fdab705055ef85162
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/assets/vale/.vale.ini value: .claude/skills/skill-audit/assets/vale/.vale.ini
@@ -2260,6 +2387,15 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f content_hash: sha256:0d1108b17a941b514dd9a62a7382d1febdd543118750246c81fba406440a9f9f
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/CompositionNote.yml
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:e0a52fb9ff65aee9d21d1f7b61bef0f71d14b8edd9af1d70246715bbb8844ccf
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/DescriptionOpener.yml
@@ -2268,7 +2404,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:a399516a457d40e0af5536a6575c70221909cecac5722eda2788430ebddd8f67 content_hash: sha256:60984e0af965137a151a07875f388c94ea2da93d4ee4f2b92811bd14105527f2
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml value: .claude/skills/skill-audit/assets/vale/styles/Kyberforge/PaddingPhrase.yml
@@ -2304,7 +2440,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:2295d2fc72fa529f3700c21fa93516ad186a7cc66d470370173ab1a784d03d31 content_hash: sha256:f8a27d7266f4453781712f0bead151580158581a445a641613203a67a1c337d7
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/references/description-quality.md value: .claude/skills/skill-audit/references/description-quality.md
@@ -2313,7 +2449,34 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:ab077e71bbc6e9d8e2a1384bedaf613a4219f28bbe42eb9e89f933b579db6b33 content_hash: sha256:2d37eccb4889cade6cbad0deaaed6d1f5fe4c3276c5438c244b2f87ae27bf432
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/file-structure.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:b24638bd639ef048da171f6dc711e345749cde3c70ec6ba1b7fcbd696b921841
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/formatting-and-scripts.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:5c319866b2f22ba07789dae7b0813132f67196c508e8da23971307c2a9e57095
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/patterns.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:4a942ab30b95dc0cbf0fbe7da3b91157f166bce80cbd17bcf60dc365ea9237af
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/references/sources.md value: .claude/skills/skill-audit/references/sources.md
@@ -2322,7 +2485,16 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:cb65dd3cc411d7b264fab24de5cd2353dec8fbb7bbcfe2388535d963be240280 content_hash: sha256:1db16ea23884ac2db799b42d1284daaab4b24eb94f184a95fb67ddc280385934
- kind: project-relative
target: claude
value: .claude/skills/skill-audit/references/validation-scripts.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:44f3b82413b57f2b5671637bb449a4c01b6d5fcd9059245aaa38e45108adf480
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-audit/scripts/vale-wrap.sh value: .claude/skills/skill-audit/scripts/vale-wrap.sh
@@ -2349,7 +2521,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:ebbef859276135b7fe4189b31396fd98e5d4019685d7cb55e39a10fac8ca546d content_hash: sha256:7ce27df82e4160c6296db6c8314865f022da5c4334151857570a86167c8d4e11
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author value: .claude/skills/skill-author
@@ -2367,7 +2539,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:6c0b36f9b28a33de1646df45bd8e4d733ab3b26c0bdff49743962aa068085f6d content_hash: sha256:d22035d302818e103486e447bd92d2da4c9b73da60f30157941710f32f400b89
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/SKILL.md value: .claude/skills/skill-author/SKILL.md
@@ -2376,7 +2548,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:7b82d16fe0d61a71c5b59a244cf92b9b5fc2635916ad1572f4f5f6e37172bf09 content_hash: sha256:615a936580f44dd8e523496aadf88df6d512ac58369190b90407e8fca86e8345
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/assets/templates/README.md value: .claude/skills/skill-author/assets/templates/README.md
@@ -2394,7 +2566,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:f05a127963874bfbbe4333c42c5208736d84d5bf12dd8478351f6853304cc9d1 content_hash: sha256:b20c65bd185b300de7e65d16decdf0ab4aaf6c094822c1f798b3c278d52abbff
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/assets/templates/assets/README.md value: .claude/skills/skill-author/assets/templates/assets/README.md
@@ -2412,7 +2584,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:63754636f84a7841f31ab1f2854025ee449a29840ed6b9b51bcb1422ab5522d0 content_hash: sha256:e2ef117972ab2625a456ed80ff085859666d145de4e270f383cde7c8e84ad60a
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/assets/templates/references/sources.md value: .claude/skills/skill-author/assets/templates/references/sources.md
@@ -2440,6 +2612,24 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442 content_hash: sha256:5d331de121105ca79b544b9d3779a316a64cee46fa8d51ba0ea789ab5c233442
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/contract.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:d350721118a2bd57094fa9151f11b48a663a1c8a04e50fba71ff2baf64b7282f
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/create.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:0837a77ad6da7ae9894134d15eebd57950b8505e8bd2b32ee69f281d65a6abcb
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/references/deployment-modes.md value: .claude/skills/skill-author/references/deployment-modes.md
@@ -2449,6 +2639,24 @@ deployments:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759 content_hash: sha256:ffe2d928f2b5ec90c509f4d4cc5bd33c71899852cb5cc5a31fe1513b707fb759
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/improve.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:abe029587ce475fed165d8fcfa46ea1abe83f90727d093f8121a9a7a7daa5a3d
- kind: project-relative
target: claude
value: .claude/skills/skill-author/references/retrofit.md
runtime: null
scope: project
owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:6c8336caa717f2abd38cb1f9c776479c0e908f7dbf577021d3689b375287dc77
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/references/scripts.md value: .claude/skills/skill-author/references/scripts.md
@@ -2466,7 +2674,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:27637acad4c0cdc7f1db15bc9cab339ebdac643e084642c58945ac2f81020c75 content_hash: sha256:652f7ce26c0d68a3ed11db09206bff20ba230ca8ff1fe71ae45b6f4505979327
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/skill-author/scripts/new-skill.sh value: .claude/skills/skill-author/scripts/new-skill.sh
@@ -2475,7 +2683,7 @@ deployments:
owners: owners:
- git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge - git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge active_owner: git.dev.rkdr.net/Defame1297/holocron/plugins/kyberforge
content_hash: sha256:46c6903404b9eabbd6c83892213fdabf9cad193be64613b8c1b84c8dc37e8eb2 content_hash: sha256:c788b56f73ed4fd03edb179159361fe16e3afbf528a9895e9251909c5aa40a7f
- kind: project-relative - kind: project-relative
target: claude target: claude
value: .claude/skills/tdd value: .claude/skills/tdd

24
apm.yml
View File

@@ -1,5 +1,5 @@
name: holocron name: holocron
version: 0.4.2 version: 0.5.0
description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows. description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
license: MIT license: MIT
@@ -42,7 +42,7 @@ dependencies:
# after a kyberforge release, check this first. # after a kyberforge release, check this first.
executables: executables:
allow: allow:
kyberforge#1.6.0: kyberforge#1.7.0:
hooks: true hooks: true
bin: true bin: true
@@ -52,7 +52,7 @@ marketplace:
# top-level apm.yml description:/version: above are NOT inherited into the # top-level apm.yml description:/version: above are NOT inherited into the
# compiled output despite being used elsewhere (e.g. by `apm audit`). # 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. description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
version: 0.4.2 version: 0.5.0
owner: owner:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net
@@ -79,31 +79,31 @@ marketplace:
- name: kyberforge - name: kyberforge
description: Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace. description: Skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace.
source: ./plugins/kyberforge source: ./plugins/kyberforge
version: 1.6.0 version: 1.7.0
category: Developer Tools category: Developer Tools
- name: bin - name: bin
description: A place for things to be binned description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
source: ./plugins/bin source: ./plugins/bin
version: 1.1.3 version: 1.2.0
category: Utilities category: Utilities
- name: git - name: git
description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow. description: Skills and agents for working with a local Git clone over the git wire protocol, and for authoring and running the pre-commit hooks that guard it.
source: ./plugins/git source: ./plugins/git
version: 1.3.3 version: 1.4.0
category: Version Control category: Version Control
- name: gitea - name: gitea
description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis. description: Skills and agents for working with a Gitea forge through its HTTP API — the forge's own objects, as distinct from the local git clone.
source: ./plugins/gitea source: ./plugins/gitea
version: 1.3.4 version: 1.4.0
category: Version Control category: Version Control
- name: core - name: core
description: Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it. description: Skills for authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it.
source: ./plugins/core source: ./plugins/core
version: 1.1.1 version: 1.2.0
category: Productivity category: Productivity
- name: mattpocock-skills - name: mattpocock-skills
@@ -115,5 +115,5 @@ marketplace:
- name: lint - name: lint
description: Skills and agents for configuring and running linters. description: Skills and agents for configuring and running linters.
source: ./plugins/lint source: ./plugins/lint
version: 1.1.6 version: 1.2.0
category: Developer Tools category: Developer Tools

2
docs/adr/0007-gitea-canonical-issue-tracker.md
View File

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

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

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

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

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

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

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

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

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

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

@@ -203,8 +203,14 @@ with no trigger list.
Verified end-to-end rather than assumed: `plugins/bin/.apm/skills/zoom-out/SKILL.md:4` carries the 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 flag, apm passes it through verbatim to both `.claude/skills/zoom-out/SKILL.md:4` and the flat mirror
at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` is the one installed skill absent from at `plugins/bin/skills/zoom-out/SKILL.md:4`, and `zoom-out` was — at the time of that check, when it
the model-visible skill listing in a live session. It remains invocable as `/zoom-out`. was the only carrier — the one installed skill absent from the model-visible skill listing in a live
session. It remains invocable as `/zoom-out`. `caveman` has since taken the flag as well, so the
corpus now has **two** carriers. Do not read a carrier list off this page; re-derive it:
```
grep -l '^disable-model-invocation: true' plugins/*/.apm/skills/*/SKILL.md
```
### Merging siblings ### Merging siblings
@@ -219,10 +225,13 @@ rather than the core job.
skills still exist separately, and this change made the split deeper rather than shallower: retrofit 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, 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 and their two same-named `references/description-quality.md` files now differ on 100 of ~120 lines
after normalising `skill`/`agent`, where before they were closer. The merge stays the decision; it after normalising `skill`/`agent`, where before they were closer. It has kept deepening since: the
reopens ADR-0008 (agent-audit's single-file invocation contract) and touches every call site in #99 retrofit added `finding-criteria.md` to `skill-audit`, drawing it level with `agent-audit`. Both
`skill-author`, `agent-author` and `forge`, which is why it is its own change and not a rider on figures move with the next retrofit, so measure rather than quote —
this one. Recorded here rather than dropped, so the gap between the rule and the tree is deliberate `ls plugins/kyberforge/.apm/skills/<name>/references/ | grep -c '\.md$'`. The merge stays the
decision; it reopens ADR-0008 (agent-audit's single-file invocation contract) and touches every call
site in `skill-author`, `agent-author` and `forge`, which is why it is its own change and not a rider
on this one. Recorded here rather than dropped, so the gap between the rule and the tree is deliberate
and dated instead of discovered later. and dated instead of discovered later.
### Enforcement and rollout ### Enforcement and rollout
@@ -233,11 +242,13 @@ which tier each rule is in, because the failure this ADR is most exposed to is a
| Check | Applies to | Tier | Home | | 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` | | 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 | | description present and non-empty (ERROR) | skills, agents | deterministic | same |
| boundary target resolves to a real skill or agent (ERROR when written as `/name` or `-> name`, or when its own sentence names another target that resolves; SUGGESTION otherwise) | skills, agents | deterministic | same | | boundary target resolves to a real skill or agent (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) | skills, agents | deterministic | same |
| boundary clause absent (SUGGESTION) | skills, agents | deterministic | same | | boundary clause absent — `absent` (SUGGESTION) † | skills, agents | deterministic | same |
| an arrow clause is present but no target can be read out of it — `unparsed` (SUGGESTION) † | skills, agents | deterministic | same |
| one arrow clause naming two or more targets, of which only the first is resolved (SUGGESTION, issue #107) † | skills, agents | deterministic | same |
| Gotchas entry count over five (SUGGESTION) | skills | deterministic | same | | Gotchas entry count over five (SUGGESTION) | skills | deterministic | same |
| Gotchas over 25% of the body (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 | | every `references/<file>.md` a body names exists (ERROR) | skills | deterministic | same |
@@ -254,6 +265,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 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. 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 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 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`, boundary sentence, and a single-word name is never matchable bare — `research`, `triage`, `forge`,
@@ -264,7 +290,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 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 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 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 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-` / 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 `milestones` fold. On the body-shape checks: a `## Gotchas` heading must *end* in "gotchas", not
@@ -296,6 +323,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 - `description-quality.md:45-50` has no FAIL condition for internal-mechanics content, which is why
`skill-author/SKILL.md:102` never bit. `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 ## Consequences
**Editing any non-compliant skill now requires retrofitting it first.** At decision time, 30 of 39 **Editing any non-compliant skill now requires retrofitting it first.** At decision time, 30 of 39
@@ -342,8 +409,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 — 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. routing degrades, the tier is the first thing to revisit.
**Four broken routing targets were found; two are fixed here and two are live.** Tracked as issue **Four broken routing targets were found; two were fixed here and two shortly after.** Tracked as
#100. issue #100.
- `skill-audit` routed to `/skill-improve` twice in its description plus `README.md:10`, and no such - `skill-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 skill exists — the real target is `skill-author`. **Fixed here**, as a side effect of retrofitting
@@ -353,14 +420,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 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 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. 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 - `gitea-issues` carries the literal string `gitea-labels- milestones` in its folded description, a
stray space introduced by YAML wrapping mid-token, breaking the skill name in preloaded text. stray space introduced by YAML wrapping mid-token, breaking the skill name in preloaded text. Was
**Live** — the check reports it as a dangling `gitea-labels`. **live**, reported as a dangling `gitea-labels`; **fixed under #99** — the name now folds intact.
So the check fires on 3 of the 4 against the base commit and on 2 at the tip of this change, and So the check fired on 3 of the 4 against the base commit and on 2 at the tip of the change that
`tests/test-skill-size-check.sh` probes exactly those three by name rather than asserting a count, so carried this ADR. **The corpus dangling set is now empty**, and that is asserted rather than
it degrades to SKIP as #100 lands rather than going stale. observed: `tests/test-adr0020-targets.sh` pins the set as empty, so a new boundary clause naming a
non-existent skill fails the suite instead of joining a backlog. `tests/test-skill-size-check.sh`
probed the three original names rather than asserting a count; as each was retrofitted its probe was
**removed, not skipped**, because a `pass "SKIP: …"` branch is an assertion-free result counted in
the totals and makes the suite look one test stronger than it is. That file's commentary survives the
probes and states the rule. Re-derive the current set — never read it off this page:
```
bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep 'does not resolve'
```
**Duplication between `skill-author` and `agent-author` survives un-gated.** The merge rule **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 deliberately excludes the author pair, so the commit-verification argument in four near-copies, the

227
docs/adr/0021-plugin-descriptions-state-a-domain-boundary.md Normal file
View File

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

27
docs/spec/architecture.md
View File

@@ -21,11 +21,26 @@ project repo (local overrides)
Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately — in this repo by `apm install` against the `dependencies.apm` entries in the root `apm.yml`, which lands them in `.claude/skills/` and `.claude/agents/` (ADR-0018); elsewhere by `claude plugin install <name>@holocron`. Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately — in this repo by `apm install` against the `dependencies.apm` entries in the root `apm.yml`, which lands them in `.claude/skills/` and `.claude/agents/` (ADR-0018); elsewhere by `claude plugin install <name>@holocron`.
`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication. `~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance) and carries nothing else — the content index of on-demand instruction files sits in `core/AGENTS.md`, deployed to `~/.agents/AGENTS.md` and imported by it. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
## Plugin model ## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source. Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently — via `apm install` here, or `claude plugin install <name>@holocron` for a host consuming the marketplace natively (ADR-0018). Self-contained is a hard constraint, not a description: a plugin is copied to a cache on install, so nothing inside it may reference a file outside its own directory. That is why the Vale styles are duplicated across two skills rather than shared (ADR-0014), and why ADR-0020's constants are copied into three validators rather than sourced from one. Each plugin is an **apm package**: `plugins/<name>/apm.yml` plus a hand-authored `plugins/<name>/.apm/{skills,agents,hooks,commands,instructions,extensions}/` tree (ADR-0015). There is no hand-maintained `plugin.json` — every manifest and every host-visible content directory is compiled from that source.
Which plugin a new skill belongs in follows from what each one is scoped to. The boundary that matters most in practice is `core` vs `kyberforge`: `core` is the home for cross-cutting, repo-agnostic utility skills that a consumer would want against *their* repo, while `kyberforge` is meta-tooling for the holocron marketplace itself. A skill that authors a target repo's `AGENTS.md` is `core`; a skill that audits a `SKILL.md` against this marketplace's contract is `kyberforge`.
The second boundary worth stating is `git` vs `gitea`, because both own things called branches and both touch pull requests: `git` is whatever works over the git wire protocol against a local clone, `gitea` is whatever goes through the forge's HTTP API. That is why `git-branches` and `gitea-branches` both exist and are not duplicates.
These are routing boundaries, not inventories — they answer "where does a new skill go", so they deliberately do not enumerate what each plugin ships today. The plugin's published `description` in its `apm.yml` states the same boundary for a consumer deciding whether to install (ADR-0021); neither carries an inventory. For what a plugin ships today, read `plugins/<name>/.apm/skills/` or the plugin list in `README.md`.
| Plugin | Scope |
|---|---|
| `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it |
| `git` | Git operations and git hook tooling — anything driven over the git wire protocol against a local clone, plus the pre-commit hooks that guard it |
| `gitea` | Anything reached through the Gitea HTTP API rather than the git wire protocol — the forge's own objects |
| `kyberforge` | Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling |
| `lint` | Configuring and running linters against a target repo; repo-agnostic, first linter is Vale |
| `bin` | Unsorted skills that have not earned a home yet |
Two compilers produce the plugin roots you see in the tree: Two compilers produce the plugin roots you see in the tree:
@@ -40,6 +55,8 @@ That immunity is positional, not by filename. Anything placed *inside* a mirrore
`core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins. `core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins.
Those on-demand files are plain markdown — no frontmatter, no schema. The agent decides when to read each one from task context and the content index label alone. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice; it is a deliberate deferral, not an oversight to close.
The governance layer has two phases: The governance layer has two phases:
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language. - **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`. - **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
@@ -57,10 +74,14 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
`CONTEXT.md` is therefore **not** always-loaded. `AGENTS.md` instructs agents to read it at session start, which is a behavioural instruction, not an `@import` guarantee — `LESSONS.md`'s 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change. `CONTEXT.md` is therefore **not** always-loaded. `AGENTS.md` instructs agents to read it at session start, which is a behavioural instruction, not an `@import` guarantee — `LESSONS.md`'s 2026-05-17 entry proposed adding the import and it was never applied. Treat that entry as open work rather than a record of a landed change.
## Reference conventions
The stated convention is that files referencing other files declare those references explicitly: the referencing file carries the forward reference (the content index in `core/AGENTS.md`, `references:` in frontmatter), the referenced file carries a `when:` field describing when it is loaded, and divergence between the two signals staleness. It is aspirational, not a description of the repo today — no file under `core/instructions/` carries frontmatter at all, `when:` appears in exactly one of the 39 `SKILL.md` sources under `plugins/*/.apm/skills/`, and the reference scanner script meant to derive the reverse map ("what files reference this file?") does not exist; `docs/notes/skill-implementation-workflow.md` still lists it as unbuilt work. Treat it as intent for instruction files, skills, and workflow documents, not as a rule the repo enforces.
## Provider model ## Provider model
`core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change. `core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
## Architectural decisions ## Architectural decisions
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds 19 numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that `.claude/settings.json`'s committed content is exactly `{"hooks": {}}`) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots). Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds numbered ADRs whose filenames state their decision, so `ls docs/adr/` is the index. Read a superseding ADR before the one it supersedes: ADR-0015 (apm as the authoring source of truth) supersedes ADR-0001 and moots ADR-0006, ADR-0017 corrects ADR-0015's host-discovery gap, and ADR-0019 supersedes one claim in ADR-0018 (that `.claude/settings.json`'s committed content is exactly `{"hooks": {}}`) while keeping the rule behind it. Entry points for the structure described on this page: ADR-0002 (two-tier CLAUDE.md), ADR-0003 (AGENTS.md as the provider-agnostic entry point), ADR-0015 and ADR-0017 (the two compilers behind the plugin roots).

899
docs/spec/gates.md Normal file
View File

@@ -0,0 +1,899 @@
# Enforcement gates
Reference for this repo's pre-commit and pre-push hooks: what each one guards, what its numbers
mean, and which shapes were tried and rejected. Read it when a gate fails, before changing anything
in `.pre-commit-config.yaml`, or before "fixing" something that looks like an inconsistency — several
of the oddities documented here are load-bearing and have already been re-litigated once.
`AGENTS.md` carries only the operative rules an agent needs in the moment. The reasoning lives here.
---
## Running the gates
| Command | Scope |
|---|---|
| `pre-commit run --all-files` | the commit-stage hooks |
| `pre-commit run --hook-stage pre-push --all-files` | the push gate, one command — with one caveat below |
| `pre-commit run skill-size-check --all-files` | just the ADR-0020 size/context gates |
Install hooks via `pc-run`, wiring **all three stages**. This repo's `.pre-commit-config.yaml` has no
`default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits)
and `pre-push` (everything below).
The pre-push command reports **16** hooks, not 14. 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
is the count of hooks this repo authors itself.
**The caveat: one of those 14 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
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.
**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)) |
`check-executables-allow-sync` is the odd one in this group: it guards a *silent failure* rather than
drift in generated text.
**Artifact validators**
| Hook | Guards |
|---|---|
| `check-apm-agents-valid` | runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md` (see [Agent files](#agent-files-take-the-description-gates-not-the-body-gate)) |
**apm's own gates**
| 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)
| Hook | Guards |
|---|---|
| `validate-plugins` | `claude plugin validate --strict` on every plugin directory |
| `validate-marketplace` | `claude plugin validate --strict` on the root marketplace manifest |
**Release**
| Hook | Guards |
|---|---|
| `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`).
## 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`. It is also shipped to external repos as
`kyberforge-skill-size-check` (see
[External consumers](#external-consumers-the-root-pre-commit-hooksyaml)).
**Two things fall outside that scope, both deliberately.** The `[^/]+/SKILL\.md$` tail admits only a
`SKILL.md` sitting directly in a skill directory under `.apm/skills/`:
- the `plugins/kyberforge/docs/research/examples/` reference skills, which are vendored upstream
corpus and not this repo's to gate;
- `plugins/kyberforge/.apm/skills/skill-author/assets/templates/SKILL.md` — inside `.apm/skills/`,
but two directories deeper. It is the `FILL IN:` scaffold `skill-author` copies, so its
`description: >` is a comment block rather than a description and every ADR-0020 measurement over
it would be meaningless. A reader adjusting the pattern needs to know it is there.
Everything else it matches exactly, with nothing over- or under-caught. Re-derive both halves:
```
git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$' # the real skills
git ls-files | grep -E '^plugins/[^/]+/\.apm/skills/.*SKILL\.md$' \
| grep -vE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$' # the scaffold only
```
The first count equals the number of skill directories (`ls -d plugins/*/.apm/skills/*/ | wc -l`);
the second returns exactly the template. The remaining unmatched `SKILL.md` files in the tree are the
generated flat mirror, which is excluded by the `.apm/` segment on purpose — a mirror edit is drift,
not an authoring change.
### `skill-frontmatter`, the other hook on that scope
A second `repo: local` pre-commit hook, `skill-frontmatter`, runs on the **same** `files:` pattern at
the same stage. It is a short shell loop: for each file, `grep -q "^name:"` and
`grep -q "^description:"`, failing with "missing required frontmatter fields" if either is absent.
**It overlaps ADR-0020's "description present and non-empty" FAIL, and the overlap is not clean.**
The ADR (`:95-101`) requires that question be decided on the **YAML-folded value** and nowhere else,
precisely because a line regex gets it wrong in both directions. Measured on fixtures:
| Frontmatter | `skill-frontmatter` | `skill-size-check` |
|---|---|---|
| `description:` with no value, then `model: sonnet` | passes — the key is on a line | ERROR, "missing or empty" |
| `"description": …` (quoted key, valid YAML) | **fails** — `^description:` does not match | passes, description read normally |
So the grep is not a second opinion on presence. It is blind to the shape ADR-0020 was written
against, and it is the only one of the two that objects to a quoted key. Neither disagreement is
currently live in the corpus, and the honest reading is that presence is `skill-size-check`'s
question — the grep's contribution to it is noise on one shape and silence on the other.
What the grep does add is the `name:` key, which **no** ADR-0020 check reads: a `SKILL.md` with no
`name:` passes `skill-size-check` at exit 0. That is its real and only unique coverage, and the
reason not to fold it into the size gate on the grounds of redundancy.
### Two independent gate families, neither replaced the other
**Family 1 — agentskills.io spec backstop** (unchanged, conformance not quality):
| Constant | Value | Measured over |
|---|---|---|
| `MAX_LINES` | 500 | whole file, **frontmatter included** |
| `MAX_WORDS` | 2,770 | whole file, **frontmatter included** |
**Family 2 — ADR-0020 context budget** (measured differently, on purpose):
| Check | SUGGESTION | FAIL | Measured over |
|---|---|---|---|
| `description` characters | 250 | 400 | the YAML-**folded** value |
| body words | 600 | 900 | **body only** — everything after the frontmatter's closing `---` |
Plus two hard FAILs with no suggestion tier:
- **A missing, valueless or `null` `description:`.** Not a skip. The description is the one field
preloaded into every session, so a gate that declines to measure it reports green. (This is not
hypothetical: `description:` with no value followed by `model: sonnet` let a line regex capture the
*next* key, which looked non-empty, so the "missing or empty" branch never fired and every gate
below early-returned on the genuinely empty folded value — exit 0, zero output, on a blocking gate.)
- **Every `references/<file>.md` a body names must exist** on disk. A dispatch table pointing at a
file that was never written is a silently dead branch, and nothing else in the gate/audit/vale
stack notices it.
A file can sit well inside one family and fail the other. 2,770 whole-file words is a conformance
backstop; 900 body-only words is a quality gate. Conflating them is what produced the current state.
### An unresolved routing target is not automatically a FAIL
A boundary-clause target that resolves to no skill or agent has **three** possible verdicts, not one
(`unresolved_targets()` in `scripts/skill-size-check.sh`):
| Verdict | When |
|---|---|
| **SUGGESTION** — the default | the target does not resolve and neither promotion condition below holds |
| **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
tool, a file format or an English compound as a route: "pre-commit hooks" is prose about a tool and
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.
**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
gets promoted.
### Target resolution walk
Resolution walks up **from the file being checked** — never from the script's own location. Deriving
it from `${BASH_SOURCE}` leaked holocron's 39-skill universe into every consumer repo running the
hook through pre-commit, so a consumer skill routing to `skill-audit` resolved against a plugin it
had never installed.
The walk finds an **authoring root**: the nearest ancestor holding `plugins/*/.apm/skills` or
`plugins/*/.apm/agents`, falling back to the nearest ancestor holding `.git`. **Two passes, not one
interleaved walk**, so a nested `.git` (a submodule, a sub-package worktree) cannot beat a real
monorepo root further up.
The universe is then:
1. every skill and agent under `<root>/plugins/*/` — sibling plugins resolve, which is what a
monorepo means;
2. the checked file's own apm package;
3. the packages that package declares in **its own** `apm.yml` `dependencies.apm`.
The **root** manifest's `dependencies:` block is not read, and no plugin here declares a cross-plugin
apm dependency — none needs to.
Deployed `.claude/` / `.agents/` trees are consulted **only** when the walk found no plugin monorepo
root, whether it landed on a bare `.git` ancestor or on nothing at all. That is the consumer case.
**The gate keys on which of the two passes matched, never on whether the root contributed a new
name.** A name-count delta looks equivalent and is not: `_collect_authoring_root()` re-collects the
checked file's own plugin, whose names the earlier steps already added, so a single-plugin monorepo
shows a delta of zero and would wrongly reach for the deployed trees — including the user's global
`~/.claude/skills`, making the verdict depend on what happens to be installed.
Why it matters: those trees are gitignored `apm install` output, present only on a machine that has
run it. Four cross-plugin targets here (`gitea-branches` → `git-branches`, `gitea-branches` →
`git-history`, `gitea-issues` → `git-branches`, `gitea-workflow` → `git-workflow`) once resolved
through `.claude/skills/` alone, so **the same commit measured 2 dangling targets on a developer
machine and 6 on a fresh clone**. A gate shipping hot with no baseline cannot give two answers.
Verified fixed: running the hook over a tree holding only `plugins/` and the root `apm.yml`, 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
— are the pre-retrofit corpus as it stood when the experiment was run, kept here as the evidence for
the install-independence claim. They are not current: the retrofit under #99 took the first three to
zero. What the experiment establishes is that the two trees agree, not what either measured.
### Boundary-clause detection: three outcomes, not two
`boundary_clause_status()` returns one of three values, and the two findings get separate messages:
| Status | When | Reported as |
|---|---|---|
| `present` | a prose marker (`do not`, `instead`, `rather than`, `not for`) or an arrow clause was found | nothing |
| `absent` | neither was found | SUGGESTION: add a boundary clause, in either form |
| `unparsed` | an arrow clause was found and **no target could be read out of it** | SUGGESTION: the clause is present — this is a *parse* failure, not a missing clause |
The third had to be split out. Collapsing it into `absent` is a **wrong** finding, not a strict one:
it sends the author to add a clause that is already there. Three of them instead reworded a correct
clause until the regex accepted it, one stripping the very filename that discriminates the skill
from its neighbour (**#110**).
`unparsed` is narrow and certain on purpose. It fires only on the arrow form, which *always* names a
target, so zero targets means the name is written in a shape the extractor cannot see — in practice
a bare single-word target, per the known gap above, and the message says to write it `` `name` `` or
`/name`. A **prose** clause yielding no target is not reported at all: "Do not use for anything else"
is a complete and legitimate boundary clause that names nowhere to go.
**One arrow, one target.** An arrow clause naming two or more targets draws its own SUGGESTION,
quoting both names and asking for a split, because only the first is ever resolved: the conjunction
continuation (`CONT_MARKED` / `CONT_ANY`) is wired to the prose route verbs and never to arrows. So
`Not X -> a or b` resolved `a`, left `b` resolved by nothing and reported by nothing, and then let
the audit print "1 of 1 boundary target(s) resolve" on a clause naming two — a gate under-reporting
its own coverage, which is the one failure mode ADR-0020 says a gate must not have (**#107**). The
clause is **rejected rather than the arrow scan extended**: extending it would widen the resolver's
deliberately conservative false-positive tuning across every arrow in the corpus, where splitting
costs the author one full stop. The convention is one arrow per target — `Not X -> a. Not Y -> b.` —
already what every retrofitted `gitea-*` skill does in practice, now stated in
`skill-author`'s `references/contract.md` instead of being folklore.
**Dotted filenames in a boundary clause now parse.** `CLAUSE_BODY` — what may sit between `Not` and
the arrow — used to be `[^.;]`, a class that cannot cross a `.`, so every clause naming a dotted
filename between the two (`AGENTS.md`, `.vale.ini`, `.pre-commit-config.yaml`) was invisible to both
`BOUNDARY_ARROW` and `ARROW_BOUNDARY`. The two resulting failures were different sizes (**#110**):
- with a **backticked** target the clause was *misdiagnosed*. The backtick sweep still extracted the
target, so the route was checked, but the gate reported "no boundary clause" on a clause that was
present and working. That is the misdiagnosis the three rewordings above came from.
- with a **bare** target the clause was *unchecked*. `ARROW_BOUNDARY` is the only extractor for a
bare arrow target, so `Not AGENTS.md -> no-such-skill` produced no target, no dangling report and
no missing-clause SUGGESTION. Silence, not noise — the worse of the two.
`CLAUSE_BODY` is now `(?:[^.;]|\.(?=\S))`: a dot inside a filename is followed by a non-space, a
sentence-ending dot by whitespace or end of string, so the class crosses `AGENTS.md` and still stops
at a real sentence end. **Read the second bullet forward as well as back:** a bare target sitting
after a dotted filename is now extracted, resolved, and a blocking ERROR when it dangles, where the
same clause used to pass unchecked in silence.
### SUGGESTION-only checks
Deterministic to measure, judgment to act on:
- 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
all for a passing hook, and a SUGGESTION deliberately does not fail — without verbose every
suggestion is swallowed, which is exactly the invisibility ADR-0013 records for Vale warnings.
ADR-0020's preload arithmetic depends on it: writing to the 400-char FAIL delivers roughly half the
cut that writing to the 250-char SUGGESTION does, so the intended saving depends entirely on that
tier being visible. The numbers, and the measurement method behind them, are not restated here —
they live in ADR-0020's Consequences section, under "A ceiling does not produce an average", whose
figures are pinned to the base commit the decision was taken on (`f9b919d`). Quoting them here would
just create a second copy to go stale. It costs nothing on a clean file — the script prints only
findings.
### Duplicated constants
`skill-audit`'s `validate.sh` holds a second copy of the four ADR-0020 constants
(`DESC_SUGGEST_CHARS` / `DESC_MAX_CHARS` / `BODY_SUGGEST_WORDS` / `BODY_MAX_WORDS`), and
`agent-audit`'s `validate.sh` holds a third copy of the two description constants. They are copied
rather than imported because a cache-installed plugin's scripts cannot read files outside their own
plugin directory. `tests/test-skill-size-check.sh` asserts the copies agree, so drift fails CI rather
than silently letting an audit bless a skill the commit hook then rejects. The shared boundary
resolver block is embedded verbatim in all three scripts between `BEGIN`/`END ADR-0020 SHARED
BOUNDARY RESOLVER` markers and must stay byte-identical.
### `python3` and PyYAML are hard requirements
Both, and neither is a best-effort accelerator.
`python3` because the script measures the **folded** `description` value. Most descriptions here are
`>`-block scalars, so a regex over the raw lines measures indentation and newlines instead of the
value. Missing it fails the hook with an install pointer rather than skipping the ADR-0020 checks,
which would be a vacuous green. In practice it is already present — pre-commit is itself a Python
application.
**PyYAML** because the hand-rolled fallback frontmatter reader has been **removed deliberately**. It
disagreed with a real parser across the FAIL boundary — one corpus description measured 270
characters parsed and 412 unparsed — and a quoted `"description"` key or an explicit
`description: null` returned empty from it, silently skipping the description *and* routing checks. A
reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured,
which is the exact vacuous-green failure the `python3` check exists to avoid. `pip install pyyaml`
(or `python3 -m pip install PyYAML`, or the distro's `python3-yaml`) if the hook reports it missing.
## Agent files take the description gates, not the body gate
`check-apm-agents-valid` runs agent-audit's `validate.sh` over every real
`plugins/*/.apm/agents/*.agent.md`. It derives its expected file set from `git ls-files` — the pattern
`tests/run-bats.sh` established — so an agent file deleted from the worktree but still tracked fails
the run, and **discovering zero agent files is an error, not a pass**. An untracked *new* agent file
is still validated: the derivation is one-directional on purpose, so uncommitted work is not blocked
but also cannot bypass the gate.
The hook exists because `validate.sh` was previously exercised only by `check-scope-walkup-sync`,
against synthetic `mktemp` fixtures — it had never run against the agent files it governs. That is
how ADR-0016 could be amended to bless a `disallowedTools` frontmatter field while `validate.sh`'s
allowlist still rejected it: spec and enforcer disagreed and every gate stayed green.
Agents take the ADR-0020 **description** gates (agent-audit's `validate.sh` holds its own copy of
those two constants) and, deliberately, **no body word gate**. A skill body is loaded into the
caller's context and competes with the live conversation; an agent body becomes the system prompt of
a *fresh* context. The rationale for the 900-word FAIL does not transfer. A bats test pins that
absence in agent-audit's validator — adding a body gate there contradicts the ADR rather than fixing
an inconsistency.
**Be precise about the scope of that guarantee: it holds for the *validator*, not for the shared
script.** `scripts/skill-size-check.sh` applies its body gate to whatever path it is handed, and
```
bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md
```
exits 1 today with 900-word body FAILs on `git-orchestrate` 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 corpus is now clean on both gates.** Issue **#99** retrofitted all 39 skills plugin by plugin;
`kyberforge` was the last wave, after which the corpus was swept as a whole rather than per plugin.
Each sweep is followed by an **independent review round**: a fresh agent with no memory of the
retrofit re-measures the corpus and files what it finds, and the round repeats until one lands no
findings. The rounds are recorded as comments on **#99** — read the current state off that thread,
which is why no round count is pinned here.
| Gate | Current findings |
|---|---|
| `skill-size-check` | **0 of 39** descriptions and **0 of 39** bodies exceed their FAIL tier; 0 dangling targets; SUGGESTIONs outstanding (count not pinned — see below) |
| `Kyberforge.CompositionNote` (Vale) | **0 errors** — the four `gitea-*` carriers were all retrofitted |
**The SUGGESTION count is deliberately not recorded here.** It moves with every skill edit *and*
with every change to the gate's own tiering, so any figure written down is stale by the next commit.
Measure it instead:
```
bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep -c '^SUGGESTION'
pre-commit run skill-size-check --all-files # same findings, via the hook
```
A non-zero count is the expected steady state, not a regression. SUGGESTIONs exit 0 and block
nothing; only the two FAIL tiers, the dangling-target ERROR and the missing-`references/` ERROR do.
Read the count as a work queue, and the FAIL columns above as the gate.
`Kyberforge.CompositionNote` is the ADR-0020 Vale rule banning composition and architecture prose
from a description. Every Vale rule here is `level: error` with no ignorable tier, so a description
that reintroduces one blocks the commit even though no skill carries one today.
Because nothing is grandfathered, the gates now bite on **first commit**: a new skill, or an edit
that pushes a description past 400 characters or a body past 900 words, is blocked until it
complies. That is the steady state the retrofit was for — it is no longer true that an unrelated
one-line fix to a skill requires retrofitting that skill first.
Check where a skill stands before starting, and check **both** gates:
```
pre-commit run skill-size-check --all-files # size/context only
pre-commit run --all-files # size AND Vale
```
Scoping a retrofit off `skill-size-check` output alone leaves you blocked at the second gate.
## Vale
Install the `vale` binary — `brew install vale` (macOS), `snap install vale` (Linux),
`choco install vale` (Windows), or see <https://vale.sh/docs/vale-cli/installation/>. No `vale sync`
is needed: the `Kyberforge` styles are **committed** under
`plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded
packages (ADR-0014).
### Two copies, one canonical
Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension
(motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it does not live
in `plugins/lint/` — and per ADR-0014 it no longer lives at the repo root either. It lives **twice**,
one copy per skill, both under `plugins/kyberforge/.apm/skills/`:
| Copy | Styles | `.vale.ini` sections |
|---|---|---|
| `agent-audit/assets/vale/` — **canonical** | `Kyberforge`, `KyberforgeCopilot` | `[**/agents/*.md]`, `[**/*.agent.md]` |
| `skill-audit/assets/vale/` — smaller duplicate | `Kyberforge` | `[**/SKILL.md]` |
Duplicated rather than shared because a plugin's cache-install copies only each skill's own files —
there is no cross-skill sharing to point at. `check-vale-style-sync` at pre-push is what keeps them
from drifting; `KyberforgeCopilot` is the one deliberate inequality, being scoped only to `.agent.md`
files for the Copilot-only "`Use proactively` has no effect" check.
### What Vale owns, and what stays LLM judgment
Eleven rule files across the two copies, six distinct rules:
| Rule | Vale scope | Bans | From |
|---|---|---|---|
| `Kyberforge.DescriptionOpener` | `text.frontmatter.description` | non-imperative openers ("This skill/agent…") | issue #84 |
| `Kyberforge.VagueWording` | `text.frontmatter.description` | vague capability wording ("helps with", "utilize", …) | issue #84 |
| `Kyberforge.PaddingPhrase` | `text` | generic "see `references/` for details" padding | issue #84 |
| `KyberforgeCopilot.ProactivePhrase` | `text.frontmatter.description` | `Use proactively` (no effect in Copilot) | issue #84 |
| `Kyberforge.SentenceOpenerThereIs` | `sentence` | "There is/are" sentence openers | ADR-0013 |
| `Kyberforge.CompositionNote` | `text.frontmatter.description` | architecture and composition prose in a description | ADR-0020 |
Vale covers the **pattern-matchable** sub-checks named in issue #84 plus, per ADR-0013, one
cherry-picked body-wide prose-pattern rule. Everything else stays LLM judgment: defaults-vs-menus,
why-rationale, the non-pattern-matchable body-discipline calls, near-miss exclusion strength, and
control calibration. New rules land directly in `styles/Kyberforge` and block immediately — there is
no trial tier.
The cherry-pick record, so it is not re-litigated:
- `Kyberforge.SentenceOpenerThereIs` **landed** — 22 held-out hits, both in-corpus hits clean
rewrites, zero suppressions needed.
- `Kyberforge.VagueQualifier` was cherry-picked and then **deleted**. 2 hits across the corpus as it
stood on 2026-08-08 (before the `.apm/` restructure): one marginal, and one unfixable false
positive — `caveman/SKILL.md` quotes `of course` as an example of filler, a mention rather than a
use — which forced the repo's only Vale suppression comments.
- `governance.md` and `CONTROLS.md` were evaluated as rule sources and **excluded**: nothing
prose-pattern-matchable to mine.
### Why every rule is `level: error`
Every alert is a FAIL, with no ignorable tier — same all-or-nothing model as shellcheck, the test
suite, and conventional-pre-commit. Graded severities do not work here: **Vale's exit code keys on
`error` alerts alone**, so a `warning` or `suggestion` rule exits 0, and pre-commit swallows a
passing hook's output. Such a rule would be invisible and would block nothing.
`MinAlertLevel` and `--minAlertLevel` are correspondingly **absent** from both `.vale.ini` files and
from the hook definitions. Under this model they are no-ops; adding one is not a missing knob.
The `verbose: true` escape hatch that makes `skill-size-check`'s SUGGESTION tier audible has no
analogue here — Vale has no tier to make audible.
### External consumers: the root `.pre-commit-hooks.yaml`
The root `.pre-commit-hooks.yaml` exposes both Vale copies (`kyberforge-vale-audit-skill`,
`kyberforge-vale-audit-agent`) plus `kyberforge-skill-size-check`, so any external repo can enforce
the same rules with `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml`.
pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the
`kyberforge` plugin is installed at all; the same mechanism covers CI via `pre-commit run
--all-files`. `skill-size-check` has no external asset dependency, so it needed no relocation under
ADR-0014 — only exposure.
This repo's own `vale-audit-prefilter-skill` / `-agent` hooks consume the **identical**
plugin-bundled copies via `repo: local`. Deliberately not a third root copy, and deliberately **not a
pinned self-reference** — a pinned self-reference would lint working-tree edits against the last
tagged release rather than against the change being made.
### Pre-commit
Two prefilter hooks, with `.apm/`-scoped `files:` patterns:
| Hook | Pattern |
|---|---|
| `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.
**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
shape (see [A 0-file Vale run is NOT RUN](#a-0-file-vale-run-is-not-run)).
### The `.vale.ini` globs do no scoping
Each `.vale.ini`'s section globs are **path-agnostic** — `[**/SKILL.md]` for skill-audit's copy,
`[**/agents/*.md]` and `[**/*.agent.md]` for agent-audit's — and constrain filename *shape*, not
location: Vale's `*` crosses `/`. A `SKILL.md` outside `plugins/` (a project-scope
`.claude/skills/foo/SKILL.md`, say) still matches `[**/SKILL.md]` and gets linted normally.
All scoping therefore comes from the pre-commit hook's own `files:` regex and from the audit skills
passing one explicit file per invocation. The two manifests scope **differently on purpose**:
| Manifest | `-skill` | `-agent` |
|---|---|---|
| `.pre-commit-config.yaml` (pins this repo's layout) | `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` | `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` |
| `.pre-commit-hooks.yaml` (layout-agnostic for consumers) | `(^\|/)SKILL\.md$` | `(^\|/)agents/[^/]+\.md$\|\.agent\.md$` |
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**
`scripts/vale-wrap.sh`, not `vale`. It works around a confirmed **Vale 3.15.2** limitation:
`text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions.
Verified by reproduction on a deliberately-bad fixture, not assumed:
| Description scalar spanning 2+ lines | Vale's behaviour |
|---|---|
| `>` folded block | 0 alerts, exit 0 — **broken** |
| plain (unquoted) continuation lines | 0 alerts, exit 0 — **broken** |
| single- or double-quoted, wrapped | 0 alerts, exit 0 — **broken** |
| `\|` literal block | alerts fire, exit 1 — lints normally |
The wrapper flattens the three broken forms to a single-line scalar in a scratch copy — or, for the
rare value no inline scalar can spell verbatim, a `|-` block with one content line — padding with
blank lines so **every other line number is unchanged**. `|` literal blocks and single-line
descriptions pass through untouched. Most descriptions in this repo are `>` blocks, so before the
wrapper a bad description in any of the three broken forms sailed straight through the prefilter.
### The `--config` argv defect
Handed **no `--config` at all**, the wrapper falls back to its own sibling `assets/vale/.vale.ini`,
located from `${BASH_SOURCE[0]}` rather than from the cwd. That is why both manifests' `entry:` is
now the bare script path with **no argument after it**.
pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]),
*cmd[1:])`), so every later argument resolves against the **consuming** repo's root. A `--config` in
`.pre-commit-hooks.yaml` therefore pointed at a path no consumer has and hard-failed every external
run with `E100 [--config] Runtime error`.
`.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical.
The local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was*
this repo — and that divergence is why three review rounds exercised a path no external consumer
takes and missed the defect. **Do not reintroduce a `--config` to either manifest to make the local
run "explicit".**
An explicit `--config` from any other caller still wins, in all three argv forms (`--config X`,
`--config=/abs`, `--config=rel`), and a relative one resolves against the caller's cwd — matching
bare `vale`, not the repo root.
Both audit skills' Step 1 passes no `--config` either. Step 1 resolves the script relative to the
skill's own directory so the call works from an installed plugin cache; a relative `--config`
alongside it would resolve against the cwd instead, yielding `E100 Runtime error … does not exist`
and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to
full LLM judgment.
`tests/test-vale-wrap.sh` regression-tests this against **skill-audit's** copy specifically: its
fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` carries that glob section.
### A 0-file Vale run is NOT RUN
Vale reports 0 files only when the path it is handed matches **no glob section at all** — a
differently-named file, or a directory argument holding nothing that matches. That run prints
```
✔ 0 errors ... in 0 files.
```
and exits 0, indistinguishable from a clean pass. Both audits therefore treat a 0-file Vale run as
**NOT RUN** and fall back to full LLM judgment rather than reporting the Description dimension
clean.
### Pre-push
`vale` is a **pre-push** dependency too, not only pre-commit. `check-vale-style-sync` runs **six
glob-coverage probes** by invoking `vale --config` — one representative path per file shape the
prefilter is supposed to cover. They are the only assertions in the script that catch a `.vale.ini`
glob typo (`[**/SKILL.md]` → `[**/SKILLS.md]`), the failure mode where every text-level check stays
clean while vale lints zero files. As a warning this self-disabled on exactly that mutation and
exited 0, and since pre-commit swallows a passing hook's output the stderr line was never seen — the
hook reported `Passed`. Missing `vale` is therefore a hard failure here.
The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and **it is not `SKIP=`**: the hook
still runs and still asserts everything verifiable from file text, but the six probes do not, and its
summary says so explicitly —
```
Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified.
```
Use it only on a machine that genuinely cannot install `vale`, and read that line as "the glob axis
was not checked", not as a pass. The hook is `verbose: true` for exactly that reason — its clean
output is a single line, so it costs one line per push.
### Mentioning banned phrasing without tripping the rule
House convention: banned phrasing that must be **mentioned** rather than used goes in backticks or a
fenced code block. Vale skips code spans and fences, so no suppression is needed — which is why this
document quotes `Use proactively` and "There is/are" the way it does.
Inline `<!-- vale Rule = NO -->` is the fallback **only** where backticking is impossible. Use the
HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown. The one time a rule forced
suppression comments, the rule was deleted instead (see the `VagueQualifier` entry above).
## Tests
```
bash tests/run-tests.sh # every test-*.sh plus the bats suite
bash tests/run-tests.sh --bats-only # just bats
```
First run auto-initializes the bats submodules; no manual `git submodule update` needed.
**Exit 77 = SKIPPED.** A suite that skips because a dependency is missing does **not** fail an ad-hoc
run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent),
where a skip **does** fail the push: at pre-push a skip means one of the documented dependencies is
absent on this machine, so the gate would otherwise report success having run fewer suites than it
appears to. Without `--strict` the gate once went green having verified 15 of 17 suites on a
vale-less PATH, with the skip list swallowed. Without vale, three suites skip —
`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh` — and the strict
failure names each one and what to install.
`tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats`
file deleted from the worktree but still tracked in the index fails the run rather than silently
shrinking the suite. Remove one with `git rm` (or stage the deletion) when intentional; an untracked
new `.bats` file is picked up and needs no ceremony.
Both discovery walks (`tests/run-bats.sh` and `tests/run-tests.sh`) exclude `apm_modules/`:
`apm install` materializes a full copy of every plugin there, and running a dependency's copy of a
`.bats` file breaks its relative path to the bats helpers — **167 spurious failures** before the
exclusion landed.
## apm gates
### `apm-audit-ci`
Runs `apm audit --ci` **once per manifest** — the root one and each of the six plugin packages —
because the root-only invocation audits the marketplace manifest and **nothing else**, and
`apm-pack-check-clean` does not parse plugin `dependencies:` blocks either. Verified: a malformed
dependency entry passes `apm pack --check-versions --check-clean --dry-run` and fails
`apm audit --ci` in that package's directory. Costs ~0.5s per package.
It verifies **exactly two things** per manifest and claims no more:
- **manifest-parse** — each `apm.yml` parses as a valid APM manifest. Unconditional; verified to fire
on a dependency entry missing its `git`/`path`/`registry` field (`Cannot parse apm.yml`).
- **lockfile-exists** — any package declaring dependencies has a consistent `apm.lock.yaml`.
Conditional, and vacuous while every plugin `apm.yml` declares `dependencies: {apm: [], mcp: []}`;
it arms itself the moment one does not (verified by adding a git dependency to
`plugins/lint/apm.yml`).
It does **not** enforce an org policy. apm discovers one from the git remote and only understands
github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints:
```
No org policy found at unknown; enforcement skipped
```
**Do not "fix" that with `policy.fetch_failure_default: block` in `apm.yml`.** apm's own message
suggests it; it was tried on a scratch copy and **rejected**. With no reachable policy source it does
not make the check meaningful, it makes it permanently red — `apm audit --ci` exits 1 with
`No org policy found at unknown (policy.fetch_failure_default=block)` on every push, forever. A gate
that can never go green is not a gate. Revisit only if this repo gains a policy source apm can reach.
It also does not scan for hidden Unicode: that scan is plain `apm audit`, a different mode (`--ci`
refuses to combine with `--file`/`--strip`/`--dry-run`/`PACKAGE`), and plain `apm audit` here reports
`No apm.lock.yaml found -- nothing to scan` and exits 0. Adding it would buy a second vacuous check.
### `check-executables-allow-sync`
apm gates a package's `hooks/` and `bin/` on an **exact `<package>#<version>` dictionary lookup** in
root `apm.yml`'s `executables.allow` (`apm_cli/security/executables.py`, `is_package_approved`).
There is no wildcard and no version-less form.
So bumping `plugins/kyberforge/apm.yml`'s `version:` without bumping the key **errors nowhere**: the
entry simply stops matching, the gate blocks the hook, kyberforge's `SessionStart` hook stops
deploying, and the apm install goes quietly stale — the exact failure ADR-0019 exists to end,
reintroduced through the mechanism meant to secure it. ADR-0019 records this as a live failure mode;
the release that shipped the hook hit it immediately.
`scripts/check-executables-allow-sync.sh` parses `version:` out of `plugins/kyberforge/apm.yml` and
asserts root `apm.yml` carries the matching `kyberforge#<version>` key. A comment in the
`executables:` block stays as the human-facing pointer; the hook is what actually holds. It parses
with PyYAML where importable and falls back to a two-shape scan otherwise, so a missing pip package
cannot become the thing that blocks every push.
## `.claude/settings.json`
**apm owns this file. Nothing repo-authored goes in it.**
`apm audit --ci` replays the install into a scratch tree and diffs the result byte-for-byte, so
anything apm would not have written there — an `enabledPlugins` block, a real `hooks` entry — is
permanent drift that fails `apm-audit-ci`. A hook you want in this repo is authored in
`plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written here.
Its committed content is whatever apm last wrote, which today is the merged `SessionStart` entry for
kyberforge's `check-apm-current.sh`. That is apm's own output and it belongs in the commit (ADR-0019;
ADR-0018's statement that the committed content is exactly `{"hooks": {}}` is superseded on that
point only). Machine-specific settings go in the gitignored `.claude/settings.local.json`, which apm
does not deploy and the replay does not compare; shared enforcement belongs in
`.pre-commit-config.yaml`.
### 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.
`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
file in that hook's scope therefore rewrites apm's output into a form apm would never produce on the
way into **every** commit, and `apm-audit-ci` then reports permanent drift on a file with an empty
`git diff` — exactly what happened when the `SessionStart` hook first landed in `2e395a4`. Re-running
`apm install` fixes the file; leaving it in scope would re-break it on the very commit carrying the
fix.
**Load-bearing. Do not tidy it out of that list** (see `LESSONS.md`, 2026-08-14).
## 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`.
| 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.
---
## See also
- `docs/adr/0020-skill-description-and-body-context-contract.md` — the context contract, its
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/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

29
plugins/bin/.apm/skills/caveman/README.md Normal file
View File

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

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

@@ -1,17 +1,16 @@
--- ---
name: caveman name: caveman
disable-model-invocation: true
description: > description: >
Ultra-compressed communication mode. Cuts token usage ~75% by dropping Ultra-compressed output mode that drops articles, filler and pleasantries while
filler, articles, and pleasantries while keeping full technical accuracy. keeping technical substance exact, cutting token usage by roughly 75%.
Use when user says "caveman mode", "talk like caveman", "use caveman",
"less tokens", "be brief", or invokes /caveman.
--- ---
Respond terse like smart caveman. All technical substance stay. Only fluff die. Respond terse like smart caveman. All technical substance stay. Only fluff die.
## Persistence ## 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 ## Rules

35
plugins/bin/.apm/skills/diagnose/README.md Normal file
View File

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

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

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

27
plugins/bin/.apm/skills/grill-me/README.md Normal file
View File

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

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

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

36
plugins/bin/.apm/skills/grill-with-docs/README.md Normal file
View File

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

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

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

36
plugins/bin/.apm/skills/improve-codebase-architecture/README.md Normal file
View File

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

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

@@ -1,6 +1,10 @@
--- ---
name: improve-codebase-architecture 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 a codebase's architecture improved — deepening
opportunities that turn shallow modules into deep ones, informed by
`CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. Not
test-first feature work -> `tdd`.
--- ---
# Improve Codebase Architecture # Improve Codebase Architecture
@@ -65,7 +69,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
Side effects happen inline as decisions crystallize: Side effects happen inline as decisions crystallize:
- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. Create the file lazily if it doesn't exist.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `ADR-FORMAT.md`.
- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

32
plugins/bin/.apm/skills/prototype/README.md Normal file
View File

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

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

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

5
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." - "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**. - 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 ## Process
@@ -72,8 +72,5 @@ When the prototype has done its job, the answer to the question is the only thin
## Anti-patterns ## 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 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. - **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.

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. 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 ## 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
```

31
plugins/bin/.apm/skills/research/README.md Normal file
View File

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

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

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

32
plugins/bin/.apm/skills/tdd/README.md Normal file
View File

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

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

@@ -1,6 +1,9 @@
--- ---
name: tdd name: tdd
description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. description: >
Use when the user wants a feature built or a bug fixed test-first, in a strict
red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
--- ---
# Test-Driven Development # Test-Driven Development

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

@@ -1,6 +1,6 @@
# Writing Agent Briefs # 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 ## 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. 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" - **Bad:** "Triage should work correctly"
### Explicit scope boundaries ### Explicit scope boundaries

35
plugins/bin/.apm/skills/triage/README.md Normal file
View File

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

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

@@ -1,6 +1,9 @@
--- ---
name: triage name: triage
description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. description: >
Use when the user wants an issue created, triaged, or moved through the
tracker's triage states, or an issue prepared for an AFK agent. Not debugging
the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
--- ---
# Triage # Triage
@@ -35,7 +38,7 @@ Five **state** roles:
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else. 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. 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.

30
plugins/bin/.apm/skills/write-docs/README.md Normal file
View File

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

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

@@ -1,6 +1,9 @@
--- ---
name: write-docs name: write-docs
description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills. description: >
Use when the user wants technical documentation produced or updated from code
or spec, every claim traced to a source. Not a PRD, ADR, or decision doc ->
`grill-with-docs`. Not an external tool researched from its docs -> `research`.
version: "1.0" version: "1.0"
updated: 2026-05-17 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 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
@@ -35,7 +38,7 @@ 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" - User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
**Do not use when:** **Do not use when:**
- User wants a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me` - User wants a PRD, decision doc, or architecture proposal → `grill-me` or `grill-with-docs`
- User wants to document a skill file (skill files are self-describing) - User wants to document a skill file (skill files are self-describing)
- User wants marketing or blog copy - User wants marketing or blog copy
- Documentation requires tacit organisational knowledge that cannot be read from code or spec - Documentation requires tacit organisational knowledge that cannot be read from code or spec
@@ -88,7 +91,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 - 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 - 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 - 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 a PRD, decision doc, or architecture proposal → redirect to `grill-me` or `grill-with-docs`
## Self-check ## Self-check

25
plugins/bin/.apm/skills/zoom-out/README.md Normal file
View File

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

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

@@ -1,7 +1,7 @@
{ {
"name": "bin", "name": "bin",
"version": "1.1.3", "version": "1.2.0",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

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

@@ -1,7 +1,7 @@
{ {
"name": "bin", "name": "bin",
"version": "1.1.3", "version": "1.2.0",
"description": "A place for things to be binned", "description": "Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/bin/apm.yml
View File

@@ -1,6 +1,6 @@
name: bin name: bin
version: 1.1.3 version: 1.2.0
description: A place for things to be binned description: Skills for everyday AI-assisted development work that is not tied to a single tool, forge or language, and has not yet been split into a focused plugin.
author: author:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net

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

@@ -26,11 +26,6 @@ trigger_tests:
query: "Research why these integration tests are failing" query: "Research why these integration tests are failing"
should_trigger: false 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 - id: negative-context7-direct-question
name: "Negative — direct doc question goes to context7-mcp, not research" name: "Negative — direct doc question goes to context7-mcp, not research"
query: "What are the Next.js middleware options?" query: "What are the Next.js middleware options?"

29
plugins/bin/skills/caveman/README.md Normal file
View File

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

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

@@ -1,17 +1,16 @@
--- ---
name: caveman name: caveman
disable-model-invocation: true
description: > description: >
Ultra-compressed communication mode. Cuts token usage ~75% by dropping Ultra-compressed output mode that drops articles, filler and pleasantries while
filler, articles, and pleasantries while keeping full technical accuracy. keeping technical substance exact, cutting token usage by roughly 75%.
Use when user says "caveman mode", "talk like caveman", "use caveman",
"less tokens", "be brief", or invokes /caveman.
--- ---
Respond terse like smart caveman. All technical substance stay. Only fluff die. Respond terse like smart caveman. All technical substance stay. Only fluff die.
## Persistence ## 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 ## Rules

35
plugins/bin/skills/diagnose/README.md Normal file
View File

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

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

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

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

40
plugins/bin/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/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.

27
plugins/bin/skills/grill-me/README.md Normal file
View File

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

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

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

36
plugins/bin/skills/grill-with-docs/README.md Normal file
View File

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

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

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

36
plugins/bin/skills/improve-codebase-architecture/README.md Normal file
View File

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

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

@@ -1,6 +1,10 @@
--- ---
name: improve-codebase-architecture 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 a codebase's architecture improved — deepening
opportunities that turn shallow modules into deep ones, informed by
`CONTEXT.md` and `docs/adr/`. Not debugging a failure -> `diagnose`. Not
test-first feature work -> `tdd`.
--- ---
# Improve Codebase Architecture # Improve Codebase Architecture
@@ -65,7 +69,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
Side effects happen inline as decisions crystallize: Side effects happen inline as decisions crystallize:
- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `grill-with-docs`, in the format `grill-with-docs`'s `CONTEXT-FORMAT.md` defines. Create the file lazily if it doesn't exist.
- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See `grill-with-docs`'s `ADR-FORMAT.md`.
- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

32
plugins/bin/skills/prototype/README.md Normal file
View File

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

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

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

5
plugins/bin/skills/prototype/LOGIC.md → plugins/bin/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." - "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**. - 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 ## Process
@@ -72,8 +72,5 @@ When the prototype has done its job, the answer to the question is the only thin
## Anti-patterns ## 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 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. - **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.

2
plugins/bin/skills/prototype/UI.md → plugins/bin/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. 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 ## When this is the right shape

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

31
plugins/bin/skills/research/README.md Normal file
View File

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

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

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

32
plugins/bin/skills/tdd/README.md Normal file
View File

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

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

@@ -1,6 +1,9 @@
--- ---
name: tdd name: tdd
description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. description: >
Use when the user wants a feature built or a bug fixed test-first, in a strict
red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
--- ---
# Test-Driven Development # Test-Driven Development

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

@@ -1,6 +1,6 @@
# Writing Agent Briefs # 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 ## 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. 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" - **Bad:** "Triage should work correctly"
### Explicit scope boundaries ### Explicit scope boundaries

35
plugins/bin/skills/triage/README.md Normal file
View File

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

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

@@ -1,6 +1,9 @@
--- ---
name: triage name: triage
description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. description: >
Use when the user wants an issue created, triaged, or moved through the
tracker's triage states, or an issue prepared for an AFK agent. Not debugging
the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
--- ---
# Triage # Triage
@@ -35,7 +38,7 @@ Five **state** roles:
Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else. 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. 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.

30
plugins/bin/skills/write-docs/README.md Normal file
View File

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

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

@@ -1,6 +1,9 @@
--- ---
name: write-docs name: write-docs
description: Write documentation for X, document this module, create docs for this feature. Use when the user wants to produce or update technical documentation derived from code, spec, or existing artifacts. Do NOT use when the user wants a PRD, ADR, decision doc, or skill file — those have dedicated skills. description: >
Use when the user wants technical documentation produced or updated from code
or spec, every claim traced to a source. Not a PRD, ADR, or decision doc ->
`grill-with-docs`. Not an external tool researched from its docs -> `research`.
version: "1.0" version: "1.0"
updated: 2026-05-17 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 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
@@ -35,7 +38,7 @@ 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" - User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
**Do not use when:** **Do not use when:**
- User wants a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me` - User wants a PRD, decision doc, or architecture proposal → `grill-me` or `grill-with-docs`
- User wants to document a skill file (skill files are self-describing) - User wants to document a skill file (skill files are self-describing)
- User wants marketing or blog copy - User wants marketing or blog copy
- Documentation requires tacit organisational knowledge that cannot be read from code or spec - Documentation requires tacit organisational knowledge that cannot be read from code or spec
@@ -88,7 +91,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 - 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 - 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 - 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 a PRD, decision doc, or architecture proposal → redirect to `grill-me` or `grill-with-docs`
## Self-check ## Self-check

25
plugins/bin/skills/zoom-out/README.md Normal file
View File

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

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

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

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

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

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

@@ -1,20 +1,10 @@
--- ---
name: agentsmd-author name: agentsmd-author
description: > description: >
Use when the user wants to create or update a repo's AGENTS.md file Use when the user wants a repo's AGENTS.md written or updated, root or
("write an AGENTS.md for this repo", "add setup/test instructions for nested, including "document this for AI coding tools". Writes only verified
agents", "update AGENTS.md", "give this package its own AGENTS.md") — even conventions. Not review-only -> `agentsmd-audit`. Not converting CLAUDE.md ->
if they don't name the file explicitly, e.g. "document this for AI coding `provider-adapter-author`.
tools" or "make sure agents know how to run tests here". Writes/updates
AGENTS.md by exploring the target repo for real build, test, lint, and
style conventions — never invents commands. Supports nested monorepo
placement (a subdirectory can get its own AGENTS.md following
nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
inline, and calls provider-adapter-author when an existing provider file
(CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
provider-adapter-author instead.
allowed-tools: Bash Read Write Edit allowed-tools: Bash Read Write Edit
metadata: metadata:
category: docs category: docs
@@ -22,16 +12,13 @@ metadata:
- agents-md-official - agents-md-official
- context7-websites-agents-md - context7-websites-agents-md
- context7-agentsmd-agents-md - context7-agentsmd-agents-md
version: "0.1.1" version: "0.1.2"
--- ---
## Gotchas ## 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. - Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one. - Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
## Step 1 — Explore the target repo ## 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 ## Step 2 — Decide placement
- No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions. - 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. - Otherwise → update the existing file(s) in place.
## Step 3 — Write or update ## 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 ## 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 ## 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.

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

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

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

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

32
plugins/core/.apm/skills/provider-adapter-author/references/provider-matrix.md Normal file
View File

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

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

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

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

@@ -16,16 +16,27 @@ Arguments:
Options: Options:
--no-import-syntax The target provider has no native cross-file import --no-import-syntax The target provider has no native cross-file import
mechanism. Accept a plain-text pointer mention of mechanism. Require a plain-text pointer line naming
"AGENTS.md" instead of requiring an @import-style line. "AGENTS.md" instead of an @import-style line; an
@AGENTS.md line alone does not satisfy it, because
such a provider never resolves it. Without this flag
an actual @import line is required, and naming
AGENTS.md in prose alone does not satisfy it.
--max-lines N Max non-blank lines allowed in the adapter file before --max-lines N Max non-blank lines allowed in the adapter file before
it's considered no longer "thin". Default: 60. it's considered no longer "thin". Must be a
non-negative integer. Default: 60.
--help, -h Show this help and exit 0. --help, -h Show this help and exit 0.
Exit codes: Exit codes:
0 Adapter file passes all checks 0 Adapter file passes all checks
1 One or more checks failed (empty file, no reference to AGENTS.md, 1 One or more checks failed (empty file, no reference to AGENTS.md,
excessive duplication, or file too long) excessive duplication, or file too long)
2 Usage or input error — a bad or missing argument, a path that is not a
file, or a file that is not UTF-8. Nothing was graded, so there is no
FAIL line and no adapter edit to make: fix the invocation or the file's
encoding and re-run. Kept distinct from 1 because the skill's own
closeout tells the agent to fix every non-zero exit by editing the
provider file, which for a mistyped flag edits the wrong file forever.
EOF EOF
} }
@@ -44,7 +55,15 @@ while [[ $# -gt 0 ]]; do
shift shift
;; ;;
--max-lines) --max-lines)
MAX_LINES="${2:-}" if [[ $# -lt 2 ]]; then
echo "Error: --max-lines requires a value (a non-negative integer)." >&2
exit 2
fi
MAX_LINES="$2"
if [[ ! "$MAX_LINES" =~ ^[0-9]+$ ]]; then
echo "Error: --max-lines expects a non-negative integer, got '$MAX_LINES'." >&2
exit 2
fi
shift 2 shift 2
;; ;;
*) *)
@@ -58,7 +77,7 @@ if [[ ${#ARGS[@]} -lt 2 ]]; then
echo "Error: adapter-file and agents-md-file are required." >&2 echo "Error: adapter-file and agents-md-file are required." >&2
echo "" >&2 echo "" >&2
usage >&2 usage >&2
exit 1 exit 2
fi fi
python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON' python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
@@ -72,15 +91,43 @@ max_lines = int(max_lines)
if not os.path.isfile(adapter_path): if not os.path.isfile(adapter_path):
print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr) print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
sys.exit(1) sys.exit(2)
if not os.path.isfile(agents_md_path): if not os.path.isfile(agents_md_path):
print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr) print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
sys.exit(1) sys.exit(2)
with open(adapter_path, encoding="utf-8", errors="replace") as f:
adapter_content = f.read() def read_text(path):
with open(agents_md_path, encoding="utf-8", errors="replace") as f: r"""File contents as text, UTF-8, BOM stripped.
agents_md_content = f.read()
The BOM strip is not cosmetic. IMPORT_RE anchors on `^\s*@`, and a BOM is
not `\s` in Python, so a CLAUDE.md saved by an editor that emits one had
its first line — the `@AGENTS.md` import, which is the whole adapter —
silently treated as prose. The check then said "no reference to AGENTS.md"
told the author to add the line already sitting in front of them. Same
class of silent BOM miss recorded in scripts/skill-size-check.sh; strip it
at the reader so no later check has to know about it.
Decoding is strict, not errors="replace". Replacement mangles the file and
the checks then grade the mangling: a UTF-16 adapter whose first line is
`@AGENTS.md` decoded to interleaved NULs and failed as "no reference",
which is a true FAIL for a false reason and points the fix at the wrong
thing. A file this gate cannot read gets an encoding diagnostic and exit 2,
the same policy the ADR-0020 validators' read_text() uses.
"""
try:
with open(path, encoding="utf-8") as fh:
text = fh.read()
except UnicodeDecodeError as exc:
print(f"Error: '{path}' is not valid UTF-8 ({exc.reason} at byte "
f"{exc.start}) — re-save it as UTF-8; this check does not guess "
"at other encodings.", file=sys.stderr)
sys.exit(2)
return text[1:] if text.startswith("\ufeff") else text
adapter_content = read_text(adapter_path)
agents_md_content = read_text(agents_md_path)
has_fail = False has_fail = False
@@ -94,21 +141,25 @@ if not adapter_content.strip():
IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$') IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
lines = adapter_content.splitlines() lines = adapter_content.splitlines()
import_lines = [ln for ln in lines if IMPORT_RE.match(ln)] import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
# A prose pointer is any line naming AGENTS.md that is not itself an import
# line — an inert `@AGENTS.md` in a provider that resolves no imports points
# a reader at nothing.
pointer_lines = [ln for ln in lines if not IMPORT_RE.match(ln) and "AGENTS.md" in ln]
if no_import_syntax: if no_import_syntax:
has_reference = "AGENTS.md" in adapter_content has_reference = bool(pointer_lines)
else: else:
has_reference = bool(import_lines) or "AGENTS.md" in adapter_content has_reference = bool(import_lines)
if not has_reference: if not has_reference:
has_fail = True has_fail = True
print(f"FAIL Adapter has no reference to AGENTS.md — {adapter_path}") print(f"FAIL Adapter has no reference to AGENTS.md — {adapter_path}")
if no_import_syntax: if no_import_syntax:
print(" Why: This provider has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.") print(" Why: This provider resolves no cross-file import, so the adapter must point at AGENTS.md in prose; an `@AGENTS.md` line here is inert text.")
print(" Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"") print(" Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
else: else:
print(" Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.") print(" Why: A thin adapter must import AGENTS.md with an `@AGENTS.md` line of its own; naming the file mid-sentence or inside backticks is prose this check will not credit, and merely naming it defers nothing.")
print(" Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.") print(" Fix: Put `@AGENTS.md` (or the equivalent relative path) alone on its own line, or pass --no-import-syntax if this provider resolves no imports.")
print() print()
# --- Duplication check --- # --- Duplication check ---
@@ -132,7 +183,7 @@ if non_blank_count > max_lines:
has_fail = True has_fail = True
print(f"FAIL Adapter is not thin — {adapter_path}") print(f"FAIL Adapter is not thin — {adapter_path}")
print(f" Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.") print(f" Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
print(" Fix: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.") print(" Fix: Delete the lines already covered by AGENTS.md; keep only genuinely provider-specific additions here.")
print() print()
if has_fail: if has_fail:

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

@@ -115,6 +115,51 @@ EOF
assert_output --partial "no reference" assert_output --partial "no reference"
} }
@test "the two --no-import-syntax branches disagree: a text-pointer-only adapter fails in default mode" {
ADAPTER="$TMPDIR/copilot-instructions.md"
cat > "$ADAPTER" <<'EOF'
See AGENTS.md at the repo root for setup, style, and testing conventions.
## Copilot-specific
Prefer inline suggestions over chat for one-line edits.
EOF
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "no reference"
run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
assert_success
}
@test "with --no-import-syntax, an inert @AGENTS.md line alone is not a prose pointer" {
ADAPTER="$TMPDIR/copilot-instructions.md"
cat > "$ADAPTER" <<'EOF'
@AGENTS.md
## Copilot-specific
Prefer inline suggestions over chat for one-line edits.
EOF
run bash "$SCRIPT" --no-import-syntax "$ADAPTER" "$AGENTS_MD"
assert_failure
assert_output --partial "no reference"
}
@test "--max-lines as the final argument reports a real error instead of failing silently" {
ADAPTER="$TMPDIR/CLAUDE.md"
echo "@AGENTS.md" > "$ADAPTER"
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD" --max-lines
assert_failure 2
assert_output --partial "--max-lines requires a value"
}
@test "--max-lines rejects a non-numeric value with a real error" {
ADAPTER="$TMPDIR/CLAUDE.md"
echo "@AGENTS.md" > "$ADAPTER"
run bash "$SCRIPT" --max-lines abc "$ADAPTER" "$AGENTS_MD"
assert_failure 2
assert_output --partial "non-negative integer"
}
@test "--help exits 0 and documents usage" { @test "--help exits 0 and documents usage" {
run bash "$SCRIPT" --help run bash "$SCRIPT" --help
assert_success assert_success
@@ -123,6 +168,47 @@ EOF
@test "fails with a clear error when the adapter file argument is missing" { @test "fails with a clear error when the adapter file argument is missing" {
run bash "$SCRIPT" run bash "$SCRIPT"
assert_failure assert_failure 2
assert_output --partial "required" assert_output --partial "required"
} }
@test "a UTF-8 BOM before the @import line does not hide it" {
ADAPTER="$TMPDIR/CLAUDE.md"
python3 -c "import sys; open(sys.argv[1], 'w', encoding='utf-8-sig').write('@AGENTS.md\n')" "$ADAPTER"
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_success
}
@test "a usage error exits 2, a genuine finding exits 1" {
ADAPTER="$TMPDIR/CLAUDE.md"
echo "@AGENTS.md" > "$ADAPTER"
run bash "$SCRIPT" --max-lines -3 "$ADAPTER" "$AGENTS_MD"
assert_failure 2
refute_output --partial "FAIL"
: > "$ADAPTER"
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure 1
assert_output --partial "FAIL"
}
@test "a non-UTF-8 adapter is reported as an encoding error, not as a missing reference" {
ADAPTER="$TMPDIR/CLAUDE.md"
python3 -c "import sys; open(sys.argv[1], 'wb').write('@AGENTS.md\n'.encode('utf-16'))" "$ADAPTER"
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure 2
assert_output --partial "not valid UTF-8"
refute_output --partial "no reference"
}
@test "an @AGENTS.md folded into a sentence fails, and the message says the import needs its own line" {
ADAPTER="$TMPDIR/CLAUDE.md"
cat > "$ADAPTER" <<'EOF'
See @AGENTS.md for shared conventions.
EOF
run bash "$SCRIPT" "$ADAPTER" "$AGENTS_MD"
assert_failure 1
assert_output --partial "no reference"
assert_output --partial "line of its own"
}

2
plugins/core/.claude-plugin/plugin.json
View File

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

2
plugins/core/.github/plugin/plugin.json vendored
View File

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

2
plugins/core/apm.yml
View File

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

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

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

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

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

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

@@ -1,20 +1,10 @@
--- ---
name: agentsmd-author name: agentsmd-author
description: > description: >
Use when the user wants to create or update a repo's AGENTS.md file Use when the user wants a repo's AGENTS.md written or updated, root or
("write an AGENTS.md for this repo", "add setup/test instructions for nested, including "document this for AI coding tools". Writes only verified
agents", "update AGENTS.md", "give this package its own AGENTS.md") — even conventions. Not review-only -> `agentsmd-audit`. Not converting CLAUDE.md ->
if they don't name the file explicitly, e.g. "document this for AI coding `provider-adapter-author`.
tools" or "make sure agents know how to run tests here". Writes/updates
AGENTS.md by exploring the target repo for real build, test, lint, and
style conventions — never invents commands. Supports nested monorepo
placement (a subdirectory can get its own AGENTS.md following
nearest-file-wins precedence). Closes every run by invoking agentsmd-audit
inline, and calls provider-adapter-author when an existing provider file
(CLAUDE.md, etc.) now duplicates what AGENTS.md owns. Do not use to review
an existing AGENTS.md without changing it — use agentsmd-audit instead. Do
not use to convert CLAUDE.md/.cursor/rules into a thin adapter — use
provider-adapter-author instead.
allowed-tools: Bash Read Write Edit allowed-tools: Bash Read Write Edit
metadata: metadata:
category: docs category: docs
@@ -22,16 +12,13 @@ metadata:
- agents-md-official - agents-md-official
- context7-websites-agents-md - context7-websites-agents-md
- context7-agentsmd-agents-md - context7-agentsmd-agents-md
version: "0.1.1" version: "0.1.2"
--- ---
## Gotchas ## 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. - Never invent a command. Every line under a setup/test/build section must come from something you actually found in the repo (`package.json` scripts, a `Makefile` target, a CI workflow step, a README). If you can't verify a command, don't include it.
- AGENTS.md has no required schema — don't force every common-sections-checklist heading into every repo. Include only sections that reflect something real about this repo; a thin, accurate file beats a padded, generic one. - Never write to a provider file yourself, in any circumstance: `CLAUDE.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md` and their equivalents are `provider-adapter-author`'s to own. That holds even when the user asks for one in the same breath as AGENTS.md, and even when the file is merely stale or missing a pointer rather than duplicating anything. Detect it and hand off.
- Nested placement is for genuinely different conventions, not convenience. Only create a subdirectory AGENTS.md when that subtree has its own build tool, stack, or conventions distinct from the root — otherwise you're duplicating content the root already covers, which the nearest-file-wins rule doesn't merge back together.
- This skill never touches CLAUDE.md, `.cursor/rules/*.mdc`, `copilot-instructions.md`, or similar provider files directly — that's `provider-adapter-author`'s job. Detect and hand off; don't reconcile it yourself.
- This skill never audits on its own judgment — the closing `agentsmd-audit` invocation is mandatory, not optional, even when the change looks trivial.
## Step 1 — Explore the target repo ## 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 ## Step 2 — Decide placement
- No `AGENTS.md` at the repo root yet → create one there first, covering whole-repo conventions. - 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. - Otherwise → update the existing file(s) in place.
## Step 3 — Write or update ## 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 ## 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 ## 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.

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

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

38
plugins/core/skills/provider-adapter-author/SKILL.md
View File

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

32
plugins/core/skills/provider-adapter-author/references/provider-matrix.md Normal file
View File

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

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

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

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

@@ -16,16 +16,27 @@ Arguments:
Options: Options:
--no-import-syntax The target provider has no native cross-file import --no-import-syntax The target provider has no native cross-file import
mechanism. Accept a plain-text pointer mention of mechanism. Require a plain-text pointer line naming
"AGENTS.md" instead of requiring an @import-style line. "AGENTS.md" instead of an @import-style line; an
@AGENTS.md line alone does not satisfy it, because
such a provider never resolves it. Without this flag
an actual @import line is required, and naming
AGENTS.md in prose alone does not satisfy it.
--max-lines N Max non-blank lines allowed in the adapter file before --max-lines N Max non-blank lines allowed in the adapter file before
it's considered no longer "thin". Default: 60. it's considered no longer "thin". Must be a
non-negative integer. Default: 60.
--help, -h Show this help and exit 0. --help, -h Show this help and exit 0.
Exit codes: Exit codes:
0 Adapter file passes all checks 0 Adapter file passes all checks
1 One or more checks failed (empty file, no reference to AGENTS.md, 1 One or more checks failed (empty file, no reference to AGENTS.md,
excessive duplication, or file too long) excessive duplication, or file too long)
2 Usage or input error — a bad or missing argument, a path that is not a
file, or a file that is not UTF-8. Nothing was graded, so there is no
FAIL line and no adapter edit to make: fix the invocation or the file's
encoding and re-run. Kept distinct from 1 because the skill's own
closeout tells the agent to fix every non-zero exit by editing the
provider file, which for a mistyped flag edits the wrong file forever.
EOF EOF
} }
@@ -44,7 +55,15 @@ while [[ $# -gt 0 ]]; do
shift shift
;; ;;
--max-lines) --max-lines)
MAX_LINES="${2:-}" if [[ $# -lt 2 ]]; then
echo "Error: --max-lines requires a value (a non-negative integer)." >&2
exit 2
fi
MAX_LINES="$2"
if [[ ! "$MAX_LINES" =~ ^[0-9]+$ ]]; then
echo "Error: --max-lines expects a non-negative integer, got '$MAX_LINES'." >&2
exit 2
fi
shift 2 shift 2
;; ;;
*) *)
@@ -58,7 +77,7 @@ if [[ ${#ARGS[@]} -lt 2 ]]; then
echo "Error: adapter-file and agents-md-file are required." >&2 echo "Error: adapter-file and agents-md-file are required." >&2
echo "" >&2 echo "" >&2
usage >&2 usage >&2
exit 1 exit 2
fi fi
python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON' python3 -u - "${ARGS[0]}" "${ARGS[1]}" "$NO_IMPORT_SYNTAX" "$MAX_LINES" <<'PYTHON'
@@ -72,15 +91,43 @@ max_lines = int(max_lines)
if not os.path.isfile(adapter_path): if not os.path.isfile(adapter_path):
print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr) print(f"Error: '{adapter_path}' is not a file.", file=sys.stderr)
sys.exit(1) sys.exit(2)
if not os.path.isfile(agents_md_path): if not os.path.isfile(agents_md_path):
print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr) print(f"Error: '{agents_md_path}' is not a file.", file=sys.stderr)
sys.exit(1) sys.exit(2)
with open(adapter_path, encoding="utf-8", errors="replace") as f:
adapter_content = f.read() def read_text(path):
with open(agents_md_path, encoding="utf-8", errors="replace") as f: r"""File contents as text, UTF-8, BOM stripped.
agents_md_content = f.read()
The BOM strip is not cosmetic. IMPORT_RE anchors on `^\s*@`, and a BOM is
not `\s` in Python, so a CLAUDE.md saved by an editor that emits one had
its first line — the `@AGENTS.md` import, which is the whole adapter —
silently treated as prose. The check then said "no reference to AGENTS.md"
told the author to add the line already sitting in front of them. Same
class of silent BOM miss recorded in scripts/skill-size-check.sh; strip it
at the reader so no later check has to know about it.
Decoding is strict, not errors="replace". Replacement mangles the file and
the checks then grade the mangling: a UTF-16 adapter whose first line is
`@AGENTS.md` decoded to interleaved NULs and failed as "no reference",
which is a true FAIL for a false reason and points the fix at the wrong
thing. A file this gate cannot read gets an encoding diagnostic and exit 2,
the same policy the ADR-0020 validators' read_text() uses.
"""
try:
with open(path, encoding="utf-8") as fh:
text = fh.read()
except UnicodeDecodeError as exc:
print(f"Error: '{path}' is not valid UTF-8 ({exc.reason} at byte "
f"{exc.start}) — re-save it as UTF-8; this check does not guess "
"at other encodings.", file=sys.stderr)
sys.exit(2)
return text[1:] if text.startswith("\ufeff") else text
adapter_content = read_text(adapter_path)
agents_md_content = read_text(agents_md_path)
has_fail = False has_fail = False
@@ -94,21 +141,25 @@ if not adapter_content.strip():
IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$') IMPORT_RE = re.compile(r'(?m)^\s*@\S*AGENTS\.md\s*$')
lines = adapter_content.splitlines() lines = adapter_content.splitlines()
import_lines = [ln for ln in lines if IMPORT_RE.match(ln)] import_lines = [ln for ln in lines if IMPORT_RE.match(ln)]
# A prose pointer is any line naming AGENTS.md that is not itself an import
# line — an inert `@AGENTS.md` in a provider that resolves no imports points
# a reader at nothing.
pointer_lines = [ln for ln in lines if not IMPORT_RE.match(ln) and "AGENTS.md" in ln]
if no_import_syntax: if no_import_syntax:
has_reference = "AGENTS.md" in adapter_content has_reference = bool(pointer_lines)
else: else:
has_reference = bool(import_lines) or "AGENTS.md" in adapter_content has_reference = bool(import_lines)
if not has_reference: if not has_reference:
has_fail = True has_fail = True
print(f"FAIL Adapter has no reference to AGENTS.md — {adapter_path}") print(f"FAIL Adapter has no reference to AGENTS.md — {adapter_path}")
if no_import_syntax: if no_import_syntax:
print(" Why: This provider has no import syntax, so the adapter must at least mention AGENTS.md as a text pointer.") print(" Why: This provider resolves no cross-file import, so the adapter must point at AGENTS.md in prose; an `@AGENTS.md` line here is inert text.")
print(" Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"") print(" Fix: Add a sentence like \"See AGENTS.md at the repo root for shared conventions.\"")
else: else:
print(" Why: A thin adapter must import AGENTS.md (e.g. `@AGENTS.md`) rather than silently omitting it.") print(" Why: A thin adapter must import AGENTS.md with an `@AGENTS.md` line of its own; naming the file mid-sentence or inside backticks is prose this check will not credit, and merely naming it defers nothing.")
print(" Fix: Add an `@AGENTS.md` (or equivalent relative path) import line.") print(" Fix: Put `@AGENTS.md` (or the equivalent relative path) alone on its own line, or pass --no-import-syntax if this provider resolves no imports.")
print() print()
# --- Duplication check --- # --- Duplication check ---
@@ -132,7 +183,7 @@ if non_blank_count > max_lines:
has_fail = True has_fail = True
print(f"FAIL Adapter is not thin — {adapter_path}") print(f"FAIL Adapter is not thin — {adapter_path}")
print(f" Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.") print(f" Why: {non_blank_count} non-blank lines exceeds the {max_lines}-line threshold for a thin adapter.")
print(" Fix: Move provider-agnostic content into AGENTS.md; keep only genuinely provider-specific additions here.") print(" Fix: Delete the lines already covered by AGENTS.md; keep only genuinely provider-specific additions here.")
print() print()
if has_fail: if has_fail:

15
plugins/git/.apm/skills/git-branches/README.md
View File

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

103
plugins/git/.apm/skills/git-branches/SKILL.md
View File

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

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