plan: glossary integration
Task-by-task plan for the glossary-integration spec. Seven tasks plus a final sweep: create docs/glossary-convention.md and the dogfooded docs/glossary.md, document the paths.glossary slot in profile-schema.md, add the commented slot to the project-profile template, wire one standing-reading sentence each into agent-template.md and pipeline.md, and point boss/SKILL.md at the convention's write-rule. Docs-only cycle: no test runner, so each task closes on a grep presence assertion calibrated against verified zero baselines. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,418 @@
|
||||
# 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):
|
||||
|
||||
````markdown
|
||||
# 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 'record reality' -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).
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user