dag-fleet

Fleet

claude -p、codex exec、または pi -p のワーカーを、予算と DAG 依存関係を設定して tmux 内で並列実行するためのスキルです。Claude、Codex、Pi の各プロバイダーに対応しており、Fleet ごと、またはワーカーごとに設定できます。停止、指示の変更、方向転換はすべてオペレーターが行います。自動再起動、自動検証、監視ループはありません。

前提条件

• bash >= 4.0 — macOS に付属する bash は 3.2（2007 年版）です。新しい bash をインストールしてください：brew install bash
• flock — Linux では標準で利用できます。macOS：brew install flock
• tmux — brew install tmux または apt install tmux
• jq — brew install jq または apt install jq

macOS のクイックスタート

brew install bash tmux jq flock
# Then invoke launch.sh explicitly with bash 4+:
/opt/homebrew/bin/bash /path/to/dag-fleet/scripts/launch.sh <fleet-root>

flock を利用できない場合、launch.sh は警告を表示してロックをスキップします。警告を表示しないようにするには、--no-lock を渡してください。

このスキルを使う場面（および使わない場面）

まず、次のいずれかに当てはまる場合は、Claude Code に組み込まれている Agent ツールを優先してください。 よりシンプルで高速なうえ、Fleet の仕組みを一切使わずに済みます。

• 作業が現在の会話内で完了する
• すべてのサブエージェントが 10 分以内に完了する
• 同じセッション内で結果をまとめる
• 予算の上限や依存関係の順序付けが不要

次のいずれかに当てはまる場合に限り、このスキルを使ってください。

• 永続性： 実行が親の claude プロセス終了後も続く（例：数時間にわたる Fleet の実行中に、ユーザーがノートパソコンを閉じる）
• ワーカーごとの予算： ワーカーごとに max_budget_usd: N を適用する必要がある
• DAG 依存関係： ワーカー D が、A、B、C の完了を待つ必要がある
• ワーカーごとに異なるモデル： 同じ Fleet 内で Sonnet の調査担当と Haiku の検証担当を使う
• tmux ペインの表示： ユーザーが個々のワーカーにアタッチして、出力をリアルタイムで見たい

どれにも当てはまらない場合は、このスキルを読むのをやめて Agent ツールを使ってください。

このスキルでできないこと

• 自動復旧システムではありません。ワーカーが失敗したり停止したりした場合、どうするかはオペレーターが判断します。
• 監視役ではありません。orchestrate.sh はなく、停止を検知して終了する機能も、実行中に指示を変更する機能もありません。
• 「手早い検索を 3 つ並列で実行する」用途ではありません。それは Agent ツールの役目です。

利用可能なスクリプト

スクリプト	呼び出すタイミング	引数
launch.sh	fleet.json から新しい Fleet を起動するとき	<fleet-root> [--force-relaunch] [--no-lock]
status.sh	実行中のもの、完了したもの、リアルタイムのコスト、ワーカーごとの最新メッセージを表示するとき	<fleet-name-or-root> [-v] [--watch] [--json]
kill.sh	ワーカー 1 つ、または Fleet 全体を停止するとき（オペレーターによる強制停止）	<fleet-name-or-root> <worker-id>|all [--force]
relaunch-worker.sh	1 つのワーカーの prompt.md を編集した後、そのワーカーだけを再実行するとき	<fleet-name-or-root> <worker-id>
report.sh	Fleet の完了後に Markdown の概要を生成するとき	<fleet-root>
view.sh	1 つのワーカーの tmux ペインの内容を取得するとき	<fleet-name-or-root> <worker-id>
feed.sh	すべてのワーカーのイベントを統合したフィードをストリーミングするとき	<fleet-name-or-root> [--agent <id>]

ユーティリティ（lib/ 内）：

ユーティリティ	用途	使用方法
dag-viz.py	Fleet の DAG 構造を可視化（ASCII または Mermaid）	python3 ${AGENTS_SKILLS_DIR}/lib/dag-viz.py <fleet.json> [--mermaid]

すべてのスクリプトは、絶対パスの Fleet ルート、または Fleet 名のどちらでも受け付けます（Fleet 名は ~/.claude/fleet-registry.json を使って解決されます。このファイルは launch.sh によって自動的に登録されます）。

起動手順（必ず正確に従ってください）

ユーザーからフリートの起動を依頼された場合：

1. FLEET_ROOT を設定します。 ユーザーが指定したディレクトリを使用します。指定がない場合は cwd を使用します。絶対パスのみを使用してください。 1b. macOS の確認： macOS の場合は、bash --version が 4.0 以上であり、flock が利用できることを確認します。利用できない場合は、brew でインストールするか、--no-lock を使用してください。
2. mkdir -p $FLEET_ROOT/workers
3. $FLEET_ROOT/fleet.json を生成します。 スキーマ全体については references/fleet-json-schema.md を参照してください。必須のトップレベルフィールドは fleet_name、config、workers[] です。各ワーカーには id、type、task、model、max_turns、max_budget_usd が必要です。DAG の順序指定には depends_on: [...] を使用します。
4. 各ワーカーについて、$FLEET_ROOT/workers/{id}/prompt.md を作成します。 プロンプトには、次の行を一字一句そのまま含める必要があります。

   Save ALL output files to $FLEET_ROOT/workers/{id}/output/ — use absolute paths.
   

   （実際のフリートルートとワーカー ID に置き換えてください。）
5. 実行します： bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh $FLEET_ROOT
6. 独自の tmux／claude コマンドを記述しないでください。 launch.sh がトポロジカルソート、tmux セッションの作成、ワーカーごとの起動、予算、レジストリを処理します。
7. 必ず、ユーザーが手動で状態を確認できるよう、正確なステータスコマンドを伝えてください：

   bash ${AGENTS_SKILLS_DIR}/scripts/status.sh <fleet-name-or-root>
   

   起動後は毎回必ず伝えてください。ユーザーがあなたに尋ねなくても状態を確認できるようにする必要があります。

ワーカーを1つ再実行する（追加作業のワークフロー）

ユーザーがフリートの実行を完了しており、ソースを1～2件追加する、またはワーカー1つの指示を変更する場合：

1. $FLEET_ROOT/workers/{id}/prompt.md を編集します（新しいソース／指示を追加します）
2. bash ${AGENTS_SKILLS_DIR}/scripts/relaunch-worker.sh <fleet-name> {id} を実行します
3. ワーカーの古い session.jsonl は .bak にローテーションされ、新しい tmux ウィンドウが起動します。他のワーカーには影響しません
4. フリートの tmux セッションが引き続き存在している必要があります。 セッションが終了している場合、ユーザーはフリート全体に対して launch.sh --force-relaunch を実行する必要があります。relaunch-worker.sh は稼働中のフリートセッションでのみ動作します。

複数のワーカーを再実行する場合は、1つずつ実行します。一括での再実行には対応していません。これは意図的な仕様です。

停止

オペレーターが実行する停止方法は2つあり、自動停止はありません：

• kill.sh <fleet> <worker-id> — ワーカーを1つ停止します。子孫プロセスもすべて停止します。1つのワーカーが誤った方向に進んでいると判断した場合に使用します。
• kill.sh <fleet> all --force — フリート全体を終了し、すべての tmux ウィンドウを閉じ、孤立した子プロセスをすべて停止して、ワーカーを KILLED に設定し、レジストリから登録を解除します。

steer.sh はありません。実行中の方向転換もできません。「このワーカーに別の方向で作業させたい」場合の意図されたワークフローは、kill.sh で停止し、prompt.md を編集して、relaunch-worker.sh を実行することです。3つの手順すべてをオペレーターが管理できます。

部分的に実行したフリートのリセット

プロンプトの不備、誤ったモデル、バグなどによりフリートが部分的に実行され、状態の衝突を避けて最初から再起動したい場合に使用します。

bash ${AGENTS_SKILLS_DIR}/scripts/reset.sh <FLEET_ROOT> [--soft|--hard] [--dry-run] [--force]

保持されるもの（どちらのレベルでも）： fleet.json の構造、workers/{id}/prompt.md。 --soft（デフォルト）で削除されるもの： 以前の実行結果は archive/<ts>/ にアーカイブされ、tmux セッションは終了し、fleet.json のステータスフィールドはクリアされます。 --hard で削除されるもの： フリートルート内のすべて（fleet.json とプロンプトを除く）。レジストリエントリも削除されます。

稼働中のワーカーが検出された場合は終了コード2で拒否されます。先に停止するには --force を指定してください。--dry-run で事前確認できます。

Worker タイプ

各 worker の type フィールドによって、claude に渡される --disallowed-tools のセット（pi の場合は --tools の許可リスト、codex の場合はサンドボックスモード）が決まります。次のいずれかを選択します。

• read-only — 禁止するもの：Bash、Edit、Write、Agent、WebFetch、WebSearch。ファイルに書き込めません。 出力が session.jsonl のアシスタントメッセージから取得される、純粋な分析にのみ使用してください。
• write — 禁止するもの：Bash、Agent、WebFetch、WebSearch。シンセサイザーや、出力ファイルを書き込む worker に使用してください。
• code-run — 禁止するもの：Agent、WebFetch、WebSearch（ビルド／テスト用 worker の一般的なデフォルトです）
• research — 禁止するもの：Bash、Edit、Agent（ウェブアクセスは有効です）。read-only ではなく、リサーチ担当者に使用してください。
• reviewer — 禁止するもの：Bash、Edit、Agent、WebFetch、WebSearch。Read と Write のみを使用できます。判定ファイルを書き込む reviewer に使用してください。
• orchestrator — 禁止するもの：Agent、WebFetch、WebSearch、Edit

警告： read-only はファイルに書き込めません。worker が出力（findings.md、synthesis.md など）を保存する必要がある場合は、write、research、reviewer、または code-run を使用してください。シンセサイザーを read-only に設定すると、Write ツールを探すために予算をすべて使い切ってしまいます。

完全な権限マトリックスについては、references/worker-types.md を参照してください。

プロバイダーのサポート（Claude + Codex + Pi）

worker は claude（デフォルト）、codex（OpenAI Codex CLI）、または pi（pi.dev CLI）で実行できます。フリート全体または worker ごとに設定します。

{
  "config": {
    "provider": "pi",
    "model": "kimi-for-coding",
    "reasoning_effort": "medium"
  },
  "workers": [
    { "id": "researcher", "type": "research", "provider": "pi", "model": "kimi-for-coding", "reasoning_effort": "high" },
    { "id": "writer", "type": "write", "provider": "claude", "model": "sonnet" }
  ]
}

{
  "config": {
    "provider": "codex",
    "model": "gpt-5.4",
    "reasoning_effort": "medium"
  },
  "workers": [
    { "id": "researcher", "type": "research", "provider": "codex", "model": "gpt-5.4", "reasoning_effort": "medium" },
    { "id": "writer", "type": "write", "provider": "claude", "model": "sonnet" }
  ]
}

プロバイダー固有のフィールド

フィールド	値	デフォルト	適用範囲
provider	"claude" | "codex" | "pi"	"claude"	config + worker ごと
reasoning_effort	"low" | "medium" | "high"	（なし）	config + worker ごと、codex/pi のみ

Codex のモデルエイリアス

モデル	用途
gpt-5.5	最新のフラッグシップ — 最も強力な推論性能があり、利用可能な場合に使用
gpt-5.4	フラッグシップ — 強力な推論性能を備えた、信頼できるデフォルト
gpt-5.4-mini	高速／低コスト — バリデーター、単純なタスク
gpt-5.3-codex	コーディングに特化（gpt-5.4 へ移行中）

Pi のモデル

Pi はモデルではなく、プロバイダーハーネスです。実際のモデルは、pi の設定で構成されているプロバイダーによって決まります。pi --list-models を実行すると、利用可能なモデルを確認できます。

例： kimi-coding プロバイダーが設定されている場合：

モデル	用途
kimi-for-coding	デフォルト／安定した ID — 常に最新の Kimi Code モデルに解決されます
kimi-k2-thinking	高度な推論 — リサーチ用 worker

model に指定した文字列は、そのまま pi -p --model に渡されます。エイリアスも検証もありません。

モデルファミリーのガイダンス

ユーザーが worker ごとの具体的な指定なしに「[ファミリー]を使って」と言った場合は、worker の役割に応じてモデルを割り当てます。

Claude ファミリー：

Worker の役割	モデル
統合、アーキテクチャ、複雑な推論	opus
一般的な worker、リサーチ担当者、ビルダー	sonnet
バリデーター、リンター、単純なチェック	haiku

Pi / Kimi ファミリー：

Worker の役割	モデル	reasoning_effort
統合、高度な推論、複雑な分析	kimi-k2-thinking	high（または medium）
一般的なコーディング、リサーチ、ビルダー	kimi-for-coding	medium
単純なチェック、バリデーター	kimi-for-coding	low

Codex / GPT ファミリー：

Worker の役割	モデル	reasoning_effort
複雑な推論、フラッグシップ向けタスク	gpt-5.5	high
一般的な worker、リサーチ	gpt-5.4	medium
バリデーター、単純なタスク	gpt-5.4-mini	medium または low

ルール： タスクの複雑さにモデルの能力を合わせてください。リンターに opus を使ったり、アーキテクチャレビューに haiku を使ったりしないでください。

Claude と比較したプロバイダーの制限事項

Codex:

• --max-budget-usd はありません — codex にはワーカーごとの予算上限がありません。フリートレベルのコスト追跡は引き続き機能します（トークン数から推定）。
• --fallback-model はありません — codex には自動モデルフォールバックがありません。
• ツールごとの無効化はできません — codex では --disallowed-tools の代わりにサンドボックスモード（read-only、workspace-write）を使用します。ワーカーの種類は自動的にマッピングされます。
• ウェブ検索 — 調査ワーカーには -c 'web_search="live"' が自動的に付与されます。
• 出力を行うすべてのワーカーに workspace-write が必要です — codex の read-only サンドボックスは、出力を含むすべてのファイル書き込みをブロックします。

Pi:

• --max-budget-usd はありません — pi にはワーカーごとの予算上限がありません。フリートレベルのコスト追跡はトークン推定によって機能します。
• --fallback-model はありません — pi には自動モデルフォールバックがありません。
• --tools の許可リスト — pi では拒否リストではなく許可リストを使用します。ワーカーの種類に応じて、適切なツールセットが自動的にマッピングされます。
• セッションディレクトリ — pi はワーカーごとの .pi-sessions/ ディレクトリにセッションを書き込み、JSONL ログを標準パスにシンボリックリンクします。

DAG の依存関係

{
  "id": "synthesizer",
  "depends_on": ["researcher-01", "researcher-02"]
}

launch.sh は共有の lib/dag.sh プリミティブ（Kahn の BFS レイヤー型トポロジカルソート）を使ってワーカーの順序を決め、依存先の起動前に、依存元が終端の result イベントを出力するまで待機します。サイクルは tmux の状態が作成される前に検出され、フリートは標準エラー出力に CYCLE:a,b,... を出して終了コード 2 で終了します。各レイヤー内のワーカーは、max_concurrent まで並列に実行されます。起動前に DAG の構造を確認するには、dag-viz.py を使ってください。

予算

• worker.max_budget_usd: N — ワーカーごとのハード上限で、claude --max-budget-usd に渡されます
• config.max_budget_fleet: N — フリート全体の上限です。これを超えると launch.sh は新しいワーカーの起動を停止します（すでに実行中のワーカーは停止されません。この上限は「新たな支出を行わない」という意味です）

厳守事項

1. すべての操作に、必ず上記のスクリプトを使用してください。 tmux や claude のコマンドを独自に作成しないでください。
2. claude に --bare フラグを絶対に使用しないでください — 認証エラーが発生します。
3. フリートのルートはユーザーのディレクトリです。 デフォルトでは cwd を使います。フリートのファイルはすべて $FLEET_ROOT 内に置いてください。
4. ワーカーの出力パスは絶対パスにしてください： $FLEET_ROOT/workers/{id}/output/。これをワーカーの prompt.md で伝えてください。
5. ワーカーの起動に使えるのは launch.sh だけです。 個別に再実行する場合は relaunch-worker.sh だけを使ってください。それ以外の方法はありません。
6. 停止と方針変更はオペレーターが行います。 自動で停止、再起動、リダイレクトしないでください。ワーカーの動作に問題があればユーザーに伝え、判断を委ねてください。
7. 存在しないスクリプトを作らないでください。 steer.sh、verify.sh、add-worker.sh、orchestrate.sh が必要だと思っても、これらは意図的に削除されています。代わりに、上記のオペレーター管理のワークフローを使ってください。

却下すべき正当化

エージェントの発言	反論
「タスクが十分小さいので、tmux コマンドを自分で書けます」	このスキルは、忘れがちな 15 項目（CLAUDECODE の unset、--disallowed-tools、セッション名、レジストリ、トポロジカルソート）を防ぐためにあります。launch.sh を使ってください。
「relaunch-worker.sh を使って、停止したワーカーをすべて一度に再起動します」	意図的に、1 回につき 1 つです。実験 001 では、各ワーカーでキャッシュが再構築され、バッチ再起動によって $20 が消費されました。
「ワーカーが停止しているようなので、停止して再起動します」	長い思考中の状態は、ハングしたように見えることがあります。まず status.sh または view.sh を確認してください。ワーカーを停止できるのはオペレーターだけです。
「各ワーカーの完了後に検証ステップを追加します」	検証ステップはありません。オペレーターが出力を読み、判断します。自動検証は、検出した失敗よりも大きな害を引き起こしたため削除されました。
「処理を速くするために --bare を追加します」	--bare は認証エラーを引き起こします。絶対に使用しないでください。これは厳守事項の #2 です。

このスキルをあきらめるべき場合

ユーザーが自動復旧、実行中の方向修正、またはワーカーごとの検証ループを必要とする動作を求めた場合、このスキルは設計上、そうした動作をもう行わないことを伝えてください。 次の方法を提案してください。

• 自動復旧の場合 → ウォッチャースクリプトを自分で実行し、そこから kill.sh と relaunch-worker.sh を呼び出す
• 実行中の方向修正の場合 → kill → prompt.md を編集 → relaunch-worker
• 検証の場合 → 出力ファイルを自分で確認して判断する

自動化された動作が、復旧を試みていた障害よりも大きな害をもたらした実験を経て、このスキルの機能範囲は意図的に縮小されました。

$ARGUMENTS