fleet-plan

Fleet 规划

分析工作，选择合适的 fleet 类型，生成 fleet.json 和 worker 提示词。由你负责规划，fleet 技能负责执行。

步骤 0：选择 fleet 类型

使用以下内置决策树。无需外部查询。

可用的 fleet 类型

Fleet 类型	适用场景	不适用场景
dag-fleet	使用带依赖关系、预算以及混合模型／提供商的一次性 DAG workers。可跨会话持久运行。	Workers 需要 git 隔离，或会编辑重叠的文件。
worktree-fleet	处理不重叠文件的独立任务。每个 worker 都在自己的 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.

选择后，只阅读所选 fleet 的 SKILL.md，以了解完整的 schema。切勿阅读所有 fleet 的 SKILL.md 文件——这会浪费上下文。

步骤 0.5：检查前置条件

生成 fleet 前，如果缺少任何前置条件，请提醒用户：

• 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：询问 fleet 的放置位置

开始分析前，询问用户：

应将 fleet 根目录放在哪里？（按 Enter 使用默认位置）

• 如果用户提供路径 → 使用该路径
• 如果用户忽略、表示“默认”或没有回复 → 使用当前工作目录下的 fleet-{YYYYMMDD-HHMMSS}-{fleet-name}/

fleet 根目录始终使用绝对路径。

步骤 2：选择 fleet 类型

使用上方的表格和决策树，根据用户的任务选择合适类型。快速判断规则：

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 的 SKILL.md，了解准确的 fleet.json schema、worker 类型规则和输出路径约定。不要凭记忆猜测 schema——请阅读 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 覆盖：worker.provider。
• config.reasoning_effort — "low"、"medium" 或 "high"（仅适用于 codex）。可按 worker 覆盖：worker.reasoning_effort。
• 当 provider: "codex" 时，fallback_model 字段会被忽略（codex 没有回退模型）。
• 当 provider: "codex" 时，不会对每个 worker 强制执行 max_budget_usd（codex 没有预算标志）。Fleet 级别的成本跟踪仍可通过 token 估算实现。

worktree-fleet 的附加要求：

• 每个 worker 都必须有 target_files（文件 glob 数组）和 branch（唯一分支名称）
• 不同 worker 的 target_files 不得重叠
• 默认 worker 类型：code-run（worktree workers 需要 Bash 才能执行 git commit）

iterative-fleet 的附加要求：

• 必须且只能有一个 type: "reviewer" 的 worker（使用 depends_on 确保其在构建者之后运行）
• 必须包含 stop_when 块，且至少包含 max_iterations 和 reviewer_lgtm_count
• Workers 使用 max_budget_per_iter，而不是 max_budget_usd

dag-fleet 的附加要求：

• 使用 depends_on: ["worker-id"] 指定依赖顺序
• 没有依赖关系的 workers 会并行运行

配置 → 提示词同步规则

对 fleet.json（模型、预算、方法论、提供方）进行任何更改后，都必须重新生成所有 prompt.md 文件，使其保持一致。提示词不会自动同步——过时的提示词会导致部分更新传播错误。

请具体核实每个 prompt.md 中的以下内容：

• 模型名称与 fleet.json 一致
• 预算值与 fleet.json 一致
• 方法论（MECE、引用、网页搜索）符合用户要求
• 输出路径规则与 Fleet 类型一致

第 4 步：为每个工作器生成 prompt.md

为每个工作器创建 $FLEET_ROOT/workers/{id}/prompt.md。每个提示词都必须包含：

1. 清晰的任务描述——具体说明要做什么
2. 范围边界——说明可以修改哪些文件，以及哪些文件不可修改

输出路径规则（关键——不同 Fleet 类型的规则各不相同）

worktree-fleet：

• 不要添加“将所有输出保存到 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/。只能有一个目标位置。

iterative-fleet：

• 与 dag-fleet 相同：如果交付物是特定文件，请给出确切路径。不要同时提及 output/。

• **审核者提示词必须包含撰写评定结果的说明。**如果没有这些说明，审核者就不会写入评定文件，编排器会默认执行 iterate，浪费一次迭代。每个审核者的 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 曾因审核者提示词未指定评定结果的写入位置和方式而浪费了一次迭代。

**规则：**绝不能给工作器指定两个目标位置。一个任务 = 一个输出位置。相互冲突的指令会导致工作器把内容写到错误的位置。

第 5 步：向用户输出

完成所有内容后，告知用户：

1. 计划摘要——说明每个工作器的任务（用表格呈现）
2. 选择的 Fleet 类型及其原因
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> 是 Fleet 目录的绝对路径。虽然 status.sh 可以解析 Fleet 名称，但始终向用户提供绝对路径，以免造成混淆。

**始终向用户提供状态命令。**这是强制要求。

首选默认值

• 实现工作器： 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

仅当用户在请求中指定了不同的模型或上限时才覆盖这些默认值。

应当驳斥的自我辩解

Agent 的说法	反驳
“没有 fleet 我也能搞定”	如果用户要求使用 fleet-plan，他们想要并行执行。按决策树逐步判断并选择类型。只有在 Q1 确实为 YES 时，才说“无需 fleet”。
“Opus 更好，所以我会让所有工作者都用 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。不要浪费钱。
“我不知道该选哪种 fleet 类型”	你有决策树。按决策树逐步判断。如果按决策树判断后仍确实无法确定，则默认使用 dag-fleet。
“综合者只读取输出，所以只读权限就够了”	不对。 只读权限无法执行 Write。综合者会读取输入，但也会写入综合文件。使用 write。这项错误在实验 007 中造成了 $1.23 的损失：Opus 花了 26 轮尝试寻找 Write 工具。
“研究人员只是在阅读，所以应该设置为只读”	不对。 只读权限不包含 WebFetch/WebSearch，也不包含 Write。研究人员需要使用 research 类型。

$ARGUMENTS