/refactor

name: refactor
description: "Intelligent refactor command. Triggers: refactor, refactoring, cleanup, restructure, extract, simplify, modernize."

Claude Code Harness Tool Compatibility

This skill may include examples copied from the OpenCode or Codex harness. In Claude Code, do not call OpenCode/Codex-only tools such as `task(...)`, `call_omo_agent(...)`, `spawn_agent(...)`, `background_output(...)`, `wait_agent(...)`, `team_*(...)`, `send_message(...)`, `followup_task(...)`, or `close_agent(...)` literally. Translate those examples to Claude Code native tools:

| OpenCode / Codex example | Claude Code tool to use | | --- | --- | | `task(subagent_type="explore", ...)` / `call_omo_agent(...)` / `spawn_agent(agent_type="explorer", ...)` | the `Task` tool (spawn a subagent of the matching type) | | `task(subagent_type="plan"/"oracle", ...)` / `spawn_agent(agent_type="plan"/"reviewer", ...)` | the `Task` tool with the planner/reviewer subagent, or the `Skill` tool | | `task(category="...", ...)` | the `Task` tool (general-purpose subagent) or run the work inline | | `background_output(...)` / `wait_agent(...)` | await the subagent's return value / the system completion notification | | `team_*(...)` / `send_message`/`followup_task`/`close_agent` | run multiple `Task` subagents and synthesize their results |

When translating `load_skills=[...]`, invoke the requested skills with the `Skill` tool or pass their names in the spawned subagent's prompt. If a code block below conflicts with this section, this section wins.

export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command

Usage

\`\`\` /refactor <refactoring-target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]

Arguments: refactoring-target: What to refactor. Can be:

• File path: src/auth/handler.ts
• Symbol name: "AuthService class"
• Pattern: "all functions using deprecated API"
• Description: "extract validation logic into separate module"

Options: --scope: Refactoring scope (default: module)

• file: Single file only
• module: Module/directory scope
• project: Entire codebase

--strategy: Risk tolerance (default: safe)

• safe: Conservative, maximum test coverage required
• aggressive: Allow broader changes with adequate coverage

\`\`\`

What This Command Does

Performs intelligent, deterministic refactoring with full codebase awareness. Unlike blind search-and-replace, this command:

1. **Understands your intent** - Analyzes what you actually want to achieve 2. **Maps the codebase** - Builds a definitive codemap before touching anything 3. **Assesses risk** - Evaluates test coverage and determines verification strategy 4. **Plans meticulously** - Creates a detailed plan with Plan agent 5. **Executes precisely** - Step-by-step refactoring with LSP and AST-grep 6. **Verifies constantly** - Runs tests after each change to ensure zero regression

---

PHASE 0: INTENT GATE (MANDATORY FIRST STEP)

**BEFORE ANY ACTION, classify and validate the request.**

Step 0.1: Parse Request Type

| Signal | Classification | Action | |--------|----------------|--------| | Specific file/symbol | Explicit | Proceed to codebase analysis | | "Refactor X to Y" | Clear transformation | Proceed to codebase analysis | | "Improve", "Clean up" | Open-ended | **MUST ask**: "What specific improvement?" | | Ambiguous scope | Uncertain | **MUST ask**: "Which modules/files?" | | Missing context | Incomplete | **MUST ask**: "What's the desired outcome?" |

Step 0.2: Validate Understanding

Before proceeding, confirm:

• [ ] Target is clearly identified
• [ ] Desired outcome is understood
• [ ] Scope is defined (file/module/project)
• [ ] Success criteria can be articulated

**If ANY of above is unclear, ASK CLARIFYING QUESTION:**

\`\`\` I want to make sure I understand the refactoring goal correctly.

**What I understood**: [interpretation] **What I'm unsure about**: [specific ambiguity]

Options I see: 1. [Option A] - [implications] 2. [Option B] - [implications]

**My recommendation**: [suggestion with reasoning]

Should I proceed with [recommendation], or would you prefer differently? \`\`\`

Step 0.3: Create Initial Todos

**IMMEDIATELY after understanding the request, create todos:**

\`\`\` TodoWrite([ {"id": "phase-1", "content": "PHASE 1: Codebase Analysis - launch parallel explore agents", "status": "pending", "priority": "high"}, {"id": "phase-2", "content": "PHASE 2: Build Codemap - map dependencies and impact zones", "status": "pending", "priority": "high"}, {"id": "phase-3", "content": "PHASE 3: Test Assessment - analyze test coverage and verification strategy", "status": "pending", "priority": "high"}, {"id": "phase-4", "content": "PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan", "status": "pending", "priority": "high"}, {"id": "phase-5", "content": "PHASE 5: Execute Refactoring - step-by-step with continuous verification", "status": "pending", "priority": "high"}, {"id": "phase-6", "content": "PHASE 6: Final Verification - full test suite and regression check", "status": "pending", "priority": "high"} ]) \`\`\`

---

PHASE 1: CODEBASE ANALYSIS (PARALLEL EXPLORATION)

**Mark phase-1 as in_progress.**

1.1: Launch Parallel Explore Agents (BACKGROUND)

Fire ALL of these simultaneously using \`call_omo_agent\`:

\`\`\` // Agent 1: Find the refactoring target call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find all occurrences and definitions of [TARGET]. Report: file paths, line numbers, usage patterns." )

// Agent 2: Find related code call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find all code that imports, uses, or depends on [TARGET]. Report: dependency chains, import graphs." )

// Agent 3: Find similar patterns call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find similar code patterns to [TARGET] in the codebase.