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.
- package/AGENTS.md +90 -0
- package/LICENSE +21 -0
- package/README.md +281 -0
- package/agents/code-reviewer.md +33 -0
- package/agents/qa-tester.md +28 -0
- package/dist/hooks/README.md +182 -0
- package/dist/hooks/bash-npm-silent.mjs +81 -0
- package/dist/hooks/session-inject.mjs +53 -0
- package/dist/hooks/session-precompact.mjs +36 -0
- package/dist/hooks/session-writer.mjs +142 -0
- package/dist/hooks/skill-reminder.mjs +89 -0
- package/dist/hooks/truncate-bash-output.mjs +46 -0
- package/dist/hooks/truncate-output.mjs +88 -0
- package/dist/hooks/worktree-env-setup.mjs +123 -0
- package/dist/install.js +962 -0
- package/docs/adopting-a-repo.md +80 -0
- package/docs/architecture.md +76 -0
- package/docs/decisions.md +72 -0
- package/docs/developing.md +143 -0
- package/docs/evaluating-skills.md +41 -0
- package/docs/git-worktrees.md +62 -0
- package/docs/rules/clean-architecture-deps.md +66 -0
- package/docs/rules/commits.md +59 -0
- package/docs/rules/detection-gap-protocol.md +55 -0
- package/docs/rules/error-handling-discipline.md +62 -0
- package/docs/rules/minimal-code.md +58 -0
- package/docs/rules/no-raw-sql-interpolation.md +57 -0
- package/docs/rules/pre-commit-secret-detection.md +54 -0
- package/docs/rules/secure-logging.md +53 -0
- package/docs/rules/sql-migrations-discipline.md +58 -0
- package/docs/rules/subscription-cleanup.md +63 -0
- package/docs/rules/test-discipline.md +66 -0
- package/docs/rules/ui-states-complete.md +52 -0
- package/docs/templates/SKILL.template.md +66 -0
- package/docs/templates/rule.template.md +16 -0
- package/docs/writing-a-rule.md +43 -0
- package/docs/writing-a-skill.md +118 -0
- package/package.json +45 -0
- package/rules/clean-architecture-deps.md +20 -0
- package/rules/commits.md +16 -0
- package/rules/detection-gap-protocol.md +35 -0
- package/rules/error-handling-discipline.md +23 -0
- package/rules/minimal-code.md +32 -0
- package/rules/no-raw-sql-interpolation.md +20 -0
- package/rules/pre-commit-secret-detection.md +14 -0
- package/rules/secure-logging.md +16 -0
- package/rules/sql-migrations-discipline.md +18 -0
- package/rules/subscription-cleanup.md +22 -0
- package/rules/test-discipline.md +20 -0
- package/rules/ui-states-complete.md +23 -0
- package/scripts/subscription-leak-scan.ts +53 -0
- package/skills/adversarial-feature-challenge/README.md +65 -0
- package/skills/adversarial-feature-challenge/SKILL.md +96 -0
- package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
- package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
- package/skills/api-contract-versioning/README.md +62 -0
- package/skills/api-contract-versioning/SKILL.md +76 -0
- package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
- package/skills/audit-architecture/README.md +56 -0
- package/skills/audit-architecture/SKILL.md +97 -0
- package/skills/audit-architecture/reference/ar-architecture.md +275 -0
- package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
- package/skills/audit-architecture/reference/im-incidents.md +217 -0
- package/skills/audit-architecture/reference/pa-pannes.md +362 -0
- package/skills/audit-architecture/reference/re-recuperation.md +300 -0
- package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
- package/skills/audit-architecture/reference/su-support.md +180 -0
- package/skills/audit-ci-cd/README.md +54 -0
- package/skills/audit-ci-cd/SKILL.md +124 -0
- package/skills/audit-ci-cd/reference/artefacts.md +39 -0
- package/skills/audit-ci-cd/reference/deploiement.md +100 -0
- package/skills/audit-ci-cd/reference/dora.md +94 -0
- package/skills/audit-ci-cd/reference/iac.md +40 -0
- package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
- package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
- package/skills/audit-compliance/README.md +69 -0
- package/skills/audit-compliance/SKILL.md +176 -0
- package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
- package/skills/audit-compliance/reference/finops.md +318 -0
- package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
- package/skills/audit-industrialisation/README.md +53 -0
- package/skills/audit-industrialisation/SKILL.md +251 -0
- package/skills/audit-observability/README.md +64 -0
- package/skills/audit-observability/SKILL.md +134 -0
- package/skills/audit-observability/reference/alerting.md +214 -0
- package/skills/audit-observability/reference/logging.md +114 -0
- package/skills/audit-observability/reference/metriques.md +166 -0
- package/skills/audit-observability/reference/traces-dashboards.md +90 -0
- package/skills/audit-performance-frontend/README.md +91 -0
- package/skills/audit-performance-frontend/SKILL.md +194 -0
- package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
- package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
- package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
- package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
- package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
- package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
- package/skills/audit-quality/README.md +85 -0
- package/skills/audit-quality/SKILL.md +126 -0
- package/skills/audit-quality/reference/qa-devops.md +539 -0
- package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
- package/skills/audit-report/README.md +72 -0
- package/skills/audit-report/SKILL.md +241 -0
- package/skills/audit-report/reference/scoring-model.md +45 -0
- package/skills/audit-security/README.md +72 -0
- package/skills/audit-security/SKILL.md +140 -0
- package/skills/audit-security/reference/auth-identite.md +98 -0
- package/skills/audit-security/reference/autorisation.md +66 -0
- package/skills/audit-security/reference/chiffrement-tls.md +97 -0
- package/skills/audit-security/reference/detection-patching.md +67 -0
- package/skills/audit-security/reference/incident-response.md +98 -0
- package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
- package/skills/audit-security/reference/secrets.md +36 -0
- package/skills/audit-testing/README.md +82 -0
- package/skills/audit-testing/SKILL.md +131 -0
- package/skills/audit-testing/reference/golden-dataset.md +65 -0
- package/skills/audit-testing/reference/resilience-chaos.md +93 -0
- package/skills/audit-testing/reference/tests-contractuels.md +65 -0
- package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
- package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
- package/skills/bug-ticket-root-cause/README.md +67 -0
- package/skills/bug-ticket-root-cause/SKILL.md +86 -0
- package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
- package/skills/bug-triage-structured/README.md +63 -0
- package/skills/bug-triage-structured/SKILL.md +104 -0
- package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
- package/skills/ci-pipeline-orchestration/README.md +55 -0
- package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
- package/skills/commit-readiness-review/README.md +66 -0
- package/skills/commit-readiness-review/SKILL.md +82 -0
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
- package/skills/comprehensive-test-strategy/README.md +64 -0
- package/skills/comprehensive-test-strategy/SKILL.md +108 -0
- package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
- package/skills/daily-workflow-optimization/README.md +56 -0
- package/skills/daily-workflow-optimization/SKILL.md +80 -0
- package/skills/database-schema-evolution/README.md +54 -0
- package/skills/database-schema-evolution/SKILL.md +107 -0
- package/skills/ddd-backend-implementation/README.md +63 -0
- package/skills/ddd-backend-implementation/SKILL.md +95 -0
- package/skills/design-system-component-lifecycle/README.md +56 -0
- package/skills/design-system-component-lifecycle/SKILL.md +97 -0
- package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
- package/skills/detection-sweep/README.md +58 -0
- package/skills/detection-sweep/SKILL.md +93 -0
- package/skills/detection-sweep/scripts/sweep.ts +80 -0
- package/skills/domain-modeling-design/README.md +57 -0
- package/skills/domain-modeling-design/SKILL.md +83 -0
- package/skills/frontend-fullstack-implementation/README.md +60 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
- package/skills/frontend-spec-call-site-audit/README.md +66 -0
- package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
- package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
- package/skills/merge-request-review/README.md +60 -0
- package/skills/merge-request-review/SKILL.md +77 -0
- package/skills/merge-request-review/templates/mr-review-report.md +29 -0
- package/skills/production-incident-diagnostic/README.md +63 -0
- package/skills/production-incident-diagnostic/SKILL.md +103 -0
- package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
- package/skills/qa-session-intake/README.md +56 -0
- package/skills/qa-session-intake/SKILL.md +78 -0
- package/skills/recording-decisions/README.md +91 -0
- package/skills/recording-decisions/SKILL.md +84 -0
- package/skills/recurring-bug-root-cause/README.md +64 -0
- package/skills/recurring-bug-root-cause/SKILL.md +93 -0
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
- package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
- package/skills/refactoring-shared-component-api/README.md +50 -0
- package/skills/refactoring-shared-component-api/SKILL.md +84 -0
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
- package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
- package/skills/validating-features-end-to-end/README.md +50 -0
- package/skills/validating-features-end-to-end/SKILL.md +90 -0
- package/skills/visual-regression-check/README.md +51 -0
- package/skills/visual-regression-check/SKILL.md +89 -0
- package/skills/writing-robust-tests/README.md +53 -0
- package/skills/writing-robust-tests/SKILL.md +88 -0
- package/templates/.adopted.example +8 -0
- package/templates/anti-drift.gitlab-ci.yml +23 -0
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Adopting Ronce Racine in a repo
|
|
2
|
+
|
|
3
|
+
## Option A - Smart installer (recommended)
|
|
4
|
+
|
|
5
|
+
`ronce-racine` detects the project's stack (frontend/backend/tests/SQL/migrations/CI/infra/git) and proposes the relevant artifacts, with a reason for each.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# 1. Proposal (read-only) - nothing is written
|
|
9
|
+
npx ronce-racine plan .
|
|
10
|
+
|
|
11
|
+
# 2. Install the recommended ones (add --all to include optionals: audits, etc.)
|
|
12
|
+
npx ronce-racine install . --all
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
The installer copies into `.claude/`:
|
|
16
|
+
- `rules/shared/` + the `.adopted` manifest (rules) - drift is watchable via `ronce-racine check .`
|
|
17
|
+
- `skills/<name>/` (relevant skills), `hooks/`, `agents/`
|
|
18
|
+
|
|
19
|
+
It merges the hook wirings into `.claude/settings.json` (writes a `settings.json.bak` backup, deep-merges by event + matcher, idempotent, preserves unrelated settings). Check the diff (`git diff`, `git status`), then commit - `.claude/` travels via git → teammates + CI agents.
|
|
20
|
+
|
|
21
|
+
Update later: rerun `ronce-racine install .` (idempotent). For rules only, use `ronce-racine install . --rules-only` (same lockfile-based drift as everything else).
|
|
22
|
+
|
|
23
|
+
### Anti-drift (lockfile)
|
|
24
|
+
|
|
25
|
+
`ronce-racine` writes `.claude/.ronce-racine.json`: what is managed + the package version and a content hash at install time.
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx ronce-racine check . # soft: warns (drift + staleness)
|
|
29
|
+
npx ronce-racine check . --strict # exit 1 on drift (blocking gate)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
- **Drift**: a managed artifact was modified locally → reported (`~file`, `-missing`, `+added`).
|
|
33
|
+
- **Assumed customization**: `ronce-racine detach . skill:detection-sweep` takes the item out of control (it becomes "yours").
|
|
34
|
+
- **Staleness**: the canonical version has moved on since install → "rerun install" warning.
|
|
35
|
+
|
|
36
|
+
CI gate: the [`templates/anti-drift.gitlab-ci.yml`](../templates/anti-drift.gitlab-ci.yml) snippet (soft via `allow_failure`, blocking by removing that line).
|
|
37
|
+
|
|
38
|
+
> The sections below describe the **rules-only approach** (rules and nothing else), still driven by `ronce-racine`.
|
|
39
|
+
|
|
40
|
+
## 1. Declare the adopted rules
|
|
41
|
+
|
|
42
|
+
Create `<repo>/.claude/rules/shared/.adopted` (template: [`templates/.adopted.example`](../templates/.adopted.example)):
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
# Generic rules managed by the Ronce Racine canonical source.
|
|
46
|
+
minimal-code.md
|
|
47
|
+
commits.md
|
|
48
|
+
test-discipline.md
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Only list the rules for which you want the **generic canonical** version. A rule you want to **enrich locally** (e.g. `secure-logging` with the project's identifiers and lint): do not list it, and keep your version in `.claude/rules/shared/` or `rules/<project>/`.
|
|
52
|
+
|
|
53
|
+
## 2. Synchronize
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npx ronce-racine install . --rules-only
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The adopted files are copied into `.claude/rules/shared/` and tracked in the lockfile (same drift mechanism as everything else). Check the diff (`git diff`), then commit:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git add .claude/rules/shared
|
|
63
|
+
git commit -m "chore(rules): adopt the generic canonical rules (ronce-racine)"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## 3. Anti-drift CI gate (recommended)
|
|
67
|
+
|
|
68
|
+
Add the job from [`templates/anti-drift.gitlab-ci.yml`](../templates/anti-drift.gitlab-ci.yml) to the repo's `.gitlab-ci.yml`. It fails if an adopted rule has diverged from the canonical version.
|
|
69
|
+
|
|
70
|
+
Prerequisite: the runner must be able to reach the npm registry (the job runs `npx ronce-racine@<version> check`). If you prefer no network dependency in CI, the committed files already freeze the content - the gate only adds drift **detection**.
|
|
71
|
+
|
|
72
|
+
## 4. Update later
|
|
73
|
+
|
|
74
|
+
When the canonical version evolves:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
cd <repo>
|
|
78
|
+
npx ronce-racine install . --rules-only
|
|
79
|
+
git add .claude/rules/shared && git commit -m "chore(rules): resync canonical rules"
|
|
80
|
+
```
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
## The problem
|
|
4
|
+
|
|
5
|
+
Claude Code injects rules by file type via `.claude/rules/` (`paths:` frontmatter). For a long time each project kept its own copy of the "generic" rules in `rules/shared/`. Observed result: **the copies drift**. Across two projects, `commits.md` was identical but `secure-logging.md`, `test-discipline.md` and `detection-gap-protocol.md` had diverged (sections added on one side, not the other).
|
|
6
|
+
|
|
7
|
+
A generic rule should have **a single source of truth**.
|
|
8
|
+
|
|
9
|
+
## The solution: two layers
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
flowchart TB
|
|
13
|
+
subgraph canon["ronce-racine (this repo)"]
|
|
14
|
+
R["rules/*.md - single source"]
|
|
15
|
+
end
|
|
16
|
+
subgraph perso["Global layer (personal)"]
|
|
17
|
+
S["~/.claude/rules/shared → symlink"]
|
|
18
|
+
end
|
|
19
|
+
subgraph repos["Per-repo layer (team / CI)"]
|
|
20
|
+
A[".claude/rules/shared/ (real committed files)"]
|
|
21
|
+
end
|
|
22
|
+
R -->|"ln -s"| S
|
|
23
|
+
R -->|"ronce-racine install --rules-only"| A
|
|
24
|
+
A -->|"ronce-racine check (CI gate)"| A
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Global layer (personal) - `~/.claude/rules/`
|
|
28
|
+
|
|
29
|
+
`~/.claude/rules/` is a **user-level** rules directory natively supported by Claude Code: it applies to **all projects** on the machine. In it we place a `shared → ronce-racine/rules` symlink.
|
|
30
|
+
|
|
31
|
+
- Advantage: zero copies, zero drift, written once, valid everywhere (and on all my machines via `git pull`).
|
|
32
|
+
- Limitation: machine-local and **not versioned per project** → invisible to a teammate or a CI runner that just clones the project repo.
|
|
33
|
+
- Priority: user-level rules are loaded **before** project rules, so a project rule with the same name still takes precedence.
|
|
34
|
+
|
|
35
|
+
### Per-repo layer (team / CI) - `.claude/rules/shared/`
|
|
36
|
+
|
|
37
|
+
For teammates and **headless/CI agents** to see the rules, you need **real committed files** in the repo. A symlink pointing outside the repo (`~/lab/...`) does not travel via git: it would point nowhere after a clone.
|
|
38
|
+
|
|
39
|
+
`ronce-racine install --rules-only` copies the **adopted** rules (declared in `.adopted`) from the canonical source into `.claude/rules/shared/`. `ronce-racine check` is the anti-drift gate (exit 1 on `--strict` if an adopted rule has diverged).
|
|
40
|
+
|
|
41
|
+
## The `.adopted` manifest
|
|
42
|
+
|
|
43
|
+
A repo does not necessarily adopt every rule, and may want to **keep an enriched version** of a rule (e.g. `secure-logging` with its project identifiers and its CI lint). The `.claude/rules/shared/.adopted` file (written by `ronce-racine` for rules) explicitly lists the rules managed by the canonical source (one per line). Rules **not listed are left intact** by install/check.
|
|
44
|
+
|
|
45
|
+
Splitting rule: the **generic** part of a rule lives here (the *principle*); the **tooled/named** part (script paths, crate names, ast-grep gates) stays in a project rule `rules/<project>/`.
|
|
46
|
+
|
|
47
|
+
## Coexistence of the two layers
|
|
48
|
+
|
|
49
|
+
In an adopted repo, the rule exists twice in context (global + project), with identical content → the project version wins, no effect. The slight context duplication is accepted: it guarantees that **non-adopted** repos still benefit from the global layer.
|
|
50
|
+
|
|
51
|
+
## Beyond rules: skills, hooks, agents
|
|
52
|
+
|
|
53
|
+
The same drift problem applies to **skills** (on-demand workflows), **hooks** (settings.json scripts) and **agents** (subagents). `ronce-racine` is the single CLI and covers all **4 families** (rules included, via `--rules-only` when you want rules and nothing else).
|
|
54
|
+
|
|
55
|
+
```mermaid
|
|
56
|
+
flowchart TB
|
|
57
|
+
subgraph canon["ronce-racine (this repo)"]
|
|
58
|
+
C["rules/ · skills/ · hooks/ · agents/"]
|
|
59
|
+
end
|
|
60
|
+
subgraph target["target repo (.claude/)"]
|
|
61
|
+
T["rules/shared · skills/<name> · hooks · agents"]
|
|
62
|
+
L[".ronce-racine.json (lockfile)"]
|
|
63
|
+
end
|
|
64
|
+
C -->|"ronce-racine plan (detects the stack → proposes)"| C
|
|
65
|
+
C -->|"ronce-racine install (copies + writes the lockfile)"| T
|
|
66
|
+
T -->|"ronce-racine check (drift + staleness)"| L
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
- **`plan`** scans the target repo (frontend/backend/tests/sql/migrations/ci/infra/git) and only proposes the relevant artifacts - since the metadata of installed skills loads in every session, we don't install everything.
|
|
70
|
+
- **`install`** copies to the right place (`rules/shared/` + `.adopted`, `skills/<name>/`, `hooks/`, `agents/`) and writes the **lockfile** `.claude/.ronce-racine.json`: `{ source: { package, version, contentHash }, installed: [tokens], detached: [] }`.
|
|
71
|
+
- **`check`** compares each managed artifact to the canonical version (byte-for-byte; recursive for skills) → **drift**; and compares the version + content hash → **staleness**. Soft by default (warns), `--strict` to block.
|
|
72
|
+
- **`detach`** takes a deliberately customized artifact out of control (≈ the role of `.adopted` for rules, but per item).
|
|
73
|
+
|
|
74
|
+
### Versioning & validation
|
|
75
|
+
|
|
76
|
+
Skills and rules carry `version` (semver) + `metadata.last-reviewed` in their frontmatter. The `tools/skills.ts` harness (`npm test`) validates three axes: **structure** of the skills (frontmatter, sections, links), **routing discriminability** (each trigger classifies its skill at the top), **versioning of the rules**. Detailed contract: [writing-a-skill.md](writing-a-skill.md) · [writing-a-rule.md](writing-a-rule.md).
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Decision log - Ronce Racine
|
|
2
|
+
|
|
3
|
+
Non-obvious decisions of the project. Never modify an entry: add one that supersedes it.
|
|
4
|
+
|
|
5
|
+
## 2026-07-10 - Product decisions from the outside-in review
|
|
6
|
+
|
|
7
|
+
**Context**: two adversarial "external adopter" review passes surfaced product/adoption objections beyond the bugs (which were fixed and covered by `tests.ts`). These four shape how the repo presents and behaves; decided with the owner.
|
|
8
|
+
|
|
9
|
+
**Decisions**:
|
|
10
|
+
1. **Audit suite stays in this repo** but the README leads with the ~10 daily-driver skills and relegates the 9-skill industrialization-audit suite to an "advanced / opt-in" section. Rationale: splitting into a second repo/plugin is a large chore; de-emphasizing is cheap and fixes the blurred "discipline vs audit product" identity. Reassess a split if the audit suite grows its own release cadence.
|
|
11
|
+
2. **One CLI**: fold rules-only distribution into `install.ts --rules-only`; `rules.ts` becomes a deprecated shim (kept working, prints a notice) then removed later. Rationale: two CLIs + two drift mechanisms + two lockfiles for rules is the #1 day-one confusion. Single lockfile-based drift for everything.
|
|
12
|
+
3. **The installer auto-merges hook wirings into `.claude/settings.json`** (deep-merge by event+matcher, idempotent, writes a `.bak` backup and prints the diff) instead of only printing a snippet for the user to hand-merge. Rationale: the manual `settings.json` surgery was the highest-friction, highest-blast-radius step (clobbers an existing `hooks` block on a naive paste).
|
|
13
|
+
4. **README leads with the "why"**: the differentiator is *one canonical source installed into many repos with drift control*, which copy-paste and native plugins do not provide. Also document the Node ≥ 18 requirement in the target repo (hooks run via `npx tsx`) and keep the audit scoring table in a single shared `reference/` file (was duplicated across audit-report / audit-industrialisation).
|
|
14
|
+
|
|
15
|
+
**Consequences**: changes to `install.ts` (`--rules-only`, settings.json merge) are covered by new deterministic tests in `tests.ts`. `rules.ts` deprecated. Docs (README, adopting-a-repo, architecture, AGENTS) updated to the single-CLI story.
|
|
16
|
+
|
|
17
|
+
**Status**: Accepted · implementation in progress.
|
|
18
|
+
|
|
19
|
+
## 2026-07-10 - OSS strategy: the whole repo, public GitHub, MIT
|
|
20
|
+
|
|
21
|
+
**Context**: the repo (canonical source of generic Claude Code config) has always been designed to be project-agnostic - genericity is a hard admission criterion. The question "do we make it public OSS, and in what form?" had never been settled or recorded. Today it is framed to unblock preparation (license, hosting, cleanup).
|
|
22
|
+
|
|
23
|
+
**Options**: *Scope* - the whole repo vs. just `rules/`+`skills/` vs. a curated subset. *Hosting* - public GitHub vs. public GitLab vs. staying private. *License* - MIT vs. Apache-2.0.
|
|
24
|
+
|
|
25
|
+
**Decision**:
|
|
26
|
+
- **Scope**: **the whole repo** (rules + skills + hooks + agents + scripts + installer) becomes the OSS product.
|
|
27
|
+
- **Hosting**: **public GitHub** (better visibility for the Claude Code / plugins / skills ecosystem). The prior private repository stays or becomes a mirror/private source depending on infra needs.
|
|
28
|
+
- **License**: **MIT** (permissive, de facto standard, maximum adoption).
|
|
29
|
+
|
|
30
|
+
**Consequences** - blockers to lift before public release:
|
|
31
|
+
1. Add an MIT `LICENSE` file.
|
|
32
|
+
2. **Replace the private project names** embedded in the `skills/*/SKILL.md` routing examples and `templates/` with fictional example names (`acme-app`, `beta-app`).
|
|
33
|
+
3. Reframe the README (from an internal-projects framing) into a public positioning.
|
|
34
|
+
4. Couple it to the **Ronce Racine** rename (see the 2026-06-25 decision): name the GitHub repo `ronce-racine` at public creation rather than migrating afterward.
|
|
35
|
+
5. Add CONTRIBUTING / CODE_OF_CONDUCT / public CI (finishing touches).
|
|
36
|
+
6. Translate the whole public repo to English and add a per-artifact documentation layer; make every skill invocable in both English and French.
|
|
37
|
+
To reassess if: the genericity scope changes, or an infra constraint requires keeping the primary source elsewhere.
|
|
38
|
+
|
|
39
|
+
**Status**: Accepted (strategy locked) · preparation in progress.
|
|
40
|
+
|
|
41
|
+
## 2026-06-25 - Repo name: "Ronce Racine"
|
|
42
|
+
|
|
43
|
+
**Context**: the repo (canonical source of the generic Claude config) needs a name in the same evocative vein as the rest of the ecosystem, replacing the working name `claude-rules`.
|
|
44
|
+
|
|
45
|
+
**Options**: explored several registers (garden/plant, forge/workshop, runic). Convergence on the **root** theme (the buried source from which everything else grows), then adjective+noun short-lists. Final proposal chosen, coming from the user.
|
|
46
|
+
|
|
47
|
+
**Decision**: **Ronce Racine** (slug `ronce-racine`).
|
|
48
|
+
Rationale: memorable alliteration; the meaning fits the repo - a bramble (*ronce*) roots (*racine*) and spreads everywhere, unkillable, like a layer of always-on disciplines distributed into every project, with a thorny side that says "discipline". A two-nouns-joined form, both words singular.
|
|
49
|
+
|
|
50
|
+
**Consequences**: the **actual rename** (local folder, git remote, occurrences of `claude-rules` in README/AGENTS/docs/`package.json`) is a separate operation. The internal name `claude-rules` stays valid until the rename is done.
|
|
51
|
+
|
|
52
|
+
**Status**: Accepted (name locked) · rename to implement.
|
|
53
|
+
|
|
54
|
+
## 2026-07-20 - Rename completed; public release via an orphan branch
|
|
55
|
+
|
|
56
|
+
**Context**: supersedes the "rename to implement" status of the 2026-06-25 entry. The rename to **Ronce Racine** is done everywhere (README, AGENTS, docs, `package.json`, lockfile name `.ronce-racine.json`); `claude-rules` only survives in historical entries of this file. Separately, the first public release had to decide what git history to publish: 46 of the 62 work commits contained private project names (the cleanup had only covered the working tree).
|
|
57
|
+
|
|
58
|
+
**Decision**: publish on GitHub (`ChariereFiedler/ronce-racine`, branch `main`, tag `v0.1.0`) from an **orphan branch** carrying a single initial commit of the clean tree. The full work history stays on the private GitLab remote.
|
|
59
|
+
|
|
60
|
+
**Consequences**: any future publication must regenerate the orphan branch from the private work branch - never push the work history to the public remote. The public repo's history starts at v0.1.0 by design.
|
|
61
|
+
|
|
62
|
+
**Status**: Done.
|
|
63
|
+
|
|
64
|
+
## 2026-07-21 - Public releases are linear, not orphan-per-release
|
|
65
|
+
|
|
66
|
+
**Context**: the 2026-07-20 entry established publishing from an orphan branch to keep the private work history out of the public repository. Applying that literally to the second release would have meant a second unrelated-history orphan, forcing a force-push over the published v0.1.0 and breaking every existing clone.
|
|
67
|
+
|
|
68
|
+
**Decision**: keep ONE public history. Each release is a single commit whose TREE is the work branch's tree and whose PARENT is the previous public commit, built with `git commit-tree $(git rev-parse <work-branch>^{tree}) -p github/main`. The private history still never reaches the public remote, and the public repository grows a normal linear history (v0.1.0 -> v0.2.0 -> ...) that pulls cleanly.
|
|
69
|
+
|
|
70
|
+
**Consequences**: no force-push, existing clones pull normally, `git log` on the public repo reads as one commit per release. The squash is deliberate: public history granularity is the release, not the work commit.
|
|
71
|
+
|
|
72
|
+
**Status**: Done (v0.2.0 published this way).
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Developing on Ronce Racine
|
|
2
|
+
|
|
3
|
+
How to work **on the toolkit itself**. To adopt it in a project instead, see
|
|
4
|
+
[adopting-a-repo.md](adopting-a-repo.md); for the distribution model, see
|
|
5
|
+
[architecture.md](architecture.md).
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
This clone is the **contributor** path, for working on the toolkit itself. It
|
|
10
|
+
is no longer the documented way to *adopt* Ronce Racine in a project - that
|
|
11
|
+
path is `npx ronce-racine`, see [adopting-a-repo.md](adopting-a-repo.md).
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
git clone https://github.com/ChariereFiedler/ronce-racine.git
|
|
15
|
+
cd ronce-racine && npm ci
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Node >= 18 and nothing else. The toolkit has **no runtime dependency**: the
|
|
19
|
+
three devDependencies are TypeScript, `tsx` and Node's type definitions.
|
|
20
|
+
Everything else is Node builtins, on purpose - a config toolkit that drags a
|
|
21
|
+
dependency tree into your repo would defeat its own point.
|
|
22
|
+
|
|
23
|
+
If you `npm link` this clone into a test repo, that repo's `ronce-racine`
|
|
24
|
+
resolves to your local build instead of the published package, so `check`
|
|
25
|
+
will report staleness against your (uncommitted, unpublished) local changes -
|
|
26
|
+
that is expected, not a bug. Run `npm unlink ronce-racine` in the test repo to
|
|
27
|
+
restore the published resolution.
|
|
28
|
+
|
|
29
|
+
## Repository map
|
|
30
|
+
|
|
31
|
+
| Path | What it is |
|
|
32
|
+
|---|---|
|
|
33
|
+
| `install.ts` | the only user-facing CLI (`plan`/`install`/`check`/`detach`), and the `bin` target |
|
|
34
|
+
| `tools/` | internal harnesses, never distributed |
|
|
35
|
+
| `skills/` `rules/` `hooks/` `agents/` `scripts/` | the artifacts themselves, the actual product |
|
|
36
|
+
| `tests/` | behavioral tests by domain (installer, hooks, selector, fixtures, eval) |
|
|
37
|
+
| `playground/` | fixture generator: throwaway repos to run the installer and the evals against |
|
|
38
|
+
| `templates/` | what a CONSUMER copies into their repo (`.adopted.example`, anti-drift CI) |
|
|
39
|
+
| `docs/templates/` | what a CONTRIBUTOR copies to author an artifact |
|
|
40
|
+
|
|
41
|
+
One build step, run automatically by `npm install` (`prepare`):
|
|
42
|
+
`tools/build.ts` compiles `hooks/*.ts` into `dist/hooks/*.mjs` (`.mjs` so a
|
|
43
|
+
target repo without `"type": "module"` in its `package.json` doesn't get a
|
|
44
|
+
Node `MODULE_TYPELESS_PACKAGE_JSON` warning on every hook fire) and
|
|
45
|
+
`install.ts` into `dist/install.js`. Hooks must never be compiled at run time: measured on
|
|
46
|
+
a hook that fires on every prompt, `npx tsx` costs 527 ms, node's own type
|
|
47
|
+
stripping 99 ms, and built JS 34 ms. Building once also means an adopting
|
|
48
|
+
repo needs Node and nothing else.
|
|
49
|
+
|
|
50
|
+
The four harnesses under `tools/`:
|
|
51
|
+
|
|
52
|
+
- `skills.ts` - static contract: frontmatter, semver, sections, links, trigger routing
|
|
53
|
+
- `tests.ts` - discovers and runs every `*.test.ts`
|
|
54
|
+
- `mutations.ts` - breaks the code on purpose and requires the tests to notice
|
|
55
|
+
- `eval.ts` - plays a skill through a real agent and verdicts the result
|
|
56
|
+
|
|
57
|
+
## The four commands
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm test # contract + behavioral tests
|
|
61
|
+
npm run typecheck
|
|
62
|
+
npm run test:mutation # every declared mutation must turn its tests red
|
|
63
|
+
npm run eval:dry # every eval.yaml parses and names an existing fixture
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
All four run in CI, on Node 18 and 22. What each one actually protects:
|
|
67
|
+
|
|
68
|
+
- **`npm test`** proves the artifacts respect their contract and the tooling
|
|
69
|
+
behaves. It does NOT prove a skill still works: prose is not lintable.
|
|
70
|
+
- **`npm run test:mutation`** protects the tests themselves. A test that stays
|
|
71
|
+
green on deliberately broken code is worse than no test, because it grants
|
|
72
|
+
confidence it has not earned.
|
|
73
|
+
- **`npm run eval:dry`** protects the eval manifests without spending a token.
|
|
74
|
+
- Real agent evals cost API tokens and are never in CI - see below.
|
|
75
|
+
|
|
76
|
+
## The playground
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npx tsx playground/setup.ts # (re)create playground/fixtures/
|
|
80
|
+
npx tsx install.ts plan playground/fixtures/fullstack-ci
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Nine throwaway git repos with distinct stacks. Five carry **planted defects and
|
|
84
|
+
an `EXPECTED.md` ground truth** (`flawed-app`, `buggy-app`, `shipped-feature`,
|
|
85
|
+
`design-system`, `audit-target`), so a detector that stops detecting gets
|
|
86
|
+
caught by a test rather than by a user. `playground/fixtures/` is gitignored
|
|
87
|
+
and rebuilt from scratch on every run.
|
|
88
|
+
|
|
89
|
+
## Running a real evaluation
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npx tsx tools/eval.ts run --only detection-sweep # one skill, real agent, real cost
|
|
93
|
+
npx tsx tools/eval.ts run # all 34, before a release
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Needs the `claude` CLI on PATH (or `EVAL_CLAUDE_BIN`). Full guide:
|
|
97
|
+
[evaluating-skills.md](evaluating-skills.md).
|
|
98
|
+
|
|
99
|
+
## Adding an artifact
|
|
100
|
+
|
|
101
|
+
| Type | Guide | Also required |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| Rule | [writing-a-rule.md](writing-a-rule.md) | `docs/rules/<name>.md`, entry in the README table |
|
|
104
|
+
| Skill | [writing-a-skill.md](writing-a-skill.md) | `README.md` + `eval.yaml` in the skill folder (neither is distributed) |
|
|
105
|
+
| Hook | see below | `@version` and `@last-reviewed` in the file header |
|
|
106
|
+
| Agent | copy an existing `agents/*.md` | entry in the README table |
|
|
107
|
+
| Script | belongs to a skill (`skills/<name>/scripts/`) | a co-located `*.test.ts` and a mutation entry |
|
|
108
|
+
|
|
109
|
+
**Hooks** live in `hooks/`, one file per hook, TypeScript only (never `.sh`).
|
|
110
|
+
Each carries `@version` (semver) and `@last-reviewed` (ISO date) in its header
|
|
111
|
+
comment, validated by `tools/skills.ts hooks`. A hook must **fail open**: it
|
|
112
|
+
runs on every session of every repo that installed it, so any error has to end
|
|
113
|
+
in a silent `exit 0` rather than blocking the user. Hooks that touch the
|
|
114
|
+
filesystem or persist anything are documented in [`SECURITY.md`](../SECURITY.md).
|
|
115
|
+
|
|
116
|
+
## What travels and what does not
|
|
117
|
+
|
|
118
|
+
The installer copies artifacts into a target repo's `.claude/`. A target repo
|
|
119
|
+
gets what its agent reads, and nothing that merely explains or verifies the
|
|
120
|
+
toolkit. Excluded from both the copy and the drift comparison in `install.ts`
|
|
121
|
+
(`copyToken` **and** `compareToken`):
|
|
122
|
+
|
|
123
|
+
- `*.test.ts` - test procedures
|
|
124
|
+
- `eval.yaml` - evaluation manifests
|
|
125
|
+
- `README.md` - the human page of a skill, which describes THIS repository
|
|
126
|
+
|
|
127
|
+
The one deliberate exception is `hooks/README.md`, copied on purpose: hooks
|
|
128
|
+
execute automatically on the target's machine, so documenting what runs there
|
|
129
|
+
is transparency rather than clutter. If you add another internal-only category,
|
|
130
|
+
exclude it in both places and cover it with a test.
|
|
131
|
+
|
|
132
|
+
Where human docs live follows the artifact's shape: next to it when the
|
|
133
|
+
artifact is a folder (`skills/<name>/README.md`), under `docs/` when it is a
|
|
134
|
+
single file (`docs/rules/<name>.md`, since a rule has no folder of its own).
|
|
135
|
+
Neither is ever distributed, and both are guarded against drifting from the
|
|
136
|
+
artifact they document.
|
|
137
|
+
|
|
138
|
+
## Conventions
|
|
139
|
+
|
|
140
|
+
Commits follow `type(scope): description`, first line <= 72 characters.
|
|
141
|
+
Everything user-facing is in English, US spelling. Non-obvious decisions get an
|
|
142
|
+
append-only entry in [decisions.md](decisions.md) at the moment they are made -
|
|
143
|
+
never edit an old entry, add one that supersedes it.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Evaluating the prose skills
|
|
2
|
+
|
|
3
|
+
`tools/eval.ts` plays a skill through headless `claude -p` inside a throwaway
|
|
4
|
+
fixture and verdicts the result: mechanical gates first (from the skill's exit
|
|
5
|
+
conditions), an adjunct LLM judge for what stays subjective.
|
|
6
|
+
Design: [the spec](superpowers/specs/2026-07-20-skill-eval-harness-design.md).
|
|
7
|
+
|
|
8
|
+
## Commands
|
|
9
|
+
|
|
10
|
+
npx tsx playground/setup.ts # materialize the fixtures once
|
|
11
|
+
npx tsx tools/eval.ts run --dry-run # validate every skills/*/eval.yaml (CI does this)
|
|
12
|
+
npx tsx tools/eval.ts run --only detection-sweep # one skill, real agent run (API cost)
|
|
13
|
+
npx tsx tools/eval.ts run # full run - before a release only
|
|
14
|
+
|
|
15
|
+
Real runs need the `claude` CLI on PATH (or `EVAL_CLAUDE_BIN`); they are never
|
|
16
|
+
part of the public CI. Verdicts: PASS · FAIL(gate) · JUDGE-FAIL(criterion,
|
|
17
|
+
marked `~`, non-deterministic) · ERROR(infra - never treated as a regression).
|
|
18
|
+
|
|
19
|
+
## Adding a skill to the eval
|
|
20
|
+
|
|
21
|
+
All 34 skills carry one and all 34 pass a real agent run. Each combines mechanical gates
|
|
22
|
+
with a short judge rubric, in two shapes: gates+judge for skills with greppable
|
|
23
|
+
exit conditions, and class C (judge plus a `repo_clean` that only permits the
|
|
24
|
+
written deliverable) for judgment-heavy skills. A pure gates-only manifest is
|
|
25
|
+
allowed by the format but none is needed so far. Gate vocabulary:
|
|
26
|
+
`file_exists`, `file_absent`, `grep_zero`, `grep_count`, `repo_clean`,
|
|
27
|
+
`grep_min`, `transcript_contains`, `transcript_absent`, `exit_ok`. Extend the runner if a
|
|
28
|
+
new gate kind is needed - never free-form logic in YAML.
|
|
29
|
+
|
|
30
|
+
Judge criteria must be SHORT one-liners: the anti-leniency parser requires the
|
|
31
|
+
judge to echo each criterion verbatim, and long or multi-clause criteria get
|
|
32
|
+
paraphrased by real judges, which turns the run into an ERROR (calibrated on
|
|
33
|
+
the recording-decisions pilot).
|
|
34
|
+
|
|
35
|
+
Derive gates from the skill's own `## Exit condition` section, never from
|
|
36
|
+
intuition about what "clean" means. A skill that legitimately edits files must
|
|
37
|
+
not be gated with a bare `repo_clean`: list what it may touch in `except`, or
|
|
38
|
+
gate on the RESULT instead (a zero-match grep of the removed name, an exact
|
|
39
|
+
count of the migrated call sites). Numeric `grep_count` gates must be computed
|
|
40
|
+
against the fixture, not guessed: a rename that touches a declaration line plus
|
|
41
|
+
its usages yields more matches than the number of call sites.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Git worktrees - multi-agent isolation patterns
|
|
2
|
+
|
|
3
|
+
Generic reference for making several agents (or features) work in parallel without collision, via `git worktree`. Complements `superpowers:using-git-worktrees` (the basic when/how) with scaling patterns and pitfalls.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- When to use a worktree
|
|
8
|
+
- Symlinking heavy directories
|
|
9
|
+
- Conventions
|
|
10
|
+
- Caps (budgets)
|
|
11
|
+
- Session checklists
|
|
12
|
+
- Pitfalls
|
|
13
|
+
|
|
14
|
+
## When to use a worktree
|
|
15
|
+
|
|
16
|
+
One worktree = one branch = one isolated directory. Useful as soon as two independent bodies of work must not share the working tree (parallel agents, a long-running feature isolated from a hotfix). A single task at a time on a simple repo does not justify it.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
git worktree add ../repo-wt-<id> -b feat/<id>-<slug> # creates branch + worktree
|
|
20
|
+
git worktree list # worktree status
|
|
21
|
+
git worktree remove ../repo-wt-<id> # cleanup after merge
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Symlinking heavy directories
|
|
25
|
+
|
|
26
|
+
Reinstalling dependencies per worktree costs time and space. Symlink the heavy, regenerable directories to the main repo:
|
|
27
|
+
|
|
28
|
+
| Typical directory | Why symlink it |
|
|
29
|
+
|-----------------|-----------------------|
|
|
30
|
+
| `node_modules/` | avoids an `install` (often ~1 GB) per worktree |
|
|
31
|
+
| framework build caches (`.next`, `.nuxt`, `.turbo`…) | avoids regeneration |
|
|
32
|
+
| native build directory (`target/`, `build/`…) | avoids recompilation (can be huge) |
|
|
33
|
+
|
|
34
|
+
→ Never rerun dependency installation in a symlinked worktree. Build tools that place a lock (Cargo, etc.) serialize parallel builds automatically.
|
|
35
|
+
|
|
36
|
+
## Conventions
|
|
37
|
+
|
|
38
|
+
| Element | Suggested format |
|
|
39
|
+
|---------|----------------|
|
|
40
|
+
| Feature branch | `feat/{id}-<slug>` |
|
|
41
|
+
| Bugfix branch | `fix/{id}-<slug>` |
|
|
42
|
+
| Worktree path | `../<repo>-wt-{id}` (outside the main tree) |
|
|
43
|
+
| Resume | `git pull --rebase origin <base>` |
|
|
44
|
+
|
|
45
|
+
Adapt `{id}` to the project's tracker (ticket number, issue…).
|
|
46
|
+
|
|
47
|
+
## Caps (budgets)
|
|
48
|
+
|
|
49
|
+
Beyond a certain number of worktrees / branches in flight, the cognitive cost and conflicts explode. Set an explicit cap (e.g. ~6 worktrees, ~5 branches in review at once) and enforce it - via a hook (see `hooks/`) or a manual check at the start of a session. A cap reached = finish/merge before opening a new front.
|
|
50
|
+
|
|
51
|
+
## Session checklists
|
|
52
|
+
|
|
53
|
+
**Start**: list the existing worktrees → create/join the one for the current work → work **in that worktree only**.
|
|
54
|
+
|
|
55
|
+
**End**: `git status` + check for unpushed commits (`git log origin/<branch>..HEAD`) → after merge, remove the worktree → never manually delete a worktree before the merge.
|
|
56
|
+
|
|
57
|
+
## Pitfalls
|
|
58
|
+
|
|
59
|
+
- **Working in the wrong worktree**: always check the `pwd`/branch before editing.
|
|
60
|
+
- **Coupling between tickets**: two worktrees touching the same files → merge conflicts. Detect the overlap before parallelizing; serialize if coupled.
|
|
61
|
+
- **Deleting a dirty/unpushed worktree**: loss of work. Check the state before `remove`.
|
|
62
|
+
- **`install` in a symlinked worktree**: breaks the shared symlink. Forbidden.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Rule - `clean-architecture-deps`
|
|
2
|
+
|
|
3
|
+
> The business core knows nothing about I/O, frameworks, or databases. Dependencies always point inward, toward the domain.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (path-scoped) |
|
|
8
|
+
| **Scope (`paths`)** | `**/*.ts`, `**/*.py`, `**/*.go`, `**/*.rs`, `**/*.php`, `**/*.java` |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/clean-architecture-deps.md`](../../rules/clean-architecture-deps.md) |
|
|
11
|
+
| **Paired skills** | [`ddd-backend-implementation`](../../skills/ddd-backend-implementation/), [`domain-modeling-design`](../../skills/domain-modeling-design/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
The **dependency rule** of layered / hexagonal / clean architectures: source-code dependencies only ever point toward the business core. Concretely:
|
|
16
|
+
|
|
17
|
+
- The domain (entities, value objects, use cases) imports nothing technical - no HTTP client, no ORM, no framework type.
|
|
18
|
+
- Controllers, handlers, and routes stay thin: parse input, call a use case, serialize output. No business rule lives there.
|
|
19
|
+
- Interfaces (ports) are declared where they are **used** (application layer); their concrete implementations (adapters) live in infrastructure and depend inward.
|
|
20
|
+
- Invariants are validated at construction of the entity or value object, not scattered across callers.
|
|
21
|
+
- No layer is short-circuited (a handler never talks to the DB directly).
|
|
22
|
+
|
|
23
|
+
## Why it matters
|
|
24
|
+
|
|
25
|
+
When the domain depends on infrastructure, every technical decision leaks into the business logic: you cannot swap a database, test a use case without a live connection, or reason about a rule without loading a framework. Inverting the dependencies keeps the core **pure and testable**, isolates churn (frameworks change far more often than business rules), and makes the boundaries explicit so the codebase does not collapse into a big ball of mud.
|
|
26
|
+
|
|
27
|
+
Validating invariants at the data's construction point means an invalid entity simply cannot exist - every downstream layer can trust it, instead of re-checking or discovering corruption late.
|
|
28
|
+
|
|
29
|
+
## How to apply it
|
|
30
|
+
|
|
31
|
+
### Define the port where it is consumed
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// application/ports/UserRepository.ts (application layer owns the interface)
|
|
35
|
+
export interface UserRepository {
|
|
36
|
+
findById(id: UserId): Promise<User | null>;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
// infrastructure/PostgresUserRepository.ts (adapter depends inward)
|
|
40
|
+
export class PostgresUserRepository implements UserRepository { /* ... */ }
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Keep the handler thin
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
// Bad - business logic in the route
|
|
47
|
+
app.post('/orders', (req, res) => {
|
|
48
|
+
if (req.body.total > creditLimit) { /* rule leaked into the controller */ }
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
// Good - parse, delegate, serialize
|
|
52
|
+
app.post('/orders', async (req, res) => {
|
|
53
|
+
const result = await placeOrder.execute(toCommand(req.body));
|
|
54
|
+
res.json(toDto(result));
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Push invariants into the type
|
|
59
|
+
|
|
60
|
+
Prefer a constrained value object (`EmailAddress`, `PositiveQuantity`) over a bare `string`/`number`, and validate in its constructor so no invalid instance can be built.
|
|
61
|
+
|
|
62
|
+
## Related
|
|
63
|
+
|
|
64
|
+
- [`ddd-backend-implementation`](../../skills/ddd-backend-implementation/) applies this layering when building a backend feature.
|
|
65
|
+
- [`domain-modeling-design`](../../skills/domain-modeling-design/) drives the modeling of entities, value objects, and boundaries.
|
|
66
|
+
- Companion rule: [`error-handling-discipline`](error-handling-discipline.md) (errors cross boundaries as typed values).
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Rule - `commits`
|
|
2
|
+
|
|
3
|
+
> Every commit message follows one conventional format, stays under 72 characters on the first line, and never mentions the tooling that wrote it.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Rule (always-on) |
|
|
8
|
+
| **Scope (`paths`)** | always active |
|
|
9
|
+
| **Version** | 1.0.0 |
|
|
10
|
+
| **Artifact** | [`rules/commits.md`](../../rules/commits.md) |
|
|
11
|
+
| **Paired skill** | [`commit-readiness-review`](../../skills/commit-readiness-review/) |
|
|
12
|
+
|
|
13
|
+
## What it enforces
|
|
14
|
+
|
|
15
|
+
A single, machine-parseable commit convention:
|
|
16
|
+
|
|
17
|
+
- **Format**: `type(scope): description (Closes #XX)`
|
|
18
|
+
- **Allowed types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
|
|
19
|
+
- First line **≤ 72 characters**
|
|
20
|
+
- `(Closes #<iid>)` when the commit closes a ticket
|
|
21
|
+
- **Never** mention Claude, AI, or LLM in the message
|
|
22
|
+
- Ask for confirmation before `git commit`
|
|
23
|
+
- Split unrelated changes into separate logical commits
|
|
24
|
+
|
|
25
|
+
## Why it matters
|
|
26
|
+
|
|
27
|
+
Conventional commit messages are not cosmetic. A consistent `type(scope):` prefix lets tooling derive changelogs, compute semantic version bumps, and group history by area. The 72-character limit keeps `git log --oneline`, blame views, and hosting UIs readable without truncation. Linking `Closes #XX` wires the commit to its ticket so traceability is automatic.
|
|
28
|
+
|
|
29
|
+
Keeping tooling attribution out of the message keeps history about **what changed and why**, not about how it was produced - the authorship that matters is the engineering intent.
|
|
30
|
+
|
|
31
|
+
Asking before committing keeps a human in the loop for the one action that rewrites shared history.
|
|
32
|
+
|
|
33
|
+
## How to apply it
|
|
34
|
+
|
|
35
|
+
### Check the local convention first
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
git log --oneline -5
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Recent history is the source of truth for scope naming; match it before writing a new message.
|
|
42
|
+
|
|
43
|
+
### Well-formed examples
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
feat(auth): add refresh-token rotation (Closes #142)
|
|
47
|
+
fix(parser): handle empty payload without throwing
|
|
48
|
+
refactor(orders): extract pricing into a use case
|
|
49
|
+
docs(readme): document the install flow
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Splitting unrelated work
|
|
53
|
+
|
|
54
|
+
If a diff touches an auth fix and a docs update, make two commits - even if that means running the pre-commit hooks twice. One concern per commit keeps `git revert` and `git bisect` surgical.
|
|
55
|
+
|
|
56
|
+
## Related
|
|
57
|
+
|
|
58
|
+
- [`commit-readiness-review`](../../skills/commit-readiness-review/) runs the pre-commit gate (secret scan, leftovers, message format) before the commit lands.
|
|
59
|
+
- Companion rule: [`pre-commit-secret-detection`](pre-commit-secret-detection.md) (never commit a credential).
|