Create Worktree

Creates and bootstraps a git worktree for isolated development work.

Arguments

• •name (required): Name for the worktree directory and branch
• •--spec=<path>: Path to a spec file to copy into the worktree's specs directory
• •--base=<branch>: Base branch to create worktree from (default: current branch or configured default)
• •--no-bootstrap: Skip the onBootstrap hook

Configuration

Check for .claude/spec-workflow/config.yaml:

paths:
  worktrees: "./worktrees"      # Where worktrees are created
  specs: "./specs"              # Where specs live (for copying)

worktree:
  branchNaming: "{name}"        # Branch naming pattern
  defaultBase: null             # Default base branch (null = current)
  onBootstrap: null             # Hook script to run after creation

Branch Naming

The branchNaming pattern supports these tokens:

• •{name} - The worktree name
• •{date} - Current date (YYYY-MM-DD)

Examples:

• •"{name}" → my-feature
• •"feature/{name}" → feature/my-feature
• •"{date}-{name}" → 2024-01-15-my-feature

Bootstrap Hook

If worktree.onBootstrap is configured, it runs after worktree creation with these environment variables:

Example hook script:

#!/bin/bash
cd "$WORKTREE_PATH"
npm install
# ... any other setup

Steps

1. •

   Check if worktree exists

   • •Check if a worktree with the given name already exists at the configured path
   • •If it does, respond with "Worktree already exists at [path]" and exit
   • •If it does not exist, proceed
2. •

   Determine paths and branch name

   • •Worktree path: {config.paths.worktrees}/{name} (default: ./worktrees/{name})
   • •Branch name: Apply branchNaming pattern (default: {name})
   • •Base branch: --base argument, or worktree.defaultBase, or current branch
3. •

   Create the worktree

   bash

   git worktree add -b [branch-name] [worktree-path] [base-branch]
   

4. •

   Notify the user

   code

   Worktree created at [path] on branch [branch-name].
   

5. •

   Handle spec file (if --spec provided)

   • •Copy the spec file to the worktree's specs directory
   • •Update spec frontmatter with worktree and branch info
6. •

   Run bootstrap hook (unless --no-bootstrap)

   • •If worktree.onBootstrap is configured, run it with environment variables
   • •If not configured, skip this step
   • •Report success or failure
7. •

   Final confirmation

   code

   Worktree ready at [path].
   
   To work in this worktree:
   - Open a new terminal in [path]
   - Or use: cd [path]
   

Example Usage

# Basic worktree creation
/create-worktree feature-login

# Create worktree with a spec file
/create-worktree user-notifications --spec=specs/2024-01-15-notifications-spec.md

# Create worktree from a different base branch
/create-worktree hotfix-auth --base=release/v2.0

# Create worktree without running bootstrap
/create-worktree quick-fix --no-bootstrap

Notes

• •Worktrees are typically gitignored (add worktrees/ to .gitignore)
• •Each worktree has its own working directory but shares git history
• •Worktrees allow parallel work on different features without stashing
• •Use /worktree-cleanup (if available) to remove stale worktrees