/dev-workflow

name: dev-workflow
description: >
  Run the governed SDLC pipeline for a work item. USER-ENTRY — invoke only
  when the user explicitly runs /dev-workflow <work-item-id>; never trigger
  autonomously from conversation, and never from a subagent (guard-enforced).

dev-workflow — the thin orchestrator walker

You are the **orchestrator**: a coordinator, not an implementer. You never write code, never touch `ai/<run>/` authority files directly, and never run raw `git commit|merge|rebase` — every mutation goes through `harness` (guards block the raw paths and redirect you here).

Every command below runs through `${CLAUDE_PLUGIN_ROOT}/bin/harness` — a wrapper script that resolves the plugin venv (created by /init-workspace, either OS layout) and falls back to system `python3`/`python` pre-setup; it runs under Git Bash on Windows too. `--workspace <ws>` and `--run <run>` may go before or after the verb, in any mix — e.g. both `harness --workspace <ws> --run <run> <verb> …` and `harness <verb> --workspace <ws> --run <run> …` work. Always use the full `${CLAUDE_PLUGIN_ROOT}` path; a bare `harness` is not on PATH, and shell variables do not persist between separate Bash calls. Non-zero exit = refused; read the JSON error.

Startup

1. `${CLAUDE_PLUGIN_ROOT}/bin/harness fetch --id <work-item-id>` — refuses if bootstrap is incomplete (run `/init-workspace` first) or a live run already exists (offer the user **Resume or Abort** — never clobber). Abort is a real verb: `${CLAUDE_PLUGIN_ROOT}/bin/harness abort --run <run> --reason "<why>"` — terminal (mutations refuse from then on), sweeps worktrees, keeps the audit trail, and releases the work-item slot so a fresh fetch works. On success note `run`, `mode`. 2. The pipeline manifest (`${CLAUDE_PLUGIN_ROOT}/pipeline/manifest.yaml`) is the single source of truth for step order. Do not improvise steps.

The walk

Loop until the mode's sequence is exhausted, then close the run: `${CLAUDE_PLUGIN_ROOT}/bin/harness complete --run <run>` (terminal, the successful sibling of abort — the final step's file says exactly when).

1. `${CLAUDE_PLUGIN_ROOT}/bin/harness show --run <run>` → current step, mode, tasks, gates. It also returns `next_steps` (the engine-legal cursor moves right now, the same `{step: reason}` set `cursor --to` validates against), `derived` (ledger-fresh `verdict_bound` outcomes that the persisted `state.artifacts` cache hasn't caught up to yet — e.g. a plan-review already APPROVED in the ledger shows `{"plan-review.outcome": "approved"}` here while `state` still reads `pending`), and `probe_error` (`null` normally; a non-null value is the engine's own reason there is no legal move yet — a seal-valid but malformed state, a `when` predicate needing an artifact this step still produces, or a corrupt ledger — so an empty `next_steps` is never mistaken for "wedged" (a fail-closed verdict window is NOT one of these: the walk completes and returns `{}` with `probe_error` null). These are a read-only compass, not a substitute for the step contract: the step file (2) remains the instruction authority for what to actually do. 2. Read the step's file: `${CLAUDE_PLUGIN_ROOT}/skills/dev-workflow/steps/<step>.md` — load ONE step file at a time (context economy). Gate steps all use `steps/gate.md`. 3. Execute it. Spawning a shape? The prompt MUST carry the structured headers (`harness-mode`, `harness-task`, `harness-run`, `harness-repo`, `harness-test-cmd`, `harness-plugin-root`). **Agent identity**: step text says "Spawn `reviewer`" — that's the shape word; pass the agent's frontmatter name (`ai-sdlc-reviewer`), not a generic agent. See `shared/spawn-identity.md` for the mapping and the reason a wrong identity silently disables governance. The spawn guard now BLOCKS a harness-headed spawn that uses a non-harness agent type. Enforcement, precisely: the spawn guard BLOCKS a harness-shape spawn missing `harness-mode`, and one missing `harness-run` whenever the spawn is legalized by a run's current step (the header must name THAT run). The remaining headers are capture conventions — `harness-task` attributes the token ledger and reviewer verdicts (a per-task review whose spawn omits it cannot satisfy the task's completion guard), `harness-repo`/`harness-test-cmd` scope the subagent's work, `harness-plugin-root` passes the resolved plugin install path (agents use it as `$PLUGIN_ROOT` to open instruction files and run `bin/harness` — the token must NOT be `${CLAUDE_PLUGIN_ROOT}` because Qwen's `templateString` scans agent bodies for braced tokens and rejects unknown keys at spawn). Before every spawn, resolve its model: `${CLAUDE_PLUGIN_ROOT}/bin/harness resolve-model --shape <shape> --mode <mode>` (per-mode ?? per-shape default ?? `inherit`, from `subagent_models`). Pass the result as the spawn's `model` param — unless it's the literal string `inherit`, in which case omit the `model` param entirely so the subagent runs on the session model. If the resolve-model result carries a `notice` key, relay its text to the user verbatim the FIRST time it appears in this run; it repeats on every resolve and needn't be repeated. **Background or foreground — both are captured:** where the Agent tool has `run_in_background`, `true` and `false` are equally legal; where it defaults spawns to background or has no such parameter, the spawn returns a launch STUB in place of the reply. On a stub: WAIT for its completion notification, do not proceed on the stub, and do not `stall` (`show`'s `outstanding_spawns` names every spawn still in flight — the Stalls triage below starts there, not at the events tail). Read the verdict from the LEDGER (`show`, or the cursor/task gate refusing) — never from reply text. One live spawn per (task, mode): the guard refuses a second while the first is unreported