vamseeachanta 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 (D) and rename/relocation (R) of generated-output paths; otherwise a prohibited generated-artifact move can pass merely because the path itself is classified.
Phase 1 Contract Checker Pattern
For approved Phase 1 repo-structure issues, use the packaged pattern in references/phase1-contract-checker-pattern.md: bounded docs/config/checker/tests/enforcement only, TDD slices for unapproved roots and generated-root metadata, default checker coverage of git ls-files plus non-ignored working-tree paths, and no broad moves/deletions until artifacts are classified.
Agent/runtime folder authority mapping
When work touches provider identity/config folders, generated runtime files, local home-directory symlinks, memory bridges, or skill roots, classify each path by authority before editing. Use references/agent-runtime-authority-map.md for the canonical source vs generated runtime vs local symlink vs bridge output workflow and issue-body shape for recurring human/agent folder-confusion reports.
Repo placement and relocation audit
When moving nested checkouts out of a parent repo or preparing machine-placement decisions for tier-1 repos, follow references/repo-placement-and-relocation-audit.md: classify each checkout first, move whole repos intact, verify nested=gone/sibling=git, and audit stale nested-path references before creating follow-on placement issues.
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"