agent-orchestration

Orchestrate work too large for one straight pass to done. Both patterns below share one concern, bounded units that converge to a green gate. Never run unbounded and unreported. No two agents may race the same file.

• The loop: drive to done one bounded iteration at a time, in sequence. Depth work fits here, since each slice builds on the last and done is a backlog of gate-decidable criteria.
• Fan-out: decompose into independent owned-file units and run them through parallel subagents. Choose it for breadth, where the units are independent and the work cuts so no two agents write the same file.

The patterns compose, so a loop slice with independent sub-parts fans out. Pick the pattern, then follow its steps.

The loop: drive to done iteratively

Pick the mode before the first iteration. Checkpointed (default, safe) means a human approves at each phase boundary, which suits high-stakes or judgment-heavy work. Autonomous (ralph-style) runs one stable prompt that re-reads the state file and advances the backlog unattended under the full guardrail set; a large mechanical gate-decidable backlog earns it. Autonomous is safe only where a gate, with no human reading the diff, could decide each backlog item correctly. Under any doubt, run checkpointed.

1. Define done as acceptance criteria. Write done as a numbered backlog. Each item is observable and binary, and a gate can decide it. Record the chosen mode on the same page. This step ends once every backlog item is checkable, the list as a whole means the codebase is finished, and the mode is recorded. See the loop protocol.

2. Seed the resumable state. Write the backlog and counters into a committed handoff/state.json tied to handoff: open items, done items, iteration count, spend, and the consecutive-stall count. Autonomous mode also needs its four bounds set now, an iteration cap N, a cost/time budget, a stall limit K, and the named gate command. This step ends once a cold reader could reconstruct the loop position from the file alone.

3. Open the iteration and plan one slice. Read handoff/state.json fresh, then cut the smallest slice that moves one open criterion measurably (a thin vertical cut expressible as a single failing test). Autonomous checks the four halt conditions before any work starts. Checkpointed reports the slice goal and its target criterion, states the expected diff size, then pauses for approval. This step ends once one slice names its target criterion and the mode's precondition clears.

4. Build the slice test-first, then gate it. Follow tdd: write a failing test for the slice's behavior, then the minimum code that turns it green. No destructive or external mutation runs without recorded approval. To fan one slice across independent owned-file units, use the fan-out pattern below. Then run skill-gate --strict. A red gate holds the slice open: the changed files go back to their pre-iteration state and the stall count goes up. A green gate moves the criterion to done and resets the stall count. This step ends once skill-gate --strict exits zero, or the failed slice's edits are reverted.