--- name: next-task description: Start the next unblocked task in the build with full ceremony (project specifics from the profile). Use when the user says "next task", "work the next task", "continue the build", "what's next", or names a task ID to implement. Picks the task, opens the issue, cuts the branch, implements with tests, verifies, and runs review — stopping at PR (review mode). --- # /next-task — Claude Code binding The workflow logic is runtime-neutral and demand-loaded from **`.claude/workflow/next-task/*.md`**. Start with the compact project packet and `next-task/00-foundations.md`; when a stage completes, follow that card's `Next:` link and load only its successor. Do **not** preload the ordered `.claude/workflow/next-task.md` index, another card, or the old full procedure for ordinary work. Escalate to the index only to resume at an unknown stage or audit the full procedure. This file maps the cards' abstract **[roles]** to concrete Claude Code mechanisms: | Neutral role | Claude Code mechanism | |---|---| | **[reviewer]** | the `spec-auditor` / `constitution-auditor` / `contract-auditor` / `spec-quality-auditor` subagents (`.claude/agents/`), dispatched via the Agent tool — read-only, own context (pass `spec-auditor` the task ID in its prompt). **Membership, tier, and dispatch-condition are single-sourced in the roster (`gate-loop.md`) + §7, not this row** — so the Workflow-tool-absent fallback (this row → §7) dispatches the full set, the two conditional reviewers (`contract-auditor` / `spec-quality-auditor`) firing on their roster conditions; never omit the spec-quality reviewer on a `specs/*/spec.md` diff. `reviewer-roster.test.sh` pins this map's membership so a reviewer can't silently drop off it | | **[frontier tier] / [strong tier] / [cheap tier]** | resolved per the model table **`.claude/MODELS.md`** (the adapter's ONLY file naming models) — `--model` headless; the Agent tool's `model` parameter on EVERY reviewer dispatch (the agents carry no model pin; the constitution reviewer is always dispatched at-or-above the strong-tier row) | | **[code-review pass] / [security-review pass]** | `/code-review` / `/security-review` | | **[craft-review pass]** *(optional)* | the `engineering-craft` skill's review mode — `engineering-craft review` (equivalently `/engineering-craft review`), run **alongside** `/code-review` at §7 step 3, **never** a roster `[reviewer]` and advisory only (findings to the PR body, no PASS/FAIL gate). An **external**, separately-installed skill (unlike the built-in `/code-review`), so when it is absent skip the craft layer and note the skip in the PR (`workflow/README.md` → "How an adapter degrades gracefully"). Full mechanism + external-dependency detail: `.claude/README.md` | | **[visual verification]** | `/run` + `/verify` launch and drive the app; the preview tooling captures screenshots (screen-recording where available, for animation work); commit evidence under `docs/visual-evidence//` on the task branch and embed it in the PR body's "your call" section via commit-SHA-pinned raw URLs (URL form: the [environment block] below) | | **[orchestrated run]** | the Workflow tool running `.claude/workflows/gate-loop.js` (binding of `workflow/gate-loop.md`) for §7 steps 2/4/5 — commit first, resolve `{strongModel, cheapModel}` from `.claude/MODELS.md`, then invoke with `args: {taskId, strongModel, cheapModel, dispatchContract, dispatchSpec, taskBranch}` **from a session rooted in the repo** — the reviewer subagents dispatch by custom `agentType`, which the runtime resolves from the **session root's `.claude/agents/`** (not `workspacePath`), so a dispatcher rooted elsewhere resolves none of them; a **deterministic preflight** (T642/#214) probes the roster agent types before round 1 and **aborts before any reviewer dispatch** (zero fix rounds) with a diagnostic naming the unresolvable type(s) + the dispatcher-rooted-outside-the-repo cause, never a NO-RESULT fan-out that burns the fix budget grading nothing. `taskBranch` is the branch you cut in §4 and is the **required review-mode audited ref** (T639/#240): the gate's diff-provider verifies the **shared** tree's HEAD still matches it before every dispatch — through `.claude/hooks/gate-diff.sh`, which fails the gate **loud** on a concurrent-session branch switch instead of letting the reviewers grade the wrong diff — AND the gate's fix step restores the **shared** working tree onto it before each fix-and-re-dispatch round (review mode: a shell-holding step in the loop — the diff-provider or the fixer — can drift the shared HEAD off the task branch, so the loop heals it at the fix boundary, not only after the run; the read-only reviewers can't, holding no shell — #140/T622, #188). One of `taskBranch` (review) or `workspacePath` (autonomous) is **required** — the loop hard-errors on neither, refusing to audit an inferred working directory — **plus `workspacePath`** (the `enter`-printed worktree path) under an engaged isolated autonomous run, so the diff-provider reads the **workspace's** committed diff via an explicit `git -C ` (the reviewers audit that provided diff, #188) and the fixer commits there (gate-in-place, T612; the work is isolated there, so the shared-tree `taskBranch` restore does not apply; omit `workspacePath` for review mode and those commands target the main tree instead); it returns every verdict verbatim for §8 posting, plus `telemetry`: the gate-run record payload (`workflow/telemetry.md`). **After the workflow returns** (any outcome), **first restore the task branch (review mode)** — run `.claude/hooks/restore-task-branch.sh ` from the repo root: the loop's shell-holding steps (the diff-provider and the fixer) run in the **shared** working tree, so a stray `git checkout`/`switch` there can silently relocate the maker's HEAD off the task branch (#140/T622; the read-only reviewers no longer can — they hold no shell, #188); the helper is a no-op when nothing drifted and **fails loud** (exit 1) when it cannot guarantee the branch — surface that, never push/PR from a drifted HEAD. Run it **before** the `commit` capture below so telemetry records the restored HEAD, not a drifted one. (Autonomous mode's work lives in the ephemeral `[isolated workspace]` governed by the lifecycle, so this shared-tree restore is review-mode only.) Then append the record: take `result.telemetry`, add the envelope (`timestamp` ISO-8601 UTC now; `repo` = basename of `git rev-parse --show-toplevel`) **and** `commit` = `git rev-parse HEAD` (the head SHA of the audited diff — read it here, after the gate returns, so any fix-round commits the loop made on the task branch are included), resolve the stream path from the packet (`.claude/PROJECT.compact.md` → "Paths" → "Telemetry stream" — the packet carries this routing fact, drift-checked against the full profile; escalate to `.claude/PROJECT.md` only if the packet is absent), creating the parent directory if missing, and append it as ONE JSON line (`jq -c` or equivalent — never pretty-printed, never rewriting the file). A failed append is silent-to-the-gate: note it in the session and proceed exactly as if it had succeeded — the gate outcome, §8 posting, and the PR are unaffected. If the Workflow tool is unavailable, fall back to §7's prose (dispatch the reviewers via the Agent tool yourself; build and append the same record from your own dispatch history) | | **[bulk-read offload]** | the `Explore` subagent (spawn on the [cheap tier] model per `.claude/MODELS.md`) | | **[headless run]** | `claude -p "/next-task "` | | **[live-state reconciliation]** (the §1 selection precondition) | run `.claude/hooks/reconcile-task-selection.sh ` from the repo root before committing to a candidate: **exit 3** = drift — its box is unchecked but merged/landed work exists, so refuse the candidate and surface the printed evidence, never start it; **exit 0** = selectable; **exit 2** = usage. Git-based, so it shares `lib-tasks-drift.sh` with CI's `check-tasks-consistency.sh` (one drift definition, two consumers) and needs no network; it **fails open** (warns + exit 0) when git state is unreadable. This git-only check covers the **merged/landed** axis (a landed `[T]` commit subject). Its **in-flight** companion is `.claude/hooks/reconcile-inflight-selection.sh `, run **after** this one clears a candidate: it resolves the candidate's mapped issue and consults `gh` for an open PR whose title carries `[]` or a remote branch `/-…` — **exit 3** = in-flight (refuse + surface the conflicting PR/branch), **exit 0** = selectable, **exit 2** = usage. Being a tracker read it **fails open** (warns + exit 0) when `gh`/network is unavailable, degrading to this git-only result — never a stall (T615/#105). It deliberately does **not** source `lib-tasks-drift.sh`: in-flight is a distinct tracker signal, not a fork of the git drift definition (P2) | | **[selection announce-and-confirm]** (the §1 announce + conditional confirm) | After resolving the candidate, run `.claude/hooks/announce-task-selection.sh ` from the repo root, passing the mode **explicitly** — the binding knows whether the user named a task id/issue, never inferred. It prints the decision on stdout: **`proceed`** = announce the resolved target (task id + issue) and continue, no prompt; **`confirm`** = announce, then **pause and ask the user** before the first file edit (present the live-state contradiction + the drift evidence via the `AskUserQuestion` tool, offering "confirm this target" / "pick a different task or issue" — on a redirect re-run §1 with the named target; the pause **never starts the contradicted candidate**, and a merge is never an offered choice); **`announce-only`** = announce + continue, degraded (live state unreadable — no stall). Exit 0 (decision) / 2 (usage). **Composition with [live-state reconciliation], keyed to the selection's provenance:** for an **explicit** pick, reconcile's `exit 3` is the *terminal* refusal of a named stale task and announce then only ever `proceed`s; for an **implicit** pick, run announce on the lowest-unchecked candidate and let its `confirm` surface the *same* drift reconcile detects as a pause-for-redirect — so `confirm` is reachable on the real composed path and is **not** gated behind a reconcile `exit 0` (the composed path is pinned by `announce-task-selection.test.sh`'s `run_composed` cases). Shares `lib-tasks-drift.sh` — the third consumer (one drift definition, never forked). A `[headless run]` names the id explicitly, so it resolves to `proceed`; the confirm pause is an interactive-session affordance. T614 | | **[autonomy activation]** (the §0.5 run-mode decision) | run `.claude/hooks/autonomy-mode.sh [--session-authorized]` from the repo root — it prints `review` or `autonomous` on stdout (exit 0; 2 = usage). Default-OFF and **fails closed to review** (the deliberate inverse of the [guard]); `autonomous` only when the profile carries `autonomy-opt-in: enabled` **or** `--session-authorized` is passed (the runtime sets that flag when the user authorizes autonomy in-session — explicit-context, never inferred from env). On `review` run the normal path; on `autonomous` enter the [isolated workspace] (next row). T610 / DESIGN-NOTES §13 | | **[isolated workspace]** (the §4 enter; the §8 outcome-driven teardown) | the worktree lifecycle in `.claude/hooks/isolated-workspace.sh`: `enter [--base ]` adds an ephemeral git worktree on a **fresh** branch and **prints its path** on stdout — capture it and carry it forward (explicit-context); `exit ` tears the workspace **directory** down, **leaving** the branch (the teardown half of promote); `discard ` tears the directory down **and deletes the ephemeral branch** (discard-on-FAIL). `enter` **fails loud** (non-zero, no path) → **abort** the autonomous run, never fall back to the base branch. **Gate-in-place (T612):** the §7 gate reads the workspace diff (pass the path as `workspacePath` to the [orchestrated run] above), then §8's terminal step follows the gate outcome — **PASS → promote** = commit + `git push` + `gh pr create`, then `exit `; **FAIL → discard** = `discard `, no push, no PR. Promotion is a PR (merge stays session-explicit, §8), never a direct base-branch write (P4). All three verbs refuse any path `enter` did not create — a provenance marker `enter` writes beside the workspace, not the `creance-ws-*` name alone, is the proof (Codex P2, #114). **Falsification proof (T613):** `.claude/hooks/isolation-falsification.test.sh` (wired into `verify`) adversarially proves an un-gated change cannot reach the base branch through the lifecycle, and the live **P-IW** conformance probe (`.claude/adapters/claude-code-probes.md`) confirms the isolation tier fires on a real driver. T611+T612+T613 / DESIGN-NOTES §14 | | **[guard]** | the PreToolUse hook → `.claude/hooks/guard.sh` | | **[permission allowlist]** | `.claude/settings.json` → `permissions.allow` | | **[environment block]** | "This environment's concrete forms" below (the single copy) | | **[comment marker]** | "The [comment marker] concrete form" below (the single copy) — appended to every engine-posted `gh issue comment` / `gh pr comment` body | **Profile read — packet first (spec 007 US3.AC3).** The workflow doc's "read the profile once at the start" resolves to **`.claude/PROJECT.compact.md`** by default — the compact packet of active routing facts (base branch, paths, conventions, required check, autonomy status, blocked list, review passes, critical invariants + backstops, the [edit guard] map), drift-checked against the full profile by `.claude/hooks/compact-packet-drift.sh` in CI `verify`. **Escalate to the full `.claude/PROJECT.md` explicitly** — say you are escalating and why — when a step needs a fact the packet deliberately omits (an invariant's full text or auditor rule, the maker-eval records path, architecture boundaries, constitution watch, coverage policy, autonomy rationale). The full profile stays the source of truth; the packet is the read optimization, never a second authority. **Task index — selection reads it first (spec 007 US5.AC3).** §1's "read the profile's **task index**" resolves to **`specs/TASK_INDEX.md`** — a generated digest of every backlog task's selection-critical fields (id, tier, checkbox state, owning acceptance-criterion refs, short title; the spec path is each section's heading), regenerated from `specs/*/tasks.md` by `python3 .claude/hooks/task-index.py --write` and staleness-checked (`--check`) in CI `verify`, so it can never silently rot. Read it to pick the candidate — ~3.5k tokens instead of every tasks file — then load only the **selected** task's full spec/tasks context (§2, the profile's tasks/spec paths). The §1 selection preconditions — `reconcile-task-selection.sh`, then `reconcile-inflight-selection.sh`, then `announce-task-selection.sh` — run **unchanged** on that candidate: the index changes the read surface, never the deterministic gates. If the index is absent or its `--check` is red (stale), fall back to reading `specs/*/tasks.md` directly and regenerate it. Plan note: usage may be account-wide (interactive + heartbeat + reviewers sharing one pool) — apply the methodology's "Model & usage economy" tiering as written. **The [comment marker] concrete form** — the single adapter-wide definition (other bindings reference it; the role's semantics live in `workflow/README.md` and the reading rules in `workflow/next-task.md` §2.5). Every engine-posted issue/PR comment body ends with this literal final line (write it into the temp `.md` before the `--body-file` call): ``` 🤖 harness comment — engine-authored, not owner steering ``` The line is exact and machine-checkable (P-CM greps for it verbatim) and plainly readable by a non-developer. **Recognition is anchored to the comment's final line ONLY**: a comment is marked iff its last non-empty line is exactly this string. The marker appearing anywhere else (e.g. quoted mid-body) neither marks the comment nor demotes an owner comment that embeds it. A comment not so marked, posted from the owner login, is owner steering per §2.5. When quoting an owner comment inside a marked comment, render the quoted text as a blockquote so it stays visibly distinct from the engine wrapper, and never append the footer to the quoted text itself. **This environment's concrete forms** (Windows PowerShell 5.1 + `gh`) — this section is the **[environment block]**: the ONE home for OS/shell/CLI gotchas. Other bindings (e.g. `/triage`) reference it; never copy these facts elsewhere. **Per-machine — rewrite on adoption:** the bullets below are the *Windows PowerShell 5.1* instantiation, shipped as a worked example. On macOS/Linux, replace them with your forms (e.g. heredocs are UTF-8 by default, so the `Out-File -Encoding utf8` rule becomes "write the temp `.md` with a plain heredoc"; `gh` falls back to `/opt/homebrew/bin/gh` or `/usr/local/bin/gh` instead of a `Program Files` path). A fully worked macOS/Linux translation to copy from is `docs/examples/environment-block-macos-linux.md` (illustrative, **not** a second live block). Keep this section the single [environment block] either way. - `gh` invocation — use it from PATH; in a headless run it may be absent, so fall back to the absolute install path (`C:\Program Files\GitHub CLI\gh.exe`). `gh repo set-default` is set to the fork locally, so a bare `gh` targets the right repo — no slug-derivation preamble needed in interactive sessions (re-run `set-default` after any re-clone/port). - Issue-tracker authentication precondition — run `gh auth status`; if it fails, ask the user to authenticate with `gh auth login` before tracker-dependent steps. - **Allowlist-shaped commands (autonomy):** the [permission allowlist] matches command *prefixes*, so issue tool calls as single plain commands (`git …`, `gh …`, `npm …`, `npx …`). A leading variable assignment (`$x = …;`), a bespoke polling loop, or an `&`-invoked absolute path can never match a prefix rule and WILL interrupt an unattended run with a prompt. To wait on CI, use `gh pr checks --watch` (allowlisted) instead of a hand-rolled loop. - §8 PR body — write the temp `.md` with `Out-File -Encoding utf8` (PS 5.1 defaults to UTF-16+BOM, which breaks `gh ... --body-file`), then `gh pr create --body-file `. - §8 verdict comments — write each reviewer's saved verdict report to its own temp `.md` (same `Out-File -Encoding utf8` rule), then `gh pr comment --body-file ` — one comment per dispatched reviewer, PASS results included. - §8 visual evidence — images cannot be uploaded to GitHub from the CLI (`gh` has no comment/body image-upload). Commit the evidence (small PNGs; short MP4/GIF for animation work) under `docs/visual-evidence//` on the task branch, push, then embed `https://raw.githubusercontent.com///` in the PR body (slug per the profile). **Pin to the full commit SHA, never the branch name** — branches auto-delete on squash-merge and the URL would die; PR head commits stay reachable. - §8 verify — `gh pr view --json number,url,state,mergeStateStatus,statusCheckRollup`. - §3 issue body — use a heredoc with `gh issue create`. - `/triage` inbox/run-log default (`triage.md` §4.3 / §1.5.3) — when neither the `inbox:` argument nor `TRIAGE_INBOX` is given, the portable default directory is `/.claude/triage/` (`` = `$HOME`; PS 5.1: `$env:USERPROFILE`), so the inbox is `/.claude/triage/-triage.md` and the run log sits beside it as `-heartbeat.log`. `` = last segment of `git rev-parse --show-toplevel`.