vinvcn 使用 Git Worktrees
概览
确保工作发生在隔离 workspace 中。优先使用你所在平台的原生 worktree 工具。只有在没有原生工具可用时，才 fallback 到手动 git worktrees。
核心原则： 先检测现有隔离。然后使用原生工具。然后 fallback 到 git。绝不对抗 harness。
开始时宣布： "I'm using the using-git-worktrees skill to set up an isolated workspace."
Step 0: 检测现有隔离
创建任何东西之前，检查你是否已经在隔离 workspace 中。
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
Submodule 防护： GIT_DIR != GIT_COMMON 在 git submodules 内部也为 true。得出“already in a worktree”结论之前，先验证你不在 submodule 中：
# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null
如果 GIT_DIR != GIT_COMMON（且不是 submodule）： 你已经在 linked worktree 中。跳到 Step 3（Project Setup）。不要再创建另一个 worktree。
报告 branch 状态：
- 在 branch 上："Already in isolated workspace at
<path>on branch<name>." - Detached HEAD："Already in isolated workspace at
<path>(detached HEAD, externally managed). Branch creation needed at finish time."
如果 GIT_DIR == GIT_COMMON（或在 submodule 中）： 你在普通 repo checkout 中。
用户是否已经在你的说明中表明了他们的 worktree 偏好？如果没有，在创建 worktree 前征得同意：
"Would you like me to set up an isolated worktree? It protects your current branch from changes."
遵循任何已有的明确偏好，不要再询问。如果用户拒绝同意，就在原地工作并跳到 Step 3。
Step 1: 创建隔离 Workspace
你有两种机制。按此顺序尝试。
1a. 原生 Worktree 工具（首选）
用户已经要求使用隔离 workspace（Step 0 consent）。你是否已经有创建 worktree 的方式？它可能是名为 EnterWorktree、WorktreeCreate 的工具、/worktree 命令，或 --worktree flag。如果有，使用它并跳到 Step 3。
原生工具会自动处理目录位置、branch 创建和清理。在你有原生工具时使用 git worktree add，会创建 harness 无法看到或管理的 phantom state。
只有在没有原生 worktree 工具可用时，才继续 Step 1b。
1b. Git Worktree Fallback
只有在 Step 1a 不适用时才使用这个 —— 你没有可用的原生 worktree 工具。用 git 手动创建 worktree。
目录选择
遵循此优先级顺序。明确的用户偏好始终优先于观察到的 filesystem state。
检查你的说明中是否声明了 worktree 目录偏好。 如果用户已经指定了一个，不询问直接使用它。
检查是否存在项目本地 worktree 目录：
ls -d .worktrees 2>/dev/null # Preferred (hidden) ls -d worktrees 2>/dev/null # Alternative如果找到，就使用它。如果两者都存在，
.worktrees优先。检查是否存在全局目录：
project=$(basename "$(git rev-parse --show-toplevel)") ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null如果找到，就使用它（与旧版全局路径保持 backward compatibility）。
如果没有其他可用 guidance，默认使用项目根目录下的
.worktrees/。
安全验证（仅限项目本地目录）
创建 worktree 前必须验证目录已被 ignored：
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
如果没有被 ignored： 添加到 .gitignore，提交该更改，然后继续。
为什么关键： 防止意外把 worktree contents commit 到 repository。
全局目录（~/.config/superpowers/worktrees/）无需验证。
创建 Worktree
project=$(basename "$(git rev-parse --show-toplevel)")
# Determine path based on chosen location
# For project-local: path="$LOCATION/$BRANCH_NAME"
# For global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
Sandbox fallback： 如果 git worktree add 因 permission error（sandbox denial）失败，告诉用户 sandbox 阻止了 worktree 创建，你将改在当前目录工作。然后在原地运行 setup 和 baseline tests。
Step 3: Project Setup
自动检测并运行适当 setup：
# Node.js
if [ -f package.json ]; then npm install; fi
# Rust
if [ -f Cargo.toml ]; then cargo build; fi
# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
# Go
if [ -f go.mod ]; then go mod download; fi
Step 4: 验证干净 Baseline
运行测试，确保 workspace 起始状态干净：
# Use project-appropriate command
npm test / cargo test / pytest / go test ./...
如果测试失败： 报告失败，询问是继续还是调查。
如果测试通过： 报告已就绪。
报告
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
快速参考
| 情况 | 操作 |
|---|---|
| 已经在 linked worktree 中 | 跳过创建（Step 0） |
| 在 submodule 中 | 视为普通 repo（Step 0 guard） |
| 原生 worktree 工具可用 | 使用它（Step 1a） |
| 没有原生工具 | Git worktree fallback（Step 1b） |
.worktrees/ 存在 |
使用它（验证 ignored） |
worktrees/ 存在 |
使用它（验证 ignored） |
| 两者都存在 | 使用 .worktrees/ |
| 两者都不存在 | 检查 instruction file，然后默认 .worktrees/ |
| 全局路径存在 | 使用它（backward compat） |
| 目录未 ignored | 添加到 .gitignore + commit |
| 创建时 permission error | Sandbox fallback，原地工作 |
| baseline 期间测试失败 | 报告失败 + 询问 |
| 没有 package.json/Cargo.toml | 跳过 dependency install |
常见错误
对抗 harness
- 问题： 在平台已经提供隔离时使用
git worktree add - 修复： Step 0 检测现有隔离。Step 1a 交给原生工具。
跳过检测
- 问题： 在现有 worktree 内部创建嵌套 worktree
- 修复： 创建任何东西之前始终运行 Step 0
跳过 ignore 验证
- 问题： Worktree contents 被 tracked，污染 git status
- 修复： 创建项目本地 worktree 前始终使用
git check-ignore
假设目录位置
- 问题： 制造不一致，违反项目约定
- 修复： 遵循优先级：existing > global legacy > instruction file > default
在测试失败时继续
- 问题： 无法区分新 bug 和已有问题
- 修复： 报告失败，获得明确许可后再继续
Red Flags
绝不：
- 在 Step 0 检测到现有隔离时创建 worktree
- 在你有原生 worktree 工具（例如
EnterWorktree）时使用git worktree add。这是 #1 mistake —— 如果你有它，就使用它。 - 跳过 Step 1a，直接跳到 Step 1b 的 git commands
- 不验证它已被 ignored（项目本地）就创建 worktree
- 跳过 baseline test verification
- 不询问就在测试失败时继续
始终：
- 先运行 Step 0 detection
- 优先使用原生工具，而不是 git fallback
- 遵循目录优先级：existing > global legacy > instruction file > default
- 对项目本地目录验证 directory is ignored
- 自动检测并运行 project setup
- 验证 clean test baseline