Swarm-orchestrated iterative code refactoring with specialized AI agents that ensure test coverage, design optimizations, simplify code, and verify quality through parallel execution and multiple refinement cycles.
The Refactor plugin orchestrates four specialized agents as a swarm team to systematically improve code quality while preserving functionality:
- Architect Agent — Reviews code architecture, plans optimizations, scores quality
- Refactor-Test Agent — Ensures comprehensive test coverage and validates changes
- Refactor-Code Agent — Implements clean code improvements safely
- Simplifier Agent — Simplifies changed code for clarity, consistency, and maintainability
The refactoring process uses swarm orchestration (TeamCreate, TaskCreate/TaskUpdate, SendMessage) with parallel execution where possible:
Phase 0: Initialize
├── Create swarm team
├── Spawn 4 teammates: architect, refactor-test, refactor-code, simplifier
└── Create phase tasks
Phase 1: Foundation (PARALLEL)
├── [refactor-test] → Analyze coverage, add missing tests, verify passing
└── [architect] → Initial architecture review, identify all opportunities
Phase 2: Iteration Loop (×3)
│
├── Step A: [architect] → Create optimization plan (top 3 priorities)
├── Step B: [refactor-code] → Implement top 3 optimizations
├── Step C: [refactor-test] → Run full test suite, report pass/fail
├── Step D: [refactor-code] → Fix test failures if any → [refactor-test] re-run
├── Step E: [simplifier] → Simplify all code changed this iteration
└── Step F: [refactor-test] → Verify simplification preserved functionality
Phase 3: Final Assessment (PARALLEL)
├── [simplifier] → Final whole-scope simplification pass
└── [architect] → Prepare final quality assessment framework
Phase 4: Final Verification & Report
├── [refactor-test] → Final test suite run
├── [architect] → Score code (Clean Code + Architecture, 1-10 each)
├── Generate refactor-result-{timestamp}.md
└── Shutdown team
# Refactor entire codebase
/refactor
# Refactor specific directory
/refactor src/utils/
# Refactor specific file
/refactor src/app.ts
# Refactor by description
/refactor "authentication logic"
# Override iteration count
/refactor --iterations=5 src/- Claude Code CLI
- Git
- (Optional) GitHub CLI (
gh) for PR and report publishing features
claude --plugin-dir /path/to/refactor- Safety First — Only improves code quality, never alters behavior. Tests pass before and after every change.
- Parallel Execution — Phase 1 and Phase 3 run agents simultaneously for faster results.
- Automatic Test Generation — Adds missing test cases for critical paths, edge cases, and error handling.
- Architecture Scoring — Objective Clean Code and Architecture scores (1--10) with per-criteria justifications.
- Code Simplification — Post-implementation polish: naming clarity, guard clauses, redundancy removal, cross-file consistency.
- Configurable Workflow — Commit strategies, PR creation, and report publishing via
.claude/refactor.config.json.
| Document | Quadrant | Description |
|---|---|---|
| Tutorial: Your First Refactor | Tutorial | Guided walkthrough from install to report review |
| How to Configure Commit Strategies | How-to | Set up commits, PRs, and report publishing |
| How to Scope Refactoring | How-to | Choose effective scopes for different project sizes |
| Troubleshooting | How-to | Diagnose and resolve common problems |
| Configuration Reference | Reference | Full config schema, fields, and examples |
| Agent Reference | Reference | Agent specifications, tools, and invocation points |
| Quality Score Reference | Reference | Scoring rubrics and criteria |
| Swarm Orchestration Design | Explanation | Why the plugin works this way |
Q: Will this change my code's functionality? A: No. The refactoring process explicitly preserves all functionality. Only code quality and structure are improved.
Q: What if my project has no tests? A: The test agent will create them. That's Phase 1.
Q: What languages/frameworks are supported? A: All languages. Agents adapt to your project's testing framework and conventions.
Q: Can I stop mid-refactor? A: Yes, but you'll lose progress. Better to start with smaller scope.
- Configuration-driven post-refactor workflow via
.claude/refactor.config.json - Interactive first-run setup wizard with AskUserQuestion prompts
- Commit strategies: none, per-iteration, single-final
- Optional PR creation (draft or ready-for-review) after refactoring
- Report publishing to GitHub Issues or GitHub Discussions
- Cross-referencing between PRs and published reports
- Non-blocking error handling for all GitHub operations
- Swarm orchestration (TeamCreate, TaskCreate/TaskUpdate, SendMessage)
- New simplifier agent (opus model) for code clarity passes
- Parallel execution in Phase 1 (foundation) and Phase 3 (final assessment)
- 4-phase workflow replacing 7-step sequential process
- Code simplification step after each iteration cycle
- Initial release with sequential 7-step workflow
- Three agents: architect, refactor-test, refactor-code