Refactor Tool

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

Overview

Refactor Tool helps you refactor frontend projects (React@16.14 + 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

``bash
npm install -g @refactor-tool/cli
`

Quick Start

1. Initialize the tool in your project:
`bash
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 - 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 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 --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

`bash


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
├── / # 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-/

.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//analysis.md - Generated by AI based on skill capabilities
- Proposal Context: refactor/changes//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-/`
- 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