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