From 1d07d1a76ba2a1a8fde6ca096c39d07b1ba5e12e Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 17:06:07 +0000
Subject: [PATCH 01/11] docs(kyberforge): add Microsoft APM research reference
 set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture Microsoft's Agent Package Manager (APM) — overview, install,
config, CLI reference, registries/marketplace, monorepo shapes,
testing/validation, troubleshooting, and examples — as structured
reference docs under plugins/kyberforge/docs/research/docs/microsoft-apm/.

Lays the groundwork for issue #88 (build agents/skills to execute a
marketplace-to-APM conversion of this repo).
---
 .../docs/microsoft-apm/cli-reference.md       |  99 +++++++++++++++
 .../docs/microsoft-apm/configuration.md       | 118 ++++++++++++++++++
 .../research/docs/microsoft-apm/examples.md   |  80 ++++++++++++
 .../docs/microsoft-apm/installation.md        |  39 ++++++
 .../marketplace-and-registries.md             |  76 +++++++++++
 .../microsoft-apm/monorepo-and-repo-shapes.md |  71 +++++++++++
 .../research/docs/microsoft-apm/overview.md   |  37 ++++++
 .../research/docs/microsoft-apm/sources.md    |   8 ++
 .../microsoft-apm/testing-and-validation.md   |  51 ++++++++
 .../docs/microsoft-apm/troubleshooting.md     |  52 ++++++++
 10 files changed, 631 insertions(+)
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/configuration.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/examples.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/marketplace-and-registries.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/overview.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/testing-and-validation.md
 create mode 100644 plugins/kyberforge/docs/research/docs/microsoft-apm/troubleshooting.md

diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md
new file mode 100644
index 0000000..0a24d22
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/cli-reference.md
@@ -0,0 +1,99 @@
+---
+topic: cli-reference
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Install
+
+```bash
+apm install [PACKAGE_REF...] [OPTIONS]
+```
+
+With no arguments, resolves and installs everything declared in `apm.yml` against `apm.lock.yaml`. Explicit `PACKAGE_REF` arguments (e.g. `acme/internal-tools#^1.0.0`) install and add that dependency. `apm install --update` re-resolves and accepts new upstream content even when it doesn't match the recorded lockfile hash (see troubleshooting). `apm install --target agent-skills` generates a vendor-neutral output directory for IDE-agnostic tool support instead of a harness-specific one.
+
+## Compile
+
+```bash
+apm compile
+```
+
+Generates per-target output (Claude, Copilot, etc.) from the vendor-neutral `.apm/` primitive source tree, per the `compilation:` block in `apm.yml`.
+
+## Pack
+
+```bash
+apm pack --dry-run              # resolve and print; do not write
+apm pack --offline              # cached refs only
+apm pack --include-prerelease   # allow pre-release tags
+apm pack -v                     # per-entry resolution detail
+apm pack --marketplace=claude --json   # JSON output for CI pipelines
+```
+
+Bundles a producer package into a distributable artifact.
+
+## Publish
+
+```bash
+apm publish --package acme/my-skill --dry-run -v
+apm publish --package acme/my-skill
+```
+
+Publishes a producer package (root containing `apm.yml`, `.apm/`, and optionally a `registries:` block) to a registry. Always dry-run with `-v` first to see resolution detail before publishing for real.
+
+## Runtime management
+
+```bash
+apm runtime setup copilot              # install with APM defaults
+apm runtime setup codex --version 0.20.0   # pinned version
+apm runtime setup llm --vanilla        # skip APM-managed config
+apm runtime list                       # what's installed
+apm runtime status                     # which runtime `apm run` will pick
+apm runtime remove gemini -y           # uninstall without prompting
+```
+
+## Run
+
+```bash
+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 (used, for example, when the script wraps a Gemini CLI invocation).
+
+## Audit (validation)
+
+```bash
+apm audit                  # local: scan deployed files for hidden Unicode
+apm audit --ci             # CI gate: lockfile consistency + drift replay + policy
+apm audit --file <path>    # standalone: scan an arbitrary file
+```
+
+See `testing-and-validation.md` for CI wiring and exit-code behavior.
+
+## Marketplace
+
+```bash
+apm marketplace init                          # add the marketplace: block to apm.yml
+apm marketplace check                         # validate every listed package ref resolves
+apm marketplace package add <path> --name <n> # register a local package into the marketplace
+apm marketplace add <source> [--name <n>]     # register a marketplace as a consumer (see marketplace-and-registries.md for source forms)
+```
+
+## Plugin scaffolding
+
+```bash
+apm plugin init <name> --yes
+```
+
+Scaffolds a new package's `apm.yml` + `.apm/` skeleton in the current directory.
+
+## Config
+
+```bash
+apm config set <key> <value>
+apm config get <key>
+apm config unset <key>
+apm experimental enable registries   # required before registry.* config takes effect
+```
+
+Used for workstation-level settings such as private registry URLs/tokens (see `marketplace-and-registries.md`).
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/configuration.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/configuration.md
new file mode 100644
index 0000000..b1012bf
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/configuration.md
@@ -0,0 +1,118 @@
+---
+topic: configuration
+source_keys:
+  - context7-microsoft-apm
+---
+
+## The `apm.yml` manifest
+
+Every APM package — producer or consumer — is rooted in an `apm.yml` file. The only required fields are `name` and `version` (SemVer):
+
+```yaml
+name: my-pkg
+version: 1.0.0
+```
+
+## Full schema
+
+```yaml
+name: my-pkg
+version: 1.0.0
+description: Code review skills for Python services
+author: Jane Doe            # plain string, or {name, email?, url?} object
+license: MIT
+homepage: https://example.com/my-pkg
+repository: https://github.com/org/my-pkg
+keywords: [ai, review, python]
+
+# Constrains what .apm/ may contain: instructions, skill, hybrid, or prompts
+type: skill
+
+# Pins which harnesses this package compiles to. Prefer the plural `targets:`
+# list form; the legacy singular `target:` CSV form is still accepted.
+targets:
+  - copilot
+  - claude
+
+# "auto" publishes the authoritative local source layout, or list explicit
+# repo paths to define the complete publication set.
+includes: auto
+
+dependencies:
+  apm:
+    - microsoft/apm-sample-package#v1.0.0        # pinned to a tag
+    - github/awesome-copilot/skills/review-and-refactor  # single primitive
+  mcp:
+    - microsoft/azure-devops-mcp                 # MCP server dependency
+  lsp:
+    - name: pyright
+      command: pyright-langserver
+      args: ["--stdio"]
+      extensionToLanguage:
+        ".py": python
+
+# Same shape as dependencies, but excluded from the shipped artifact —
+# for dev-only tooling and tests.
+devDependencies:
+  apm:
+    - my-org/internal-test-skills
+
+# Named commands runnable via `apm run <name>`
+scripts:
+  start: "copilot -p 'README.prompt.md'"
+  review: "copilot -p 'code-review.prompt.md'"
+
+compilation:
+  target: all
+  strategy: distributed
+  exclude:
+    - "apm_modules/**"
+  placement:
+    min_instructions_per_file: 1
+
+policy:
+  fetch_failure_default: warn
+
+registries:
+  public-apm:
+    url: https://registry.example.com/api/public-apm
+  default: public-apm
+
+marketplace:
+  owner:
+    name: contoso
+    url: https://github.com/contoso
+  packages:
+    - name: code-review
+      source: contoso/code-review
+      version: "^1.0.0"
+      tags: [review, quality]
+```
+
+## Dependency reference forms
+
+`dependencies.apm` entries accept several forms: a pinned tag (`owner/repo#tag`), a plain repo (uses default branch), a single primitive path within a repo, a raw git URL, a `git:`/`path:`/`ref:` object for finer control, or a local relative path (`./packages/my-shared-skills`).
+
+## MCP server secrets
+
+Secrets for MCP server config (headers, env vars) should use `${VAR}` indirection rather than literal values, so they're resolved by APM or the host harness at install/runtime and never committed to the manifest:
+
+```yaml
+mcp:
+  - name: linear
+    registry: false
+    transport: http
+    url: https://mcp.linear.app/sse
+    headers:
+      Authorization: "Bearer ${LINEAR_TOKEN}"
+  - name: my-internal
+    registry: false
+    transport: stdio
+    command: my-server
+    env:
+      API_TOKEN: "${MY_API_TOKEN}"
+```
+
+## Registries
+
+Registries are optional — any git repo is a valid package source by default — but a project can declare named registries and pick a `default:` for shorthand dependency resolution, useful for teams centralizing internal packages.
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/examples.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/examples.md
new file mode 100644
index 0000000..33faf58
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/examples.md
@@ -0,0 +1,80 @@
+---
+topic: examples
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Producer quickstart
+
+A minimal consumer flow: install a package by owner/name, then compile it to the active harness's format.
+
+```bash
+apm install your-org/your-project
+apm compile
+```
+
+## Authoring an agent primitive
+
+Agents are markdown files with YAML frontmatter defining metadata, model constraints, and tool permissions, followed by a prose system-instructions body:
+
+```markdown
+---
+name: security-review
+description: Reviews diffs for OWASP top-10 issues and missing input validation.
+model: gpt-5
+tools:
+  Read: true
+  Grep: true
+---
+
+You are a security reviewer. Your job is to inspect the working diff
+for...
+```
+
+## On-disk package layout
+
+```text
+.apm/
+  skills/
+    my-skill/
+      SKILL.md
+      scripts/
+      references/
+      assets/
+  prompts/
+    review.prompt.md
+  instructions/
+    style.instructions.md
+  agents/
+    cli-logging-expert.agent.md
+  hooks/
+    pre-commit.json
+```
+
+## Publish → install round trip
+
+```bash
+# Producer: package root with apm.yml, .apm/, and (optionally) a registries: block
+apm publish --package acme/my-skill --dry-run -v
+apm publish --package acme/my-skill
+
+# Consumer: another repo
+apm install acme/internal-tools#^1.0.0
+```
+
+## Cross-tool / IDE-agnostic install
+
+```bash
+apm install --target agent-skills
+```
+
+Generates a vendor-neutral skills directory usable across IDEs rather than a single harness-specific output.
+
+## Running a script with parameters (Gemini CLI example)
+
+```bash
+# Run a script from apm.yml, substituting a parameter
+apm run start --param service_name=api-gateway
+```
+
+Once a runtime like Gemini CLI is installed via `apm runtime setup gemini`, it can also be invoked directly for interactive mode (`gemini`), sandboxed/isolated execution (`gemini -s`), or with an explicit model (`gemini -m gemini-2.5-pro-preview`).
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
new file mode 100644
index 0000000..c617e2f
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
@@ -0,0 +1,39 @@
+---
+topic: installation
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Quick install (recommended)
+
+A one-line install script auto-detects the platform, downloads the latest binary, and configures the system `PATH`:
+
+```bash
+curl -sSL https://aka.ms/apm-unix | sh
+```
+
+On Windows, the installer adds both the current directory and the bin directory to `PATH`, so it works from native shells, Git Bash, and process APIs alike.
+
+## Customizing the install
+
+- **Pin a specific version**: append `@vX.Y.Z` to the piped script arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
+- **Custom install directory**: set `APM_INSTALL_DIR` before running the script, e.g. `APM_INSTALL_DIR=$HOME/.local/bin sh`.
+- **Air-gapped / GitHub Enterprise mirror**: set `GITHUB_URL` and `VERSION` env vars against a local `install.sh`, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
+
+## Alternative install methods
+
+- **pip**: `pip install apm-cli` — requires Python 3.10 or higher.
+- **Manual binary**: download the platform-specific archive from the GitHub releases page, extract it, move the binary to a permanent directory, and add that directory to `PATH`.
+
+## Installing agent runtimes
+
+APM itself doesn't execute agents, but it can install and manage the runtimes that do, via `apm runtime setup <name>`:
+
+```bash
+apm runtime setup copilot   # recommended default
+apm runtime setup codex
+apm runtime setup gemini
+apm runtime setup llm
+```
+
+Installing GitHub Copilot CLI through APM pulls it from the public npm registry and requires Node.js v22+ and npm v10+; no authentication is needed for the install step itself. Use `apm runtime list` to see which runtimes are currently installed and which one `apm run` will pick by default.
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/marketplace-and-registries.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/marketplace-and-registries.md
new file mode 100644
index 0000000..5e3d96f
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/marketplace-and-registries.md
@@ -0,0 +1,76 @@
+---
+topic: marketplace-and-registries
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Building a marketplace from a producer repo
+
+Standard sequence to turn a repo into an APM marketplace (a curated set of packages other consumers can point at):
+
+```bash
+apm marketplace init                          # 1. add the marketplace: block to apm.yml
+$EDITOR apm.yml                               # 2. describe each package
+apm marketplace check                         # 3. validate refs resolve
+apm pack                                      # 4. build marketplace artifacts
+git add apm.yml .claude-plugin/marketplace.json
+git commit -m "Release v1.0.0" && git tag v1.0.0 && git push --tags
+```
+
+Note the build step emits a `.claude-plugin/marketplace.json` artifact alongside `apm.yml` — APM's `apm pack` generates the Claude Code-native marketplace manifest as one of its per-target compile outputs, so an APM-based marketplace can still be consumed by Claude Code's existing marketplace mechanism without a separate hand-maintained file.
+
+## Registering a marketplace as a consumer
+
+`apm marketplace add` accepts many source shapes — this is the distribution/consumption side:
+
+```bash
+# GitHub shorthand
+apm marketplace add my-org/awesome-agents
+
+# GitLab via host shorthand
+apm marketplace add gitlab.com/my-org/awesome-agents --host gitlab.com
+
+# Azure DevOps Services / Server, Gitea, Bitbucket Server — any self-hosted git, pinned with #ref
+apm marketplace add https://gitea.example.com/org/repo.git#v1.0.0 --name custom
+
+# Hosted marketplace.json URL
+apm marketplace add https://catalog.example.com/marketplace.json --name catalog
+
+# SSH
+apm marketplace add git@gitea.example.com:org/repo.git --name custom
+
+# Local filesystem (bare repo, working directory, or marketplace.json file directly) — no server needed
+apm marketplace add /srv/marketplaces/agent-forge.git --name agent-forge
+apm marketplace add ./vendor/marketplace.json --name vendor
+apm marketplace add file:///srv/marketplaces/agent-forge.git --name agent-forge
+```
+
+The local-filesystem and `file://` forms mean a fully local, offline marketplace — pointing `apm marketplace add` at a path or bare repo on disk — needs no hosted registry or network access at all. This is the direct fit for an internal/homelab setup that wants package discovery without standing up infrastructure.
+
+## Private / self-hosted registries (experimental)
+
+Distinct from `marketplace add` (which points at a *catalog* of packages), registries are a REST endpoint for hosting the packages themselves (e.g., Artifactory, JFrog, or any endpoint implementing the standard Registry HTTP API). This is opt-in and currently experimental:
+
+```bash
+apm experimental enable registries
+
+# Project-level: apm.yml has a registries: block and registry-routed deps
+apm install
+
+# Workstation-level config only (no registries: block committed to apm.yml)
+apm config set registry.corp-main.url https://artifactory.corp.example.com/apm
+apm config set registry.corp-main.token eyJ...
+apm config set registry.corp-main.default true
+apm install
+
+# CI: pass the token via env var, never commit it
+APM_REGISTRY_TOKEN_CORP_MAIN=eyJ... apm install --frozen
+```
+
+`apm config get`/`apm config unset` manage individual keys the same way. Public registries need no authentication; private ones need a token configured per the above.
+
+## Which mechanism to use
+
+- **Local packages, no distribution needed yet**: local-path dependencies in `apm.yml` (`./packages/my-shared-skills`) — no marketplace or registry involved at all.
+- **Internal catalog, still git-based, no server**: `apm marketplace add` against a local path, bare repo, or `file://` URI, or a plain git host (Gitea, GitHub, etc.) — this is the natural fit if this repo's own git remote should double as the marketplace source.
+- **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.
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md
new file mode 100644
index 0000000..6c5c161
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/monorepo-and-repo-shapes.md
@@ -0,0 +1,71 @@
+---
+topic: monorepo-and-repo-shapes
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Repo shapes
+
+APM documents named patterns for how a repo can host multiple packages. Two are directly relevant to converting an existing multi-plugin repo:
+
+### Monorepo
+
+Multiple independent plugins under one repo, each with its own manifest and `.apm/` tree, plus a root `apm.yml` that lists them as local-path packages:
+
+```text
+my-monorepo/
+  apm.yml                          # marketplace + local-path packages
+  packages/
+    plugin-a/
+      apm.yml                      # plugin-a's manifest
+      .apm/
+        agents/
+          expert.agent.md
+        instructions/
+          style.instructions.md
+        skills/
+          my-skill/
+            SKILL.md
+    plugin-b/
+      apm.yml
+      .apm/
+        prompts/
+          review.prompt.md
+        hooks/
+          pre-tool.json
+```
+
+### Monorepo-hybrid
+
+The variant for a repo that both ships its own plugins *and* curates/re-lists others: multiple plugins live under a packages directory, each with its own manifest for independent compilation and testing, while a single root marketplace lists them all as local-path entries. This is the closest documented match to this repo's current `plugins/<name>/` layout (each plugin already self-contained with its own skills/agents/hooks).
+
+## Scaffolding a monorepo
+
+```bash
+apm plugin init plugin-a --yes              # run from inside packages/plugin-a
+apm plugin init plugin-b --yes              # run from inside packages/plugin-b
+cd ../..
+apm marketplace init --owner acme-org --name acme-monorepo
+apm marketplace package add ./packages/plugin-a --name plugin-a
+apm marketplace package add ./packages/plugin-b --name plugin-b
+```
+
+`apm plugin init` scaffolds a single package's `apm.yml` + `.apm/` skeleton; `apm marketplace package add` registers an already-existing local package path into the root marketplace listing without re-scaffolding it — this is the command to point at each of this repo's existing `plugins/*` directories once each has its own `apm.yml`.
+
+## Per-package versioning
+
+Plugins in a monorepo don't have to share a version with the root or each other:
+
+```yaml
+marketplace:
+  versioning: { strategy: per_package }
+  packages:
+    - { name: plugin-a, source: ./packages/plugin-a, version: 2.0.0 }
+    - { name: plugin-b, source: ./packages/plugin-b, version: 0.1.0 }
+```
+
+Without this, the default versioning strategy ties all listed packages to the marketplace/root version — worth checking explicitly, since this repo's plugins (git, gitea, kyberforge, lint, core, bin) currently version independently (see the patch-bump-per-plugin pattern already in this repo's commit history).
+
+## What's still a manual translation, not an APM feature
+
+Nothing in the docs describes an automated converter from an existing `.claude-plugin/marketplace.json` + `plugin.json` pair into `apm.yml`. The shapes are compatible (`apm pack` emits `.claude-plugin/marketplace.json` as a compile target), but populating each plugin's `apm.yml` metadata, `type:`, `targets:`, and `dependencies:` from the current manifests is manual per-package work, not a single migration command.
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/overview.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/overview.md
new file mode 100644
index 0000000..610a988
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/overview.md
@@ -0,0 +1,37 @@
+---
+topic: overview
+source_keys:
+  - context7-microsoft-apm
+---
+
+## What APM is
+
+APM (Agent Package Manager) applies a standard package-management model — declare, lock, install, audit — to AI agent configuration. It manages the skills, prompts, instructions, agents, and tools an AI coding assistant needs, so that configuration is version-controlled, peer-reviewed, and reproducible across developer machines and CI pipelines, the same way a dependency manager keeps application code reproducible.
+
+## Scope: install and integrity plane only
+
+APM is deliberately narrow. It governs what reaches disk and enforces policy conformance on that install — nothing more. It is explicitly **not**:
+- A runtime for executing agents
+- An LLM gateway or model-call proxy
+- A fine-tuning tool
+- A marketplace requiring a specific distribution platform
+
+It also does not manage agent permissions or version model weights. Any git repository can serve as a valid APM package — there's no mandated central registry, though named registries are supported for teams that want one.
+
+## Producer / consumer model
+
+- A **producer** package is a directory containing an `apm.yml` manifest, primitives under `.apm/`, and a `README.md`.
+- A **consumer** project declares dependencies on producer packages in its own `apm.yml` and installs them with `apm install`.
+- `apm compile` generates per-target output (e.g., Claude-specific or Copilot-specific files) from the vendor-neutral `.apm/` source tree.
+- `apm pack` bundles a producer package into a distributable artifact.
+
+## Package anatomy
+
+APM packages organize content into subdirectories under `.apm/` by primitive type:
+- `skills/` — multi-file capabilities (each with its own `SKILL.md`, plus optional `scripts/`, `references/`, `assets/`)
+- `prompts/` — reusable prompt templates (`*.prompt.md`)
+- `instructions/` — always-on rules (`*.instructions.md`)
+- `agents/` — model and tool configuration for a named agent (`*.agent.md`)
+- `hooks/` — host-harness lifecycle event bindings
+
+This mirrors how the vendor-neutral primitives compile down to provider-specific formats (Claude, Copilot, etc.) via `apm compile`.
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
new file mode 100644
index 0000000..2c7ddf5
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
@@ -0,0 +1,8 @@
+# Sources
+
+## context7-microsoft-apm
+
+- **URL:** context7:/microsoft/apm
+- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
+- **Contributing files:** overview.md, installation.md, configuration.md, cli-reference.md, examples.md, troubleshooting.md, testing-and-validation.md, marketplace-and-registries.md, monorepo-and-repo-shapes.md
+- **Status:** `extracted`
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/testing-and-validation.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/testing-and-validation.md
new file mode 100644
index 0000000..390ff86
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/testing-and-validation.md
@@ -0,0 +1,51 @@
+---
+topic: testing-and-validation
+source_keys:
+  - context7-microsoft-apm
+---
+
+## `apm audit`
+
+APM's built-in validation/integrity tool, usable both locally and as a CI gate:
+
+```bash
+apm audit                  # local: scan deployed files for hidden Unicode
+apm audit --ci             # CI gate: lockfile consistency + drift replay
+apm audit --file <path>    # standalone: scan an arbitrary file
+```
+
+`apm audit --ci` runs baseline lockfile checks, install-replay drift detection (does a clean `apm install` reproduce what's on disk), and org policy checks. It returns exit code `0` on success and `1` on any violation, so it composes as a normal CI gate step. It's meant to sit alongside — not replace — existing lint/test/security-scan CI steps: it specifically covers AI agent configuration integrity, hidden-content scanning, lockfile verification, and policy enforcement, not general code correctness.
+
+## Policy checks
+
+`apm audit --ci` auto-discovers an org policy from the git remote if `--policy`/`--policy-source` isn't given explicitly; `--no-policy` skips policy discovery for a single invocation. This lets an org centrally define required checks (e.g., which primitive types are allowed, required metadata fields) without every package repo repeating the config.
+
+## Marketplace ref validation
+
+Separately from `apm audit`, `apm marketplace check` validates that every package reference declared in a marketplace's `apm.yml` actually resolves (correct path/ref, manifest present) before you build or publish — this is the step that catches a typo'd local path or a stale pinned tag before it ships.
+
+## CI integration example (GitHub Actions)
+
+```yaml
+jobs:
+  apm-audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install apm-cli==X.Y.Z  # pin to the version you standardize on
+      - run: apm install
+      - run: apm audit --ci -f sarif --output apm-audit.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: apm-audit.sarif }
+```
+
+`-f sarif --output <file>` emits SARIF, which GitHub Code Scanning can ingest directly for inline annotations on PRs — useful if this repo's CI already surfaces findings that way.
+
+## Frozen installs
+
+`apm install --frozen` (seen in the private-registry install flow) fails instead of silently re-resolving if the lockfile is out of date — the CI equivalent of `npm ci` vs `npm install`. Worth using in any CI job that shouldn't be allowed to drift the lockfile.
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/troubleshooting.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/troubleshooting.md
new file mode 100644
index 0000000..1de34d5
--- /dev/null
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/troubleshooting.md
@@ -0,0 +1,52 @@
+---
+topic: troubleshooting
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Manifest / lockfile ref mismatch
+
+Happens when the version or ref declared in `apm.yml` no longer matches what's recorded in the stale `apm.lock.yaml`:
+
+```text
+<owner>/<repo>: manifest ref 'v2' != lockfile ref 'v1'
+N ref mismatch(es) -- run 'apm install' to update lockfile
+```
+
+Fix: run `apm install` to reconcile the lockfile with the manifest.
+
+## Missing lockfile
+
+Occurs when a command that needs a resolved dependency graph runs before the first install:
+
+```text
+lockfile not found at apm.lock.yaml; run 'apm install' to generate it
+```
+
+## Lockfile version mismatch
+
+The installed `apm` binary is older than the lockfile format it's being asked to read:
+
+```text
+[x] apm.lock.yaml uses lockfile_version "2", this binary supports "1"
+    [>] Upgrade APM: see https://...
+```
+
+Fix: upgrade the APM binary to a version that supports the newer lockfile schema.
+
+## Content hash mismatch (possible supply-chain issue)
+
+Raised when downloaded dependency bytes don't match the hash recorded in the lockfile:
+
+```text
+[x] Content hash mismatch for <owner>/<repo>: expected <sha>, got <sha>.
+The downloaded content differs from the lockfile record. This may
+indicate a supply-chain attack. Use 'apm install --update' to accept
+new content and update the lockfile.
+```
+
+This is a fail-closed integrity check — treat an unexpected occurrence as a security signal, not just a stale-cache annoyance. Only use `apm install --update` once you've confirmed the new upstream content is legitimate (e.g., a real re-tag), since it deliberately overwrites the recorded hash.
+
+## Dependency version conflicts
+
+Direct and transitive dependency constraints are resolved by intersecting version ranges. Example: a manifest directly depends on `acme/foo#^1.2.0`, and a transitive dependency (`acme/bar`) pulls in `acme/foo#^1.5.0`. The effective constraint is the intersection, `[>=1.5.0, <2.0.0)`, and APM picks the highest tag in that range. If the two constraints don't overlap at all (e.g. `^1.2.0` vs. `^2.0.0`), resolution fails closed rather than silently picking one side — install errors out instead of guessing.
-- 
2.43.0


From 0e421acdbbf8697263f33da2f7043efa473204c4 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 17:42:31 +0000
Subject: [PATCH 02/11] docs(adr): add ADR-0015 for outright APM conversion

Records the grill-with-docs decision on issue #88: replace the
hand-authored plugin/marketplace manifest model with Microsoft APM
(apm.yml + .apm/) as this repo's authoring source of truth. The
plugins/<name>/ monorepo-hybrid layout survives; marketplace.json and
provider plugin.json files become compiled output. Supersedes
ADR-0001; touches but does not resolve ADR-0006/0010/0014. Follow-up
work tracked in issues #89 and #90.
---
 ...m-replaces-plugin-marketplace-authoring.md | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md

diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
new file mode 100644
index 0000000..446c3bf
--- /dev/null
+++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
@@ -0,0 +1,74 @@
+# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth
+
+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 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`.
+- 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. 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.
+
+## 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-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.
-- 
2.43.0


From c48c9f54902744c045f16d73b3361b5739697675 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 17:43:23 +0000
Subject: [PATCH 03/11] feat(kyberforge): add apm-install skill

Wraps apm CLI binary install and agent-runtime setup
(apm runtime setup/list/status/remove), the bootstrap step
ahead of apm-workflow's configure/compile/audit loop.
---
 .../kyberforge/skills/apm-install/README.md   | 22 ++++++++
 .../kyberforge/skills/apm-install/SKILL.md    | 53 +++++++++++++++++++
 .../skills/apm-install/references/sources.md  |  9 ++++
 3 files changed, 84 insertions(+)
 create mode 100644 plugins/kyberforge/skills/apm-install/README.md
 create mode 100644 plugins/kyberforge/skills/apm-install/SKILL.md
 create mode 100644 plugins/kyberforge/skills/apm-install/references/sources.md

diff --git a/plugins/kyberforge/skills/apm-install/README.md b/plugins/kyberforge/skills/apm-install/README.md
new file mode 100644
index 0000000..5cacb8f
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-install/README.md
@@ -0,0 +1,22 @@
+# apm-install
+
+Installs and configures the `apm` (Agent Package Manager) CLI and the agent runtimes it manages.
+
+## What it does
+
+Covers the two provisioning steps for working with apm: installing the `apm` binary itself (quick-install script, pinned version, air-gapped mirror, or pip), and installing/managing an agent runtime apm drives (`apm runtime setup copilot|codex|gemini|llm`, listing installed runtimes, checking which one `apm run` defaults to).
+
+## Usage
+
+```
+/apm-install
+```
+
+Once `apm` and a runtime are in place, use `apm-workflow` for authoring `apm.yml`, scaffolding packages/marketplaces, compiling, packing, publishing, and auditing.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/sources.md` | Provenance chain — research sources that informed this skill |
diff --git a/plugins/kyberforge/skills/apm-install/SKILL.md b/plugins/kyberforge/skills/apm-install/SKILL.md
new file mode 100644
index 0000000..318f0b3
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-install/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: apm-install
+description: >
+  Use when the user wants to install the apm (Agent Package Manager) CLI
+  itself, pin or upgrade its version, set up an air-gapped/enterprise mirror
+  install, or install and manage an agent runtime that apm drives (Copilot
+  CLI, Codex, Gemini, generic llm) — "install apm", "set up apm", "pin apm to
+  a version", "apm runtime setup", "which runtime will apm run pick". Do not
+  use for authoring apm.yml, scaffolding a package/marketplace, compiling,
+  packing, publishing, or running apm audit — use apm-workflow for those.
+metadata:
+  category: apm
+  source_keys:
+    - context7-microsoft-apm
+---
+
+## Gotchas
+
+- apm does not execute agents itself — it only installs and manages the runtimes that do. "Install apm" and "install a runtime apm manages" are two separate steps; don't conflate them or skip the second when the user actually wants a working agent CLI, not just the package manager.
+- The air-gapped/enterprise mirror path needs `GITHUB_URL` and `VERSION` set together against a downloaded `install.sh` — it does not work through the piped one-liner form.
+- `pip install apm-cli` requires Python 3.10+; the quick-install script has no such prerequisite. Prefer the quick-install script unless the environment is pip-first.
+- Installing the Copilot CLI runtime through `apm runtime setup copilot` requires Node.js v22+ and npm v10+ already present — apm does not install Node/npm for you.
+
+## Install apm
+
+Default:
+
+```bash
+curl -sSL https://aka.ms/apm-unix | sh
+```
+
+Escape hatches — combine as needed:
+- Pin a version: append `@vX.Y.Z` to the piped script's arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
+- Custom install directory: set `APM_INSTALL_DIR` before running, e.g. `APM_INSTALL_DIR=$HOME/.local/bin sh`.
+- Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
+- pip (Python 3.10+ environments): `pip install apm-cli`.
+- Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.
+
+Verify with `apm --version`.
+
+## Install or manage an agent runtime
+
+Default:
+
+```bash
+apm runtime setup copilot
+```
+
+Other targets: `apm runtime setup codex`, `apm runtime setup gemini`, `apm runtime setup llm`.
+
+- `apm runtime list` — show installed runtimes.
+- `apm runtime status` — show which runtime `apm run` will pick by default.
+- `apm runtime remove <name> -y` — uninstall without an interactive prompt.
diff --git a/plugins/kyberforge/skills/apm-install/references/sources.md b/plugins/kyberforge/skills/apm-install/references/sources.md
new file mode 100644
index 0000000..1d8a50a
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-install/references/sources.md
@@ -0,0 +1,9 @@
+# Sources
+
+## context7-microsoft-apm
+
+- **URL:** context7:/microsoft/apm
+- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Contributing files:** SKILL.md
+- **Status:** `extracted`
-- 
2.43.0


From fc69553ba78483cb8f2c3156f54455f0293a3312 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 17:46:03 +0000
Subject: [PATCH 04/11] feat(kyberforge): add apm-workflow skill

Human-facing dispatch over apm's configure/marketplace/compile/audit
lifecycle, one reference file per concern, gitea-issues-style
dispatch table. apm-install handles the one-time binary/runtime
bootstrap that precedes this loop.
---
 .../kyberforge/skills/apm-workflow/README.md  |  31 +++++
 .../kyberforge/skills/apm-workflow/SKILL.md   |  43 ++++++
 .../skills/apm-workflow/references/audit.md   |  49 +++++++
 .../skills/apm-workflow/references/compile.md |  42 ++++++
 .../apm-workflow/references/configure.md      | 127 ++++++++++++++++++
 .../apm-workflow/references/marketplace.md    |  61 +++++++++
 .../skills/apm-workflow/references/sources.md |   9 ++
 7 files changed, 362 insertions(+)
 create mode 100644 plugins/kyberforge/skills/apm-workflow/README.md
 create mode 100644 plugins/kyberforge/skills/apm-workflow/SKILL.md
 create mode 100644 plugins/kyberforge/skills/apm-workflow/references/audit.md
 create mode 100644 plugins/kyberforge/skills/apm-workflow/references/compile.md
 create mode 100644 plugins/kyberforge/skills/apm-workflow/references/configure.md
 create mode 100644 plugins/kyberforge/skills/apm-workflow/references/marketplace.md
 create mode 100644 plugins/kyberforge/skills/apm-workflow/references/sources.md

diff --git a/plugins/kyberforge/skills/apm-workflow/README.md b/plugins/kyberforge/skills/apm-workflow/README.md
new file mode 100644
index 0000000..b813436
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/README.md
@@ -0,0 +1,31 @@
+# apm-workflow
+
+Authors, scaffolds, compiles, and audits apm packages and marketplaces.
+
+## What it does
+
+Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches by requested action to one of four reference files, each self-contained for its concern.
+
+## Before you start
+
+Requires the `apm` binary and (for runtime-driven scripts) an agent runtime already installed — use `apm-install` first if either is missing.
+
+## Usage
+
+```
+/apm-workflow configure
+/apm-workflow marketplace
+/apm-workflow compile
+/apm-workflow audit
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Dispatch table and cross-cutting gotchas |
+| `references/configure.md` | apm.yml schema, apm plugin init, dependency forms, MCP secrets, registries |
+| `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/sources.md` | Provenance chain — research sources that informed this skill |
diff --git a/plugins/kyberforge/skills/apm-workflow/SKILL.md b/plugins/kyberforge/skills/apm-workflow/SKILL.md
new file mode 100644
index 0000000..c2f1b2d
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: apm-workflow
+description: >
+  Use when the user wants to author or edit an apm.yml manifest
+  (dependencies, scripts, compilation, policy, registries), scaffold a new
+  apm package or marketplace (apm plugin init, apm marketplace init/package
+  add), register a marketplace as a consumer, compile/pack/publish an apm
+  package for distribution, or validate/audit apm.yml and installed content
+  (apm audit, apm marketplace check) — even if the user doesn't say "apm"
+  explicitly, e.g. "set up the package manifest", "scaffold this as an apm
+  package", "build the distributable", "check this passes CI". Do not use
+  for installing the apm binary itself or setting up an agent runtime — use
+  apm-install for those.
+metadata:
+  category: apm
+  source_keys:
+    - context7-microsoft-apm
+---
+
+## Gotchas
+
+- `apm.yml`'s `type:` field (`instructions`, `skill`, `hybrid`, `prompts`) constrains what `.apm/` may contain — set it before scaffolding content, not after. Changing it later doesn't retroactively validate what's already on disk.
+- `includes: auto` publishes the authoritative local layout as-is. Anything narrower needs an explicit repo-path list — don't assume `auto` means "scoped down to what's relevant."
+- `apm marketplace add` (registering a marketplace as a *consumer*, pointing at someone else's catalog) and `apm marketplace package add` (registering a local package *into* a marketplace you're building) are opposite directions of the same command family — don't conflate them.
+- `apm pack` is the same command that both bundles a distributable artifact *and* emits `.claude-plugin/marketplace.json` as one of its compile targets — regenerating the Claude Code-native manifest isn't a separate step from packing.
+- MCP server secrets (headers, env vars) inside `apm.yml` must use `${VAR}` indirection, never literal values, so they're resolved at install/runtime and never committed to the manifest.
+- `apm experimental enable registries` must run before any `registry.*` config takes effect. Declaring a `registries:` block or running `apm config set registry.*` without it silently does nothing — no error, no warning.
+- Plain `apm audit` and `apm audit --ci` check different things: plain `apm audit` scans deployed files for hidden Unicode only; `--ci` additionally runs lockfile-consistency checks, install-replay drift detection, and org policy checks. A clean plain `apm audit` is not a CI-equivalent pass.
+
+## Step 1 — Dispatch
+
+| Invocation | Action | Reference |
+|---|---|---|
+| `/apm-workflow configure` | Author/edit `apm.yml`; scaffold a new package (`apm plugin init`) | `references/configure.md` |
+| `/apm-workflow marketplace` | Build a marketplace, register packages into it, or register a marketplace as a consumer (`apm marketplace init/check/package add/add`) | `references/marketplace.md` |
+| `/apm-workflow compile` | Generate per-target output, bundle, or publish (`apm compile`, `apm pack`, `apm publish`) | `references/compile.md` |
+| `/apm-workflow audit` | Validate integrity/policy, wire a CI gate, or check marketplace refs resolve (`apm audit`, `apm audit --ci`, `apm marketplace check`) | `references/audit.md` |
+
+Read only the reference file matching the requested action — each is self-contained for its concern.
+
+## Step 2 — Execute
+
+Follow the matched reference file's instructions. Report back which `apm` command(s) were run (or drafted, if the user asked for a plan rather than execution) and their outcome.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/audit.md b/plugins/kyberforge/skills/apm-workflow/references/audit.md
new file mode 100644
index 0000000..a286e97
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/references/audit.md
@@ -0,0 +1,49 @@
+---
+topic: audit
+source_keys:
+  - context7-microsoft-apm
+---
+
+## `apm audit`
+
+```bash
+apm audit                  # local: scan deployed files for hidden Unicode
+apm audit --ci              # CI gate: lockfile consistency + drift replay + policy
+apm audit --file <path>     # standalone: scan an arbitrary file
+```
+
+`apm audit --ci` runs baseline lockfile checks, install-replay drift detection (does a clean `apm install` reproduce what's on disk), and org policy checks. Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. It covers AI agent configuration integrity, hidden-content scanning, lockfile verification, and policy enforcement — it does not replace general lint/test/security-scan CI steps, it sits alongside them.
+
+## Policy checks
+
+`apm audit --ci` auto-discovers an org policy from the git remote if `--policy`/`--policy-source` isn't given explicitly; `--no-policy` skips policy discovery for a single invocation.
+
+## Marketplace ref validation
+
+Separate from `apm audit`: `apm marketplace check` validates that every package reference declared in a marketplace's `apm.yml` actually resolves (correct path/ref, manifest present) — run before `apm pack`/publish, to catch a typo'd local path or stale pinned tag before it ships.
+
+## CI integration example (GitHub Actions)
+
+```yaml
+jobs:
+  apm-audit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install apm-cli==X.Y.Z  # pin to the version standardized on
+      - run: apm install
+      - run: apm audit --ci -f sarif --output apm-audit.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: apm-audit.sarif }
+```
+
+`-f sarif --output <file>` emits SARIF for GitHub Code Scanning's inline PR annotations.
+
+## 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.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/compile.md b/plugins/kyberforge/skills/apm-workflow/references/compile.md
new file mode 100644
index 0000000..84e3708
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/references/compile.md
@@ -0,0 +1,42 @@
+---
+topic: compile
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Compile
+
+```bash
+apm compile
+```
+
+Generates per-target output (Claude, Copilot, etc.) from the vendor-neutral `.apm/` primitive source tree, per the `compilation:` block in `apm.yml`. Run this after any change to `.apm/` content or to `compilation:`/`targets:` in `apm.yml`.
+
+## Pack
+
+```bash
+apm pack --dry-run              # resolve and print; do not write
+apm pack --offline              # cached refs only
+apm pack --include-prerelease   # allow pre-release tags
+apm pack -v                     # per-entry resolution detail
+apm pack --marketplace=claude --json   # JSON output for CI pipelines
+```
+
+Bundles a producer package into a distributable artifact. Default to `--dry-run -v` first when packing something for the first time or after a dependency change — resolution errors surface before anything is written.
+
+## Publish
+
+```bash
+apm publish --package acme/my-skill --dry-run -v
+apm publish --package acme/my-skill
+```
+
+Publishes a producer package (root containing `apm.yml`, `.apm/`, and optionally a `registries:` block) to a registry. Always dry-run with `-v` first — publishing is not trivially reversible once a version tag is claimed on a registry.
+
+## Run
+
+```bash
+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.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/configure.md b/plugins/kyberforge/skills/apm-workflow/references/configure.md
new file mode 100644
index 0000000..ae6d304
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/references/configure.md
@@ -0,0 +1,127 @@
+---
+topic: configure
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Scaffolding a new package
+
+```bash
+apm plugin init <name> --yes
+```
+
+Scaffolds `apm.yml` + a `.apm/` skeleton in the current directory. Run this once per package (e.g. once per `plugins/<name>/` directory in a monorepo-hybrid layout), not once for the whole repo.
+
+## `apm.yml` — required fields
+
+Only `name` and `version` (SemVer) are required:
+
+```yaml
+name: my-pkg
+version: 1.0.0
+```
+
+## `apm.yml` — full schema
+
+```yaml
+name: my-pkg
+version: 1.0.0
+description: Code review skills for Python services
+author: Jane Doe            # plain string, or {name, email?, url?} object
+license: MIT
+homepage: https://example.com/my-pkg
+repository: https://github.com/org/my-pkg
+keywords: [ai, review, python]
+
+type: skill                 # instructions | skill | hybrid | prompts — constrains .apm/ contents
+
+targets:                    # which harnesses this package compiles to; prefer plural list form
+  - copilot
+  - claude
+
+includes: auto               # "auto" = publish the authoritative local layout; or list explicit repo paths
+
+dependencies:
+  apm:
+    - microsoft/apm-sample-package#v1.0.0        # pinned to a tag
+    - github/awesome-copilot/skills/review-and-refactor  # single primitive
+  mcp:
+    - microsoft/azure-devops-mcp                 # MCP server dependency
+  lsp:
+    - name: pyright
+      command: pyright-langserver
+      args: ["--stdio"]
+      extensionToLanguage:
+        ".py": python
+
+devDependencies:             # same shape as dependencies, excluded from the shipped artifact
+  apm:
+    - my-org/internal-test-skills
+
+scripts:                     # named commands runnable via `apm run <name>`
+  start: "copilot -p 'README.prompt.md'"
+  review: "copilot -p 'code-review.prompt.md'"
+
+compilation:
+  target: all
+  strategy: distributed
+  exclude:
+    - "apm_modules/**"
+  placement:
+    min_instructions_per_file: 1
+
+policy:
+  fetch_failure_default: warn
+
+registries:
+  public-apm:
+    url: https://registry.example.com/api/public-apm
+  default: public-apm
+
+marketplace:                 # see references/marketplace.md for the full marketplace workflow
+  owner:
+    name: contoso
+    url: https://github.com/contoso
+  packages:
+    - name: code-review
+      source: contoso/code-review
+      version: "^1.0.0"
+      tags: [review, quality]
+```
+
+## Dependency reference forms
+
+`dependencies.apm` entries accept: a pinned tag (`owner/repo#tag`), a plain repo (uses default branch), a single primitive path within a repo, a raw git URL, a `git:`/`path:`/`ref:` object for finer control, or a local relative path (`./packages/my-shared-skills`).
+
+## MCP server secrets
+
+Use `${VAR}` indirection for headers/env vars — never a literal secret value in `apm.yml`:
+
+```yaml
+mcp:
+  - name: linear
+    registry: false
+    transport: http
+    url: https://mcp.linear.app/sse
+    headers:
+      Authorization: "Bearer ${LINEAR_TOKEN}"
+  - name: my-internal
+    registry: false
+    transport: stdio
+    command: my-server
+    env:
+      API_TOKEN: "${MY_API_TOKEN}"
+```
+
+## Registries (config-level, not `apm.yml`)
+
+Any git repo is a valid package source by default — no registry required. To declare named registries for shorthand dependency resolution:
+
+```bash
+apm experimental enable registries   # required first — see SKILL.md Gotchas
+apm config set registry.corp-main.url https://artifactory.corp.example.com/apm
+apm config set registry.corp-main.token eyJ...
+apm config set registry.corp-main.default true
+```
+
+`apm config get`/`apm config unset` manage individual keys the same way.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
new file mode 100644
index 0000000..55311ea
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
@@ -0,0 +1,61 @@
+---
+topic: marketplace
+source_keys:
+  - context7-microsoft-apm
+---
+
+## Building a marketplace from a producer repo
+
+```bash
+apm marketplace init                          # 1. add the marketplace: block to apm.yml
+$EDITOR apm.yml                               # 2. describe each package
+apm marketplace check                         # 3. validate refs resolve
+apm pack                                      # 4. build marketplace artifacts
+git add apm.yml .claude-plugin/marketplace.json
+git commit -m "Release v1.0.0" && git tag v1.0.0 && git push --tags
+```
+
+`apm pack` emits `.claude-plugin/marketplace.json` as one of its compile targets — an APM-based marketplace stays consumable by Claude Code's existing marketplace mechanism without a separately hand-maintained file.
+
+## Registering a package into a marketplace you're building
+
+```bash
+apm marketplace package add ./packages/plugin-a --name plugin-a
+```
+
+Registers an already-existing local package path into the root marketplace listing without re-scaffolding it — this is the monorepo-hybrid command: point it at each existing `plugins/<name>/` directory once that directory has its own `apm.yml`.
+
+## Registering a marketplace as a consumer
+
+`apm marketplace add` accepts many source shapes:
+
+```bash
+apm marketplace add my-org/awesome-agents                              # GitHub shorthand
+apm marketplace add gitlab.com/my-org/awesome-agents --host gitlab.com # GitLab
+apm marketplace add https://gitea.example.com/org/repo.git#v1.0.0 --name custom  # self-hosted git, pinned
+apm marketplace add https://catalog.example.com/marketplace.json --name catalog  # hosted marketplace.json
+apm marketplace add git@gitea.example.com:org/repo.git --name custom   # SSH
+apm marketplace add /srv/marketplaces/agent-forge.git --name agent-forge         # local bare repo/working dir
+apm marketplace add ./vendor/marketplace.json --name vendor            # local marketplace.json file
+apm marketplace add file:///srv/marketplaces/agent-forge.git --name agent-forge  # file:// form
+```
+
+The local-filesystem and `file://` forms need no hosted registry or network access — the fit for an internal/homelab setup.
+
+## Per-package versioning
+
+```yaml
+marketplace:
+  versioning: { strategy: per_package }
+  packages:
+    - { name: plugin-a, source: ./packages/plugin-a, version: 2.0.0 }
+    - { name: plugin-b, source: ./packages/plugin-b, version: 0.1.0 }
+```
+
+Without this block, the default versioning strategy ties every listed package to the marketplace/root version.
+
+## Which mechanism to use
+
+- **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.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/sources.md b/plugins/kyberforge/skills/apm-workflow/references/sources.md
new file mode 100644
index 0000000..ab4a6c5
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/references/sources.md
@@ -0,0 +1,9 @@
+# Sources
+
+## context7-microsoft-apm
+
+- **URL:** context7:/microsoft/apm
+- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Contributing files:** SKILL.md, references/configure.md, references/marketplace.md, references/compile.md, references/audit.md
+- **Status:** `extracted`
-- 
2.43.0


From 0aa66fe65d364e9877fa31dca075f14f1fc3b1dc Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 17:49:12 +0000
Subject: [PATCH 05/11] feat(kyberforge): add apm-orchestrate agent

Deterministic counterpart to apm-workflow for subagent dispatch,
mirroring git-orchestrate/gitea-orchestrate. Scoped to
configure/marketplace/compile/audit, with fan-out across multiple
packages for the future multi-plugin conversion; apm-install has no
orchestrator counterpart since it's a one-time machine bootstrap.

Bumps kyberforge 1.2.8 -> 1.3.0 (new agent, first in the plugin).
---
 plugins/kyberforge/.claude-plugin/plugin.json |  2 +-
 .../agents/apm-orchestrate.agent.md           | 63 +++++++++++++++
 plugins/kyberforge/agents/apm-orchestrate.md  | 78 +++++++++++++++++++
 plugins/kyberforge/plugin.json                |  2 +-
 plugins/kyberforge/sources.md                 |  9 +++
 5 files changed, 152 insertions(+), 2 deletions(-)
 create mode 100644 plugins/kyberforge/agents/apm-orchestrate.agent.md
 create mode 100644 plugins/kyberforge/agents/apm-orchestrate.md
 create mode 100644 plugins/kyberforge/sources.md

diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 98049c5..53c4ce3 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.8"
+  "version": "1.3.0"
 }
diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md
new file mode 100644
index 0000000..75148cf
--- /dev/null
+++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md
@@ -0,0 +1,63 @@
+---
+name: apm-orchestrate
+
+description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo.
+
+tools: ["execute", "read"]
+
+source_keys:
+  - context7-microsoft-apm
+
+---
+
+You are the orchestrator for apm package/marketplace operations — a composable workflow dispatcher designed for other agents to invoke multi-step `apm` operations reliably, especially the same operation repeated across several packages in a monorepo-hybrid layout. Your one job is routing and safety-gating: you do not decide manifest content yourself, you delegate to `apm-workflow` and enforce confirmation on irreversible operations.
+
+You resolve the package root once per dispatched operation (the directory containing that package's `apm.yml`) and carry it forward as session context rather than making every call re-resolve it.
+
+**Scope:** this orchestrator routes `apm-workflow`'s four concerns only — configure/scaffold, marketplace, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
+
+## Hard rules
+
+These are non-negotiable regardless of `confirm` or any skill-local override:
+- `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
+- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value.
+- `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
+- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
+- A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
+- `apm experimental enable registries` must have already run before any `registry.*` config takes effect — check this precondition before dispatching an operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does.
+
+When invoked, you:
+1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
+2. Check safety gates: if the operation is `publish` and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"
+3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `compile`, `audit`)
+4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
+5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
+6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
+7. Aggregate results and return structured JSON output suitable for agent chaining
+
+## Inputs
+
+- **operation:** string, one of:
+  - configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`)
+  - marketplace: init-marketplace, check-marketplace, add-package, add-marketplace
+  - compile: compile, pack, publish, run-script
+  - audit: audit, audit-ci
+- **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
+- **parameters:** object, operation-specific arguments (package name for `add-package`, script name for `run-script`, registry name, etc.)
+- **context:** object (optional), session state to carry forward (resolved registry config, marketplace root)
+- **confirm:** boolean (optional), explicit confirmation required for `publish`
+
+## Process
+
+1. Validate the request structure and check if `operation` is known
+2. Check the request against the Hard rules above (publish confirmation, secret indirection, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
+3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
+4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
+5. Invoke `apm-workflow` with the resolved action, `package_root`, and parameters
+6. If fanning across multiple packages, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
+7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics
+8. Aggregate all outputs and return as structured JSON
+
+## Output
+
+Returns structured JSON with operation status, result (output — or a list of per-package results when fanned out — plus resolved package-root/registry context), and optional error details with recovery suggestions.
diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md
new file mode 100644
index 0000000..4253c8a
--- /dev/null
+++ b/plugins/kyberforge/agents/apm-orchestrate.md
@@ -0,0 +1,78 @@
+---
+name: apm-orchestrate
+
+description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo.
+
+tools: Bash, Read
+
+source_keys:
+  - context7-microsoft-apm
+
+---
+
+You are the orchestrator for apm package/marketplace operations — a composable workflow dispatcher designed for other agents to invoke multi-step `apm` operations reliably, especially the same operation repeated across several packages in a monorepo-hybrid layout. Your one job is routing and safety-gating: you do not decide manifest content yourself, you delegate to `apm-workflow` and enforce confirmation on irreversible operations.
+
+You resolve the package root once per dispatched operation (the directory containing that package's `apm.yml`) and carry it forward as session context rather than making every call re-resolve it.
+
+**Scope:** this orchestrator routes `apm-workflow`'s four concerns only — configure/scaffold, marketplace, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
+
+## Hard rules
+
+These are non-negotiable regardless of `confirm` or any skill-local override:
+- `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
+- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value.
+- `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
+- `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
+- A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
+- `apm experimental enable registries` must have already run before any `registry.*` config takes effect — check this precondition before dispatching an operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does.
+
+When invoked, you:
+1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
+2. Check safety gates: if the operation is `publish` and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"
+3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `compile`, `audit`)
+4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
+5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
+6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
+7. Aggregate results and return structured JSON output suitable for agent chaining
+
+## Inputs
+
+- **operation:** string, one of:
+  - configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`)
+  - marketplace: init-marketplace, check-marketplace, add-package, add-marketplace
+  - compile: compile, pack, publish, run-script
+  - audit: audit, audit-ci
+- **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
+- **parameters:** object, operation-specific arguments (package name for `add-package`, script name for `run-script`, registry name, etc.)
+- **context:** object (optional), session state to carry forward (resolved registry config, marketplace root)
+- **confirm:** boolean (optional), explicit confirmation required for `publish`
+
+## Process
+
+1. Validate the request structure and check if `operation` is known
+2. Check the request against the Hard rules above (publish confirmation, secret indirection, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
+3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
+4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
+5. Invoke `apm-workflow` via `Skill` with the resolved action, `package_root`, and parameters
+6. If fanning across multiple packages, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
+7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics
+8. Aggregate all outputs and return as structured JSON
+
+## Output
+
+```json
+{
+  "status": "success" | "error" | "partial",
+  "operation": "<operation_name>",
+  "result": {
+    "output": "<apm-workflow output or result, or a list of per-package results when fanned out>",
+    "context": { "package_root": "...", "resolved_registry": "..." }
+  },
+  "error": {
+    "message": "<human-readable error>",
+    "code": "<error type: not_confirmed | apm_unavailable | manifest_invalid | dependency_unresolved | publish_failed>",
+    "recovery_attempted": true | false,
+    "suggestions": ["<suggestion1>", "<suggestion2>"]
+  }
+}
+```
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index 1554ed0..a8e907f 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.8"
+  "version": "1.3.0"
 }
diff --git a/plugins/kyberforge/sources.md b/plugins/kyberforge/sources.md
new file mode 100644
index 0000000..a369fdc
--- /dev/null
+++ b/plugins/kyberforge/sources.md
@@ -0,0 +1,9 @@
+# Sources
+
+## context7-microsoft-apm
+
+- **URL:** context7:/microsoft/apm
+- **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
+- **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
+- **Contributing files:** agents/apm-orchestrate.md, agents/apm-orchestrate.agent.md
+- **Status:** `extracted`
-- 
2.43.0


From 2305f1c3158446251f0ca41fe8ce32528001830a Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 19:27:34 +0000
Subject: [PATCH 06/11] chore(config): enable lint plugin in settings

Adds lint@holocron to enabledPlugins so Vale-based prose linting
skills are available in this repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
---
 .claude/settings.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.claude/settings.json b/.claude/settings.json
index 8136bbd..9b97c07 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -4,7 +4,8 @@
     "core@holocron": true,
     "git@holocron": true,
     "gitea@holocron": true,
-    "kyberforge@holocron": true
+    "kyberforge@holocron": true,
+    "lint@holocron": true
   },
   "hooks": {
     "PreToolUse": []
-- 
2.43.0


From e16c3dc95f2e41affcf99bcdc7923791985e8a99 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Mon, 10 Aug 2026 21:23:07 +0000
Subject: [PATCH 07/11] docs(kyberforge): fix PR #91 review findings in
 ADR-0015 and apm docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 CONTEXT.md                                    |  4 +--
 ...m-replaces-plugin-marketplace-authoring.md | 26 ++++++++++++-------
 .../agents/apm-orchestrate.agent.md           |  5 ++--
 plugins/kyberforge/agents/apm-orchestrate.md  |  5 ++--
 .../skills/apm-workflow/references/compile.md |  2 ++
 .../apm-workflow/references/marketplace.md    |  5 ++--
 6 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index b77c576..eb05cdb 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -27,10 +27,10 @@ A separate product (separate repo) for browsing, editing, and configuring AI dev
 Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Deployed via plugin — `plugins/<plugin-name>/skills/<skill-name>/SKILL.md`, available after the plugin is installed (`claude plugin install <name>@<marketplace>`). Skills are self-contained — they cannot reference files outside the plugin directory after install-time caching.
 
 ### Plugin
-The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. Each plugin has two manifests: `.claude-plugin/plugin.json` (Claude Code) and `plugin.json` at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under `plugins/<name>/`. Install a plugin with `claude plugin install <name>@<marketplace>`.
+The deployable unit in the plugin marketplace. A plugin bundles one or more skills, agents, hooks, prompts, MCP servers, and optionally a `bin/` directory into a single installable directory. Each plugin has two manifests: `.claude-plugin/plugin.json` (Claude Code) and `plugin.json` at the plugin root (Copilot CLI). Plugins are copied to a cache on install — they cannot reference files outside their own directory. In this repo, plugins live under `plugins/<name>/`. Install a plugin with `claude plugin install <name>@<marketplace>`. These manifests are hand-authored today but are slated to become APM-compiled output per ADR-0015, pending issue #90 (not yet changed).
 
 ### Plugin marketplace
-A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest lives at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) and is mirrored to `.github/plugin/marketplace.json`.
+A Git repository with a `marketplace.json` manifest listing installable plugins. No backend, registry, or SaaS required — the Git repo is the marketplace. This repo is the `holocron` marketplace. The manifest lives at `.claude-plugin/marketplace.json` (read by both Claude Code and Copilot CLI) and is mirrored to `.github/plugin/marketplace.json`. This manifest is hand-authored today but is slated to become APM-compiled output per ADR-0015, pending issue #90 (not yet changed).
 
 ### HITL (human-in-the-loop)
 Agent pauses before a consequential action; human approves before execution. Required for irreversible or high-stakes actions (architecture changes, production deployments, security configuration). The agent drafts the change plan and waits — it does not proceed autonomously. Contrast with HOTL.
diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
index 446c3bf..012858e 100644
--- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
+++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
@@ -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.
diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md
index 75148cf..5ea8be9 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.agent.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md
@@ -20,7 +20,6 @@ You resolve the package root once per dispatched operation (the directory contai
 
 These are non-negotiable regardless of `confirm` or any skill-local override:
 - `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
-- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value.
 - `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
 - `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
 - A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
@@ -38,8 +37,8 @@ When invoked, you:
 ## Inputs
 
 - **operation:** string, one of:
-  - configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`)
-  - marketplace: init-marketplace, check-marketplace, add-package, add-marketplace
+  - configure: init-package
+  - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer)
   - compile: compile, pack, publish, run-script
   - audit: audit, audit-ci
 - **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md
index 4253c8a..56dd67e 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.md
@@ -20,7 +20,6 @@ You resolve the package root once per dispatched operation (the directory contai
 
 These are non-negotiable regardless of `confirm` or any skill-local override:
 - `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
-- MCP server secrets in any `apm.yml` content this orchestrator writes or edits must use `${VAR}` indirection — never a literal value.
 - `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
 - `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
 - A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
@@ -38,8 +37,8 @@ When invoked, you:
 ## Inputs
 
 - **operation:** string, one of:
-  - configure: init-package, compile-manifest-check (does `apm.yml` parse and match `type:`)
-  - marketplace: init-marketplace, check-marketplace, add-package, add-marketplace
+  - configure: init-package
+  - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer)
   - compile: compile, pack, publish, run-script
   - audit: audit, audit-ci
 - **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
diff --git a/plugins/kyberforge/skills/apm-workflow/references/compile.md b/plugins/kyberforge/skills/apm-workflow/references/compile.md
index 84e3708..6ea2972 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/compile.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/compile.md
@@ -24,6 +24,8 @@ apm pack --marketplace=claude --json   # JSON output for CI pipelines
 
 Bundles a producer package into a distributable artifact. Default to `--dry-run -v` first when packing something for the first time or after a dependency change — resolution errors surface before anything is written.
 
+Run `apm audit` after compile/pack, not before — audit scans deployed/compiled output, not the source `apm.yml` manifest; see `references/audit.md`.
+
 ## Publish
 
 ```bash
diff --git a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
index 55311ea..239d1d7 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
@@ -11,10 +11,11 @@ apm marketplace init                          # 1. add the marketplace: block to
 $EDITOR apm.yml                               # 2. describe each package
 apm marketplace check                         # 3. validate refs resolve
 apm pack                                      # 4. build marketplace artifacts
-git add apm.yml .claude-plugin/marketplace.json
-git commit -m "Release v1.0.0" && git tag v1.0.0 && git push --tags
 ```
 
+5. Commit and release — via the `git-commits` skill (commit message + tag) and `git-remotes` skill
+   (push), not raw `git` commands; see this repo's AGENTS.md "Prefer plugin skills over raw shell".
+
 `apm pack` emits `.claude-plugin/marketplace.json` as one of its compile targets — an APM-based marketplace stays consumable by Claude Code's existing marketplace mechanism without a separately hand-maintained file.
 
 ## Registering a package into a marketplace you're building
-- 
2.43.0


From 394052ff66a7783c117d7160ab4d25994c0cd758 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Tue, 11 Aug 2026 11:09:43 +0000
Subject: [PATCH 08/11] docs(kyberforge): fix remaining PR #91 review findings,
 add apm install routing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Re-review (comment 24) of fix commit e16c3dc found six new issues, mostly
introduced by that fix commit itself: a dangling reference to a Hard Rule
bullet the same commit deleted (apm-orchestrate.md/.agent.md Process step
2 still named "secret indirection"), and an ADR-0015 Decision bullet that
claimed "this ADR does not update CONTEXT.md" while the same commit had
just added a forward-pointer sentence to CONTEXT.md's Plugin/Plugin
marketplace entries. Both reworded to match what actually happened.

apm-install's APM_INSTALL_DIR escape-hatch example dropped the curl pipe
entirely (`APM_INSTALL_DIR=... sh` with nothing piped into it) — fixed in
both apm-install/SKILL.md and the installation.md research doc, verified
against the upstream Microsoft APM docs via Context7.

Neither apm-workflow nor apm-orchestrate routed to plain `apm install
[PACKAGE_REF]`, the CLI command that actually resolves/fetches
dependencies declared in apm.yml — apm-install only bootstraps the apm
binary/runtime, not per-package deps. Added a 5th "install" dispatch
action to apm-workflow (new references/install.md, SKILL.md table row,
README usage/files sync, sources.md provenance entry) and a matching
"install" operation group on apm-orchestrate so it can route there.

configure.md's apm.yml schema block was also missing the "legacy singular
`target:` CSV form is still accepted" caveat its sibling research doc
documents for the same field — added for consistency.

The sixth finding (paired .md/.agent.md Output-contract disagreement) was
checked against git-orchestrate and gitea-orchestrate's existing pairs and
found to match established repo convention (JSON schema in .md, prose
summary without the enum in .agent.md) — left unchanged as a false
positive rather than "fixed."

kyberforge bumped 1.3.0 -> 1.3.1 via agent-author's normal improve flow.

Refs: #91

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
---
 ...m-replaces-plugin-marketplace-authoring.md |  5 +++--
 plugins/kyberforge/.claude-plugin/plugin.json |  2 +-
 .../agents/apm-orchestrate.agent.md           |  7 ++++---
 plugins/kyberforge/agents/apm-orchestrate.md  |  7 ++++---
 .../docs/microsoft-apm/installation.md        |  2 +-
 plugins/kyberforge/plugin.json                |  2 +-
 .../kyberforge/skills/apm-install/SKILL.md    |  2 +-
 .../kyberforge/skills/apm-workflow/README.md  |  4 +++-
 .../kyberforge/skills/apm-workflow/SKILL.md   |  1 +
 .../apm-workflow/references/configure.md      |  2 +-
 .../skills/apm-workflow/references/install.md | 20 +++++++++++++++++++
 .../skills/apm-workflow/references/sources.md |  2 +-
 12 files changed, 41 insertions(+), 15 deletions(-)
 create mode 100644 plugins/kyberforge/skills/apm-workflow/references/install.md

diff --git a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
index 012858e..a2c9901 100644
--- a/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
+++ b/docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md
@@ -44,8 +44,9 @@ new hand-maintained manifest format.
 - 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.
+- `CONTEXT.md`'s "Plugin"/"Plugin marketplace" glossary entries get a forward-pointer to this
+  ADR so a session-start read surfaces the pending change; their substantive definitions remain
+  accurate until issue #90's conversion actually executes — this ADR does not rewrite them.
 
 ## Considered options
 
diff --git a/plugins/kyberforge/.claude-plugin/plugin.json b/plugins/kyberforge/.claude-plugin/plugin.json
index 53c4ce3..38a4a31 100644
--- a/plugins/kyberforge/.claude-plugin/plugin.json
+++ b/plugins/kyberforge/.claude-plugin/plugin.json
@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.3.0"
+  "version": "1.3.1"
 }
diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md
index 5ea8be9..eacd220 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.agent.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md
@@ -14,7 +14,7 @@ You are the orchestrator for apm package/marketplace operations — a composable
 
 You resolve the package root once per dispatched operation (the directory containing that package's `apm.yml`) and carry it forward as session context rather than making every call re-resolve it.
 
-**Scope:** this orchestrator routes `apm-workflow`'s four concerns only — configure/scaffold, marketplace, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
+**Scope:** this orchestrator routes `apm-workflow`'s five concerns only — configure/scaffold, marketplace, install, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
 
 ## Hard rules
 
@@ -28,7 +28,7 @@ These are non-negotiable regardless of `confirm` or any skill-local override:
 When invoked, you:
 1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
 2. Check safety gates: if the operation is `publish` and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"
-3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `compile`, `audit`)
+3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `install`, `compile`, `audit`)
 4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
 5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
 6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
@@ -39,6 +39,7 @@ When invoked, you:
 - **operation:** string, one of:
   - configure: init-package
   - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer)
+  - install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything)
   - compile: compile, pack, publish, run-script
   - audit: audit, audit-ci
 - **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
@@ -49,7 +50,7 @@ When invoked, you:
 ## Process
 
 1. Validate the request structure and check if `operation` is known
-2. Check the request against the Hard rules above (publish confirmation, secret indirection, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
+2. Check the request against the Hard rules above (publish confirmation, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
 3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
 4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
 5. Invoke `apm-workflow` with the resolved action, `package_root`, and parameters
diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md
index 56dd67e..ca67dcf 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.md
@@ -14,7 +14,7 @@ You are the orchestrator for apm package/marketplace operations — a composable
 
 You resolve the package root once per dispatched operation (the directory containing that package's `apm.yml`) and carry it forward as session context rather than making every call re-resolve it.
 
-**Scope:** this orchestrator routes `apm-workflow`'s four concerns only — configure/scaffold, marketplace, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
+**Scope:** this orchestrator routes `apm-workflow`'s five concerns only — configure/scaffold, marketplace, install, compile/pack/publish, audit. It does not route `apm-install` (binary install, agent-runtime setup) — that's a one-time machine bootstrap, not a per-package, fan-out-able operation, and has no orchestrator counterpart. Confirm `apm --version` succeeds before dispatching any operation; if it fails, tell the caller to run `apm-install` first rather than attempting recovery here.
 
 ## Hard rules
 
@@ -28,7 +28,7 @@ These are non-negotiable regardless of `confirm` or any skill-local override:
 When invoked, you:
 1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
 2. Check safety gates: if the operation is `publish` and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"
-3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `compile`, `audit`)
+3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `install`, `compile`, `audit`)
 4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
 5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
 6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
@@ -39,6 +39,7 @@ When invoked, you:
 - **operation:** string, one of:
   - configure: init-package
   - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer)
+  - install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything)
   - compile: compile, pack, publish, run-script
   - audit: audit, audit-ci
 - **package_root:** string, path to the directory containing the target `apm.yml` (required for every operation except `init-marketplace` when scaffolding the repo root)
@@ -49,7 +50,7 @@ When invoked, you:
 ## Process
 
 1. Validate the request structure and check if `operation` is known
-2. Check the request against the Hard rules above (publish confirmation, secret indirection, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
+2. Check the request against the Hard rules above (publish confirmation, marketplace-add direction, `type:` ordering, audit-vs-audit-ci, registries precondition) — refuse outright on violation, independent of `confirm`
 3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
 4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
 5. Invoke `apm-workflow` via `Skill` with the resolved action, `package_root`, and parameters
diff --git a/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md b/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
index c617e2f..e254c66 100644
--- a/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
+++ b/plugins/kyberforge/docs/research/docs/microsoft-apm/installation.md
@@ -17,7 +17,7 @@ On Windows, the installer adds both the current directory and the bin directory
 ## Customizing the install
 
 - **Pin a specific version**: append `@vX.Y.Z` to the piped script arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
-- **Custom install directory**: set `APM_INSTALL_DIR` before running the script, e.g. `APM_INSTALL_DIR=$HOME/.local/bin sh`.
+- **Custom install directory**: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
 - **Air-gapped / GitHub Enterprise mirror**: set `GITHUB_URL` and `VERSION` env vars against a local `install.sh`, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
 
 ## Alternative install methods
diff --git a/plugins/kyberforge/plugin.json b/plugins/kyberforge/plugin.json
index a8e907f..4f7f8b0 100644
--- a/plugins/kyberforge/plugin.json
+++ b/plugins/kyberforge/plugin.json
@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.3.0"
+  "version": "1.3.1"
 }
diff --git a/plugins/kyberforge/skills/apm-install/SKILL.md b/plugins/kyberforge/skills/apm-install/SKILL.md
index 318f0b3..4c8f07f 100644
--- a/plugins/kyberforge/skills/apm-install/SKILL.md
+++ b/plugins/kyberforge/skills/apm-install/SKILL.md
@@ -31,7 +31,7 @@ curl -sSL https://aka.ms/apm-unix | sh
 
 Escape hatches — combine as needed:
 - Pin a version: append `@vX.Y.Z` to the piped script's arguments, e.g. `curl -sSL https://aka.ms/apm-unix | sh -s -- @v1.2.3`.
-- Custom install directory: set `APM_INSTALL_DIR` before running, e.g. `APM_INSTALL_DIR=$HOME/.local/bin sh`.
+- Custom install directory: set `APM_INSTALL_DIR` on the piped script's command, e.g. `curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh`.
 - Air-gapped / GitHub Enterprise mirror: download `install.sh` first, then run it with `GITHUB_URL` and `VERSION` set, e.g. `GITHUB_URL=https://github.corp.com VERSION=v1.2.3 sh install.sh`.
 - pip (Python 3.10+ environments): `pip install apm-cli`.
 - Manual: download the platform archive from the GitHub releases page, extract, place the binary on `PATH`.
diff --git a/plugins/kyberforge/skills/apm-workflow/README.md b/plugins/kyberforge/skills/apm-workflow/README.md
index b813436..9c88640 100644
--- a/plugins/kyberforge/skills/apm-workflow/README.md
+++ b/plugins/kyberforge/skills/apm-workflow/README.md
@@ -4,7 +4,7 @@ Authors, scaffolds, compiles, and audits apm packages and marketplaces.
 
 ## What it does
 
-Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches by requested action to one of four reference files, each self-contained for its concern.
+Covers the apm.yml lifecycle a session moves through repeatedly: configuring/scaffolding a package manifest, resolving/fetching its declared dependencies, building or registering a marketplace, compiling/packing/publishing a distributable, and validating integrity via apm audit. Dispatches by requested action to one of five reference files, each self-contained for its concern.
 
 ## Before you start
 
@@ -14,6 +14,7 @@ Requires the `apm` binary and (for runtime-driven scripts) an agent runtime alre
 
 ```
 /apm-workflow configure
+/apm-workflow install
 /apm-workflow marketplace
 /apm-workflow compile
 /apm-workflow audit
@@ -25,6 +26,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 |
diff --git a/plugins/kyberforge/skills/apm-workflow/SKILL.md b/plugins/kyberforge/skills/apm-workflow/SKILL.md
index c2f1b2d..01b5b62 100644
--- a/plugins/kyberforge/skills/apm-workflow/SKILL.md
+++ b/plugins/kyberforge/skills/apm-workflow/SKILL.md
@@ -32,6 +32,7 @@ metadata:
 | Invocation | Action | Reference |
 |---|---|---|
 | `/apm-workflow configure` | Author/edit `apm.yml`; scaffold a new package (`apm plugin init`) | `references/configure.md` |
+| `/apm-workflow install` | Resolve/fetch dependencies declared in `apm.yml` (`apm install`, `apm install [PACKAGE_REF]`) | `references/install.md` |
 | `/apm-workflow marketplace` | Build a marketplace, register packages into it, or register a marketplace as a consumer (`apm marketplace init/check/package add/add`) | `references/marketplace.md` |
 | `/apm-workflow compile` | Generate per-target output, bundle, or publish (`apm compile`, `apm pack`, `apm publish`) | `references/compile.md` |
 | `/apm-workflow audit` | Validate integrity/policy, wire a CI gate, or check marketplace refs resolve (`apm audit`, `apm audit --ci`, `apm marketplace check`) | `references/audit.md` |
diff --git a/plugins/kyberforge/skills/apm-workflow/references/configure.md b/plugins/kyberforge/skills/apm-workflow/references/configure.md
index ae6d304..7647909 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/configure.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/configure.md
@@ -35,7 +35,7 @@ keywords: [ai, review, python]
 
 type: skill                 # instructions | skill | hybrid | prompts — constrains .apm/ contents
 
-targets:                    # which harnesses this package compiles to; prefer plural list form
+targets:                    # which harnesses this package compiles to; prefer plural list form — legacy singular `target: copilot,claude` CSV form is still accepted
   - copilot
   - claude
 
diff --git a/plugins/kyberforge/skills/apm-workflow/references/install.md b/plugins/kyberforge/skills/apm-workflow/references/install.md
new file mode 100644
index 0000000..760c44e
--- /dev/null
+++ b/plugins/kyberforge/skills/apm-workflow/references/install.md
@@ -0,0 +1,20 @@
+---
+topic: install
+source_keys:
+  - context7-microsoft-apm
+---
+
+## `apm install`
+
+```bash
+apm install                            # resolve/install everything in apm.yml against apm.lock.yaml
+apm install acme/internal-tools#^1.0.0  # install and add this dependency
+apm install --update                    # re-resolve; accept new upstream content even if it doesn't match the lockfile hash
+apm install --target agent-skills       # emit a vendor-neutral output dir instead of a harness-specific one
+```
+
+With no arguments, resolves and installs everything declared under `dependencies:`/`devDependencies:` in `apm.yml` against `apm.lock.yaml`. One or more `PACKAGE_REF` arguments (any of the forms in `references/configure.md`'s "Dependency reference forms" — pinned tag, plain repo, single primitive, raw git URL, `git:`/`path:`/`ref:` object, or local relative path) install that dependency and add it to `apm.yml`.
+
+`--update` is the escape hatch for a lockfile hash mismatch against upstream — normal `apm install` treats that as drift and won't silently accept it; see `references/audit.md` for the CI-side check (`apm install --frozen`) that fails instead of re-resolving.
+
+`--target agent-skills` generates the vendor-neutral output directory instead of a Claude/Copilot-specific one — for IDE-agnostic tool support.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/sources.md b/plugins/kyberforge/skills/apm-workflow/references/sources.md
index ab4a6c5..3d257ea 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/sources.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/sources.md
@@ -5,5 +5,5 @@
 - **URL:** context7:/microsoft/apm
 - **Description:** Microsoft APM (Agent Package Manager) — open-source dependency manager for AI agent configuration (skills, prompts, instructions, agents, hooks, MCP/LSP deps), applying a declare/lock/install/audit workflow.
 - **Research doc:** plugins/kyberforge/docs/research/docs/microsoft-apm/sources.md
-- **Contributing files:** SKILL.md, references/configure.md, references/marketplace.md, references/compile.md, references/audit.md
+- **Contributing files:** SKILL.md, references/configure.md, references/install.md, references/marketplace.md, references/compile.md, references/audit.md
 - **Status:** `extracted`
-- 
2.43.0


From 92e7ff26aae59736083b8305137bd9c46ea90676 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Tue, 11 Aug 2026 12:09:43 +0000
Subject: [PATCH 09/11] 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/<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`).
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 <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.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
index 239d1d7..9bf8675 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
+++ b/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`.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/sources.md b/plugins/kyberforge/skills/apm-workflow/references/sources.md
index 3d257ea..9e1ddeb 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/sources.md
+++ b/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`
-- 
2.43.0


From d6fd9b677024a0ad474fd846bbeb6bdcab2af408 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Tue, 11 Aug 2026 14:22:31 +0000
Subject: [PATCH 10/11] fix(kyberforge): resolve PR #91 review findings in apm
 docs and orchestrators

Addresses 7 verified findings from the /code-review pass on PR #91's
APM-conversion changes:

- apm-workflow's description omitted install triggers, misrouting
  "install my apm dependencies" requests to apm-install instead
- `apm marketplace check` was listed under both the marketplace and
  audit dispatch rows, breaking the "one reference file per action"
  contract; kept under marketplace.md, its real usage-sequence home
- ADR-0015 claimed apm-workflow docs are generic/repo-agnostic while
  marketplace.md cited this repo's AGENTS.md and git-commits/
  git-remotes skills by name; stripped the holocron-specific
  citations (marketplace.md, compile.md) so the claim now holds
- plugin-author/marketplace-author are superseded per ADR-0015 with
  deletion deferred to #90; added deprecation notices pointing to
  the replacing apm-workflow dispatch actions
- apm-orchestrate/gitea-orchestrate/git-orchestrate all instruct
  dispatch "via Skill" without granting the Skill tool; added it to
  all three
- apm-orchestrate mandated strictly sequential fan-out across
  independent packages with no shared state; relaxed to permit
  parallel dispatch, matching this repo's own subagent-parallelization
  guidance

Refs: #91
---
 plugins/git/agents/git-orchestrate.md          |  2 +-
 plugins/gitea/agents/gitea-orchestrate.md      |  2 +-
 .../kyberforge/agents/apm-orchestrate.agent.md |  4 ++--
 plugins/kyberforge/agents/apm-orchestrate.md   |  6 +++---
 .../kyberforge/skills/apm-workflow/SKILL.md    | 18 ++++++++++--------
 .../skills/apm-workflow/references/compile.md  |  2 +-
 .../apm-workflow/references/marketplace.md     |  6 ++++--
 .../skills/marketplace-author/SKILL.md         |  2 ++
 .../kyberforge/skills/plugin-author/SKILL.md   |  2 ++
 9 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/plugins/git/agents/git-orchestrate.md b/plugins/git/agents/git-orchestrate.md
index 9539666..5a0c777 100644
--- a/plugins/git/agents/git-orchestrate.md
+++ b/plugins/git/agents/git-orchestrate.md
@@ -3,7 +3,7 @@ name: git-orchestrate
 
 description: Orchestrates git workflow operations for other agents. Invoke when a caller needs a multi-step or destructive git operation (rebase, force-push, branch deletion) coordinated across domain skills with safety gates, session context, and structured results.
 
-tools: Bash, Read, Edit
+tools: Bash, Read, Edit, Skill
 
 source_keys:
   - context7-git-htmldocs
diff --git a/plugins/gitea/agents/gitea-orchestrate.md b/plugins/gitea/agents/gitea-orchestrate.md
index bebf398..e2d26cd 100644
--- a/plugins/gitea/agents/gitea-orchestrate.md
+++ b/plugins/gitea/agents/gitea-orchestrate.md
@@ -3,7 +3,7 @@ name: gitea-orchestrate
 
 description: Orchestrates Gitea operations for other agents. Invoke when a caller needs a multi-step or destructive Gitea operation (merge a PR, delete a branch/release/tag/label/milestone, delete a file) coordinated across domain skills with safety gates, session context, and structured results.
 
-tools: Bash, Read
+tools: Bash, Read, Skill
 
 source_keys:
   - gitea-mcp-repo
diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md
index eacd220..e6a94f6 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.agent.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md
@@ -31,7 +31,7 @@ When invoked, you:
 3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `install`, `compile`, `audit`)
 4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
 5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
-6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
+6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch independent packages in parallel when no shared state or ordering dependency exists between them; keep dispatch strictly sequential only for packages with a real dependency on another package's completion (e.g. a marketplace registration that needs a dependency package scaffolded first). Either way, continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
 7. Aggregate results and return structured JSON output suitable for agent chaining
 
 ## Inputs
@@ -54,7 +54,7 @@ When invoked, you:
 3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
 4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
 5. Invoke `apm-workflow` with the resolved action, `package_root`, and parameters
-6. If fanning across multiple packages, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
+6. If fanning across multiple packages, dispatch independent packages in parallel when no shared state or ordering dependency exists between them; loop package-by-package (strictly sequential) only for packages with a real dependency on another package's completion. Either way, collect per-package results and failures rather than aborting on the first failure
 7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics
 8. Aggregate all outputs and return as structured JSON
 
diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md
index ca67dcf..f49e08f 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.md
@@ -3,7 +3,7 @@ name: apm-orchestrate
 
 description: Orchestrates apm package/marketplace operations for other agents. Invoke when a caller needs a multi-step apm operation (scaffold a package, register it into a marketplace, compile/pack/publish, audit) coordinated across the apm-workflow skill with safety gates, session context, and structured results — especially fanning the same operation out across multiple packages in a monorepo.
 
-tools: Bash, Read
+tools: Bash, Read, Skill
 
 source_keys:
   - context7-microsoft-apm
@@ -31,7 +31,7 @@ When invoked, you:
 3. Route to `apm-workflow` with the resolved action (`configure`, `marketplace`, `install`, `compile`, `audit`)
 4. Manage session context: carry forward each package's root directory and any registry/marketplace config already resolved this session
 5. Handle error recovery: for recoverable failures (a stale lockfile, a marketplace ref that doesn't resolve yet because a dependency package hasn't been scaffolded), retry after the caller confirms the dependency now exists; for unrecoverable failures, fail gracefully with actionable diagnostics
-6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch one package at a time and continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
+6. When fanning an operation across multiple packages (e.g. `init-package` for every `plugins/<name>/` directory in a monorepo-hybrid conversion), dispatch independent packages in parallel when no shared state or ordering dependency exists between them; keep dispatch strictly sequential only for packages with a real dependency on another package's completion (e.g. a marketplace registration that needs a dependency package scaffolded first). Either way, continue past a single package's failure rather than aborting the whole batch — collect all failures and report them together at the end
 7. Aggregate results and return structured JSON output suitable for agent chaining
 
 ## Inputs
@@ -54,7 +54,7 @@ When invoked, you:
 3. If `operation` is `publish`: require `confirm: true`, dispatch `--dry-run -v` first regardless, surface that output, else fail with structured "requires explicit confirmation" error
 4. Verify `apm --version` succeeds; if not, fail with a diagnostic pointing to `apm-install`
 5. Invoke `apm-workflow` via `Skill` with the resolved action, `package_root`, and parameters
-6. If fanning across multiple packages, loop package-by-package, collecting per-package results and failures rather than aborting on the first failure
+6. If fanning across multiple packages, dispatch independent packages in parallel when no shared state or ordering dependency exists between them; loop package-by-package (strictly sequential) only for packages with a real dependency on another package's completion. Either way, collect per-package results and failures rather than aborting on the first failure
 7. Catch and handle apm errors: retry once for a dependency-not-yet-scaffolded failure after the caller confirms the dependency exists; otherwise return error structure with diagnostics
 8. Aggregate all outputs and return as structured JSON
 
diff --git a/plugins/kyberforge/skills/apm-workflow/SKILL.md b/plugins/kyberforge/skills/apm-workflow/SKILL.md
index 01b5b62..e7e26f1 100644
--- a/plugins/kyberforge/skills/apm-workflow/SKILL.md
+++ b/plugins/kyberforge/skills/apm-workflow/SKILL.md
@@ -4,13 +4,15 @@ description: >
   Use when the user wants to author or edit an apm.yml manifest
   (dependencies, scripts, compilation, policy, registries), scaffold a new
   apm package or marketplace (apm plugin init, apm marketplace init/package
-  add), register a marketplace as a consumer, compile/pack/publish an apm
-  package for distribution, or validate/audit apm.yml and installed content
-  (apm audit, apm marketplace check) — even if the user doesn't say "apm"
-  explicitly, e.g. "set up the package manifest", "scaffold this as an apm
-  package", "build the distributable", "check this passes CI". Do not use
-  for installing the apm binary itself or setting up an agent runtime — use
-  apm-install for those.
+  add), install or resolve dependencies declared in apm.yml (apm install,
+  apm install [PACKAGE_REF]), register a marketplace as a consumer,
+  compile/pack/publish an apm package for distribution, or validate/audit
+  apm.yml and installed content (apm audit, apm marketplace check) — even if
+  the user doesn't say "apm" explicitly, e.g. "set up the package manifest",
+  "scaffold this as an apm package", "install my apm dependencies", "resolve
+  apm.yml deps", "build the distributable", "check this passes CI". Do not
+  use for installing the apm binary itself or setting up an agent runtime —
+  use apm-install for those.
 metadata:
   category: apm
   source_keys:
@@ -35,7 +37,7 @@ metadata:
 | `/apm-workflow install` | Resolve/fetch dependencies declared in `apm.yml` (`apm install`, `apm install [PACKAGE_REF]`) | `references/install.md` |
 | `/apm-workflow marketplace` | Build a marketplace, register packages into it, or register a marketplace as a consumer (`apm marketplace init/check/package add/add`) | `references/marketplace.md` |
 | `/apm-workflow compile` | Generate per-target output, bundle, or publish (`apm compile`, `apm pack`, `apm publish`) | `references/compile.md` |
-| `/apm-workflow audit` | Validate integrity/policy, wire a CI gate, or check marketplace refs resolve (`apm audit`, `apm audit --ci`, `apm marketplace check`) | `references/audit.md` |
+| `/apm-workflow audit` | Validate integrity/policy or wire a CI gate (`apm audit`, `apm audit --ci`) | `references/audit.md` |
 
 Read only the reference file matching the requested action — each is self-contained for its concern.
 
diff --git a/plugins/kyberforge/skills/apm-workflow/references/compile.md b/plugins/kyberforge/skills/apm-workflow/references/compile.md
index b85c550..33f53d7 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/compile.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/compile.md
@@ -45,4 +45,4 @@ Executes a named script defined under `scripts:` in `apm.yml`, with `--param` su
 
 ## 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.
+- `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 (an empirically observed Claude Code platform behavior, not an `apm` mechanic). 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.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
index 9bf8675..d86adfb 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
@@ -15,8 +15,10 @@ apm marketplace check                         # 3. validate refs resolve
 apm pack                                      # 4. build marketplace artifacts
 ```
 
-5. Commit and release — via the `git-commits` skill (commit message + tag) and `git-remotes` skill
-   (push), not raw `git` commands; see this repo's AGENTS.md "Prefer plugin skills over raw shell".
+5. Commit and release — commit the manifest changes, tag the release, and push, following your
+   project's established git tooling/conventions (a dedicated commit/release skill or workflow,
+   commitlint/Conventional Commits rules, required tags) rather than ad hoc raw `git` invocations,
+   if such tooling exists.
 
 `apm pack` emits `.claude-plugin/marketplace.json` as one of its compile targets — an APM-based marketplace stays consumable by Claude Code's existing marketplace mechanism without a separately hand-maintained file.
 
diff --git a/plugins/kyberforge/skills/marketplace-author/SKILL.md b/plugins/kyberforge/skills/marketplace-author/SKILL.md
index 6fae3d8..37a7040 100644
--- a/plugins/kyberforge/skills/marketplace-author/SKILL.md
+++ b/plugins/kyberforge/skills/marketplace-author/SKILL.md
@@ -22,6 +22,8 @@ metadata:
     - github-plugins-finding-installing
 ---
 
+> **Deprecated:** Superseded by `apm-workflow` per ADR-0015 — deletion pending issue #90 (not yet changed). Use `apm-workflow marketplace` (`apm marketplace init`/`package add`/`check`) for CREATE/ADD/REMOVE/UPDATE and `apm-workflow compile` (`apm pack` emits `.claude-plugin/marketplace.json`) instead.
+
 ## Gotchas
 
 - Both marketplace files must be identical after every operation — never update one without the other in the same edit pass.
diff --git a/plugins/kyberforge/skills/plugin-author/SKILL.md b/plugins/kyberforge/skills/plugin-author/SKILL.md
index 91fb0d8..7402e5f 100644
--- a/plugins/kyberforge/skills/plugin-author/SKILL.md
+++ b/plugins/kyberforge/skills/plugin-author/SKILL.md
@@ -22,6 +22,8 @@ metadata:
     - github-plugins-finding-installing
 ---
 
+> **Deprecated:** Superseded by `apm-workflow` per ADR-0015 — deletion pending issue #90 (not yet changed). Use `apm-workflow configure` (apm.yml authoring, `apm plugin init` scaffolding) for CREATE/UPDATE and `apm-workflow compile` (`apm compile`/`apm pack`/`apm publish`) for RELEASE instead.
+
 ## Gotchas
 
 - Both manifests must carry identical `version` values — version parity is a hard invariant (ADR-0016). Never update version in one manifest without updating the other in the same edit pass.
-- 
2.43.0


From 591b9cccb83f35f795fd15a748d7c99718bf9160 Mon Sep 17 00:00:00 2001
From: Defame1297 <gitea@rkdr.net>
Date: Tue, 11 Aug 2026 15:20:46 +0000
Subject: [PATCH 11/11] fix(kyberforge): resolve second round of PR #91 review
 findings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two review passes on PR #91 (correctness + simplification) found the
prior fixup commit (d6fd9b6) left the deprecation notice it added
half-applied, cited a nonexistent ADR, and introduced/compounded a
few duplicate restatements of the same facts across apm-workflow's
skill files and apm-orchestrate's Hard rules.

- plugin-author/SKILL.md cited ADR-0016 (doesn't exist) instead of
  ADR-0006 for the version-parity invariant.
- The deprecation banner on plugin-author/marketplace-author wasn't
  reflected in their routing `description:` frontmatter, forge's
  routing table, either kyberforge README skill table, or CONTEXT.md
  — now propagated consistently; routing behavior is unchanged since
  issue #90 (repo-wide apm conversion) hasn't landed yet.
- apm-orchestrate's `configure` operation only covered scaffolding a
  new package, not editing an existing apm.yml (e.g. removing a
  marketplace.packages[] entry, which has no dedicated `apm` CLI verb
  and is just a manifest edit). Added `edit-config`, intentionally
  ungated — a local file edit isn't the same class of irreversible
  action as `apm publish`, and normal review already gates the commit.
- Deduplicated facts restated 3-4x across SKILL.md/references/ADR
  boundaries (audit semantics, reserved name prefixes, marketplace-add
  direction, registries precondition), and trimmed configure.md's
  ~55-line apm.yml schema dump — copied near-verbatim from the
  research doc — down to a compact key list with a pointer, matching
  install.md's existing terse cross-referencing style.

Deliberately left as-is: apm-orchestrate's parallel/sequential
fan-out logic stays inline rather than extracted to a shared
reference, since neither git-orchestrate nor gitea-orchestrate need
it yet — premature extraction for a single caller.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0186ERbyACLRuRxPRnqwpa4m
---
 CONTEXT.md                                    |  2 +-
 plugins/kyberforge/README.md                  |  6 +-
 .../agents/apm-orchestrate.agent.md           |  6 +-
 plugins/kyberforge/agents/apm-orchestrate.md  |  6 +-
 plugins/kyberforge/skills/README.md           |  6 +-
 .../kyberforge/skills/apm-workflow/SKILL.md   |  1 -
 .../skills/apm-workflow/references/audit.md   |  2 +-
 .../apm-workflow/references/configure.md      | 96 +++----------------
 .../apm-workflow/references/marketplace.md    |  4 +-
 plugins/kyberforge/skills/forge/SKILL.md      |  4 +-
 .../skills/marketplace-author/SKILL.md        |  3 +-
 .../kyberforge/skills/plugin-author/SKILL.md  |  7 +-
 12 files changed, 41 insertions(+), 102 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index eb05cdb..ea48c76 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -49,7 +49,7 @@ The provider-agnostic always-on instruction entry point. Two files:
 Contains always-on rules in plain markdown with no provider-specific syntax (no `@import`). Provider-specific files (`CLAUDE.md`) are thin adapters that import the relevant `AGENTS.md` and add only Claude Code-specific syntax. This pattern means a single source of truth can serve multiple providers without duplication. See ADR-0003.
 
 ### Skill composition
-A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`.
+A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology; `forge` calls `grill-with-docs` to refine intent, classifies the target artifact type (skill / agent / plugin / marketplace entry), then routes to the matching `*-author` skill — which owns its own create/improve logic and, where applicable, its own inline audit closeout (`skill-author` runs `/skill-audit`, `agent-author` runs `kyberforge:agent-audit`, both in the same context as the authoring work). Reserve `forge` for genuinely undecided "which artifact type is this" questions — an already-fully-specified corrective edit (exact file, line, and fix already known) should call the target author skill directly instead (`skill-author`, `plugin-author`, `agentsmd-author`, etc.); routing a known fix through `forge`'s grill-and-classify layer adds unnecessary indirection and, in practice, has been observed to lose track of hard constraints handed down the chain (e.g. "don't commit yet," "edit in this worktree") because each hop re-derives instructions from a shorter brief. `forge` additionally runs its own independent recheck after a skill/agent route finishes: a clean-context subagent (not forked, no inherited context) re-runs the same audit skill against the finished artifact, as a distinct verification layer from the author skill's inline audit — the two can share blind spots since the inline audit runs in the same context as the work it checks. If the clean audit surfaces any unresolved finding, `forge` loops — re-invoke the author skill to resolve it, re-run the clean audit — until the clean audit comes back with nothing unresolved; only then is the route done. `plugin-author` and `marketplace-author` have no audit counterpart and get no recheck; their terminal check is `claude plugin validate`. Both are deprecated per ADR-0015, superseded by `apm-workflow`, pending issue #90 (not yet changed).
 
 ### Provider-agnostic issue tracker
 Skills and workflows reference "linked issue" generically rather than a specific provider. Gitea is the canonical issue tracker for this repo (see ADR-0017). "Issue" is the cross-provider term (GitHub, GitLab, Gitea all use it).
diff --git a/plugins/kyberforge/README.md b/plugins/kyberforge/README.md
index 3c21dc1..c4b7b3e 100644
--- a/plugins/kyberforge/README.md
+++ b/plugins/kyberforge/README.md
@@ -46,8 +46,10 @@ copilot plugin install ./plugins/kyberforge
 | `agent-author` | Author an agent definition file |
 | `pc-author` | Create, add, remove, and configure `.pre-commit-config.yaml` |
 | `pc-run` | Install, run, autoupdate, and maintain the pre-commit setup |
-| `plugin-author` | Create, update, and release plugin scaffolds for the holocron marketplace |
-| `marketplace-author` | Add, remove, and update plugin entries in the holocron marketplace manifest |
+| `plugin-author` | (Deprecated — see apm-workflow) Create, update, and release plugin scaffolds for the holocron marketplace |
+| `marketplace-author` | (Deprecated — see apm-workflow) Add, remove, and update plugin entries in the holocron marketplace manifest |
+| `apm-install` | Install or upgrade the apm CLI and set up the agent runtimes it drives (Copilot CLI, Codex, Gemini, generic llm) |
+| `apm-workflow` | Author apm.yml, scaffold an apm package/marketplace, install dependencies, and compile/pack/publish/audit apm content |
 
 ## Author
 
diff --git a/plugins/kyberforge/agents/apm-orchestrate.agent.md b/plugins/kyberforge/agents/apm-orchestrate.agent.md
index e6a94f6..f500183 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.agent.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.agent.md
@@ -20,10 +20,10 @@ You resolve the package root once per dispatched operation (the directory contai
 
 These are non-negotiable regardless of `confirm` or any skill-local override:
 - `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
-- `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
+- Never guess the marketplace-add direction from context — resolve strictly from the operation name (`add-package` vs `add-marketplace`); see apm-workflow/SKILL.md Gotchas for why the two are easy to conflate.
 - `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
 - A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
-- `apm experimental enable registries` must have already run before any `registry.*` config takes effect — check this precondition before dispatching an operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does.
+- Check the `apm experimental enable registries` precondition before dispatching any operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does — see apm-workflow/SKILL.md Gotchas for the underlying constraint.
 
 When invoked, you:
 1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
@@ -37,7 +37,7 @@ When invoked, you:
 ## Inputs
 
 - **operation:** string, one of:
-  - configure: init-package
+  - configure: init-package, edit-config (→ author/edit an existing package's `apm.yml` directly — adding a dependency, script, registries block, or removing a `marketplace.packages[]` entry; not a distinct `apm` CLI verb, just a manifest edit, optionally followed by `compile: pack` if it affects a published marketplace listing)
   - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer)
   - install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything)
   - compile: compile, pack, publish, run-script
diff --git a/plugins/kyberforge/agents/apm-orchestrate.md b/plugins/kyberforge/agents/apm-orchestrate.md
index f49e08f..b9df652 100644
--- a/plugins/kyberforge/agents/apm-orchestrate.md
+++ b/plugins/kyberforge/agents/apm-orchestrate.md
@@ -20,10 +20,10 @@ You resolve the package root once per dispatched operation (the directory contai
 
 These are non-negotiable regardless of `confirm` or any skill-local override:
 - `apm publish` claims a version on a registry — treat it as irreversible. Refuse without explicit `confirm: true`; always dispatch with `--dry-run -v` first and surface that output to the caller before the real publish, even when `confirm: true` was given.
-- `apm marketplace add` (registering a marketplace as a consumer) and `apm marketplace package add` (registering a local package into a marketplace being built) are opposite directions — resolve which one the caller means from the operation name, never guess from context alone.
+- Never guess the marketplace-add direction from context — resolve strictly from the operation name (`add-package` vs `add-marketplace`); see apm-workflow/SKILL.md Gotchas for why the two are easy to conflate.
 - `apm.yml`'s `type:` field constrains what `.apm/` may contain — when scaffolding (`init-package`), set `type:` before any primitive content is added; do not defer it.
 - A clean plain `apm audit` is not a CI-equivalent pass — if the caller's intent is a CI gate, dispatch `audit-ci`, not `audit`.
-- `apm experimental enable registries` must have already run before any `registry.*` config takes effect — check this precondition before dispatching an operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does.
+- Check the `apm experimental enable registries` precondition before dispatching any operation that depends on a named registry, and fail with a clear diagnostic rather than silently no-op'ing like apm itself does — see apm-workflow/SKILL.md Gotchas for the underlying constraint.
 
 When invoked, you:
 1. Parse the incoming workflow request (operation type, parameters, target package(s), context overrides)
@@ -37,7 +37,7 @@ When invoked, you:
 ## Inputs
 
 - **operation:** string, one of:
-  - configure: init-package
+  - configure: init-package, edit-config (→ author/edit an existing package's `apm.yml` directly — adding a dependency, script, registries block, or removing a `marketplace.packages[]` entry; not a distinct `apm` CLI verb, just a manifest edit, optionally followed by `compile: pack` if it affects a published marketplace listing)
   - marketplace: init-marketplace, check-marketplace, add-package (→ `apm marketplace package add` — register a local package into a marketplace being built), add-marketplace (→ `apm marketplace add` — register a marketplace as a consumer)
   - install: install (→ `apm install [PACKAGE_REF]` — resolve/fetch dependencies declared in `apm.yml` against `apm.lock.yaml`; no arguments re-resolves everything)
   - compile: compile, pack, publish, run-script
diff --git a/plugins/kyberforge/skills/README.md b/plugins/kyberforge/skills/README.md
index 7900b42..40c1e5e 100644
--- a/plugins/kyberforge/skills/README.md
+++ b/plugins/kyberforge/skills/README.md
@@ -27,5 +27,7 @@ authoring standard — trigger descriptions and body discipline are required.
 | `agent-author` | Author an agent definition file |
 | `pc-author` | Create, add, remove, and configure `.pre-commit-config.yaml` |
 | `pc-run` | Install, run, autoupdate, and maintain the pre-commit setup |
-| `plugin-author` | Create, update, and release plugin scaffolds for the holocron marketplace |
-| `marketplace-author` | Add, remove, and update plugin entries in the holocron marketplace manifest |
+| `plugin-author` | (Deprecated — see apm-workflow) Create, update, and release plugin scaffolds for the holocron marketplace |
+| `marketplace-author` | (Deprecated — see apm-workflow) Add, remove, and update plugin entries in the holocron marketplace manifest |
+| `apm-install` | Install or upgrade the apm CLI and set up the agent runtimes it drives (Copilot CLI, Codex, Gemini, generic llm) |
+| `apm-workflow` | Author apm.yml, scaffold an apm package/marketplace, install dependencies, and compile/pack/publish/audit apm content |
diff --git a/plugins/kyberforge/skills/apm-workflow/SKILL.md b/plugins/kyberforge/skills/apm-workflow/SKILL.md
index e7e26f1..8e41917 100644
--- a/plugins/kyberforge/skills/apm-workflow/SKILL.md
+++ b/plugins/kyberforge/skills/apm-workflow/SKILL.md
@@ -24,7 +24,6 @@ metadata:
 - `apm.yml`'s `type:` field (`instructions`, `skill`, `hybrid`, `prompts`) constrains what `.apm/` may contain — set it before scaffolding content, not after. Changing it later doesn't retroactively validate what's already on disk.
 - `includes: auto` publishes the authoritative local layout as-is. Anything narrower needs an explicit repo-path list — don't assume `auto` means "scoped down to what's relevant."
 - `apm marketplace add` (registering a marketplace as a *consumer*, pointing at someone else's catalog) and `apm marketplace package add` (registering a local package *into* a marketplace you're building) are opposite directions of the same command family — don't conflate them.
-- `apm pack` is the same command that both bundles a distributable artifact *and* emits `.claude-plugin/marketplace.json` as one of its compile targets — regenerating the Claude Code-native manifest isn't a separate step from packing.
 - MCP server secrets (headers, env vars) inside `apm.yml` must use `${VAR}` indirection, never literal values, so they're resolved at install/runtime and never committed to the manifest.
 - `apm experimental enable registries` must run before any `registry.*` config takes effect. Declaring a `registries:` block or running `apm config set registry.*` without it silently does nothing — no error, no warning.
 - Plain `apm audit` and `apm audit --ci` check different things: plain `apm audit` scans deployed files for hidden Unicode only; `--ci` additionally runs lockfile-consistency checks, install-replay drift detection, and org policy checks. A clean plain `apm audit` is not a CI-equivalent pass.
diff --git a/plugins/kyberforge/skills/apm-workflow/references/audit.md b/plugins/kyberforge/skills/apm-workflow/references/audit.md
index c9ec111..4e2b2c4 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/audit.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/audit.md
@@ -14,7 +14,7 @@ apm audit --ci              # CI gate: lockfile consistency + drift replay + pol
 apm audit --file <path>     # standalone: scan an arbitrary file
 ```
 
-`apm audit --ci` runs baseline lockfile checks, install-replay drift detection (does a clean `apm install` reproduce what's on disk), and org policy checks. Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. It covers AI agent configuration integrity, hidden-content scanning, lockfile verification, and policy enforcement — it does not replace general lint/test/security-scan CI steps, it sits alongside them.
+Exit code `0` on success, `1` on any violation — composes as a normal CI gate step. It does not replace general lint/test/security-scan CI steps, it sits alongside them.
 
 ## Policy checks
 
diff --git a/plugins/kyberforge/skills/apm-workflow/references/configure.md b/plugins/kyberforge/skills/apm-workflow/references/configure.md
index 7647909..890d156 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/configure.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/configure.md
@@ -21,73 +21,21 @@ name: my-pkg
 version: 1.0.0
 ```
 
-## `apm.yml` — full schema
+## `apm.yml` — top-level keys
 
-```yaml
-name: my-pkg
-version: 1.0.0
-description: Code review skills for Python services
-author: Jane Doe            # plain string, or {name, email?, url?} object
-license: MIT
-homepage: https://example.com/my-pkg
-repository: https://github.com/org/my-pkg
-keywords: [ai, review, python]
+- `name`, `version` — required (see above)
+- `description`, `author`, `license`, `homepage`, `repository`, `keywords` — standard package metadata
+- `type` — `instructions | skill | hybrid | prompts`; constrains `.apm/` contents
+- `targets` — which harnesses this package compiles to (plural list form preferred; legacy singular `target: copilot,claude` CSV form still accepted)
+- `includes` — `auto` publishes the authoritative local layout as-is, or list explicit repo paths
+- `dependencies`/`devDependencies` — `apm`/`mcp`/`lsp` entries; `devDependencies` share the same shape but are excluded from the shipped artifact
+- `scripts` — named commands runnable via `apm run <name>`
+- `compilation` — target/strategy/exclude/placement controls for `apm compile`/`apm pack`
+- `policy` — e.g. `fetch_failure_default`
+- `registries` — named registry endpoints for shorthand dependency resolution
+- `marketplace` — owner + packages list; see `references/marketplace.md` for the full marketplace workflow
 
-type: skill                 # instructions | skill | hybrid | prompts — constrains .apm/ contents
-
-targets:                    # which harnesses this package compiles to; prefer plural list form — legacy singular `target: copilot,claude` CSV form is still accepted
-  - copilot
-  - claude
-
-includes: auto               # "auto" = publish the authoritative local layout; or list explicit repo paths
-
-dependencies:
-  apm:
-    - microsoft/apm-sample-package#v1.0.0        # pinned to a tag
-    - github/awesome-copilot/skills/review-and-refactor  # single primitive
-  mcp:
-    - microsoft/azure-devops-mcp                 # MCP server dependency
-  lsp:
-    - name: pyright
-      command: pyright-langserver
-      args: ["--stdio"]
-      extensionToLanguage:
-        ".py": python
-
-devDependencies:             # same shape as dependencies, excluded from the shipped artifact
-  apm:
-    - my-org/internal-test-skills
-
-scripts:                     # named commands runnable via `apm run <name>`
-  start: "copilot -p 'README.prompt.md'"
-  review: "copilot -p 'code-review.prompt.md'"
-
-compilation:
-  target: all
-  strategy: distributed
-  exclude:
-    - "apm_modules/**"
-  placement:
-    min_instructions_per_file: 1
-
-policy:
-  fetch_failure_default: warn
-
-registries:
-  public-apm:
-    url: https://registry.example.com/api/public-apm
-  default: public-apm
-
-marketplace:                 # see references/marketplace.md for the full marketplace workflow
-  owner:
-    name: contoso
-    url: https://github.com/contoso
-  packages:
-    - name: code-review
-      source: contoso/code-review
-      version: "^1.0.0"
-      tags: [review, quality]
-```
+See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
 
 ## Dependency reference forms
 
@@ -95,23 +43,7 @@ marketplace:                 # see references/marketplace.md for the full market
 
 ## MCP server secrets
 
-Use `${VAR}` indirection for headers/env vars — never a literal secret value in `apm.yml`:
-
-```yaml
-mcp:
-  - name: linear
-    registry: false
-    transport: http
-    url: https://mcp.linear.app/sse
-    headers:
-      Authorization: "Bearer ${LINEAR_TOKEN}"
-  - name: my-internal
-    registry: false
-    transport: stdio
-    command: my-server
-    env:
-      API_TOKEN: "${MY_API_TOKEN}"
-```
+`${VAR}` indirection is required for MCP server secrets in `apm.yml` — see SKILL.md Gotchas.
 
 ## Registries (config-level, not `apm.yml`)
 
diff --git a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
index d86adfb..39c611e 100644
--- a/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
+++ b/plugins/kyberforge/skills/apm-workflow/references/marketplace.md
@@ -67,5 +67,5 @@ Without this block, the default versioning strategy ties every listed package to
 
 ## 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`.
+- A package/plugin `name` compiling to the `claude` target must avoid Claude Code's reserved name prefixes (see `plugin-author/SKILL.md` Gotchas for the current list) — 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. Confirm with the user in conversation before removing the entry and running `apm pack` — this is a normal `apm.yml` edit (not a distinct apm-orchestrate operation with its own gate), so the confirmation is conversational, the same as any other consequential manifest edit.
diff --git a/plugins/kyberforge/skills/forge/SKILL.md b/plugins/kyberforge/skills/forge/SKILL.md
index ea2ea5b..b7429c1 100644
--- a/plugins/kyberforge/skills/forge/SKILL.md
+++ b/plugins/kyberforge/skills/forge/SKILL.md
@@ -21,7 +21,7 @@ metadata:
 
 ## Gotchas
 
-- forge is an optional guided entry point, not a gate — the six existing factory skills (`skill-author`, `skill-audit`, `agent-author`, `agent-audit`, `plugin-author`, `marketplace-author`) remain directly invokable and forge does not intercept those calls.
+- forge is an optional guided entry point, not a gate — the six existing factory skills (`skill-author`, `skill-audit`, `agent-author`, `agent-audit`, `plugin-author`, `marketplace-author`) remain directly invokable and forge does not intercept those calls. Note `plugin-author` and `marketplace-author` are deprecated per ADR-0015 — superseded by `apm-workflow`, pending issue #90 — but still function normally until that lands.
 - Claude Code's skill-level `context: fork` frontmatter field and the `/fork` subagent command are opposites despite sharing a name — `context: fork` isolates (fresh context, no parent access), while `/fork` inherits the full conversation. Keep this straight when deciding how to invoke a subagent in Step 3.
 
 ## Step 1 — Grill the intent
@@ -43,6 +43,8 @@ Match the grilled intent against exactly one row (or more than one, if the inten
 
 If the intent is genuinely ambiguous between rows even after grilling, ask the user directly rather than guessing.
 
+Note: `kyberforge:plugin-author` and `kyberforge:marketplace-author` are deprecated per ADR-0015, superseded by `apm-workflow` — pending issue #90, so routing to them is unchanged for now.
+
 This table classifies what to build, not how to run it — a one-off task that merely needs an isolated vs. context-inheriting run (rather than a new, reusable definition) isn't an artifact at all; there's nothing here to route it to.
 
 ## Step 3 — Announce, then route
diff --git a/plugins/kyberforge/skills/marketplace-author/SKILL.md b/plugins/kyberforge/skills/marketplace-author/SKILL.md
index 37a7040..926f40f 100644
--- a/plugins/kyberforge/skills/marketplace-author/SKILL.md
+++ b/plugins/kyberforge/skills/marketplace-author/SKILL.md
@@ -9,7 +9,8 @@ description: >
   the same pass. Out of scope: plugin scaffold and configuration — use
   /plugin-author for that. Does not run `claude plugin marketplace add` or
   equivalent CLI registration commands — only manages `marketplace.json`
-  entries.
+  entries. Deprecated per ADR-0015 — superseded by apm-workflow; kept until
+  issue #90 lands.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: factory
diff --git a/plugins/kyberforge/skills/plugin-author/SKILL.md b/plugins/kyberforge/skills/plugin-author/SKILL.md
index 7402e5f..5a663ed 100644
--- a/plugins/kyberforge/skills/plugin-author/SKILL.md
+++ b/plugins/kyberforge/skills/plugin-author/SKILL.md
@@ -8,7 +8,8 @@ description: >
   (.claude-plugin/plugin.json) and Copilot CLI (plugin.json) manifests in one
   pass. Do not use when the request is about plugin content (skills, agents,
   hooks, or MCP servers inside those directories). Do not use for
-  marketplace.json entries — use /marketplace-author for that.
+  marketplace.json entries — use /marketplace-author for that. Deprecated
+  per ADR-0015 — superseded by apm-workflow; kept until issue #90 lands.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: factory
@@ -26,7 +27,7 @@ metadata:
 
 ## Gotchas
 
-- Both manifests must carry identical `version` values — version parity is a hard invariant (ADR-0016). Never update version in one manifest without updating the other in the same edit pass.
+- Both manifests must carry identical `version` values — version parity is a hard invariant (ADR-0006). Never update version in one manifest without updating the other in the same edit pass.
 - Every UPDATE to non-version fields (description, keywords, author, etc.) requires a patch bump to `version` in both manifests in the same edit pass. Consumers cache plugin metadata and use the version to detect changes — skipping the bump makes the update invisible until a forced refresh.
 - `author.email` is placed in the Copilot manifest by convention; `author.url` is placed in the CC manifest by convention. Both fields are supported by both platforms — do not add them to the other manifest without a deliberate reason.
 - `claude plugin tag --push` is irreversible: it creates a git tag and pushes it to remote. Always present the HITL gate and wait for explicit confirmation before running it.
@@ -105,7 +106,7 @@ Open both manifest files and replace every `FILL_IN_*` placeholder.
 Check:
 - [ ] `name` identical in both manifests, kebab-case, no reserved prefixes
 - [ ] `description` identical in both manifests, non-empty
-- [ ] `version` identical in both manifests (version parity — ADR-0016)
+- [ ] `version` identical in both manifests (version parity — ADR-0006)
 - [ ] `author.name` identical in both manifests
 - [ ] `license` identical in both manifests
 - [ ] `keywords` identical in both manifests
-- 
2.43.0