Defame1297
5e232503c4
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
124 lines
8.7 KiB
Markdown
124 lines
8.7 KiB
Markdown
# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth
|
|
|
|
**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` +
|
|
`.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 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).
|
|
- 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. `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
|
|
|
|
**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 — 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 (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`).
|