iterative-fleet

Iterative Fleet

並列で実行する claude -p、codex exec、または pi -p ワーカーの、レビュアー承認を経て反復するループのためのスキルです。ワーカーはイテレーションごとに実行され、レビュアーがその出力を読み取って判定を書き込み、生成されたオーケストレーターが続行するか停止するかを決定します。ワーカーを強制終了したり再起動したりすることはありません。Claude、Codex、Pi の各プロバイダーに対応しており、フリート単位またはワーカー単位で設定できます。プロバイダーの詳細なドキュメント（モデルのエイリアス、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 はトポロジカルソートと依存関係のチェックを提供し、すべてのフリートタイプで再利用できます。

どのワーカーにも 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 がありません。45〜48 行目を try/except json.JSONDecodeError で囲み、失敗した場合は None を返してください。
2. src/parser.py:validate_schema() — 72 行目のスキーマ辞書に必須フィールド "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 を作成し、depends_on がビルダーワーカーを指す type: "reviewer" ワーカーをちょうど 1 つ含めます
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

拒否すべき合理化

エージェントの発言	反論
「ワーカーが 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