Iterative Fleet

Iterative Fleet

A skill for reviewer-gated iterative loops of parallel claude -p, codex exec, or pi -p workers. Workers run per-iteration, a reviewer reads their output and writes a verdict, and a generated orchestrator decides whether to continue or stop — without ever killing or restarting workers. Supports Claude, Codex, and Pi providers — set per-fleet or per-worker. See dag-fleet SKILL.md for full provider documentation (model aliases, reasoning_effort, limitations).

When to use this skill

Reach for iterative-fleet when:

• The work needs multiple rounds of refinement (not one-shot)
• A reviewer/verifier must approve output before the work is done
• You want operator-declared stop conditions (max iterations, LGTM count, cost cap)
• Workers are long-running or have high bootstrap costs (no auto-restart — see CRITICAL section)

Use dag-fleet instead when:

• Workers run once and are done (no iteration needed)
• There is no reviewer quality gate

Use worktree-fleet instead when:

• Tasks are fully independent with no shared state

CRITICAL: No auto-kill, no auto-restart

The orchestrator generated by this skill reads and decides only. It NEVER kills or restarts workers. Workers run to natural completion per iteration. This design comes from a $20 death spiral in experiment 001 where auto-restart on "stuck" workers caused cache rebuilds that cost more than the actual work. The reviewer is the quality gate. The operator is the kill switch.

fleet.json schema

{
  "fleet_name": "my-iterative-fleet",
  "type": "iterative",
  "config": {
    "max_concurrent": 3,
    "model": "sonnet",
    "fallback_model": "haiku",
    "max_iterations": 10,
    "cost_cap_usd": 10.0
  },
  "workers": [
    { "id": "builder-a", "type": "code-run", "task": "...", "max_budget_per_iter": 1.0 },
    { "id": "builder-b", "type": "code-run", "task": "...", "max_budget_per_iter": 1.0 },
    { "id": "reviewer",  "type": "reviewer", "task": "Review output, write verdict: lgtm | iterate | escalate",
      "depends_on": ["builder-a", "builder-b"] }
  ],
  "stop_when": {
    "reviewer_lgtm_count": 3,
    "max_iterations": 10,
    "cost_cap_usd": 10.0
  }
}

DAG ordering via depends_on

Each iteration is a DAG. Workers declare dependencies with depends_on:

{ "id": "reviewer", "type": "reviewer", "depends_on": ["builder-a", "builder-b"] }

At launch, only layer-0 workers (no deps) are spawned. The orchestrator spawns subsequent layers after their dependencies complete, then repeats the DAG on the next iteration.

iteration 1:  [builder-a, builder-b] → [reviewer] → verdict: iterate
iteration 2:  [builder-a, builder-b] → [reviewer] → verdict: lgtm → stop

Multi-layer DAGs work too (e.g., researcher → builder → reviewer = 3 layers). The shared lib/dag.sh provides topo-sort and dependency checking, reusable across all fleet types.

If no worker has depends_on, all workers launch in parallel (backward compatible).

Iteration directory structure

$FLEET_ROOT/
  fleet.json
  iterations/
    1/
      builder-a.log
      builder-b.log
      review.md          # reviewer writes verdict here
    2/
      ...
  workers/
    builder-a/
      prompt.md
      session.jsonl
    ...
  orchestrator.sh        # generated — reads logs, decides iterate/pause/stop
  .paused                # exists when paused (touch to pause, rm to resume)

Reviewer interface

The reviewer worker reads iterations/<N>/*.log and writes iterations/<N>/review.md. The review.md MUST contain one of:

• verdict: lgtm — output is approved, count toward stop condition
• verdict: iterate — needs another round
• verdict: escalate — needs human attention, orchestrator pauses

Reviewer prompt requirements

Every reviewer prompt.md MUST include these instructions verbatim (with paths adjusted). Without them, the reviewer won't know where to write the verdict and the orchestrator defaults to iterate, wasting an iteration.

## Writing your verdict

1. Determine the current iteration number: list the `iterations/` directory and find the
   highest-numbered subdirectory that does NOT yet contain a `review.md`.
2. Write your verdict to `iterations/<N>/review.md` (relative to your working directory).
   **Never use absolute paths.**
3. The file MUST contain a line exactly like one of:
   - `verdict: lgtm`
   - `verdict: iterate`
   - `verdict: escalate`
4. Below the verdict line, list **actionable fix instructions** per worker — not just what's
   wrong, but exactly where and how to fix it (file path, function name, what to change).
   The builder sees this feedback on the next iteration, so vague issues waste a cycle.

Example `iterations/1/review.md`:

verdict: iterate

builder-a

1. src/parser.py:parse_input() — no try/except around JSON decode. Wrap lines 45-48 in try/except json.JSONDecodeError, return None on failure.
2. src/parser.py:validate_schema() — missing required field "timestamp" in schema dict at line 72. Add "timestamp": {"type": "string", "required": True}.

builder-b

1. src/utils.py — format_output() defined but not in __all__ or exported in __init__.py. Add to src/__init__.py line 5: from .utils import format_output.

Available scripts

Launch procedure

1. Create $FLEET_ROOT/fleet.json with workers including exactly one type: "reviewer" worker (with depends_on pointing to builder workers)
2. Create $FLEET_ROOT/workers/<id>/prompt.md for each worker
3. Run bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh $FLEET_ROOT
4. ALWAYS tell the user the exact status command so they can monitor manually:

   bash ${AGENTS_SKILLS_DIR}/scripts/status.sh $FLEET_ROOT
   

   This is mandatory after every launch. The user must be able to check status without asking you.
5. Pause if needed: bash ${AGENTS_SKILLS_DIR}/scripts/pause.sh $FLEET_ROOT
6. Hard stop: bash ${AGENTS_SKILLS_DIR}/scripts/kill.sh $FLEET_ROOT all

Rationalizations to reject

Decision tree: which fleet?

1. Tasks independent (no shared files/state)?  YES → worktree-fleet
2. Need iteration with reviewer quality gate?  YES → iterative-fleet (this skill)
3. One-shot DAG with dependencies?             YES → dag-fleet
4. None of the above?                          → open multiple Claude Code sessions

$ARGUMENTS