You are an expert at orchestrating parallel mechanical renames across large codebases using swarms of lightweight agents. This skill documents a proven pattern for completing bulk renames in a single batch rather than sequential file-by-file edits.

When to Use

• Renaming an identifier, parameter, key, or variable across 5+ files

• The renames are mechanical — same find-and-replace logic in each file, no reasoning required

• Files are independent — editing file A doesn't affect what needs to change in file B

• Examples: renaming issue_number to plan_number , renaming old_func to new_func , updating a key name across config consumers

When NOT to Use

• Cross-file cascading refactors where renaming a shared type changes method signatures, requiring each file to adapt differently

• Renames requiring judgment — e.g., "rename this concept" where each call site needs context-aware naming

• Fewer than 5 files — sequential edits are simpler and have less overhead

• Complex AST transforms — use libcst-refactor agent instead

The Pattern

Step 1: Identify All Files

Use Grep to find every file containing the target identifier:

Grep(pattern="old_name", output_mode="files_with_matches")

Partition files into two groups:

• Source files (src/ or library code)

• Test files (tests/ )

Step 2: Launch Source File Agents in Parallel

Launch one Task agent per file (or per small group of 2-3 closely related files):

Task( subagent_type='general-purpose', model='haiku', description='Rename old_name in path/to/file.py', prompt="""...""" # See agent prompt template below )

Launch ALL source file agents in a single message so they run concurrently.

Step 3: Wait for Source Agents to Complete

Collect results from all source file agents. Review for errors.

Step 4: Launch Test File Agents in Parallel

Same pattern as Step 2, but for test files. This second wave runs after source files because tests import from source — if source renames fail, test renames would be wrong.

Step 5: Verify

After all agents complete:

• Grep check: Confirm old name no longer appears (except intentional exceptions)

• Run CI: Use devrun agent to run tests, type checking, and linting

Agent Prompt Template

Each agent receives a focused, self-contained prompt:

In the file {file_path}:

Rename all occurrences of {old_name} to {new_name}.

This includes:

• Variable names and assignments
• Function/method parameter names
• Dictionary keys (both definition and access)
• String literals that reference the identifier programmatically
• Type annotations
• Comments that reference the identifier by name

DO NOT rename:

• {boundary_constraints}

Read the file first, then apply all renames using the Edit tool.

Boundary Constraints

Boundary constraints are critical for partial renames. Always specify what should NOT be renamed. Examples:

• "Do not rename occurrences inside string literals that are user-facing messages"

• "Do not rename the GitHub API field 'issue_number' — only rename internal references"

• "Do not rename imports from external packages"

If there are no exceptions, state: "No exceptions — rename ALL occurrences."

Batching Strategy

Wave Files Rationale

1 Source files (src/ ) Core renames, no dependencies on other waves

2 Test files (tests/ ) Tests import from source; must run after source renames land

Within each wave, all agents run in parallel. Between waves, wait for completion.

For very large renames (30+ files), consider sub-batching into groups of ~10-15 agents per message to avoid overwhelming the system.

Key Design Decisions

• Model: haiku — mechanical edits need speed, not deep reasoning. Haiku is 10x cheaper and sufficient for find-and-replace tasks.

• One agent per file — keeps prompts focused, avoids cross-file edit conflicts, makes failures isolated and retriable.

• Two waves (source then test) — tests depend on source; parallel within each wave, sequential between waves.

• Explicit boundary constraints — every agent prompt MUST specify what not to rename. Omitting this causes over-eager renames (e.g., renaming API field names that must stay as-is).

Example: Renaming issue_number to pr_number

• Grep found 16 source files and 12 test files containing issue_number

• Wave 1: Launched 16 haiku agents for source files — completed in ~25 seconds

• Wave 2: Launched 12 haiku agents for test files — completed in ~20 seconds

• Verification: Grep(pattern="issue_number") confirmed only intentional GitHub API references remained

• CI: All tests passed, type checker clean

Total wall time: ~60 seconds for 28 files, vs ~10+ minutes for sequential edits.