@ai-agent-lead/skills 1.2.0 → 1.4.0

package/package.json

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

package/skills/README.md

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

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

package/skills/TRIGGERS.md

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

package/skills/WORKFLOWS.md

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

@@ -1,8 +1,6 @@
 ---
 name: bench
 description: Performance benchmarking discipline. Measures latency, throughput, and records baseline environments. Triggered by phrases like "benchmark", "performance test", "measure latency".
-complexity: medium
-expected_duration: 30 minutes
 ---
 
 # Benchmark

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/bootstrap/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: bootstrap
 description: Initializes a greenfield repository. Creates the docs/ directory, the initial CONTEXT.md, and the first ADR. Triggered by phrases like "new project", "initialize", "bootstrap".
-complexity: low
-expected_duration: 10 minutes
 ---
 
 # Bootstrap

package/skills/caveman/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: caveman
 description: Ultra-concise communication utility for token optimization. Use when the user mentions "caveman mode", "be concise", "save tokens", or "ooga booga". Strips articles, pleasantries, and filler words to maximize efficiency. Skip when the user explicitly requests professional or detailed explanations.
-complexity: low
-expected_duration: 5 minutes
 ---
 
 # Caveman Mode (Token Optimizer)

package/skills/debug/SKILL.md

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

package/skills/design/ILLEGAL-STATES.md

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

package/skills/design/SKILL.md

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

@@ -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
@@ -101,12 +99,14 @@ Once the doc is reviewed and ACs are stable:
 - **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).
+  - No `CONTEXT.md` or ADRs yet → run [`investigate`](../investigate/SKILL.md) to map options first; or, if the plan is chosen but vocabulary is fuzzy, run `grill-plan` in [bootstrap mode](../bootstrap/BOOTSTRAP.md).
 - **Hard-to-reverse / surface-changing** (new auth flow, public API, sensitive data flow) → run [`security-review`](../security-review/SKILL.md) alongside `tdd` / `tdd-rounds`.
 
 ## Done when
 
+- A feature branch (e.g. `feat/<short-name>` or `fix/<short-name>`) is checked out and the contract doc is committed on it, **not on `main`**.
 - `docs/features/<short-name>.md` exists with all four required sections.
+- The doc opens with OKF frontmatter (`type: feature`) per [`skills/formats/OKF.md`](../formats/OKF.md).
 - ACs are testable Given / When / Then statements.
 - Non-Goals is non-empty (or explicitly "none — see scope in Problem").
 - One reviewer has signed off.

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/{code-hygiene/SKILL.md → formats/CODE-HYGIENE.md}

@@ -1,34 +1,18 @@
----
-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.
 
-Five 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.
 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.
-
-## 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.
-- 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.
+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.
+7. **Constants live where they're used** — narrowest honest scope; no `constants.ts` dumping ground.
 
 ## Principle 1: Boring code beats clever code
 
@@ -66,32 +50,35 @@ Duplicate twice; extract on the third occurrence — not the second.
 The first occurrence is unique. The second might be coincidence. The third is a pattern. Extracting at two reveals only one axis of variation; extracting at three reveals the *real* axis.
 
 **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.
-5. **Locality of behavior** — related code lives together; don't split by category.
-6. **Comments earn their keep** — default to none. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot.
 
-## When to 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/`).
 
 **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
 
-Default to none. Keep only WHY-comments: a constraint, an invariant, a trade-off, or a provenance link to an ADR / round / snapshot. Delete WHAT-comments, "used by X" / "added for Y" caller references, banner dividers, and commented-out code on sight.
+**The bar:** [`STYLE-comments.md`](STYLE-comments.md). Apply it *while writing*, not only during the `simplify` sweep.
 
-**Smells**:
-- A comment that restates the next line of code.
-- A comment naming a caller — that reference rots the moment someone renames or removes the caller. Use `grep`.
-- A TODO / FIXME / HACK with no owner, ticket, ADR, or date.
-- Commented-out code "in case we need it again". Git has it.
+**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.
+
+## 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.
 
-**Project-specific conventions** (package docstrings, provenance grammar) live in the repo's comment style doc — usually [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md).
+**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.
 
-## Done when
+## 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).
@@ -99,9 +86,10 @@ Default to none. Keep only WHY-comments: a constraint, an invariant, a trade-off
 - 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

@@ -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