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).

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.

plugins/kyberforge/.claude-plugin/plugin.json

@@ -8,5 +8,5 @@
   "keywords": [],
   "license": "MIT",
   "name": "kyberforge",
-  "version": "1.2.8"
+  "version": "1.3.0"
 }

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.

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>"]
+  }
+}
+```

plugins/kyberforge/plugin.json

@@ -13,5 +13,5 @@
   "skills": [
     "skills/"
   ],
-  "version": "1.2.8"
+  "version": "1.3.0"
 }

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 |

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.

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`

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 |

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.

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.

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.

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.

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.

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`

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`