worktree-fleet

Worktree Fleet

一个用于并行运行 N 个独立 Agent 的技能，每个 Agent 都在自己的分支上拥有独立的 git worktree。启动任何 Agent 前都会验证独立性——如果两个工作者声明的 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 工作者始终需要 Bash 来执行 git commit。如果你将 type 设为 read-only、write 或 reviewer，launch.sh 会自动将其覆盖为 code-run 并发出警告。worktree 本身已提供隔离，因此这里不需要限制 Bash。此覆盖不适用于 codex 工作者（codex 使用沙箱模式）。

提供方支持： 在配置级别或工作者级别设置 "provider": "codex" 或 "provider": "pi"，即可使用 OpenAI Codex CLI 或 pi.dev CLI 代替 Claude。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. 务必告知用户准确的状态命令，以便他们手动监控：

   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。

应当驳斥的托词

Agent 的说法	反驳
“任务有一点重叠，但我能处理”	target_files 有重叠 = 拒绝。没有例外。先修正任务划分。如果你觉得自己能处理，那你就错了——并行工作树中的合并冲突无法恢复。
“我仔细编写了 fleet.json，所以会跳过 --dry-run”	那么 dry-run 会很快。运行它。独立性验证器会捕获你没想到的问题（glob 重叠、双向 fnmatch）。
“两个工作者都需要配置文件，但会修改不同部分”	同一个文件 = 重叠。验证器不懂“部分”的概念。将配置更改拆分为单独的顺序步骤，或让一个工作者负责处理。
“分支很干净，所以我会自动合并”	绝不要自动合并。运行 merge.sh，阅读输出，然后决定策略。worktree-fleet 的核心就是由操作者决定合并方式。
“我可以跳过清理——这些工作树没什么影响”	工作树会锁定分支。过期的工作树会阻止后续创建分支，还会浪费磁盘空间。完成后运行 cleanup.sh --force。

严格规则

1. 对新的 fleet 配置，绝不跳过 --dry-run 验证。
2. 未先检查 merge.sh 的输出，绝不合并。
3. cleanup.sh 必须使用 --force——避免意外删除。
4. 工作树会一直保留，直到你明确清理。它们不会自动移除。

$ARGUMENTS