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