Git Worktree Agent Workflow

Orchestrate parallel agent workflows using git worktrees for isolated, concurrent issue resolution.

When to Use This Skill

Core Expertise

• Issue Isolation: Create independent working directories for each issue
• Contamination Recovery: Preserve mixed work as patches, reset, redistribute
• Parallel Execution: Launch multiple agents working simultaneously
• Atomic PRs: Each worktree produces exactly one focused commit/PR
• Clean Integration: Sequential PR creation maintains proper git history

Problem Statement

When multiple issues get mixed into a single branch/PR (contamination), or when you need to work on multiple independent issues in parallel, the standard single-branch workflow becomes a bottleneck. Each issue blocks the others, and mixed commits make clean PRs impossible.

Solution: Use git worktrees to create isolated working directories for each issue, allowing parallel agent work with clean, single-purpose commits.

Workflow Phases

Phase 1: Preserve and Reset

Save all in-progress work and reset to a clean baseline.

# 1. Identify the clean base commit
git log --oneline -20  # Find last clean commit before contamination

# 2. Preserve work as patches
git format-patch <clean-base>..HEAD -o /tmp/patches/

# 3. Save stash if exists
git stash show -p > /tmp/patches/stash.patch 2>/dev/null || true

# 4. Save uncommitted changes
git diff > /tmp/patches/working-tree.patch
git diff --staged > /tmp/patches/staged.patch

# 5. Reset to clean state (requires user confirmation)
git reset --hard <clean-base>
git stash drop 2>/dev/null || true

Patch contents:

• 0001-*.patch, 0002-*.patch, etc. – Individual commits
• stash.patch – Stashed changes
• working-tree.patch – Uncommitted modifications
• staged.patch – Staged but uncommitted changes

Phase 2: Create Isolated Worktrees

Create independent working directories for each issue.

# Create worktree for each issue
git worktree add ../project-wt-issue-47 -b wt/issue-47 main
git worktree add ../project-wt-issue-49 -b wt/issue-49 main
git worktree add ../project-wt-issue-50 -b wt/issue-50 main

# List all worktrees
git worktree list

# Each worktree:
# - Has its own working directory
# - Shares the same .git database (efficient)
# - Has an independent branch
# - Can be worked on simultaneously

Naming convention: ../project-wt-issue-{N} with branch wt/issue-{N}

Phase 3: Apply Existing Work

Distribute saved patches to appropriate worktrees.

For complete patches (single-issue commits):

cd ../project-wt-issue-47
git am /tmp/patches/0001-feat-issue-47-implementation.patch

For mixed patches (multi-issue commits):

# Extract specific files from a mixed commit
git show <commit> -- path/to/file1 path/to/file2 > /tmp/patches/issue-47-files.patch

# Apply to appropriate worktree
cd ../project-wt-issue-47
git apply /tmp/patches/issue-47-files.patch

For partial work (needs agent completion):

cd ../project-wt-issue-50
git apply /tmp/patches/partial-work.patch
# Agent will complete remaining work

Phase 4: Parallel Agent Execution

Launch agents to complete work in their respective worktrees.

Critical: Each agent receives the absolute path to its worktree.

Agent prompt template:

You are working in the worktree at: /absolute/path/to/project-wt-issue-{N}

**Issue #{N}**: {issue title}

{issue description}

## Already applied changes
{list of files with partial changes}

## Your task
1. {specific tasks}
2. Stage all changes and create a commit with message:
   {commit type}: {description}

   Fixes #{N}

   Co-Authored-By: Claude <noreply@anthropic.com>

DO NOT modify any files outside the worktree at /absolute/path/to/project-wt-issue-{N}

Parallelization: Agents run simultaneously because:

• Each has its own isolated directory
• No file conflicts possible
• Independent git histories until merge

Phase 5: Sequential Integration

Push branches and create PRs in order.

# From each worktree, push to origin
cd ../project-wt-issue-47
git push origin wt/issue-47:fix/issue-47

# Create PR
gh pr create --head fix/issue-47 --base main \
  --title "fix: {description}" \
  --body "Fixes #47"

Why sequential: PRs are created one at a time to:

• Allow proper PR numbering
• Enable dependent PRs if needed
• Maintain clean git history

Phase 6: Cleanup

Remove worktrees and temporary branches after PRs are merged.

# Remove worktrees
git worktree remove ../project-wt-issue-47
git worktree remove ../project-wt-issue-49
git worktree remove ../project-wt-issue-50

# Prune stale worktree references
git worktree prune

# Delete local branches
git branch -D wt/issue-47 wt/issue-49 wt/issue-50

# Clean up patches
rm -rf /tmp/patches/

Orchestrator Responsibilities

The main agent (orchestrator) handles:

1. Analysis: Determine which issues are independent vs. interdependent
2. Patch extraction: Separate mixed commits into per-issue patches
3. Worktree creation: Set up isolated environments
4. Agent dispatch: Launch subagents with precise worktree paths
5. Verification: Run tests in each worktree before integration
6. Integration: Push branches and create PRs
7. Cleanup: Remove worktrees and temporary artifacts

Subagent Responsibilities

Each subagent handles:

1. Work in assigned worktree only (critical constraint)
2. Complete the assigned issue
3. Run relevant tests
4. Create a single, focused commit
5. Report completion status

Decision Matrix

Verification Checklist

Before integration:

• Each worktree has exactly 1 commit ahead of base
• Tests pass in each worktree
• Commits reference correct issue numbers
• No cross-worktree file modifications

After integration:

• Each PR has clean, single-purpose changes
• All worktrees removed
• Local branches cleaned up
• Main branch unchanged (PRs merge to remote)

Key Constraints for Agents

1. Absolute paths only: Always pass full paths to avoid confusion
2. No directory changes: Work should happen via path arguments, not cd
3. Single commit per worktree: Keep changes atomic and reviewable
4. Issue reference in commit: Always include Fixes #N for auto-closing
5. Dependency installation: Each worktree may need bun install / npm install

Agentic Optimizations

Quick Reference

Example Coordination Flow

Orchestrator (main repo)
    |
    +--- Phase 1: Analyze & preserve contaminated work
    |
    +--- Phase 2: Create worktrees
    |         +-- ../wt-issue-47 (complete patch)
    |         +-- ../wt-issue-49 (complete patch)
    |         +-- ../wt-issue-50 (partial, needs agent)
    |
    +--- Phase 3: Apply patches
    |         +-- git am (complete patches)
    |         +-- git apply (partial patches)
    |
    +--- Phase 4: Launch agents IN PARALLEL
    |         |
    |         +---> Agent 1 -> ../wt-issue-50
    |         |         +-- Completes work, commits
    |         |
    |         +---> Agent 2 -> ../wt-issue-XX
    |                   +-- Implements from scratch, commits
    |
    +--- Phase 5: Sequential integration
    |         +-- Verify tests pass in each worktree
    |         +-- Push branches to origin
    |         +-- Create PRs
    |
    +--- Phase 6: Cleanup
              +-- Remove worktrees
              +-- Delete local branches

Related Skills

• git-branch-pr-workflow – Standard branch workflows
• git-rebase-patterns – Advanced rebase techniques
• multi-agent-workflows – General agent orchestration