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:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user