Skip to main content
skill CX Codex

batch-orchestration — Claude Code skill: what it does, how to install

batch-orchestration decomposes large codebase changes into independent units and runs parallel agents in isolated git worktrees.

MIT ★ 2,966 updated 2026-09-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What batch-orchestration does

The skill introduces the /batch <instruction> pattern for mechanical edits touching 10 or more files. It scans the repository for matching code patterns, breaks the work into 5 to 30 independent units, and builds an execution plan. Background agents never start without explicit user confirmation.

Once approved, each unit gets a dedicated git worktree. An isolated agent applies the transformation, runs relevant test suites, and opens a pull request without sharing context with other runs. When finished, the orchestrator outputs a summary table with PR links and error details for any failed units.

The pattern requires zero shared state between tasks. Handling fewer than 5 units adds unnecessary overhead, while database schema changes and architectural redesigns break when forced into parallel worktrees.

What it helps with

  • split large library migrations into independent parallel tasks
  • refactor repeated component patterns across dozens of files
  • apply tracing or logging patterns across all API endpoints
  • generate pull requests with passing tests for self-contained modules

Example prompts for the agent

  • /batch Convert all React class components to function components
  • /batch Migrate from moment.js to dayjs across the codebase
  • /batch Add OpenTelemetry tracing to all API handlers

How to install batch-orchestration

1Plugin marketplace

/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

This installs the whole pro-workflow plugin with all its skills

2Skills CLI (Vercel)

npx skills add rohitg00/pro-workflow --skill batch-orchestration -a claude-code

3Manually: put the files in place

~/.claude/skills/batch-orchestration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/batch-orchestration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about batch-orchestration

How to install batch-orchestration in Claude Code?

Run /plugin marketplace add rohitg00/pro-workflow and then /plugin install pro-workflow@pro-workflow. You can also install it directly via npx skills add rohitg00/pro-workflow --skill batch-orchestration -a claude-code.

What does batch-orchestration do?

It finds files matching an edit instruction, splits them into isolated units, and runs parallel agents in git worktrees to implement changes, run tests, and open PRs.

When should batch-orchestration be avoided?

Avoid it for sequential database schema updates, interdependent code changes, and any refactor where multiple agents must touch the same state or configuration files.

Source text

SKILL.md · MIT
---
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

```text
/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

```bash
/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:

```bash
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:**
```text
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:**
```text
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:

```text
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.

```text
[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

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
wiki-viewer wiki-viewer writes a pro-workflow wiki out as a single HTML file with pages, sources, claims, a seed queue, a link graph and search. Useful for handing research state to someone else. CX Codex +1 ★ 2,966repo stars llm-council llm-council runs multi-model deliberation in three stages: parallel drafts, anonymous peer rankings, and final synthesis by a designated chairman. CX Codex +1 ★ 2,966repo stars design-engineering The design-engineering skill guides interface animation choices and UI reviews. Use it when refining a component, transition, modal, or other interactive state. CX Codex +1 ★ 2,966repo stars permission-tuner The permission-tuner skill reads permission prompts and auto mode denials from your session logs, then suggests permission rules and autoMode entries to reduce interruptions. CX Codex +1 ★ 2,966repo stars insights insights turns your pro-workflow history into numbers: edits per session, rules you actually apply, mistakes that keep coming back. Useful when you want to see where the agent keeps slipping. CX Codex +1 ★ 2,966repo stars doctor doctor scans your pro-workflow and Claude Code setup: checks hooks, database, context usage, MCP servers, and git state. Spots broken hook scripts and settings conflicts before they cause problems. CX Codex +1 ★ 2,966repo stars thoroughness-scoring thoroughness-scoring rates implementation choices from 1 to 10 and prompts the agent to pick thorough solutions with tests and typing over brittle shortcuts. CX Codex +1 ★ 2,966repo stars skill-optimizer The skill-optimizer skill proposes edits to a SKILL.md based on stored corrections, then checks candidates against held-out examples before accepting changes. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open