fork-worktree

name	fork-worktree
description	Use when user wants to create new autonomy branch with dedicated worktree for parallel agent workflows
user-invocable	true

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 fork-iteration instead)
• Creating non-autonomy branches (use git directly)
• Starting iterations (use start-iteration instead)

Quick Reference

Step	Action	Tool
1. Parse arguments	Extract iteration (optional) and strategy-name	Manual
2. Detect repository root	Find git root from anywhere (main repo or worktree)	Bash
3. Validate	Check strategy-name, branch, and worktree path availability	Bash
4. Resolve fork point	Find iteration tag or use HEAD	Bash
5. Create worktree	Create branch + worktree at root level	Bash
6. Report success	Confirm creation with navigation instructions	Direct output

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 fork-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

Mistake	Reality
"Create worktree in current directory"	NO. Always create at repo root .worktrees/autonomy/ regardless of where invoked.
"I'll use relative path .worktrees/..."	YES, but must cd to repo_root first. Path is relative to repo root.
"Branch exists, I'll create worktree for it"	NO. This skill creates NEW branches. Existing branch = error.
"I'll also start the iteration"	NO. Worktree creation is separate. User navigates and runs /start-iteration.
"I'll checkout the branch in current directory"	NO. Branch checked out in worktree, current directory unchanged.
"Nested worktrees are fine"	NO. All worktrees must be at root level .worktrees/autonomy/.
"I'll use git rev-parse --show-toplevel"	NO. That gives worktree root, not repo root. Use --git-common-dir.

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