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

Use this skill when... Use standard workflow instead when...

Starting implementation on any issue Reading code or researching (no changes)

Working on a feature or fix Quick single-line edit (typo, config value)

Processing multiple issues in parallel Interactive debugging session

Delegating work to subagents Already inside a worktree

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:

Task type Worktree path Branch name

Issue ./worktrees/issue-{N}

wt/issue-{N}

Feature ./worktrees/feat-{name}

wt/feat-{name}

Fix ./worktrees/fix-{name}

wt/fix-{name}

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)

• Create worktrees for each task

• Dispatch subagents with worktree paths

• Verify results in each worktree

• Push branches and create PRs sequentially

• Clean up worktrees

Subagent

• Work only in the assigned worktree

• Implement the assigned task

• Run tests

• Create a single, focused commit

• 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

Context Command

List worktrees git worktree list --porcelain

Create worktree git worktree add ./worktrees/issue-N -b wt/issue-N origin/main

Remove worktree git worktree remove ./worktrees/issue-N

Check worktree status git -C ./worktrees/issue-N status --porcelain

Worktree log git -C ./worktrees/issue-N log --oneline origin/main..HEAD

Worktree diff git -C ./worktrees/issue-N diff --stat origin/main

Push worktree branch git -C ./worktrees/issue-N push -u origin wt/issue-N

Run tests in worktree cd ./worktrees/issue-N && npm test

Prune stale git worktree prune

Quick Reference

Operation Command

Add worktree git worktree add <path> -b <branch> <start-point>

List worktrees git worktree list

Remove worktree git worktree remove <path>

Prune stale git worktree prune

Lock worktree git worktree lock <path>

Unlock worktree git worktree unlock <path>

Move worktree git worktree move <path> <new-path>

Related Skills

• git-branch-pr-workflow - Standard branch workflows

• git-rebase-patterns - Advanced rebase techniques

• multi-agent-workflows - General agent orchestration