@ai-agent-lead/skills 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-agent-lead/skills",
-  "version": "1.3.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
 

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,9 +350,9 @@ A few things that happen across all workflows:
 
 12. **Vocabulary is shared.** All architecture-talking skills (`design`, `system-design`, `improve-codebase-architecture`, `pr-review`, `grill-plan`) read from [`skills/LANGUAGE.md`](./LANGUAGE.md). Format references (ADRs, CONTEXT.md) live in [`skills/formats/`](./formats/). Domain vocabulary (Customer, Order, etc.) lives in `docs/CONTEXT.md`. Keep them distinct.
 
-13. **Bootstrap mode for greenfield repos** is documented in one place — [`grill-plan/BOOTSTRAP.md`](./grill-plan/BOOTSTRAP.md). `feature-doc` and `system-design` defer there rather than re-explaining the rules.
+13. **Bootstrap mode for greenfield repos** is documented in one place — [`bootstrap/BOOTSTRAP.md`](./bootstrap/BOOTSTRAP.md). `feature-doc`, `system-design`, and `improve-codebase-architecture` defer there rather than re-explaining the rules.
 
-14. **`simplify` is the end-of-slice / end-of-round sweep.** Runs after every `tdd` slice goes green; in `tdd-rounds`, lands as its own commit per [`tdd-rounds/COMMITS.md` rule 4](./tdd-rounds/COMMITS.md). Applies the `code-hygiene` lens to the changed files, plus a test-relevance check. Distinct from `code-hygiene` (the lens) and from `improve-codebase-architecture` (the structural escalation when simplify finds bigger issues).
+14. **`simplify` is the end-of-slice / end-of-round sweep.** Runs after every `tdd` slice goes green; in `tdd-rounds`, lands as its own commit per [`tdd-rounds/COMMITS.md` rule 4](./tdd-rounds/COMMITS.md). Applies the [`code-hygiene`](./formats/CODE-HYGIENE.md) lens to the changed files, plus a test-relevance and telemetry check. Distinct from the `code-hygiene` lens reference itself and from `improve-codebase-architecture` (the structural escalation when simplify finds bigger issues).
 
 15. **Artifacts accumulate in `docs/`:**
 

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

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,7 +99,7 @@ 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

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/DOC-DRIFT-AUDIT.md

@@ -0,0 +1,55 @@
+# 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 six 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.
+
+## 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/grill-plan/SKILL.md

@@ -1,8 +1,6 @@
 ---
 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
 ---
 
 ## When to use
@@ -98,7 +96,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/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,7 +18,7 @@ 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
 

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

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,24 +85,11 @@ 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 six 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`).
 - Names that mislead (boolean returning non-bool, `getX` that mutates, `Manager`/`Helper` suffixes hiding what the thing is).
@@ -186,9 +171,9 @@ The classification (blocker / suggestion / nit) lives in the parent's notes; onl
 ## 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
 ---
 
 # Prod-Readiness Checklist
@@ -54,16 +52,16 @@ 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 six 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.
 
-If a doc type isn't relevant to this work, write "n/a" — explicit beats implicit.
+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.
 
 ## When to skip
 

package/skills/security-review/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: security-review
 description: Threat-model + control-review pass for surface-changing work — runs alongside `tdd` and as a heavier gate than `prod-ready` Section 3 when the change introduces or alters trust boundaries, authentication, authorization, sensitive data flows, or external surfaces. Use when the user mentions "security review", "threat model", "STRIDE", "auth flow", "permissions", "secrets", "PII", "public API", "external surface", "abuse", "hardening", or whenever a feature doc / PR adds a new entry point, identity flow, or sensitive-data path. Skip for pure-internal refactors with no surface change, dependency bumps that don't change runtime behavior, or doc-only changes. Pairs with `feature-doc` (informs the threat model) and `prod-ready` (which has the lighter operational-security checklist for every change).
-complexity: high
-expected_duration: 30 minutes
 ---
 
 # Security Review

package/skills/simplify/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: simplify
-description: Single end-of-round sweep that tightens what `tdd` just left green — review every changed file for reuse, quality, efficiency, and test relevance. Use after `tdd` reaches green and before opening a PR (or before a Builder closes a round in `tdd-rounds`). Triggered by phrases like "simplify pass", "tighten this", "clean up before commit", "end-of-round sweep", or appearing as a step in a Builder brief. Skip for trivial diffs (typo, dep bump, doc-only). Pairs with `tdd` (runs immediately after green), `code-hygiene` (the lens applied during the sweep), and `pr-review` (a self-check after this).
-complexity: low
-expected_duration: 10 minutes
+description: Single end-of-round sweep that tightens what `tdd` just left green — review every changed file for reuse, quality, efficiency, and test relevance. Use after `tdd` reaches green and before opening a PR (or before a Builder closes a round in `tdd-rounds`). Triggered by phrases like "simplify pass", "tighten this", "clean up before commit", "end-of-round sweep", or appearing as a step in a Builder brief. Skip for trivial diffs (typo, dep bump, doc-only). Pairs with `tdd` (runs immediately after green), the `code-hygiene` lens (`formats/CODE-HYGIENE.md`, applied during the sweep), and `pr-review` (a self-check after this).
 ---
 
 # Simplify
@@ -34,7 +32,7 @@ The simplify pass catches these once, deliberately, before the diff lands. Witho
 - Slices where the diff is one or two lines and there's nothing to sweep.
 - During red phase — never refactor while red. See [`tdd/SKILL.md`](../tdd/SKILL.md).
 
-## The four lenses
+## The five lenses
 
 Walk every changed file. Apply each lens in order. Fix what you find inline.
 
@@ -49,14 +47,7 @@ Walk every changed file. Apply each lens in order. Fix what you find inline.
 - Names that read clearly out of context — would a stranger guess what `result`, `data`, `value` referred to? If not, rename.
 - Error messages that name the failing input — `"could not parse: <value>"` beats `"parse error"`.
 - Abstractions that haven't earned their keep — a base class with one subclass, an interface with one implementation. Inline.
-- Comments — **default during the sweep is DELETE**:
-  - Delete WHAT-comments (the code already says it).
-  - Delete docstrings on exports whose contract is obvious from the signature.
-  - Delete "used by X" / "added for Y" caller references — these rot; use grep.
-  - Delete commented-out code (git has it).
-  - Delete banner / ASCII-art dividers and in-function section headers (`// validate`, `// build response`).
-  - KEEP only why-comments — constraint, invariant, trade-off, provenance — and only when the next reader would otherwise reattempt the rejected alternative.
-  - If a kept comment cites a round / ADR / AC / snapshot, normalize to [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md) §3 (`ADR-007 §7`, `R6 AC-3`, `v0.3 R1b2`, `snapshot §"Invariants"`).
+- Comments — **default during the sweep is DELETE.** Apply [`CODE-HYGIENE.md`](../formats/CODE-HYGIENE.md) Principle 6 and the bar in [`STYLE-comments.md`](../formats/STYLE-comments.md): delete WHAT-comments, obvious-from-signature docstrings, "used by X" caller references, commented-out code, banners, and in-function section headers (`// validate`, `// build response`); keep only why-comments the next reader would otherwise reattempt. Normalize any kept citation (`ADR-007 §7`, `R6 AC-3`, `v0.3 R1b2`) to [`STYLE-comments.md`](../formats/STYLE-comments.md) §3.
 
 ### 3. Efficiency — dead code, redundant work, premature defensive checks
 
@@ -100,7 +91,7 @@ In single-feature flow (no rounds), the sweep can land as a separate commit befo
 ## Pairing with other skills
 
 - **`tdd`** runs first. Simplify runs after green. Never simplify while red.
-- **`code-hygiene`** is the lens — its 5 principles (boring code, naming, YAGNI, rule of 3, locality) are what you apply during the sweep. Read it once; apply it many times.
+- **[`code-hygiene`](../formats/CODE-HYGIENE.md)** is the lens — its seven principles (boring code, naming, YAGNI, rule of 3, locality, comments, constants placement) are what you apply during the sweep. Read it once; apply it many times.
 - **`pr-review`** comes after — a self-check against the diff. Some of the same lenses, applied as a reviewer rather than an author.
 - **`improve-codebase-architecture`** is the escalation — when simplify surfaces structural issues bigger than a sweep can fix.
 

package/skills/system-design/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: system-design
 description: System-level architecture for greenfield work — name the modules, define responsibilities, set dependency direction, identify seams. Use when starting a new multi-module system or service from scratch, when defining topology before code lands, or when the user mentions "system architecture", "module boundaries", "service boundaries", "how should I structure this system", "draw the architecture", "topology". Skip for single-module work — use `design` instead. Skip for reorganizing an existing codebase — use `improve-codebase-architecture`. Pairs with `investigate` (comes before, surveying options) and `design` (comes after, shaping each module's interface).
-complexity: high
-expected_duration: 30 minutes
 ---
 
 # System Design
@@ -38,7 +36,7 @@ Before drawing anything, read what already exists:
 - `docs/adr/` — decisions already taken.
 - The feature set — what the system has to do.
 
-If `CONTEXT.md` doesn't exist yet, **resolve the core domain terms first** — defer to [`grill-plan` bootstrap mode](../grill-plan/BOOTSTRAP.md) (single source of truth for the lazy-creation rules). Module names without domain terms are placeholders.
+If `CONTEXT.md` doesn't exist yet, **resolve the core domain terms first** — defer to [`grill-plan` bootstrap mode](../bootstrap/BOOTSTRAP.md) (single source of truth for the lazy-creation rules). Module names without domain terms are placeholders.
 
 ### 2. List the modules
 

package/skills/tdd/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: tdd
 description: Test-driven development with the red-green-refactor loop. Use when implementing a feature, fixing a bug, changing core logic, or when the user mentions "TDD", "test-first", "red-green-refactor", or "integration tests". Skip for trivial UI glue, config changes, or pure docs edits.
-complexity: medium
-expected_duration: 20 minutes
 ---
 
 # Test-Driven Development

package/skills/tdd-rounds/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: tdd-rounds
 description: Multi-round TDD orchestration. Use when delivering a feature larger than one TDD slice — typically 5-15 acceptance criteria across multiple packages — by dispatching Builder sub-agents per round, with the parent maintaining state and verifying. Triggered when the user mentions "drive the sub-agent team", "multi-round TDD", "orchestrate rounds", "Builder agents", or when a plan from `feature-doc` lists more ACs than one agent should reasonably tackle in a single invocation. Pairs with `tdd` (Builders invoke that skill per round) and `prod-ready` (final round before tag).
-complexity: high
-expected_duration: 1 hour
 ---
 
 # Multi-Round TDD Orchestration

package/skills/verify-real-deps/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: verify-real-deps
 description: Pre-tag smoke test against real third-party APIs. Use after `prod-ready` is clean, before tagging vN.0 — the gate that catches wire-shape mismatches that fakes accept but real upstreams reject. Triggered when the user mentions "smoke test", "real API", "live verify", "before tag", or "end-to-end against actual <vendor>". Pairs with `prod-ready` (which catches ops/infra issues tests miss) and `tdd-rounds` (the orchestration that feeds into this gate).
-complexity: high
-expected_duration: 45 minutes
 ---
 
 # Verify Against Real Dependencies

package/skills/zoom-out/SKILL.md

@@ -2,8 +2,6 @@
 name: zoom-out
 description: User-invoked utility — pulls the agent up an abstraction layer when the user is lost in unfamiliar code. Produces a map of relevant modules, callers, and seams in `docs/CONTEXT.md` vocabulary. Use when the user says "I'm lost", "zoom out", "give me higher-level context", "I don't know this area", "what depends on what here", or invokes the slash command. Does not change which workflow the user is in — interrupts to orient, then hands back. Skip when the user already has the map and just needs to read code.
 disable-model-invocation: true
-complexity: low
-expected_duration: 5 minutes
 ---
 
 # Zoom Out

package/skills/sync-check/SKILL.md

@@ -1,69 +0,0 @@
----
-name: sync-check
-description: Diagnostic "Context Auditor" that scans code changes for terminology drift against `CONTEXT.md` and architectural contradictions against `docs/adr/`. Use before `pr-review`, after significant refactors, or when names feel "off." Prevents term collisions (e.g., "Account" vs "Customer") and silent deviations from established architectural decisions. Pairs with `grill-plan` (to resolve contradictions found) and `pr-review` (downstream gate).
-complexity: low
-expected_duration: 10 minutes
----
-
-# Sync Check (Context Auditor)
-
-The discipline of ensuring that the code's implementation matches the project's **Domain Language** and **Architectural History**.
-
-## Why this skill exists
-
-As a codebase grows, it is easy for synonyms ("User", "Account", "Profile") to bleed into the code, diluting the domain model. Similarly, architectural decisions recorded in ADRs are often forgotten by developers (or LLMs) focused on local implementation. `sync-check` is the background auditor that surfaces these drifts before they calcify.
-
-## When to use
-
-- Before starting a `pr-review` (as a primary step).
-- After a large refactor round in `tdd-rounds`.
-- When you encounter a term in the code that isn't in `CONTEXT.md`.
-- When the user asks "is this consistent with our model?" or "are we following our ADRs?"
-
-## When to skip
-
-- Initial project setup (pre-vocabulary).
-- Pure doc/comment changes.
-- Trivial typo/config fixes.
-
-## Process
-
-### 1. Identify the Scope
-
-Map the files changed in the current branch or round to their corresponding domain contexts.
-- Use `CONTEXT-MAP.md` if it exists.
-- Otherwise, use the root `CONTEXT.md`.
-
-### 2. Terminology Audit
-
-Scan the `git diff` for new or changed public identifiers (classes, functions, types, variables).
-
-- **Term Collision**: Check if a new term is listed as an `_Avoid_:` alias in `CONTEXT.md`.
-- **Fuzzy Mapping**: Check if a term exists in the code but is missing from the glossary.
-- **Synonym Drift**: Check if the code uses two different words for the same domain concept.
-
-### 3. ADR Consistency Check
-
-Read the `docs/adr/` entries relevant to the changed packages.
-
-- **Direct Contradiction**: Does the change perform an action explicitly forbidden by an ADR (e.g., using an ORM when an ADR mandates manual SQL)?
-- **Surprise Deviation**: Does the change introduce a pattern that warrants a new ADR (hard to reverse, surprising, real trade-off)?
-
-### 4. Report Drifts
-
-Output a numbered list of findings. For each:
-- **Location**: `file:line` or `ADR-NNNN`.
-- **Severity**: `Blocker` (direct contradiction/collision) or `Suggestion` (fuzzy mapping).
-- **Finding**: "Code uses 'Account', but `CONTEXT.md` specifies 'Customer'."
-- **Recommended Action**: "Rename to 'Customer' or update `CONTEXT.md` if the concept is genuinely new."
-
-## Done when
-
-- All changed files have been cross-referenced with the glossary and relevant ADRs.
-- Every "Avoid" alias found in the diff has been flagged.
-- Every architectural deviation from active ADRs has been surfaced.
-
-## Handoff
-
-- If contradictions are found → run `grill-plan` to resolve the terminology or architectural mismatch.
-- If clean → proceed to `pr-review`.