docs(kyberforge): fix PR #91 review findings in ADR-0015 and apm docs

ADR-0015's Decision bullet stated ADR-0001 was superseded as present
fact while Consequences framed it as conditional on issue #90 —
reworded Decision to match, and added a Supersedes header (repo
convention per ADR-0007/ADR-0010) so the pending change is visible
from the title. Also fixed a forward-note that misattributed the
pre-existing .agent.md convention (ADR-0005/0010) to the APM move,
and reworded the rejected-plugins/apm/ rationale to acknowledge the
shipped skills are actually generic rather than repo-specific.

CONTEXT.md's Plugin/Plugin-marketplace glossary entries got a
forward-pointer to ADR-0015 so a session-start read surfaces the
pending manifest-authoring change.

apm-orchestrate.md/.agent.md: removed a Hard Rule requiring ${VAR}
secret indirection that can never fire (the orchestrator has no
Edit/Write tool and never touches apm.yml — apm-workflow's SKILL.md
already owns this rule where content is actually written); removed
compile-manifest-check, an operation with no backing apm CLI command
anywhere in the research docs; added explicit CLI mappings for
add-package/add-marketplace so an executing agent can't invert them.

marketplace.md's release steps shelled out to raw git add/commit/
tag/push — replaced with a pointer to the git-commits/git-remotes
skills per AGENTS.md's "prefer plugin skills over raw shell" rule.

compile.md now states audit runs after compile/pack (audit scans
deployed output, not the source apm.yml) — answers a reviewer
question that had no documented answer.

Refs: #91

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
This commit is contained in:
2026-08-10 21:23:07 +00:00
parent 2305f1c315
commit e16c3dc95f
6 changed files with 28 additions and 19 deletions

View File

@@ -1,5 +1,8 @@
# 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
@@ -28,9 +31,10 @@ 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 directly supersedes ADR-0001** ("Skills are distributed via plugins... each plugin
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`.
- **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).
@@ -53,18 +57,22 @@ 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
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.
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 under
`.apm/agents/` with the `.agent.md` extension — 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.