ronce-racine 0.5.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 (179) hide show
  1. package/AGENTS.md +90 -0
  2. package/LICENSE +21 -0
  3. package/README.md +281 -0
  4. package/agents/code-reviewer.md +33 -0
  5. package/agents/qa-tester.md +28 -0
  6. package/dist/hooks/README.md +182 -0
  7. package/dist/hooks/bash-npm-silent.mjs +81 -0
  8. package/dist/hooks/session-inject.mjs +53 -0
  9. package/dist/hooks/session-precompact.mjs +36 -0
  10. package/dist/hooks/session-writer.mjs +142 -0
  11. package/dist/hooks/skill-reminder.mjs +89 -0
  12. package/dist/hooks/truncate-bash-output.mjs +46 -0
  13. package/dist/hooks/truncate-output.mjs +88 -0
  14. package/dist/hooks/worktree-env-setup.mjs +123 -0
  15. package/dist/install.js +962 -0
  16. package/docs/adopting-a-repo.md +80 -0
  17. package/docs/architecture.md +76 -0
  18. package/docs/decisions.md +72 -0
  19. package/docs/developing.md +143 -0
  20. package/docs/evaluating-skills.md +41 -0
  21. package/docs/git-worktrees.md +62 -0
  22. package/docs/rules/clean-architecture-deps.md +66 -0
  23. package/docs/rules/commits.md +59 -0
  24. package/docs/rules/detection-gap-protocol.md +55 -0
  25. package/docs/rules/error-handling-discipline.md +62 -0
  26. package/docs/rules/minimal-code.md +58 -0
  27. package/docs/rules/no-raw-sql-interpolation.md +57 -0
  28. package/docs/rules/pre-commit-secret-detection.md +54 -0
  29. package/docs/rules/secure-logging.md +53 -0
  30. package/docs/rules/sql-migrations-discipline.md +58 -0
  31. package/docs/rules/subscription-cleanup.md +63 -0
  32. package/docs/rules/test-discipline.md +66 -0
  33. package/docs/rules/ui-states-complete.md +52 -0
  34. package/docs/templates/SKILL.template.md +66 -0
  35. package/docs/templates/rule.template.md +16 -0
  36. package/docs/writing-a-rule.md +43 -0
  37. package/docs/writing-a-skill.md +118 -0
  38. package/package.json +45 -0
  39. package/rules/clean-architecture-deps.md +20 -0
  40. package/rules/commits.md +16 -0
  41. package/rules/detection-gap-protocol.md +35 -0
  42. package/rules/error-handling-discipline.md +23 -0
  43. package/rules/minimal-code.md +32 -0
  44. package/rules/no-raw-sql-interpolation.md +20 -0
  45. package/rules/pre-commit-secret-detection.md +14 -0
  46. package/rules/secure-logging.md +16 -0
  47. package/rules/sql-migrations-discipline.md +18 -0
  48. package/rules/subscription-cleanup.md +22 -0
  49. package/rules/test-discipline.md +20 -0
  50. package/rules/ui-states-complete.md +23 -0
  51. package/scripts/subscription-leak-scan.ts +53 -0
  52. package/skills/adversarial-feature-challenge/README.md +65 -0
  53. package/skills/adversarial-feature-challenge/SKILL.md +96 -0
  54. package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
  55. package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
  56. package/skills/api-contract-versioning/README.md +62 -0
  57. package/skills/api-contract-versioning/SKILL.md +76 -0
  58. package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
  59. package/skills/audit-architecture/README.md +56 -0
  60. package/skills/audit-architecture/SKILL.md +97 -0
  61. package/skills/audit-architecture/reference/ar-architecture.md +275 -0
  62. package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
  63. package/skills/audit-architecture/reference/im-incidents.md +217 -0
  64. package/skills/audit-architecture/reference/pa-pannes.md +362 -0
  65. package/skills/audit-architecture/reference/re-recuperation.md +300 -0
  66. package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
  67. package/skills/audit-architecture/reference/su-support.md +180 -0
  68. package/skills/audit-ci-cd/README.md +54 -0
  69. package/skills/audit-ci-cd/SKILL.md +124 -0
  70. package/skills/audit-ci-cd/reference/artefacts.md +39 -0
  71. package/skills/audit-ci-cd/reference/deploiement.md +100 -0
  72. package/skills/audit-ci-cd/reference/dora.md +94 -0
  73. package/skills/audit-ci-cd/reference/iac.md +40 -0
  74. package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
  75. package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
  76. package/skills/audit-compliance/README.md +69 -0
  77. package/skills/audit-compliance/SKILL.md +176 -0
  78. package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
  79. package/skills/audit-compliance/reference/finops.md +318 -0
  80. package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
  81. package/skills/audit-industrialisation/README.md +53 -0
  82. package/skills/audit-industrialisation/SKILL.md +251 -0
  83. package/skills/audit-observability/README.md +64 -0
  84. package/skills/audit-observability/SKILL.md +134 -0
  85. package/skills/audit-observability/reference/alerting.md +214 -0
  86. package/skills/audit-observability/reference/logging.md +114 -0
  87. package/skills/audit-observability/reference/metriques.md +166 -0
  88. package/skills/audit-observability/reference/traces-dashboards.md +90 -0
  89. package/skills/audit-performance-frontend/README.md +91 -0
  90. package/skills/audit-performance-frontend/SKILL.md +194 -0
  91. package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
  92. package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
  93. package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
  94. package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
  95. package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
  96. package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
  97. package/skills/audit-quality/README.md +85 -0
  98. package/skills/audit-quality/SKILL.md +126 -0
  99. package/skills/audit-quality/reference/qa-devops.md +539 -0
  100. package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
  101. package/skills/audit-report/README.md +72 -0
  102. package/skills/audit-report/SKILL.md +241 -0
  103. package/skills/audit-report/reference/scoring-model.md +45 -0
  104. package/skills/audit-security/README.md +72 -0
  105. package/skills/audit-security/SKILL.md +140 -0
  106. package/skills/audit-security/reference/auth-identite.md +98 -0
  107. package/skills/audit-security/reference/autorisation.md +66 -0
  108. package/skills/audit-security/reference/chiffrement-tls.md +97 -0
  109. package/skills/audit-security/reference/detection-patching.md +67 -0
  110. package/skills/audit-security/reference/incident-response.md +98 -0
  111. package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
  112. package/skills/audit-security/reference/secrets.md +36 -0
  113. package/skills/audit-testing/README.md +82 -0
  114. package/skills/audit-testing/SKILL.md +131 -0
  115. package/skills/audit-testing/reference/golden-dataset.md +65 -0
  116. package/skills/audit-testing/reference/resilience-chaos.md +93 -0
  117. package/skills/audit-testing/reference/tests-contractuels.md +65 -0
  118. package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
  119. package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
  120. package/skills/bug-ticket-root-cause/README.md +67 -0
  121. package/skills/bug-ticket-root-cause/SKILL.md +86 -0
  122. package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
  123. package/skills/bug-triage-structured/README.md +63 -0
  124. package/skills/bug-triage-structured/SKILL.md +104 -0
  125. package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
  126. package/skills/ci-pipeline-orchestration/README.md +55 -0
  127. package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
  128. package/skills/commit-readiness-review/README.md +66 -0
  129. package/skills/commit-readiness-review/SKILL.md +82 -0
  130. package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
  131. package/skills/comprehensive-test-strategy/README.md +64 -0
  132. package/skills/comprehensive-test-strategy/SKILL.md +108 -0
  133. package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
  134. package/skills/daily-workflow-optimization/README.md +56 -0
  135. package/skills/daily-workflow-optimization/SKILL.md +80 -0
  136. package/skills/database-schema-evolution/README.md +54 -0
  137. package/skills/database-schema-evolution/SKILL.md +107 -0
  138. package/skills/ddd-backend-implementation/README.md +63 -0
  139. package/skills/ddd-backend-implementation/SKILL.md +95 -0
  140. package/skills/design-system-component-lifecycle/README.md +56 -0
  141. package/skills/design-system-component-lifecycle/SKILL.md +97 -0
  142. package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
  143. package/skills/detection-sweep/README.md +58 -0
  144. package/skills/detection-sweep/SKILL.md +93 -0
  145. package/skills/detection-sweep/scripts/sweep.ts +80 -0
  146. package/skills/domain-modeling-design/README.md +57 -0
  147. package/skills/domain-modeling-design/SKILL.md +83 -0
  148. package/skills/frontend-fullstack-implementation/README.md +60 -0
  149. package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
  150. package/skills/frontend-spec-call-site-audit/README.md +66 -0
  151. package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
  152. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
  153. package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
  154. package/skills/merge-request-review/README.md +60 -0
  155. package/skills/merge-request-review/SKILL.md +77 -0
  156. package/skills/merge-request-review/templates/mr-review-report.md +29 -0
  157. package/skills/production-incident-diagnostic/README.md +63 -0
  158. package/skills/production-incident-diagnostic/SKILL.md +103 -0
  159. package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
  160. package/skills/qa-session-intake/README.md +56 -0
  161. package/skills/qa-session-intake/SKILL.md +78 -0
  162. package/skills/recording-decisions/README.md +91 -0
  163. package/skills/recording-decisions/SKILL.md +84 -0
  164. package/skills/recurring-bug-root-cause/README.md +64 -0
  165. package/skills/recurring-bug-root-cause/SKILL.md +93 -0
  166. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
  167. package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
  168. package/skills/refactoring-shared-component-api/README.md +50 -0
  169. package/skills/refactoring-shared-component-api/SKILL.md +84 -0
  170. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
  171. package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
  172. package/skills/validating-features-end-to-end/README.md +50 -0
  173. package/skills/validating-features-end-to-end/SKILL.md +90 -0
  174. package/skills/visual-regression-check/README.md +51 -0
  175. package/skills/visual-regression-check/SKILL.md +89 -0
  176. package/skills/writing-robust-tests/README.md +53 -0
  177. package/skills/writing-robust-tests/SKILL.md +88 -0
  178. package/templates/.adopted.example +8 -0
  179. package/templates/anti-drift.gitlab-ci.yml +23 -0
package/AGENTS.md ADDED
@@ -0,0 +1,90 @@
1
+ # Agent guide - Ronce Racine
2
+
3
+ Doc aimed at an agent (LLM) that **works on** this repo or uses it to **equip another project**. For the conceptual detail, see `docs/architecture.md`.
4
+
5
+ ## What this repo is
6
+
7
+ Canonical source of **generic Claude Code config** (project-agnostic), installable in any repository:
8
+ `rules/` (always-on, by `paths`) · `skills/` (on-demand workflows) · `hooks/` (settings.json scripts - granular, one hook per `.ts` file) · `agents/` (subagents) · `scripts/` (executable detections). CLI: `install.ts` is the single tool (all families; rules-only via `--rules-only`).
9
+
10
+ ## Non-negotiable rules
11
+
12
+ - **Genericity**: an artifact here contains **no** project coupling (crate/script/path name, imposed tracker, imposed stack). If useful but coupled → split: the generic principle here, the tooling in the project repo. A routing override "e.g. acme-app → `x`, it wins" is allowed.
13
+ - **Language**: English (code identifiers may remain as-is). Correct accents, "siliceum" always lowercase.
14
+ - **Commits**: `type(scope): description` format (`feat|fix|refactor|test|docs|chore`), 1st line ≤ 72 chars, **never** mention Claude/AI/LLM. **Ask for confirmation before any commit.**
15
+ - **Pre-commit validation**: `npm test` must be **green** (see Harness).
16
+
17
+ ## Using this repo on another project
18
+
19
+ ```bash
20
+ npx ronce-racine plan <repo> # detects the stack, PROPOSES (read-only)
21
+ npx ronce-racine install <repo> [--all] # copies relevant rules/skills/hooks/agents + lockfile
22
+ npx ronce-racine check <repo> [--strict] # drift vs canonical (soft, or blocking)
23
+ npx ronce-racine detach <repo> <kind:name> # excludes a customized artifact from control
24
+ ```
25
+ Detail: `docs/adopting-a-repo.md`. The lockfile `<repo>/.claude/.ronce-racine.json` tracks what is managed + the source package version and content hash.
26
+
27
+ ## Adding / modifying a hook
28
+
29
+ Hooks live in `hooks/`: one `.ts` file per logical hook. Each file must carry in its header JSDoc:
30
+
31
+ ```
32
+ * @version X.Y.Z (semver)
33
+ * @last-reviewed YYYY-MM-DD
34
+ ```
35
+
36
+ The `tools/skills.ts hooks` harness checks these two fields on every `npm test`. Available wirings per hook:
37
+
38
+ | Hook | Event | Matcher |
39
+ |------|-----------|---------|
40
+ | `skill-reminder.ts` | `UserPromptSubmit` | none |
41
+ | `bash-npm-silent.ts` | `PreToolUse` | `Bash` |
42
+ | `truncate-output.ts` | `PreToolUse` | `Bash` |
43
+ | `session-writer.ts` | `Stop` | none |
44
+ | `session-inject.ts` | `SessionStart` | `compact` |
45
+ | `session-precompact.ts` | `PreCompact` | none |
46
+ | `worktree-env-setup.ts` | `SessionStart` | none |
47
+
48
+ The `install.ts` installer merges the hook wirings for the selected hooks into `<repo>/.claude/settings.json` (deep-merge by event + matcher, idempotent, writes a `settings.json.bak` backup, preserves unrelated settings).
49
+
50
+ ## Modifying / adding a skill
51
+
52
+ 1. Read `docs/writing-a-skill.md` (contract) + `docs/templates/SKILL.template.md` (model).
53
+ 2. The skill must be generic, follow the standard sections, and have a `name` + `description` frontmatter ("Use when …", third person, **describes WHEN not HOW**) + `version` (semver) + `metadata.last-reviewed` + `category`.
54
+ 3. Body < 500 lines; beyond that → progressive disclosure (`reference/*.md`). Runnable detection → `scripts/*.ts` (never `.sh`). Output template → `templates/`.
55
+ 4. Bump `version` + `last-reviewed`, add a line to the `## Changelog`.
56
+ 5. `npm test` green, then update the table in `README.md`.
57
+
58
+ ## Modifying / adding a rule
59
+
60
+ 1. Read `docs/writing-a-rule.md` + `docs/templates/rule.template.md`.
61
+ 2. Frontmatter: `paths` (globs; omit = always-on) + `version` + `metadata.last-reviewed`. Body: imperative, short bullets, no magic numbers.
62
+ 3. `npm test` green + `README.md` table.
63
+
64
+ ## Harness (`npm test`)
65
+
66
+ Five axes, all must pass:
67
+ - `tools/skills.ts validate` - frontmatter, version, sections, `reference/`/`scripts/`/`templates/` links, depth ≤ 1.
68
+ - `tools/skills.ts triggers` - routing discriminability (each quoted trigger classifies its skill in the top-3).
69
+ - `tools/skills.ts rules` - versioning of the rules.
70
+ - `tools/skills.ts scripts` - existence and non-emptiness of each `.ts` in `scripts/`.
71
+ - `tools/skills.ts hooks` - presence and validity of `@version` (semver) and `@last-reviewed` (ISO date) in each `hooks/*.ts`.
72
+
73
+ Useful commands: `npm run skills:list`, `npm run skills:triggers`, `npm run rules:validate`, `npm run typecheck`.
74
+
75
+ ## Layout
76
+
77
+ ```
78
+ rules/ skills/<name>/SKILL.md (+ reference/ scripts/ templates/)
79
+ hooks/ agents/ scripts/
80
+ install.ts (user-facing CLI, at the root)
81
+ tools/ (internal harnesses: skills.ts, tests.ts, mutations.ts, eval.ts, all via tsx)
82
+ docs/ templates/ README.md AGENTS.md
83
+ ```
84
+
85
+ ## Common pitfalls
86
+
87
+ - Do not summarize a skill's workflow in its `description` (the agent would follow the summary instead of the skill).
88
+ - In a SKILL.md, only reference **existing** `reference/`/`scripts/`/`templates/` files (the harness checks).
89
+ - No `.sh`: every script/hook is `.ts` run by `tsx`.
90
+ - Any discipline still coupled (RLS, compiled queries, conventions of a specific framework) stays **on the project side**, not here.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Cedric Chariere Fiedler
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,281 @@
1
+ ![Ronce Racine](assets/header.webp)
2
+
3
+ # Ronce Racine
4
+
5
+ Canonical source of **generic [Claude Code](https://claude.com/claude-code) config** (project-agnostic), installable in any repository. It provides a layer of *always-on* disciplines and *on-demand* workflows that spreads into every project:
6
+
7
+ - **`rules/`**: *always-on* rules, injected by file type (`paths:`)
8
+ - **`skills/`**: *on-demand* workflows, invoked as needed (versioned, validated by a harness)
9
+ - **`hooks/`**: reusable Claude Code hooks to wire into `settings.json`
10
+ - **`agents/`**: generic subagent definitions to copy into `<repo>/.claude/agents/`
11
+ - **`scripts/`**: executable detection scripts (TypeScript via `tsx`, read-only)
12
+
13
+ An artifact lives here **only if it is truly generic**: no coupling to a project (no specific crate, script, path, or identifier name, no imposed tracker). Project-specific variants stay on the project side (`<repo>/.claude/rules/<project>/`, `<repo>/.claude/skills/`). The doc's examples use fictional project names (`acme-app`, `beta-app`).
14
+
15
+ > Admission criteria → [`docs/writing-a-rule.md`](docs/writing-a-rule.md) (rules) · [`docs/writing-a-skill.md`](docs/writing-a-skill.md) (skills)
16
+ > An agent (LLM) that operates on this repo or installs it elsewhere → [`AGENTS.md`](AGENTS.md)
17
+
18
+ ## Why Ronce Racine, not copy-paste?
19
+
20
+ Copy-pasted `.claude/` config **rots**: every repo drifts, and nobody remembers which rule came from where. Ronce Racine keeps **one canonical source** installed into many repos, with a **lockfile + anti-drift CI gate** so they never silently diverge, plus a smart installer that proposes only what fits each project's stack. That is what plain copy-paste and hand-rolled per-repo config don't give you: **fleet-wide consistency you can enforce in CI**, while any repo can still `detach` an artifact to customize it.
21
+
22
+ ## Requirements
23
+
24
+ - **Node ≥ 18**. The installer runs via `npx ronce-racine`, no clone needed; the target repo needs **only Node**, because hooks ship pre-built (`dist/hooks/*.js`).
25
+ - **rules / skills / agents are plain Markdown** and need no toolchain at all.
26
+
27
+ ## The name
28
+
29
+ *Ronce Racine* means "bramble root" in English. A bramble roots deeply and spreads everywhere, unkillable: the exact image of a layer of *always-on* disciplines that takes root in every project and refuses to die, with just enough thorns to remind you it says "discipline". The two words are singular, joined in the style of the ecosystem the project comes from.
30
+
31
+ > *In English:* **Ronce Racine** is French for "bramble root", a plant that roots deep and spreads everywhere, unkillable. A fitting name for a layer of engineering discipline meant to take hold in every repository.
32
+
33
+ ## Two distribution layers
34
+
35
+ ```mermaid
36
+ flowchart LR
37
+ C["ronce-racine<br/>(rules/*.md)"]
38
+ G["~/.claude/rules/shared<br/>(symlink)"]
39
+ R1["repo A<br/>.claude/rules/shared/*"]
40
+ R2["repo B<br/>.claude/rules/shared/*"]
41
+ C -- "symlink (personal, all machines)" --> G
42
+ C -- "ronce-racine install --rules-only (real files, git)" --> R1
43
+ C -- "ronce-racine install --rules-only" --> R2
44
+ G -. "all your projects, interactive" .-> R1
45
+ ```
46
+
47
+ | Layer | Mechanism | Scope |
48
+ |--------|-----------|--------|
49
+ | **Global (personal)** | `~/.claude/rules/shared` → symlink to `rules/` | All your machines, all your projects, interactive. Not versioned per project. |
50
+ | **Per-repo (team / CI)** | `ronce-racine install <repo> --rules-only` copies real files into `<repo>/.claude/rules/shared/` | Travels via git → teammates + headless/CI agents |
51
+
52
+ The two coexist: an adopted repo loads its project copy (which takes precedence) **and** the global layer; identical content → no effect. Detail → [`docs/architecture.md`](docs/architecture.md).
53
+
54
+ ## Available rules (`rules/`)
55
+
56
+ | File | Scope (`paths`) | Purpose |
57
+ |---------|------------------|-------|
58
+ | `minimal-code.md` | code (rs/ts/tsx/vue/py/go) | YAGNI + readability > brevity guardrail |
59
+ | `commits.md` | always active | commit message format |
60
+ | `test-discipline.md` | `*.spec.ts` / `*.test.ts` | test discipline (generic core) |
61
+ | `secure-logging.md` | `*.rs` / `*.ts` | GDPR: never log sensitive data |
62
+ | `detection-gap-protocol.md` | `docs/postmortems/**` | a P0 found by a user = a detection failure |
63
+ | `sql-migrations-discipline.md` | `**/migrations/**` | immutable, idempotent, expand-contract migrations |
64
+ | `pre-commit-secret-detection.md` | always active | no secret committed (gitleaks + grep fallback) |
65
+ | `subscription-cleanup.md` | front-end code (ts/tsx/js/vue) | explicit teardown of subscriptions/listeners/timers |
66
+ | `error-handling-discipline.md` | code (ts/py/go/rs/php/java) | no swallowed error, no panic/unwrap on fallible |
67
+ | `clean-architecture-deps.md` | code (ts/py/go/rs/php/java) | dependencies toward the domain, no logic in the handler |
68
+ | `no-raw-sql-interpolation.md` | code (ts/py/go/rs/php/java) | parameterized queries, never SQL interpolation |
69
+ | `ui-states-complete.md` | components (tsx/jsx/vue/svelte) | loading/error/empty/success all handled and distinguishable |
70
+
71
+ Each rule also carries `version` + `metadata.last-reviewed` (parity with the skills), validated by `npm test`.
72
+
73
+ ## What a day looks like
74
+
75
+ Skills are not invoked by name from a menu: their `description` carries trigger
76
+ phrases, and the agent picks the right one from what you ask. Below is what
77
+ actually fires, in order, on three common jobs. Nothing here is a special
78
+ command - it is plain English, in either language.
79
+
80
+ ### Starting on a repo (once)
81
+
82
+ ```bash
83
+ npx ronce-racine plan . # read-only: what fits this repo, and why
84
+ npx ronce-racine install . # copies into .claude/, wires the hooks
85
+ git add .claude && git commit # the config travels with the repo
86
+ ```
87
+
88
+ `plan` reads the repo's signals (stack, tests, SQL, CI, infra) and proposes
89
+ only what they justify: a Go service with no frontend gets neither the UI rules
90
+ nor the frontend skills. Add the [anti-drift CI job](templates/anti-drift.gitlab-ci.yml)
91
+ and the config can no longer rot silently.
92
+
93
+ ### Implementing a feature
94
+
95
+ | You say | What runs | What you get |
96
+ |---|---|---|
97
+ | *"model the billing domain"* | `domain-modeling-design` | aggregates, invariants and their placement, written down, **no code yet** |
98
+ | *"implement it"* | `ddd-backend-implementation` or `frontend-fullstack-implementation` | layered implementation; the frontend one refuses to ship without loading/error/empty/success states |
99
+ | *"write tests for it"* | `writing-robust-tests` | tests you have **seen fail** before they pass, no hard waits, no fragile locators |
100
+ | *"does it actually work?"* | `validating-features-end-to-end` | the feature exercised for real, evidence pasted, not "the unit tests are green" |
101
+ | *"is it really ready?"* | `adversarial-feature-challenge` | at least two personas attack it; zero flaws found means a bad challenge, not a perfect feature |
102
+ | *"commit this"* | `commit-readiness-review` | staged diff scanned for secrets, debug leftovers and disabled tests before anything is written |
103
+
104
+ ### Fixing a bug
105
+
106
+ | You say | What runs | What you get |
107
+ |---|---|---|
108
+ | *"this is broken: …"* | `bug-triage-structured` | reproduction, root cause with `file:line`, then an argued fix-now-or-ticket decision |
109
+ | *(the scope already had 2+ recent fixes)* | `recurring-bug-root-cause` | it stops treating the symptom: a blocking guardrail, so the class cannot come back |
110
+ | *"I'm not fixing it now"* | `bug-ticket-root-cause` | a ticket carrying the cause and a red-then-green confirmation test, not just the symptom |
111
+
112
+ The triage step now runs `git log --grep="fix(<scope>)"` rather than trusting
113
+ memory, because evaluation runs showed agents skipping the recurrence check.
114
+
115
+ ### Auditing an existing project
116
+
117
+ ```
118
+ "audit industrialisation" -> 8 domain audits in parallel, consolidated report,
119
+ 214 questions, 0-4 maturity scoring
120
+ "audit sécurité" -> one domain only
121
+ ```
122
+
123
+ Heavyweight and opt-in: reach for it on a periodic review, not day to day.
124
+
125
+ ## Available skills (`skills/`)
126
+
127
+ Generalized (project-agnostic) versions of the heavy workflows. The project variants (coupled to a tracker, a stack, scripts) stay in the relevant repo. Each skill carries a semver `version` + `metadata` in its frontmatter and follows the standard contract (see [`docs/writing-a-skill.md`](docs/writing-a-skill.md)).
128
+
129
+ **Daily drivers**: the discipline skills you reach for during normal development:
130
+
131
+ | Family | Skills |
132
+ |---------|--------|
133
+ | Tests & quality | `writing-robust-tests` · `comprehensive-test-strategy` · `adversarial-feature-challenge` · `validating-features-end-to-end` · `commit-readiness-review` · `detection-sweep` |
134
+ | Design & implementation | `domain-modeling-design` · `ddd-backend-implementation` · `api-contract-versioning` · `database-schema-evolution` |
135
+ | Frontend | `frontend-spec-call-site-audit` · `frontend-fullstack-implementation` · `refactoring-shared-component-api` · `design-system-component-lifecycle` · `visual-regression-check` |
136
+ | Bugs / recurrence | `bug-triage-structured` · `bug-ticket-root-cause` · `recurring-bug-root-cause` |
137
+ | Ops & review | `merge-request-review` · `ci-pipeline-orchestration` · `production-incident-diagnostic` |
138
+ | Process | `recording-decisions` · `qa-session-intake` · `daily-workflow-optimization` |
139
+
140
+ **Advanced: industrialization audit (opt-in)**: a heavyweight maturity-assessment suite for periodic reviews, not day-to-day use. Install it only if you run engineering audits:
141
+
142
+ | Orchestrator | Domain audits |
143
+ |---------|--------|
144
+ | `audit-industrialisation` (runs the domains + consolidates) → `audit-report` | `audit-architecture` · `audit-ci-cd` · `audit-compliance` · `audit-observability` · `audit-performance-frontend` · `audit-quality` · `audit-security` · `audit-testing` |
145
+
146
+ > Deliberately excluded: `git-workflow`, `jira-bug` (coupled to a specific project: dedicated branch hierarchy and Jira tracker).
147
+
148
+ Some skills embed detection `scripts/` (read-only) and `reference/` files loaded on demand (progressive disclosure of the audit grids). Validation: `npm test` (the `tools/skills.ts` harness).
149
+
150
+ Distribution: the **smart installer** (`ronce-racine`, see below) copies the relevant skills into `<repo>/.claude/skills/` and watches their drift. Manually: copy the desired folder into `~/.claude/skills/` (global) or `<repo>/.claude/skills/` (per-repo). `ronce-racine` is the single CLI for all families (rules/skills/hooks/agents); for rules only, use `ronce-racine install <repo> --rules-only`.
151
+
152
+ ## Available scripts (`scripts/`)
153
+
154
+ Executable detection scripts (TypeScript, `tsx`, read-only). Referenceable from a skill via `scripts/<file>`.
155
+
156
+ | File | Scope | Purpose |
157
+ |---------|--------|-------|
158
+ | `subscription-leak-scan.ts` | frontend (staged git diff) | subscription/listener/timer leaks |
159
+
160
+ ## Quickstart
161
+
162
+ > The package is not on npm yet: the commands below are the adoption path as of
163
+ > the next release. Until then, clone the repo and run `npx tsx install.ts plan .`
164
+ > from it (see [`docs/developing.md`](docs/developing.md)).
165
+
166
+ ```bash
167
+ # 1. Propose an adapted install for your project (read-only)
168
+ npx ronce-racine plan .
169
+
170
+ # 2. Apply it, then review the diff before committing
171
+ npx ronce-racine install .
172
+ ```
173
+
174
+ ![Propose, install, then catch a local edit with the drift gate](assets/demo.gif)
175
+
176
+ The same run as text, on a full-stack repo (`plan` is read-only, nothing is written):
177
+
178
+ ```console
179
+ $ npx ronce-racine plan ./my-app
180
+ Analysis of ./my-app
181
+ Signals: git (.git/), ci (CI config), infra (Docker/infra), frontend (frontend
182
+ dependencies), backend (Node backend dependencies), tests (E2E deps), code (sources detected)
183
+
184
+ ✓ Recommended (installed by default):
185
+ Rules (9) :
186
+ • minimal-code - YAGNI + readability, any code project
187
+ • commits - commit message format
188
+ • secure-logging - GDPR: never log sensitive data
189
+ • pre-commit-secret-detection - no committed secrets
190
+ • test-discipline - tests detected
191
+ • subscription-cleanup - frontend: subscription teardown
192
+ • clean-architecture-deps - backend: dependency direction
193
+ … 2 more
194
+ Skills (21) :
195
+ • commit-readiness-review - self-review before commit
196
+ • detection-sweep - project detection sweep
197
+ • recurring-bug-root-cause - recurring bug → root cause
198
+ • ci-pipeline-orchestration - CI detected: check/diagnose/retry
199
+ … 17 more
200
+ Scripts (1) :
201
+ • subscription-leak-scan.ts - detects subscriptions/listeners/timers without teardown
202
+ Hooks (3) :
203
+ • skill-reminder.ts - suggests the relevant skills for the prompt
204
+ • bash-npm-silent.ts - silences npm install/ci (less noise)
205
+ • truncate-output.ts - caps verbose output (cargo/git/docker…)
206
+ Agents (2) :
207
+ • code-reviewer - diff review agent
208
+ • qa-tester - E2E testing agent
209
+ ```
210
+
211
+ Each artifact is proposed because a signal justified it: a Go repo with no frontend gets
212
+ neither `subscription-cleanup` nor the frontend skills. Try it on throwaway repos with
213
+ [`playground/setup.ts`](playground/README.md).
214
+
215
+ The installer runs code on your machine and wires hooks into your `settings.json`. Read [`SECURITY.md`](SECURITY.md) first to know exactly what runs and when.
216
+
217
+ ## Adopting in a repo
218
+
219
+ ### Smart installer (recommended)
220
+
221
+ `ronce-racine` scans the target project (stack, tests, SQL, migrations, CI, infra, git) and **proposes** the relevant rules/skills/hooks/agents, then installs on confirmation. Full procedure → [`docs/adopting-a-repo.md`](docs/adopting-a-repo.md).
222
+
223
+ ```bash
224
+ npx ronce-racine plan <repo> # proposes (read-only)
225
+ npx ronce-racine install <repo> [--all] # applies (--all = + optionals)
226
+ ```
227
+
228
+ Copies rules (+ the `.adopted` manifest), skills, hooks and agents into `<repo>/.claude/`, and **merges the hook wirings into `<repo>/.claude/settings.json`** (deep-merge by event/matcher, idempotent, backs up an existing file to `settings.json.bak`, preserves unrelated settings). Check the diff, then commit.
229
+
230
+ ### Rules only
231
+
232
+ ```bash
233
+ npx ronce-racine install <repo> --rules-only # rules + lockfile only
234
+ ```
235
+
236
+ Then wire the anti-drift CI gate → [`templates/anti-drift.gitlab-ci.yml`](templates/anti-drift.gitlab-ci.yml).
237
+
238
+ ## Global setup (once per machine)
239
+
240
+ ```bash
241
+ # Symlink the canonical rules folder as your global shared layer.
242
+ # Remove any individual rule file previously copied to ~/.claude/rules/ that
243
+ # would otherwise duplicate the symlinked set (e.g. an old minimal-code.md).
244
+ ln -s /path/to/ronce-racine/rules ~/.claude/rules/shared
245
+ ```
246
+
247
+ ## CLI
248
+
249
+ ```bash
250
+ npx ronce-racine plan <repo> # proposes an install adapted to the repo's stack
251
+ npx ronce-racine install <repo> [--all] # installs rules+skills+hooks+agents (--all = + optionals)
252
+ npx ronce-racine install <repo> --rules-only# installs only the rules
253
+ npx ronce-racine check <repo> [--strict] # drift vs canonical (soft, or blocking)
254
+ npx ronce-racine detach <repo> <token> # excludes a customized artifact from control
255
+ npm test # validates artifacts (structure + routing + versioning) AND runs behavioral tests
256
+ npm run skills:list # lists the version + category of each skill
257
+ npm run rules:validate # validates the versioning of the rules
258
+ ```
259
+
260
+ ## Hooks (`hooks/`)
261
+
262
+ Generic Claude Code hooks (detail → [`hooks/README.md`](hooks/README.md)). The installer offers them à la carte and **merges the selected ones into `<repo>/.claude/settings.json`** for you (idempotent, with a backup).
263
+
264
+ | Hook | Event | Role |
265
+ |------|-----------|------|
266
+ | `skill-reminder.ts` | `UserPromptSubmit` | Suggests the relevant skills based on the prompt (self-maintained, silent when there is no match) |
267
+ | `bash-npm-silent.ts` | `PreToolUse / Bash` | Appends `--silent` to setup `npm install` / `npm ci` to reduce context noise |
268
+ | `truncate-output.ts` (+ helper `truncate-bash-output.ts`) | `PreToolUse / Bash` | Truncates verbose output beyond a threshold; always preserves the output on error |
269
+ | `session-writer` + `session-inject` + `session-precompact` | `Stop` / `SessionStart(compact)` / `PreCompact` | Session-memo trio: persists the context at session end, re-injects it after compaction |
270
+ | `worktree-env-setup.ts` | `SessionStart` | Symlinks the main repo's `.env` into the current worktree (idempotent, fail-open) |
271
+
272
+ All scripts/hooks are TypeScript (run via `tsx`), no `.sh`. These hooks run **automatically** on Claude Code lifecycle events once wired. See [`SECURITY.md`](SECURITY.md) for exactly what each one does and the two to scrutinize (`worktree-env-setup.ts` symlinks your `.env`; the session-memo hooks write to disk).
273
+
274
+ ## Agents (`agents/`)
275
+
276
+ Generic subagent definitions (project-agnostic), to copy into `<repo>/.claude/agents/`:
277
+
278
+ - `code-reviewer`: architecture/reliability/correctness review of a diff, read-only, actionable verdict.
279
+ - `qa-tester`: running/writing E2E tests (stable locators, zero hard waits).
280
+
281
+ A project agent (coupled to the stack, the credentials, the tracker) takes precedence over its generic version.
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: code-reviewer
3
+ description: Use when reviewing code for correctness, architecture, reliability and clean boundaries - reviewing a diff/MR/PR, a new feature, or auditing an existing module before merge. Read-only: it reports findings, it does not edit.
4
+ tools: Read, Grep, Glob, Bash
5
+ ---
6
+
7
+ You are a senior code reviewer, language- and framework-agnostic. You bring a demand for clean architecture, reliability (resilience patterns, error handling, observability) and correctness. You **change nothing** - you produce an actionable review.
8
+
9
+ ## Method
10
+
11
+ 1. **Understand the intent** before judging: read the diff/ticket/spec, identify what the change is aiming for.
12
+ 2. **Read the code actually changed** (not just the file names) and its call sites.
13
+ 3. Evaluate in this order, from most to least severe:
14
+ - **Correctness**: bugs, unhandled edge cases, broken invariants, race conditions.
15
+ - **Contracts**: a change to a public API consumed elsewhere without synchronization (see the call sites).
16
+ - **Architecture**: dependency direction, separation of concerns, business logic at the right level, coupling.
17
+ - **Reliability**: swallowed errors, missing retries/timeouts/circuit breakers, unreleased resources, uncleaned subscriptions.
18
+ - **Security & data**: secrets in the clear, sensitive data logged, unvalidated inputs.
19
+ - **Tests**: is the change covered? Was a test seen failing? Hardcoded expectations / fragile locators?
20
+ - **Readability**: naming, overly long functions, dead code, premature abstraction.
21
+
22
+ ## Reporting
23
+
24
+ Findings ranked by severity (**blocking / major / minor / nit**), each with: file:line, the problem, and a concrete proposed fix. End with a **verdict**: approve / request changes, with the list of blockers.
25
+
26
+ ## Guardrails
27
+
28
+ - No hollow praise or restating of the diff: every review line delivers actionable information.
29
+ - Distinguish what is **wrong** (blocking) from what is **taste** (nit) - do not mix them.
30
+ - If a point depends on context you do not have, **ask** for it, do not invent it.
31
+ - Respect the repo's conventions (read a neighbor before proposing a different style).
32
+
33
+ > Related skills: `merge-request-review` (reviewing an MR/PR before merge), `commit-readiness-review` (before a commit), `writing-robust-tests` (test quality). If the repo has a specific review agent, it takes precedence.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: qa-tester
3
+ description: Use when running or writing end-to-end tests for a web app - executing an E2E suite, triaging failures, or adding E2E coverage for a flow. Drives a real browser; favors stable locators over timing hacks.
4
+ tools: Read, Grep, Glob, Bash
5
+ ---
6
+
7
+ You are an E2E QA tester, framework-agnostic (Playwright, Cypress…). You validate real user journeys in a browser and produce robust tests, not tests that pass by luck.
8
+
9
+ ## Before running
10
+
11
+ - Read the project's test config (`playwright.config.*` / `cypress.config.*`): base URL, projects/browsers, test credentials (never hardcoded in the test - env variables / project fixtures).
12
+ - Read an existing neighboring test and copy its conventions (page objects, helpers, fixtures) before inventing.
13
+
14
+ ## Discipline (non-negotiable)
15
+
16
+ 1. **`data-testid` for every locator** - never `text=`, placeholder, CSS class, or XPath. If the component doesn't have one, adding it is part of the task.
17
+ 2. **Page Object**: locators / actions / assertions separated, locators scoped to the parent.
18
+ 3. **Zero hard waits** (`waitForTimeout`, `sleep`) - wait for a concrete state: element visible, URL, network response.
19
+ 4. **Zero coupling to implementation timing**: drive or neutralize the clock, or test the state not the duration.
20
+ 5. **AAA**, a single *act*, one concept per test.
21
+ 6. **Level chosen deliberately**: true E2E (real backend + seeded data) covers the contract; mocking everything makes it a component test - declare it as such.
22
+
23
+ ## Execution & triage
24
+
25
+ - Run the suite, **paste the real output** (never "it should pass").
26
+ - For each failure: reproduce, isolate the cause (product regression vs fragile test vs data), report with the command and the trace. A test failing because of a missing `data-testid` → add the testid, don't work around it.
27
+
28
+ > Related skills: `writing-robust-tests` (ISTQB design + proof that a test can fail), `comprehensive-test-strategy` (coverage matrix), `visual-regression-check` (visual rendering). If the repo has a specific QA agent (credentials, golden dataset), it takes precedence.
@@ -0,0 +1,182 @@
1
+ # Reusable hooks
2
+
3
+ Generic Claude Code hooks, to be wired into `settings.json` (or a repo's `.claude/settings.json`). The harness runs these scripts; they depend on no particular project.
4
+
5
+ All scripts are TypeScript, run via `tsx` (like `install.ts`/`tools/skills.ts`). The target repo must have `tsx` available (`npx tsx` resolves it on the fly).
6
+
7
+ > **Note** - the `install.ts` installer copies the selected hooks and automatically composes the merged `settings.json` snippet - the manual wiring below is only useful for a hand install.
8
+
9
+ ---
10
+
11
+ ## `skill-reminder.ts` - skill suggestion (UserPromptSubmit)
12
+
13
+ On prompt submit, reads the descriptions of the skills present and suggests those whose triggers match. Self-maintained (no hardcoded list), silent when there is no match, never blocks.
14
+
15
+ Locates skills in this order: `$CLAUDE_PROJECT_DIR/.claude/skills`, `./.claude/skills`, `./skills`.
16
+
17
+ ```json
18
+ {
19
+ "hooks": {
20
+ "UserPromptSubmit": [
21
+ { "hooks": [{ "type": "command", "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/skill-reminder.ts" }] }
22
+ ]
23
+ }
24
+ }
25
+ ```
26
+
27
+ ---
28
+
29
+ ## `bash-npm-silent.ts` - silencing npm installs (PreToolUse)
30
+
31
+ **Event**: `PreToolUse` · **Matcher**: `Bash`
32
+
33
+ Intercepts `npm install` / `npm ci` calls with no package argument (build/setup) and appends `--silent` to reduce the noise injected into the context. If the command contains `# no-silent`, it is passed through unchanged.
34
+
35
+ Leaves interactive `npm install <pkg>` calls (adding a dependency) untouched.
36
+
37
+ **Bypass**: add `# no-silent` in the command.
38
+
39
+ ```json
40
+ {
41
+ "hooks": {
42
+ "PreToolUse": [
43
+ { "matcher": "Bash",
44
+ "hooks": [{ "type": "command",
45
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/bash-npm-silent.ts" }] }
46
+ ]
47
+ }
48
+ }
49
+ ```
50
+
51
+ ---
52
+
53
+ ## `truncate-output.ts` + `truncate-bash-output.ts` - truncating verbose output (PreToolUse)
54
+
55
+ **Event**: `PreToolUse` · **Matcher**: `Bash`
56
+
57
+ `truncate-output.ts` wraps verbose commands (`cargo build/test`, `npm install`, `git log`, `curl`…): their output is truncated beyond a character threshold. On error (exit ≠ 0), the full output is always preserved for debugging.
58
+
59
+ `truncate-bash-output.ts` is the helper script invoked by `truncate-output.ts` (actual execution + truncation) - it is not wired separately.
60
+
61
+ **Bypass**: add `# no-truncate` in the command.
62
+
63
+ ```json
64
+ {
65
+ "hooks": {
66
+ "PreToolUse": [
67
+ { "matcher": "Bash",
68
+ "hooks": [{ "type": "command",
69
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/truncate-output.ts" }] }
70
+ ]
71
+ }
72
+ }
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Session memo: `session-writer.ts` + `session-inject.ts` + `session-precompact.ts`
78
+
79
+ A coordinated trio that persists and re-injects the session context across compactions.
80
+
81
+ ### `session-writer.ts` - writing the memo (Stop)
82
+
83
+ **Event**: `Stop` · **Matcher**: none (every session end)
84
+
85
+ Writes a session memo to `~/.claude/projects/<repo-slug>/sessions/<branch>.md` (outside the repo, does not pollute `git status`).
86
+
87
+ ```json
88
+ {
89
+ "hooks": {
90
+ "Stop": [
91
+ { "hooks": [{ "type": "command",
92
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-writer.ts" }] }
93
+ ]
94
+ }
95
+ }
96
+ ```
97
+
98
+ ### `session-inject.ts` - re-injection after compaction (SessionStart)
99
+
100
+ **Event**: `SessionStart` · **Matcher**: `compact`
101
+
102
+ Re-reads the memo (written by `session-writer`) and injects it as `additionalContext`. Silent exit 0 if there is no memo for the current branch.
103
+
104
+ ```json
105
+ {
106
+ "hooks": {
107
+ "SessionStart": [
108
+ { "matcher": "compact",
109
+ "hooks": [{ "type": "command",
110
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-inject.ts" }] }
111
+ ]
112
+ }
113
+ }
114
+ ```
115
+
116
+ ### `session-precompact.ts` - anchoring before compaction (PreCompact)
117
+
118
+ **Event**: `PreCompact` · **Matcher**: none (every compaction)
119
+
120
+ Injects the memo as `systemMessage` into the compaction prompt, so the generated summary preserves the intent and context of the session.
121
+
122
+ ```json
123
+ {
124
+ "hooks": {
125
+ "PreCompact": [
126
+ { "hooks": [{ "type": "command",
127
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/session-precompact.ts" }] }
128
+ ]
129
+ }
130
+ }
131
+ ```
132
+
133
+ ---
134
+
135
+ ## `worktree-env-setup.ts` - `.env` symlink in worktrees (SessionStart)
136
+
137
+ **Event**: `SessionStart` · **Matcher**: none (every session)
138
+
139
+ If the session starts in a linked git worktree (not the main worktree) and the main repo has a `.env` that is absent from the worktree, creates a `.env → <main-repo>/.env` symlink. Idempotent, never overwrites an existing `.env`. Absolutely fail-open (any error → silent exit 0).
140
+
141
+ ```json
142
+ {
143
+ "hooks": {
144
+ "SessionStart": [
145
+ { "hooks": [{ "type": "command",
146
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/hooks/worktree-env-setup.ts" }] }
147
+ ]
148
+ }
149
+ }
150
+ ```
151
+
152
+ ---
153
+
154
+ ## `precommit-scan.ts` - secret/debug scan before commit
155
+
156
+ Shipped with the `commit-readiness-review` skill (`skills/commit-readiness-review/scripts/precommit-scan.ts`). Read-only, exit 1 if a secret/sensitive file is staged. Two possible wirings:
157
+
158
+ **Native git hook** (`.husky/pre-commit` or `.git/hooks/pre-commit`):
159
+ ```bash
160
+ exec npx tsx "$CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts/precommit-scan.ts"
161
+ ```
162
+
163
+ **Claude Code PreToolUse hook** (warns before a `git commit` launched by the agent):
164
+ ```json
165
+ {
166
+ "hooks": {
167
+ "PreToolUse": [
168
+ { "matcher": "Bash",
169
+ "hooks": [{ "type": "command",
170
+ "command": "npx tsx $CLAUDE_PROJECT_DIR/.claude/skills/commit-readiness-review/scripts/precommit-scan.ts || true" }] }
171
+ ]
172
+ }
173
+ }
174
+ ```
175
+
176
+ ---
177
+
178
+ ## Installing in a target repo
179
+
180
+ The `install.ts` installer copies the selected hooks and automatically composes the merged `settings.json` snippet - this is the recommended method.
181
+
182
+ For a manual install: copy the desired `.ts` files into `<repo>/.claude/hooks/`, then add the corresponding wiring to `<repo>/.claude/settings.json`. Paths use `$CLAUDE_PROJECT_DIR` (resolved by Claude Code) - no hardcoded absolute path.