@ai-agent-lead/skills 1.3.0 → 1.5.0

package/skills/feature-doc/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: feature-doc
 description: One-page contract for a non-trivial feature or bug fix — Problem, User Story, Acceptance Criteria, Non-Goals. The ACs become the test list for `tdd`. Use before any non-trivial feature or bug fix; when the user mentions "spec this out", "write a feature doc", "before any non-trivial feature", or describes a feature without listing ACs. Skip for typo fixes, dependency bumps, or pure refactors. Pairs with `tdd` / `tdd-rounds` (downstream — ACs feed the test list), `investigate` (upstream — when direction itself is unclear), and `grill-plan` (when the chosen plan needs stress-testing against existing model).
-complexity: low
-expected_duration: 10 minutes
 ---
 
 # Feature Doc
@@ -68,13 +66,6 @@ STRONG
 
 The strong list translates 1:1 into tests. The weak list translates into vibes.
 
-## Definition of Done for the doc
-
-- [ ] Problem stated in 2–3 sentences.
-- [ ] At least one acceptance criterion in Given / When / Then form.
-- [ ] Non-goals listed (or explicitly "none — see scope in Problem").
-- [ ] Reviewed by at least one other person.
-
 ## Anti-patterns
 
 - **AC list as task list.** "Implement the login form" is a task; "Given a user with valid credentials, when they POST `/login`, then they receive a session cookie" is an AC. Tasks belong in your TODO; ACs belong in the contract.
@@ -93,23 +84,24 @@ The strong list translates 1:1 into tests. The weak list translates into vibes.
 - **`security-review`** — runs *alongside* `tdd` when the feature is surface-changing (new entry point, identity flow, sensitive data path).
 - **`prod-ready`** — runs after green, against this doc. Section 7 catches doc-drift if behavior shifted during implementation.
 
-## Handoff
-
-Once the doc is reviewed and ACs are stable:
-
-- **Single-feature delivery** (one package, manageable AC count) → run [`tdd`](../tdd/SKILL.md). Each AC becomes one TDD slice.
-- **Larger delivery** (≥10 ACs or multi-package) → run [`tdd-rounds`](../tdd-rounds/SKILL.md). The AC list maps to round splits.
-- **Direction still feels uncertain after writing the doc**:
-  - Project has `CONTEXT.md` and/or ADRs → run [`grill-plan`](../grill-plan/SKILL.md) to stress-test against the existing model.
-  - No `CONTEXT.md` or ADRs yet → run [`investigate`](../investigate/SKILL.md) to map options first; or, if the plan is chosen but vocabulary is fuzzy, run `grill-plan` in [bootstrap mode](../grill-plan/BOOTSTRAP.md).
-- **Hard-to-reverse / surface-changing** (new auth flow, public API, sensitive data flow) → run [`security-review`](../security-review/SKILL.md) alongside `tdd` / `tdd-rounds`.
-
 ## Done when
 
 - A feature branch (e.g. `feat/<short-name>` or `fix/<short-name>`) is checked out and the contract doc is committed on it, **not on `main`**.
 - `docs/features/<short-name>.md` exists with all four required sections.
 - The doc opens with OKF frontmatter (`type: feature`) per [`skills/formats/OKF.md`](../formats/OKF.md).
+- Problem is stated in 2–3 sentences.
 - ACs are testable Given / When / Then statements.
 - Non-Goals is non-empty (or explicitly "none — see scope in Problem").
 - One reviewer has signed off.
 - Status is `Approved` and the next skill (`tdd` / `tdd-rounds` / `grill-plan` / `security-review`) is named.
+
+## Handoff
+
+Once the doc is reviewed and ACs are stable:
+
+- **Single-feature delivery** (one package, manageable AC count) → run [`tdd`](../tdd/SKILL.md). Each AC becomes one TDD slice.
+- **Larger delivery** (≥10 ACs or multi-package) → run [`tdd-rounds`](../tdd-rounds/SKILL.md). The AC list maps to round splits.
+- **Direction still feels uncertain after writing the doc**:
+  - Project has `CONTEXT.md` and/or ADRs → run [`grill-plan`](../grill-plan/SKILL.md) to stress-test against the existing model.
+  - No `CONTEXT.md` or ADRs yet → run [`investigate`](../investigate/SKILL.md) to map options first; or, if the plan is chosen but vocabulary is fuzzy, run `grill-plan` in [bootstrap mode](../bootstrap/BOOTSTRAP.md).
+- **Hard-to-reverse / surface-changing** (new auth flow, public API, sensitive data flow) → run [`security-review`](../security-review/SKILL.md) alongside `tdd` / `tdd-rounds`.

package/skills/{code-hygiene/SKILL.md → formats/CODE-HYGIENE.md}

@@ -1,15 +1,10 @@
----
-name: code-hygiene
-description: Day-to-day coding discipline at the line and function level — boring code, naming as primary refactor, YAGNI, rule of 3, locality of behavior. Use when reviewing or writing code, when names feel wrong, when tempted to abstract too early, when a solution looks clever, when the simplify pass after `tdd` runs, or when the user mentions "simpler", "boring", "naming", "YAGNI", "premature abstraction", "over-engineered". Skip for module-level interface design — use `design` instead. Skip for whole-codebase architectural sweeps — use `improve-codebase-architecture`.
-complexity: low
-expected_duration: 5 minutes
----
-
 # Code Hygiene
 
-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.
+The line-level and function-level lens this skill set carries into any turn that writes or reads code. Smaller in scope than [`design`](../design/SKILL.md) (which shapes module interfaces) — these are the day-to-day habits that keep a codebase readable, navigable, and easy to change.
+
+This is a **shared reference**, not a standalone skill. It is the lens applied *while writing*, during the [`simplify`](../simplify/SKILL.md) sweep after `tdd` reaches green, and during [`pr-review`](../pr-review/SKILL.md) (§3f). Read it once; apply it many times.
 
-Six principles.
+Seven 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.
@@ -17,19 +12,7 @@ Six principles.
 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 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.
-
-## When to skip
-
-- Module-level shape (interface, depth, dependencies) — use `design`.
-- Whole-codebase sweeps for shallow modules — use `improve-codebase-architecture`.
-- The horizontal-vs-vertical TDD failure mode — that's `tdd`'s territory.
+7. **Constants live where they're used** — narrowest honest scope; no `constants.ts` dumping ground.
 
 ## Principle 1: Boring code beats clever code
 
@@ -74,17 +57,28 @@ Related code lives close together. Don't split a system by *type of code* (`cont
 
 **Why**: a new contributor should be able to read one folder and understand one feature, not bounce across five folders to follow one request.
 
-**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.)
+**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 an [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md) 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.
+**The bar:** [`STYLE-COMMENTS.md`](STYLE-COMMENTS.md). Apply it *while writing*, not only during the `simplify` sweep.
 
 **Default: NONE.** If you're unsure whether a comment earns its line, delete it. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot — and only if the next reader would otherwise reattempt the rejected alternative.
 
 **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
+## Principle 7: Constants live where they're used
+
+A constant belongs at the **narrowest honest scope** — next to the code that uses it, not in a far-off catch-all file.
+
+- **Default to local.** Define it in the function or module that uses it. Widen the scope only when a *second* caller genuinely shares the same value (rule of 3) or it's a single-source-of-truth domain value (a timeout, a retry limit, a page size, an external URL) that must not diverge between call sites.
+- **Reject the dumping ground.** A `constants.ts` / `config.ts` / `utils.ts` god-file of unrelated constants breaks locality — you bounce across files to understand one feature. Group constants by the *responsibility* they serve, not by the fact that they're all constants.
+- **Name a literal only when its meaning is non-obvious.** `MAX_RETRIES = 3` earns its name; `index + 1` and `slice(0, 1)` don't. A magic number whose *meaning* a reader can't infer is a naming problem (Principle 2); a self-evident one isn't.
+- **Environment-varying values are config from env, not constants in source.** A timeout you tune per environment, an API base URL, a feature flag — those come from the env / secret store ([`prod-ready`](../prod-ready/SKILL.md) §3), not a hardcoded literal. Centralizing constants and hardcoding env values are opposite mistakes; don't make both.
+
+**Smell**: a top-level `constants.ts` that grows every feature, imported by half the codebase. Each import is a caller reaching across the codebase for one value that probably belonged next to its single use.
+
+## The bar — clean when
 
 - Names communicate intent — a stranger reads them and forms the right mental model.
 - The clever shortcut is replaced with the obvious version (or its cleverness is justified by a comment naming the constraint).
@@ -92,9 +86,10 @@ Related code lives close together. Don't split a system by *type of code* (`cont
 - 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.
+- Constants sit at their narrowest honest scope — no unrelated-constants dumping ground; env-varying values come from config, not source literals.
 
-## Pairing with other skills
+## Scope boundaries
 
-- **`design`** sets module shape; `code-hygiene` polishes within the module. Different scopes; both apply.
-- **`tdd`** reaches green; `code-hygiene` is part of the simplify sweep that follows.
-- **`improve-codebase-architecture`** finds shallow modules; if the diagnosis is "shallow" but the fix is line-level (rename, inline, delete dead helper), this skill applies. If the fix is structural (deepen the module), that one does.
+- Module-level shape (interface, depth, dependencies) is [`design`](../design/SKILL.md)'s job, not this lens's.
+- Whole-codebase sweeps for shallow modules are [`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md). If the diagnosis is "shallow" but the fix is line-level (rename, inline, delete dead helper), this lens applies; if the fix is structural (deepen the module), that skill does.
+- Architecture vocabulary (module, interface, depth, seam) comes from [`LANGUAGE.md`](../LANGUAGE.md) — don't redefine.

package/skills/formats/CONTEXT-FORMAT.md

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

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

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

package/skills/formats/CONVENTION-FORMAT.md

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

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

@@ -0,0 +1,56 @@
+# Doc-Drift Audit
+
+The single source for one question: *does this change leave the durable docs consistent with the code?* Implementation lands → docs drift. The natural moment to catch the drift is at the merge boundary, not "next sprint".
+
+This is a **shared reference**, run from three places with the same checks but a different lens:
+
+- [`prod-ready`](../prod-ready/SKILL.md) Section 7 — **author lens.** Walk the checks before opening the PR; fix drift inline now.
+- [`pr-review`](../pr-review/SKILL.md) §3e — **reviewer lens.** Second line of defense; what the author missed, classified by severity.
+- **Standalone** — the old `sync-check` role. Run mid-stream after a significant refactor, or when a name feels "off", to surface terminology and ADR drift before it calcifies. Produces a numbered findings list (see "Standalone report" below).
+
+Files don't need to pre-exist — `docs/adr/`, `CONTEXT.md`, design notes are created lazily when the first relevant change appears. If a doc type isn't relevant to this work, write `n/a` — explicit beats implicit.
+
+## The seven checks
+
+One question per doc type: *did this work change X? Then update Y.*
+
+1. **New decision with viable alternatives** → an ADR exists in `docs/adr/`, names what it supersedes (if anything), and is referenced from code where the decision is load-bearing. See [`ADR-FORMAT.md`](ADR-FORMAT.md).
+2. **New or changed domain term** → [`docs/CONTEXT.md`](../../docs/CONTEXT.md) entry created or updated, including `_Avoid_:` aliases if the term risks being confused with an existing one. A new term that collides with an existing `_Avoid_:` alias (e.g. "Account" where the glossary says "Customer") is the highest-signal finding here.
+3. **New/removed package, changed public interface, or shifted module boundary** → the feature's design note (`docs/features/<feature>.design.md`) is updated: module map, file layout, public-interface signatures, test boundaries.
+4. **Changed acceptance criteria** → the feature doc reflects what was actually built. Silently-dropped or silently-added behavior is the most common drift class — fix here, don't kick to a follow-up.
+5. **User-visible change** → `CHANGELOG.md` has an entry under `[Unreleased]`, grouped by `Added / Changed / Fixed / Removed`. Skip only for formatter-only / lint-only / test-only / internal-refactor-with-no-behavior-change / dep-bump-with-no-runtime-impact diffs. (Overlaps but is **not identical** to `feature-doc`'s skip list, which also waives the *doc* for typo fixes and one-line config tweaks. A typo fix can still merit a one-liner here.)
+6. **New or changed produced doc under `docs/`** → it opens with OKF frontmatter carrying a non-empty `type` from [`OKF.md`](OKF.md) §2. A produced doc with no `type` breaks bundle conformance.
+7. **New or removed produced doc under `docs/`** → [`docs/index.md`](../../docs/index.md) (the bundle manifest) gains or loses its entry. A produced doc that exists but isn't listed is invisible to progressive disclosure; a listed file that was deleted is a dangling entry.
+
+## ADR consistency (read alongside check 1)
+
+Beyond "does an ADR exist", check the change against the ones already recorded:
+
+- **Direct contradiction** — does the change do something an active ADR explicitly forbids (e.g. uses an ORM where an ADR mandates hand-written SQL)? That's a blocker until the ADR is superseded.
+- **Surprise deviation** — does the change introduce a pattern that *warrants* a new ADR (hard to reverse, surprising, a real trade-off) but doesn't have one?
+
+## Severity
+
+- **Blocker** — the missing/contradicted doc is load-bearing for the next reader: an ADR for a hard-to-reverse decision, a `CONTEXT.md` entry for a term other changes will use, an AC drift hiding behavior, or a direct ADR contradiction.
+- **Suggestion** — the doc would help but the diff is self-explanatory in isolation.
+
+In the author lens (`prod-ready`) every check resolves to `✓`, `✗ + remediation`, or `n/a + reason` and is fixed before the PR. In the reviewer lens (`pr-review`) an unresolved check without `n/a + reason` is a finding at the severity above.
+
+## Standalone report
+
+When run on its own (the former `sync-check`), output a numbered list. For each finding:
+
+- **Location** — `file:line` or `ADR-NNNN`.
+- **Severity** — `Blocker` or `Suggestion` per above.
+- **Finding** — e.g. "Code uses 'Account', but `CONTEXT.md` specifies 'Customer'."
+- **Recommended action** — e.g. "Rename to 'Customer', or update `CONTEXT.md` if the concept is genuinely new."
+
+If a contradiction is found in *existing* code (not just this diff), escalate to [`grill-plan`](../grill-plan/SKILL.md) to resolve the terminology or architectural mismatch.
+
+## Done when
+
+- Every relevant check is `✓`, `✗ + remediation`, or `n/a + reason`.
+- Every `_Avoid_:` alias appearing in the diff has been flagged.
+- Every deviation from an active ADR has been surfaced.
+
+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.

package/skills/formats/OKF.md

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

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

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

package/skills/grill-plan/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: grill-plan
 description: Grilling session that stress-tests a chosen plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use AFTER a direction has been picked (post-`investigate` or post-`feature-doc`), when the user wants to pressure-test the plan — triggered by phrases like "grill me on this", "stress-test this plan", "walk me through this", "is this consistent with our model". Skip if the direction is still being explored — use `investigate` instead.
-complexity: medium
-expected_duration: 20 minutes
 ---
 
+# Grill Plan
+
+Stress-test a chosen plan against the existing domain model — interview-style — resolving each decision one at a time and capturing the sharpened terms and ADRs in `CONTEXT.md` / `docs/adr/` as they crystallise.
+
 ## When to use
 
 - A direction has been picked (post-`investigate` or post-`feature-doc`) and you want to pressure-test it against the existing model.
@@ -98,7 +100,7 @@ If any of the three is missing, skip the ADR. Use the format in [`../formats/ADR
 ## Pairing with other skills
 
 - **[`investigate`](../investigate/SKILL.md)** — runs *before* when direction is unclear. Once a direction is chosen, hand off here.
-- **[`sync-check`](../sync-check/SKILL.md)** — escalates here when a terminology collision or ADR contradiction is found in existing code.
+- **[`DOC-DRIFT-AUDIT.md`](../formats/DOC-DRIFT-AUDIT.md)** — the terminology/ADR audit (formerly the `sync-check` skill) escalates here when it finds a terminology collision or ADR contradiction in existing code.
 - **[`feature-doc`](../feature-doc/SKILL.md)** — runs *before* when a feature doc is the input to grilling, or *after* when grilling refines the plan into a feature doc.
 - **[`system-design`](../system-design/SKILL.md)** — defers here for hard-to-reverse topology decisions.
 - **[`improve-codebase-architecture`](../improve-codebase-architecture/SKILL.md)** — borrows this skill's grilling discipline in its own grilling loop.

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

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

package/skills/improve-codebase-architecture/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: improve-codebase-architecture
 description: Find deepening opportunities in EXISTING code, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Use for EXISTING code; for designing the shape of a new module from scratch, use `design`. Skip for single-module local refactors with no cross-module impact — use `design` or just refactor inline.
-complexity: high
-expected_duration: 45 minutes
 ---
 
 # Improve Codebase Architecture
@@ -20,28 +18,19 @@ Surface architectural friction and propose **deepening opportunities** — refac
 - Designing the shape of a new module from scratch — use [`design`](../design/SKILL.md).
 - Greenfield system topology — use [`system-design`](../system-design/SKILL.md).
 - Single-module local refactor with no cross-module impact — use `design` or refactor inline.
-- Line-level cleanup (renames, dead-code removal) — use [`code-hygiene`](../code-hygiene/SKILL.md) + [`simplify`](../simplify/SKILL.md).
+- Line-level cleanup (renames, dead-code removal) — use the [`code-hygiene`](../formats/CODE-HYGIENE.md) lens + [`simplify`](../simplify/SKILL.md).
 
-## Glossary
+## Vocabulary
 
-Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [skills/LANGUAGE.md](../LANGUAGE.md).
+Use the shared architecture terms **exactly** — **module**, **interface**, **implementation**, **depth** (deep / shallow), **seam**, **adapter**, **leverage**, **locality** — and don't drift into "component," "service," "API," or "boundary." Definitions and principles are canonical in [`LANGUAGE.md`](../LANGUAGE.md); this skill links rather than restating them.
 
-- **Module** — anything with an interface and an implementation (function, class, package, slice).
-- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
-- **Implementation** — the code inside.
-- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
-- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
-- **Adapter** — a concrete thing satisfying an interface at a seam.
-- **Leverage** — what callers get from depth.
-- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
+Three principles from there do the heavy lifting here:
 
-Key principles (see [skills/LANGUAGE.md](../LANGUAGE.md) for the full list):
-
-- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **Deletion test** — imagine deleting the module. If complexity vanishes, it was a pass-through; if it reappears across N callers, it was earning its keep. This is the primary filter for the candidates below.
 - **The interface is the test surface.**
-- **One adapter = hypothetical seam. Two adapters = real seam.**
+- **One adapter = hypothetical seam; two adapters = real seam.**
 
-This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
+This skill is _informed_ by the project's domain model: the domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
 
 ## Process
 

package/skills/investigate/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: investigate
 description: Use when the user asks for investigation, research, a proposal, or "options" before any code lands; or proactively for non-trivial structural decisions (new dependency, framework choice, API contract change, cross-cutting refactor). Triggered by phrases like "investigate X", "research Y", "give me a proposal", "what are our options", "how would we approach", "let's explore", "should we...". Produces a durable research note in `docs/research/<topic>.md`. Skip for tasks where one obvious approach exists (typo fixes, config tweaks, mechanical refactors). Pairs with `feature-doc` (captures *what* we're building once a direction is chosen) and `grill-plan` (stress-tests a chosen plan).
-complexity: medium
-expected_duration: 20 minutes
 ---
 
 # Investigation Workflow
@@ -87,6 +85,20 @@ The note must include:
 - Do **not** skip the artifact for "small" investigations. The discipline of writing it is the value; the durable trail is the bonus.
 - Do **not** add a Recommendation that just lists the options again. Pick one.
 
+## Pairing with other skills
+
+- **[`feature-doc`](../feature-doc/SKILL.md)** — runs *after*. The "Decided" recommendation becomes the feature contract.
+- **[`grill-plan`](../grill-plan/SKILL.md)** — runs *after* when the chosen option is load-bearing and needs stress-testing into an ADR.
+- **[`system-design`](../system-design/SKILL.md)** — runs *after* when the investigation settled a greenfield topology direction.
+- **[`debug`](../debug/SKILL.md)** — *lateral*. Also emits a `docs/research/<topic>.md` note, but for an unexplained bug rather than a forward-looking decision.
+
+## Done when
+
+- A research note exists at `docs/research/<topic>.md`, opening with `type: research` OKF frontmatter, containing Context (cited), 2–3 Options, a single Recommendation, Checkpoint questions, and Out-of-scope.
+- Every claim in Context cites `path:line` — nothing is worked from impression.
+- Exactly one option is recommended, with the accepted trade-off named (not a re-listing of the options).
+- The user has the checkpoint questions needed to choose, and no implementation has started.
+
 ## Handoff
 
 Once the user picks an option:

package/skills/pr-review/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: pr-review
-description: Discipline for reviewing someone else's pull request — the inverse of `prod-ready` (which is the author's pre-merge gate). Use when the user asks to "review this PR", "look over the diff", "check this change", "give feedback on", or invokes a code-review slash command. Reviews against the linked feature doc / ADRs / domain vocabulary, classifies findings by severity (blocker / suggestion / nit), and returns a structured report. Skip for trivial PRs (typo, dep bump, lint-only) — approve directly. Pairs with `prod-ready` (the author's checklist; the reviewer verifies it landed honestly), `security-review` (escalation when the diff is surface-changing), and `code-hygiene` (the line-level lens applied during the read).
-complexity: medium
-expected_duration: 20 minutes
+description: Discipline for reviewing someone else's pull request — the inverse of `prod-ready` (which is the author's pre-merge gate). Use when the user asks to "review this PR", "look over the diff", "check this change", "give feedback on", or invokes a code-review slash command. Reviews against the linked feature doc / ADRs / domain vocabulary, classifies findings by severity (blocker / suggestion / nit), and returns a structured report. Skip for trivial PRs (typo, dep bump, lint-only) — approve directly. Pairs with `prod-ready` (the author's checklist; the reviewer verifies it landed honestly), `security-review` (escalation when the diff is surface-changing), and the `code-hygiene` lens (`formats/CODE-HYGIENE.md`, applied line-level during the read).
 ---
 
 # PR Review
@@ -87,26 +85,13 @@ 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 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).
-- **Suggestion** — the doc would help but the diff is self-explanatory in isolation.
-
-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.
+Walk the seven checks in [`skills/formats/DOC-DRIFT-AUDIT.md`](../formats/DOC-DRIFT-AUDIT.md) against the diff — **reviewer lens**. This is the second line of defense for `prod-ready` Section 7: the author may have missed it; you catch what's left. Any check that resolves to "no" without `n/a + reason` is a finding, at the severity that reference defines — **Blocker** for load-bearing drift (a missing ADR for a hard-to-reverse decision, a `CONTEXT.md` entry for a term other PRs will use, AC drift hiding behavior, a direct ADR contradiction), **Suggestion** when the diff is self-explanatory in isolation.
 
 #### 3f. Hygiene (line level)
 
-Apply `code-hygiene` as a lens here, not as a primary phase:
+Apply the [`code-hygiene`](../formats/CODE-HYGIENE.md) 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`).
+- **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.
@@ -179,16 +164,16 @@ A `tdd-rounds` parent verifying a Builder's round runs a focused subset:
 2. Run the test command independently — don't trust pasted output.
 3. Read the diff, classify findings.
 4. Tick AC checkboxes in the feature doc with the test names.
-5. Append the round summary to `docs/STATE.md`.
+5. Append the round summary to the feature's `docs/features/<name>.state.md`.
 
 The classification (blocker / suggestion / nit) lives in the parent's notes; only blockers gate the next round.
 
 ## Pairing with other skills
 
 - **`prod-ready`** is the author's pre-merge checklist. Reviewer verifies it landed.
-- **`sync-check`** is the diagnostic context auditor. Reviewer runs it (or verifies it was run) to catch terminology drift and ADR contradictions early.
+- **[`DOC-DRIFT-AUDIT.md`](../formats/DOC-DRIFT-AUDIT.md)** is the shared terminology/ADR/doc-map audit run from §3e — the former `sync-check` skill, now single-sourced and shared with `prod-ready` Section 7.
 - **`security-review`** is the surface-change escalation. Reviewer flags when required.
-- **`code-hygiene`** is the line-level lens applied during the read.
+- **[`code-hygiene`](../formats/CODE-HYGIENE.md)** is the line-level lens applied during the read (§3f).
 - **`grill-plan`** is where load-bearing disagreements go (a new ADR, not a PR comment thread).
 - **`debug`** if a finding turns out to be "this PR introduces a bug" — switch to debug to characterise it before recommending a change.
 

package/skills/prod-ready/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: prod-ready
-description: Pre-merge production-readiness checklist — operational, infrastructure, and consistency checks that tests alone don't surface. Use after `tdd` reaches green; before opening a PR or merging to main; after significant infra changes (new DB, new deployment target, new auth flow); or when the user mentions "shipping", "ready to merge", "before deploy", "production readiness", or "prod-ready". Pairs with the `tdd` skill — tdd proves the feature works; this catches what tests can't see (server timeouts, DB pragmas, error-response consistency, secrets at rest).
-complexity: low
-expected_duration: 10 minutes
+description: Pre-merge production-readiness checklist — operational, infrastructure, and consistency checks that tests alone don't surface. Use after `tdd` reaches green; before opening a PR or merging to main; after significant infra changes (new DB, new deployment target, new auth flow); or when the user mentions "shipping", "ready to merge", "before deploy", "production readiness", or "prod-ready". Skip for pure docs / comment / test-only diffs, dependency bumps with no runtime change, or one-line bug fixes that don't touch infra, auth, or error paths. Pairs with `tdd` (proves the feature works; this catches what tests can't see — server timeouts, DB pragmas, error-response consistency, secrets at rest), `security-review` (the heavier threat-model pass when the surface changes), `pr-review` (the reviewer's mirror of this gate), and `verify-real-deps` (after, for releases that touch third-party APIs).
 ---
 
 # Prod-Readiness Checklist
@@ -17,6 +15,12 @@ A short pre-merge gate. Tests prove the **feature** works. This skill catches wh
 - Before opening a PR or merging to main.
 - After significant infrastructure changes (new DB, new deployment target, new auth flow).
 
+## When to skip
+
+- Pure docs / comment / test-only changes.
+- Dependency bumps that don't change runtime behavior.
+- One-line business-logic bug fixes that don't touch infra, auth, or error paths.
+
 ## Checklist
 
 Walk each section. An item is OK to fail **only if** the feature doc's Notes / Non-Goals explicitly accepts the gap.
@@ -54,22 +58,17 @@ Walk each section. An item is OK to fail **only if** the feature doc's Notes / N
 
 ### 7. Documentation (the doc-map)
 
-Implementation lands → docs drift. The natural moment to catch drift is now, not "next sprint". One question per doc type: *did this work change X? Then update Y.* Files don't need to pre-exist — create `docs/adr/`, `CONTEXT.md`, design notes lazily when the first relevant change appears.
+Implementation lands → docs drift. The natural moment to catch drift is now, not "next sprint". Walk the seven checks in [`skills/formats/DOC-DRIFT-AUDIT.md`](../formats/DOC-DRIFT-AUDIT.md) — **author lens**: tick each `✓`, `✗ + remediation`, or `n/a + reason`, and fix the drift inline before the PR (don't kick it to a follow-up). Files don't need to pre-exist — create `docs/adr/`, `CONTEXT.md`, design notes lazily when the first relevant change appears.
 
-- [ ] **New decision with viable alternatives** → ADR exists in `docs/adr/`, names what it supersedes (if anything), and is referenced from code where the decision is load-bearing.
-- [ ] **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.
+- [ ] ADR for any new decision with viable alternatives (and no active ADR is contradicted).
+- [ ] `CONTEXT.md` updated for any new/changed domain term, with `_Avoid_:` aliases where confusion is likely.
+- [ ] Design note updated for any new/removed package, changed public interface, or shifted module boundary.
+- [ ] Feature doc reflects what was actually built (no silently-dropped or silently-added behavior).
+- [ ] `CHANGELOG.md` `[Unreleased]` entry for any user-visible change.
+- [ ] Every new/changed `docs/` file opens with OKF `type` frontmatter.
+- [ ] `docs/index.md` lists every produced doc — new ones added, deleted ones removed.
 
-If a doc type isn't relevant to this work, write "n/a" — explicit beats implicit.
-
-## When to skip
-
-- Pure docs / comment / test-only changes.
-- Dependency bumps that don't change runtime behavior.
-- One-line business-logic bug fixes that don't touch infra, auth, or error paths.
+Per-check definitions, skip lists, and severity live in [`DOC-DRIFT-AUDIT.md`](../formats/DOC-DRIFT-AUDIT.md) — this is the same audit `pr-review` §3e runs from the reviewer side.
 
 ## Pairing with other skills