Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Announce at start: “I’m using the using-git-worktrees skill to set up an isolated workspace.”

Directory Selection Process

Follow this priority order:

1. Check existing directories — Use .worktrees/ or worktrees/ if present (.worktrees/ wins if both exist)
2. Check CLAUDE.md — Use any worktree directory preference specified there
3. Ask user — Offer .worktrees/ (project-local) or ~/.config/superpowers/worktrees/<project>/ (global)

See references/directory-selection.md for full bash commands and ask-user flow.

Safety Verification

For project-local directories only (not needed for global):

1. Check gitignore — git check-ignore -q .worktrees to verify directory is ignored
2. Add if needed — Add to .gitignore if not ignored
3. Commit — Commit the .gitignore change before proceeding

See references/safety-verification.md for full verification protocol.

Creation Steps (Task-Tracked)

Create 6 native tasks, each blocked by the previous (non-skippable sequence):

1. Select worktree directory location — Check existing dirs, CLAUDE.md, or ask user
2. Verify gitignore for project-local directory — Run git check-ignore, add to .gitignore if needed
3. Create worktree — git worktree add <path> -b <branch>
4. Install dependencies — Auto-detect project type, run appropriate install command
5. Run baseline tests — Capture output showing pass/fail; ask user if tests fail
6. Worktree ready — Report location and test status; only complete if tests passed

See references/creation-steps.md for full TaskCreate blocks, bash commands, and setup detection.

Quick Reference

Common Mistakes

• Skipping ignore verification — worktree contents pollute git status. Always git check-ignore first.
• Assuming directory location — follow priority: existing > CLAUDE.md > ask.
• Proceeding with failing tests — report failures, get permission first.
• Hardcoding setup commands — auto-detect from project files instead.

Integration

Called by: brainstorming (after design), any skill needing isolated workspace Pairs with: finishing-a-development-branch (cleanup), executing-plans / subagent-driven-development (work happens here)

Reference Files

• references/directory-selection.md: full priority order with bash commands and ask-user flow
• references/safety-verification.md: full gitignore verification protocol with commands
• references/creation-steps.md: full TaskCreate blocks, bash commands, and setup detection
• references/example-workflow.md: annotated example of complete worktree setup workflow
• references/red-flags.md: Never/Always lists for quick self-check