auto-build/plugin/commands/worktree.md

---
description: Manage git worktrees for feature isolation
argument-hint: <action> [name] - Actions: create, list, switch, cleanup
---

# Git Worktree Management

Manage isolated git worktrees for feature development. Worktrees provide complete isolation between features, preventing conflicts during parallel development.

## Actions

### create <feature-name>

Create a new isolated worktree for a feature.

**Workflow:**
1. Validate feature name provided
2. Determine project name from current directory
3. Create branch: `feature/ab-{feature-name}`
4. Create worktree at: `../ab-worktrees/{project}-{feature-name}/`
5. Register in `.auto-build-data/worktrees/worktree-registry.json`
6. Display success message with path

**Command:**
```bash
bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-create.sh {feature-name}
```

**Output:**
```
Created worktree for: feature-name
  Branch: feature/ab-feature-name
  Path: ../ab-worktrees/project-feature-name/

To work in this worktree:
  cd ../ab-worktrees/project-feature-name/
```

### list

List all active worktrees.

**Workflow:**
1. Read `.auto-build-data/worktrees/worktree-registry.json`
2. Verify each worktree still exists (git worktree list)
3. Display table:
   ```
   Active Worktrees:
   | Feature | Branch | Path | Created |
   |---------|--------|------|---------|
   | user-dashboard | feature/ab-user-dashboard | ../ab-worktrees/project-user-dashboard/ | 2h ago |
   ```

**Command:**
```bash
bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-list.sh
```

### switch <feature-name>

Provide instructions to switch to a worktree.

**Workflow:**
1. Look up worktree path from registry
2. Verify worktree exists
3. Display switch instructions:
   ```
   To switch to feature-name worktree:

   cd ../ab-worktrees/project-feature-name/

   Or start a new Claude Code session in that directory.
   ```

**Note:** Claude Code sessions are directory-bound, so actual switching requires changing the working directory.

### cleanup [feature-name]

Remove completed worktrees.

**Workflow:**
If feature-name provided:
1. Look up worktree in registry
2. Check if branch is merged to main
3. If merged or user confirms: Remove worktree and branch
4. Update registry

If no feature-name:
1. List all worktrees
2. Check which branches are merged
3. Offer to cleanup merged ones:
   ```
   Found 2 merged worktrees:
   - old-feature (merged 3 days ago)
   - bug-fix (merged 1 week ago)

   Remove these? [Yes] [Select] [No]
   ```

**Command:**
```bash
bash ${CLAUDE_PLUGIN_ROOT}/scripts/worktree-cleanup.sh [feature-name]
```

## Registry Format

`.auto-build-data/worktrees/worktree-registry.json`:
```json
{
  "worktrees": [
    {
      "name": "user-dashboard",
      "branch": "feature/ab-user-dashboard",
      "path": "../ab-worktrees/project-user-dashboard/",
      "created": "2025-01-15T10:30:00Z",
      "status": "active",
      "spec": ".auto-build-data/specs/user-dashboard/"
    }
  ]
}
```

## Worktree Location

Worktrees are created **outside** the project directory to avoid:
- Nested git repository issues
- IDE confusion
- Accidental commits from wrong directory

Structure:
```
/projects/
├── my-project/              # Main project
│   └── .auto-build-data/
└── ab-worktrees/            # Worktrees directory
    ├── my-project-user-dashboard/
    └── my-project-api-refactor/
```

## Error Cases

- **Branch already exists**: Ask to use existing or create new
- **Worktree path exists**: Ask to reuse or choose different path
- **Not a git repository**: Inform user and abort
- **Uncommitted changes**: Warn user before creating worktree