diff --git a/docs/plans/2026-05-31-glossary-skill.md b/docs/plans/2026-05-31-glossary-skill.md new file mode 100644 index 0000000..987e57d --- /dev/null +++ b/docs/plans/2026-05-31-glossary-skill.md @@ -0,0 +1,506 @@ +# glossary skill — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-31-glossary-skill-design.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use the `implement` +> skill to run this plan. Steps use `- [ ]` checkboxes for tracking. + +**Goal:** Add a `glossary` utility skill (two procedures — maintain and +bootstrap) plus its dedicated read-only `glossary-extractor` agent, and +wire three single-sentence references, so a project can build and +conformance-check its glossary. + +**Architecture:** A new top-level `glossary/` skill directory (picked up +by `install.sh`'s existing glob) holding `SKILL.md` (mode dispatch +`maintain | bootstrap`) and `agents/glossary-extractor.md` +(template-conforming, read-only). The skill applies the rules in +`docs/glossary-convention.md` and restates none. Three referencing edits +in `boss/SKILL.md`, `docs/glossary-convention.md`, and `README.md`. + +**Tech Stack:** Markdown skill + agent files; docs/prose-only repo, no +test runner — every task closes on a `grep` presence-assertion against +the touched file, each calibrated against a verified zero baseline. + +--- + +**Files this plan creates or modifies:** + +- Create: `glossary/SKILL.md` — the mode-dispatch utility skill. +- Create: `glossary/agents/glossary-extractor.md` — read-only per-slice prose extractor. +- Modify: `boss/SKILL.md:131` — append the bootstrap bounce-back sentence to the glossary-write paragraph. +- Modify: `docs/glossary-convention.md:66` — append the one-line tooling pointer to § Extending. +- Modify: `README.md:17,28` — reword the count-pinned framing line; add a utility-skills note after the table. + +Read-only references (not edited): `docs/glossary.md` (collision-scan +example), `docs/profile-schema.md` § `paths` (slot semantics), +`docs/agent-template.md` (agent skeleton), `install.sh` (glob covers the +new dir — AC 8, no edit). + +--- + +### Task 1: `glossary/SKILL.md` + +**Files:** +- Create: `glossary/SKILL.md` + +- [ ] **Step 1: Create the directory and write the skill file** + +Create `glossary/SKILL.md` with exactly this content: + +````markdown +--- +name: glossary +description: Use when adding, changing, or removing a glossary entry (maintain), or building a new glossary for an existing project from its prose surface (bootstrap). The skill applies the rules in docs/glossary-convention.md — it restates none of them. maintain keeps the existing user-any-time / boss-record-reality write authority and adds a conformance check; bootstrap is user-only (high-context multi-agent work; boss may recommend it via bounce-back but never runs it). +--- + +# glossary — build and maintain a project's glossary + +> **Violating the letter of these rules is violating the spirit.** + +## Overview + +A project's glossary pins canonical nomenclature so terminology does not +drift over time, and so LLM-driven work reuses the established term for a +concept instead of coining a fresh synonym each session. +`../docs/glossary-convention.md` owns the rules — the three-field format, +the reading obligation, the record-reality write-rule, and the +glossary-as-source-of-truth declaration. This skill is the *procedure* +that applies those rules; it restates none of them. + +It carries two procedures. **maintain** adds, changes, or removes a +single entry under a conformance check. **bootstrap** builds a fresh +glossary for a project that has none, by fanning out read-only +`glossary-extractor` agents over the project's prose surface and +synthesising their observations into conforming entries. + +## When to Use / Skipping + +Triggers: + +- **maintain** — a term is to be added, changed, or removed in an + existing glossary, by the user any time, or by boss to record reality + (a term already in consistent use, or a drift boss just resolved). +- **bootstrap** — a project has terminology to pin but no glossary + (`paths.glossary` unset, or naming an empty file), and the user invokes + the build. + +Skip or refuse: + +- maintain asked with no `paths.glossary` slot set: there is nowhere to + write. Stop and instruct the user to set `paths.glossary` (see + `../docs/profile-schema.md` § `paths`) first. +- bootstrap asked on a glossary that already has entries: do not clobber. + Stop with the entry count and recommend maintain. +- bootstrap asked in a boss (autonomous) session: refuse. bootstrap is + user-only; boss may recommend it via bounce-back but never runs it (see + Authority). + +## Authority + +maintain inherits the existing write authority unchanged +(`../docs/glossary-convention.md` § Extending): the user any time; boss +autonomously but only to record reality, never to invent. This 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. In a boss session, recommend a bootstrap via bounce-back +when a project lacks a glossary and drift is visible — do not run one. + +## Mode dispatch + +On invocation, route on the argument: + +- `maintain` (or `add` / `change` / `remove`) → the maintain procedure. +- `bootstrap` → the bootstrap procedure (user-only). + +If the mode is ambiguous, ask once; do not guess. + +## The maintain procedure + +1. **Read the glossary and the convention.** Read the file named by + `paths.glossary` and `../docs/glossary-convention.md`. If + `paths.glossary` is unset, stop (see When to Use / Skipping). +2. **Take the proposed entry.** A canonical-term heading, an `**Avoid:**` + line, and a definition — the user's, or (in a boss session bound by + record-reality) the term already in consistent use. +3. **Run the local conformance check** against the proposed entry and the + rest of the glossary: + - the three-field shape the convention defines; + - the definition is at most two sentences; + - collision scan: the proposed canonical term must not already sit + under another entry's **Avoid**, and a proposed **Avoid** synonym + must not be another entry's canonical term. + On any failure, REJECT — name the violated rule, do not write the + entry, and ask for a corrected one. +4. **Run the stale-usage sweep** (on add / change / rename): grep the + prose surface for the old canonical term (change/rename) and for each + **Avoid** synonym, and report the hits as drift the user may want to + fix. The sweep reports; it does not block — guidance, not enforcement. +5. **Write the conforming entry UNSTAGED.** Add, edit, or remove the + entry in the glossary file, preserving the flat per-term-block shape so + the diff stays line-wise clean. Leave it unstaged for review. +6. **Hand back** to the user for review. In a boss session, the + record-reality discipline governs whether the write was permitted at + all (boss never coins). + +## The bootstrap procedure (user-only) + +1. **Guard.** Read `paths.glossary`. If it names a file that already has + entries, stop with the count and recommend maintain. If the slot is + unset, continue, and note the build will also propose setting the slot + (see `../docs/profile-schema.md` § `paths`). +2. **Partition the prose surface into slices** — the readable prose of + the project: `docs/`, `README.md`, the design ledger (if + `paths.design_ledger` is set), the spec directory. One slice per + coherent group, sized so a single agent can sweep it. +3. **Fan out one `glossary-extractor` per slice.** Dispatch the read-only + agent (`agents/glossary-extractor.md`) with the carrier: the slice and + the extraction task. Agents do not nest; the skill curates each + carrier. +4. **Merge and cluster.** Collect the reports. Cluster variants that name + the same concept across slices, summing frequencies. +5. **Synthesise.** For each cluster: + - a clear cluster (one dominant variant) → auto-include it as a + conforming entry: canonical heading = the dominant variant, + **Avoid** = the other variants, a ≤2-sentence definition drawn from + the observed usage; + - a contested cluster (≥2 comparable variants) → surface it to the user + with the variants, frequencies, and locations, and ask which is + canonical. Never decide a contested canonical yourself. +6. **Handle the unresolved.** A contested cluster the user does not + resolve is left OUT of the glossary and noted as deferred. Never coin a + term to fill a gap. +7. **Assemble UNSTAGED.** Write the conforming glossary to + `paths.glossary` (proposing the slot value if it was unset), in the + convention's flat per-term-block format. Leave it unstaged for review. + +## Iron Law + +``` +THE CONVENTION OWNS THE RULES; THIS SKILL ONLY APPLIES THEM — RESTATE NOTHING. +A NON-CONFORMING ENTRY IS REJECTED, NOT WRITTEN. +BOOTSTRAP IS USER-ONLY. NEVER COIN A TERM — RECORD REALITY. +``` + +## Handoff Contract + +| Direction | Carrier | +|-----------|---------| +| user → glossary (maintain) | the proposed entry + the operation (add / change / remove) | +| user → glossary (bootstrap) | the build request | +| glossary → glossary-extractor (bootstrap) | one prose slice + the extraction task | +| boss → user (bounce-back) | a recommendation to run a bootstrap; boss never runs one itself | + +## Common Rationalisations + +| Excuse | Reality | +|--------|---------| +| "The entry is obviously fine, skip the conformance check" | The check is the skill's whole reason to exist over hand-editing. Run it. | +| "Two variants are close; I'll pick the more frequent as canonical" | A contested cluster is a nomenclature judgement that belongs to the user. Surface it; do not decide it. | +| "The concept clearly needs a term, I'll coin one" | The glossary records reality, never invents. An unresolved concept is left out and deferred. | +| "boss is running and the project has no glossary, I'll bootstrap it" | bootstrap is user-only. Recommend it via bounce-back; do not run it. | +| "I'll restate the format here so the skill is self-contained" | The convention is the single source for the rules. Cite it; restating it is the cross-doc drift this split exists to prevent. | +| "The stale-usage hits should block the write" | The sweep is guidance, not enforcement. Report the drift; write the entry regardless. | + +## Red Flags — STOP + +- About to write a non-conforming entry instead of rejecting it. +- About to pick a canonical term for a genuinely contested cluster. +- About to coin a term for a concept that has no observed term. +- About to run a bootstrap in a boss / autonomous session. +- About to restate the convention's format or write-rule in this file. +- About to clobber a populated glossary with a bootstrap. + +## Cross-references + +- **Rules (the single source):** `../docs/glossary-convention.md` — + format, reading obligation, write-rule, glossary-as-SoT. This skill + applies these; it restates none. +- **Slot semantics:** `../docs/profile-schema.md` § `paths` — the + `paths.glossary` slot (set ⇒ standing reading for every role; unset ⇒ + no-op). +- **Agent dispatched:** `agents/glossary-extractor.md` — read-only + per-slice prose extraction, fanned out in bootstrap. +- **Glossary instance (dogfood):** `../docs/glossary.md` — this plugin's + own glossary. +- **boss write authority:** `../boss/SKILL.md` — the record-reality rule + for the only autonomous glossary writer, and the bootstrap bounce-back. +```` + +- [ ] **Step 2: Verify the file is present and conforming** + +Run: `grep -c "BOOTSTRAP IS USER-ONLY" glossary/SKILL.md` +Expected: `1` (the Iron-Law fence line; baseline before this task: file does not exist). + +Run: `grep -c "^## The bootstrap procedure (user-only)$" glossary/SKILL.md` +Expected: `1` (the bootstrap-procedure heading is present). + +Run: `grep -c "^name: glossary$" glossary/SKILL.md` +Expected: `1` (frontmatter `name` slug is correct). + +--- + +### Task 2: `glossary/agents/glossary-extractor.md` + +**Files:** +- Create: `glossary/agents/glossary-extractor.md` + +- [ ] **Step 1: Create the agents directory and write the agent file** + +Create `glossary/agents/glossary-extractor.md` with exactly this content: + +````markdown +--- +name: glossary-extractor +description: Read-only per-slice prose extractor for glossary bootstrap. Sweeps one slice of a project's prose surface and reports the recurring domain-concept terms and their competing synonyms as actually written, with frequencies and locations. Coins nothing; dispatched fan-out by the glossary skill's bootstrap procedure. +tools: Read, Glob, Grep, Bash +--- + +> Violating the letter of these rules is violating the spirit. + +## What this role is for + +This role exists to prevent an orchestrator from sweeping a whole +project's prose in its own context to coin a glossary — which blows the +context window, conflates orchestration with execution, and tempts +invention over observation. The extractor sweeps exactly one assigned +slice, reports the concept terms and competing variants it actually +finds, and coins nothing. The glossary skill fans out one extractor per +slice and merges their reports. + +## Standing reading list + +Read everything in the standing reading list passed in the carrier before +doing anything else. A set `paths.glossary` is part of every role's +standing reading, and `docs/glossary-convention.md` defines what a +glossary-worthy concept term is versus incidental vocabulary — consult it +so you report concepts, not every capitalised word. + +## Carrier contract + +| Field | Content | +|-------|---------| +| `slice` | the one prose region this agent sweeps (e.g. `docs/`, `README.md`) — do not read outside it | +| `task` | the extraction instruction: recurring domain-concept terms and their competing synonyms, as actually written | + +You receive the carrier inline in the dispatch prompt. Do NOT widen your +sweep beyond the assigned slice; another extractor covers the rest. + +## Iron Law + +``` +REPORT TERMS YOU OBSERVE IN THE SLICE. NEVER COIN A TERM. +EVERY REPORTED VARIANT CARRIES A FREQUENCY AND AT LEAST ONE LOCATION. +SWEEP ONLY THE ASSIGNED SLICE. +A CANONICAL CHOICE IS NOT YOURS TO MAKE — REPORT VARIANTS, NOT A WINNER. +``` + +## The Process + +1. Read the standing reading list, then `docs/glossary-convention.md` for + what counts as a concept term. +2. Enumerate the files in the assigned slice (`Glob` / `ls`). +3. Sweep for recurring domain-concept terms: nouns and noun-phrases that + name a project concept and recur across the slice. Use `grep -c` for + frequencies and `grep -n` for locations. +4. Cluster variants that name the same concept within the slice (e.g. + "design ledger" / "design index"). Do not decide which is canonical. +5. Drop incidental vocabulary: terms that appear once, generic English, + and code identifiers that are not concept names. +6. Emit the report in the format below. If the slice yields no recurring + concept terms, say so — fabricate nothing. + +## Status protocol + +| Status | Meaning | +|--------|---------| +| `DONE` | The slice was swept; the report lists every recurring concept term found (possibly none). | +| `PARTIAL` | The slice was too large to finish; report what was swept and name the unswept files. | +| `BLOCKED` | The slice could not be read (missing path, permission). Explanation in the report. | +| `NEEDS_CONTEXT` | The carrier is ambiguous (no slice, or an unreadable task). | + +This is a read-only role: it writes no files under any status. + +## Output format + +Plain text, word-budgeted. One block per concept: + +``` +- concept: + variants: [ (x), (x), ...] + locations: [, , ...] +``` + +End with a one-line `Swept: files in ` summary. On an empty +slice, emit `No recurring concept terms found in .` + +## Common Rationalisations + +| Excuse | Reality | +|--------|---------| +| "This concept obviously needs a canonical term, I'll mark one" | Picking the canonical is the skill's job (and the user's for contested clusters). Report variants, not a winner. | +| "There's a clearly better word the project should use" | You report what is written, not what should be. Coining is forbidden. | +| "The neighbouring slice has related terms, let me peek" | Sweep only your slice. Another extractor covers the rest; merging is the skill's job. | +| "This term appears once but feels important" | A single occurrence is not a recurring concept. Drop it, or the merge fills with noise. | +| "I'll skip frequencies, the list is enough" | Frequencies are how the skill tells a clear cluster from a contested one. Every variant carries a count. | + +## Red Flags — STOP + +- About to write or edit any file. +- About to report a term that does not appear in the slice. +- About to name a canonical winner instead of listing variants. +- About to read files outside the assigned slice. +- About to report a variant with no frequency or no location. +```` + +- [ ] **Step 2: Verify the agent file is present and conforming** + +Run: `grep -c "NEVER COIN A TERM" glossary/agents/glossary-extractor.md` +Expected: `1` (the Iron-Law fence line; baseline before this task: file does not exist). + +Run: `grep -c "^name: glossary-extractor$" glossary/agents/glossary-extractor.md` +Expected: `1` (frontmatter slug correct). + +Run: `grep -c "^tools: Read, Glob, Grep, Bash$" glossary/agents/glossary-extractor.md` +Expected: `1` (read-only tool set, AC 2). + +--- + +### Task 3: `boss/SKILL.md` — bootstrap bounce-back sentence + +**Files:** +- Modify: `boss/SKILL.md:131` + +- [ ] **Step 1: Append the bootstrap sentence to the glossary-write paragraph** + +Find this exact line (`boss/SKILL.md:131`, the tail of the Step-4 +glossary-write paragraph): + +``` +invent. This is the only glossary write authority outside the user. +``` + +Replace it with: + +``` +invent. This is the only glossary write authority outside the user. +Building a glossary from scratch (the `glossary` skill's bootstrap) is +*not* this authority — it is high-context, user-only work; when a project +lacks a glossary and drift is visible, recommend a bootstrap via +bounce-back, never run one autonomously. +``` + +This keeps maintain-by-boss (record-reality) and bootstrap (user-only) +consistent with the existing "only glossary write authority outside the +user" claim on the same line. + +- [ ] **Step 2: Verify the sentence landed** + +Run: `grep -c "bootstrap" boss/SKILL.md` +Expected: `≥1` (verified baseline before this task: `0`). + +--- + +### Task 4: `docs/glossary-convention.md` — tooling pointer + +**Files:** +- Modify: `docs/glossary-convention.md:66` + +- [ ] **Step 1: Append the tooling pointer to § Extending** + +Find this exact line (`docs/glossary-convention.md:66`, the last line of +the file / § Extending): + +``` +skills and agents are read-only consumers of the glossary. +``` + +Append immediately after it (new paragraph at the section tail): + +``` +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. +``` + +- [ ] **Step 2: Verify the pointer landed** + +Run: `grep -c "glossary/SKILL.md" docs/glossary-convention.md` +Expected: `≥1` (verified baseline before this task: `0`; `glossary/SKILL.md` +is a contiguous token, no line-wrap risk). + +--- + +### Task 5: `README.md` — list glossary, reconcile the stale framing + +**Files:** +- Modify: `README.md:17` (the count-pinned framing line) +- Modify: `README.md:28` (append a utility-skills note after the table) + +- [ ] **Step 1: Reword the count-pinned framing line** + +Find this exact line (`README.md:17`): + +``` +Eight skills, each with the agents it primarily dispatches: +``` + +Replace it with (count-free, since the table omits the existing utility +skill `issue` and now also `glossary`): + +``` +The pipeline skills, each with the agents it primarily dispatches: +``` + +- [ ] **Step 2: Add a utility-skills note after the skill table** + +Find the last table row (`README.md:28`): + +``` +| `boss` | User types `/boss` | autonomous-orchestrator session — dispatches the other skills until done-state or bounce-back | User-invoked, never auto-dispatched | +``` + +Append immediately after it (a blank line, then the note): + +``` +| `boss` | User types `/boss` | autonomous-orchestrator session — dispatches the other skills until done-state or bounce-back | User-invoked, never auto-dispatched | + +Two further **utility skills** are invoked on demand rather than as +pipeline phases: `issue` (file or update a tracker item) and `glossary` +(build or maintain the project glossary — see `docs/glossary-convention.md`). +``` + +- [ ] **Step 3: Verify the listing change landed** + +Run: `grep -c "glossary" README.md` +Expected: `≥1` (verified baseline before this task: `0`). + +Run: `grep -c "utility skills" README.md` +Expected: `≥1` (the reconciled framing names the utility-skill class; baseline: `0`). + +--- + +### Final sweep + +- [ ] **Step F1: All new and changed surfaces present** + +Run: +``` +test -f glossary/SKILL.md && \ +test -f glossary/agents/glossary-extractor.md && \ +grep -q "bootstrap" boss/SKILL.md && \ +grep -q "glossary/SKILL.md" docs/glossary-convention.md && \ +grep -q "glossary" README.md && \ +echo ALL_PRESENT +``` +Expected: `ALL_PRESENT` + +- [ ] **Step F2: install.sh glob covers the new skill (AC 8, no edit needed)** + +Run: `bash -n install.sh && grep -c 'SKILL.md' install.sh` +Expected: `bash -n` exits 0 (installer still parses) and the glob gate on +`SKILL.md` is present (`≥1`); confirms the new `glossary/` dir with its +`SKILL.md` + `agents/` subdir is linked with no installer change.