refactor(kyberforge): retrofit apm-workflow to the ADR-0020 contract

Description 817 -> 324 chars, body 421 -> 237 words, Gotchas 6 -> 2.

The five capability clauses, the second trigger register and the prose
boundary form go; one trigger clause, the indirect trigger and one
boundary clause remain. Four of six Gotchas move into the flow file that
every branch needing them already loads.

Two stay in the always-loaded body because a dispatch body must carry the
gates common to every branch, not just the dispatch table: the MCP secret
indirection rule, and the `apm experimental enable registries`
precondition. The first pass moved registries into references/configure.md
alone, which stranded it -- references/compile.md documents publishing to a
registry and references/install.md resolves dependencies through one, and
neither points at configure.md. Declaring a registry without the
precondition is a silent no-op, so the failure had no signal.

Also drops an unsourced claim the compression pass introduced (that apm
checks `type:` going forward -- no source supports it), corrects the MCP
rationale to install *or* runtime per configuration.md:98, and repoints
two apm-orchestrate back-references that pointed at body Gotchas which had
moved.

Refs #99

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MWb5RQgCL1ye7cGp2RPb2u
This commit is contained in:
2026-08-30 16:31:11 +00:00
parent 915eb09ae2
commit 1e4aab53a7
14 changed files with 52 additions and 60 deletions

View File

@@ -1,18 +1,11 @@
---
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.
Use when the user wants to author, scaffold, install, compile, publish, or
audit an apm package, an apm.yml manifest, or an apm marketplace, or register
someone else's to consume — even when they do not say "apm"
explicitly, e.g. "set up the package manifest". Not the apm binary itself or
an agent runtime -> `apm-install`.
metadata:
category: apm
source_keys:
@@ -21,12 +14,8 @@ metadata:
## 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." Note: `auto` still excludes generic root-level passthrough files (README.md, docs/, sources.md, config files) from the `apm pack` distribution bundle — see `references/compile.md`.
- `apm marketplace add` (registering a marketplace as a *consumer*, pointing at someone else's catalog) and `apm marketplace package add` (registering a package by remote reference — `owner/repo`, host URL, or full URL — into a marketplace you're building) are opposite directions of the same command family — don't conflate them. `package add` does NOT accept local paths; a local package is registered by hand-editing `apm.yml`'s `marketplace.packages[]` directly — see `references/marketplace.md`.
- 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.
- MCP server secrets in `apm.yml` (headers, env vars) must use `${VAR}` indirection, never literal values, so they resolve at install or runtime and are never committed.
- `apm experimental enable registries` must run before a `registries:` block or `registry.*` config takes effect anywhere — configure, install or publish. Without it, declaring one silently does nothing: no error, no warning.
## Step 1 — Dispatch
@@ -38,7 +27,7 @@ metadata:
| `/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.
Read only the reference file matching the requested action — each is self-contained for its concern, and each carries the traps specific to its flow.
## Step 2 — Execute