Apply only the roles and documents needed by the requested work. Preserve valid project conventions; surface a material restructuring choice before making it. Language and stack skills own language-specific commands and config.
Core layout
Name these roles according to the ecosystem:
- Root: user-facing
README.md, manifest, one canonical lockfile, agent context, optional contribution rules, and governance files. - Source: one conventional source root, organized by domain or namespace.
- Tests: unit tests co-located with source; end-to-end suites in one top-level project-owned location; add layer-specific tests only for delivered or regression-prone layers.
docs/: architecture, quick start, tooling, code style, and deployment.- Scripts: one-off automation in
scripts/,bin/, ortools/. - Generated output: one ignored build/output location.
- Optional: generator templates, static assets, and provisioned agent skills.
Tests must catch meaningful regressions. End-to-end coverage is the primary system-level net; unit tests cover public module behavior without duplicating the same assertion.
Governance
Projects on this style keep these canonical root files:
VISION.md: durable product and technical direction, including exclusions.DEFINITION_OF_READY.md: hard gate before implementation.DEFINITION_OF_DONE.md: hard gate before a change is called shippable.
In a multi-area repo, the nearest area-specific file wins. Link between governance, agent, contributor, and project docs instead of duplicating policy. Flag a missing governance file when a workflow requires it; do not invent a substitute.
Agent context
AGENTS.md is canonical. CLAUDE.md is a symlink to it, or contains only an
include plus genuine Claude-specific additions when symlinks are unavailable.
Never maintain divergent copies.
Keep the root AGENTS.md lightweight: briefly identify the repository, then
spend its context on non-obvious gotchas, exact commands, hard constraints, and
safety boundaries. Do not restate a file tree or conventions evident from the
repository.
Add nested <area>/AGENTS.md only where rules differ; the root points to each
area. Use CONTRIBUTING.md for authoritative human merge requirements and link
to it rather than repeating them.
If curated skills are provisioned, .agents/skills/ and skills-lock.json are
generated by the skills tool, never hand-edited. Symlink .claude/skills to
.agents/skills.
Situational references
- Read references/documentation.md when creating or restructuring README, docs, governance, agent files, or a multi-area repo.
- Read references/tooling.md when installing hooks, scripts, changelog generation, markdown/link/duplication checks, or architectural-drift enforcement.
Completion
- The repository's declared verification gate passes.
- Documentation changed by the work is current and has one authoritative home.
- Generated files were changed through their owner tool.
- No unrelated structural migration was introduced.