# Domain Modeling > Use when designing a product or feature and the project lacks shared, agreed terminology - builds and maintains a pure domain glossary so agents speak one language - **Type:** Skill - **Install:** `agentstack add skill-etr-groundwork-domain-modeling` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [etr](https://agentstack.voostack.com/s/etr) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [etr](https://github.com/etr) - **Source:** https://github.com/etr/groundwork/tree/main/skills/domain-modeling ## Install ```sh agentstack add skill-etr-groundwork-domain-modeling ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Domain Modeling ## Overview A project's agents are verbose and misaligned when they lack a shared language: the same concept gets three names, one name covers three concepts, and every prompt re-explains what a term means. A tight glossary fixes this — it collapses ambiguity and tokens at once. **Core principle:** the glossary is **terminology only**. One authoritative definition per term, and nothing else. It is never a spec, never an architecture doc, never a scratchpad. The moment an entry carries implementation detail or a design decision, it stops being a glossary and starts rotting. The glossary lives at `{{specs_dir}}/glossary.md`. ## When to Use - Defining a product or feature and a term keeps getting used loosely or two ways ([[design-product]], [[understanding-feature-requests]]) - Architecture work surfaces concepts the team has no agreed name for ([[design-architecture]]) - You catch yourself re-explaining the same concept across prompts or docs ## Lazy Creation `{{specs_dir}}/glossary.md` does not exist until the **first term resolves**. Do not scaffold an empty file or a placeholder. An empty glossary is sediment; create the file when you have a real first entry, not before. ## Process Capture terms **inline, as they crystallize** during design and requirements work — never in a batch at the end. Batching loses the context that made the term precise. 1. **Capture on crystallization.** A concept earns an entry the moment it has a stable, agreed meaning. Write it immediately, in the format below. Do not wait for a "glossary pass." 2. **Challenge vague or conflicting language on the spot.** When usage drifts, name it: *"Your glossary defines X as A, but you're using it as B — which is it?"* Resolve to one definition; update the entry or the usage, never both meanings. 3. **Stress-test relationships with concrete edge cases.** Walk a real scenario at the boundary — empty, zero, expired, two-at-once — and check the definition and its links still hold. If the scenario breaks the entry, the term was underspecified; tighten it. 4. **Cross-check terms against the code.** Surface contradictions where the code's structures and names disagree with the agreed term. A glossary that contradicts the codebase is worse than none — reconcile the name, the definition, or the code. Follow the entry format in the sibling. See `CONTEXT-FORMAT.md`. ### Glossary vs. decision A glossary entry records *what a word means*, not *why a path was chosen*. When resolving a term forces a real architectural trade-off, that's a decision record (see the **decision-record gate** in `${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md`), not a glossary entry. Record it in the architecture doc via [[design-architecture]] and link the term to it. Do not narrate the decision inside the definition. ## Rationalizations | Excuse | Reality | |--------|---------| | "I'll add the schema/endpoint so it's all in one place" | That makes it a spec. The glossary holds meaning only; implementation rots the entry out of sync. | | "I'll collect all the terms at the end in one pass" | The precision came from the context you had when the term crystallized. Batching loses it. | | "Both teams use the word slightly differently — I'll note both" | Two meanings is the bug, not the entry. One authoritative definition; redirect the rest. | | "I'll explain *why* we defined it this way here" | Rationale belongs in the architecture decision record, not the glossary. The definition states what, not why. | | "Let me stub an empty glossary so it exists" | Empty file = sediment. Create on the first resolved term. | ## Red Flags - An entry contains a table name, function signature, file path, or library choice - The same concept has two entries under different names - One entry's definition contradicts how the code names or structures the thing - You're writing the glossary in a single batch after design is "done" - An entry argues *why* a choice was made instead of stating what the term means - A placeholder or empty `glossary.md` committed before any term resolved ## Verification - [ ] `glossary.md` exists only because at least one term has resolved; no placeholder entries - [ ] Every entry follows `CONTEXT-FORMAT.md` (Term, Definition, Relationships, Edge cases; alphabetical) - [ ] No entry contains implementation detail or decision rationale - [ ] Each concept appears exactly once; no synonym has its own definition - [ ] Every term was stress-tested against at least one concrete edge-case scenario - [ ] Terms checked against the code; no name or meaning contradicts the codebase - [ ] Any trade-off uncovered while resolving a term is recorded as an architecture decision (see [[design-architecture]]), not inside the definition ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [etr](https://github.com/etr) - **Source:** [etr/groundwork](https://github.com/etr/groundwork) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-etr-groundwork-domain-modeling - Seller: https://agentstack.voostack.com/s/etr - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.