worktree-lifecycle

What this skill does

# Worktree Lifecycle

**Purpose:** Manage git worktrees for isolated feature work with safety checks, multi-stack setup, and clean lifecycle management.

## When to Use

This skill applies whenever you:
- Start a new feature that requires isolated workspace
- Execute risky or experimental changes
- Need to keep current work untouched while testing alternatives
- Coordinate parallel agent work (each agent in separate worktree)
- Follow an implementation plan requiring clean environment
- Preserve long-running feature work across sessions

**Trigger keywords:** experiment, prototype, risky, breaking, parallel, isolate, worktree, workspace

## Red Flags (Anti-Patterns)

- [ ] Creating worktree without checking if branch already exists
- [ ] Creating worktree without checking if directory path is available
- [ ] Forgetting to add worktree directory to .gitignore
- [ ] Manually deleting worktree with `rm -rf` (use `git worktree remove`)
- [ ] Removing worktree with uncommitted changes without user confirmation
- [ ] Using same branch in multiple worktrees simultaneously
- [ ] Working in worktree after returning to main directory (stale CWD)
- [ ] Not storing original CWD before entering worktree
- [ ] Skipping dependency installation in new worktree
- [ ] Not running baseline tests before starting work

## 6-Phase Lifecycle

### Phase 1: Pre-flight Checks

**Purpose:** Verify all prerequisites before creating anything.

**Required checks** (all must pass):

```bash
# 1. Verify git repository
git rev-parse --git-dir &>/dev/null
if [ $? -ne 0 ]; then
  ERROR: "Not a git repository"
  RECOVERY: Abort with clear error message
fi

# 2. Detect detached HEAD state
if ! git symbolic-ref HEAD &>/dev/null; then
  WARNING: "Currently in detached HEAD state"
  RECOVERY: Ask user if they want to create branch from current commit
fi

# 3. Check if branch already in a worktree
if git worktree list | grep -q "$BRANCH"; then
  ERROR: "Branch $BRANCH already checked out in a worktree"
  RECOVERY: Ask user - reuse existing, rename branch, or cancel
fi

# 4. Check if branch exists (but not in worktree)
if git branch --list "$BRANCH" | grep -q .; then
  WARNING: "Branch $BRANCH already exists"
  RECOVERY: Ask user - use existing branch or create new with different name
fi

# 5. Check if target path is available
# IMPORTANT: Create directory first before checking (git check-ignore needs path to exist)
mkdir -p "$WORKTREE_DIR"
if [ -d "$WORKTREE_PATH" ]; then
  ERROR: "Directory $WORKTREE_PATH already exists"
  RECOVERY: Ask user - choose different path or remove existing
fi
```

**Error Recovery Table:**

| Error | Detection | Recovery |
|-------|-----------|----------|
| Not a git repo | `git rev-parse --git-dir` fails | Abort with clear error |
| Detached HEAD | `git symbolic-ref HEAD` fails | Ask: create branch from commit? |
| Branch in worktree | `git worktree list \| grep $BRANCH` succeeds | Ask: reuse, rename, or cancel |
| Branch exists | `git branch --list $BRANCH` returns result | Ask: use existing or rename |
| Path exists | Directory already present | Ask: choose different path or remove |
| Parent not writable | Cannot create parent directory | Abort with permission error |

### Phase 2: Directory Selection

**Priority order** (cascading, first match wins):

1. **Check for existing `.worktrees/` directory** → use it (no prompt)
2. **Check for existing `worktrees/` directory** → use it (no prompt)
3. **Check CLAUDE.md for worktree preference** → follow it (no prompt)
4. **Ask user** (only if no default found)

**For orchestrator integration**: Pass `WORKTREE_DIR=".worktrees"` to skip this phase entirely.

**Example detection**:
```bash
if [ -d ".worktrees" ]; then
  WORKTREE_DIR=".worktrees"
elif [ -d "worktrees" ]; then
  WORKTREE_DIR="worktrees"
elif grep -q "worktree.*directory" CLAUDE.md 2>/dev/null; then
  WORKTREE_DIR=$(grep "worktree.*directory" CLAUDE.md | extract_path)
else
  # Ask user via AskUserQuestion
  # Options: .worktrees/, worktrees/, custom
fi
```

### Phase 3: Creation

**Steps** (must be executed in order):

```bash
# 1. Verify .gitignore safety
# IMPORTANT: Directory must exist before git check-ignore
mkdir -p "$WORKTREE_DIR"

if ! git check-ignore -q "$WORKTREE_DIR" 2>/dev/null; then
  echo "$WORKTREE_DIR/" >> .gitignore
  git add .gitignore
  git commit -m "chore: add $WORKTREE_DIR to .gitignore"
fi

# 2. Store original CWD (critical for Phase 6 cleanup)
ORIGINAL_CWD=$(pwd)

# 3. Create worktree
git worktree add "$WORKTREE_PATH" -b "$BRANCH"

# 4. Verify creation succeeded
if [ ! -d "$WORKTREE_PATH" ]; then
  ERROR: "Worktree creation failed"
  RECOVERY: Clean up any partial state, report error
  exit 1
fi

# 5. Change to worktree directory
cd "$WORKTREE_PATH"

# 6. Initialize submodules (if any)
if [ -f .gitmodules ]; then
  git submodule update --init --recursive
fi

# 7. Write statusline worktree marker (persists across compaction)
if [ -n "$SESSION_ID" ]; then
  cat > "$HOME/.claude/.statusline-worktree-${SESSION_ID}" <<MARKER_EOF
{
  "worktree_path": "$WORKTREE_PATH",
  "branch": "$BRANCH",
  "worktree_name": "$(basename "$WORKTREE_PATH")"
}
MARKER_EOF
fi
```

**Error handling**: If `git worktree add` fails, clean up any partial state and report the error to user.

### Phase 4: Setup

**Multi-stack detection**:

```bash
# Detect all present stacks
STACKS=()
[ -f package.json ] && STACKS+=("nodejs")
[ -f Cargo.toml ] && STACKS+=("rust")
[ -f go.mod ] && STACKS+=("golang")
[ -f pyproject.toml ] || [ -f requirements.txt ] && STACKS+=("python")
[ -f Gemfile ] && STACKS+=("ruby")

# Run setup for each detected stack
for stack in "${STACKS[@]}"; do
  echo "Setting up $stack..."
  case "$stack" in
    nodejs)
      if [ -f bun.lockb ]; then
        bun install
      elif [ -f pnpm-lock.yaml ]; then
        pnpm install
      elif [ -f yarn.lock ]; then
        yarn install
      else
        npm install
      fi
      ;;
    rust)
      cargo build
      ;;
    golang)
      go mod download
      ;;
    python)
      if [ -f pyproject.toml ]; then
        pip install -e .
      else
        pip install -r requirements.txt
      fi
      ;;
    ruby)
      bundle install
      ;;
  esac
done
```

**Baseline test verification**:

```bash
# Run tests and capture output (allow pre-existing failures)
for stack in "${STACKS[@]}"; do
  case "$stack" in
    nodejs)
      if [ -f bun.lockb ]; then
        bun test 2>&1 | tee test-output.log
      else
        npm test 2>&1 | tee test-output.log
      fi
      ;;
    rust)
      cargo test 2>&1 | tee test-output.log
      ;;
    golang)
      go test ./... 2>&1 | tee test-output.log
      ;;
    python)
      pytest 2>&1 | tee test-output.log
      ;;
  esac

  # Parse test results (do NOT block on pre-existing failures)
  PASSING=$(grep -o '[0-9]* passing' test-output.log | cut -d' ' -f1)
  FAILING=$(grep -o '[0-9]* failing' test-output.log | cut -d' ' -f1)

  echo "Baseline tests: $PASSING passing, $FAILING failing"
  if [ "${FAILING:-0}" -gt 0 ]; then
    echo "WARNING: Pre-existing test failures detected. Proceed with caution."
  fi
done
```

### Phase 5: Handoff

**Structured output for orchestrator**:

```
Worktree ready:
  Path: .worktrees/feature-auth-system
  Branch: feature/auth-system
  Stacks: nodejs
  Dependencies: installed
  Tests: 47 passing, 0 failing
  Status: READY

Original CWD: /path/to/project
Worktree CWD: /path/to/project/.worktrees/feature-auth-system
```

**Write metadata to session** (for cleanup phase):

```bash
cat > "${SESSION_PATH}/worktree-metadata.json" <<EOF
{
  "worktreePath": "$WORKTREE_PATH",
  "absolutePath": "$(realpath $WORKTREE_PATH)",
  "branchName": "$BRANCH",
  "originalCwd": "$ORIGINAL_CWD",
  "createdAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "stacks": $(printf '%s\n' "${STACKS[@]}" | jq -R . | jq -s .),
  "baselineTests": {
    "passing": ${PASSING:-0},
    "failing": ${FAILING:-0}
  },
  "status": "active"
}
EOF
```

**Orchestrator context passing** (for