feat(kyberforge): add apm-install/apm-workflow/apm-orchestrate, ADR-0015 #91
74
docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
Normal 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
|
||||
|
Defame1297 marked this conversation as resolved
|
||||
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
|
||||
|
Defame1297 marked this conversation as resolved
Outdated
Claude
commented
This says CONTEXT.md's Plugin/Skill/Plugin-marketplace glossary 'remains accurate as written until issue #90', but neither CONTEXT.md nor ADR-0001 gets any status marker or forward-pointer to this ADR. CONTEXT.md is mandated reading 'at the start of every session' per AGENTS.md, and this repo's own convention elsewhere (e.g. ADR-0007/ADR-0010) is to add an inline 'Superseded by' / 'Update' note on the older doc. Without that, an agent consulting CONTEXT.md or ADR-0001 directly has no signal a foundational change is pending and will keep hand-authoring plugin.json/marketplace.json exactly as this ADR says is being phased out. This says CONTEXT.md's Plugin/Skill/Plugin-marketplace glossary 'remains accurate as written until issue #90', but neither CONTEXT.md nor ADR-0001 gets any status marker or forward-pointer to this ADR. CONTEXT.md is mandated reading 'at the start of every session' per AGENTS.md, and this repo's own convention elsewhere (e.g. ADR-0007/ADR-0010) is to add an inline 'Superseded by' / 'Update' note on the older doc. Without that, an agent consulting CONTEXT.md or ADR-0001 directly has no signal a foundational change is pending and will keep hand-authoring plugin.json/marketplace.json exactly as this ADR says is being phased out.
|
||||
written until issue #90 actually executes — this ADR does not update them.
|
||||
|
||||
## Considered options
|
||||
|
||||
|
Defame1297 marked this conversation as resolved
Outdated
Claude
commented
ADR-0015 states "CONTEXT.md's Plugin/Skill/Plugin-marketplace glossary entries remain accurate as written until issue #90 actually executes — this ADR does not update them," but this same PR's fix commit ( Failure scenario: A reader trusts the ADR's own claim about its change boundary and skips re-checking CONTEXT.md, or a future auditor treats the ADR as the authoritative record of what this PR touched and gets it wrong — the document contradicts the diff it ships alongside. ADR-0015 states "CONTEXT.md's Plugin/Skill/Plugin-marketplace glossary entries remain accurate as written until issue #90 actually executes — this ADR does not update them," but this same PR's fix commit (e16c3dc) edited CONTEXT.md's Plugin and Plugin marketplace entries to add an ADR-0015 forward-pointer sentence.
**Failure scenario:** A reader trusts the ADR's own claim about its change boundary and skips re-checking CONTEXT.md, or a future auditor treats the ADR as the authoritative record of what this PR touched and gets it wrong — the document contradicts the diff it ships alongside.
|
||||
**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
|
||||
|
Defame1297 marked this conversation as resolved
Outdated
Claude
commented
The rationale for rejecting a standalone The rationale for rejecting a standalone `plugins/apm/` plugin claims this tooling's scope is 'specifically converting *this* repo's marketplace, not standing up a reusable generic apm toolkit' — but the shipped apm-install/apm-workflow SKILL.md files are fully generic, repo-agnostic APM CLI documentation with essentially no holocron-specific content. The stated justification doesn't match what was actually built, which will make the placement decision look post-hoc to a future reviewer.
Defame1297
commented
agree that the created files are agnostic, but they still fit the kyberforge purpose. agree that the created files are agnostic, but they still fit the kyberforge purpose.
|
||||
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.
|
||||
|
Defame1297 marked this conversation as resolved
Outdated
Claude
commented
Attributes the Attributes the `.agent.md` extension to the future APM conversion ('needs revisiting once agents move under .apm/agents/ with the .agent.md extension'), but `.agent.md` is this repo's pre-existing Copilot-pairing convention (ADR-0005/ADR-0010), already in use by this very diff's own apm-orchestrate.agent.md. Whoever executes #90 could read this as license to redesign an already-settled, orthogonal naming convention that has nothing to do with the APM move.
|
||||
- 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.
|
||||
This Decision bullet states 'This directly supersedes ADR-0001' as a present-tense fact, but the Consequences section (line 63) says 'ADR-0001 is superseded once issue #90 executes' — a future, conditional event. The same document licenses opposite conclusions depending which section a reader lands on. Pick one framing (recommend: conditional, matching Consequences) and make the Decision bullet match it.