---
name: worktree-workflow
description: |
  Manages git worktrees for isolated feature development. MUST be used when:
  - A plan has been approved and implementation is about to begin
  - User says "implement", "let's build", "start coding", or similar
  - Transitioning from planning phase to coding phase
  - Creating a new feature, fix, or refactor that will need a PR
  Also use when user asks about worktree status or cleanup.
---

# Worktree Workflow

Manages git worktrees for isolated feature development. Creates worktrees before implementation, cleans up after merge.

## Current Worktree Status

!`bash .claude/skills/worktree-workflow/status.sh 2>/dev/null || git worktree list`

## Phase 1: Before Implementation

**CRITICAL**: Before writing ANY implementation code for an approved plan, create a worktree.

### 1. Derive Branch Name

From the plan context, create a descriptive branch name:
- `feature/<name>` - New functionality
- `fix/<name>` - Bug fixes
- `refactor/<name>` - Code restructuring
- `chore/<name>` - Maintenance tasks

Use kebab-case, keep it short but descriptive.

### 2. Create Branch and Worktree

```bash
# Ensure base branch is current
git fetch origin <base-branch>

# Create branch from base
git branch <branch-name> origin/<base-branch>

# Create worktree
git worktree add <project-root>-<short-name> <branch-name>

# Configure git identity in worktree
cd <project-root>-<short-name>
git config user.name "<Your Name>"
git config user.email "<your@email.com>"
```

### 3. Work in Worktree

All file operations during implementation use the worktree path, not the main repo.

## Phase 2: After Merge

When a branch's PR is merged:

### Check if Merged

```bash
gh pr view <branch-name> --json state,mergedAt
```

### Cleanup

```bash
git worktree remove <worktree-path>
git branch -D <branch-name>
```

## Important Rules

1. **Never implement in main repo** - Always use a worktree
2. **One worktree per feature** - Don't mix unrelated changes
3. **Clean up promptly** - Remove worktrees after PRs merge
4. **Protected branches** - Never delete your base branch (main, develop, master)