loop-go

Loop Go

Loop-dispatch builder to write/fix code, checker to run checks, until all green or a stop rule is hit.

Prerequisites

builder and checker are defined by /setup-claude-code(Claude Code) or /setup-pi(pi). If not loaded, stop and prompt to switch back to the main branch and rerun the corresponding setup.

.claude/ is not in git—the worktree won't carry builder/checker. Go back to the main working directory and run /setup-claude-code, the worktree shares the main repository's .claude/agents/。

Steps

0. Align on the goal

Write the task as a brief: goal, files involved, completion criteria. If no completion criteria are written, ask first. The same brief runs through all rounds.

1. Dispatch builder

Use the Task tool,subagent_type: "builder", the prompt contains only the brief and this round's task. Wait for builder to finish and get the list of changed files before continuing.

2. Dispatch checker

Use the Task tool,subagent_type: "checker", the prompt contains the same brief. Wait for checker to finish and get the check result report before continuing.

If it reports failure but with no details, have checker rerun and output the real error lines.

3. Decide

• All green: show the diff and check results.
• Failure: hand checker's full report to builder, go back to step 1. The original error is builder's only clue for locating the root cause.
• Checker can't find the check command: stop and ask the user for the check command the project actually uses.
• Checker times out or output can't be parsed: terminate per stop rule 6.

Rounds

Declare at the start of each round Cycle N/5. At most 5 rounds.

Stop immediately if any of the following occurs:

1. All green
2. The same failure appears two rounds in a row (builder is guessing, not fixing)
3. A fix introduces a regression—a previously passing check fails (robbing Peter to pay Paul)
4. Still not all green by round 5—show the last round's changes and failing items
5. Builder violates a red line: weakening tests, deleting/commenting out/skipping failing checks, claiming a fix without running checks
6. Checker can't produce a valid report: can't find the check command, output can't be parsed, consecutive timeouts

Repository CLAUDE.md or AGENTS.md if there is a ## Loop 停止规则 section written by setup, the repository version takes precedence.

Pause when the user inserts new instructions during the loop, then decide whether to continue after handling them. If the task scope expands during the loop, stop and ask the user.

pi adaptation (the pi harness has no built-in Task tool)

pi doesn't have Claude Code's Task/subagent tool, use the official subagent extension instead (each subagent is an independent pi process, with isolated context).

Prerequisites (one-time):

1. Install the subagent extension: symlink the official example examples/extensions/subagent/ 's index.ts、agents.ts to ~/.pi/agent/extensions/subagent/。
2. Confirm there is a user-level ~/.pi/agent/agents/ under builder.md、checker.md(pi version agent, tools use pi's lowercase tool names; don't lock the model, use pi's default model).

The above is installed uniformly by /setup-pi ; if any item is missing, prompt to run /setup-pifirst. Dispatch under pi:

• Step 1 (dispatch builder): subagent tool single mode,agent: "builder", task contains the brief and this round's task.
• Step 2 (dispatch checker): subagent tool in single mode,agent: "checker", put the same brief in task.
• Step 3 (decision) is unchanged—the checker's final output is the report; on failure, put the full report into the next round's builder task.

Project-level override:.pi/agents/builder.md、.pi/agents/checker.md overrides the user level, requires agentScope: "both" and confirmation..pi/agents/ and .claude/agents/ are each maintained independently.