RonanCodes/ubiquitous-language

Ubiquitous Language

Build and maintain a glossary of domain terms so the team (and Claude) uses consistent language across code, docs, and conversation.

Usage

/ubiquitous-language --scan          # Scan codebase, build/update GLOSSARY.md
/ubiquitous-language --check         # Audit codebase for inconsistent terminology
/ubiquitous-language --add <term>    # Add a new term interactively

Default (no flag): run --scan.

--scan: Build/Update the Glossary

1. Read project context — scan these files (skip any that don't exist):

   • CLAUDE.md, README.md, package.json / Cargo.toml / go.mod
   • **/types.ts, **/models/**, **/schema*, **/domain/**
   • **/entities/**, **/interfaces/**, **/*.graphql, **/*.proto
   • Existing GLOSSARY.md (to preserve manually added terms)

2. Extract domain terms — look for:

   • Nouns in type/interface/class/struct names (PascalCase -> split into words)
   • Enum values that represent domain concepts
   • Terms defined or explained in README/CLAUDE.md
   • Recurring nouns in comments and docstrings
   • Terms already in GLOSSARY.md marked [manual]

3. Deduplicate and define — for each term:

   • Write a one-sentence definition based on how the codebase uses it
   • Identify aliases/synonyms to avoid (e.g., "user" vs "account" vs "member")
   • Note which files/modules use the term

4. Write GLOSSARY.md at project root using the format below.

5. Present a summary — show how many terms were found, any new terms added since last scan, and any suspected inconsistencies.

--check: Audit Consistency

1. Read GLOSSARY.md — if it doesn't exist, tell the user to run --scan first.

2. For each term that has Aliases to Avoid, search the codebase for those aliases:

   • Search file names, variable names, comments, docs
   • Ignore vendored/generated code (node_modules, dist, build, .git)

3. Report findings as a table:

| File | Line | Found | Should Be |
|------|------|-------|-----------|
| src/api.ts | 42 | `account` | `user` (per glossary) |

4. Ask the user if they want to fix any of the flagged inconsistencies.

--add: Add a Term

Use AskUserQuestion for each:

1. Term — the canonical name (use the argument if provided)
2. Definition — one-sentence description
3. Aliases to Avoid — synonyms the team should NOT use (comma-separated, or "none")
4. Used In — key files/modules, or "project-wide"

Append to GLOSSARY.md (create it if missing). Mark as [manual] so --scan preserves it.

GLOSSARY.md Format

# Ubiquitous Language

> Domain glossary for this project. Auto-generated by `/ubiquitous-language`.
> Terms marked `[manual]` were added by hand and are preserved across scans.

| Term | Definition | Aliases to Avoid | Used In |
|------|-----------|-----------------|---------|
| Vault | A self-contained wiki with its own git repo | repository, folder, workspace | `vaults/`, CLAUDE.md |
| Ingest | Import and process a source into wiki pages | import, add, fetch | `.claude/skills/ingest/` |
| Story `[manual]` | A vertical slice of work in a PRD | task, ticket, issue | `.ralph/prd.json` |

Rules

• One canonical term per concept. If two words mean the same thing, pick one and list the other as an alias.
• Definitions describe usage, not dictionary meaning. "Vault" means what it means in THIS project.
• Keep it flat. No sub-glossaries, no hierarchy. One table, alphabetically sorted.
• Preserve [manual] terms. Never remove or overwrite terms tagged [manual] during a scan.
• Skip generic programming terms. Don't include "function", "array", "string", etc. Only domain-specific terms.