Files

Defame1297 e16c3dc95f 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

2026-08-10 21:23:07 +00:00

5.4 KiB

Raw Blame History

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"/"Skill"/"Plugin marketplace" glossary entries remain accurate as written until issue #90 actually executes — this ADR does not update 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.

5.4 KiB Raw Blame History