worktree-fleet

Worktree Fleet

N 個の独立したエージェントを並列で実行するスキルです。各エージェントは専用のブランチ上にある独自の git worktree で隔離されます。何かを起動する前に独立性を検証します。2 つのワーカーが重複する target_files を宣言している場合、このスキルは明確な競合メッセージを表示して処理を拒否します。

判断ツリー — どの fleet を使うか

You want to run multiple agents in parallel. Which fleet?

1. Are the tasks independent (no shared files, no shared state)?
   YES → worktree-fleet  ← YOU ARE HERE
   NO  → continue

2. Does the work need iteration with a reviewer making accept/iterate decisions?
   YES → iterative-fleet
   NO  → continue

3. Is the work a one-shot DAG (each agent runs to completion, dependencies via depends_on)?
   YES → dag-fleet
   NO  → continue

4. None of the above?
   → You're the orchestrator. Open multiple Claude Code sessions.

このスキルを使う場合

• タスクが重複しないファイル（異なるモジュール、異なるドキュメントなど）を対象とする
• マージ時の安全な隔離が必要 — 各ワーカーが独自のブランチで作業し、作業中に競合が起きない
• マージ方法は自分で判断したい — ワーカーの完了後に、マージの順序や戦略を選ぶ
• git で独立したブランチを作成し、内容を確認したり、チェリーピックしたり、破棄したりしたい

このスキルを使わない場合

• ワーカー間の調整や互いの出力の参照が必要 → depends_on を指定して dag-fleet を使います
• タスクの対象ファイルが（部分的にでも）重複している → まずタスクの分割を修正してから、再度実行します
• ヘッドレスワーカーとレビュアーが介在するワークフローが必要 → iterative-fleet を使います
• 現在の会話内で完了できる作業 → Claude Code の組み込み Agent ツールを直接使います

fleet.json のスキーマ

{
  "fleet_name": "refactor-utils",
  "type": "worktree",
  "config": {
    "max_concurrent": 4,
    "model": "sonnet",
    "fallback_model": "haiku"
  },
  "workers": [
    {
      "id": "rename-foo",
      "task": "Rename foo() to baz() in src/utils/foo.ts and all callers",
      "target_files": ["src/utils/foo.ts", "src/**/*.test.ts"],
      "branch": "rename-foo-to-baz",
      "type": "code-run",
      "max_turns": 30,
      "max_budget_usd": 2.0
    }
  ]
}

dag-fleet と異なる新しいフィールド：

• target_files（ワーカーごとに必須）— このワーカーが変更するファイルの glob のリストです。ワーカー間で重複があると、起動は終了コード 2 で拒否されます。
• branch（ワーカーごとに必須）— このワーカーの worktree に使用する git ブランチ名です。既存のブランチ名は指定できません。

ワーカータイプの上書き（Claude のみ）： Worktree ワーカーには git commit のために Bash が必要です。type を read-only、write、または reviewer に設定すると、launch.sh は警告を表示して自動的に code-run に上書きします。worktree 自体が隔離を提供するため、ここでは Bash の制限は不要です。この上書きは codex ワーカーには適用されません（codex はサンドボックスモードを使用します）。

プロバイダーのサポート： 設定レベルまたはワーカーごとのレベルで "provider": "codex" または "provider": "pi" を設定すると、Claude の代わりに OpenAI Codex CLI または pi.dev CLI を使用できます。Codex ワーカーは --sandbox workspace-write を使用します（git commit に必要です）。Pi ワーカーはツール制限に --tools の許可リストを使用します。プロバイダーに関する詳細（モデルのエイリアス、reasoning_effort、制限事項）については dag-fleet の SKILL.md を参照してください。

デフォルトの max_turns は 100 です（dag-fleet の 50 とは異なります）。Worktree ワーカーは通常、編集、テスト、コミットを行うため、余裕が必要です。

利用可能なスクリプト

スクリプト	呼び出すタイミング	引数
launch.sh	独立性を検証し、worktree を作成して、tmux でワーカーを起動する	<fleet-root> [--dry-run]
status.sh	worktree ごとの進捗、コスト、完了状態を確認する	<fleet-name-or-root> [--json]
merge.sh	マージ計画を表示する（変更ファイル、行数）— 自動マージはしない	<fleet-name-or-root>
cleanup.sh	git worktree を削除する。--force が必要	<fleet-name-or-root> --force

起動手順

1. FLEET_ROOT に絶対パスを設定します。
2. 上記のスキーマに従って $FLEET_ROOT/fleet.json を作成します。
3. 各ワーカーについて、$FLEET_ROOT/workers/{id}/prompt.md を作成します。以下を含めます：

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

4. 次を実行します：bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh $FLEET_ROOT
5. --dry-run は worktree の作成やワーカーの起動を行わずに、独立性を検証します。
6. 必ずユーザーに、手動で進捗を確認できるよう、正確な status コマンドを伝えます：

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

   これは起動のたびに必須です。ユーザーがあなたに尋ねずに状態を確認できる必要があります。

重要： ワーカープロンプトでは、終了前に変更をコミットするようワーカーに必ず指示してください：

When you are done, commit your changes on the current branch with a descriptive message.

これを指定しないと、変更はステージされていない状態で残り、git merge でマージできません。

ワーカー完了後

1. merge.sh を実行して、各ブランチで変更された内容を確認します。
2. マージ戦略（順番にマージする、チェリーピックするなど）を決めます。
3. 手動でマージします — このスキルは自動マージを行いません。
4. cleanup.sh --force を実行して worktree を削除します。

避けるべき合理化

エージェントの発言	反論
「タスクは少し重複していますが、対応できます」	target_files が重複している場合は却下です。例外はありません。まずタスクの分割を修正してください。対応できると思うなら、それは間違いです。並列ワークツリーでのマージコンフリクトは解決できません。
「fleet.json を慎重に書いたので、--dry-run は省略します」	それならドライランはすぐ終わるはずです。実行してください。独立性バリデーターは、考慮していなかった点（glob の重複、双方向の fnmatch）を検出します。
「2 人のワーカーが設定ファイルを使う必要がありますが、別々のセクションです」	同じファイルなら重複です。バリデーターは「セクション」を認識しません。設定変更を別の逐次ステップに分けるか、1 人のワーカーに担当させてください。
「ブランチはクリーンなので、自動マージします」	自動マージは絶対にしないでください。merge.sh を実行し、出力を読み、方針を決めてください。worktree-fleet の目的は、オペレーターがマージの判断を担うことです。
「クリーンアップは省略できます。ワークツリーがあっても問題ありません」	ワークツリーはブランチのロックを保持します。古いワークツリーは今後のブランチ作成を妨げ、ディスク容量を無駄にします。完了したら cleanup.sh --force を実行してください。

厳守事項

1. 新しいフリート設定では、--dry-run による検証を絶対に省略しないでください。
2. merge.sh の出力を先に確認せずにマージしてはいけません。
3. cleanup.sh には --force が必要です。不用意な削除を防ぐためです。
4. ワークツリーは明示的にクリーンアップするまで残ります。自動的に削除されることはありません。

$ARGUMENTS