Download packages/shared-skills/skills/refactor/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does refactor live?
The publisher keeps it at https://github.com/code-yeongyu/oh-my-openagent.
Which agents can use refactor?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.
Guides a refactor, cleanup, or restructure with the right decomposition. Use when the user asks to refactor, simplify, extract, or modernize code.
name: refactor
description: "Guides a refactor, cleanup, or restructure with the right decomposition. Use when the user asks to refactor, simplify, extract, or modernize code."
argument-hint: " [--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:
Understands your intent - Analyzes what you actually want to achieve
Maps the codebase - Builds a definitive codemap before touching anything
Assesses risk - Evaluates test coverage and determines verification strategy
Plans meticulously - Creates a detailed plan with Plan agent
Executes precisely - Step-by-step refactoring with LSP and AST-grep
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:
[Option A] - [implications]
[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
```
```
// 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]:
Which test files cover this code?
What test cases exist?
Are there integration tests?
What edge cases are tested?
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:
Add tests first, then refactor (RECOMMENDED)
Proceed with extra caution, manual verification required
Abort refactoring
Which approach do you prefer?
```
3.4: Document Verification Plan
```
VERIFICATION PLAN
Test Commands
Unit: `bun test` / `npm test` / `pytest` / etc.
Integration: [command if exists]
Type check: `tsc --noEmit` / `pyright` / etc.
Verification Checkpoints
After each refactoring step:
lsp_diagnostics → zero new errors
Run test command → all pass
Type check → clean
Regression Indicators
[Specific test that must pass]
[Behavior that must be preserved]
[API contract that must not change]
```
Mark phase-3 as completed.
PHASE 4: PLAN GENERATION (PLAN AGENT)
Mark phase-4 as in_progress.
4.1: Invoke Plan Agent
```
Task(
subagent_type="plan",
prompt="Create a detailed refactoring plan:
Refactoring Goal
[User's original request]
Codemap (from Phase 2)
[Insert codemap here]
Test Coverage (from Phase 3)
[Insert verification plan here]
Constraints
MUST follow existing patterns: [list]
MUST NOT break: [critical paths]
MUST run tests after each step
Requirements
Break down into atomic refactoring steps
Each step must be independently verifiable
Order steps by dependency (what must happen first)
Specify exact files and line ranges for each step
Include rollback strategy for each step
Define commit checkpoints"
)
```
4.2: Review and Validate Plan
After receiving plan from Plan agent:
Verify completeness: All identified files addressed?
Verify safety: Each step reversible?
Verify order: Dependencies respected?
Verify verification: Test commands specified?
4.3: Register Detailed Todos
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
])
```
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
Mark phase-5 as completed when all refactoring steps done.
PHASE 6: FINAL VERIFICATION (REGRESSION CHECK)
Mark phase-6 as in_progress.
6.1: Full Test Suite
```bash
Run complete test suite
bun test # or npm test, pytest, go test, etc.
```
6.2: Type Check
```bash
Full type check
tsc --noEmit # or equivalent
```
6.3: Lint Check
```bash
Run linter
eslint . # or equivalent
```
6.4: Build Verification (if applicable)
```bash
Ensure build still works
bun run build # or npm run build, etc.
```
6.5: Final Diagnostics
```typescript
// Check all changed files
for (file of changedFiles) {
lsp_diagnostics(file) // Must all be clean
}
```
6.6: Generate Summary
```markdown
Refactoring Complete
What Changed
[List of changes made]
Files Modified
`path/to/file.ts` - [what changed]
`path/to/file2.ts` - [what changed]
Verification Results
Tests: PASSED (X/Y passing)
Type Check: CLEAN
Lint: CLEAN
Build: SUCCESS
No Regressions Detected
All existing tests pass. No new errors introduced.
```
Mark phase-6 as completed.
CRITICAL RULES
NEVER DO
Skip lsp_diagnostics check after changes
Proceed with failing tests
Make changes without understanding impact
Use `as any`, `@ts-ignore`, `@ts-expect-error`
Delete tests to make them pass
Commit broken code
Refactor without understanding existing patterns
ALWAYS DO
Understand before changing
Preview before applying (sg --pattern ... --rewrite ... --lang ...)
Verify after every change
Follow existing codebase patterns
Keep todos updated in real-time
Commit at logical checkpoints
Report issues immediately
ABORT CONDITIONS
If any of these occur, STOP and consult user:
Test coverage is zero for target code
Changes would break public API
Refactoring scope is unclear
3 consecutive verification failures
User-defined constraints violated
Tool Usage Philosophy
You already know these tools. Use them intelligently:
LSP Tools
Leverage LSP tools for precision analysis. Key patterns:
Understand before changing: `LspGotoDefinition` to grasp context
Impact analysis: `LspFindReferences` to map all usages before modification
Safe refactoring: `lsp_prepare_rename` → `lsp_rename` for symbol renames
Continuous verification: `lsp_diagnostics` after every change
AST-Grep
Use `ast-grep` skill helper or `sg` CLI for structural transformations.
Critical: Always preview first, review, then execute.
Agents
`explore`: Parallel codebase pattern discovery
`plan`: Detailed refactoring plan generation
`oracle`: Read-only consultation for complex architectural decisions and debugging
`librarian`: Use proactively when encountering deprecated methods or library migration tasks. Query official docs and OSS examples for modern replacements.
Deprecated Code & Library Migration
When you encounter deprecated methods/APIs during refactoring:
Fire `librarian` to find the recommended modern alternative
DO NOT auto-upgrade to latest version unless user explicitly requests migration
If user requests library migration, use `librarian` to fetch latest API docs before making changes
Remember: Refactoring without tests is reckless. Refactoring without understanding is destructive. This command ensures you do neither.
export const REFACTOR_TEAM_MODE_ADDENDUM = `
Team Mode Protocol (active when team_* tools are present)
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.
Phase 4 override: Plan agent staffing requirement
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:
total_atomic_steps: integer
file_independent_steps: integer (parallelizable, no cross-file blocker)
`unspecified-low`: logic-preserving refactors that need reasoning — extract function, restructure conditional, pattern transformation, cross-file API change.
Recommend `team` path when `file_independent_steps >= 3`; recommend `legacy` otherwise.
Phase 5 override: Dispatch path selection
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:
Team path (5.1-T): when the plan recommends `team` AND `file_independent_steps >= 3`. Members execute in parallel, Lead orchestrates, a `deep` verifier lives outside the team.
Legacy path (5.1-L): otherwise. Use the original 5.1 / 5.2 / 5.3 flow from above.
Record the chosen path in the TodoWrite list.
Phase 5.1-T: `refactor-squad` team execution
Precondition checks (fail hard if any step fails):
Load the `team-mode` skill via the `skill` tool for lifecycle, message protocol, and limits.
Call `team_list` and verify no active `refactor-squad` run exists; if one does, shutdown + delete the orphan before proceeding.
If `~/.omo/teams/refactor-squad/config.json` is missing, write it using the spec below.
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:
4 workers = team mode's parallel cap. 5+ just queues.
No verifier team member. Verification needs `deep-high` reasoning (or `unspecified-high` fallback). In-team category routing downcasts to the category worker, which is weaker than required — the verifier runs OUTSIDE the team as a `task(category="deep-high")`.
quick × 2 for mechanical edits, unspecified-low × 2 for reasoning edits — mirrors the plan's split.
Team lifecycle (one team, reused until Phase 6 cleanup):
`team_create(teamName="refactor-squad")`. Record `teamRunId`.
Broadcast the refactor Intent Card ONCE (keep task descriptions slim):
```
team_send_message(
teamRunId=, to="*", kind="announcement",
summary="refactor-intent",
body=<codemap summary + constraints + established patterns from Phase 2>
)
```
For each plan step, `team_task_create(teamRunId=, subject="refactor step : ", description=<per-step instructions from plan, including target files and line ranges, rollback strategy>, blockedBy=<from plan's per_step_assignment>)`.
Lead monitoring loop:
While any team task is `pending | claimed | in_progress`:
Wait for `` or member messages. Avoid tight polling; a single `team_status` check is acceptable if no notification arrives within roughly 10 seconds of expected completion.
On a worker completion report, immediately dispatch an external verifier — verification runs OUTSIDE the team because team-member category routing downcasts to the category worker:
```
task(
category="deep-high",
load_skills=[],
run_in_background=true,
description="verify step ",
prompt=<files touched + verify-spec commands + instruction to return "PASS" or "FAIL:<failing test + specific error + suggested revert hunks>">
)
```
If `deep` is unavailable, fall back to `category="unspecified-high"`. Do not create a commit checkpoint until the verifier returns PASS.
On a verifier PASS: make the commit checkpoint for that step (see original 5.3). Proceed.
On a verifier FAIL: Lead decides:
Retry with fix hint: `team_task_update(status=pending)` on the original step + `team_send_message(teamRunId=, to=, summary="retry", body=)`. Runtime reassigns.
Escalate: after three FAIL cycles on the same step, STOP and consult the user with full evidence.
On a member UNCLEAR message: re-harvest context via a targeted `task()` outside the team, broadcast an updated Intent Card fragment, then reassign.
Proceed to Phase 6 only when every team task is `completed` AND every paired verifier task returned PASS.
Phase 6 override: Team cleanup before summary
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.
`team_shutdown_request` for each member, then `team_approve_shutdown` if members do not self-approve within a reasonable window.
`team_delete(teamRunId=)`.
`team_list` to confirm no residual `refactor-squad` run.
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).
MUST NOT (team mode)
Lead never edits files directly — orchestrate only.
Do not inline the Intent Card or verify-spec into task descriptions — rely on the broadcasts.
Do not recreate the team mid-session.
Do not run tests from Lead — the external verifier owns that lane.
Do not put `oracle` / `librarian` / `deep` into the team spec — curated read-only agents are team-ineligible, and `deep` under category routing downcasts to the category worker. Use them via `task()` outside the team when needed.
`
How do I install refactor?
Download packages/shared-skills/skills/refactor/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does refactor live?
The publisher keeps it at https://github.com/code-yeongyu/oh-my-openagent.
Which agents can use refactor?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.