Orchestrate Safe Batch Code Refactoring

Orchestrate Batch Refactor runs high-throughput refactors safely across many files: analyze scope in parallel with explorer sub-agents, synthesize their findings into a single dependency-aware plan, then execute independent work packets with worker sub-agents.

Use this for a refactor spanning many files or subsystems that needs clear work partitioning and dependency-aware planning before parallel implementation. Skip multi-agent execution for tiny edits or highly coupled single-file work, where the coordination overhead isn't worth it.

Inputs: the repo path and target scope (paths, modules, or feature area), the goal type (refactor, rewrite, or hybrid), and constraints such as behavior parity, API stability, deadlines, and test requirements. The six-step workflow: define scope and success criteria, including non-goals and behavior constraints like preserving external behavior; run parallel analysis by splitting the scope into lanes and spawning one explorer sub-agent per lane to produce an intent map, coupling risks, candidate work packets, and required validations; merge that explorer output into a single dependency-aware work graph, creating work packets with clear file ownership and validation commands, sequenced by dependency level so only independent packets run in parallel; spawn one worker sub-agent per independent packet with explicit file ownership, instructed that other agents are working in the same codebase and unrelated edits must be ignored; integrate outputs by resolving overlaps and running validation gates, first targeted tests per packet then a broader suite for the integrated scope; and finally report packet outcomes, key refactors, conflicts resolved, and residual risks.

Every work packet follows a fixed planning contract: packet ID and objective, owned files, dependencies (none or specific packet IDs), risks and invariants to preserve, required checks, and integration notes for the main thread, using references/work-packet-template.md for the exact shape. Explorer and worker prompts follow templates in references/agent-prompt-templates.md - explorer prompts focus on analysis and decomposition, worker prompts on implementation and validation within strict ownership boundaries. Validation runs in a fixed order: packet-level checks first (fast and scoped), then cross-packet integration checks, then full project safety checks when scope is broad.

Teams or agents running large, multi-file refactors who need one owner per file per execution wave, no parallel edits on overlapping file sets, and explicit safety guardrails: never start worker execution before plan synthesis is complete, never parallelize across unresolved dependencies, never claim completion if a required packet check fails, and stop to re-plan if packet boundaries keep causing merge conflicts.