@ai-agent-lead/skills 1.4.0 → 1.5.0

package/README.md

@@ -16,6 +16,36 @@ The goal: turn engineering discipline from something I have to enforce into some
 
 - [`skills/`](./skills/) — the skill set. See [`skills/README.md`](./skills/README.md) for the index, the role/trigger taxonomy, and how skills compose into workflows.
 
+## What the skills produce
+
+Run the skill set on a project and a self-documenting `docs/` tree accumulates. Every file is created **lazily** — on first use, never up front — and carries [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) frontmatter, so the whole tree is a consumable knowledge bundle. The canonical registry of doc kinds is [`skills/formats/OKF.md`](./skills/formats/OKF.md) §2; the artifacts table in [`skills/WORKFLOWS.md`](./skills/WORKFLOWS.md) maps each kind to the workflow step that emits it. The shape the tree converges to:
+
+```
+repo-root/
+├── CHANGELOG.md                    ← prod-ready          (the bundle's OKF log)
+└── docs/                           ← the OKF bundle root
+    ├── index.md                    ← bundle listing / feature manifest (no frontmatter)
+    ├── CONTEXT.md                  ← bootstrap, grill-plan          [type: context]
+    ├── CONTEXT-MAP.md              ← bootstrap (multi-context repos) [type: context-map]
+    ├── CONVENTIONS.md              ← bootstrap                      [type: convention]
+    ├── architecture.md             ← system-design                  [type: architecture]
+    ├── known-issues.md             ← verify-real-deps, tdd-rounds   [type: known-issues]
+    ├── adr/
+    │   └── NNNN-<slug>.md          ← grill-plan, improve-codebase-architecture  [type: adr]
+    ├── features/
+    │   ├── <name>.md               ← feature-doc                    [type: feature]
+    │   ├── <name>.design.md        ← design (optional)              [type: design]
+    │   └── <name>.state.md         ← tdd-rounds (one per feature)   [type: state]
+    ├── research/
+    │   └── <topic>.md              ← investigate, debug             [type: research]
+    ├── security/
+    │   └── <feature>.md            ← security-review (high-stakes)  [type: security]
+    └── benchmarks/
+        └── <feature>.md            ← bench                          [type: benchmark]
+```
+
+The three feature siblings — `<name>.md` (the contract), `<name>.design.md` (the module shape), `<name>.state.md` (the round-by-round state) — share a stem so a feature's contract, design, and progress sit together. There is no global state file; `docs/index.md` is the manifest.
+
 ## Installation
 
 You can install all the skills in this repository directly using `npx`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-agent-lead/skills",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Install AI agent skills for Claude Code, Codex, Antigravity, and OpenCode",
   "main": "bin/install.js",
   "bin": {

package/skills/README.md

@@ -35,8 +35,8 @@ The `code-hygiene` line-level lens is no longer a routable skill — it lives at
 | --- | --- | --- | --- |
 | `debug` | Non-trivial bug whose root cause isn't obvious — runs **before** `tdd` | Reproduction + named root cause; optional `docs/research/<bug>.md` | [debug/](./debug/) |
 | `tdd` | Implementing a feature or fixing a bug, test-first | Test-first code | [tdd/](./tdd/) |
-| `tdd-rounds` | Multi-round TDD orchestration via Builder sub-agents (≥10 ACs / multi-package) | Builder briefs + reports + `docs/STATE.md` | [tdd-rounds/](./tdd-rounds/) |
-| `simplify` | End-of-slice / end-of-round sweep — reuse, quality, efficiency, test relevance | Tightened diff + a separate `simplify` commit | [simplify/](./simplify/) |
+| `tdd-rounds` | Multi-round TDD orchestration via Builder sub-agents (≥10 ACs / multi-package) | Builder briefs + reports + `docs/features/<name>.state.md` | [tdd-rounds/](./tdd-rounds/) |
+| `simplify` | End-of-slice / end-of-round sweep — reuse, quality, efficiency, test relevance, telemetry | Tightened diff + a separate `simplify` commit | [simplify/](./simplify/) |
 
 ### Pre-merge gates & review
 
@@ -134,15 +134,22 @@ The skills compose into canonical workflows (greenfield feature, large feature,
 
 - [`formats/ADR-FORMAT.md`](./formats/ADR-FORMAT.md) — ADR template, numbering, when-to-write criteria.
 - [`formats/CONTEXT-FORMAT.md`](./formats/CONTEXT-FORMAT.md) — `CONTEXT.md` structure, single-vs-multi-context layout, minimal example.
+- [`formats/CONVENTION-FORMAT.md`](./formats/CONVENTION-FORMAT.md) — `CONVENTIONS.md` structure (branches, commits, naming, code style). Seeded by `bootstrap`.
 - [`formats/CODE-HYGIENE.md`](./formats/CODE-HYGIENE.md) — the line-level lens (boring code, naming, YAGNI, rule of 3, locality, comments, constants placement). Applied during `simplify` and `pr-review` §3f.
 - [`formats/DOC-DRIFT-AUDIT.md`](./formats/DOC-DRIFT-AUDIT.md) — the terminology / ADR / doc-map audit. Run from `prod-ready` §7 (author), `pr-review` §3e (reviewer), or standalone (the former `sync-check`).
-- [`formats/OKF.md`](./formats/OKF.md) — frontmatter contract for produced `docs/` files. [`formats/STYLE-comments.md`](./formats/STYLE-comments.md) — the comment bar.
+- [`formats/OKF.md`](./formats/OKF.md) — frontmatter contract for produced `docs/` files. [`formats/STYLE-COMMENTS.md`](./formats/STYLE-COMMENTS.md) — the comment bar.
+- [`formats/OBSERVABILITY.md`](./formats/OBSERVABILITY.md) — the observability-by-design lens (what to instrument, log levels, telemetry placement). Applied during `simplify`'s telemetry pass.
+- [`formats/PERSONAS.md`](./formats/PERSONAS.md) — design-exploration personas (the Minimalist, the Extensible, …) for assigning distinct lenses to parallel sub-agents. Used by `improve-codebase-architecture`'s interface-design step.
 
 Used by `grill-plan`, `improve-codebase-architecture`, `system-design`, `investigate`, `simplify`, `prod-ready`, `pr-review`, and (lazily) `feature-doc`.
 
 ## Conventions
 
-- **File naming.** UPPERCASE for skill-level reference docs (`SKILL.md`, `LANGUAGE.md`, `MOTIVATION.md`, `*-FORMAT.md`, etc.) — Claude loads these as supporting context. lowercase for templates inside `<skill>/templates/` — skeletons to copy and fill in.
+- **File naming — the one rule (canonical; other docs link here).** Case signals *role*:
+  - **`UPPERCASE-KEBAB.md`** — *standing references you read by a fixed name.* All skill machinery and supporting docs under `skills/` (`SKILL.md`, `LANGUAGE.md`, `WORKFLOWS.md`, per-skill `BOOTSTRAP.md` / `COMMITS.md` / `TESTS.md` / …, and everything in [`formats/`](./formats/)); **plus** the produced bundle's repo-wide **orientation / governance** layer — the files you read to *speak, navigate, and track the whole repo*: `docs/CONTEXT.md`, `docs/CONTEXT-MAP.md`, `docs/CONVENTIONS.md`, and root `CHANGELOG.md`.
+  - **`lowercase-kebab.md`** — *fill-in skeletons and produced work-products.* Templates in `<skill>/templates/`; and every doc a skill emits as a deliverable — `docs/architecture.md`, `docs/known-issues.md`, and all instances under `adr/`, `features/`, `research/`, `security/`, `benchmarks/` (named after their subject).
+  - **Reserved:** `index.md` and `log.md` stay lowercase — OKF reserves them.
+  - **The test:** *does this file govern how you read / name / track the whole repo (UPPERCASE), or is it something a skill produced — a map, a contract, a decision, a ledger, a manifest (lowercase)?* `docs/architecture.md` is lowercase because it's a produced deliverable, like a feature doc — not part of the orientation layer the way `CONTEXT.md` is.
 - Output artifacts live under `docs/` in the repo root, never inside `.claude/`.
 - Status enums, frontmatter shape, and cross-doc linking rules are in [`docs/CONVENTIONS.md`](../docs/CONVENTIONS.md).
 - Domain vocabulary is in [`docs/CONTEXT.md`](../docs/CONTEXT.md). Terms there beat synonyms invented at the keyboard.

package/skills/SKILL-TEMPLATE.md

@@ -8,6 +8,8 @@ The order is load-bearing. Claude scans top-to-bottom — `When to use` / `When
 
 ## Naming and placement
 
+The full file-naming rule (skills **and** produced docs) is single-sourced in [`README.md` §Conventions](README.md#conventions). The essentials for a skill directory:
+
 - File path: `skills/<skill-name>/SKILL.md` (lowercase, hyphenated directory).
 - Supporting reference docs in the same directory go UPPERCASE (`MOTIVATION.md`, `DEEPENING.md`, etc.).
 - Templates that callers fill in go in `<skill-name>/templates/` and stay lowercase (`feature-template.md`).
@@ -54,7 +56,7 @@ A `description` that names only the happy path will route falsely. Always name w
 - <case where a different skill is the right answer; name that skill>
 - <case where no skill is needed at all — "just fix it">
 
-## Phases  (or **Process**, or **Workflow** — pick one and stick to it)
+## Phases  (or **Process**, **Workflow**, **Steps**, **Principles**, **The N lenses** — pick the one descriptive heading that fits the skill, and use only one)
 
 ### 1. <Phase name — verb-leading>
 
@@ -94,7 +96,7 @@ A `description` that names only the happy path will route falsely. Always name w
 | Why this skill exists | optional | Include for *teaching* skills (discipline being taught). Skip for *orchestration* and *utility* skills. |
 | When to use | yes | Body section, not just frontmatter. Frontmatter alone is too easy to skim past. |
 | When to skip | yes | Body section. Mirror the description — explicit, not implied. |
-| Phases / Process / Workflow | yes | Pick one heading. Don't mix. |
+| The "how it works" body | yes | Its **position** (after `When to skip`, before `Anti-patterns`) is canonical; its **name** is not. Use the heading that fits — `Phases`, `Process`, `Workflow`, `Steps`, `Principles`, `The N lenses`. One such section (a set of same-kind sub-sections — e.g. `Principle 1…N` — counts as one); don't mix different kinds. |
 | Anti-patterns | recommended | Skip only if the skill is so simple there are none. |
 | Pairing with other skills | yes | At minimum name 1 upstream and 1 downstream. |
 | Done when | yes | Verifiable conditions, not vibes. |

package/skills/WORKFLOWS.md

@@ -94,7 +94,7 @@ For a single-package feature with a manageable acceptance-criteria count.
         │
         ▼
    ┌──────── Round N ────────┐
-   │   Parent writes brief    │  ◄─── self-contained, references docs/STATE.md
+   │   Parent writes brief    │  ◄─── self-contained, references docs/features/<name>.state.md
    │              │           │
    │              ▼           │
    │   Builder is dispatched  │
@@ -113,7 +113,7 @@ For a single-package feature with a manageable acceptance-criteria count.
    │              ▼           │
    │   Parent reviews diff,   │
    │   runs tests independently,
-   │   appends to STATE.md    │
+   │   appends to state file  │
    └──────────┬───────────────┘
               │
               ▼
@@ -361,15 +361,18 @@ A few things that happen across all workflows:
     | `docs/features/<name>.md` | `feature-doc` | One per feature |
     | `docs/features/<name>.design.md` | `design` (optional) | One per feature with non-trivial module shape |
     | `docs/research/<topic>.md` | `investigate`, `debug` (optional) | One per investigation or non-trivial bug |
-    | `docs/adr/<n>-<topic>.md` | `grill-plan`, `improve-codebase-architecture` | One per architectural decision |
-    | `docs/CONTEXT.md` | `grill-plan`, `improve-codebase-architecture` (inline updates) | One per repo / context |
+    | `docs/adr/<n>-<topic>.md` | `grill-plan`, `bootstrap`, `investigate` (handoff), `improve-codebase-architecture` | One per architectural decision |
+    | `docs/CONTEXT.md` | `bootstrap` (seed), `grill-plan`, `improve-codebase-architecture` (inline updates) | One per repo / context |
+    | `docs/CONTEXT-MAP.md` | `bootstrap` | One per repo with >1 bounded context |
+    | `docs/CONVENTIONS.md` | `bootstrap` | One per repo; structure & process rules |
     | `docs/architecture.md` | `system-design` | One per system (the system map) |
-    | `docs/features/<name>/state/snapshot.md` | `tdd-rounds` parent | Living snapshot per feature (target end-state per ADR-0001; not yet wired through `tdd-rounds` skill text) |
-    | `docs/features/<name>/state/rounds/*.md` | `tdd-rounds` Builder | Immutable round logs (target end-state per ADR-0001) |
-    | `docs/STATE.md` | `tdd-rounds` parent | Currently the single running summary; ADR-0001 demotes it to a global manifest after migration. |
+    | `docs/features/<name>.state.md` | `tdd-rounds` parent | One living, append-only state file per feature — `## Round N` sections, sibling to the contract and design note (per ADR-0001). |
     | `docs/security/<feature>.md` | `security-review` (high-stakes only) | One per surface-changing feature where a feature-doc section isn't enough |
     | `docs/benchmarks/<feature>.md` | `bench` | One per performance-critical feature |
-    | `docs/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record); also holds follow-up tracking for accepted-but-unimplemented ADRs. |
+    | `docs/known-issues.md` | `verify-real-deps`, `tdd-rounds` | One per repo (post-mortem record); also holds follow-up tracking for accepted-but-unimplemented ADRs. |
+    | `docs/index.md` | doc-drift audit (maintained; reserved OKF name, no frontmatter) | Bundle manifest — lists every produced doc |
     | `CHANGELOG.md` | `prod-ready` Section 7 | One per repo; `[Unreleased]` accumulates between releases. |
     All `docs/` files are created **lazily** — they don't have to pre-exist for a workflow to run. The skill creates them on first use.
 
+    The canonical registry of produced-doc kinds and their `type` values is [`formats/OKF.md` §2](./formats/OKF.md); this table maps each kind to the workflow step that emits it.
+

package/skills/bench/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bench
-description: Performance benchmarking discipline. Measures latency, throughput, and records baseline environments. Triggered by phrases like "benchmark", "performance test", "measure latency".
+description: Performance benchmarking discipline — measures latency and throughput against a recorded baseline environment. Triggered by phrases like "benchmark", "performance test", "measure latency", "profile". Skip when there's no performance AC or suspected regression. Pairs with `feature-doc` (the perf AC it verifies) and `prod-ready` (the pre-merge gate the result feeds).
 ---
 
 # Benchmark
@@ -17,6 +17,12 @@ Performance claims are often "vibes-based" or measured on a developer's machine
 - Identifying regressions or improvements after a major refactor.
 - Profiling hot paths to guide optimization.
 
+## When to skip
+
+- No performance AC and no suspected regression — don't benchmark for its own sake.
+- Cold paths users rarely hit — measure where the load actually is.
+- Functional-only changes with no latency / throughput / memory claim to verify.
+
 ## Process
 
 ### 1. Establish Baseline
@@ -29,7 +35,19 @@ Run the same test against the changed code. Ensure identical environment conditi
 
 ### 3. Record Findings
 
-Create a report in `docs/benchmarks/<feature>.md` using the template.
+Create a report in `docs/benchmarks/<feature>.md` using [`templates/benchmark-report.md`](templates/benchmark-report.md).
+
+## Anti-patterns
+
+- **Baseline-free numbers.** "40ms faster" with nothing to compare against — record the before-measurement and the environment, or the figure is meaningless.
+- **Noisy-machine benchmarking.** Measuring on a laptop mid-build — pin hardware, load, and concurrency and keep them identical across runs.
+- **Reporting the warmup.** Quoting the first cold-cache iteration — discard warmup and report steady-state percentiles (p50 / p95 / p99).
+
+## Pairing with other skills
+
+- **[`feature-doc`](../feature-doc/SKILL.md)** — runs *before*. The performance AC it pins is what this skill verifies.
+- **[`tdd`](../tdd/SKILL.md)** — runs *alongside* for functional correctness; `bench` covers the perf AC tests can't assert.
+- **[`prod-ready`](../prod-ready/SKILL.md)** — runs *after*. The benchmark result feeds the pre-merge gate for performance-sensitive work.
 
 ## Done when
 

package/skills/bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bootstrap
-description: Initializes a greenfield repository. Creates the docs/ directory, the initial CONTEXT.md, and the first ADR. Triggered by phrases like "new project", "initialize", "bootstrap".
+description: Initializes a greenfield repository — creates the docs/ directory, the initial CONTEXT.md, an optional CONVENTIONS.md, and the first ADR. Triggered by phrases like "new project", "initialize", "bootstrap". Skip when docs/CONTEXT.md and a docs/ structure already exist. Pairs with `feature-doc`, `system-design`, and `improve-codebase-architecture` (which defer here for greenfield setup, per BOOTSTRAP.md) and `grill-plan` (bootstrap mode seeds CONTEXT.md / ADRs lazily during grilling).
 ---
 
 # Bootstrap
@@ -22,24 +22,35 @@ Starting from a blank slate often leads to inconsistent documentation structure.
 
 ## Process
 
-### 1. Initialize docs/
+Everything below is created **lazily** — only when first needed (see [`BOOTSTRAP.md`](BOOTSTRAP.md)). No file or directory is required to pre-exist.
 
-Create the standard directory structure:
-- `docs/`
-- `docs/adr/`
-- `docs/features/`
-- `docs/research/`
+### 1. Seed CONTEXT.md
 
-### 2. Seed CONTEXT.md
+Ask the user for 3-7 core domain terms. Create `docs/CONTEXT.md` using the canonical format ([`../formats/CONTEXT-FORMAT.md`](../formats/CONTEXT-FORMAT.md)). The `docs/` directory comes into being with it.
 
-Ask the user for 3-7 core domain terms. Create `docs/CONTEXT.md` using the canonical format.
+### 2. Seed CONVENTIONS.md (optional)
 
-### 3. Record ADR-0000
+If the repo has decided structure / process rules worth recording (branch model, commit style, file naming), create `docs/CONVENTIONS.md` using [`../formats/CONVENTION-FORMAT.md`](../formats/CONVENTION-FORMAT.md). Skip if nothing is decided yet — like everything else, it's created lazily.
 
-If any major architectural decisions are made during initialization, record them in `docs/adr/0000-architectural-overview.md`.
+### 3. Record the first ADR (only if warranted)
+
+If a major architectural decision is made during initialization — and it meets all three [`ADR-FORMAT`](../formats/ADR-FORMAT.md) criteria (hard-to-reverse / surprising / real trade-off) — record it as `docs/adr/0001-<slug>.md`. ADR numbering starts at `0001` and is monotonic; create `docs/adr/` lazily with it.
+
+Other directories (`docs/features/`, `docs/research/`, …) are created by the skills that first write into them, not here.
+
+## Anti-patterns
+
+- **Eager scaffolding.** Creating empty `docs/features/`, `docs/research/`, etc. up front — directories are born when a skill first writes into them, not here.
+- **Implementation terms in `CONTEXT.md`.** Seeding the glossary with framework / storage nouns instead of the domain terms a domain expert would recognise.
+- **Forcing ADR 0001.** Writing an ADR when no decision meets all three criteria (hard-to-reverse / surprising / real trade-off) — skip it; ADRs are earned.
+
+## Pairing with other skills
+
+- **[`feature-doc`](../feature-doc/SKILL.md)** / **[`system-design`](../system-design/SKILL.md)** / **[`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md)** — defer *here* for greenfield setup rather than re-explaining the rules (see [`BOOTSTRAP.md`](BOOTSTRAP.md)).
+- **[`grill-plan`](../grill-plan/SKILL.md)** — runs *after* in bootstrap mode, seeding `CONTEXT.md` / ADRs lazily as terms and decisions crystallise.
 
 ## Done when
 
-- `docs/` directory exists with the required subdirectories.
 - `docs/CONTEXT.md` is seeded with core domain terms.
-- (Optional) `docs/adr/0000-architectural-overview.md` exists.
+- (Optional) `docs/CONVENTIONS.md` exists if the repo has decided structure / process rules.
+- (Optional) `docs/adr/0001-<slug>.md` exists if a qualifying decision was made.

package/skills/caveman/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: caveman
-description: Ultra-concise communication utility for token optimization. Use when the user mentions "caveman mode", "be concise", "save tokens", or "ooga booga". Strips articles, pleasantries, and filler words to maximize efficiency. Skip when the user explicitly requests professional or detailed explanations.
+description: Ultra-concise communication utility for token optimization. Use when the user mentions "caveman mode", "be concise", "save tokens", or "ooga booga". Strips articles, pleasantries, and filler words to maximize efficiency. Skip when the user explicitly requests professional or detailed explanations. Pairs with `simplify` (the quality / efficiency kin) and applies inside `tdd-rounds` Builder reports.
 ---
 
 # Caveman Mode (Token Optimizer)

package/skills/design/SKILL.md

@@ -12,6 +12,8 @@ Principles that make code easier to understand, change, and test.
 3. **Illegal states unrepresentable** — encode runtime invariants in the type system.
 4. **Functional core, imperative shell** — pure logic at the center, side effects at the edges.
 
+The architecture vocabulary here — **module**, **interface**, **depth** (deep / shallow), **seam** — is canonical in [`LANGUAGE.md`](../LANGUAGE.md); this skill teaches how to *apply* it and links there rather than redefining it.
+
 ## When to use
 
 - Before writing a new module, class, or public function.
@@ -116,6 +118,13 @@ If TDD feels painful — tests need elaborate setup, mocks of internals, or peek
 - `design` decides *what the interface should be*.
 - `tdd` decides *how to build it test-first*.
 
+## Pairing with other skills
+
+- **[`system-design`](../system-design/SKILL.md)** — runs *before*. It says which modules should exist; `design` shapes each one's interface.
+- **[`tdd`](../tdd/SKILL.md)** — runs *after* (see *How this connects to TDD* above). `design` decides the interface; `tdd` builds it test-first.
+- **[`tdd-rounds`](../tdd-rounds/SKILL.md)** — *invokes* `design` on rounds that introduce a new package or non-trivial interface.
+- **[`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md)** — the *brownfield* sibling: same vocabulary, but for deepening existing modules rather than shaping new ones.
+
 ## Done when
 
 The interface is small enough that you can describe it in one sentence, and the testability rules hold:
@@ -134,4 +143,4 @@ Most of the time `design` is guidance only — the shape lives in the code that
 - The interface decisions are load-bearing for downstream rounds of `tdd-rounds`.
 - A `prod-ready` reviewer will need to verify "module map / public-interface signatures / test boundaries" against something explicit (per [prod-ready Section 7](../prod-ready/SKILL.md)).
 
-When captured, save as a sibling to the feature doc: `docs/features/<feature>.design.md`, opening with OKF frontmatter (`type: design`) per [`skills/formats/OKF.md`](../formats/OKF.md). Skip when the interface is small enough that the code is the design.
+When captured, save as a sibling to the feature doc: `docs/features/<feature>.design.md` — copy [`templates/design-note.md`](templates/design-note.md), which opens with OKF frontmatter (`type: design`) per [`skills/formats/OKF.md`](../formats/OKF.md). Skip when the interface is small enough that the code is the design.

package/skills/design/templates/design-note.md

@@ -0,0 +1,47 @@
+---
+type: design
+title: "<Feature Name> — design note"
+description: <one sentence — the module shape this note pins down>
+tags: [<area>, design]
+timestamp: YYYY-MM-DD
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md (`type: design`).
+     Save as a sibling to the contract: docs/features/<name>.design.md. -->
+
+# <Feature Name> — design note
+
+The module shape decided before code. Sibling to the contract (`<name>.md`); the round-by-round log lives in `<name>.state.md`.
+
+## Modules
+
+| Module | Responsibility (one sentence) | Depth |
+| --- | --- | --- |
+| `<name>` | <what it does> | deep / shallow-but-justified |
+
+## Public interface
+
+What every caller and test must know — types, invariants, error modes, ordering, required config. Not just the signatures.
+
+```
+<the signature(s) — the seam callers cross>
+```
+
+## What's hidden behind the seam
+
+The complexity the interface keeps out of callers' heads. If nothing is hidden, the module is shallow — reconsider the shape.
+
+## Interface options considered
+
+- **Option A — <name>:** <one line>. Chosen / rejected because <reason>.
+- **Option B — <name>:** <one line>. Chosen / rejected because <reason>.
+
+## Test boundaries
+
+- What is exercised through the public interface (the seam).
+- Which collaborators are real vs faked, and where the fake sits.
+
+## Related
+
+- Contract: [`<name>.md`](./<name>.md)
+- ADRs: [`ADR-NNNN`](../adr/NNNN-slug.md) — load-bearing constraints this shape respects

package/skills/feature-doc/SKILL.md

@@ -66,13 +66,6 @@ STRONG
 
 The strong list translates 1:1 into tests. The weak list translates into vibes.
 
-## Definition of Done for the doc
-
-- [ ] Problem stated in 2–3 sentences.
-- [ ] At least one acceptance criterion in Given / When / Then form.
-- [ ] Non-goals listed (or explicitly "none — see scope in Problem").
-- [ ] Reviewed by at least one other person.
-
 ## Anti-patterns
 
 - **AC list as task list.** "Implement the login form" is a task; "Given a user with valid credentials, when they POST `/login`, then they receive a session cookie" is an AC. Tasks belong in your TODO; ACs belong in the contract.
@@ -91,6 +84,17 @@ The strong list translates 1:1 into tests. The weak list translates into vibes.
 - **`security-review`** — runs *alongside* `tdd` when the feature is surface-changing (new entry point, identity flow, sensitive data path).
 - **`prod-ready`** — runs after green, against this doc. Section 7 catches doc-drift if behavior shifted during implementation.
 
+## Done when
+
+- A feature branch (e.g. `feat/<short-name>` or `fix/<short-name>`) is checked out and the contract doc is committed on it, **not on `main`**.
+- `docs/features/<short-name>.md` exists with all four required sections.
+- The doc opens with OKF frontmatter (`type: feature`) per [`skills/formats/OKF.md`](../formats/OKF.md).
+- Problem is stated in 2–3 sentences.
+- ACs are testable Given / When / Then statements.
+- Non-Goals is non-empty (or explicitly "none — see scope in Problem").
+- One reviewer has signed off.
+- Status is `Approved` and the next skill (`tdd` / `tdd-rounds` / `grill-plan` / `security-review`) is named.
+
 ## Handoff
 
 Once the doc is reviewed and ACs are stable:
@@ -101,13 +105,3 @@ Once the doc is reviewed and ACs are stable:
   - Project has `CONTEXT.md` and/or ADRs → run [`grill-plan`](../grill-plan/SKILL.md) to stress-test against the existing model.
   - No `CONTEXT.md` or ADRs yet → run [`investigate`](../investigate/SKILL.md) to map options first; or, if the plan is chosen but vocabulary is fuzzy, run `grill-plan` in [bootstrap mode](../bootstrap/BOOTSTRAP.md).
 - **Hard-to-reverse / surface-changing** (new auth flow, public API, sensitive data flow) → run [`security-review`](../security-review/SKILL.md) alongside `tdd` / `tdd-rounds`.
-
-## Done when
-
-- A feature branch (e.g. `feat/<short-name>` or `fix/<short-name>`) is checked out and the contract doc is committed on it, **not on `main`**.
-- `docs/features/<short-name>.md` exists with all four required sections.
-- The doc opens with OKF frontmatter (`type: feature`) per [`skills/formats/OKF.md`](../formats/OKF.md).
-- ACs are testable Given / When / Then statements.
-- Non-Goals is non-empty (or explicitly "none — see scope in Problem").
-- One reviewer has signed off.
-- Status is `Approved` and the next skill (`tdd` / `tdd-rounds` / `grill-plan` / `security-review`) is named.

package/skills/formats/CODE-HYGIENE.md

@@ -61,7 +61,7 @@ Related code lives close together. Don't split a system by *type of code* (`cont
 
 ## Principle 6: Comments earn their keep
 
-**The bar:** [`STYLE-comments.md`](STYLE-comments.md). Apply it *while writing*, not only during the `simplify` sweep.
+**The bar:** [`STYLE-COMMENTS.md`](STYLE-COMMENTS.md). Apply it *while writing*, not only during the `simplify` sweep.
 
 **Default: NONE.** If you're unsure whether a comment earns its line, delete it. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot — and only if the next reader would otherwise reattempt the rejected alternative.
 

package/skills/formats/CONTEXT-FORMAT.md

@@ -98,9 +98,9 @@ An item on a User's personal list — text plus a done flag. Owned by exactly on
 
 ## Single vs multi-context repos
 
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
+**Single context (most repos):** One `docs/CONTEXT.md`.
 
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+**Multiple contexts:** A `docs/CONTEXT-MAP.md` lists the contexts, where they live, and how they relate to each other:
 
 ```md
 ---
@@ -128,8 +128,8 @@ timestamp: 2026-05-22
 
 The skill infers which structure applies:
 
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+- If `docs/CONTEXT-MAP.md` exists, read it to find contexts
+- If only `docs/CONTEXT.md` exists, single context
+- If neither exists, create `docs/CONTEXT.md` lazily when the first term is resolved
 
 When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/formats/CONTEXT-MAP-FORMAT.md

@@ -1,6 +1,17 @@
-# Context Map Format
+# CONTEXT-MAP.md Format
 
-Used when a single `CONTEXT.md` becomes a bottleneck (>100 terms).
+`CONTEXT-MAP.md` is the index for a repo with **more than one bounded context** — each context has its own `CONTEXT.md`, and the map lists them and how they relate. One per repo, at `docs/CONTEXT-MAP.md`. It is a produced doc, so it opens with OKF frontmatter per [`OKF.md`](OKF.md) (`type: context-map`).
+
+## When you need one
+
+- **More than one bounded context** in the repo (e.g. `ordering/`, `billing/`, `fulfillment/`, each with its own glossary). That is the real trigger.
+- A single `CONTEXT.md` growing past ~100 terms is usually a *symptom* of this — one file is hiding several contexts. Split them rather than scrolling one giant glossary.
+
+A single-context repo needs only `docs/CONTEXT.md`; don't create a map for it.
 
 ## Structure
-- Links to sub-contexts.
+
+The full frontmatter shape and a worked example live in [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md) (the "Single vs multi-context repos" section) — this kind shares that spec. In short:
+
+- A `## Contexts` list, one bullet per context, linking its `CONTEXT.md`.
+- A `## Relationships` section naming how the contexts interact (domain events, shared types, synchronous calls).

package/skills/formats/CONVENTION-FORMAT.md

@@ -0,0 +1,40 @@
+# CONVENTIONS.md Format
+
+`CONVENTIONS.md` records the repo's structure and process rules — the things a contributor (human or agent) must follow but can't infer from the code: branch model, commit style, file naming, code-style anchors. One per repo, at `docs/CONVENTIONS.md`. It is a produced doc, so it opens with OKF frontmatter per [`OKF.md`](OKF.md) (`type: convention`).
+
+Created lazily by [`bootstrap`](../bootstrap/SKILL.md) — seed only the rules the repo has actually decided; don't pad with defaults nobody chose.
+
+## Template
+
+```md
+---
+type: convention
+title: Conventions
+description: How documentation and code are structured in this repository.
+tags: [conventions]
+timestamp: YYYY-MM-DD
+---
+
+# Conventions
+
+## Documentation Artifacts
+- Lazy creation; OKF frontmatter on every produced doc; file-naming rule.
+
+## Branches
+- <e.g. code lands on `feat/<name>`; `main` receives merges, not commits>.
+
+## Commits
+- <e.g. Conventional Commits; any repo-specific prefixes>.
+
+## Code Style
+- <pointers to the repo's formatter / linter and comment discipline>.
+
+## Terminology
+- Adhere to `docs/CONTEXT.md`; stale terminology is a bug.
+```
+
+## Rules
+
+- **Record decisions, not aspirations.** A convention nobody follows is worse than none.
+- **Link, don't restate.** Point at `docs/CONTEXT.md`, the [naming rule](../README.md#conventions), and [`STYLE-COMMENTS.md`](STYLE-COMMENTS.md) rather than copying them.
+- **Keep it short.** If a section needs more than a few bullets, it's probably an ADR or a design note, not a convention.

package/skills/formats/DOC-DRIFT-AUDIT.md

@@ -10,7 +10,7 @@ This is a **shared reference**, run from three places with the same checks but a
 
 Files don't need to pre-exist — `docs/adr/`, `CONTEXT.md`, design notes are created lazily when the first relevant change appears. If a doc type isn't relevant to this work, write `n/a` — explicit beats implicit.
 
-## The six checks
+## The seven checks
 
 One question per doc type: *did this work change X? Then update Y.*
 
@@ -20,6 +20,7 @@ One question per doc type: *did this work change X? Then update Y.*
 4. **Changed acceptance criteria** → the feature doc reflects what was actually built. Silently-dropped or silently-added behavior is the most common drift class — fix here, don't kick to a follow-up.
 5. **User-visible change** → `CHANGELOG.md` has an entry under `[Unreleased]`, grouped by `Added / Changed / Fixed / Removed`. Skip only for formatter-only / lint-only / test-only / internal-refactor-with-no-behavior-change / dep-bump-with-no-runtime-impact diffs. (Overlaps but is **not identical** to `feature-doc`'s skip list, which also waives the *doc* for typo fixes and one-line config tweaks. A typo fix can still merit a one-liner here.)
 6. **New or changed produced doc under `docs/`** → it opens with OKF frontmatter carrying a non-empty `type` from [`OKF.md`](OKF.md) §2. A produced doc with no `type` breaks bundle conformance.
+7. **New or removed produced doc under `docs/`** → [`docs/index.md`](../../docs/index.md) (the bundle manifest) gains or loses its entry. A produced doc that exists but isn't listed is invisible to progressive disclosure; a listed file that was deleted is a dangling entry.
 
 ## ADR consistency (read alongside check 1)
 

package/skills/formats/OKF.md

@@ -2,7 +2,7 @@
 
 Every document a skill writes under `docs/` carries [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF v0.1) YAML frontmatter. That makes the whole `docs/` tree a consumable OKF **bundle** — a directory of markdown "concept" files any OKF-aware tool, agent, or static server can ingest, with no change to how we author.
 
-This is the substrate every doc-producing skill consumes (`feature-doc`, `investigate`, `bootstrap`, `grill-plan`, `bench`, `tdd-rounds`, `verify-real-deps`, …) — the way `STYLE-comments.md` is the substrate for comments. The per-skill templates carry a filled-in frontmatter block; this doc is the contract behind them.
+This is the substrate every doc-producing skill consumes (`feature-doc`, `investigate`, `bootstrap`, `grill-plan`, `bench`, `tdd-rounds`, `verify-real-deps`, …) — the way `STYLE-COMMENTS.md` is the substrate for comments. The per-skill templates carry a filled-in frontmatter block; this doc is the contract behind them.
 
 > **Why OKF and not our own scheme:** the format is vendor-neutral and additive — the only hard requirement is a non-empty `type`, and consumers preserve unknown keys. We get interop for free without giving up any of our existing structure.
 
@@ -41,26 +41,30 @@ OKF does not register types centrally — producers pick descriptive, self-expla
 
 | Doc kind | `type` | Produced by | Lives in |
 | --- | --- | --- | --- |
-| Architecture decision record | `adr` | `bootstrap`, `grill-plan`, `investigate` handoff | `docs/adr/NNNN-slug.md` |
+| Architecture decision record | `adr` | `grill-plan`, `bootstrap`, `investigate` (handoff), `improve-codebase-architecture` | `docs/adr/NNNN-slug.md` |
 | Feature contract | `feature` | `feature-doc` | `docs/features/<name>.md` |
 | Module / interface design note | `design` | `design` | `docs/features/<name>.design.md` |
-| Research / options note | `research` | `investigate` | `docs/research/<topic>.md` |
-| Ubiquitous-language map | `context` | `bootstrap`, `grill-plan` | `docs/CONTEXT.md` |
-| Multi-context map | `context-map` | `bootstrap` | `CONTEXT-MAP.md` |
+| Round / feature state | `state` | `tdd-rounds` | `docs/features/<name>.state.md` |
+| Research / options note | `research` | `investigate`, `debug` | `docs/research/<topic>.md` |
+| System architecture map | `architecture` | `system-design` | `docs/architecture.md` |
+| Surface threat model | `security` | `security-review` | `docs/security/<feature>.md` |
+| Ubiquitous-language map | `context` | `bootstrap`, `grill-plan`, `improve-codebase-architecture` | `docs/CONTEXT.md` |
+| Multi-context map | `context-map` | `bootstrap` | `docs/CONTEXT-MAP.md` |
 | Repo conventions | `convention` | `bootstrap` | `docs/CONVENTIONS.md` |
-| Accepted-but-unimplemented tracker | `known-issues` | `tdd-rounds`, `verify-real-deps` | `docs/known-issues.md` |
-| Benchmark report | `benchmark` | `bench` | `docs/bench/<name>.md` |
-| Round / feature state | `state` | `tdd-rounds` | `docs/features/<name>/state/*.md` |
+| Bug ledger / accepted-but-unimplemented tracker | `known-issues` | `verify-real-deps`, `tdd-rounds` | `docs/known-issues.md` |
+| Benchmark report | `benchmark` | `bench` | `docs/benchmarks/<feature>.md` |
 
 Pick the closest existing value before inventing a new one. A new doc kind adds a row here in the same change that first emits it.
 
+**This table is the canonical registry of produced-doc kinds.** [`WORKFLOWS.md`](../WORKFLOWS.md) (the artifacts table) and the root `README.md` (the bundle tree) map these kinds to workflow steps and locations — they link here rather than redefining the set. A kind that isn't in this table isn't a produced kind; add it here first.
+
 ---
 
 ## 3. Bundle conventions
 
 `docs/` is the bundle root. Two filenames are **reserved** by OKF and never used for a concept:
 
-- **`index.md`** — a directory listing for progressive disclosure. No frontmatter. Entries are `* [Title](relative-url) — short description`, optionally grouped under `## Section` headings. Add `docs/index.md` once the bundle has more than a couple of files; keep it current as docs are added.
+- **`index.md`** — a directory listing for progressive disclosure. No frontmatter. Entries are `* [Title](relative-url) — short description`, optionally grouped under `## Section` headings. Add `docs/index.md` once the bundle has more than a couple of files. Its currency is owned by the doc-drift audit (check 7), run from `prod-ready` §7 (author) and `pr-review` §3e (reviewer) — a produced doc missing from the manifest is a finding.
 - **`log.md`** — a date-grouped changelog. Our repo's root **`CHANGELOG.md`** already plays this role (Keep-a-Changelog, newest first); treat it as the bundle's log rather than adding a second file. An OKF consumer tolerates the absence of `log.md`.
 
 **Cross-references** between docs are plain markdown links. OKF accepts two forms: **bundle-relative** (begin with `/`, resolved from the bundle root: `/adr/0001-distributed-state.md`) and **relative** (`../known-issues.md`). Bundle-relative is the more move-stable form, but this repo's docs use ordinary **relative** links by convention (they also reach files outside the bundle, like `../skills/formats/OKF.md`), and both are equally valid. A link asserts a *relationship* — the kind (supersedes, depends-on, refines) is carried by the surrounding prose, not the link. Broken links are tolerated, not malformed.

package/skills/formats/{STYLE-comments.md → STYLE-COMMENTS.md}

@@ -61,7 +61,7 @@ When a kept comment cites the project record, use **exactly one** of these forms
 | TDD round + acceptance criterion       | `RN AC-M`               | `R6 AC-3`, `R1 AC-12`                   |
 | Tagged round + batch within a release  | `vX.Y RNbM`             | `v0.3 R1b2`, `v0.8 R2b1`                |
 | Dated verification                     | `<kind> YYYY-MM-DD`     | `smoke-test 2026-05-09`                 |
-| Feature state snapshot                 | `snapshot §SECTION`     | `snapshot §"Invariants"`                |
+| Feature state                          | `state §SECTION`        | `state §"Invariants"`                   |
 
 **Avoid** (normalize to the table above):
 - `Round 6`, `round-six`, `R 6` → `R6`

package/skills/grill-plan/SKILL.md

@@ -3,6 +3,10 @@ name: grill-plan
 description: Grilling session that stress-tests a chosen plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use AFTER a direction has been picked (post-`investigate` or post-`feature-doc`), when the user wants to pressure-test the plan — triggered by phrases like "grill me on this", "stress-test this plan", "walk me through this", "is this consistent with our model". Skip if the direction is still being explored — use `investigate` instead.
 ---
 
+# Grill Plan
+
+Stress-test a chosen plan against the existing domain model — interview-style — resolving each decision one at a time and capturing the sharpened terms and ADRs in `CONTEXT.md` / `docs/adr/` as they crystallise.
+
 ## When to use
 
 - A direction has been picked (post-`investigate` or post-`feature-doc`) and you want to pressure-test it against the existing model.

package/skills/improve-codebase-architecture/INTERFACE-DESIGN.md

@@ -22,7 +22,7 @@ Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radi
 
 Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. 
 
-**Assign each sub-agent a specific persona from [`skills/design/PERSONAS.md`](../design/PERSONAS.md)** (e.g., Agent 1 is "The Minimalist", Agent 2 is "The Extensible").
+**Assign each sub-agent a specific persona from [`skills/formats/PERSONAS.md`](../formats/PERSONAS.md)** (e.g., Agent 1 is "The Minimalist", Agent 2 is "The Extensible").
 
 Include both [skills/LANGUAGE.md](../LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.