| name | module-based-refactor |
| description | Reorganize a repository from flat structure to a module-based 5-layer architecture (src/tests/specs/docs/examples) while preserving git history. Use when restructuring a codebase into modules, migrating import paths, cleaning up hidden folders, consolidating duplicate directories, removing root-level artifacts, or archiving completed plan files. Capabilities: parallel agent spawn strategy, hidden-folder consolidation patterns, benchmark fixture separation, 4-phase atomic commit workflow.
|
| version | 3.2.0 |
| updated | "2026-01-20T00:00:00.000Z" |
| category | _internal |
| triggers | ["repository reorganization","flat to module structure","codebase restructuring","module-based architecture","import path migration","git mv refactor","5-layer architecture","artifact cleanup","directory consolidation","hidden folder cleanup","hidden folder consolidation","merge hidden folders"] |
| tags | [] |
Module-Based Refactor Skill
Reorganize a repository from flat to a consistent module-based 5-layer
architecture while preserving git history. Handles cleanup of artifacts,
runtime data, and hidden folders.
See references/patterns.md for: full checklists, hidden-folder
consolidation patterns, cleanup categories table, benchmark reorganization,
complete session workflow, metrics tracking, and common issues/solutions.
When to Use
- Reorganizing a flat repository to module-based layout
- Consolidating scattered modules into a unified hierarchy
- Migrating import paths while preserving git history
- Cleaning up root-level artifacts (logs, temp files, build artifacts)
- Consolidating duplicate directories (agents/, coordination/, memory/)
- Reviewing and removing obsolete hidden folders
Pre-flight Checks
Run before starting any reorganization:
git ls-files | head -50
git ls-files --others --exclude-standard | grep -v "/"
find . -type d -name "skills" -o -name "agents" 2>/dev/null
ls -la .* 2>/dev/null | grep "^d"
ls *.log *.tmp *.html *.sim 2>/dev/null
Target Structure
src/<package>/modules/<module_name>/
tests/modules/<module_name>/
specs/modules/<module_name>/
docs/modules/<module_name>/
examples/modules/<module_name>/
Process Steps
Phase 1 — Analysis (parallel): List directories, inventory root
artifacts, audit hidden folders.
Phase 2 — Directory creation (sequential):
mkdir -p src/<pkg>/modules tests/modules specs/modules docs/modules examples/modules
touch specs/modules/.gitkeep docs/modules/.gitkeep examples/modules/.gitkeep
Phase 3 — Module moves (parallel per module): Always use git mv.
git src/<pkg>/<module> src/<pkg>/modules/<module>
git tests/<module> tests/modules/<module>
