-
Resolve repo root. git rev-parse --show-toplevel. If not in a
git repo, STOP and report: "glossary needs a tracked repo; git init first or run /init-repo".
-
Detect mode.
- If
GLOSSARY.md does not exist at root → bootstrap mode.
- If
GLOSSARY.md exists and $ARGUMENTS includes --add <term> →
single-add mode (skip candidate ranking, jump to step 6 for
that one term).
- If
GLOSSARY.md exists and no --add → extend mode: surface
candidates that aren't already in the existing file, propose
additions.
-
Detect primary language by file extension counts in tracked
files (git ls-files | head -2000):
.py → Python.ts / .tsx / .js / .jsx → TypeScript / JavaScript.go → Go.rs → Rust- Mixed → use all detected.
- Override with
--lang.
-
Walk identifiers. From git ls-files (skip generated paths,
tests, vendor, node_modules, __pycache__, dist, build,
.git, bench/), extract identifiers via language-aware patterns:
- Python:
class\s+([A-Z][A-Za-z0-9_]+) (classes — high signal),
def\s+([a-z_][a-z0-9_]+) (functions — medium signal). Domain
terms are usually classes / type aliases / dataclasses, not
ordinary functions.
- TypeScript:
(?:class|interface|type|enum)\s+([A-Z][A-Za-z0-9_]+).
- Go:
type\s+([A-Z][A-Za-z0-9_]+)\s+(?:struct|interface).
- Rust:
(?:struct|enum|trait|type)\s+([A-Z][A-Za-z0-9_]+).
Count occurrences across the repo (not just declarations — also
usage). The more a term is referenced, the more load-bearing.
-
Filter and rank. Drop:
- Language keywords, standard library names, common framework
base classes (
BaseModel, Exception, HTTPException, Error,
Request, Response, Client, Config, Settings).
- Single-character names, names < 3 chars.
- Generic CRUD verbs presented as nouns (
Get, Set, Create,
Update, Delete alone).
- PascalCase that's plausibly a library type (rough heuristic:
starts with
Http, Json, Sql, Db, Aws, Gcp, Azure).
Rank remaining by occurrences * log(distinct_files) — terms that
appear in many places AND many files are more central than a term
used 50 times in one file.
Cap candidates at --top N (default 30).
-
Surface candidates (skip in --add mode):
I found these load-bearing domain terms in <repo>:
1. Tenant (47 refs across 12 files) — e.g. src/auth/tenant.py:14
2. Invoice (38 refs across 8 files) — e.g. src/billing/invoice.py:8
3. Lead (29 refs across 6 files) — e.g. src/content/lead.py:22
...
Pick which to include (numbers separated by spaces, "all", or "skip").
In --noninteractive mode, include the top 15 with <TODO: definition>
placeholders so the user fills them later. Mark such entries with
an HTML comment <!-- claude-leverage:glossary-todo --> so future
runs can spot them.
-
For each picked term, prompt:
- 1–2 sentence definition (required).
- Aliases (optional, comma-separated): other names the same concept
goes by in code, docs, conversations with this user.
- Code pointers (optional): up to 3 representative paths.
In --noninteractive, fill definition with <TODO> placeholder.
-
Write GLOSSARY.md.
<!-- claude-leverage:glossary v1 -->
# Glossary
Domain terms specific to this repo. Hand-curated. Update via
`/glossary-init --add <term>` or by editing this file directly.
Read this **before** assuming a term means what it does elsewhere —
domain vocabulary diverges between projects.
## Tenant
A customer organization. One Tenant → many Users. Distinct from
"Account" which is the billing entity.
- Aliases: org, organization
- Code: `src/auth/tenant.py`, `src/billing/account.py`
## Invoice
<definition>
Entries are sorted alphabetically by term (case-insensitive). Each
entry is one H2 + body + optional bullet list. The H1 + intro
paragraph + claude-leverage:glossary v1 marker are written exactly
once on bootstrap; subsequent runs preserve them.
-
Update AGENTS.md (idempotent, ask before write). If
AGENTS.md exists at root and doesn't already mention GLOSSARY.md,
offer to append a one-line pointer at the end of the "Code
conventions" section:
### Domain glossary
Domain terms specific to this repo live in [`GLOSSARY.md`](GLOSSARY.md).
**Grep there before assuming** what a term means — domain vocabulary
diverges between projects.
Skip if --no-update-agents-md is passed.
-
Report. Print the new path, count of entries added, count of
<TODO> placeholders remaining. Remind the user that ranking is
just a starting point; entries can be added by hand or via
--add <term> at any time.
