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

build(apm): consume holocron plugins through apm instead of plugin install

Browse Source 
Why:
The repo published apm packages but consumed them the old way — `claude plugin install
<name>@holocron`, six plugins enabled per project. Dogfooding stopped one layer short of the
install tooling kyberforge itself ships.

Implementation notes:
- Root apm.yml declares the six packages as dependencies.apm git+path objects against the
  holocron remote. Object form over `<name>@holocron` aliases on purpose: an alias first needs
  `apm marketplace add`, which writes to ~/.apm/marketplaces.json — user scope, absent on a fresh
  clone. Unpinned against the default branch, matching the autoUpdate the native install had.
- apm.lock.yaml is committed; .claude/skills/, .claude/agents/ and apm_modules/ are gitignored
  regenerable install output. Committing the deployed skills would add a third mirror of content
  ADR-0017 already governs two copies of.
- .mcp.json is generated by apm from plugins/bin/.mcp.json, so the obsidian MCP server survives
  the switch.
- .claude/settings.json is reduced to {"hooks": {}}. apm replays the install into a scratch tree
  and diffs, so any repo-owned key there is permanent drift that fails apm-audit-ci. Nothing was
  lost: enabledPlugins was empty after the uninstall and the only hooks entry was PreToolUse: [].
- tests/run-bats.sh and tests/run-tests.sh exclude apm_modules/. It holds a full copy of every
  plugin, and a copied .bats file resolves its helpers against the dependency root rather than
  this repo — 334 tests, 167 failures before the exclusion.

Impact:
Skills are now unnamespaced — `git-commits`, not `git:git-commits` — because apm deploys plain
project skills with no plugin to prefix. AGENTS.md, CONTEXT.md and docs/spec/architecture.md are
updated accordingly. Root apm.yml now declares dependencies, which arms apm-audit-ci's
lockfile-exists check for the root manifest. External consumers are unaffected: the marketplace
manifests are untouched and `apm pack --check-clean` stays clean. Project scope only.

ADR: 0018

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT
This commit is contained in:
Defame1297
2026-08-14 17:15:17 +00:00
parent c3ec5f2d3d
commit 2e8732a8e5
11 changed files with 2907 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md Normal file
View File

@@ -0,0 +1,112 @@
# This repo installs its own plugins through apm, not Claude Code's native plugin install
ADR-0015 moved plugin **authoring** to apm; ADR-0017 added the flat content mirror that keeps the
authored `.apm/` tree discoverable by hosts that install natively. Both are about producing the
marketplace. This ADR is about consuming it: how the plugins get onto the machine this repo is
worked on.
**Status: executed (2026-08-14).** All six packages are installed into `/root/ai-development` by
`apm install`; the six native project-scope installs (`claude plugin uninstall <name>@holocron
--scope project`) are gone and `.claude/settings.json`'s `enabledPlugins` block is empty.
## Context
Until now the repo consumed its own output the same way any user would: `claude plugin install
<name>@holocron`, six plugins enabled per-project in `.claude/settings.json`, the `holocron`
marketplace registered in `~/.claude/plugins/known_marketplaces.json` with `autoUpdate: true`.
That worked. It also meant the repo's dogfooding stopped one layer short of the tooling it
publishes: `kyberforge` ships `apm-workflow` and `apm-install` skills describing an install path
the repo itself did not take.
apm supports both scopes. `apm install --global` deploys to `~/.claude/`; plain `apm install`
deploys to the project. Global was rejected deliberately — the switch should be provable in one
repo before it changes how every other project on the machine resolves its skills.
## Decision
Root `apm.yml` declares all six packages under `dependencies.apm`, each as a `git:`/`path:` object
against the holocron remote:
```yaml
dependencies:
apm:
- git: git@git.dev.rkdr.net:Defame1297/holocron.git
path: plugins/core
```
`apm install` deploys them to `.claude/skills/<name>/` and `.claude/agents/<name>.md`.
Three sub-decisions inside that:
- **Object form over the `<name>@holocron` marketplace alias.** The alias is shorter and apm
resolves it correctly (verified end-to-end against this remote), but it first requires
`apm marketplace add`, which writes to `~/.apm/marketplaces.json` — user scope, outside the
repo, and absent on a fresh clone. The object form needs nothing beyond the committed manifest.
- **Remote source over local path.** apm accepts `path: /root/ai-development/plugins/<name>` as a
local dependency, which would make the working tree live instantly. Rejected: it erases the
distinction between editing a skill and shipping one, which is the entire point of having a
marketplace. The remote form keeps the repo running the same released content every other
consumer gets.
- **Unpinned against the default branch.** Parity with the `autoUpdate: true` the native install
had. apm warns on every install (`6 dependencies unpinned`); accepted knowingly. Pinning is a
per-entry `ref:` away once the repo tags releases per package — today `git tag` lists one tag
total, so there is nothing meaningful to pin to.
## Consequences
**Skills lose their namespace.** apm deploys plain project skills, so `git:git-commits` is now
`git-commits` and `kyberforge:skill-audit` is `skill-audit`. This is not configurable — a project
skill has no plugin to prefix. Every `<plugin>:<skill>` reference in the repo's own instructions
was stale the moment the switch landed; `AGENTS.md` and `CONTEXT.md` are updated. The namespaced
form still resolves for anyone installing holocron natively, so skill bodies written for both
audiences should name the bare skill.
**apm owns `.claude/settings.json`.** `apm audit --ci` replays the install into a scratch tree and
diffs it against the worktree. apm's hook integrator writes that file, so the replay expects
exactly what apm would have written — `{"hooks": {}}` — and any repo-owned key in it is permanent
drift that fails the `apm-audit-ci` pre-push hook. Verified both directions: with the pre-existing
`enabledPlugins` block present, `1 of 10 check(s) failed`; reduced to `{"hooks": {}}`,
`All 10 check(s) passed`. Nothing was lost in that reduction — `enabledPlugins` was empty after the
native uninstall and the only `hooks` entry was an empty `PreToolUse: []` — but it does mean the
file is no longer available for repo-owned settings. Machine-specific settings go in the gitignored
`.claude/settings.local.json`, which apm does not deploy; shared enforcement belongs in
`.pre-commit-config.yaml`, where this repo already keeps it.
**`apm_modules/` breaks naive tree walks.** apm materializes a full copy of every dependency there
— including this repo's own plugins, `.bats` files and all. The dependency copies resolve their
bats helpers relative to their own root, not this repo's, so `tests/run-tests.sh` went from 167
tests passing to `334 tests, 167 failures` on the first install. Both discovery walks
(`tests/run-bats.sh`, `tests/run-tests.sh`) now exclude `apm_modules/`, on the find side and on the
`git ls-files` side that derives the expected set. Any future script that walks the repo tree needs
the same exclusion.
**Install output is gitignored; the lockfile is not.** `.claude/skills/`, `.claude/agents/`, and
`apm_modules/` are regenerated by `apm install`. Committing the deployed skills would add a third
mirror of content ADR-0017 already governs two copies of. `apm.lock.yaml` is committed — it is what
makes the install reproducible, and `apm audit --ci` checks it.
**MCP survived the switch; hooks were never at risk.** apm read `plugins/bin/.mcp.json` as a
self-defined direct-dependency MCP server and configured `obsidian` into the repo's `.mcp.json`
unprompted. The `gitea` and `context7` servers were never plugin-provided — they live in
`~/.claude.json` and are untouched. Every plugin's `.apm/hooks/hooks.json` is `{"hooks": {}}`, so
apm's "contributed no entries to claude settings; skipped" warning on `kyberforge` and `lint` is
accurate and harmless.
**A `.apm/` edit now needs a round trip.** The dependency resolves from the remote, so an edit is
invisible to the running session until it is pushed and `apm install` re-runs. Under the native
install with `autoUpdate` the shape was the same; it is more noticeable now because `apm install`
is a manual step where marketplace auto-update was not.
**User scope is untouched, deliberately.** `bin@holocron`, `gitea@holocron`, and a stale
`hello-world@holocron` remain natively installed at user scope, and every project other than this
one still resolves its skills that way. Converting them is a separate decision with a blast radius
beyond this repo.
## Alternatives considered
- **`apm install --global`.** Verified working in an isolated `HOME`: user-scope deploys land in
`~/.claude/skills/` and `~/.claude/agents/`, and it is the only scope where a plugin's `bin/`
executables deploy (moot here — every `bin/` in this repo is empty but for a README). Deferred,
not rejected: it changes skill resolution for every project on the machine at once.
- **Keeping both install paths.** Rejected: the same skill would be present twice under two names,
and `.claude/settings.json` cannot hold `enabledPlugins` without failing `apm audit --ci`.

4
docs/spec/architecture.md
View File

@@ -19,13 +19,13 @@ project repo (local overrides)
- **Executables** (`DEPLOY_EXECUTABLES`): `providers/claude-code/statusline-command.sh` → `~/.claude/statusline-command.sh` (with `+x`)
- **Directories** (`DEPLOY_DIRS`): `core/` → `~/.claude/core/` (destination fully replaced on each deploy)
Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately via `claude plugin install <name>@holocron`.
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.
## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`, installed independently via `claude plugin install <name>@holocron`. 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). 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.
Two compilers produce the plugin roots you see in the tree: