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

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/<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.
@@ -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`).

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 |

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.

plugins/kyberforge/skills/apm-workflow/references/compile.md

@@ -42,3 +42,7 @@ apm run <script> [--param key=value]
 ```
 
 Executes a named script defined under `scripts:` in `apm.yml`, with `--param` substituting values into the script's parameters.
+
+## Gotchas
+
+- `claude plugin validate --strict` auto-scans every `.md` file directly under a compiled plugin's `agents/` directory and treats it as an agent definition requiring frontmatter, independent of any manifest declaration (this repo's own empirically-tested finding — see ADR-0010). A non-agent `.md` file (notes, provenance record, README) that ends up under `.apm/agents/` in the source tree will still fail validation once compiled to the `claude` target. Keep such files outside `.apm/agents/` (e.g. at the package root), regardless of what `apm.yml` declares.

plugins/kyberforge/skills/apm-workflow/references/marketplace.md

@@ -2,6 +2,8 @@
 topic: marketplace
 source_keys:
   - context7-microsoft-apm
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
 ---
 
 ## Building a marketplace from a producer repo
@@ -60,3 +62,8 @@ Without this block, the default versioning strategy ties every listed package to
 - **Local packages, no distribution needed yet** — local-path dependencies in `apm.yml` (`./packages/my-shared-skills`); no marketplace or registry involved.
 - **Internal catalog, still git-based, no server** — `apm marketplace add` against a local path, bare repo, `file://` URI, or a plain git host.
 - **Package-level hosting at scale / access control** — registries (Artifactory-style REST endpoint); more infrastructure, only worth it once package count or access-control needs outgrow git-based discovery.
+
+## Gotchas
+
+- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved prefixes — `anthropic-*`, `claude-*`, `agent-skills`, `official-claude-plugins` — otherwise the compiled `.claude-plugin/marketplace.json` is rejected by Claude Code's validator. This is a Claude Code platform constraint, independent of how the manifest gets authored.
+- Removing a package from `marketplace.packages[]` in `apm.yml` and re-packing changes the public/consumed catalog. Whoever/whatever is driving this skill (human or agent) should confirm before proceeding, the same way `apm publish` is treated — see `apm-orchestrate.md`'s "Hard rules" section for the existing precedent on `publish`.

plugins/kyberforge/skills/apm-workflow/references/sources.md

@@ -7,3 +7,27 @@
 - **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
 - **Contributing files:** SKILL.md, references/configure.md, references/install.md, references/marketplace.md, references/compile.md, references/audit.md
 - **Status:** `extracted`
+
+## context7-websites-code-claude
+
+- **URL:** context7:/websites/code_claude
+- **Description:** Official Claude Code documentation site indexed by Context7 — marketplace manifest schema (reserved name prefixes), `claude plugin validate` command behavior. Claude Code platform facts that hold true independent of how the compiled manifest is authored (APM or hand-authored).
+- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
+- **Contributing files:** references/marketplace.md, references/audit.md
+- **Status:** `extracted`
+
+## claude-code-plugins-docs
+
+- **URL:** https://code.claude.com/docs/en/plugins
+- **Description:** Official Claude Code plugin authoring guide — marketplace submission constraints (reserved name prefixes), `claude plugin validate` behavior and its scope relative to other CI checks.
+- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
+- **Contributing files:** references/marketplace.md, references/audit.md
+- **Status:** `extracted`
+
+## claude-code-subagents-docs
+
+- **URL:** https://code.claude.com/docs/en/sub-agents
+- **Description:** Official Claude Code subagent reference — definition format, all frontmatter fields, scope priority, built-in agents, CLI flags, environment variables, known limitations
+- **Research doc:** plugins/kyberforge/docs/research/docs/claude-code-plugins/sources.md
+- **Contributing files:** (none)
+- **Status:** `referenced`