Defame1297
394052ff66
Re-review (comment 24) of fix commit e16c3dc found six new issues, mostly
introduced by that fix commit itself: a dangling reference to a Hard Rule
bullet the same commit deleted (apm-orchestrate.md/.agent.md Process step
2 still named "secret indirection"), and an ADR-0015 Decision bullet that
claimed "this ADR does not update CONTEXT.md" while the same commit had
just added a forward-pointer sentence to CONTEXT.md's Plugin/Plugin
marketplace entries. Both reworded to match what actually happened.
apm-install's APM_INSTALL_DIR escape-hatch example dropped the curl pipe
entirely (`APM_INSTALL_DIR=... sh` with nothing piped into it) — fixed in
both apm-install/SKILL.md and the installation.md research doc, verified
against the upstream Microsoft APM docs via Context7.
Neither apm-workflow nor apm-orchestrate routed to plain `apm install
[PACKAGE_REF]`, the CLI command that actually resolves/fetches
dependencies declared in apm.yml — apm-install only bootstraps the apm
binary/runtime, not per-package deps. Added a 5th "install" dispatch
action to apm-workflow (new references/install.md, SKILL.md table row,
README usage/files sync, sources.md provenance entry) and a matching
"install" operation group on apm-orchestrate so it can route there.
configure.md's apm.yml schema block was also missing the "legacy singular
`target:` CSV form is still accepted" caveat its sibling research doc
documents for the same field — added for consistency.
The sixth finding (paired .md/.agent.md Output-contract disagreement) was
checked against git-orchestrate and gitea-orchestrate's existing pairs and
found to match established repo convention (JSON schema in .md, prose
summary without the enum in .agent.md) — left unchanged as a false
positive rather than "fixed."
kyberforge bumped 1.3.0 -> 1.3.1 via agent-author's normal improve flow.
Refs: #91
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
84 lines
5.5 KiB
Markdown
84 lines
5.5 KiB
Markdown
# 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.
|