| name | repo-structure-reviewer |
| description | Audit a repository's structure and propose a safe, approval-gated reorganization plan. Use when asked to review repo anatomy, propose folder changes, or apply an approved reorg with rollback. |
Repo Structure Reviewer
Overview
Create a repo anatomy review and an optimized structure plan, then apply approved changes safely with a rollback plan. Default behavior is dry-run, with per-change approvals before any filesystem modifications.
Quick Start
python3 skills/repo-structure-reviewer/scripts/repo_structure_review.py --root .
Apply mode (still per-change approval):
python3 skills/repo-structure-reviewer/scripts/repo_structure_review.py --root . --apply
Scope and safety controls:
python3 skills/repo-structure-reviewer/scripts/repo_structure_review.py --root . --scope top-level-only --max-changes 25
Full scan with file cap:
python3 skills/repo-structure-reviewer/scripts/repo_structure_review.py --root . --scope full-scan --max-files 20000
Workflow
Phase A: Review + Plan
- Scan the repo structure and detect languages/frameworks/build systems.
- Produce a "Repo Anatomy Review" report:
- top-level tree summary + key subtrees
- detected languages/frameworks/build systems
- pain points and smells
- archive candidates
- stale/outdated/delete candidates
- Produce an "Optimization Plan":
- target structure outline
- ordered list of proposed changes
- per-change rationale, risk, and reversibility notes
Phase B: Approval + Apply
If --apply is provided, start an interactive approval loop:
- Prompt one change at a time (or batched when explicitly supported) with:
- Change ID
- Operation type (MOVE/RENAME/CREATE)
- Before/After paths
- Rationale
- Risk level
- Show details / show diff options
- Print the full list of proposed files/changes for the selected phase before prompting for approvals.
- Require explicit approval for each change.
- Default to skip for delete candidates.
- Stop on error and report the last successful step and rollback guidance.
Hard Safety Requirements
- Default is DRY RUN. No changes without explicit user approval.
- Prefer
git mv when git is present and the file is tracked.
- Never delete by default.
- Deletion proposals require explicit approval.
- Default action is soft-delete into
.repo_reorg_backup/deletions/<timestamp>/....
- Permanent delete requires explicit per-item approval.
- Generate a rollback plan for every applied change.
- Never edit lockfiles unless explicitly approved.
- If any step fails, stop and report how to roll back.
Archive + Stale/Delete Review
The Repo Anatomy Review must include two additional sections:
Archive Candidates (safe to keep, not active)
Flag items that likely belong in an archive area. For each item list:
- path
- why flagged (signals: last modified time, naming patterns, lack of references, superseded by newer file/folder)
- confidence (low/med/high)
- suggested destination (e.g.,
archive/, docs/archive/, .archive/)
- safe handling note: archive = move, not delete
Stale / Outdated / Delete Candidates (needs review)
Flag items that might be removable or require updating. For each item list:
- path
- why flagged
- evidence (last modified, reference scan results, git tracked status, file size)
- recommendation: archive vs update vs delete
- confidence (low/med/high)
- risk notes
Heuristics must be conservative and always label results as candidates.
Outputs / Artifacts
repo_anatomy_review.mdrepo_reorg_plan.jsonrepo_reorg_actions_log.mdrollback_plan.jsonARCHIVE_INDEX.md (when archive moves are approved)
Implementation Layout
scripts/repo_structure_review.py - CLI entrypointscripts/scanner.py - repo scanning and metadata extractionscripts/planner.py - plan generation and candidate detectionscripts/approvals.py - interactive approval loopscripts/applier.py - safe apply + reference updatesscripts/reporting.py - report + artifact writersscripts/models.py - dataclasses shared across modules
Tests
Use pytest to validate:
- dry-run makes zero modifications
- apply requires explicit approval
- rollback artifact is generated
- git move path uses
git mv when git is present (with fallback)
- archive moves create/update
ARCHIVE_INDEX.md
- delete candidates are not removed without explicit approval
Run:
python3 -m pytest skills/repo-structure-reviewer/tests
