Skills/docs/specs/2026-05-31-glossary-integration-design.md

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.

# 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:

# <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:

## 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:

# 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.