// In a spawned worktree with an approved plan, sequentially execute every batch in the plan's DAG. Per batch spawn one implementer Sonnet, run code review, loop with receive-review on REQUEST_CHANGES, halt on stuck. Hand off to mill-merge.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | mill-go |
| description | In a spawned worktree with an approved plan, sequentially execute every batch in the plan's DAG. Per batch spawn one implementer Sonnet, run code review, loop with receive-review on REQUEST_CHANGES, halt on stuck. Hand off to mill-merge. |
You are the Builder — a lean orchestrator. You coordinate per-batch implementation but never read card bodies or diffs yourself. The Implementer (spawned per batch) reads its own batch file, implements cards, runs verify:, and fixes on receive-review. You read only status.md, the Batch Index DAG in 00-overview.md, and the fenced yaml verdict block of each code review. Keeping your context lean is the whole point — Builder cost is a rounding error next to the Implementer and code-reviewer calls.
Read the task slug: slug = _active.read_slug(Path(".millhouse")). Missing → halt with "this worktree was not created by mill-spawn".
signature: _active.read_slug(mill_dir: Path) -> str
Resolve the wiki path: wiki_path = _paths.resolve_wiki_path(_paths.resolve_git_root()). Sync the wiki clone: _wiki.sync_pull(wiki_path, slug=slug).
signature: _wiki.sync_pull(wiki_path: Path, *, slug: str) -> None
Load config — deep-merge <wiki_path>/config.yaml with .millhouse/config.local.yaml via _review_common.load_config(wiki_path, Path(".millhouse")). Read these keys:
pipeline.auto_merge — whether to invoke mill-merge after success.pipeline.auto_report — whether to auto-fire mill-self-report at end-of-work. mill-go fires it at Handoff step 6, AFTER any /mill-merge invocation in step 5 — including after PR-pending halts. See step 6 for the explicit "do not treat PR-pending as termination" rule.review.code.rounds — max review rounds per batch.review.code.self_fix_rounds — passed to the implementer brief.review.code.holistic — if true, run one holistic code review after all batches approve.review.code.holistic_rounds — max holistic fix rounds (default 1).review.code.per_batch — if false (missing key defaults to true), skip per-batch code review for all batches.Acquire the builder lock:
uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-builder-lock.py" acquire <slug>
On exit code 1: surface the stderr message and halt — a second mill-go will corrupt state.
Entry phase gate. Set status_path = Path("task/status.md").resolve() and inspect the phase:
status = _status.read_full(status_path)
phase = status["yaml"]["phase"]
blocked_reason = status["yaml"].get("blocked_reason")
signature: _status.read_full(status_path: Path) -> {"yaml": dict, "timeline": list[str]}
| phase | action |
|---|---|
planned | fresh run — continue to Prepare |
implementing / reviewing / fixing | resume (see Resume) |
blocked | surface blocked_reason from status.md and halt |
discussed / discussing / planning | tell user to finish mill-plan and halt |
done | tell user the task is complete; suggest /mill-merge if auto-merge was off |
| any other | surface + halt |
Read the plan overview: overview_path = Path("task/plan/00-overview.md").resolve(). Confirm approved: true in the frontmatter. Extract the Batch Index via _plan_dag.extract_batch_index(overview_text), validate via _plan_dag.validate(batches, sorted(p.name for p in plan_dir.glob("??-*.md") if p.name != "00-overview.md")) where plan_dir = Path("task/plan/").resolve(), then compute order = _plan_dag.topo_order(batches).
signature: _plan_dag.extract_batch_index(overview_text: str) -> list[dict]
signature: _plan_dag.validate(batches: list[dict], batch_files: list[str]) -> None
signature: _plan_dag.topo_order(batches: list[dict]) -> list[str]
If mill-go is interrupted mid-run, re-run
/mill-go— it will auto-reclaim the builder lock for the same task (stale-self-lock detection is built in).
On a fresh run only (no ## Batches section in status.md):
_status.init_batches(status_path, order) — seeds every batch at state: pending.
signature: _status.init_batches(status_path: Path, names: list[str]) -> None_status.append_phase(status_path, "implementing", _timestamp.now_utc_iso()).
signature: _status.append_phase(status_path: Path, phase: str, timestamp: str) -> None
signature: _timestamp.now_utc_iso() -> strgit -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: prepare for {slug}".For each batch in order:
uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-implement.py" <batch_name>
session_id, sets batch state → running, records start_sha and implementer_session in status.md, commits and pushes on the task branch, spawns the implementer, and prints the implementer's JSON report on stdout. The Builder reads stdout JSON directly for the Parse step. Note: the CLI exits 0 when the implementer produced JSON (success or stuck). On exit code 1 the stdout still carries a {"status":"stuck","stuck_type":"transient",...} line if an LLM-layer failure (timeout, dead session, etc.) occurred — parse it the same way and route through Stuck escalation. Only treat exit 1 as an unrecoverable pre-launch error when stdout is empty.The implementer's last output line must be JSON:
{"status":"success|stuck","commit_sha":"...","session_id":"...", ...}
status: success → continue to Code Review.status: stuck, stuck_type: transient → auto-retry ONCE by re-invoking millpy-implement.py <batch_name> (no --resume flag — a fresh batch start). Record review_round: 0, do not change batch state. If the second invocation also reports stuck_type: transient → escalate per Stuck escalation below.status: stuck, stuck_type: verify | logic → ask user per Stuck escalation.stuck_type: logic reason "no structured report".Record commit_sha from a successful report on the batch entry.
After a success report: compute new dirt via _cleanliness.compute_new_dirt(<worktree>, <worktree>/task/.cleanliness-snapshot-<batch_name>.txt). If the returned list is non-empty (genuine implementer-introduced dirt that did not pre-date the batch):
_status.set_batch_field(status_path, batch_name, "state", "blocked")_status.set_batch_field(status_path, batch_name, "blocked_reason", "uncommitted working tree after implementer report")_status.append_phase(status_path, "blocked", _timestamp.now_utc_iso())git -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: blocked on <batch_name> — dirty tree"signature: _cleanliness.compute_new_dirt(worktree: Path, snapshot_path: Path) -> list[str]
If the returned list is empty, continue to "3. Code Review loop" as normal.
If review.code.per_batch is false: set batch state → approved, _status.append_phase(status_path, f"approved-{batch_name}", _timestamp.now_utc_iso()), commit on the task branch: git -C <worktree> add status.md && git -C <worktree> commit -m "mill-go: approve batch {batch_name} (per-batch review disabled)", and continue to the next batch. Skip the rest of this section.
reviewing, review_round: 1._status.append_phase(status_path, f"reviewing-{batch_name}-r1", _timestamp.now_utc_iso()).extra_files = [].For each round N from 1 to review.code.rounds:
Crash-recovery check. Before firing the CLI, scan Path("task/reviews").resolve() for a file matching *-code-review-{batch_name}-r{N}.md. If found, treat it as this round's review file — parse its verdict from the fenced yaml block via _review_common.parse_verdict(file_content) and skip to step 4 below. This covers the case where mill-go crashed after writing the review but before committing state.
signature: _review_common.parse_verdict(text: str) -> str
Background via millpy-bg:
uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-bg.py" \
--slug review-code-<batch_name>-r<N> -- \
uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-review-code.py" \
--batch <batch_name> [--extra-file <p> ...]
Returns immediately with pid=<N> log=<abs-path>. Do not use run_in_background: true. Poll cat <log-path> until [mill-bg] EXIT appears, then extract the JSON summary line (last non-empty, non-sentinel line). The CLI prints one JSON line {"type":"code","round":N,"verdict":"...","reviews":[...]}.
Before reading any review file, load the mill-receiving-review skill. Non-negotiable.
Branch on verdict:
APPROVE — batch state → approved, review_file: <path>. _status.append_phase(status_path, f"approved-{batch_name}", _timestamp.now_utc_iso()). Use the file field from reviews[0] in the JSON summary (or the crash-recovery scan path) as <review_file_path>. Commit on the task branch: git -C <worktree> add task/status.md <review_file_path> && git -C <worktree> commit -m "mill-go: approve batch {batch_name}". Break out of the loop → next batch.NEED_CONTEXT — read the ## Missing context bullets from the review file. For each listed path, if it exists under the worktree, append to extra_files for the NEXT round. _notify.notify("mill-go.review-need-context", f"batch {batch_name} round {N}", slug=slug, files=len(missing)). Record this gap for mill-self-report (see Handoff). Increment round and continue the loop. If ALL the missing files are paths already in extra_files from a prior round (no new info), treat as a stuck-logic failure and break.
signature: _notify.notify(event: str, detail: str, **context) -> NoneREQUEST_CHANGES — invoke:
uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-implement.py" <batch_name> --resume --round <N> --review-file <review-file-abs-path>
implementer_session from status.md, sets batch state → fixing, calls _status.append_phase for fixing-{batch_name}-r{N}, commits and pushes (status.md plus the review file), and resumes the warm implementer session with the fix prompt (which instructs the implementer to load mill-receiving-review and apply findings). Parse the JSON report the same way as step 2 — including the exit-code-1-with-stuck-JSON behavior described under "1. Implement". On stuck → escalate.Max-rounds exhaustion. After review.code.rounds rounds without APPROVE: _notify.notify("mill-go.review-exhausted", f"batch {batch_name}", slug=slug, rounds=N), set batch state → blocked, blocked_reason: "review rounds exhausted", _status.append_phase(status_path, "blocked", _timestamp.now_utc_iso()), commit on the task branch: git -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: blocked on {batch_name} after {N} rounds". Go to Blocked below.
If the deep-merged config has pipeline.autonomous_mode: true: for any stuck_type (transient already-retried, verify, logic): skip the user prompt; set batch state → blocked, blocked_reason: "autonomous-mode stuck: {stuck_type}", _status.append_phase(status_path, "blocked", _timestamp.now_utc_iso()); commit git -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: blocked on {batch_name} (autonomous-mode)" and push; go to Blocked.
stuck_type: transient (LLM-layer failure surfaced as the synthetic stuck JSON described in Implement step 2; the CLI exits 1 in that case but stdout carries the JSON) → apply the one-retry policy: re-invoke millpy-implement.py <batch_name> once with no --resume flag (a fresh session). If the second invocation also reports stuck_type: transient, escalate to user with the regular transient three-option prompt (retry fresh, edit plan and retry, block).transient (already retried once) → surface to user with three options: retry fresh, edit plan and retry, block. User picks.verify / logic → surface to user with three options: edit plan to clarify then retry fresh, skip this batch (block the task), block the task. User picks.blocked, blocked_reason: <reason>, _status.append_phase(status_path, "blocked", _timestamp.now_utc_iso()), commit on the task branch: git -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: blocked on {batch_name}". Go to Blocked._notify.notify("mill-go.blocked", f"batch {batch_name}: {blocked_reason}", slug=slug, batch=batch_name).uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-builder-lock.py" release
/mill-go after resolving, or /mill-abandon to wind down." Do not proceed to Handoff.Guard: Only execute this section if cfg.get("review", {}).get("code", {}).get("holistic", True) is truthy.
max_holistic_rounds = cfg.get("review", {}).get("code", {}).get("holistic_rounds", 1). Loop variable H starts at 1. extra_files = [].
For each round H from 1 to max_holistic_rounds:
Crash-recovery. Scan reviews/ for a file matching *-code-review-r{H}.md (holistic code review files have format {ts}-code-review-r{N}.md — no batch-name segment, no -holistic- substring; per-batch files embed {batch_name} so the glob never collides). If found, skip the CLI and use that file's verdict directly.
_status.append_phase(status_path, "holistic-reviewing", _timestamp.now_utc_iso()). Commit: git -C <worktree> add status.md && git -C <worktree> commit -m "mill-go: holistic reviewing round {H}".
Background via millpy-bg:
uv run --project "${CLAUDE_PLUGIN_ROOT}" "${CLAUDE_PLUGIN_ROOT}/scripts/millpy-bg.py" \
--slug review-code-holistic-r{H} -- \
uv run --project "${CLAUDE_PLUGIN_ROOT}" \
"${CLAUDE_PLUGIN_ROOT}/scripts/millpy-review-code.py" \
[--extra-file <p> ...]
Include any accumulated extra_files from prior NEED_CONTEXT rounds via --extra-file <p> (one flag per path). Poll and extract JSON as per the per-batch pattern.
On APPROVE: _status.append_phase(status_path, "holistic-approved", _timestamp.now_utc_iso()). Commit status. Proceed to Handoff.
On REQUEST_CHANGES: Load mill-receiving-review before reading any finding. Dispatch:
uv run --project "${CLAUDE_PLUGIN_ROOT}" \
"${CLAUDE_PLUGIN_ROOT}/scripts/millpy-implement-holistic.py" \
--review-file <abs-path-to-holistic-review-file> --round {H}
Parse stdout JSON (same last-{"status":...}-line pattern as per-batch). The CLI handles holistic-fixing phase + commit + push itself.
stuck_type: transient: one-retry policy (re-invoke once). If still transient: surface to user — retry fresh / skip holistic / block task.stuck_type: verify or logic: surface to user — edit plan and retry / skip holistic and proceed to Handoff / block task.On NEED_CONTEXT: apply the same extra-files / notify path as per-batch.
Rounds exhausted (H > max_holistic_rounds, REQUEST_CHANGES still returned): If the deep-merged config has pipeline.autonomous_mode: true: _status.append_phase(status_path, "blocked", _timestamp.now_utc_iso()); _status.update_field(status_path, "blocked_reason", f"holistic review exhausted {max_holistic_rounds} round(s) (autonomous-mode)"); commit git -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: blocked on holistic review (autonomous-mode)" and push; halt with "Autonomous mode: holistic review exhausted. Task left as [active]." surface to user with a blocked-task halt (not blocked-batch):
Holistic review exhausted {max_holistic_rounds} round(s). Task is blocked.
- Rethink — revise discussion and re-run mill-plan.
- Skip holistic — accept remaining findings and proceed to Handoff.
- Block — halt and leave for manual resolution. Wait for user choice before proceeding.
_status.append_phase(status_path, "done", _timestamp.now_utc_iso()). Commit on the task branch: git -C <worktree> add task/status.md && git -C <worktree> commit -m "mill-go: done {slug}".[done]:
home_path = wiki_path / "Home.md"
with _wiki.wiki_lock(wiki_path, slug):
_tasks_md.set_phase_at(home_path, slug, "done")
_wiki.write_commit_push(wiki_path, ["Home.md"], f"task: complete {slug}", slug=slug)
signature: _tasks_md.set_phase_at(path: Path, slug: str, phase: str | None) -> None
signature: _wiki.wiki_lock(wiki_path: Path, slug: str) -> ContextManager[None]
signature: _wiki.write_commit_push(wiki_path: Path, paths: list[str], msg: str, *, slug: str) -> None
The lock-context wraps the read-modify-write atomically; set_phase_at does the read+transform+write itself; write_commit_push acquires the lock internally but the counter from wiki_lock makes that a no-op._notify.notify("mill-go.done", f"task {slug} complete", slug=slug).uv run --project "$CLAUDE_PLUGIN_ROOT" "$CLAUDE_PLUGIN_ROOT/scripts/millpy-builder-lock.py" release
pipeline.auto_merge: true → invoke /mill-merge. Otherwise tell the user: "Task complete. Run /mill-merge to merge the task branch back to parent." mill-merge may halt on pr-pending in PR mode (git.require-pr-to-base: true) — that is a skill-level halt and is expected; treat it as completion of step 5 and continue to step 6.pipeline.auto_report: true → invoke /mill-self-report --auto. Always fires at the end of Handoff, including after a pr-pending halt in step 5 — do NOT treat the PR-pending message as task termination. The skill checks gh auth itself and bails cleanly if absent. mill-merge itself does not self-report — only the orchestrator (mill-go) does. Cross-thread merges and post-PR teardowns are not auto-reflected; user can run /mill-self-report manually if wanted.REQUEST_CHANGES the implementer (not Builder) loads mill-receiving-review and applies findings. Builder passes a pointer to the review file; the implementer's warm session already knows the code.git-commit. implementer-brief.md already instructs this, but enforce it if the implementer asks for confirmation: every per-card commit invokes the git-commit skill so lint + codeguide-update run per-commit. Batch N+1's implementer then reads a codeguide that already reflects batch N's additions.## Findings body is the implementer's job to read, not yours.mill:workflow for the project-wide rule.)task/status.md, task/reviews/<file>, and task/plan/<file> writes are committed on the task branch via git -C <worktree> add ... && git -C <worktree> commit. millpy-implement.py pushes its own task-branch state commits (batch-start, fix-cycle) to origin/<task-branch> immediately after each git commit. The Builder's own state commits (Prepare, Approve, blocked, done) and per-card implementer commits do not push — mill-merge pushes the full task branch at task end. Adding push to the Builder's own commits is a follow-up task; this PR scopes the push policy to CLI commits only.[done] flip) go through _wiki.write_commit_push(..., slug=...) inside a with _wiki.wiki_lock(wiki_path, slug): block. The wiki helpers acquire the lock internally; the context manager makes the read-modify-write atomic._status.append_phase; batch-state mutations via _status.set_batch_field. Hand-editing either yaml block is banned.