Skills/docs/plans/2026-05-31-glossary-integration.md

Glossary Integration — Implementation Plan

Parent spec: docs/specs/2026-05-31-glossary-integration-design.md

For agentic workers: REQUIRED SUB-SKILL: use the implement skill to run this plan. Steps use - [ ] checkboxes for tracking.

Goal: Add an optional paths.glossary profile slot whose file becomes standing reading for every role, a convention doc that owns the format and the boss write-rule, and a dogfooded docs/glossary.md for the plugin's own vocabulary.

Architecture: The glossary rides the existing standing-reading mechanism — one optional path slot, no new delivery path. The "set ⇒ standing reading for every role" semantics are single-sourced at the paths.glossary row in profile-schema.md; agent-template.md and pipeline.md carry one referencing sentence each. The format and write-rule live once in docs/glossary-convention.md; boss/SKILL.md only points to it.

Tech Stack: Markdown docs, one YAML template. No executable surface — this repo has no test runner, so each task verifies with a grep presence assertion against the file it touched.

---

Note on verification & the parse gate

This repo ships no .claude/dev-cycle-profile.yml, so commands.test is empty and spec_validation is undeclared. Per the planner self-review parse gate (docs/profile-schema.md § spec_validation), the inlined blocks here are markdown / yaml fences with no configured parser — the parse-the-bytes-you-inline gate is a documented no-op for this plan. Each task therefore closes on a grep assertion whose pattern is named to match ≥1 real line in the file just written (self-review item 8), not a test-runner result.

---

Task 1: Create docs/glossary-convention.md

The single source for the glossary format, the standing-reading obligation, and the boss record-reality write-rule. Created first so later tasks can cross-reference it.

Files:

• Create: docs/glossary-convention.md

• Step 1: Write the convention doc

Create docs/glossary-convention.md with exactly this content (the outer fence is four backticks so the inner three-backtick format example below survives — write only the inner content to the file):

# Glossary convention

A project's glossary pins canonical 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. This file owns the format, the reading obligation, and the
write discipline; an individual project's glossary is an instance of
this convention.

## Where it lives

A project opts in by setting `paths.glossary` in its
`.claude/dev-cycle-profile.yml` (see `profile-schema.md` § `paths`).
When the slot is set, the file it names is standing reading for every
role — no separate `standing_reading.always` entry is required. When
the slot is unset, the whole feature is a documented no-op.

## Format

The glossary is a flat list of per-term blocks (not a table), so an
appended entry produces a clean line-wise diff. Each block has exactly
three fields:

1. a level-3 heading naming the **canonical term** to use;
2. an **Avoid:** line listing known synonyms that must NOT be used;
3. a definition of at most two sentences.

```
### canonical-term
**Avoid:** synonym-one, synonym-two
A definition of at most two sentences.
```

A term with no known synonyms still carries an `**Avoid:** —` line so
every block has the same three-field shape.

## Reading obligation

Every skill and agent reads the glossary as part of its standing
reading and, when producing prose or naming a concept, uses the
canonical term and avoids the listed synonyms. If a concept is not
listed, reuse the closest existing term — do not silently coin a new
one.

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

• Step 2: Verify the three load-bearing parts are present

Run: grep -c -e '## Format' -e 'reality, never to invent' -e 'standing reading' docs/glossary-convention.md Expected: a count of at least 3 (the format section, the record-reality rule, and the reading obligation are all present). The reality, never to invent pattern matches the unwrapped line in the verbatim content (the words record reality are split across a line break, so a record reality pattern would spuriously miss).

---

Task 2: Create docs/glossary.md (dogfood)

The plugin's own glossary, proving the format on real vocabulary. Content is lifted verbatim from the spec's primary artefact (spec lines 58-92).

Files:

• Create: docs/glossary.md

• Step 1: Write the dogfood glossary

Create docs/glossary.md with exactly this content:

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

• Step 2: Verify every entry conforms to the three-field shape

Run: grep -c '^\*\*Avoid:\*\*' docs/glossary.md Expected: 5 (one Avoid line per term: cycle, milestone, iteration, drift, hard-gate).

---

Task 3: Document the slot in docs/profile-schema.md

Add the glossary row to the paths table (single source for the "set ⇒ standing reading" semantics) and a referencing sentence in the standing_reading section.

Files:

• Modify: docs/profile-schema.md:13 (paths table) and :152 (standing_reading tail)

• Step 1: Add the glossary row after the plan_dir row

Exact-string replace this anchor:

| `plan_dir`          | string | `docs/plans`           | Where the planner skill writes plans. |

with:

| `plan_dir`          | string | `docs/plans`           | Where the planner skill writes plans. |
| `glossary`          | string | (unset)                | Canonical-nomenclature file (optional). If set, it is standing reading for every role — no separate `standing_reading.always` entry is needed; unset is a documented no-op. See `glossary-convention.md`. |

• Step 2: Add the cross-reference sentence at the end of standing_reading

Exact-string replace this anchor (end of the standing_reading section, just before ## \git``):

Entries may be shell commands as well as file paths — they are
read as opaque strings the agent should fetch / execute, e.g.
`"git log -10 --format=full"`.

## `git`

with:

Entries may be shell commands as well as file paths — they are
read as opaque strings the agent should fetch / execute, e.g.
`"git log -10 --format=full"`.

A set `paths.glossary` is implicitly appended to every role's
`always` list — it does not need its own entry here. The slot's
authoritative semantics live at the `paths` row above.

## `git`

• Step 3: Verify both edits landed

Run: grep -c 'glossary' docs/profile-schema.md Expected: a count of 2 (the new paths table row line, and the one new sentence line in the standing_reading section). grep -c counts matching lines, so the table row counts once even though it names the glossary twice.

---

Task 4: Add the commented slot to templates/project-profile.yml

Files:

• Modify: templates/project-profile.yml:9 (paths block)

• Step 1: Insert the commented glossary line after plan_dir

Exact-string replace this anchor:

  spec_dir: docs/specs
  plan_dir: docs/plans
  # design_ledger: design/INDEX.md       # optional

with:

  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

• Step 2: Verify the commented slot is present

Run: grep -c 'glossary: docs/glossary.md' templates/project-profile.yml Expected: 1.

---

Task 5: Add the standing-reading sentence to docs/agent-template.md

Files:

• Modify: docs/agent-template.md:125 (Standing reading list section)

• Step 1: Append the paths.glossary sentence to the standing-reading paragraph

Exact-string replace this anchor:

and passes the resolved list to the agent via the carrier. The
agent's body says, prosaically: "Read everything in the standing
reading list before doing anything else."

The agent file itself does not hardcode file paths.

with:

and passes the resolved list to the agent via the carrier. The
agent's body says, prosaically: "Read everything in the standing
reading list before doing anything else."

A set `paths.glossary` is implicitly part of `always`, so every role
reads the project glossary without a per-role entry (see
`profile-schema.md` § `paths`).

The agent file itself does not hardcode file paths.

• Step 2: Verify the sentence landed

Run: grep -c 'paths.glossary' docs/agent-template.md Expected: 1.

---

Task 6: Add the standing-reading sentence to docs/pipeline.md

pipeline.md does not currently mention standing reading; the natural home is the tail of the "Pipeline configuration" section, which already cross-references the profile.

Files:

• Modify: docs/pipeline.md:178 (end of Pipeline configuration)

• Step 1: Append the glossary sentence after the configuration cross-reference

Exact-string replace this anchor (the final line of the file):

See `profile-schema.md` for the syntax.

with:

See `profile-schema.md` for the syntax.

If the profile sets `paths.glossary`, that file is standing reading
for every role — the canonical-nomenclature source every skill and
agent consults (see `glossary-convention.md`). Unset, it is a no-op.

• Step 2: Verify the sentence landed

Run: grep -c 'paths.glossary' docs/pipeline.md Expected: 1.

---

Task 7: Add the cross-reference pointer to boss/SKILL.md

Boss gets a pointer to the convention's write-rule in two places: the loop (Step 4) and the Cross-references list. No rule text is duplicated.

Files:

• Modify: boss/SKILL.md (Step 4 loop area; Cross-references section)

• Step 1: Add the write-rule pointer after the Step-4 decision bullets

Exact-string replace this anchor:

  fieldtest green and stays a deliberate manual act (see
  `../docs/pipeline.md` § Milestone-close gate).

### Step 5 — On done-state: Notify

with:

  fieldtest green and stays a deliberate manual act (see
  `../docs/pipeline.md` § Milestone-close gate).

If a term-drift is resolved during the loop — two names collapsed to
one, or a settled term not yet listed — record it in the project
glossary per `../docs/glossary-convention.md`: record reality, never
invent. This is the only glossary write authority outside the user.

### Step 5 — On done-state: Notify

• Step 2: Add the Cross-references bullet

Exact-string replace this anchor:

- **Queue:** the URL configured under `git.issue_tracker.url` in
  the profile; CLI command at `git.issue_tracker.list_cmd`.
- **Downstream skills dispatched:** `../brainstorm`,

with:

- **Queue:** the URL configured under `git.issue_tracker.url` in
  the profile; CLI command at `git.issue_tracker.list_cmd`.
- **Glossary write-rule:** `../docs/glossary-convention.md` —
  record-reality discipline for the only autonomous glossary writer.
- **Downstream skills dispatched:** `../brainstorm`,

• Step 3: Verify both pointers landed

Run: grep -c 'glossary-convention.md' boss/SKILL.md Expected: 2.

---

Final acceptance sweep

• Step 1: Confirm all spec acceptance criteria are covered

Run: ls docs/glossary.md docs/glossary-convention.md && grep -l 'glossary' docs/profile-schema.md templates/project-profile.yml docs/agent-template.md docs/pipeline.md boss/SKILL.md Expected: both new files listed, and all five modified files reported as containing glossary.