worktree-setup

Worktree Setup Skill

Create a git worktree for isolated feature development with proper branch setup.

When to Use This Skill

Use this skill when:

• Starting work on a new feature that needs isolation
• You have a design doc or clear understanding of what to build
• The project has been initialized with /init

Prerequisites

Before using this skill:

1. Threadwork must be initialized (.threadwork.yaml exists)
2. You should have a feature name/slug ready
3. The base branch should be up to date

Skill Workflow

Step 1: Read Configuration

Read .threadwork.yaml to get:

• base_branch - The branch to create from (default: dev)
• branch_prefix - Prefix for branch names (default: feature/)
• worktree_base_path - Where to create worktrees (default: .claude-worktrees)

cat .threadwork.yaml

Step 2: Determine Feature Branch Name

Ask the user for a feature slug if not already provided. The branch name will be:

{branch_prefix}{feature-slug}

Examples:

• feature/jwt-auth
• feature/user-dashboard
• feature/api-rate-limiting

Naming conventions:

• Use lowercase
• Use hyphens for spaces
• Keep it short but descriptive
• Match the epic/feature being implemented

Step 3: Verify Base Branch is Up to Date

# Fetch latest from remote
git fetch origin

# Check if base branch exists locally
git rev-parse --verify {base_branch} 2>/dev/null

# If not, create tracking branch
git checkout -b {base_branch} origin/{base_branch}

# Check for uncommitted changes
git status --porcelain

If there are uncommitted changes, warn the user and ask how to proceed:

• Stash changes
• Commit changes
• Abort

Step 4: Create the Feature Branch

# Create branch from base
git checkout {base_branch}
git pull origin {base_branch}
git checkout -b {branch_prefix}{feature-slug}

Step 5: Create the Worktree

Determine the worktree path:

{home}/{worktree_base_path}/{repo-name}/{feature-slug}

Example: ~/.claude-worktrees/my-express-app/jwt-auth