refactor

## Codex Harness Tool Compatibility This skill may include examples copied from the OpenCode harness. In Codex, do not call OpenCode-only tools such as `call_omo_agent(...)`, `task(...)`, `background_output(...)`, or `team_*(...)` literally. Translate those examples to Codex native tools: | OpenCode example | Codex tool to use | | --- | --- | | `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` | | `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` | | `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` | | `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})` | | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` | | `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals | | `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` | Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, `lazycodex-code-reviewer`, `lazycodex-qa-executor`, and `lazycodex-gate-reviewer` - pass the matching name as `agent_type` so the child gets that role's model and instructions. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If a code block below conflicts with this section, this section wins. When translating `load_skills=[...]`, include the requested skill names in the spawned agent's `message`. If a code block below conflicts with this section, this section wins. For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. 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 Skill for Pattern Analysis: \`\`\`bash // Find structural patterns python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' --lang ts src/ # Preview refactoring first sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/ \`\`\` ### 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(