repo-structurer

name	repo-structurer
description	Cleans up and structures a repository for production. Adds README files to every directory, modularizes code, removes dead files, and makes the repo LLM-smart. Use when the user asks to "clean up", "structure", "document", or "organize" their repo. Don't use for code review or bug fixing.

Repo Structurer

Makes any repository clean, documented, and agent-friendly by adding READMEs, improving organization, and removing clutter.

How It Works

1. Analyze the current directory structure
2. Identify directories missing READMEs
3. Generate context-aware READMEs for each directory
4. Identify dead code and unused files
5. Suggest modularization improvements
6. Create agent configuration files (AGENTS.md, .cursorrules)

Step-by-Step Procedure

Step 1: Map the Directory Structure

find . -type d -not -path './.git/*' -not -path './node_modules/*' -not -path './.next/*' -not -path './dist/*' -not -path './__pycache__/*' -not -path './venv/*'

Step 2: Check README Coverage

# Find directories without READMEs
for dir in $(find . -type d -not -path './.git/*' -not -path './node_modules/*' -not -path './.next/*' -maxdepth 3); do
  if [ ! -f "$dir/README.md" ]; then
    echo "MISSING: $dir"
  fi
done

Step 3: Generate READMEs

For each directory missing a README, create one following this template:

# {Directory Name}

{One sentence describing what this directory contains and why it exists.}

## Contents

{List the key files/subdirectories with one-line descriptions.}

## How It Works

{2-3 sentences explaining the role of this directory in the overall project.}

## Key Files

| File | Purpose |
|------|---------|
| `{file}` | {description} |

Rules for README generation:

• Read 2-3 files in the directory to understand purpose
• Keep it under 30 lines
• Focus on WHAT and WHY, not HOW (the code shows how)
• Make it useful for AI agents navigating the codebase
• Include relationships to other directories if relevant

Step 4: Identify Dead Code

• Files not imported anywhere
• Commented-out code blocks > 10 lines
• Unused dependencies in package.json / requirements.txt
• Empty files or placeholder files
• Duplicate files with slightly different names

Step 5: Suggest Modularization

Look for:

• Files > 300 lines that could be split
• Functions > 50 lines that could be extracted
• Mixed concerns (API routes + business logic + database queries in one file)
• Utility functions scattered across multiple files

Step 6: Create Agent Config

AGENTS.md (if not exists):

• Describe the project purpose
• List the tech stack
• Document key commands (build, test, deploy)
• Set boundaries (what agents should/shouldn't modify)

.cursorrules (if not exists):

• Define code style preferences
• Set framework-specific patterns
• Include file organization rules

Output Format

## 🧹 Structure Report

### README Coverage
- Before: X/Y directories documented
- After: Y/Y directories documented
- Files created: {list}

### Dead Code Found
- {file}: {reason}

### Modularization Suggestions
1. {suggestion with rationale}

### Agent Config
- AGENTS.md: {created/updated/already exists}
- .cursorrules: {created/updated/already exists}

Important

• ALWAYS ask before deleting files
• ALWAYS explain WHY a change is recommended
• Keep READMEs concise — agents have limited context windows
• Prioritize directories that other developers/agents interact with most