Using Git Worktrees

Adapted from obra/superpowers for Cursor IDE.

Overview

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

Core principle: Systematic directory selection + safety verification = reliable isolation.

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

Directory Selection Process

1. Check Existing Directories

ls -d .worktrees 2>/dev/null   # Preferred (hidden)
ls -d worktrees 2>/dev/null    # Alternative

If both exist, .worktrees wins.

2. Ask User

If no directory exists:

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. ~/worktrees/<project>/ (global location)

Safety Verification

For project-local directories: verify directory is ignored before creating worktree:

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

If NOT ignored: Add to .gitignore, commit, then proceed.

Creation Steps

1. •

   Create worktree:

   bash

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

2. •

   Run project setup: Auto-detect from package.json, Cargo.toml, requirements.txt, go.mod, etc.

3. •

   Verify clean baseline: Run tests. If tests fail: report failures, ask whether to proceed.

4. •

   Report location:

   code

   Worktree ready at <path>
   Tests passing (N tests, 0 failures)
   Ready to implement <feature>
   

Red Flags

Never:

• •Create worktree without verifying it's ignored (project-local)
• •Skip baseline test verification
• •Proceed with failing tests without asking
• •Assume directory location when ambiguous