Defame1297
b0ef503485
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.
127 lines
8.2 KiB
Markdown
127 lines
8.2 KiB
Markdown
# 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, milestones, releases, wikis
|
|
- **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
|