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

Description 648 -> 387 chars, body 1093 -> 541 words. This was the last
body FAIL in the 39-skill corpus.

The body was not trimmed to fit. forge routes four artifact types that a
single invocation classifies between, so the contract requires a dispatch
table plus the gates common to every route, with each route self-contained
in references/. Adds references/author-routes.md (skill and agent),
references/apm-routes.md (plugin and marketplace entry) and
references/version-bump.md. Skill and agent share one file: they differ on
one axis only, which audit skill verifies the result.

Fixes three defects the first pass introduced or relocated:

- references/apm-routes.md claimed `apm audit` "already runs inside
  apm-workflow's own flow" and told the agent to confirm it ran clean.
  apm-workflow dispatches audit as its own row; the configure and
  marketplace rows never reach it. That was the only completion check
  these routes had, and it could never be satisfied. Replaced with a
  manual read-back the agent performs itself.
- "Read only the reference file" forbade the multi-artifact case the same
  body documents two lines later, and ADR-0011 records eight artifacts
  authored in one pass.
- The announce gate became a closing gate, reachable only after the
  invocation it was meant to precede. Moved to the end of Step 2.

Also restores the artifact enumeration to the plugin row, normalises to
bare unnamespaced skill names per AGENTS.md, adds a dispatch fallback for
artifacts matching no row, and corrects three provenance entries -- one
asserted a contribution that did not happen.

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:23 +00:00
parent 1e4aab53a7
commit 4aab9d327c
12 changed files with 330 additions and 140 deletions

View File

@@ -0,0 +1,42 @@
---
source_keys:
- claude-code-subagents-docs
---
# Routing a plugin or marketplace entry to apm-workflow
Reached from `SKILL.md` Step 2 when the classified artifact is a plugin or a marketplace entry.
Both route to `apm-workflow` — a plugin to its configure flow (`apm plugin init`), a marketplace
entry to its marketplace flow (`apm marketplace package add`).
No other skill is a candidate for these two rows: `plugin-author` and `marketplace-author` were
removed per ADR-0015 once issue #90 landed, and `apm-workflow` is their sole successor.
## Always inline, never forked
Run these routes inline, in the current conversation. Their flows are short, prompt-heavy or
gated — `apm-workflow`'s publish and release steps take a HITL gate, and removing a marketplace
entry takes a conversational confirmation — and a backgrounded fork cannot surface those
checkpoints to the user in real time.
## No clean-context recheck, and no automatic audit
Skill and agent routes close with a clean-context audit rerun; these two do not, and the omission
is deliberate rather than an oversight. Neither artifact type has an audit skill counterpart to
re-run, so detaching the route to earn a recheck it would never get buys nothing.
These routes get no automated terminal check either. `apm audit` is a separate action on
`apm-workflow`'s own dispatch table, not a closing step of the configure or marketplace flow a
forge route lands in, so a completion message from either says nothing about it. Do not wait for
one and do not report one you did not see.
Verify by hand instead. Read back what the route wrote against what the grill settled:
- **Plugin** — the package directory exists where the intent said it should, and its `apm.yml`
carries the intended `name`, a top-level `type:` field, and a `version`.
- **Marketplace entry** — the entry names that package, points at the source the intent settled
on, and carries the version the package actually declares.
If the change warrants the full integrity and policy check rather than a read-back, invoke
`apm-workflow` again for its audit action and run `apm audit` deliberately. Then return to
`SKILL.md` Step 3 for the closing gates common to every route.