refactor

/refactor - Multi-File Refactoring Orchestrator

Advanced refactoring orchestration with rollback automation, test generation, synergy detection, and incremental refactoring support.

🎯 Purpose

Transform large-scale refactoring from a risky manual process into a safe, automated, and observable workflow. The refactor skill provides:

• Rollback Automation: Git-based safety nets with auto-generated rollback scripts
• Test Generation: TDD phases (RED → GREEN → REFACTOR) with automated test scaffolding
• Synergy Detection: Cross-file pattern analysis for DRY violations and extraction opportunities
• Complexity Triage: Risk-based prioritization using cyclomatic complexity scoring
• Incremental Refactoring: State persistence for resumable multi-session refactoring
• Configuration Management: CLI + YAML/JSON config with sensible defaults

🚀 Quick Start

Claude Code Skill

# Create junction (Windows - no admin required)
# Run from the skills parent directory
mklink /J "P:\.claude\skills\refactor" "P:\.claude\skills\refactor"

# Or create symlink (macOS/Linux)
ln -s "$(pwd)" ~/.claude/skills/refactor

The skill is accessed via /refactor in Claude Code.

Three Deployment Models

IMPORTANT: This package supports three different deployment modes. Choose the right one for your use case.

1. SKILLS (Dev Deployment) ⭐ Recommended for Development

For: When you're actively developing this package and want instant feedback.

Setup:

# Windows (Junction - No admin required)
# For plugins with skills: Junction to the skills/ subdirectory

# IMPORTANT: Sanitize the junction name to remove problematic characters
$junctionName = "refactor" -replace '[@?*:<>|+]', ''

New-Item -ItemType Junction -Path "P:\.claude\skills\$junctionName" -Target "P:\packages\refactor\skills\refactor"

Key points:

• ✅ Edit in P:/packages/refactor/, changes work immediately
• ✅ No reinstallation required - skills auto-discover from P:/.claude/skills/
• ✅ Perfect for active development

2. HOOKS (Dev Deployment - Hook Files Only)

For: When this package has hook files (.py files in scripts/hooks/) you want to test.

Setup:

# Symlink individual hook files to P:/.claude/hooks/
cd P:/.claude/hooks
cmd /c "mklink HookName.py P:/packages/refactor/scripts/hooks/HookName.py"

3. PLUGINS (End User Deployment)

For: Distributing this package to other users via marketplace or GitHub.

Setup:

# End users install via /plugin command
/plugin P:/packages/refactor

🏗️ Architecture

System Overview

graph TD
    A[User invokes /refactor] --> B[Skill Interface]
    B --> C{Mode Selection}
    C -->|Discovery| D[Pattern Detection]
    C -->|TDD| E[Test Generation]
    C -->|Rollback| F[Git State Capture]
    C -->|Analysis| G[Complexity Triage]
    C -->|Incremental| H[State Persistence]

    D --> I[Synergy Detector]
    E --> J[Test Generator]
    F --> K[Rollback Manager]
    G --> L[Complexity Scorer]
    H --> M[State Manager]

    I --> N[Report Generation]
    J --> N
    K --> N
    L --> N
    M --> N

    style B fill:#e1f5ff
    style N fill:#c8e6c9

Module Structure

refactor/
├── SKILL.md                 # Skill definition and usage
├── __init__.py              # Public API exports
├── README.md                # This file
├── CHANGELOG.md             # Version history
├── LICENSE                  # MIT License
├── plan.md                  # Implementation roadmap
│
├── lib/                     # Python skill modules
│   ├── plan_review.py       # Plan review and validation
│   └── refactor_plan.py     # Refactoring plan generation
│
└── scripts/                 # Utility scripts
    ├── code_scanner.py      # Code analysis scanner
    └── install-dev.bat      # Windows junction automation

Key Components

Module	Responsibility	Key Features
RefactorConfig	Configuration management	CLI + YAML/JSON, threshold customization
RollbackManager	Git-based safety	State capture, rollback script generation, cleanup
TestGenerator	TDD orchestration	RED → GREEN → REFACTOR phases, test result tracking
SynergyDetector	Cross-file analysis	DRY violation detection, extraction opportunity finding
ComplexityTriage	Risk prioritization	Cyclomatic complexity scoring, priority levels (P0-P3)
StateManager	Incremental progress	Terminal-isolated state persistence, atomic writes

📖 Usage

As Claude Code Skill

Invoke the refactor skill from Claude Code: