ad-domain

<background_information> Implements ADR-0019 — Layer 2 of the artifact stack. Lazy lifecycle owner of CONTEXT.md. Process scaffold for capturing the project's ubiquitous language.

The skill owns capture of vocabulary. The trigger for most updates lives in adjacent skills:

• ad-grill-me resolves a term during interview → routes here.
• ad-spec introduces a new noun while drafting a spec → routes here.
• ad-architecture names a domain-bound concept → routes here.
• ad-drift detects code/glossary drift → routes here.
• Direct /ad-domain invocation when the user wants to add a term explicitly.

Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user mentions a domain term, ubiquitous language, glossary, or naming drift, invoke this skill manually. </background_information>

1. Read CONTEXT.md at the repo root. If present → single-context repo; updates land here.
2. Read CONTEXT-MAP.md at the repo root. If present → multi-context repo; updates land in the per-context CONTEXT.md named by the map.
3. Neither present → no CONTEXT.md exists yet. Decide:
   • Single-context (default): plan to create CONTEXT.md at the repo root.
   • Multi-context: only declare this when the user has explicitly named ≥2 bounded contexts. Plan to create CONTEXT-MAP.md plus the relevant per-context file.

Lazy-creation rule: do not create the file just because the skill was invoked. Create it only when there is at least one resolved term to write.

Step 1 — resolve the term. A glossary entry has four parts:

### <Canonical Noun>

**Definition:** <one-sentence, project-specific, no general programming words>.

_Avoid_: <Alias 1>, <Alias 2>. <Why each is misleading>.

**Related code:** [`path/to/file.ts:42`](path/to/file.ts:42).

Resolution discipline:

• Be opinionated. One canonical name. Others become _Avoid_ aliases with a one-line reason.
• One-sentence definitions. If it takes a paragraph, the term is not yet sharp.
• Project-specific only. "Customer", "Triage role", "Materialization cascade" qualify. "Service", "Handler", "Controller" do not (those belong to architectural vocabulary per ADR-0020, not domain).
• Flag conflicts. If two terms could mean the same thing, add the conflict to the Flagged ambiguities section instead of forcing a premature resolution.

Step 2 — locate the insertion point. CONTEXT.md has three canonical sections:

# <Project Name> — Domain Glossary

## Language

<term entries here, one per `### <Term>` heading>

## Relationships

- A **Customer** has many **Orders**.
- An **Order** belongs to one **Customer** and contains one or more **LineItems**.

## Flagged ambiguities

- "Account" vs "User" — see Issue #42; treated interchangeably in code today, separation pending ADR-NNNN.

Insert the new term alphabetically under ## Language. If a relationship clause is implied, append to ## Relationships. If the resolution surfaces an ambiguity rather than closing one, append to ## Flagged ambiguities and mark the term entry "(resolution pending)".

Step 3 — write or update. First creation uses Write; subsequent updates use Edit. Preserve existing entries — never reorder or rewrite past terms while adding new ones.

For first creation, the file shape is:

# <Project Name> — Domain Glossary

_Lazy artifact — only contains terms that have been resolved through grilling, spec drafting, or explicit capture. Empty entries are worse than no entry; speculation belongs elsewhere._

_Maintained by `/ad-domain`._

## Language

### <First resolved term>

...

## Relationships

(empty until the second term resolves)

## Flagged ambiguities

(empty)

For multi-context repos, CONTEXT-MAP.md is the index:

# Context Map

This repository contains multiple bounded contexts. Each has its own `CONTEXT.md`.

- **Ordering** — `src/ordering/CONTEXT.md`. Owns: Customer, Order, LineItem, Cancellation.
- **Billing** — `src/billing/CONTEXT.md`. Owns: Invoice, Payment, Refund.

System-wide ADRs live at `doc/adr/`. Context-scoped ADRs live under each context.