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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user