refactor

## 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. Report: analogous implementations, established conventions." ) // Agent 4: Find tests call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find all test files related to [TARGET]. Report: test file paths, test case names, coverage indicators." ) // Agent 5: Architecture context call_omo_agent( subagent_type="explore", run_in_background=true, prompt="Find architectural patterns and module organization around [TARGET]. Report: module boundaries, layer structure, design patterns in use." ) \`\`\` ## 1.2: Direct Tool Exploration (WHILE AGENTS RUN) While background agents are running, use direct tools: ### LSP Tools for Precise Analysis: \`\`\`typescript // Find definition(s) LspGotoDefinition(filePath, line, character) // Where is it defined? // Find ALL usages across workspace LspFindReferences(filePath, line, character, includeDeclaration=true) // Get file structure LspDocumentSymbols(filePath) // Hierarchical outline LspWorkspaceSymbols(filePath, query="[target_symbol]") // Search by name // Get current diagnostics lsp_diagnostics(filePath) // Errors, warnings before we start \`\`\` ### AST-Grep for Pattern Analysis: \`\`\`typescript // Find structural patterns ast_grep_search( pattern="function $NAME($$$) { $$$ }", // or relevant pattern lang="typescript", // or relevant language paths=["src/"] ) // Preview refactoring (DRY RUN) ast_grep_replace( pattern="[old_pattern]", rewrite="[new_pattern]", lang="[language]", dryRun=true // ALWAYS preview first ) \`\`\` ### Grep for Text Patterns: \`\`\` grep(pattern="[search_term]", path="src/", include="*.ts") \`\`\` ## 1.3: Collect Background Results \`\`\` background_output(task_id="[agent_1_id]") background_output(task_id="[agent_2_id]") ... \`\`\` **Mark phase-1 as completed after all results collected.** --- # PHASE 2: BUILD CODEMAP (DEPENDENCY MAPPING) **Mark phase-2 as in_progress.** ## 2.1: Construct Definitive Codemap Based on Phase 1 results, build: \`\`\` ## CODEMAP: [TARGET] ### Core Files (Direct Impact) - \`path/to/file.ts:L10-L50\` - Primary definition - \`path/to/file2.ts:L25\` - Key usage ### Dependency Graph \`\`\` [TARGET] ├── imports from: │ ├── module-a (types) │ └── module-b (utils) ├── imported by: │ ├── consumer-1.ts │ ├── consumer-2.ts │ └── consumer-3.ts └── used by: ├── handler.ts (direct call) └── service.ts (dependency injection) \`\`\` ### Impact Zones | Zone | Risk Level | Files Affected | Test Coverage | |------|------------|----------------|---------------| | Core | HIGH | 3 files | 85% covered | | Consumers | MEDIUM | 8 files | 70% covered | | Edge | LOW | 2 files | 50% covered | ### Established Patterns - Pattern A: [description] - used in N places - Pattern B: [description] - established convention \`\`\` ## 2.2: Identify Refactoring Constraints Based on codemap: - **MUST follow**: [existing patterns identified] - **MUST NOT break**: [critical dependencies] - **Safe to change**: [isolated code zones] - **Requires migration**: [breaking changes impact] **Mark phase-2 as completed.** --- # PHASE 3: TEST ASSESSMENT (VERIFICATION STRATEGY) **Mark phase-3 as in_progress.** ## 3.1: Detect Test Infrastructure \`\`\`bash # Check for test commands cat package.json | jq '.scripts | keys[] | select(test("test"))' # Or for Python ls -la pytest.ini pyproject.toml setup.cfg # Or for Go ls -la *_test.go \`\`\` ## 3.2: Analyze Test Coverage \`\`\` // Find all tests related to target call_omo_agent( subagent_type="explore", run_in_background=false, // Need this synchronously prompt="Analyze test coverage for [TARGET]: 1. Which test files cover this code? 2. What test cases exist? 3. Are there integration tests? 4. What edge cases are tested? 5. Estimated coverage percentage?" ) \`\`\` ## 3.3: Determine Verification Strategy Based on test analysis: | Coverage Level | Strategy | |----------------|----------| | HIGH (>80%) | Run existing tests after each step | | MEDIUM (50-80%) | Run tests + add safety assertions | | LOW (<50%) | **PAUSE**: Propose adding tests first | | NONE | **BLOCK**: Refuse aggressive refactoring | **If coverage is LOW or NONE, ask user:** \`\`\` Test coverage for [TARGET] is [LEVEL]. **Risk Assessment**: Refactoring without adequate tests is dangerous. Options: 1. Add tests first, then refactor (RECOMMENDED) 2. Proceed with extra caution, manual verification required 3. Abort refactoring Which approach do you prefer? \`\`\` ## 3.4: Document Verification Plan \`\`\` ## VERIFICATION PLAN