Implement dsl: Project glossary and domain language management

[vredchenko]

Summary

The `dsl` plugin maintains a project-specific glossary of terminology and domain vocabulary. Despite its name, this is not about creating domain-specific languages — it's about ensuring Claude (and developers) use consistent, correct terminology. This is valuable because Claude often uses generic or incorrect terms for domain-specific concepts, leading to confusing code and documentation.

Note: The plugin name `dsl` is inherited from the original stub. Consider updating the description in `marketplace.json` from "Domain-Specific Language utilities" to "Project glossary and domain language management" to better reflect its purpose.

Original Intent

Maintain a vocabulary of project-specific terminology with definitions, keep it updated and configure Claude Code to reference it and be aware when these terms are used as to their meaning.

Commands

`/dsl:init` (new — current only has placeholder)

Purpose: Initialize a project glossary.

Behavior:

1. Create glossary file at `docs/glossary.md` (or `.claude/glossary.md`):
   ```markdown

   Project Glossary

   Domain-specific terminology for this project. Claude Code references this
   glossary to ensure consistent use of terms in code, docs, and communication.

   Terms

   Term	Definition	Also Known As	Context
   Tenant	An organization-level account that contains multiple users	Account, Org	Multi-tenant SaaS
   Workspace	A collaborative space within a tenant	Project, Team	—
   Pipeline	A sequence of data transformation steps	Flow, Chain	Data processing
   ```

2. Bootstrap with auto-detected terms:

   • Scan code for frequently used domain nouns (class names, type names, enum values)
   • Scan README and docs for defined terms
   • Identify acronyms used in the codebase
   • Present candidates and ask user to define/confirm each

3. Add glossary reference to CLAUDE.md (or create if not exists):
   ```markdown

   Glossary

   See docs/glossary.md for project-specific terminology.
   Always use the defined terms consistently in code, comments, and docs.
   ```

4. Output: glossary file created + number of terms bootstrapped

Edge cases:

• Glossary already exists → offer to merge new terms
• No CLAUDE.md → ask if user wants to create one
• Very large codebase → limit term detection to top-level modules

`/dsl:add` (new)

Purpose: Add a new term to the glossary.

Behavior:

1. Ask user for:
   • Term (required): the canonical name
   • Definition (required): one-sentence explanation
   • Also Known As (optional): aliases, abbreviations, common misspellings
   • Context (optional): when/where this term is used
   • Do NOT confuse with (optional): similar but different terms
2. Check for conflicts:
   • Term already exists → offer to update definition
   • Similar term exists (fuzzy match) → ask if it's the same or different
3. Add to glossary table in alphabetical order
4. Scan codebase for inconsistent usage:
   • If "Also Known As" terms appear in code → report locations where the alias is used instead of the canonical term
     ```
     Found inconsistent usage:
     src/api/routes.ts:15 — uses "Account" instead of "Tenant"
     src/models/user.ts:42 — uses "Org" instead of "Tenant"
     ```
5. Offer to rename for consistency (but don't auto-rename without confirmation)
6. Output: term added + any inconsistencies found

Edge cases:

• Multiple glossary files (monorepo) → ask which one
• Term is an acronym → add expanded form as "Also Known As"

`/dsl:check` (new)

Purpose: Check codebase for glossary compliance — find inconsistent terminology.

Behavior:

1. Read glossary file

2. For each term with "Also Known As" entries:

   • Search codebase for alias usage (in code, comments, docs, variable names)
   • Report instances where aliases are used instead of canonical terms

3. For each term with "Do NOT confuse with" entries:

   • Check if confused terms are used in the same context

4. Check for undefined jargon:

   • Find capitalized multi-word phrases or acronyms in code/docs that aren't in the glossary
   • Present as candidates for addition

5. Output report:
   ```
   Glossary Compliance Check

   Inconsistent Terminology:
   ⚠ "Account" used instead of "Tenant" in 3 files:

   • src/api/routes.ts:15
   • src/models/user.ts:42
   • docs/architecture.md:28

   ⚠ "Flow" used instead of "Pipeline" in 1 file:

   • src/engine/processor.ts:8

   Undefined Terms (candidates for glossary):
   ? "RBAC" — found in 5 files, not in glossary
   ? "Webhook Relay" — found in 3 files, not in glossary

   ✓ 12/15 terms used consistently
   ```

6. Offer to add undefined terms or fix inconsistencies

Edge cases:

• Empty glossary → suggest running `/dsl:init` first
• Technical terms that are intentionally different in code vs docs (e.g., `user_id` in code vs "User ID" in docs) → don't flag snake_case/camelCase variations
• Generated code (migrations, protobuf) → exclude from checking

Hooks

SessionStart: `glossary_loader`

Trigger: At session start (when Claude Code opens a project)

Behavior:

• If `docs/glossary.md` or `.claude/glossary.md` exists, load its contents into context
• This ensures Claude uses the correct terminology from the first message
• No output — silent context loading

Implementation note: This may be implemented as a reference in CLAUDE.md rather than a hook, depending on plugin hook capabilities. The CLAUDE.md approach:
```markdown

Glossary

@docs/glossary.md
```

File Manifest

File	Est. Lines	Purpose
`commands/init.md`	80-100	Initialize glossary
`commands/add.md`	70-90	Add term to glossary
`commands/check.md`	80-100	Check terminology compliance
`README.md`	130-160	Full plugin documentation
`.claude-plugin/plugin.json`	15-20	Plugin manifest

README Outline

1. Overview — Why domain vocabulary matters for AI-assisted development
2. Quick Start — Installation + `/dsl:init` + adding first terms
3. Commands — Table with all 3 commands
4. Glossary Format — Reference for the glossary markdown table format
5. Bootstrapping — How auto-detection works and what it scans
6. Consistency Checking — How compliance checking works, what it flags
7. Integration with CLAUDE.md — How the glossary is loaded into Claude's context
8. Best Practices — When to add terms, how specific to be, handling acronyms

Marketplace Description Update

Update `marketplace.json` description from:
```json
"description": "Domain-Specific Language utilities"
```
to:
```json
"description": "Project glossary and domain language management"
```

Prerequisites

• No external tools required

Quality Checklist

• Each command .md is 60+ lines with concrete steps
• README is 100+ lines with examples and reference tables
• Glossary format is well-defined with examples
• Consistency checking covers code, comments, and docs
• Plugin provides clear value (terminology consistency + auto-detection)
• `placeholder.md` command is removed and replaced with real commands