orchestrate-batch-refactor

SKILL.md

Orchestrate Batch Refactor

Overview

Use this skill to run high-throughput refactors safely.
Analyze scope in parallel, synthesize a single plan, then execute independent work packets with sub-agents.

Inputs

Repo path and target scope (paths, modules, or feature area)

Goal type: refactor, rewrite, or hybrid

Constraints: behavior parity, API stability, deadlines, test requirements

When to Use Parallelization

Use this skill for medium/large scope touching many files or subsystems.

Skip multi-agent execution for tiny edits or highly coupled single-file work.

Core Workflow

Define scope and success criteria.

List target paths/modules and non-goals.

State behavior constraints (for example: preserve external behavior).

Run parallel analysis first.

Split target scope into analysis lanes.

Spawn explorer sub-agents in parallel to analyze each lane.

Ask each agent for: intent map, coupling risks, candidate work packets, required validations.

Build one dependency-aware plan.

Merge explorer output into a single work graph.

Create work packets with clear file ownership and validation commands.

Sequence packets by dependency level; run only independent packets in parallel.

Execute with worker agents.

Spawn one worker per independent packet.

Assign explicit ownership (files/responsibility).

Instruct every worker that they are not alone in the codebase and must ignore unrelated edits.

Integrate and verify.

Review packet outputs, resolve overlaps, and run validation gates.

Run targeted tests per packet, then broader suite for integrated scope.

Report and close.

Summarize packet outcomes, key refactors, conflicts resolved, and residual risks.

Work Packet Rules

One owner per file per execution wave.

No parallel edits on overlapping file sets.

Keep packet goals narrow and measurable.

Include explicit done criteria and required checks.

Prefer behavior-preserving refactors unless user explicitly requests behavior change.

Planning Contract

Every packet must include:

Packet ID and objective.

Owned files.

Dependencies (none or packet IDs).

Risks and invariants to preserve.

Required checks.

Integration notes for main thread.

Use references/work-packet-template.md for the exact shape.

Agent Prompting Contract

Use the prompt templates in references/agent-prompt-templates.md.

Explorer prompts focus on analysis and decomposition.

Worker prompts focus on implementation and validation with strict ownership boundaries.

Safety Guardrails

Do not start worker execution before plan synthesis is complete.

Do not parallelize across unresolved dependencies.

Do not claim completion if any required packet check fails.

Stop and re-plan when packet boundaries cause repeated merge conflicts.

Validation Strategy

Run in this order:

Packet-level checks (fast and scoped).

Cross-packet integration checks.

Full project safety checks when scope is broad.

Prefer fast feedback loops, but never skip required behavior checks.