---
name: using-git-worktrees
description: Use when starting implementation work that needs branch isolation — creates a .worktrees/ workspace before ship executes tasks
---

# Using Git Worktrees

Isolated workspace sharing the same repo. `ship` calls this at the start of every plan execution.

**RTK note:** `git` commands auto-proxied — run them normally.

## Setup Steps

### 1. Ensure `.worktrees/` is gitignored

```bash
git check-ignore -q .worktrees 2>/dev/null || echo ".worktrees/" >> .gitignore && git add .gitignore && git commit -m "chore: gitignore .worktrees/"
```

### 2. Create worktree

```bash
git worktree add .worktrees/<branch-name> -b <branch-name>
```

Branch naming: `feat/<slug>`, `fix/<slug>`, `chore/<slug>` — derive from plan filename or task description.

### 3. Install dependencies

```bash
cd .worktrees/<branch-name>

# Auto-detect:
[ -f bun.lockb ] && bun install
[ -f package-lock.json ] && npm install
[ -f yarn.lock ] && yarn
[ -f Cargo.toml ] && cargo build
[ -f requirements.txt ] && pip install -r requirements.txt
```

### 4. Verify clean baseline

Run project test suite. If tests fail → report failures, don't proceed.

### 5. Report ready

```
Worktree ready: .worktrees/<branch-name>/
Branch: <branch-name>
Tests: N passing
```

Pass `WORKTREE_PATH=.worktrees/<branch-name>` to all implementer subagents in their prompt context.

## Cleanup

Handled by `finishing-a-development-branch` — don't remove manually.

## Red Flags

**Never:**
- Skip gitignore check for `.worktrees/`
- Proceed with failing baseline tests
- Use `/tmp` — worktrees stay inside project

## Integration

**Called by:** `ship` — first step before any task dispatch
**Pairs with:** `finishing-a-development-branch` — cleanup after work complete