repo-maintainer

auldsyababua's avatarfrom auldsyababua

Audits and reorganizes messy repositories into clean, LLM-friendly structures. It uses a non-destructive "Migration Manifest" process to safely consolidate scripts, establish documentation, and create AI context zones.

⭐0stars🔀0forks📁View on GitHub🕐Updated Nov 21, 2025
[Developer Tools]

When & Why to Use This Skill

The Repo Maintainer skill is a specialized utility designed to audit and reorganize disorganized codebases into clean, LLM-optimized structures. It addresses the challenge of 'polluted' repositories by implementing a non-destructive 'Migration Manifest' process that preserves Git history while establishing dedicated AI context zones. This skill significantly enhances repository navigability and reduces technical debt, making codebases more readable for both human developers and AI agents.

Use Cases

  • Cleaning up cluttered root directories by categorizing files into standardized src, docs, and archive folders.
  • Optimizing repositories for AI-assisted development by generating .ai/ context maps and architecture guidelines.
  • Safely refactoring project file structures using a reversible manifest-based approach to ensure zero data loss.
  • Establishing a 'Source of Truth' for legacy projects where documentation is missing or scattered across orphan scripts.
  • Quarantining obsolete or deprecated code without breaking the main build or losing version control history.
namerepo-maintainer
descriptionAudits and reorganizes messy repositories into clean, LLM-friendly structures. It uses a non-destructive "Migration Manifest" process to safely consolidate scripts, establish documentation, and create AI context zones.

Repository Maintainer

Overview

This skill turns disorganized codebases ("polluted roots," "orphan scripts") into structured, readable repositories. It prioritizes LLM-Readability (creating explicit context maps) and Safety (using a reversible migration manifest).

Use this skill when:

  • A repository has too many files in the root directory.
  • Documentation is missing, outdated, or scattered.
  • An LLM struggles to find relevant context due to noise.
  • You need to "refactor" the file structure without breaking git history.

Workflow

1. The Audit (Discovery)

First, analyze the repository to understand "Hot" (frequently changed) vs "Cold" (stale) zones.

  • Run scripts/scaffold_manifest.py to generate a draft manifest.
  • Identify the "blood flow" (dependencies): Does main.py import that messy script?
  • Output: A mental model of the current chaos.

2. The Manifest (Planning)

Do not move files immediately. Create a migration_manifest.yaml that defines the desired state.

  • Run scripts/scaffold_manifest.py to generate a draft manifest if you haven't already.
  • Categorize files into:
    • Core: Application logic (src/)
    • Scaffolding: Configs (.env, docker-compose)
    • Artifacts: One-off scripts (Move to archive/)
    • Knowledge: Docs (Move to docs/)
  • Review the YAML file. It is the "Contract of Changes."

3. Execution (Safe Move)

Apply the changes using the manifest.

  • Run scripts/apply_migration.py.
  • Safety Rule: This script uses git mv to preserve history.
  • Quarantine: Unknown scripts go to archive/quarantine/ rather than being deleted.

4. LLM Optimization (Contextualizing)

Once files are moved, establish the .ai/ directory.

  • Copy assets/CONTEXT_TEMPLATE.md to .ai/CONTEXT.md.
  • Fill it with a high-level summary of the architecture.
  • This ensures future agents understand why the code exists, not just what it does.

Directory Structure Standards

When planning the migration, aim for this specific structure (The "LLM-First" Architecture):

/ (Root)
├── .ai/                 # Context specifically for LLMs
│   ├── CONTEXT.md       # Architecture & Business Logic
│   └── GUIDELINES.md    # Coding standards
├── src/                 # Source code
├── scripts/             # DevOps/Maintenance scripts
├── docs/                # Human documentation
├── archive/             # Deprecated/Quarantine
└── README.md            # The Map