Using Git Worktrees

{
  "sections": {
    "Directory Selection Process": "ls -d .worktrees 2>/dev/null     # Preferred (hidden)\r\nls -d worktrees 2>/dev/null      # Alternative\r\n```\r\n\r\n**If found:** Use that directory. If both exist, `.worktrees` wins.\r\n\r\n### 2. Check CLAUDE.md\r\n\r\n```bash\r\ngrep -i \"worktree.*director\" CLAUDE.md 2>/dev/null\r\n```\r\n\r\n**If preference specified:** Use it without asking.\r\n\r\n### 3. Ask User\r\n\r\nIf no directory exists and no CLAUDE.md preference:\r\n\r\n```\r\nNo worktree directory found. Where should I create worktrees?\r\n\r\n1. .worktrees/ (project-local, hidden)\r\n2. ~/.config/superpowers/worktrees/<project-name>/ (global location)\r\n\r\nWhich would you prefer?\r\n```",
    "Example Workflow": "```\r\nYou: I'm using the using-git-worktrees skill to set up an isolated workspace.\r\n\r\n[Check .worktrees/ - exists]\r\n[Verify .gitignore - contains .worktrees/]\r\n[Create worktree: git worktree add .worktrees/auth -b feature/auth]\r\n[Run npm install]\r\n[Run npm test - 47 passing]\r\n\r\nWorktree ready at /Users/jesse/myproject/.worktrees/auth\r\nTests passing (47 tests, 0 failures)\r\nReady to implement auth feature\r\n```",
    "Common Mistakes": "**Skipping .gitignore verification**\r\n- **Problem:** Worktree contents get tracked, pollute git status\r\n- **Fix:** Always grep .gitignore before creating project-local worktree\r\n\r\n**Assuming directory location**\r\n- **Problem:** Creates inconsistency, violates project conventions\r\n- **Fix:** Follow priority: existing > CLAUDE.md > ask\r\n\r\n**Proceeding with failing tests**\r\n- **Problem:** Can't distinguish new bugs from pre-existing issues\r\n- **Fix:** Report failures, get explicit permission to proceed\r\n\r\n**Hardcoding setup commands**\r\n- **Problem:** Breaks on projects using different tools\r\n- **Fix:** Auto-detect from project files (package.json, etc.)",
    "Overview": "Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.\r\n\r\n**Core principle:** Systematic directory selection + safety verification = reliable isolation.\r\n\r\n**Announce at start:** \"I'm using the using-git-worktrees skill to set up an isolated workspace.\"",
    "Quick Reference": "| Situation | Action |\r\n|-----------|--------|\r\n| `.worktrees/` exists | Use it (verify .gitignore) |\r\n| `worktrees/` exists | Use it (verify .gitignore) |\r\n| Both exist | Use `.worktrees/` |\r\n| Neither exists | Check CLAUDE.md → Ask user |\r\n| Directory not in .gitignore | Add it immediately + commit |\r\n| Tests fail during baseline | Report failures + ask |\r\n| No package.json/Cargo.toml | Skip dependency install |",
    "Creation Steps": "npm test\r\ncargo test\r\npytest\r\ngo test ./...\r\n```\r\n\r\n**If tests fail:** Report failures, ask whether to proceed or investigate.\r\n\r\n**If tests pass:** Report ready.\r\n\r\n### 5. Report Location\r\n\r\n```\r\nWorktree ready at <full-path>\r\nTests passing (<N> tests, 0 failures)\r\nReady to implement <feature-name>\r\n```",
    "Integration": "**Called by:**\r\n- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows\r\n- Any skill needing isolated workspace\r\n\r\n**Pairs with:**\r\n- **finishing-a-development-branch** - REQUIRED for cleanup after work complete\r\n- **executing-plans** or **subagent-driven-development** - Work happens in this worktree",
    "Safety Verification": "grep -q \"^\\.worktrees/$\" .gitignore || grep -q \"^worktrees/$\" .gitignore\r\n```\r\n\r\n**If NOT in .gitignore:**\r\n\r\nPer Jesse's rule \"Fix broken things immediately\":\r\n1. Add appropriate line to .gitignore\r\n2. Commit the change\r\n3. Proceed with worktree creation\r\n\r\n**Why critical:** Prevents accidentally committing worktree contents to repository.\r\n\r\n### For Global Directory (~/.config/superpowers/worktrees)\r\n\r\nNo .gitignore verification needed - outside project entirely.",
    "Red Flags": "**Never:**\r\n- Create worktree without .gitignore verification (project-local)\r\n- Skip baseline test verification\r\n- Proceed with failing tests without asking\r\n- Assume directory location when ambiguous\r\n- Skip CLAUDE.md check\r\n\r\n**Always:**\r\n- Follow directory priority: existing > CLAUDE.md > ask\r\n- Verify .gitignore for project-local\r\n- Auto-detect and run project setup\r\n- Verify clean test baseline"
  },
  "content": "Follow this priority order:\r\n\r\n### 1. Check Existing Directories\r\n\r\n```bash\r\n\r\n### For Project-Local Directories (.worktrees or worktrees)\r\n\r\n**MUST verify .gitignore before creating worktree:**\r\n\r\n```bash\r\n\r\n### 1. Detect Project Name\r\n\r\n```bash\r\nproject=$(basename \"$(git rev-parse --show-toplevel)\")\r\n```\r\n\r\n### 2. Create Worktree\r\n\r\n```bash\r\ncase $LOCATION in\r\n  .worktrees|worktrees)\r\n    path=\"$LOCATION/$BRANCH_NAME\"\r\n    ;;\r\n  ~/.config/superpowers/worktrees/*)\r\n    path=\"~/.config/superpowers/worktrees/$project/$BRANCH_NAME\"\r\n    ;;\r\nesac\r\n\r\ngit worktree add \"$path\" -b \"$BRANCH_NAME\"\r\ncd \"$path\"\r\n```\r\n\r\n### 3. Run Project Setup\r\n\r\nAuto-detect and run appropriate setup:\r\n\r\n```bash\r\nif [ -f package.json ]; then npm install; fi\r\n\r\nif [ -f Cargo.toml ]; then cargo build; fi\r\n\r\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\r\nif [ -f pyproject.toml ]; then poetry install; fi\r\n\r\nif [ -f go.mod ]; then go mod download; fi\r\n```\r\n\r\n### 4. Verify Clean Baseline\r\n\r\nRun tests to ensure worktree starts clean:\r\n\r\n```bash",
  "id": "using-git-worktrees_obra",
  "name": "using-git-worktrees",
  "description": "Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification"
}

---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
---

# Using Git Worktrees

## Overview

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

**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

Follow this priority order:

### 1. Check Existing Directories

```bash
# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative
```

**If found:** Use that directory. If both exist, `.worktrees` wins.

### 2. Check CLAUDE.md

```bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
```

**If preference specified:** Use it without asking.

### 3. Ask User

If no directory exists and no CLAUDE.md preference:

```
No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?
```

## Safety Verification

### For Project-Local Directories (.worktrees or worktrees)

**MUST verify .gitignore before creating worktree:**

```bash
# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore
```

**If NOT in .gitignore:**

Per Jesse's rule "Fix broken things immediately":
1. Add appropriate line to .gitignore
2. Commit the change
3. Proceed with worktree creation

**Why critical:** Prevents accidentally committing worktree contents to repository.

### For Global Directory (~/.config/superpowers/worktrees)

No .gitignore verification needed - outside project entirely.

## Creation Steps

### 1. Detect Project Name

```bash
project=$(basename "$(git rev-parse --show-toplevel)")
```

### 2. Create Worktree

```bash
# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```

### 3. Run Project Setup

Auto-detect and run appropriate setup:

```bash
# 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
```

### 4. Verify Clean Baseline

Run tests to ensure worktree starts clean:

```bash
# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
```

**If tests fail:** Report failures, ask whether to proceed or investigate.

**If tests pass:** Report ready.

### 5. Report Location

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

## Quick Reference

| Situation | Action |
|-----------|--------|
| `.worktrees/` exists | Use it (verify .gitignore) |
| `worktrees/` exists | Use it (verify .gitignore) |
| Both exist | Use `.worktrees/` |
| Neither exists | Check CLAUDE.md → Ask user |
| Directory not in .gitignore | Add it immediately + commit |
| Tests fail during baseline | Report failures + ask |
| No package.json/Cargo.toml | Skip dependency install |

## Common Mistakes

**Skipping .gitignore verification**
- **Problem:** Worktree contents get tracked, pollute git status
- **Fix:** Always grep .gitignore before creating project-local worktree

**Assuming directory location**
- **Problem:** Creates inconsistency, violates project conventions
- **Fix:** Follow priority: existing > CLAUDE.md > ask

**Proceeding with failing tests**
- **Problem:** Can't distinguish new bugs from pre-existing issues
- **Fix:** Report failures, get explicit permission to proceed

**Hardcoding setup commands**
- **Problem:** Breaks on projects using different tools
- **Fix:** Auto-detect from project files (package.json, etc.)

## Example Workflow

```
You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
```

## Red Flags

**Never:**
- Create worktree without .gitignore verification (project-local)
- Skip baseline test verification
- Proceed with failing tests without asking
- Assume directory location when ambiguous
- Skip CLAUDE.md check

**Always:**
- Follow directory priority: existing > CLAUDE.md > ask
- Verify .gitignore for project-local
- Auto-detect and run project setup
- Verify clean test baseline

## Integration

**Called by:**
- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
- Any skill needing isolated workspace

**Pairs with:**
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
- **executing-plans** or **subagent-driven-development** - Work happens in this worktree