worktree-manager

Alpha-Forge Worktree Manager

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 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:

Step 2: Verify Main Worktree Status

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

/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:

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":

cd ~/eon/alpha-forge
git checkout main

Step 3: Fetch Remote and Display Branches

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:

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:

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

/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)

/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

/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

/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

/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/

iTerm2 Tab Naming (Acronym-Based)

Format: AF-{acronym} where acronym = first character of each word in slug

Stale Worktree Detection

Check for worktrees whose branches are already merged to main:

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

# Get branches merged to main
MERGED=$(git branch --merged main | grep -v '^\*' | grep -v 'main' | tr -d ' ')

# Check each worktree
git worktree list --porcelain | grep '^branch' | cut -d' ' -f2 | while read branch; do
    branch_name="${branch##refs/heads/}"
    if echo "$MERGED" | grep -q "^${branch_name}$"; then
        path=$(git worktree list | grep "\[${branch_name}\]" | awk '{print $1}')
        echo "STALE: $branch_name at $path"
    fi
done
PREFLIGHT_EOF

If stale worktrees found, prompt user to cleanup using AskUserQuestion.

Cleanup Workflow

Remove Stale Worktree

# Remove worktree (keeps branch)
git worktree remove ~/eon/alpha-forge.worktree-{DATE}-{SLUG}

# Optionally delete merged branch
git branch -d {BRANCH}

Prune Orphaned Entries

git worktree prune

Error Handling

Branch Not Found

✗ Branch 'feat/nonexistent' not found

  Available branches:
  - feat/2025-12-14-sharpe-statistical-validation
  - main

  To create from remote:
  Specify: "create worktree from origin/branch-name"

Worktree Already Exists

✗ Worktree already exists for this branch

  Existing path: ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation

  To use existing worktree:
  cd ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation

Integration

direnv Environment Setup

Worktrees automatically get a .envrc file that loads shared credentials from ~/eon/.env.alpha-forge.

What happens on worktree creation:

1. Script checks if ~/eon/.env.alpha-forge exists
2. Creates .envrc in the new worktree with dotenv directive
3. Runs direnv allow to approve the new .envrc

Shared secrets file (~/eon/.env.alpha-forge):

# ClickHouse credentials, API keys, etc.
CLICKHOUSE_HOST_READONLY="..."
CLICKHOUSE_USER_READONLY="..."
CLICKHOUSE_PASSWORD_READONLY="..."

Generated .envrc (in each worktree):

# alpha-forge worktree direnv config
# Auto-generated by create-worktree.sh

# Load shared alpha-forge secrets
dotenv $HOME/eon/.env.alpha-forge

# Worktree-specific overrides can be added below

Prerequisites:

• direnv installed via mise (mise use -g direnv@latest)
• Shell hook configured (eval "$(direnv hook zsh)" in ~/.zshrc)
• Shared secrets file at ~/eon/.env.alpha-forge

iTerm2 Dynamic Detection

The default-layout.py script auto-discovers worktrees:

1. Globs ~/eon/alpha-forge.worktree-*
2. Validates each against git worktree list
3. Generates AF-{acronym} tab names
4. Inserts tabs after main AF tab

References

• Naming Conventions
• ADR: Alpha-Forge Git Worktree Management
• Design Spec

Troubleshooting

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path before editing.
1. What failed? — Fix the instruction that caused it.
2. What worked better than expected? — Promote to recommended practice.
3. What drifted? — Fix any script, reference, or dependency that no longer matches reality.
4. Log it. — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.