.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": []

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

docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md

@@ -0,0 +1,115 @@
+# Microsoft APM replaces the hand-authored plugin/marketplace model as this repo's authoring source of truth
+
+**Will supersede:** ADR-0001 ("Skills are distributed via plugins... each plugin contains its
+own `skills/` directory") — once issue #90's conversion actually executes; not yet in effect.
+
+This repo replaces its hand-maintained Claude Code plugin/marketplace authoring model
+(`.claude-plugin/marketplace.json` + per-plugin `plugin.json`) with Microsoft APM (`apm.yml` +
+`.apm/`) as the authoring source of truth — an outright replacement of the authoring layer, not an
+additive overlay. This ADR records the decision from a `grill-with-docs` session on issue #88.
+
+## Context
+
+Every plugin under `plugins/<name>/` currently ships two hand-maintained manifests
+(`.claude-plugin/plugin.json` for Claude Code, root `plugin.json` for Copilot CLI) plus a
+hand-maintained root `.claude-plugin/marketplace.json` listing all plugins. Adding a provider means
+hand-authoring a third manifest shape; keeping the two existing ones in parity is itself a tracked
+concern (ADR-0006).
+
+Research on Microsoft APM (`plugins/kyberforge/docs/research/docs/microsoft-apm/`) found that its
+documented "monorepo-hybrid" repo shape maps directly onto this repo's existing `plugins/<name>/`
+layout: each plugin becomes its own `apm.yml` + `.apm/{skills,agents,hooks,prompts,instructions}/`
+package, listed from a root `apm.yml`'s `marketplace:` block. `apm compile`/`apm pack` generate
+per-target output — including a `.claude-plugin/marketplace.json` — from that vendor-neutral
+`.apm/` tree, so provider manifests become compiled artifacts instead of hand-authored files, and
+new providers (Copilot, Gemini, Codex — all supported by `apm runtime setup`) no longer require a
+new hand-maintained manifest format.
+
+## Decision
+
+- **The `plugins/<name>/` monorepo-hybrid directory layout survives.** `.claude-plugin/marketplace.json`
+  and per-provider `plugin.json` files become **compiled output** via `apm compile`/`apm pack`,
+  generated from `apm.yml` + `.apm/` per plugin, extensible to other `apm runtime`-supported
+  providers without hand-maintaining a separate manifest per provider.
+- **This will supersede ADR-0001** ("Skills are distributed via plugins... each plugin
+  contains its own `skills/` directory"), but not yet — supersession is pending on issue #90's
+  conversion. Once that real conversion executes, skills and agents physically move to
+  `plugins/<name>/.apm/skills/` and `plugins/<name>/.apm/agents/*.agent.md`.
+- New operational tooling — `apm-install` (skill), `apm-workflow` (skill), `apm-orchestrate`
+  (agent) — lands in `kyberforge`, tracked in issue #88
+  (https://git.dev.rkdr.net/Defame1297/holocron/issues/88).
+- Adapting `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).
+- `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
+
+**Additive/compile-layer only, no `apm.yml` (rejected).** Keep `plugin.json`/`marketplace.json`
+hand-authored and bolt APM on top as an optional extra. Rejected: doesn't achieve the multi-provider
+compile-reuse goal APM's package model provides, and leaves the existing dual-manifest hand
+maintenance in place unchanged.
+
+**New standalone `plugins/apm/` plugin (rejected).** `plugins/lint/` was split out of `kyberforge`
+specifically because Vale tooling is generic and repo-agnostic, not holocron-marketplace-specific
+(see `CONTEXT.md`'s "lint plugin" entry) — the same argument applies to a generic `apm` CLI
+wrapper. The shipped `apm-install`/`apm-workflow` skills are, in fact, generic, repo-agnostic APM
+CLI documentation with no holocron-specific content, so a standalone `plugins/apm/` would have
+been a defensible split on artifact content alone. Rejected anyway, in favor of `kyberforge`,
+because holocron is currently the only repo that needs this tooling — standing up a separate
+plugin for a single consumer isn't worth it yet. Accepted as an explicit tradeoff (same pattern
+as ADR-0011's `gitea-workflow` naming tradeoff) — worth revisiting if this tooling is ever reused
+outside holocron's own conversion.
+
+## 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) 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.
+- 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 track the remaining work: #89 (`skill-author`/`agent-author` routing
+  adaptation) and #90 (the actual repo conversion, which also deletes `plugin-author`/
+  `marketplace-author`).

plugins/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

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

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

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

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
 

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 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
+
+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.
+- 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`.
+- 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)
+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`, `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 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
+
+- **operation:** string, one of:
+  - 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
+  - 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, 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, 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
+
+## 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, Skill
+
+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 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
+
+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.
+- 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`.
+- 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)
+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`, `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 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
+
+- **operation:** string, one of:
+  - 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
+  - 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, 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, 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
+
+## 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/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`).

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.

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

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` 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
+
+- **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.

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.

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.

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

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`

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.

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.

plugins/kyberforge/plugin.json

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

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 |

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` 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`.
+
+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,33 @@
+# 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, 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
+
+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 install
+/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/install.md` | apm install, apm install [PACKAGE_REF], --update, --target agent-skills |
+| `references/marketplace.md` | Building/registering a marketplace, package registration, versioning, Claude Code reserved-name/publish-confirm gotchas |
+| `references/compile.md` | apm compile / pack / publish / run, claude plugin validate agents/ gotcha |
+| `references/audit.md` | apm audit, apm audit --ci, apm marketplace check, CI wiring, frozen installs, claude plugin validate terminal check |
+| `references/sources.md` | Provenance chain — research sources that informed this skill |

plugins/kyberforge/skills/apm-workflow/SKILL.md

@@ -0,0 +1,45 @@
+---
+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), 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:
+    - 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.
+- 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 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 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.
+
+## 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,55 @@
+---
+topic: audit
+source_keys:
+  - context7-microsoft-apm
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+---
+
+## `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
+```
+
+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
+
+`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.
+
+## Claude Code validation is a separate terminal check
+
+For packages compiling to the `claude` target, also run `claude plugin validate [--strict]` against the compiled output as a terminal check. `apm audit`/`apm audit --ci` do not check Claude Code-marketplace-specific schema rules (reserved prefixes, the `agents/` stray-file behavior — see `references/compile.md` — etc.), so they don't substitute for it.

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

@@ -0,0 +1,48 @@
+---
+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.
+
+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
+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.
+
+## 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 (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.

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

@@ -0,0 +1,59 @@
+---
+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` — top-level keys
+
+- `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
+
+See `docs/research/docs/microsoft-apm/configuration.md` for the complete annotated schema.
+
+## 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
+
+`${VAR}` indirection is required for MCP server secrets in `apm.yml` — see SKILL.md Gotchas.
+
+## 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/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.

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

@@ -0,0 +1,71 @@
+---
+topic: marketplace
+source_keys:
+  - context7-microsoft-apm
+  - context7-websites-code-claude
+  - claude-code-plugins-docs
+---
+
+## 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
+```
+
+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.
+
+## 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.
+
+## Gotchas
+
+- 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.

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

@@ -0,0 +1,33 @@
+# 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/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`

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

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
@@ -22,6 +23,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.

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
@@ -22,9 +23,11 @@ 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.
+- 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.
@@ -103,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

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`