# Repo Structure

> 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.

- Skill: `vamseeachanta/repo-structure` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vamseeachanta/repo-structure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/repo-structure/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vamseeachanta (https://skillmd.com/u/vamseeachanta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamseeachanta/repo-structure

---


# Repo Structure

## Sub-Skills

- [Tier Classification (Determines Which Rules Apply)](tier-classification-determines-which-rules-apply/SKILL.md)
- [Canonical Structure (+1)](canonical-structure/SKILL.md)
- [Allowed at Repo Root (+2)](allowed-at-repo-root/SKILL.md)
- [Gitignore Enforcement: Root-Level Output Artifacts](gitignore-enforcement-root-level-output-artifacts/SKILL.md)
- [Allowed in docs/ (+1)](allowed-in-docs/SKILL.md)
- [Agent Infrastructure Rules](agent-infrastructure-rules/SKILL.md)
- [Compliance Quick-Check](compliance-quick-check/SKILL.md)
- [NEVER: tests/ inside src/ (+7)](never-tests-inside-src/SKILL.md)
- [See Also](see-also/SKILL.md)

## 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"