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

Compare commits

base: Defame1297:b9c7762463805049ad49b29b8d8d083cb6b4625f
Branches Tags
Defame1297:main Defame1297:feat/primitive-author 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:v2.0.1
Branches Tags
Defame1297:feat/primitive-author 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

14 Commits
b9c7762463 ... v2.0.1

Author SHA1 Message Date
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
29 changed files with 475 additions and 122 deletions
Expand all files Collapse all files

14
.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.4.5",
"owner": { "owner": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",
@@ -17,22 +17,22 @@
}, },
{ {
"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.1.5",
"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.3.5",
"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.3.6",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/gitea" "source": "./plugins/gitea"
}, },

14
.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.4.5",
"owner": { "owner": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",
@@ -17,22 +17,22 @@
}, },
{ {
"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.1.5",
"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.3.5",
"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.3.6",
"category": "Version Control", "category": "Version Control",
"source": "./plugins/gitea" "source": "./plugins/gitea"
}, },

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.

10
AGENTS.md
View File

@@ -27,25 +27,25 @@ This repo dogfoods its own plugins. Before shelling out, check whether a skill a
- 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. The `<plugin>:` form (`gitea:gitea-prs`) also still resolves, because user-scope native installs were left enabled on purpose (ADR-0018) — a working namespaced call is not evidence that anything is broken and is not something to "fix". Prefer the bare name anyway: it is what `apm install` deploys, and what survives those user-scope installs eventually being converted. 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.
## Session rules ## Session rules
- **Do not add repo-owned keys to `.claude/settings.json`.** apm treats it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. 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 it as its own deployed artifact and `apm audit --ci` replays the install and diffs, so anything apm would not have written is permanent drift that fails the `apm-audit-ci` pre-push hook. A hook you want here is authored in `plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written into that file. The `SessionStart` entry already in it is exactly that: kyberforge authors it in `plugins/kyberforge/.apm/hooks/hooks.json` and apm merges it in, so it is apm's own output, it is what the replay expects, and it belongs in the commit — do not strip it (ADR-0019). Machine-specific settings go in the gitignored `.claude/settings.local.json`; shared enforcement goes in `.pre-commit-config.yaml`.
- **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook runs `apm outdated` at startup and `apm update --yes` when something is behind, which rewrites the lock. Commit or discard it deliberately. - **`apm.lock.yaml` turning up modified is expected, not a bug.** kyberforge's `SessionStart` hook runs `apm outdated` at startup and `apm update --yes` when something is behind, which rewrites the lock. Commit or discard it deliberately.
- **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs. - **A `.apm/` edit is not live in this session until it is pushed.** The six dependencies resolve from the holocron remote, unpinned against the default branch. `apm install` deploys from the lock; `apm update` is what re-resolves refs.
- **The ADR-0020 skill gates ship hot, with no baseline.** 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the `Kyberforge.CompositionNote` Vale rule fires 10 errors across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Editing any of those skills *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. `skill-size-check` will not warn you about the Vale half, so check both: `pre-commit run --all-files`. - **The ADR-0020 skill gates ship hot, with no baseline.** 26 of 39 descriptions and 9 of 39 bodies exceed their FAIL tier, and the `Kyberforge.CompositionNote` Vale rule fires 10 errors across `gitea-issues`, `gitea-labels-milestones`, `gitea-prs` and `gitea-workflow`. Editing any of those skills *for any reason* means retrofitting it to the contract first — a one-line fix cannot be committed until the skill complies. Deliberate; tracked as Gitea issue #99. `skill-size-check` will not warn you about the Vale half, so check both: `pre-commit run --all-files`.
- **Run `bash tests/run-tests.sh` before considering any change done.** - **Run `bash tests/run-tests.sh --strict` before considering any change done.** Keep the flag: without it a suite whose dependency is missing exits 77 and is counted SKIPPED rather than failed, so the run goes green having verified less than it claims.
- **Before pushing, run the whole gate locally:** `pre-commit run --hook-stage pre-push --all-files`. Pushing runs 14 repo-defined hooks, not just the test suite. - **Before pushing, rehearse the gate locally:** `pre-commit run --hook-stage pre-push --all-files`. It runs the 14 pre-push hooks this repo authors itself plus pre-commit's 2 `meta` hooks, so it prints 16; `check-release-needed` passes without checking anything, because it needs a real push to `main`. `docs/spec/gates.md` reconciles both.
- **Pushing without a network** needs `SKIP=apm-marketplace-check,apm-pack-check-clean git push` — those two resolve a remote marketplace entry via `git ls-remote`. Skip only those two; the rest are real local checks, and adding one to `SKIP` disarms it silently. - **Pushing without a network** needs `SKIP=apm-marketplace-check,apm-pack-check-clean git push` — those two resolve a remote marketplace entry via `git ls-remote`. Skip only those two; the rest are real local checks, and adding one to `SKIP` disarms it silently.
- **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces. - **Author commits with `git-commits`** — it validates Conventional Commits, which `commit-msg` enforces.
- **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. - **This repo and Gitea are the only source of truth.** All project state, decisions, and working conventions live here. Do not use an external memory system for this project — cached state diverges from the repo and you get a split brain. Before answering any design or architecture question, check `docs/adr/` for an existing decision.
## Key documents ## Key documents
Read `CONTEXT.md` at the start of every session — it is this repo's domain language, and the terms in it are used unglossed everywhere else. 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:

48
CONTEXT.md
View File

@@ -16,8 +16,8 @@ decisions.
**Preload tax**: **Preload tax**:
The always-on context cost of every installed skill's `name` and `description`, charged from the 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. Measured 2026-08-14 at ~5,900 first token of every session whether the skill is invoked or not. Measurement method and current
tokens across 39 skills; method in `docs/spec/gates.md`. figure: ADR-0020.
_Avoid_: context cost, token overhead _Avoid_: context cost, token overhead
**Skill context contract**: **Skill context contract**:
@@ -57,6 +57,24 @@ The deployable unit — one or more skills, agents, hooks, commands, and MCP ser
single installable directory under `plugins/<name>/`, compiled from that plugin's `.apm/` source. single installable directory under `plugins/<name>/`, compiled from that plugin's `.apm/` source.
_Avoid_: package, bundle, module _Avoid_: package, bundle, module
**apm package**:
The unit apm builds and installs — `plugins/<name>/apm.yml` plus the hand-authored
`plugins/<name>/.apm/` tree it compiles from (ADR-0015).
_Avoid_: plugin directory, source tree
**Content mirror**:
The generated flat `skills/`, `agents/`, `commands/`, `instructions/`, `extensions/` directories and
merged `hooks/hooks.json` at a plugin root — also called the flat mirror — compiled from that
plugin's `.apm/` tree so hosts that convention-scan those paths discover the content (ADR-0017).
_Avoid_: generated copy, duplicate tree
**Output profile**:
An `apm pack` target format for a generated *marketplace* manifest; apm has `claude`
(`.claude-plugin/marketplace.json`) and `codex` (the differently-shaped
`.agents/plugins/marketplace.json`), and none for `.github/plugin/marketplace.json` (Copilot CLI's
legacy path), which a sync script mirrors instead. Mechanics: `docs/spec/architecture.md`.
_Avoid_: build target, export format
**Plugin marketplace**: **Plugin marketplace**:
A Git repository carrying a `marketplace.json` manifest that lists installable plugins. There is no 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. backend, registry, or SaaS — the Git repo is the marketplace.
@@ -114,8 +132,7 @@ content of its own (ADR-0002, ADR-0003).
_Avoid_: wrapper, shim, provider file _Avoid_: wrapper, shim, provider file
**LESSONS.md**: **LESSONS.md**:
The long-loop feedback log for patterns observed across sessions, at the repo root. Written by the The long-loop feedback log for patterns observed across sessions, at the repo root.
session-handoff skill or directly by the human.
_Avoid_: changelog, retro, postmortem _Avoid_: changelog, retro, postmortem
**Management Application**: **Management Application**:
@@ -136,6 +153,23 @@ The deterministic Vale pass that runs ahead of `skill-audit`/`agent-audit`'s Des
so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`. so LLM judgment is spent only on what a pattern cannot catch. Mechanics: `docs/spec/gates.md`.
_Avoid_: linting, style check _Avoid_: linting, style check
**Authoring root**:
The directory a gate resolves against — the nearest ancestor of the file being checked holding
`plugins/*/.apm/skills` or `plugins/*/.apm/agents`, falling back to the nearest ancestor holding
`.git`. The walk: `docs/spec/gates.md`.
_Avoid_: repo root, project root
**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
**Vacuous green**:
A check that reports success because it measured nothing — zero files scanned, an unparsed value read
as empty, a conditional branch that never armed.
_Avoid_: false pass, clean run
**Issue**: **Issue**:
The cross-provider term for a tracked unit of work. Gitea is this repo's canonical tracker 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. (ADR-0007), but skills say "linked issue" generically rather than naming a provider.
@@ -182,9 +216,9 @@ _Avoid_: ticket, card, task
- "skill" was used for both the authored `SKILL.md` under `plugins/<name>/.apm/skills/` and the - "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 under `.claude/skills/` — resolved: the authoring source is the **Skill**; the
deployed copy is gitignored `apm install` output and is never edited. deployed copy is gitignored `apm install` output and is never edited.
- Skills answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), because - Skills can answer to two names, bare (`gitea-prs`) and namespaced (`gitea:gitea-prs`), depending on
user-scope native installs were left enabled deliberately (ADR-0018) — resolved: write the bare whether a native install exists at user scope alongside the apm one (ADR-0018) — resolved: write
name; a working namespaced call is not evidence of a defect. 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 - "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. 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 - "audit" was used for both an author skill's inline closeout and `forge`'s independent

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

19
README.md
View File

@@ -8,7 +8,7 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa
| Path | What it holds | | Path | What it holds |
| --- | --- | | --- | --- |
| `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, agents, hooks, MCP servers, and bundled assets | | `plugins/` | Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets |
| `providers/claude-code/` | Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh` | | `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/` | | `core/` | Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/` |
| `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes | | `docs/` | Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes |
@@ -18,11 +18,11 @@ Content ships as six installable plugins, each an apm (Agent Package Manager) pa
The six plugins: The six plugins:
- **kyberforge** — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace - **kyberforge** — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace
- **git** — conventional commits, branch management, pull requests, feature flow - **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, milestones, releases, wikis - **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 - **core** — authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it
- **lint** — configuring and running linters - **lint** — configuring and running linters
- **bin** — a place for things to be binned - **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 ## Prerequisites
@@ -50,12 +50,12 @@ Run these in order, from the repo root.
apm install apm install
# 2. Install the git hooks — all three stages # 2. Install the git hooks — all three stages
# (use the `pc-run` skill, which knows the stage wiring) pre-commit install -t pre-commit -t commit-msg -t pre-push
``` ```
**`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`. **`apm install`** deploys the six plugins into `.claude/skills/` and `.claude/agents/`. Both are gitignored install output, *not* authoring source — `plugins/<name>/.apm/` remains the only place to edit. It needs the network, materializes `apm_modules/` (which stays gitignored), and also configures the `obsidian` MCP server into the repo's `.mcp.json`.
**Git hooks** go in via the `pc-run` skill, wiring **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). **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 ## Keeping the install current
@@ -81,12 +81,17 @@ A suite that exits 77 because a dependency is missing is reported as SKIPPED and
## Before pushing ## Before pushing
Run the whole pre-push gate locally in one command: Run the pre-push gate locally in one command:
```bash ```bash
pre-commit run --hook-stage pre-push --all-files 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. 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`: **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`:

16
apm.yml
View File

@@ -1,5 +1,5 @@
name: holocron name: holocron
version: 0.4.2 version: 0.4.5
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
@@ -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.4.5
owner: owner:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net
@@ -83,21 +83,21 @@ marketplace:
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.1.5
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.3.5
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.3.6
category: Version Control category: Version Control
- name: core - name: core

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/0015-apm-replaces-plugin-marketplace-authoring.md
View File

@@ -57,7 +57,9 @@ new hand-maintained manifest format.
- `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 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`. 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
@@ -68,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`,

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

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.

18
docs/spec/architecture.md
View File

@@ -21,21 +21,25 @@ 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) and carries nothing else — the content index of on-demand instruction files sits in `core/AGENTS.md`, deployed beside it. 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`. 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 | | Plugin | Scope |
|---|---| |---|---|
| `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it | | `core` | Authoring and auditing a repo's `AGENTS.md` and the provider adapter files that defer to it |
| `git` | Conventional commits, branch management, history, worktrees, remotes | | `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` | Issues, pull requests, labels, milestones, releases, wikis | | `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 | | `kyberforge` | Creating and maintaining a Claude Code / Copilot CLI plugin marketplace — this repo's own meta-tooling |
| `lint` | Configuring and running linters; repo-agnostic, first linter is Vale (`vale-config` / `vale-run`, plus the `lint-runner` agent) | | `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 | | `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:
@@ -72,7 +76,7 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
## Reference conventions ## 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 two of the 39 skill 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. 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
@@ -80,4 +84,4 @@ The stated convention is that files referencing other files declare those refere
## Architectural decisions ## Architectural decisions
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. There is no index file — the directory holds 20 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).

73
docs/spec/gates.md
View File

@@ -14,7 +14,7 @@ of the oddities documented here are load-bearing and have already been re-litiga
| Command | Scope | | Command | Scope |
|---|---| |---|---|
| `pre-commit run --all-files` | the commit-stage hooks | | `pre-commit run --all-files` | the commit-stage hooks |
| `pre-commit run --hook-stage pre-push --all-files` | the whole push gate, one command | | `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 | | `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 Install hooks via `pc-run`, wiring **all three stages**. This repo's `.pre-commit-config.yaml` has no
@@ -23,11 +23,22 @@ and `pre-push` (everything below).
The pre-push command reports **16** hooks, not 14. The extra two are pre-commit's own `meta` hooks, The pre-push command reports **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 `check-hooks-apply` and `check-useless-excludes`: they declare no `stages:`, so they run at every
stage including this one. Fourteen is the count of repo-defined pre-push hooks. 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 ## The pre-push gate
Fourteen hooks, in config order. Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
**Core checks** **Core checks**
@@ -74,7 +85,7 @@ drift in generated text.
| Hook | Guards | | Hook | Guards |
|---|---| |---|---|
| `check-release-needed` | on push to `main` only — fails if files exposed via `.pre-commit-hooks.yaml` changed since the last tag | | `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`, 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 and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). The
@@ -87,8 +98,9 @@ loudly (`Error: jq is required but not installed`).
## Skill and agent context gates (ADR-0020) ## Skill and agent context gates (ADR-0020)
The `skill-size-check` pre-commit hook, scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$`, The `skill-size-check` pre-commit hook, scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$`,
runs `scripts/skill-size-check.sh`. That scope means it never lints `docs/research/examples/` runs `scripts/skill-size-check.sh`. That scope means it never lints the
reference skills. It is also shipped to external repos as `kyberforge-skill-size-check` (see `plugins/kyberforge/docs/research/examples/` reference skills. It is also shipped to external repos
as `kyberforge-skill-size-check` (see
[External consumers](#external-consumers-the-root-pre-commit-hooksyaml)). [External consumers](#external-consumers-the-root-pre-commit-hooksyaml)).
### Two independent gate families, neither replaced the other ### Two independent gate families, neither replaced the other
@@ -107,14 +119,13 @@ reference skills. It is also shipped to external repos as `kyberforge-skill-size
| `description` characters | 250 | 400 | the YAML-**folded** value | | `description` characters | 250 | 400 | the YAML-**folded** value |
| body words | 600 | 900 | **body only** — everything after the frontmatter's closing `---` | | body words | 600 | 900 | **body only** — everything after the frontmatter's closing `---` |
Plus three hard FAILs with no suggestion tier: Plus two hard FAILs with no suggestion tier:
- **A missing, valueless or `null` `description:`.** Not a skip. The description is the one field - **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 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 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 *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.) below early-returned on the genuinely empty folded value — exit 0, zero output, on a blocking gate.)
- **Every boundary-clause routing target must resolve** to a real skill or agent.
- **Every `references/<file>.md` a body names must exist** on disk. A dispatch table pointing at a - **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 file that was never written is a silently dead branch, and nothing else in the gate/audit/vale
stack notices it. stack notices it.
@@ -122,6 +133,35 @@ Plus three hard FAILs with no suggestion tier:
A file can sit well inside one family and fail the other. 2,770 whole-file words is a conformance 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. 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 **terminal** (not a compound modifier) **and** either written in route notation (`/name` for any name; `-> name` only when the name is hyphenated — see the gap below) **or** corroborated by another target in the same sentence that *does* resolve |
| **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.
**Known gap: the arrow form only works for hyphenated names.** Target extraction is built on
`NAME_HYPH` (`scripts/skill-size-check.sh:543`), which requires at least one hyphen, and
`ARROW_BOUNDARY` (`:561`) inherits that. So `-> gitea-prs` is extracted and checked, while
`-> triage` is not extracted at all — no ERROR, no SUGGESTION, exit 0. The unicode arrow `→` is not
recognised in either case. This makes the SUGGESTION's own advice unsafe for a single-word skill:
taking it silences the finding rather than checking it. `/name` has no such restriction and is the
form to prefer. Tracked as a defect; `tests/test-adr0020-targets.sh` has one arrow case and its
target happens to be hyphenated, so nothing currently covers this.
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 ### Target resolution walk
Resolution walks up **from the file being checked** — never from the script's own location. Deriving Resolution walks up **from the file being checked** — never from the script's own location. Deriving
@@ -176,10 +216,13 @@ Three more, deterministic to measure but judgment to act on:
The hook is declared `verbose: true` so the SUGGESTION tier is audible. pre-commit prints nothing at 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 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. suggestion is swallowed, which is exactly the invisibility ADR-0013 records for Vale warnings.
ADR-0020's arithmetic depends on it: writing to the 400-char FAIL lands the preload at 39 × 400 = ADR-0020's preload arithmetic depends on it: writing to the 400-char FAIL delivers roughly half the
15,600 chars (a 33% cut off 23,427); writing to the 250-char SUGGESTION lands at 9,750 (58%). The cut that writing to the 250-char SUGGESTION does, so the intended saving depends entirely on that
halving depends entirely on that tier being visible. It costs nothing on a clean file — the script tier being visible. The numbers, and the measurement method behind them, are not restated here —
prints only findings. 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 ### Duplicated constants
@@ -637,8 +680,10 @@ remote *before* any network call, so it does not join the pair above.
enforcement table (deterministic vs. auditor judgment), and every rejected alternative 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 - `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 executable-trust gate, and the version-pinned allow key
- `docs/adr/0017` / `0015` / `0014` — plugin content sync, apm-generated manifests, committed Vale - `docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md`,
styles `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 - `docs/spec/architecture.md` — directory structure, install pipeline, what is generated and what is
hand-authored hand-authored
- `.pre-commit-config.yaml` — the hooks themselves, with inline rationale comments - `.pre-commit-config.yaml` — the hooks themselves, with inline rationale comments

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

@@ -1,7 +1,7 @@
{ {
"name": "bin", "name": "bin",
"version": "1.1.3", "version": "1.1.5",
"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.1.5",
"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.1.5
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/git/.claude-plugin/plugin.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "git", "name": "git",
"version": "1.3.3", "version": "1.3.5",
"description": "Skills for working with Git \u2014 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.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

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

@@ -1,7 +1,7 @@
{ {
"name": "git", "name": "git",
"version": "1.3.3", "version": "1.3.5",
"description": "Skills for working with Git \u2014 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.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/git/apm.yml
View File

@@ -1,6 +1,6 @@
name: git name: git
version: 1.3.3 version: 1.3.5
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.
author: author:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net

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

@@ -1,7 +1,7 @@
{ {
"name": "gitea", "name": "gitea",
"version": "1.3.4", "version": "1.3.6",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API \u2014 the forge's own objects, as distinct from the local git clone.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

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

@@ -1,7 +1,7 @@
{ {
"name": "gitea", "name": "gitea",
"version": "1.3.4", "version": "1.3.6",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.", "description": "Skills and agents for working with a Gitea forge through its HTTP API \u2014 the forge's own objects, as distinct from the local git clone.",
"author": { "author": {
"name": "Defame1297", "name": "Defame1297",
"email": "defame1297@rkdr.net", "email": "defame1297@rkdr.net",

4
plugins/gitea/apm.yml
View File

@@ -1,6 +1,6 @@
name: gitea name: gitea
version: 1.3.4 version: 1.3.6
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.
author: author:
name: Defame1297 name: Defame1297
email: defame1297@rkdr.net email: defame1297@rkdr.net

17
scripts/check-vale-style-sync.sh
View File

@@ -127,8 +127,8 @@ for ini in "$SKILL_INI" "$AGENT_INI"; do
err "$rel_ini has no section whose BasedOnStyles names Kyberforge — every rule the audit prefilters on lives in that style" err "$rel_ini has no section whose BasedOnStyles names Kyberforge — every rule the audit prefilters on lives in that style"
fi fi
# Per-rule overrides are the third way to retire a rule without touching a # Per-rule overrides are the third way to retire a rule without touching a
# style file or a glob. CONTEXT.md's "Vale audit prefilter" entry: "Every rule # style file or a glob. Per ADR-0013, every rule is `level: error` and every
# is `level: error` and every alert is a FAIL — no ignorable tier". Vale's exit # alert is a FAIL — there is no ignorable tier. Vale's exit
# code keys on `error` alerts alone, so any override that leaves a rule at # code keys on `error` alerts alone, so any override that leaves a rule at
# anything other than `error` still lints the file, still exits 0, and still # anything other than `error` still lints the file, still exits 0, and still
# shows `Passed` in pre-commit. The glob probe below cannot backstop this: it # shows `Passed` in pre-commit. The glob probe below cannot backstop this: it
@@ -175,9 +175,10 @@ for ini in "$SKILL_INI" "$AGENT_INI"; do
fi fi
done done
# KyberforgeCopilot is agent-audit's alone — CONTEXT.md describes it as "scoped # KyberforgeCopilot is agent-audit's alone — ADR-0013 scopes it to `.agent.md`
# only to `.agent.md` files for the Copilot-only 'Use proactively has no effect' # files only, for the Copilot-only 'Use proactively has no effect' check, and
# check". The loop above deliberately asserts only `Kyberforge`, since # records that it must not be extended to `.md` files. The loop above
# deliberately asserts only `Kyberforge`, since
# skill-audit's copy legitimately has no Copilot style, so dropping # skill-audit's copy legitimately has no Copilot style, so dropping
# `, KyberforgeCopilot` from agent-audit's `[**/*.agent.md]` section unloaded the # `, KyberforgeCopilot` from agent-audit's `[**/*.agent.md]` section unloaded the
# whole style silently: no glob broke, the styles/ diff above stayed clean (the # whole style silently: no glob broke, the styles/ diff above stayed clean (the
@@ -353,10 +354,10 @@ while IFS='|' read -r skill rel scope; do
# `.pre-commit-config.yaml`'s regex correctly no longer matches it and that's # `.pre-commit-config.yaml`'s regex correctly no longer matches it and that's
# not drift. `demo.agent.md` is the real, current shape and is `shared`. # not drift. `demo.agent.md` is the real, current shape and is `shared`.
# #
# The two `.claude/`-prefixed probes carry the location-independence CONTEXT.md # The two `.claude/`-prefixed probes carry the location-independence property: a
# asserts: "A `SKILL.md` outside `plugins/` (e.g. project-scope # `SKILL.md` outside `plugins/` (e.g. project-scope
# `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted # `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted
# normally — the globs constrain filename shape, not location." Every other # normally — the globs constrain filename shape, not location. Every other
# probe here starts with `plugins/`, so narrowing a glob to a `plugins/`-shaped # probe here starts with `plugins/`, so narrowing a glob to a `plugins/`-shaped
# path (`[**/SKILL.md]` -> `[**/.apm/skills/*/SKILL.md]`) left all of them # path (`[**/SKILL.md]` -> `[**/.apm/skills/*/SKILL.md]`) left all of them
# matching while the project-scope shape started linting as `0 errors ... in 0 # matching while the project-scope shape started linting as `0 errors ... in 0

16
scripts/sync-marketplace-mirror.sh
View File

@@ -6,7 +6,7 @@ set -euo pipefail
# that same file at .claude-plugin/marketplace.json directly, but also has a legacy # that same file at .claude-plugin/marketplace.json directly, but also has a legacy
# convention path at .github/plugin/marketplace.json (see # convention path at .github/plugin/marketplace.json (see
# plugins/kyberforge/docs/research/docs/github-copilot-plugins/marketplace.md) -- and # plugins/kyberforge/docs/research/docs/github-copilot-plugins/marketplace.md) -- and
# CONTEXT.md documents that path as a mirror of the Claude output, not a separate apm # that path is a mirror of the Claude output, not a separate apm
# output profile (apm only ships "claude" and "codex" mappers; codex writes a # output profile (apm only ships "claude" and "codex" mappers; codex writes a
# differently-shaped file to .agents/plugins/marketplace.json, not this path). This # differently-shaped file to .agents/plugins/marketplace.json, not this path). This
# script keeps that legacy mirror byte-identical to .claude-plugin/marketplace.json # script keeps that legacy mirror byte-identical to .claude-plugin/marketplace.json
@@ -60,7 +60,19 @@ fi
if [[ "$CHECK" -eq 1 ]]; then if [[ "$CHECK" -eq 1 ]]; then
if [[ ! -f "$DST" ]] || ! diff -q "$SRC" "$DST" >/dev/null 2>&1; then if [[ ! -f "$DST" ]] || ! diff -q "$SRC" "$DST" >/dev/null 2>&1; then
echo "DRIFT $DST: out of sync with .claude-plugin/marketplace.json" >&2 echo "DRIFT $DST: out of sync with .claude-plugin/marketplace.json" >&2
echo "Fix: bash scripts/sync-marketplace-mirror.sh" >&2 # The runnable command gets a line to ITSELF, and the rationale gets its own
# echo. It was one line -- `Fix: bash scripts/sync-marketplace-mirror.sh --
# apm ships no output profile...` -- which put the prose after `--`, the
# POSIX end-of-options marker, so copy-pasting the Fix line ran this script
# with ~24 stray argv entries: `${1:-}` was `--` (so CHECK stayed 0 and no
# shift happened), `[[ $# -eq 0 ]]` failed, and the tool meant to fix the
# drift answered with its own usage error and exit 1. The backticks around
# `apm pack` made it worse: the paste also command-substituted a real
# `apm pack` run before the script was even reached. Hence plain quotes
# below too. Keep the command alone on its line.
echo "Fix: run, from the repository root:" >&2
echo " bash scripts/sync-marketplace-mirror.sh" >&2
echo "Note: apm ships no output profile targeting this path, so 'apm pack' does not refresh it. Expecting it to is exactly the drift this script and its pre-push hook exist to prevent." >&2
exit 1 exit 1
fi fi
exit 0 exit 0

14
tests/run-tests.sh
View File

@@ -13,11 +13,13 @@
# dev binary, the other 15 suites still tell you something, and turning that # dev binary, the other 15 suites still tell you something, and turning that
# into a red run would just train people to ignore red. # into a red run would just train people to ignore red.
# * as a GATE (the run-tests pre-push hook): a skip is a SETUP ERROR, not a # * as a GATE (the run-tests pre-push hook): a skip is a SETUP ERROR, not a
# legitimate state. AGENTS.md documents vale, apm and jq as required pre-push # legitimate state. README.md's Prerequisites table documents vale, apm and
# dependencies, so a suite that cannot run on the machine doing the pushing # python3/PyYAML -- the dependencies these suites actually guard on -- as
# means the machine is misconfigured -- and pre-commit prints NOTHING for a # required pre-push, so a suite that cannot run on the machine doing the
# passing hook, so the skip list below is swallowed entirely. On a vale-less # pushing means the machine is misconfigured -- and
# PATH that silently shipped a green gate having verified 15 of 17 suites. # pre-commit prints NOTHING for a passing hook, so the skip list below is
# swallowed entirely. On a vale-less PATH that once silently shipped a
# green gate having verified 15 of the 17 suites that existed then.
# Exactly the vacuous-pass class the rest of this file exists to close. # Exactly the vacuous-pass class the rest of this file exists to close.
# #
# Deliberately its own switch, NOT folded into # Deliberately its own switch, NOT folded into
@@ -258,7 +260,7 @@ fi
# here (not just referenced) because this block goes to stderr and is what a # here (not just referenced) because this block goes to stderr and is what a
# pre-push reader actually gets handed. # pre-push reader actually gets handed.
if [[ "$STRICT" == true && ${#SKIPPED[@]} -gt 0 ]]; then if [[ "$STRICT" == true && ${#SKIPPED[@]} -gt 0 ]]; then
echo "Error: --strict and ${#SKIPPED[@]} suite(s) skipped. Run as a gate, a skip is a SETUP ERROR on this machine, not a legitimate state: AGENTS.md documents vale, apm and jq as required pre-push dependencies, so every suite is expected to be runnable here. Install what each suite names below and re-run; do not skip the hook." >&2 echo "Error: --strict and ${#SKIPPED[@]} suite(s) skipped. Run as a gate, a skip is a SETUP ERROR on this machine, not a legitimate state: README.md's Prerequisites table documents vale, apm and python3/PyYAML — what these suites guard on — as required pre-push dependencies, so every suite is expected to be runnable here. Install what each suite names below and re-run; do not skip the hook." >&2
sidx=0 sidx=0
for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do for s in ${SKIPPED[@]+"${SKIPPED[@]}"}; do
echo " $s" >&2 echo " $s" >&2

16
tests/test-check-vale-style-sync.sh
View File

@@ -457,8 +457,8 @@ fi
# --- 9b. Exits 1 when a per-rule override leaves a rule at anything but error --- # --- 9b. Exits 1 when a per-rule override leaves a rule at anything but error ---
# The third way to switch a rule off without touching a style file or a glob. # The third way to switch a rule off without touching a style file or a glob.
# CONTEXT.md's "Vale audit prefilter" entry: "Every rule is `level: error` and # Per ADR-0013, every rule is `level: error` and every alert is a FAIL -- there
# every alert is a FAIL -- no ignorable tier". Vale's exit code keys on `error` # is no ignorable tier. Vale's exit code keys on `error`
# alerts alone, so any such override leaves the glob intact, the styles # alerts alone, so any such override leaves the glob intact, the styles
# byte-identical, and the run at `0 errors`, exit 0, `Passed`. # byte-identical, and the run at `0 errors`, exit 0, `Passed`.
# #
@@ -553,9 +553,9 @@ fi
# equality check applies, and case 10's probe still passed because it keys on a # equality check applies, and case 10's probe still passed because it keys on a
# Kyberforge alert. Verified dead by probing a `.agent.md` carrying # Kyberforge alert. Verified dead by probing a `.agent.md` carrying
# "Use proactively": 0 alerts under the broken config, KyberforgeCopilot. # "Use proactively": 0 alerts under the broken config, KyberforgeCopilot.
# ProactivePhrase under the shipped one. CONTEXT.md describes the style as # ProactivePhrase under the shipped one. ADR-0013 scopes the style to
# "scoped only to `.agent.md` files for the Copilot-only 'Use proactively has # `.agent.md` files only, for the Copilot-only 'Use proactively has no effect'
# no effect' check", so shipping it unloaded is drift. # check, so shipping it unloaded is drift.
echo "" echo ""
echo "--- exits 1 when the shipped KyberforgeCopilot style is named by no BasedOnStyles ---" echo "--- exits 1 when the shipped KyberforgeCopilot style is named by no BasedOnStyles ---"
FIXTURE11C="$(make_fixture)" FIXTURE11C="$(make_fixture)"
@@ -609,9 +609,9 @@ fi
# still matched all of them and the check passed -- while a project-scope # still matched all of them and the check passed -- while a project-scope
# `.claude/skills/foo/SKILL.md` started linting as `0 errors ... in 0 files`, # `.claude/skills/foo/SKILL.md` started linting as `0 errors ... in 0 files`,
# exit 0, hook `Passed`: the exact failure the script's own header comment says # exit 0, hook `Passed`: the exact failure the script's own header comment says
# it exists to catch. CONTEXT.md: "A `SKILL.md` outside `plugins/` (e.g. # it exists to catch. A `SKILL.md` outside `plugins/` (e.g. project-scope
# project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and # `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted
# gets linted normally -- the globs constrain filename shape, not location." # normally -- the globs constrain filename shape, not location.
# These narrowings are still valid glob syntax and break no `plugins/`-shaped # These narrowings are still valid glob syntax and break no `plugins/`-shaped
# file, so only a non-`plugins/` probe path catches them. # file, so only a non-`plugins/` probe path catches them.
echo "" echo ""

9
tests/test-run-tests.sh
View File

@@ -392,10 +392,11 @@ fi
# --- 10. --strict turns a skip into a failure, and names the suite AND the reason --- # --- 10. --strict turns a skip into a failure, and names the suite AND the reason ---
# Graceful skipping is right for an ad-hoc run and wrong for a gate. At pre-push a # Graceful skipping is right for an ad-hoc run and wrong for a gate. At pre-push a
# suite exiting 77 means a dependency AGENTS.md documents as required is missing # suite exiting 77 means a dependency README.md's Prerequisites table documents
# on the pushing machine -- and pre-commit prints nothing at all for a passing # as required is missing on the pushing machine -- and pre-commit prints nothing
# hook, so the skip list this script writes to stdout was swallowed whole. A # at all for a passing hook, so the skip list this script writes to stdout was
# vale-less PATH shipped a green gate having verified 15 of 17 suites. # swallowed whole. A vale-less PATH once shipped a green gate having verified
# 15 of the 17 suites that existed then.
# #
# The reason is asserted, not just the name: "something was skipped" leaves the # The reason is asserted, not just the name: "something was skipped" leaves the
# reader with no idea which binary to install, which is most of why the swallowed # reader with no idea which binary to install, which is most of why the swallowed

7
tests/test-vale-wrap.sh
View File

@@ -451,8 +451,11 @@ fi
# cover anything new: it omitted scripts/lib/batch-run.sh — the shared runner # cover anything new: it omitted scripts/lib/batch-run.sh — the shared runner
# this branch introduced, whose own header (batch-run.sh:9-11) documents it as # this branch introduced, whose own header (batch-run.sh:9-11) documents it as
# bash-3.2-safe — along with four other scripts/*.sh. Deriving the list means a # bash-3.2-safe — along with four other scripts/*.sh. Deriving the list means a
# new script is covered the moment it lands. AGENTS.md names bash 3.2 as an # new script is covered the moment it lands. The script headers name bash 3.2 as
# explicit repo target, so the scope is four globs, each floor-asserted below: # an explicit repo target -- scripts/lib/batch-run.sh:10 ("all three callers are
# explicitly bash-3.2-safe") and providers/claude-code/statusline-command.sh:100
# ("macOS's system bash, and an explicit repo target") -- so the scope is four
# globs, each floor-asserted below:
# - scripts/**/*.sh — repo tooling and pre-commit hook scripts # - scripts/**/*.sh — repo tooling and pre-commit hook scripts
# - tests/*.sh — the runners and every regression test # - tests/*.sh — the runners and every regression test
# - plugins/*/.apm/**/*.sh — the scripts plugins ship to users # - plugins/*/.apm/**/*.sh — the scripts plugins ship to users