Skill

Safe Refactoring

Install

npx claudepluginhub joshuarweaver/cascade-code-general-misc-3 --plugin conarylabs-mira

Tool Access

This skill uses the workspace's default tool permissions.

Preview

SKILL.md

Similar Skills

cache-components

Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.

cache-components

139.2k

mcp-builder

9 files

Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).

anthropics-skills-13

124.2k

canvas-design

20 files

Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.

anthropics-skills-13

124.2k

Stats

Parent Repo Stars6

Parent Repo Forks1

Last CommitMar 1, 2026

Actions

View Source View Plugin View on GitHub View README

name: refactor description: This skill should be used when the user asks to "refactor this", "restructure code", "reorganize modules", "rename and move", "safe restructuring", "reorganize code", "move and rename", or wants to reorganize code without changing behavior. argument-hint: "[refactoring goal]" disable-model-invocation: true

Safe Refactoring

Requires: Claude Code Agent Teams feature.

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

Arguments: $ARGUMENTS

Instructions

Parse arguments (optional):
- Any text -> use as the refactoring goal/context for the architect
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

Launch for analysis: Call the Mira launch MCP tool to get the architect agent spec:
```
launch(team="refactor-team", scope=user_context, members="atlas")
```

Create the team:

TeamCreate(team_name=result.data.suggested_team_id)

Create and assign the analysis task:

TaskCreate(subject=atlas_agent.task_subject, description=atlas_agent.task_description)
TaskUpdate(taskId=id, owner="atlas", status="in_progress")

Spawn Atlas (architect) using Task tool:

Task(
  subagent_type="general-purpose",
  name="atlas",
  model=atlas_agent.model,
  team_name=result.data.suggested_team_id,
  prompt=atlas_agent.prompt + "\n\n## Refactoring Goal\n\n" + user_context,
  run_in_background=true
)

IMPORTANT: Do NOT use mode="bypassPermissions" -- Atlas is read-only. IMPORTANT: Always pass model="sonnet" to the Task tool. This ensures read-only agents use a cost-efficient model.

Wait for Atlas to report via SendMessage.

Phase 2: Validation

Launch for validation: Call launch to get the reviewer agent spec:

launch(team="refactor-team", scope=user_context, members="iris")

Spawn Iris (safety reviewer) using Task tool:

Task(
  subagent_type="general-purpose",
  name="iris",
  model=iris_agent.model,
  team_name=result.data.suggested_team_id,
  prompt=iris_agent.prompt + "\n\n## Refactoring Plan\n\n" + atlas_plan,
  run_in_background=true
)

IMPORTANT: Do NOT use mode="bypassPermissions" -- Iris is read-only. IMPORTANT: Always pass model="sonnet" to the Task tool. This ensures read-only agents use a cost-efficient model.

Send Atlas's plan to Iris via SendMessage so she has the specific plan to validate.
Create and assign the validation task.
Wait for Iris to report via SendMessage. Then shut down both analyst agents.

Phase 3: Synthesis

Combine Atlas's plan with Iris's feedback:
- If Iris found missing callers or risks, incorporate them
- If rated "needs revision" or "too risky", revise accordingly
Present the validated refactoring plan to the user and WAIT for approval.

Phase 4: Implementation

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
For large refactors (5+ files), launch implementation agents:
```
launch(team="refactor-team", scope=implementation_plan, members="ash")
```
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

Launch for verification: Call launch to get the verifier agent spec:

launch(team="refactor-team", scope=summary_of_changes, members="ash")

Spawn Ash (build verifier) using Task tool:

Task(
  subagent_type="general-purpose",
  name="ash",
  model=ash_agent.model,
  team_name=result.data.suggested_team_id,
  prompt=ash_agent.prompt + "\n\n## Changes Made\n\n" + summary_of_changes,
  run_in_background=true,
  mode="bypassPermissions"
)

Wait for Ash to report. If tests fail: fix regressions or update test imports/paths.

Phase 6: Finalize

Report summary of structural changes to the user.
Cleanup: Send shutdown_request to remaining agents, then 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
-> Atlas analyzes the DB module, plans the split, Iris 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

Phase	Agent	Focus
Analysis	Atlas (architect)	Map current structure, design target, plan migration steps
Validation	Iris (safety reviewer)	Verify completeness, check for hidden behavior changes
Verification	Ash (build verifier)	Run tests, compilation, linters between steps