Refactor

Refactoring Workflow

Before starting work, create a marker: mkdir -p ~/.claude/tmp && echo "refactor" > ~/.claude/tmp/heavy-skill-active && date -u +"%Y-%m-%dT%H:%M:%SZ" >> ~/.claude/tmp/heavy-skill-active

You are in Maestro orchestration mode. Delegate immediately.

Workflow

1. Explore - Spawn explore agent to analyze current code
2. Plan - Spawn planner agent to design refactoring approach
3. Implement - Spawn implementer agent to refactor
4. Test - Spawn tester agent to verify behavior unchanged
5. Review - Spawn reviewer agent to check quality
6. Learn - Store patterns discovered during refactoring

Agent Delegation

Spawn explore and planner first — they accept thin prompts because they discover what they need from the codebase:

Agent(explore, "Analyze the code to refactor: $ARGUMENTS. Identify patterns, issues, dependencies.")
Agent(planner, "Design refactoring approach based on analysis. Keep behavior unchanged.")

Then assemble the implementer prompt from the actual planner output. Implementer runs in an isolated worktree with no access to prior agent results, so paste the real plan — not "according to plan":

• The user's refactor target ($ARGUMENTS) verbatim
• The planner's step-by-step plan, including file paths and each move/rename/extract operation
• Any "preserve behavior" invariants the planner called out
• The test command that must remain green
• Scope: "only the files in the plan; do not touch anything else"

Now spawn:

Agent(implementer, "")
Agent(tester, "Verify refactored code behaves identically to original.")
Agent(reviewer, "Review refactoring for quality and completeness.")

Refactors are a top source of subtle regressions — behavior that "shouldn't change" quietly does. When the Codex bridge is available, run a cross-model review in parallel with the reviewer:

Agent(codex-verifier, "Cross-model review of the refactor diff. Confirm behavior is preserved; report findings by severity.")

The bridge is gated and fails open: if Codex is unavailable, the reviewer agent alone is fine.

Output

Return a summary:

• What changed: Brief description
• Files modified: List of files
• Tests passing: Verification status
• Improvements: What's better now
• Learnings: Patterns worth remembering

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: darkroomengineering
• Source: darkroomengineering/cc-settings
• License: MIT

Install and usage instructions live in the source repository linked above.