# Roll — Conventions & AGENTS.md

Roll's convention system gives every AI agent the same shared understanding of
your project — its domain, coding standards, and navigation pointers.

## AGENTS.md

`AGENTS.md` is the primary convention file. It defines:

- **Domain model**: bounded contexts, aggregates, key entities
- **Coding standards**: language idioms, naming, forbidden patterns
- **Scope rules**: which files an agent is allowed to touch
- **Where to Look**: named pointers to key docs and directories
- **Goal-Driven Execution**: instructions for agents to define verifiable goals before acting

Roll writes an `AGENTS.md` skeleton during `roll init`. You fill in the domain
model and standards that are specific to your project.

## Goal-Driven Execution Rule

Every agent must define a verifiable goal before starting work:

```
Verifiable Goal: <one sentence that can be confirmed true or false>
Success Criteria: <measurable outcomes>
```

This prevents vague execution ("refactor the auth module") and forces the agent
to state what "done" looks like. Roll's skills enforce this at the start of each
story.

## Where to Look

The `AGENTS.md` navigation section maps concept names to file paths. Roll 2.0
consolidates everything Roll touches under `.roll/`, so navigation is anchored
there:

```markdown
## Where to Look

| Concept | Location |
|---------|----------|
| Backlog index | `.roll/backlog.md` |
| Feature specs | `.roll/features/<name>.md` |
| Domain model | `.roll/domain/context-map.md` |
| Architecture decisions | `.roll/decisions/` |
| Autonomous output (briefs, dream) | `.roll/briefs/`, `.roll/dream/` |
| User guides | `guide/en/`, `guide/zh/` |
| Test helpers | `tests/unit/helpers.bash` |
```

The contract: `AGENTS.md` lives at the project root (every AI client reads it
first); everything it points into lives under `.roll/`. The root stays clean,
and the navigation table is the single map agents need.

`$roll-design` maintains this table as new docs and directories are added.
Any agent entering the project can navigate to authoritative sources without
scanning the whole tree.

## Language Surface Policy

Roll separates the contract language from rendered user language:

- Agent contracts, TypeScript code, git metadata, schemas, and stable keys stay
  in English.
- Owner conversation follows the owner's language in the current task.
- CLI output, help, docs, and HTML pages render one visible language at a time,
  selected by `ROLL_LANG`, `roll config lang`, `roll help --lang`, or locale
  detection.

Write user documentation in the matching locale file under `guide/en/` or
`guide/zh/`. For CLI and generated HTML, add or update i18n catalog entries
instead of putting translation pairs into one output string. Run
`roll doctor language` before release when conventions, help, docs, or generated
surfaces changed. The policy is covered by
`packages/cli/test/cli-language-surface.test.ts`,
`packages/cli/test/__snapshots__/cli-language-surface.test.ts.snap`, and
`packages/cli/test/doctor-language.test.ts`.

## Existing Codebases: `$roll-onboard` and `$roll-doc-audit`

For an existing codebase with no `.roll/` yet, the entry point is
`$roll-onboard` (the **graft** adoption pattern). It scans the code, asks a
focused set of cognition / scope / privacy questions, and writes
`.roll/onboard-plan.yaml` as a reviewable contract. After review,
`roll init --apply` prints the planned operation checkpoint and waits for
confirmation before turning that plan into the on-disk structure; non-interactive
automation must use `roll init --apply --auto` — see
[legacy-onboarding.md](legacy-onboarding.md) and
[patterns/](patterns/README.md).

For projects that already have `AGENTS.md` but scattered or stale docs:

```bash
$roll-doc-audit
```

`roll-doc-audit` checks README, guides, site pages, CLI help, and docs against
implemented behavior. When inventory is requested, it infers domain structure
from existing code, refreshes the `Where to Look` navigation table, and flags
documentation gaps (missing architecture docs, undocumented public APIs) for
`$roll-build` to fill.

## Global Conventions

Files in `~/.roll/conventions/global/` are synced into every AI tool's config
directory by `roll setup` and `roll sync`. Changes to global conventions
propagate to all projects on your next sync.

## See Also

- [project-setup.md](project-setup.md) — `roll init` creates AGENTS.md
- [overview.md](overview.md) — three-layer model (human / BACKLOG / autonomous)