Agent-Skills.md

Agent Skills: Repo Structure Reviewer

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.

UncategorizedID: therealityreport/THB-BBL/repo-structure-reviewer

Repository

therealityreport/THB-BBL
therealityreport

Install this agent skill to your local

pnpm dlx add-skill https://github.com/therealityreport/THB-BBL/tree/HEAD/skills/repo-structure-reviewer

Skill Files

Browse the full folder contents for repo-structure-reviewer.

Download Skill

Loading file tree…

skills/repo-structure-reviewer/SKILL.md

Skill Metadata

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

  1. Scan the repo structure and detect languages/frameworks/build systems.
  2. 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
  3. 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.md
  • repo_reorg_plan.json
  • repo_reorg_actions_log.md
  • rollback_plan.json
  • ARCHIVE_INDEX.md (when archive moves are approved)

Implementation Layout

  • scripts/repo_structure_review.py - CLI entrypoint
  • scripts/scanner.py - repo scanning and metadata extraction
  • scripts/planner.py - plan generation and candidate detection
  • scripts/approvals.py - interactive approval loop
  • scripts/applier.py - safe apply + reference updates
  • scripts/reporting.py - report + artifact writers
  • scripts/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