feat(kyberforge): execute plugin-to-apm marketplace conversion

Why:
ADR-0015 established that Microsoft APM (apm.yml + .apm/) should replace
this repo's hand-authored plugin.json/marketplace.json model, with those
files becoming compiled output of `apm pack` instead of files edited by
hand via the (now-retired) plugin-author/marketplace-author skills.
Issue #90 was the deferred execution of that decision, gated on #88
(apm tooling) and #89 (apm-native agent-author/skill-author routing).

Implementation notes:
- All six plugins (bin, core, git, gitea, kyberforge, lint) now carry
  apm.yml + .apm/{skills,agents,hooks} as their authoring source. Skills
  moved with a plain git mv (content-identical across targets). Agents
  were re-authored, not moved: per ADR-0016, .apm/agents/*.agent.md
  compiles verbatim to both Claude and Copilot, so plugin-scope agents
  now carry only name/description/model/source_keys -- no tools: field,
  no Claude-only knobs (isolation, maxTurns, effort, memory,
  permissionMode).
- Root apm.yml registers all 7 marketplace packages (6 local plus
  mattpocock-skills as a remote entry) under versioning: per_package,
  matching this repo's existing independent-plugin-versioning practice.
- .claude-plugin/marketplace.json and every plugin's plugin.json are now
  apm-pack-compiled output, verified against the prior hand-maintained
  content: same names/descriptions/versions/licenses/authors, only
  cosmetic serialization differences (JSON key order, owner email vs.
  url, Unicode escaping).
- plugin-author and marketplace-author are retired now that apm-based
  authoring fully replaces their job; kyberforge bumped 1.3.1 -> 1.4.0
  for that removal, and the root marketplace catalog bumped
  0.3.1 -> 0.3.2 to match, per the version-bump convention now
  documented in apm-workflow's reference docs instead of a dedicated
  script (apm has no native version-bump automation).
- Fixed hardcoded pre-.apm/ path assumptions across
  .pre-commit-config.yaml, .pre-commit-hooks.yaml,
  scripts/check-scope-walkup-sync.sh, scripts/sync-vale-styles.sh,
  scripts/check-vale-style-sync.sh, six plugins' root plugin.json
  (stale skills/hooks/agents pointer fields that check-manifests.sh
  validates), and several tests/*.bats and tests/*.sh fixtures --
  including a bats REPO_ROOT relative-path depth bug (10 files, one
  extra .apm/ directory level to walk up) and a vale probe-path
  isolation regression introduced mid-fix.
- Corrected empirically-wrong assumptions surfaced this session in
  apm-workflow/apm-install's own reference docs: `apm marketplace
  package add` does not accept local paths (only owner/repo remote
  shorthand -- local packages are registered by editing apm.yml's
  marketplace.packages[] directly); `apm compile` is a consumer-side
  AGENTS.md/CLAUDE.md generator, not the plugin.json producer, and
  hard-fails on skill/agent-only packages without --clean; `apm plugin
  init <name>` nests a stray subdirectory when run with a positional
  name arg from inside a same-named directory; no native Copilot
  marketplace output profile exists; .mcp.json is merged into the
  compiled plugin.json content-aware and target-scoped, with no
  dependencies.mcp entry needed for simple passthrough; pipx is the
  correct pip fallback on externally-managed Python environments.
- Renamed agent-author's copilot.agent.md template asset to
  copilot.agent.md.template so apm compile's recursive *.agent.md glob
  stops misparsing the placeholder template as a real agent primitive.

Impact:
plugin.json and marketplace.json are compiled artifacts from here on --
editing them by hand is no longer the workflow; edit apm.yml/.apm/ and
run apm pack. CONTEXT.md's Plugin/Plugin marketplace glossary entries
reflect this. ADR-0001 is marked superseded, ADR-0006 moot, and
ADR-0010 updated for the new .apm/agents/ path (project/user scope
unaffected, per ADR-0016). Full local verification: claude plugin
validate --strict on all 6 plugins, apm audit --ci, apm marketplace
check, check-manifests.sh, and the full test suite (165/165 bats,
13/13 shell scripts) all pass clean.

Fixes: #90
Refs: #88, #89
ADR: 0015
ADR: 0016

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ub96PyaSRD9BHPktotj1pC
This commit is contained in:
2026-08-12 18:09:37 +00:00
parent 50d5c30a3c
commit 5e232503c4
289 changed files with 741 additions and 1974 deletions

View File

@@ -1,7 +1,9 @@
# 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.
**Status: executed (2026-08-12, issue #90).** All six plugins now carry `apm.yml` + `.apm/` as
their authoring source; `.claude-plugin/marketplace.json` and every plugin's `plugin.json` are
`apm pack`-compiled output. **Supersedes ADR-0001** ("Skills are distributed via plugins... each
plugin contains its own `skills/` directory") — 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` +
@@ -31,10 +33,9 @@ new hand-maintained manifest format.
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`.
- **This supersedes ADR-0001** ("Skills are distributed via plugins... each plugin
contains its own `skills/` directory"). Executed in issue #90: skills and agents physically moved
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).
@@ -49,13 +50,11 @@ new hand-maintained manifest format.
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.
did. `plugin-author`/`marketplace-author` were deleted in issue #90's execution.
- Translating the existing plugins into `apm.yml` + `.apm/` and running the real conversion was
executed in issue #90 (https://git.dev.rkdr.net/Defame1297/holocron/issues/90, closed).
- `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries were rewritten in issue #90 to
describe the compiled-output model directly, rather than carrying a forward-pointer to this ADR.
## Considered options
@@ -89,27 +88,36 @@ correction) sorted what they document into three buckets:
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.
- **Holocron policy choice — resolved in #90.** `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, and has no native version-bump automation at all — so rather than
building a new script, the convention is now documented as guidance inside `apm-workflow`'s
reference docs (`references/marketplace.md` for the root catalog version rule,
`references/configure.md` for the per-package version-bump-on-content-edit rule), applied
manually by whoever edits `apm.yml`.
## 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`).
- ADR-0001 is superseded (issue #90).
- ADR-0006 (plugin-version-parity) is moot (issue #90): `plugin.json`/`marketplace.json` are now
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 — was deleted rather than adapted
(see "Content migration" above).
- ADR-0010 (agent sources relocated outside agents dir) was updated (issue #90) for agents now
living at `plugins/<name>/.apm/agents/*.agent.md` — the directory path changed; the pre-existing
`.agent.md` extension convention (ADR-0005/ADR-0010) and project/user scope are unaffected, per
ADR-0016.
- ADR-0014 (Vale prefilter ships from the plugin) had its hardcoded path regexes
(`plugins/<name>/skills/...`/`plugins/<name>/agents/...`) updated for the `.apm/` nesting as part
of issue #90's execution.
- `kyberforge` gained three new artifacts (issue #88) before any conversion of existing content
happened, then lost two (`plugin-author`/`marketplace-author`, deleted once issue #90 verified
parity) — net version bump 1.3.1 → 1.4.0. The root marketplace catalog bumped 0.3.1 → 0.3.2 to
match.
- ADR-0016 (a narrower decision discovered while designing issue #89) turned out to gate how
issue #90 had to re-author plugin-scope agents: `.apm/agents/*.agent.md` compiles verbatim to
both Claude and Copilot, so those files carry only `name`/`description`/`model`/`source_keys` —
existing dual-file `<name>.md`+`<name>.agent.md` pairs could not be raw-moved, only re-authored.
- Two follow-up issues tracked the remaining work, both done: #89 (`skill-author`/`agent-author`
routing adaptation, merged in #93) and #90 (the actual repo conversion, which also deleted
`plugin-author`/`marketplace-author`).