# 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//` 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 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//.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 `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//.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//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 track the remaining work: #89 (`skill-author`/`agent-author` routing adaptation) and #90 (the actual repo conversion, which also deletes `plugin-author`/ `marketplace-author`).