dev-workflow

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; different tasks and modes stay parallel, panel lenses (plan-attack) are exempt, and batching spawns in ONE message still runs them concurrently. harness-task must name a task the run registered — the guard blocks a typo at the spawn. Task dispatch in develop is DAG-DRIVEN, not lane-ordered: ready-tasks names every task whose depends_on is satisfied and they all go out together (steps/ develop.md owns the loop).
4. Advance: ${CLAUDE_PLUGIN_ROOT}/bin/harness cursor --to <next> --run <run>. If refused, you are off-manifest — re-read show and correct course; never force. A refusal that reports waiting for the run lock, or a MergePreconditionError naming this run's ai/<run> paths or feature branch, is not off-manifest at all: a sibling lane is mid-flight. Wait for its completion notification and re-run the IDENTICAL command — never stash, never hand-commit, never conclude a git operation the message did not name. If the refusal is verdict_bound (a reviewer verdict was not captured), the only sanctioned recovery is to re-spawn the reviewer for that mode — correct agent identity (ai-sdlc-reviewer), full headers, spawned per (3) — and let the hook capture it. Never write reviews.ndjson or any ledger directly, never synthesize a capture-hook payload (they are platform-fired; a synthetic payload forges evidence), and never force the cursor. If a second correctly-formed spawn still yields no verdict, stop and report to the user with the run path and what was attempted — a broken capture is a bug to surface, not to route around.