Alpha-Forge Worktree Manager

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

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:

• Parse description from user input

• Convert to lowercase

• Apply word economy (remove filler words)

• 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.

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

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

alpha-forge.worktree-2025-12-13-feature-genesis-skills

fix/quick-patch

alpha-forge.worktree-{TODAY}-quick-patch

iTerm2 Tab Naming (Acronym-Based)

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

Worktree Slug Tab Name

sharpe-statistical-validation

AF-ssv

feature-genesis-skills

AF-fgs

eth-block-metrics-data-plugin

AF-ebmdp

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

Scenario Action

Branch already exists Suggest using Mode 3 (existing branch) or rename

Remote branch not found List available remote branches

Main worktree on feature Warn via AskUserQuestion, offer to switch

Empty description Show usage examples

Network error on fetch Allow offline mode with local branches only

Worktree path exists Suggest cleanup or different slug

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:

• Script checks if ~/eon/.env.alpha-forge exists

• Creates .envrc in the new worktree with dotenv directive

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

• Globs ~/eon/alpha-forge.worktree-*

• Validates each against git worktree list

• Generates AF-{acronym} tab names

• Inserts tabs after main AF tab

References

• Naming Conventions

• ADR: Alpha-Forge Git Worktree Management

• Design Spec

Troubleshooting

Issue Cause Solution

Branch already exists Local branch with same name Use Mode 3 (existing branch) or rename slug

Remote branch not found Typo or not pushed yet Run git fetch --all --prune and list branches

Worktree path exists Previous worktree not cleaned Remove old worktree or use different slug

direnv not loading Shell hook not configured Add eval "$(direnv hook zsh)" to ~/.zshrc

Shared secrets not found ~/eon/.env.alpha-forge missing Create shared secrets file with required vars

iTerm2 tab not appearing Dynamic layout not refreshed Restart iTerm2 to trigger layout regeneration

Main worktree not on main Previous work not switched Run git checkout main in main worktree first

Stale worktree detected Branch merged but not cleaned Run git worktree remove <path> to cleanup