iterate

/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)