/batch-orchestration

name: batch-orchestration
description: Decompose large-scale changes into independent units and spawn parallel agents in isolated worktrees. Use for migrations, refactors, codemods, and any change touching 10+ files with the same pattern.
user-invocable: true

Batch Orchestration

The `/batch` command pattern for large-scale parallel changes.

How It Works

/batch <instruction>
  │
  ├── 1. Research: scan repo, understand scope
  ├── 2. Decompose: split into 5-30 independent units
  ├── 3. Present plan: show units, ask for approval
  ├── 4. Execute: one background agent per unit in isolated worktree
  └── 5. Collect: each agent runs tests and opens a PR

Syntax

/batch Convert all React class components to function components
/batch Add error boundaries to every page component
/batch Migrate from moment.js to dayjs across the codebase
/batch Add OpenTelemetry tracing to all API handlers

The instruction should describe the change pattern, not individual files. The batch system finds the files.

Phase 1: Research

The orchestrator scans the repo to find every instance that matches the instruction:

grep -r "class.*extends.*Component" --include="*.tsx" -l

It builds a complete list of targets and groups them by independence.

Phase 2: Decompose

Each unit must be:

• **Independent** — no shared state with other units
• **Self-contained** — can be implemented and tested alone
• **Verifiable** — has a clear pass/fail criteria

**Good units:**

Unit 1: Convert src/components/Header.tsx (class → function)
Unit 2: Convert src/components/Footer.tsx (class → function)
Unit 3: Convert src/components/Sidebar.tsx (class → function)

**Bad units:**

Unit 1: Convert all components in src/components/ (too broad)
Unit 2: Fix issues from Unit 1 (dependent)

Target 5-30 units. Fewer than 5 doesn't justify the overhead. More than 30 and coordination costs grow.

Phase 3: Plan Approval

The orchestrator presents:

BATCH: Convert class components to function components

Found: 18 class components across src/

Units (18):
  1. src/components/Header.tsx — class Header → function
  2. src/components/Footer.tsx — class Footer → function
  ...
  18. src/pages/Settings.tsx — class Settings → function

Per unit: convert class to function, update hooks, run component tests
Estimated: ~2 min per unit, ~5 min total (parallel)

Proceed? (y/n)

**Wait for approval.** Never spawn agents without explicit confirmation.

Phase 4: Execute

After approval, for each unit:

1. Create isolated git worktree 2. Spawn background agent in that worktree 3. Agent implements the change 4. Agent runs relevant tests 5. Agent opens a PR

Agents run in parallel. Each has its own context window and worktree — no conflicts.

[Agent 1] ── worktree-1 ── Header.tsx ── tests pass ── PR #41
[Agent 2] ── worktree-2 ── Footer.tsx ── tests pass ── PR #42
[Agent 3] ── worktree-3 ── Sidebar.tsx ── tests fail ── flagged

Phase 5: Collect

After all agents complete:

• Summary of pass/fail per unit
• Links to opened PRs
• Any units that failed with error details
• Failed units can be retried individually

Best For

| Use Case | Why Batch Works | |----------|-----------------| | API migrations | Same pattern across many endpoints | | Dependency upgrades | Find/replace + fix across codebase | | Codemod-style refactors | Mechanical transformation, file by file | | Adding instrumentation | Same tracing/logging pattern everywhere | | Test coverage gaps | Add tests to untested modules independently | | Lint rule adoption | Apply new rule fixes across all files |

Anti-Patterns

| Don't Batch | Why | |-------------|-----| | Interdependent changes | Units can't run in parallel if they depend on each other | | Shared state modifications | Multiple agents writing to the same config or state file | | Architecture changes | Need holistic reasoning, not file-by-file | | Schema migrations | Database changes must be sequential | | Changes requiring human judgment per file | Defeats the purpose of automation |

Relationship to Other Patterns

| Pattern | Scale | Isolation | |---------|-------|-----------| | Direct edit | 1-3 files | None needed | | Subagent | 1 focused task | Forked context | | Worktree | 1 feature branch | Full repo copy | | Agent teams | 3-5 parallel tasks | Shared task list | | **Batch** | 5-30 identical pattern | Full worktree per unit |

Batch is the heaviest tool. Use it when the change is mechanical, repetitive, and the units are truly independent.

Guardrails

• Always review the decomposition before approving
• Each agent must run tests before opening a PR
• Failed units get flagged, not silently skipped
• Clean up worktrees after all agents complete
• Review PRs in batches — don't merge blindly