Defame1297
175ea89c0a
Check 9 shipped in #130 to close #118, but three defects meant it could not do the job it was added for. Why: - It is INFO-only, so it always exits 0 — and SKILL.md graded exit 0 "a genuine pass" and said the script "prints nothing on success". Every check-9 INFO was discarded before it reached a report, behind three further doors that only opened on a non-zero exit. - `parse_field_raw()` matched `(.+)`, which does not span newlines, so only the first physical line of a wrapped value was compared. Rewriting only the continuation line of a wrapped Description from a hedge to a confident claim produced no finding at all — verbatim the regression #118 was filed about. The bullet branch had the same shape: a wrapped bullet broke the loop and dropped every later entry. - A `git show` failure at the base ref was treated as "creation, nothing to flag" and skipped the whole skill with no output, collapsing "absent at that ref" with "not tracked under that name". A gitignored `.claude/skills/` copy reported clean while the authoring path reported four changed claims. The script's own usage text promises this is "never a silent skip". Implementation notes: - Exit-code guidance re-keyed on output as well as code: 0-and-silent passes, 0-with-output is INFO-only findings, 1 is FAILs, 2 never ran. - `parse_field_raw()` is line-based and joins continuation lines; `normalize_field_text()`'s docstring is now true rather than aspirational. A reorder deliberately fires: the two fields share one parser, and order-insensitivity would mean splitting a prose Description on commas. - The discarded `show_err` is now surfaced as one whole-check INFO naming both readings. - `--base-ref=` given empty now beats the env var, as the usage text always claimed. `validate.sh` gains an ADR-0022 `metadata.version` check at FAIL tier, because any lower tier lets skill-author Step 4 report done on a file the commit gate then refuses. Its `read` heuristic now skips here-doc bodies — reflowing the one offending line would have cleared the finding and left the cause, since every usage() heredoc is one wrap from putting the English verb in column 0. Impact: provenance tests 73 -> 82, validate tests 64 -> 72. Test 72 previously deleted origin/main before asserting the override, so it proved the flag works with no default rather than that it beats one; it now moves origin/main forward first. Refs: #118 ADR: 0022 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
holocron
The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments.
Content ships as six installable plugins, each an apm (Agent Package Manager) package. This repo consumes its own plugins through apm, so the working copy runs the same released content every other consumer gets.
Repo layout
| Path | What it holds |
|---|---|
plugins/ |
Six apm packages — bin, core, git, gitea, kyberforge, lint — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets |
providers/claude-code/ |
Claude Code adapter, deployed to ~/.claude/ via scripts/install.sh |
core/ |
Provider-agnostic always-on content — core/AGENTS.md and core/instructions/ |
docs/ |
Specs (docs/spec/), architectural decisions (docs/adr/), governance, research, and notes |
scripts/ |
Install, sync, and check scripts used by the git hooks |
tests/ |
run-tests.sh, run-bats.sh, the test-*.sh suites, and the bats submodules |
The six plugins:
- kyberforge — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace
- git — conventional commits, branches, history, submodules, worktrees, remotes, pre-commit hook authoring and running (
pc-author/pc-run), and an interactive router (git-workflow) - gitea — issues, pull requests, labels, milestones, releases, branches, files, and an interactive router (
gitea-workflow) - core — authoring and auditing a repo's
AGENTS.mdand the provider adapter files that defer to it - lint — configuring and running linters
- bin — cross-cutting workflow skills not yet split into a focused plugin: research, documentation, TDD, prototyping, triage, diagnosis, architecture review, requirement grilling, compressed output (
caveman), and re-orienting mid-task (zoom-out)
Prerequisites
Install all of these before setting up. Each one is a hard dependency of a git hook or a script — several fail with an unhelpful "command not found" if missing.
| Tool | Why | Install |
|---|---|---|
apm CLI |
Four pre-push hooks shell out to it (apm-marketplace-check, apm-audit-ci, apm-pack-check-clean, and check-plugin-content-sync via scripts/sync-plugin-content.sh) |
The apm-install skill, or curl -sSL https://aka.ms/apm-unix | sh. Verify with apm --version |
jq |
Required by scripts/check-manifests.sh and scripts/sync-plugin-content.sh, both pre-push |
Your package manager |
python3 + PyYAML |
Required by scripts/skill-size-check.sh (the skill-size-check pre-commit hook), which reads folded YAML frontmatter |
python3 is usually present — pre-commit is itself a Python application. pip install pyyaml if the hook reports PyYAML missing |
vale |
Required by the vale-audit-prefilter-skill / -agent pre-commit hooks and the check-vale-style-sync pre-push hook |
brew install vale (macOS), snap install vale (Linux), choco install vale (Windows), or https://vale.sh/docs/vale-cli/installation/ |
claude CLI |
Required by the validate-plugins and validate-marketplace pre-push hooks |
Claude Code |
Two notes worth reading before you skip one:
- PyYAML is a hard requirement, not an optional accelerator. The hand-rolled fallback frontmatter reader was removed deliberately: a reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured.
- No
vale syncis needed. TheKyberforgestyles are committed underplugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/, not downloaded packages (ADR-0014).
Setup
Run these in order, from the repo root.
# 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 installdeploys fromapm.lock.yaml. It does not pick up remote changes.apm updatere-resolves refs. This is the command that pulls in a merged.apm/edit.
Running tests
bash tests/run-tests.sh # every test-*.sh script plus the bats suite
bash tests/run-tests.sh --bats-only # just bats
The first run auto-initializes the bats submodules; no manual git submodule update needed.
A suite that exits 77 because a dependency is missing is reported as SKIPPED and does not fail an ad-hoc run. It does fail under --strict (equivalently RUN_TESTS_STRICT=1), which is how the pre-push hook invokes it — at pre-push, a skip means one of the prerequisites above is absent on this machine, and the gate would otherwise report success having run fewer suites than it appears to. The strict failure names each skipped suite and what to install.
Before pushing
Run the pre-push gate locally in one command:
pre-commit run --hook-stage pre-push --all-files
One caveat: check-release-needed is a silent no-op under this invocation. It exits 0 unless
PRE_COMMIT_REMOTE_BRANCH is refs/heads/main, and pre-commit exports that only from the real
pre-push git hook during an actual git push — so the hook reports Passed having checked nothing.
Every other pre-push hook does run.
See docs/spec/gates.md 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:
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.
For external consumers
Install a plugin natively from the marketplace manifests:
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— the rules for AI agents working in this repoCONTEXT.md— domain language; read at the start of every session heredocs/spec/architecture.md— directory structure, install pipeline, provider modeldocs/spec/gates.md— the enforcement gates in depthdocs/adr/— architectural decisions; read before proposing structural changesdocs/VISION.md— where this is goingLESSONS.md— things that went wrong once and should not again