name: forking-worktree description: Use when user wants to create new autonomy branch with dedicated worktree for parallel agent workflows

Forking Worktree

Overview

Create new autonomy branch with dedicated worktree for running parallel Claude agents on different branches simultaneously. All worktrees created at repository root level (.worktrees/autonomy/), regardless of where command is invoked.

Core principle: Worktrees represent branches, not iterations. Multiple iterations happen within same worktree. Worktrees enable parallel exploration with isolated working directories.

When to Use

Use this skill when:

• User runs /fork-worktree command
• User wants to run multiple agents in parallel on different autonomy branches
• User wants isolated working directory for new exploration branch
• User wants to create autonomy branch without disturbing current working directory

DO NOT use for:

• Creating branches without worktrees (use forking-iteration instead)
• Creating non-autonomy branches (use git directly)
• Starting iterations (use starting-an-iteration instead)

Quick Reference

Process

Step 1: Parse and Validate Arguments

Extract arguments from command args:

Format: [iteration] <strategy-name>

Parse:

If args contains only one word:
  iteration = None
  strategy_name = args
Else if args contains two words:
  iteration = first word
  strategy_name = second word
Else:
  Error: "Invalid arguments. Usage: /fork-worktree [iteration] <strategy-name>"

Validate strategy-name:

• Must be kebab-case (lowercase, hyphens, no special chars)
• Must not be empty
• Should be descriptive (warn if too generic like "test" or "new")

Normalize strategy-name:

# Convert to lowercase, replace invalid chars with hyphens
strategy_name=$(echo "$strategy_name" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]-' '-' | sed 's/^-*//; s/-*$//')

Step 2: Detect Repository Root

Find the git repository root, regardless of whether we're in main repo or inside a worktree:

# Get common git directory (works from anywhere, including worktrees)
git_common_dir=$(git rev-parse --git-common-dir)

# Repository root is parent of .git directory
# For main repo: .git is directory -> parent is repo root
# For worktree: .git is file pointing to .git/worktrees/X -> common-dir points back to main .git
if [ -d "$git_common_dir" ]; then
  repo_root=$(cd "$git_common_dir/.." && pwd)
else
  echo "Error: Unable to determine repository root"
  exit 1
fi

Why this matters:

• Ensures all worktrees created at .worktrees/autonomy/ relative to repo root
• Prevents nested worktrees (.worktrees/autonomy/experiment-a/.worktrees/...)
• Works whether invoked from main repo or from within another worktree

Step 3: Validate Branch and Worktree Availability

Check that we can create the new branch and worktree:

Check branch doesn't exist:

if git branch -a | grep -q "autonomy/$strategy_name\$"; then
  echo "Error: Branch 'autonomy/$strategy_name' already exists."
  echo ""
  echo "To work on existing branch:"
  echo "  git checkout autonomy/$strategy_name"
  echo ""
  echo "To create worktree for existing branch:"
  echo "  cd $repo_root"
  echo "  git worktree add .worktrees/autonomy/$strategy_name autonomy/$strategy_name"
  echo ""
  echo "Available autonomy branches:"
  git branch -a | grep autonomy/
  exit 1
fi

Check worktree path doesn't exist:

worktree_path="$repo_root/.worktrees/autonomy/$strategy_name"

if [ -e "$worktree_path" ]; then
  echo "Error: Worktree directory already exists: $worktree_path"
  echo ""
  echo "Remove it first:"
  echo "  /remove-worktree $strategy_name"
  echo "Or:"
  echo "  git worktree remove .worktrees/autonomy/$strategy_name"
  exit 1
fi

Create parent directory if needed:

mkdir -p "$repo_root/.worktrees/autonomy"

Step 4: Resolve Fork Point

Determine what commit to fork from (same logic as forking-iteration):

If iteration specified:

# Search for iteration tag in current branch history
matching_tags=$(git tag --merged HEAD | grep "iteration-$(printf '%04d' $iteration)\$")

tag_count=$(echo "$matching_tags" | grep -c '^' || echo "0")

if [ "$tag_count" -eq 0 ]; then
  echo "Error: Iteration $iteration not found in current branch history."
  echo ""
  echo "Most recent iterations in current branch:"
  git tag --merged HEAD | grep 'iteration-' | tail -5
  exit 1
elif [ "$tag_count" -eq 1 ]; then
  fork_point="$matching_tags"
  fork_description="iteration $iteration (tag: $matching_tags)"
else
  # Multiple matches (shouldn't happen with branch-namespaced tags)
  echo "Multiple iteration tags found for iteration $iteration:"
  echo "$matching_tags"
  echo ""
  echo "Please specify which tag to fork from."
  exit 1
fi

If iteration NOT specified:

# Fork from current HEAD
fork_point=$(git rev-parse HEAD)
fork_description="current commit ($(git rev-parse --short HEAD))"

Validate fork point exists:

if ! git rev-parse "$fork_point" >/dev/null 2>&1; then
  echo "Error: Fork point '$fork_point' not found in git history."
  exit 1
fi

Step 5: Create Worktree

Create the branch and worktree in a single git command:

# Navigate to repository root (important for relative path resolution)
cd "$repo_root"

# Create branch + worktree together
# -b creates new branch
# path is relative to repo root: .worktrees/autonomy/<strategy-name>
# fork_point is where to create the branch from
git worktree add -b "autonomy/$strategy_name" \
  ".worktrees/autonomy/$strategy_name" \
  "$fork_point"

# Verify worktree created successfully
if [ ! -d "$worktree_path" ]; then
  echo "Error: Failed to create worktree at $worktree_path"
  exit 1
fi

# Verify branch exists
if ! git branch -a | grep -q "autonomy/$strategy_name\$"; then
  echo "Error: Failed to create branch 'autonomy/$strategy_name'"
  exit 1
fi

What this does:

• Creates new branch autonomy/<strategy-name> at fork point
• Creates worktree directory at .worktrees/autonomy/<strategy-name>/
• Checks out the new branch in the worktree (not in current directory)
• Current directory remains unchanged

Step 6: Report Success

Announce successful worktree creation with navigation instructions:

✓ Worktree created successfully

Branch: autonomy/<strategy-name>
Worktree: .worktrees/autonomy/<strategy-name>/
Forked from: [fork_description]

Next steps:
1. Navigate to worktree:
   cd .worktrees/autonomy/<strategy-name>

2. Start iteration:
   /start-iteration

The worktree is an isolated working directory where you can work on this branch independently of other branches.

Calculate relative path for convenience:

# If we're already in a worktree, provide sibling navigation
current_dir=$(pwd)
if [[ "$current_dir" == *"/.worktrees/autonomy/"* ]]; then
  # In a worktree, provide relative navigation to sibling
  echo "From your current location:"
  echo "  cd ../$strategy_name"
fi

Important Notes

Repository Root Detection

Works from anywhere:

• Main repository working directory
• Inside any worktree (including deeply nested work)
• Detached HEAD state
• Any subdirectory

All worktrees created at same level:

repo-root/
├── .git/
├── .worktrees/
│   └── autonomy/
│       ├── experiment-a/    # Created from main repo
│       ├── experiment-b/    # Created from experiment-a worktree
│       └── experiment-c/    # Created from experiment-b worktree

Branch and Worktree Lifecycle

Branch persists after worktree removal:

• Removing worktree (via /remove-worktree) deletes directory
• Branch autonomy/<strategy-name> and all commits persist
• Can create new worktree for same branch later
• All iteration tags remain in git history

One branch per worktree:

• Git enforces: branch can only be checked out in one worktree at a time
• Attempting to create worktree for already-checked-out branch fails
• This is a feature, not a bug (prevents conflicting changes)

Worktrees Are Optional

Existing workflows unchanged:

• /fork-iteration still creates branches without worktrees
• All autonomy skills work in both main repo and worktrees
• Worktrees are enhancement for parallel agent workflows
• Use worktrees when beneficial, ignore when not needed

Isolation and Independence

Each worktree is independent:

• Separate working directory with own file state
• Can have uncommitted changes independent of other worktrees
• Can be at different commits (though shares branch history)
• Perfect for running multiple Claude agents in parallel

Shared git metadata:

• All commits immediately visible across all worktrees
• Tags created in one worktree visible in all worktrees
• Branch operations (create, delete) affect all worktrees
• .git directory is shared

Common Mistakes

After Creating Worktree

Once worktree is created:

• New directory exists at .worktrees/autonomy/<strategy-name>/
• Branch autonomy/<strategy-name> checked out in that directory
• Current working directory unchanged (still in main repo or original worktree)
• User must navigate to worktree: cd .worktrees/autonomy/<strategy-name>
• User runs /start-iteration to begin work
• All autonomy skills work normally in worktree

Integration with Parallel Agents

Typical workflow:

# Terminal 1: First agent
/fork-worktree experiment-a
cd .worktrees/autonomy/experiment-a
/start-iteration
# Agent 1 works here

# Terminal 2: Second agent (can run while agent 1 is working)
/fork-worktree experiment-b
cd .worktrees/autonomy/experiment-b
/start-iteration
# Agent 2 works here independently

# Terminal 3: Analysis (from anywhere)
/list-branches
/compare-branches experiment-a experiment-b

Each agent has:

• Isolated working directory
• Independent iteration journals
• Separate uncommitted changes
• Shared git history and tags