/ubiquitous-language

name: ubiquitous-language
description: |
  Maintain a project thesaurus (domain glossary) following DDD ubiquitous language
  principles. Use PROACTIVELY when naming anything: variables, functions, classes,
  modules, database fields, API endpoints, events, files, or directories. Also use
  when the user asks to "create thesaurus", "update glossary", "add term", "rename
  to match domain", "check naming consistency", "what should I call this", "domain
  language", "ubiquitous language", or "naming conventions". Ensures all names in
  the codebase are consistent, descriptive, and aligned with the shared domain
  vocabulary. Also mines git history to resolve naming ambiguities — when a name
  was born, which name replaced which, which spelling is dying. Not for general
  code style or linting — only for domain term consistency.
metadata:
  version: "2.1.0"
  thesaurus-format: "2.0"
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Glob
  - Bash
  - Agent
  - AskUserQuestion

Ubiquitous Language: Project Thesaurus Manager

You enforce naming consistency across the codebase by maintaining a living thesaurus of domain terms and consulting it every time something needs a name.

**Four modes:**

• **Naming consultation** (frequent) — everything in this file
• **Thesaurus generation** (rare) — read [references/generating-thesaurus.md](references/generating-thesaurus.md)
• **Naming audit** (periodic) — read [references/naming-audit.md](references/naming-audit.md)
• **History mining** (optional) — read [references/git-history-mining.md](references/git-history-mining.md)

when `## Unresolved` items need evidence: which name came first, which replaced which, which is dying. Offered after generation, or on demand against an existing thesaurus.

Foundations

This skill combines two bodies of knowledge:

• **Domain-Driven Design (DDD)** by Eric Evans — ubiquitous language, bounded contexts, aggregate naming
• **[First Principles Framework (FPF)](https://github.com/ailev/FPF/blob/main/FPF-Spec.md)** — a transdisciplinary "operating system for thought" that provides formal tools for semantic precision: bounded contexts as declared semantic frames, polysemy unpacking, lexical firewalls, cross-context bridges with loss notes, term continuity relations, and anti-explosion naming control. References like "FPF F.5" or "FPF A.1.1" point to specific sections of the FPF specification.

Core Principle

> "A project should use a single, shared vocabulary. Every name in code, docs, APIs, > and conversations must map to a term in the thesaurus. If a concept isn't in the > thesaurus — add it before naming anything." > > — Domain-Driven Design, Eric Evans

**The codebase is primary evidence, not automatic authority.** Use code to discover which terms are currently in circulation. Use the thesaurus and user input to decide which terms SHOULD be canonical.

• For **what exists today** — derive from code (classes, DB schemas, API routes, events)
• For **what should become the standard** — ask the user/domain expert
• If code contradicts the approved thesaurus — the thesaurus wins for new code
• If the user says "fix legacy naming" — the user's directive overrides the codebase;

map existing code names to `## Legacy` lines and use the user's terms as canonical

**Tacit knowledge**: For areas not yet implemented, the most important domain knowledge exists only in experts' heads, not in any artifact.

Thesaurus File

**Locating the thesaurus:** 1. If the user specified a path — use it 2. If `THESAURUS.md` already exists somewhere in the repo — use that location 3. Default: `docs/THESAURUS.md`

Single source of truth for domain vocabulary.

Versioning

The thesaurus declares its **format version** and the skill that maintains it in YAML frontmatter — machine-readable, outside the body, still one grep away:

---
thesaurus-format: "2.0"
skill: ubiquitous-language
---

# Project Thesaurus

Quote the version — unquoted `2.10` is the YAML float `2.1`.

• `rg -n '^thesaurus-format:' THESAURUS.md` → the version in one hit. **No key = 1.0**

(the pre-index prose layout shipped before skill 2.0) — unless the file already has ``- **Term** `Id` kind: `` Index lines: that is an unstamped 2.0 file from plugin 9.2.0; just add the stamp.

• Format major = skill major (`metadata.version` in this file's frontmatter). Skill

minor/patch releases never change the format.

• **Read** any format ≤ your own; **write** only the current one. A major gap means

migration first (see generating-thesaurus.md); a minor gap means new optional tokens — older readers keep working, you may add the tokens as you touch lines.

• A thesaurus with a format **newer** than yours: read it, don't rewrite it — tell the user

to update the skill.

• Only the format is versioned in the file. The skill's own version is not recorded there —

it would go stale on every edit and `git log` already answers "who wrote this". `skill:` is a pointer, so an agent without the skill knows what to install.

| Format | Layout | Skill | |--------|--------|-------| | 1.0 | `### Term` entries with `Synonyms to AVOID`; `## Legacy Terms` entries; `## Forbidden Lexicon` table | ≤ 1.x (plugin ≤ 9.1.1) | | 2.0 | grep-first: `## Index` lines with `kind:`/`ctx:`/`avoid:`, `use:` Forbidden lines, `→` Legacy lines, SKOS bridges | 2.x |

Layout: grep-first

The file is designed so that **one `rg`/`grep` for any name answers "what do I do with this name?"** without reading the surrounding text. Five sections, fixed order:

| Section | Shape | One line answers | |---------|-------|------------------| | `## Index` | one line per concept | "Is there a term for this? Which name is canonical? What is banned?" | | `## Terms` | `### Term` entries | "What exactly does it mean / not mean / relate to?" | | `## Forbidden` | one line per word | "Is this word banned from domain names?" | | `## Legacy` | one line per old name | "This old name is in t