Brummel
4fd5408b1d
Gives the plugin an executable procedure over a project's glossary, closing the two gaps the glossary-convention infrastructure left open: no on-ramp to build a glossary for an existing project, and no conformance check around hand-maintenance. New `glossary` utility skill (invoked on demand like `issue`, not a pipeline phase) with a mode dispatch: - maintain: guided add / change / remove of one entry under a local conformance check (three-field shape, <=2-sentence definition, collision scan against existing entries) plus a stale-usage sweep on change/rename. A non-conforming entry is rejected with the named rule, not written. The sweep reports drift; it does not block (guidance, not enforcement). - bootstrap (user-only): fans out one read-only glossary-extractor agent per prose slice, merges and clusters their observed variants, auto- includes clear winners, surfaces contested clusters to the user for the canonical choice, and leaves unresolved clusters out (never coined). New `glossary-extractor` agent (read-only, template-conforming): sweeps one prose slice, reports recurring concept terms + competing variants with frequencies and locations, coins nothing. Single-sourcing held throughout: the skill applies the rules in docs/glossary-convention.md and restates none of them. Authority is unchanged — maintain keeps the user-any-time / boss-record-reality rule; bootstrap is user-only, with boss allowed to recommend it via bounce-back (one wired sentence in boss/SKILL.md). docs/glossary-convention.md gains a one-line tooling pointer to the skill; README.md lists `glossary` and `issue` as utility skills and drops the stale 'Eight skills' count the fresh-context grounding-check flagged (it had silently omitted `issue`). install.sh links the new skill + agent with no installer change (its glob covers any top-level dir with a SKILL.md + agents/ subdir; verified). Docs/prose-only repo, no test runner: all 13 grep presence-gates green against verified zero baselines; final sweep ALL_PRESENT, install.sh still parses (bash -n). Implements docs/specs/2026-05-31-glossary-skill-design.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2.8 KiB
Glossary convention
A project's glossary pins canonical nomenclature so terminology does not drift over time, and so that LLM-driven work reuses the established term for a concept instead of coining a fresh synonym each session. This file owns the format, the reading obligation, and the write discipline; an individual project's glossary is an instance of this convention.
Where it lives
A project opts in by setting paths.glossary in its
.claude/dev-cycle-profile.yml (see profile-schema.md § paths).
When the slot is set, the file it names is standing reading for every
role — no separate standing_reading.always entry is required. When
the slot is unset, the whole feature is a documented no-op.
A set glossary is the source of truth for the project's nomenclature.
Where any other document names a concept differently — including the
example renamings in profile-schema.md § vocabulary — the
glossary's canonical entry, and its Avoid list, win. A
vocabulary.* slot only sets which term the glossary then pins as
canonical; it does not override the glossary.
Format
The glossary is a flat list of per-term blocks (not a table), so an appended entry produces a clean line-wise diff. Each block has exactly three fields:
- a level-3 heading naming the canonical term to use;
- an Avoid: line listing known synonyms that must NOT be used;
- a definition of at most two sentences.
### canonical-term
**Avoid:** synonym-one, synonym-two
A definition of at most two sentences.
A term with no known synonyms still carries an **Avoid:** — line so
every block has the same three-field shape.
Reading obligation
Every skill and agent reads the glossary as part of its standing reading and, when producing prose or naming a concept, uses the canonical term and avoids the listed synonyms. If a concept is not listed, reuse the closest existing term — do not silently coin a new one.
Extending the glossary (user + boss only)
The user may edit the glossary at any time. In a /boss session the
orchestrator may extend it autonomously — but only to record
reality, never to invent:
- A term already used consistently across shipped artefacts but not yet listed → add it, with its known synonyms under Avoid.
- A drift the orchestrator just resolved (two terms for one concept) → record the winner as the canonical entry, the loser under Avoid.
The orchestrator never coins a brand-new term into the glossary: a term earns its entry by already being in consistent use. All other skills and agents are read-only consumers of the glossary.
The glossary skill (../glossary/SKILL.md) is the executable procedure
for building and extending a glossary under these rules: this file stays
the rules, the skill applies them.