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	["Codex","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.

Red Flags

These phrases signal you are about to violate the Iron Law:

• "I'll just put this here for now"
• "it doesn't matter where this file goes"
• "this is a temporary file"
• "the existing structure doesn't have a place for this"
• "tests/ is too far from the code"