dsl— plugin

<p align="center"> <img src="docs/hero.svg" alt="dsl — Domain-Shared Lexicon: the words you and the AI already share, written down once and loaded every session" width="900"> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-4d8759" alt="Apache-2.0"></a> <img src="https://img.shields.io/badge/Claude%20Code-skill-37708f" alt="Claude Code skill"> <img src="https://img.shields.io/badge/scope-vocabulary%20only-bf7d2a" alt="Vocabulary only"> <a href="https://github.com/p-vbordei/cubemap"><img src="https://img.shields.io/badge/companion-cubemap-6a5a8c" alt="companion: cubemap"></a> </p>

<p align="center"><i>A Claude Code skill that gives the AI the vocabulary you and your team<br>already speak — and keeps it from quietly meaning something else.</i></p>

Why this exists

A conversation rarely breaks on a hard word. It breaks on an easy one that means two different things.

You say "the heat tapped late" and you mean a furnace batch was drained behind schedule. The AI hears a temperature reading that arrived late. Nobody corrects it, because nobody noticed — and three turns later the furnace logic is wearing the shape of a charting library. The drift compounds: code uses one name, comments another, you a third, the AI a fourth.

dsl does one thing about that. It builds and maintains a shared glossary — Term · Definition · Aliases to avoid — and loads it into the AI's context so the two of you mean the same thing every time. It does not write PRDs, draft ADRs, run design reviews, refactor your code, or grill your plans. There are good skills for those; this isn't trying to be one.

<p align="center"> <img src="docs/align.svg" alt="The same sentence splits into two meanings without a lexicon — what the user means versus what the AI hears — and collapses into one shared meaning with LEXICON.md" width="900"> </p>

The idea in one minute

• One source of truth for meaning. A LEXICON.md of Term | Definition | Aliases to avoid tables, the relationships between terms, the ambiguities you've already tripped on, and one example dialogue that shows the words used precisely.
• It loads itself. Wired into CLAUDE.md once, the lexicon enters context at the start of every session in that repo — including the fresh session you'll open three weeks from now.
• It stays in its lane. Vocabulary only. The moment a definition starts describing how a feature works, it's drifted out of scope and belongs elsewhere.
• Every write is confirmed. No flow ever creates or edits LEXICON.md or CLAUDE.md silently — you see the proposed content first, always.

Three ways it runs

<p align="center"> <img src="docs/modes.svg" alt="Three ways the skill runs: on demand via commands, proactively flagging ambiguity in one line, and automatically loading at session start" width="900"> </p>

• On demand — you run /dsl-init, /dsl-update, or /dsl-ingest and the skill walks the flow (interview, ingest, or scan).
• Proactive — mid-task, the AI notices one word being used in two senses (or a domain term it genuinely can't define), raises it in a single line, and drops it if you don't bite. It never derails what you're doing.
• At session start — it reads ./LEXICON.md if present, matches your global domains against the current project, and loads only the ones that fit.

Two scopes, one matching guarantee

A project lexicon (./LEXICON.md) applies to one repo, unconditionally. A global lexicon (~/.claude/LEXICON.md) holds the domains you work in across all your projects — and here's the part that matters: it is not one big bag dumped into every session. It's a stack of per-domain sections, each declaring Applies when: signals, and the AI loads only the domains the current project actually matches.

<p align="center"> <img src="docs/scopes.svg" alt="The project lexicon always applies; global domains load only on a strong signal — matching deps or two-plus README keywords — never on a lone filename" width="900"> </p>

Strong signals load a domain. Weak ones don't. A named dependency that matches (e.g. pyfoundry in your pyproject.toml), two or more keyword hits in the README, or an explicit domain: <name> line in the project — those load the domain. A single matching filename is a weak signal and is ignored on its own. Loading smelting vocabulary into a recipe side project is worse than loading nothing, so when in doubt the skill loads nothing. You can always force-attach a domain with /dsl-init.

Project always wins. If a term is defined in both the project and a matching global domain, the project definition takes precedence — and the AI says so, once.

Why another glossary skill?

Several similar skills exist — grill-me, grill-with-docs, the original DDD ubiquitous-language. They informed this one. The differences:

Want a plan-stress-test session? Use grill-me. Want a full domain model with architecture decisions? Use Matt Pocock's grill-with-docs. Just want the AI and you to mean the same thing when you say Heat, Order, or Cluster? That's this.

Pairs with [`cubemap`](https://github.com/p-vbordei/cubemap) — a companion skill for mapping a business from boardroom to code. cubemap discovers the client's vocabulary as it maps; dsl stores and reloads it. Use the two together.

Install

This repo ships skill and command files. Installation is a copy step plus a one-time CLAUDE.md edit.

1. Clone the source

git clone https://github.com/p-vbordei/dsl.git ~/src/dsl

2. Copy the skill and commands into your Claude config

mkdir -p ~/.claude/skills/dsl ~/.claude/commands
cp ~/src/dsl/skills/dsl/SKILL.md   ~/.claude/skills/dsl/SKILL.md
cp ~/src/dsl/commands/dsl-init.md   ~/.claude/commands/dsl-init.md
cp ~/src/dsl/commands/dsl-update.md ~/.claude/commands/dsl-update.md
cp ~/src/dsl/commands/dsl-ingest.md ~/.claude/commands/dsl-ingest.md

3. Wire CLAUDE.md

For a per-project lexicon, append the snippet from templates/claude-md-snippet-project.md to that project's ./CLAUDE.md. (Strip the leading HTML comment when you paste.)

For a global lexicon, append the snippet from templates/claude-md-snippet-global.md to ~/.claude/CLAUDE.md. (Same — strip the HTML comment.)

You don't have to do step 3 by hand — running /dsl-init offers to do it for you and shows you the snippet before writing.

4. Restart Claude Code

New skills and commands are picked up on the next session. Start a fresh session in any repo and run /dsl-init.

First time installing a Claude Code skill? Skills live in ~/.claude/skills/<name>/SKILL.md and are auto-discovered. Slash commands live in ~/.claude/commands/<name>.md. No registration needed beyond placing the files.

Quickstart

You:    /dsl-init
Claude: Scope? [project] / [global-new-domain] / [global-add-to-existing]
You:    project
Claude: Source? [interview] / [ingest] / [scan] / [hybrid]
You:    scan
Claude: I read README.md and the directory tree. Candidates: Heat, Tap,
        Charge, Slag, Ingot, Ferroalloy. Heat — your README implies "one
        furnace batch". Confirm?
You:    yes
… (a few more)
Claude: About to write ./LEXICON.md with 6 terms in 1 domain, and append a
        block to ./CLAUDE.md. Show diff? (y/n)
You:    y
…
You:    proceed
Claude: Wrote ./LEXICON.md: 6 terms in 1 domain. CLAUDE.md updated.

From here on, the AI reads the lexicon at every session start in this repo and uses your terms instead of inventing its own.

The lexicon format

Tight, opinionated, small enough to actually fit in context. From templates/lexicon-template.md:

## Domain: <name>           # only for the global file

**Applies when:**            # only for the global file
- Project deps include: ...
- README mentions any of: ...
- File extensions present: ...
- Explicit override: a line `domain: <name>` in project CLAUDE.md

### <subgroup>

| Term | Definition | Aliases to avoid |
|------|------------|-------------------|
| **Heat** | One batch of molten metal produced in one furnace cycle. | run, batch, melt |
| **Tap** | The act of opening a furnace to drain a **Heat**. | drain, pour |

### Relationships

- A **Charge** produces one **Heat** per furnace cycle.

### Flagged ambiguities

- `pour` was used for both **Tap** and accidental spill — a spill is a `breakout`.

### Example dialogue

> **User:** What's the carbon target on the next **Heat**?
> **Domain expert:** Under 0.15% — heavy on scrap, light on coke.

Project lexicons drop the ## Domain: wrapper — every term applies. See templates/example-lexicon.md for a full two-domain example.

Commands

What this skill does not do

• Generate ADRs, PRDs, design docs, or feature specs
• Refactor code or rename identifiers
• Run plan-grilling sessions
• Document the codebase ("here's how the auth system works")
• Replace CLAUDE.md itself — it appends a small snippet that references the lexicon

If you find yourself reaching for one of those, you want a different skill.

License

Apache License 2.0 — Vlad Bordei <[email protected]>