@ai-agent-lead/skills 1.1.0 → 1.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 A library of Claude Code skills that encode engineering discipline so Claude follows it by default.
 
+**Website:** [AgentLead.Dev](https://AgentLead.Dev)
+
 ## Why
 
 Out of the box Claude writes code competently, but shipping well needs more than that: investigate before building, design the interface before writing, test-first, review at PR boundaries, and verify before merge.
@@ -19,7 +21,7 @@ The goal: turn engineering discipline from something I have to enforce into some
 You can install all the skills in this repository directly using `npx`:
 
 ```bash
-npx github:ai-agent-lead/skills
+npx @ai-agent-lead/skills
 ```
 
 ### Options and Customization

package/package.json

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

package/skills/README.md

@@ -41,6 +41,7 @@ Grouped by role. Trigger phrases are in each skill's `description` frontmatter.
 
 | 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/) |
@@ -52,16 +53,16 @@ Orthogonal axis. The trigger-phrase index above tells you *when* a skill fires;
 
 | Role | Skills | What they have in common |
 | --- | --- | --- |
-| **Doc-producing** (writes a durable artifact under `docs/`) | `feature-doc`, `investigate`, `system-design`, `grill-plan`, `debug` (optional), `security-review` (optional), `verify-real-deps` | Output survives the conversation. The discipline of writing it is the value. |
+| **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` | Pre-merge or pre-tag — refuse to advance until the checklist passes. |
+| **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. |
 | **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` | Five principles you carry into `simplify`, `pr-review`, and any code-reading session. |
+| **Lens** (applied during other skills, not invoked alone) | `code-hygiene`, `caveman` | Principles you carry into any turn to maintain quality or efficiency. |
 
 ## Skill relationship map
 
-The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
+The 20 skills + their dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
 
 ```
                      ┌─────────────────────────────────────────────┐
@@ -80,16 +81,16 @@ The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
    │       │              ▲                │          │     prod-ready│
    │       │              │                │          │          │   │
    │       └──────────────┘                │          │          ▼   │
-   │                                       │          │     pr-review │
+   │                                       │          │      sync-check │
    │   system-design ──► design (per mod) ─┘          │          │   │
    │       │                                          │          ▼   │
-   │       ▼                                          │  verify-real-deps │
+   │       ▼                                          │      pr-review │
    │  docs/architecture.md                            │          │   │
    │                                                  │          ▼   │
-   │   improve-codebase-architecture ─────────────────┘     [merge]  │
-   │       ▲                                                          │
-   │       │                                                          │
-   │   tdd-rounds (orchestrator) ── dispatches Builders ──────────────│
+   │   improve-codebase-architecture ─────────────────┘  verify-real-deps│
+   │       ▲                                                     │   │
+   │       │                                                     ▼   │
+   │   tdd-rounds (orchestrator) ── dispatches Builders ────── [merge]│
    │       │      ▲   ▲     ▲                                         │
    │       │      │   │     │                                         │
    │       │   debug security-review                                  │
@@ -97,7 +98,7 @@ The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
    │                                                                  │
    │   ┌────────────── LENSES & UTILITIES ──────────────┐             │
    │   │  code-hygiene ──► applied during simplify,    │             │
-   │   │                   pr-review, any code reading  │             │
+   │   │  caveman     ──► pr-review, any code reading  │             │
    │   │                                                │             │
    │   │  zoom-out ──► interrupts any workflow,        │             │
    │   │              maps unfamiliar areas             │             │
@@ -105,14 +106,16 @@ The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
    └──────────────────────────────────────────────────────────────────┘
 ```
 
-**Six things the map shows:**
+**Seven things the map shows:**
 
-1. `code-hygiene` and `zoom-out` are not nodes in any flow — they're lenses / utilities applied across.
+1. `code-hygiene`, `caveman`, and `zoom-out` are not nodes in any flow — they're lenses / utilities applied across.
 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. `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.
+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.
+
 
 ## Workflows
 
@@ -153,4 +156,3 @@ Used by `grill-plan`, `improve-codebase-architecture`, `system-design`, `investi
 5. Add the skill to **both** index tables above (by trigger phase AND by role).
 6. Add an entry to [TRIGGERS.md](./TRIGGERS.md) for routing.
 7. Update [WORKFLOWS.md](./WORKFLOWS.md) if the skill participates in a canonical workflow or as a cross-workflow pattern.
-. Update [WORKFLOWS.md](./WORKFLOWS.md) if the skill participates in a canonical workflow or as a cross-workflow pattern.

package/skills/TRIGGERS.md

@@ -25,6 +25,12 @@ If a phrase appears in multiple rows, the disambiguation column names how to cho
 | "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. |
 | "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
+
+| Phrase / situation | Routes to | Disambiguator |
+| --- | --- | --- |
+| "caveman mode", "be concise", "save tokens", "ooga booga" | [`caveman`](caveman/SKILL.md) | Token optimization lens. |
+
 ## Implementation
 
 | Phrase / situation | Routes to | Disambiguator |

package/skills/WORKFLOWS.md

@@ -1,6 +1,6 @@
 # Workflows
 
-How the 16 skills compose into the common paths users actually walk.
+How the 20 skills compose 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,6 +32,8 @@ 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)               │
+├─────────────────────────────────────┼──────────────────────────────────┤
 │ Lost in unfamiliar area, mid-task   │ /zoom-out  (utility, anytime)    │
 └─────────────────────────────────────┴──────────────────────────────────┘
 ```
@@ -73,6 +75,9 @@ For a single-package feature with a manageable acceptance-criteria count.
        prod-ready  ──── 7-section checklist
             │
             ▼
+       sync-check  ──── terminology and ADR audit
+            │
+            ▼
        (optional) pr-review  ── self-check against the diff before opening
             │
             ▼
@@ -331,25 +336,27 @@ A few things that happen across all workflows:
 
 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.
 
-5. **`debug` runs *before* `tdd` for non-trivial bugs.** Workflow 5b makes this explicit. The reproduction from `debug` becomes the failing test for `tdd`. Skip for bugs whose root cause is obvious from the trace (Workflow 5a).
+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.
 
-6. **`security-review` is a gate, not a workflow.** Fires when a change is **surface-changing** — new entry point, identity / session / token flow, authorization logic, sensitive-data path, new external dependency, secrets handling. Runs alongside `design` and `tdd` in Workflows 1, 2, 4, 5a, 5b, 6 whenever those criteria hit. Not a substitute for `prod-ready` Section 3 — both run when the surface changes.
+6. **`debug` runs *before* `tdd` for non-trivial bugs.** Workflow 5b makes this explicit. The reproduction from `debug` becomes the failing test for `tdd`. Skip for bugs whose root cause is obvious from the trace (Workflow 5a).
 
-7. **`pr-review` is a utility workflow.** Runs when reviewing someone else's PR. Also runs (lighter form) as a self-check before opening the PR. The `tdd-rounds` parent's per-round verification borrows from it.
+7. **`security-review` is a gate, not a workflow.** Fires when a change is **surface-changing** — new entry point, identity / session / token flow, authorization logic, sensitive-data path, new external dependency, secrets handling. Runs alongside `design` and `tdd` in Workflows 1, 2, 4, 5a, 5b, 6 whenever those criteria hit. Not a substitute for `prod-ready` Section 3 — both run when the surface changes.
 
-8. **`prod-ready` is the universal pre-merge gate** for Workflows 1, 2, 4, and sometimes 5. Single exit ramp before opening a PR.
+8. **`pr-review` is a utility workflow.** Runs when reviewing someone else's PR. Also runs (lighter form) as a self-check before opening the PR. The `tdd-rounds` parent's per-round verification borrows from it.
 
-9. **`verify-real-deps` fires whenever a workflow ends in a tagged release that touches a third-party API.** Most commonly that's Workflow 2 (large feature → tag), but it also applies when Workflow 1, 4, or 6 culminates in a release whose code path talks to an upstream you don't control. It does **not** fire for pure-internal services with database-only state, or for continuous-deploy environments that don't tag.
+9. **`prod-ready` is the universal pre-merge gate** for Workflows 1, 2, 4, and sometimes 5. Single exit ramp before opening a PR.
 
-10. **`system-design` runs once per system, not per feature.** It's the greenfield precursor to Workflows 1 and 2. Once the topology is set, individual features run their own Workflow 1 or 2 inside it.
+10. **`verify-real-deps` fires whenever a workflow ends in a tagged release that touches a third-party API.** Most commonly that's Workflow 2 (large feature → tag), but it also applies when Workflow 1, 4, or 6 culminates in a release whose code path talks to an upstream you don't control. It does **not** fire for pure-internal services with database-only state, or for continuous-deploy environments that don't tag.
 
-11. **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.
+11. **`system-design` runs once per system, not per feature.** It's the greenfield precursor to Workflows 1 and 2. Once the topology is set, individual features run their own Workflow 1 or 2 inside it.
+
+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.
 
 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).
 
-12. **Artifacts accumulate in `docs/`:**
+15. **Artifacts accumulate in `docs/`:**
 
     | Location | Produced by | Type |
     |---|---|---|
@@ -359,11 +366,12 @@ A few things that happen across all workflows:
     | `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/architecture.md` | `system-design` | One per system (the system map) |
-    | `docs/STATE.md` | `tdd-rounds` parent (append-only) | One per multi-round project |
+    | `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/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) |
+    | `docs/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record); also holds follow-up tracking for accepted-but-unimplemented ADRs. |
+    | `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.
-s/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record) |
 
-    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.

package/skills/bench/templates/benchmark-report.md

@@ -1,7 +1,16 @@
+---
+type: benchmark
+title: "Benchmark Report: <feature>"
+description: <one sentence — what was measured and the headline result>
+tags: [performance, <area>]
+timestamp: YYYY-MM-DD
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md (`type: benchmark`). -->
+
 # Benchmark Report
 
 **Feature:** <feature>
-**Date:** YYYY-MM-DD
 
 ## Environment
 - **Hardware:** <e.g., Apple M1 Max, 64GB RAM>

package/skills/caveman/SKILL.md

@@ -0,0 +1,60 @@
+---
+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
+---
+
+# Caveman Mode (Token Optimizer)
+
+The discipline of "speaking in tokens" to minimize cost and maximize context window longevity.
+
+## Why this skill exists
+
+Standard AI responses are often padded with 30-50% filler words ("Certainly," "I have completed," "As a senior engineer"). In long-running sessions or multi-round orchestration, this "politeness tax" adds up to significant cost and premature context exhaustion.
+
+## When to use
+
+- The user explicitly invokes "caveman mode" or "ooga booga".
+- The session is approaching context limits (warning from system).
+- You are operating as a Builder sub-agent where brevity is the primary mandate.
+
+## When to skip
+
+- The user asks for a detailed explanation or architectural rationale.
+- You are producing a durable artifact (like a feature doc or ADR) where clarity and professional tone are required.
+
+## Process
+
+### 1. Strip the "Fluff"
+
+Remove all conversational filler:
+- "Sure, I can help with that."
+- "I have successfully updated the file."
+- "Let me know if you need anything else."
+
+### 2. Compress the Prose
+
+Remove articles (a, an, the) and simplify verbs:
+- **Normal**: "I am updating the user controller to handle the new session timeout logic."
+- **Caveman**: "Update user controller. Handle session timeout."
+
+### 3. Bullet-Only Output
+
+Prefer short, punchy bullet points over paragraphs. One line per action.
+
+## Anti-patterns
+
+- **Losing Technical Accuracy.** Conciseness must not compromise path names, variable names, or command flags. `Update src/main.go` is good; `Fix file` is bad.
+- **Being Rude.** Caveman mode is about *token density*, not hostility. It is a technical optimization, not a personality shift.
+
+## Pairing with other skills
+
+- **[`tdd-rounds`](../tdd-rounds/SKILL.md)** — Excellent for Builder reports.
+- **[`simplify`](../simplify/SKILL.md)** — Use to report the "before/after" of a cleanup pass.
+
+## Done when
+
+- The response contains zero conversational filler.
+- All technical details remain accurate and actionable.
+- Token usage for the turn is significantly lower than a standard response.

package/skills/code-hygiene/SKILL.md

@@ -9,18 +9,19 @@ expected_duration: 5 minutes
 
 Day-to-day discipline that keeps a codebase readable, navigable, and easy to change. Smaller in scope than `design` (which shapes module interfaces) — these are line-level and function-level habits.
 
-Five principles.
+Six principles.
 
 1. **Boring code beats clever code** — prefer the obvious solution over the elegant trick.
 2. **Naming is the primary refactor** — a bad name misleads longer than a bad implementation.
 3. **YAGNI** — don't build for hypothetical futures.
 4. **Rule of 3 before extracting** — duplicate twice; extract on the third occurrence, not the second.
 5. **Locality of behavior** — related code lives together; don't split by category.
+6. **Comments earn their keep** — default NONE; keep only why-comments tied to an invariant, trade-off, or provenance the next reader would otherwise miss.
 
 ## When to use
 
 - Writing new code, line by line — keep these in mind as you type.
-- Reviewing a PR — these are five common smell categories.
+- Reviewing a PR — these are six common smell categories.
 - After `tdd` reaches green, during the [`simplify`](../simplify/SKILL.md) sweep — `code-hygiene` is the lens you apply.
 - When you read code and pause to figure out what it's doing — that pause is a smell.
 
@@ -67,8 +68,6 @@ The first occurrence is unique. The second might be coincidence. The third is a
 
 **Why**: premature abstractions calcify. Once a wrong abstraction exists, callers shape themselves to it, and rewriting becomes expensive. Three concrete copies are cheap; one wrong abstraction is not.
 
-**Smell**: a helper function with one caller, or a base class with one subclass. That's an abstraction in search of a use.
-
 ## Principle 5: Locality of behavior
 
 Related code lives close together. Don't split a system by *type of code* (`controllers/`, `services/`, `repositories/`) — split by *responsibility* (`orders/`, `billing/`, `auth/`).
@@ -77,6 +76,14 @@ Related code lives close together. Don't split a system by *type of code* (`cont
 
 **Smell**: changing one feature requires editing 5 files in 5 directories. That's a sign the structure separates *type* of code, not *responsibility*. (This is a `improve-codebase-architecture` issue at scale, but at smaller scale you can fix it inline by colocating files.)
 
+## Principle 6: Comments earn their keep
+
+**The bar:** [`skills/formats/STYLE-comments.md`](../formats/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.
+
+**Delete on sight**: WHAT-comments, "used by X" / "added for Y" caller references, banner dividers, commented-out code, in-function section headers (`// validate`, `// build response`), and docstrings on exports whose contract is obvious from the signature.
+
 ## Done when
 
 - Names communicate intent — a stranger reads them and forms the right mental model.
@@ -84,6 +91,7 @@ Related code lives close together. Don't split a system by *type of code* (`cont
 - No "in case we need it" parameters, classes, or interfaces remain.
 - Duplications either survived the 2-occurrence test (left as-is) or proved themselves at the 3rd occurrence (extracted).
 - Related code lives near related code.
+- Every surviving comment names a why, an invariant, a trade-off, or a provenance link. None restates the code.
 
 ## Pairing with other skills
 

package/skills/design/SKILL.md

@@ -136,4 +136,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`. 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`, 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.

package/skills/feature-doc/SKILL.md

@@ -106,7 +106,9 @@ Once the doc is reviewed and ACs are stable:
 
 ## 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.

package/skills/feature-doc/templates/feature-template.md

@@ -1,8 +1,20 @@
+---
+type: feature
+title: <Feature Name>
+description: <one sentence — the user pain this feature solves>
+tags: [<area>]
+timestamp: YYYY-MM-DD
+status: Draft
+owner: <name>
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md. `timestamp` is the canonical date;
+     `status`/`owner` mirror the human-facing lines below (OKF models neither). -->
+
 # <Feature Name>
 
 **Status:** Draft | Approved | In Progress | Shipped
 **Owner:** <name — primary author and point of contact for follow-up>
-**Date:** YYYY-MM-DD
 
 <!--
 Status values:

package/skills/formats/ADR-FORMAT.md

@@ -4,18 +4,28 @@ ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slu
 
 Create the `docs/adr/` directory lazily — only when the first ADR is needed.
 
+An ADR is a produced doc, so it opens with OKF frontmatter per [`OKF.md`](OKF.md) (`type: adr`).
+
 ## Template
 
 ```md
+---
+type: adr
+title: {Short title of the decision}
+description: {one sentence — what we decided and why}
+tags: [{area}]
+timestamp: YYYY-MM-DD
+status: accepted
+---
+
 # {Short title of the decision}
 
 **Status:** accepted
-**Date:** YYYY-MM-DD
 
 {1-3 sentences: what's the context, what did we decide, and why.}
 ```
 
-That's it. An ADR can be a single paragraph plus the two header lines. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+That's it. An ADR can be a single paragraph plus the frontmatter and the `Status` line. The value is in recording *that* a decision was made and *why* — not in filling out sections. The date lives in `timestamp`; don't also keep a `**Date:**` line.
 
 ## Optional sections
 

package/skills/formats/CONTEXT-FORMAT.md

@@ -1,8 +1,18 @@
 # CONTEXT.md Format
 
+`CONTEXT.md` is a produced doc, so it opens with OKF frontmatter per [`OKF.md`](OKF.md) (`type: context`; a `CONTEXT-MAP.md` uses `type: context-map`).
+
 ## Structure
 
 ```md
+---
+type: context
+title: {Context Name}
+description: {one sentence on what this context is and why it exists}
+tags: [{area}]
+timestamp: YYYY-MM-DD
+---
+
 # {Context Name}
 
 {One or two sentence description of what this context is and why it exists.}
@@ -52,6 +62,14 @@ _Avoid_: Client, buyer, account
 The opening example uses an Ordering/Billing domain to show cross-context structure. For a smaller project a `CONTEXT.md` may be just a handful of terms and no relationships:
 
 ```md
+---
+type: context
+title: Todo App
+description: Vocabulary used across internal/auth and internal/todos.
+tags: [auth, todos]
+timestamp: 2026-05-22
+---
+
 # Todo App
 
 Vocabulary used across `internal/auth` and `internal/todos`.
@@ -85,6 +103,14 @@ An item on a User's personal list — text plus a done flag. Owned by exactly on
 **Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
 
 ```md
+---
+type: context-map
+title: Context Map
+description: Lists the bounded contexts in this repo and how they relate.
+tags: [architecture]
+timestamp: 2026-05-22
+---
+
 # Context Map
 
 ## Contexts

package/skills/formats/OKF.md

@@ -0,0 +1,82 @@
+# OKF Frontmatter for Produced Docs
+
+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.
+
+> **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.
+
+---
+
+## 1. The frontmatter block
+
+Every non-reserved `.md` file under `docs/` opens with a YAML frontmatter block:
+
+```yaml
+---
+type: feature
+title: Distributed State for TDD Rounds
+description: Feature-scoped state replaces the global STATE.md to cut merge conflicts.
+tags: [tdd-rounds, state, architecture]
+timestamp: 2026-05-25
+---
+```
+
+| Field | OKF status | Rule |
+| --- | --- | --- |
+| `type` | **required** | One value from the vocabulary in §2. Non-empty. This is the only field a bundle is rejected for missing. |
+| `title` | recommended | Human-readable display name. Mirror the `# H1`. Omit only if the filename already says it. |
+| `description` | recommended | One sentence. Reuse the doc's opening sentence — don't invent a second summary. |
+| `tags` | recommended | YAML list of short cross-cutting labels. Skip rather than pad. |
+| `timestamp` | recommended | ISO 8601 date (or datetime) of the last meaningful change. This is the canonical home for the date — do **not** also keep a `**Date:**` bold line. |
+| `resource` | recommended | A URI for the underlying asset. Our docs are abstract concepts, so in practice this is usually **absent** — include it only when the doc fronts a real external resource (a dashboard, a BigQuery table, an API). |
+
+**Extension keys** are allowed and encouraged where a doc kind carries status OKF doesn't model. Our kinds keep `status:` (and `owner:` on feature docs) as extension keys *in addition to* the human-facing `**Status:**` / `**Owner:**` bold lines the skills already read. OKF consumers preserve them; our skills keep working.
+
+---
+
+## 2. The `type` vocabulary
+
+OKF does not register types centrally — producers pick descriptive, self-explanatory values and consumers tolerate unknowns. These are the values this repo's skills emit:
+
+| Doc kind | `type` | Produced by | Lives in |
+| --- | --- | --- | --- |
+| Architecture decision record | `adr` | `bootstrap`, `grill-plan`, `investigate` handoff | `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` |
+| 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` |
+
+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.
+
+---
+
+## 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.
+- **`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.
+
+**Body:** no required sections. Favor structural markdown (headings, lists, tables, fenced code) over prose — it aids both human reading and agent retrieval. The headings `# Schema`, `# Examples`, `# Citations` carry their conventional OKF meaning when present.
+
+---
+
+## 4. Conformance checklist
+
+A produced doc is OKF-conformant when:
+
+- [ ] It opens with a parseable YAML frontmatter block.
+- [ ] `type` is present and non-empty, drawn from §2 (or added there in the same change).
+- [ ] `title` mirrors the H1; `description` reuses the opening sentence; the date lives only in `timestamp`.
+- [ ] Reserved filenames (`index.md`, `log.md` / `CHANGELOG.md`) follow §3 and are **not** used for concepts.
+- [ ] Cross-links use bundle-relative (`/…`) or relative paths.
+
+This checklist is enforced at the doc-drift audits in `pr-review` (§3e) and `prod-ready` (Section 7) — a produced doc missing `type` is a finding.

package/skills/formats/STYLE-comments.md

@@ -0,0 +1,102 @@
+# Comment Style
+
+Codifies the comment discipline for this codebase. New contributors (human or agent) match what's here, rather than re-deriving conventions per package.
+
+> **Default: write NO comment.** Add one only when the WHY is non-obvious AND a future reader is likely to make the opposite assumption.
+
+The code's identifiers, types, and structure explain the *what*. A comment earns its line only when it captures something the reader cannot recover by reading the next ten lines: a constraint, an invariant, a trade-off, or a pointer to the decision record. If you're unsure whether a comment earns its keep, **delete it** — git history and the next maintainer will be fine.
+
+---
+
+## 1. Three kinds of comment we keep
+
+### 1.1 Package docstring (one per package, only when the design needs it)
+
+A package whose design choice or invariant would not be obvious from reading the primary file gets a short docstring block:
+- One-line purpose.
+- One paragraph on the design choice and its rationale.
+- The failure mode or invariant the next reader needs to know.
+
+A package that is what it says it is (a thin utility, a generated stub, a glue adapter) does not need a docstring. Don't pad.
+
+### 1.2 Docstrings on exported identifiers (only when the contract is non-obvious from the signature)
+
+Skip the docstring on getters, simple constructors, and any function whose name + types already convey the contract. Write one only when:
+- The call is **not** cheap, idempotent, or safe under concurrency, and the next reader would assume it was.
+- The function may be invoked multiple times per request (e.g. retried) and that matters.
+- A parameter or return has non-obvious zero-value or nil semantics (`0 = "unknown"`, `(nil, nil) = "not found"`).
+
+When you write one, start with the identifier name (`// Cache stores …`, not `// Stores …`).
+
+### 1.3 Invariant / constraint / trade-off / provenance (only when the alternative would otherwise be reattempted)
+
+A comment whose absence would let the next maintainer write the bug, reattempt the rejected alternative, or "fix" the deliberate choice. If the next reader would just say "OK, sure" and move on, the comment is not earning its line.
+
+- **Invariant** — `// Zero means 'unknown'` (and re-stated where the bug would bite).
+- **Constraint** — `// Selector must be cheap and side-effect-free; ServeHTTP may invoke Pick multiple times on 429 retry.`
+- **Trade-off** — `// Cold-cache choice: an account whose (pk, model) is not yet in the cache is treated as INELIGIBLE.`
+- **Provenance** — `// Manual SQL instead of ORM — see ADR-007 §"Query shape".`
+
+---
+
+## 2. Six kinds of comment we delete on sight
+
+1. **Restates the code.** `// increment i`, `// return the user`, `// loop over items`.
+2. **Commented-out code.** Git has it. Delete.
+3. **"Added for X" / "Used by Y" caller references.** These rot the day someone renames or removes the caller. Use `grep`.
+4. **Banner / ASCII-art dividers.** `// =====` and `// --- section ---`. Use a function or a file boundary, not a banner.
+5. **Stale TODO / FIXME / HACK with no owner, ticket, ADR, or date.** Either link it to a decision record or fix it now.
+6. **Section-header comments inside a function.** `// validate`, `// build response`, `// compute total`. If a function needs internal section headers, extract those sections into named functions — the function name is the comment.
+
+---
+
+## 3. Provenance grammar (canonical forms)
+
+When a kept comment cites the project record, use **exactly one** of these forms. Comments that follow the canonical grammar are greppable and stable.
+
+| Kind                                   | Canonical form          | Examples                                |
+| -------------------------------------- | ----------------------- | --------------------------------------- |
+| Architectural decision record          | `ADR-NNN §SECTION`      | `ADR-007 §7`, `ADR-002 §"Routing"`      |
+| TDD round                              | `RN`                    | `R6`, `R3`                              |
+| 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"`                |
+
+**Avoid** (normalize to the table above):
+- `Round 6`, `round-six`, `R 6` → `R6`
+- `ADR 007`, `ADR7`, `ADR-7`, `adr-007` → `ADR-007`
+- `AC 3`, `AC3`, `ac-3` → `AC-3`
+- Section anchors: prefer `§7` or `§"Quoted Heading"`; avoid `section 7`, `sec. 7`, `(7)`.
+
+---
+
+## 4. When the comment grows
+
+If the explanation needs more than **~6 lines**, the right home is an ADR or a `docs/research/<topic>.md` note. Leave a one-line pointer in the code:
+
+```go
+// Selection rationale: see docs/research/tier-spill.md and ADR-002 §"Routing".
+```
+
+---
+
+## 5. Test files
+
+Non-trivial tests — those with fakes, harnesses, time control, or unusual lifecycle — get a **5–20 line block comment** at the top of the file (or above the harness type) stating:
+- What is **faked** versus real (and why each choice).
+- Why the design (deterministic? avoid `time.Sleep`? exercise a specific retry path?).
+- Which knobs are overridden and to **what value**.
+
+Trivial tests get nothing. The test name carries the intent.
+
+---
+
+## 6. Done when
+
+Apply this checklist during the [`simplify`](../simplify/SKILL.md) sweep or in code review:
+- [ ] Every surviving comment names a why, invariant, trade-off, or provenance link — none restates the code.
+- [ ] No commented-out code, no `// used by X`, no banner dividers, no orphan TODOs, no in-function section headers.
+- [ ] Every provenance citation matches the canonical grammar in §3.
+- [ ] Docstrings on exported identifiers exist only where the contract isn't obvious from the signature.
+- [ ] Test files with non-trivial harnesses have a strategy preamble; trivial ones do not.

package/skills/investigate/templates/research-note.md

@@ -1,8 +1,20 @@
+---
+type: research
+title: "Research: <topic>"
+description: <one sentence — the question this note investigates>
+tags: [<area>]
+timestamp: YYYY-MM-DD
+status: Open
+owner: <user>
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md. `timestamp` is the canonical date;
+     `status`/`owner` mirror the human-facing lines below (OKF models neither). -->
+
 # Research: <topic>
 
 **Status:** Open | Decided | Superseded
 **Owner:** <user>
-**Date:** YYYY-MM-DD
 
 <!--
 Status values:

package/skills/pr-review/SKILL.md

@@ -87,12 +87,14 @@ For non-surface-changing diffs: walk `prod-ready` Section 3 (defense-in-depth) b
 
 #### 3e. Doc-drift audit
 
-This is the second line of defense for `prod-ready` Section 7. Author may have missed it; reviewer catches what's left. Walk these four questions against the diff:
+This is the second line of defense for `prod-ready` Section 7. Author may have missed it; reviewer catches what's left. Walk these questions against the diff:
 
 - **New decision with viable alternatives** → does an ADR exist in `docs/adr/` for it? Does it name what it supersedes? If load-bearing, is it referenced from the code?
 - **New or changed domain term** → has [`docs/CONTEXT.md`](../../docs/CONTEXT.md) been updated? Are `_Avoid_:` aliases listed if there's risk of confusion?
 - **New / removed package, changed public interface, shifted module boundary** → is the feature's design note (`docs/features/<feature>.design.md`) updated? Module map, file layout, public-interface signatures, test boundaries.
 - **Changed acceptance criteria** → does the feature doc reflect what was actually built? Silently-dropped or silently-added behavior is the most common drift class — flag and don't accept "we'll fix in a follow-up".
+- **User-visible change** → does `CHANGELOG.md` have 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. Missing entry on a user-visible change = finding.
+- **New or changed produced doc under `docs/`** → does it open with OKF frontmatter carrying a non-empty `type` from [`skills/formats/OKF.md`](../formats/OKF.md) §2? A produced doc with no `type` breaks bundle conformance = finding.
 
 If any answer is "no" without `n/a + reason`, that's a finding. Severity:
 - **Blocker** — the missing doc is load-bearing for the next reader (ADR for a hard-to-reverse decision; CONTEXT.md entry for a term other PRs will use; AC drift hiding behavior).
@@ -100,10 +102,11 @@ If any answer is "no" without `n/a + reason`, that's a finding. Severity:
 
 The doc-map is small enough to walk in 2–3 minutes. Skip it and you're trading 3 minutes now for an hour of orientation in 3 months.
 
-#### 3e. Hygiene (line level)
+#### 3f. Hygiene (line level)
 
 Apply `code-hygiene` as a lens here, not as a primary phase:
 
+- **Comment noise**: new WHAT-comments, docstrings on exports whose contract is obvious from the signature, in-function section headers (`// validate`, `// build response`), stale "used by X" references, citation grammar that doesn't match the repo's comment style doc ([`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md)). Flag as **nits by default**; promote to a suggestion only when cumulative comment noise obscures the diff (signal the author skipped `simplify`).
 - Names that mislead (boolean returning non-bool, `getX` that mutates, `Manager`/`Helper` suffixes hiding what the thing is).
 - Cleverness that earns its cost? Or could be boring?
 - YAGNI — "in case we need it" parameters / interfaces / classes? Strip.

package/skills/prod-ready/SKILL.md

@@ -60,6 +60,8 @@ Implementation lands → docs drift. The natural moment to catch drift is now, n
 - [ ] **New or changed domain term** → `CONTEXT.md` entry created or updated. Includes `_Avoid_:` aliases if the term is at risk of being confused with an existing one.
 - [ ] **New/removed package, changed public interface, or shifted module boundary** → the feature's design note (e.g., `docs/features/<feature>.design.md`) updated. Specifically: Module map, File layout, public-interface signatures, Test boundaries.
 - [ ] **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.
+- [ ] **User-visible change** → `CHANGELOG.md` has an entry under `[Unreleased]`, grouped by `Added / Changed / Fixed / Removed`. Skip only if the diff is formatter-only, lint-only, test-only, internal refactor with no behavior change, or a dependency bump with no runtime impact. (Overlaps but is **not identical** to `feature-doc`'s skip list — that one also waives the *doc* for typo fixes and one-line config tweaks. A typo fix can still merit a one-liner here.)
+- [ ] **New or changed doc under `docs/`** → it opens with OKF frontmatter carrying a non-empty `type` from [`skills/formats/OKF.md`](../formats/OKF.md) §2. A produced doc with no `type` breaks the bundle's conformance — fix here.
 
 If a doc type isn't relevant to this work, write "n/a" — explicit beats implicit.
 

package/skills/simplify/SKILL.md

@@ -49,7 +49,14 @@ Walk every changed file. Apply each lens in order. Fix what you find inline.
 - Names that read clearly out of context — would a stranger guess what `result`, `data`, `value` referred to? If not, rename.
 - Error messages that name the failing input — `"could not parse: <value>"` beats `"parse error"`.
 - Abstractions that haven't earned their keep — a base class with one subclass, an interface with one implementation. Inline.
-- Comments that explain *what* the code does — delete; the code already says it. Keep comments that explain *why* (a constraint, an invariant, a workaround).
+- Comments — **default during the sweep is DELETE**:
+  - Delete WHAT-comments (the code already says it).
+  - Delete docstrings on exports whose contract is obvious from the signature.
+  - Delete "used by X" / "added for Y" caller references — these rot; use grep.
+  - Delete commented-out code (git has it).
+  - Delete banner / ASCII-art dividers and in-function section headers (`// validate`, `// build response`).
+  - KEEP only why-comments — constraint, invariant, trade-off, provenance — and only when the next reader would otherwise reattempt the rejected alternative.
+  - If a kept comment cites a round / ADR / AC / snapshot, normalize to [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md) §3 (`ADR-007 §7`, `R6 AC-3`, `v0.3 R1b2`, `snapshot §"Invariants"`).
 
 ### 3. Efficiency — dead code, redundant work, premature defensive checks
 

package/skills/tdd/SKILL.md

@@ -19,6 +19,11 @@ expected_duration: 20 minutes
 - Trivial getters / setters with no behavior.
 - Bug whose root cause isn't yet known — run [`debug`](../debug/SKILL.md) first; the reproduction crystallises into the failing test.
 
+## Pre-conditions
+
+- **Current branch is not `main` / `master`.** If it is, stop and run `git checkout -b feat/<short-name>` (or `fix/...`) before writing the first test. Code lands on a feature branch; `main` receives merges, not commits.
+- A feature doc (`docs/features/<short-name>.md`) exists with testable ACs — or a `debug` reproduction names the root cause.
+
 ## Philosophy
 
 Tests verify **behavior through public interfaces**, not implementation details. Code can change entirely; tests shouldn't.

package/skills/tdd-rounds/SKILL.md

@@ -22,6 +22,7 @@ Distills the pattern of a parent agent driving Builder sub-agents through a feat
 
 ## The parent's contract
 
+- **Dispatch on a feature branch, never `main`.** Verify the current branch before dispatching the first Builder; if it's `main` / `master`, create `feat/<short-name>` first. The whole multi-round delivery lives on one feature branch (or a stack of feature branches), merged to `main` only at the end.
 - **Plan once.** The plan file lists rounds, each round's ACs, the dependency order, and the skills cadence per round (which rounds need `design`; when to invoke `improve-codebase-architecture` mid-project; when to invoke `prod-ready`).
 - **Brief per round.** A self-contained brief — the Builder shouldn't need conversation history. 
   - **Briefing Sub-agent**: For complex rounds, invoke a sub-agent to autonomously generate the brief by analyzing `docs/STATE.md`, the `feature-doc`, and the results of the previous round. See `templates/builder-brief.md` for the schema.
@@ -32,6 +33,7 @@ Distills the pattern of a parent agent driving Builder sub-agents through a feat
 
 When dispatched for a round, the Builder:
 
+0. **Pre-flight.** Verifies the current branch is **not** `main` / `master`. If it is, refuses immediately and returns a blocking report — does not proceed to step 1.
 1. Reads the brief, the plan file, `docs/STATE.md`, and any ADRs / feature docs the brief cites.
 2. **Executes the listed skills sequentially in this single invocation.** When a brief says "Skills (in order): design, tdd, simplify" — that means run all three in this run, not return to the parent between them. This rule is non-obvious; the brief template makes it explicit.
 3. Commits per AC slice (or per behavior slice for refactor rounds), prefix `R<N>:`. **Read [`COMMITS.md`](COMMITS.md) before the first commit** — it captures the seven rules (`R<N>:` prefix, `#<X>` for bug fixes, per-AC slicing, separate simplify-pass commit, separate doc commits, single-commit-with-justification, honest messages) and the message-body shape. The parent reads commits as the review surface; a clean sequence is reviewable one diff at a time, a mono-commit isn't.
@@ -69,7 +71,7 @@ Known follow-ups: <one line>
 - **Builder stuck (test won't go green / design feels wrong).** Builder reports a *blocking* open question instead of thrashing. Hard rule: **Builder must not silently descope an AC.**
   - **Concrete escalation signals** (any one fires → stop and surface):
     - 3 consecutive failed attempts at making the same test green with the same approach.
-    - 2 design-level questions that the brief + STATE.md + cited ADRs don't answer.
+    - 2 design-level questions that the brief + feature state + cited ADRs don't answer.
     - The Builder finds itself wanting to modify a file in the "must NOT touch" allowlist to make progress.
     - A new test would require mocking >3 internal collaborators (smell: design is wrong, not the test).
   - **Parent's response**: shrink scope (split the round), or invoke `design` explicitly with the friction described, or run `grill-plan` if a load-bearing decision is wobbling. Don't push the Builder to keep trying.
@@ -94,3 +96,4 @@ When the final round completes:
 1. Run `verify-real-deps`. Capture surfaced bugs into `docs/known-issues.md`.
 2. Iterate fix-rounds until clean, or document deferrals to vN.1 with rationale.
 3. Tag and publish via whatever release / distribution channel applies.
+

package/skills/verify-real-deps/templates/known-issues.md

@@ -1,3 +1,14 @@
+---
+type: known-issues
+title: "Known issues — post-vN.0 smoke test findings"
+description: Bugs surfaced by the first end-to-end run against the real upstream.
+tags: [smoke-test, known-issues]
+timestamp: YYYY-MM-DD
+---
+
+<!-- Frontmatter is OKF per skills/formats/OKF.md (`type: known-issues`).
+     `timestamp` tracks the last edit; the Discovered line below pins the first run. -->
+
 # Known issues — post-vN.0 smoke test findings
 
 **Discovered:** YYYY-MM-DD (first end-to-end run against real <upstream>).