@ai-agent-lead/skills 1.3.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.3.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

@@ -25,23 +25,23 @@ Grouped by role. Trigger phrases are in each skill's `description` frontmatter.
 | `system-design` | Greenfield system architecture — modules, dependency direction, seams | `docs/architecture.md` (system map) | [system-design/](./system-design/) |
 | `design` | Designing a module or public API before implementation | Guidance only — optional `docs/features/<feature>.design.md` for non-trivial shapes | [design/](./design/) |
 | `improve-codebase-architecture` | Finding deepening opportunities — turning shallow modules into deep ones | Numbered candidate list, optional ADR / CONTEXT.md updates | [improve-codebase-architecture/](./improve-codebase-architecture/) |
-| `code-hygiene` | Line/function-level coding discipline (boring, naming, YAGNI, rule of 3, locality) | Guidance only — applied as a lens during `simplify` and `pr-review` | [code-hygiene/](./code-hygiene/) |
 | `zoom-out` | User-invoked: ask for higher-level context when unfamiliar with an area | Map of relevant modules and callers in `CONTEXT.md` vocabulary | [zoom-out/](./zoom-out/) |
 
+The `code-hygiene` line-level lens is no longer a routable skill — it lives at [`formats/CODE-HYGIENE.md`](./formats/CODE-HYGIENE.md) and is applied during `simplify` and `pr-review` §3f.
+
 ### Implementation
 
 | Skill | Trigger | Produces | Location |
 | --- | --- | --- | --- |
 | `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
 
 | Skill | Trigger | Produces | Location |
 | --- | --- | --- | --- |
-| `sync-check` | Before pr-review or after refactor | Terminology/ADR drift report | [sync-check/](./sync-check/) |
 | `prod-ready` | After tdd green, before merge | Verified pre-merge checklist (incl. doc drift) | [prod-ready/](./prod-ready/) |
 | `security-review` | Surface-changing work — new entry points, identity flows, authz, sensitive data, external deps | Threat model + verified controls; appended to feature doc, or `docs/security/<feature>.md` for high-stakes | [security-review/](./security-review/) |
 | `pr-review` | Reviewing someone else's PR (or self-reviewing before opening) | Structured review with severity-classified findings (blocker / suggestion / nit / question) | [pr-review/](./pr-review/) |
@@ -55,14 +55,14 @@ Orthogonal axis. The trigger-phrase index above tells you *when* a skill fires;
 | --- | --- | --- |
 | **Doc-producing** (writes a durable artifact under `docs/`) | `feature-doc`, `investigate`, `system-design`, `grill-plan`, `debug` (optional), `security-review` (optional), `verify-real-deps`, `bench`, `bootstrap` | Output survives the conversation. The discipline of writing it is the value. |
 | **Build** (writes code) | `tdd`, `tdd-rounds`, `simplify` | Diff-producing. Always behind a contract (feature doc + ACs). |
-| **Gate** (verifies before merge / tag) | `prod-ready`, `security-review`, `pr-review`, `verify-real-deps`, `sync-check` | Pre-merge or pre-tag — refuse to advance until the checklist passes. |
-| **Diagnose** (no code, no doc — just analysis) | `debug`, `zoom-out`, `sync-check` | Run *before* a build skill when the input isn't yet clear. |
+| **Gate** (verifies before merge / tag) | `prod-ready`, `security-review`, `pr-review`, `verify-real-deps` | Pre-merge or pre-tag — refuse to advance until the checklist passes. |
+| **Diagnose** (no code, no doc — just analysis) | `debug`, `zoom-out` | Run *before* a build skill when the input isn't yet clear. |
 | **Shape** (decides module / topology) | `design`, `system-design`, `improve-codebase-architecture` | Greenfield-module / greenfield-system / brownfield. Same vocabulary ([`LANGUAGE.md`](./LANGUAGE.md)). |
-| **Lens** (applied during other skills, not invoked alone) | `code-hygiene`, `caveman` | Principles you carry into any turn to maintain quality or efficiency. |
+| **Lens** (applied during other skills, not invoked alone) | `caveman` skill; `code-hygiene` reference ([`formats/CODE-HYGIENE.md`](./formats/CODE-HYGIENE.md)) | Principles you carry into any turn to maintain quality or efficiency. The line-level lens is a shared reference, not a routable skill. |
 
 ## Skill relationship map
 
-The 20 skills + their dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
+The skill set + its dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
 
 ```
                      ┌─────────────────────────────────────────────┐
@@ -81,7 +81,7 @@ The 20 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
    │       │              ▲                │          │     prod-ready│
    │       │              │                │          │          │   │
    │       └──────────────┘                │          │          ▼   │
-   │                                       │          │      sync-check │
+   │                                       │          │          │   │
    │   system-design ──► design (per mod) ─┘          │          │   │
    │       │                                          │          ▼   │
    │       ▼                                          │      pr-review │
@@ -97,24 +97,23 @@ The 20 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
    │       │   (when bug)  (when surface)                             │
    │                                                                  │
    │   ┌────────────── LENSES & UTILITIES ──────────────┐             │
-   │   │  code-hygiene ──► applied during simplify,    │             │
-   │   │  caveman     ──► pr-review, any code reading  │             │
+   │   │  code-hygiene (formats/) -> line-level lens    │             │
+   │   │  caveman -> token lens, any code reading       │             │
    │   │                                                │             │
-   │   │  zoom-out ──► interrupts any workflow,        │             │
+   │   │  zoom-out -> interrupts any workflow,          │             │
    │   │              maps unfamiliar areas             │             │
    │   └────────────────────────────────────────────────┘             │
    └──────────────────────────────────────────────────────────────────┘
 ```
 
-**Seven things the map shows:**
+**Six things the map shows:**
 
-1. `code-hygiene`, `caveman`, and `zoom-out` are not nodes in any flow — they're lenses / utilities applied across.
+1. `caveman` and `zoom-out` are not nodes in any flow — they're a lens / utility applied across. The `code-hygiene` line-level lens is the same idea, now a shared reference ([`formats/CODE-HYGIENE.md`](./formats/CODE-HYGIENE.md)) rather than a routable skill.
 2. `grill-plan` is the only skill invoked from three upstreams (`investigate`, `feature-doc`, `improve-codebase-architecture`) — it's the shared pressure-test step.
 3. `tdd-rounds` is the only multi-callee orchestrator — dispatches `design`, `tdd`, `simplify`, `prod-ready`, `verify-real-deps` to Builders.
-4. `pr-review` is the reviewer-side mirror of `prod-ready` — Section 7 doc-drift covered in both.
-5. `sync-check` sits before `pr-review` as a final terminology and ADR audit.
-6. `system-design` and `improve-codebase-architecture` are duals — same [LANGUAGE.md](./LANGUAGE.md), greenfield vs brownfield.
-7. The shared substrate ([LANGUAGE.md](./LANGUAGE.md), [formats/](./formats/), [TRIGGERS.md](./TRIGGERS.md)) is referenced everywhere — never copy-paste the content into a skill.
+4. `pr-review` is the reviewer-side mirror of `prod-ready` — the Section 7 / §3e doc-drift audit is single-sourced in [`formats/DOC-DRIFT-AUDIT.md`](./formats/DOC-DRIFT-AUDIT.md) (the former `sync-check` skill) and run from both sides.
+5. `system-design` and `improve-codebase-architecture` are duals — same [LANGUAGE.md](./LANGUAGE.md), greenfield vs brownfield.
+6. The shared substrate ([LANGUAGE.md](./LANGUAGE.md), [formats/](./formats/), [TRIGGERS.md](./TRIGGERS.md)) is referenced everywhere — never copy-paste the content into a skill.
 
 
 ## Workflows
@@ -135,12 +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/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`, and (lazily) `feature-doc`.
+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

@@ -2,10 +2,14 @@
 
 Canonical scaffold for every skill in this set. Copy the body below into a new `<skill-name>/SKILL.md`, fill it in, then prune sections that genuinely don't apply (rather than leaving placeholders).
 
+**Before you create one:** apply the test in [ADR-0003](../docs/adr/0003-lenses-as-shared-references.md). A discipline applied only *inside* other skills — a lens or diagnostic never invoked on its own — belongs in [`formats/`](formats/) as a shared reference, not a `SKILL.md`. A `SKILL.md` is earned by a routable phase a user or another skill invokes directly.
+
 The order is load-bearing. Claude scans top-to-bottom — `When to use` / `When to skip` should hit early so routing is decided before the reader gets to the body.
 
 ## 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`).
@@ -28,6 +32,8 @@ The `description` is the routing signal. It should:
 
 A `description` that names only the happy path will route falsely. Always name what to skip.
 
+**Optional frontmatter.** Add `disable-model-invocation: true` for a user-only utility that should never auto-fire (e.g. `zoom-out`); the skill then runs only on explicit invocation. No other keys are read by the harness — `name` and `description` are the whole routing contract. Don't add decorative metadata (`complexity`, `expected_duration`, etc.); it isn't consumed and only drifts.
+
 ## Canonical body shape
 
 ```md
@@ -50,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>
 
@@ -90,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. |
@@ -98,7 +104,7 @@ A `description` that names only the happy path will route falsely. Always name w
 
 ## Voice and length
 
-- **Body length matches role**, not importance. Teaching skills run long (debug, security-review, tdd). Orchestration / utility / lens skills run short (tdd-rounds, simplify, code-hygiene). Don't pad an orchestration skill to match a teaching skill — it adds noise.
+- **Body length matches role**, not importance. Teaching skills run long (debug, security-review, tdd). Orchestration / utility skills run short (tdd-rounds, simplify, caveman). Don't pad an orchestration skill to match a teaching skill — it adds noise.
 - **No hedging.** "Sometimes consider maybe doing X" is dead text. Pick a recommendation.
 - **No corporate voice.** Direct sentences. The reader is a fast-reading senior engineer or an LLM, not an executive.
 - **Cite paths**: `path:line` or `[link](relative/path.md)`. Don't say "see the auth module"; say `src/auth/session.go:42`.

package/skills/TRIGGERS.md

@@ -13,7 +13,7 @@ If a phrase appears in multiple rows, the disambiguation column names how to cho
 | "before any non-trivial feature", "let's spec this out", "write a feature doc" | [`feature-doc`](feature-doc/SKILL.md) | Skip for typo / dep bump / pure refactor. |
 | "grill me on this", "stress-test this plan", "walk me through this", "is this consistent with our model" | [`grill-plan`](grill-plan/SKILL.md) | A plan exists; you want it pressure-tested. |
 | "benchmark", "performance test", "measure latency", "profile" | [`bench`](bench/SKILL.md) | Performance verification. |
-| "is the naming right?", "does this match our glossary?", "audit terminology", "sync check", "context audit" | [`sync-check`](sync-check/SKILL.md) | Before `pr-review` or after refactor. |
+| "is the naming right?", "does this match our glossary?", "audit terminology", "sync check", "context audit" | doc-drift audit ([`formats/DOC-DRIFT-AUDIT.md`](formats/DOC-DRIFT-AUDIT.md)) | The former `sync-check` skill — now a shared reference. Run standalone, or from `prod-ready` §7 / `pr-review` §3e. |
 
 ## Design & architecture
 
@@ -22,7 +22,7 @@ If a phrase appears in multiple rows, the disambiguation column names how to cho
 | "system architecture", "module boundaries", "service boundaries", "how should I structure this system", "draw the architecture", "topology" | [`system-design`](system-design/SKILL.md) | Greenfield, multi-module. For single-module work → `design`. For reorganising an existing codebase → `improve-codebase-architecture`. |
 | "how should I structure this", "deep modules", "testability", "API design", "design this module" | [`design`](design/SKILL.md) | Single module / public API, NEW code. For existing code → `improve-codebase-architecture`. |
 | "improve architecture", "find refactoring opportunities", "consolidate", "deepen these modules", "make this more testable" | [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) | EXISTING code, cross-module. For local single-module refactor → `design` or just refactor inline. |
-| "simpler", "boring", "naming", "YAGNI", "premature abstraction", "over-engineered", "clean this up at line level" | [`code-hygiene`](code-hygiene/SKILL.md) | Lens, not phase — applies during simplify, pr-review, or whenever you re-read code. |
+| "simpler", "boring", "naming", "YAGNI", "premature abstraction", "over-engineered", "clean this up at line level" | [`code-hygiene`](formats/CODE-HYGIENE.md) lens (via `simplify`) | A shared reference, not a routable skill — applies during `simplify`, `pr-review` §3f, or whenever you re-read code. |
 | "I'm lost", "give me higher-level context", "zoom out", "I don't know this area" | [`zoom-out`](zoom-out/SKILL.md) | User-invoked utility (`disable-model-invocation`). |
 
 ## Utilities & efficiency
@@ -55,7 +55,7 @@ Some phrases overlap. Pick by the disambiguator:
 
 - **"design"** alone — almost always [`design`](design/SKILL.md). If the user means "system design", that phrase routes to [`system-design`](system-design/SKILL.md).
 - **"refactor"** — [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) for cross-module; [`design`](design/SKILL.md) or just inline edits for one-module shape; [`simplify`](simplify/SKILL.md) for end-of-round line-level cleanup.
-- **"clean up"** — [`code-hygiene`](code-hygiene/SKILL.md) as a lens; [`simplify`](simplify/SKILL.md) as the end-of-round action; [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) if the cleanup is structural.
+- **"clean up"** — the [`code-hygiene`](formats/CODE-HYGIENE.md) lens; [`simplify`](simplify/SKILL.md) as the end-of-round action; [`improve-codebase-architecture`](improve-codebase-architecture/SKILL.md) if the cleanup is structural.
 - **"test"** — [`tdd`](tdd/SKILL.md) for writing tests against new behavior; [`debug`](debug/SKILL.md) when the test you'd write isn't obvious yet (root cause unclear); [`simplify`](simplify/SKILL.md)'s lens 4 for assessing existing tests.
 - **"ship"** — [`prod-ready`](prod-ready/SKILL.md) for the gate; [`verify-real-deps`](verify-real-deps/SKILL.md) for tagged release with third-party APIs.
 

package/skills/WORKFLOWS.md

@@ -1,6 +1,6 @@
 # Workflows
 
-How the 20 skills compose into the common paths users actually walk.
+How the skill set composes into the common paths users actually walk.
 
 The skills aren't a flat menu — they form a workflow with branching. This file maps the canonical paths so you can see where to enter, what to expect, and what produces what.
 
@@ -32,7 +32,7 @@ Got a task? Pick by what you have in front of you:
 │ Surface-changing work (auth, public │ /security-review (gate, runs     │
 │   API, sensitive data, new entry pt)│  alongside Workflow 1/2/6)       │
 ├─────────────────────────────────────┼──────────────────────────────────┤
-│ Audit terminology or ADR compliance │ /sync-check (gate)               │
+│ Audit terminology or ADR compliance │ doc-drift audit (DOC-DRIFT-AUDIT)│
 ├─────────────────────────────────────┼──────────────────────────────────┤
 │ Lost in unfamiliar area, mid-task   │ /zoom-out  (utility, anytime)    │
 └─────────────────────────────────────┴──────────────────────────────────┘
@@ -73,9 +73,7 @@ For a single-package feature with a manageable acceptance-criteria count.
             │
             ▼
        prod-ready  ──── 7-section checklist
-            │
-            ▼
-       sync-check  ──── terminology and ADR audit
+            │             (§7 = doc-drift audit: terminology + ADR + doc-map)
             │
             ▼
        (optional) pr-review  ── self-check against the diff before opening
@@ -96,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  │
@@ -115,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  │
    └──────────┬───────────────┘
               │
               ▼
@@ -334,7 +332,7 @@ A few things that happen across all workflows:
 
 3. **`design` doesn't have a workflow of its own** — it's a sub-step inside Workflow 1, 2, and 4. Always paired with `tdd` (or implicitly with `tdd-rounds`). Optional sibling artifact `docs/features/<name>.design.md` when the module shape is non-trivial.
 
-4. **`code-hygiene` is a lens, not a phase.** Apply it during the simplify sweep that follows TDD green, during `pr-review`, or whenever you re-read code and pause to understand it. Especially relevant in Workflows 1, 2, 4, and 5.
+4. **`code-hygiene` is a lens, not a phase** — and now a shared reference ([`formats/CODE-HYGIENE.md`](./formats/CODE-HYGIENE.md)), not a routable skill. Apply it during the simplify sweep that follows TDD green, during `pr-review` §3f, or whenever you re-read code and pause to understand it. Especially relevant in Workflows 1, 2, 4, and 5.
 
 5. **`caveman` is an efficiency lens.** Apply it whenever token optimization is needed, particularly in Builder reports or long sessions. It doesn't change the workflow but compresses the communication.
 
@@ -352,9 +350,9 @@ A few things that happen across all workflows:
 
 12. **Vocabulary is shared.** All architecture-talking skills (`design`, `system-design`, `improve-codebase-architecture`, `pr-review`, `grill-plan`) read from [`skills/LANGUAGE.md`](./LANGUAGE.md). Format references (ADRs, CONTEXT.md) live in [`skills/formats/`](./formats/). Domain vocabulary (Customer, Order, etc.) lives in `docs/CONTEXT.md`. Keep them distinct.
 
-13. **Bootstrap mode for greenfield repos** is documented in one place — [`grill-plan/BOOTSTRAP.md`](./grill-plan/BOOTSTRAP.md). `feature-doc` and `system-design` defer there rather than re-explaining the rules.
+13. **Bootstrap mode for greenfield repos** is documented in one place — [`bootstrap/BOOTSTRAP.md`](./bootstrap/BOOTSTRAP.md). `feature-doc`, `system-design`, and `improve-codebase-architecture` defer there rather than re-explaining the rules.
 
-14. **`simplify` is the end-of-slice / end-of-round sweep.** Runs after every `tdd` slice goes green; in `tdd-rounds`, lands as its own commit per [`tdd-rounds/COMMITS.md` rule 4](./tdd-rounds/COMMITS.md). Applies the `code-hygiene` lens to the changed files, plus a test-relevance check. Distinct from `code-hygiene` (the lens) and from `improve-codebase-architecture` (the structural escalation when simplify finds bigger issues).
+14. **`simplify` is the end-of-slice / end-of-round sweep.** Runs after every `tdd` slice goes green; in `tdd-rounds`, lands as its own commit per [`tdd-rounds/COMMITS.md` rule 4](./tdd-rounds/COMMITS.md). Applies the [`code-hygiene`](./formats/CODE-HYGIENE.md) lens to the changed files, plus a test-relevance and telemetry check. Distinct from the `code-hygiene` lens reference itself and from `improve-codebase-architecture` (the structural escalation when simplify finds bigger issues).
 
 15. **Artifacts accumulate in `docs/`:**
 
@@ -363,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,8 +1,6 @@
 ---
 name: bench
-description: Performance benchmarking discipline. Measures latency, throughput, and records baseline environments. Triggered by phrases like "benchmark", "performance test", "measure latency".
-complexity: medium
-expected_duration: 30 minutes
+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
@@ -19,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
@@ -31,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,8 +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".
-complexity: low
-expected_duration: 10 minutes
+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
@@ -24,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,8 +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.
-complexity: low
-expected_duration: 5 minutes
+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/debug/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: debug
 description: Disciplined reproduction, isolation, and hypothesis-testing for non-trivial bugs — runs BEFORE `tdd` when the failing assertion isn't yet known. Use when the user reports a bug whose root cause is not obvious from the symptom — triggered by phrases like "it's broken", "this is failing", "intermittent", "flaky", "regression", "not sure why", "production issue", "doesn't work in <env>". Skip for typos, clear stack traces with one-step fixes, or bugs whose fix is obvious from reading the message. Pairs with `tdd` (downstream — the failing test crystallises once the bug is reproduced) and `zoom-out` (upstream, when the area is unfamiliar).
-complexity: high
-expected_duration: 45 minutes
 ---
 
 # Debug

package/skills/design/ILLEGAL-STATES.md

@@ -4,6 +4,15 @@ The single highest-leverage application of the type system: prevent bad states a
 
 The pattern: take a runtime invariant ("a verified user must have a verification timestamp") and encode it in the types. The bad state can no longer be constructed.
 
+## This is simplicity, not ceremony — bounded by "boring beats clever"
+
+If you prefer simple code, this principle is *on your side*. Constructive typing **deletes** code: the `if (!x) throw` guards repeated across call sites, the `// invariant:` comments that rot. Making a bad state uncompilable is fewer moving parts than defending against it at runtime, not more.
+
+The tension people feel is with *defensive* typing — casts, assertions, validate-everywhere, generics for their own sake. That's not this. The rule that keeps the two apart is [`CODE-HYGIENE`](../formats/CODE-HYGIENE.md) Principle 1, applied at the type level:
+
+- **Reach for the boring tools first:** sum types / discriminated unions, a narrow domain type where the distinction earns its keep (`Email` vs raw `string`), parse-at-the-boundary then trust, exhaustive matching.
+- **Treat the clever tools as advanced:** phantom types, conditional / mapped-type gymnastics, deep generics, type-level programming. Reach for them only when the invariant is load-bearing *and* the boring encoding can't carry it — the same "is this worth the puzzle?" bar as any clever code. When in doubt, validate at construction (see "Limits" below) instead.
+
 ## Example 1 — Optional fields that should move together
 
 WEAK
@@ -34,7 +43,9 @@ type User =
 
 Each state names itself. Pattern matching is exhaustive. The fourth (incoherent) state cannot compile.
 
-## Example 2 — Phantom types for pipeline stages
+## Example 2 — Phantom types for pipeline stages *(advanced — reach for only when load-bearing)*
+
+Phantom types are the "clever" end of the spectrum: powerful, but a tax on every reader. Use this only when the *ordering* invariant is genuinely load-bearing (a security-sensitive sanitize-before-persist flow) and the cost of getting the order wrong is high. For an ordinary pipeline, a sum type plus validation at the boundary is the boring, sufficient choice.
 
 When the same data flows through stages (e.g. `RawInput` → `Validated` → `Sanitized`), encode the stage in the type:
 

package/skills/design/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: design
 description: Module and interface design principles — deep modules and testable interfaces. Use when designing a NEW module, class, or public API; deciding what to expose vs hide; reviewing an interface before implementation; or when the user asks "how should I structure this", mentions "deep modules", "testability", or "API design". Use for NEW code shape; for finding deepening opportunities in EXISTING code, use `improve-codebase-architecture`. Skip for trivial glue, getters/setters, or single-call wrappers. Pairs with the tdd skill — good design is what makes TDD pleasant.
-complexity: medium
-expected_duration: 20 minutes
 ---
 
 # Module and Interface Design
@@ -14,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.
@@ -118,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:
@@ -136,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