Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

spec: glossary integration

Browse Source 
Optional paths.glossary slot: when set, the file is standing reading
for every role (no separate standing_reading.always entry). Adds a
docs/glossary-convention.md single-sourcing the three-field format,
the standing-reading obligation, and the boss record-reality
write-rule; plus a dogfooded docs/glossary.md over the plugin's own
vocabulary. Guidance, not enforcement — no synonym check.

Grounding-check PASS: the one new semantic (paths.glossary auto-
promotion into standing reading) is carried as deliverable wiring,
not assumed to pre-exist.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Brummel
2026-05-31 14:05:45 +02:00
parent fc0e1d0d46
commit 3e5765be4e
1 changed files with 252 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specs/2026-05-31-glossary-integration-design.md
+252
View File
@@ -0,0 +1,252 @@
# Glossary Integration — Design Spec
**Date:** 2026-05-31
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude
## Goal
Give consuming projects a single, canonical place that pins
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. The glossary is **guidance,
not enforcement**: it becomes standing reading for every skill and
agent, but no tool scans artefacts for forbidden synonyms.
The plugin stays mechanics-only. This cycle adds:
1. an optional profile slot `paths.glossary`,
2. a convention doc that owns the glossary format and the write
discipline,
3. standing-reading wiring so a set `paths.glossary` is read by
every role automatically,
4. a boss write-rule (record reality, never invent),
5. a dogfooded `docs/glossary.md` in this repo proving the format
on the plugin's own vocabulary.
## Architecture
The glossary rides the **existing standing-reading mechanism**
rather than introducing a new delivery path. One optional path slot
carries the whole feature:
- `paths.glossary` (optional). **If set, the file it points to is
automatically standing reading for every agent** — no separate
`standing_reading.always` entry is required. If unset, the whole
feature is a documented no-op, exactly matching the plugin's
existing "missing optional slot = silent skip" contract.
Semantics ("set ⇒ standing reading for all roles") live in
`docs/profile-schema.md` next to the slot, so the wiring is
single-sourced and a project cannot set the path yet forget to make
it read.
The format and the write discipline live in a new
`docs/glossary-convention.md`, following the established
`docs/`-doc pattern (`pipeline.md`, `profile-schema.md`). Skills and
`boss` cross-reference it rather than restating it.
## Concrete code shapes
### 1. The delivered `docs/glossary.md` (dogfood — primary artefact)
This is the actual file the feature produces, shown on the plugin's
own vocabulary. Per-term blocks (not a table) so boss-appended
entries produce clean line-wise diffs.
```markdown
# Glossary
Canonical nomenclature for this project. Use the **canonical term**;
never use a term under **Avoid**. If you need a concept that is not
listed here, reuse the closest existing term — do not silently coin
a new one. New entries are added only to record nomenclature already
in consistent use; see `docs/glossary-convention.md`.
---
### cycle
**Avoid:** release, epic, round, sprint
One round in the pipeline graph (design → plan → execute → review →
close). Not the top-level container — that is a *milestone*.
### milestone
**Avoid:** epic, phase, big-ticket
A tracker container spanning potentially many cycles; closes only
when its promised work is complete and functional. A cycle close is
never a milestone close.
### iteration
**Avoid:** sprint, story, step
The default sub-unit of a cycle; one pass through the inner loop. A
project may rename it via `vocabulary.subcycle`.
### drift
**Avoid:** divergence, rot, skew
Accumulated mismatch between the codebase and its design ledger.
Surfaced by the architect agent at audit, not by any synonym check.
### hard-gate
**Avoid:** checkpoint, barrier, blocker
A pipeline point that forbids downstream work until an artefact
exists and is approved (e.g. an approved spec before any plan).
```
### 2. The profile slot (worked author example)
What a consuming project writes — one line opts the whole project
in:
```yaml
# <project>/.claude/dev-cycle-profile.yml
paths:
spec_dir: docs/specs
plan_dir: docs/plans
glossary: docs/glossary.md # optional — if set, every agent reads
# it as standing reading
code_roots: [src]
```
### 3. The boss write-rule (lives in `docs/glossary-convention.md`)
`boss/SKILL.md` carries only a cross-reference pointer; the rule
text itself is single-sourced here:
```markdown
## 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.
```
### Implementation shape (secondary — before → after)
**`templates/project-profile.yml`**, `paths:` block:
```yaml
# before
paths:
spec_dir: docs/specs
plan_dir: docs/plans
# design_ledger: design/INDEX.md # optional
code_roots: [src]
# after
paths:
spec_dir: docs/specs
plan_dir: docs/plans
# glossary: docs/glossary.md # optional — if set, read as
# standing reading by every role
# design_ledger: design/INDEX.md # optional
code_roots: [src]
```
**`docs/profile-schema.md`**, `paths` section: add a `glossary`
entry documenting the slot AND the "set ⇒ standing reading for all
roles" semantics, and a no-op-when-unset note.
**`docs/agent-template.md`** and **`docs/pipeline.md`**: where
standing reading is described, add one sentence: a set
`paths.glossary` is part of every role's standing reading.
**`boss/SKILL.md`**: add a short pointer (in the process/loop and a
cross-reference entry) to `docs/glossary-convention.md` for the
record-reality write-rule. No rule text duplicated.
## Components
- **`docs/glossary.md`** (new) — dogfooded glossary for the plugin's
own vocabulary; the lived proof of the format.
- **`docs/glossary-convention.md`** (new) — single source for the
format (three fields: canonical term, Avoid synonyms, ≤2-sentence
definition), the standing-reading obligation, and the boss
record-reality write-rule.
- **`paths.glossary` slot** — in `templates/project-profile.yml`
(commented) and `docs/profile-schema.md` (documented).
- **Standing-reading wiring** — one sentence each in
`docs/agent-template.md` and `docs/pipeline.md`.
- **`boss/SKILL.md`** — cross-reference pointer to the convention.
## Data flow
Author/consume:
1. A project sets `paths.glossary: docs/glossary.md` and writes the
file using the convention's three-field block format.
2. Every dispatched skill/agent, per the standing-reading contract,
reads the glossary alongside `CLAUDE.md` and the git-log entries.
3. When producing prose or naming a concept, the role uses the
canonical term and avoids the listed synonyms.
Extend (boss):
1. In `/boss`, when the orchestrator observes a term already in
consistent use but unlisted, or has just resolved a two-term
drift, it appends/edits one block per the convention.
2. The edit is an ordinary working-tree change committed under the
only-orchestrator-commits rule; no separate gate.
Unset:
- No `paths.glossary` ⇒ standing reading omits it, the convention
doc is inert reference, boss has nothing to extend. Documented
no-op.
## Error handling
- **Slot set but file missing:** a role that cannot read the
glossary treats it as it treats any missing standing-reading
source — notes the gap, proceeds; this is a profile error for the
project to fix, not a plugin failure.
- **Boss tempted to invent:** guarded by the convention's
red-flag/rationalisation framing ("a term earns its entry by
already being in use"); mirrors the existing boss anti-invention
discipline.
- **Convention vs. glossary drift:** the convention owns format and
rule; `docs/glossary.md` is an instance. The dogfood file is
expected to conform and serves as the conformance example.
## Testing strategy
This is a docs/profile cycle with no executable surface; the plugin
has no test runner (`commands.test` is empty for this repo). The
acceptance evidence is therefore the concrete artefacts above plus
two manual conformance checks:
1. **Dogfood conformance:** every block in `docs/glossary.md` has
exactly the three fields the convention mandates (canonical term
heading, **Avoid:** line, ≤2-sentence definition).
2. **No-op proof:** the wording added to `profile-schema.md`,
`agent-template.md`, and `pipeline.md` states the unset-slot case
so a profile without `glossary` provably skips the feature.
No fenced block in this spec targets a configured `spec_validation`
parser (this repo declares none); the parse-every-block gate is a
documented no-op here.
## Acceptance criteria
- `paths.glossary` documented in `docs/profile-schema.md` (slot +
"set ⇒ standing reading" semantics + unset no-op) and present
commented in `templates/project-profile.yml`.
- `docs/glossary-convention.md` exists and owns: the three-field
format, the standing-reading obligation, and the boss
record-reality write-rule (with the never-invent guard).
- `docs/agent-template.md` and `docs/pipeline.md` each state that a
set `paths.glossary` is standing reading for every role.
- `boss/SKILL.md` cross-references the convention for the write-rule
without duplicating its text.
- `docs/glossary.md` exists, dogfoods the plugin vocabulary, and
every entry conforms to the three-field format.
- With no `paths.glossary` set, the feature is a provable no-op.