holocron/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md

Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth

Will supersede: ADR-0001 ("Skills are distributed via plugins... each plugin contains its own skills/ directory") — once issue #90's conversion actually executes; not yet in effect.

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 will supersede ADR-0001 ("Skills are distributed via plugins... each plugin contains its own skills/ directory"), but not yet — supersession is pending on issue #90's conversion. Once that 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"/"Plugin marketplace" glossary entries get a forward-pointer to this ADR so a session-start read surfaces the pending change; their substantive definitions remain accurate until issue #90's conversion actually executes — this ADR does not rewrite 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. The shipped apm-install/apm-workflow skills are, in fact, generic, repo-agnostic APM CLI documentation with no holocron-specific content, so a standalone plugins/apm/ would have been a defensible split on artifact content alone. Rejected anyway, in favor of kyberforge, because holocron is currently the only repo that needs this tooling — standing up a separate plugin for a single consumer isn't worth it yet. 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 to plugins/<name>/.apm/agents/ — the directory path changes, not the pre-existing .agent.md extension convention (ADR-0005/ADR-0010, unaffected) — 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.