- 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