Files

Defame1297 d42f6368fe fix(docs): correct claims the first fix round asserted without measuring

Why: two blind verifiers re-ran the five preceding commits and found four
defects of the same class this branch exists to close -- a confidently stated
measured claim that does not survive re-measurement -- this time inside the
fixes themselves.

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

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

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

Refs: #105

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w

2026-08-17 13:18:55 +00:00

8.9 KiB

Raw Blame History

holocron

The global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Built as a homelab tool intended to scale to professional environments.

Content ships as six installable plugins, each an apm (Agent Package Manager) package. This repo consumes its own plugins through apm, so the working copy runs the same released content every other consumer gets.

Repo layout

Path	What it holds
`plugins/`	Six apm packages — `bin`, `core`, `git`, `gitea`, `kyberforge`, `lint` — each carrying skills, and where relevant agents, hooks, MCP servers, and bundled assets
`providers/claude-code/`	Claude Code adapter, deployed to `~/.claude/` via `scripts/install.sh`
`core/`	Provider-agnostic always-on content — `core/AGENTS.md` and `core/instructions/`
`docs/`	Specs (`docs/spec/`), architectural decisions (`docs/adr/`), governance, research, and notes
`scripts/`	Install, sync, and check scripts used by the git hooks
`tests/`	`run-tests.sh`, `run-bats.sh`, the `test-*.sh` suites, and the bats submodules

The six plugins:

kyberforge — skills and agents for creating, maintaining, and managing a Claude Code / Copilot CLI plugin marketplace
git — conventional commits, branches, history, submodules, worktrees, remotes, pre-commit hook authoring and running (pc-author / pc-run), and an interactive router (git-workflow)
gitea — issues, pull requests, labels, milestones, releases, branches, files, and an interactive router (gitea-workflow)
core — authoring and auditing a repo's AGENTS.md and the provider adapter files that defer to it
lint — configuring and running linters
bin — cross-cutting workflow skills not yet split into a focused plugin: research, documentation, TDD, prototyping, triage, diagnosis, architecture review, requirement grilling, compressed output (caveman), and re-orienting mid-task (zoom-out)

Prerequisites

Install all of these before setting up. Each one is a hard dependency of a git hook or a script — several fail with an unhelpful "command not found" if missing.

Tool	Why	Install
`apm` CLI	Four pre-push hooks shell out to it (`apm-marketplace-check`, `apm-audit-ci`, `apm-pack-check-clean`, and `check-plugin-content-sync` via `scripts/sync-plugin-content.sh`)	The `apm-install` skill, or `curl -sSL https://aka.ms/apm-unix \| sh`. Verify with `apm --version`
`jq`	Required by `scripts/check-manifests.sh` and `scripts/sync-plugin-content.sh`, both pre-push	Your package manager
`python3` + PyYAML	Required by `scripts/skill-size-check.sh` (the `skill-size-check` pre-commit hook), which reads folded YAML frontmatter	`python3` is usually present — pre-commit is itself a Python application. `pip install pyyaml` if the hook reports PyYAML missing
`vale`	Required by the `vale-audit-prefilter-skill` / `-agent` pre-commit hooks and the `check-vale-style-sync` pre-push hook	`brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or https://vale.sh/docs/vale-cli/installation/
`claude` CLI	Required by the `validate-plugins` and `validate-marketplace` pre-push hooks	Claude Code

Two notes worth reading before you skip one:

PyYAML is a hard requirement, not an optional accelerator. The hand-rolled fallback frontmatter reader was removed deliberately: a reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured.
No vale sync is needed. The Kyberforge styles are committed under plugins/kyberforge/.apm/skills/{skill-audit,agent-audit}/assets/vale/styles/, not downloaded packages (ADR-0014).

Setup

Run these in order, from the repo root.

# 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 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 repo
CONTEXT.md — domain language; read at the start of every session here
docs/spec/architecture.md — directory structure, install pipeline, provider model
docs/spec/gates.md — the enforcement gates in depth
docs/adr/ — architectural decisions; read before proposing structural changes
docs/VISION.md — where this is going
LESSONS.md — things that went wrong once and should not again

8.9 KiB Raw Blame History