| name | repo-structure |
| version | 1.4.0 |
| category | workspace |
| description | Canonical source layout, test mirroring, root cleanliness, gitignore, docs classification, and committed artifact rules for all workspace-hub tier-1 repos. Consult before creating directories or files in any submodule. |
| type | reference |
| invocation | /repo-structure |
| applies-to | ["claude","codex","gemini"] |
| capabilities | [] |
| requires | [] |
| tags | [] |
Repo Structure
Sub-Skills
Iron Law
No file or directory shall be created outside the canonical structure without consulting this skill first — ever.
Rationalization Defense
| Excuse | Reality |
|---|
| "I just need a quick temp directory at the root" | Root-level clutter is permanent. Use the canonical location or it does not get created. |
| "Tests next to source files are easier to find" | Tests inside src/ is an explicit NEVER rule (+7 violations tracked). Use the tests/ mirror. |
| "This output file is small, no need for .gitignore" | Committed artifacts accumulate. If it is generated, it belongs in .gitignore, regardless of size. |
| "The user didn't specify where to put this" | That is exactly when you consult repo-structure. Silence is not permission to improvise. |
Generated Evidence Exception Pattern
When tracked files already exist under generated-output roots (outputs/**, reports/**, dist/**, etc.), do not blindly move or delete them during a structure refactor. First classify the path as unauthorized generated artifact, durable evidence, or temporary durable exception. Temporary durable exceptions must include owner/category/review-date metadata, a concrete follow-up issue URL or permanent-justification schema, and checker coverage that rejects placeholders. If live source/docs intentionally reference the generated path, broad zero-match stale-reference gates are invalid; use scoped checks that only reject unauthorized tracked generated roots and stale committed-evidence links.
Checker pitfall: path-only parsing of git status --short is insufficient. Preserve status codes so the checker rejects deletion () and rename/relocation () of generated-output paths; otherwise a prohibited generated-artifact move can pass merely because the path itself is classified.
