holocron/README.md

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, 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	Two pre-push hooks shell out to it (apm-audit-ci and apm-pack-check-clean)	The apm-install skill, or curl -sSL https://aka.ms/apm-unix | sh. Verify with apm --version
python3 + PyYAML	Required by scripts/skill-size-check.sh (the skill-size-check pre-commit hook) and scripts/check-skill-version-bump.sh (the check-skill-version-bump pre-push hook), which both parse 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 by the test-vale-wrap.sh / test-vale-hooks-consumer.sh suites that run-tests --strict runs at pre-push	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-marketplace pre-push hook	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/factory-audit/assets/vale/styles/, not downloaded packages (ADR-0014, ADR-0025).

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 and materializes apm_modules/ (which stays gitignored).

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's SessionStart hook keeps the install current automatically on launch, rewriting apm.lock.yaml in the process — an unexplained modification to it after opening a session is expected, not a bug. On main, commit or discard it deliberately. On a feature branch, discard it (git checkout -- apm.lock.yaml, then apm install). The committed lock records a main commit too, just an older one. Discarding keeps lock churn unrelated to the branch out of its diff, and keeps the deployed tree consistent with the committed lock that apm pack --check-clean reads. The trade-off: the session then runs the older main the lock records, which is accepted on a feature branch. The discard also lasts only until the next session start, when the hook finds the lock behind main and refreshes again. Mechanism and rationale: docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md.

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? No pre-push hook needs the network: root apm.yml's marketplace has no remote package entries (the last one, mattpocock-skills, was removed), so apm-pack-check-clean resolves everything from local sources. All pre-push hooks pass offline.

Editing plugin content

plugins/<name>/.apm/ is the only hand-edited source for plugin content — the root marketplace.json manifest is generated by apm pack, and a hand-edit there is reported as drift by apm-pack-check-clean. Hand-authored material that is not an .apm/ primitive (README.md, docs/, bin/, sources.md) lives at the plugin root instead.

Full model, including what's exempt and why: docs/spec/architecture.md.

For external consumers

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. apm is the only supported install path.

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