git-worktrees

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Worktrees Skill

Git Worktrees 技能

Overview

概述

Create and manage isolated git worktrees for parallel development tasks.

为并行开发任务创建并管理独立的git worktree。

Triggers

触发条件

Activate this skill when:

Multiple tasks can run in parallel
User runs
```
/delegate
```
with parallelizable tasks
Need isolated environment for subagent work
User explicitly requests worktree setup

在以下场景激活此技能：

多个任务可并行运行
用户运行/delegate并带有可并行化的任务
需要为子Agent提供独立工作环境
用户明确请求设置worktree

Worktree Directory Location

Worktree 目录位置

Priority Order:

```
.worktrees/
```
- If exists and gitignored
```
worktrees/
```
- If exists and gitignored
Check
```
CLAUDE.md
```
for project conventions
Ask user if unclear

Safety Check (REQUIRED):

bash

undefined

优先级顺序：

```
.worktrees/
```
- 若存在且已被git忽略
```
worktrees/
```
- 若存在且已被git忽略
查看
```
CLAUDE.md
```
了解项目约定
若不明确则询问用户

安全检查（必填）：

bash

undefined

Verify directory is gitignored before creating

git check-ignore -q .worktrees && echo "Safe" || echo "NOT GITIGNORED"


If not gitignored, add to `.gitignore`:

.worktrees/

undefined

git check-ignore -q .worktrees && echo "Safe" || echo "NOT GITIGNORED"


如果未被git忽略，添加到`.gitignore`：

.worktrees/

undefined

Worktree Lifecycle

Worktree 生命周期

1. Create Worktree

1. 创建Worktree

bash

undefined

bash

undefined

Create feature branch

git branch feature/task-name main

Create worktree

git worktree add .worktrees/task-name feature/task-name

Verify creation

git worktree list


**Naming Convention:** `.worktrees/<task-id>-<brief-name>`
- Example: `.worktrees/001-user-auth`
- Example: `.worktrees/002-api-endpoints`

git worktree list


**命名规范：** `.worktrees/<task-id>-<brief-name>`
- 示例：`.worktrees/001-user-auth`
- 示例：`.worktrees/002-api-endpoints`

2. Setup Environment

2. 环境设置

See

references/commands-reference.md

for the full environment setup table and scripts per project type.

查看

references/commands-reference.md

获取完整的环境设置表格和各项目类型对应的脚本。

3. Baseline Verification

3. 基线验证

Run baseline tests to ensure the worktree is ready:

typescript

exarchos_orchestrate({
  action: "verify_worktree_baseline",
  worktreePath: ".worktrees/task-name"
})

The script auto-detects project type (Node.js, .NET, Rust) and runs the appropriate test command.

On
passed: true
: Baseline tests pass — worktree is ready for implementation. On
passed: false
: Baseline tests failed or unknown project type — investigate before proceeding.

If baseline fails:

Check if main branch has failing tests
Report issue to user
Do not proceed with implementation

运行基线测试确保worktree已就绪：

typescript

exarchos_orchestrate({
  action: "verify_worktree_baseline",
  worktreePath: ".worktrees/task-name"
})

该脚本会自动检测项目类型（Node.js、.NET、Rust）并运行相应的测试命令。

当
passed: true
时：基线测试通过 — worktree可开始开发工作。当
passed: false
时：基线测试失败或项目类型未知 — 先排查问题再继续。

若基线测试失败：

检查主分支是否存在测试失败情况
向用户报告问题
不要继续开发工作

4. Work in Worktree

4. 在Worktree中工作

Subagents work in worktree directory:

Full isolation from other tasks
Commits go to feature branch
Can run tests independently

子Agent在worktree目录中工作：

与其他任务完全隔离
提交记录归属于特性分支
可独立运行测试

5. Cleanup After Merge

5. 合并后清理

bash

undefined

bash

undefined

After PR merged, remove worktree

git worktree remove .worktrees/task-name

Optionally delete branch

git branch -d feature/task-name

Prune stale worktree refs

git worktree prune

undefined

git worktree prune

undefined

Parallel Worktree Management

并行Worktree管理

See

references/commands-reference.md

for parallel worktree creation examples, tracking format, and the full commands reference table.

查看

references/commands-reference.md

获取并行worktree创建示例、跟踪格式及完整命令参考表。

Worktree Validation

Worktree 验证

Why Validate?

为什么要验证？

Subagents MUST verify they're in a worktree before making changes. Working in the main project root causes:

Merge conflicts between parallel tasks
Accidental changes to shared state
Build/test interference

子Agent在修改文件前必须确认处于worktree环境中。在主项目根目录工作会导致：

并行任务间的合并冲突
意外修改共享状态
构建/测试互相干扰

Worktree Verification

Worktree 验证

Run the worktree verification script before any file modifications:

typescript

exarchos_orchestrate({
  action: "verify_worktree"
})

To check a specific path instead of the current directory:

typescript

exarchos_orchestrate({
  action: "verify_worktree",
  cwd: "/path/to/.worktrees/task-name"
})

On
passed: true
: In a valid worktree — proceed with implementation. On
passed: false
: NOT in a worktree — STOP immediately, do not modify files.

在修改任何文件前运行worktree验证脚本：

typescript

exarchos_orchestrate({
  action: "verify_worktree"
})

若要检查指定路径而非当前目录：

typescript

exarchos_orchestrate({
  action: "verify_worktree",
  cwd: "/path/to/.worktrees/task-name"
})

当
passed: true
时：处于有效的worktree环境 — 可继续开发。当
passed: false
时：未处于worktree环境 — 立即停止，不要修改文件。

Subagent Instructions

子Agent说明

Include in all implementer prompts:

markdown

undefined

在所有执行者提示中加入以下内容：

markdown

undefined

CRITICAL: Worktree Verification (MANDATORY)

重要提示：Worktree验证（必填）

Before making ANY file changes, run:

exarchos_orchestrate({ action: "verify_worktree" })

passed: false

: STOP and report error. DO NOT proceed with any modifications outside a worktree.

undefined

在进行任何文件修改前，请运行：

exarchos_orchestrate({ action: "verify_worktree" })

若

passed: false

：请停止操作并报告错误。请勿在worktree之外进行任何修改。

undefined

Anti-Patterns

反模式

Don't	Do Instead
Create worktrees in tracked directory	Use gitignored `.worktrees/`
Skip baseline test verification	Always verify tests pass first
Leave stale worktrees	Clean up after merge
Forget dependency installation	Run project setup in each worktree
Mix work across worktrees	One task per worktree

禁止操作	正确做法
在已跟踪目录中创建worktree	使用已被git忽略的 `.worktrees/`
跳过基线测试验证	始终先确认测试通过
保留过期的worktree	合并后及时清理
忘记安装依赖	在每个worktree中运行项目设置
在不同worktree间交叉工作	一个worktree对应一个任务

Integration with Delegation

与委托功能的集成

When delegation skill spawns parallel tasks:

Create worktree for each parallel group
Set up environment
Verify baseline tests
Dispatch subagent with worktree path
Track progress
Merge branches in dependency order
Clean up worktrees

当委托技能生成并行任务时：

为每个并行组创建worktree
设置环境
验证基线测试
携带worktree路径调度子Agent
跟踪进度
按依赖顺序合并分支
清理worktree

Merge-Pending Handoff

待合并交接

When a subagent completes a task in its worktree, the workflow's HSM transitions from

delegate

feature/merge-pending

. The

merge_orchestrate

action lands the worktree's branch onto the integration branch via a local

git merge

with a recorded rollback SHA — see

@skills/merge-orchestrator/SKILL.md

for the full handoff protocol.

Worktree cleanup (step 7 above) runs after the merge orchestrator reports

phase: 'completed'

This is not the same as the synthesize-phase remote PR merge (

merge_pr

merge_orchestrate

operates on local refs in the main worktree;

merge_pr

calls the VCS provider once the integration branch is ready for the human-review PR.

当子Agent在其worktree中完成任务后，工作流的HSM会从

delegate

状态转换为

feature/merge-pending

状态。

merge_orchestrate

操作会通过本地

git merge

将worktree的分支合并到集成分支，并记录回滚SHA — 完整的交接协议请查看

@skills/merge-orchestrator/SKILL.md

。

上述步骤7的worktree清理会在合并编排器报告

phase: 'completed'

后执行。

这与合成阶段的远程PR合并（

merge_pr

）不同。

merge_orchestrate

在主worktree中操作本地引用；

merge_pr

则在集成分支准备好进行人工审核PR时调用版本控制服务提供商接口。

git-worktrees

Original

Translation

Git Worktrees Skill

Git Worktrees 技能

Overview

概述

Triggers

触发条件

Worktree Directory Location

Worktree 目录位置

Verify directory is gitignored before creating

Verify directory is gitignored before creating

Worktree Lifecycle

Worktree 生命周期

1. Create Worktree

1. 创建Worktree

Create feature branch

Create feature branch

Create worktree

Create worktree

Verify creation

Verify creation

2. Setup Environment

2. 环境设置

3. Baseline Verification

3. 基线验证

4. Work in Worktree

4. 在Worktree中工作

5. Cleanup After Merge

5. 合并后清理

After PR merged, remove worktree

After PR merged, remove worktree

Optionally delete branch

Optionally delete branch

Prune stale worktree refs

Prune stale worktree refs

Parallel Worktree Management

并行Worktree管理

Worktree Validation

Worktree 验证

Why Validate?

为什么要验证？

Worktree Verification

Worktree 验证

Subagent Instructions

子Agent说明

CRITICAL: Worktree Verification (MANDATORY)

重要提示：Worktree验证（必填）

Anti-Patterns

反模式

Integration with Delegation

与委托功能的集成

Merge-Pending Handoff

待合并交接

Completion Criteria

完成标准