git-worktrees

name	git-worktrees
description	Parallel development workflow using git worktrees. Prepares isolated worktree directories and executes tasks across multiple workspaces for concurrent feature development. Use when user wants parallel branches, concurrent development, or asks about git worktrees.

Git Worktrees - Parallel Development Workflow

Enable parallel feature development by creating isolated git worktree directories, then executing the same plan across multiple workspaces simultaneously.

Workflow Overview

Phase 1: Prepare Worktrees

Create N isolated worktrees for parallel development:

# Create worktree directory
mkdir -p trees

# Create worktrees (example: 3 parallel workspaces)
git worktree add -b feature-1 ./trees/feature-1
git worktree add -b feature-2 ./trees/feature-2
git worktree add -b feature-3 ./trees/feature-3

# Verify worktrees
git worktree list

Each worktree is a complete, isolated copy of the codebase. All worktrees share git history but have independent working directories.

Phase 2: Execute Tasks in Parallel

Launch N subagents (one per worktree) using the Task tool:

1. Each agent independently implements the plan in their workspace
2. Agents produce RESULTS.md summarising their changes
3. Compare results and cherry-pick the best implementation

Example Task invocation:

Use the Task tool to launch a general-purpose agent with:
- prompt: "Working in trees/feature-1, implement [plan]. Write a RESULTS.md summarising changes."
- run_in_background: true (for parallel execution)

When to Use

• Experimental implementations - Compare different approaches
• A/B testing code changes - Try multiple solutions simultaneously
• Reducing iteration time - Run multiple attempts in parallel
• Complex refactoring - Test different strategies concurrently

Best Practices

1. Keep worktree count reasonable (2-4) to manage cognitive load
2. Focus on code changes only - No tests during parallel execution
3. Clean up worktrees after selecting the winning implementation:

   git worktree remove ./trees/feature-1
   git worktree prune
   

4. Cherry-pick the winner to your main branch:

   git cherry-pick feature-2
   # or merge the branch
   git merge feature-2
   

Directory Structure

project/
├── trees/
│   ├── feature-1/     # Worktree 1 (full codebase copy)
│   │   └── RESULTS.md
│   ├── feature-2/     # Worktree 2 (full codebase copy)
│   │   └── RESULTS.md
│   └── feature-3/     # Worktree 3 (full codebase copy)
│       └── RESULTS.md
└── (main working directory)

RESULTS.md Template

Each agent should produce a summary in this format:

# Results - [Feature Name]

## Changes Made
- List of files modified/created
- Summary of approach taken

## Key Decisions
- Design choices made
- Trade-offs considered

## Testing Notes
- How to verify the implementation
- Known limitations