| name | repository-organization |
| author | JM Labs (Javier Montaño) |
| version | 1.0.0 |
| description | Audit and improve repository structure: naming consistency, directory patterns, file organization, staleness detection. Auto-organization per Constitution XVIII. [EXPLICIT] Trigger: "repo organization", "structure audit", "naming consistency", "directory cleanup", "auto-organize"
|
| allowed-tools | ["Read","Glob","Grep","Bash","Write"] |
Repository Organization
"Entropy is actively countered — the repo gets more organized over time, not less."
TL;DR
Audits and improves repository structure for navigability and maintainability. Checks naming consistency (kebab-case slugs), directory patterns (self-documenting layout), file organization (no accumulation without structure), and staleness (empty/outdated directories). Implements Constitution XVIII auto-organization: when files accumulate without structure, organize into named subdirectories with READMEs. [EXPLICIT]
Deterministic Safety Contract
- Use
assets/repository-organization-contract.json for report shape.
- Use
assets/transient-placement-policy.json to classify workspace/archive files.
- Use
assets/move-manifest-policy.json before moving, archiving, or deleting local files.
- Use
assets/private-boundary-policy.json to keep private context out of publishable paths.
- Validate reports with
scripts/validate_repository_organization_report.py.
- Run
scripts/check.sh before claiming the repo is organized.
Fail closed when a private path is moved or published, a cleanup action lacks a manifest, or clean_claim is true while unresolved transient/private findings remain. [EXPLICIT]
Procedure
Step 1: Discover
- Scan full directory tree
- Check naming conventions across all directories and files
- Identify directories with >10 files (candidates for sub-organization)
- Check for empty directories
- Read .gitignore for completeness
Step 2: Analyze
- Naming audit: all directories kebab-case? All files follow conventions?
- Pattern consistency: do similar components follow same directory layout?
- Accumulation check: any directory with >10 unorganized files?
- Staleness: empty directories? Directories with no recent commits?
- Workspace separation: any transient files outside workspace/?
Step 3: Execute
- Generate organization report with findings and recommendations
- For accumulated files: propose subdirectory structure with READMEs
- For naming violations: propose renames (with impact assessment)
- For empty directories: propose removal
- For stale directories: flag for review
- Auto-generate READMEs for any directory missing one
Step 4: Validate
- All directories follow naming conventions
- No directory has >10 unorganized files
- No empty directories remain
- All transient files are in workspace/
- Every directory has a README
- Report is actionable (specific paths, specific recommendations)
Quality Criteria
Related Skills
indexability-validator — README-specific validationcode-review — Code sustainability includes naming (XII)workspace-governance — Workspace structure separate from repo
Usage
Example invocations:
- "/repository-organization" — Run the full repository organization workflow
- "repository organization on this project" — Apply to current context
Assumptions & Limits
- Assumes access to project artifacts (code, docs, configs) [EXPLICIT]
- Requires English-language output unless otherwise specified [EXPLICIT]
- Does not replace domain expert judgment for final decisions [EXPLICIT]
Edge Cases
| Scenario | Handling |
|---|
| Empty or minimal input | Request clarification before proceeding |
| Conflicting requirements | Flag conflicts explicitly, propose resolution |
| Out-of-scope request | Redirect to appropriate skill or escalate |
