fleet-plan

Fleet Plan

作業を分析し、適切なフリートタイプを選び、fleet.json とワーカープロンプトを生成します。計画を立てるのはあなた、実行するのはフリートスキルです。

ステップ 0：フリートタイプを選ぶ

以下の組み込み決定ツリーを使います。外部の情報を調べる必要はありません。

利用可能なフリートタイプ

フリートタイプ	使用する場合	使用しない場合
dag-fleet	依存関係、予算、複数のモデル／プロバイダーを使う一度きりの DAG ワーカー。セッションをまたいで維持されます。	ワーカーに Git の分離が必要な場合や、編集するファイルが重複する場合。
worktree-fleet	重複しないファイルを扱う独立したタスク。各ワーカーは専用の Git worktree／ブランチで作業します。安全にマージできる分離を実現します。	タスクでファイルを共有する場合や、連携したり互いの出力を読んだりする必要がある場合。
iterative-fleet	レビュアーを交えた作業が必要な場合（ビルダー → レビュアー → 判定 → 繰り返し）。品質ゲートを設けた反復作業です。	レビューサイクルのない一度きりの作業。
autoresearch-fleet	高速な評価ハーネスで単一の指標を最適化する場合。夜間の自律実行に適しています。停滞するとウェブ検索が起動します。	評価ハーネスがない場合や、タスクが最適化ではない場合。

決定ツリー

Q1: Can one agent handle this in a single session?
    YES → "No fleet needed — this fits in one session." STOP.

Q2: Are the tasks independent (no shared files, no shared state)?
    YES → worktree-fleet
    NO  → continue

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

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

Q5: Is it an optimization loop with a fast eval harness?
    YES → autoresearch-fleet
    NO  → "Open multiple sessions — you're the orchestrator." STOP.

選んだ後は、完全なスキーマを確認するため、選択したフリートの SKILL.md だけを読みます。すべてのフリートの SKILL.md を読むのは、コンテキストの無駄になるため避けてください。

ステップ 0.5：前提条件を確認する

フリートを生成する前に、前提条件が不足している場合はユーザーに知らせます。

• bash >= 4.0 — launch.sh の連想配列に必要です。macOS の場合：brew install bash を実行し、/opt/homebrew/bin/bash で呼び出します
• flock — Linux では標準で利用できます。macOS の場合：brew install flock を実行するか、launch.sh --no-lock を使用します
• tmux — brew install tmux または apt install tmux
• jq — brew install jq または apt install jq

ユーザーが macOS を使っている場合は、起動に失敗しないよう、これらを最初に伝えてください。

ステップ 1：フリートの配置場所を尋ねる

何かを分析する前に、ユーザーに尋ねます。

フリートのルートをどこに配置しますか？（デフォルトの場合は Enter キーを押してください）

• ユーザーがパスを指定した場合 → そのパスを使用します
• ユーザーが指定を無視した場合、「default」と答えた場合、または応答がない場合 → 現在の作業ディレクトリに fleet-{YYYYMMDD-HHMMSS}-{fleet-name}/ を使用します

フリートのルートには、常に絶対パスを使用してください。

ステップ 2：フリートタイプを選ぶ

上記の表と決定ツリーを使って、ユーザーのタスクに合うタイプを選びます。簡易的な目安：

Q1: Can one agent handle this in a single session?
    YES → "No fleet needed — this fits in one session." STOP.

Q2: Does the decision tree match a fleet type?
    YES → Pick it. Read its SKILL.md for the full schema.

Q3: No match?
    → "Open multiple Claude Code sessions — you're the orchestrator." STOP.

選んだ後は、正確な fleet.json スキーマ、ワーカータイプのルール、出力パスの規則を確認するため、選択したフリートの SKILL.md を読みます。記憶に基づいてスキーマを推測せず、SKILL.md を読んでください。 ここで停止します。

**Show the user your reasoning.** Don't just pick a type — explain why.

## Step 3: Generate fleet.json

### Guardrail: unsupported provider or model

If the user requests a provider or model not in the valid lists below, you MUST either:
1. **Map to closest valid equivalent** and explicitly disclose: *"Fleet mode only supports [valid providers]. Mapped your request to [X] with [Y]."*
2. **Error and refuse to generate** if no reasonable mapping exists.

**Never silently emit invalid config.** The agent's own thinking recognizing a value is unsupported is not sufficient — the output must be valid.

### Valid models — ONLY use these

**Claude models (provider: "claude", default):**

| Alias | Full ID | When to use |
|-------|---------|-------------|
| `sonnet` | `claude-sonnet-4-6` | Default for most workers |
| `opus` | `claude-opus-4-6` | Complex reasoning, architectural review, large-context synthesis |
| `haiku` | `claude-haiku-4-5` | Cheap/fast — validators, linters, simple checks |

**Codex models (provider: "codex"):**

| Model | When to use |
|-------|-------------|
| `gpt-5.5` | Latest flagship — strongest reasoning, use when available |
| `gpt-5.4` | Flagship — strong reasoning, reliable default |
| `gpt-5.4-mini` | Fast/cheap — validators, simple tasks |
| `gpt-5.3-codex` | Coding-focused (migrating to gpt-5.4) |

**Default:** `sonnet` for Claude workers, `haiku` for fallback_model.
**Only use `opus`** when the task clearly needs it. Cost difference is significant.
**Use codex** when the user requests it or the task benefits from OpenAI models (e.g. research with web search via codex).

### Model family guidance

When the user says "use the [family]" without per-worker specifics, assign models by worker role:

**Claude family (provider: "claude"):**
| Worker role | Model | Why |
|-------------|-------|-----|
| Synthesis, architecture, complex reasoning | `opus` | Highest intelligence, largest context |
| General workers, researchers, builders | `sonnet` | Default — best cost/performance |
| Validators, linters, simple checks | `haiku` | Cheap/fast |

**Pi / Kimi family (provider: "pi"):**
| Worker role | Model | reasoning_effort |
|-------------|-------|------------------|
| Synthesis, deep reasoning, complex analysis | `kimi-k2-thinking` | `high` (or `medium` if not deeply analytical) |
| General coding, research, builders | `kimi-for-coding` | `medium` |
| Simple checks, validators | `kimi-for-coding` | `low` |

**Codex / GPT family (provider: "codex"):**
| Worker role | Model | reasoning_effort |
|-------------|-------|------------------|
| Complex reasoning, flagship tasks | `gpt-5.5` | `high` |
| General workers, research | `gpt-5.4` | `medium` |
| Validators, simple tasks | `gpt-5.4-mini` | `medium` or `low` |

**Rule:** Match model capability to task complexity. Don't put `opus` on a linter or `haiku` on an architecture review.

### Budget guidelines

| Task complexity | max_budget_usd |
|----------------|---------------|
| One-line change, simple edit | 0.25 - 0.50 |
| Moderate task (new function, refactor one file) | 1.00 - 2.00 |
| Complex task (new feature, multi-file changes) | 3.00 - 5.00 |
| Large task (architectural change, full module) | 5.00 - 10.00 |

**Do NOT set max_turns.** It defaults to unlimited. Budget is the only limiter.

### Validation checklist (MUST complete before output)

Before writing fleet.json to disk, verify EVERY item:
- [ ] `type` field present at top level (`"worktree"`, `"dag"`, or `"iterative"`)
- [ ] `max_turns` is NOT set on any worker (omit entirely for unlimited)
- [ ] `reasoning_effort` only paired with `codex` or `pi` provider
- [ ] All provider/model values are from the valid lists above
- [ ] Status command template uses `<fleet-root>` path, not fleet name

### Worker type selection — CRITICAL

Pick the worker type based on what the worker **needs to output**, not what it reads:

| Worker role | Correct type | WRONG type | Why wrong |
|-------------|-------------|------------|-----------|
| Researcher (web + findings file) | `research` | `read-only` | read-only has no WebFetch/WebSearch and cannot Write |
| Synthesizer (reads inputs, writes synthesis) | `write` | `read-only` | read-only cannot Write — burns entire budget trying |
| Code builder (shell + files) | `code-run` | `write` | write has no Bash |
| Reviewer (reads code, runs tests, writes verdict) | `reviewer` | `write` | reviewer has full access (Bash, Edit, etc.) for verification |

**`read-only` CANNOT write files.** Only use it for workers whose output is captured from assistant messages in session.jsonl, not from output files. If a worker needs to save ANY file, use `write`, `research`, `code-run`, or `reviewer`.

### fleet.json rules by type

**All types:**
```json
{
  "fleet_name": "<descriptive-kebab-case-name>",
  "type": "<worktree|dag|iterative>",
  "config": {
    "max_concurrent": 3,
    "model": "sonnet",
    "fallback_model": "haiku",
    "provider": "claude",
    "reasoning_effort": ""
  },
  "workers": [...]
}

"type" は必須のトップレベルフィールドです。

プロバイダーフィールド（任意）：

• config.provider — "claude"（デフォルト）または "codex"。ワーカーごとの上書き：worker.provider。
• config.reasoning_effort — "low"、"medium"、または "high"（codex のみ）。ワーカーごとの上書き：worker.reasoning_effort。
• provider: "codex" の場合、fallback_model フィールドは無視されます（codex にはフォールバックがありません）。
• provider: "codex" の場合、max_budget_usd はワーカーごとに適用されません（codex には予算フラグがありません）。トークン推定によるフリート全体のコスト追跡は引き続き機能します。

worktree-fleet の追加要件：

• すべてのワーカーに target_files（ファイル glob の配列）と branch（一意のブランチ名）が必要です
• 2 つのワーカーの target_files が重複してはいけません
• デフォルトのワーカータイプ：code-run（worktree ワーカーには Git コミット用の Bash が必要です）

iterative-fleet の追加要件：

• type: "reviewer" のワーカーをちょうど 1 つ指定します（ビルダーの後に実行されるよう depends_on を使います）
• max_iterations と reviewer_lgtm_count を含む stop_when ブロックが必要です
• ワーカーには max_budget_usd ではなく max_budget_per_iter を指定します

dag-fleet の追加要件：

• 依存関係の順序付けには depends_on: ["worker-id"] を使います
• 依存関係のないワーカーは並列で実行されます

Config → プロンプトの同期ルール

fleet.json（モデル、予算、方法論、プロバイダー）を変更した後は、必ずすべての prompt.md ファイルを再生成して、内容を一致させてください。プロンプトは自動的に同期されません。古いプロンプトは部分的な更新伝播のバグを引き起こします。

各 prompt.md で、特に次の点を確認してください：

• モデル名が fleet.json と一致していること
• 予算値が fleet.json と一致していること
• 方法論（MECE、引用、ウェブ検索）がユーザー要件と一致していること
• 出力パスのルールがフリートの種類と一致していること

ステップ 4：各ワーカーの prompt.md を生成する

各ワーカーについて $FLEET_ROOT/workers/{id}/prompt.md を作成します。すべてのプロンプトに、必ず次の内容を含めてください：

1. 明確なタスクの説明 — 具体的に何をするか
2. スコープの境界 — 変更するファイルと、変更してはいけないファイル

出力パスのルール（重要 — フリートの種類によって異なります）

worktree-fleet：

• 「Save ALL output to output/」という行は含めないでください。ワーカーは、実際のリポジトリのパスにあるファイルを自身の worktree 内で編集します。
• 必ず最後に次を含めてください：

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

dag-fleet：

• 成果物（調査、要約、マトリックス）を作成するワーカー → 次を含めてください：

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

• リポジトリ内のファイルを編集するワーカー（コード変更、特定のパスへのドキュメント作成） → 正確な対象パスを指示してください。output/ にも言及してはいけません。出力先は1つだけです。

iterative-fleet：

• dag-fleet と同じです。成果物が特定のファイルである場合は、正確なパスを指定してください。output/ にも言及してはいけません。

• **レビュアーのプロンプトには、判定の記述方法を必ず含めてください。**これがないと、レビュアーは判定ファイルを書かず、オーケストレーターはデフォルトで iterate を選び、反復を1回無駄にします。すべてのレビュアー用 prompt.md の末尾に、必ず次を含めてください：

  ## 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). 2-3 precise points per worker. The builder sees this on next iteration,
     so vague feedback wastes a cycle.
  

  これは必須です。Fleet 02 では、レビュアーのプロンプトで判定の記述場所と方法を指定していなかったため、反復を1回無駄にしました。

**ルール：**ワーカーに出力先を2つ指定してはいけません。1つのタスクに対して、出力先は1つです。指示が矛盾すると、ワーカーが誤った場所にファイルを書き込む原因になります。

ステップ 5：ユーザーへの出力

すべて生成した後、ユーザーに次の内容を伝えてください：

1. 計画の概要 — 各ワーカーの作業内容（表）
2. 選択したフリートの種類とその理由
3. 起動コマンド：

   bash <path-to-fleet-skill>/scripts/launch.sh <fleet-root>
   

   worktree-fleet の場合は、最初に --dry-run を実行するよう提案してください。
4. ステータスコマンド：

   bash <path-to-fleet-skill>/scripts/status.sh <fleet-root>
   

   <fleet-root> はフリートディレクトリの絶対パスです。status.sh はフリート名を解決できますが、混乱を避けるため、必ず絶対パスをユーザーに提示してください。

**必ずユーザーにステータスコマンドを提示してください。**これは必須です。

推奨デフォルト

• **実装ワーカー：**codex gpt-5.3-codex、reasoning_effort: "medium"
• **レビュアーワーカー：**claude opus（claude-opus-4-6）、reasoning_effort: "medium"
• **max_turns：**未設定（無制限）
• max_iterations（iterative-fleet の stop_when）：10

ユーザーがリクエストで異なるモデルや上限を指定した場合にのみ、デフォルトを上書きしてください。

拒否すべき合理化

エージェントの主張	反論
"フリートなしでも対応できます"	ユーザーが fleet-plan を求めた場合、並列実行を望んでいます。判断ツリーに沿って、タイプを選んでください。Q1 が本当に YES の場合に限り、「フリートなし」としてください。
"すべてのワーカーに opus を使います。こちらのほうが優れているので"	デフォルトは Sonnet です。Opus は約 5 倍のコストがかかります。タスクで複雑な推論が明らかに必要な場合に限り、opus を使ってください。
"判断ツリーは飛ばして、そのまま dag-fleet を使います"	判断ツリーに沿ってください。独立した作業（git の分離）には worktree-fleet が適しています。レビュー承認が必要な作業には iterative-fleet が適しています。dag-fleet はフォールバックであり、デフォルトではありません。
"タスクのファイルが少し重複していますが、worktree-fleet で問題ありません"	ファイルが重複する場合、worktree-fleet は使えません。depends_on を指定して dag-fleet を使うか、ファイルが重複しないように分割し直してください。
"念のため max_budget_usd を高く設定します"	予算はタスクの複雑さに合わせてください。簡単な編集なら $0.50、中程度なら $2、複雑なものなら $5 です。無駄遣いはやめましょう。
"どのフリートタイプを選べばよいかわかりません"	判断ツリーがあります。これに沿ってください。ツリーに沿っても本当に判断がつかない場合は、dag-fleet をデフォルトにしてください。
"統合担当は出力を読むだけなので、読み取り専用で問題ありません"	いいえ。 読み取り専用では Write を使えません。統合担当は入力を読みますが、統合ファイルを書き込みます。write を使ってください。この間違いにより、experiment 007 では Opus が Write ツールを見つけようと 26 ターン費やし、$1.23 の損失が発生しました。
"研究者は読むだけなので、読み取り専用にすべきです"	いいえ。 読み取り専用では WebFetch／WebSearch も Write も使えません。研究者には research タイプが必要です。

$ARGUMENTS