# Refactor

> Behavior-preserving restructuring of code outside the current diff, such as extracting modules, renaming across files, or paying down debt. Triggers "refactor X", "restructure", "extract Y from Z". Just-changed code goes to /zero-tech-debt.

- Skill: `darkroomengineering/refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add darkroomengineering/refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/darkroomengineering/refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: darkroomengineering (https://skillmd.com/u/darkroomengineering)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/darkroomengineering/refactor

---


# Refactoring Workflow

## Standalone Codex

Create each new agent with `spawn_agent`, deliver
context to a running agent with `send_message`, trigger another turn for an idle
existing agent with `followup_task`, wait with `wait_agent`, and stop a current
turn with `interrupt_agent` only when necessary. Never spawn `codex-verifier`
and never run `codex-run.ts` from inside Codex.

Writers share the working tree unless the live host explicitly offers
isolation. Assign non-overlapping ownership and serialize planner handoff,
implementer, and test-writer phases; only read-only reviewers may overlap.
Codex implementers are not promised Claude worktree isolation.

You are in **Maestro orchestration mode**. Delegate immediately.

## Workflow

1. **Explore** - Spawn `explore` agent to analyze current code
2. **Plan** - Spawn `planner` agent to design refactoring approach
3. **Implement** - Spawn `implementer` agent to refactor
4. **Test** - Spawn `tester` agent to verify behavior unchanged
5. **Review** - Spawn `reviewer` agent to check quality
6. **Learn** - Store patterns discovered during refactoring

## Agent Delegation

Spawn explore and planner first — they accept thin prompts because they
discover what they need from the codebase:

```
Agent(explore, "Analyze the code to refactor: $ARGUMENTS. Identify patterns, issues, dependencies.")
Agent(planner, "Design refactoring approach based on analysis. Keep behavior unchanged.")
```

**Claude: then assemble the implementer prompt from the actual planner output.**
The Claude implementer runs in an isolated worktree with no access to prior agent
results, so paste the real plan — not "according to plan":

- The user's refactor target (`$ARGUMENTS`) verbatim
- The planner's step-by-step plan, including file paths and each move/rename/extract operation
- Any "preserve behavior" invariants the planner called out
- The test command that must remain green
- Scope: "only the files in the plan; do not touch anything else"

Now spawn:

```
Agent(implementer, "<the assembled briefing above — all five items inline>")
Agent(tester, "Verify refactored code behaves identically to original.")
Agent(reviewer, "Review refactoring for quality and completeness.")
```

**Standalone Codex branch:** follow the lifecycle and serialization rules at
the top. Use a fresh read-only `reviewer` for the independent pass after the
writer and tester finish. Skip the Claude bridge branch below.

Refactors are a top source of subtle regressions — behavior that "shouldn't change" quietly does. When the Codex bridge is available, run a cross-model review in parallel with the reviewer:

```
Agent(codex-verifier, "Cross-model review of the refactor diff. Confirm behavior is preserved; report findings by severity.")
```

The bridge is gated and fails open: if Codex is unavailable, the reviewer agent alone is fine.

If the `codex-verifier` spawn fails, or it reports that Bash was stripped (forked skill contexts), run `bun "$HOME/.claude/src/scripts/codex-run.ts" review` directly instead — never skip the cross-model pass.

## Output

Return a summary:
- **What changed**: Brief description
- **Files modified**: List of files
- **Tests passing**: Verification status
- **Improvements**: What's better now
- **Learnings**: Patterns worth remembering