feat: add /batch skill for parallel worktree fan-out

[iheitlager]

Description

The swarm infrastructure (swarm-job, launch-agents, worktrees) supports parallel agents, and /trio handles sequential issue processing with review gates. But there's no single-command entry point for the compound pattern: plan a batch of changes interactively, then fan out N parallel agents in isolated worktrees, each making changes, testing, and opening a PR independently.

Inspired by: Boris Cherny's Part 5 tip — /batch migrate src/ from Solid to React — interactive planning followed by parallel execution across dozens of agents.

Complexity

Estimate: large
Reasoning: New skill + integration with existing swarm infra (swarm-job, launch-agents, worktrees)

Context

The infrastructure exists but there's no orchestration layer that ties planning to parallel fan-out. Currently you either work sequentially (/trio) or manually set up parallel agents via launch-agents.

How It Would Work

1. /batch <description> — User describes the batch operation
2. Plan phase (interactive): Claude identifies affected files, groups them into independent work units
3. Fan-out phase: For each work unit, spawn an agent in a worktree via launch-agents, injecting the plan + specific file scope
4. Each agent independently: implements changes, runs tests, opens a PR
5. Report phase: Summarize results — which PRs succeeded, which need human attention

Existing Infrastructure to Leverage

• launch-agents — worktree creation and tmux session management
• swarm-job — job queue with atomic claiming
• swarm-daemon — monitoring and event tracking
• /pr — PR creation per agent
• Agent definitions (code-reviewer etc.) for post-change review

Acceptance Criteria

• /batch <description> enters interactive planning mode
• Plan shows work units and affected files per unit
• User approves before fan-out begins
• Each work unit runs in an isolated worktree
• Each agent tests and opens a PR independently
• Summary report shows success/failure per work unit
• Integrates with swarm-job for tracking

[m13v]

we built almost exactly this pattern and it works really well for parallelizing agent work. the core loop is: plan interactively, then for each work unit spin up a tmux session with a fresh git worktree, inject the task scope, and let each agent run independently.

the gotcha we hit was agent coordination when multiple worktrees touch shared config files or overlapping dependencies. you need a merge strategy before the agents start, not after. we handle it by having the planner identify file-level conflicts during the plan phase and either serializing conflicting units or designating one agent as the owner of shared files.

the report phase is important too. we poll tmux sessions for completion and aggregate results, but the tricky part is detecting when an agent is stuck vs still working. a simple timeout-based approach with progress file checks worked better than trying to parse agent output.

[m13v]

here is the parallel agent orchestration skill we run with tmux + worktrees: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md - includes the plan-then-fanout pattern, session monitoring, and completion detection. might be useful as reference for the /batch skill design.