Refactor Tool

AI-powered refactoring tool for frontend projects with OpenSpec integration.

Overview

Refactor Tool helps you refactor frontend projects ([email protected] + TypeScript + antd@4) using independent refactor capabilities. Each capability can be executed independently without requiring other capabilities to complete first.

Available Capabilities:

1. directory-structure - Analyze and refactor project/component directory structure
2. component-design - Analyze component design, props, and reusability
3. code-style - Analyze code style issues (ESLint, Stylelint, TypeScript, JS→TS conversion)
4. business-logic - Analyze business logic, state management, and API patterns
5. styled-jsx-to-css-module - Convert styled-jsx to CSS Module format

Features

• ✅ Independent capabilities - Execute any refactor capability independently
• ✅ Optional stage workflow - Use --stage-mode for stage-based workflow if preferred
• ✅ OpenSpec integration - Manage refactoring proposals with OpenSpec
• ✅ Cursor IDE support - Integrated commands and skills for Cursor
• ✅ Capability dependencies - Optional dependency checking with warnings (non-blocking)
• ✅ Batch analysis - Support for large projects with incremental analysis

Installation

npm install -g @refactor-tool/cli

Quick Start

1. Initialize the tool in your project:

refactor init

This creates:

• refactor/ directory with OpenSpec structure
• 4 refactoring skills in .cursor/skills/
• Cursor commands in .cursor/commands/

2. Start refactoring:
   • Use /refactor-tool-refactor command in Cursor to analyze your project
   • Review and apply proposals using /refactor-tool-apply
   • Archive completed proposals using /refactor-tool-archive

CLI Commands

• refactor init [path] - Initialize refactor tool in your project
• refactor capabilities - List all available refactor capabilities
• refactor list - List all active refactoring proposals
• refactor show [proposal-id] - Show a refactoring proposal
• refactor archive [proposal-id] - Archive a completed proposal
• refactor update [path] - Update refactor tool instruction files

Cursor Commands

After running refactor init, these commands are available in Cursor:

• /refactor-tool-refactor - Start refactoring analysis (shows capability list)
• /refactor-tool-refactor <capability-id> - Execute a specific capability directly
• /refactor-tool-apply - Apply a refactoring proposal
• /refactor-tool-archive - Archive a completed proposal

Refactoring Capabilities

The tool includes 5 refactor capabilities (each can be executed independently):

1. directory-structure - Analyzes directory structure and organization
2. component-design - Analyzes component design and architecture
3. code-style - Analyzes code style and linting issues
4. business-logic - Analyzes business logic and patterns
5. styled-jsx-to-css-module - Converts styled-jsx to CSS Module format

Workflow (Default - Independent Mode)

1. Run refactor init to set up the tool
2. Use /refactor-tool-refactor to select a capability, or /refactor-tool-refactor <capability-id> to run directly
3. Review generated OpenSpec proposals
4. Apply proposals using /refactor-tool-apply or manually
5. Archive completed proposals
6. Execute other capabilities as needed (no order required)

Workflow (Optional - Stage Mode)

If you prefer stage-based workflow:

1. Use --stage-mode flag: refactor run <capability> --stage-mode
2. Execute capabilities in stage order
3. Complete all proposals in a stage before moving to next
4. Stage gate checks are enforced

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Run CLI locally
npm run dev:cli

# Test
npm test

Project Structure

refactor/
├── AGENTS.md              # Instructions for AI assistants
├── project.md             # Project context and conventions
├── progress.md            # Progress tracking (capability execution history)
├── specs/                 # Refactoring specifications
│   ├── directory-structure/
│   ├── component-design/
│   ├── code-style/
│   └── business-logic/
└── changes/               # OpenSpec proposals
    ├── <change-id>/       # Active proposals
    │   ├── proposal.md    # Proposal details
    │   ├── tasks.md       # Implementation tasks
    │   ├── design.md      # Design decisions (optional)
    │   ├── analysis.md    # Analysis report (generated by AI)
    │   ├── context.md     # Skill execution context
    │   └── specs/         # Specification deltas
    └── archive/           # Archived proposals
        └── YYYY-MM-DD-<change-id>/

.cursor/
├── commands/              # Cursor commands
│   ├── refactor-tool-refactor.md
│   ├── refactor-tool-apply.md
│   └── refactor-tool-archive.md
└── skills/                # Refactoring skills
    ├── directory-structure-refactor/
    ├── component-design-refactor/
    ├── code-style-refactor/
    └── business-logic-refactor/

File Path Conventions

Refactor Tool uses standard file path conventions to ensure AI knows which files to read:

• Analysis Report: refactor/changes/<change-id>/analysis.md - Generated by AI based on skill capabilities
• Proposal Context: refactor/changes/<change-id>/context.md - Skill execution context (skill name, capability ID, analysis report path, execution params)
• Progress Tracking: refactor/progress.md - Capability execution history and proposal associations

Proposal Completeness:

• Each proposal directory contains all materials for that requirement (proposal.md, tasks.md, design.md, analysis.md, context.md, specs/)
• When archiving, all files in the proposal directory are archived together to refactor/changes/archive/YYYY-MM-DD-<proposal-id>/
• This ensures no redundant files remain in the project after archiving

Requirements

• Node.js >= 20.19.0
• OpenSpec (installed globally or as dependency)
• Cursor IDE (for full integration)

License

MIT