project-structure

Project structure

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/, or tools/.
• 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 regular file whose first line is @AGENTS.md, followed only by genuine Claude-specific additions. It covers Claude Code sessions that cannot read AGENTS.md directly, and an imported AGENTS.md is never loaded twice. Never a copy, and never a symlink: Git checks a symlink out as a one-line text file on Windows without core.symlinks, and Claude Code's Edit and Write tools refuse to write through one. Replace a symlinked or copied CLAUDE.md with the import, and update anything that relied on the link.

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.