holocron/docs/adr/0018-repo-consumes-its-own-plugins-through-apm.md

# 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 gain an unnamespaced name.** apm deploys plain project skills, so `git:git-commits` also
answers to `git-commits` and `kyberforge:skill-audit` to `skill-audit`. This is not configurable —
a project skill has no plugin to prefix. `AGENTS.md` and `CONTEXT.md` are updated to name the bare
form, which is what apm deploys and the only form a repo consuming holocron through apm gets.

**Correction (2026-08-14): the namespaced form did not stop resolving.** An earlier revision of
this consequence said every `<plugin>:<skill>` reference "was stale the moment the switch landed",
and `AGENTS.md`/`CONTEXT.md` were written to match. That contradicts the "User scope is untouched,
deliberately" consequence below, and the contradiction resolves against it: `~/.claude.json` still
enables `core`, `git`, `gitea`, `kyberforge` and `lint` at user scope, so both names are live at
once and a working `gitea:gitea-prs` is the user-scope copy answering. That doubling is the same
"present twice under two names" outcome the "Keeping both install paths" alternative was rejected
for — reached by leaving user scope alone rather than by adopting it, which is why it is a
consequence to record rather than a decision to revisit. Prefer the bare name regardless: it
survives those user-scope installs eventually being converted, and 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`.** (ADR-0019 supersedes the "exactly `{"hooks": {}}`" claim
below — once a package ships a hook, apm merges it into that file and the merged entry is apm's own
output. The rule that nothing repo-authored goes in the file is unchanged.) `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 the install is refreshed. Under the native
install with `autoUpdate` the shape was the same; it was more noticeable here at first because the
refresh is a manual step where marketplace auto-update was not — ADR-0019 automates it at
`SessionStart`.

**Correction (2026-08-14): the refresh command is `apm update`, not `apm install`.** An earlier
revision of this paragraph named `apm install`, which is wrong: `apm install` deploys from the
pinned `resolved_commit` in `apm.lock.yaml` and does not re-resolve refs (`apm install --force`
documents this explicitly — "does NOT refresh refs; use 'apm update' for that"). Running it after a
merge redeploys the same content and reports success.

**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`.