diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md new file mode 100644 index 0000000..446c3bf --- /dev/null +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -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//` 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//` +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//` 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//.apm/skills/` and `plugins//.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//skills/...`/`plugins//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.