Worktree Management Skill Skill

Worktree Management Skill

Git worktree isolation for parallel agent development with simple, safe workflows.

Quick Start

# Create isolated worktree for a task
/sc:worktree create feature-auth

# List all active worktrees
/sc:worktree list

# Propose changes for human review
/sc:worktree propose feature-auth

# Clean up stale worktrees
/sc:worktree cleanup

Behavioral Flow

Create - Initialize isolated worktree with unique naming
Validate - Preflight checks (clean repo, no conflicts)
Assign - Spawn subagent with CWD set to worktree
Work - Agent operates in isolation, commits to branch
Propose - Push branch and create PR for human review
Cleanup - Remove merged/stale worktrees

Commands

| Command | Purpose | Git Operations | |---------|---------|----------------| | create <task-id> | Create isolated worktree | git worktree add -b wt/<task> | | list | Show all active worktrees | git worktree list | | status <task-id> | Check worktree state | git status, git log | | cleanup [--all] | Remove stale worktrees | git worktree remove, prune | | propose <task-id> | Create PR for human review | git push, gh pr create |

Flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | --commits | bool | true | Agent commits directly to branch | | --patches | bool | false | Agent produces patch files only | | --run-tests | bool | false | Run tests before proposing | | --force | bool | false | Override existing worktree/branch | | --base | string | main | Base branch for worktree |

Evidence Requirements

This skill does NOT require hard evidence. Worktree operations are self-documenting through:

Git worktree list output
Branch history
PR creation confirmation

Naming Convention

Worktrees use deterministic naming to prevent collisions:

Path:   .worktrees/<task-id>/
Branch: wt/<task-id>

Example:

Path:   .worktrees/feature-auth/
Branch: wt/feature-auth

Operations

Create Worktree

/sc:worktree create feature-auth

# Executes:
# 1. mkdir -p .worktrees
# 2. git worktree add -b wt/feature-auth .worktrees/feature-auth
# 3. Returns worktree path for subagent CWD

List Worktrees

/sc:worktree list

# Shows:
# - Active worktrees
# - Associated branches
# - Last commit info

Check Status

/sc:worktree status feature-auth

# Shows:
# - Uncommitted changes
# - Commits ahead of base branch
# - Conflict warnings

Propose Changes

/sc:worktree propose feature-auth

# Executes:
# 1. git push -u origin wt/feature-auth
# 2. gh pr create --title "feat: feature-auth" --body "..."
# 3. Returns PR URL for human review

Cleanup Worktrees

/sc:worktree cleanup          # Remove merged worktrees
/sc:worktree cleanup --all    # Remove ALL worktrees
/sc:worktree cleanup feature-auth  # Remove specific worktree

# Executes:
# 1. git worktree remove .worktrees/<task-id>
# 2. git branch -d wt/<task-id>
# 3. git worktree prune

Subagent Integration

When spawning a subagent to work in a worktree:

# 1. Create worktree
/sc:worktree create feature-auth

# 2. Spawn subagent with CWD
Task(
    prompt="Implement JWT authentication",
    subagent_type="general-purpose",
    # CWD implicitly set to .worktrees/feature-auth/
)

# 3. Agent works in isolation
# - All file operations scoped to worktree
# - Commits go to wt/feature-auth branch

# 4. Propose for review
/sc:worktree propose feature-auth

Preflight Checks

Before creating a worktree, the skill validates:

Repository State
- Repo is clean OR --force flag provided
- Main branch is up to date
Branch Availability
- wt/<task-id> branch doesn't exist OR explicit reuse
- No conflicting remote branch
Path Availability
- .worktrees/<task-id> doesn't exist OR --force flag

Conflict Detection

Before proposing, the skill checks for conflicts:

# Fetch latest changes
git fetch origin main

# Check if worktree is behind
git merge-base --is-ancestor origin/main HEAD

# Warn but don't block if behind
# Human reviewer handles merge strategy

Examples

Single Agent Workflow

# Create worktree
/sc:worktree create add-logging

# Work in worktree (agent operates here)
# ... agent makes changes, commits ...

# Propose changes
/sc:worktree propose add-logging

# Human reviews PR, merges

# Cleanup
/sc:worktree cleanup add-logging

Parallel Multi-Agent Workflow

# Orchestrator creates multiple worktrees
/sc:worktree create feature-auth
/sc:worktree create feature-logging
/sc:worktree create feature-metrics

# Spawn agents in parallel (each with own worktree)
# Agent A -> .worktrees/feature-auth/
# Agent B -> .worktrees/feature-logging/
# Agent C -> .worktrees/feature-metrics/

# Propose all changes
/sc:worktree propose feature-auth
/sc:worktree propose feature-logging
/sc:worktree propose feature-metrics

# Human reviews 3 PRs, merges sequentially

# Cleanup all
/sc:worktree cleanup --all

Patch Mode (No Direct Commits)

/sc:worktree create refactor-api --patches

# Agent produces .patch files instead of commits
# Orchestrator reviews patches before applying

/sc:worktree propose refactor-api  # Creates PR from patches

MCP Integration

PAL MCP (Validation & Review)

| Tool | When to Use | Purpose | |------|-------------|---------| | mcp__pal__precommit | Before propose | Validate changes in worktree | | mcp__pal__codereview | Before propose | Review worktree changes | | mcp__pal__consensus | Conflict resolution | Multi-model merge strategy |

PAL Usage Patterns

# Validate worktree changes before proposing
mcp__pal__precommit(
    path=".worktrees/feature-auth",
    step="Validating worktree changes",
    findings="Security, test coverage, completeness",
    compare_to="main"
)

# Review worktree branch
mcp__pal__codereview(
    review_type="full",
    step="Reviewing feature-auth worktree",
    relevant_files=[".worktrees/feature-auth/src/auth.py"]
)

Rube MCP (Automation & Notifications)

| Tool | When to Use | Purpose | |------|-------------|---------| | mcp__rube__RUBE_SEARCH_TOOLS | GitHub integration | Find PR tools | | mcp__rube__RUBE_MULTI_EXECUTE_TOOL | Propose command | Create PR, notify team |

Rube Usage Patterns

# Create PR and notify team
mcp__rube__RUBE_MULTI_EXECUTE_TOOL(tools=[
    {"tool_slug": "GITHUB_CREATE_PULL_REQUEST", "arguments": {
        "repo": "myapp",
        "title": "feat: feature-auth from worktree",
        "body": "## Worktree: feature-auth\nCreated via /sc:worktree",
        "base": "main",
        "head": "wt/feature-auth"
    }},
    {"tool_slug": "SLACK_SEND_MESSAGE", "arguments": {
        "channel": "#pull-requests",
        "text": "New PR from worktree: wt/feature-auth"
    }}
])

Flags (Extended)

| Flag | Type | Default | Description | |------|------|---------|-------------| | --pal-review | bool | false | Use PAL codereview before propose | | --create-pr | bool | true | Create GitHub PR via Rube | | --notify | string | - | Notify via Rube (slack, teams) | | --draft | bool | false | Create draft PR |

Tool Coordination

Bash - Git worktree commands, directory operations
Read - Check worktree status and logs
Task - Spawn subagents with worktree CWD
PAL MCP - Pre-propose validation, code review
Rube MCP - PR creation, team notifications

Safety Guarantees

Isolation - Each worktree has separate working directory
No Auto-Merge - Human review required for all merges
Unique Naming - Deterministic paths prevent collisions
Crash-Safe - cleanup --all removes stale worktrees
Warning-Only Conflicts - Conflicts warn but don't block

Limitations

No automatic quality scoring (use CI/tests)
No lease tracking (periodic cleanup instead)
No sophisticated conflict resolution (human review)
No auto-merge to main (PR-based workflow)

Agent Skills: Worktree Management Skill

Install this agent skill to your local

Skill Files