# Specs And Guardrails Layout

> Canonical path: `specs/repository/specs-and-guardrails-layout.md`
> Status: living-spec
> Scope: repository-wide organization for canonical specs, guardrail scripts, and spec-owned assets.

## 1. Purpose

AgentTeam keeps long-lived product, architecture, and engineering contracts in repository-root `specs/`. Executable checks that protect those contracts live in repository-root `guardrails/`.

This layout gives humans, agents, and CI one canonical place to find durable specs and their enforceable rules. It also prevents a second canonical spec tree from reappearing under documentation folders.

## 2. Directory Contract

Canonical specs MUST use one of these layouts:

- `specs/{domain}/{spec-name}.md`
- `specs/{domain}/{subdomain}/{spec-name}.md`

Every `specs/{domain}/` directory MUST include `README.md` with links to all specs in that domain. Order entries by conceptual reading order, not by filename or commit history. Domain overview specs should come first, followed by subdomain or specialized specs. `README.md` is required instead of `INDEX.md` so directory viewers open the domain index automatically.

The maximum spec directory depth is two semantic levels after `specs/`: `{domain}` and optional `{subdomain}`. Put deeper detail in headings inside the spec instead of adding more directories.

Executable guardrails MUST mirror the same ownership shape:

- `guardrails/{domain}/{script-name}.sh`
- `guardrails/{domain}/{subdomain}/{script-name}.sh`

Every `guardrails/{domain}/` directory MUST include `README.md` with links to all guardrail scripts in that domain. Order entries by validation dependency: layout/inventory checks first, then semantic guardrails, then ratchet or snapshot checks. `README.md` is required instead of `INDEX.md` so directory viewers open the guardrail index automatically.

The domain and subdomain of a guardrail must match the spec ownership it protects.

## 3. Naming Rules

Use lowercase kebab-case for domains, subdomains, spec filenames, guardrail filenames, generated snapshot names, and media filenames.

Do not use dates, task numbers, PR numbers, branch names, implementation phases, or agent names in canonical spec paths. Canonical spec bodies should state current facts, stable contracts, ownership, and durable rationale; implementation history, retired alternatives, phase notes, and task/PR context belong in Git history instead of long-lived prose.

Specs use `.md`. Executable guardrails use `.sh`. Non-executable helper data must live next to the matching spec or guardrail with a clear kebab-case name.

## 4. Assets

Media for a domain spec lives under `specs/{domain}/assets/media/`.

Media for a subdomain spec lives under `specs/{domain}/{subdomain}/assets/media/`.

Name media by purpose, for example `handler-flow-diagram.svg`. Do not scatter spec-owned images under unrelated documentation folders.

## 5. Guardrail Requirements

Guardrail scripts must be deterministic, repo-root relative, safe for CI, and executable. Shell guardrails must start with:

```bash
#!/usr/bin/env bash
set -euo pipefail
```

Guardrails should print actionable failures and exit non-zero when the repository violates the protected contract. Inventory-only output is allowed, but it must be clearly labeled and must not hide failures.

## 6. Canonical Entry Rules

Root `SPECS.md` is the only top-level spec index. Root `specs/` is the only canonical spec tree. Root `guardrails/` is the only canonical guardrail tree.

Documentation entry points may link to specs, summarize them, or provide user guides, but they must not become a second canonical spec location. Repository guidance should point readers to root `SPECS.md` as the top-level spec index and to `specs/**/*.md` for long-lived domain contracts.