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 tracking status
git ls-files | head -50
git ls-files --others --exclude-standard | grep -v "/"

# Duplicate directory detection
find . -type d -name "skills" -o -name "agents" 2>/dev/null

# Hidden folder inventory
ls -la .* 2>/dev/null | grep "^d"

# Stale artifacts at root
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 mv src/<pkg>/<module> src/<pkg>/modules/<module>
git mv tests/<module> tests/modules/<module>

Phase 3.5 — Hidden folder consolidation (parallel per folder): See references/patterns.md §Hidden Folder Consolidation.

Phase 4 — Import updates (parallel by file type):

find . -name "*.py" -exec sed -i \
  's/from <pkg>\.<mod>/from <pkg>.modules.<mod>/g' {} \;

Phase 5 — Cleanup (parallel): Remove root artifacts, consolidate agent dirs, update .gitignore.

Phase 6 — Verification (parallel then sequential):

uv run pytest tests/ -v
git log --follow --oneline -- src/<pkg>/modules/<module>/<file>.py

Quick Start

# Pre-flight
git status && git ls-files --others --exclude-standard | wc -l

# Create module structure
mkdir -p src/<pkg>/modules tests/modules specs/modules docs/modules examples/modules

# Archive completed plan files
git mv specs/modules/<completed-plan>.md specs/archive/

# Verify after cleanup
uv run pytest tests/ -v && git status

Atomic Commit Strategy

Related Skills

• ../context-management/SKILL.md — Managing context during large refactors
• ../meta/session-start-routine/SKILL.md — Session initialization