Back to Details

iterative-fleet

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Iterative Fleet

迭代式Fleet

A skill for reviewer-gated iterative loops of parallel 
claude -p
or 
codex exec
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 both Claude and Codex providers — set per-fleet or per-worker. See dag-fleet SKILL.md for full codex provider documentation (model aliases, reasoning_effort, limitations).
这是一项用于由审核者把关的
claude -p
或
codex exec
并行工作节点迭代循环的Skill。工作节点按迭代周期运行，审核者读取其输出并写下裁决结果，生成的编排器决定是继续还是停止——但绝不会终止或重启工作节点。支持Claude和Codex两种提供商——可按Fleet或单个工作节点设置。完整的Codex提供商文档（模型别名、reasoning_effort、限制）请查看dag-fleet的SKILL.md。

When to use this skill

何时使用该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
在以下场景选择iterative-fleet：
  • 工作需要多轮优化（而非一次性完成）
  • 审核者/验证者必须在工作完成前批准输出
  • 你需要操作员声明的停止条件（最大迭代次数、LGTM次数、成本上限）
  • 工作节点运行时间长或启动成本高（无自动重启——详见CRITICAL部分）
在以下场景选择dag-fleet：
  • 工作节点运行一次即完成（无需迭代）
  • 没有审核者质量关卡
在以下场景选择worktree-fleet：
  • 任务完全独立，无共享状态

CRITICAL: No auto-kill, no auto-restart

CRITICAL：无自动终止，无自动重启

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.
本Skill生成的编排器仅负责读取和决策。它绝不会终止或重启工作节点。工作节点会在每次迭代中自然运行至完成。这种设计源于实验001中一次20美元的“死亡螺旋”——当时对“卡住”的工作节点进行自动重启导致缓存重建，成本远超实际工作。审核者是质量关卡，操作员是终止开关。

fleet.json schema

fleet.json schema

json
{
  "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
  }
}
json
{
  "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

基于
depends_on
的DAG排序

Each iteration is a DAG. Workers declare dependencies with 
depends_on
:
json
{ "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).
每次迭代都是一个DAG。工作节点通过
depends_on
声明依赖关系：
json
{ "id": "reviewer", "type": "reviewer", "depends_on": ["builder-a", "builder-b"] }
启动时，仅会生成无依赖的0层工作节点。编排器会在依赖节点完成后生成后续层的节点，然后在下一次迭代中重复该DAG。
iteration 1:  [builder-a, builder-b] → [reviewer] → verdict: iterate
iteration 2:  [builder-a, builder-b] → [reviewer] → verdict: lgtm → stop
多层DAG同样适用（例如：researcher → builder → reviewer = 3层）。共享的
lib/dag.sh
提供拓扑排序和依赖检查功能，可在所有Fleet类型中复用。
如果没有工作节点设置
depends_on
，则所有工作节点会并行启动（向后兼容）。

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)
$FLEET_ROOT/
  fleet.json
  iterations/
    1/
      builder-a.log
      builder-b.log
      review.md          # 审核者在此处写下裁决结果
    2/
      ...
  workers/
    builder-a/
      prompt.md
      session.jsonl
    ...
  orchestrator.sh        # 生成的脚本——读取日志，决定迭代/暂停/停止
  .paused                # 暂停时存在（创建该文件以暂停，删除以恢复）

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
审核者工作节点读取
iterations/<N>/*.log
并写入
iterations/<N>/review.md
。review.md必须包含以下内容之一：
  • verdict: lgtm
    — 输出已获批准，计入停止条件
  • verdict: iterate
    — 需要进行下一轮迭代
  • verdict: escalate
    — 需要人工干预，编排器将暂停

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.
undefined
每个审核者的prompt.md必须逐字包含以下说明（路径需调整）。如果没有这些说明，审核者将不知道在哪里写入裁决结果，编排器会默认选择
iterate
，浪费一次迭代。
undefined

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
  1. 确定当前迭代次数：列出
    iterations/
    目录，找到尚未包含
    review.md
    的编号最大的子目录。
  2. 将裁决结果写入
    iterations/<N>/review.md
    （相对于你的工作目录）。 切勿使用绝对路径。
  3. 文件中必须包含且仅包含以下一行内容： 
    • verdict: lgtm
    • verdict: iterate
    • verdict: escalate
  4. 在裁决行下方，列出每个工作节点的可操作修复说明——不仅要指出问题所在，还要明确说明修复的位置和方法（文件路径、函数名称、修改内容）。 构建者会在下一次迭代中看到这些反馈，模糊的问题会浪费一个周期。
示例
iterations/1/review.md
:
verdict: iterate

builder-a

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}
    .
  1. src/parser.py:parse_input()
    — JSON解码周围没有try/except语句。将第45-48行 包裹在try/except json.JSONDecodeError中，失败时返回None。
  2. src/parser.py:validate_schema()
    — 第72行的schema字典中缺少必填字段"timestamp"。 添加
    "timestamp": {"type": "string", "required": True}
    。

builder-b

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
    .
undefined
  1. src/utils.py
    — 
    format_output()
    已定义但未加入
    __all__
    或在
    __init__.py
    中导出。 在
    src/__init__.py
    第5行添加：
    from .utils import format_output
    。
undefined

Available scripts

可用脚本

ScriptPurpose
launch.sh <fleet-root> [--dry-run]
Parse fleet.json, generate orchestrator.sh, spawn workers + orchestrator in tmux
status.sh <fleet-root>
Show iteration count, reviewer verdict history, per-worker status, cost
pause.sh <fleet-root>
Touch 
.paused
— orchestrator stops at next iteration boundary
resume.sh <fleet-root>
Remove 
.paused
— orchestrator continues
kill.sh <fleet-root> all [--force]
Hard stop: kill tmux session, sweep orphans, unregister
脚本用途
launch.sh <fleet-root> [--dry-run]
解析fleet.json，生成orchestrator.sh，在tmux中启动工作节点和编排器
status.sh <fleet-root>
显示迭代次数、审核者裁决历史、各工作节点状态、成本
pause.sh <fleet-root>
创建
.paused
文件——编排器将在下一次迭代边界处停止
resume.sh <fleet-root>
删除
.paused
文件——编排器继续运行
kill.sh <fleet-root> all [--force]
强制停止：终止tmux会话，清理孤儿进程，注销Fleet

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 ${CLAUDE_SKILL_DIR}/scripts/launch.sh $FLEET_ROOT
  4. ALWAYS tell the user the exact status command so they can monitor manually: 
    bash ${CLAUDE_SKILL_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 ${CLAUDE_SKILL_DIR}/scripts/pause.sh $FLEET_ROOT
  6. Hard stop: 
    bash ${CLAUDE_SKILL_DIR}/scripts/kill.sh $FLEET_ROOT all
  1. 创建
    $FLEET_ROOT/fleet.json
    ，其中需包含且仅包含一个
    type: "reviewer"
    的工作节点（
    depends_on
    指向构建工作节点）
  2. 为每个工作节点创建
    $FLEET_ROOT/workers/<id>/prompt.md
  3. 运行
    bash ${CLAUDE_SKILL_DIR}/scripts/launch.sh $FLEET_ROOT
  4. 务必告知用户确切的状态查询命令，以便他们手动监控： 
    bash ${CLAUDE_SKILL_DIR}/scripts/status.sh $FLEET_ROOT
    每次启动后都必须执行此操作。用户必须能够无需询问即可检查状态。
  5. 如需暂停：
    bash ${CLAUDE_SKILL_DIR}/scripts/pause.sh $FLEET_ROOT
  6. 强制停止：
    bash ${CLAUDE_SKILL_DIR}/scripts/kill.sh $FLEET_ROOT all

Rationalizations to reject

需拒绝的错误理由

Agent saysRebuttal
"The worker has been running for 10 minutes with no output — it must be stuck, I should pause it"Long thinking blocks look like silence. The orchestrator waits for 
result
events, not timeouts. This is exactly the failure mode that caused the $20 death spiral in experiment 001. Do not intervene.
"The reviewer said 'looks mostly good' — I'll count that as LGTM"Only 
verdict: lgtm
counts. "Mostly good" is 
iterate
. If the reviewer is ambiguous, the verdict is 
iterate
. Do not interpret generously.
"I should kill this worker and restart it with a better prompt"The orchestrator NEVER kills workers. Workers run to natural completion. If you need a different prompt, pause the fleet, edit prompt.md, and let the next iteration pick it up.
"The cost is getting high — I'll reduce max_iterations mid-run"Stop conditions are baked into orchestrator.sh at generation time. To change them, kill the fleet, regenerate with new fleet.json, and relaunch. Do not edit orchestrator.sh directly.
"I can skip the reviewer for this simple task"If the task doesn't need a reviewer, use dag-fleet (one-shot) or worktree-fleet (independent). Iterative-fleet without a reviewer is a runaway loop.
Agent表述反驳理由
"该工作节点已运行10分钟无输出——肯定卡住了，我应该暂停它"长时间思考阶段看起来像是无输出。编排器等待的是
result
事件，而非超时。这正是实验001中导致20美元死亡螺旋的失败模式。请勿干预。
"审核者说'看起来大体不错'——我算它是LGTM"只有
verdict: lgtm
才算数。“大体不错”属于
iterate
。如果审核者表述模糊，裁决结果默认是
iterate
。请勿宽松解读。
"我应该终止这个工作节点，用更好的提示词重启它"编排器绝不会终止工作节点。工作节点会自然运行至完成。如果需要更换提示词，请暂停Fleet，编辑prompt.md，让下一次迭代自动获取新提示词。
"成本越来越高——我要在运行中减少max_iterations"停止条件在生成orchestrator.sh时已固化。如需更改，请终止Fleet，使用新的fleet.json重新生成并重启。请勿直接编辑orchestrator.sh。
"这个简单任务可以跳过审核者"如果任务不需要审核者，请使用dag-fleet（一次性）或worktree-fleet（独立任务）。没有审核者的iterative-fleet会陷入失控循环。

Decision tree: which fleet?

决策树：选择哪种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
1. 任务是否独立（无共享文件/状态）？  是 → worktree-fleet
2. 是否需要带审核者质量关卡的迭代？  是 → iterative-fleet（本Skill）
3. 是否是带依赖的一次性DAG？          是 → dag-fleet
4. 以上都不是？                          → 打开多个Claude Code会话
$ARGUMENTS