@ai-agent-lead/skills 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +3 -1
  2. package/package.json +1 -1
  3. package/skills/README.md +18 -15
  4. package/skills/TRIGGERS.md +6 -0
  5. package/skills/WORKFLOWS.md +18 -9
  6. package/skills/caveman/SKILL.md +60 -0
  7. package/skills/code-hygiene/SKILL.md +17 -2
  8. package/skills/formats/STYLE-comments.md +113 -0
  9. package/skills/pr-review/SKILL.md +1 -0
  10. package/skills/simplify/SKILL.md +7 -1
  11. package/skills/tdd-rounds/SKILL.md +14 -1
package/README.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  A library of Claude Code skills that encode engineering discipline so Claude follows it by default.
4
4
 
5
+ **Website:** [AgentLead.Dev](https://AgentLead.Dev)
6
+
5
7
  ## Why
6
8
 
7
9
  Out of the box Claude writes code competently, but shipping well needs more than that: investigate before building, design the interface before writing, test-first, review at PR boundaries, and verify before merge.
@@ -19,7 +21,7 @@ The goal: turn engineering discipline from something I have to enforce into some
19
21
  You can install all the skills in this repository directly using `npx`:
20
22
 
21
23
  ```bash
22
- npx github:ai-agent-lead/skills
24
+ npx @ai-agent-lead/skills
23
25
  ```
24
26
 
25
27
  ### Options and Customization
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ai-agent-lead/skills",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Install AI agent skills for Claude Code, Codex, Antigravity, and OpenCode",
5
5
  "main": "bin/install.js",
6
6
  "bin": {
package/skills/README.md CHANGED
@@ -41,6 +41,7 @@ Grouped by role. Trigger phrases are in each skill's `description` frontmatter.
41
41
 
42
42
  | Skill | Trigger | Produces | Location |
43
43
  | --- | --- | --- | --- |
44
+ | `sync-check` | Before pr-review or after refactor | Terminology/ADR drift report | [sync-check/](./sync-check/) |
44
45
  | `prod-ready` | After tdd green, before merge | Verified pre-merge checklist (incl. doc drift) | [prod-ready/](./prod-ready/) |
45
46
  | `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/) |
46
47
  | `pr-review` | Reviewing someone else's PR (or self-reviewing before opening) | Structured review with severity-classified findings (blocker / suggestion / nit / question) | [pr-review/](./pr-review/) |
@@ -52,16 +53,16 @@ Orthogonal axis. The trigger-phrase index above tells you *when* a skill fires;
52
53
 
53
54
  | Role | Skills | What they have in common |
54
55
  | --- | --- | --- |
55
- | **Doc-producing** (writes a durable artifact under `docs/`) | `feature-doc`, `investigate`, `system-design`, `grill-plan`, `debug` (optional), `security-review` (optional), `verify-real-deps` | Output survives the conversation. The discipline of writing it is the value. |
56
+ | **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. |
56
57
  | **Build** (writes code) | `tdd`, `tdd-rounds`, `simplify` | Diff-producing. Always behind a contract (feature doc + ACs). |
57
- | **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. |
58
+ | **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. |
58
59
  | **Diagnose** (no code, no doc — just analysis) | `debug`, `zoom-out`, `sync-check` | Run *before* a build skill when the input isn't yet clear. |
59
60
  | **Shape** (decides module / topology) | `design`, `system-design`, `improve-codebase-architecture` | Greenfield-module / greenfield-system / brownfield. Same vocabulary ([`LANGUAGE.md`](./LANGUAGE.md)). |
60
- | **Lens** (applied during other skills, not invoked alone) | `code-hygiene` | Five principles you carry into `simplify`, `pr-review`, and any code-reading session. |
61
+ | **Lens** (applied during other skills, not invoked alone) | `code-hygiene`, `caveman` | Principles you carry into any turn to maintain quality or efficiency. |
61
62
 
62
63
  ## Skill relationship map
63
64
 
64
- The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
65
+ The 20 skills + their dependencies. Lateral edges are vocabulary / lens; vertical edges are workflow flow.
65
66
 
66
67
  ```
67
68
  ┌─────────────────────────────────────────────┐
@@ -80,16 +81,16 @@ The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
80
81
  │ │ ▲ │ │ prod-ready│
81
82
  │ │ │ │ │ │ │
82
83
  │ └──────────────┘ │ │ ▼ │
83
- │ │ │ pr-review │
84
+ │ │ │ sync-check │
84
85
  │ system-design ──► design (per mod) ─┘ │ │ │
85
86
  │ │ │ ▼ │
86
- │ ▼ │ verify-real-deps │
87
+ │ ▼ │ pr-review │
87
88
  │ docs/architecture.md │ │ │
88
89
  │ │ ▼ │
89
- │ improve-codebase-architecture ─────────────────┘ [merge] │
90
- │ ▲ │
91
- │ │ │
92
- │ tdd-rounds (orchestrator) ── dispatches Builders ──────────────│
90
+ │ improve-codebase-architecture ─────────────────┘ verify-real-deps│
91
+ │ ▲ │ │
92
+ │ │ ▼ │
93
+ │ tdd-rounds (orchestrator) ── dispatches Builders ────── [merge]│
93
94
  │ │ ▲ ▲ ▲ │
94
95
  │ │ │ │ │ │
95
96
  │ │ debug security-review │
@@ -97,7 +98,7 @@ The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
97
98
  │ │
98
99
  │ ┌────────────── LENSES & UTILITIES ──────────────┐ │
99
100
  │ │ code-hygiene ──► applied during simplify, │ │
100
- │ │ pr-review, any code reading │ │
101
+ │ │ caveman ──► pr-review, any code reading │ │
101
102
  │ │ │ │
102
103
  │ │ zoom-out ──► interrupts any workflow, │ │
103
104
  │ │ maps unfamiliar areas │ │
@@ -105,14 +106,16 @@ The 16 skills + their dependencies. Lateral edges are vocabulary / lens; vertica
105
106
  └──────────────────────────────────────────────────────────────────┘
106
107
  ```
107
108
 
108
- **Six things the map shows:**
109
+ **Seven things the map shows:**
109
110
 
110
- 1. `code-hygiene` and `zoom-out` are not nodes in any flow — they're lenses / utilities applied across.
111
+ 1. `code-hygiene`, `caveman`, and `zoom-out` are not nodes in any flow — they're lenses / utilities applied across.
111
112
  2. `grill-plan` is the only skill invoked from three upstreams (`investigate`, `feature-doc`, `improve-codebase-architecture`) — it's the shared pressure-test step.
112
113
  3. `tdd-rounds` is the only multi-callee orchestrator — dispatches `design`, `tdd`, `simplify`, `prod-ready`, `verify-real-deps` to Builders.
113
114
  4. `pr-review` is the reviewer-side mirror of `prod-ready` — Section 7 doc-drift covered in both.
114
- 5. `system-design` and `improve-codebase-architecture` are duals — same [LANGUAGE.md](./LANGUAGE.md), greenfield vs brownfield.
115
- 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.
115
+ 5. `sync-check` sits before `pr-review` as a final terminology and ADR audit.
116
+ 6. `system-design` and `improve-codebase-architecture` are duals — same [LANGUAGE.md](./LANGUAGE.md), greenfield vs brownfield.
117
+ 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.
118
+
116
119
 
117
120
  ## Workflows
118
121
 
package/skills/TRIGGERS.md CHANGED
@@ -25,6 +25,12 @@ If a phrase appears in multiple rows, the disambiguation column names how to cho
25
25
  | "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. |
26
26
  | "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`). |
27
27
 
28
+ ## Utilities & efficiency
29
+
30
+ | Phrase / situation | Routes to | Disambiguator |
31
+ | --- | --- | --- |
32
+ | "caveman mode", "be concise", "save tokens", "ooga booga" | [`caveman`](caveman/SKILL.md) | Token optimization lens. |
33
+
28
34
  ## Implementation
29
35
 
30
36
  | Phrase / situation | Routes to | Disambiguator |
package/skills/WORKFLOWS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Workflows
2
2
 
3
- How the 16 skills compose into the common paths users actually walk.
3
+ How the 20 skills compose into the common paths users actually walk.
4
4
 
5
5
  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.
6
6
 
@@ -32,6 +32,8 @@ Got a task? Pick by what you have in front of you:
32
32
  │ Surface-changing work (auth, public │ /security-review (gate, runs │
33
33
  │ API, sensitive data, new entry pt)│ alongside Workflow 1/2/6) │
34
34
  ├─────────────────────────────────────┼──────────────────────────────────┤
35
+ │ Audit terminology or ADR compliance │ /sync-check (gate) │
36
+ ├─────────────────────────────────────┼──────────────────────────────────┤
35
37
  │ Lost in unfamiliar area, mid-task │ /zoom-out (utility, anytime) │
36
38
  └─────────────────────────────────────┴──────────────────────────────────┘
37
39
  ```
@@ -73,6 +75,9 @@ For a single-package feature with a manageable acceptance-criteria count.
73
75
  prod-ready ──── 7-section checklist
74
76
  │
75
77
  ▼
78
+ sync-check ──── terminology and ADR audit
79
+ │
80
+ ▼
76
81
  (optional) pr-review ── self-check against the diff before opening
77
82
  │
78
83
  ▼
@@ -331,19 +336,21 @@ A few things that happen across all workflows:
331
336
 
332
337
  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.
333
338
 
334
- 5. **`debug` runs *before* `tdd` for non-trivial bugs.** Workflow 5b makes this explicit. The reproduction from `debug` becomes the failing test for `tdd`. Skip for bugs whose root cause is obvious from the trace (Workflow 5a).
339
+ 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.
340
+
341
+ 6. **`debug` runs *before* `tdd` for non-trivial bugs.** Workflow 5b makes this explicit. The reproduction from `debug` becomes the failing test for `tdd`. Skip for bugs whose root cause is obvious from the trace (Workflow 5a).
335
342
 
336
- 6. **`security-review` is a gate, not a workflow.** Fires when a change is **surface-changing** — new entry point, identity / session / token flow, authorization logic, sensitive-data path, new external dependency, secrets handling. Runs alongside `design` and `tdd` in Workflows 1, 2, 4, 5a, 5b, 6 whenever those criteria hit. Not a substitute for `prod-ready` Section 3 — both run when the surface changes.
343
+ 7. **`security-review` is a gate, not a workflow.** Fires when a change is **surface-changing** — new entry point, identity / session / token flow, authorization logic, sensitive-data path, new external dependency, secrets handling. Runs alongside `design` and `tdd` in Workflows 1, 2, 4, 5a, 5b, 6 whenever those criteria hit. Not a substitute for `prod-ready` Section 3 — both run when the surface changes.
337
344
 
338
- 7. **`pr-review` is a utility workflow.** Runs when reviewing someone else's PR. Also runs (lighter form) as a self-check before opening the PR. The `tdd-rounds` parent's per-round verification borrows from it.
345
+ 8. **`pr-review` is a utility workflow.** Runs when reviewing someone else's PR. Also runs (lighter form) as a self-check before opening the PR. The `tdd-rounds` parent's per-round verification borrows from it.
339
346
 
340
- 8. **`prod-ready` is the universal pre-merge gate** for Workflows 1, 2, 4, and sometimes 5. Single exit ramp before opening a PR.
347
+ 9. **`prod-ready` is the universal pre-merge gate** for Workflows 1, 2, 4, and sometimes 5. Single exit ramp before opening a PR.
341
348
 
342
- 9. **`verify-real-deps` fires whenever a workflow ends in a tagged release that touches a third-party API.** Most commonly that's Workflow 2 (large feature → tag), but it also applies when Workflow 1, 4, or 6 culminates in a release whose code path talks to an upstream you don't control. It does **not** fire for pure-internal services with database-only state, or for continuous-deploy environments that don't tag.
349
+ 10. **`verify-real-deps` fires whenever a workflow ends in a tagged release that touches a third-party API.** Most commonly that's Workflow 2 (large feature → tag), but it also applies when Workflow 1, 4, or 6 culminates in a release whose code path talks to an upstream you don't control. It does **not** fire for pure-internal services with database-only state, or for continuous-deploy environments that don't tag.
343
350
 
344
- 10. **`system-design` runs once per system, not per feature.** It's the greenfield precursor to Workflows 1 and 2. Once the topology is set, individual features run their own Workflow 1 or 2 inside it.
351
+ 11. **`system-design` runs once per system, not per feature.** It's the greenfield precursor to Workflows 1 and 2. Once the topology is set, individual features run their own Workflow 1 or 2 inside it.
345
352
 
346
- 11. **Vocabulary is shared.** All architecture-talking skills (`design`, `system-design`, `improve-codebase-architecture`, `pr-review`, `grill-plan`) read from [`skills/LANGUAGE.md`](./LANGUAGE.md). Format references (ADRs, CONTEXT.md) live in [`skills/formats/`](./formats/). Domain vocabulary (Customer, Order, etc.) lives in `docs/CONTEXT.md`. Keep them distinct.
353
+ 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.
347
354
 
348
355
  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.
349
356
 
@@ -359,7 +366,9 @@ A few things that happen across all workflows:
359
366
  | `docs/adr/<n>-<topic>.md` | `grill-plan`, `improve-codebase-architecture` | One per architectural decision |
360
367
  | `docs/CONTEXT.md` | `grill-plan`, `improve-codebase-architecture` (inline updates) | One per repo / context |
361
368
  | `docs/architecture.md` | `system-design` | One per system (the system map) |
362
- | `docs/STATE.md` | `tdd-rounds` parent (append-only) | One per multi-round project |
369
+ | `docs/features/<name>/state/snapshot.md` | `tdd-rounds` parent | Living snapshot per feature |
370
+ | `docs/features/<name>/state/rounds/*.md` | `tdd-rounds` Builder | Immutable round logs |
371
+ | `docs/STATE.md` | `tdd-rounds` parent | Global manifest (index only) |
363
372
  | `docs/security/<feature>.md` | `security-review` (high-stakes only) | One per surface-changing feature where a feature-doc section isn't enough |
364
373
  | `docs/benchmarks/<feature>.md` | `bench` | One per performance-critical feature |
365
374
  | `docs/known-issues.md` | `verify-real-deps` | One per repo (post-mortem record) |
package/skills/caveman/SKILL.md ADDED
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: caveman
3
+ 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.
4
+ complexity: low
5
+ expected_duration: 5 minutes
6
+ ---
7
+
8
+ # Caveman Mode (Token Optimizer)
9
+
10
+ The discipline of "speaking in tokens" to minimize cost and maximize context window longevity.
11
+
12
+ ## Why this skill exists
13
+
14
+ Standard AI responses are often padded with 30-50% filler words ("Certainly," "I have completed," "As a senior engineer"). In long-running sessions or multi-round orchestration, this "politeness tax" adds up to significant cost and premature context exhaustion.
15
+
16
+ ## When to use
17
+
18
+ - The user explicitly invokes "caveman mode" or "ooga booga".
19
+ - The session is approaching context limits (warning from system).
20
+ - You are operating as a Builder sub-agent where brevity is the primary mandate.
21
+
22
+ ## When to skip
23
+
24
+ - The user asks for a detailed explanation or architectural rationale.
25
+ - You are producing a durable artifact (like a feature doc or ADR) where clarity and professional tone are required.
26
+
27
+ ## Process
28
+
29
+ ### 1. Strip the "Fluff"
30
+
31
+ Remove all conversational filler:
32
+ - "Sure, I can help with that."
33
+ - "I have successfully updated the file."
34
+ - "Let me know if you need anything else."
35
+
36
+ ### 2. Compress the Prose
37
+
38
+ Remove articles (a, an, the) and simplify verbs:
39
+ - **Normal**: "I am updating the user controller to handle the new session timeout logic."
40
+ - **Caveman**: "Update user controller. Handle session timeout."
41
+
42
+ ### 3. Bullet-Only Output
43
+
44
+ Prefer short, punchy bullet points over paragraphs. One line per action.
45
+
46
+ ## Anti-patterns
47
+
48
+ - **Losing Technical Accuracy.** Conciseness must not compromise path names, variable names, or command flags. `Update src/main.go` is good; `Fix file` is bad.
49
+ - **Being Rude.** Caveman mode is about *token density*, not hostility. It is a technical optimization, not a personality shift.
50
+
51
+ ## Pairing with other skills
52
+
53
+ - **[`tdd-rounds`](../tdd-rounds/SKILL.md)** — Excellent for Builder reports.
54
+ - **[`simplify`](../simplify/SKILL.md)** — Use to report the "before/after" of a cleanup pass.
55
+
56
+ ## Done when
57
+
58
+ - The response contains zero conversational filler.
59
+ - All technical details remain accurate and actionable.
60
+ - Token usage for the turn is significantly lower than a standard response.
package/skills/code-hygiene/SKILL.md CHANGED
@@ -66,9 +66,11 @@ Duplicate twice; extract on the third occurrence — not the second.
66
66
  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.
67
67
 
68
68
  **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.
69
+ 5. **Locality of behavior** — related code lives together; don't split by category.
70
+ 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.
69
71
 
70
- **Smell**: a helper function with one caller, or a base class with one subclass. That's an abstraction in search of a use.
71
-
72
+ ## When to use
73
+ ...
72
74
  ## Principle 5: Locality of behavior
73
75
 
74
76
  Related code lives close together. Don't split a system by *type of code* (`controllers/`, `services/`, `repositories/`) — split by *responsibility* (`orders/`, `billing/`, `auth/`).
@@ -77,6 +79,18 @@ Related code lives close together. Don't split a system by *type of code* (`cont
77
79
 
78
80
  **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.)
79
81
 
82
+ ## Principle 6: Comments earn their keep
83
+
84
+ 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.
85
+
86
+ **Smells**:
87
+ - A comment that restates the next line of code.
88
+ - A comment naming a caller — that reference rots the moment someone renames or removes the caller. Use `grep`.
89
+ - A TODO / FIXME / HACK with no owner, ticket, ADR, or date.
90
+ - Commented-out code "in case we need it again". Git has it.
91
+
92
+ **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).
93
+
80
94
  ## Done when
81
95
 
82
96
  - Names communicate intent — a stranger reads them and forms the right mental model.
@@ -84,6 +98,7 @@ Related code lives close together. Don't split a system by *type of code* (`cont
84
98
  - No "in case we need it" parameters, classes, or interfaces remain.
85
99
  - Duplications either survived the 2-occurrence test (left as-is) or proved themselves at the 3rd occurrence (extracted).
86
100
  - Related code lives near related code.
101
+ - Every surviving comment names a why, an invariant, a trade-off, or a provenance link. None restates the code.
87
102
 
88
103
  ## Pairing with other skills
89
104
 
package/skills/formats/STYLE-comments.md ADDED
@@ -0,0 +1,113 @@
1
+ # Comment Style
2
+
3
+ Codifies the comment discipline for this codebase. New contributors (human or agent) should match what's here, and what's already in the code, rather than re-deriving conventions per package.
4
+
5
+ > Default: write **no** comment. Add one only when the WHY is non-obvious.
6
+
7
+ The code's identifiers, types, and structure already explain the *what*. A comment earns its line only when it captures something the reader cannot recover by reading the next ten lines: a constraint, an invariant, a trade-off, a workaround, or a pointer to the decision record.
8
+
9
+ ---
10
+
11
+ ## 1. Five kinds of comment we keep
12
+
13
+ ### 1.1 Package docstring (required, one per package)
14
+
15
+ Every package starts with a multi-paragraph docstring block in its primary file.
16
+
17
+ Shape:
18
+ - One-line purpose.
19
+ - One paragraph on the design choice and its rationale.
20
+ - Round / ADR provenance for major decisions.
21
+ - The failure mode or invariant the next reader needs to know.
22
+
23
+ ### 1.2 Docstrings on every exported identifier (required)
24
+
25
+ - Starts with the identifier name (`// Cache stores …`, not `// Stores …`).
26
+ - Interface methods state the **contract**, not just the action: is the call cheap, idempotent, safe under concurrency, called once per request or many times?
27
+
28
+ ### 1.3 Invariant / constraint comments (encouraged)
29
+
30
+ A comment that catches a bug the next maintainer would otherwise write.
31
+ - `// Zero means 'unknown'` (and re-stated where the bug would bite).
32
+ - `// Selector must be cheap and side-effect-free; ServeHTTP may invoke Pick multiple times on 429 retry.`
33
+
34
+ ### 1.4 Trade-off comments (encouraged)
35
+
36
+ Name the alternative considered and why it lost. Cite the failure mode if the choice has one.
37
+
38
+ ### 1.5 Provenance comments (use the grammar in §3)
39
+
40
+ Anchor non-obvious behavior to its decision record (ADR, round, AC, snapshot).
41
+
42
+ ---
43
+
44
+ ## 2. Five kinds of comment we delete on sight
45
+
46
+ 1. **Restates the code.** `// increment i`, `// return the user`, `// loop over items`. The code already says it.
47
+ 2. **Commented-out code.** Git has it. Delete.
48
+ 3. **"Added for X" / "Used by Y" caller references.** These rot the day someone renames or removes the caller. Use `grep` instead.
49
+ 4. **Banner / ASCII-art dividers.** `// =====` and `// --- section ---`. Use a function or a file boundary, not a banner.
50
+ 5. **Stale TODO / FIXME / HACK with no owner, ticket, ADR, or date.** Either link it to a decision record or fix it now.
51
+
52
+ ---
53
+
54
+ ## 3. Provenance grammar (canonical forms)
55
+
56
+ When a comment cites the project record, use **exactly one** of these forms. Comments that follow the canonical grammar are greppable and stable.
57
+
58
+ | Kind | Canonical form | Examples |
59
+ | -------------------------------------- | ----------------------- | --------------------------------------- |
60
+ | Architectural decision record | `ADR-NNN §SECTION` | `ADR-007 §7`, `ADR-002 §"Routing"` |
61
+ | TDD round | `RN` | `R6`, `R3` |
62
+ | TDD round + acceptance criterion | `RN AC-M` | `R6 AC-3`, `R1 AC-12` |
63
+ | Tagged round + batch within a release | `vX.Y RNbM` | `v0.3 R1b2`, `v0.8 R2b1` |
64
+ | Dated verification | `<kind> YYYY-MM-DD` | `smoke-test 2026-05-09` |
65
+ | Feature state snapshot | `snapshot §SECTION` | `snapshot §"Invariants"` |
66
+
67
+ **Avoid** (normalize to the table above):
68
+ - `Round 6`, `round-six`, `R 6` → `R6`
69
+ - `ADR 007`, `ADR7`, `ADR-7`, `adr-007` → `ADR-007`
70
+ - `AC 3`, `AC3`, `ac-3` → `AC-3`
71
+ - Section anchors: prefer `§7` or `§"Quoted Heading"`; avoid `section 7`, `sec. 7`, `(7)`.
72
+
73
+ ---
74
+
75
+ ## 4. When the comment grows
76
+
77
+ If the explanation needs more than **~6 lines**, the right home is an ADR or a `docs/research/<topic>.md` note. Leave a one-line pointer in the code:
78
+
79
+ ```go
80
+ // Selection rationale: see docs/research/tier-spill.md and ADR-002 §"Routing".
81
+ ```
82
+
83
+ ---
84
+
85
+ ## 5. "Documented for the next reader" framing
86
+
87
+ When a comment exists because a future reader is **likely to make the opposite assumption**, say so explicitly:
88
+
89
+ ```go
90
+ // Cold-cache choice (documented for the next reader): an account whose
91
+ // (pk, model) is not yet in the cache is treated as INELIGIBLE …
92
+ ```
93
+
94
+ ---
95
+
96
+ ## 6. Test files
97
+
98
+ Non-trivial tests — those with fakes, harnesses, time control, channel-driven ceremonies, or unusual lifecycle — get a **5–20 line block comment at the top** of the file (or above the harness type) stating:
99
+ - What is **faked** versus real (and why each choice).
100
+ - Why the design (deterministic? avoid `time.Sleep`? exercise a specific retry path?).
101
+ - Which knobs are overridden for the test and to **what value**.
102
+
103
+ ---
104
+
105
+ ## 7. Done when
106
+
107
+ Apply this checklist during the [`simplify`](../simplify/SKILL.md) sweep or in code review:
108
+ - [ ] Every package has a docstring matching §1.1.
109
+ - [ ] Every exported identifier has a docstring starting with its name.
110
+ - [ ] Every comment that survived the sweep is a why, an invariant, a trade-off, or a provenance link — none restates the code.
111
+ - [ ] No commented-out code, no `// used by X`, no banner dividers, no orphan TODOs.
112
+ - [ ] Every provenance citation matches the canonical grammar in §3.
113
+ - [ ] Test files with non-trivial harnesses have a strategy preamble; trivial ones do not.
package/skills/pr-review/SKILL.md CHANGED
@@ -104,6 +104,7 @@ The doc-map is small enough to walk in 2–3 minutes. Skip it and you're trading
104
104
 
105
105
  Apply `code-hygiene` as a lens here, not as a primary phase:
106
106
 
107
+ - **Comment churn**: new WHAT-comments, 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)). These are nits individually; in aggregate they're a signal the author didn't run `simplify`. Flag as suggestions, not blockers.
107
108
  - Names that mislead (boolean returning non-bool, `getX` that mutates, `Manager`/`Helper` suffixes hiding what the thing is).
108
109
  - Cleverness that earns its cost? Or could be boring?
109
110
  - YAGNI — "in case we need it" parameters / interfaces / classes? Strip.
package/skills/simplify/SKILL.md CHANGED
@@ -49,7 +49,13 @@ Walk every changed file. Apply each lens in order. Fix what you find inline.
49
49
  - Names that read clearly out of context — would a stranger guess what `result`, `data`, `value` referred to? If not, rename.
50
50
  - Error messages that name the failing input — `"could not parse: <value>"` beats `"parse error"`.
51
51
  - Abstractions that haven't earned their keep — a base class with one subclass, an interface with one implementation. Inline.
52
- - Comments that explain *what* the code does — delete; the code already says it. Keep comments that explain *why* (a constraint, an invariant, a workaround).
52
+ - Comments:
53
+ - Delete WHAT-comments (the code already says it).
54
+ - Delete "used by X" / "added for Y" caller references — these rot; use grep.
55
+ - Delete commented-out code (git has it).
56
+ - Delete banner / ASCII-art dividers.
57
+ - KEEP why-comments: constraint, invariant, trade-off, provenance.
58
+ - If a kept comment cites a round / ADR / AC / snapshot, normalize to the project grammar in [`skills/formats/STYLE-comments.md`](../formats/STYLE-comments.md) (§3 — `ADR-007 §7`, `R6 AC-3`, `v0.3 R1b2`, `snapshot §"Invariants"`).
53
59
 
54
60
  ### 3. Efficiency — dead code, redundant work, premature defensive checks
55
61
 
package/skills/tdd-rounds/SKILL.md CHANGED
@@ -69,7 +69,7 @@ Known follow-ups: <one line>
69
69
  - **Builder stuck (test won't go green / design feels wrong).** Builder reports a *blocking* open question instead of thrashing. Hard rule: **Builder must not silently descope an AC.**
70
70
  - **Concrete escalation signals** (any one fires → stop and surface):
71
71
  - 3 consecutive failed attempts at making the same test green with the same approach.
72
- - 2 design-level questions that the brief + STATE.md + cited ADRs don't answer.
72
+ - 2 design-level questions that the brief + feature state + cited ADRs don't answer.
73
73
  - The Builder finds itself wanting to modify a file in the "must NOT touch" allowlist to make progress.
74
74
  - A new test would require mocking >3 internal collaborators (smell: design is wrong, not the test).
75
75
  - **Parent's response**: shrink scope (split the round), or invoke `design` explicitly with the friction described, or run `grill-plan` if a load-bearing decision is wobbling. Don't push the Builder to keep trying.
@@ -94,3 +94,16 @@ When the final round completes:
94
94
  1. Run `verify-real-deps`. Capture surfaced bugs into `docs/known-issues.md`.
95
95
  2. Iterate fix-rounds until clean, or document deferrals to vN.1 with rationale.
96
96
  3. Tag and publish via whatever release / distribution channel applies.
97
+ hape the Builder returns.
98
+
99
+ ## Supporting docs
100
+
101
+ - [`COMMITS.md`](COMMITS.md) — commit cadence and message style (per-AC slicing, `R<N>:` prefix, when single-commit is OK, honesty rule). Builders read this before the first commit.
102
+
103
+ ## Handoff
104
+
105
+ When the final round completes:
106
+
107
+ 1. Run `verify-real-deps`. Capture surfaced bugs into `docs/known-issues.md`.
108
+ 2. Iterate fix-rounds until clean, or document deferrals to vN.1 with rationale.
109
+ 3. Tag and publish via whatever release / distribution channel applies.