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

0. Clarify - A refactor's target shape is rarely fixed by the request. Before exploring, run clarifying rounds through the host's question tool until no fork is left: target shape, what must not change, and what "done" looks like; recommendation first on each
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.

Refactors are a top source of subtle regressions. The one cross-model Codex review per PR (run by /ship, or on request) covers the refactor diff; do not run a separate Codex pass here. The reviewer agent above is the in-workflow review.

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