Skip to main content
subagent CX Codex

refactoring-specialist · voltagent/awesome-codex-subagents — Codex subagent: how it works

refactoring-specialist delivers low-risk structural refactoring that preserves existing runtime behavior while improving modularity.

MIT ★ 6,505 updated 2026-10-05

Install into Codex · Manually: put the files in place All methods and platforms ↓
.codex/agents/refactoring-specialist.toml
Open on GitHub

What refactoring-specialist does

This subagent targets concrete structural friction points and applies the smallest safe code intervention. It prioritizes extracting clear seams, reducing hidden coupling, and maintaining stable public contracts for downstream callers.

Validation requires running tests across one normal flow, one failure path, and one integration edge before and after editing files. The returned report lists the analyzed boundaries, root causes, verification checks performed, and residual risks.

The subagent strictly forbids mixing feature work into a refactor pass unless the parent agent explicitly demands it.

What it helps with

  • isolate clean module boundaries with minimal file churn
  • cut down complexity and duplicate logic across critical paths
  • verify behavioral equivalence with tests before and after code moves
  • organize incremental commits for safe reviews and rollbacks

Example prompts for the agent

  • Extract the database handling logic from this service into a separate adapter
  • Reduce cyclomatic complexity in this module while keeping all behavior intact
  • Refactor this legacy parser and verify normal, failure, and edge integration paths

How to install refactoring-specialist

Manually: put the files in place

.codex/agents/refactoring-specialist.toml

Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about refactoring-specialist

How to install refactoring-specialist in Codex?

Place the subagent definition file at .codex/agents/refactoring-specialist.toml in your repository.

What does refactoring-specialist do?

It applies minimal structural code improvements that preserve runtime behavior and protect API stability.

Will it introduce new features during a cleanup?

No, it isolates structural cleanup from new capabilities unless you explicitly ask for combined changes.

Source text

refactoring-specialist.toml · MIT
# refactoring-specialist

Use when a task needs a low-risk structural refactor that preserves behavior while improving readability, modularity, or maintainability.

Own behavior-preserving refactoring work as developer productivity and workflow reliability engineering, not checklist execution.

Prioritize the smallest practical change or recommendation that reduces friction, preserves safety, and improves day-to-day delivery speed.

Working mode:
1. Map the workflow boundary and identify the concrete pain/failure point.
2. Distinguish evidence-backed root causes from symptoms.
3. Implement or recommend the smallest coherent intervention.
4. Validate one normal path, one failure path, and one integration edge.

Focus on:
- scope control to isolate structural change from feature change
- seam extraction and modular boundary improvements with minimal churn
- reduction of complexity, duplication, and hidden coupling
- test safety net quality around refactored code paths
- API/interface stability for downstream callers
- incremental commit strategy enabling safe review and rollback
- preservation of runtime behavior and non-functional expectations

Quality checks:
- verify refactor diff keeps behavior equivalent on critical paths
- confirm structural improvements are measurable and localized
- check tests cover key invariants before and after refactor
- ensure compatibility risks are identified where signatures or contracts shift
- call out residual technical debt intentionally deferred

Return:
- exact workflow/tool boundary analyzed or changed
- primary friction/failure source and supporting evidence
- smallest safe change/recommendation and key tradeoffs
- validations performed and remaining environment-level checks
- residual risk and prioritized follow-up actions

Do not mix unrelated feature work into structural refactor changes unless explicitly requested by the parent agent.

© VoltAgent · MIT · VoltAgent/awesome-codex-subagents

Similar subagents

All subagents for Code review and refactoring →

refactoring-specialist by other authors comes first.

refactoring-specialist VoltAgent Community refactoring-specialist transforms messy, duplicated code into clean structures while keeping existing behavior intact. Ideal for legacy refactoring and reducing cyclomatic complexity. CX Codex 784installs refactoring-specialist coco-research refactoring-specialist cleans up code smells and reduces complexity step by step while maintaining existing behavior through constant test runs. CX Codex ★ 328repo stars refactoring-patterns proffesor-for-testing Applies refactoring patterns. Runs when you need to improve code structure without changing behavior. CX Codex +1 140installs refactoring-expert SuperClaude-Org The refactoring-expert subagent cuts cyclomatic complexity and eliminates technical debt using SOLID principles. It helps restructure legacy code safely without altering existing system behavior. CX Codex ★ 23,950repo stars dry-refactoring kucherenko The dry-refactoring skill automates refactoring of copy-paste clones found by jscpd. It guides you through extraction strategies—function, parameterization, module or class—and highlights which files to start with. CX Codex +1 4,100installs safe-refactor JuliusBrussee safe-refactor restructures code while preserving existing behavior, enforcing verification boundaries before structural edits. CX Codex +1 130,700installs codebase-refactoring kucherenko codebase-refactoring runs a guided audit of code duplication, dead code, and complexity using jscpd. Helps clean up technical debt systematically. CX Codex +1 704installs code-refactoring akillness The code-refactoring skill turns a refactoring request into a behavior-aware plan with clear guardrails, reviewable slices, and a defined next step. CX Codex +1 552installs

From the same set176

The whole set →
api-documenter api-documenter — a subagent that generates API documentation from live implementation, schemas, and examples. CX Codex ★ 6,505repo stars visual-asset-generator visual-asset-generator builds production-ready app icons, logos, favicons, and social cards matching project specs via prompt-to-asset MCP. CX Codex ★ 6,505repo stars tooling-engineer The tooling-engineer subagent works on internal tooling, scripts, automation glue, and workflow utilities. Use it when a developer workflow has a concrete failure or friction point. CX Codex ★ 6,505repo stars slack-expert slack-expert is a Codex subagent for Slack development, from bot behavior to event handling and workflows. It joins tasks that involve Slack interactions or platform-specific integration details. CX Codex ★ 6,505repo stars readme-generator The readme-generator subagent builds a README from the repository’s actual files and behavior. Use it to document setup, commands, and configuration without making up details. CX Codex ★ 6,505repo stars powershell-ui-architect powershell-ui-architect is a Codex subagent for PowerShell interfaces in terminals, forms, WPF, and admin tools. It examines interactive workflows to locate friction and failures. CX Codex ★ 6,505repo stars powershell-module-architect powershell-module-architect designs PowerShell module structures, refines cmdlet contracts, and handles packaging issues with minimal disruption. CX Codex ★ 6,505repo stars mcp-developer The mcp-developer subagent handles MCP servers, clients, tool wiring, and protocol-aware integrations. Use it when contract behavior and failure handling need a close review. CX Codex ★ 6,505repo stars

Project sponsors

Companies that keep this analytics open