/iterate — Diverge, Compare, Converge

Spin up N parallel agents on isolated git worktrees, each exploring a different direction for the same problem. Review all variants, pick the best, merge it back.

When to Use

• User wants to explore multiple approaches to a problem
• Design/UI work where visual comparison matters
• Refactoring where there are multiple valid strategies
• Any task where "try a few things and pick the best" is the right move

Prerequisites

• Must be inside a git repository with a clean working tree (or stashable changes)
• The repo should have committed state to branch from

Usage

/iterate <task description>
/iterate 3 <task description>        # explicit count (default: 3)
/iterate 2 redesign the settings page using shadcn

How It Works

Phase 1: Parse Arguments

Parse $ARGUMENTS to extract:

• N (number of variants): First token if it's a number 1-5, otherwise default to 3
• Task: Everything after the count (or all of $ARGUMENTS if no count)

If no arguments provided, ask the user:

1. What task/problem should the agents explore?
2. How many variants? (default 3)

Phase 2: Generate Divergent Angles

Before spawning agents, generate N distinct approaches. These should be meaningfully different, not just cosmetic variations.

Example for "redesign the settings page":

1. Minimal — strip to essentials, single scrollable page, maximum whitespace
2. Tabbed — group settings into logical tabs with a sidebar nav
3. Search-first — spotlight-style search with categorized results

Example for "implement caching":

1. In-memory LRU cache with TTL
2. Redis-backed with cache invalidation events
3. Service worker + Cache API for edge caching

Present the angles to the user for approval before spawning. The user may adjust, add, or remove angles.

Phase 3: Spawn Agents

For each variant, spawn an agent using:

Agent tool with:
  - isolation: "worktree"
  - subagent_type: "general-purpose"
  - run_in_background: true (to run all N in parallel)

Each agent gets this prompt structure:

You are variant {i} of {N} exploring: {task}

YOUR ANGLE: {angle_description}

INSTRUCTIONS:
1. Implement the solution following the angle described above
2. Make it complete and functional — this will be compared against other approaches
3. If this is a web project with a dev server, start it on port {base_port + i}
   (use the project's dev command with --port flag)
4. When done, write a brief VARIANT_NOTES.md at the repo root with:
   - Approach taken
   - Key decisions and tradeoffs
   - What you'd improve with more time
5. Commit all changes with message: "iterate: variant {i} — {angle_name}"

Port assignment: Base port = 3100, so variants get 3101, 3102, 3103, etc.

Phase 4: Monitor & Report

Wait for all agents to complete. As each finishes, collect:

• Worktree path and branch name (from agent result)
• Whether a dev server is running and on which port
• Summary from VARIANT_NOTES.md if it exists

Present a comparison table:

┌─────────┬──────────────────────┬──────────┬─────────────────────────┐
│ Variant │ Angle                │ Port     │ Summary                 │
├─────────┼──────────────────────┼──────────┼─────────────────────────┤
│ 1       │ Minimal              │ :3101    │ Single page, 3 sections │
│ 2       │ Tabbed               │ :3102    │ 4 tabs, sidebar nav     │
│ 3       │ Search-first         │ :3103    │ Spotlight + categories  │
└─────────┴──────────────────────┴──────────┴─────────────────────────┘

Tell the user to review each variant (visit the ports, check the code).

Phase 5: Converge

Ask the user: "Which variant do you want to keep?"

Options:

• Pick a single winner (1, 2, or 3)
• Cherry-pick pieces from multiple variants
• None — discard all and try again with different angles

If single winner:

1. Merge the winning branch into the current branch
2. Remove VARIANT_NOTES.md from the merge
3. Clean up all worktrees (git worktree remove)
4. Kill any running dev servers on the variant ports

If cherry-pick:

1. Ask which parts from which variants
2. Apply changes manually from the relevant worktrees
3. Clean up all worktrees

If none:

1. Clean up all worktrees
2. Offer to re-run with new angles

Cleanup

Always clean up worktrees when done, even if the user abandons the process:

# List worktrees
git worktree list

# Remove each variant worktree
git worktree remove <path> --force

# Delete variant branches
git branch -D iterate-variant-1 iterate-variant-2 iterate-variant-3

# Kill dev servers on variant ports
lsof -ti:3101 -ti:3102 -ti:3103 | xargs kill 2>/dev/null

Important Notes

• Git safety: Never force-push or modify the user's current branch until they explicitly pick a winner
• Port conflicts: Check if ports are in use before assigning; shift base port if needed
• Large repos: Worktrees share the git object store, so disk usage is minimal
• Context isolation: Each agent starts fresh — no context pollution between variants
• Dev server detection: Look for package.json scripts (dev, start, serve) or common framework commands to determine if/how to start a preview server