name: git-worktrees description: “Git工作树隔离用于并行计划执行。创建隔离的工作目录，以便多个计划可以同时执行而不会发生冲突。” triggers: [worktree, isolation, parallel]

Git工作树隔离

在并行中运行多个计划而不会相互干扰。

何时使用

当以下情况时使用工作树隔离：

执行一个会修改其他计划也会触及的文件的计划
同时运行多个 /work 会话
想要一个干净的基准，无需存储或提交进行中的工作

目录优先级链

工作树根目录按以下顺序解析：

优先级	位置	备注
1	`.worktrees/`	默认 — 在项目根目录（`.maestro/`、`.claude/` 的同级）
2	`worktrees/`	备用 — 同一级别
3	CLAUDE.md 偏好	如果项目 CLAUDE.md 指定了自定义路径
4	询问用户	如果上述都不存在，提示输入目录

所有路径都相对于项目根目录（包含 .maestro/ 和 .claude/ 的目录）。

安全验证

在创建工作树之前，验证环境是否安全：

1. Gitignore 检查

git check-ignore -q .worktrees

如果命令成功（退出码 0）：.worktrees/ 已经被忽略 — 继续。
如果命令失败（退出码 1）：.worktrees/ 没有被忽略 — 自动添加：

echo "" >> .gitignore
echo "# Maestro worktrees (auto-added)" >> .gitignore
echo ".worktrees/" >> .gitignore

2. 仓库状态检查

验证仓库是否足够干净以创建分支：

git status --porcelain

如果有未提交的更改，警告用户但继续（工作树从 HEAD 分支创建，无论如何）。
如果有合并冲突，停止 — 用户必须先解决它们。

工作树创建

1. 创建工作树

git worktree add "<worktree-dir>/<plan-slug>" -b "maestro/<plan-slug>"

<worktree-dir> 是从优先级链解析的目录（例如，.worktrees/）
<plan-slug> 是计划文件名没有 .md（例如，add-auth 来自 add-auth.md）
-b 标志创建分支 maestro/<plan-slug> 跟踪当前 HEAD

2. 复制计划文件

mkdir -p "<worktree-dir>/<plan-slug>/.maestro/plans"
cp ".maestro/plans/<plan-slug>.md" "<worktree-dir>/<plan-slug>/.maestro/plans/"

3. 创建运行时目录

mkdir -p "<worktree-dir>/<plan-slug>/.maestro/handoff"
mkdir -p "<worktree-dir>/<plan-slug>/.maestro/drafts"
mkdir -p "<worktree-dir>/<plan-slug>/.maestro/wisdom"
mkdir -p "<worktree-dir>/<plan-slug>/.maestro/archive"

项目设置自动检测

在创建工作树后，检测并运行项目的设置命令在工作树目录内：

文件	设置命令	备注
`package.json`	`bun install`	总是使用 `bun`，从不使用 npm/yarn/pnpm
`Cargo.toml`	`cargo build`	Rust 项目
`pyproject.toml`	`uv sync`	总是使用 `uv`，从不使用 pip/poetry/pipenv
`go.mod`	`go mod download`	Go 模块
`build.gradle` 或 `gradlew`	`./gradlew build`	当项目包装器可用时使用
`pom.xml` 或 `mvnw`	`./mvnw install`	当项目包装器可用时使用

从工作树根目录运行设置命令：

cd "<worktree-dir>/<plan-slug>"
# 检测并运行适当的设置命令

如果存在多个项目文件（例如，单体仓库），运行每个适用的设置命令。

测试基准验证

在开始任何工作在工作树之前，验证现有的测试套件通过：

cd "<worktree-dir>/<plan-slug>"
# 运行项目的测试命令（从项目惯例中检测）

如果测试通过：确认干净基准 — 继续计划执行。
如果测试失败：警告用户。失败是预先存在的，不是由计划引起的。记录失败并继续，但在最终报告中注明它们。

完成工作流程

当计划执行完成时（所有任务完成或用户停止）：

1. 合并智慧回主树

复制执行期间生成的任何智慧文件回主树：

cp "<worktree-dir>/<plan-slug>/.maestro/wisdom/"* ".maestro/wisdom/" 2>/dev/null

2. 报告分支

报告分支名称给用户用于合并或PR：

计划完成。更改在分支上：maestro/<plan-slug>
您可以合并：git merge maestro/<plan-slug>
或从这个分支创建PR。

3. 工作树清理

询问用户是否现在删除工作树或保留检查：

如果删除：

git worktree remove "<worktree-dir>/<plan-slug>"

可选删除分支如果完全合并：

git branch -d "maestro/<plan-slug>"

如果没有合并，在强制删除前警告 — 让用户决定：

# 只有当用户确认时：
git branch -D "maestro/<plan-slug>"

如果保留： 将工作树留在原地。用户以后可以用 git worktree remove 移除它。

常见错误

使用 npm/yarn/pnpm 而不是 bun — 这个项目使用 bun 用于所有 JavaScript/TypeScript 操作。从不回退到 npm。
使用 pip/poetry 而不是 uv — 这个项目使用 uv 用于 Python。从不回退到 pip。
在工作树内创建项目树 — 工作树必须在 .worktrees/（或等效的解析目录）在项目根目录，而不是嵌套在 src/ 或其他目录中。
忘记复制计划文件 — 工作树需要自己的计划副本在 .maestro/plans/ 以便工作者可以找到它。
不在工作树中运行设置 — 依赖必须单独安装在工作树中。从主树符号链接的 node_modules 或虚拟环境将不起作用。
强制删除未合并的分支 — 总是先使用 git branch -d。只有在用户明确确认时才使用 -D。
跳过 gitignore 验证 — 如果 .worktrees/ 不在 .gitignore 中，工作树内容可能被意外提交。

红色标志

工作树目录已经存在 — 先前的运行可能没有清理。在创建前检查 git worktree list。
分支名称冲突 — maestro/<plan-slug> 已经存在。要么计划之前运行过（提供重用或选择新名称），要么存在命名冲突。
完成时的脏工作树 — 完成时在工作树中有未提交的更改。警告用户 — 如果工作树被移除，这些更改将丢失。
主树前进 — 如果主分支在工作树活动期间前进，合并可能有冲突。建议先重定基工作树分支。
磁盘空间 — 工作树复制工作树。对于大型仓库有重型构建工件，这可以消耗大量磁盘空间。

集成点

由调用：/work 命令 — 在生成工作者之前提供工作树隔离
从读取：.maestro/plans/ — 要执行的计划文件
写入到：.maestro/wisdom/ — 从工作树合并回在完成时
依赖于：git 支持工作树（Git 2.5+）
补充：project-conventions 技能 — 用于设置自动检测