# Project Structure

> Applies the user's language-agnostic repository layout, documentation, governance, hook, test, agent-file, and changelog conventions. Use when scaffolding or restructuring a repo, writing AGENTS.md or docs, or laying out folders.

- Skill: `frostney/project-structure` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add frostney/project-structure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frostney/project-structure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Unlicense OR MIT
- Author: frostney (https://skillmd.com/u/frostney)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frostney/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 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](references/documentation.md) when creating
  or restructuring README, docs, governance, agent files, or a multi-area repo.
- Read [references/tooling.md](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.