Menu
Intelligent refactor command. Triggers: refactor, refactoring, cleanup, restructure, extract, simplify, modernize.
MUST USE for planning before coding: 5+ steps, ambiguous scope, multiple modules, architecture decisions, a vague 'just make it good / figure out what to build' brief, or any request to plan, interview, or break work down. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode, just make it good, figure out what to build.
(builtin) Initialize hierarchical AGENTS.md knowledge base
MUST USE for planning before coding: 5+ steps, ambiguous scope, multiple modules, architecture decisions, a vague 'just make it good / figure out what to build' brief, or any request to plan, interview, or break work down. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode, just make it good, figure out what to build.
(builtin) Initialize hierarchical AGENTS.md knowledge base
MUST USE for planning before coding: 5+ steps, ambiguous scope, multiple modules, architecture decisions, a vague 'just make it good / figure out what to build' brief, or any request to plan, interview, or break work down. Explore-first planning consultant (Prometheus) that grounds in the codebase, asks only the forks exploration cannot resolve - or researches them to best practice when the intent is fuzzy - waits for explicit approval, then writes ONE decision-complete work plan a worker executes with zero further interview. Triggers: ulw-plan, plan this, make a plan, plan before coding, interview me, break this down, start planning, plan mode, just make it good, figure out what to build.
Thorough, file-cited technical debt audit across 9 dimensions using AST-grep (tree-sitter), grep, language-native tooling, and optionally CodeGraph knowledge graph. Produces TECH_DEBT_AUDIT.md with severity, effort estimates, and prioritized fixes. Use when asked for codebase health check, tech debt audit, architecture review, code quality assessment, or cleanup planning. Triggers: 'tech debt', 'technical debt', 'debt audit', 'code health', 'technical debt audit', 'codebase health check', 'find tech debt', 'debt analysis', 'audit code quality'.
| name | refactor |
| description | Intelligent refactor command. Triggers: refactor, refactoring, cleanup, restructure, extract, simplify, modernize. |
export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command
``` /refactor [--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 ```
Performs intelligent, deterministic refactoring with full codebase awareness. Unlike blind search-and-replace, this command:
BEFORE ANY ACTION, classify and validate the request.
| 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?" |
Before proceeding, confirm:
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:
My recommendation: [suggestion with reasoning]
Should I proceed with [recommendation], or would you prefer differently? ```
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"} ]) ```
Mark phase-1 as in_progress.
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." ) ```
While background agents are running, use direct tools:
```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 ```
```bash // Find structural patterns python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' --lang ts src/
sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/ ```
``` grep(pattern="[search_term]", path="src/", include="*.ts") ```
``` background_output(task_id="[agent_1_id]") background_output(task_id="[agent_2_id]") ... ```
Mark phase-1 as completed after all results collected.
Mark phase-2 as in_progress.
Based on Phase 1 results, build:
```
``` [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) ```
| 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 |
Based on codemap:
Mark phase-2 as completed.
Mark phase-3 as in_progress.
```bash
cat package.json | jq '.scripts | keys[] | select(test("test"))'
ls -la pytest.ini pyproject.toml setup.cfg
ls -la *_test.go ```
``` // 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]:
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:
Which approach do you prefer? ```
```
After each refactoring step:
Mark phase-3 as completed.
Mark phase-4 as in_progress.
``` Task( subagent_type="plan", prompt="Create a detailed refactoring plan:
[User's original request]
[Insert codemap here]
[Insert verification plan here]
After receiving plan from Plan agent:
Convert Plan agent output into granular todos:
``` TodoWrite([ // Each step from the plan becomes a todo {"id": "refactor-1", "content": "Step 1: [description]", "status": "pending", "priority": "high"}, {"id": "verify-1", "content": "Verify Step 1: run tests", "status": "pending", "priority": "high"}, {"id": "refactor-2", "content": "Step 2: [description]", "status": "pending", "priority": "medium"}, {"id": "verify-2", "content": "Verify Step 2: run tests", "status": "pending", "priority": "medium"}, // ... continue for all steps ]) ```
Mark phase-4 as completed.
Mark phase-5 as in_progress.
For EACH refactoring step:
Use appropriate tool:
For Symbol Renames: ```typescript lsp_prepare_rename(filePath, line, character) // Validate rename is possible lsp_rename(filePath, line, character, newName) // Execute rename ```
For Pattern Transformations: ```bash // Preview first sg --pattern '[pattern]' --rewrite '[rewrite]' --lang ts path/to/file.ts
// If preview looks good, execute python3 scripts/ast_grep_helper.py replace '[pattern]' '[rewrite]' --lang ts path/to/file.ts --apply ```
For Structural Changes: ```typescript // Use Edit tool for precise changes edit(filePath, oldString, newString) ```
```typescript // 1. Check diagnostics lsp_diagnostics(filePath) // Must be clean or same as baseline
// 2. Run tests bash("bun test") // Or appropriate test command
// 3. Type check bash("tsc --noEmit") // Or appropriate type check ```
If ANY verification fails:
NEVER proceed to next step with broken tests.
After each logical group of changes:
```bash git add [changed-files] git commit -m "refactor(scope): description
[details of what was changed and why]" ```
Mark phase-5 as completed when all refactoring steps done.
Mark phase-6 as in_progress.
```bash
bun test # or npm test, pytest, go test, etc. ```
```bash
tsc --noEmit # or equivalent ```
```bash
eslint . # or equivalent ```
```bash
bun run build # or npm run build, etc. ```
```typescript // Check all changed files for (file of changedFiles) { lsp_diagnostics(file) // Must all be clean } ```
```markdown
All existing tests pass. No new errors introduced. ```
Mark phase-6 as completed.
sg --pattern ... --rewrite ... --lang ...)If any of these occur, STOP and consult user:
You already know these tools. Use them intelligently:
Leverage LSP tools for precision analysis. Key patterns:
Use `ast-grep` skill helper or `sg` CLI for structural transformations. Critical: Always preview first, review, then execute.
When you encounter deprecated methods/APIs during refactoring:
Remember: Refactoring without tests is reckless. Refactoring without understanding is destructive. This command ensures you do neither.
$ARGUMENTS `Team mode is enabled for this session. The rules below override Phase 4-6 above. Follow this protocol instead of the in-session step-by-step execution.
When invoking the Plan agent in Phase 4.1, append this additional requirement to the prompt:
``` 7. (REQUIRED when team mode is active) Output a Team Staffing Recommendation section with these fields — missing fields fail Phase 5.0:
Classification rules the plan agent must apply to each step:
Read the Team Staffing Recommendation from Phase 4. If any required field is missing, fail here and re-request the plan with the exact missing field names. Do not proceed with a partial plan.
Then choose the path:
Record the chosen path in the TodoWrite list.
Precondition checks (fail hard if any step fails):
Team spec (`~/.omo/teams/refactor-squad/config.json`):
```json { "name": "refactor-squad", "lead": { "kind": "subagent_type", "subagent_type": "sisyphus" }, "members": [ { "kind": "category", "category": "quick", "prompt": "You handle mechanical refactoring steps (LSP rename, extract variable, inline, simple move, signature change). Use LSP tools for correctness. Apply the task description's per-step instructions verbatim — no scope expansion. After edits, run lsp_diagnostics on touched files. Report via team_send_message(teamRunId=, to="lead", summary=, body=<lsp status + diff summary>) + team_task_update(status=completed). Never run tests — the external verifier handles that. Never git add, never --continue." }, { "kind": "category", "category": "quick", "prompt": "Same contract as peer quick worker." }, { "kind": "category", "category": "unspecified-low", "prompt": "You handle logic-preserving refactors that need reasoning (extract function, restructure conditional, pattern transformation, cross-file API change). Read the task description's plan step carefully. Use the ast-grep skill helper or sg CLI to preview structural rewrites first, review the preview, then execute. If the step is ambiguous or would require out-of-scope changes, STOP and send team_send_message(teamRunId=, to="lead", summary="UNCLEAR", body=) + team_task_update(status=pending). Same reporting contract as peer quick workers. Never run tests." }, { "kind": "category", "category": "unspecified-low", "prompt": "Same contract as peer unspecified-low worker." } ] } ```
Rationale for this composition:
Team lifecycle (one team, reused until Phase 6 cleanup):
Lead monitoring loop:
While any team task is `pending | claimed | in_progress`:
Proceed to Phase 6 only when every team task is `completed` AND every paired verifier task returned PASS.
If Phase 5 used the team path, dismantle `refactor-squad` BEFORE producing the 6.6 summary. Every exit path — success, escalation, abort — must cleanup; orphan teams poison the next session's precondition check.
The `~/.omo/teams/refactor-squad/config.json` declaration stays on disk; next session reuses it.
Append to the 6.6 summary a "Dispatch path" line and, when team path was used, team metrics (teamRunId, tasks created, verifier runs, team lifetime).