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

Compare commits

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

9 Commits
v2.0.0 ... 65bac15257

Author SHA1 Message Date
Defame1297
65bac15257 chore(apm): correct git and gitea published descriptions and regenerate 
Why: both plugins' published descriptions named capabilities that do not exist
and omitted ones that do. `gitea` advertised wikis — no wiki skill exists and
`grep -ri wiki plugins/gitea/.apm/` is empty — while omitting gitea-branches and
gitea-files. `git` advertised pull requests, which are gitea's, while omitting
pc-author/pc-run, git-submodules and git-workflow. These are compiled into
plugin.json and both marketplace.json files, so they are published metadata, not
internal notes.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

10
.claude-plugin/marketplace.json
View File

@@ -1,7 +1,7 @@
{
"name": "holocron",
"description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
"version": "0.4.2",
"version": "0.4.3",
"owner": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
@@ -24,15 +24,15 @@
},
{
"name": "git",
"description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.",
"version": "1.3.3",
"description": "Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.",
"version": "1.3.4",
"category": "Version Control",
"source": "./plugins/git"
},
{
"name": "gitea",
"description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.",
"version": "1.3.4",
"description": "Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.",
"version": "1.3.5",
"category": "Version Control",
"source": "./plugins/gitea"
},

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

@@ -1,7 +1,7 @@
{
"name": "holocron",
"description": "AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.",
"version": "0.4.2",
"version": "0.4.3",
"owner": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",
@@ -24,15 +24,15 @@
},
{
"name": "git",
"description": "Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.",
"version": "1.3.3",
"description": "Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.",
"version": "1.3.4",
"category": "Version Control",
"source": "./plugins/git"
},
{
"name": "gitea",
"description": "Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.",
"version": "1.3.4",
"description": "Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.",
"version": "1.3.5",
"category": "Version Control",
"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
# the opt-out reinstated exactly the silent vacuous pass the script was
# written to kill, one level up -- the run showed a bare `Passed` and
# AGENTS.md's instruction to read that summary line was impossible to
# the documented instruction to read that summary line was impossible to
# follow in the one situation the opt-out exists for. The script's clean
# output is a single line, so this costs one line per push.

63
AGENTS.md
View File

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

221
CONTEXT.md
View File

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

2
LESSONS.md
View File

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

126
README.md Normal file
View File

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

350
apm.lock.yaml
View File

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

10
apm.yml
View File

@@ -52,7 +52,7 @@ marketplace:
# top-level apm.yml description:/version: above are NOT inherited into the
# compiled output despite being used elsewhere (e.g. by `apm audit`).
description: AI development skills for Claude Code and GitHub Copilot CLI — factory, design, implement, review, and cross-cutting workflows.
version: 0.4.2
version: 0.4.3
owner:
name: Defame1297
email: defame1297@rkdr.net
@@ -89,15 +89,15 @@ marketplace:
category: Utilities
- name: git
description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.
description: Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.
source: ./plugins/git
version: 1.3.3
version: 1.3.4
category: Version Control
- name: gitea
description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.
description: Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.
source: ./plugins/gitea
version: 1.3.4
version: 1.3.5
category: Version Control
- 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 "Provider-agnostic issue tracker" glossary entry in CONTEXT.md is updated in the same workstream to remove the file-based phase framing. The `providers/gitea/` adapter path described in ADR-0011 was never implemented — Gitea integration runs entirely via MCP, not a provider adapter.
The "Provider-agnostic issue tracker" glossary entry in CONTEXT.md is updated in the same workstream to remove the file-based phase framing. (Amended 2026-08-17: the CONTEXT.md trim renamed that entry to **Issue**; it still records Gitea as this repo's canonical tracker and still tells skills to say "linked issue" generically.) The `providers/gitea/` adapter path described in ADR-0011 was never implemented — Gitea integration runs entirely via MCP, not a provider adapter.

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

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

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

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

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

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

27
docs/spec/architecture.md
View File

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

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

@@ -0,0 +1,644 @@
# Enforcement gates
Reference for this repo's pre-commit and pre-push hooks: what each one guards, what its numbers
mean, and which shapes were tried and rejected. Read it when a gate fails, before changing anything
in `.pre-commit-config.yaml`, or before "fixing" something that looks like an inconsistency — several
of the oddities documented here are load-bearing and have already been re-litigated once.
`AGENTS.md` carries only the operative rules an agent needs in the moment. The reasoning lives here.
---
## Running the gates
| Command | Scope |
|---|---|
| `pre-commit run --all-files` | the commit-stage hooks |
| `pre-commit run --hook-stage pre-push --all-files` | the whole push gate, one command |
| `pre-commit run skill-size-check --all-files` | just the ADR-0020 size/context gates |
Install hooks via `pc-run`, wiring **all three stages**. This repo's `.pre-commit-config.yaml` has no
`default_install_hook_types`, so a plain install silently skips `commit-msg` (Conventional Commits)
and `pre-push` (everything below).
The pre-push command reports **16** hooks, not 14. The extra two are pre-commit's own `meta` hooks,
`check-hooks-apply` and `check-useless-excludes`: they declare no `stages:`, so they run at every
stage including this one. Fourteen is the count of repo-defined pre-push hooks.
## The pre-push gate
Fourteen hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
**Core checks**
| Hook | Guards |
|---|---|
| `run-tests` | `bash tests/run-tests.sh --strict` — the whole suite, skips fatal (see [Tests](#tests)) |
| `check-manifests` | `marketplace.json` and `plugin.json` paths resolve (needs `jq`) |
**Generated-content drift gates**
| Hook | Guards |
|---|---|
| `check-plugin-content-sync` | each plugin's flat `skills/agents/commands/hooks` mirror matches `.apm/` (issue #90) |
| `check-marketplace-mirror-sync` | `.github/plugin/marketplace.json` is byte-identical to `.claude-plugin/marketplace.json` — no apm output profile targets that path |
| `check-vale-style-sync` | skill-audit's Vale copy matches agent-audit's canonical copy, plus six glob-coverage probes (see [Vale](#vale)) |
| `check-scope-walkup-sync` | `validate.sh`, `validate-provenance.sh`, `new-agent.sh` and `new-skill.sh`'s four independent `$HOME`/`.git`/`apm.yml` walk-up ports still agree behaviorally |
| `check-executables-allow-sync` | root `apm.yml`'s `executables.allow` key names kyberforge's actual version (see [apm gates](#apm-gates)) |
`check-executables-allow-sync` is the odd one in this group: it guards a *silent failure* rather than
drift in generated text.
**Artifact validators**
| Hook | Guards |
|---|---|
| `check-apm-agents-valid` | runs agent-audit's `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md` (see [Agent files](#agent-files-take-the-description-gates-not-the-body-gate)) |
**apm's own gates**
| Hook | Guards |
|---|---|
| `apm-marketplace-check` | every `marketplace.packages[]` entry resolves, including network reachability of remote refs |
| `apm-audit-ci` | `apm audit --ci` once per manifest — root plus each of the six plugin packages |
| `apm-pack-check-clean` | `apm pack --check-versions --check-clean --dry-run` — the compiled marketplace still matches what `apm.yml` + `.apm/` would generate, and per-package versions agree with the `per_package` strategy |
**Host validators** (both need the `claude` CLI on PATH)
| Hook | Guards |
|---|---|
| `validate-plugins` | `claude plugin validate --strict` on every plugin directory |
| `validate-marketplace` | `claude plugin validate --strict` on the root marketplace manifest |
**Release**
| Hook | Guards |
|---|---|
| `check-release-needed` | on push to `main` only — fails if files exposed via `.pre-commit-hooks.yaml` changed since the last tag |
Four of these shell out to `apm`: `apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`,
and `check-plugin-content-sync` (via `scripts/sync-plugin-content.sh`, which wraps `apm pack`). The
first and third are bare `apm …` entries and the second is a `bash -c` loop calling `apm` once per
package, so without the CLI the push dies with an unhelpful "command not found". Install with
`apm-install`, or `curl -sSL https://aka.ms/apm-unix | sh`; verify with `apm --version`. `jq` is
needed by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh` — those at least fail
loudly (`Error: jq is required but not installed`).
## Skill and agent context gates (ADR-0020)
The `skill-size-check` pre-commit hook, scoped to `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$`,
runs `scripts/skill-size-check.sh`. That scope means it never lints `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)).
### Two independent gate families, neither replaced the other
**Family 1 — agentskills.io spec backstop** (unchanged, conformance not quality):
| Constant | Value | Measured over |
|---|---|---|
| `MAX_LINES` | 500 | whole file, **frontmatter included** |
| `MAX_WORDS` | 2,770 | whole file, **frontmatter included** |
**Family 2 — ADR-0020 context budget** (measured differently, on purpose):
| Check | SUGGESTION | FAIL | Measured over |
|---|---|---|---|
| `description` characters | 250 | 400 | the YAML-**folded** value |
| body words | 600 | 900 | **body only** — everything after the frontmatter's closing `---` |
Plus three hard FAILs with no suggestion tier:
- **A missing, valueless or `null` `description:`.** Not a skip. The description is the one field
preloaded into every session, so a gate that declines to measure it reports green. (This is not
hypothetical: `description:` with no value followed by `model: sonnet` let a line regex capture the
*next* key, which looked non-empty, so the "missing or empty" branch never fired and every gate
below early-returned on the genuinely empty folded value — exit 0, zero output, on a blocking gate.)
- **Every 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
file that was never written is a silently dead branch, and nothing else in the gate/audit/vale
stack notices it.
A file can sit well inside one family and fail the other. 2,770 whole-file words is a conformance
backstop; 900 body-only words is a quality gate. Conflating them is what produced the current state.
### Target resolution walk
Resolution walks up **from the file being checked** — never from the script's own location. Deriving
it from `${BASH_SOURCE}` leaked holocron's 39-skill universe into every consumer repo running the
hook through pre-commit, so a consumer skill routing to `skill-audit` resolved against a plugin it
had never installed.
The walk finds an **authoring root**: the nearest ancestor holding `plugins/*/.apm/skills` or
`plugins/*/.apm/agents`, falling back to the nearest ancestor holding `.git`. **Two passes, not one
interleaved walk**, so a nested `.git` (a submodule, a sub-package worktree) cannot beat a real
monorepo root further up.
The universe is then:
1. every skill and agent under `<root>/plugins/*/` — sibling plugins resolve, which is what a
monorepo means;
2. the checked file's own apm package;
3. the packages that package declares in **its own** `apm.yml` `dependencies.apm`.
The **root** manifest's `dependencies:` block is not read, and no plugin here declares a cross-plugin
apm dependency — none needs to.
Deployed `.claude/` / `.agents/` trees are consulted **only** when the walk found no plugin monorepo
root, whether it landed on a bare `.git` ancestor or on nothing at all. That is the consumer case.
**The gate keys on which of the two passes matched, never on whether the root contributed a new
name.** A name-count delta looks equivalent and is not: `_collect_authoring_root()` re-collects the
checked file's own plugin, whose names the earlier steps already added, so a single-plugin monorepo
shows a delta of zero and would wrongly reach for the deployed trees — including the user's global
`~/.claude/skills`, making the verdict depend on what happens to be installed.
Why it matters: those trees are gitignored `apm install` output, present only on a machine that has
run it. Four cross-plugin targets here (`gitea-branches` → `git-branches`, `gitea-branches` →
`git-history`, `gitea-issues` → `git-branches`, `gitea-workflow` → `git-workflow`) once resolved
through `.claude/skills/` alone, so **the same commit measured 2 dangling targets on a developer
machine and 6 on a fresh clone**. A gate shipping hot with no baseline cannot give two answers.
Verified fixed: running the hook over a tree holding only `plugins/` and the root `apm.yml`, with no
`.claude/` or `.agents/` anywhere, produces findings identical to the working tree — **26 description
FAILs, 9 body FAILs, 2 dangling targets, 0 missing references, 58 SUGGESTIONs**.
### SUGGESTION-only checks
Three more, deterministic to measure but judgment to act on:
- a description with **no boundary clause at all**;
- a `## Gotchas` section with **more than five entries**;
- a `## Gotchas` section over **25% of the body**.
### `verbose: true` is load-bearing
The hook is declared `verbose: true` so the SUGGESTION tier is audible. pre-commit prints nothing at
all for a passing hook, and a SUGGESTION deliberately does not fail — without verbose every
suggestion is swallowed, which is exactly the invisibility ADR-0013 records for Vale warnings.
ADR-0020's arithmetic depends on it: writing to the 400-char FAIL lands the preload at 39 × 400 =
15,600 chars (a 33% cut off 23,427); writing to the 250-char SUGGESTION lands at 9,750 (58%). The
halving depends entirely on that tier being visible. It costs nothing on a clean file — the script
prints only findings.
### Duplicated constants
`skill-audit`'s `validate.sh` holds a second copy of the four ADR-0020 constants
(`DESC_SUGGEST_CHARS` / `DESC_MAX_CHARS` / `BODY_SUGGEST_WORDS` / `BODY_MAX_WORDS`), and
`agent-audit`'s `validate.sh` holds a third copy of the two description constants. They are copied
rather than imported because a cache-installed plugin's scripts cannot read files outside their own
plugin directory. `tests/test-skill-size-check.sh` asserts the copies agree, so drift fails CI rather
than silently letting an audit bless a skill the commit hook then rejects. The shared boundary
resolver block is embedded verbatim in all three scripts between `BEGIN`/`END ADR-0020 SHARED
BOUNDARY RESOLVER` markers and must stay byte-identical.
### `python3` and PyYAML are hard requirements
Both, and neither is a best-effort accelerator.
`python3` because the script measures the **folded** `description` value. Most descriptions here are
`>`-block scalars, so a regex over the raw lines measures indentation and newlines instead of the
value. Missing it fails the hook with an install pointer rather than skipping the ADR-0020 checks,
which would be a vacuous green. In practice it is already present — pre-commit is itself a Python
application.
**PyYAML** because the hand-rolled fallback frontmatter reader has been **removed deliberately**. It
disagreed with a real parser across the FAIL boundary — one corpus description measured 270
characters parsed and 412 unparsed — and a quoted `"description"` key or an explicit
`description: null` returned empty from it, silently skipping the description *and* routing checks. A
reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured,
which is the exact vacuous-green failure the `python3` check exists to avoid. `pip install pyyaml`
(or `python3 -m pip install PyYAML`, or the distro's `python3-yaml`) if the hook reports it missing.
## Agent files take the description gates, not the body gate
`check-apm-agents-valid` runs agent-audit's `validate.sh` over every real
`plugins/*/.apm/agents/*.agent.md`. It derives its expected file set from `git ls-files` — the pattern
`tests/run-bats.sh` established — so an agent file deleted from the worktree but still tracked fails
the run, and **discovering zero agent files is an error, not a pass**. An untracked *new* agent file
is still validated: the derivation is one-directional on purpose, so uncommitted work is not blocked
but also cannot bypass the gate.
The hook exists because `validate.sh` was previously exercised only by `check-scope-walkup-sync`,
against synthetic `mktemp` fixtures — it had never run against the agent files it governs. That is
how ADR-0016 could be amended to bless a `disallowedTools` frontmatter field while `validate.sh`'s
allowlist still rejected it: spec and enforcer disagreed and every gate stayed green.
Agents take the ADR-0020 **description** gates (agent-audit's `validate.sh` holds its own copy of
those two constants) and, deliberately, **no body word gate**. A skill body is loaded into the
caller's context and competes with the live conversation; an agent body becomes the system prompt of
a *fresh* context. The rationale for the 900-word FAIL does not transfer. A bats test pins that
absence in agent-audit's validator — adding a body gate there contradicts the ADR rather than fixing
an inconsistency.
**Be precise about the scope of that guarantee: it holds for the *validator*, not for the shared
script.** `scripts/skill-size-check.sh` applies its body gate to whatever path it is handed, and
```
bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md
```
exits 1 today with 900-word body FAILs on `git-orchestrate` (933), `gitea-orchestrate` (1,199) and
`apm-orchestrate` (1,080). Agent files escape only because the hook definitions filter on `SKILL.md`
— a file-pattern accident that happens to implement the design, not the design itself. **Do not
"extend" that hook's `files:` pattern to cover agents** on the assumption that the script already
knows the difference; doing so silently enforces a gate ADR-0020 declines to set.
## Current retrofit status
**The ADR-0020 gates ship hot, with no baseline file.** A shrinking baseline recording each
non-compliant skill's current numbers was considered and rejected in favour of hot gates.
Two independent hot gates are currently red, and the first will not warn you about the second.
| Gate | Current findings |
|---|---|
| `skill-size-check` | **26 of 39** descriptions and **9 of 39** bodies exceed their FAIL tier; 2 dangling targets; 58 SUGGESTIONs |
| `Kyberforge.CompositionNote` (Vale) | **10 errors across four skills**: `gitea-issues`, `gitea-labels-milestones`, `gitea-prs`, `gitea-workflow` |
`Kyberforge.CompositionNote` is the ADR-0020 Vale rule banning composition and architecture prose
from a description. Every Vale rule here is `level: error` with no ignorable tier, so touching any of
those four skills means fixing its prose findings as well as its size findings.
Consequence: editing a non-compliant skill *for any reason* means retrofitting it to the contract
first — a one-line fix to `gitea-prs` cannot be committed until that skill complies. This is
deliberate; it guarantees convergence and avoids a half-state. Tracked as Gitea issue **#99**.
Check where a skill stands before starting, and check **both** gates:
```
pre-commit run skill-size-check --all-files # size/context only
pre-commit run --all-files # size AND Vale
```
Scoping a retrofit off `skill-size-check` output alone leaves you blocked at the second gate.
## Vale
Install the `vale` binary — `brew install vale` (macOS), `snap install vale` (Linux),
`choco install vale` (Windows), or see <https://vale.sh/docs/vale-cli/installation/>. No `vale sync`
is needed: the `Kyberforge` styles are **committed** under
`plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/`, not downloaded
packages (ADR-0014).
### Two copies, one canonical
Wiring Vale as a deterministic prefilter for `skill-audit`/`agent-audit`'s Description dimension
(motivation: issue #84) is repo-specific, not part of the generic `lint` plugin, so it does not live
in `plugins/lint/` — and per ADR-0014 it no longer lives at the repo root either. It lives **twice**,
one copy per skill, both under `plugins/kyberforge/.apm/skills/`:
| Copy | Styles | `.vale.ini` sections |
|---|---|---|
| `agent-audit/assets/vale/` — **canonical** | `Kyberforge`, `KyberforgeCopilot` | `[**/agents/*.md]`, `[**/*.agent.md]` |
| `skill-audit/assets/vale/` — smaller duplicate | `Kyberforge` | `[**/SKILL.md]` |
Duplicated rather than shared because a plugin's cache-install copies only each skill's own files —
there is no cross-skill sharing to point at. `check-vale-style-sync` at pre-push is what keeps them
from drifting; `KyberforgeCopilot` is the one deliberate inequality, being scoped only to `.agent.md`
files for the Copilot-only "`Use proactively` has no effect" check.
### What Vale owns, and what stays LLM judgment
Eleven rule files across the two copies, six distinct rules:
| Rule | Vale scope | Bans | From |
|---|---|---|---|
| `Kyberforge.DescriptionOpener` | `text.frontmatter.description` | non-imperative openers ("This skill/agent…") | issue #84 |
| `Kyberforge.VagueWording` | `text.frontmatter.description` | vague capability wording ("helps with", "utilize", …) | issue #84 |
| `Kyberforge.PaddingPhrase` | `text` | generic "see `references/` for details" padding | issue #84 |
| `KyberforgeCopilot.ProactivePhrase` | `text.frontmatter.description` | `Use proactively` (no effect in Copilot) | issue #84 |
| `Kyberforge.SentenceOpenerThereIs` | `sentence` | "There is/are" sentence openers | ADR-0013 |
| `Kyberforge.CompositionNote` | `text.frontmatter.description` | architecture and composition prose in a description | ADR-0020 |
Vale covers the **pattern-matchable** sub-checks named in issue #84 plus, per ADR-0013, one
cherry-picked body-wide prose-pattern rule. Everything else stays LLM judgment: defaults-vs-menus,
why-rationale, the non-pattern-matchable body-discipline calls, near-miss exclusion strength, and
control calibration. New rules land directly in `styles/Kyberforge` and block immediately — there is
no trial tier.
The cherry-pick record, so it is not re-litigated:
- `Kyberforge.SentenceOpenerThereIs` **landed** — 22 held-out hits, both in-corpus hits clean
rewrites, zero suppressions needed.
- `Kyberforge.VagueQualifier` was cherry-picked and then **deleted**. 2 hits across the corpus as it
stood on 2026-08-08 (before the `.apm/` restructure): one marginal, and one unfixable false
positive — `caveman/SKILL.md` quotes `of course` as an example of filler, a mention rather than a
use — which forced the repo's only Vale suppression comments.
- `governance.md` and `CONTROLS.md` were evaluated as rule sources and **excluded**: nothing
prose-pattern-matchable to mine.
### Why every rule is `level: error`
Every alert is a FAIL, with no ignorable tier — same all-or-nothing model as shellcheck, the test
suite, and conventional-pre-commit. Graded severities do not work here: **Vale's exit code keys on
`error` alerts alone**, so a `warning` or `suggestion` rule exits 0, and pre-commit swallows a
passing hook's output. Such a rule would be invisible and would block nothing.
`MinAlertLevel` and `--minAlertLevel` are correspondingly **absent** from both `.vale.ini` files and
from the hook definitions. Under this model they are no-ops; adding one is not a missing knob.
The `verbose: true` escape hatch that makes `skill-size-check`'s SUGGESTION tier audible has no
analogue here — Vale has no tier to make audible.
### External consumers: the root `.pre-commit-hooks.yaml`
The root `.pre-commit-hooks.yaml` exposes both Vale copies (`kyberforge-vale-audit-skill`,
`kyberforge-vale-audit-agent`) plus `kyberforge-skill-size-check`, so any external repo can enforce
the same rules with `repo: <this-repo-url>, rev: <tag>` in its own `.pre-commit-config.yaml`.
pre-commit clones the pinned rev into its own cache, independent of whether Claude Code or the
`kyberforge` plugin is installed at all; the same mechanism covers CI via `pre-commit run
--all-files`. `skill-size-check` has no external asset dependency, so it needed no relocation under
ADR-0014 — only exposure.
This repo's own `vale-audit-prefilter-skill` / `-agent` hooks consume the **identical**
plugin-bundled copies via `repo: local`. Deliberately not a third root copy, and deliberately **not a
pinned self-reference** — a pinned self-reference would lint working-tree edits against the last
tagged release rather than against the change being made.
### Pre-commit
Two prefilter hooks, with `.apm/`-scoped `files:` patterns:
| Hook | Pattern |
|---|---|
| `vale-audit-prefilter-skill` | `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` |
| `vale-audit-prefilter-agent` | `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` |
Only the **authoring source** triggers them. A `SKILL.md` in the generated flat mirror matches
neither pattern, so prose findings surface only when you edit the file you are supposed to be
editing. Without the binary the hooks fail with a bare "command not found" and no install pointer.
**Two hooks, not one combined hook.** Both manifests split the prefilter in two precisely because a
single hook can point at only one copy, and that copy would silently 0-file-skip the other file
shape (see [A 0-file Vale run is NOT RUN](#a-0-file-vale-run-is-not-run)).
### The `.vale.ini` globs do no scoping
Each `.vale.ini`'s section globs are **path-agnostic** — `[**/SKILL.md]` for skill-audit's copy,
`[**/agents/*.md]` and `[**/*.agent.md]` for agent-audit's — and constrain filename *shape*, not
location: Vale's `*` crosses `/`. A `SKILL.md` outside `plugins/` (a project-scope
`.claude/skills/foo/SKILL.md`, say) still matches `[**/SKILL.md]` and gets linted normally.
All scoping therefore comes from the pre-commit hook's own `files:` regex and from the audit skills
passing one explicit file per invocation. The two manifests scope **differently on purpose**:
| Manifest | `-skill` | `-agent` |
|---|---|---|
| `.pre-commit-config.yaml` (pins this repo's layout) | `^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$` | `^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$` |
| `.pre-commit-hooks.yaml` (layout-agnostic for consumers) | `(^\|/)SKILL\.md$` | `(^\|/)agents/[^/]+\.md$\|\.agent\.md$` |
Narrowing a `.vale.ini` glob to a `plugins/`-shaped path to "tighten" it breaks the consumer case,
and `check-vale-style-sync`'s probe set is built to catch exactly that.
### `vale-wrap.sh`, never bare `vale`
Both audit skills' Step 1 and both pre-commit hooks call **each copy's own**
`scripts/vale-wrap.sh`, not `vale`. It works around a confirmed **Vale 3.15.2** limitation:
`text.frontmatter.description` silently stops matching on most — not all — multi-line descriptions.
Verified by reproduction on a deliberately-bad fixture, not assumed:
| Description scalar spanning 2+ lines | Vale's behaviour |
|---|---|
| `>` folded block | 0 alerts, exit 0 — **broken** |
| plain (unquoted) continuation lines | 0 alerts, exit 0 — **broken** |
| single- or double-quoted, wrapped | 0 alerts, exit 0 — **broken** |
| `\|` literal block | alerts fire, exit 1 — lints normally |
The wrapper flattens the three broken forms to a single-line scalar in a scratch copy — or, for the
rare value no inline scalar can spell verbatim, a `|-` block with one content line — padding with
blank lines so **every other line number is unchanged**. `|` literal blocks and single-line
descriptions pass through untouched. Most descriptions in this repo are `>` blocks, so before the
wrapper a bad description in any of the three broken forms sailed straight through the prefilter.
### The `--config` argv defect
Handed **no `--config` at all**, the wrapper falls back to its own sibling `assets/vale/.vale.ini`,
located from `${BASH_SOURCE[0]}` rather than from the cwd. That is why both manifests' `entry:` is
now the bare script path with **no argument after it**.
pre-commit prefixes only `entry[0]` with the hook-repo clone path (`cmd = (prefix.path(cmd[0]),
*cmd[1:])`), so every later argument resolves against the **consuming** repo's root. A `--config` in
`.pre-commit-hooks.yaml` therefore pointed at a path no consumer has and hard-failed every external
run with `E100 [--config] Runtime error`.
`.pre-commit-config.yaml` drops the argument too, deliberately keeping the two entries identical.
The local `repo: local` hook resolved its `--config` correctly only because the consuming repo *was*
this repo — and that divergence is why three review rounds exercised a path no external consumer
takes and missed the defect. **Do not reintroduce a `--config` to either manifest to make the local
run "explicit".**
An explicit `--config` from any other caller still wins, in all three argv forms (`--config X`,
`--config=/abs`, `--config=rel`), and a relative one resolves against the caller's cwd — matching
bare `vale`, not the repo root.
Both audit skills' Step 1 passes no `--config` either. Step 1 resolves the script relative to the
skill's own directory so the call works from an installed plugin cache; a relative `--config`
alongside it would resolve against the cwd instead, yielding `E100 Runtime error … does not exist`
and exit 2 — which both skills' fallback misreads as "vale unavailable" and silently downgrades to
full LLM judgment.
`tests/test-vale-wrap.sh` regression-tests this against **skill-audit's** copy specifically: its
fixtures are all `SKILL.md`-shaped, and only skill-audit's `.vale.ini` carries that glob section.
### A 0-file Vale run is NOT RUN
Vale reports 0 files only when the path it is handed matches **no glob section at all** — a
differently-named file, or a directory argument holding nothing that matches. That run prints
```
✔ 0 errors ... in 0 files.
```
and exits 0, indistinguishable from a clean pass. Both audits therefore treat a 0-file Vale run as
**NOT RUN** and fall back to full LLM judgment rather than reporting the Description dimension
clean.
### Pre-push
`vale` is a **pre-push** dependency too, not only pre-commit. `check-vale-style-sync` runs **six
glob-coverage probes** by invoking `vale --config` — one representative path per file shape the
prefilter is supposed to cover. They are the only assertions in the script that catch a `.vale.ini`
glob typo (`[**/SKILL.md]` → `[**/SKILLS.md]`), the failure mode where every text-level check stays
clean while vale lints zero files. As a warning this self-disabled on exactly that mutation and
exited 0, and since pre-commit swallows a passing hook's output the stderr line was never seen — the
hook reported `Passed`. Missing `vale` is therefore a hard failure here.
The opt-out is `CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1`, and **it is not `SKIP=`**: the hook
still runs and still asserts everything verifiable from file text, but the six probes do not, and its
summary says so explicitly —
```
Vale style sync check passed (text-level only, vale unavailable): … 0 glob probe(s) verified.
```
Use it only on a machine that genuinely cannot install `vale`, and read that line as "the glob axis
was not checked", not as a pass. The hook is `verbose: true` for exactly that reason — its clean
output is a single line, so it costs one line per push.
### Mentioning banned phrasing without tripping the rule
House convention: banned phrasing that must be **mentioned** rather than used goes in backticks or a
fenced code block. Vale skips code spans and fences, so no suppression is needed — which is why this
document quotes `Use proactively` and "There is/are" the way it does.
Inline `<!-- vale Rule = NO -->` is the fallback **only** where backticking is impossible. Use the
HTML-comment form; the MDX `{/* */}` form does not work in plain Markdown. The one time a rule forced
suppression comments, the rule was deleted instead (see the `VagueQualifier` entry above).
## Tests
```
bash tests/run-tests.sh # every test-*.sh plus the bats suite
bash tests/run-tests.sh --bats-only # just bats
```
First run auto-initializes the bats submodules; no manual `git submodule update` needed.
**Exit 77 = SKIPPED.** A suite that skips because a dependency is missing does **not** fail an ad-hoc
run. The pre-push hook invokes the same script as `--strict` (`RUN_TESTS_STRICT=1` is equivalent),
where a skip **does** fail the push: at pre-push a skip means one of the documented dependencies is
absent on this machine, so the gate would otherwise report success having run fewer suites than it
appears to. Without `--strict` the gate once went green having verified 15 of 17 suites on a
vale-less PATH, with the skip list swallowed. Without vale, three suites skip —
`test-check-vale-style-sync.sh`, `test-vale-hooks-consumer.sh`, `test-vale-wrap.sh` — and the strict
failure names each one and what to install.
`tests/run-bats.sh` derives the set of `.bats` files it expects from `git ls-files`, so a `.bats`
file deleted from the worktree but still tracked in the index fails the run rather than silently
shrinking the suite. Remove one with `git rm` (or stage the deletion) when intentional; an untracked
new `.bats` file is picked up and needs no ceremony.
Both discovery walks (`tests/run-bats.sh` and `tests/run-tests.sh`) exclude `apm_modules/`:
`apm install` materializes a full copy of every plugin there, and running a dependency's copy of a
`.bats` file breaks its relative path to the bats helpers — **167 spurious failures** before the
exclusion landed.
## apm gates
### `apm-audit-ci`
Runs `apm audit --ci` **once per manifest** — the root one and each of the six plugin packages —
because the root-only invocation audits the marketplace manifest and **nothing else**, and
`apm-pack-check-clean` does not parse plugin `dependencies:` blocks either. Verified: a malformed
dependency entry passes `apm pack --check-versions --check-clean --dry-run` and fails
`apm audit --ci` in that package's directory. Costs ~0.5s per package.
It verifies **exactly two things** per manifest and claims no more:
- **manifest-parse** — each `apm.yml` parses as a valid APM manifest. Unconditional; verified to fire
on a dependency entry missing its `git`/`path`/`registry` field (`Cannot parse apm.yml`).
- **lockfile-exists** — any package declaring dependencies has a consistent `apm.lock.yaml`.
Conditional, and vacuous while every plugin `apm.yml` declares `dependencies: {apm: [], mcp: []}`;
it arms itself the moment one does not (verified by adding a git dependency to
`plugins/lint/apm.yml`).
It does **not** enforce an org policy. apm discovers one from the git remote and only understands
github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints:
```
No org policy found at unknown; enforcement skipped
```
**Do not "fix" that with `policy.fetch_failure_default: block` in `apm.yml`.** apm's own message
suggests it; it was tried on a scratch copy and **rejected**. With no reachable policy source it does
not make the check meaningful, it makes it permanently red — `apm audit --ci` exits 1 with
`No org policy found at unknown (policy.fetch_failure_default=block)` on every push, forever. A gate
that can never go green is not a gate. Revisit only if this repo gains a policy source apm can reach.
It also does not scan for hidden Unicode: that scan is plain `apm audit`, a different mode (`--ci`
refuses to combine with `--file`/`--strip`/`--dry-run`/`PACKAGE`), and plain `apm audit` here reports
`No apm.lock.yaml found -- nothing to scan` and exits 0. Adding it would buy a second vacuous check.
### `check-executables-allow-sync`
apm gates a package's `hooks/` and `bin/` on an **exact `<package>#<version>` dictionary lookup** in
root `apm.yml`'s `executables.allow` (`apm_cli/security/executables.py`, `is_package_approved`).
There is no wildcard and no version-less form.
So bumping `plugins/kyberforge/apm.yml`'s `version:` without bumping the key **errors nowhere**: the
entry simply stops matching, the gate blocks the hook, kyberforge's `SessionStart` hook stops
deploying, and the apm install goes quietly stale — the exact failure ADR-0019 exists to end,
reintroduced through the mechanism meant to secure it. ADR-0019 records this as a live failure mode;
the release that shipped the hook hit it immediately.
`scripts/check-executables-allow-sync.sh` parses `version:` out of `plugins/kyberforge/apm.yml` and
asserts root `apm.yml` carries the matching `kyberforge#<version>` key. A comment in the
`executables:` block stays as the human-facing pointer; the hook is what actually holds. It parses
with PyYAML where importable and falls back to a two-shape scan otherwise, so a missing pip package
cannot become the thing that blocks every push.
## `.claude/settings.json`
**apm owns this file. Nothing repo-authored goes in it.**
`apm audit --ci` replays the install into a scratch tree and diffs the result byte-for-byte, so
anything apm would not have written there — an `enabledPlugins` block, a real `hooks` entry — is
permanent drift that fails `apm-audit-ci`. A hook you want in this repo is authored in
`plugins/<name>/.apm/hooks/` and deployed by apm, never hand-written here.
Its committed content is whatever apm last wrote, which today is the merged `SessionStart` entry for
kyberforge's `check-apm-current.sh`. That is apm's own output and it belongs in the commit (ADR-0019;
ADR-0018's statement that the committed content is exactly `{"hooks": {}}` is superseded on that
point only). Machine-specific settings go in the gitignored `.claude/settings.local.json`, which apm
does not deploy and the replay does not compare; shared enforcement belongs in
`.pre-commit-config.yaml`.
### Why it is excluded from `pretty-format-json`
It is the **sixth and last alternation** in that hook's `exclude:` pattern, and the only one there
for a reason other than "generated manifest". Mind which number you are quoting: **six alternations,
expanding to sixteen real files** — 3 root marketplace manifests, 2 per plugin × 6 plugins, plus this
one.
`pretty-format-json --autofix` sorts object keys unless `--no-sort-keys` is passed, while apm's hook
integrator emits insertion order (`matcher` before `hooks`, `type` before `command`). Leaving the
file in that hook's scope therefore rewrites apm's output into a form apm would never produce on the
way into **every** commit, and `apm-audit-ci` then reports permanent drift on a file with an empty
`git diff` — exactly what happened when the `SessionStart` hook first landed in `2e395a4`. Re-running
`apm install` fixes the file; leaving it in scope would re-break it on the very commit carrying the
fix.
**Load-bearing. Do not tidy it out of that list** (see `LESSONS.md`, 2026-08-14).
## Pushing without a network
Exactly **two** pre-push hooks need the network, for one shared reason: root `apm.yml`'s
`marketplace.packages[]` contains exactly one remote entry — `mattpocock-skills`,
`source: mattpocock/skills` — and resolving it needs a `git ls-remote`.
| Hook | Offline failure |
|---|---|
| `apm-marketplace-check` (`always_run`, resolves every entry) | `No cached refs (offline)` |
| `apm-pack-check-clean` (re-resolves the same entry) | `Error: Git network timeout during ls-remote` |
Pinning the entry to an exact version does **not** remove the call — an exact pin still ls-remotes.
`--offline` rescues neither.
To push without a network, skip both using pre-commit's own mechanism:
```
SKIP=apm-marketplace-check,apm-pack-check-clean git push
```
**Skip those two alone.** Verified under `unshare -rn`: the other twelve pre-push hooks pass offline
because they are real local checks. (`check-executables-allow-sync` landed after that run, but reads
two local manifests and makes no network call.) Adding any other hook to `SKIP` disarms it silently.
`apm-audit-ci` calls `apm` too but stays local: its org-policy discovery resolves nothing on this
remote *before* any network call, so it does not join the pair above.
---
## See also
- `docs/adr/0020-skill-description-and-body-context-contract.md` — the context contract, its
enforcement table (deterministic vs. auditor judgment), and every rejected alternative
- `docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md` — the `SessionStart` hook, the
executable-trust gate, and the version-pinned allow key
- `docs/adr/0017` / `0015` / `0014` — plugin content sync, apm-generated manifests, committed Vale
styles
- `docs/spec/architecture.md` — directory structure, install pipeline, what is generated and what is
hand-authored
- `.pre-commit-config.yaml` — the hooks themselves, with inline rationale comments

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

@@ -1,7 +1,7 @@
{
"name": "git",
"version": "1.3.3",
"description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.",
"version": "1.3.4",
"description": "Skills for working with Git \u2014 conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",

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

@@ -1,7 +1,7 @@
{
"name": "git",
"version": "1.3.3",
"description": "Skills for working with Git \u2014 conventional commits, branch management, pull requests, and feature flow.",
"version": "1.3.4",
"description": "Skills for working with Git \u2014 conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",

4
plugins/git/apm.yml
View File

@@ -1,6 +1,6 @@
name: git
version: 1.3.3
description: Skills for working with Git — conventional commits, branch management, pull requests, and feature flow.
version: 1.3.4
description: Skills for working with Git — conventional commits, branches, history, submodules, worktrees, remotes, and pre-commit hook authoring and running.
author:
name: Defame1297
email: defame1297@rkdr.net

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

@@ -1,7 +1,7 @@
{
"name": "gitea",
"version": "1.3.4",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.",
"version": "1.3.5",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, labels, milestones, releases, branches, and files.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",

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

@@ -1,7 +1,7 @@
{
"name": "gitea",
"version": "1.3.4",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, milestones, releases, and wikis.",
"version": "1.3.5",
"description": "Skills for managing Gitea repositories \u2014 issues, pull requests, labels, milestones, releases, branches, and files.",
"author": {
"name": "Defame1297",
"email": "defame1297@rkdr.net",

4
plugins/gitea/apm.yml
View File

@@ -1,6 +1,6 @@
name: gitea
version: 1.3.4
description: Skills for managing Gitea repositories — issues, pull requests, milestones, releases, and wikis.
version: 1.3.5
description: Skills for managing Gitea repositories — issues, pull requests, labels, milestones, releases, branches, and files.
author:
name: Defame1297
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"
fi
# 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
# is `level: error` and every alert is a FAIL — no ignorable tier". Vale's exit
# style file or a glob. Per ADR-0013, every rule is `level: error` and every
# 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
# 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
@@ -175,9 +175,10 @@ for ini in "$SKILL_INI" "$AGENT_INI"; do
fi
done
# KyberforgeCopilot is agent-audit's alone — CONTEXT.md describes it as "scoped
# only to `.agent.md` files for the Copilot-only 'Use proactively has no effect'
# check". The loop above deliberately asserts only `Kyberforge`, since
# KyberforgeCopilot is agent-audit's alone — ADR-0013 scopes it to `.agent.md`
# files only, for the Copilot-only 'Use proactively has no effect' check, and
# 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
# `, KyberforgeCopilot` from agent-audit's `[**/*.agent.md]` section unloaded 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
# not drift. `demo.agent.md` is the real, current shape and is `shared`.
#
# The two `.claude/`-prefixed probes carry the location-independence CONTEXT.md
# asserts: "A `SKILL.md` outside `plugins/` (e.g. project-scope
# The two `.claude/`-prefixed probes carry the location-independence property: a
# `SKILL.md` outside `plugins/` (e.g. project-scope
# `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted
# normally — the globs constrain filename shape, not location." 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
# path (`[**/SKILL.md]` -> `[**/.apm/skills/*/SKILL.md]`) left all of them
# matching while the project-scope shape started linting as `0 errors ... in 0

4
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
# convention path at .github/plugin/marketplace.json (see
# 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
# differently-shaped file to .agents/plugins/marketplace.json, not this path). This
# script keeps that legacy mirror byte-identical to .claude-plugin/marketplace.json
@@ -60,7 +60,7 @@ fi
if [[ "$CHECK" -eq 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 "Fix: bash scripts/sync-marketplace-mirror.sh" >&2
echo "Fix: bash scripts/sync-marketplace-mirror.sh -- 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
fi
exit 0

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 ---
# 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
# every alert is a FAIL -- no ignorable tier". Vale's exit code keys on `error`
# Per ADR-0013, every rule is `level: error` and every alert is a FAIL -- there
# is no ignorable tier. Vale's exit code keys on `error`
# alerts alone, so any such override leaves the glob intact, the styles
# 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
# Kyberforge alert. Verified dead by probing a `.agent.md` carrying
# "Use proactively": 0 alerts under the broken config, KyberforgeCopilot.
# ProactivePhrase under the shipped one. CONTEXT.md describes the style as
# "scoped only to `.agent.md` files for the Copilot-only 'Use proactively has
# no effect' check", so shipping it unloaded is drift.
# ProactivePhrase under the shipped one. ADR-0013 scopes the style to
# `.agent.md` files only, for the Copilot-only 'Use proactively has no effect'
# check, so shipping it unloaded is drift.
echo ""
echo "--- exits 1 when the shipped KyberforgeCopilot style is named by no BasedOnStyles ---"
FIXTURE11C="$(make_fixture)"
@@ -609,9 +609,9 @@ fi
# 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`,
# 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.
# project-scope `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and
# gets linted normally -- the globs constrain filename shape, not location."
# it exists to catch. A `SKILL.md` outside `plugins/` (e.g. project-scope
# `.claude/skills/foo/SKILL.md`) still matches `[**/SKILL.md]` and gets linted
# normally -- the globs constrain filename shape, not location.
# These narrowings are still valid glob syntax and break no `plugins/`-shaped
# file, so only a non-`plugins/` probe path catches them.
echo ""

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

@@ -451,8 +451,9 @@ fi
# 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
# 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
# explicit repo target, so the scope is four globs, each floor-asserted below:
# new script is covered the moment it lands. LESSONS.md and the script headers
# name bash 3.2 as an explicit repo target, so the scope is four globs, each
# floor-asserted below:
# - scripts/**/*.sh — repo tooling and pre-commit hook scripts
# - tests/*.sh — the runners and every regression test
# - plugins/*/.apm/**/*.sh — the scripts plugins ship to users