ronce-racine 0.5.3 → 0.7.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 (63) hide show
  1. package/AGENTS.md +4 -2
  2. package/README.md +213 -207
  3. package/agents/code-reviewer.md +1 -1
  4. package/dist/hooks/README.md +40 -0
  5. package/dist/hooks/readme-freshness.mjs +159 -0
  6. package/dist/install.js +114 -711
  7. package/dist/src/catalog.js +80 -0
  8. package/dist/src/detect.js +140 -0
  9. package/dist/src/lock.js +200 -0
  10. package/dist/src/paths.js +25 -0
  11. package/dist/src/selector.js +324 -0
  12. package/dist/src/settings.js +55 -0
  13. package/dist/src/uninstall.js +170 -0
  14. package/docs/adopting-a-repo.md +29 -22
  15. package/docs/architecture.md +9 -10
  16. package/docs/catalog.md +86 -0
  17. package/docs/decisions.md +31 -13
  18. package/docs/developing.md +69 -29
  19. package/docs/distribution-model.md +130 -0
  20. package/docs/evaluating-skills.md +42 -2
  21. package/docs/git-worktrees.md +2 -2
  22. package/docs/quality-bar.md +55 -0
  23. package/docs/templates/rule.template.md +2 -1
  24. package/docs/writing-a-rule.md +13 -3
  25. package/docs/writing-a-skill.md +16 -7
  26. package/package.json +17 -4
  27. package/skills/adversarial-feature-challenge/SKILL.md +5 -3
  28. package/skills/api-contract-versioning/SKILL.md +6 -4
  29. package/skills/bug-ticket-root-cause/SKILL.md +5 -3
  30. package/skills/bug-triage-structured/SKILL.md +5 -3
  31. package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
  32. package/skills/commit-readiness-review/SKILL.md +7 -3
  33. package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
  34. package/skills/comprehensive-test-strategy/SKILL.md +5 -3
  35. package/skills/daily-workflow-optimization/SKILL.md +6 -4
  36. package/skills/database-schema-evolution/SKILL.md +6 -4
  37. package/skills/ddd-backend-implementation/SKILL.md +5 -3
  38. package/skills/design-system-component-lifecycle/SKILL.md +6 -4
  39. package/skills/detection-sweep/SKILL.md +7 -3
  40. package/skills/detection-sweep/scripts/sweep.ts +3 -3
  41. package/skills/domain-glossary/README.md +44 -0
  42. package/skills/domain-glossary/SKILL.md +166 -0
  43. package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
  44. package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
  45. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
  46. package/skills/merge-request-review/SKILL.md +5 -3
  47. package/skills/performance-profiling/README.md +69 -0
  48. package/skills/performance-profiling/SKILL.md +223 -0
  49. package/skills/performance-profiling/reference/go.md +235 -0
  50. package/skills/performance-profiling/reference/native.md +148 -0
  51. package/skills/performance-profiling/reference/node-web.md +157 -0
  52. package/skills/performance-profiling/reference/statistics.md +181 -0
  53. package/skills/performance-profiling/reference/tracy.md +137 -0
  54. package/skills/production-incident-diagnostic/SKILL.md +5 -3
  55. package/skills/qa-session-intake/SKILL.md +5 -3
  56. package/skills/recording-decisions/SKILL.md +5 -3
  57. package/skills/recurring-bug-root-cause/SKILL.md +5 -3
  58. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
  59. package/skills/refactoring-shared-component-api/SKILL.md +7 -3
  60. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
  61. package/skills/validating-features-end-to-end/SKILL.md +5 -3
  62. package/skills/visual-regression-check/SKILL.md +6 -4
  63. package/skills/writing-robust-tests/SKILL.md +8 -4
package/AGENTS.md CHANGED
@@ -12,7 +12,7 @@ Canonical source of **generic Claude Code config** (project-agnostic), installab
12
12
 
13
13
  ## Non-negotiable rules
14
14
 
15
- - **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.
15
+ - **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 precedence note ("if this repo has a specific X skill, it wins") is expected, and states what the project variant knows that this one cannot - without naming an example project.
16
16
  - **Language**: English (code identifiers may remain as-is). Correct accents, "siliceum" always lowercase.
17
17
  - **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.**
18
18
  - **Pre-commit validation**: `npm test` must be **green** (see Harness).
@@ -24,6 +24,7 @@ npx ronce-racine plan <repo> # detects the stack, PROPOSES (read-onl
24
24
  npx ronce-racine install <repo> [--all] # copies relevant rules/skills/hooks/agents + lockfile
25
25
  npx ronce-racine check <repo> [--strict] # drift vs canonical (soft, or blocking)
26
26
  npx ronce-racine detach <repo> <kind:name> # excludes a customized artifact from control
27
+ npx ronce-racine uninstall <repo> [--dry-run] # removes what the lockfile records, and only that
27
28
  ```
28
29
  Detail: `docs/adopting-a-repo.md`. The lockfile `<repo>/.claude/.ronce-racine.json` tracks what is managed + the source package version and content hash.
29
30
 
@@ -80,7 +81,8 @@ Useful commands: `npm run skills:list`, `npm run skills:triggers`, `npm run rule
80
81
  ```
81
82
  rules/ skills/<name>/SKILL.md (+ reference/ scripts/ templates/)
82
83
  hooks/ agents/ scripts/
83
- install.ts (user-facing CLI, at the root)
84
+ install.ts (user-facing CLI, at the root: commands + argument parsing)
85
+ src/ (the CLI split up: paths, lock, catalog, detect, settings, selector, uninstall)
84
86
  tools/ (internal harnesses: skills.ts, tests.ts, mutations.ts, eval.ts, all via tsx)
85
87
  docs/ templates/ README.md AGENTS.md
86
88
  ```
package/README.md CHANGED
@@ -5,282 +5,288 @@
5
5
  [![npm](https://img.shields.io/npm/v/ronce-racine)](https://www.npmjs.com/package/ronce-racine)
6
6
  [![license](https://img.shields.io/npm/l/ronce-racine)](LICENSE)
7
7
 
8
- 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:
8
+ **A personal [Claude Code](https://claude.com/claude-code) config, packaged so it
9
+ installs into any repository and stays up to date there.**
9
10
 
10
- - **`rules/`**: *always-on* rules, injected by file type (`paths:`)
11
- - **`skills/`**: *on-demand* workflows, invoked as needed (versioned, validated by a harness)
12
- - **`hooks/`**: reusable Claude Code hooks to wire into `settings.json`
13
- - **`agents/`**: generic subagent definitions to copy into `<repo>/.claude/agents/`
14
- - **`scripts/`**: executable detection scripts (TypeScript via `tsx`, read-only)
11
+ ```bash
12
+ npx ronce-racine plan . # read-only: what fits this repo, and why
13
+ ```
15
14
 
16
- 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`).
15
+ It is a set of habits I use every day, written down once and shipped by a CLI:
17
16
 
18
- > Admission criteria → [`docs/writing-a-rule.md`](docs/writing-a-rule.md) (rules) · [`docs/writing-a-skill.md`](docs/writing-a-skill.md) (skills)
19
- > An agent (LLM) that operates on this repo or installs it elsewhere → [`AGENTS.md`](AGENTS.md)
17
+ - **13 rules**, always on, injected by file type. The standing constraints an
18
+ agent should never need to be reminded of.
19
+ - **36 skills**, on demand. Procedures the agent loads when what you asked for
20
+ matches, from modeling a domain to triaging a bug.
21
+ - **6 hooks** (9 scripts), wired into `settings.json` for you. Small automatic
22
+ behaviors on Claude Code events.
23
+ - **2 agents** and **1 detection script**, for the jobs that deserve their own
24
+ context.
20
25
 
21
- ## Why Ronce Racine, not copy-paste?
26
+ Not a framework and not a team product. One person's working setup, made
27
+ installable so twelve repositories cannot quietly become twelve different
28
+ configurations.
22
29
 
23
- 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.
30
+ If you work across several repositories and keep telling Claude the same things,
31
+ this should save you the repeating. If you are looking for a team standard to
32
+ adopt wholesale, this is not one: take the parts you agree with.
24
33
 
25
- ## Requirements
34
+ [Quickstart](#quickstart) · [What you get](#what-you-get) · [How it is proven](#why-you-should-not-trust-the-tables-above) · [Staying in sync](#staying-in-sync) · [Install options](#install-options) · [Contributing](CONTRIBUTING.md)
26
35
 
27
- - **Node ≥ 18** in the target repo. The installer runs via `npx ronce-racine`,
28
- no clone needed, and hooks ship pre-built (`.mjs`) so they run on plain
29
- `node` with no TypeScript runtime.
30
- - **rules / skills / agents are plain Markdown** and need no toolchain at all.
31
- - **`tsx` only if you install a detection script.** The optional `scripts/*.ts`
32
- (secret scan, project sweep, call-site audit) ship as TypeScript and are run
33
- on demand with `npx tsx`. Skip them and Node alone is enough.
36
+ ## Why it is packaged at all
34
37
 
35
- ## The name
38
+ Copy-pasted `.claude/` config rots. You write a good rule in one project, paste
39
+ it into the next two, improve it in the third, and six months later no two
40
+ repositories agree. Nobody remembers which version came from where, and the CI
41
+ agent works from a config nobody has read since the day it landed.
36
42
 
37
- *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.
43
+ So the config is a package: an installer that proposes only what a project's
44
+ stack justifies, a lockfile so a repository that drifts says so, and `detach`
45
+ for the artifacts you customized on purpose.
38
46
 
39
- > *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.
40
-
41
- ## Two distribution layers
47
+ ## Quickstart
42
48
 
43
- ```mermaid
44
- flowchart LR
45
- C["ronce-racine<br/>(rules/*.md)"]
46
- G["~/.claude/rules/shared<br/>(symlink)"]
47
- R1["repo A<br/>.claude/rules/shared/*"]
48
- R2["repo B<br/>.claude/rules/shared/*"]
49
- C -- "symlink (personal, all machines)" --> G
50
- C -- "ronce-racine install --rules-only (real files, git)" --> R1
51
- C -- "ronce-racine install --rules-only" --> R2
52
- G -. "all your projects, interactive" .-> R1
49
+ ```bash
50
+ npx ronce-racine plan . # 1. read-only: what fits this repo, and why
51
+ npx ronce-racine install . # 2. apply, then review the diff before committing
53
52
  ```
54
53
 
55
- | Layer | Mechanism | Scope |
56
- |--------|-----------|--------|
57
- | **Global (personal)** | `~/.claude/rules/shared` → symlink to `rules/` | All your machines, all your projects, interactive. Not versioned per project. |
58
- | **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 |
54
+ ![Propose, install, then catch a local edit with the drift gate](assets/demo.gif)
59
55
 
60
- 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).
56
+ Nothing is written by `plan`. Here is a real run on a full-stack repository,
57
+ abridged:
61
58
 
62
- ## Available rules (`rules/`)
59
+ ```console
60
+ $ npx ronce-racine plan ./my-app
61
+ Analysis of ./my-app
62
+ Signals: git (.git/), ci (CI config), infra (Docker/infra), frontend (frontend dependencies), backend (Node backend dependencies), tests (E2E deps), code (sources detected)
63
63
 
64
- | File | Scope (`paths`) | Purpose |
65
- |---------|------------------|-------|
66
- | `minimal-code.md` | code (rs/ts/tsx/vue/py/go) | YAGNI + readability > brevity guardrail |
67
- | `commits.md` | always active | commit message format |
68
- | `test-discipline.md` | `*.spec.ts` / `*.test.ts` | test discipline (generic core) |
69
- | `secure-logging.md` | `*.rs` / `*.ts` | GDPR: never log sensitive data |
70
- | `detection-gap-protocol.md` | `docs/postmortems/**` | a P0 found by a user = a detection failure |
71
- | `sql-migrations-discipline.md` | `**/migrations/**` | immutable, idempotent, expand-contract migrations |
72
- | `pre-commit-secret-detection.md` | always active | no secret committed (gitleaks + grep fallback) |
73
- | `subscription-cleanup.md` | front-end code (ts/tsx/js/vue) | explicit teardown of subscriptions/listeners/timers |
74
- | `error-handling-discipline.md` | code (ts/py/go/rs/php/java) | no swallowed error, no panic/unwrap on fallible |
75
- | `clean-architecture-deps.md` | code (ts/py/go/rs/php/java) | dependencies toward the domain, no logic in the handler |
76
- | `no-raw-sql-interpolation.md` | code (ts/py/go/rs/php/java) | parameterized queries, never SQL interpolation |
77
- | `ui-states-complete.md` | components (tsx/jsx/vue/svelte) | loading/error/empty/success all handled and distinguishable |
78
- | `doc-code-parity.md` | Markdown (README, docs/) | documented commands are run before commit; behavior changes sweep the docs |
64
+ ✓ Recommended (installed by default):
65
+ Rules (10) :
66
+ • minimal-code - YAGNI + readability, any code project
67
+ • secure-logging - GDPR: never log sensitive data
68
+ • subscription-cleanup - frontend: subscription teardown
69
+ • clean-architecture-deps - backend: dependency direction
70
+ [... 6 more]
71
+ Skills (23) :
72
+ • recording-decisions - record non-obvious choices
73
+ • commit-readiness-review - self-review before commit (+ scripts/precommit-scan.ts)
74
+ • bug-triage-structured - full triage of a bug
75
+ [... 20 more]
76
+ Scripts (1) :
77
+ • subscription-leak-scan.ts - detects subscriptions/listeners/timers without teardown
78
+ Hooks (3) :
79
+ • skill-reminder.ts - suggests the relevant skills for the prompt
80
+ [... 2 more]
81
+ Agents (2) :
82
+ • code-reviewer - diff review agent
83
+ • qa-tester - E2E testing agent
79
84
 
80
- Each rule also carries `version` + `metadata.last-reviewed` (parity with the skills), validated by `npm test`.
85
+ • Optional (add with --all):
86
+ Rules (1) :
87
+ • detection-gap-protocol - P0 found by user = detection failure
88
+ Skills (12) :
89
+ • audit-industrialisation - maturity audit orchestrator
90
+ [... 11 more]
91
+ Hooks (3) :
92
+ • readme-freshness.ts - re-reads the README against what a push changes
93
+ [... 2 more]
94
+ ```
81
95
 
82
- ## What a day looks like
96
+ (The `[... n more]` lines mark where this transcript is abridged; a real run
97
+ prints every entry, then the exact install command to copy.)
83
98
 
84
- Skills are not invoked by name from a menu: their `description` carries trigger
85
- phrases, and the agent picks the right one from what you ask. Below is what
86
- actually fires, in order, on three common jobs. Nothing here is a special
87
- command - it is plain English, in either language.
99
+ Then `git add .claude && git commit`: the config travels with the repository, so
100
+ your teammates and your CI agent work from the same one you do.
88
101
 
89
- ### Starting on a repo (once)
102
+ > The installer runs code on your machine and wires hooks into your
103
+ > `settings.json`. [`SECURITY.md`](SECURITY.md) says exactly what runs and when.
104
+ > Worth two minutes before you install anything, here or anywhere else.
90
105
 
91
- ```bash
92
- npx ronce-racine plan . # read-only: what fits this repo, and why
93
- npx ronce-racine install . # copies into .claude/, wires the hooks
94
- git add .claude && git commit # the config travels with the repo
95
- ```
106
+ **Requirements**: Node 18 or later in the target repo, and nothing else. Hooks
107
+ ship pre-built, rules and skills are plain Markdown. Only the optional detection
108
+ scripts need `npx tsx`.
96
109
 
97
- `plan` reads the repo's signals (stack, tests, SQL, CI, infra) and proposes
98
- only what they justify: a Go service with no frontend gets neither the UI rules
99
- nor the frontend skills. Add the [anti-drift CI job](templates/anti-drift.gitlab-ci.yml)
100
- and the config can no longer rot silently.
110
+ ## What you get
101
111
 
102
- ### Implementing a feature
112
+ ### Rules: the constraints that are always on
103
113
 
104
- | You say | What runs | What you get |
105
- |---|---|---|
106
- | *"model the billing domain"* | `domain-modeling-design` | aggregates, invariants and their placement, written down, **no code yet** |
107
- | *"implement it"* | `ddd-backend-implementation` or `frontend-fullstack-implementation` | layered implementation; the frontend one refuses to ship without loading/error/empty/success states |
108
- | *"write tests for it"* | `writing-robust-tests` | tests you have **seen fail** before they pass, no hard waits, no fragile locators |
109
- | *"does it actually work?"* | `validating-features-end-to-end` | the feature exercised for real, evidence pasted, not "the unit tests are green" |
110
- | *"is it really ready?"* | `adversarial-feature-challenge` | at least two personas attack it; zero flaws found means a bad challenge, not a perfect feature |
111
- | *"commit this"* | `commit-readiness-review` | staged diff scanned for secrets, debug leftovers and disabled tests before anything is written |
114
+ Rules are injected automatically based on the files in play, so they cost you
115
+ nothing to remember. Each one exists because forgetting it produced a real
116
+ defect.
112
117
 
113
- ### Fixing a bug
118
+ | Rule | Applies to | What it prevents |
119
+ |---|---|---|
120
+ | `commits.md` | always | commit messages that nobody can scan six months later |
121
+ | `pre-commit-secret-detection.md` | always | a key or token reaching a commit, where a revert no longer saves you |
122
+ | `minimal-code.md` | code (rs/ts/tsx/vue/py/go) | speculative code, and its opposite: unreadable one-liners written to save a line |
123
+ | `error-handling-discipline.md` | code (ts/js/vue/py/go/rs/php/java) | swallowed errors, and a `panic`/`unwrap` on a fallible path |
124
+ | `doc-code-parity.md` | `README.md`, `docs/**` | a documented command that no longer matches the code, which the reader trusts anyway |
125
+ | `clean-architecture-deps.md` | code (ts/py/go/rs/php/java) | business logic leaking into handlers, dependencies pointing away from the domain |
126
+ | `no-raw-sql-interpolation.md` | code (ts/js/py/go/rs/php/java) | a query built by string concatenation, which is an injection |
127
+ | `sql-migrations-discipline.md` | `**/migrations/**` | a migration edited after it shipped, or one that cannot be replayed |
128
+ | `secure-logging.md` | `*.rs`, `*.ts` | an email, IP or token in the logs, which is a GDPR problem |
129
+ | `subscription-cleanup.md` | frontend (ts/tsx/js/jsx/vue) | subscriptions, listeners and timers with no teardown, and the leaks they cause |
130
+ | `ui-states-complete.md` | components (tsx/jsx/vue/svelte) | a screen that handles the happy path and shows nothing while loading or failing |
131
+ | `test-discipline.md` | `*.spec.ts`, `*.test.ts` | tests that pass without ever having been seen to fail |
132
+ | `detection-gap-protocol.md` | `docs/postmortems/**` | treating a P0 found by a user as a bug rather than as a detection failure |
133
+
134
+ ### Skills: the procedures, loaded on demand
135
+
136
+ There is nothing to type. Each skill's description carries trigger phrases, and
137
+ the agent loads the one that matches what you asked for, in English or in
138
+ French. Five that show the character of the set:
114
139
 
115
140
  | You say | What runs | What you get |
116
141
  |---|---|---|
117
- | *"this is broken: …"* | `bug-triage-structured` | reproduction, root cause with `file:line`, then an argued fix-now-or-ticket decision |
118
- | *(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 |
119
- | *"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 |
142
+ | *"this is broken: ..."* | `bug-triage-structured` | a reproduction, the root cause with `file:line`, then an argued fix-now-or-open-a-ticket decision |
143
+ | *"commit this"* | `commit-readiness-review` | the staged diff scanned for secrets, debug leftovers and disabled tests before anything is written |
144
+ | *"is it really ready?"* | `adversarial-feature-challenge` | the feature attacked from several personas; zero flaws found means a bad challenge, not a perfect feature |
145
+ | *"three names for the same thing here"* | `domain-glossary` | one name per concept in a `GLOSSARY.md`, the rejected synonyms recorded so a search for the wrong word still lands right |
146
+ | *"why is this slow?"* | `performance-profiling` | the noise floor measured before anything else, then a profile, with "inconclusive" as a valid answer |
120
147
 
121
- The triage step now runs `git log --grep="fix(<scope>)"` rather than trusting
122
- memory, because evaluation runs showed agents skipping the recurrence check.
148
+ The full set, grouped by intention:
123
149
 
124
- ### Auditing an existing project
125
-
126
- ```
127
- "audit industrialisation" -> 8 domain audits in parallel, consolidated report,
128
- 214 questions, 0-4 maturity scoring
129
- "audit sécurité" -> one domain only
130
- ```
150
+ | Group | Skills | For example |
151
+ |---|---|---|
152
+ | Designing, before code | 5 | `domain-modeling-design`, `comprehensive-test-strategy` |
153
+ | Implementing | 6 | `ddd-backend-implementation`, `api-contract-versioning` |
154
+ | Testing and validating | 4 | `writing-robust-tests`, `visual-regression-check` |
155
+ | Fixing a bug | 5 | `bug-triage-structured`, `production-incident-diagnostic` |
156
+ | Reviewing and shipping | 4 | `merge-request-review`, `ci-pipeline-orchestration` |
157
+ | Sweeping and auditing | 12 | `detection-sweep`, and the opt-in `audit-*` family |
131
158
 
132
- Heavyweight and opt-in: reach for it on a periodic review, not day to day.
159
+ What each one is for, in full: [`docs/catalog.md`](docs/catalog.md).
133
160
 
134
- ## Available skills (`skills/`)
135
161
 
136
- 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)).
162
+ ### Hooks: the small automatic behaviors
137
163
 
138
- **Daily drivers**: the discipline skills you reach for during normal development:
164
+ | Hook | Event | Why it is there |
165
+ |---|---|---|
166
+ | `skill-reminder.ts` | `UserPromptSubmit` | surfaces the skills matching your prompt, so a relevant one is not missed. Self-maintained, silent when nothing matches |
167
+ | `bash-npm-silent.ts` | `PreToolUse` / `Bash` | appends `--silent` to setup `npm install` / `npm ci`, which otherwise burn context on noise |
168
+ | `truncate-output.ts` (+ `truncate-bash-output.ts`) | `PreToolUse` / `Bash` | caps verbose command output past a threshold, always preserving it on error |
169
+ | `session-writer` + `session-inject` + `session-precompact` | `Stop` / `SessionStart(compact)` / `PreCompact` | a per-branch session memo: persists the context at session end and re-injects it after a compaction |
170
+ | `worktree-env-setup.ts` | `SessionStart` | symlinks the main repo's `.env` into the current worktree, so a worktree session is not born broken |
171
+ | `readme-freshness.ts` | `PreToolUse` / `Bash` | before a `git push`, has Claude re-read the README against the diff and report the claims it contradicts. Opt-in, warns without blocking |
139
172
 
140
- | Family | Skills |
141
- |---------|--------|
142
- | Tests & quality | `writing-robust-tests` · `comprehensive-test-strategy` · `adversarial-feature-challenge` · `validating-features-end-to-end` · `commit-readiness-review` · `detection-sweep` |
143
- | Design & implementation | `domain-modeling-design` · `ddd-backend-implementation` · `api-contract-versioning` · `database-schema-evolution` |
144
- | Frontend | `frontend-spec-call-site-audit` · `frontend-fullstack-implementation` · `refactoring-shared-component-api` · `design-system-component-lifecycle` · `visual-regression-check` |
145
- | Bugs / recurrence | `bug-triage-structured` · `bug-ticket-root-cause` · `recurring-bug-root-cause` |
146
- | Ops & review | `merge-request-review` · `ci-pipeline-orchestration` · `production-incident-diagnostic` |
147
- | Process | `recording-decisions` · `qa-session-intake` · `daily-workflow-optimization` |
173
+ Every hook fails open: it runs on every session of every repository that
174
+ installed it, so an error ends in a silent `exit 0` rather than blocking you.
175
+ The two to scrutinize before installing (`worktree-env-setup` symlinks your
176
+ `.env`, the session-memo trio writes to disk) are documented in
177
+ [`SECURITY.md`](SECURITY.md).
148
178
 
149
- **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:
179
+ ### Agents and scripts
150
180
 
151
- | Orchestrator | Domain audits |
152
- |---------|--------|
153
- | `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` |
181
+ - `code-reviewer`: architecture, reliability and correctness review of a diff.
182
+ Read-only, and it ends on an actionable verdict.
183
+ - `qa-tester`: runs and writes E2E tests, favoring stable locators over timing
184
+ hacks.
185
+ - `subscription-leak-scan.ts`: scans a staged frontend diff for subscriptions,
186
+ listeners and timers with no teardown.
154
187
 
155
- > Deliberately excluded: `git-workflow`, `jira-bug` (coupled to a specific project: dedicated branch hierarchy and Jira tracker).
188
+ A project-specific agent or skill, coupled to your stack and your tracker, takes
189
+ precedence over its generic version here. Every generic skill says so up front.
156
190
 
157
- 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).
191
+ ## Why you should not trust the tables above
158
192
 
159
- 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`.
193
+ A skill nobody can trigger does not exist, and prose cannot be unit-tested. So
194
+ two things are mechanical here rather than hoped for.
160
195
 
161
- ## Available scripts (`scripts/`)
196
+ **Routing is linted.** Ten realistic sentences must reach the right skill ahead
197
+ of the ones it is confusable with. When that lint was introduced, five of the
198
+ ten failed, which is what a catalog looks like before anyone checks it.
162
199
 
163
- Executable detection scripts (TypeScript, `tsx`, read-only). Referenceable from a skill via `scripts/<file>`.
200
+ **Every skill is evaluated against a real agent run.** Each carries an
201
+ `eval.yaml`: a fixture, a realistic prompt, gates derived from its own exit
202
+ conditions, and a judge for what stays subjective. It regularly says no.
164
203
 
165
- | File | Scope | Purpose |
166
- |---------|--------|-------|
167
- | `subscription-leak-scan.ts` | frontend (staged git diff) | subscription/listener/timer leaks |
204
+ What that costs and what else it caught:
205
+ [`docs/quality-bar.md`](docs/quality-bar.md).
168
206
 
169
- ## Quickstart
207
+ ## Staying in sync
170
208
 
171
209
  ```bash
172
- # 1. Propose an adapted install for your project (read-only)
173
- npx ronce-racine plan .
174
-
175
- # 2. Apply it, then review the diff before committing
176
- npx ronce-racine install .
177
- ```
178
-
179
- ![Propose, install, then catch a local edit with the drift gate](assets/demo.gif)
180
-
181
- The same run as text, on a full-stack repo (`plan` is read-only, nothing is written):
182
-
183
- ```console
184
- $ npx ronce-racine plan ./my-app
185
- Analysis of ./my-app
186
- Signals: git (.git/), ci (CI config), infra (Docker/infra), frontend (frontend
187
- dependencies), backend (Node backend dependencies), tests (E2E deps), code (sources detected)
188
-
189
- ✓ Recommended (installed by default):
190
- Rules (9) :
191
- • minimal-code - YAGNI + readability, any code project
192
- • commits - commit message format
193
- • secure-logging - GDPR: never log sensitive data
194
- • pre-commit-secret-detection - no committed secrets
195
- • test-discipline - tests detected
196
- • subscription-cleanup - frontend: subscription teardown
197
- • clean-architecture-deps - backend: dependency direction
198
- … 2 more
199
- Skills (21) :
200
- • commit-readiness-review - self-review before commit
201
- • detection-sweep - project detection sweep
202
- • recurring-bug-root-cause - recurring bug → root cause
203
- • ci-pipeline-orchestration - CI detected: check/diagnose/retry
204
- … 17 more
205
- Scripts (1) :
206
- • subscription-leak-scan.ts - detects subscriptions/listeners/timers without teardown
207
- Hooks (3) :
208
- • skill-reminder.ts - suggests the relevant skills for the prompt
209
- • bash-npm-silent.ts - silences npm install/ci (less noise)
210
- • truncate-output.ts - caps verbose output (cargo/git/docker…)
211
- Agents (2) :
212
- • code-reviewer - diff review agent
213
- • qa-tester - E2E testing agent
210
+ npx ronce-racine check <repo> # drift vs the canonical source
211
+ npx ronce-racine check <repo> --strict # same, but fails CI
212
+ npx ronce-racine detach <repo> <token> # exempt an artifact you customized on purpose
214
213
  ```
215
214
 
216
- Each artifact is proposed because a signal justified it: a Go repo with no frontend gets
217
- neither `subscription-cleanup` nor the frontend skills. Try it on throwaway repos with
218
- [`playground/setup.ts`](playground/README.md).
219
-
220
- 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.
215
+ The lockfile records what was installed, `check --strict` turns drift into a
216
+ failing job, and `detach` keeps a deliberate local customization from having to
217
+ lie to the gate. Drop in the
218
+ [anti-drift CI job](templates/anti-drift.gitlab-ci.yml) and the config can no
219
+ longer rot silently.
221
220
 
222
- ## Adopting in a repo
221
+ Mechanics (the `settings.json` merge, the two distribution layers, the lockfile
222
+ states): [`docs/distribution-model.md`](docs/distribution-model.md) ·
223
+ [`docs/architecture.md`](docs/architecture.md).
223
224
 
224
- ### Smart installer (recommended)
225
+ ## Install options
225
226
 
226
- `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).
227
+ ### The CLI (recommended)
227
228
 
228
229
  ```bash
229
- npx ronce-racine plan <repo> # proposes (read-only)
230
- npx ronce-racine install <repo> [--all] # applies (--all = + optionals)
230
+ npx ronce-racine plan <repo> # proposes, read-only
231
+ npx ronce-racine install <repo> [--all] # applies (--all = + optionals)
232
+ npx ronce-racine install <repo> --rules-only # rules + lockfile only
233
+ npx ronce-racine check <repo> [--strict] # drift vs canonical (warns, or fails CI)
234
+ npx ronce-racine detach <repo> <token> # exempt a customized artifact from control
235
+ npx ronce-racine uninstall <repo> [--dry-run] # remove what it installed, nothing else
231
236
  ```
232
237
 
233
- 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.
238
+ It copies into `<repo>/.claude/` and merges the hook wirings into
239
+ `settings.json` without disturbing what is already there. Full procedure:
240
+ [`docs/adopting-a-repo.md`](docs/adopting-a-repo.md).
234
241
 
235
- ### Rules only
242
+ Changed your mind? `uninstall` reverses it, driven by the lockfile so it removes
243
+ what it installed and nothing else:
236
244
 
237
245
  ```bash
238
- npx ronce-racine install <repo> --rules-only # rules + lockfile only
246
+ npx ronce-racine uninstall <repo> --dry-run # what would go
247
+ npx ronce-racine uninstall <repo> # remove it
239
248
  ```
240
249
 
241
- Then wire the anti-drift CI gate → [`templates/anti-drift.gitlab-ci.yml`](templates/anti-drift.gitlab-ci.yml).
250
+ It unwires its own hooks from `settings.json` and leaves the rest of that file
251
+ alone, keeps anything you `detach`ed, and gives you back any file it overwrote
252
+ on the way in.
242
253
 
243
- ## Global setup (once per machine)
244
-
245
- ```bash
246
- # Symlink the canonical rules folder as your global shared layer.
247
- # Remove any individual rule file previously copied to ~/.claude/rules/ that
248
- # would otherwise duplicate the symlinked set (e.g. an old minimal-code.md).
249
- ln -s /path/to/ronce-racine/rules ~/.claude/rules/shared
250
- ```
254
+ Try it against throwaway repositories first with
255
+ [`playground/setup.ts`](playground/README.md).
251
256
 
252
- ## CLI
257
+ ### Or as a Claude Code plugin
253
258
 
254
259
  ```bash
255
- npx ronce-racine plan <repo> # proposes an install adapted to the repo's stack
256
- npx ronce-racine install <repo> [--all] # installs rules+skills+hooks+agents (--all = + optionals)
257
- npx ronce-racine install <repo> --rules-only# installs only the rules
258
- npx ronce-racine check <repo> [--strict] # drift vs canonical (soft, or blocking)
259
- npx ronce-racine detach <repo> <token> # excludes a customized artifact from control
260
- npm test # validates artifacts (structure + routing + versioning) AND runs behavioral tests
261
- npm run skills:list # lists the version + category of each skill
262
- npm run rules:validate # validates the versioning of the rules
260
+ /plugin marketplace add ChariereFiedler/ronce-racine
261
+ /plugin install ronce-racine@ronce-racine
263
262
  ```
264
263
 
265
- ## Hooks (`hooks/`)
264
+ The skills and the agents, subscribed rather than copied: they update when you
265
+ update the plugin, and nothing lands in your repository. The rules, the hooks
266
+ and the drift control are deliberately not in it, because always-on context and
267
+ code that runs on your machine belong in a reviewed diff. Reasoning:
268
+ [`docs/distribution-model.md`](docs/distribution-model.md).
266
269
 
267
- 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).
270
+ ## Contributing
268
271
 
269
- | Hook | Event | Role |
270
- |------|-----------|------|
271
- | `skill-reminder.ts` | `UserPromptSubmit` | Suggests the relevant skills based on the prompt (self-maintained, silent when there is no match) |
272
- | `bash-npm-silent.ts` | `PreToolUse / Bash` | Appends `--silent` to setup `npm install` / `npm ci` to reduce context noise |
273
- | `truncate-output.ts` (+ helper `truncate-bash-output.ts`) | `PreToolUse / Bash` | Truncates verbose output beyond a threshold; always preserves the output on error |
274
- | `session-writer` + `session-inject` + `session-precompact` | `Stop` / `SessionStart(compact)` / `PreCompact` | Session-memo trio: persists the context at session end, re-injects it after compaction |
275
- | `worktree-env-setup.ts` | `SessionStart` | Symlinks the main repo's `.env` into the current worktree (idempotent, fail-open) |
272
+ An artifact lives here only if it is truly generic: no crate, script, path or
273
+ identifier tied to a project, no imposed tracker, no imposed stack. If a
274
+ workflow is useful but coupled, split it: the generic protocol here, the tooled
275
+ specifics in your own repository.
276
276
 
277
- 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).
277
+ [`CONTRIBUTING.md`](CONTRIBUTING.md) for the bar and the workflow ·
278
+ [`docs/writing-a-rule.md`](docs/writing-a-rule.md) ·
279
+ [`docs/writing-a-skill.md`](docs/writing-a-skill.md) ·
280
+ [`docs/evaluating-skills.md`](docs/evaluating-skills.md) ·
281
+ [`docs/developing.md`](docs/developing.md) for working on the toolkit itself ·
282
+ [`docs/decisions.md`](docs/decisions.md) for why things are the way they are ·
283
+ [`AGENTS.md`](AGENTS.md) if you *are* the agent reading this.
278
284
 
279
- ## Agents (`agents/`)
280
-
281
- Generic subagent definitions (project-agnostic), to copy into `<repo>/.claude/agents/`:
285
+ ## The name
282
286
 
283
- - `code-reviewer`: architecture/reliability/correctness review of a diff, read-only, actionable verdict.
284
- - `qa-tester`: running/writing E2E tests (stable locators, zero hard waits).
287
+ *Ronce Racine* is French for "bramble root", a plant that roots deep, spreads
288
+ everywhere and refuses to die. A fitting name for a layer of engineering
289
+ discipline meant to take hold in every repository, with just enough thorns to
290
+ remind you it says "discipline".
285
291
 
286
- A project agent (coupled to the stack, the credentials, the tracker) takes precedence over its generic version.
292
+ MIT licensed. Built by [Cedric Chariere Fiedler](https://github.com/ChariereFiedler).
@@ -1,6 +1,6 @@
1
1
  ---
2
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.
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
4
  tools: Read, Grep, Glob, Bash
5
5
  ---
6
6
 
@@ -173,6 +173,46 @@ If the session starts in a linked git worktree (not the main worktree) and the m
173
173
 
174
174
  ---
175
175
 
176
+ ## `readme-freshness.ts` - re-reads the README before a push (PreToolUse/Bash)
177
+
178
+ **Event**: `PreToolUse` · **Matcher**: `Bash` · **Opt-in** (spends one API call per push)
179
+
180
+ Before a `git push` that carries structural changes (`install.ts`, `package.json`,
181
+ `skills/`, `rules/`, `hooks/`, `agents/`, `scripts/`, `templates/`), asks Claude to
182
+ read `README.md` against the diff being pushed and report the claims it
183
+ contradicts: a wrong count, a renamed command, a mechanism that changed, a
184
+ documented file that moved.
185
+
186
+ An LLM rather than a grep, because the drift that matters is semantic - "34
187
+ skills" or "validated by npm test" stays true-looking to any pattern you can
188
+ write, and stops being true the moment the number or the command changes.
189
+
190
+ **Warns, never blocks, by default.** It fails open on every failure mode: no
191
+ `claude` on PATH, not authenticated, timed out, rate-limited, no upstream to
192
+ diff against. A push is never held hostage by this check.
193
+
194
+ | Variable | Effect |
195
+ |---|---|
196
+ | `RONCE_README_CHECK=block` | a contradiction denies the push instead of warning |
197
+ | `RONCE_README_CHECK=off` | skips the check entirely |
198
+ | `RONCE_CLAUDE_BIN` | path to the `claude` binary (default: `claude` on PATH) |
199
+
200
+ Scope: this sees pushes made by Claude. A human typing `git push` in their own
201
+ terminal does not go through it - keep a CI job for that guarantee.
202
+
203
+ ```json
204
+ {
205
+ "hooks": {
206
+ "PreToolUse": [
207
+ { "matcher": "Bash", "hooks": [{ "type": "command",
208
+ "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/readme-freshness.mjs" }] }
209
+ ]
210
+ }
211
+ }
212
+ ```
213
+
214
+ ---
215
+
176
216
  ## `precommit-scan.ts` - secret/debug scan before commit
177
217
 
178
218
  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: