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 skill-author/agent-author's routing to author .apm/-native content (retargeting to .apm/skills/, .apm/agents/ paths — the content these two skills author is still meaningful post-conversion) is deferred to issue #89 (https://git.dev.rkdr.net/Defame1297/holocron/issues/89). forge is out of scope for #89 — it stays untouched by this whole conversion effort and keeps routing to whatever the live author skills are at the time.
• plugin-author/marketplace-author are not adapted — they are superseded and deleted. Unlike skill-author/agent-author, nothing in these two skills carries forward as authoring routing: apm compile/apm pack will generate .claude-plugin/marketplace.json and per-provider plugin.json directly from apm.yml + .apm/, so apm-install/apm-workflow/ apm-orchestrate (issue #88, already landed on this branch) fully replace what these two skills did. Deleting plugin-author/marketplace-author is part of issue #90's execution, not #89's.
• 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.

Content migration out of plugin-author/marketplace-author

A content audit of plugin-author/marketplace-author (same grill-with-docs session as this correction) sorted what they document into three buckets:

• Claude Code platform constraints — carried forward. Facts that stay true regardless of authoring model (reserved plugin-name prefixes; the agents/-directory stray-.md-file validator gotcha, ADR-0010; claude plugin validate as a required terminal check) have been added into apm-workflow's reference docs, since compiled output still has to satisfy these constraints post-conversion.
• Dual-manifest artifacts — obsolete, not carried forward. Conventions that existed only because of hand-authored dual manifests (ADR-0006's version-parity/patch-bump rule, the CC-vs-Copilot field-placement split, dual-file mirroring) are obsolete under apm.yml's single-manifest model and were deliberately dropped.
• Holocron policy choice — flagged for #90, not resolved here. marketplace-author's catalog-version convention (minor bump for package add/remove, patch bump for field-only updates) isn't an APM mechanic — apm doesn't enforce it — but it's still a meaningful holocron policy worth re-applying to apm.yml's marketplace.packages[].version field once #90 wires up real marketplace authoring. Where/how that gets implemented is #90's decision, not this ADR's.

Consequences

• ADR-0001 is superseded once issue #90 executes.
• ADR-0006 (plugin-version-parity) becomes moot once #90 lands: plugin.json/marketplace.json become compiled output of a single apm.yml, so there's no second hand-authored file left to keep in parity, and plugin-author — the skill that enforced ADR-0006 — is deleted rather than adapted (see "Content migration" above). 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 track the remaining work: #89 (skill-author/agent-author routing adaptation) and #90 (the actual repo conversion, which also deletes plugin-author/ marketplace-author).