ubiquitous-language

Enforces one glossary-driven ubiquitous language per bounded context through a five-step decision protocol.

Updated May 18, 2024
One-click install
npx skills add https://github.com/joshhornby/dotfiles --skill ubiquitous-language-joshhornby
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ubiquitous-language
Source: https://github.com/joshhornby/dotfiles/tree/main/.claude/skills/ubiquitous-language
Command: npx skills add https://github.com/joshhornby/dotfiles --skill ubiquitous-language-joshhornby

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Domain terminology drifts silently in codebases: synonyms multiply, near-duplicate identifiers appear, and names change mid-feature without any recorded decision. This Skill makes a repository-declared glossary the naming authority for each bounded context and forces every new, changed, or suspect domain term through an explicit detect-propose-decide-record-rename protocol. ## Core Features & Use Cases - Five-step language protocol: Detect missing or duplicated terms, propose them to a human with a recommendation, record approved terms in the glossary, and rename code, tests, and schemas together in one reviewable change. - Glossary format guidance: Bootstrap a glossary from greenfield conversations or brownfield code, with context-scoped aliases, deprecation records, and an optional Contextive YAML example. - Mechanical enforcement design: Define glossary-driven lint ratchets for identifiers, test titles, and DSL verbs, with positive-control fixtures proving forbidden vocabulary is caught. - Use Case: While building a payments feature you need a verb for a customer leaving checkout. The Skill stops you from silently coining cancelCheckout, walks you through proposing abandonCheckout with a definition and example, and records it in the ordering context glossary alongside the code change. ## Quick Start Ask the agent to check whether the domain term you are about to use exists in the project's glossary and to run the language protocol if it does not.

Frequently Asked Questions about ubiquitous-language

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enforce a ubiquitous language in a DDD codebase?

Declare one glossary per bounded context as the naming authority, then route every new or changed domain term through a five-step protocol: detect, propose to a human, decide, record in the glossary, and rename code and tests together. Optionally add glossary-driven lint rules for identifiers and test titles.

How do I bootstrap a domain glossary for an existing project?

Harvest candidate terms from domain identifiers, event names, database entities, comments, and tests, treating existing code as evidence rather than authority. Admit terms through the proposal protocol as work slices touch them, so the glossary grows with the protected capability instead of ahead of it.

Can I use Contextive glossary files with this approach?

Yes, Contextive's YAML glossary format is one supported example, providing folder scoping and editor hover support. Deprecated terms become aliases on the canonical term, with a lint convention layered on top that rejects the alias and names its replacement.

When should a rename use a decision record instead of just a glossary update?

Use the repository's decision-record mechanism when the rename changes the model's meaning, not just a label. Routine additions and label-only changes need only the glossary diff riding the same reviewable change as the code.

What are the limits of glossary-driven lint enforcement?

Lint rules are scoped ratchets, not whole-repository proof: they cover configured paths and token classes only. Until a mechanical gate is installed, everything is convention, and green results must be reported with their configured scope rather than as full language compliance.