tribunal-kit 6.0.0 → 7.0.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 (353) hide show
  1. package/.agent/.manifest.json +78 -0
  2. package/.agent/ARCHITECTURE.md +19 -241
  3. package/.agent/agents/accessibility-reviewer.md +23 -16
  4. package/.agent/agents/ai-code-reviewer.md +25 -21
  5. package/.agent/agents/anti-pattern-reviewer.md +12 -7
  6. package/.agent/agents/api-architect.md +1 -0
  7. package/.agent/agents/backend-specialist.md +23 -22
  8. package/.agent/agents/cloud-engineer.md +1 -0
  9. package/.agent/agents/code-archaeologist.md +1 -0
  10. package/.agent/agents/complexity-reviewer.md +10 -7
  11. package/.agent/agents/database-architect.md +3 -2
  12. package/.agent/agents/db-latency-auditor.md +6 -2
  13. package/.agent/agents/debugger.md +3 -2
  14. package/.agent/agents/dependency-reviewer.md +1 -0
  15. package/.agent/agents/devops-engineer.md +9 -8
  16. package/.agent/agents/documentation-writer.md +6 -5
  17. package/.agent/agents/explorer-agent.md +1 -0
  18. package/.agent/agents/frontend-reviewer.md +21 -17
  19. package/.agent/agents/frontend-specialist.md +23 -20
  20. package/.agent/agents/game-developer.md +1 -0
  21. package/.agent/agents/interaction-reviewer.md +10 -5
  22. package/.agent/agents/logic-reviewer.md +3 -0
  23. package/.agent/agents/minimalist-reviewer.md +6 -0
  24. package/.agent/agents/mobile-developer.md +7 -6
  25. package/.agent/agents/mobile-reviewer.md +14 -13
  26. package/.agent/agents/orchestrator.md +3 -0
  27. package/.agent/agents/penetration-tester.md +1 -0
  28. package/.agent/agents/performance-optimizer.md +6 -5
  29. package/.agent/agents/performance-reviewer.md +6 -6
  30. package/.agent/agents/pipeline-reviewer.md +144 -0
  31. package/.agent/agents/precedence-reviewer.md +1 -0
  32. package/.agent/agents/product-manager.md +1 -0
  33. package/.agent/agents/product-owner.md +1 -0
  34. package/.agent/agents/product-reviewer.md +12 -7
  35. package/.agent/agents/project-planner.md +3 -0
  36. package/.agent/agents/qa-automation-engineer.md +50 -43
  37. package/.agent/agents/resilience-reviewer.md +1 -0
  38. package/.agent/agents/schema-reviewer.md +1 -0
  39. package/.agent/agents/security-auditor.md +24 -24
  40. package/.agent/agents/seo-specialist.md +33 -23
  41. package/.agent/agents/sql-reviewer.md +5 -4
  42. package/.agent/agents/supervisor-agent.md +12 -2
  43. package/.agent/agents/swarm-worker-contracts.md +13 -13
  44. package/.agent/agents/swarm-worker-registry.md +51 -51
  45. package/.agent/agents/system-architect.md +1 -0
  46. package/.agent/agents/test-coverage-reviewer.md +25 -22
  47. package/.agent/agents/test-engineer.md +12 -11
  48. package/.agent/agents/throughput-optimizer.md +45 -40
  49. package/.agent/agents/type-safety-reviewer.md +5 -4
  50. package/.agent/agents/ui-ux-auditor.md +6 -4
  51. package/.agent/agents/ui-visual-auditor.md +3 -0
  52. package/.agent/agents/ux-reviewer.md +11 -6
  53. package/.agent/agents/visual-reviewer.md +11 -6
  54. package/.agent/agents/vitals-reviewer.md +5 -4
  55. package/.agent/history/memory/.memory.idx +3716 -1
  56. package/.agent/history/memory/MEMORY.md +246 -1
  57. package/.agent/mcp_config.json +1 -6
  58. package/.agent/routing_index.json +2034 -263
  59. package/.agent/rules/GEMINI.md +12 -10
  60. package/.agent/rules/GEMINI_PLANNER.md +19 -21
  61. package/.agent/scripts/_colors.js +52 -54
  62. package/.agent/scripts/_utils.js +52 -53
  63. package/.agent/scripts/auto_preview.js +39 -43
  64. package/.agent/scripts/bundle_analyzer.js +47 -60
  65. package/.agent/scripts/case_law_manager.js +200 -294
  66. package/.agent/scripts/checklist.js +73 -94
  67. package/.agent/scripts/cicd_validator.js +305 -0
  68. package/.agent/scripts/compile_router.py +4 -111
  69. package/.agent/scripts/context_broker.js +317 -412
  70. package/.agent/scripts/contract_engine.js +402 -0
  71. package/.agent/scripts/dependency_analyzer.js +112 -124
  72. package/.agent/scripts/graph_builder.js +75 -103
  73. package/.agent/scripts/graph_visualizer.js +10 -12
  74. package/.agent/scripts/graph_zoom.js +38 -55
  75. package/.agent/scripts/guardrail_engine.js +195 -145
  76. package/.agent/scripts/impact_classifier.js +55 -30
  77. package/.agent/scripts/inner_loop_validator.js +108 -159
  78. package/.agent/scripts/integrity_manifest.js +59 -67
  79. package/.agent/scripts/lint_runner.js +65 -75
  80. package/.agent/scripts/marathon_harness.js +131 -208
  81. package/.agent/scripts/migrate_skills_frontmatter.py +4 -63
  82. package/.agent/scripts/minify_context.js +29 -33
  83. package/.agent/scripts/minimal_change_engine.js +95 -87
  84. package/.agent/scripts/mutation_runner.js +46 -62
  85. package/.agent/scripts/pipeline_engine.js +320 -209
  86. package/.agent/scripts/prompt_compiler.js +118 -93
  87. package/.agent/scripts/schema_validator.js +73 -121
  88. package/.agent/scripts/security_scan.js +88 -117
  89. package/.agent/scripts/session_manager.js +52 -69
  90. package/.agent/scripts/signal_detector.js +24 -22
  91. package/.agent/scripts/skill_evolution.js +184 -245
  92. package/.agent/scripts/skill_integrator.js +35 -48
  93. package/.agent/scripts/socratic_gate_policy.js +15 -12
  94. package/.agent/scripts/strengthen_skills.js +29 -33
  95. package/.agent/scripts/swarm_dispatcher.js +120 -151
  96. package/.agent/scripts/test_runner.js +54 -56
  97. package/.agent/scripts/token_budget_broker.js +9 -7
  98. package/.agent/scripts/trace_engine.js +126 -0
  99. package/.agent/scripts/verify_all.js +76 -93
  100. package/.agent/scripts/visual_audit.js +16 -21
  101. package/.agent/skill_topic_map.json +237 -0
  102. package/.agent/skills/12-principles-of-animation/SKILL.md +7 -0
  103. package/.agent/skills/60fps-animation/SKILL.md +7 -0
  104. package/.agent/skills/accessible-animation/SKILL.md +5 -1
  105. package/.agent/skills/adapt/SKILL.md +7 -1
  106. package/.agent/skills/advanced-rag-pipelines/SKILL.md +1 -0
  107. package/.agent/skills/agent-organizer/SKILL.md +1 -0
  108. package/.agent/skills/agentic-patterns/SKILL.md +33 -25
  109. package/.agent/skills/agentic-workflows-2026/SKILL.md +80 -0
  110. package/.agent/skills/ai-app-hardening/SKILL.md +59 -0
  111. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +7 -6
  112. package/.agent/skills/animation-on-scroll/SKILL.md +24 -15
  113. package/.agent/skills/animation-systems/SKILL.md +11 -10
  114. package/.agent/skills/antfu-conventions/SKILL.md +7 -2
  115. package/.agent/skills/api-patterns/SKILL.md +14 -10
  116. package/.agent/skills/api-security-auditor/SKILL.md +15 -14
  117. package/.agent/skills/app-builder/SKILL.md +1 -0
  118. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +2 -2
  119. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +1 -1
  120. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +12 -12
  121. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +3 -3
  122. package/.agent/skills/apple-design/SKILL.md +8 -7
  123. package/.agent/skills/architecture/SKILL.md +3 -2
  124. package/.agent/skills/audit-and-fix/SKILL.md +8 -5
  125. package/.agent/skills/authentication-best-practices/SKILL.md +9 -8
  126. package/.agent/skills/backend-security-expert/SKILL.md +1 -0
  127. package/.agent/skills/baseline-ui/SKILL.md +8 -7
  128. package/.agent/skills/bash-linux/SKILL.md +1 -0
  129. package/.agent/skills/behavioral-modes/SKILL.md +1 -0
  130. package/.agent/skills/better-colors/SKILL.md +11 -7
  131. package/.agent/skills/better-typography/SKILL.md +30 -16
  132. package/.agent/skills/better-ui/SKILL.md +17 -10
  133. package/.agent/skills/bolder/SKILL.md +6 -0
  134. package/.agent/skills/brainstorming/SKILL.md +6 -4
  135. package/.agent/skills/browser-native-ai/SKILL.md +5 -4
  136. package/.agent/skills/build-primitive/SKILL.md +5 -0
  137. package/.agent/skills/building-native-ui/SKILL.md +1 -0
  138. package/.agent/skills/cicd-pro/SKILL.md +2 -1
  139. package/.agent/skills/clarify/SKILL.md +19 -14
  140. package/.agent/skills/clean-code/SKILL.md +16 -15
  141. package/.agent/skills/cloud-architect/SKILL.md +1 -0
  142. package/.agent/skills/cobejs/SKILL.md +7 -9
  143. package/.agent/skills/code-review-checklist/SKILL.md +1 -0
  144. package/.agent/skills/codebase-design/SKILL.md +7 -2
  145. package/.agent/skills/colorize/SKILL.md +8 -3
  146. package/.agent/skills/compact-landing/SKILL.md +8 -3
  147. package/.agent/skills/company-logos/SKILL.md +6 -0
  148. package/.agent/skills/config-validator/SKILL.md +10 -9
  149. package/.agent/skills/containerization-pro/SKILL.md +6 -5
  150. package/.agent/skills/context-engineering-pro/SKILL.md +70 -0
  151. package/.agent/skills/create-design-md/SKILL.md +13 -5
  152. package/.agent/skills/critique/SKILL.md +10 -8
  153. package/.agent/skills/csharp-developer/SKILL.md +1 -0
  154. package/.agent/skills/data-validation-schemas/SKILL.md +28 -23
  155. package/.agent/skills/database-design/SKILL.md +2 -1
  156. package/.agent/skills/delight/SKILL.md +6 -0
  157. package/.agent/skills/deployment-procedures/SKILL.md +2 -1
  158. package/.agent/skills/design-lab/SKILL.md +5 -0
  159. package/.agent/skills/devops-engineer/SKILL.md +3 -2
  160. package/.agent/skills/devops-incident-responder/SKILL.md +2 -1
  161. package/.agent/skills/diagnosing-bugs/SKILL.md +12 -2
  162. package/.agent/skills/distill/SKILL.md +7 -2
  163. package/.agent/skills/documentation-templates/SKILL.md +3 -2
  164. package/.agent/skills/domain-modeling/SKILL.md +12 -4
  165. package/.agent/skills/duckdb-analytical-sql/SKILL.md +59 -0
  166. package/.agent/skills/edge-ai-mobile/SKILL.md +50 -0
  167. package/.agent/skills/edge-computing/SKILL.md +9 -8
  168. package/.agent/skills/emil-design-eng/SKILL.md +43 -27
  169. package/.agent/skills/error-resilience/SKILL.md +34 -16
  170. package/.agent/skills/expo-router-v4/SKILL.md +81 -0
  171. package/.agent/skills/extract-design-system/SKILL.md +12 -11
  172. package/.agent/skills/fabel-protocol/SKILL.md +24 -17
  173. package/.agent/skills/fixing-accessibility/SKILL.md +23 -16
  174. package/.agent/skills/fixing-metadata/SKILL.md +24 -13
  175. package/.agent/skills/fixing-motion-performance/SKILL.md +7 -5
  176. package/.agent/skills/framer-motion-expert/SKILL.md +29 -15
  177. package/.agent/skills/frontend-design/SKILL.md +21 -13
  178. package/.agent/skills/frontend-security-expert/SKILL.md +1 -0
  179. package/.agent/skills/game-design-expert/SKILL.md +1 -0
  180. package/.agent/skills/game-engineering-expert/SKILL.md +1 -0
  181. package/.agent/skills/generative-ui-expert/SKILL.md +3 -2
  182. package/.agent/skills/geo-fundamentals/SKILL.md +2 -1
  183. package/.agent/skills/git-pro/SKILL.md +10 -9
  184. package/.agent/skills/github-operations/SKILL.md +2 -1
  185. package/.agent/skills/gpt-taste/SKILL.md +7 -0
  186. package/.agent/skills/gsap-core/SKILL.md +26 -22
  187. package/.agent/skills/gsap-frameworks/SKILL.md +6 -5
  188. package/.agent/skills/gsap-performance/SKILL.md +4 -3
  189. package/.agent/skills/gsap-plugins/SKILL.md +34 -33
  190. package/.agent/skills/gsap-react/SKILL.md +9 -8
  191. package/.agent/skills/gsap-scrolltrigger/SKILL.md +34 -33
  192. package/.agent/skills/gsap-timeline/SKILL.md +18 -15
  193. package/.agent/skills/gsap-utils/SKILL.md +25 -24
  194. package/.agent/skills/harden/SKILL.md +9 -3
  195. package/.agent/skills/harness-protocol/SKILL.md +1 -0
  196. package/.agent/skills/i18n-localization/SKILL.md +10 -9
  197. package/.agent/skills/impeccable/SKILL.md +5 -0
  198. package/.agent/skills/improve-codebase-architecture/SKILL.md +10 -5
  199. package/.agent/skills/improve-ui/SKILL.md +12 -5
  200. package/.agent/skills/intelligent-routing/SKILL.md +7 -6
  201. package/.agent/skills/knowledge-graph/SKILL.md +1 -0
  202. package/.agent/skills/landing-page/SKILL.md +1 -0
  203. package/.agent/skills/lint-and-validate/SKILL.md +9 -4
  204. package/.agent/skills/llm-engineering/SKILL.md +55 -54
  205. package/.agent/skills/local-first/SKILL.md +20 -19
  206. package/.agent/skills/local-first-architecture/SKILL.md +6 -1
  207. package/.agent/skills/lottie-animation/SKILL.md +7 -3
  208. package/.agent/skills/marquee-loop/SKILL.md +1 -0
  209. package/.agent/skills/masked-reveal/SKILL.md +17 -4
  210. package/.agent/skills/mcp-builder/SKILL.md +13 -10
  211. package/.agent/skills/micro-interaction/SKILL.md +20 -5
  212. package/.agent/skills/mobile-design/SKILL.md +26 -15
  213. package/.agent/skills/monorepo-management/SKILL.md +3 -2
  214. package/.agent/skills/morphing-icons/SKILL.md +16 -6
  215. package/.agent/skills/motion-engineering/SKILL.md +19 -15
  216. package/.agent/skills/nextjs-react-expert/SKILL.md +26 -21
  217. package/.agent/skills/nodejs-best-practices/SKILL.md +89 -76
  218. package/.agent/skills/observability/SKILL.md +45 -44
  219. package/.agent/skills/opentelemetry-observability/SKILL.md +59 -0
  220. package/.agent/skills/page-transition-animation/SKILL.md +6 -3
  221. package/.agent/skills/parallel-agents/SKILL.md +7 -2
  222. package/.agent/skills/performance-profiling/SKILL.md +24 -13
  223. package/.agent/skills/plan-writing/SKILL.md +1 -0
  224. package/.agent/skills/platform-engineer/SKILL.md +3 -2
  225. package/.agent/skills/platform-engineering-opentofu/SKILL.md +68 -0
  226. package/.agent/skills/playwright-ai-e2e/SKILL.md +60 -0
  227. package/.agent/skills/playwright-best-practices/SKILL.md +29 -28
  228. package/.agent/skills/polish/SKILL.md +13 -12
  229. package/.agent/skills/powershell-windows/SKILL.md +1 -0
  230. package/.agent/skills/pricing-page/SKILL.md +8 -3
  231. package/.agent/skills/product-aware-heuristics/SKILL.md +122 -72
  232. package/.agent/skills/progressive-blur/SKILL.md +9 -4
  233. package/.agent/skills/project-idioms/SKILL.md +1 -0
  234. package/.agent/skills/property-based-testing/SKILL.md +58 -0
  235. package/.agent/skills/python-patterns/SKILL.md +1 -0
  236. package/.agent/skills/python-pro/SKILL.md +1 -0
  237. package/.agent/skills/quieter/SKILL.md +6 -0
  238. package/.agent/skills/react-doctor/SKILL.md +6 -0
  239. package/.agent/skills/react-specialist/SKILL.md +32 -28
  240. package/.agent/skills/readme-builder/SKILL.md +1 -0
  241. package/.agent/skills/realtime-patterns/SKILL.md +34 -33
  242. package/.agent/skills/red-team-tactics/SKILL.md +1 -0
  243. package/.agent/skills/redesign-skill/SKILL.md +6 -0
  244. package/.agent/skills/review-animations/SKILL.md +5 -2
  245. package/.agent/skills/review-animations/STANDARDS.md +37 -23
  246. package/.agent/skills/rust-pro/SKILL.md +1 -0
  247. package/.agent/skills/seo-fundamentals/SKILL.md +4 -3
  248. package/.agent/skills/server-management/SKILL.md +1 -0
  249. package/.agent/skills/shadcn-ui-expert/SKILL.md +28 -22
  250. package/.agent/skills/shape/SKILL.md +9 -2
  251. package/.agent/skills/skill-creator/SKILL.md +1 -0
  252. package/.agent/skills/soft-skill/SKILL.md +6 -0
  253. package/.agent/skills/sounds-on-the-web/SKILL.md +1 -0
  254. package/.agent/skills/sql-pro/SKILL.md +1 -0
  255. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +1 -0
  256. package/.agent/skills/svg-animation/SKILL.md +16 -7
  257. package/.agent/skills/swiftui-expert/SKILL.md +1 -0
  258. package/.agent/skills/swiss-design/SKILL.md +5 -0
  259. package/.agent/skills/system-design-pro/SKILL.md +1 -0
  260. package/.agent/skills/systematic-debugging/SKILL.md +1 -0
  261. package/.agent/skills/tailwind-patterns/SKILL.md +25 -11
  262. package/.agent/skills/taste-skill/SKILL.md +6 -0
  263. package/.agent/skills/tdd-workflow/SKILL.md +5 -0
  264. package/.agent/skills/test-result-analyzer/SKILL.md +1 -0
  265. package/.agent/skills/testing-patterns/SKILL.md +123 -115
  266. package/.agent/skills/thermo-nuclear-code-quality-review/SKILL.md +5 -0
  267. package/.agent/skills/thinking-protocol/SKILL.md +3 -0
  268. package/.agent/skills/to-spring-or-not-to-spring/SKILL.md +9 -8
  269. package/.agent/skills/transitions-dev/SKILL.md +19 -6
  270. package/.agent/skills/trend-researcher/SKILL.md +1 -0
  271. package/.agent/skills/typescript-advanced/SKILL.md +23 -18
  272. package/.agent/skills/typeset/SKILL.md +10 -1
  273. package/.agent/skills/ui-reasoning-engine/SKILL.md +67 -48
  274. package/.agent/skills/ui-skill-packs/SKILL.md +6 -1
  275. package/.agent/skills/ui-skills-root/SKILL.md +39 -38
  276. package/.agent/skills/ui-ux-pro-max/SKILL.md +34 -26
  277. package/.agent/skills/ui-ux-researcher/SKILL.md +1 -0
  278. package/.agent/skills/vector-search-pgvector/SKILL.md +78 -0
  279. package/.agent/skills/vue-expert/SKILL.md +22 -19
  280. package/.agent/skills/vulnerability-scanner/SKILL.md +22 -21
  281. package/.agent/skills/web-accessibility-auditor/SKILL.md +2 -1
  282. package/.agent/skills/web-design-guidelines/SKILL.md +16 -10
  283. package/.agent/skills/web-quality-audit/SKILL.md +5 -0
  284. package/.agent/skills/webapp-testing/SKILL.md +14 -13
  285. package/.agent/skills/webgpu-performance/SKILL.md +1 -0
  286. package/.agent/skills/whimsy-injector/SKILL.md +9 -5
  287. package/.agent/skills/workflow-optimizer/SKILL.md +1 -0
  288. package/.agent/skills/zero-trust-passkeys/SKILL.md +90 -0
  289. package/.agent/templates/DESIGN.md +119 -110
  290. package/.agent/templates/design-tokens.json +9 -6
  291. package/.agent/workflows/acf.md +1 -0
  292. package/.agent/workflows/api-tester.md +1 -0
  293. package/.agent/workflows/audit.md +1 -0
  294. package/.agent/workflows/brainstorm.md +1 -0
  295. package/.agent/workflows/changelog.md +1 -0
  296. package/.agent/workflows/contract.md +60 -0
  297. package/.agent/workflows/create.md +1 -0
  298. package/.agent/workflows/debug.md +1 -0
  299. package/.agent/workflows/deploy.md +1 -0
  300. package/.agent/workflows/enhance.md +1 -0
  301. package/.agent/workflows/fix-ci.md +89 -0
  302. package/.agent/workflows/fix.md +1 -0
  303. package/.agent/workflows/generate.md +1 -0
  304. package/.agent/workflows/marathon.md +1 -0
  305. package/.agent/workflows/migrate.md +1 -0
  306. package/.agent/workflows/minimal.md +9 -7
  307. package/.agent/workflows/orchestrate.md +1 -0
  308. package/.agent/workflows/performance-benchmarker.md +1 -0
  309. package/.agent/workflows/pipeline.md +26 -21
  310. package/.agent/workflows/plan.md +1 -0
  311. package/.agent/workflows/preview.md +1 -0
  312. package/.agent/workflows/refactor.md +3 -2
  313. package/.agent/workflows/review-ai.md +4 -3
  314. package/.agent/workflows/review.md +1 -0
  315. package/.agent/workflows/session.md +1 -0
  316. package/.agent/workflows/status.md +1 -0
  317. package/.agent/workflows/strengthen-skills.md +1 -0
  318. package/.agent/workflows/super-prompt.md +1 -0
  319. package/.agent/workflows/swarm.md +15 -3
  320. package/.agent/workflows/test.md +8 -7
  321. package/.agent/workflows/tribunal-backend.md +3 -2
  322. package/.agent/workflows/tribunal-cicd.md +104 -0
  323. package/.agent/workflows/tribunal-database.md +1 -0
  324. package/.agent/workflows/tribunal-frontend.md +8 -6
  325. package/.agent/workflows/tribunal-full.md +15 -14
  326. package/.agent/workflows/tribunal-mobile.md +6 -5
  327. package/.agent/workflows/tribunal-performance.md +1 -0
  328. package/.agent/workflows/tribunal-speed.md +1 -0
  329. package/.agent/workflows/tribunal-ui.md +29 -21
  330. package/.agent/workflows/ui-ux-pro-max.md +19 -15
  331. package/CONTRIBUTING.md +3 -3
  332. package/README.md +160 -88
  333. package/SECURITY.md +11 -11
  334. package/bin/mcp-server.js +512 -233
  335. package/bin/tribunal-kit.js +29 -30
  336. package/bin/wrapper.js +45 -48
  337. package/dist/cli.js +26 -0
  338. package/dist/commands/case.js +2 -0
  339. package/dist/commands/contract.js +440 -0
  340. package/dist/commands/memory.js +3 -2
  341. package/dist/commands/native.js +36 -0
  342. package/dist/commands/status.js +6 -0
  343. package/dist/esm/index.mjs +32 -0
  344. package/dist/index.d.ts +58 -3
  345. package/package.json +20 -16
  346. package/scripts/benchmark.js +62 -86
  347. package/scripts/changelog.js +67 -73
  348. package/scripts/fix-vbc.js +13 -15
  349. package/scripts/fix-vbc.ps1 +2 -118
  350. package/scripts/stress_benchmark.js +358 -0
  351. package/scripts/sync-version.js +71 -41
  352. package/scripts/validate-payload.js +23 -30
  353. package/scripts/visual_audit.js +23 -13
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before attempting bug diagnostics or proposing code fixes, you MUST inspect:
23
+
23
24
  1. Red-Capable Feedback Loop Rule (Section 34) → Construct a fast, deterministic, automated feedback loop command that reproduces the bug (goes red) BEFORE making code edits
24
25
  2. Falsifiable Hypotheses Formulation (Section 107) → Formulate 3–5 falsifiable hypotheses (`"If X is cause, then Y prediction"`) before testing any single theory
25
26
  3. Tagged Debug Logging & Cleanup (Section 123) → Tag debug log instrumentation (`[DEBUG-id]`) and sweep clean before finalizing regression fixes
@@ -66,6 +67,7 @@ Build the right feedback loop, and the bug is 90% fixed.
66
67
  ### Tighten the Loop
67
68
 
68
69
  Treat the loop as a product. Once you have a loop, tighten it:
70
+
69
71
  - **Can I make it faster?** (Cache setup, skip unrelated init, narrow the test scope.)
70
72
  - **Can I make the signal sharper?** (Assert on the specific symptom, not "didn't crash".)
71
73
  - **Can I make it more deterministic?** (Pin time, seed RNG, isolate filesystem, freeze network.)
@@ -79,21 +81,23 @@ The goal is not a clean repro but a higher reproduction rate. Loop the trigger 1
79
81
  ### When You Genuinely Cannot Build a Loop
80
82
 
81
83
  Stop and say so explicitly. List what you tried. Ask the user for:
84
+
82
85
  1. Access to whatever environment reproduces it.
83
86
  2. A captured artifact (HAR file, log dump, core dump, screen recording with timestamps).
84
87
  3. Permission to add temporary production instrumentation.
85
88
 
86
- *Do not proceed to hypothesise without a loop.*
89
+ _Do not proceed to hypothesise without a loop._
87
90
 
88
91
  ### Phase 1 Completion Criterion — A Tight Loop That Goes Red
89
92
 
90
93
  Phase 1 is done when the loop is tight and red-capable: you can name **one command** — a script path, a test invocation, a curl — that you have already run at least once (paste the invocation and its output), and that is:
94
+
91
95
  - ✅ **Red-capable**: Drives the actual bug code path and asserts the user's exact symptom, going red on this bug and green once fixed. Not "runs without erroring" — it must catch this specific bug.
92
96
  - ✅ **Deterministic**: Same verdict every run (or high, pinned reproduction rate).
93
97
  - ✅ **Fast**: Seconds, not minutes.
94
98
  - ✅ **Agent-runnable**: Runnable unattended (HITL only via `scripts/hitl-loop.template.sh`).
95
99
 
96
- *If you catch yourself reading code to build a theory before this command exists, stop. No red-capable command, no Phase 2.*
100
+ _If you catch yourself reading code to build a theory before this command exists, stop. No red-capable command, no Phase 2._
97
101
 
98
102
  ---
99
103
 
@@ -102,11 +106,13 @@ Phase 1 is done when the loop is tight and red-capable: you can name **one comma
102
106
  Run the loop. Watch it go red — the bug appears.
103
107
 
104
108
  ### Confirm
109
+
105
110
  1. The loop produces the failure mode the user described — not a different failure nearby. (Wrong bug = wrong fix.)
106
111
  2. The failure is reproducible across multiple runs (or at a high enough reproduction rate).
107
112
  3. You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix addresses it.
108
113
 
109
114
  ### Minimise
115
+
110
116
  Once it's red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, data, and steps one at a time, re-running the loop after each cut — keep only what's load-bearing for the failure.
111
117
 
112
118
  > 🎯 **Why bother**: A minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
@@ -134,6 +140,7 @@ Show the ranked list to the user before testing. (Proceed with your ranking if t
134
140
  Each probe must map to a specific prediction from Phase 3. Change one variable at a time.
135
141
 
136
142
  ### Tool Preference
143
+
137
144
  1. **Debugger / REPL Inspection**: If the environment supports it. One breakpoint beats ten logs.
138
145
  2. **Targeted Logs**: Place logs at boundaries that distinguish hypotheses. Never "log everything and grep".
139
146
  3. **Tag Every Debug Log**: Prefix every debug log with a unique tag, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep.
@@ -150,6 +157,7 @@ A correct seam is one where the test exercises the real bug pattern as it occurs
150
157
  If no correct seam exists, note it. The codebase architecture is preventing the bug from being locked down. Flag this for Phase 6.
151
158
 
152
159
  ### If a Correct Seam Exists:
160
+
153
161
  1. Turn the minimised repro into a failing test at that seam.
154
162
  2. Watch it fail.
155
163
  3. Apply the fix.
@@ -161,6 +169,7 @@ If no correct seam exists, note it. The codebase architecture is preventing the
161
169
  ## Phase 6 — Cleanup + Post-Mortem
162
170
 
163
171
  ### Required Before Declaring Done
172
+
164
173
  - [ ] Original repro no longer reproduces (re-run Phase 1 loop)
165
174
  - [ ] Regression test passes (or absence of seam is documented)
166
175
  - [ ] All `[DEBUG-...]` instrumentation removed (grep the prefix)
@@ -168,6 +177,7 @@ If no correct seam exists, note it. The codebase architecture is preventing the
168
177
  - [ ] Correct hypothesis stated in commit / PR message
169
178
 
170
179
  ### Post-Mortem Handoff
180
+
171
181
  Ask: **What would have prevented this bug?** If the answer involves architectural debt (no good test seam, tangled callers, hidden coupling), hand off to `/improve-codebase-architecture` with specific findings.
172
182
 
173
183
  ---
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before decluttering UI layouts, you MUST inspect:
23
+
23
24
  1. Active screen components → Identify core primary user task and secondary/tertiary options
24
25
  2. Container Reduction rules (Section 25) → Replace nested card containers and redundant borders with whitespace grid gaps
25
26
  3. Progressive Disclosure patterns (Section 30) → Move advanced parameters into collapsible accordions or popovers
@@ -31,18 +32,22 @@ Systematically strip away visual clutter, redundant controls, and cognitive fric
31
32
  ## The 4 Distillation Steps
32
33
 
33
34
  ### 1. Identify & Remove Visual Noise
35
+
34
36
  - **Container Reduction**: Eliminate unnecessary nested cards, boxes inside boxes, and decorative borders. Use whitespace instead of lines to separate content blocks.
35
37
  - **Icon Pruning**: Remove decorative icons that restate obvious text labels (e.g. an envelope icon next to a button that clearly says "Send Email").
36
38
 
37
39
  ### 2. Collapse Secondary Actions
40
+
38
41
  - **Primary vs Overflow**: Keep only 1 primary action button and max 1 secondary button visible. Hide tertiary actions inside an overflow dropdown (`...` menu).
39
42
  - **Progressive Disclosure**: Hide advanced settings or non-essential controls behind an "Advanced Settings" accordion or popover.
40
43
 
41
44
  ### 3. Trim Copy & Microcopy
42
- - **Cut Conversational Filler**: Strip verbose instructions. Change *"Please fill out the form below to register your account"* to *"Create account"*.
43
- - **Shorten Button Labels**: Change *"Click here to update your profile settings"* to *"Save profile"*.
45
+
46
+ - **Cut Conversational Filler**: Strip verbose instructions. Change _"Please fill out the form below to register your account"_ to _"Create account"_.
47
+ - **Shorten Button Labels**: Change _"Click here to update your profile settings"_ to _"Save profile"_.
44
48
 
45
49
  ### 4. Group Related Fields
50
+
46
51
  - **Consolidate Form Inputs**: Merge separate "First Name" and "Last Name" fields into "Full Name" if separate values aren't strictly required. Merge city/state/zip into single address lookup where possible.
47
52
 
48
53
  ---
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before creating or editing documentation, API references, or comments, you MUST inspect:
23
+
23
24
  1. Target Audience Identification (Section 27) → Match template strictly to audience (README for 10-min quickstart, API docs for payload contracts, Runbook for on-call triage)
24
25
  2. Explain "Why", Not "What" in Code Comments (Section 147) → Document non-obvious business rules or bug workarounds; ban restating obvious code syntax
25
26
  3. AI-Friendly Documentation Mapping (Section 171) → Maintain `ARCHITECTURE.md` and `@purpose:` annotations for codebase mental models and automated ingestion
@@ -149,8 +150,8 @@ Creates a new user account.
149
150
  **Example**
150
151
  \`\`\`bash
151
152
  curl -X POST /api/users \
152
- -H "Content-Type: application/json" \
153
- -d '{"email": "user@example.com", "name": "Jane"}'
153
+ -H "Content-Type: application/json" \
154
+ -d '{"email": "user@example.com", "name": "Jane"}'
154
155
  \`\`\`
155
156
  ```
156
157
 
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before designing domain entities or business modeling, you MUST inspect:
23
+
23
24
  1. Ubiquitous Language Uniformity (Section 25) → Standardize 1 explicit term across UI, code, and DB (e.g. Customer vs User); ban interchangeable synonyms
24
25
  2. Bounded Context Separation (Section 30) → Isolate models per context (e.g. Inventory Product vs Catalog Product); ban 60-column monolithic entities
25
26
  3. Aggregate Root Invariants (Section 34) → Mutate child entities strictly through Aggregate Root methods (`order.addItem(...)`); ban direct child mutations
@@ -33,30 +34,37 @@ Model business domain concepts cleanly before committing to database schemas or
33
34
  ## 4 Domain Modeling Rules
34
35
 
35
36
  ### 1. Establish Ubiquitous Language
37
+
36
38
  - Agree on strict, unambiguous terms used identically across domain experts, code variable names, database tables, and UI copy.
37
- - ❌ *User*, *Account*, *Member*, *Client* used interchangeably for the same concept.
39
+ - ❌ _User_, _Account_, _Member_, _Client_ used interchangeably for the same concept.
38
40
  - ✅ Define 1 clear term: **Customer** (for billing context) vs **User** (for authentication context).
39
41
 
40
42
  ### 2. Define Bounded Contexts
41
- - Separate large systems into distinct bounded contexts. An entity named `Product` in the *Inventory Context* (stock level, warehouse bin) has different attributes than `Product` in the *Catalog Context* (hero image, pricing).
43
+
44
+ - Separate large systems into distinct bounded contexts. An entity named `Product` in the _Inventory Context_ (stock level, warehouse bin) has different attributes than `Product` in the _Catalog Context_ (hero image, pricing).
42
45
 
43
46
  ### 3. Aggregates & Invariants
47
+
44
48
  - An **Aggregate Root** (e.g. `Order`) enforces internal business invariants across child entities (`OrderItem`).
45
49
  - Never mutate a child entity (`OrderItem`) directly without passing through the aggregate root method (`order.addItem(product, qty)`).
46
50
 
47
51
  ### 4. Value Objects Over Primitives
52
+
48
53
  - Wrap primitives into type-safe Value Objects to enforce validation logic:
54
+
49
55
  ```typescript
50
56
  // Value Object enforcing domain rule
51
57
  export class EmailAddress {
52
58
  private readonly value: string;
53
59
 
54
60
  constructor(email: string) {
55
- if (!email.includes("@")) throw new Error("Invalid email domain");
61
+ if (!email.includes('@')) throw new Error('Invalid email domain');
56
62
  this.value = email.toLowerCase().trim();
57
63
  }
58
64
 
59
- public toString(): string { return this.value; }
65
+ public toString(): string {
66
+ return this.value;
67
+ }
60
68
  }
61
69
  ```
62
70
 
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: duckdb-analytical-sql
3
+ description: Embedded OLAP analytics, high-speed Parquet/JSON processing, in-memory analytical SQL, and DuckDB integrations in Node.js, Python, and WASM.
4
+ tools: Read, Grep, Glob, Edit, Write
5
+ version: 3.0.0
6
+ last-updated: 2026-08-05
7
+ script: .agent/scripts/schema_validator.js
8
+ scripts-binding:
9
+ - .agent/scripts/schema_validator.js
10
+ skills:
11
+ - sql-pro
12
+ - database-design
13
+ - performance-profiling
14
+ ---
15
+
16
+ # DuckDB Analytical SQL — Embedded Analytics
17
+
18
+ ## Mandatory Pre-Flight Context Inspection
19
+
20
+ Before writing analytical queries:
21
+
22
+ 1. Direct File Querying → Query Parquet/CSV/JSON directly without importing into a traditional DB
23
+ 2. Memory Allocation → Set explicit memory limit (`SET max_memory = '4GB'`) to prevent OOM
24
+ 3. Vectorized Engine Usage → Use column-oriented aggregation over line-by-line loops
25
+
26
+ ## Node.js DuckDB Parquet Query Pattern
27
+
28
+ ```typescript
29
+ import { Database } from 'duckdb-async';
30
+
31
+ export async function runAnalyticalReport(parquetGlobPath: string) {
32
+ const db = await Database.create(':memory:');
33
+
34
+ // Set memory limits for embedded execution
35
+ await db.exec("SET max_memory = '2GB'; SET threads = 4;");
36
+
37
+ const rows = await db.all(
38
+ `
39
+ SELECT
40
+ date_trunc('day', timestamp) as event_day,
41
+ event_type,
42
+ COUNT(*) as total_count,
43
+ QUANTILE_CONT(duration_ms, 0.95) as p95_latency
44
+ FROM read_parquet(?)
45
+ GROUP BY 1, 2
46
+ ORDER BY 1 DESC
47
+ LIMIT 100
48
+ `,
49
+ [parquetGlobPath],
50
+ );
51
+
52
+ return rows;
53
+ }
54
+ ```
55
+
56
+ ## 🛑 Verification-Before-Completion (VBC) Protocol
57
+
58
+ - Verify query execution on sample Parquet dataset without loading entire file into RAM.
59
+ - Benchmark query throughput against memory constraints.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: edge-ai-mobile
3
+ description: On-device mobile AI, CoreML, Android NNAPI, ONNX Runtime Web/Mobile, local LLM execution (SLMs), and sub-10ms privacy-first edge inference.
4
+ tools: Read, Grep, Glob, Edit, Write
5
+ version: 3.0.0
6
+ last-updated: 2026-08-05
7
+ script: .agent/scripts/bundle_analyzer.js
8
+ scripts-binding:
9
+ - .agent/scripts/bundle_analyzer.js
10
+ skills:
11
+ - mobile-developer
12
+ - browser-native-ai
13
+ - performance-profiling
14
+ ---
15
+
16
+ # Edge AI & On-Device Mobile Machine Learning
17
+
18
+ ## Mandatory Pre-Flight Context Inspection
19
+
20
+ Before deploying on-device AI models:
21
+
22
+ 1. Model Quantization → Use 4-bit/8-bit quantized models (GGUF/ONNX) to fit mobile RAM budgets (<500MB)
23
+ 2. Hardware Acceleration → Bind inference engine to Apple Neural Engine (ANE) or Android NPU
24
+ 3. Fallback Mechanism → Fall back gracefully to cloud LLM API if local inference exceeds latency budget (>200ms)
25
+
26
+ ## Mobile ONNX Edge Inference Pattern
27
+
28
+ ```typescript
29
+ import * as ort from 'onnxruntime-react-native';
30
+
31
+ export async function runLocalEmbeddings(textTokens: number[]): Promise<Float32Array> {
32
+ const session = await ort.InferenceSession.create('model_quantized.onnx', {
33
+ executionProviders: ['cpu'], // Accelerates via ANE/NNAPI internally
34
+ });
35
+
36
+ const tensor = new ort.Tensor('int64', new BigInt64Array(textTokens.map(BigInt)), [
37
+ 1,
38
+ textTokens.length,
39
+ ]);
40
+ const feeds = { input_ids: tensor };
41
+
42
+ const results = await session.run(feeds);
43
+ return results.embedding.data as Float32Array;
44
+ }
45
+ ```
46
+
47
+ ## 🛑 Verification-Before-Completion (VBC) Protocol
48
+
49
+ - Verify local memory usage remains under 300MB during active model inference.
50
+ - Measure battery consumption impact.
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before engineering edge computing handlers or Cloudflare Workers, you MUST inspect:
23
+
23
24
  1. Edge Runtime Restrictions (Section 25) → Strictly ban Node.js native core modules (`fs`, `child_process`, native `bcrypt`); use Web APIs (`fetch`, `crypto.subtle`)
24
25
  2. Stale-While-Revalidate Caching (Section 47) → Use `Cache-Control: s-maxage=60, stale-while-revalidate=86400` and asynchronous `ctx.waitUntil()` cache puts
25
26
  3. Edge Database Access (Section 81) → Never open direct raw TCP connections to DBs; use HTTP connection poolers (Prisma Accelerate, LibSQL, Supabase Pooler)
@@ -48,11 +49,11 @@ Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standar
48
49
 
49
50
  ```typescript
50
51
  // ❌ BAD: Attempting to use Node native core modules
51
- import fs from "fs";
52
- import bcrypt from "bcrypt"; // Has C++ bindings, will instantly crash on V8 edge
52
+ import fs from 'fs';
53
+ import bcrypt from 'bcrypt'; // Has C++ bindings, will instantly crash on V8 edge
53
54
 
54
55
  // ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
55
- const hashBuffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(password));
56
+ const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(password));
56
57
  ```
57
58
 
58
59
  ---
@@ -79,7 +80,7 @@ export default {
79
80
  // Instructs the Edge CDN: Serve the stale version instantly to the user,
80
81
  // but fire an async request in the background to update the cache for the next user.
81
82
  response = new Response(response.body, response);
82
- response.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=86400");
83
+ response.headers.set('Cache-Control', 's-maxage=60, stale-while-revalidate=86400');
83
84
 
84
85
  // 4. Store in Cache asynchronously (do not block the user response)
85
86
  ctx.waitUntil(cache.put(request, response.clone()));
@@ -104,14 +105,14 @@ Running logic globally while querying a monolithic database in `us-east-1` is co
104
105
 
105
106
  ```typescript
106
107
  // ✅ Turso / LibSQL (Distributed Edge DB) usage:
107
- import { createClient } from "@libsql/client/web";
108
+ import { createClient } from '@libsql/client/web';
108
109
 
109
110
  const client = createClient({
110
111
  url: env.TURSO_DATABASE_URL,
111
112
  authToken: env.TURSO_AUTH_TOKEN,
112
113
  });
113
114
 
114
- const result = await client.execute("SELECT * FROM users WHERE id = ?", [userId]);
115
+ const result = await client.execute('SELECT * FROM users WHERE id = ?', [userId]);
115
116
  ```
116
117
 
117
118
  ---
@@ -137,9 +138,9 @@ export class ChatRoom {
137
138
  pair.server.accept();
138
139
 
139
140
  // Handle incoming Chat messages
140
- pair.server.addEventListener("message", (msg) => {
141
+ pair.server.addEventListener('message', msg => {
141
142
  // Broadcast to all other connected edge users
142
- this.sessions.forEach((session) => session.send(msg.data));
143
+ this.sessions.forEach(session => session.send(msg.data));
143
144
  });
144
145
 
145
146
  return new Response(null, { status: 101, webSocket: pair.client });
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before designing or reviewing UI micro-animations, you MUST inspect:
23
+
23
24
  1. Frequency Gate (Section 54) → Never animate keyboard actions or high-frequency controls (100+ times/day); keep UI animations under 300ms
24
25
  2. Easing Rule (Section 75) → Use strong `ease-out` (`cubic-bezier(0.23, 1, 0.32, 1)`) for entering UI elements; ban `ease-in`
25
26
  3. Origin-Aware Popovers (Section 114) → Never animate scale from `scale(0)`; start at `scale(0.95)` with origin bound to trigger coordinates
@@ -35,44 +36,50 @@ You are a design engineer with the craft sensibility. You build interfaces where
35
36
  ## Core Philosophy
36
37
 
37
38
  ### Taste is trained, not innate
39
+
38
40
  Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. Develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.
39
41
 
40
42
  ### Unseen details compound
43
+
41
44
  Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. Every decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.
42
45
 
43
46
  ### Beauty is leverage
47
+
44
48
  People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Use beauty as leverage to stand out.
45
49
 
46
50
  ## Review Format (Required)
47
51
 
48
52
  When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:
49
53
 
50
- | Before | After | Why |
51
- | --- | --- | --- |
52
- | `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
53
- | `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
54
- | `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
55
- | No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
56
- | `transform-origin: center` | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger |
54
+ | Before | After | Why |
55
+ | ---------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------- |
56
+ | `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
57
+ | `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
58
+ | `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
59
+ | No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
60
+ | `transform-origin: center` | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger |
57
61
 
58
62
  ## The Animation Decision Framework
59
63
 
60
64
  Before writing any animation code, answer these questions in order:
61
65
 
62
66
  ### 1. Should this animate at all?
67
+
63
68
  **Ask:** How often will users see this animation?
64
69
 
65
- | Frequency | Decision |
66
- | --- | --- |
67
- | 100+ times/day (keyboard shortcuts, command palette) | No animation. Ever. |
68
- | Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
69
- | Occasional (modals, drawers, toasts) | Standard animation |
70
- | Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight |
70
+ | Frequency | Decision |
71
+ | ---------------------------------------------------------- | ---------------------------- |
72
+ | 100+ times/day (keyboard shortcuts, command palette) | No animation. Ever. |
73
+ | Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
74
+ | Occasional (modals, drawers, toasts) | Standard animation |
75
+ | Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight |
71
76
 
72
77
  **Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow and disconnected.
73
78
 
74
79
  ### 2. What is the purpose?
80
+
75
81
  Valid purposes:
82
+
76
83
  - **Spatial consistency**: toast enters/exits from the same direction.
77
84
  - **State indication**: a morphing feedback button shows state change.
78
85
  - **Explanation**: a marketing animation showing a feature.
@@ -82,45 +89,52 @@ Valid purposes:
82
89
  If the purpose is just "it looks cool" and the user sees it often, don't animate.
83
90
 
84
91
  ### 3. What easing should it use?
92
+
85
93
  Is the element entering or exiting?
86
- Yes → ease-out (starts fast, feels responsive)
87
- No →
88
- Is it moving/morphing on screen?
89
- Yes → ease-in-out (natural acceleration/deceleration)
90
- Is it a hover/color change?
91
- Yes → ease
92
- Is it constant motion?
93
- Yes → linear
94
- Default → ease-out
94
+ Yes → ease-out (starts fast, feels responsive)
95
+ No →
96
+ Is it moving/morphing on screen?
97
+ Yes → ease-in-out (natural acceleration/deceleration)
98
+ Is it a hover/color change?
99
+ Yes → ease
100
+ Is it constant motion?
101
+ Yes → linear
102
+ Default → ease-out
95
103
 
96
104
  **Critical: use custom easing curves.**
105
+
97
106
  ```css
98
107
  /* Strong ease-out for UI interactions */
99
108
  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
100
109
  /* Strong ease-in-out for on-screen movement */
101
110
  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
102
111
  ```
112
+
103
113
  **Never use ease-in for UI animations.** It makes the interface feel sluggish.
104
114
 
105
115
  ### 4. How fast should it be?
106
- | Element | Duration |
107
- | --- | --- |
108
- | Button press feedback | 100-160ms |
116
+
117
+ | Element | Duration |
118
+ | ------------------------ | --------- |
119
+ | Button press feedback | 100-160ms |
109
120
  | Tooltips, small popovers | 125-200ms |
110
- | Dropdowns, selects | 150-250ms |
111
- | Modals, drawers | 200-500ms |
121
+ | Dropdowns, selects | 150-250ms |
122
+ | Modals, drawers | 200-500ms |
112
123
 
113
124
  **Rule: UI animations should stay under 300ms.** Perception of speed matters as much as actual speed.
114
125
 
115
126
  ## Component Building Principles
116
127
 
117
128
  ### Buttons must feel responsive
129
+
118
130
  Add `transform: scale(0.97)` on `:active` with subtle transition (160ms ease-out).
119
131
 
120
132
  ### Never animate from scale(0)
133
+
121
134
  Start from `scale(0.95)` or higher combined with opacity.
122
135
 
123
136
  ### Make popovers origin-aware
137
+
124
138
  Popovers should scale in from their trigger, not from center. Explicitly set `transform-origin` to the trigger coordinates (e.g., `var(--radix-popover-content-transform-origin)`). Modals are exempt as they are viewport-centered.
125
139
 
126
140
  ---
@@ -141,6 +155,7 @@ Popovers should scale in from their trigger, not from center. Explicitly set `tr
141
155
  ### ✅ Pre-Flight Self-Audit
142
156
 
143
157
  Review these questions before confirming output:
158
+
144
159
  ```
145
160
  ✅ Did I justify the animation's existence based on frequency?
146
161
  ✅ Are all UI animations under 300ms?
@@ -152,5 +167,6 @@ Review these questions before confirming output:
152
167
  ### 🛑 Verification-Before-Completion (VBC) Protocol
153
168
 
154
169
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
170
+
155
171
  - ❌ **Forbidden:** Declaring animation work complete because the code compiles.
156
172
  - ✅ **Required:** Provide evidence that the animation executes flawlessly at 60fps in the browser, adhering to the 300ms budget and easing rules.
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before writing retry logic, circuit breakers, or error handling routines, you MUST inspect:
23
+
23
24
  1. Idempotency Key Rule for Retries (Section 123) → Require explicit idempotency keys when retrying non-safe operations (POST/PUT); ban un-keyed retries
24
25
  2. Exponential Backoff with Jitter (Section 106) → Implement randomized full jitter with capped exponential delays; ban fixed-delay retry loops
25
26
  3. Operational vs Programmer Error Split (Section 28) → Catch and recover strictly from `OperationalError` instances; allow programmer bugs (`TypeError`) to crash fast
@@ -102,7 +103,12 @@ const DEFAULT_RETRY: RetryOptions = {
102
103
  maxRetries: 3,
103
104
  baseDelayMs: 500,
104
105
  maxDelayMs: 15_000,
105
- retryableErrors: (err) => err instanceof Error && (err.message.includes("ECONNRESET") || err.message.includes("ETIMEDOUT") || err.message.includes("503") || err.message.includes("429")),
106
+ retryableErrors: err =>
107
+ err instanceof Error &&
108
+ (err.message.includes('ECONNRESET') ||
109
+ err.message.includes('ETIMEDOUT') ||
110
+ err.message.includes('503') ||
111
+ err.message.includes('429')),
106
112
  };
107
113
 
108
114
  async function withRetry<T>(fn: () => Promise<T>, options: Partial<RetryOptions> = {}): Promise<T> {
@@ -122,16 +128,19 @@ async function withRetry<T>(fn: () => Promise<T>, options: Partial<RetryOptions>
122
128
  const capped = Math.min(exponential, opts.maxDelayMs);
123
129
  const jitter = Math.random() * capped;
124
130
 
125
- console.warn(`[RETRY] Attempt ${attempt + 1}/${opts.maxRetries} failed. ` + `Retrying in ${Math.round(jitter)}ms...`);
131
+ console.warn(
132
+ `[RETRY] Attempt ${attempt + 1}/${opts.maxRetries} failed. ` +
133
+ `Retrying in ${Math.round(jitter)}ms...`,
134
+ );
126
135
 
127
136
  await sleep(jitter);
128
137
  }
129
138
  }
130
- throw new Error("Unreachable");
139
+ throw new Error('Unreachable');
131
140
  }
132
141
 
133
142
  function sleep(ms: number): Promise<void> {
134
- return new Promise((resolve) => setTimeout(resolve, ms));
143
+ return new Promise(resolve => setTimeout(resolve, ms));
135
144
  }
136
145
 
137
146
  // ❌ NEVER retry non-idempotent operations without idempotency keys
@@ -145,9 +154,9 @@ function sleep(ms: number): Promise<void> {
145
154
 
146
155
  ```typescript
147
156
  enum CircuitState {
148
- CLOSED = "CLOSED", // Normal — requests pass through
149
- OPEN = "OPEN", // Tripped — requests fail immediately
150
- HALF_OPEN = "HALF_OPEN", // Testing — one request allowed
157
+ CLOSED = 'CLOSED', // Normal — requests pass through
158
+ OPEN = 'OPEN', // Tripped — requests fail immediately
159
+ HALF_OPEN = 'HALF_OPEN', // Testing — one request allowed
151
160
  }
152
161
 
153
162
  class CircuitBreaker {
@@ -210,7 +219,7 @@ const paymentCircuit = new CircuitBreaker(5, 30_000);
210
219
 
211
220
  const result = await paymentCircuit.execute(
212
221
  () => paymentGateway.charge(amount),
213
- () => ({ status: "deferred", message: "Payment queued for retry" }),
222
+ () => ({ status: 'deferred', message: 'Payment queued for retry' }),
214
223
  );
215
224
  ```
216
225
 
@@ -220,7 +229,7 @@ const result = await paymentCircuit.execute(
220
229
 
221
230
  ```tsx
222
231
  // ✅ Error boundary with recovery
223
- import { Component, type ReactNode } from "react";
232
+ import { Component, type ReactNode } from 'react';
224
233
 
225
234
  interface Props {
226
235
  children: ReactNode;
@@ -251,7 +260,9 @@ class ErrorBoundary extends Component<Props, State> {
251
260
  this.props.fallback ?? (
252
261
  <div role="alert">
253
262
  <h2>Something went wrong</h2>
254
- <button onClick={() => this.setState({ hasError: false, error: null })}>Try Again</button>
263
+ <button onClick={() => this.setState({ hasError: false, error: null })}>
264
+ Try Again
265
+ </button>
255
266
  </div>
256
267
  )
257
268
  );
@@ -273,7 +284,10 @@ class ErrorBoundary extends Component<Props, State> {
273
284
 
274
285
  ```typescript
275
286
  // ✅ AbortController-based timeout (modern, cancellable)
276
- async function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs: number): Promise<T> {
287
+ async function withTimeout<T>(
288
+ fn: (signal: AbortSignal) => Promise<T>,
289
+ timeoutMs: number,
290
+ ): Promise<T> {
277
291
  const controller = new AbortController();
278
292
  const timer = setTimeout(() => controller.abort(), timeoutMs);
279
293
 
@@ -290,7 +304,7 @@ async function withTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs
290
304
  }
291
305
 
292
306
  // Usage
293
- const data = await withTimeout((signal) => fetch("https://api.example.com/data", { signal }), 5000);
307
+ const data = await withTimeout(signal => fetch('https://api.example.com/data', { signal }), 5000);
294
308
  ```
295
309
 
296
310
  ---
@@ -318,8 +332,8 @@ async function getUserProfile(userId: string): Promise<UserProfile> {
318
332
  // Layer 3: Default
319
333
  return {
320
334
  id: userId,
321
- name: "Unknown User",
322
- avatar: "/default-avatar.png",
335
+ name: 'Unknown User',
336
+ avatar: '/default-avatar.png',
323
337
  _stale: true,
324
338
  _default: true,
325
339
  };
@@ -343,7 +357,11 @@ interface DeadLetter<T> {
343
357
  originalQueue: string;
344
358
  }
345
359
 
346
- async function processWithDLQ<T>(payload: T, processor: (item: T) => Promise<void>, dlqStore: { push: (item: DeadLetter<T>) => Promise<void> }): Promise<void> {
360
+ async function processWithDLQ<T>(
361
+ payload: T,
362
+ processor: (item: T) => Promise<void>,
363
+ dlqStore: { push: (item: DeadLetter<T>) => Promise<void> },
364
+ ): Promise<void> {
347
365
  try {
348
366
  await withRetry(() => processor(payload), { maxRetries: 3 });
349
367
  } catch (error) {
@@ -353,7 +371,7 @@ async function processWithDLQ<T>(payload: T, processor: (item: T) => Promise<voi
353
371
  error: error instanceof Error ? error.message : String(error),
354
372
  failedAt: new Date().toISOString(),
355
373
  attempts: 4,
356
- originalQueue: "main",
374
+ originalQueue: 'main',
357
375
  });
358
376
  // Don't throw — the message is preserved for manual review
359
377
  }