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

# glossary skill — Design Spec

**Date:** 2026-05-31
**Status:** Draft — awaiting user spec review
**Authors:** orchestrator + Claude

## Goal

Give the plugin an executable procedure for a project's glossary. Today
`docs/glossary-convention.md` declares the rules (three-field format,
reading obligation, the boss record-reality write-rule, glossary-as-SoT)
and `docs/glossary.md` dogfoods them — but nothing *does* anything. Two
gaps follow:

- **No way to build a glossary for an existing project.** The convention
  assumes a glossary already exists and is hand-maintained. A project
  with terminology drift but no glossary has no on-ramp.
- **Hand-maintenance has no conformance check.** A user (or boss) adding
  a term can silently break the three-field shape, exceed the
  two-sentence limit, or collide with another entry (a new **Avoid**
  synonym that is some other entry's canonical term, or vice versa).

The `glossary` skill closes both gaps with one skill carrying two
procedures: **maintain** (guided, conformance-checked add / change /
remove of a single entry) and **bootstrap** (a fan-out of read-only
extraction agents that build a fresh glossary from a project's prose
surface). The skill is the executable procedure; the convention stays
the rules. The skill never restates the convention's format or
write-rule — it points to it and applies it.

## Architecture

`glossary` is a **utility skill**, invoked on demand like `issue` — not a
pipeline phase. It does **not** appear in the `design → plan → implement
→ audit` loop, takes no `pipeline:` profile entry, and gates nothing.

It lives at `glossary/` with the standard layout:

- `glossary/SKILL.md` — a mode dispatch at the head (`maintain` |
  `bootstrap`) followed by the two procedures.
- `glossary/agents/glossary-extractor.md` — one dedicated, read-only,
  template-conforming agent.

`install.sh` links any top-level directory with a `SKILL.md` (and its
`agents/` subdir) by glob; the new skill and agent are picked up with no
change to the installer.

**Role split, single-sourced.** `docs/glossary-convention.md` owns the
rules: the three-field format, the reading obligation, the boss
record-reality write-rule, and the glossary-as-source-of-truth
declaration. The `glossary` skill owns the *procedure* that applies those
rules. The skill points to the convention for every rule it enforces and
restates none of them, exactly as `boss/SKILL.md` points to the
convention for the write-rule rather than copying it.

**Authority.**

- *maintain* is governed by the existing write authority unchanged: the
  user any time; boss autonomously but only to record reality, never to
  invent (`glossary-convention.md` § Extending). The skill adds the
  conformance check around that authority; it does not widen it.
- *bootstrap* is **user-only**. It is high-context multi-agent work
  analogous to a fresh `brainstorm`, which boss bounces back rather than
  starting autonomously. boss MAY recommend a bootstrap via a bounce-back
  when a project lacks a glossary and drift is visible, but never runs
  one itself.

## Concrete code shapes

### User-facing: a bootstrap run

```
User: /glossary bootstrap

Skill:
  1. read paths.glossary → file is unset or empty  (else: refuse, see Error handling)
  2. partition the prose surface into slices:
       docs/, README.md, design-ledger (if paths.design_ledger set), specs/
  3. fan out one glossary-extractor per slice (read-only)
  4. merge reports → cluster variants of the same concept
  5. clear cluster (one dominant variant) → draft entry, auto-included
     contested cluster (≥2 comparable variants) → surface to user
  6. assemble the conforming glossary, write it UNSTAGED to paths.glossary
  7. user reviews the working-tree file
```

### Carrier and report (the glossary-extractor contract)

```
# carrier  skill → glossary-extractor
slice: docs/                       # the one prose slice this agent sweeps
task:  "extract recurring domain-CONCEPT terms and their competing
        synonyms as actually written; do NOT coin terms"

# report  glossary-extractor → skill   (word-budgeted, structured)
- concept: cycle
  variants: [cycle (41x), round (6x), sprint (2x)]
  locations: [docs/pipeline.md:3, README.md:30]
- concept: design ledger
  variants: [design ledger (12x), design index (9x)]
  locations: [docs/profile-schema.md:15, docs/specs/...]
```

### Synthesis — a clear cluster becomes a conforming entry automatically

```
### cycle
**Avoid:** round, sprint, release, epic
One round in the pipeline graph (design -> plan -> execute -> review ->
close). Not the top-level container — that is a milestone.
```

### A contested cluster is surfaced, never auto-decided

```
Contested: "design ledger" (12x, docs/) vs "design index" (9x, specs/)
name the same concept. Which is canonical?
  [design ledger]  [design index]  [other]
```

If the user does not resolve it, the concept is left OUT of the glossary
and noted as deferred — never coined.

### User-facing: a maintain run, and the must-reject case

```
User: /glossary add  (proposes)
  ### design ledger
  **Avoid:** drift
  The canonical specification index ... <three sentences> ...

Skill (local conformance, before writing):
  REJECT — two violations, entry not written:
    1. definition is 3 sentences; the format allows at most 2.
    2. "drift" under **Avoid** is the canonical term of an existing
       entry (docs/glossary.md "### drift"). A synonym cannot be
       another entry's canonical term.
  Fix and resubmit.
```

A conforming add, by contrast, passes the local check, then triggers the
stale-usage sweep:

```
Skill: conformance OK. Stale-usage sweep for the **Avoid** terms:
  "design index" still appears at docs/profile-schema.md:15, specs/foo.md:8
  → these are drift you may want to fix; entry written UNSTAGED regardless.
```

### Implementation shape (secondary — what files change)

New files:

- `glossary/SKILL.md` — head: `> Violating the letter...` lead-in,
  Overview, When to Use / Skipping, a **Mode dispatch** section routing
  `maintain` vs `bootstrap`, then the two numbered procedures, Handoff
  Contract, Common Rationalisations, Red Flags, Cross-references.
- `glossary/agents/glossary-extractor.md` — per `docs/agent-template.md`:
  frontmatter (`name: glossary-extractor`, third-person description,
  `tools: Read, Glob, Grep, Bash`), spirit-letter lead-in, What this role
  is for, Standing reading list, Carrier contract, Iron Law, The Process,
  Status protocol, Output format, Common Rationalisations, Red Flags.

Edited files (one referencing sentence each — no rule restated):

- `boss/SKILL.md` — in § Direction freedom / Notifications, one sentence:
  boss may recommend a bootstrap via bounce-back when a project lacks a
  glossary and drift is visible, but never runs one autonomously (it is
  high-context work like a fresh brainstorm).
- `docs/glossary-convention.md` — in § Extending, one tooling pointer:
  the `glossary` skill is the executable procedure for building and
  extending a glossary; this file stays the rules.
- `README.md` — the skill listing is updated to include `glossary` as a
  utility skill (like `issue`). Note the current README has **no**
  agent-roster note to extend (its "Eight skills" table carries only
  Trigger / Output / Mandatory columns), and that "Eight skills" framing
  is already stale — it omits the existing utility skill `issue`. The
  edit therefore adds `glossary` to the listing and reconciles the
  framing so the listing is accurate, rather than appending to a roster
  note that does not exist. No agent-roster surface is created — the
  agent roster lives in the per-skill `agents/` directories, not in
  README.

## Components

### `glossary/SKILL.md`

A mode-dispatch skill. The head routes on the invocation:

- **maintain** — add / change / remove one entry. Steps: (1) read the
  glossary and the convention; (2) take the proposed entry; (3) run the
  **local conformance check** — three-field shape, definition ≤ 2
  sentences, and the collision scan (a proposed canonical term must not
  already sit under another entry's **Avoid**; a proposed **Avoid**
  synonym must not be another entry's canonical term); reject with the
  named rule on failure, do not write; (4) on add / change / rename, run
  the **stale-usage sweep** — grep the old canonical and the **Avoid**
  synonyms across the prose surface and report the hits as drift the user
  may want to fix; (5) write the conforming entry UNSTAGED; (6) hand back
  to the user (or, in a boss session, the boss record-reality discipline
  governs whether the write was permitted at all).

- **bootstrap** — build a new glossary. Steps as in § Concrete code
  shapes: empty/unset check, partition, fan-out, merge + cluster,
  auto-include clear winners, surface contested clusters, assemble
  UNSTAGED, user review.

The skill restates none of the convention's rules; it cites
`docs/glossary-convention.md` for the format and the write-rule and
`docs/profile-schema.md` § `paths` for the `paths.glossary` semantics.

### `glossary/agents/glossary-extractor.md`

A read-only extraction agent. **Failure mode it exists to prevent:** an
orchestrator sweeping a whole project's prose in its own context to coin
a glossary — blowing context and conflating orchestration with
execution, and tempting invention over observation. The agent sweeps one
slice, reports *observed* concept terms and their competing variants with
frequencies and locations, and coins nothing. The skill fans out one
agent per slice and curates each carrier; agents do not nest (Claude Code
platform constraint).

## Data flow

**maintain.** proposal → local conformance (format, ≤2 sentences,
collision scan) → reject-with-rule on failure / continue on pass → (add /
change / rename) stale-usage sweep → report stale hits → write conforming
entry UNSTAGED → user review. boss-initiated writes stay bound to
record-reality.

**bootstrap.** user invokes → empty/unset guard → partition prose surface
into slices → fan out N × glossary-extractor → merge reports → cluster
variants → clear cluster auto-included as entry / contested cluster
surfaced to user for the canonical choice → unresolved contested cluster
left out (deferred, never coined) → assemble conforming glossary file
UNSTAGED → user review.

## Error handling

- **`paths.glossary` unset.** bootstrap still builds a glossary and
  proposes setting the slot (pointing at `docs/profile-schema.md` §
  `paths`); maintain has no target and stops, instructing the user to set
  the slot first.
- **bootstrap on a populated glossary.** No clobber. The skill stops with
  a diagnosis ("glossary already has N entries") and recommends maintain
  for incremental work.
- **conformance failure in maintain.** The entry is rejected with the
  specific rule cited and is NOT written. (This is the must-fail evidence
  for the feature-acceptance criterion: a wrong entry must fail the
  check.)
- **glossary-extractor returns empty or BLOCKED.** The skill reports the
  empty slice and fabricates no terms — record reality, never invent.
- **contested cluster the user does not resolve.** Left out of the
  glossary entirely and noted as deferred. The skill never picks a
  canonical term for a genuinely contested cluster on its own.

## Testing strategy

This repo ships no test runner; it is docs / prose only. Following the
glossary-integration cycle precedent, each implementation task closes on
a grep presence-assertion against the file it touches, calibrated against
a verified zero baseline (the `git log` for that cycle records the
mis-calibrated-grep failure mode to avoid: assert against the unwrapped
line, not a pattern that straddles a line break).

The behavioural evidence is the worked examples embedded in § Concrete
code shapes: a conforming entry accepted, a non-conforming entry rejected
with the named rule, and a contested cluster surfaced to the user. These
are the empirical evidence the feature-acceptance criterion demands for a
no-executable-surface infra cycle.

No `spec_validation` parser is configured for this repo, so the
brainstorm parse-every-block gate is a documented no-op here: the fenced
blocks in this spec are illustrative CLI / prose, none carrying a fence
label with a configured parser.

## Acceptance criteria

1. `glossary/SKILL.md` exists with a mode dispatch (`maintain` |
   `bootstrap`) and both procedures.
2. `glossary/agents/glossary-extractor.md` exists, conforms to
   `docs/agent-template.md`, and is read-only (`tools: Read, Glob, Grep,
   Bash`).
3. The skill single-sources against `docs/glossary-convention.md`: it
   cites the format and write-rule and restates neither.
4. bootstrap is user-only; `boss/SKILL.md` carries one sentence wiring
   the boss-may-recommend-via-bounce-back rule.
5. maintain runs the local conformance check plus the stale-usage sweep;
   a non-conforming proposed entry is rejected with the named rule and
   not written.
6. bootstrap surfaces contested clusters to the user, auto-includes clear
   winners, and never coins a contested canonical term.
7. `README.md`'s skill listing includes `glossary` as a utility skill and
   the stale "Eight skills" framing (which omits the existing `issue`
   utility skill) is reconciled so the listing is accurate; no
   agent-roster note is added (none exists). `docs/glossary-convention.md`
   carries a one-line tooling pointer to the skill.
8. `install.sh` links the new skill and agent with no change to the
   installer (the existing glob covers them).