worktree-manager

What this skill does

# Alpha-Forge Worktree Manager

<!-- ADR: /docs/adr/2025-12-14-alpha-forge-worktree-management.md -->

Create and manage git worktrees for the alpha-forge repository with automatic branch naming, consistent conventions, and lifecycle management.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

Use this skill when:

- Creating a new worktree for alpha-forge development
- Setting up a worktree from a remote branch
- Using an existing local branch in a new worktree
- Managing multiple parallel feature branches

## Operational Modes

This skill supports three distinct modes based on user input:

| Mode             | User Input Example                            | Action                                |
| ---------------- | --------------------------------------------- | ------------------------------------- |
| **New Branch**   | "create worktree for sharpe validation"       | Derive slug, create branch + worktree |
| **Remote Track** | "create worktree from origin/feat/existing"   | Track remote branch in new worktree   |
| **Local Branch** | "create worktree for feat/2025-12-15-my-feat" | Use existing branch in new worktree   |

---

## Mode 1: New Branch from Description (Primary)

This is the most common workflow. User provides a natural language description, Claude derives the slug.

### Step 1: Parse Description and Derive Slug

**Claude derives kebab-case slugs following these rules:**

**Word Economy Rule**:

- Each word in slug MUST convey unique meaning
- Remove filler words: the, a, an, for, with, and, to, from, in, on, of, by
- Avoid redundancy (e.g., "database" after "ClickHouse")
- Limit to 3-5 words maximum

**Conversion Steps**:

1. Parse description from user input
2. Convert to lowercase
3. Apply word economy (remove filler words)
4. Replace spaces with hyphens

**Examples**:

| User Description                        | Derived Slug                    |
| --------------------------------------- | ------------------------------- |
| "sharpe statistical validation"         | `sharpe-statistical-validation` |
| "fix the memory leak in metrics"        | `memory-leak-metrics`           |
| "implement user authentication for API" | `user-authentication-api`       |
| "add BigQuery data source support"      | `bigquery-data-source`          |

### Step 2: Verify Main Worktree Status

**CRITICAL**: Before proceeding, check that main worktree is on `main` branch.

```bash
/usr/bin/env bash << 'GIT_EOF'
cd ~/eon/alpha-forge
CURRENT=$(git branch --show-current)
GIT_EOF
```

**If NOT on main/master**:

Use AskUserQuestion to warn user:

```yaml
question: "Main worktree is on '$CURRENT', not main. Best practice is to keep main worktree clean. Continue anyway?"
header: "Warning"
options:
  - label: "Continue anyway"
    description: "Proceed with worktree creation"
  - label: "Switch main to 'main' first"
    description: "I'll switch the main worktree to main branch before creating"
multiSelect: false
```

If user selects "Switch main to 'main' first":

```bash
cd ~/eon/alpha-forge
git checkout main
```

### Step 3: Fetch Remote and Display Branches

```bash
cd ~/eon/alpha-forge
git fetch --all --prune

# Display available branches for user reference
echo "Available remote branches:"
git branch -r | grep -v HEAD | head -20
```

### Step 4: Prompt for Branch Type

Use AskUserQuestion:

```yaml
question: "What type of branch is this?"
header: "Branch type"
options:
  - label: "feat"
    description: "New feature or capability"
  - label: "fix"
    description: "Bug fix or correction"
  - label: "refactor"
    description: "Code restructuring (no behavior change)"
  - label: "chore"
    description: "Maintenance, tooling, dependencies"
multiSelect: false
```

### Step 5: Prompt for Base Branch

Use AskUserQuestion:

```yaml
question: "Which branch should this be based on?"
header: "Base branch"
options:
  - label: "main (Recommended)"
    description: "Base from main branch"
  - label: "develop"
    description: "Base from develop branch"
multiSelect: false
```

If user needs a different branch, they can select "Other" and provide the branch name.

### Step 6: Construct Branch Name

```bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
TYPE="feat"           # From Step 4
DATE=$(date +%Y-%m-%d)
SLUG="sharpe-statistical-validation"  # From Step 1
BASE="main"           # From Step 5

BRANCH="${TYPE}/${DATE}-${SLUG}"
# Result: feat/2025-12-15-sharpe-statistical-validation
SKILL_SCRIPT_EOF
```

### Step 7: Create Worktree (Atomic)

```bash
/usr/bin/env bash << 'GIT_EOF_2'
cd ~/eon/alpha-forge

WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"

# Atomic branch + worktree creation
git worktree add -b "${BRANCH}" "${WORKTREE_PATH}" "origin/${BASE}"
GIT_EOF_2
```

### Step 8: Generate Tab Name and Report

```bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
# Generate acronym from slug
ACRONYM=$(echo "$SLUG" | tr '-' '\n' | cut -c1 | tr -d '\n')
TAB_NAME="AF-${ACRONYM}"
SKILL_SCRIPT_EOF_2
```

Report success:

```
✓ Worktree created successfully

  Path:    ~/eon/alpha-forge.worktree-2025-12-15-sharpe-statistical-validation
  Branch:  feat/2025-12-15-sharpe-statistical-validation
  Tab:     AF-ssv
  Env:     .envrc created (loads shared secrets)

  iTerm2: Restart iTerm2 to see the new tab
```

---

## Mode 2: Remote Branch Tracking

When user specifies `origin/branch-name`, create a local tracking branch.

**Detection**: User input contains `origin/` prefix.

**Example**: "create worktree from origin/feat/2025-12-10-existing-feature"

### Workflow

```bash
/usr/bin/env bash << 'GIT_EOF_3'
cd ~/eon/alpha-forge
git fetch --all --prune

REMOTE_BRANCH="origin/feat/2025-12-10-existing-feature"
LOCAL_BRANCH="feat/2025-12-10-existing-feature"

# Extract date and slug for worktree naming
# Pattern: type/YYYY-MM-DD-slug
if [[ "$LOCAL_BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
    DATE="${BASH_REMATCH[2]}"
    SLUG="${BASH_REMATCH[3]}"
else
    DATE=$(date +%Y-%m-%d)
    SLUG="${LOCAL_BRANCH##*/}"
fi

WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"

# Create tracking branch + worktree
git worktree add -b "${LOCAL_BRANCH}" "${WORKTREE_PATH}" "${REMOTE_BRANCH}"
GIT_EOF_3
```

---

## Mode 3: Existing Local Branch

When user specifies a local branch name (without `origin/`), use it directly.

**Detection**: User input is a valid branch name format (e.g., `feat/2025-12-15-slug`).

**Example**: "create worktree for feat/2025-12-15-my-feature"

### Workflow

```bash
/usr/bin/env bash << 'VALIDATE_EOF'
cd ~/eon/alpha-forge

BRANCH="feat/2025-12-15-my-feature"

# Verify branch exists
if ! git show-ref --verify "refs/heads/${BRANCH}" 2>/dev/null; then
    echo "ERROR: Local branch '${BRANCH}' not found"
    echo "Available local branches:"
    git branch | head -20
    exit 1
fi

# Extract date and slug
if [[ "$BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
    DATE="${BASH_REMATCH[2]}"
    SLUG="${BASH_REMATCH[3]}"
else
    DATE=$(date +%Y-%m-%d)
    SLUG="${BRANCH##*/}"
fi

WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"

# Create worktree for existing branch (no -b flag)
git worktree add "${WORKTREE_PATH}" "${BRANCH}"
VALIDATE_EOF
```

---

## Naming Conventions

### Worktree Folder Naming (ADR-Style)

**Format**: `alpha-forge.worktree-YYYY-MM-DD-slug`

**Location**: `~/eon/`

| Branch                                          | Worktree Folder                                                 |
| ----------------------------------------------- | --------------------------------------------------------------- |
| `feat/2025-12-14-sharpe-statistical-validation` | `alpha-forge.worktree-2025-12-14-sharpe-statistical-validation` |
| `feat/2025-12-13-feature-genesis-skills`