qualia-framework 2.6.0 → 3.1.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 (328) hide show
  1. package/CLAUDE.md +63 -0
  2. package/README.md +108 -30
  3. package/agents/builder.md +110 -0
  4. package/agents/planner.md +186 -0
  5. package/agents/qa-browser.md +186 -0
  6. package/agents/verifier.md +369 -0
  7. package/bin/cli.js +691 -492
  8. package/bin/install.js +622 -0
  9. package/bin/qualia-ui.js +284 -0
  10. package/bin/state.js +824 -0
  11. package/bin/statusline.js +252 -0
  12. package/docs/erp-contract.md +161 -0
  13. package/guide.md +63 -0
  14. package/hooks/auto-update.js +117 -0
  15. package/hooks/block-env-edit.js +52 -0
  16. package/hooks/branch-guard.js +68 -0
  17. package/hooks/migration-guard.js +83 -0
  18. package/hooks/pre-compact.js +52 -0
  19. package/hooks/pre-deploy-gate.js +149 -0
  20. package/hooks/pre-push.js +53 -0
  21. package/hooks/session-start.js +126 -0
  22. package/package.json +30 -20
  23. package/rules/design-reference.md +179 -0
  24. package/rules/frontend.md +126 -0
  25. package/rules/infrastructure.md +87 -0
  26. package/skills/qualia/SKILL.md +88 -0
  27. package/skills/qualia-build/SKILL.md +115 -0
  28. package/skills/qualia-debug/SKILL.md +87 -0
  29. package/skills/qualia-design/SKILL.md +99 -0
  30. package/skills/qualia-handoff/SKILL.md +66 -0
  31. package/skills/qualia-help/SKILL.md +60 -0
  32. package/skills/qualia-idk/SKILL.md +8 -0
  33. package/skills/qualia-learn/SKILL.md +111 -0
  34. package/skills/qualia-new/SKILL.md +323 -0
  35. package/skills/qualia-pause/SKILL.md +63 -0
  36. package/skills/qualia-plan/SKILL.md +101 -0
  37. package/skills/qualia-polish/SKILL.md +207 -0
  38. package/skills/qualia-quick/SKILL.md +37 -0
  39. package/skills/qualia-report/SKILL.md +114 -0
  40. package/skills/qualia-resume/SKILL.md +49 -0
  41. package/skills/qualia-review/SKILL.md +161 -0
  42. package/skills/qualia-ship/SKILL.md +90 -0
  43. package/skills/qualia-skill-new/SKILL.md +167 -0
  44. package/skills/qualia-task/SKILL.md +91 -0
  45. package/skills/qualia-test/SKILL.md +134 -0
  46. package/skills/qualia-verify/SKILL.md +113 -0
  47. package/templates/DESIGN.md +475 -0
  48. package/templates/help.html +476 -0
  49. package/templates/plan.md +42 -0
  50. package/templates/project.md +22 -0
  51. package/templates/state.md +27 -0
  52. package/templates/tracking.json +20 -0
  53. package/tests/bin.test.sh +687 -0
  54. package/tests/hooks.test.sh +384 -0
  55. package/tests/runner.js +1956 -0
  56. package/tests/state.test.sh +713 -0
  57. package/tests/statusline.test.sh +243 -0
  58. package/bin/collect-metrics.sh +0 -62
  59. package/framework/.claudeignore +0 -51
  60. package/framework/CLAUDE.md +0 -51
  61. package/framework/MCP_SETUP.md +0 -229
  62. package/framework/agents/architecture-strategist.md +0 -53
  63. package/framework/agents/backend-agent.md +0 -150
  64. package/framework/agents/code-simplicity-reviewer.md +0 -86
  65. package/framework/agents/frontend-agent.md +0 -111
  66. package/framework/agents/kieran-typescript-reviewer.md +0 -96
  67. package/framework/agents/performance-oracle.md +0 -111
  68. package/framework/agents/qualia-codebase-mapper.md +0 -761
  69. package/framework/agents/qualia-debugger.md +0 -1204
  70. package/framework/agents/qualia-executor.md +0 -882
  71. package/framework/agents/qualia-integration-checker.md +0 -424
  72. package/framework/agents/qualia-phase-researcher.md +0 -457
  73. package/framework/agents/qualia-plan-checker.md +0 -700
  74. package/framework/agents/qualia-planner.md +0 -1245
  75. package/framework/agents/qualia-project-researcher.md +0 -603
  76. package/framework/agents/qualia-research-synthesizer.md +0 -200
  77. package/framework/agents/qualia-roadmapper.md +0 -606
  78. package/framework/agents/qualia-verifier.md +0 -686
  79. package/framework/agents/red-team-qa.md +0 -130
  80. package/framework/agents/security-auditor.md +0 -72
  81. package/framework/agents/team-orchestrator.md +0 -229
  82. package/framework/agents/teams/framework-audit-team.md +0 -66
  83. package/framework/agents/teams/full-stack-team.md +0 -48
  84. package/framework/agents/teams/optimize-team.md +0 -53
  85. package/framework/agents/teams/review-team.md +0 -70
  86. package/framework/agents/teams/ship-team.md +0 -86
  87. package/framework/agents/test-agent.md +0 -182
  88. package/framework/hooks/auto-format.sh +0 -54
  89. package/framework/hooks/block-env-edit.sh +0 -42
  90. package/framework/hooks/branch-guard.sh +0 -43
  91. package/framework/hooks/confirm-delete.sh +0 -59
  92. package/framework/hooks/migration-validate.sh +0 -77
  93. package/framework/hooks/notification-speak.sh +0 -16
  94. package/framework/hooks/pre-commit.sh +0 -100
  95. package/framework/hooks/pre-compact.sh +0 -56
  96. package/framework/hooks/pre-deploy-gate.sh +0 -160
  97. package/framework/hooks/qualia-colors.sh +0 -32
  98. package/framework/hooks/retention-cleanup.sh +0 -62
  99. package/framework/hooks/save-session-state.sh +0 -185
  100. package/framework/hooks/session-context-loader.sh +0 -96
  101. package/framework/hooks/session-learn.sh +0 -32
  102. package/framework/hooks/skill-announce.sh +0 -123
  103. package/framework/hooks/tool-error-announce.sh +0 -27
  104. package/framework/install.ps1 +0 -323
  105. package/framework/install.sh +0 -313
  106. package/framework/qualia-framework/VERSION +0 -1
  107. package/framework/qualia-framework/assets/qualia-logo.png +0 -0
  108. package/framework/qualia-framework/bin/collect-metrics.sh +0 -67
  109. package/framework/qualia-framework/bin/generate-report-docx.py +0 -429
  110. package/framework/qualia-framework/bin/qualia-tools.js +0 -2201
  111. package/framework/qualia-framework/bin/qualia-tools.test.js +0 -1054
  112. package/framework/qualia-framework/references/checkpoints.md +0 -775
  113. package/framework/qualia-framework/references/completion-checklists.md +0 -359
  114. package/framework/qualia-framework/references/continuation-format.md +0 -249
  115. package/framework/qualia-framework/references/continuation-prompt.md +0 -97
  116. package/framework/qualia-framework/references/decimal-phase-calculation.md +0 -65
  117. package/framework/qualia-framework/references/design-quality.md +0 -56
  118. package/framework/qualia-framework/references/employee-guide.md +0 -167
  119. package/framework/qualia-framework/references/git-integration.md +0 -254
  120. package/framework/qualia-framework/references/git-planning-commit.md +0 -50
  121. package/framework/qualia-framework/references/model-profile-resolution.md +0 -32
  122. package/framework/qualia-framework/references/model-profiles.md +0 -73
  123. package/framework/qualia-framework/references/phase-argument-parsing.md +0 -61
  124. package/framework/qualia-framework/references/planning-config.md +0 -195
  125. package/framework/qualia-framework/references/questioning.md +0 -141
  126. package/framework/qualia-framework/references/tdd.md +0 -263
  127. package/framework/qualia-framework/references/ui-brand.md +0 -160
  128. package/framework/qualia-framework/references/verification-patterns.md +0 -612
  129. package/framework/qualia-framework/templates/DEBUG.md +0 -159
  130. package/framework/qualia-framework/templates/DESIGN.md +0 -81
  131. package/framework/qualia-framework/templates/UAT.md +0 -247
  132. package/framework/qualia-framework/templates/codebase/architecture.md +0 -255
  133. package/framework/qualia-framework/templates/codebase/concerns.md +0 -310
  134. package/framework/qualia-framework/templates/codebase/conventions.md +0 -307
  135. package/framework/qualia-framework/templates/codebase/integrations.md +0 -280
  136. package/framework/qualia-framework/templates/codebase/stack.md +0 -186
  137. package/framework/qualia-framework/templates/codebase/structure.md +0 -285
  138. package/framework/qualia-framework/templates/codebase/testing.md +0 -480
  139. package/framework/qualia-framework/templates/config.json +0 -35
  140. package/framework/qualia-framework/templates/context.md +0 -283
  141. package/framework/qualia-framework/templates/continue-here.md +0 -78
  142. package/framework/qualia-framework/templates/debug-subagent-prompt.md +0 -91
  143. package/framework/qualia-framework/templates/discovery.md +0 -146
  144. package/framework/qualia-framework/templates/lab-notes.md +0 -16
  145. package/framework/qualia-framework/templates/milestone-archive.md +0 -123
  146. package/framework/qualia-framework/templates/milestone.md +0 -115
  147. package/framework/qualia-framework/templates/phase-prompt.md +0 -567
  148. package/framework/qualia-framework/templates/planner-subagent-prompt.md +0 -117
  149. package/framework/qualia-framework/templates/project.md +0 -184
  150. package/framework/qualia-framework/templates/projects/ai-agent.md +0 -156
  151. package/framework/qualia-framework/templates/projects/mobile-app.md +0 -181
  152. package/framework/qualia-framework/templates/projects/voice-agent.md +0 -134
  153. package/framework/qualia-framework/templates/projects/website.md +0 -137
  154. package/framework/qualia-framework/templates/requirements.md +0 -231
  155. package/framework/qualia-framework/templates/research-project/ARCHITECTURE.md +0 -204
  156. package/framework/qualia-framework/templates/research-project/FEATURES.md +0 -147
  157. package/framework/qualia-framework/templates/research-project/PITFALLS.md +0 -200
  158. package/framework/qualia-framework/templates/research-project/STACK.md +0 -120
  159. package/framework/qualia-framework/templates/research-project/SUMMARY.md +0 -170
  160. package/framework/qualia-framework/templates/research.md +0 -552
  161. package/framework/qualia-framework/templates/roadmap.md +0 -206
  162. package/framework/qualia-framework/templates/state.md +0 -179
  163. package/framework/qualia-framework/templates/summary-complex.md +0 -59
  164. package/framework/qualia-framework/templates/summary-minimal.md +0 -41
  165. package/framework/qualia-framework/templates/summary-standard.md +0 -48
  166. package/framework/qualia-framework/templates/summary.md +0 -246
  167. package/framework/qualia-framework/templates/user-setup.md +0 -311
  168. package/framework/qualia-framework/templates/verification-report.md +0 -322
  169. package/framework/qualia-framework/workflows/add-phase.md +0 -179
  170. package/framework/qualia-framework/workflows/add-todo.md +0 -157
  171. package/framework/qualia-framework/workflows/audit-milestone.md +0 -241
  172. package/framework/qualia-framework/workflows/check-todos.md +0 -176
  173. package/framework/qualia-framework/workflows/complete-milestone.md +0 -858
  174. package/framework/qualia-framework/workflows/diagnose-issues.md +0 -219
  175. package/framework/qualia-framework/workflows/discovery-phase.md +0 -289
  176. package/framework/qualia-framework/workflows/discuss-phase.md +0 -534
  177. package/framework/qualia-framework/workflows/execute-phase.md +0 -559
  178. package/framework/qualia-framework/workflows/execute-plan.md +0 -438
  179. package/framework/qualia-framework/workflows/help.md +0 -470
  180. package/framework/qualia-framework/workflows/insert-phase.md +0 -220
  181. package/framework/qualia-framework/workflows/list-phase-assumptions.md +0 -178
  182. package/framework/qualia-framework/workflows/map-codebase.md +0 -327
  183. package/framework/qualia-framework/workflows/new-milestone.md +0 -363
  184. package/framework/qualia-framework/workflows/new-project.md +0 -982
  185. package/framework/qualia-framework/workflows/pause-work.md +0 -122
  186. package/framework/qualia-framework/workflows/plan-milestone-gaps.md +0 -256
  187. package/framework/qualia-framework/workflows/plan-phase.md +0 -422
  188. package/framework/qualia-framework/workflows/progress.md +0 -389
  189. package/framework/qualia-framework/workflows/quick.md +0 -252
  190. package/framework/qualia-framework/workflows/remove-phase.md +0 -326
  191. package/framework/qualia-framework/workflows/research-phase.md +0 -74
  192. package/framework/qualia-framework/workflows/resume-project.md +0 -306
  193. package/framework/qualia-framework/workflows/set-profile.md +0 -80
  194. package/framework/qualia-framework/workflows/settings.md +0 -145
  195. package/framework/qualia-framework/workflows/transition.md +0 -556
  196. package/framework/qualia-framework/workflows/update.md +0 -197
  197. package/framework/qualia-framework/workflows/verify-phase.md +0 -195
  198. package/framework/qualia-framework/workflows/verify-work.md +0 -625
  199. package/framework/rules/context7.md +0 -14
  200. package/framework/rules/frontend.md +0 -33
  201. package/framework/rules/speed.md +0 -23
  202. package/framework/scripts/__pycache__/say.cpython-314.pyc +0 -0
  203. package/framework/scripts/apply-retention.sh +0 -120
  204. package/framework/scripts/bootstrap-pop-os.sh +0 -354
  205. package/framework/scripts/claude-voice +0 -13
  206. package/framework/scripts/cleanup.sh +0 -131
  207. package/framework/scripts/cowork-mode.sh +0 -141
  208. package/framework/scripts/generate-project-claude-md.sh +0 -153
  209. package/framework/scripts/load-test-webhook.js +0 -172
  210. package/framework/scripts/say.py +0 -236
  211. package/framework/scripts/showcase-video-recorder/ffmpeg-builder.js +0 -167
  212. package/framework/scripts/showcase-video-recorder/playwright-helpers.js +0 -216
  213. package/framework/scripts/speak.py +0 -55
  214. package/framework/scripts/speak.sh +0 -18
  215. package/framework/scripts/status.sh +0 -138
  216. package/framework/scripts/sync-to-framework.sh +0 -65
  217. package/framework/scripts/voice-hotkey.py +0 -227
  218. package/framework/scripts/voice-input.sh +0 -51
  219. package/framework/skills/animate/SKILL.md +0 -202
  220. package/framework/skills/bolder/SKILL.md +0 -144
  221. package/framework/skills/browser-qa/SKILL.md +0 -536
  222. package/framework/skills/clarify/SKILL.md +0 -179
  223. package/framework/skills/client-handoff/SKILL.md +0 -135
  224. package/framework/skills/collab-onboard/SKILL.md +0 -111
  225. package/framework/skills/colorize/SKILL.md +0 -170
  226. package/framework/skills/critique/SKILL.md +0 -126
  227. package/framework/skills/deep-research/SKILL.md +0 -240
  228. package/framework/skills/delight/SKILL.md +0 -329
  229. package/framework/skills/deploy/SKILL.md +0 -261
  230. package/framework/skills/deploy-verify/SKILL.md +0 -377
  231. package/framework/skills/deploy-verify/scripts/canary-check.sh +0 -206
  232. package/framework/skills/deploy-verify/scripts/check-console-errors.js +0 -147
  233. package/framework/skills/deploy-verify/scripts/check-cwv.js +0 -139
  234. package/framework/skills/deploy-verify/scripts/project-detect.sh +0 -84
  235. package/framework/skills/deploy-verify/scripts/verify.sh +0 -548
  236. package/framework/skills/design-quieter/SKILL.md +0 -130
  237. package/framework/skills/distill/SKILL.md +0 -149
  238. package/framework/skills/docs-lookup/SKILL.md +0 -79
  239. package/framework/skills/fcm-notifications/SKILL.md +0 -125
  240. package/framework/skills/financial-ledger/SKILL.md +0 -1039
  241. package/framework/skills/frontend-master/NOTICE.md +0 -4
  242. package/framework/skills/frontend-master/SKILL.md +0 -127
  243. package/framework/skills/frontend-master/reference/color-and-contrast.md +0 -132
  244. package/framework/skills/frontend-master/reference/interaction-design.md +0 -123
  245. package/framework/skills/frontend-master/reference/motion-design.md +0 -99
  246. package/framework/skills/frontend-master/reference/responsive-design.md +0 -114
  247. package/framework/skills/frontend-master/reference/spatial-design.md +0 -100
  248. package/framework/skills/frontend-master/reference/typography.md +0 -131
  249. package/framework/skills/frontend-master/reference/ux-writing.md +0 -107
  250. package/framework/skills/harden/SKILL.md +0 -357
  251. package/framework/skills/i18n-rtl/SKILL.md +0 -752
  252. package/framework/skills/learn/SKILL.md +0 -95
  253. package/framework/skills/memory/SKILL.md +0 -50
  254. package/framework/skills/mobile-expo/SKILL.md +0 -977
  255. package/framework/skills/mobile-expo/references/store-checklist.md +0 -550
  256. package/framework/skills/nestjs-backend/README.md +0 -73
  257. package/framework/skills/nestjs-backend/SKILL.md +0 -446
  258. package/framework/skills/nestjs-backend/references/templates.md +0 -1173
  259. package/framework/skills/normalize/SKILL.md +0 -79
  260. package/framework/skills/onboard/SKILL.md +0 -242
  261. package/framework/skills/openrouter-agent/SKILL.md +0 -922
  262. package/framework/skills/polish/SKILL.md +0 -209
  263. package/framework/skills/pr/SKILL.md +0 -66
  264. package/framework/skills/qualia/SKILL.md +0 -199
  265. package/framework/skills/qualia-add-todo/SKILL.md +0 -68
  266. package/framework/skills/qualia-audit-milestone/SKILL.md +0 -95
  267. package/framework/skills/qualia-check-todos/SKILL.md +0 -55
  268. package/framework/skills/qualia-complete-milestone/SKILL.md +0 -134
  269. package/framework/skills/qualia-debug/SKILL.md +0 -149
  270. package/framework/skills/qualia-design/SKILL.md +0 -203
  271. package/framework/skills/qualia-discuss-phase/SKILL.md +0 -72
  272. package/framework/skills/qualia-evolve/SKILL.md +0 -200
  273. package/framework/skills/qualia-execute-phase/SKILL.md +0 -89
  274. package/framework/skills/qualia-framework-audit/SKILL.md +0 -604
  275. package/framework/skills/qualia-guide/SKILL.md +0 -32
  276. package/framework/skills/qualia-help/SKILL.md +0 -114
  277. package/framework/skills/qualia-idk/SKILL.md +0 -352
  278. package/framework/skills/qualia-list-phase-assumptions/SKILL.md +0 -67
  279. package/framework/skills/qualia-new-milestone/SKILL.md +0 -72
  280. package/framework/skills/qualia-new-project/SKILL.md +0 -232
  281. package/framework/skills/qualia-optimize/SKILL.md +0 -417
  282. package/framework/skills/qualia-pause-work/SKILL.md +0 -96
  283. package/framework/skills/qualia-plan-milestone-gaps/SKILL.md +0 -57
  284. package/framework/skills/qualia-plan-phase/SKILL.md +0 -104
  285. package/framework/skills/qualia-production-check/SKILL.md +0 -0
  286. package/framework/skills/qualia-progress/SKILL.md +0 -53
  287. package/framework/skills/qualia-quick/SKILL.md +0 -89
  288. package/framework/skills/qualia-report/SKILL.md +0 -166
  289. package/framework/skills/qualia-research-phase/SKILL.md +0 -88
  290. package/framework/skills/qualia-resume-work/SKILL.md +0 -62
  291. package/framework/skills/qualia-review/SKILL.md +0 -263
  292. package/framework/skills/qualia-start/SKILL.md +0 -161
  293. package/framework/skills/qualia-verify-work/SKILL.md +0 -132
  294. package/framework/skills/rag/SKILL.md +0 -750
  295. package/framework/skills/responsive/SKILL.md +0 -231
  296. package/framework/skills/retro/SKILL.md +0 -284
  297. package/framework/skills/sakani-conventions/SKILL.md +0 -136
  298. package/framework/skills/sakani-conventions/evals/evals.json +0 -23
  299. package/framework/skills/sakani-conventions/references/entities.md +0 -365
  300. package/framework/skills/sakani-conventions/references/error-codes.md +0 -95
  301. package/framework/skills/seo-master/SKILL.md +0 -490
  302. package/framework/skills/seo-master/references/checklist.md +0 -199
  303. package/framework/skills/seo-master/references/structured-data.md +0 -609
  304. package/framework/skills/ship/SKILL.md +0 -239
  305. package/framework/skills/stack-researcher/SKILL.md +0 -215
  306. package/framework/skills/status/SKILL.md +0 -154
  307. package/framework/skills/status/scripts/health-check.sh +0 -562
  308. package/framework/skills/subscription-payments/SKILL.md +0 -250
  309. package/framework/skills/supabase/SKILL.md +0 -973
  310. package/framework/skills/supabase/references/templates.md +0 -159
  311. package/framework/skills/team/SKILL.md +0 -67
  312. package/framework/skills/test-runner/SKILL.md +0 -202
  313. package/framework/skills/voice-agent/SKILL.md +0 -1312
  314. package/framework/skills/zoho-workflow/SKILL.md +0 -51
  315. package/framework/statusline-command.sh +0 -117
  316. package/framework/teams/default/inboxes/plan-04.json +0 -9
  317. package/framework/teams/review-team.md +0 -75
  318. package/framework/teams/ship-team.md +0 -86
  319. package/profiles/fawzi.json +0 -16
  320. package/profiles/hasan.json +0 -16
  321. package/profiles/moayad.json +0 -16
  322. package/templates/CLAUDE-owner.md +0 -52
  323. package/templates/CLAUDE.md.hbs +0 -58
  324. package/templates/env.claude.template +0 -12
  325. package/templates/settings.json +0 -172
  326. package/uninstall.sh +0 -90
  327. /package/{framework/rules → rules}/deployment.md +0 -0
  328. /package/{framework/rules → rules}/security.md +0 -0
package/rules/design-reference.md ADDED
@@ -0,0 +1,179 @@
1
+ ---
2
+ globs: ["*.tsx", "*.jsx", "*.css", "*.scss"]
3
+ ---
4
+
5
+ # Design Reference — Deep Specs
6
+
7
+ Detailed values for motion, accessibility, and responsive design. Loaded alongside `frontend.md` for frontend work.
8
+
9
+ ## Motion Specification
10
+
11
+ ### Duration Table
12
+
13
+ | Action | Duration | Easing | Example |
14
+ |--------|----------|--------|---------|
15
+ | Micro-feedback | 100ms | ease-out | Button press, checkbox toggle |
16
+ | Hover/focus | 150ms | ease-out | Color change, underline appear |
17
+ | Small reveal | 200ms | ease-out | Tooltip show, dropdown open |
18
+ | Expand/collapse | 250ms | ease-in-out | Accordion, panel slide |
19
+ | Page element enter | 300ms | cubic-bezier(0, 0, 0.2, 1) | Card fade-in, section reveal |
20
+ | Page transition | 400ms | cubic-bezier(0.4, 0, 0.2, 1) | Route change, modal open |
21
+ | Complex orchestration | 500–800ms | staggered | Page load sequence |
22
+
23
+ ### Easing Curves (CSS)
24
+
25
+ ```css
26
+ --ease-standard: cubic-bezier(0.4, 0, 0.2, 1); /* General movement */
27
+ --ease-decelerate: cubic-bezier(0, 0, 0.2, 1); /* Enter screen */
28
+ --ease-accelerate: cubic-bezier(0.4, 0, 1, 1); /* Exit screen */
29
+ --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1); /* Playful bounce */
30
+ --ease-smooth: cubic-bezier(0.25, 0.1, 0.25, 1); /* Subtle shift */
31
+ ```
32
+
33
+ ### Stagger Pattern
34
+
35
+ ```css
36
+ /* Stagger children on page load */
37
+ @keyframes fadeUp {
38
+ from { opacity: 0; transform: translateY(12px); }
39
+ to { opacity: 1; transform: translateY(0); }
40
+ }
41
+
42
+ .stagger > * {
43
+ animation: fadeUp 300ms var(--ease-decelerate) both;
44
+ }
45
+ .stagger > *:nth-child(1) { animation-delay: 0ms; }
46
+ .stagger > *:nth-child(2) { animation-delay: 60ms; }
47
+ .stagger > *:nth-child(3) { animation-delay: 120ms; }
48
+ .stagger > *:nth-child(4) { animation-delay: 180ms; }
49
+ .stagger > *:nth-child(5) { animation-delay: 240ms; }
50
+ ```
51
+
52
+ ### Reduced Motion
53
+
54
+ ```css
55
+ @media (prefers-reduced-motion: reduce) {
56
+ *, *::before, *::after {
57
+ animation-duration: 0.01ms !important;
58
+ animation-iteration-count: 1 !important;
59
+ transition-duration: 0.01ms !important;
60
+ scroll-behavior: auto !important;
61
+ }
62
+ }
63
+ ```
64
+
65
+ ## WCAG AA Checklist
66
+
67
+ ### Perceivable
68
+ - [ ] All images have descriptive alt text (decorative: `alt=""` + `aria-hidden="true"`)
69
+ - [ ] Color contrast: 4.5:1 normal text, 3:1 large text (18px+ bold / 24px+)
70
+ - [ ] Color contrast: 3:1 for UI components and graphical objects
71
+ - [ ] Information not conveyed by color alone — icons, text, patterns as supplements
72
+ - [ ] Video/audio: captions or transcripts where applicable
73
+ - [ ] Text resizable to 200% without loss of content
74
+ - [ ] Content reflows at 320px viewport width (no horizontal scroll)
75
+
76
+ ### Operable
77
+ - [ ] All functionality available via keyboard (Tab, Enter, Space, Escape, Arrows)
78
+ - [ ] No keyboard traps (except intentional focus traps in modals)
79
+ - [ ] Visible focus indicator: 2px+ ring, contrasting color, no `outline: none` without replacement
80
+ - [ ] Skip navigation link as first focusable element
81
+ - [ ] Touch targets: 44x44px minimum (48x48px recommended)
82
+ - [ ] No content that flashes more than 3 times per second
83
+ - [ ] Page titles are descriptive and unique
84
+
85
+ ### Understandable
86
+ - [ ] Form inputs have visible labels (not placeholder-only)
87
+ - [ ] Error messages identify the field and describe the error
88
+ - [ ] Error suggestions explain how to fix the problem
89
+ - [ ] Required fields marked with `aria-required="true"` and visual indicator
90
+ - [ ] Language set: `<html lang="en">`
91
+ - [ ] Consistent navigation across pages
92
+ - [ ] No unexpected context changes on input
93
+
94
+ ### Robust
95
+ - [ ] Valid HTML (no duplicate IDs, proper nesting)
96
+ - [ ] ARIA used correctly: `role`, `aria-label`, `aria-describedby`, `aria-expanded`, `aria-hidden`
97
+ - [ ] Dynamic content: `aria-live="polite"` for updates, `aria-live="assertive"` for errors
98
+ - [ ] Custom components have proper roles and keyboard interaction patterns
99
+
100
+ ## Responsive Breakpoints
101
+
102
+ ### Strategy: Mobile-First with Fluid Scaling
103
+
104
+ ```css
105
+ /* Base: mobile (320px–639px) */
106
+ /* sm: 640px+ — large phone / small tablet */
107
+ /* md: 768px+ — tablet */
108
+ /* lg: 1024px+ — laptop */
109
+ /* xl: 1280px+ — desktop */
110
+ /* 2xl: 1536px+ — large desktop */
111
+ ```
112
+
113
+ ### Common Patterns
114
+
115
+ | Pattern | Mobile | Tablet | Desktop |
116
+ |---------|--------|--------|---------|
117
+ | Navigation | Hamburger + drawer | Hamburger or condensed | Full horizontal |
118
+ | Grid | 1 column | 2 columns | 3–4 columns |
119
+ | Sidebar | Hidden, overlay | Collapsible | Always visible |
120
+ | Hero | Stacked, full-width | Stacked, padded | Side-by-side |
121
+ | Table | Card view or scroll | Scroll with sticky col | Full table |
122
+ | Modal | Full screen | Centered, 80% width | Centered, max-width |
123
+ | Form | Single column | Single column | Two column for long forms |
124
+
125
+ ### Fluid Typography
126
+
127
+ ```css
128
+ /* Body */
129
+ font-size: clamp(1rem, 0.5rem + 1.5vw, 1.125rem);
130
+
131
+ /* H1 */
132
+ font-size: clamp(2rem, 1rem + 3vw, 3.75rem);
133
+
134
+ /* H2 */
135
+ font-size: clamp(1.5rem, 0.75rem + 2.25vw, 2.5rem);
136
+
137
+ /* H3 */
138
+ font-size: clamp(1.25rem, 0.75rem + 1.5vw, 1.875rem);
139
+ ```
140
+
141
+ ### Fluid Spacing
142
+
143
+ ```css
144
+ /* Section padding */
145
+ padding-inline: clamp(1rem, 5vw, 4rem);
146
+ padding-block: clamp(2rem, 8vw, 6rem);
147
+
148
+ /* Component gap */
149
+ gap: clamp(1rem, 3vw, 2rem);
150
+ ```
151
+
152
+ ## React/Next.js Performance (Critical)
153
+
154
+ ### Priority 1: Eliminate Waterfalls
155
+ - Fetch data in parallel (`Promise.all`), not sequentially
156
+ - Use Suspense boundaries to stream content progressively
157
+ - Prefetch data on hover/focus for anticipated navigation
158
+ - Colocate data fetching with the component that needs it
159
+
160
+ ### Priority 2: Bundle Size
161
+ - Import specific functions, not entire libraries (`import { format } from 'date-fns'`)
162
+ - Avoid barrel files (index.ts re-exports) — import directly from source
163
+ - Use `next/dynamic` for heavy components not needed on initial load
164
+ - Lazy-load below-fold content and non-critical features
165
+
166
+ ### Priority 3: Rendering
167
+ - Server Components by default — only add `'use client'` when needed (state, effects, browser APIs)
168
+ - Avoid unnecessary `useEffect` — derive values during render when possible
169
+ - Use CSS `content-visibility: auto` for long scrollable lists
170
+ - Images: `next/image` with proper `width`/`height` to prevent layout shift
171
+
172
+ ## Compound Component Patterns
173
+
174
+ When building reusable components:
175
+ - **No boolean prop proliferation** (`isCompact`, `showHeader`, `isRounded`) — use composition instead
176
+ - Compound components: `<Select>`, `<Select.Trigger>`, `<Select.Content>` with shared context
177
+ - Explicit variants: `<Alert.Destructive>` instead of `<Alert isDestructive>`
178
+ - Children over render props: `children` for composition, not `renderHeader`/`renderFooter`
179
+ - React 19: use `use()` instead of `useContext()`, skip `forwardRef` (ref is a regular prop)
package/rules/frontend.md ADDED
@@ -0,0 +1,126 @@
1
+ ---
2
+ globs: ["*.tsx", "*.jsx", "*.css", "*.scss", "tailwind.config.*"]
3
+ ---
4
+
5
+ # Frontend Design Standards
6
+
7
+ These are Qualia brand standards — mandatory for every frontend component. Not suggestions.
8
+
9
+ ## Typography
10
+
11
+ **Never use:** Inter, Roboto, Arial, Helvetica, system-ui, Space Grotesk (overused by AI).
12
+
13
+ - Pair a distinctive display font with a refined body font
14
+ - Type scale: 12 / 14 / 16 / 18 / 20 / 24 / 30 / 36 / 48 / 60 / 72
15
+ - Body: 16px min, line-height 1.5–1.7
16
+ - Headings: line-height 1.1–1.3, letter-spacing -0.02em for large sizes
17
+ - Weight hierarchy: Regular (400) body, Medium (500) labels, Semibold (600) headings, Bold (700) display
18
+ - Prose max-width: 65ch. Everything else: fluid full-width
19
+
20
+ ## Color
21
+
22
+ - Commit to a cohesive palette — define in CSS variables
23
+ - One dominant brand color with sharp accent for CTAs
24
+ - Never: blue-purple gradients, rainbow palettes, gray-on-gray
25
+ - Dark mode: not just inverted — rethink surfaces, reduce contrast slightly
26
+ - Semantic colors: success (green), warning (amber), error (red), info (blue) — always with non-color indicator too
27
+ - All text must meet **WCAG AA** contrast: 4.5:1 normal text, 3:1 large text (18px+ bold or 24px+)
28
+
29
+ ## Layout
30
+
31
+ - Full-width layouts — no hardcoded `max-width: 1200px` or `1280px` caps
32
+ - Fluid padding: `clamp(1rem, 5vw, 4rem)` for horizontal, generous vertical
33
+ - 8px spacing grid: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96
34
+ - Tight spacing within groups, generous between sections
35
+ - Asymmetry > symmetry. Overlap, diagonal flow, grid-breaking elements when appropriate
36
+ - No card grids — use varied layouts with visual hierarchy
37
+ - No generic hero sections — make them distinctive and purposeful
38
+
39
+ ## Motion & Animation
40
+
41
+ - Hover/focus transitions: 150–200ms ease-out
42
+ - Expand/collapse: 200–300ms ease-in-out
43
+ - Page transitions: 300–500ms ease-out
44
+ - Staggered entrance animations: 50–80ms delay between items
45
+ - **Always** respect `prefers-reduced-motion: reduce` — disable non-essential animation
46
+ - Easing: `cubic-bezier(0.4, 0, 0.2, 1)` (standard), `cubic-bezier(0, 0, 0.2, 1)` (decelerate), `cubic-bezier(0.4, 0, 1, 1)` (accelerate)
47
+ - One well-orchestrated page load > scattered micro-interactions
48
+ - CSS-only for HTML projects, Motion library (`motion/react`) for React
49
+
50
+ ## States (Every Interactive Element)
51
+
52
+ - **Loading:** Skeleton or spinner on async operations — never a blank void
53
+ - **Empty:** Helpful message + action when lists/data are empty — never "No results"
54
+ - **Error:** User-friendly message + recovery action — never raw error text
55
+ - **Hover:** Visual feedback within 100ms
56
+ - **Focus:** Visible focus ring (2px+ offset, high contrast) — never `outline: none` without replacement
57
+ - **Active/Pressed:** Scale down slightly or color shift
58
+ - **Disabled:** Reduced opacity (0.5) + `cursor: not-allowed` + `aria-disabled`
59
+
60
+ ## Accessibility (WCAG AA Minimum)
61
+
62
+ - Semantic HTML: `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<header>`, `<footer>` — not divs for everything
63
+ - Heading hierarchy: One `<h1>` per page, sequential order (no skipping h2→h4)
64
+ - All images: descriptive `alt` text (or `alt=""` + `aria-hidden` if decorative)
65
+ - All form inputs: visible `<label>` linked via `htmlFor` — not placeholder-only
66
+ - All interactive elements: keyboard accessible (Tab, Enter, Escape, Arrow keys)
67
+ - Touch targets: 44x44px minimum
68
+ - ARIA: use native HTML elements first. Only add ARIA when HTML semantics aren't enough
69
+ - Never rely solely on color to convey information — add icons, text, or patterns
70
+ - Skip link: `<a href="#main" class="sr-only focus:not-sr-only">` on every page
71
+ - Live regions: `aria-live="polite"` for dynamic content updates (toasts, form validation)
72
+
73
+ ## Responsive Design
74
+
75
+ - Mobile-first: base styles for mobile, `@media (min-width)` for larger screens
76
+ - Breakpoints: `sm: 640px`, `md: 768px`, `lg: 1024px`, `xl: 1280px`, `2xl: 1536px`
77
+ - Fluid typography: `clamp(1rem, 0.5rem + 1.5vw, 1.25rem)` for body, scale up for headings
78
+ - Stack on mobile, expand on desktop — never force horizontal scroll
79
+ - Test: 320px (small phone), 375px (iPhone), 768px (tablet), 1024px (laptop), 1440px (desktop)
80
+ - Images: `max-width: 100%`, `height: auto`, use `srcset` for responsive images
81
+ - Navigation: hamburger menu on mobile, expanded on desktop
82
+
83
+ ## Component Quality
84
+
85
+ - `cursor: pointer` on ALL clickable elements
86
+ - Smooth transitions (150–300ms) on all state changes
87
+ - No emoji as icons — use SVGs or icon libraries
88
+ - Buttons: clear visual hierarchy (primary, secondary, ghost, destructive)
89
+ - Inputs: visible borders, focus rings, error states with `aria-describedby`
90
+ - Links: distinguishable from text (underline or color + another indicator)
91
+ - Modals: trap focus, close on Escape, `aria-modal="true"`, restore focus on close
92
+ - Toast/notifications: `aria-live`, auto-dismiss with adequate time (5s+), dismissible
93
+
94
+ ## Anti-Patterns (Kill on Sight)
95
+
96
+ - Card grids where every card looks identical → varied layouts
97
+ - Generic hero with stock photo → distinctive, purposeful hero
98
+ - Blue-purple gradients → brand colors
99
+ - Static pages with no motion → purposeful animation
100
+ - Fixed widths → fluid responsive
101
+ - Gray text on white (#999 on #fff fails WCAG) → proper contrast
102
+ - Placeholder text shipped to production → real content or proper empty states
103
+ - `outline: none` without focus replacement → visible focus indicators
104
+ - `div` soup → semantic HTML
105
+ - Hardcoded colors scattered in JSX → CSS variables or Tailwind config
106
+
107
+ ## Design System Integration
108
+
109
+ If `.planning/DESIGN.md` exists in the project, it takes precedence over these defaults.
110
+ Read it before any frontend work. It contains project-specific: palette, typography, spacing, component patterns.
111
+
112
+ ## Impeccable Design Skills (global)
113
+ - `/polish` — Final detail pass before shipping
114
+ - `/bolder` — Amplify safe/boring designs
115
+ - `/design-quieter` — Tone down overly aggressive designs
116
+ - `/animate` — Add purposeful micro-interactions
117
+ - `/colorize` — Inject strategic color into monochrome UIs
118
+ - `/clarify` — Fix unclear UX copy, labels, error messages
119
+ - `/critique` — Design director-level review
120
+ - `/distill` — Strip unnecessary complexity
121
+ - `/delight` — Add memorable touches and personality
122
+ - `/harden` — Edge cases, overflow, i18n robustness
123
+ - `/responsive` — Cross-device responsive adaptation
124
+
125
+ ### Recommended workflow
126
+ 1. Build feature → 2. `/critique` → 3. `/polish` → 4. `/harden` → ship
package/rules/infrastructure.md ADDED
@@ -0,0 +1,87 @@
1
+ ---
2
+ globs: ["*.env*", "vercel.json", "next.config.*", "supabase/**", "railway.*"]
3
+ ---
4
+
5
+ # Infrastructure & Services
6
+
7
+ Standard services across all Qualia projects. Use these unless the project explicitly specifies otherwise.
8
+
9
+ ## Database: Supabase (every project)
10
+ - Every project uses Supabase for auth, database, and storage
11
+ - **CLI:** `npx supabase` — migrations, type generation, local dev
12
+ - **MCP:** Supabase MCP server is available in Claude Code for direct database operations
13
+ - Always enable RLS on every table (see `rules/security.md`)
14
+ - Use `lib/supabase/server.ts` for server-side, `lib/supabase/client.ts` for client-side
15
+ - Run `npx supabase gen types` after schema changes
16
+ - Migrations go in `supabase/migrations/` — never edit production directly
17
+
18
+ ## AI Models: OpenRouter (every project)
19
+ - Use OpenRouter API for all LLM calls — it routes to the best-suited model per task
20
+ - API key env var: `OPENROUTER_API_KEY`
21
+ - Don't have a key? Ask Fawzi for one
22
+ - Never hardcode a specific model provider (OpenAI, Anthropic, etc.) directly — always go through OpenRouter
23
+ - Exception: if a client specifically requires a direct provider integration
24
+
25
+ ## Voice AI: Retell AI + ElevenLabs
26
+ - **Retell AI** — primary voice agent platform. API key: `RETELL_API_KEY`
27
+ - **ElevenLabs** — voice synthesis, cloning, streaming. API key: `ELEVENLABS_API_KEY`
28
+ - **Telnyx** — telephony/SIP for voice agent phone numbers. API key: `TELNYX_API_KEY`
29
+ - For new voice projects, default to Retell AI + ElevenLabs unless client specifies otherwise
30
+
31
+ ## Compute: Vercel + Railway
32
+ - **Vercel** — primary hosting for all Next.js projects. Deploy via CLI only (see below)
33
+ - **Railway** — secondary compute for long-running agents, background jobs, and agentic workloads that exceed Vercel's function timeout
34
+ - **Railway CLI:** `railway` — deploy, logs, env management
35
+ - **Railway MCP:** Railway MCP server is available in Claude Code for project management
36
+ - Railway projects use Nixpacks (auto-detected) — check for `railway.json` or `railway.toml`
37
+
38
+ ## MCP Servers (available in Claude Code)
39
+ - **Supabase MCP** — database queries, table management, migrations from within Claude Code
40
+ - **Railway MCP** — project deployment, logs, environment variables from within Claude Code
41
+ - **next-devtools MCP** — runtime error visibility for Next.js 16+ dev servers (optional, added by framework install)
42
+
43
+ ## CLIs (must be installed)
44
+ - `npx supabase` — Supabase CLI (database, migrations, types)
45
+ - `railway` — Railway CLI (deploy, logs, env)
46
+ - `vercel` — Vercel CLI (deploy, env, link)
47
+ - `gh` — GitHub CLI (PRs, issues, repos)
48
+
49
+ ## GitHub Organizations
50
+ - **QualiasolutionsCY** — primary org for all Qualia Solutions projects
51
+ - **SakaniQualia** — org for Sakani-related projects (real estate platform)
52
+ - All repos are private by default
53
+ - Branch protection: main/master require PR reviews (enforced by framework guards)
54
+
55
+ ## Vercel Teams (admin knowledge)
56
+ - Qualia operates across **3 Vercel teams** — projects are distributed across them
57
+ - Check which team a project belongs to before deploying: `vercel whoami` and `vercel link`
58
+ - If a project isn't linked, link it first: `vercel link`
59
+
60
+ ## Deployment Rules
61
+ - **NO auto-deploys from GitHub pushes** — all Vercel projects have GitHub integration auto-deploy DISABLED
62
+ - Deploys happen ONLY via `vercel --prod` through the CLI (or `/qualia-ship`)
63
+ - This is intentional — we control when things go live, not git push triggers
64
+ - If you find a project with auto-deploy enabled, disable it: Vercel Dashboard → Project Settings → Git → Disable "Automatic Deployments"
65
+
66
+ ## Required Environment Variables (typical project)
67
+
68
+ ```bash
69
+ # Supabase (every project)
70
+ NEXT_PUBLIC_SUPABASE_URL=
71
+ NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
72
+ SUPABASE_SERVICE_ROLE_KEY= # NEVER in client code
73
+
74
+ # AI (if applicable)
75
+ OPENROUTER_API_KEY= # ask Fawzi if you don't have one
76
+
77
+ # Voice (if applicable)
78
+ RETELL_API_KEY=
79
+ ELEVENLABS_API_KEY=
80
+ TELNYX_API_KEY=
81
+
82
+ # Deployment
83
+ VERCEL_ORG_ID= # from vercel link
84
+ VERCEL_PROJECT_ID= # from vercel link
85
+ ```
86
+
87
+ Always use `vercel env pull` to sync env vars locally. Never create `.env` manually from scratch.
package/skills/qualia/SKILL.md ADDED
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: qualia
3
+ description: "Smart router — reads project state, classifies your situation, tells you the exact next command. Use whenever you type /qualia, 'what next', 'next', 'idk', 'what now', 'what should I do', 'I'm stuck', 'help me decide', 'lost', 'confused', or are unsure about your next step."
4
+ ---
5
+
6
+ # /qualia — What's Next?
7
+
8
+ Read project state. Classify your situation. Tell you the exact next command.
9
+
10
+ ## Process
11
+
12
+ ### 1. Get State
13
+
14
+ ```bash
15
+ node ~/.claude/bin/state.js check 2>/dev/null
16
+ ```
17
+
18
+ Also gather context:
19
+ ```bash
20
+ test -f .continue-here.md && echo "HANDOFF_EXISTS" && head -20 .continue-here.md || echo "NO_HANDOFF"
21
+ git status --short 2>/dev/null | head -10
22
+ git log --oneline -3 2>/dev/null
23
+ ls .planning/phase-*-plan.md 2>/dev/null || echo "NO_PLANS"
24
+ ls .planning/phase-*-verification.md 2>/dev/null || echo "NO_VERIFICATIONS"
25
+ ```
26
+
27
+ Read conversation context — what has the user been doing, what errors occurred.
28
+
29
+ ### 2. Classify and Route
30
+
31
+ Use the state.js JSON output plus gathered context:
32
+
33
+ | Situation | Detection | Route |
34
+ |-----------|-----------|-------|
35
+ | `no-project` | state.js returns NO_PROJECT | → `/qualia-new` |
36
+ | `handoff` | `.continue-here.md` exists | → Read it, summarize, route to next step |
37
+ | `mid-work` | Uncommitted changes + phase in progress | → Continue or `/qualia-pause` |
38
+ | `ready-to-plan` | status == "setup" | → `/qualia-plan {N}` |
39
+ | `ready-to-build` | status == "planned" | → `/qualia-build {N}` |
40
+ | `ready-to-verify` | status == "built" | → `/qualia-verify {N}` |
41
+ | `gaps-found` | status == "verified", verification == "fail", gap_cycles < 2 | → `/qualia-plan {N} --gaps` |
42
+ | `gap-limit` | status == "verified", verification == "fail", gap_cycles >= 2 | → Escalate to Fawzi or re-plan from scratch |
43
+ | `phase-complete` | state.js auto-advanced (status == "setup", phase > 1) | → `/qualia-plan {N}` |
44
+ | `all-verified` | last phase verified pass, status == "verified" | → `/qualia-polish` |
45
+ | `polished` | status == "polished" | → `/qualia-ship` |
46
+ | `shipped` | status == "shipped" | → `/qualia-handoff` |
47
+ | `handed-off` | status == "handed_off" | → `/qualia-report` then done |
48
+ | `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
49
+ | `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
50
+ | `need-tests` | User mentions "tests", "coverage", "test this" | → `/qualia-test` |
51
+
52
+ **Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
53
+
54
+ ### 3. Display
55
+
56
+ **Clear next step** (use the UI helper — it reads state.js itself):
57
+ ```bash
58
+ node ~/.claude/bin/qualia-ui.js banner router
59
+ node ~/.claude/bin/qualia-ui.js next "{next_command from state.js}"
60
+ ```
61
+
62
+ **Ambiguous situation (multiple options):**
63
+ Print the banner first, then use plain markdown for the options:
64
+ ```bash
65
+ node ~/.claude/bin/qualia-ui.js banner router
66
+ ```
67
+ ```
68
+ ## Where You Are
69
+ {1-2 sentences}
70
+
71
+ ## I Recommend
72
+ **{action}** — {why}
73
+ {command}
74
+
75
+ ## Other Options
76
+ 1. **{option}** — {what}
77
+ 2. **{option}** — {what}
78
+ 3. **{option}** — {what}
79
+ ```
80
+
81
+ **Blocker detected** (gap-limit, bug-loop, employee escalation):
82
+ ```bash
83
+ node ~/.claude/bin/qualia-ui.js banner router
84
+ node ~/.claude/bin/qualia-ui.js fail "{blocker description}"
85
+ node ~/.claude/bin/qualia-ui.js warn "Escalate to Fawzi or re-plan from scratch"
86
+ ```
87
+
88
+ User can respond with a number, "just do it", or natural language.
package/skills/qualia-build/SKILL.md ADDED
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: qualia-build
3
+ description: "Execute the current phase — spawns builder subagents per task with wave-based parallelization. Fresh context per task."
4
+ ---
5
+
6
+ # /qualia-build — Build a Phase
7
+
8
+ Execute the phase plan. Each task runs in a fresh subagent context. Independent tasks run in parallel.
9
+
10
+ ## Usage
11
+ `/qualia-build` — build the current planned phase
12
+ `/qualia-build {N}` — build specific phase
13
+
14
+ ## Process
15
+
16
+ ### 1. Load Plan
17
+
18
+ ```bash
19
+ cat .planning/phase-{N}-plan.md
20
+ ```
21
+
22
+ Parse: tasks, waves, file references.
23
+
24
+ ### 1b. Create Recovery Point
25
+
26
+ Before executing any tasks, tag current HEAD for rollback:
27
+
28
+ ```bash
29
+ git tag -f "pre-build-phase-{N}" HEAD 2>/dev/null
30
+ ```
31
+
32
+ ```bash
33
+ node ~/.claude/bin/qualia-ui.js info "Recovery point: pre-build-phase-{N}"
34
+ ```
35
+
36
+ If a wave fails and the user needs to roll back:
37
+ ```bash
38
+ git reset --hard pre-build-phase-{N}
39
+ node ~/.claude/bin/state.js transition --to planned --force
40
+ ```
41
+
42
+ ### 2. Execute Waves
43
+
44
+ ```bash
45
+ node ~/.claude/bin/qualia-ui.js banner build {N} "{phase name}"
46
+ ```
47
+
48
+ **For each wave (sequential):**
49
+
50
+ ```bash
51
+ node ~/.claude/bin/qualia-ui.js wave {W} {total_waves} {tasks_in_wave}
52
+ ```
53
+
54
+ **For each task in the wave (parallel if multiple):**
55
+
56
+ ```bash
57
+ node ~/.claude/bin/qualia-ui.js task {task_num} "{task title}"
58
+ ```
59
+
60
+ Spawn a fresh builder subagent:
61
+
62
+ ```
63
+ Agent(prompt="
64
+ Read your role: @agents/builder.md
65
+
66
+ Project context:
67
+ @.planning/PROJECT.md
68
+
69
+ YOUR TASK:
70
+ {paste the single task block from the plan — title, files, action, context refs, done-when}
71
+
72
+ Execute this task. Read all @file references before writing. Commit when done.
73
+ ", subagent_type="qualia-builder", description="Task {N}: {title}")
74
+ ```
75
+
76
+ **After each task completes:**
77
+ - Verify the commit exists: `git log --oneline -1`
78
+ - Show result:
79
+ ```bash
80
+ node ~/.claude/bin/qualia-ui.js done {task_num} "{title}" {commit_hash}
81
+ ```
82
+
83
+ **After each wave completes:**
84
+ - Move to next wave
85
+ - Show wave summary
86
+
87
+ ### 3. Wave Completion
88
+
89
+ After all waves complete:
90
+
91
+ ```bash
92
+ node ~/.claude/bin/qualia-ui.js divider
93
+ node ~/.claude/bin/qualia-ui.js ok "Tasks: {done}/{total}"
94
+ node ~/.claude/bin/qualia-ui.js ok "Commits: {count}"
95
+ node ~/.claude/bin/qualia-ui.js ok "Waves: {count}"
96
+ ```
97
+
98
+ ### 4. Handle Failures
99
+
100
+ If a builder subagent returns a deviation or blocker:
101
+ - **Minor deviation:** Log it, continue
102
+ - **Major deviation:** Show to employee, ask how to proceed
103
+ - **Blocker:** Show the blocker, suggest fix or escalation
104
+
105
+ ### 5. Update State
106
+
107
+ ```bash
108
+ node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
109
+ ```
110
+ If state.js returns an error, show it to the employee and stop.
111
+ Do NOT manually edit STATE.md or tracking.json — state.js handles both.
112
+
113
+ ```bash
114
+ node ~/.claude/bin/qualia-ui.js end "PHASE {N} BUILT" "/qualia-verify {N}"
115
+ ```
package/skills/qualia-debug/SKILL.md ADDED
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: qualia-debug
3
+ description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
4
+ ---
5
+
6
+ # /qualia-debug — Structured Debugging
7
+
8
+ Systematic debugging. Don't guess — gather symptoms, confirm diagnosis, then fix.
9
+
10
+ ## Usage
11
+
12
+ - `/qualia-debug` — Interactive (gather symptoms, diagnose, fix)
13
+ - `/qualia-debug --frontend` — CSS/layout/visual issues
14
+ - `/qualia-debug --perf` — Performance issues
15
+
16
+ ## Interactive Mode (Default)
17
+
18
+ ```bash
19
+ node ~/.claude/bin/qualia-ui.js banner debug
20
+ ```
21
+
22
+ ### 0. Check Known Fixes First
23
+
24
+ Before gathering symptoms, check if we've seen this before:
25
+
26
+ ```bash
27
+ cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
28
+ ```
29
+
30
+ If the user's description matches a known fix, suggest it first: *"I've seen this before — check {fix title}. Want to try that before we dig deeper?"* Only proceed to full investigation if the known fix doesn't apply.
31
+
32
+ ### 1. Gather Symptoms
33
+
34
+ Ask:
35
+ - What's happening? (exact error or behavior)
36
+ - What should happen instead?
37
+ - When did it start? (after what change?)
38
+ - What have you tried?
39
+
40
+ ### 2. Confirm Diagnosis
41
+
42
+ Before ANY code changes, present your diagnosis:
43
+
44
+ > "Based on the symptoms, I think: [diagnosis]. I'll investigate [specific area]. Does that match what you're seeing?"
45
+
46
+ Wait for confirmation. If user corrects → adjust. Never proceed on a wrong diagnosis.
47
+
48
+ ### 3. Investigate and Fix
49
+
50
+ 1. Reproduce the issue
51
+ 2. Isolate the cause (binary search: which file, which function, which line)
52
+ 3. Identify root cause (not symptoms)
53
+ 4. Implement minimal fix
54
+ 5. Verify fix works
55
+ 6. Check for related issues
56
+
57
+ ### 4. Commit
58
+
59
+ ```bash
60
+ git add {specific files}
61
+ git commit -m "fix: {what was broken and why}"
62
+ ```
63
+
64
+ ## Frontend Mode (`--frontend`)
65
+
66
+ For layout breaks, z-index issues, overflow, animation glitches.
67
+
68
+ **Quick diagnostics:**
69
+ - Z-index not working → element needs `position: relative/absolute/fixed`, check parent stacking contexts
70
+ - Horizontal scroll → use `width: 100%` not `100vw`, find overflowing element
71
+ - Flex overflow → add `min-width: 0`
72
+ - Grid blowout → use `minmax(0, 1fr)`
73
+ - Janky animations → only animate `transform` and `opacity`
74
+ - Safari → `-webkit-backdrop-filter`, `100dvh` not `100vh`
75
+
76
+ ## Performance Mode (`--perf`)
77
+
78
+ ### Investigate
79
+ 1. Profile the bottleneck (network, render, compute, database)
80
+ 2. Measure baseline
81
+ 3. Identify the hot path
82
+
83
+ ### Common fixes
84
+ - Slow queries → check indexes, `EXPLAIN ANALYZE`, optimize joins
85
+ - Large bundles → code split, lazy load, tree shake
86
+ - Slow renders → memoize, virtualize long lists
87
+ - API latency → cache, reduce payload, parallelize requests