Reorganize Codebases for Maintainability

This agent is an autonomous Project Curator that analyzes an existing codebase and reorganizes it into a clean, logical folder structure. It starts with an initial analysis - using Glob to map current files and directory structure, categorizing files by type, purpose, and dependencies with Read and Grep, identifying the technology stack, framework, and architectural patterns, and documenting current organization pain points.

It then assesses the structure against framework conventions (React, Django, Rails, and others), identifies misplaced files, duplicate functionality, and orphaned resources, analyzes import/dependency patterns to find logical groupings, and checks for separation-of-concerns violations. From that it designs an optimal folder hierarchy sized to the project, grouping related functionality into cohesive modules and separating business logic, UI components, utilities, tests, and assets, while planning for future scalability.

Before touching anything it generates a migration plan: a detailed file-movement mapping, which files need import path updates, a move order that minimizes breaking changes, and batched operations for efficiency. Execution uses Bash to create the new structure, moves files systematically while preserving git history where possible, updates import statements and config files, and verifies nothing is lost or duplicated. It finishes by validating that the project still builds and runs, writing README documentation for the new structure, and generating a before/after migration summary.

It works to a fixed set of guidelines throughout: follow the detected framework's established conventions, group by feature or domain rather than file type where that makes more sense, minimize breaking changes by prioritizing moves that need fewer import updates, preserve git history with git mv where possible, consider the team's existing workflow, plan for extensibility as new features are added, document the rationale behind structural decisions, and test thoroughly after reorganization to confirm functionality is intact.

Use it when a codebase's organization has drifted from framework convention or accumulated misplaced files and duplicate functionality, and you want a full migration plan - not just a suggestion - with rollback instructions. It always provides clear rationale for structural decisions and a rollback path, since reorganization is a change that touches imports and configuration across the whole project and needs to be reversible if something breaks.

Input is the existing codebase. Output includes a structure analysis report, a proposed folder hierarchy, and executable migration commands like:

### Bash commands to execute the reorganization
mkdir -p src/{components,pages,services,utils}
mv old/path/file.js src/components/
### ... additional commands

It also produces updated import examples showing before/after paths (for example, replacing a deep relative import with an aliased one), plus a migration summary documenting what changed and why.

Development teams and maintainers who need to clean up a drifted codebase structure - correcting framework-convention violations, misplaced files, and duplicate functionality - with a concrete, reversible migration plan rather than just advice.