/worktree

name: worktree
description: "Manage git worktrees (--list default, --status, --review, --merge, --discard)"
argument-hint: "Optional flags: --list (default), --status FEATURE, --review FEATURE, --merge FEATURE, --discard FEATURE"
allowed-tools: [Task, Read, Write, Bash, Grep, Glob]
disable-model-invocation: true
user-invocable: true
user_facing: true

Implementation

python3 ~/.claude/lib/worktree_command.py "$@"

---

Worktree - Git Worktree Management

**Safe feature isolation with git worktrees for review/merge/discard workflow**

The `/worktree` command provides a complete workflow for managing git worktrees created by the autonomous development pipeline. It enables reviewing changes, merging to main branch, or discarding unwanted work - all without affecting your main working directory.

---

Quick Start

# List all worktrees (default mode)
/worktree                    # Shows all active worktrees
/worktree --list             # Explicit list mode

# Show detailed status
/worktree --status my-feature    # Commits ahead/behind, uncommitted changes

# Interactive review (diff + approve/reject)
/worktree --review my-feature    # Shows diff, prompts for merge approval

# Merge to target branch
/worktree --merge my-feature     # Merges feature to master

# Discard worktree
/worktree --discard my-feature   # Deletes worktree with confirmation

**Time**: 5-30 seconds (depends on mode) **Interactive**: Review and discard modes require confirmation **Safe Operations**: All destructive operations require explicit approval

---

Use Cases

When to Use /worktree

**Review workflow**:

• Feature completed in worktree
• Want to review changes before merging
• Need to compare against main branch
• Decide whether to merge or discard

**Isolation benefits**:

• Main branch stays clean
• Multiple features in parallel
• Easy rollback (just discard)
• No context switching overhead

**Typical workflow**: 1. Feature developed in worktree (via `/auto-implement`) 2. Review changes (`/worktree --review my-feature`) 3. Approve to merge (or reject to iterate) 4. Discard worktree after merge (`/worktree --discard my-feature`)

---

Worktree Modes

List Mode (`--list`) - DEFAULT

Shows all active worktrees with status indicators.

**What it does**:

• Lists all worktrees in repository
• Shows feature name, branch, and status
• Filters out main repository
• Quick overview of all features in progress

**When to use**:

• Check what features are in progress
• Find worktree names for other operations
• See status at a glance

**Example**:

/worktree
/worktree --list

**Output**:

Feature              Branch                         Status
------------------------------------------------------------
feature-auth         feature/feature-auth           clean
feature-logging      feature/feature-logging        dirty
hotfix-123           hotfix/hotfix-123              active

**Status indicators**:

• `clean` - No uncommitted changes, ready to merge
• `dirty` - Has uncommitted changes
• `active` - Currently checked out
• `stale` - Directory doesn't exist (orphaned)
• `detached` - Detached HEAD state

---

Status Mode (`--status FEATURE`)

Shows detailed information for a specific worktree.

**What it does**:

• Path to worktree directory
• Current branch name
• Clean/dirty status
• Commits ahead/behind target branch
• List of uncommitted files

**When to use**:

• Before merging (check if ready)
• Troubleshooting worktree issues
• Understanding feature state

**Example**:

/worktree --status feature-auth

**Output**:

Worktree Status: feature-auth
============================================================
Path:            /Users/dev/project/.worktrees/feature-auth
Branch:          feature/feature-auth
Status:          dirty
Target Branch:   master
Commits Ahead:   5
Commits Behind:  2

Uncommitted Changes (3 files):
  - auth/models.py
  - auth/tests.py
  - README.md

**Understanding output**:

• **Commits Ahead**: How many commits will be merged
• **Commits Behind**: How many commits from master are missing
• **Uncommitted Changes**: Files modified but not committed

---

Review Mode (`--review FEATURE`)

Interactive diff review with approve/reject workflow.

**What it does**: 1. Shows full git diff against target branch 2. Prompts for approval (approve/reject) 3. If approved → automatically merges to target branch 4. If rejected → exits without merging

**When to use**:

• Final review before merging
• Ensure changes match expectations
• Catch unintended modifications
• Quality gate before integration

**Example**:

/worktree --review feature-auth

**Output**:

Diff for worktree: feature-auth
============================================================
diff --git a/auth/models.py b/auth/models.py
index 1234567..89abcde 100644
--- a/auth/models.py
+++ b/auth/models.py
@@ -10,6 +10,12 @@ class User(Model):
     email = CharField()
+    def authenticate(self, password):
+        """Authenticate user with password."""
+        return check_password(password, self.password_hash)
+
 [... more diff output ...]
============================================================

Approve or reject changes? [approve/reject]: approve

✓ Successfully merged 12 files

**Interactive prompts**:

• Approval required before merge
• Shows all changes first
• Safe default: reject (if unclear)

---

Merge Mode (`--merge FEATURE`)

Directly merge worktree to target branch without review.

**What it does**:

• Checks out target branch (default: master)
• Merges feature branch
• Shows list of merged files
• Handles merge conflicts gracefully

**When to use**:

• Already reviewed changes manually
• Confident in worktree state
• Non-interactive merge needed
• Batch processing multiple features

**Example**:

/worktree --merge feature-auth

**Success output**:

✓ Successfully merged 12 files

Merged files:
  - auth/models.py
  - au