worktree-manager_skill

Overview

This skill creates and manages git worktrees for the alpha-forge repository with automatic branch naming, consistent folder/tab conventions, and lifecycle tools for cleanup. It derives kebab-case slugs from natural language, constructs dated branch names, and performs atomic worktree creation with direnv and iTerm2 integration. The skill supports new-branch creation, remote tracking, and attaching existing local branches.

How this skill works

Given a natural-language description or explicit branch reference, the skill derives a compact slug (3–5 meaningful words), prompts for branch type and base, verifies the main worktree state, fetches remotes, and builds a branch name like type/YYYY-MM-DD-slug. It then creates an atomic git worktree at ~/eon/alpha-forge.worktree-YYYY-MM-DD-slug, generates an AF-{acronym} tab name, writes a .envrc that points to shared secrets, and reports the created path and branch. Alternative modes handle origin/branch (remote track) and existing local branches.

When to use it

• Start a new feature, fix, refactor, or chore for alpha-forge from a short description
• Create a worktree that tracks an existing remote branch (origin/...)
• Open a worktree for an already-created local branch
• Manage multiple parallel feature branches without touching main worktree state
• Detect and clean stale worktrees after branches are merged

Best practices

• Keep the main worktree on main before creating worktrees; the skill will warn and offer to switch
• Follow the word-economy rule in descriptions: remove filler words and limit to 3–5 meaningful words
• Choose appropriate branch type (feat/fix/refactor/chore) and base branch (main or develop) when prompted
• Use the generated worktree path and tab naming to quickly identify active worktrees in iTerm2
• Run git fetch --all --prune regularly and prune worktrees after branch deletion

Example use cases

• "create worktree for sharpe statistical validation" -> creates feat/YYYY-MM-DD-sharpe-statistical-validation with AF-ssv tab
• "create worktree from origin/feat/2025-12-10-existing-feature" -> creates local tracking branch and worktree
• "create worktree for feat/2025-12-15-my-feature" -> attaches an existing local branch to a new worktree
• Detect stale worktrees whose branches are merged to main and prompt to remove them
• Generate .envrc in each worktree that loads shared secrets from ~/eon/.env.alpha-forge