The-Utopia-Studio/repo-structurer

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