From 92e7ff26aae59736083b8305137bd9c46ea90676 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Tue, 11 Aug 2026 12:09:43 +0000 Subject: [PATCH] docs(kyberforge): narrow issue #89 scope, migrate CC platform facts to apm-workflow A grill-me session determined plugin-author/marketplace-author are fully superseded by the landed apm-install/apm-workflow/apm-orchestrate artifacts and will be deleted (not adapted) under issue #90, narrowing issue #89 to skill-author/agent-author only; forge stays untouched. ADR-0015 is amended to record this correction plus a three-way content-migration audit. Claude Code platform-constraint facts that lived only in plugin-author/marketplace-author (reserved name prefixes, the ADR-0010 agents/ stray-.md validator gotcha, claude plugin validate as a terminal check, and a removal/re-pack confirm-before-proceeding note) remain true post-conversion and are migrated into apm-workflow's reference docs via kyberforge:skill-author, which also updated the skill's README and sources.md provenance records. Dual-manifest-specific conventions (ADR-0006 parity, CC/Copilot field-placement split) do not carry forward since they no longer apply. ADR: 0015 --- ...m-replaces-plugin-marketplace-authoring.md | 46 ++++++++++++++++--- .../kyberforge/skills/apm-workflow/README.md | 6 +-- .../skills/apm-workflow/references/audit.md | 6 +++ .../skills/apm-workflow/references/compile.md | 4 ++ .../apm-workflow/references/marketplace.md | 7 +++ .../skills/apm-workflow/references/sources.md | 24 ++++++++++ 6 files changed, 83 insertions(+), 10 deletions(-) diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md index a2c9901..e64e07d 100644 --- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md +++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md @@ -38,9 +38,18 @@ new hand-maintained manifest format. - 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). +- 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. 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). @@ -66,11 +75,33 @@ plugin for a single consumer isn't worth it yet. Accepted as an explicit tradeof 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 — 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. + ## 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-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//.apm/agents/` — the directory path changes, not the pre-existing `.agent.md` extension convention (ADR-0005/ADR-0010, unaffected) — not resolved by this ADR. @@ -79,5 +110,6 @@ outside holocron's own conversion. 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. +- 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`). diff --git a/plugins/kyberforge/skills/apm-workflow/README.md b/plugins/kyberforge/skills/apm-workflow/README.md index 9c88640..1996384 100644 --- a/plugins/kyberforge/skills/apm-workflow/README.md +++ b/plugins/kyberforge/skills/apm-workflow/README.md @@ -27,7 +27,7 @@ Requires the `apm` binary and (for runtime-driven scripts) an agent runtime alre | `SKILL.md` | Dispatch table and cross-cutting gotchas | | `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, registries | | `references/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills | -| `references/marketplace.md` | Building/registering a marketplace, package registration, versioning | -| `references/compile.md` | apm compile / pack / publish / run | -| `references/audit.md` | apm audit, apm audit --ci, apm marketplace check, CI wiring, frozen installs | +| `references/marketplace.md` | Building/registering a marketplace, package registration, versioning, Claude Code reserved-name/publish-confirm gotchas | +| `references/compile.md` | apm compile / pack / publish / run, claude plugin validate agents/ gotcha | +| `references/audit.md` | apm audit, apm audit --ci, apm marketplace check, CI wiring, frozen installs, claude plugin validate terminal check | | `references/sources.md` | Provenance chain — research sources that informed this skill | diff --git a/plugins/kyberforge/skills/apm-workflow/references/audit.md b/plugins/kyberforge/skills/apm-workflow/references/audit.md index a286e97..c9ec111 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/audit.md +++ b/plugins/kyberforge/skills/apm-workflow/references/audit.md @@ -2,6 +2,8 @@ topic: audit source_keys: - context7-microsoft-apm + - context7-websites-code-claude + - claude-code-plugins-docs --- ## `apm audit` @@ -47,3 +49,7 @@ jobs: ## Frozen installs `apm install --frozen` fails instead of silently re-resolving if the lockfile is out of date — the CI equivalent of `npm ci` vs `npm install`. Use in any CI job that must not be allowed to drift the lockfile. + +## Claude Code validation is a separate terminal check + +For packages compiling to the `claude` target, also run `claude plugin validate [--strict]` against the compiled output as a terminal check. `apm audit`/`apm audit --ci` do not check Claude Code-marketplace-specific schema rules (reserved prefixes, the `agents/` stray-file behavior — see `references/compile.md` — etc.), so they don't substitute for it. diff --git a/plugins/kyberforge/skills/apm-workflow/references/compile.md b/plugins/kyberforge/skills/apm-workflow/references/compile.md index 6ea2972..b85c550 100644 --- a/plugins/kyberforge/skills/apm-workflow/references/compile.md +++ b/plugins/kyberforge/skills/apm-workflow/references/compile.md @@ -42,3 +42,7 @@ apm run