# Glossary convention

A project's glossary pins canonical nomenclature so terminology does
not drift over time, and so that LLM-driven work reuses the
established term for a concept instead of coining a fresh synonym each
session. This file owns the format, the reading obligation, and the
write discipline; an individual project's glossary is an instance of
this convention.

## Where it lives

A project opts in by naming a glossary path in its CLAUDE.md project
facts (see `conventions.md`). When it is named, the file it points to
is standing reading for every role — no separate standing-reading entry
is required. When the project names none, the whole feature is a
documented no-op.

A glossary is the source of truth for the project's nomenclature.
Where any other document names a concept differently — including the
fixed vocabulary in `conventions.md` (cycle / iteration / milestone /
contract) — the glossary's canonical entry, and its **Avoid** list,
win.

## Format

The glossary is a flat list of per-term blocks (not a table), so an
appended entry produces a clean line-wise diff. Each block has exactly
three fields:

1. a level-3 heading naming the **canonical term** to use;
2. an **Avoid:** line listing known synonyms that must NOT be used;
3. a definition of at most two sentences.

```
### canonical-term
**Avoid:** synonym-one, synonym-two
A definition of at most two sentences.
```

A term with no known synonyms still carries an `**Avoid:** —` line so
every block has the same three-field shape.

## Reading obligation

Every skill and agent reads the glossary as part of its standing
reading and, when producing prose or naming a concept, uses the
canonical term and avoids the listed synonyms. If a concept is not
listed, reuse the closest existing term — do not silently coin a new
one.

## Extending the glossary (user + boss only)

The user may edit the glossary at any time. In a `/boss` session the
orchestrator may extend it autonomously — but only to **record
reality, never to invent**:

- A term already used consistently across shipped artefacts but not
  yet listed → add it, with its known synonyms under **Avoid**.
- A drift the orchestrator just resolved (two terms for one concept)
  → record the winner as the canonical entry, the loser under
  **Avoid**.

The orchestrator never coins a brand-new term into the glossary: a
term earns its entry by already being in consistent use. All other
skills and agents are read-only consumers of the glossary.

The `glossary` skill (`../glossary/SKILL.md`) is the executable procedure
for building and extending a glossary under these rules: this file stays
the rules, the skill applies them.