fork-iteration

name	fork-iteration
description	Use when user wants to create new autonomy branch from current commit or specific past iteration
user-invocable	true

Forking Iteration

Overview

Create new autonomy branch forked from current commit or any iteration tag in git history. Enables "slime mold strategy" of parallel exploration.

Core principle: Branch creation is independent of iteration management. Fork creates branch, start-iteration begins work.

When to Use

Use this skill when:

• User runs /fork-iteration command
• User wants to create new exploration branch
• User wants to try alternative approach from past iteration
• User wants to bootstrap autonomy workflow from non-autonomy branch

DO NOT use for:

• 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. Validate strategy-name	Check kebab-case, not already exists	Bash
3. Resolve fork point	Find iteration tag or use HEAD	Bash
4. Create branch	Checkout fork point, create autonomy branch	Bash
5. Report success	Confirm creation with next steps	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-iteration [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: Check if Branch Already Exists

Validate that autonomy/<strategy-name> doesn't already exist:

# Check for existing branch (local or remote)
if git branch -a | grep -q "autonomy/$strategy_name\$"; then
  # Error: branch exists
fi

If exists:

Error: Branch 'autonomy/<strategy-name>' already exists.

To work on existing branch:
  git checkout autonomy/<strategy-name>

To create with different name:
  /fork-iteration [iteration] <different-name>

Available autonomy branches:
[List from git branch -a | grep autonomy/]

Stop here if branch exists.

Step 3: Resolve Fork Point

Determine what commit to fork from:

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" | wc -l)

if [ "$tag_count" -eq 0 ]; then
  # Error: iteration not found
  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
  # Use the tag
  fork_point="$matching_tags"
else
  # Multiple matches (shouldn't happen with branch-namespaced tags, but handle it)
  echo "Multiple iteration tags found for iteration $iteration:"
  echo "$matching_tags"
  echo ""
  # Use AskUserQuestion to let user choose
  exit 1
fi

If iteration NOT specified:

# Fork from current HEAD
fork_point=$(git rev-parse HEAD)
fork_description="current commit (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 4: Create New Branch

Checkout fork point and create new autonomy branch:

# Checkout fork point (detached HEAD)
git checkout "$fork_point"

# Create and switch to new branch
git checkout -b "autonomy/$strategy_name"

# Confirm creation
current_branch=$(git branch --show-current)
if [ "$current_branch" != "autonomy/$strategy_name" ]; then
  echo "Error: Failed to create branch 'autonomy/$strategy_name'"
  exit 1
fi

On success:

• Branch created and checked out
• Working directory contains files from fork point
• Ready for /start-iteration

Step 5: Report Success

Announce successful branch creation:

✓ Branch `autonomy/<strategy-name>` created

Forked from: [tag or commit hash]
Current branch: autonomy/<strategy-name>

Next step: Run `/start-iteration` to begin work on this branch.

Important Notes

Branch Creation Only

This skill ONLY creates branches:

• Does NOT start iterations
• Does NOT modify journal files
• Does NOT determine iteration numbering
• start-iteration will handle iteration logic when user runs it

Works from Any Starting Point

Can fork from:

• Autonomy branches (e.g., autonomy/experiment-a)
• Non-autonomy branches (e.g., main, develop)
• Detached HEAD
• Any commit with autonomy iteration tags

No Merge Provisions

Autonomy branches NEVER merge:

• Each branch is independent exploration
• Branches learn from each other via /analyze-branch (read-only)
• No git merge operations
• No rebase operations
• Branches are peers, not hierarchical

Strategy Name Matters

Branch name becomes identity:

• Used in tag names: autonomy/<strategy-name>/iteration-NNNN
• Appears in branch listings
• Should describe exploration direction
• Can't easily change later (would require tag renaming)

Good names:

• usage-based-pricing
• cdn-optimization
• react-migration

Bad names:

• test (too generic)
• new (not descriptive)
• experiment1 (meaningless)

Iteration Numbering Continuity

When start-iteration runs on new branch:

• If forked from iteration tag: continues numbering (fork from 0015 → next is 0016)
• If forked from non-iteration commit: starts at 0001 (if goal exists)
• If no goal exists: user must run /create-goal first

Common Mistakes

Mistake	Reality
"I'll also start the iteration in this skill"	NO. Branch creation is separate. User runs /start-iteration when ready.
"User wants to fork, I'll check out the branch for them"	Already doing this. Checkout happens during creation.
"Branch name has spaces, I'll keep them"	NO. Normalize to kebab-case.
"I'll search all branches for iteration tag"	NO. Only search tags reachable from current HEAD (git tag --merged HEAD).
"Branch exists, I'll overwrite it"	NO. Error and show user how to work with existing branch.
"No goal found, I'll create one"	NO. User must run /create-goal explicitly.

After Forking

Once branch is created:

• User is on new autonomy/<strategy-name> branch
• Working directory contains files from fork point
• No iterations started yet
• User runs /start-iteration to begin work
• Iteration numbering determined by start-iteration skill