From 0d60bb38d6e71a873b199f03b4d243b5cf5f1574 Mon Sep 17 00:00:00 2001 From: Brummel Date: Fri, 29 May 2026 15:10:56 +0200 Subject: [PATCH] docs: README section on keeping a profile current Documents that profile slots are versioned with the plugin, not the project: optional slots degrade to documented no-ops when absent, so an out-of-date profile silently skips the gates a new slot powers. Tells maintainers to skim the template's commented blocks and the schema after a plugin update, and gives a concrete retrofit recipe for `spec_validation` (the slot the compound-hallucination hardening added) and the three gates it powers. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index b4d0b8a..b6eaa78 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,46 @@ Your project carries a small **profile** that fills the slots: See `docs/profile-schema.md` for the full schema and `templates/project-profile.yml` for a copy-and-fill starting point. +## Keeping a profile current + +Profile slots are versioned with the plugin, not with your project. +A new optional slot lands in `docs/profile-schema.md` and as a +commented-out block in `templates/project-profile.yml` — but an +existing profile does **not** gain it automatically. Every +consuming skill treats a missing optional slot as a documented +no-op, so an out-of-date profile never breaks; it just silently +skips whatever the new slot would have enabled. + +That silence cuts both ways: a profile written before a slot +existed will quietly not run the gate the slot powers, and nothing +flags it. So after pulling a plugin update, skim the commented +blocks in `templates/project-profile.yml` and the matching sections +in `docs/profile-schema.md`; any optional section your profile +lacks is a candidate to retrofit. The slot reference lives with the +plugin, never in the project — when in doubt, the schema is the +source of truth. + +### Retrofitting `spec_validation` + +The `spec_validation.parsers` slot maps a markdown fence label to +the tool that validates a spec code block of that kind. It powers +the parse gates that stop a spec from shipping code blocks that do +not parse against the live tool: + +- `brainstorm` Step 7 self-review — the parse-every-block gate +- `planner` Step 5 self-review — the parse-the-bytes-you-inline gate +- the `grounding-check` agent's code-block parse pass + +A profile written before this slot existed has no `spec_validation` +section, so all three gates are silent no-ops there. To opt in, add +the section: map each fence label your specs use (a surface +language, a JSON-against-schema block, an IR block, …) to its +`ext` + `cmd`, where `cmd` carries the `{file}` placeholder and +exits non-zero on a parse failure. A fence label with no entry is +skipped and documented, never silently trusted. See +`docs/profile-schema.md` § `spec_validation` for the shape and +`templates/project-profile.yml` for a commented example. + ## Install See `INSTALL.md`. In short: clone, run `install.sh`, then drop