Brummel
26e9630496
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing). Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign. Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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 naming a glossary path in its CLAUDE.md project
|
|
facts (see `conventions.md`). When it is named, the file it points to
|
|
is standing reading for every role — no separate standing-reading entry
|
|
is required. When the project names none, the whole feature is a
|
|
documented no-op.
|
|
|
|
A glossary is the source of truth for the project's nomenclature.
|
|
Where any other document names a concept differently — including the
|
|
fixed vocabulary in `conventions.md` (cycle / iteration / milestone /
|
|
contract) — the glossary's canonical entry, and its **Avoid** list,
|
|
win.
|
|
|
|
## 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:
|
|
|
|
1. a level-3 heading naming the **canonical term** to use;
|
|
2. an **Avoid:** line listing known synonyms that must NOT be used;
|
|
3. 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.
|