---
name: using-git-worktrees
description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans
---

# 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
ls -d .worktrees 2>/dev/null  # Preferred (hidden)
ls -d worktrees 2>/dev/null    # Alternative
```

This project already has a `.worktrees/` directory — use it.

### 2. Safety Verification

**MUST verify directory is ignored before creating worktree:**

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

**If NOT ignored:** Add to `.gitignore` and commit before proceeding.

### 3. Create Worktree

```bash
project=$(basename "$(git rev-parse --show-toplevel)")
git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME
cd .worktrees/$BRANCH_NAME
```

### 4. Run Project Setup

```bash
# This is a Node.js project
if [ -f package.json ]; then
  npm install
fi
```

### 5. Verify Clean Baseline

```bash
npm run test
```

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

### 6. Report Location

```
Worktree ready at .worktrees/$BRANCH_NAME
Tests passing (X tests, 0 failures)
Ready to implement.
```

## Quick Reference

| Situation | Action |
|-----------|--------|
| `.worktrees/` exists | Use it (verify ignored) |
| `.worktrees/` not ignored | Add to `.gitignore` + commit first |
| Tests fail during baseline | Report failures + ask |
| No package.json | Skip dependency install |

## Common Mistakes

### Skipping ignore verification
- **Problem:** Worktree contents get tracked, pollute git status
- **Fix:** Always use `git check-ignore` before creating worktree

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

## Red Flags

**Never:**
- Create worktree without verifying it's ignored
- Skip baseline test verification
- Proceed with failing tests without asking

**Always:**
- Verify directory is ignored
- Auto-detect and run project setup (`npm install`)
- Verify clean test baseline

## Integration

**Called by:**
- **brainstorming** — REQUIRED when design is approved and implementation follows
- **subagent-driven-development** — REQUIRED before executing any tasks
- **executing-plans** — REQUIRED before executing any tasks

**Pairs with:**
- **finishing-a-development-branch** — REQUIRED for cleanup after work complete