Terminal.skills
Skills/orchestrate-batch-refactor
>

orchestrate-batch-refactor

Plan and execute large refactor efforts with parallel multi-agent analysis. Use when: refactoring many files, splitting workstreams, or coordinating sub-agents for batch code changes.

#refactoring#multi-agent#batch#code-quality
terminal-skillsv1.0.0
Works with:claude-codeopenai-codexgemini-clicursor
Source

Usage

$
✓ Installed orchestrate-batch-refactor v1.0.0

Getting Started

  1. Install the skill using the command above
  2. Open your AI coding agent (Claude Code, Codex, Gemini CLI, or Cursor)
  3. Reference the skill in your prompt
  4. The AI will use the skill's capabilities automatically

Example Prompts

  • "Review the open pull requests and summarize what needs attention"
  • "Generate a changelog from the last 20 commits on the main branch"

Information

Version
1.0.0
Author
terminal-skills
Category
Development
License
MIT

Documentation

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

  1. Define scope and success criteria.
    • List target paths/modules and non-goals.
    • State behavior constraints (for example: preserve external behavior).
  2. 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.
  3. 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.
  4. 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.
  5. Integrate and verify.
    • Review packet outputs, resolve overlaps, and run validation gates.
    • Run targeted tests per packet, then broader suite for integrated scope.
  6. 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:

  1. Packet ID and objective.
  2. Owned files.
  3. Dependencies (none or packet IDs).
  4. Risks and invariants to preserve.
  5. Required checks.
  6. 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:

  1. Packet-level checks (fast and scoped).
  2. Cross-packet integration checks.
  3. Full project safety checks when scope is broad.

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