iterative-fleet

Iterative Fleet

用于由审核者把关的并行 claude -p、codex exec 或 pi -p 工作器迭代循环的技能。工作器按迭代运行，审核者读取其输出并写出判定结果，生成的编排器则决定继续还是停止——绝不会终止或重启工作器。支持 Claude、Codex 和 Pi 提供方——可按 Fleet 或工作器设置。完整的提供方文档（模型别名、reasoning_effort、限制）请参阅 dag-fleet SKILL.md。

何时使用此技能

在以下情况使用 iterative-fleet：

• 工作需要多轮完善（而非一次完成）
• 工作完成前必须由审核者／验证者批准输出
• 你希望由操作者声明停止条件（最大迭代次数、LGTM 次数、成本上限）
• 工作器运行时间较长或启动开销较高（不会自动重启——见「重要」部分）

在以下情况改用 dag-fleet：

• 工作器只运行一次便完成（无需迭代）
• 没有审核者质量关卡

在以下情况改用 worktree-fleet：

• 任务完全独立，没有共享状态

重要：不自动终止，不自动重启

此技能生成的编排器只读取并做出决定。它绝不会终止或重启工作器。工作器会在每轮迭代中运行至自然完成。这一设计源自实验 001 中的一次 20 美元损失：对「卡住」的工作器自动重启导致缓存重建，其成本超过了实际工作。审核者是质量关卡，操作者则是紧急停止开关。

fleet.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
  }
}

通过 depends_on 设置 DAG 顺序

每轮迭代都是一个 DAG。工作器通过 depends_on 声明依赖项：

{ "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（例如，研究员 → 构建者 → 审核者 = 3 层）。共享的 lib/dag.sh 提供拓扑排序和依赖检查功能，可在所有 Fleet 类型中复用。

如果没有工作器设置 depends_on，所有工作器都会并行启动（向后兼容）。

迭代目录结构

$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)

审核者接口

审核者工作器读取 iterations/<N>/*.log，并写入 iterations/<N>/review.md。review.md 必须包含以下判定之一：

• verdict: lgtm — 输出已获批准，计入停止条件
• verdict: iterate — 需要再进行一轮
• verdict: escalate — 需要人工关注，编排器会暂停

审核者提示词要求

每个审核者的 prompt.md 都必须逐字包含以下指示（路径可作相应调整）。否则，审核者将不知道应将判定写到哪里，而编排器会默认使用 iterate，浪费一轮迭代。

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

builder-b

1. src/utils.py — 定义了 format_output()，但它未列入 __all__，也未在 __init__.py 中导出。添加到 src/__init__.py 第 5 行：from .utils import format_output。

可用脚本

脚本	用途
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 会话、清理孤儿进程并取消注册

启动流程

1. 创建 $FLEET_ROOT/fleet.json，其中包含工作者，并且恰好有一个 type: "reviewer" 工作者（其 depends_on 指向构建者工作者）
2. 为每个工作者创建 $FLEET_ROOT/workers/<id>/prompt.md
3. 运行 bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh $FLEET_ROOT
4. 务必告知用户确切的状态命令，以便他们手动监控：

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

   每次启动后都必须执行此操作。用户必须能够在不询问你的情况下检查状态。
5. 如有需要，暂停：bash ${AGENTS_SKILLS_DIR}/scripts/pause.sh $FLEET_ROOT
6. 强制停止：bash ${AGENTS_SKILLS_DIR}/scripts/kill.sh $FLEET_ROOT all

应拒绝的自我合理化

Agent 的说法	反驳
“工作者已经运行了 10 分钟，没有任何输出——肯定是卡住了，我应该暂停它”	长时间思考时看起来就像没有动静。编排器等待的是 result 事件，而不是超时。这正是导致实验 001 中 $20 资金损失恶性循环的故障模式。不要干预。
“审查者说‘看起来基本不错’——我就当作 LGTM 吧”	只有 verdict: lgtm 才算数。“基本不错”属于 iterate。如果审查者的结论模棱两可，就按 iterate 处理。不要往宽松了理解。
“我应该终止这个工作者，再用更好的提示词重启它”	编排器绝不会终止工作者。工作者会运行至自然完成。如果需要更换提示词，请暂停整个工作组，编辑 prompt.md，并让下一轮采用新提示词。
“成本越来越高——我来在运行过程中调低 max_iterations”	停止条件在生成时就写入了 orchestrator.sh。要更改这些条件，请终止工作组，使用新的 fleet.json 重新生成，然后重新启动。不要直接编辑 orchestrator.sh。
“这个简单任务可以跳过审查者”	如果任务不需要审查者，请使用 dag-fleet（单次运行）或 worktree-fleet（独立运行）。没有审查者的 Iterative-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