glossary git:20261010.c6c87e0A

Immutable. This exact content never changes and is served at /api/v1/blob/6d1e03a7a8157b11.

---
name: glossary
description: >-
  Writes the ubiquitous language of a bounded context, before any code, and keeps its
  CONTEXT.md, the per-context document every agent reads first. One row per term with its
  meaning here and what it must not be confused with. Use when a business term is missing,
  ambiguous or used with two meanings, when the generator or language/glossary-term refuses
  a name, when a CONTEXT.md is empty or stale, or as the glossary step of a new project.
  For the boundary itself use bounded-contexts.
argument-hint: "[context]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(npx ddd-ts-kit list *)
  - Bash(npx ddd-ts-kit docs)
  - Bash(npx ddd-ts-kit check *)
---

# Ubiquitous language

Context: `$ARGUMENTS` (every context of `docs/architecture/contexts.md` when empty)

The glossary is the source of every class, method, event, command and permission name. The
generator refuses a name whose words it does not define, and `language/glossary-term` fails
the check.

## Where it is written

| Project state | File |
|---|---|
| before the bootstrap | `docs/architecture/glossary.md`, one section per context; the bootstrap turns each row into a `--term` and deletes the file |
| after | `src/contexts/<context>/CONTEXT.md`, section `## Ubiquitous language`; there is no second copy |

## Collect the terms

From the discovery timeline (or from the owner), for one context at a time:

- each **noun** the business uses: candidates for aggregates, entities, value objects;
- each **verb**: candidates for commands and intention methods (`place`, `cancel`, `issue`);
- each **fact**, in the past tense: candidates for events (`placed`, `cancelled`);
- each **role** that acts.

For each, one sentence of meaning **in this context**, and for a word a neighbour also uses,
what it must not be confused with there. Refuse technical words (`record`, `data`, `item`,
`manager`, `info`, `status` alone) and ask for the business word. One word per concept: pick
`cancel` or `void`, not both. Ten precise terms beat fifty vague ones.

```markdown
## ordering
| Term | Meaning | Not to be confused with |
|---|---|---|
| Order | A customer's request to buy products, from placement to delivery | billing: Invoice, the debt it creates |
| Place | To submit an order for fulfilment; it cannot be edited afterwards | |
```

## After the bootstrap: `CONTEXT.md`

It is what an agent reads instead of the code of the context. Keep it true and short.

| Section | Written by | Content |
|---|---|---|
| `## Purpose` | you | two sentences in business terms; the first one feeds the context map |
| `## Classification` | you | the classification and one sentence of why |
| `## Ubiquitous language` | you | the table above |
| `## Aggregates`, `## Published events`, `## Permissions`, `## Scheduled jobs`, `## Relationships` | `npx ddd-ts-kit docs`, between markers | never edit between the markers; add below a list one line per aggregate with the invariant it guards |

A new term enters with the code that needs it:
`npx ddd-ts-kit generate <kind> ... --term "<Term>=<meaning>"` adds the row in the same
command. Fill "Not to be confused with" by hand, for homonyms only. Finish with
`npx ddd-ts-kit check --rule tree/context-doc --rule language/glossary-term`.

## Done when

Put this to the owner: **would a domain expert sign each definition, and does every word of
the timeline have exactly one meaning per context?** On a yes, the next step is
`ddd-ts-kit:context-map`.