worktree-lifecycle

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):

# 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