repo-structure

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

• Tier Classification (Determines Which Rules Apply)
• Canonical Structure (+1)
• Allowed at Repo Root (+2)
• Gitignore Enforcement: Root-Level Output Artifacts
• Allowed in docs/ (+1)
• Agent Infrastructure Rules
• Compliance Quick-Check
• NEVER: tests/ inside src/ (+7)
• See Also

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.