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 | By default, record a self-review in the notepad: re-read the diff, run diagnostics, and capture evidence for every acceptance criterion. Only when the user demanded strict, rigorous, or high-accuracy review, use `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"lazycodex-gate-reviewer","fork_context":false})`; include `fork_context: false`. | | `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","agent_type":"lazycodex-worker-medium","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` and `multi_agent_v1.wait_agent`; use `multi_agent_v1.send_input` and `multi_agent_v1.close_agent` only when exposed in the active tools list | 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. Inspect the actual spawn schema: whenever `agent_type` is exposed, EVERY spawn MUST select an exact LazyCodex role, on V1 or V2. Implementation difficulty selects `lazycodex-worker-low`, `lazycodex-worker-medium`, or `lazycodex-worker-high`; clone QA can select `lazycodex-clone-fidelity-reviewer`. Never select generic `worker` or `default`. If a code block below conflicts with this section, this section wins. Codex exposes ONE of two subagent tool surfaces per session; check your own tool list and route accordingly. If `multi_agent_v1.*` tools exist, use the table above as written. If instead a flat `spawn_agent` with a required `task_name` exists (`multi_agent_v2`), rewrite every `multi_agent_v1.*` example: `multi_agent_v1.spawn_agent({...,"fork_context":false})` becomes `spawn_agent({"task_name":"<lowercase_digits_underscores>","message":...,"agent_type":...,"fork_turns":"none"})` (`"all"` only when full parent history is truly required); `send_input` becomes `send_message`; do not call `close_agent`/`resume_agent` (finished agents end on their own; `followup_task` re-tasks one, `interrupt_agent` stops one); `wait_agent` takes only `timeout_ms` and returns on any child mailbox activity. Do not infer role support from V1/V2 or a model version. Legacy-schema exception: only if the actual schema lacks `agent_type`, omit that unsupported field and carry the complete role instructions in `message`, with history explicitly disabled. This cannot select a specialized TOML; an installed managed default supplies the medium worker for unnamed non-forks. The guard has no schema metadata and rejects unnamed calls, so report incompatible routing instead of retrying generically. Every deliberate full-history fork must still name its role: Codex skips role application on unnamed full-history forks, an upstream gap no LazyCodex default can repair. If a code block below conflicts with this section, this section wins. `fork_context` is rejected on `multi_agent_v2` (`fork_context is not supported in MultiAgentV2; use fork_turns instead`). 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. Omit optional keys you do not set. Never send `items: []`, `message: ""`, `model: ""`, `reasoning_effort: ""`, or `service_tier: ""` — Codex rejects them (`Items can't be empty`, `reasoning_effort must not be empty`). 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; back off between waits (double the timeout up to ~5 minutes) instead of spinning short cycles. 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 |