Worktree Rototill：检测并延后处理

Worktree Rototill：检测并延后处理

日期： 2026-04-06 状态： 草稿 Ticket: PRI-974 Subsumes: PRI-823 (Codex App 兼容性)

问题

Superpowers is opinionated about worktree 管理 — specific paths (.worktrees/<branch>), specific commands (git worktree add), specific 清理 (git worktree remove). Meanwhile, Claude Code, Codex App, Gemini CLI, and Cursor all provide 原生 worktree support with their own paths, lifecycle management, and cleanup.

This creates three 失败 modes:

1. Duplication — on Claude Code, the skill does what EnterWorktree/ExitWorktree already does
2. Conflict — on Codex App, the skill tries to create worktrees inside an already-managed worktree
3. Phantom state — skill-created worktrees at .worktrees/ are invisible to the harness; harness-created worktrees at .claude/worktrees/ are invisible to the skill

对于 harnesses without 原生 support (Codex CLI, OpenCode, Copilot standalone), superpowers fills a real gap. The skill shouldn’t go away — it should get out of the way when 原生 support exists.

目标

1. Defer to 原生 harness worktree systems when they exist
2. Continue providing worktree support for harnesses that lack it
3. Fix three known bugs in finishing-a-development-branch (#940, #999, #238)
4. Make worktree creation opt-in rather than mandatory (#991)
5. 替换 hardcoded CLAUDE.md 引用 with platform-neutral language (#1049)

Non-Goals

• Per-worktree environment conventions (.worktree-env.sh, port offsetting) — Phase 4
• PreToolUse hooks for path enforcement — Phase 4
• Multi-repo worktree documentation — Phase 4
• Brainstorming checklist changes for worktrees — Phase 4
• .superpowers-session.json metadata tracking (interesting PR #997 idea, not needed for v1)
• Hooks symlinking into worktrees (PR #965 idea, separate concern)

Design Principles

Detect state, not 平台

使用 GIT_DIR != GIT_COMMON to determine “am I already in a worktree?” rather than sniffing environment variables to identify the harness. This is a stable git primitive (since git 2.5, 2015), works universally across all harnesses, and requires zero maintenance as 新 harnesses appear.

Declarative intent, prescriptive 回退

The skill describes the goal (“ensure work happens in an 隔离工作区”) and defers to 原生工具 when available. It prescribes specific git commands only as a 回退 for harnesses without 原生 worktree support. 步骤 1a comes first and names 原生工具 explicitly (EnterWorktree, WorktreeCreate, /worktree, --worktree); 步骤 1b comes second with the git fallback. The original spec kept 步骤 1a abstract (“you know your own toolkit”), but TDD proved that agents anchor on 步骤 1b’s concrete commands when 步骤 1a is too vague. Explicit tool naming and a consent-authorization bridge were 必需 to make the preference reliable.

Provenance-based ownership

Whoever creates the worktree owns its cleanup. 如果 the harness created it, superpowers doesn’t touch it. 如果 superpowers created it (via git 回退), superpowers cleans it up. The heuristic: if the worktree lives under .worktrees/ or worktrees/, superpowers owns it. Anything else (.claude/worktrees/, ~/.codex/worktrees/, .gemini/worktrees/, or 旧 user-global Superpowers paths) belongs to the harness or user and is left alone.

Design

1. using-git-worktrees SKILL.md Rewrite

The skill gains three 新 steps before creation and simplifies the creation flow.

步骤 0: Detect Existing Isolation

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)

Three outcomes:

Condition	Meaning	Action
GIT_DIR == GIT_COMMON	Normal repo checkout	Proceed to 步骤 0.5
GIT_DIR != GIT_COMMON, named branch	Already in a 链接 worktree	Skip to 步骤 3 (项目 setup). Report: “Already in 隔离工作区 at <path> on branch <name>.”
GIT_DIR != GIT_COMMON, 分离 HEAD	Externally managed worktree (e.g., Codex App sandbox)	Skip to 步骤 3. Report: “Already in 隔离工作区 at <path> (分离 HEAD, 外部管理).”

步骤 0 does not care who created the worktree or which harness is running. A worktree is a worktree regardless of origin.

Submodule guard: GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding “already in a worktree,” check that we’re not in a submodule:

# If this returns a path, we're in a submodule, not a worktree
git rev-parse --show-superproject-working-tree 2>/dev/null

如果 in a submodule, treat as GIT_DIR == GIT_COMMON (proceed to 步骤 0.5).

步骤 0.5: Consent

当 步骤 0 finds no 现有 isolation (GIT_DIR == GIT_COMMON), ask before creating:

“Would you like me to set up an isolated worktree? This protects your 当前 branch from changes. (y/n)”

如果 yes, proceed to 步骤 1. 如果 no, work in place — 跳过 to 步骤 3 with no worktree.

This step is skipped entirely when 步骤 0 detects 现有 isolation (no point asking about what already exists).

步骤 1a: Native Tools (preferred)

The user has asked for an 隔离工作区 (步骤 0 consent). Check your 可用 tools — do you have EnterWorktree, WorktreeCreate, a /worktree command, or a --worktree flag? 如果 YES: the user’s consent to create a worktree is your 授权 to use it. 使用 it now and 跳过 to 步骤 3.

After using a 原生 tool, 跳过 to 步骤 3 (项目 setup).

Design note — TDD revision: The original spec used a deliberately short, abstract 步骤 1a (“You know your own toolkit — the skill does not need to name specific tools”). TDD validation disproved this: agents anchored on 步骤 1b’s concrete git commands and ignored the abstract guidance (2/6 pass rate). Three changes fixed it (50/50 pass rate across GREEN and PRESSURE tests):

1. Explicit tool naming — listing EnterWorktree, WorktreeCreate, /worktree, --worktree by name transforms the decision from interpretation (“do I have a 原生 tool?”) into factual lookup (“is EnterWorktree in my tool list?”). Agents on 平台 without these tools simply check, find nothing, and fall through to 步骤 1b. No false positives observed.
2. Consent bridge — “the user’s consent to create a worktree is your 授权 to use it” directly addresses EnterWorktree’s tool-level guardrail (“ONLY when user explicitly asks”). Tool descriptions override skill instructions (Claude Code #29950), so the skill must frame user consent as the 授权 the tool requires.
3. Red Flag entry — naming the specific anti-pattern (“使用 git worktree add when you have a 原生 worktree tool — this is the #1 mistake”) in the Red Flags section.

File splitting (步骤 1b in a separate skill) was tested and proven unnecessary. The anchoring problem is solved by the quality of 步骤 1a’s text, not by physical separation of git commands. Control tests with the full 240-line skill (all git commands visible) passed 20/20.

步骤 1b: Git Worktree Fallback

当 no 原生 tool is 可用, create a worktree manually.

Directory selection (priority order):

1. Check the 项目’s agent instruction file (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, or equivalent) for a worktree 目录 preference.
2. Check for 现有 .worktrees/ or worktrees/ 目录 — if found, use it. 如果 both exist, .worktrees/ wins.
3. Default to .worktrees/.

No interactive 目录 selection prompt. Old user-global Superpowers worktree paths are not detected or offered; 新 手动 worktrees are project-local unless the user explicitly specifies another location.

Safety 验证 (project-local 目录 only):

git check-ignore -q .worktrees 2>/dev/null

如果 not ignored, add to .gitignore and commit before proceeding.

创建:

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Hooks awareness: Git worktrees do not inherit the parent repo’s hooks directory. After creating a worktree via 1b, symlink the hooks 目录 from the main repo if one exists:

if [ -d "$MAIN_ROOT/.git/hooks" ]; then
    ln -sf "$MAIN_ROOT/.git/hooks" "$path/.git/hooks"
fi

This prevents pre-commit checks, linters, and other hooks from silently stopping when work moves to a worktree. (Idea from PR #965.)

Sandbox 回退: 如果 git worktree add fails with a permission 错误, treat as a restricted environment. Skip creation, work in 当前 目录, proceed to 步骤 3.

步骤 numbering note: The 当前 skill has Steps 1-4 as a flat list. This redesign uses 0, 0.5, 1a, 1b, 3, 4. There is no 步骤 2 — it was the 旧 monolithic “创建 Isolated Workspace” which is now split into the 1a/1b structure. The 实施 should renumber cleanly (e.g., 0 → “步骤 0: Detect”, 0.5 → within 步骤 0’s flow, 1a/1b → “步骤 1”, 3 → “步骤 2”, 4 → “步骤 3”) or keep the 当前 numbering with a note. Implementer’s choice.

Steps 3-4: Project Setup and Baseline Tests (unchanged)

Regardless of which path created the workspace (步骤 0 detected 现有, 步骤 1a 原生 tool, 步骤 1b git 回退, or no worktree at all), execution converges:

• 步骤 3： Auto-detect and run 项目 setup (npm install, cargo build, pip install, go mod download, etc.)
• 步骤 4： 运行 the test suite. 如果 tests fail, 报告 失败 and ask whether to proceed.

2. finishing-a-development-branch SKILL.md Rewrite

The finishing skill gains environment detection and fixes three bugs.

步骤 1: 验证 Tests (unchanged)

运行 the 项目’s test suite. 如果 tests fail, stop. Don’t offer completion options.

步骤 1.5: Detect Environment (新)

Re-run the same detection as 步骤 0 in creation:

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)

Three paths:

State	Menu	Cleanup
GIT_DIR == GIT_COMMON (normal repo)	Standard 4 options	No worktree to clean up
GIT_DIR != GIT_COMMON, named branch	Standard 4 options	Provenance-based (see 步骤 5)
GIT_DIR != GIT_COMMON, 分离 HEAD	Reduced menu: push as 新 branch + PR, keep as-is, discard	No merge options (can’t merge from 分离 HEAD)

步骤 2: Determine Base Branch (unchanged)

步骤 3: Present Options

Normal repo and named-branch worktree:

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I’ll handle it later)
4. Discard this work

Detached HEAD:

1. Push as 新 branch and create a Pull Request
2. Keep as-is (I’ll handle it later)
3. Discard this work

步骤 4: Execute Choice

Option 1 (Merge locally):

# Get main repo root for CWD safety (Bug #238 fix)
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Merge first, verify success before removing anything
git checkout <base-branch>
git pull
git merge <feature-branch>
<run tests>

# Only after merge succeeds: remove worktree, then delete branch (Bug #999 fix)
git worktree remove "$WORKTREE_PATH"  # only if superpowers owns it
git branch -d <feature-branch>

The order is critical: merge → verify → remove worktree → delete branch. The 旧 skill deleted the branch before removing the worktree (which fails because the worktree still 引用 the branch). The naive fix of removing the worktree first is also wrong — if the merge then fails, the working 目录 is gone and changes are lost.

Option 2 (创建 PR):

Push branch, create PR. Do NOT clean up worktree — user needs it for PR iteration. (Bug #940 fix: remove contradictory “然后: Cleanup worktree” prose.)

Option 3 (Keep as-is): No action.

Option 4 (Discard): Require typed “discard” confirmation. 然后 remove worktree (if superpowers owns it), force-delete branch.

步骤 5: Cleanup (updated)

if GIT_DIR == GIT_COMMON:
    # Normal repo, no worktree to clean up
    done

if worktree path is under .worktrees/ or worktrees/:
    # Superpowers created it — we own cleanup
    cd to main repo root       # Bug #238 fix
    git worktree remove <path>

else:
    # Harness created it — hands off
    # If platform provides a workspace-exit tool, use it
    # Otherwise, leave the worktree in place

Cleanup only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree. (Bug #940 fix.)

Stale worktree pruning: After any git worktree remove, run git worktree prune as a self-healing step. Worktree 目录 can get deleted out-of-band (e.g., by harness 清理, 手动 rm, or .claude/ 清理), leaving stale registrations that cause confusing errors. One line, prevents silent rot. (Idea from PR #1072.)

3. Integration Updates

subagent-driven-development and executing-plans

Both currently list using-git-worktrees as REQUIRED in their integration sections. Change to:

using-git-worktrees — Ensures 隔离工作区 (creates one or verifies 现有)

The skill itself now handles consent (步骤 0.5) and detection (步骤 0), so calling skills don’t need to gate or prompt.

writing-plans

移除 the stale claim “should be run in a dedicated worktree (created by brainstorming skill).” Brainstorming is a 设计 skill and does not create worktrees. The worktree 提示词 happens at execution time via using-git-worktrees.

4. Platform-Neutral Instruction File References

All instances of hardcoded CLAUDE.md in worktree-related skills are replaced with:

“your 项目’s agent instruction file (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, or equivalent)”

This applies to 目录 preference checks in 步骤 1b.

Bug Fixes (bundled)

Bug	问题	Fix	Location
#940	Option 2 prose says “然后: Cleanup worktree (步骤 5)” but quick 引用 says keep it. 步骤 5 says “对于 Options 1, 2, 4” but Common Mistakes says “Options 1 and 4 only.”	移除 清理 from Option 2. 步骤 5 applies to Options 1 and 4 only.	finishing SKILL.md
#999	Option 1 deletes branch before removing worktree. git branch -d can fail because worktree still 引用 the branch.	Reorder to: merge → verify tests → remove worktree → delete branch. Merge must succeed before anything is removed.	finishing SKILL.md
#238	git worktree remove fails silently if CWD is inside the worktree being removed.	添加 CWD guard: cd to main repo root before git worktree remove.	finishing SKILL.md

Issues Resolved

Issue	Resolution
#940	Direct fix (Bug #940)
#991	Opt-in consent in 步骤 0.5
#918	步骤 0 detection + 步骤 1.5 finishing detection
#1009	Resolved by 步骤 1a — agents use 原生工具 (e.g., EnterWorktree) which create at harness-native paths. Depends on 步骤 1a working; see Risks.
#999	Direct fix (Bug #999)
#238	Direct fix (Bug #238)
#1049	平台中立 instruction file 引用
#279	Solved by detect-and-defer — 原生 paths respected because we don’t override them
#574	Deferred. Nothing in this spec touches the brainstorming skill where the bug lives. Full fix (adding a worktree step to brainstorming’s checklist) is Phase 4.

Risks

步骤 1a is the load-bearing assumption — RESOLVED

步骤 1a — agents preferring 原生 worktree tools over the git 回退 — is the foundation the entire 设计 rests on. 如果 agents ignore 步骤 1a and fall through to 步骤 1b on harnesses with 原生 support, detect-and-defer fails entirely.

状态： This risk materialized during implementation. The original abstract 步骤 1a (“You know your own toolkit”) failed at 2/6 on Claude Code. The TDD gate worked as designed — it caught the 失败 before any skill files were modified, preventing a broken release. Three REFACTOR iterations identified the root causes (agent anchoring on concrete commands, tool-description guardrail overriding skill instructions) and produced a fix validated at 50/50 across GREEN and PRESSURE tests. See 步骤 1a 设计 note above for details.

Cross-platform validation:

As of 2026-04-06, Claude Code is the only harness with an agent-callable mid-session worktree tool (EnterWorktree). All others either create worktrees before the agent starts (Codex App, Gemini CLI, Cursor) or have no 原生 worktree support (Codex CLI, OpenCode). 步骤 1a is forward-compatible: when other harnesses add agent-callable worktree tools, agents will match them against the named examples and use them without skill changes.

Harness	Current worktree model	Skill mechanism	Tested
Claude Code	Agent-callable EnterWorktree	步骤 1a	50/50 (GREEN + PRESSURE)
Codex CLI	No 原生 tool (shell only)	步骤 1b git 回退	6/6 (codex exec)
Gemini CLI	Launch-time --worktree flag, no agent tool	步骤 0 if launched with flag, 步骤 1b if not	步骤 0: 1/1, 步骤 1b: 1/1 (gemini -p)
Cursor Agent	User-facing /worktree, no agent tool	步骤 0 if user activated, 步骤 1b if not	步骤 0: 1/1, 步骤 1b: 1/1 (cursor-agent -p)
Codex App	Platform-managed, 分离 HEAD, no agent tool	步骤 0 detects 现有	1/1 simulated
OpenCode	Detection only (ctx.worktree), no agent tool	步骤 1b git 回退	Untested (no CLI access)

Residual risks:

1. 如果 Anthropic changes EnterWorktree’s tool description to be more restrictive (e.g., “Do not use based on skill instructions”), the consent bridge breaks. Worth filing an issue requesting that the tool description accommodate skill-driven invocation.
2. 当 other harnesses add agent-callable worktree tools, they may use names not in 步骤 1a’s list. The list should be updated as 新 tools appear. The generic phrasing (“a worktree or workspace-isolation tool”) 提供 some forward coverage.

Provenance heuristic

The .worktrees/ or worktrees/ = ours, anything else = hands offheuristic works for every current harness. If a future harness adopts one of those project-local directories as its convention, we'd have a false positive (superpowers tries to clean up a harness-owned worktree). Similarly, if a user manually runsgit worktree add .worktrees/experimentwithout superpowers, we'd incorrectly claim ownership. Both are low risk — every harness uses branded paths, and manual.worktrees/` creation is unlikely — but worth noting.

Detached HEAD finishing

The reduced menu for 分离 HEAD worktrees (no merge option) is correct for Codex App’s sandbox model. 如果 a user is in 分离 HEAD for another reason, the reduced menu still makes sense — you genuinely can’t merge from 分离 HEAD without creating a branch first.

Implementation Notes

Both skill files contain sections beyond the core steps that need 更新 during 实施:

• Frontmatter (name, description): 更新 to reflect detect-and-defer behavior
• Quick Reference tables: Rewrite to match 新 step structure and bug fixes
• Common Mistakes sections: 更新 or remove items that 引用 旧 behavior (e.g., “Skip CLAUDE.md check” is now wrong)
• Red Flags sections: 更新 to reflect 新 priorities (e.g., “Never create a worktree when 步骤 0 detects 现有 isolation”)
• Integration sections: 更新 cross-references between skills

The spec describes what changes; the 实施计划 will specify exact edits to these secondary sections.

Future Work (not in this spec)

• Phase 3 remainder: $TMPDIR 目录 option (#666), setup docs for caching and env inheritance (#299)
• Phase 4: PreToolUse hooks for path enforcement (#1040), per-worktree env conventions (#597), brainstorming checklist worktree step (#574), multi-repo documentation (#710)