ronce-racine 0.5.3 → 0.8.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.
- package/AGENTS.md +4 -2
- package/README.md +213 -207
- package/agents/code-reviewer.md +1 -1
- package/dist/hooks/README.md +99 -9
- package/dist/hooks/readme-freshness.mjs +161 -0
- package/dist/hooks/skill-reminder.mjs +12 -7
- package/dist/hooks/truncate-bash-output.mjs +17 -7
- package/dist/hooks/truncate-output.mjs +25 -11
- package/dist/install.js +129 -714
- package/dist/src/catalog.js +80 -0
- package/dist/src/detect.js +140 -0
- package/dist/src/lock.js +200 -0
- package/dist/src/paths.js +25 -0
- package/dist/src/selector.js +324 -0
- package/dist/src/settings.js +182 -0
- package/dist/src/uninstall.js +175 -0
- package/docs/adopting-a-repo.md +29 -22
- package/docs/architecture.md +9 -10
- package/docs/catalog.md +86 -0
- package/docs/decisions.md +71 -13
- package/docs/developing.md +69 -29
- package/docs/distribution-model.md +130 -0
- package/docs/evaluating-skills.md +42 -2
- package/docs/git-worktrees.md +2 -2
- package/docs/postmortems/2026-08-24-hook-portability.md +216 -0
- package/docs/quality-bar.md +55 -0
- package/docs/templates/rule.template.md +2 -1
- package/docs/writing-a-rule.md +13 -3
- package/docs/writing-a-skill.md +16 -7
- package/package.json +18 -4
- package/skills/adversarial-feature-challenge/SKILL.md +5 -3
- package/skills/api-contract-versioning/SKILL.md +6 -4
- package/skills/bug-ticket-root-cause/SKILL.md +5 -3
- package/skills/bug-triage-structured/SKILL.md +5 -3
- package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
- package/skills/commit-readiness-review/SKILL.md +7 -3
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
- package/skills/comprehensive-test-strategy/SKILL.md +5 -3
- package/skills/daily-workflow-optimization/SKILL.md +6 -4
- package/skills/database-schema-evolution/SKILL.md +6 -4
- package/skills/ddd-backend-implementation/SKILL.md +5 -3
- package/skills/design-system-component-lifecycle/SKILL.md +6 -4
- package/skills/detection-sweep/SKILL.md +7 -3
- package/skills/detection-sweep/scripts/sweep.ts +3 -3
- package/skills/domain-glossary/README.md +44 -0
- package/skills/domain-glossary/SKILL.md +166 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
- package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
- package/skills/merge-request-review/SKILL.md +5 -3
- package/skills/performance-profiling/README.md +69 -0
- package/skills/performance-profiling/SKILL.md +223 -0
- package/skills/performance-profiling/reference/go.md +235 -0
- package/skills/performance-profiling/reference/native.md +148 -0
- package/skills/performance-profiling/reference/node-web.md +157 -0
- package/skills/performance-profiling/reference/statistics.md +181 -0
- package/skills/performance-profiling/reference/tracy.md +137 -0
- package/skills/production-incident-diagnostic/SKILL.md +5 -3
- package/skills/qa-session-intake/SKILL.md +5 -3
- package/skills/recording-decisions/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
- package/skills/refactoring-shared-component-api/SKILL.md +7 -3
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
- package/skills/validating-features-end-to-end/SKILL.md +5 -3
- package/skills/visual-regression-check/SKILL.md +6 -4
- 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
|
|
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
|
[](https://www.npmjs.com/package/ronce-racine)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
|
-
|
|
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
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
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
|
-
|
|
15
|
+
It is a set of habits I use every day, written down once and shipped by a CLI:
|
|
17
16
|
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
## Two distribution layers
|
|
47
|
+
## Quickstart
|
|
42
48
|
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
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
|
+

|
|
59
55
|
|
|
60
|
-
|
|
56
|
+
Nothing is written by `plan`. Here is a real run on a full-stack repository,
|
|
57
|
+
abridged:
|
|
61
58
|
|
|
62
|
-
|
|
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
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
85
|
-
|
|
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
|
-
|
|
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
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
112
|
+
### Rules: the constraints that are always on
|
|
103
113
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
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:
|
|
118
|
-
| *
|
|
119
|
-
| *"
|
|
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
|
|
122
|
-
memory, because evaluation runs showed agents skipping the recurrence check.
|
|
148
|
+
The full set, grouped by intention:
|
|
123
149
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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
|
-
|
|
159
|
+
What each one is for, in full: [`docs/catalog.md`](docs/catalog.md).
|
|
133
160
|
|
|
134
|
-
## Available skills (`skills/`)
|
|
135
161
|
|
|
136
|
-
|
|
162
|
+
### Hooks: the small automatic behaviors
|
|
137
163
|
|
|
138
|
-
|
|
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
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
179
|
+
### Agents and scripts
|
|
150
180
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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
|
-
|
|
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
|
-
|
|
191
|
+
## Why you should not trust the tables above
|
|
158
192
|
|
|
159
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
207
|
+
## Staying in sync
|
|
170
208
|
|
|
171
209
|
```bash
|
|
172
|
-
|
|
173
|
-
npx ronce-racine
|
|
174
|
-
|
|
175
|
-
# 2. Apply it, then review the diff before committing
|
|
176
|
-
npx ronce-racine install .
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-

|
|
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
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
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
|
-
|
|
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
|
-
|
|
225
|
+
## Install options
|
|
225
226
|
|
|
226
|
-
|
|
227
|
+
### The CLI (recommended)
|
|
227
228
|
|
|
228
229
|
```bash
|
|
229
|
-
npx ronce-racine plan <repo>
|
|
230
|
-
npx ronce-racine install <repo> [--all]
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
246
|
+
npx ronce-racine uninstall <repo> --dry-run # what would go
|
|
247
|
+
npx ronce-racine uninstall <repo> # remove it
|
|
239
248
|
```
|
|
240
249
|
|
|
241
|
-
|
|
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
|
-
|
|
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
|
-
|
|
257
|
+
### Or as a Claude Code plugin
|
|
253
258
|
|
|
254
259
|
```bash
|
|
255
|
-
|
|
256
|
-
|
|
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
|
-
|
|
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
|
-
|
|
270
|
+
## Contributing
|
|
268
271
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
280
|
-
|
|
281
|
-
Generic subagent definitions (project-agnostic), to copy into `<repo>/.claude/agents/`:
|
|
285
|
+
## The name
|
|
282
286
|
|
|
283
|
-
|
|
284
|
-
|
|
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
|
-
|
|
292
|
+
MIT licensed. Built by [Cedric Chariere Fiedler](https://github.com/ChariereFiedler).
|
package/agents/code-reviewer.md
CHANGED
|
@@ -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
|
|