fleet-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fleet Plan

Agent集群规划

Analyze work, pick the right fleet type, generate fleet.json + worker prompts. You plan — the fleet skills execute.

分析工作内容，选择合适的集群类型，生成fleet.json文件及Worker提示词。您负责规划，集群技能负责执行。

Step 0: Discover available fleet types

步骤0：发现可用的集群类型

Before planning, read the fleet index to know what's available:

Find the index:
```
Glob
```
for
```
**/fleet/FLEET-INDEX.md
```
(or look in the same parent dir as this skill)
Read
```
FLEET-INDEX.md
```
— it has a table of all fleet types with one-liner hints on when to use each
Based on the hints, pick the best fleet type for the user's task
Then read ONLY the chosen fleet's
```
SKILL.md
```
for the full schema:
```
Glob
```
for
```
**/<chosen-fleet>/SKILL.md
```

This is a two-step lookup: cheap index first (one small file), full schema second (one SKILL.md). Never read all fleet SKILL.md files — that wastes context.

规划前，请阅读集群索引了解可用选项：

查找索引：使用
```
Glob
```
匹配
```
**/fleet/FLEET-INDEX.md
```
（或查看本技能所在的上级目录）
阅读
```
FLEET-INDEX.md
```
文件，其中包含所有集群类型的表格，每种类型配有一行使用场景提示
根据提示，为用户任务选择最优集群类型
随后仅读取所选集群的
```
SKILL.md
```
文件以获取完整架构：使用
```
Glob
```
匹配
```
**/<chosen-fleet>/SKILL.md
```

这是一个两步查找流程：先读取轻量化索引（一个小文件），再读取完整架构（一个SKILL.md文件）。切勿读取所有集群的SKILL.md文件，这会浪费上下文资源。

Step 1: Ask where to place the fleet

步骤1：询问集群存放位置

Before analyzing anything, ask the user:

Where should I place the fleet root? (Press enter for default)

If the user provides a path → use it
If the user ignores, says "default", or doesn't respond → use:
```
fleet-{YYYYMMDD-HHMMSS}-{fleet-name}/
```
in the current working directory

Always use absolute paths for the fleet root.

在进行任何分析前，先询问用户：

集群根目录应放在哪里？（按回车键使用默认路径）

若用户提供路径，则使用该路径
若用户忽略、输入“default”或未响应，则使用当前工作目录下的
```
fleet-{YYYYMMDD-HHMMSS}-{fleet-name}/
```
路径

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

Step 2: Pick a fleet type

步骤2：选择集群类型

Use the hints from FLEET-INDEX.md to match the user's task. Quick heuristic:

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

Q2: Does FLEET-INDEX.md have a matching 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.

After picking, read the chosen fleet's SKILL.md to get the exact fleet.json schema, worker type rules, and output path conventions. Do not guess schemas from memory — read the SKILL.md. STOP HERE.


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

使用FLEET-INDEX.md中的提示匹配用户任务。快速判断规则：

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

Q2: Does FLEET-INDEX.md have a matching 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.

选择完成后，读取所选集群的SKILL.md文件，获取准确的fleet.json架构、Worker类型规则及输出路径约定。切勿凭记忆猜测架构，务必读取SKILL.md文件。

向用户展示您的推理过程。 不要只选择类型，还要解释原因。

Step 3: Generate fleet.json

步骤3：生成fleet.json文件

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.4`	Flagship — strongest reasoning, recommended 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).

Claude模型（提供商："claude"，默认选项）：

别名	完整ID	使用场景
`sonnet`	`claude-sonnet-4-6`	多数Worker的默认选择
`opus`	`claude-opus-4-6`	复杂推理、架构评审、大上下文合成
`haiku`	`claude-haiku-4-5`	低成本/快速场景——验证器、代码检查器、简单校验

Codex模型（提供商："codex"）：

模型	使用场景
`gpt-5.4`	旗舰模型——推理能力最强，推荐作为默认选择
`gpt-5.4-mini`	快速/低成本场景——验证器、简单任务
`gpt-5.3-codex`	专注编码场景（正在迁移至gpt-5.4）

默认设置： Claude Worker使用

sonnet

，备用模型（fallback_model）使用

haiku

。仅在任务明确需要时使用
opus
，其成本差异较大。 当用户要求或任务能从OpenAI模型中获益时使用codex（例如通过codex进行带网页搜索的研究）。

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.

任务复杂度	最大预算（美元）
单行修改、简单编辑	0.25 - 0.50
中等任务（新增函数、重构单个文件）	1.00 - 2.00
复杂任务（新增功能、多文件修改）	3.00 - 5.00
大型任务（架构变更、完整模块开发）	5.00 - 10.00

请勿设置max_turns，其默认值为无限制。预算是唯一的限制条件。

Worker type selection — CRITICAL

Worker类型选择——至关重要

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

根据Worker需要输出的内容而非读取的内容选择类型：

Worker角色	正确类型	错误类型	错误原因
研究员（网页搜索+结果文件）	`research`	`read-only`	read-only类型无WebFetch/WebSearch功能，且无法写入文件
合成器（读取输入，生成合成内容）	`write`	`read-only`	read-only类型无法写入文件——会耗尽全部预算尝试执行写入操作
代码构建者（Shell+文件操作）	`code-run`	`write`	write类型无Bash功能
评审员（读取代码、运行测试、撰写评审结论）	`reviewer`	`write`	reviewer类型拥有完整权限（Bash、编辑等）以完成验证工作

read-only
类型无法写入文件。仅将其用于输出内容从session.jsonl中的助手消息捕获、无需生成输出文件的Worker。若Worker需要保存任何文件，请使用

write

、

research

、

code-run

或

reviewer

类型。

fleet.json rules by type

按集群类型划分的fleet.json规则

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": [...]
}

Provider fields (optional):

config.provider

—

"claude"

(default) or

"codex"

. Per-worker override:

worker.provider

config.reasoning_effort

—

"low"

"medium"

, or

"high"

(codex only). Per-worker override:

worker.reasoning_effort

When
```
provider: "codex"
```
, the
```
fallback_model
```
field is ignored (codex has no fallback).
When
```
provider: "codex"
```
,
```
max_budget_usd
```
is NOT enforced per-worker (codex has no budget flag). Fleet-level cost tracking still works via token estimation.

worktree-fleet additions:

Every worker MUST have
```
target_files
```
(array of file globs) and
```
branch
```
(unique branch name)
No two workers can have overlapping target_files
Default worker type:
```
code-run
```
(worktree workers need Bash for git commit)

iterative-fleet additions:

Exactly one worker with
```
type: "reviewer"
```
(use
```
depends_on
```
to ensure it runs after builders)

Must include

stop_when

block with at least

max_iterations

and

reviewer_lgtm_count

Workers have
```
max_budget_per_iter
```
instead of
```
max_budget_usd
```

dag-fleet additions:

Use
```
depends_on: ["worker-id"]
```
for dependency ordering
Workers without dependencies run in parallel

所有类型通用规则：

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": [...]
}

提供商字段（可选）：

```
config.provider
```
—
```
"claude"
```
（默认）或
```
"codex"
```
。可通过
```
worker.provider
```
为单个Worker覆盖此设置。
```
config.reasoning_effort
```
—
```
"low"
```
、
```
"medium"
```
或
```
"high"
```
（仅适用于codex）。可通过
```
worker.reasoning_effort
```
为单个Worker覆盖此设置。
当
```
provider: "codex"
```
时，
```
fallback_model
```
字段将被忽略（codex无备用模型）。
当
```
provider: "codex"
```
时，
```
max_budget_usd
```
不会在单个Worker层面生效（codex无预算标记）。集群层面的成本跟踪仍可通过token估算实现。

worktree集群附加规则：

每个Worker必须包含
```
target_files
```
（文件通配符数组）和
```
branch
```
（唯一分支名称）
任意两个Worker的target_files不能重叠
默认Worker类型：
```
code-run
```
（worktree Worker需要Bash执行git提交操作）

迭代式集群附加规则：

必须恰好有一个
```
type: "reviewer"
```
的Worker（使用
```
depends_on
```
确保其在构建Worker之后运行）
必须包含
```
stop_when
```
块，其中至少包含
```
max_iterations
```
和
```
reviewer_lgtm_count
```
字段
Worker使用
```
max_budget_per_iter
```
而非
```
max_budget_usd
```
字段

DAG集群附加规则：

使用
```
depends_on: ["worker-id"]
```
定义依赖顺序
无依赖的Worker将并行运行

Step 4: Generate prompt.md for each worker

步骤4：为每个Worker生成prompt.md文件

Create

$FLEET_ROOT/workers/{id}/prompt.md

for each worker. Every prompt MUST include:

Clear task description — what to do, in specific terms
Scope boundaries — what files to touch, what NOT to touch

为每个Worker创建

$FLEET_ROOT/workers/{id}/prompt.md

文件。每个提示词必须包含：

清晰的任务描述——明确说明需要执行的操作
范围边界——明确说明需要处理的文件和无需处理的文件

Output path rules (CRITICAL — different per fleet type)

输出路径规则（至关重要——不同集群类型规则不同）

worktree-fleet:

Do NOT include a "Save ALL output to output/" line. The worker edits files in its worktree at the real repo paths.

MUST include at the end:

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

dag-fleet:

Workers that produce artifacts (research, summaries, matrices) → include:

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

Workers that edit repo files (code changes, creating docs at specific paths) → tell them the exact target path. Do NOT also mention output/. One destination only.

iterative-fleet:

Same as dag-fleet: if the deliverable is a specific file, give the exact path. Do not also mention output/.

Reviewer prompt MUST include verdict-writing instructions. Without these, the reviewer won't write a verdict file and the orchestrator defaults to

iterate

, wasting an iteration. Every reviewer prompt.md must end with:

## 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.

This is non-negotiable. Fleet 02 burned an iteration because the reviewer prompt didn't specify where/how to write the verdict.

The rule: Never give a worker two destinations. One task = one output location. Conflicting instructions cause workers to write to the wrong place.

worktree集群：

请勿添加“将所有输出保存至output/”的语句。Worker将在其工作树的真实仓库路径中编辑文件。

必须在末尾添加以下内容：

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

DAG集群：

生成成果物（研究报告、摘要、矩阵）的Worker→添加以下内容：
```
Save ALL output files to $FLEET_ROOT/workers/{id}/output/ — use absolute paths.
```
编辑仓库文件（代码修改、在特定路径创建文档）的Worker→告知其准确的目标路径。请勿同时提及output/。只能指定一个目标位置。

迭代式集群：

与DAG集群规则相同：若交付物为特定文件，给出准确路径。请勿同时提及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.

此规则不可协商。集群02因评审员提示词未指定评审结论的写入位置/方式而浪费了一次迭代。

规则： 切勿为一个Worker指定两个目标位置。一项任务对应一个输出位置。冲突的指令会导致Worker写入错误位置。

Step 5: Output to user

步骤5：向用户输出结果

After generating everything, tell the user:

Plan summary — what each worker does (a table)
Fleet type chosen and why

Launch command:

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

For worktree-fleet, suggest

--dry-run

first.

Status command:

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

ALWAYS give the user the status command. This is mandatory.

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

规划摘要——每个Worker的职责（表格形式）
所选集群类型及选择原因
启动命令：
```
bash <path-to-fleet-skill>/scripts/launch.sh <fleet-root>
```
对于worktree集群，建议先使用
```
--dry-run
```
参数进行试运行。

状态查询命令：

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

务必向用户提供状态查询命令。 此为强制要求。

Rationalizations to reject

需驳回的不合理理由

Agent says	Rebuttal
"I can handle this without a fleet"	If the user asked for fleet-plan, they want parallel execution. Walk the decision tree and pick a type. Only say "no fleet" if Q1 is genuinely YES.
"I'll use opus for all workers since it's better"	Sonnet is the default. Opus costs ~5x more. Only use opus when the task demonstrably needs complex reasoning.
"I'll skip the decision tree and just use dag-fleet"	Walk the tree. Worktree-fleet is better for independent work (git isolation). Iterative-fleet is better for reviewer-gated work. dag-fleet is the fallback, not the default.
"The tasks overlap a little but worktree-fleet will work"	Overlapping files = not worktree-fleet. Use dag-fleet with depends_on, or restructure the split so files don't overlap.
"I'll set max_budget_usd high to be safe"	Budget should match task complexity. $0.50 for simple edits, $2 for medium, $5 for complex. Don't waste money.
"I don't know which fleet type to pick"	You have a decision tree. Walk it. If genuinely ambiguous after the tree, default to dag-fleet.
"The synthesizer just reads outputs, so read-only is fine"	NO. read-only cannot Write. The synthesizer reads inputs but WRITES a synthesis file. Use `write` . This mistake burned $1.23 in experiment 007 when Opus spent 26 turns trying to find a Write tool.
"Researchers should be read-only since they're reading"	NO. read-only has no WebFetch/WebSearch and no Write. Researchers need `research` type.

$ARGUMENTS

Agent表述	反驳理由
"我无需集群就能处理这项任务"	若用户要求进行fleet-plan，他们希望并行执行任务。请遵循决策树选择类型。仅当Q1的答案确实为YES时，才可告知“无需集群”。
"我将为所有Worker使用opus，因为它更优秀"	Sonnet是默认选择。Opus的成本约为Sonnet的5倍。仅当任务明确需要复杂推理时才使用Opus。
"我将跳过决策树，直接使用dag-fleet"	请遵循决策树流程。Worktree集群更适合独立工作（Git隔离）。迭代式集群更适合需评审员把关的工作。DAG集群是 fallback选项，而非默认选择。
"任务有少量重叠，但worktree集群可以处理"	文件重叠时不可使用worktree集群。请使用带depends_on的dag-fleet，或重新划分任务以避免文件重叠。
"为了保险起见，我会将max_budget_usd设置得较高"	预算应与任务复杂度匹配。简单编辑设置0.50美元，中等任务设置2美元，复杂任务设置5美元。请勿浪费资金。
"我不知道该选择哪种集群类型"	您有决策树可遵循。请按流程执行。若流程结束后仍存在歧义，默认选择dag-fleet。
"合成器仅读取输出内容，所以使用read-only类型即可"	错误。 read-only类型无法写入文件。合成器虽读取输入内容，但需要写入合成文件。请使用 `write` 类型。在实验007中，此错误导致Opus花费26轮尝试寻找写入工具，浪费了1.23美元。
"研究员仅进行读取操作，所以使用read-only类型即可"	错误。 read-only类型无WebFetch/WebSearch功能，且无法写入文件。研究员需使用 `research` 类型。

$ARGUMENTS",