batch

Overview

Parallel worktree execution engine. Takes a transformation (refactor, migration, code mod, style change) and a target scope (files, modules, services), decomposes into N independent units, executes each in its own git worktree via isolated agents, then merges results.

Why worktree isolation matters: Each agent gets its own copy of the repo. No file conflicts during execution. Merge conflicts only surface at the explicit merge step — where they can be resolved intelligently instead of causing mid-execution failures.

Step 1: Analyze Scope

Identify the transformation and target scope:

1. Parse the user's description to extract:
   • Transformation: What change to apply (e.g., "migrate from Jest to Vitest", "add error boundaries to all pages")
   • Target scope: Which files/modules to transform (e.g., src/modules/*/, **/*.test.ts)
2. Scan the target scope with Glob/Grep to enumerate candidate files
3. Verify each candidate is a valid transformation target

Step 2: Decompose

Split the scope into N independent units (max 10):

1. Group files by natural boundaries (module, directory, feature area)
2. Verify independence — units must NOT share files (a file belongs to exactly one unit)
3. For each unit, define:
   • Files: List of files in this unit
   • Prompt: Focused transformation instruction for this unit
   • Success criteria: How to verify the transformation worked (tests pass, type-checks, lint clean)

Present the decomposition table to the user:

Unit | Files        | Description
-----|-------------|------------------------------------------
1    | src/auth/*  | Migrate auth module tests from Jest to Vitest
2    | src/billing/*| Migrate billing module tests from Jest to Vitest
...

Ask for confirmation before proceeding. The user may adjust units, exclude files, or modify the transformation.

Step 3: Execute in Parallel

Spawn up to 10 agents in parallel, each with isolation: "worktree":

For each unit:
  Agent(
    isolation: "worktree",
    prompt: "Transform these files: [file list]. Apply: [transformation]. Success: [criteria]. Do NOT modify files outside your scope."
  )