docs(adr): add ADR-0015 for outright APM conversion

Records the grill-with-docs decision on issue #88: replace the
hand-authored plugin/marketplace manifest model with Microsoft APM
(apm.yml + .apm/) as this repo's authoring source of truth. The
plugins/<name>/ monorepo-hybrid layout survives; marketplace.json and
provider plugin.json files become compiled output. Supersedes
ADR-0001; touches but does not resolve ADR-0006/0010/0014. Follow-up
work tracked in issues #89 and #90.
This commit is contained in:
2026-08-10 17:42:31 +00:00
parent 1d07d1a76b
commit 0e421acdbb

View File

@@ -0,0 +1,74 @@
# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth
This repo replaces its hand-maintained Claude Code plugin/marketplace authoring model
(`.claude-plugin/marketplace.json` + per-plugin `plugin.json`) with Microsoft APM (`apm.yml` +
`.apm/`) as the authoring source of truth — an outright replacement of the authoring layer, not an
additive overlay. This ADR records the decision from a `grill-with-docs` session on issue #88.
## Context
Every plugin under `plugins/<name>/` currently ships two hand-maintained manifests
(`.claude-plugin/plugin.json` for Claude Code, root `plugin.json` for Copilot CLI) plus a
hand-maintained root `.claude-plugin/marketplace.json` listing all plugins. Adding a provider means
hand-authoring a third manifest shape; keeping the two existing ones in parity is itself a tracked
concern (ADR-0006).
Research on Microsoft APM (`plugins/kyberforge/docs/research/docs/microsoft-apm/`) found that its
documented "monorepo-hybrid" repo shape maps directly onto this repo's existing `plugins/<name>/`
layout: each plugin becomes its own `apm.yml` + `.apm/{skills,agents,hooks,prompts,instructions}/`
package, listed from a root `apm.yml`'s `marketplace:` block. `apm compile`/`apm pack` generate
per-target output — including a `.claude-plugin/marketplace.json` — from that vendor-neutral
`.apm/` tree, so provider manifests become compiled artifacts instead of hand-authored files, and
new providers (Copilot, Gemini, Codex — all supported by `apm runtime setup`) no longer require a
new hand-maintained manifest format.
## Decision
- **The `plugins/<name>/` monorepo-hybrid directory layout survives.** `.claude-plugin/marketplace.json`
and per-provider `plugin.json` files become **compiled output** via `apm compile`/`apm pack`,
generated from `apm.yml` + `.apm/` per plugin, extensible to other `apm runtime`-supported
providers without hand-maintaining a separate manifest per provider.
- **This directly supersedes ADR-0001** ("Skills are distributed via plugins... each plugin
contains its own `skills/` directory"). Once the real conversion executes, skills and agents
physically move to `plugins/<name>/.apm/skills/` and `plugins/<name>/.apm/agents/*.agent.md`.
- New operational tooling — `apm-install` (skill), `apm-workflow` (skill), `apm-orchestrate`
(agent) — lands in `kyberforge`, tracked in issue #88
(https://git.dev.rkdr.net/Defame1297/holocron/issues/88).
- Adapting `plugin-author`/`marketplace-author`/`skill-author`/`agent-author`/`forge`'s routing to
author `.apm/`-native content is deferred to issue #89
(https://git.dev.rkdr.net/Defame1297/holocron/issues/89).
- Actually translating the existing plugins into `apm.yml` + `.apm/` and running the real
conversion is deferred to issue #90
(https://git.dev.rkdr.net/Defame1297/holocron/issues/90).
- `CONTEXT.md`'s "Plugin"/"Skill"/"Plugin marketplace" glossary entries remain accurate as
written until issue #90 actually executes — this ADR does not update them.
## Considered options
**Additive/compile-layer only, no `apm.yml` (rejected).** Keep `plugin.json`/`marketplace.json`
hand-authored and bolt APM on top as an optional extra. Rejected: doesn't achieve the multi-provider
compile-reuse goal APM's package model provides, and leaves the existing dual-manifest hand
maintenance in place unchanged.
**New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge`
specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific
(see `CONTEXT.md`'s "lint plugin" entry) — the same argument applies to a generic `apm` CLI
wrapper. Rejected anyway, in favor of `kyberforge`, because this tooling's scope is specifically
converting *this* repo's marketplace, not standing up a reusable generic apm toolkit for other
repos. Accepted as an explicit tradeoff (same pattern as ADR-0011's `gitea-workflow` naming
tradeoff) — worth revisiting if this tooling is ever reused outside holocron's own conversion.
## Consequences
- ADR-0001 is superseded once issue #90 executes.
- ADR-0006 (plugin-version-parity) will need a third file, `apm.yml`, folded into its parity
check once #90 lands — not resolved by this ADR.
- ADR-0010 (agent sources relocated outside agents dir) needs revisiting once agents move under
`.apm/agents/` with the `.agent.md` extension — not resolved by this ADR.
- ADR-0014 (Vale prefilter ships from the plugin) has hardcoded path regexes assuming
`plugins/<name>/skills/...`/`plugins/<name>/agents/...`; these will need updating once paths
move under `.apm/` — not resolved by this ADR.
- `kyberforge` gains three new artifacts (issue #88) before any conversion of existing content
happens.
- Two follow-up issues (#89, #90) track the deferred authoring-tooling adaptation and the actual
repo conversion, respectively.