ronce-racine 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/AGENTS.md +90 -0
  2. package/LICENSE +21 -0
  3. package/README.md +281 -0
  4. package/agents/code-reviewer.md +33 -0
  5. package/agents/qa-tester.md +28 -0
  6. package/dist/hooks/README.md +182 -0
  7. package/dist/hooks/bash-npm-silent.mjs +81 -0
  8. package/dist/hooks/session-inject.mjs +53 -0
  9. package/dist/hooks/session-precompact.mjs +36 -0
  10. package/dist/hooks/session-writer.mjs +142 -0
  11. package/dist/hooks/skill-reminder.mjs +89 -0
  12. package/dist/hooks/truncate-bash-output.mjs +46 -0
  13. package/dist/hooks/truncate-output.mjs +88 -0
  14. package/dist/hooks/worktree-env-setup.mjs +123 -0
  15. package/dist/install.js +962 -0
  16. package/docs/adopting-a-repo.md +80 -0
  17. package/docs/architecture.md +76 -0
  18. package/docs/decisions.md +72 -0
  19. package/docs/developing.md +143 -0
  20. package/docs/evaluating-skills.md +41 -0
  21. package/docs/git-worktrees.md +62 -0
  22. package/docs/rules/clean-architecture-deps.md +66 -0
  23. package/docs/rules/commits.md +59 -0
  24. package/docs/rules/detection-gap-protocol.md +55 -0
  25. package/docs/rules/error-handling-discipline.md +62 -0
  26. package/docs/rules/minimal-code.md +58 -0
  27. package/docs/rules/no-raw-sql-interpolation.md +57 -0
  28. package/docs/rules/pre-commit-secret-detection.md +54 -0
  29. package/docs/rules/secure-logging.md +53 -0
  30. package/docs/rules/sql-migrations-discipline.md +58 -0
  31. package/docs/rules/subscription-cleanup.md +63 -0
  32. package/docs/rules/test-discipline.md +66 -0
  33. package/docs/rules/ui-states-complete.md +52 -0
  34. package/docs/templates/SKILL.template.md +66 -0
  35. package/docs/templates/rule.template.md +16 -0
  36. package/docs/writing-a-rule.md +43 -0
  37. package/docs/writing-a-skill.md +118 -0
  38. package/package.json +45 -0
  39. package/rules/clean-architecture-deps.md +20 -0
  40. package/rules/commits.md +16 -0
  41. package/rules/detection-gap-protocol.md +35 -0
  42. package/rules/error-handling-discipline.md +23 -0
  43. package/rules/minimal-code.md +32 -0
  44. package/rules/no-raw-sql-interpolation.md +20 -0
  45. package/rules/pre-commit-secret-detection.md +14 -0
  46. package/rules/secure-logging.md +16 -0
  47. package/rules/sql-migrations-discipline.md +18 -0
  48. package/rules/subscription-cleanup.md +22 -0
  49. package/rules/test-discipline.md +20 -0
  50. package/rules/ui-states-complete.md +23 -0
  51. package/scripts/subscription-leak-scan.ts +53 -0
  52. package/skills/adversarial-feature-challenge/README.md +65 -0
  53. package/skills/adversarial-feature-challenge/SKILL.md +96 -0
  54. package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
  55. package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
  56. package/skills/api-contract-versioning/README.md +62 -0
  57. package/skills/api-contract-versioning/SKILL.md +76 -0
  58. package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
  59. package/skills/audit-architecture/README.md +56 -0
  60. package/skills/audit-architecture/SKILL.md +97 -0
  61. package/skills/audit-architecture/reference/ar-architecture.md +275 -0
  62. package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
  63. package/skills/audit-architecture/reference/im-incidents.md +217 -0
  64. package/skills/audit-architecture/reference/pa-pannes.md +362 -0
  65. package/skills/audit-architecture/reference/re-recuperation.md +300 -0
  66. package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
  67. package/skills/audit-architecture/reference/su-support.md +180 -0
  68. package/skills/audit-ci-cd/README.md +54 -0
  69. package/skills/audit-ci-cd/SKILL.md +124 -0
  70. package/skills/audit-ci-cd/reference/artefacts.md +39 -0
  71. package/skills/audit-ci-cd/reference/deploiement.md +100 -0
  72. package/skills/audit-ci-cd/reference/dora.md +94 -0
  73. package/skills/audit-ci-cd/reference/iac.md +40 -0
  74. package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
  75. package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
  76. package/skills/audit-compliance/README.md +69 -0
  77. package/skills/audit-compliance/SKILL.md +176 -0
  78. package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
  79. package/skills/audit-compliance/reference/finops.md +318 -0
  80. package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
  81. package/skills/audit-industrialisation/README.md +53 -0
  82. package/skills/audit-industrialisation/SKILL.md +251 -0
  83. package/skills/audit-observability/README.md +64 -0
  84. package/skills/audit-observability/SKILL.md +134 -0
  85. package/skills/audit-observability/reference/alerting.md +214 -0
  86. package/skills/audit-observability/reference/logging.md +114 -0
  87. package/skills/audit-observability/reference/metriques.md +166 -0
  88. package/skills/audit-observability/reference/traces-dashboards.md +90 -0
  89. package/skills/audit-performance-frontend/README.md +91 -0
  90. package/skills/audit-performance-frontend/SKILL.md +194 -0
  91. package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
  92. package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
  93. package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
  94. package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
  95. package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
  96. package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
  97. package/skills/audit-quality/README.md +85 -0
  98. package/skills/audit-quality/SKILL.md +126 -0
  99. package/skills/audit-quality/reference/qa-devops.md +539 -0
  100. package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
  101. package/skills/audit-report/README.md +72 -0
  102. package/skills/audit-report/SKILL.md +241 -0
  103. package/skills/audit-report/reference/scoring-model.md +45 -0
  104. package/skills/audit-security/README.md +72 -0
  105. package/skills/audit-security/SKILL.md +140 -0
  106. package/skills/audit-security/reference/auth-identite.md +98 -0
  107. package/skills/audit-security/reference/autorisation.md +66 -0
  108. package/skills/audit-security/reference/chiffrement-tls.md +97 -0
  109. package/skills/audit-security/reference/detection-patching.md +67 -0
  110. package/skills/audit-security/reference/incident-response.md +98 -0
  111. package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
  112. package/skills/audit-security/reference/secrets.md +36 -0
  113. package/skills/audit-testing/README.md +82 -0
  114. package/skills/audit-testing/SKILL.md +131 -0
  115. package/skills/audit-testing/reference/golden-dataset.md +65 -0
  116. package/skills/audit-testing/reference/resilience-chaos.md +93 -0
  117. package/skills/audit-testing/reference/tests-contractuels.md +65 -0
  118. package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
  119. package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
  120. package/skills/bug-ticket-root-cause/README.md +67 -0
  121. package/skills/bug-ticket-root-cause/SKILL.md +86 -0
  122. package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
  123. package/skills/bug-triage-structured/README.md +63 -0
  124. package/skills/bug-triage-structured/SKILL.md +104 -0
  125. package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
  126. package/skills/ci-pipeline-orchestration/README.md +55 -0
  127. package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
  128. package/skills/commit-readiness-review/README.md +66 -0
  129. package/skills/commit-readiness-review/SKILL.md +82 -0
  130. package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
  131. package/skills/comprehensive-test-strategy/README.md +64 -0
  132. package/skills/comprehensive-test-strategy/SKILL.md +108 -0
  133. package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
  134. package/skills/daily-workflow-optimization/README.md +56 -0
  135. package/skills/daily-workflow-optimization/SKILL.md +80 -0
  136. package/skills/database-schema-evolution/README.md +54 -0
  137. package/skills/database-schema-evolution/SKILL.md +107 -0
  138. package/skills/ddd-backend-implementation/README.md +63 -0
  139. package/skills/ddd-backend-implementation/SKILL.md +95 -0
  140. package/skills/design-system-component-lifecycle/README.md +56 -0
  141. package/skills/design-system-component-lifecycle/SKILL.md +97 -0
  142. package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
  143. package/skills/detection-sweep/README.md +58 -0
  144. package/skills/detection-sweep/SKILL.md +93 -0
  145. package/skills/detection-sweep/scripts/sweep.ts +80 -0
  146. package/skills/domain-modeling-design/README.md +57 -0
  147. package/skills/domain-modeling-design/SKILL.md +83 -0
  148. package/skills/frontend-fullstack-implementation/README.md +60 -0
  149. package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
  150. package/skills/frontend-spec-call-site-audit/README.md +66 -0
  151. package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
  152. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
  153. package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
  154. package/skills/merge-request-review/README.md +60 -0
  155. package/skills/merge-request-review/SKILL.md +77 -0
  156. package/skills/merge-request-review/templates/mr-review-report.md +29 -0
  157. package/skills/production-incident-diagnostic/README.md +63 -0
  158. package/skills/production-incident-diagnostic/SKILL.md +103 -0
  159. package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
  160. package/skills/qa-session-intake/README.md +56 -0
  161. package/skills/qa-session-intake/SKILL.md +78 -0
  162. package/skills/recording-decisions/README.md +91 -0
  163. package/skills/recording-decisions/SKILL.md +84 -0
  164. package/skills/recurring-bug-root-cause/README.md +64 -0
  165. package/skills/recurring-bug-root-cause/SKILL.md +93 -0
  166. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
  167. package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
  168. package/skills/refactoring-shared-component-api/README.md +50 -0
  169. package/skills/refactoring-shared-component-api/SKILL.md +84 -0
  170. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
  171. package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
  172. package/skills/validating-features-end-to-end/README.md +50 -0
  173. package/skills/validating-features-end-to-end/SKILL.md +90 -0
  174. package/skills/visual-regression-check/README.md +51 -0
  175. package/skills/visual-regression-check/SKILL.md +89 -0
  176. package/skills/writing-robust-tests/README.md +53 -0
  177. package/skills/writing-robust-tests/SKILL.md +88 -0
  178. package/templates/.adopted.example +8 -0
  179. package/templates/anti-drift.gitlab-ci.yml +23 -0
@@ -0,0 +1,16 @@
1
+ ---
2
+ # Limit injection to the relevant files (saves context).
3
+ # Omit the whole frontmatter for an always-on rule.
4
+ paths:
5
+ - "**/*.ext"
6
+ version: 1.0.0
7
+ metadata:
8
+ last-reviewed: YYYY-MM-DD
9
+ ---
10
+
11
+ # Short rule title
12
+
13
+ - First rule, imperative and verifiable.
14
+ - Second rule.
15
+
16
+ <!-- Details and examples belong in a linked doc, not in the rule. -->
@@ -0,0 +1,43 @@
1
+ # Writing a canonical rule
2
+
3
+ ## Admission criterion: is it truly generic?
4
+
5
+ A rule belongs here **only** if it contains **no**:
6
+
7
+ - crate, package, module, or directory name of a specific project;
8
+ - specific script or file path (`scripts/...`, `validate.sh`, a template);
9
+ - business identifier (`invitation_id`, `connector_id`…) or CI gate name (`gate 8`, an ast-grep rule);
10
+ - reference to a stack imposed by a single project.
11
+
12
+ If the rule is useful but coupled, **split it**: the generic *principle* comes here, the *tooled how* stays in a project rule `rules/<project>/`.
13
+
14
+ > Example: "never log sensitive data" is generic → here. "the `validate.sh` lint blocks `email = %` and we use `invitation_id`" is project-specific → a project rule.
15
+
16
+ ## Format
17
+
18
+ ```markdown
19
+ ---
20
+ paths:
21
+ - "glob/of/files/**"
22
+ version: 1.0.0
23
+ metadata:
24
+ last-reviewed: YYYY-MM-DD
25
+ ---
26
+
27
+ # Short title
28
+
29
+ - Imperative, verifiable, concise bullets.
30
+ - No magic numbers, no fluff.
31
+ ```
32
+
33
+ - **`paths:` frontmatter**: limits injection to the relevant files (saves context). Omitting it → always-active rule (reserve for cross-cutting rules like `commits.md`).
34
+ - **`version` (semver) + `metadata.last-reviewed`**: like skills (see [writing-a-skill.md](writing-a-skill.md)). Bump on every revision. Validated by `npm run rules:validate` (included in `npm test`).
35
+ - No `<!-- ... -->` provenance comment: the source of truth is this repo, no need to repeat it (and Claude Code strips them from context anyway).
36
+ - Keep it short: a long rule is followed less. Details and examples → a linked doc, not the rule.
37
+
38
+ Ready-to-copy skeleton: [`templates/rule.template.md`](templates/rule.template.md).
39
+
40
+ ## After adding / modifying
41
+
42
+ 1. Update the rules table in the [README](../README.md).
43
+ 2. Re-sync the repos that adopt the rule (`npx ronce-racine install <repo> --rules-only`), or let their CI gate report the drift.
@@ -0,0 +1,118 @@
1
+ # Writing a canonical skill
2
+
3
+ ## Admission criterion: is it truly generic?
4
+
5
+ Same criteria as for a rule ([writing-a-rule.md](writing-a-rule.md)). A skill belongs here **only** if it contains **no**:
6
+
7
+ - crate, package, module, directory, or script name of a specific project;
8
+ - imposed tracker (GitLab/Jira/GitHub hardcoded), project identifier format;
9
+ - stack imposed by a single project (Axum, Nuxt, Supabase RLS…).
10
+
11
+ If the workflow is useful but coupled, **split it**: the generic *protocol* comes here, the *tooled how* (project scripts, golden dataset, CI gates) stays in a project skill `<repo>/.claude/skills/`. Each generic skill notes up front that the project variant takes precedence.
12
+
13
+ ## What a complete skill looks like
14
+
15
+ Every file below is required by a CI gate. A skill missing one of them fails `npm test`.
16
+
17
+ ```
18
+ skills/<name>/
19
+ SKILL.md the skill itself (contract below)
20
+ README.md human-facing page: what it is, when it fires, how it is verified
21
+ eval.yaml behavioral evaluation manifest (see below)
22
+ scripts/<x>.ts optional: deterministic detection script
23
+ scripts/<x>.test.ts REQUIRED if scripts/<x>.ts exists
24
+ reference/*.md optional: heavy material (progressive disclosure)
25
+ templates/*.md optional: output templates
26
+ ```
27
+
28
+ Ready-to-copy skeleton: [`templates/SKILL.template.md`](templates/SKILL.template.md).
29
+
30
+ ## 1. SKILL.md contract
31
+
32
+ **Frontmatter** (`version` and `metadata` are fields supported by the [agentskills.io](https://agentskills.io/specification) spec):
33
+
34
+ ```yaml
35
+ ---
36
+ name: kebab-case
37
+ description: Use when <third-person triggers, symptoms, verbatims>
38
+ version: 1.0.0
39
+ metadata:
40
+ last-reviewed: YYYY-MM-DD
41
+ category: audit | feature | bug | frontend | test | process
42
+ ---
43
+ ```
44
+
45
+ - `description`: starts with "Use when", **third person** (never "I/you"), describes WHEN not HOW - never summarize the workflow in it (the agent would follow the summary instead of reading the skill).
46
+ - **Quoted triggers, bilingual**: the description must contain the invocation phrases in quotes, in **English and French**. They are what routes a request to this skill, and `tools/skills.ts triggers` lints them: each quoted trigger must rank its own skill in the top 3 against all others. A trigger too generic to discriminate fails CI.
47
+ ```
48
+ Triggers on "run a sweep", "detect the problems", "lance un sweep", "détecte les problèmes"
49
+ ```
50
+ - `version`: semver. Bump **patch** for a clarification, **minor** for an added section, **major** for a protocol change.
51
+ - `metadata.last-reviewed`: date of the last review; `category` from the closed list.
52
+
53
+ **Body - standard sections** (omit an irrelevant section, never fill it empty):
54
+
55
+ 1. Title + principle · 2. Routing "When ME and not X" · 3. Context to gather · 4. Protocol · 5. Templates · 6. Pitfalls & rationalizations · 7. Exit condition · 8. Tooling · 9. Changelog.
56
+
57
+ The **Exit condition** section carries more weight than the rest: it is what the evaluation harness gates on. Write it as a checklist of *observable* outcomes (a file produced, a grep that returns nothing, an output pasted), not intentions.
58
+
59
+ ## 2. eval.yaml: proving the skill still works
60
+
61
+ Prose is not testable by a linter, so every skill declares how an agent following it should be judged. Full guide: [evaluating-skills.md](evaluating-skills.md).
62
+
63
+ ```yaml
64
+ fixture: flawed-app # a playground fixture (playground/setup.ts)
65
+ prompt: > # what a user would naturally ask
66
+ Run a detection sweep on this project.
67
+ gates: # mechanical, reproducible
68
+ - repo_clean: { except: "REPORT.md" }
69
+ - file_exists: "REPORT.md"
70
+ judge: # optional, for what stays subjective
71
+ criteria:
72
+ - "Findings are grouped by cause, not occurrence"
73
+ threshold: pass_all
74
+ ```
75
+
76
+ Three rules, each learned from a real run that failed for the wrong reason:
77
+
78
+ - **Derive gates from your own Exit condition section**, never from intuition about what "clean" means. A skill that legitimately writes files must list them in `repo_clean`'s `except` - otherwise the manifest punishes an agent for obeying the skill.
79
+ - **`repo_clean` is for read-only skills only.** For a skill that builds
80
+ something, you cannot enumerate upfront what an agent will legitimately
81
+ produce (tests, configs, adapters, a CI job, probe scripts): every run
82
+ surfaces a new file and the except list never converges. Gate the skill's
83
+ **invariant** instead - what must NOT happen. Examples that work: a challenge
84
+ skill must not fix the feature it attacks (`grep_zero` on validation added to
85
+ the target), a DDD skill must not invert its dependency direction
86
+ (`grep_zero` on infrastructure imports inside the domain), a bug skill must
87
+ actually remove the bug (`grep_zero` on the planted defect).
88
+ - **Judge criteria are short one-liners** (~12 words). The anti-leniency parser makes the judge echo each criterion verbatim; long ones get paraphrased and the run errors out.
89
+ - **Numeric `grep_count` gates are computed against the fixture, never guessed.** Over agent-authored content the exact count is unknowable: use `grep_min` (a floor) instead. Same reflex for file names - do not gate on `foo.test.js` when the project convention might be `foo.spec.js`.
90
+
91
+ Validate with `npm run eval:dry` (no agent call, no network). A real run costs API tokens: `npx tsx tools/eval.ts run --only <name>`.
92
+
93
+ ## 3. Scripts and their test procedure
94
+
95
+ A deterministic detection command belongs in `scripts/` ("Run `scripts/x.ts`") rather than inline prose: more reliable, saves context. Any script **must** ship a co-located `scripts/<x>.test.ts` exercising a positive AND a negative fixture, and a matching entry in [`tools/mutations.ts`](../tools/mutations.ts) so a test that cannot fail is caught.
96
+
97
+ ## Applied best practices
98
+
99
+ - **Concise**: SKILL.md body < 500 lines. Beyond that → progressive disclosure: move heavy references (grids, APIs) into `reference/*.md` with a table of contents at the top.
100
+ - **Reference depth ≤ 1**: all links start from the SKILL.md, never from a nested reference.
101
+ - **Output templates** in `templates/`, pitfalls in an Excuse → Reality table, exit condition as a checklist.
102
+
103
+ ## Validation before opening a PR
104
+
105
+ ```bash
106
+ npm test # structure, bilingual trigger routing, versioning, behavioral tests
107
+ npm run typecheck
108
+ npm run test:mutation # every declared mutation must turn its tests red
109
+ npm run eval:dry # every eval.yaml parses and names an existing fixture
110
+ ```
111
+
112
+ All four run in CI. The harness fails (exit 1) on any drift from the contract.
113
+
114
+ ## After adding / modifying
115
+
116
+ 1. Bump `version` + `last-reviewed`, add a line to the `## Changelog`.
117
+ 2. Update the skills table in the [README](../README.md).
118
+ 3. The four commands above, green.
package/package.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "ronce-racine",
3
+ "version": "0.5.0",
4
+ "type": "module",
5
+ "description": "Ronce Racine - generic Claude Code config (always-on rules + on-demand skills) with a distribution CLI",
6
+ "license": "MIT",
7
+ "bin": {
8
+ "ronce-racine": "dist/install.js"
9
+ },
10
+ "files": [
11
+ "dist/",
12
+ "rules/",
13
+ "skills/",
14
+ "!skills/**/eval.yaml",
15
+ "!skills/**/*.test.ts",
16
+ "agents/",
17
+ "scripts/",
18
+ "templates/",
19
+ "docs/",
20
+ "!docs/superpowers/",
21
+ "AGENTS.md"
22
+ ],
23
+ "repository": { "type": "git", "url": "git+https://github.com/ChariereFiedler/ronce-racine.git" },
24
+ "keywords": ["claude-code", "ai-agents", "developer-tools", "code-quality"],
25
+ "engines": {
26
+ "node": ">=18"
27
+ },
28
+ "scripts": {
29
+ "build": "tsx tools/build.ts",
30
+ "typecheck": "tsc --noEmit",
31
+ "test": "tsx tools/skills.ts validate && tsx tools/skills.ts triggers && tsx tools/skills.ts rules && tsx tools/skills.ts scripts && tsx tools/skills.ts hooks && tsx tools/skills.ts templates && tsx tools/tests.ts",
32
+ "test:mutation": "tsx tools/mutations.ts",
33
+ "eval:dry": "tsx playground/setup.ts >/dev/null && tsx tools/eval.ts run --dry-run",
34
+ "skills:list": "tsx tools/skills.ts list",
35
+ "skills:triggers": "tsx tools/skills.ts triggers",
36
+ "rules:validate": "tsx tools/skills.ts rules",
37
+ "prepare": "tsx tools/build.ts",
38
+ "prepublishOnly": "tsx tools/build.ts && npm test"
39
+ },
40
+ "devDependencies": {
41
+ "@types/node": "^22.0.0",
42
+ "tsx": "^4.0.0",
43
+ "typescript": "^5.0.0"
44
+ }
45
+ }
@@ -0,0 +1,20 @@
1
+ ---
2
+ paths:
3
+ - "**/*.ts"
4
+ - "**/*.py"
5
+ - "**/*.go"
6
+ - "**/*.rs"
7
+ - "**/*.php"
8
+ - "**/*.java"
9
+ version: 1.0.0
10
+ metadata:
11
+ last-reviewed: 2026-06-19
12
+ ---
13
+
14
+ # Dependency direction
15
+
16
+ - **Dependencies point inward**: the business core (domain, entities) depends on no external technical detail (I/O, framework, DB, HTTP). Infrastructure depends on the domain, never the reverse.
17
+ - **No business logic in the controller / handler / route**: it parses the input, calls a use case, serializes the output. Business rules live in the domain/application layer.
18
+ - **Ports on the application side, adapters on the infrastructure side**: the interface (trait/interface) is defined where it is consumed; the concrete implementation (DB, third-party API) implements it from the outside.
19
+ - **Invariants closest to the data**: validate when constructing the entity / value object, not in the calling layer. Prefer a constrained type over a bare primitive for a constrained field.
20
+ - **No layer short-circuit**: a handler does not reach the database directly by skipping the application layer.
@@ -0,0 +1,16 @@
1
+ ---
2
+ version: 1.0.0
3
+ metadata:
4
+ last-reviewed: 2026-06-19
5
+ ---
6
+
7
+ # Commit messages
8
+
9
+ - Format: `type(scope): description (Closes #XX)`
10
+ - Allowed types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
11
+ - **Never** mention Claude, AI, or LLM in a commit message
12
+ - First line ≤ 72 characters
13
+ - Include `(Closes #<iid>)` when the commit closes a ticket
14
+ - Always ask for confirmation before `git commit`
15
+ - Check the format of recent commits (`git log --oneline -5`) before committing
16
+ - Separate logical commits for unrelated changes, even if the pre-commit hooks have to run again
@@ -0,0 +1,35 @@
1
+ ---
2
+ paths:
3
+ - "docs/postmortems/**"
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ ---
8
+
9
+ # DANGER protocol - user-reported P0 regression
10
+
11
+ A P0 regression **found by a user** (not by CI/E2E/smoke/monitoring) is a **detection failure**: the user must never be the safety net.
12
+
13
+ ## Mandatory handling
14
+
15
+ 1. **Postmortem** using a dedicated "detection gap" template (not the standard one)
16
+ 2. **Mandatory "Detection gap" section** - analyzing every level that should have caught the bug
17
+ 3. **Regression test** that **would have caught the bug** - at the right level (SPA navigation, mobile, deployed)
18
+ 4. **`detection-gap` label** on the originating ticket
19
+ 5. **Blocking lint**: reject a user-reported postmortem without a "Detection gap" section
20
+
21
+ ## Coverage levels to analyze
22
+
23
+ | Level | Question |
24
+ |-------|----------|
25
+ | CI compile/lint | Did the code pass typecheck / lint / clippy? |
26
+ | Unit tests | Did a UT cover the broken invariant? |
27
+ | E2E tests | Did a scenario reproduce the user flow? |
28
+ | Post-deploy smoke | Did the smoke test hit this route? |
29
+ | Synthetic monitoring | Did a probe watch this endpoint in prod? |
30
+
31
+ ## Recurring review
32
+
33
+ Aggregate `detection-gap` tickets to identify **families of gaps** and prioritize coverage investments (E2E, smoke, monitoring).
34
+
35
+ <!-- Paths to the lint/smoke scripts and the template: to be wired in a project rule. -->
@@ -0,0 +1,23 @@
1
+ ---
2
+ paths:
3
+ - "**/*.ts"
4
+ - "**/*.tsx"
5
+ - "**/*.js"
6
+ - "**/*.vue"
7
+ - "**/*.py"
8
+ - "**/*.go"
9
+ - "**/*.rs"
10
+ - "**/*.php"
11
+ - "**/*.java"
12
+ version: 1.0.0
13
+ metadata:
14
+ last-reviewed: 2026-06-19
15
+ ---
16
+
17
+ # Error handling - no silent failure
18
+
19
+ - **Never swallow an error**: no empty `catch {}`, no `catch` that logs and carries on as if nothing happened, no `except: pass`, no ignored `_ = err`.
20
+ - **No crash on a fallible operation in prod**: no `unwrap()`/`expect()`/`panic!` (Rust), no unguaranteed `!!`/`!`, no forced cast on a value that can fail - return/propagate a typed error. (Tolerated in tests.)
21
+ - **Propagate or handle - choose explicitly**: either surface the error (`Result`/`throw`/`raise`), or deal with it (fallback, bounded retry, user message). Never something in between.
22
+ - **Enrich the context before propagating**: which operation, which non-sensitive identifier (see [`secure-logging`](secure-logging.md)) - not a bare message.
23
+ - **Distinguish expected / unexpected**: an expected business error is handled locally; an unexpected one bubbles up to a boundary that decides (and alerts).
@@ -0,0 +1,32 @@
1
+ ---
2
+ paths:
3
+ - "**/*.rs"
4
+ - "**/*.ts"
5
+ - "**/*.tsx"
6
+ - "**/*.vue"
7
+ - "**/*.py"
8
+ - "**/*.go"
9
+ version: 1.0.0
10
+ metadata:
11
+ last-reviewed: 2026-06-19
12
+ ---
13
+
14
+ # Less code, not fewer lines
15
+
16
+ The best code is the code you don't write. Before adding code, go down the hierarchy and stop at the first level that meets the need:
17
+
18
+ 1. **Is the need real?** No speculation (YAGNI). Only code what is asked for or proven necessary.
19
+ 2. **Does the stdlib / the language already do it?** (iterators, native collection methods, framework helpers.)
20
+ 3. **Does an already-installed dependency do it?** Check the manifest (`Cargo.toml`, `package.json`, `go.mod`…) before adding a lib or reimplementing.
21
+ 4. **Does a component / module / function already in the project do it?** Reuse before duplicating.
22
+ 5. **Otherwise, write the simplest solution** that covers the case - and only that case.
23
+
24
+ ## Guardrail: readability > brevity
25
+
26
+ Minimizing code **does not mean minimizing lines**. A "shortest line" goal produces unreadable, unmaintainable code - that is a failure, not a success.
27
+
28
+ - **Forbidden**: cryptic one-liners, nested operator chains, obscure abbreviations, removing intermediate names just to "save a line".
29
+ - **Preferred**: a well-named intermediate variable over a dense expression; an early return over a nested ternary; splitting into short named functions stays the priority.
30
+ - The right instinct is to **delete superfluous code** (premature abstractions, needless indirection, empty wrappers, never-used options), not to **compress useful code**.
31
+
32
+ > Arbitration rule: if the shortest code is less clear than slightly longer code, choose the clearer one. The target is *less surface to maintain*, not *fewer characters*.
@@ -0,0 +1,20 @@
1
+ ---
2
+ paths:
3
+ - "**/*.ts"
4
+ - "**/*.js"
5
+ - "**/*.py"
6
+ - "**/*.go"
7
+ - "**/*.rs"
8
+ - "**/*.php"
9
+ - "**/*.java"
10
+ version: 1.0.0
11
+ metadata:
12
+ last-reviewed: 2026-06-19
13
+ ---
14
+
15
+ # SQL - never string-interpolate
16
+
17
+ - **Never build a query by interpolating/concatenating** an input: no `format!`, template string, f-string, or `+` that injects a value into the SQL - an open door to injection.
18
+ - **Parameterized queries only**: bound placeholders (`$1`, `?`, `:name`) with the values passed separately, or a query builder / ORM that parameterizes for you.
19
+ - **Dynamic identifiers** (table/column names - not parameterizable): validate against an **explicit allowlist**, never interpolate raw input.
20
+ - Same principle for neighboring query languages (NoSQL, LDAP, shell commands): separate code from data, never stitch user input into the command.
@@ -0,0 +1,14 @@
1
+ ---
2
+ version: 1.0.0
3
+ metadata:
4
+ last-reviewed: 2026-06-19
5
+ ---
6
+
7
+ # Secret detection before commit
8
+
9
+ - **No secret ever committed**: API key, token, password, private key, connection credential. A pushed secret is compromised → rotate + purge history, never a plain revert.
10
+ - **Scan the staged diff before every commit**: a dedicated tool when available (`gitleaks protect --staged`), otherwise a grep fallback on common patterns (`AKIA…`, `BEGIN … PRIVATE KEY`, `sk_live_`, `glpat-`, `ghp_`, `password|secret|token\s*[:=]`).
11
+ - **With no tool installed**: the hook warns without blocking; CI (`gitleaks detect`, full repo + history) is the safety net. Never disable the detection CI.
12
+ - **False positive**: one-off exception via a `gitleaks:allow` comment on the line; systemic exception via a `.gitleaks.toml` allowlist (paths or value regex), never by disabling the scan.
13
+ - **If a real secret is detected**: do not commit; move the value to an environment variable / secret manager (a gitignored file). Already committed locally, not pushed → `git reset --soft HEAD~1` then remove it. Already pushed → **immediate rotation** on the provider side + purge (`git filter-repo`).
14
+ - Paired with the `commit-readiness-review` skill (secret-scan step) that orchestrates the pre-commit check.
@@ -0,0 +1,16 @@
1
+ ---
2
+ paths:
3
+ - "**/*.rs"
4
+ - "**/*.ts"
5
+ version: 1.0.0
6
+ metadata:
7
+ last-reviewed: 2026-06-19
8
+ ---
9
+
10
+ # Logging - sensitive data (GDPR)
11
+
12
+ - **Absolute rule**: never log an email, IP, token, hash, or secret in logs/traces (`warn!`, `error!`, `info!`, `console.log`, application logger…)
13
+ - Use non-personal identifiers (`user_id`, `org_id`, `*_id`) instead of the data itself
14
+ - Every new database field must be classified (Public / Internal / Confidential)
15
+
16
+ <!-- Concrete project identifiers, CI lint, and classification policy: to be detailed in a project rule + docs/security. -->
@@ -0,0 +1,18 @@
1
+ ---
2
+ paths:
3
+ - "**/migrations/**/*.sql"
4
+ - "**/migrate/**/*.sql"
5
+ - "**/db/migrate/**/*"
6
+ version: 1.0.0
7
+ metadata:
8
+ last-reviewed: 2026-06-19
9
+ ---
10
+
11
+ # SQL migrations - discipline
12
+
13
+ - **Never modify an already-applied migration**: most tools (SQLx, Flyway, Liquibase, Alembic, Knex…) store a checksum; any change breaks validation. To fix, create a **new** migration (forward-only).
14
+ - **Idempotence**: `IF NOT EXISTS` / `IF EXISTS` on DDL, conditional logic in a block (`DO $$ … $$` in PostgreSQL, equivalent elsewhere).
15
+ - **Table with data in production → two-step migration** (expand-contract): add as *nullable* → backfill → add the constraint (`NOT NULL`, FK…). Never in a single blocking step.
16
+ - **Risky operations** (drop column/table, rename, type change, adding NOT NULL on a populated table): go through expand-contract and a backward-compatible change, not a direct breaking one.
17
+ - **Validate from a clean state** before pushing: replay all migrations on a fresh database, not just the last one.
18
+ - Regenerate compiled query artifacts (prepared queries, generated types) after any change touching queries.
@@ -0,0 +1,22 @@
1
+ ---
2
+ paths:
3
+ - "**/*.ts"
4
+ - "**/*.tsx"
5
+ - "**/*.js"
6
+ - "**/*.jsx"
7
+ - "**/*.vue"
8
+ version: 1.0.0
9
+ metadata:
10
+ last-reviewed: 2026-06-19
11
+ ---
12
+
13
+ # Subscription cleanup
14
+
15
+ Any resource that "subscribes" or registers must have an explicit teardown - otherwise memory leaks, ghost handlers, double execution.
16
+
17
+ - **Observables / streams**: `unsubscribe()`, a completion operator (`takeUntil(destroy$)`, `takeUntilDestroyed()`, `take(1)`), or the `async` pipe / a binding with managed lifecycle. Never a bare `.subscribe(` without one of these.
18
+ - **Listeners**: every `addEventListener` / `on(...)` has a matching removal (`removeEventListener` / `off(...)`) on teardown.
19
+ - **Timers**: every recurring `setInterval` / `setTimeout` is cancelled (`clearInterval` / `clearTimeout`).
20
+ - **Watchers / reactive effects**: keep the handle and stop it, or use a self-managing lifecycle API (`watchEffect`, effect scope).
21
+ - **Cancellable requests / streams**: `AbortController` aborted on teardown or dependency change.
22
+ - Cleanup lives in the end-of-life hook (`onUnmounted`, `ngOnDestroy`, `useEffect` cleanup, `Drop`…), never "later".
@@ -0,0 +1,20 @@
1
+ ---
2
+ paths:
3
+ - "**/*.spec.ts"
4
+ - "**/*.test.ts"
5
+ version: 1.0.0
6
+ metadata:
7
+ last-reviewed: 2026-06-19
8
+ ---
9
+
10
+ # Test discipline
11
+
12
+ - **Zero `waitForTimeout`** - wait for a state/locator, never an arbitrary delay
13
+ - **`data-testid` selectors only** - no bare `text=` nor fragile CSS selector
14
+ - **Scoped** locators (`parent.getByTestId('child')`), no ambiguous global locator
15
+ - **Page objects** for E2E - no selectors scattered across specs
16
+ - **FIRST** principles: Fast, Isolated, Repeatable, Self-validating, Timely
17
+ - Every feature/fix → **UT + E2E + API** tests (deterministic golden dataset)
18
+ - Every bug → one UT test + one E2E confirmation test written **with** the fix
19
+
20
+ <!-- Per-framework specifics (Angular/Jasmine, Vitest, Playwright config…): to go in a project rule, not here. -->
@@ -0,0 +1,23 @@
1
+ ---
2
+ paths:
3
+ - "**/*.tsx"
4
+ - "**/*.jsx"
5
+ - "**/*.vue"
6
+ - "**/*.svelte"
7
+ version: 1.0.0
8
+ metadata:
9
+ last-reviewed: 2026-06-19
10
+ ---
11
+
12
+ # UI states - all handled
13
+
14
+ Any view fed by an async operation handles all four states, each distinguishable (ideally a distinct `data-testid`):
15
+
16
+ - **loading**: visual feedback while waiting - never a frozen screen with no indication.
17
+ - **error**: actionable message + a retry action when possible - never a silent failure nor an infinite spinner.
18
+ - **empty**: explicit empty state (0 results) distinct from loading - not an ambiguous blank page.
19
+ - **success**: the nominal content.
20
+
21
+ - No view stuck on a perpetual spinner if the promise fails: the error must end the loading.
22
+ - States do not overlap (no "loading + error" shown together).
23
+ - Applies to any async building block: page, list, form submission, request-fed widget.
@@ -0,0 +1,53 @@
1
+ #!/usr/bin/env -S npx tsx
2
+ /**
3
+ * Detects subscriptions / listeners / timers without teardown in the staged diff.
4
+ * Read-only. Companion of the subscription-cleanup.md rule.
5
+ *
6
+ * npx tsx subscription-leak-scan.ts # scans `git diff --cached`
7
+ * npx tsx subscription-leak-scan.ts --all # includes unstaged changes
8
+ * npx tsx subscription-leak-scan.ts --strict # exit 1 on leak (CI / pre-commit)
9
+ *
10
+ * Line-by-line heuristic (does not follow a multi-line subscribe): exclude a
11
+ * line with a `leak-scan:allow` comment.
12
+ */
13
+ import { execSync } from "node:child_process";
14
+
15
+ const all = process.argv.includes("--all");
16
+ const strict = process.argv.includes("--strict");
17
+ const range = all ? "HEAD" : "--cached";
18
+
19
+ function sh(cmd: string): string {
20
+ try {
21
+ return execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
22
+ } catch (e) {
23
+ return (e as { stdout?: string }).stdout ?? "";
24
+ }
25
+ }
26
+
27
+ const added = sh(`git diff ${range} -U0`)
28
+ .split("\n")
29
+ .filter((l) => l.startsWith("+") && !l.startsWith("+++"))
30
+ .map((l) => l.slice(1))
31
+ .filter((l) => !/leak-scan:allow/.test(l));
32
+
33
+ const TEARDOWN = /take\(\s*1\s*\)|takeUntil(Destroyed)?\(|\|\s*async\b|firstValueFrom|\.unsubscribe\(/;
34
+
35
+ interface Leak { kind: string; line: string }
36
+ const leaks: Leak[] = [];
37
+ for (const line of added) {
38
+ if (/\.subscribe\(/.test(line) && !TEARDOWN.test(line))
39
+ leaks.push({ kind: "subscribe without teardown", line });
40
+ else if (/addEventListener\(/.test(line))
41
+ leaks.push({ kind: "addEventListener (check removeEventListener)", line });
42
+ else if (/setInterval\(/.test(line))
43
+ leaks.push({ kind: "setInterval (check clearInterval)", line });
44
+ }
45
+
46
+ if (!leaks.length) {
47
+ console.log("✓ No subscription/listener/timer without an apparent teardown in scope.");
48
+ process.exit(0);
49
+ }
50
+ console.log(`⚠ ${leaks.length} potential leak(s) (subscription-cleanup):`);
51
+ for (const l of leaks) console.log(` [${l.kind}] ${l.line.trim()}`);
52
+ console.log("→ Add a teardown, or annotate the line with `leak-scan:allow` if justified.");
53
+ process.exit(strict ? 1 : 0);
@@ -0,0 +1,65 @@
1
+ # `adversarial-feature-challenge`
2
+
3
+ > Deliberately try to break a "done" feature before it ships - because a green golden path proves only that the happy case works.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `feature` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | [`templates/challenge-report.md`](templates/challenge-report.md), [`assets/fuzz-payloads.txt`](assets/fuzz-payloads.txt) |
11
+
12
+ ## What it is
13
+
14
+ `adversarial-feature-challenge` is a **red-team pass** for a feature that has just been declared finished. Instead of confirming that the intended flow works, you adopt the mindset of an attacker, a distracted user, or a screen-reader user and actively try to make the feature fail. Every failure you find is captured with a reproducible proof, ranked by severity, and turned into a ticket before anyone closes the original.
15
+
16
+ ## Why it exists
17
+
18
+ A passing golden path is the weakest possible evidence of quality: it is the one path the author already had in mind. Real defects hide at the edges - double-clicks, expired sessions, another tenant's token, a 10,000-character name, a 500 from an upstream call, a form that is unusable without a mouse.
19
+
20
+ Two failure modes make this skill necessary:
21
+
22
+ 1. **False confidence.** "I couldn't break it" is usually a statement about the challenger, not the feature. The skill treats *0 bugs found* as a signal to change persona and angle, not as a green light.
23
+ 2. **Blind spots.** Engineers instinctively probe backend security and numeric edge cases, but systematically forget UX, accessibility, and non-technical personas. The layer checklist forces those angles.
24
+
25
+ ## When it triggers
26
+
27
+ Invoke it when a feature is "done" and about to be closed, and phrases like these appear:
28
+
29
+ - "is it really ready?" / "find the bugs" / "red team this"
30
+ - a ticket whose only validation is that the golden path passes
31
+ - right before shipping or closing a feature ticket
32
+
33
+ Do **not** use it to prove the intended behavior works in the first place - that is `validating-features-end-to-end` (validate first, challenge afterward). Do **not** use it to grow automated coverage - that is `writing-robust-tests`.
34
+
35
+ ## How it works
36
+
37
+ The protocol is a persona-driven loop, not a single sweep. You adopt a persona, walk every layer of the checklist while injecting the fuzz payloads, and document each flaw with an archivable reproduction before switching persona and going again. Zero findings means the challenge was too shallow, not that the feature is perfect; the loop ends with a verdict and one ticket per confirmed flaw.
38
+
39
+ Full step-by-step protocol → [`SKILL.md`](SKILL.md).
40
+
41
+ ### The fuzz payloads
42
+
43
+ `assets/fuzz-payloads.txt` is a ready-to-inject list (one payload per line, `#` comments) covering SQL injection, XSS, path traversal, Unicode/RTL/Zalgo, numeric boundaries, extreme dates, tricky emails, and malformed IDs. It is designed to be piped into a curl loop against every input the feature exposes.
44
+
45
+ ### Non-negotiable rules
46
+
47
+ - **Trying to break, not validate.** The goal is failure, and finding none is a failure of the challenge.
48
+ - **Every flaw needs an archivable reproduction** - steps plus output. An undocumented flaw is an opinion.
49
+ - **Don't triage away severity on the PO's behalf.** Record cosmetic bugs with their severity; let the owner decide.
50
+
51
+ ## Worked example
52
+
53
+ > A "rename project" feature is declared done. Golden path: type a new name, click Save, the header updates.
54
+
55
+ Adopting the **malicious** persona, you send another tenant's project ID to the rename endpoint with your own token and get a `200` back - a cross-tenant write. You capture the two curl calls and the response body in `templates/challenge-report.md`, mark it **blocking**, and open a ticket.
56
+
57
+ Switching to the **distracted novice** persona on mobile, you double-click Save and the request fires twice, creating a duplicate audit-log entry. Captured, marked **improvement required**, ticketed.
58
+
59
+ Two personas, two flaws, one blocking - the ticket does not get closed.
60
+
61
+ ## Related artifacts
62
+
63
+ - [`validating-features-end-to-end`](../validating-features-end-to-end/) - prove the intended behavior works *before* challenging it.
64
+ - [`writing-robust-tests`](../writing-robust-tests/) - harden coverage once the flaws are known.
65
+ - [`bug-ticket-root-cause`](../bug-ticket-root-cause/) - turn each confirmed flaw into a root-caused ticket.