git-worktree-agent-workflow（git worktree Agent 工作流程）

Git Worktree Agent Workflow

Start every implementation in an isolated worktree. Each task gets its own directory, its own branch, and produces one focused PR.

When to Use This Skill

Core Principles

• Isolation by default: Every implementation task starts in a worktree
• Clean main: The main working directory stays on main, always clean
• Atomic PRs: One worktree = one branch = one PR = one purpose
• Parallel-ready: Multiple worktrees can be active simultaneously
• Shared .git: Worktrees share the repository database — no cloning overhead

Context

• Current branch:!git branch --show-current
• Worktrees:!git worktree list --porcelain
• Uncommitted changes:!git status --porcelain
• Default branch:!git symbolic-ref --short refs/remotes/origin/HEAD

Execution

Step 1: Ensure clean main

Fetch latest and confirm the main working directory is clean.

git fetch origin --prune
git status --porcelain

If uncommitted changes exist, stash them before proceeding.

Step 2: Create worktree

Create an isolated working directory for the task.

# Ensure worktrees directory exists (gitignored)
mkdir -p worktrees

# Single issue
git worktree add ./worktrees/issue-47 -b wt/issue-47 origin/main

# Feature work
git worktree add ./worktrees/feat-auth -b wt/feat-auth origin/main

Naming conventions:

Why ./worktrees/: Inside the project directory so agents already have file permissions. The /worktrees/ entry in .gitignore prevents tracking worktree contents.

Step 3: Implement in the worktree

All work happens inside the worktree directory.

Single agent — work directly:

# Edit files in the worktree
# Run tests in the worktree
cd ./worktrees/issue-47 && npm test

Subagent — pass the absolute path:

You are working in the worktree at: {repo_root}/worktrees/issue-{N}

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

{issue description}

## Your task
1. {specific tasks}
2. Run tests to verify changes
3. Stage all changes and create a commit with message:
   {commit type}({scope}): {description}

   Fixes #{N}

Work ONLY within {repo_root}/worktrees/issue-{N}

Multiple issues in parallel — create one worktree per issue, launch agents simultaneously:

mkdir -p worktrees
git worktree add ./worktrees/issue-47 -b wt/issue-47 origin/main
git worktree add ./worktrees/issue-49 -b wt/issue-49 origin/main
git worktree add ./worktrees/issue-50 -b wt/issue-50 origin/main

Then dispatch agents in parallel — each receives its own worktree path. Agents run simultaneously because each has an isolated directory with no file conflicts.

Step 4: Verify before integration

# Check each worktree has a clean, focused commit
git -C ./worktrees/issue-47 log --oneline origin/main..HEAD
git -C ./worktrees/issue-47 diff --stat origin/main

# Run tests in the worktree
cd ./worktrees/issue-47 && npm test

Verification checklist:

• Commit references the correct issue number
• Tests pass in the worktree
• Changes are focused on the single task
• No unrelated modifications

Step 5: Push and create PR

Push the worktree branch and create a PR. Handle PRs sequentially to maintain clean history.

# Push
git -C ./worktrees/issue-47 push -u origin wt/issue-47

# Create PR
gh pr create --head wt/issue-47 --base main \
  --title "fix(scope): description" \
  --body "Fixes #47"

Step 6: Clean up

Remove worktrees after PRs are created (or merged).

# Remove worktrees
git worktree remove ./worktrees/issue-47

# Prune stale references
git worktree prune

# Delete local branch (after PR merge)
git branch -D wt/issue-47

# Remove empty worktrees directory
rmdir worktrees 2>/dev/null || true

Orchestrator vs Subagent Roles

Orchestrator (main agent)

1. Create worktrees for each task
2. Dispatch subagents with worktree paths
3. Verify results in each worktree
4. Push branches and create PRs sequentially
5. Clean up worktrees

Subagent

1. Work only in the assigned worktree
2. Implement the assigned task
3. Run tests
4. Create a single, focused commit
5. Report completion

Dependency Installation

Each worktree is a separate directory tree. If the project uses node_modules, vendor, or similar:

# Install dependencies in the worktree
cd ./worktrees/issue-47 && npm install

Shared lockfiles ensure consistent versions across worktrees.

Example Flow

Orchestrator (main repo, on main branch)
    |
    +--- Step 1: git fetch, confirm clean
    |
    +--- Step 2: Create worktrees
    |         +-- ./worktrees/issue-47
    |         +-- ./worktrees/issue-49
    |
    +--- Step 3: Launch agents IN PARALLEL
    |         |
    |         +---> Agent 1 -> ./worktrees/issue-47
    |         |         +-- Implements, tests, commits
    |         |
    |         +---> Agent 2 -> ./worktrees/issue-49
    |                   +-- Implements, tests, commits
    |
    +--- Step 4: Verify each worktree
    |
    +--- Step 5: Push + create PRs (sequential)
    |
    +--- Step 6: Cleanup

Agentic Optimizations

Quick Reference

Related Skills

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