Safe Refactoring

Requires: Claude Code Agent Teams feature.

Architect-planned, reviewer-validated code restructuring with per-step compilation checks.

Arguments: $ARGUMENTS

Instructions

1. •

   Get the recipe: Call mcp__mira__recipe (or mcp__plugin_mira_mira__recipe) tool:

   code

   recipe(action="get", name="refactor")
   

2. •

   Parse arguments (optional):

   • •Any text -> use as the refactoring goal/context for the architect
3. •

   Determine context: What code to refactor, the goal of the restructuring, and any constraints. If no context is obvious, ask the user what they'd like refactored.

Phase 1: Analysis

1. •

   Create the team:

   code

   TeamCreate(team_name="refactor-{timestamp}")
   

2. •

   Spawn architect using Task tool:

   code

   Task(
     subagent_type="general-purpose",
     name="architect",
     team_name="refactor-{timestamp}",
     prompt=architect_prompt + "\n\n## Refactoring Goal\n\n" + user_context,
     run_in_background=true
   )
   

   IMPORTANT: Do NOT use mode="bypassPermissions" — the architect is read-only.

3. •

   Create and assign the analysis task using TaskCreate + TaskUpdate.

4. •

   Wait for the architect to report via SendMessage.

Phase 2: Validation

1. •

   Spawn code-reviewer using Task tool (same params, run_in_background=true, no bypassPermissions).

2. •

   Send the architect's plan to code-reviewer via SendMessage so they have the specific plan to validate.

3. •

   Create and assign the validation task.

4. •

   Wait for code-reviewer to report via SendMessage. Then shut down both analyst agents.

Phase 3: Synthesis

1. •

   Combine architect's plan with code-reviewer's feedback:

   • •If code-reviewer found missing callers or risks, incorporate them
   • •If rated "needs revision" or "too risky", revise accordingly
2. •

   Present the validated refactoring plan to the user and WAIT for approval.

Phase 4: Implementation

1. •

   Execute the refactoring steps yourself. For each step:

   • •Make the changes
   • •Run cargo test --no-run to verify compilation (NEVER use --release)
   • •If it doesn't compile, fix before moving to the next step
2. •

   For large refactors (5+ files), spawn implementation agents with mode="bypassPermissions":

   • •Group steps by file ownership to avoid conflicts
   • •Max 3 steps per agent
   • •Each agent verifies with cargo test --no-run

Phase 5: Verification

1. •Run cargo test to verify all tests pass (NEVER use --release).
2. •For large refactors, optionally spawn test-runner for parallel clippy + fmt + dead code checks.
3. •If tests fail: fix regressions or update test imports/paths.

Phase 6: Finalize

1. •Report summary of structural changes to the user.
2. •Cleanup: TeamDelete

Examples

/mira:refactor
-> Prompts for what to refactor, then runs the full analysis -> validation -> implementation cycle

/mira:refactor Split the database module into separate files per concern
-> Architect analyzes the DB module, plans the split, code-reviewer validates, then implements

/mira:refactor Rename the "watcher" module to "file_monitor" across the codebase
-> Safe rename with caller analysis and per-step compilation checks

Agent Roles