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,96 @@
1
+ ---
2
+ name: adversarial-feature-challenge
3
+ description: Use when a feature is "done" and needs adversarial stress-testing before shipping - "is it really ready", "est-ce vraiment prêt", "find the bugs", "trouve les bugs", "red team", before closing a ticket whose only validation is the golden path passing.
4
+ version: 1.1.0
5
+ metadata:
6
+ last-reviewed: 2026-07-21
7
+ category: feature
8
+ ---
9
+
10
+ # Adversarial feature challenge
11
+
12
+ > If the current repo has a specific challenge skill (e.g. acme-app → `feature-challenge`), it wins.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: the feature is announced "done", golden path green, and you want to know what breaks before closing the ticket / shipping
17
+ - **`validating-features-end-to-end`** instead if: you first need to prove the intended behavior works (proof before verdict). Validate first, challenge afterward
18
+ - **`writing-robust-tests`** if: the goal is to harden coverage, not to hunt flaws by hand
19
+
20
+ ## Principle
21
+
22
+ - **You try to break, not to validate.** 0 bugs found = a bad challenge, not a perfect feature - start over with another persona
23
+ - **Proof mandatory**: every flaw = a documented reproduction (steps + curl/SQL/screenshot output), no offhand claims
24
+ - The natural reflex covers backend security and edge cases well; **the systematically forgotten angles are UX, accessibility and non-technical personas** - hence the checklist
25
+
26
+ ## Context to gather (before acting)
27
+
28
+ - The ticket/spec: what is the expected behavior and the business limits (thresholds, quotas, roles) to attack
29
+ - How to start the app and call the API (project dev commands) - a challenge without a running app proves nothing
30
+ - Multi-tenant / authorization model: 2 accounts from 2 tenants to test cross-tenant leaks
31
+ - Real surface: endpoints, forms, async jobs touched by the feature
32
+
33
+ ## Protocol
34
+
35
+ 1. **Pick a persona** (table below) and attack the feature from its point of view - don't validate, break
36
+ 2. **Walk the layers**: go through every block of the checklist, inject `assets/fuzz-payloads.txt` into the inputs
37
+ 3. **Document each flaw** in `templates/challenge-report.md`: repro steps + output (curl/SQL/screenshot) + severity
38
+ 4. **Switch persona** and start over - 0 bugs = insufficient challenge, not a perfect feature. **Stopping after one persona is not a challenge**: the first persona finds what you already suspected, the second finds what you did not. Name each persona explicitly in the report as you go, so the count is visible.
39
+ 5. **Verdict + tickets**: one ticket per confirmed flaw, rule blocking / improvement / green-light
40
+
41
+ ## Traps & rationalizations
42
+
43
+ | Excuse | Reality |
44
+ |--------|---------|
45
+ | "Found nothing, it's solid" | 0 bugs = a bad challenge. Switch persona and angle (UX, a11y, non-tech) |
46
+ | "The golden path passes, we're good" | The golden path is exactly what you do NOT challenge. Attack the edges |
47
+ | "This case will never happen in prod" | Double-click, reload mid-flow, 2 tabs: it happens on day 1. Reproduce it |
48
+ | "It's just a cosmetic bug" | Note the severity in the report, don't decide to discard on the PO's behalf |
49
+ | "I describe the flaw, no need to repro" | Without steps + output, it's an opinion. An archivable repro or it doesn't exist |
50
+
51
+ ## Tooling
52
+
53
+ - `templates/challenge-report.md` - full checklist to tick + flaws table + verdict, filled in during the challenge
54
+ - `assets/fuzz-payloads.txt` - ready-to-inject payloads (SQLi, XSS, Unicode, numeric bounds, dates, tricky emails)
55
+
56
+ ## Checklist by layer
57
+
58
+ **UX & interactions**: double-click submit (idempotence), back/reload mid-flow, close while saving, buttons disabled during loading, empty state (0 items), saturated state (10k+), zoom 200%/50%, mobile (touch targets)
59
+
60
+ **Inputs**: empty/null, edge whitespace, Unicode (emoji, RTL), 10,000+ char string, SQL/XSS injection, path traversal, numbers (0, negative, MAX, NaN), extreme dates, IDs (other tenant, nonexistent, malformed)
61
+
62
+ **Auth & multi-tenant**: session expired mid-action, another tenant's token → strict 403/404, shared URL cross-tenant → 404 not 200, role downgrade mid-session, CSRF on destructive actions
63
+
64
+ **Concurrency**: 2 users editing the same object, deletion during edit, business invariants under simultaneous requests
65
+
66
+ **Network & state**: connection drop during submit (retry? idempotence?), high latency, API 500 → degraded UX, 200 payload but empty/malformed
67
+
68
+ **Data**: deletion of a referenced entity (cascade/orphans), modification during a long async process, threshold/quota bounds
69
+
70
+ **Accessibility**: 100% keyboard navigation, visible focus, labels on icon buttons, contrast, screen reader
71
+
72
+ **Observability**: logs on each key action (no PII), metrics, is the error visible in a dashboard?
73
+
74
+ ## Personas to walk through
75
+
76
+ | Persona | Focus |
77
+ |---|---|
78
+ | Distracted novice | Clicks everything, reads nothing, mobile |
79
+ | Power user | Shortcuts, multiple tabs, automation |
80
+ | Malicious | Injection, cross-tenant, rate limit |
81
+ | Blind user | Screen reader, no mouse |
82
+ | Curious dev | DevTools, localStorage, replayed requests |
83
+
84
+ ## Exit condition
85
+
86
+ - [ ] At least 2 personas walked through (one of them non-technical) - **no feature is OK without ≥ 1 challenge round**
87
+ - [ ] Each checklist layer walked or explicitly waived (justified out-of-scope)
88
+ - [ ] Each flaw = archived repro (steps + output) + severity in `templates/challenge-report.md`
89
+ - [ ] One ticket opened per confirmed flaw
90
+ - [ ] Verdict set: blocking / improvement required / green-light
91
+
92
+ ## Changelog
93
+
94
+ - 1.1.0 (2026-07-21) - persona switch made explicit and countable; eval runs showed agents stopping after one
95
+
96
+ - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
@@ -0,0 +1,60 @@
1
+ # Fuzz payloads - one per line (# lines are comments)
2
+ # Typical usage: for p in $(grep -v '^#' fuzz-payloads.txt); do curl -X POST -d "{\"name\":\"$p\"}" ...; done
3
+
4
+ # Empty and boundaries
5
+
6
+ null
7
+ undefined
8
+ whitespace around
9
+
10
+ # SQL injection
11
+ '; DROP TABLE users;--
12
+ ' OR '1'='1
13
+ 1; SELECT pg_sleep(5)--
14
+
15
+ # XSS
16
+ <script>alert(1)</script>
17
+ <img src=x onerror=alert(1)>
18
+ javascript:alert(1)
19
+ "><svg/onload=alert(1)>
20
+
21
+ # Path traversal
22
+ ../../../etc/passwd
23
+ ..%2F..%2F..%2Fetc%2Fpasswd
24
+
25
+ # Unicode / encoding
26
+ 😀🎉👨‍👩‍👧‍👦
27
+ مرحبا بالعالم
28
+ Z̴̢̛a̷l̸g̵o̶
29
+ ﷺ
30
+
31
+
32
+ # Format / type confusion
33
+ 0
34
+ -1
35
+ 9007199254740993
36
+ NaN
37
+ Infinity
38
+ 1e308
39
+ 0x41414141
40
+ true
41
+ []
42
+ {}
43
+
44
+ # Dates
45
+ 1970-01-01T00:00:00Z
46
+ 9999-12-31T23:59:59Z
47
+ 2026-02-30
48
+ 0000-00-00
49
+
50
+ # Tricky emails
51
+ user+tag@example.com
52
+ USER@EXAMPLE.COM
53
+ victim@corp.com%0ABcc:attacker@evil.com
54
+ a@b
55
+ x@example.com.
56
+
57
+ # IDs
58
+ 00000000-0000-0000-0000-000000000000
59
+ not-a-uuid
60
+ \'
@@ -0,0 +1,42 @@
1
+ # Adversarial challenge - <feature> - <YYYY-MM-DD>
2
+
3
+ ## Layers
4
+
5
+ ### UX & interactions
6
+ - [ ] Double-click submit (idempotence) · [ ] Back/reload mid-flow · [ ] Close while saving
7
+ - [ ] Buttons disabled during loading · [ ] Empty state (0) · [ ] Saturated state (10k+) · [ ] Zoom 200%/50% · [ ] Mobile
8
+
9
+ ### Inputs (payloads: assets/fuzz-payloads.txt)
10
+ - [ ] Empty/null · [ ] Edge whitespace · [ ] Unicode/RTL/emoji · [ ] 10,000+ chars
11
+ - [ ] SQLi · [ ] XSS · [ ] Path traversal · [ ] Numbers (0, negative, MAX, NaN) · [ ] Extreme dates
12
+ - [ ] IDs: other tenant, nonexistent, malformed
13
+
14
+ ### Auth & multi-tenant
15
+ - [ ] Session expired mid-action · [ ] Other tenant's token → strict 403/404 · [ ] Cross-tenant URL → 404 not 200
16
+ - [ ] Role downgrade mid-session · [ ] CSRF on destructive actions
17
+
18
+ ### Concurrency
19
+ - [ ] 2 users same object · [ ] Deletion during edit · [ ] Invariants under simultaneous requests
20
+
21
+ ### Network & state
22
+ - [ ] Drop during submit (retry/idempotence) · [ ] High latency · [ ] API 500 → degraded UX · [ ] 200 empty/malformed payload
23
+
24
+ ### Data
25
+ - [ ] Deletion of referenced entity · [ ] Modification during async process · [ ] Threshold/quota bounds
26
+
27
+ ### Accessibility
28
+ - [ ] 100% keyboard · [ ] Visible focus · [ ] Labels on icon buttons · [ ] Contrast · [ ] Screen reader
29
+
30
+ ### Observability
31
+ - [ ] Logs on key actions (no PII) · [ ] Metrics · [ ] Error visible in dashboard
32
+
33
+ ## Personas walked through
34
+ - [ ] Distracted novice (mobile) · [ ] Power user · [ ] Malicious · [ ] Blind user · [ ] Curious dev (DevTools)
35
+
36
+ ## Flaws found
37
+ | # | Flaw | Severity | Repro (steps + proof) | Ticket |
38
+ |---|---|---|---|---|
39
+ | | | | | |
40
+
41
+ ## Verdict
42
+ <blocking / improvement required / green-light> - if 0 flaws: the challenge was insufficient, start over with another persona.
@@ -0,0 +1,62 @@
1
+ # `api-contract-versioning`
2
+
3
+ > Change a network API contract without breaking the consumers you can't redeploy - inventory every consumer, classify each change, and never remove the old shape before the new one has landed everywhere.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `feature` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | [`templates/consumer-inventory.md`](templates/consumer-inventory.md) |
11
+
12
+ ## What it is
13
+
14
+ `api-contract-versioning` is a discipline for **changing a contract that crosses the network** - a REST endpoint, a GraphQL schema, a gRPC `.proto` message, a serialized DTO - when something already consumes it. It forces a full inventory of consumers, an explicit breaking-vs-additive decision per change, and an ordered migration that never leaves the chain in a broken state.
15
+
16
+ ## Why it exists
17
+
18
+ An in-process refactor is safe because the compiler sees every caller. A network contract is the opposite: its consumers are **coupled but out of sight**, and some of them outlive your deployment entirely - an installed mobile app, a third-party partner's integration, a CLI shipped to users' machines.
19
+
20
+ "The frontend compiles" is therefore a trap. It proves the one consumer that happens to live in your build is fine, and says nothing about the ones that will silently break in production the next time they call. This skill replaces that false signal with an explicit inventory, and replaces "we'll remove the old field later" with a dated removal ticket.
21
+
22
+ ## When it triggers
23
+
24
+ Invoke it when an already-consumed contract changes shape:
25
+
26
+ - renaming, removing, or restructuring a request/response field
27
+ - a pagination or envelope change
28
+ - "field X must become …", introducing a breaking change
29
+ - versioning an API or deprecating a field/route
30
+
31
+ It covers REST, GraphQL, and gRPC alike. It does **not** apply to:
32
+
33
+ - an in-process UI component/module API (props, emits, exported signatures) → use `refactoring-shared-component-api`
34
+ - a brand-new endpoint with no existing consumer → nothing to version yet
35
+
36
+ ## How it works
37
+
38
+ The approach is front-loaded on an exhaustive consumer inventory, because every later decision depends on it. From there you classify each change as breaking or additive, apply expand-contract so the old shape never disappears before the new one has landed, cover non-co-deployed consumers with a dated compat shim, then synchronize the chain in order and verify producer and consumers end to end with pasted output.
39
+
40
+ Full step-by-step protocol → [`SKILL.md`](SKILL.md).
41
+
42
+ ### The contract diff is the review
43
+
44
+ When the contract is backed by an artifact (OpenAPI/GraphQL schema, `.proto`, snapshot), its diff *is* the breaking-change review. Regenerating the snapshot without reading the diff silently disables the very guard that would have caught the break - so the skill treats the diff as a mandatory, pasted review artifact.
45
+
46
+ ## Worked example
47
+
48
+ > A `GET /orders` response returns `customer_name`. Product wants it split into `customer.first_name` / `customer.last_name`.
49
+
50
+ 1. **Inventory** - grepping `customer_name` finds it in the web app's mirror types, an E2E fixture, the OpenAPI snapshot, and - critically - a shipped mobile client and a partner webhook payload. The last two do **not** co-deploy.
51
+ 2. **Classify** - removing `customer_name` is breaking for the mobile client and the partner.
52
+ 3. **Expand** - add `customer.first_name` / `customer.last_name` *alongside* the existing `customer_name`.
53
+ 4. **Compat** - keep `customer_name` populated, open a dated removal ticket (`#412`, deadline once mobile adoption > 95%).
54
+ 5. **Sync** - regenerate the OpenAPI snapshot, review and paste the diff, migrate the web app's mirror types and fixtures.
55
+ 6. **Verify** - producer + consumer tests green, snapshot compared in compare mode, E2E green - outputs pasted into the MR via `templates/consumer-inventory.md`.
56
+
57
+ The old field is only removed in a later change, once the ticket's deadline condition is met.
58
+
59
+ ## Related artifacts
60
+
61
+ - [`refactoring-shared-component-api`](../refactoring-shared-component-api/) - the in-process counterpart, for UI component/module APIs.
62
+ - [`recording-decisions`](../recording-decisions/) - record why a field with a mechanical role must be preserved.
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: api-contract-versioning
3
+ description: Use when modifying an API endpoint, schema or contract consumed elsewhere - renaming/removing/restructuring a request or response field, pagination or envelope change, "field X must become", "le champ X doit devenir", introducing a breaking change, versioning an API, or deprecating a field/route. Covers REST, GraphQL and gRPC alike.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: feature
8
+ ---
9
+
10
+ # Versioning a network API contract
11
+
12
+ > If the current repo has a specific skill or conventions for this case (e.g. acme-app → `api-contract-evolution`), they win - they know the project's paths, snapshots and stack.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: a **network** API contract (endpoint, schema, DTO, proto message) already consumed changes shape - REST, GraphQL or gRPC
17
+ - **refactoring-shared-component-api** instead if: it is the API of an **in-process** UI component or module (props/emits/exported signature), not a contract crossing the network
18
+ - New endpoint with no existing consumer: this is not a contract evolution, this skill does not apply
19
+
20
+ ## Principle
21
+
22
+ A network API contract has a chain of consumers that are **coupled and potentially outside your deployment** (installed mobile clients, third-party partners, a distributed CLI). "The frontend compiles" proves nothing about them. The work is done when every consumer family is inventoried and then migrated or covered by a dated compatibility shim.
23
+
24
+ ## Context to gather (before acting)
25
+
26
+ - Is the contract verified by an artifact (OpenAPI/GraphQL schema, `.proto`, contract snapshot)? If so, its diff IS the breaking-change review
27
+ - Which consumers **co-deploy** (monorepo, atomic pipeline) vs **outlive the deployment** (installed apps, third-party clients)? That boundary decides what is allowed to break
28
+ - Build / lint / test commands: read `package.json` / `Cargo.toml` / `Makefile` / CI
29
+
30
+ ## Protocol
31
+
32
+ ```
33
+ - [ ] 1. EXHAUSTIVE inventory of consumers (before any decision)
34
+ - [ ] 2. Classify each change: breaking vs additive
35
+ - [ ] 3. Prefer expand-contract (additive first)
36
+ - [ ] 4. Handle non-co-deployed consumers: compat or dated deprecation
37
+ - [ ] 5. Synchronize the whole chain in order
38
+ - [ ] 6. Verify end to end, contract diff reviewed and pasted
39
+ ```
40
+
41
+ 1. **Inventory** - grep the field/route name across **all** families: client mirror types, adapters/composables, test fixtures & mocks, contract schema/snapshot, distributed clients (CLI, SDK, installed apps), outbound integrations/webhooks to third parties. List each one: this is the migration checklist.
42
+ 2. **Classify** - for each change, breaking (removal/rename/restructuring, tightened type, added required field) or additive (optional field added alongside). Explicit decision, never implicit.
43
+ 3. **Expand-contract** - add the new alongside the old (expand), migrate the consumers, then remove the old (contract) in a second step. Avoids any moment of breakage.
44
+ 4. **Non-co-deployed consumers** - a breaking change for them requires a compat shim (deserialization alias, temporary dual field, new API version/endpoint) **or** a verified tolerance, always with a **removal date tracked in a ticket** - never "we'll remove it later".
45
+ 5. **Chain sync** (order) - contract source of truth (DTO/schema/proto) + persistence if a column → regenerate the contract artifact and **review the diff** → mirror types + client adapters → test fixtures & page objects → distributed clients. A DB schema migration is a change separate from the contract change.
46
+ 6. **Verification** - build + lint + tests of the producer, then of the consumers, then contract comparison (compare mode, not `--update`), finally the touched end-to-end / E2E tests.
47
+
48
+ ## Templates
49
+
50
+ - `templates/consumer-inventory.md` - table of consumer families + status (migrated / dated compat / not affected) to paste into the MR
51
+
52
+ ## Traps & rationalizations
53
+
54
+ | Excuse | Reality |
55
+ |--------|---------|
56
+ | "The frontend compiles, we're good" | Covers neither the distributed CLI, nor installed apps, nor third-party partners, nor snapshots. The inventory is the authority. |
57
+ | "This field is only for display, I'll remove it" | A field with a mechanical role (polling id, pagination cursor) is preserved even if it looks useless to the UI. Read the usage before renaming. |
58
+ | "I regenerate the snapshot/schema and it's fixed" | Regenerating without reviewing the diff disables the contract guard by hiding it. The diff IS the review. |
59
+ | "We'll remove the old field later" | Without a tracked removal date, the compat becomes permanent. Dated ticket mandatory. |
60
+ | "Breaking accepted, everything co-deploys" | Verify: a single installed or third-party client outside the pipeline turns the breaking change into a silent prod break. |
61
+
62
+ ## Exit condition
63
+
64
+ - [ ] Consumer-family inventory done (greps cited), each one listed
65
+ - [ ] Explicit breaking/additive decision per change; expand-contract applied when viable
66
+ - [ ] Non-co-deployed consumers: compat or deprecation with a dated removal ticket
67
+ - [ ] Contract-artifact diff (schema/snapshot) reviewed and pasted into the MR
68
+ - [ ] Chain synchronized; build + lint + tests of producer and consumers run, output pasted - never "it should pass"
69
+
70
+ ## Tooling
71
+
72
+ - `templates/consumer-inventory.md` - consumer migration checklist
73
+
74
+ ## Changelog
75
+
76
+ - 1.0.0 (2026-06-19) - initial release, generalized from the acme-app `api-contract-evolution` workflow (decoupled from a Rust/Axum stack, agnostic across REST/GraphQL/gRPC)
@@ -0,0 +1,29 @@
1
+ # Contract evolution - `<endpoint/schema>`: `<old>` → `<new>`
2
+
3
+ ## Classification
4
+
5
+ - Change type: **breaking** / **additive** (specify per field)
6
+ - Strategy: expand-contract / direct additive / new API version
7
+
8
+ ## Consumer inventory (greps pasted here)
9
+
10
+ | Family | Where searched (grep) | Co-deployed? | Status |
11
+ |---|---|---|---|
12
+ | Client mirror types | | yes / no | migrated / not affected |
13
+ | Adapters / composables | | | |
14
+ | Test fixtures & mocks | | | |
15
+ | Contract schema / snapshot | | - | diff reviewed |
16
+ | Distributed clients (CLI / SDK / installed app) | | **no** | dated compat / verified tolerance |
17
+ | Outbound integrations / webhooks (third party) | | **no** | |
18
+
19
+ ## Compat & deprecation
20
+
21
+ - [ ] Non-co-deployed consumers covered (alias / dual field / new version)
22
+ - [ ] Dated removal ticket: #_____ - deadline _____
23
+
24
+ ## Verifications
25
+
26
+ - [ ] Contract-artifact diff reviewed and pasted
27
+ - [ ] Build + lint + producer tests green
28
+ - [ ] Consumer tests + touched E2E green
29
+ - [ ] Contract comparison in compare mode (not `--update`) green
@@ -0,0 +1,56 @@
1
+ # `audit-architecture`
2
+
3
+ > Score a project's architectural maturity - decisions, resilience, scalability, availability, incident management - across 74 questions and 7 sections, each rated 0-4 with evidence.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (audit protocol) |
8
+ | **Category** | `audit` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | None (evidence-driven grids; shell verification commands inline) |
11
+
12
+ ## What it is
13
+
14
+ `audit-architecture` is a structured maturity assessment for the non-functional backbone of a system: how decisions are recorded, how the software behaves under load, how it survives faults, how fast it recovers, what availability it commits to, and how incidents are run. It walks 7 sections and **74 questions**, assigns each a level from 0 (absent) to 4 (state of the art), and produces a single weighted maturity score.
15
+
16
+ The questions live in progressive-disclosure grids under [`reference/`](reference/) - one file per section - so the LLM only loads the detail for the section it is currently scoring.
17
+
18
+ ## Why it exists
19
+
20
+ Architectural weaknesses are the ones nobody notices until an incident: no rollback path, no RTO, no circuit breaker, no post-mortem discipline. They are invisible in a feature demo and expensive in production. A repeatable, evidence-based grid turns "the architecture feels mature" into a defensible number, with a per-question rationale that survives review and can be re-run later to measure progress.
21
+
22
+ It is deliberately **generic**. A project can ship its own variant under `<repo>/.claude/skills/` that tools this same protocol with repo-specific scripts, datasets and CI gates - that variant wins when present.
23
+
24
+ ## When it triggers
25
+
26
+ Invoke it for a **targeted** audit of this domain, on requests like:
27
+
28
+ - "audit architecture", "audit archi"
29
+ - "audit scalability", "audit availability", "audit resilience", "audit incidents"
30
+ - auditing ADRs, API design, coupling, SLA/RPO/RTO, high availability, or incident management
31
+
32
+ For a **full multi-domain audit**, use [`audit-industrialisation`](../audit-industrialisation/) instead - it orchestrates every audit skill (this one included) and consolidates the results. Do not invoke each audit skill separately.
33
+
34
+ ## How it works
35
+
36
+ The audit first detects the project type (backend/API, frontend SPA/PWA, fullstack, library/SDK), which decides which questions are marked N/A. It then scores each of the 7 sections in order - reading the matching `reference/<section>.md` grid, running the verification commands, and assigning each question a level 0-4 (or N/A) with evidence. The scored levels are averaged (`Σ(levels) / count(scored questions)`, N/A excluded) into a single maturity score, and the results are handed to [`audit-report`](../audit-report/) for the consolidated write-up.
37
+
38
+ Full step-by-step protocol, section grids, and per-type N/A sets → [`SKILL.md`](SKILL.md).
39
+
40
+ ## Worked example
41
+
42
+ > A backend API for `acme-app` is audited. In the PA section the auditor runs the `PA-04` probes:
43
+
44
+ ```bash
45
+ grep -ri "circuit.breaker\|circuitbreaker\|half.open\|resilience4j\|opossum" . --include="*.ts" | head -10
46
+ ```
47
+
48
+ Nothing turns up: there is a global HTTP timeout but no circuit breaker. Per the grid that is **level 1** ("Global timeout but no circuit breaker. Saturation possible."). The auditor records the level, the evidence (the grep found only a timeout config), and a **MUST** recommendation (PA-04 is criticality MUST).
49
+
50
+ `PA-04` had no condition, so it is always scored. Contrast with `AR-01a`, which is skipped as N/A whenever `AR-01 < 2` - no point grading the decision *process* when there are no decisions recorded at all. At the end, all scored levels are summed and divided by the count of scored questions to give `acme-app` its architecture maturity score.
51
+
52
+ ## Related artifacts
53
+
54
+ - [`audit-industrialisation`](../audit-industrialisation/) - the orchestrator; runs all domain audits and consolidates. Use it for a full project audit.
55
+ - [`audit-report`](../audit-report/) - the report template and scoring rules this skill hands its results to.
56
+ - Sibling domain audits: [`audit-ci-cd`](../audit-ci-cd/), [`audit-security`](../audit-security/), [`audit-observability`](../audit-observability/), [`audit-testing`](../audit-testing/), [`audit-quality`](../audit-quality/), [`audit-compliance`](../audit-compliance/).
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: audit-architecture
3
+ description: Audit Architecture, Scalability & Availability. Use when auditing ADRs, interface contracts, coupling, scalability, resilience patterns, SLA/RPO/RTO, high availability, or incident management. Triggers on "audit architecture", "audit archi", "audit scalabilité", "audit scalability", "audit disponibilité", "audit availability", "audit résilience", "audit resilience", "audit incidents".
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: audit
8
+ ---
9
+
10
+ # Audit Architecture, Scalability & Availability
11
+
12
+ > The project variant (`<repo>/.claude/skills/`) wins if it exists: it tools this generic protocol with scripts, datasets and CI gates specific to the repo.
13
+
14
+ ## When ME and not audit-industrialisation
15
+
16
+ - **ME** when: audit targeted at this domain only
17
+ - **audit-industrialisation** instead when: a global multi-domain audit - it orchestrates every audit (ME included) and produces a consolidated report
18
+
19
+ > For a full project audit, use `audit-industrialisation` rather than invoking each skill separately.
20
+
21
+ ## Overview
22
+
23
+ Audit a project's architectural maturity: documented decisions, API stability, coupling, resilience patterns, scalability, availability, operational support and incident management. Produces a maturity score (0-4) per question.
24
+
25
+ **74 questions** split across 7 sections:
26
+
27
+ | Section | Domain | Questions |
28
+ |---------|--------|-----------|
29
+ | AR | Architecture, Specification & Deployment | 11 |
30
+ | SC | Technical scalability | 7 |
31
+ | PA | Fault and interruption tolerance | 15 |
32
+ | RE | Recovery after a problem | 13 |
33
+ | DI | Availability & SLA | 11 |
34
+ | SU | Support & Operability | 8 |
35
+ | IM | Incident management | 9 |
36
+
37
+ The detailed grids (statements, criticality, conditions, verification commands, levels 0-4) live in `reference/` - one file per section.
38
+
39
+ ## Score calculation
40
+
41
+ - Each scored question is assigned a level from 0 to 4.
42
+ - Questions marked **N/A** are excluded from the calculation.
43
+ - **Global score** = sum of levels / number of scored questions (excluding N/A).
44
+ - Formula: `score = Σ(levels) / count(scored questions)`
45
+ - Example: 50 questions scored out of 74, sum = 120 → score = 120/50 = 2.4/4
46
+
47
+ ## Audit protocol
48
+
49
+ 1. **Detect the project type**: backend/API, frontend SPA/PWA, fullstack, library/SDK. Adjust the N/A questions per type (see *Variants* below).
50
+ 2. **For each section** (AR, SC, PA, RE, DI, SU, IM in this order):
51
+ - Read the matching `reference/<section>.md` file.
52
+ - For each question: run the listed **verification commands**.
53
+ - Assign a **level 0-4** (or **N/A**) in light of the grids, with justification and confidence level.
54
+ - Handle the **conditional questions** (e.g. `AR-01a` is only evaluated if `AR-01 >= 2`): if the condition is not met, mark N/A.
55
+ 3. **Mark N/A** the questions that do not apply to the project type.
56
+ 4. **Compute the global score** excluding N/A.
57
+ 5. **Produce the report** via `audit-report`.
58
+
59
+ ### Variants by project type
60
+
61
+ **Frontend SPA/PWA** - adapt:
62
+ - **SC-01 to SC-07**: PWA offline, service worker, bundle size, CDN, lazy loading. No HPA/K8s.
63
+ - **PA-01**: error boundaries (React/Vue), offline fallback, service worker cache, retry on API calls.
64
+ - **PA-06**: service worker lifecycle, graceful update.
65
+ - **PA-12**: offline fallback, stale-while-revalidate, IndexedDB cache.
66
+ - **PA-18 to PA-21**: usually N/A (no frontend DB).
67
+ - **RE-01**: retry safety of client-side API calls.
68
+ - **DI-01 to DI-09**: CDN availability, service worker health, connectivity detection.
69
+ - **IM-01 to IM-09**: error tracking (Sentry), performance monitoring (Web Vitals).
70
+
71
+ **Library / SDK** - usually N/A: SC-01 to SC-07, PA-05 to PA-09, PA-12, PA-18 to PA-21, RE-05 to RE-08a, DI-01 to DI-09, SU-01 to SU-03, IM-01 to IM-09. Focus on **AR-01** (ADR), **AR-02** (tech debt), **AR-07** (backward compatibility), **AR-08** (deprecation), **AR-09** (semver), **PA-01/PA-03** (retry guidance in the docs).
72
+
73
+ **Backend / API** - every question applies with the standard grid.
74
+
75
+ ## Grids by section
76
+
77
+ | Section | File | Description | Questions |
78
+ |---------|------|-------------|-----------|
79
+ | AR | [reference/ar-architecture.md](reference/ar-architecture.md) | ADR, technical debt, multi-level docs, progressive deployment, feature flags, rollback, compatibility, deprecation, semver | 11 |
80
+ | SC | [reference/sc-scalabilite.md](reference/sc-scalabilite.md) | Capacity planning, load testing, auto-scaling, queues/brokers, QoS, partitioning, specialized workers | 7 |
81
+ | PA | [reference/pa-pannes.md](reference/pa-pannes.md) | API error handling, retry, circuit breaker, pause, safe shutdown, recovery, isolation, degraded mode, API watch, DB backup/migration | 15 |
82
+ | RE | [reference/re-recuperation.md](reference/re-recuperation.md) | Idempotency, idempotency key, replay, data rollback, RTO/RPO, restart/recovery tests, recovery validation, reconciliation | 13 |
83
+ | DI | [reference/di-disponibilite.md](reference/di-disponibilite.md) | RPO/RTO, target availability, SLOs/error budget, SLI dashboards, alerts, SLA export, status page, synthetic monitoring | 11 |
84
+ | SU | [reference/su-support.md](reference/su-support.md) | Runbooks, L1/L2/L3 escalation, RACI, install scripts, setup time, onboarding | 8 |
85
+ | IM | [reference/im-incidents.md](reference/im-incidents.md) | P1-P4 classification, on-call, MTTD, MTTR, communication, incident commander, blameless post-mortem, metrics, automation | 9 |
86
+
87
+ ## Exit condition
88
+
89
+ - [ ] All 7 sections have been covered (each `reference/<section>.md` read).
90
+ - [ ] Every question is scored 0-4 or marked N/A (conditional questions included).
91
+ - [ ] Every level rests on evidence from running the verification commands.
92
+ - [ ] Global score computed excluding N/A per the formula.
93
+ - [ ] Report produced via `audit-report` (summary, per-question detail, strengths/weaknesses, MUST/SHOULD/COULD recommendations, non-auditable items).
94
+
95
+ ## Changelog
96
+
97
+ - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition); audit grids in reference/ (progressive disclosure)