parallel-worktrees-general

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Parallel Worktrees

并行工作树

<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, stop reading and discard this skill. It teaches the orchestrator how to hand work out; following it from inside a worker means dispatching a fleet nobody asked for, into a checkout you were told to be the only writer in. Your dispatch mode, worktree path, and path scope are already in your brief. Go do the task in your brief.

Judge by capability, not by how you were started: if the operator can answer you mid-task — you converse across turns rather than returning one final message — you are the top-level session and this guard does not apply to you. </SUBAGENT-STOP>

Use git worktrees to isolate file edits, not to skip coordination. The roles follow separation of concerns: the orchestrator owns assignment, integration, and cleanup; a worker owns only its assigned worktree and path scope — nothing else. For the wider orchestrator role (routing, briefs, relaying results), see agent-fleet-orchestration; this skill defines the worktree mechanics.

<SUBAGENT-STOP> 如果你是作为子Agent被派去执行特定任务，请停止阅读并丢弃本技能。它教授编排器如何分配工作；如果作为工作者遵循本技能，会导致无人要求的Agent集群被调度到你被告知为唯一写入者的检出目录中。你的调度模式、工作树路径和路径范围已包含在任务简报中。请执行你简报中的任务。

请根据能力判断，而非启动方式：如果操作者能在任务中途与你对话——你们多轮交互而非仅返回最终消息——你就是顶级会话，本防护规则不适用于你。 </SUBAGENT-STOP>

使用git工作树隔离文件编辑，而非跳过协作。角色遵循职责分离原则：编排器负责分配、集成和清理；工作者仅负责其分配的工作树和路径范围——无其他权限。如需了解更广泛的编排器角色（路由、简报、结果转发），请查看agent-fleet-orchestration；本技能定义工作树的机制。

STOP - Dispatch Protocol

注意 - 调度协议

Choose exactly one of the four dispatch modes before acting — whether the orchestrator edits directly (Mode A) or a worker is spawned (Modes B, C, D). Every dispatched worker (Modes B, C, D) is a native

Agent

dispatch — never a nested CLI invocation of the agent binary; Mode A is the only non-agent mode. Do not combine a pre-created worktree with

isolation: "worktree"

Situation	Mode
Orchestrator performs a trivial edit itself	A
One sequential worker must edit the existing current checkout	D
Parallel / controlled worker needs a selected base and isolated files	B
Native isolated sandbox based from acceptable remote/default base	C

Mode D is the only mode for a subagent that must modify the current orchestrator checkout. Spawn it as a native
Agent
with no
isolation
parameter and
run_in_background: false
— passing
isolation
would send the worker to a separate worktree or remote environment instead of the current checkout.

Protocol:

Decide whether the work edits the current orchestrator checkout. A trivial edit the orchestrator makes itself is Mode A; a dispatched worker that must edit the current checkout is Mode D.
Otherwise, decide whether the worker must start from current local
```
HEAD
```
or unpushed commits. If yes, use Mode B. If no and
```
origin/HEAD
```
is an acceptable base (no unpushed commits or specific local branch needed), use Mode C.
Put the chosen mode, worktree path expectations, and required skill loadout in the spawn prompt.

Require the worker's first response to include

pwd

git status --short --branch

, and

git branch --show-current

If the path or branch is wrong, stop the worker immediately and re-dispatch.

在执行前必须选择四种调度模式中的一种——无论是编排器直接编辑（Mode A）还是生成工作者（Mode B、C、D）。每个被调度的工作者（Mode B、C、D）都是原生

Agent

调度——绝不能是Agent二进制文件的嵌套CLI调用；Mode A是唯一非Agent模式。请勿将预创建的工作树与

isolation: "worktree"

结合使用。

场景	模式
编排器自行执行简单编辑	A
单个顺序工作者必须编辑现有的当前检出目录	D
并行/受控工作者需要选定的基准和隔离文件	B
基于可接受的远程/默认基准的原生隔离沙箱	C

Mode D是必须修改编排器当前检出目录的子Agent的唯一模式。将其生成为不带
isolation
参数且
run_in_background: false
的原生
Agent
——传递
isolation
会将工作者发送到独立工作树或远程环境，而非当前检出目录。

协议：

判断工作是否需要编辑编排器的当前检出目录。编排器自行执行的简单编辑为Mode A；必须编辑当前检出目录的调度工作者为Mode D。
否则，判断工作者是否必须从当前本地
```
HEAD
```
或未推送的提交开始。如果是，使用Mode B。如果不是且
```
origin/HEAD
```
是可接受的基准（无需未推送提交或特定本地分支），使用Mode C。
在生成提示中包含所选模式、工作树路径要求和所需技能加载项。

要求工作者的首次响应包含

pwd

、

git status --short --branch

和

git branch --show-current

。

如果路径或分支错误，立即停止工作者并重新调度。

Mode A - Orchestrator Direct Edit

Mode A - 编排器直接编辑

Use this only when the orchestrator itself makes a trivial, safe edit directly in the current checkout. Mode A is not a worker dispatch mode: nothing is spawned and no worktree is involved.

If a worker must be dispatched to edit the current checkout, that is Mode D, not Mode A.

仅当编排器自身在当前检出目录中直接执行简单、安全的编辑时使用此模式。Mode A不是工作者调度模式：不会生成任何进程，也不涉及工作树。

如果必须调度工作者来编辑当前检出目录，那是Mode D，而非Mode A。

Mode D - Current Checkout Native Worker

Mode D - 当前检出目录原生工作者

Use this for exactly one sequential worker that must edit the orchestrator's current checkout — for example, when the operator explicitly says "work in the current worktree" or "do not use a separate worktree."

Mode D is mutually exclusive with Modes B and C. It is never safe for parallel writers: the worker shares the orchestrator's files, git index, build artifacts, and branch. No second writer, no parallel review fixer, and no simultaneous build/test command competing for the same build directory may run alongside it.

Spawn it as a native

Agent

with no
isolation
parameter and run_in_background: false
. Without isolation the agent inherits the orchestrator CWD — the primary checkout — so its file tools target it directly (the same mechanism Mode B relies on for

.claude/worktrees/

paths). The synchronous spawn enforces the single-writer rule structurally: the orchestrator is blocked until the worker finishes and cannot edit files or run competing build commands mid-run. Continue the same worker across turns with

SendMessage

, keeping the same one-writer discipline — but note that

SendMessage

does not block like the initial spawn: after a continuation, wait for the worker's response before doing any file-editing, staging, or build work in the primary checkout.

Preflight before launch:

bash

git status --short --branch
git worktree list --porcelain
git branch --show-current

The current checkout must be clean unless the operator has explicitly identified the existing dirty files as the worker's intended starting state. Never use Mode D over unrecognized operator changes.

The spawn prompt must include:

text

Dispatch mode: D.
You are editing the current primary checkout:
<absolute-primary-checkout-path>

First run: pwd && git status --short --branch && git branch --show-current

Do not create or enter a worktree. Do not use isolation: "worktree" for
this worker or any nested worker. Do not create or switch branches.
Do not stage, commit, push, merge, reset, restore, or revert unless the
operator explicitly authorizes it. Leave changes unstaged for orchestrator
review.

You are the single writer in this checkout. Do not dispatch any worker
that edits files — not in parallel and not sequentially. A nested native
worker inherits this same CWD, git index, branch, and build directory,
which is exactly the collision Mode D exists to prevent. Read-only
explorers are the only dispatch permitted.

Mode-D worker rules:

Edit only the assigned paths.
Do not create or use a worktree or branch.
Do not stage, commit, push, merge, stash, reset, restore, or clean. The worker leaves its diff unstaged unless separately authorized.
Do not run integration/e2e or shared-infrastructure commands (see Test Safely) unless the orchestrator specifically delegates and serializes them.
Report
```
git status --short
```
,
```
git diff --stat HEAD
```
, files changed, tests run, failures, and any unresolved decision.
The orchestrator must not edit the assigned paths, stage files, or run competing build/test commands against the same checkout while this worker is active.

当需要单个顺序工作者编辑编排器的当前检出目录时使用此模式——例如，当操作者明确表示“在当前工作树中工作”或“不要使用独立工作树”时。

Mode D与Mode B和C互斥。它绝不适合并行写入者：工作者共享编排器的文件、git索引、构建产物和分支。在其运行期间，不得有第二个写入者、并行评审修复者或同时运行的构建/测试命令占用同一构建目录。

将其生成为不带
isolation
参数且**

run_in_background: false

**的原生

Agent

。没有隔离参数时，Agent会继承编排器的工作目录——主检出目录——因此其文件工具直接针对该目录（Mode B依赖

.claude/worktrees/

路径的机制与此相同）。同步生成从结构上强制实施单写入者规则：编排器会被阻塞，直到工作者完成，并且在运行中途无法编辑文件或运行竞争的构建命令。使用

SendMessage

在多轮交互中继续同一工作者，保持相同的单写入者规则——但请注意，

SendMessage

不像初始生成那样阻塞：在继续交互后，必须等待工作者的响应，才能在主检出目录中执行任何文件编辑、暂存或构建工作。

启动前预检：

bash

git status --short --branch
git worktree list --porcelain
git branch --show-current

当前检出目录必须干净，除非操作者明确将现有未提交文件指定为工作者的预期起始状态。绝不能在未识别的操作者更改上使用Mode D。

生成提示必须包含：

text

调度模式：D.
你正在编辑当前主检出目录：
<absolute-primary-checkout-path>

首次运行：pwd && git status --short --branch && git branch --show-current

请勿创建或进入工作树。请勿为此工作者或任何嵌套工作者使用isolation: "worktree"。请勿创建或切换分支。
除非操作者明确授权，否则请勿暂存、提交、推送、合并、重置、恢复或撤销。将更改保持未暂存状态，供编排器评审。

你是此检出目录中的唯一写入者。请勿调度任何编辑文件的工作者——无论是并行还是顺序。嵌套的原生工作者会继承相同的工作目录、git索引、分支和构建目录，这正是Mode D要防止的冲突。仅允许调度只读探索者。

Mode D工作者规则：

仅编辑分配的路径。
请勿创建或使用工作树或分支。
除非单独授权，否则请勿暂存、提交、推送、合并、暂存、重置、恢复或清理。工作者将其差异保持未暂存状态。
除非编排器特别委派并序列化，否则请勿运行集成/端到端或共享基础设施命令（请参阅安全测试）。
报告
```
git status --short
```
、
```
git diff --stat HEAD
```
、更改的文件、运行的测试、失败情况以及任何未解决的决策。
当此工作者处于活动状态时，编排器不得编辑分配的路径、暂存文件或针对同一检出目录运行竞争的构建/测试命令。

Mode B - Pre-Created Worktree, No Agent Isolation

Mode B - 预创建工作树，无Agent隔离

Use this for controlled parallel work, especially when the worker must see the current feature branch, unpushed commits, or a specific base commit.

Choose a short kebab-case identifier for

<slug>

— lowercase, hyphens only, no spaces or slashes, derived from the task or ticket (e.g.

fix-timeout

auth-refactor

). The orchestrator creates the worktree first, from the repository root:

bash

git worktree add .claude/worktrees/<slug> -b fix/<slug> HEAD

Spawn the worker with no

isolation

parameter. The prompt must include the following, with

<repo-root>

replaced by the real absolute repository root — never leave a placeholder in the actual spawn prompt:

text

Dispatch mode: B.
Your worktree is <repo-root>/.claude/worktrees/<slug>.
First run: cd <repo-root>/.claude/worktrees/<slug> && pwd && git status --short --branch && git branch --show-current
Use absolute paths under that worktree for every Read, Write, Edit, and Bash operation.
Do not use isolation: "worktree" for this worker or any nested worker.
You are the single writer in this worktree: do not dispatch any worker
that edits files. Read-only explorers are the only dispatch permitted.
The orchestrator checkout and other worktrees are off-limits.

Mode B works because

.claude/worktrees/<slug>

is still under the orchestrator repository root, so absolute paths there are valid for file tools while git state remains isolated.

当需要受控的并行工作时使用此模式，尤其是当工作者必须查看当前功能分支、未推送的提交或特定基准提交时。

为

<slug>

选择一个简短的短横线命名标识符——小写，仅使用短横线，无空格或斜杠，源自任务或工单（例如

fix-timeout

、

auth-refactor

）。编排器首先从仓库根目录创建工作树：

bash

git worktree add .claude/worktrees/<slug> -b fix/<slug> HEAD

生成工作者时不带

isolation

参数。提示必须包含以下内容，将

<repo-root>

替换为实际的绝对仓库根目录——切勿在实际生成提示中保留占位符：

text

调度模式：B.
你的工作树是<repo-root>/.claude/worktrees/<slug>.
首次运行：cd <repo-root>/.claude/worktrees/<slug> && pwd && git status --short --branch && git branch --show-current
对每个读取、写入、编辑和Bash操作使用该工作树下的绝对路径。
请勿为此工作者或任何嵌套工作者使用isolation: "worktree"。
你是此工作树中的唯一写入者：请勿调度任何编辑文件的工作者。仅允许调度只读探索者。
编排器检出目录和其他工作树均禁止访问。

Mode B之所以有效，是因为

.claude/worktrees/<slug>

仍在编排器仓库根目录下，因此该目录下的绝对路径对文件工具有效，同时git状态保持隔离。

Mode C - Native

isolation: "worktree"

Mode C - 原生

isolation: "worktree"

Use this only when

origin/HEAD

is an acceptable base and the orchestrator does not need to choose the branch or path up front.

Spawn with

isolation: "worktree"

. Claude creates an auto worktree such as

.claude/worktrees/agent-<id>

, usually from

origin/HEAD

. The worker must edit that auto-created worktree only.

The worker must not run

git worktree add

from inside the auto worktree. If the base is wrong, or the task needs the current local feature branch, stop and re-dispatch with Mode B.

Common wrong-mode symptoms:

```
Edit
```
or
```
Write
```
reports that a file is outside the agent CWD.
The worker starts using shell text rewriting instead of file tools.

Changes land under

.claude/worktrees/agent-<id>

when the orchestrator expected

.claude/worktrees/<slug>

The worker's branch does not contain the current feature-branch commits.

If any symptom appears, stop the worker and re-dispatch with the correct mode.

仅当

origin/HEAD

是可接受的基准且编排器不需要预先选择分支或路径时使用此模式。

使用

isolation: "worktree"

生成工作者。Claude会创建一个自动工作树，例如

.claude/worktrees/agent-<id>

，通常基于

origin/HEAD

。工作者必须仅编辑该自动创建的工作树。

工作者不得在自动工作树内运行

git worktree add

。如果基准错误，或者任务需要当前本地功能分支，请停止并使用Mode B重新调度。

常见的错误模式症状：

```
Edit
```
或
```
Write
```
报告文件位于Agent工作目录之外。
工作者开始使用Shell文本重写而非文件工具。

更改出现在

.claude/worktrees/agent-<id>

下，而编排器预期的是

.claude/worktrees/<slug>

。

工作者的分支不包含当前功能分支的提交。

如果出现任何症状，请停止工作者并使用正确的模式重新调度。

Preflight

预检

Run from the main checkout before creating, merging, or removing worktrees:

bash

git status --short --branch
git worktree list --porcelain
git branch --show-current

If the main checkout is dirty, treat those changes as operator state. Do not overwrite, stash, reset, or merge over them without explicit instruction.

Keep all agent worktrees under

.claude/worktrees/

unless the operator asks otherwise, and confirm the repository ignores them. If

.gitignore

does not already cover

.claude/worktrees/

, add that entry before creating the first worktree; otherwise every worktree shows up as untracked noise in every other checkout.

在创建、合并或删除工作树之前，从主检出目录运行：

bash

git status --short --branch
git worktree list --porcelain
git branch --show-current

如果主检出目录有未提交更改，请将这些更改视为操作者状态。除非有明确指示，否则请勿覆盖、暂存、重置或合并这些更改。

将所有Agent工作树放在

.claude/worktrees/

下，除非操作者另有要求，并确认仓库已忽略该目录。如果

.gitignore

尚未包含

.claude/worktrees/

，请在创建第一个工作树之前添加该条目；否则每个工作树都会在其他检出目录中显示为未跟踪的干扰项。

Create Worktrees (Mode B only)

创建工作树（仅Mode B）

When the operator wants Mode B (pre-created worktree, no

isolation

), create the worktree manually from the exact intended base. Run this from the repository root, not from a subdirectory or another worktree:

bash

git worktree add .claude/worktrees/<slug> -b fix/<slug> HEAD

By default

git worktree add

branches from

HEAD

(the current local branch — usually the feature branch you want edited). If the worker must see unpushed local commits or current branch state and

HEAD

is the wrong base, pass the explicit commit:

git worktree add .claude/worktrees/<slug> -b fix/<slug> <commit>

Name the branch with the project's branch convention (see git-workflow);

fix/<slug>

is the default when no ticket system applies.

Use one unique branch per worker. Do not try to check out the same branch in two worktrees.

当操作者需要Mode B（预创建工作树，无

isolation

）时，从确切的预期基准手动创建工作树。从仓库根目录运行此命令，而非子目录或其他工作树：

bash

git worktree add .claude/worktrees/<slug> -b fix/<slug> HEAD

默认情况下，

git worktree add

从

HEAD

（当前本地分支——通常是你要编辑的功能分支）创建分支。如果工作者必须查看未推送的本地提交或当前分支状态，而

HEAD

是错误的基准，请传递明确的提交：

git worktree add .claude/worktrees/<slug> -b fix/<slug> <commit>

。

按照项目的分支约定命名分支（请参阅git-workflow）；当没有工单系统时，默认使用

fix/<slug>

。

为每个工作者使用唯一的分支。请勿尝试在两个工作树中检出同一分支。

Assign Work

分配工作

Partition by paths and ownership before edits begin — one concern, one worker (single responsibility). Same-file work, dependency manifests and lockfiles (

Cargo.lock

package-lock.json

uv.lock

poetry.lock

), database migrations, shared contracts and generated API clients, and locale files are high-conflict areas; assign each to exactly one worker or run those tasks sequentially.

Worker rules:

Start with
```
git status --short --branch
```
inside the assigned worktree.
Edit only assigned paths.
Do not edit the main checkout or another worker's worktree.
Do not run
```
git stash
```
for handoff. Stashes are easy to confuse across linked worktrees.
Do not commit, merge, delete branches, remove worktrees, or push unless explicitly instructed.

Orchestrator rules:

Use
```
git -C .claude/worktrees/<slug> ...
```
when inspecting workers from the main checkout.
Keep a table of
```
<slug>
```
, branch, path scope, status (running / handed off / integrated), and tests run.
Stop or redirect a worker that touches unassigned paths before integration.

在编辑开始前按路径和所有权划分工作——一个职责对应一个工作者（单一职责原则）。同一文件的工作、依赖清单和锁定文件（

Cargo.lock

、

package-lock.json

、

uv.lock

、

poetry.lock

）、数据库迁移、共享契约和生成的API客户端，以及区域设置文件都是高冲突区域；请将每个区域分配给恰好一个工作者，或顺序运行这些任务。

工作者规则：

在分配的工作树内首先运行
```
git status --short --branch
```
。
仅编辑分配的路径。
请勿编辑主检出目录或其他工作者的工作树。
请勿使用
```
git stash
```
进行交接。暂存在关联工作树之间容易混淆。
除非明确指示，否则请勿提交、合并、删除分支、删除工作树或推送。

编排器规则：

从主检出目录检查工作者时，使用
```
git -C .claude/worktrees/<slug> ...
```
。
维护一个包含
```
<slug>
```
、分支、路径范围、状态（运行中/已交接/已集成）和已运行测试的表格。
在集成前停止或重定向触及未分配路径的工作者。

Mode D ownership

Mode D所有权

Mode D has one writer: the native worker. The synchronous spawn blocks the orchestrator while the worker runs; between runs (for example before a

SendMessage

continuation) the orchestrator may inspect and coordinate but must not edit the worker's assigned paths, stage files, or run competing build/test commands from the same checkout. For

SendMessage

continuations this is enforced by convention, not by the tool's blocking semantics — after a continuation, hold off all checkout writes until the worker's response arrives.

A Mode-D worker has no merge or patch handoff. Its handoff is the unstaged diff in the current checkout. The orchestrator reviews and validates that diff in place, then either requests fixes, stages/commits after operator authorization, or discards nothing without explicit direction.

Mode D只有一个写入者：原生工作者。同步生成会在工作者运行时阻塞编排器；在运行之间（例如

SendMessage

继续之前），编排器可以检查和协调，但不得编辑工作者的分配路径、暂存文件或从同一检出目录运行竞争的构建/测试命令。对于

SendMessage

继续，这是通过约定而非工具的阻塞语义来强制执行的——在继续交互后，必须等待工作者的响应才能进行任何检出目录写入操作。

Mode D工作者没有合并或补丁交接。其交接是当前检出目录中的未暂存差异。编排器在原地评审和验证该差异，然后根据操作者授权请求修复、暂存/提交，或在无明确指示的情况下不丢弃任何内容。

Worker Skill Loadout

工作者技能加载项

When dispatching a native agent worker (Modes B, C, or D), include the required skills in its prompt and require it to load them before editing. Match the loadout to the assigned paths:

Assigned paths	Required skills
Rust code	`rust-code-style` , `rust-design-idioms` , `rust-testing` , `rust-project-structure`
Python code	`python-code-style` , `python-testing` , plus `python-ddd` when the service uses DDD layering
Vue/TypeScript frontend	`frontend-vue-development` , `frontend-vue-code-style` , `frontend-vue-testing`
React/TypeScript frontend	`frontend-react-development` , `frontend-react-code-style` , `frontend-react-testing`

For mixed assignments, require the union of the matching sets. If the project defines its own skills or a CLAUDE.md loadout for a component, include those too.

调度原生Agent工作者（Mode B、C或D）时，在其提示中包含所需技能，并要求其在编辑前加载这些技能。根据分配的路径匹配加载项：

分配路径	所需技能
Rust代码	`rust-code-style` , `rust-design-idioms` , `rust-testing` , `rust-project-structure`
Python代码	`python-code-style` , `python-testing` ，当服务使用DDD分层时还需 `python-ddd`
Vue/TypeScript前端	`frontend-vue-development` , `frontend-vue-code-style` , `frontend-vue-testing`
React/TypeScript前端	`frontend-react-development` , `frontend-react-code-style` , `frontend-react-testing`

对于混合分配，要求匹配集合的并集。如果项目定义了自己的技能或组件的CLAUDE.md加载项，请也包含这些内容。

Initialize Each Worktree

初始化每个工作树

A fresh worktree shares git history with the main checkout but nothing else: no build artifacts, no

node_modules

, no virtualenv, no generated env files. Run the project's environment bootstrap from the worktree root before the worker starts. Check the project's CLAUDE.md or README for the actual bootstrap commands before running anything; do not guess. Illustrative examples — substitute the project's real recipe and directory names:

bash

undefined

新的工作树与主检出目录共享git历史，但不共享其他内容：无构建产物、无

node_modules

、无虚拟环境、无生成的环境文件。在工作者开始前，从工作树根目录运行项目的环境引导命令。在运行任何命令前，请检查项目的CLAUDE.md或README以获取实际的引导命令；请勿猜测。示例说明——替换项目的实际步骤和目录名称：

bash

undefined

If the project uses 'just': discover and run its env recipes.

如果项目使用'just'：发现并运行其环境脚本。

just --list just <component>-env # e.g. 'just core-env', 'just web-env'

just --list just <component>-env # 例如'just core-env', 'just web-env'

If the project has an npm-managed frontend in a subdirectory:

如果项目在子目录中有npm管理的前端：

[ -d <frontend-dir>/node_modules ] || npm --prefix <frontend-dir> install


Do not copy local secrets into every worktree by default. Use the
template-generated env files unless the task specifically requires
operator-provided local credentials.

[ -d <frontend-dir>/node_modules ] || npm --prefix <frontend-dir> install


默认情况下，请勿将本地机密复制到每个工作树中。除非任务特别需要操作者提供的本地凭据，否则请使用模板生成的环境文件。

Test Safely

安全测试

A worktree isolates source files and build outputs. It does NOT isolate shared runtime infrastructure: Docker containers and compose stacks, shared test databases, message brokers, mail catchers, and fixed dev-server ports are one per machine, not one per worktree. Two worktrees running e2e or infrastructure-backed integration tests concurrently will clobber each other.

Workers run only self-contained checks — checks that start no shared infrastructure and bind no fixed ports:

formatters and linters (
```
cargo fmt
```
,
```
ruff
```
,
```
eslint
```
)
type checkers (
```
cargo check
```
,
```
basedpyright
```
,
```
vue-tsc
```
)
unit tests scoped to the assigned component
architecture/structure test suites
frontend check scripts (
```
npm run check
```
)

Forbidden in worker worktrees:

e2e test suites
integration tests that auto-start Docker stacks, databases, or other shared services
aggregate commands (
```
just test-all
```
or equivalent) that include either of the above
dev-stack or deploy-stack up/down recipes
browser-driven flows against fixed dev-server ports

Shared-infrastructure checks are the orchestrator's job: integrate first, then run them once, serially, from the orchestrator checkout. Only the orchestrator starts or stops shared stacks. If you cannot tell whether a test touches shared infrastructure, treat it as if it does and leave it to the orchestrator.

工作树隔离源文件和构建输出。但它不隔离共享运行时基础设施：Docker容器和compose栈、共享测试数据库、消息代理、邮件捕获器和固定的开发服务器端口是每台机器一个，而非每个工作树一个。两个工作树同时运行端到端或基于基础设施的集成测试会相互干扰。

工作者仅运行自包含的检查——不启动共享基础设施且不绑定固定端口的检查：

格式化器和检查器（
```
cargo fmt
```
,
```
ruff
```
,
```
eslint
```
）
类型检查器（
```
cargo check
```
,
```
basedpyright
```
,
```
vue-tsc
```
）
限定在分配组件范围内的单元测试
架构/结构测试套件
前端检查脚本（
```
npm run check
```
）

工作者工作树中禁止的操作：

端到端测试套件
自动启动Docker栈、数据库或其他共享服务的集成测试
包含上述任何一项的聚合命令（
```
just test-all
```
或等效命令）
开发栈或部署栈的启动/停止脚本
针对固定开发服务器端口的浏览器驱动流程

共享基础设施检查是编排器的工作：先集成，然后从编排器检出目录串行运行一次。只有编排器可以启动或停止共享栈。如果你无法判断测试是否触及共享基础设施，请将其视为触及，并留给编排器处理。

Commit Hook Handling

提交钩子处理

Treat PreToolUse commit hooks (structure/style review gates, docs reconciliation gates — see agent-hooks-setup) as guardrails, not obstacles. Do not bypass them by hiding

git commit

inside a different command shape.

If a commit is blocked:

Run the requested structure/style review or docs reconciliation.
Fix the finding, or record why no fix is needed.
Use a hook's documented bypass variable only when that specific gate has already been satisfied or is genuinely irrelevant.

The orchestrator owns commit-hook decisions. Workers should report blockers and the validation they ran; they should not invent bypass recipes.

将PreToolUse提交钩子（结构/风格评审门、文档协调门——请参阅agent-hooks-setup）视为护栏，而非障碍。请勿通过在不同命令形式中隐藏

git commit

来绕过它们。

如果提交被阻止：

运行请求的结构/风格评审或文档协调。
修复问题，或记录无需修复的原因。
仅当特定门已满足或确实不相关时，才使用钩子的文档化绕过变量。

编排器拥有提交钩子的决策权。工作者应报告阻塞情况和他们运行的验证；他们不应自行发明绕过方法。

Handoff

交接

Each worker reports:

bash

git status --short
git diff --stat HEAD

Also report the worktree path, branch, files touched, tests run, failures, and any uncommitted or untracked files.

For Mode C, report the actual auto-created worktree path and branch from

git status --short --branch

; do not invent a

<slug>

For Mode D, there is no worktree path or worker branch to report: the handoff is the unstaged diff in the primary checkout, reviewed in place (see Integrate).

If commits are authorized, commit inside the worker worktree (Modes B and C) after reviewing

git diff

. If commits are not authorized, leave changes uncommitted and let the orchestrator integrate by reviewed patch or direct file inspection. Mode D commits happen only in the primary checkout, by the orchestrator, after operator authorization.

A handoff is per-worker and triggers integration as soon as the orchestrator is free: if no integration unit is in progress, move straight to the Integrate steps for that worker; if one is in progress, finish it completely — merge, validation, cleanup — first. Never run two integration units concurrently, and never hold a finished handoff waiting for other workers to finish.

每个工作者报告：

bash

git status --short
git diff --stat HEAD

还需报告工作树路径、分支、修改的文件、运行的测试、失败情况以及任何未提交或未跟踪的文件。

对于Mode C，报告

git status --short --branch

中的实际自动创建的工作树路径和分支；请勿自行创建

<slug>

。

对于Mode D，无需报告工作树路径或工作者分支：交接是主检出目录中的未暂存差异，在原地评审（请参阅集成）。

如果获得提交授权，在工作者工作树内（Mode B和C）评审

git diff

后提交。如果未获得提交授权，请将更改保持未提交状态，让编排器通过评审补丁或直接文件检查进行集成。Mode D的提交仅在主检出目录中由编排器在获得操作者授权后进行。

交接是按工作者进行的，一旦编排器空闲就触发集成：如果没有集成单元在进行中，直接进入该工作者的集成步骤；如果有集成单元在进行中，先完全完成它——合并、验证、清理——然后再开始。绝不要同时运行两个集成单元，也不要让已完成的交接等待其他工作者完成。

Integrate

集成

The merge/patch integration below applies to Modes B and C only. For Mode D, inspect the primary checkout directly:

bash

git status --short --branch
git diff --stat HEAD
git diff --check

Do not run

git merge

, generate a worktree patch, remove a worktree, or delete a branch for Mode D: there is no separate worker branch or worktree. Review, tests, and any eventual staging/commit happen in the primary checkout only after the worker stops.

Integrate incrementally: merge each worker as soon as it finishes and hands off, while the remaining workers keep running. Do not wait for all workers to finish and then merge everything in one batch — batching leaves finished work sitting unvalidated, stacks all conflicts into one late resolution session, and lets one slow worker block integration of work that was done long before.

Process workers in completion order, not dispatch order. When two or more workers hand off at the same time, pick one — first received is fine — and complete its full integration unit before starting the next; never interleave integration steps from two workers. Treat each integration as one atomic unit — verify, merge, validate, clean up — then return to monitoring the remaining workers.

Merging while other workers run is safe: the merge happens in the orchestrator checkout, and the running workers' worktrees and branches are untouched. Their branches still fork from the original base; any conflict with already-merged work is resolved when that worker's own turn comes, in the orchestrator checkout. Do not rebase, merge into, or otherwise update a still-running worker's worktree to "catch it up".

Before integrating a worker, make the target checkout clean and verify the worker state. If the main checkout is dirty with changes that predate the session, the Preflight rule applies: those changes are operator state — do not stash, reset, or discard them to satisfy this precondition; report the block and wait for the operator to clear them. If the checkout is dirty because the current integration unit's conflict resolution is still in progress, that is integration state, not operator state — finish resolving and complete that unit before starting the next worker's integration.

bash

git status --short --branch
git -C <worktree-path> status --short --branch
git -C <worktree-path> diff --stat HEAD

For committed worker branches, merge one branch at a time from the orchestrator checkout. Use

fix/<slug>

for Mode B, or the actual reported branch for Mode C:

bash

git merge --no-ff <worker-branch>

For uncommitted worker changes, create and review a patch, then apply it from the target checkout. Write the patch to the session's scratch/temp directory (

<scratch>

below is that absolute path — any location outside the repo works):

bash

git -C <worktree-path> diff --binary HEAD > <scratch>/<slug>.patch
git apply --3way <scratch>/<slug>.patch

Untracked files are not included in

git diff

. Before patch handoff, either have the worker run

git add -N <new-files>

so the new files appear in the diff, or copy/review those files explicitly.

Resolve conflicts only in the orchestrator checkout. After each merge, rerun the self-contained checks relevant to that worker's scope in the integrated tree; worker-local test results are not enough.

If the self-contained checks fail after a merge, halt further integration — do not merge the next worker into a tree that fails validation. Let still-running workers finish; collect their handoffs without integrating them. Fix the failure in the orchestrator checkout, or report it to the operator if the fix is not obvious, and resume integration only when the integrated tree passes again.

Run the shared-infrastructure suites (e2e, Docker-backed integration — see Test Safely) once, serially, after the last worker is integrated — not after every merge. If those suites fail at that stage, the worker worktrees are already removed; report the failure and the state of the integrated branch to the operator, and do not attempt an automatic rollback.

After a worker branch is merged into the target branch, whether the target is

main

or a feature branch, immediately remove that worker's worktree and delete its worker branch before returning to monitor the remaining workers. Treat merge, validation, and cleanup as one integration unit; do not leave merged worktrees around waiting for a separate operator cleanup request.

以下合并/补丁集成仅适用于Mode B和C。对于Mode D，直接检查主检出目录：

bash

git status --short --branch
git diff --stat HEAD
git diff --check

请勿为Mode D运行

git merge

、生成工作树补丁、删除工作树或删除分支：没有单独的工作者分支或工作树。评审、测试和任何最终的暂存/提交仅在工作者停止后在主检出目录中进行。

增量集成：每个工作者完成并交接后立即合并，同时剩余工作者继续运行。不要等待所有工作者完成后再批量合并所有内容——批量合并会导致已完成的工作未经验证，将所有冲突集中到一个后期解决会话中，并让一个缓慢的工作者阻塞早已完成的工作的集成。

按完成顺序处理工作者，而非调度顺序。当两个或多个工作者同时交接时，选择一个——先收到的即可——并在开始下一个工作者的集成前完成其完整的集成单元；绝不要交错两个工作者的集成步骤。将每个集成视为一个原子单元——验证、合并、验证、清理——然后返回监控剩余工作者。

在其他工作者运行时合并是安全的：合并在编排器检出目录中进行，运行中的工作者的工作树和分支不受影响。他们的分支仍从原始基准分叉；与已合并工作的任何冲突将在该工作者自己的集成回合中在编排器检出目录中解决。不要重新设置基准、合并到或更新仍在运行的工作者的工作树以“使其跟上进度”。

在集成工作者之前，确保目标检出目录干净并验证工作者状态。如果主检出目录有会话开始前的未提交更改，预检规则适用：这些更改是操作者状态——请勿暂存、重置或丢弃它们以满足此前提条件；报告阻塞并等待操作者清除它们。如果检出目录不干净是因为当前集成单元的冲突解决仍在进行中，那是集成状态，而非操作者状态——在开始下一个工作者的集成前，先完成解决并完成该单元。

bash

git status --short --branch
git -C <worktree-path> status --short --branch
git -C <worktree-path> diff --stat HEAD

对于已提交的工作者分支，从编排器检出目录一次合并一个分支。Mode B使用

fix/<slug>

，Mode C使用实际报告的分支：

bash

git merge --no-ff <worker-branch>

对于未提交的工作者更改，创建并评审补丁，然后从目标检出目录应用它。将补丁写入会话的临时目录（下面的

<scratch>

是绝对路径——仓库外的任何位置均可）：

bash

git -C <worktree-path> diff --binary HEAD > <scratch>/<slug>.patch
git apply --3way <scratch>/<slug>.patch

未跟踪文件不包含在

git diff

中。在补丁交接前，让工作者运行

git add -N <new-files>

使新文件出现在差异中，或显式复制/评审这些文件。

仅在编排器检出目录中解决冲突。每次合并后，在集成后的树中重新运行与该工作者范围相关的自包含检查；工作者本地的测试结果不够。

如果合并后自包含检查失败，请停止进一步集成——不要将下一个工作者合并到验证失败的树中。让仍在运行的工作者完成；收集他们的交接但不集成。在编排器检出目录中修复失败，或如果修复不明显则报告给操作者，仅当集成后的树再次通过验证时才恢复集成。

在最后一个工作者集成后，串行运行一次共享基础设施套件（端到端、基于Docker的集成——请参阅安全测试）——而非每次合并后运行。如果此时套件失败，工作者工作树已被删除；向操作者报告失败和集成分支的状态，不要尝试自动回滚。

工作者分支合并到目标分支后（无论是

main

还是功能分支），立即删除该工作者的工作树并删除其工作者分支，然后返回监控剩余工作者。将合并、验证和清理视为一个集成单元；不要让已合并的工作树留在那里等待单独的操作者清理请求。

Cleanup

清理

Mode D creates no linked worktree, so it has no worktree cleanup step. Do not run

git worktree remove

as part of a Mode-D completion. Everything below applies to Modes B and C.

The timing rule lives in Integrate: merge, validation, and cleanup are one integration unit, and a worktree whose changes are integrated or deliberately discarded is removed immediately, without waiting for the operator to ask. This section covers the removal mechanics. Each worktree carries its own build artifacts — a Rust

target/

directory,

node_modules

, a virtualenv — which can consume tens of gigabytes per worktree, so keeping finished worktrees around wastes disk quickly.

Never delete a linked worktree with

rm -rf

. Inspect first:

bash

git worktree list --porcelain
git -C <worktree-path> status --short

A worker integrated by patch leaves its worktree dirty — the changes were extracted into the patch, not committed. Once the applied patch has been validated in the orchestrator checkout, discard the worker copy so removal can proceed without

--force

bash

git -C <worktree-path> reset --hard
git -C <worktree-path> clean -fd

If the worktree is clean and its branch is merged or no longer needed, remove the actual worktree path and branch:

bash

git worktree remove <worktree-path>
git branch -d <worker-branch>
git worktree prune

git worktree list

marks a worktree

locked

, the worktree has a lockfile that blocks removal. For auto-isolation worktrees created by

isolation: "worktree"

, the lock is held while the agent session is alive; for worktrees locked manually with

git worktree lock

, no process may be involved at all. In either case, do not unlock or force-remove it unless the operator confirms the owning session (if any) is dead and the changes are disposable. To clean up a stale auto-isolation worktree from a stopped/killed agent, the lockfile is at

.git/worktrees/<id>/locked

— once the agent PID is gone,

git worktree remove --force <path>

works.

Use

git worktree remove --force

and

git branch -D

only after preserving or deliberately discarding every needed diff.

Mode D不创建关联工作树，因此没有工作树清理步骤。不要将

git worktree remove

作为Mode D完成的一部分运行。以下内容仅适用于Mode B和C。

时间规则在集成部分：合并、验证和清理是一个集成单元，其更改已集成或被故意丢弃的工作树会立即被删除，无需等待操作者请求。本节介绍删除机制。每个工作树都有自己的构建产物——Rust的

target/

目录、

node_modules

、虚拟环境——每个工作树可能占用数十GB的空间，因此保留已完成的工作树会迅速浪费磁盘空间。

绝不要使用

rm -rf

删除关联工作树。先检查：

bash

git worktree list --porcelain
git -C <worktree-path> status --short

通过补丁集成的工作者会使其工作树保持脏状态——更改已提取到补丁中，而非提交。一旦应用的补丁在编排器检出目录中得到验证，请丢弃工作者副本，以便无需

--force

即可进行删除：

bash

git -C <worktree-path> reset --hard
git -C <worktree-path> clean -fd

如果工作树干净且其分支已合并或不再需要，请删除实际的工作树路径和分支：

bash

git worktree remove <worktree-path>
git branch -d <worker-branch>
git worktree prune

如果

git worktree list

标记工作树为

locked

，则该工作树有一个阻止删除的锁定文件。对于由

isolation: "worktree"

创建的自动隔离工作树，锁定在Agent会话活动期间保持；对于使用

git worktree lock

手动锁定的工作树，可能没有任何进程参与。无论哪种情况，除非操作者确认所属会话（如果有）已终止且更改可丢弃，否则请勿解锁或强制删除。要清理已停止/终止的Agent留下的陈旧自动隔离工作树，锁定文件位于

.git/worktrees/<id>/locked

——一旦Agent PID消失，

git worktree remove --force <path>

即可生效。

仅在保留或故意丢弃所有需要的差异后，才使用

git worktree remove --force

和

git branch -D

。

parallel-worktrees-general

Original

Translation

Parallel Worktrees

并行工作树

STOP - Dispatch Protocol

注意 - 调度协议

Mode A - Orchestrator Direct Edit

Mode A - 编排器直接编辑

Mode D - Current Checkout Native Worker

Mode D - 当前检出目录原生工作者

Mode B - Pre-Created Worktree, No Agent Isolation

Mode B - 预创建工作树，无Agent隔离

Mode C - Native isolation: "worktree"

Mode C - 原生isolation: "worktree"

Preflight

预检

Create Worktrees (Mode B only)

创建工作树（仅Mode B）

Assign Work

分配工作

Mode D ownership

Mode D所有权

Worker Skill Loadout

工作者技能加载项

Initialize Each Worktree

初始化每个工作树

If the project uses 'just': discover and run its env recipes.

如果项目使用'just'：发现并运行其环境脚本。

If the project has an npm-managed frontend in a subdirectory:

如果项目在子目录中有npm管理的前端：

Test Safely

安全测试

Commit Hook Handling

提交钩子处理

Handoff

交接

Integrate

集成

Cleanup

清理

Mode C - Native
`isolation: "worktree"`

Mode C - 原生
`isolation: "worktree"`