Update git worktree skill

[arthursw]

• I searched existing issues and this has not been proposed before

What problem does this solve?

The git worktree implies to commit in other directories ; which requires user validation, so interrupts the agents.

Claude code now has special tools for worktrees.

I asked claude code his opinion on this ; and here is his analysis and proposal:

Superpowers Skill vs Claude Code Native Worktree Support

What Claude Code now provides natively

Claude Code has built-in worktree support that didn't exist when the superpowers skill was written:

1. --worktree CLI flag — claude --worktree feature-auth creates a worktree at <repo>/.claude/worktrees/<name> with branch worktree-<name>, based on origin/HEAD
2. EnterWorktree tool — creates a worktree mid-session, switches the session's CWD into it
3. ExitWorktree tool — exits with keep or remove, handles cleanup/uncommitted changes
4. isolation: "worktree" on Agent tool — subagents get their own worktree automatically, cleaned up when done
5. .worktreeinclude file — copies gitignored files (.env, etc.) into new worktrees
6. WorktreeCreate / WorktreeRemove hooks — customizable worktree creation logic
7. Automatic cleanup — no changes = auto-removed; changes exist = user prompted

What the superpowers skill does differently (and mostly worse)

Aspect	Superpowers Skill	Claude Code Native
Location	.worktrees/ or worktrees/ or ~/.config/superpowers/worktrees/	.claude/worktrees/<name> (standardized)
Gitignore safety	Manual git check-ignore + auto-fix	Built-in; docs say "add .claude/worktrees/ to .gitignore"
Branch base	Implicit (current HEAD)	origin/HEAD (configurable via git remote set-head)
Cleanup	None (delegates to "finishing-a-development-branch" skill)	Automatic on session exit
Env files	Not handled	.worktreeinclude copies them
Subagent isolation	Manual setup	isolation: "worktree" one-liner
Mid-session creation	Shell commands	EnterWorktree tool
Project setup	Custom detection (npm/cargo/pip/etc.)	Left to user/hooks

Key problems with the current skill

1. Reinvents the wheel — The skill manually runs git worktree add, manages directories, checks .gitignore, etc. All of this is now handled by EnterWorktree / --worktree.
2. Wrong location — Uses .worktrees/ or ~/.config/superpowers/worktrees/, but Claude Code standardized on .claude/worktrees/.
3. No cleanup — The skill creates worktrees but has no exit/cleanup logic. Native ExitWorktree handles this.
4. Misses .worktreeinclude — Doesn't know about the native mechanism for copying .env files.
5. Subagent isolation not leveraged — The skill doesn't mention isolation: "worktree" on the Agent tool, which is the proper way to give subagents isolated workspaces.

What the skill does that native doesn't

1. Auto-detect and run project setup (npm install, cargo build, etc.) — Native worktrees don't auto-install dependencies.
2. Baseline test verification — Running tests to confirm a clean starting point is a good practice not built into native.

Recommended changes

The skill should be largely rewritten to wrap the native tools instead of reimplementing worktree management:

1. Replace all manual git worktree add logic with EnterWorktree (mid-session) or guidance to use claude --worktree (new session)
2. Remove directory selection logic — native uses .claude/worktrees/ exclusively
3. Remove gitignore safety checks — native handles this; just mention .worktreeinclude for env files
4. Add ExitWorktree guidance for cleanup (replace the dependency on "finishing-a-development-branch")
5. Add isolation: "worktree" guidance for subagent-driven-development integration
6. Keep the project setup detection — this is genuinely useful and not provided natively
7. Keep baseline test verification — also useful
8. Update the "Integration" section — subagent-driven-development should use isolation: "worktree" on Agent calls, not this skill

The skill would shrink significantly — from a full worktree management procedure to essentially: "use EnterWorktree, run setup, verify tests, mention .worktreeinclude."

---

Proposed updated skill

---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - leverages Claude Code's native worktree tools for isolated workspaces
---

# Using Git Worktrees

## Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching. You have native worktree tools available: `EnterWorktree`, `ExitWorktree`, and `isolation: "worktree"` on the Agent tool.

**Core principle:** Use the native worktree tools for lifecycle management. Never run `git worktree add` manually. Add project setup and baseline verification on top.

**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."

## Creating a Worktree

Call the `EnterWorktree` tool to create a worktree and switch the session into it. It creates the worktree at `.claude/worktrees/<name>/` with a branch `worktree-<name>` based on HEAD. It also copies any files listed in `.worktreeinclude` (e.g. `.env`).

- Pass a `name` parameter to control the directory and branch name.
- Omit `name` to auto-generate a random one.

**For subagents:** When dispatching subagents via the Agent tool, set `isolation: "worktree"` instead of using this skill. Each subagent gets its own worktree that is automatically cleaned up when it finishes without changes.

## Post-Creation Setup

After `EnterWorktree` succeeds, auto-detect and run the project's dependency installation:

```bash
# Node.js / Bun
if [ -f bun.lockb ] || [ -f bunfig.toml ]; then bun install
elif [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python (uv / pixi preferred)
if [ -f uv.lock ] || [ -f pyproject.toml ]; then uv sync
elif [ -f pixi.toml ]; then pixi install
elif [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# Go
if [ -f go.mod ]; then go mod download; fi

Skip this step if no recognizable project files are found.

Baseline Test Verification

Run the project's test suite to confirm the worktree starts clean:

# Use project-appropriate command
bun test / npm test / cargo test / pytest / go test ./...

• If tests pass: Report ready with test count and proceed.
• If tests fail: Report failures and ask the user whether to proceed or investigate.

Env Files and .worktreeinclude

EnterWorktree automatically copies files matching patterns in .worktreeinclude (at the project root). If the project has gitignored config files (.env, .env.local, etc.) but no .worktreeinclude, suggest creating one:

.env
.env.local
config/secrets.json

Only files that are both matched and gitignored get copied.

Exiting a Worktree

Call the ExitWorktree tool when work is done:

• action: "keep" — preserves worktree and branch on disk for later.
• action: "remove" — deletes worktree and branch. Refuses if uncommitted changes exist unless discard_changes: true is also set.

If the session ends while still in a worktree, the user is prompted to keep or remove it.

Sandbox Considerations

Git worktrees store their index at <repo>/.git/worktrees/<name>/index.lock, which is inside .git/. The sandbox blocks writes to .git/ by default, so git add and git commit will fail inside worktrees unless sandbox.filesystem.allowWrite includes ./.git/worktrees in the project settings.

If a git command fails with Operation not permitted on an index.lock file, inform the user that they need to add this to their .claude/settings.local.json:

{
  "sandbox": {
    "filesystem": {
      "allowWrite": ["./.git/worktrees"]
    }
  }
}

Quick Reference

Situation	Action
Need isolated workspace	Call EnterWorktree with a descriptive name
Need isolated workspace for a subagent	Set isolation: "worktree" on the Agent tool
Env files needed in worktree	Suggest a .worktreeinclude file at project root
Done with worktree, keep work	Call ExitWorktree with action: "keep"
Done with worktree, discard	Call ExitWorktree with action: "remove"
Tests fail during baseline	Report failures, ask user
No package.json/Cargo.toml	Skip dependency install
Git fails with index.lock permission error	Sandbox issue — suggest allowWrite for .git/worktrees

Common Mistakes

Manually running git worktree add

• Problem: Bypasses built-in lifecycle management, cleanup, and .worktreeinclude handling.
• Fix: Always call EnterWorktree.

Skipping baseline test verification

• Problem: Can't distinguish new bugs from pre-existing issues.
• Fix: Always run tests after setup, report before proceeding.

Using this skill for subagent isolation

• Problem: Unnecessary overhead when a one-liner suffices.
• Fix: Use isolation: "worktree" on the Agent tool for subagents.

Integration

Called by:

• brainstorming (Phase 4) — when design is approved and implementation follows
• executing-plans — before executing tasks that need isolation
• Any workflow needing an isolated workspace

Pairs with:

• finishing-a-development-branch — for merge/PR decisions after work is complete
• subagent-driven-development — prefer isolation: "worktree" on Agent tool for subagent isolation

Native tools used:

• EnterWorktree — create and enter worktree
• ExitWorktree — leave and optionally clean up worktree
• Agent tool isolation: "worktree" — subagent isolation

[empyriumz]

I think this is a great suggestion. I found that when launching parallel sessions using sub-agent driven development, despite using the git worktree and told the agent to work in the specific branch in CLAUDE.md, the subagent oftentime would commit changes to another branch.

[pcvelz]

Thanks to @arthursw for the thorough analysis and the proposed direction — it made the rewrite much easier to execute against. A native-tool wrapping of the skill is now staged in draft PR #13; the PR description covers the findings, the test plan, and what's deliberately out of scope.

To try the change locally before it's merged:

/plugin marketplace add pcvelz/superpowers#issue/12-worktree-skill-native-tools
/plugin install superpowers-extended-cc@superpowers-extended-cc-marketplace

Feedback on the implementation is welcome on the PR.

[arthursw]

Nice!

I must warn you that I had troubles with the finishing-a-development-branch skill after I modified using-git-worktrees.
I saw you modified finishing-a-development-branch so it should be fine ; just make sure agents never try using git-worktree themselves to avoid any trouble.

[pcvelz]

Thanks for flagging this, @arthursw. The using-git-worktrees skill now uses the native Claude Code worktree tools end-to-end — it already preferred EnterWorktree for creation, and v6.0.2 adds the missing teardown path via ExitWorktree. Released in v6.0.2: https://github.com/pcvelz/superpowers/releases/tag/v6.0.2