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

plan: glossary skill

Browse Source 
Task-by-task plan for the glossary-skill spec. Two create tasks
(glossary/SKILL.md mode-dispatch utility skill, glossary/agents/
glossary-extractor.md read-only per-slice prose extractor) carrying full
verbatim file bodies, plus three single-sentence wiring edits
(boss/SKILL.md bootstrap bounce-back, docs/glossary-convention.md tooling
pointer, README.md utility-skill listing + count-free framing) and a
final sweep.

Docs/prose-only repo, no test runner: every task closes on a grep
presence-assertion against the touched file. All edit-task gates use
single-token patterns or code-fence lines calibrated against verified
zero baselines (bootstrap/glossary/SKILL.md path / glossary all 0 today),
sidestepping the line-wrap pitfall recorded at c7a56c2.

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

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Brummel
2026-05-31 15:31:42 +02:00
parent 79d269463d
commit b9ad490033
1 changed files with 506 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2026-05-31-glossary-skill.md
+506
View File
@@ -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: <short concept label>
variants: [<variant> (<count>x), <variant> (<count>x), ...]
locations: [<path:line>, <path:line>, ...]
```
End with a one-line `Swept: <n> files in <slice>` summary. On an empty
slice, emit `No recurring concept terms found in <slice>.`
## 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.