qualia-framework 2.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 (261) hide show
  1. package/README.md +50 -0
  2. package/bin/cli.js +519 -0
  3. package/framework/agents/architecture-strategist.md +53 -0
  4. package/framework/agents/backend-agent.md +150 -0
  5. package/framework/agents/code-simplicity-reviewer.md +86 -0
  6. package/framework/agents/frontend-agent.md +111 -0
  7. package/framework/agents/kieran-typescript-reviewer.md +96 -0
  8. package/framework/agents/performance-oracle.md +111 -0
  9. package/framework/agents/qualia-codebase-mapper.md +760 -0
  10. package/framework/agents/qualia-debugger.md +1203 -0
  11. package/framework/agents/qualia-executor.md +881 -0
  12. package/framework/agents/qualia-integration-checker.md +423 -0
  13. package/framework/agents/qualia-phase-researcher.md +453 -0
  14. package/framework/agents/qualia-plan-checker.md +699 -0
  15. package/framework/agents/qualia-planner.md +1241 -0
  16. package/framework/agents/qualia-project-researcher.md +602 -0
  17. package/framework/agents/qualia-research-synthesizer.md +236 -0
  18. package/framework/agents/qualia-roadmapper.md +605 -0
  19. package/framework/agents/qualia-verifier.md +685 -0
  20. package/framework/agents/team-orchestrator.md +228 -0
  21. package/framework/agents/teams/full-stack-team.md +48 -0
  22. package/framework/agents/teams/optimize-team.md +53 -0
  23. package/framework/agents/teams/review-team.md +62 -0
  24. package/framework/agents/teams/ship-team.md +86 -0
  25. package/framework/agents/test-agent.md +182 -0
  26. package/framework/askpass.sh +2 -0
  27. package/framework/commands/design.md +53 -0
  28. package/framework/commands/quick-db.md +22 -0
  29. package/framework/config/retention.json +35 -0
  30. package/framework/core/PRINCIPLES.md +77 -0
  31. package/framework/hooks/auto-format.sh +45 -0
  32. package/framework/hooks/block-env-edit.sh +42 -0
  33. package/framework/hooks/branch-guard.sh +46 -0
  34. package/framework/hooks/confirm-delete.sh +56 -0
  35. package/framework/hooks/migration-validate.sh +68 -0
  36. package/framework/hooks/notification-speak.sh +15 -0
  37. package/framework/hooks/pre-commit.sh +80 -0
  38. package/framework/hooks/pre-compact.sh +55 -0
  39. package/framework/hooks/pre-deploy-gate.sh +151 -0
  40. package/framework/hooks/qualia-colors.sh +32 -0
  41. package/framework/hooks/retention-cleanup.sh +43 -0
  42. package/framework/hooks/save-session-state.sh +153 -0
  43. package/framework/hooks/session-context-loader.sh +28 -0
  44. package/framework/hooks/session-learn.sh +30 -0
  45. package/framework/knowledge/claudecode-bible.md +1384 -0
  46. package/framework/knowledge/client-prefs.md +22 -0
  47. package/framework/knowledge/common-fixes.md +25 -0
  48. package/framework/knowledge/deployment-map.md +35 -0
  49. package/framework/knowledge/email-signature.html +1 -0
  50. package/framework/knowledge/employees.md +8 -0
  51. package/framework/knowledge/learned-patterns.md +51 -0
  52. package/framework/knowledge/optimization-research-2026.md +137 -0
  53. package/framework/knowledge/qualia-context.md +67 -0
  54. package/framework/knowledge/supabase-patterns.md +50 -0
  55. package/framework/knowledge/voice-agent-patterns.md +46 -0
  56. package/framework/qualia-engine/VERSION +1 -0
  57. package/framework/qualia-engine/bin/qualia-tools.js +2160 -0
  58. package/framework/qualia-engine/bin/qualia-tools.test.js +1054 -0
  59. package/framework/qualia-engine/references/checkpoints.md +775 -0
  60. package/framework/qualia-engine/references/continuation-format.md +249 -0
  61. package/framework/qualia-engine/references/decimal-phase-calculation.md +65 -0
  62. package/framework/qualia-engine/references/design-quality.md +56 -0
  63. package/framework/qualia-engine/references/git-integration.md +254 -0
  64. package/framework/qualia-engine/references/git-planning-commit.md +50 -0
  65. package/framework/qualia-engine/references/model-profile-resolution.md +32 -0
  66. package/framework/qualia-engine/references/model-profiles.md +73 -0
  67. package/framework/qualia-engine/references/phase-argument-parsing.md +61 -0
  68. package/framework/qualia-engine/references/planning-config.md +195 -0
  69. package/framework/qualia-engine/references/questioning.md +141 -0
  70. package/framework/qualia-engine/references/tdd.md +263 -0
  71. package/framework/qualia-engine/references/ui-brand.md +160 -0
  72. package/framework/qualia-engine/references/verification-patterns.md +612 -0
  73. package/framework/qualia-engine/templates/DEBUG.md +159 -0
  74. package/framework/qualia-engine/templates/DESIGN.md +81 -0
  75. package/framework/qualia-engine/templates/UAT.md +247 -0
  76. package/framework/qualia-engine/templates/codebase/architecture.md +255 -0
  77. package/framework/qualia-engine/templates/codebase/concerns.md +310 -0
  78. package/framework/qualia-engine/templates/codebase/conventions.md +307 -0
  79. package/framework/qualia-engine/templates/codebase/integrations.md +280 -0
  80. package/framework/qualia-engine/templates/codebase/stack.md +186 -0
  81. package/framework/qualia-engine/templates/codebase/structure.md +285 -0
  82. package/framework/qualia-engine/templates/codebase/testing.md +480 -0
  83. package/framework/qualia-engine/templates/config.json +35 -0
  84. package/framework/qualia-engine/templates/context.md +283 -0
  85. package/framework/qualia-engine/templates/continue-here.md +78 -0
  86. package/framework/qualia-engine/templates/debug-subagent-prompt.md +91 -0
  87. package/framework/qualia-engine/templates/discovery.md +146 -0
  88. package/framework/qualia-engine/templates/milestone-archive.md +123 -0
  89. package/framework/qualia-engine/templates/milestone.md +115 -0
  90. package/framework/qualia-engine/templates/phase-prompt.md +567 -0
  91. package/framework/qualia-engine/templates/planner-subagent-prompt.md +117 -0
  92. package/framework/qualia-engine/templates/project.md +184 -0
  93. package/framework/qualia-engine/templates/projects/ai-agent.md +156 -0
  94. package/framework/qualia-engine/templates/projects/mobile-app.md +181 -0
  95. package/framework/qualia-engine/templates/projects/voice-agent.md +134 -0
  96. package/framework/qualia-engine/templates/projects/website.md +137 -0
  97. package/framework/qualia-engine/templates/requirements.md +231 -0
  98. package/framework/qualia-engine/templates/research-project/ARCHITECTURE.md +204 -0
  99. package/framework/qualia-engine/templates/research-project/FEATURES.md +147 -0
  100. package/framework/qualia-engine/templates/research-project/PITFALLS.md +200 -0
  101. package/framework/qualia-engine/templates/research-project/STACK.md +120 -0
  102. package/framework/qualia-engine/templates/research-project/SUMMARY.md +170 -0
  103. package/framework/qualia-engine/templates/research.md +552 -0
  104. package/framework/qualia-engine/templates/roadmap.md +202 -0
  105. package/framework/qualia-engine/templates/state.md +176 -0
  106. package/framework/qualia-engine/templates/summary-complex.md +59 -0
  107. package/framework/qualia-engine/templates/summary-minimal.md +41 -0
  108. package/framework/qualia-engine/templates/summary-standard.md +48 -0
  109. package/framework/qualia-engine/templates/summary.md +246 -0
  110. package/framework/qualia-engine/templates/user-setup.md +311 -0
  111. package/framework/qualia-engine/templates/verification-report.md +322 -0
  112. package/framework/qualia-engine/workflows/add-phase.md +179 -0
  113. package/framework/qualia-engine/workflows/add-todo.md +157 -0
  114. package/framework/qualia-engine/workflows/audit-milestone.md +241 -0
  115. package/framework/qualia-engine/workflows/check-todos.md +176 -0
  116. package/framework/qualia-engine/workflows/complete-milestone.md +858 -0
  117. package/framework/qualia-engine/workflows/diagnose-issues.md +219 -0
  118. package/framework/qualia-engine/workflows/discovery-phase.md +289 -0
  119. package/framework/qualia-engine/workflows/discuss-phase.md +534 -0
  120. package/framework/qualia-engine/workflows/execute-phase.md +559 -0
  121. package/framework/qualia-engine/workflows/execute-plan.md +438 -0
  122. package/framework/qualia-engine/workflows/help.md +470 -0
  123. package/framework/qualia-engine/workflows/insert-phase.md +220 -0
  124. package/framework/qualia-engine/workflows/list-phase-assumptions.md +178 -0
  125. package/framework/qualia-engine/workflows/map-codebase.md +327 -0
  126. package/framework/qualia-engine/workflows/new-milestone.md +363 -0
  127. package/framework/qualia-engine/workflows/new-project.md +1037 -0
  128. package/framework/qualia-engine/workflows/pause-work.md +122 -0
  129. package/framework/qualia-engine/workflows/plan-milestone-gaps.md +256 -0
  130. package/framework/qualia-engine/workflows/plan-phase.md +422 -0
  131. package/framework/qualia-engine/workflows/progress.md +354 -0
  132. package/framework/qualia-engine/workflows/quick.md +252 -0
  133. package/framework/qualia-engine/workflows/remove-phase.md +326 -0
  134. package/framework/qualia-engine/workflows/research-phase.md +74 -0
  135. package/framework/qualia-engine/workflows/resume-project.md +306 -0
  136. package/framework/qualia-engine/workflows/set-profile.md +80 -0
  137. package/framework/qualia-engine/workflows/settings.md +145 -0
  138. package/framework/qualia-engine/workflows/transition.md +556 -0
  139. package/framework/qualia-engine/workflows/update.md +197 -0
  140. package/framework/qualia-engine/workflows/verify-phase.md +195 -0
  141. package/framework/qualia-engine/workflows/verify-work.md +625 -0
  142. package/framework/rules/context7.md +11 -0
  143. package/framework/rules/deployment.md +29 -0
  144. package/framework/rules/frontend.md +33 -0
  145. package/framework/rules/security.md +12 -0
  146. package/framework/rules/speed.md +20 -0
  147. package/framework/scripts/__pycache__/say.cpython-314.pyc +0 -0
  148. package/framework/scripts/apply-retention.sh +120 -0
  149. package/framework/scripts/bootstrap-pop-os.sh +354 -0
  150. package/framework/scripts/claude-voice +13 -0
  151. package/framework/scripts/cleanup.sh +131 -0
  152. package/framework/scripts/cowork-mode.sh +141 -0
  153. package/framework/scripts/generate-project-claude-md.sh +153 -0
  154. package/framework/scripts/load-test-webhook.js +172 -0
  155. package/framework/scripts/say.py +236 -0
  156. package/framework/scripts/showcase-video-recorder/ffmpeg-builder.js +167 -0
  157. package/framework/scripts/showcase-video-recorder/playwright-helpers.js +216 -0
  158. package/framework/scripts/speak.py +55 -0
  159. package/framework/scripts/speak.sh +18 -0
  160. package/framework/scripts/status.sh +138 -0
  161. package/framework/scripts/sync-to-framework.sh +65 -0
  162. package/framework/scripts/voice-hotkey.py +227 -0
  163. package/framework/scripts/voice-input.sh +51 -0
  164. package/framework/skills/animate/SKILL.md +202 -0
  165. package/framework/skills/bolder/SKILL.md +144 -0
  166. package/framework/skills/browser-qa/SKILL.md +536 -0
  167. package/framework/skills/clarify/SKILL.md +179 -0
  168. package/framework/skills/colorize/SKILL.md +170 -0
  169. package/framework/skills/critique/SKILL.md +126 -0
  170. package/framework/skills/deep-research/SKILL.md +271 -0
  171. package/framework/skills/delight/SKILL.md +329 -0
  172. package/framework/skills/deploy/SKILL.md +261 -0
  173. package/framework/skills/deploy-verify/SKILL.md +377 -0
  174. package/framework/skills/deploy-verify/scripts/canary-check.sh +206 -0
  175. package/framework/skills/deploy-verify/scripts/check-console-errors.js +147 -0
  176. package/framework/skills/deploy-verify/scripts/check-cwv.js +139 -0
  177. package/framework/skills/deploy-verify/scripts/project-detect.sh +84 -0
  178. package/framework/skills/deploy-verify/scripts/verify.sh +548 -0
  179. package/framework/skills/design-quieter/SKILL.md +130 -0
  180. package/framework/skills/distill/SKILL.md +149 -0
  181. package/framework/skills/docs-lookup/SKILL.md +78 -0
  182. package/framework/skills/fcm-notifications/SKILL.md +125 -0
  183. package/framework/skills/financial-ledger/SKILL.md +1039 -0
  184. package/framework/skills/frontend-master/NOTICE.md +4 -0
  185. package/framework/skills/frontend-master/SKILL.md +127 -0
  186. package/framework/skills/frontend-master/reference/color-and-contrast.md +132 -0
  187. package/framework/skills/frontend-master/reference/interaction-design.md +123 -0
  188. package/framework/skills/frontend-master/reference/motion-design.md +99 -0
  189. package/framework/skills/frontend-master/reference/responsive-design.md +114 -0
  190. package/framework/skills/frontend-master/reference/spatial-design.md +100 -0
  191. package/framework/skills/frontend-master/reference/typography.md +131 -0
  192. package/framework/skills/frontend-master/reference/ux-writing.md +107 -0
  193. package/framework/skills/harden/SKILL.md +357 -0
  194. package/framework/skills/i18n-rtl/SKILL.md +752 -0
  195. package/framework/skills/learn/SKILL.md +71 -0
  196. package/framework/skills/memory/SKILL.md +50 -0
  197. package/framework/skills/mobile-expo/SKILL.md +864 -0
  198. package/framework/skills/mobile-expo/references/store-checklist.md +550 -0
  199. package/framework/skills/nestjs-backend/README.md +73 -0
  200. package/framework/skills/nestjs-backend/SKILL.md +446 -0
  201. package/framework/skills/nestjs-backend/references/templates.md +1173 -0
  202. package/framework/skills/normalize/SKILL.md +79 -0
  203. package/framework/skills/onboard/SKILL.md +242 -0
  204. package/framework/skills/polish/SKILL.md +209 -0
  205. package/framework/skills/pr/SKILL.md +66 -0
  206. package/framework/skills/qualia/SKILL.md +153 -0
  207. package/framework/skills/qualia-add-todo/SKILL.md +68 -0
  208. package/framework/skills/qualia-audit-milestone/SKILL.md +92 -0
  209. package/framework/skills/qualia-check-todos/SKILL.md +55 -0
  210. package/framework/skills/qualia-complete-milestone/SKILL.md +108 -0
  211. package/framework/skills/qualia-debug/SKILL.md +149 -0
  212. package/framework/skills/qualia-design/SKILL.md +203 -0
  213. package/framework/skills/qualia-discuss-phase/SKILL.md +72 -0
  214. package/framework/skills/qualia-execute-phase/SKILL.md +86 -0
  215. package/framework/skills/qualia-help/SKILL.md +67 -0
  216. package/framework/skills/qualia-idk/SKILL.md +352 -0
  217. package/framework/skills/qualia-list-phase-assumptions/SKILL.md +67 -0
  218. package/framework/skills/qualia-new-milestone/SKILL.md +72 -0
  219. package/framework/skills/qualia-new-project/SKILL.md +92 -0
  220. package/framework/skills/qualia-optimize/SKILL.md +417 -0
  221. package/framework/skills/qualia-pause-work/SKILL.md +96 -0
  222. package/framework/skills/qualia-plan-milestone-gaps/SKILL.md +57 -0
  223. package/framework/skills/qualia-plan-phase/SKILL.md +101 -0
  224. package/framework/skills/qualia-progress/SKILL.md +53 -0
  225. package/framework/skills/qualia-quick/SKILL.md +89 -0
  226. package/framework/skills/qualia-research-phase/SKILL.md +88 -0
  227. package/framework/skills/qualia-resume-work/SKILL.md +62 -0
  228. package/framework/skills/qualia-review/SKILL.md +263 -0
  229. package/framework/skills/qualia-start/SKILL.md +182 -0
  230. package/framework/skills/qualia-verify-work/SKILL.md +105 -0
  231. package/framework/skills/qualia-workflow/SKILL.md +130 -0
  232. package/framework/skills/rag/SKILL.md +750 -0
  233. package/framework/skills/responsive/SKILL.md +231 -0
  234. package/framework/skills/retro/SKILL.md +284 -0
  235. package/framework/skills/sakani-conventions/SKILL.md +136 -0
  236. package/framework/skills/sakani-conventions/evals/evals.json +23 -0
  237. package/framework/skills/sakani-conventions/references/entities.md +365 -0
  238. package/framework/skills/sakani-conventions/references/error-codes.md +95 -0
  239. package/framework/skills/seo-master/SKILL.md +490 -0
  240. package/framework/skills/seo-master/references/checklist.md +199 -0
  241. package/framework/skills/seo-master/references/structured-data.md +609 -0
  242. package/framework/skills/ship/SKILL.md +202 -0
  243. package/framework/skills/stack-researcher/SKILL.md +215 -0
  244. package/framework/skills/status/SKILL.md +154 -0
  245. package/framework/skills/status/scripts/health-check.sh +562 -0
  246. package/framework/skills/subscription-payments/SKILL.md +250 -0
  247. package/framework/skills/supabase/SKILL.md +973 -0
  248. package/framework/skills/supabase/references/templates.md +159 -0
  249. package/framework/skills/team/SKILL.md +67 -0
  250. package/framework/skills/test-runner/SKILL.md +202 -0
  251. package/framework/skills/voice-agent/SKILL.md +407 -0
  252. package/framework/skills/zoho-workflow/SKILL.md +51 -0
  253. package/framework/statusline-command.sh +117 -0
  254. package/package.json +24 -0
  255. package/profiles/fawzi.json +16 -0
  256. package/profiles/hasan.json +16 -0
  257. package/profiles/moayad.json +16 -0
  258. package/templates/CLAUDE-owner.md +52 -0
  259. package/templates/CLAUDE.md.hbs +58 -0
  260. package/templates/env.claude.template +12 -0
  261. package/templates/settings.json +141 -0
@@ -0,0 +1,231 @@
1
+ ---
2
+ name: responsive
3
+ description: Deep responsive design expert. Analyzes and fixes layouts for all screens - mobile, tablet, desktop, ultrawide. Understands breakpoints, container queries, fluid typography, and touch targets.
4
+ tags: [responsive, mobile, layout, breakpoints, accessibility]
5
+ ---
6
+
7
+ # Responsive Design Expert
8
+
9
+ I make your UI work perfectly on every screen size.
10
+
11
+ ## What I Do
12
+
13
+ 1. **Audit current responsiveness** - Find what breaks
14
+ 2. **Fix layout issues** - Overflow, cramped content, tiny text
15
+ 3. **Optimize touch targets** - 44px minimum for mobile
16
+ 4. **Apply fluid scaling** - Typography, spacing, containers
17
+ 5. **Test edge cases** - Landscape phones, tablets, ultrawides
18
+
19
+ ## How to Use
20
+
21
+ - "Make this page responsive"
22
+ - "Fix the mobile layout"
23
+ - "The navbar breaks on tablet"
24
+ - "This looks bad on ultrawide"
25
+
26
+ I'll analyze and fix it.
27
+
28
+ ## My Analysis Process
29
+
30
+ ### 1. Find Breaking Points
31
+ ```
32
+ - Scan for fixed widths (px values that should be fluid)
33
+ - Check for horizontal overflow
34
+ - Find text that gets too small or too large
35
+ - Identify touch targets under 44px
36
+ - Look for images without max-width
37
+ ```
38
+
39
+ ### 2. Check Key Breakpoints
40
+ ```
41
+ 320px - Small phones (iPhone SE)
42
+ 375px - Standard phones
43
+ 428px - Large phones (iPhone Pro Max)
44
+ 768px - Tablets portrait
45
+ 1024px - Tablets landscape / small laptops
46
+ 1280px - Laptops
47
+ 1536px - Desktops
48
+ 1920px - Large desktops
49
+ 2560px - Ultrawides
50
+ ```
51
+
52
+ ### 3. Test Interactions
53
+ ```
54
+ - Hover states need touch alternatives
55
+ - Dropdowns need mobile-friendly triggers
56
+ - Modals need proper mobile sizing
57
+ - Forms need appropriate input sizes
58
+ ```
59
+
60
+ ## Common Fixes I Apply
61
+
62
+ ### Layout
63
+ ```css
64
+ /* Fluid container — full width with responsive padding */
65
+ .container {
66
+ width: 100%;
67
+ padding-inline: clamp(1rem, 5vw, 4rem);
68
+ margin-inline: auto;
69
+ }
70
+
71
+ /* Content container — for readable text sections only */
72
+ .container-prose {
73
+ max-width: 65ch;
74
+ margin-inline: auto;
75
+ }
76
+
77
+ /* Responsive grid */
78
+ .grid {
79
+ display: grid;
80
+ grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
81
+ gap: clamp(1rem, 3vw, 2rem);
82
+ }
83
+
84
+ /* Stack on mobile */
85
+ .flex-row {
86
+ display: flex;
87
+ flex-direction: column;
88
+ @media (min-width: 768px) {
89
+ flex-direction: row;
90
+ }
91
+ }
92
+ ```
93
+
94
+ ### Typography
95
+ ```css
96
+ /* Fluid type scale */
97
+ .heading {
98
+ font-size: clamp(1.5rem, 4vw + 1rem, 3rem);
99
+ }
100
+
101
+ .body {
102
+ font-size: clamp(1rem, 0.5vw + 0.875rem, 1.125rem);
103
+ }
104
+
105
+ /* Readable line length */
106
+ .prose {
107
+ max-width: 65ch;
108
+ }
109
+ ```
110
+
111
+ ### Spacing
112
+ ```css
113
+ /* Fluid spacing */
114
+ .section {
115
+ padding-block: clamp(2rem, 8vw, 6rem);
116
+ padding-inline: clamp(1rem, 5vw, 3rem);
117
+ }
118
+ ```
119
+
120
+ ### Images
121
+ ```css
122
+ img {
123
+ max-width: 100%;
124
+ height: auto;
125
+ display: block;
126
+ }
127
+
128
+ /* Responsive aspect ratio */
129
+ .hero-image {
130
+ aspect-ratio: 16/9;
131
+ @media (max-width: 768px) {
132
+ aspect-ratio: 4/3;
133
+ }
134
+ }
135
+ ```
136
+
137
+ ### Touch Targets
138
+ ```css
139
+ /* Minimum touch target */
140
+ button, a, input {
141
+ min-height: 44px;
142
+ min-width: 44px;
143
+ }
144
+
145
+ /* Spacing between targets */
146
+ .nav-links {
147
+ gap: 0.5rem; /* At least 8px between */
148
+ }
149
+ ```
150
+
151
+ ## Container Queries (Modern Approach)
152
+
153
+ ```css
154
+ /* Component responds to its container, not viewport */
155
+ .card-container {
156
+ container-type: inline-size;
157
+ }
158
+
159
+ @container (width < 300px) {
160
+ .card { flex-direction: column; }
161
+ .card-image { aspect-ratio: 16/9; }
162
+ }
163
+
164
+ @container (width >= 300px) {
165
+ .card { flex-direction: row; }
166
+ .card-image { width: 120px; }
167
+ }
168
+ ```
169
+
170
+ ## Mobile-First Checklist
171
+
172
+ - [ ] Base styles work without media queries
173
+ - [ ] Text readable without zooming (16px+ body)
174
+ - [ ] Touch targets 44px+
175
+ - [ ] No horizontal scroll
176
+ - [ ] Forms have proper input types
177
+ - [ ] Images scale down
178
+ - [ ] Modals fit screen
179
+ - [ ] Navigation accessible
180
+ - [ ] Focus states visible
181
+ - [ ] Landscape orientation works
182
+
183
+ ## Red Flags I Look For
184
+
185
+ ```
186
+ ❌ width: 500px (fixed widths)
187
+ ❌ font-size: 12px (too small for mobile)
188
+ ❌ height: 100vh on mobile (iOS issues)
189
+ ❌ hover-only interactions
190
+ ❌ Tiny close buttons
191
+ ❌ Side-by-side on mobile
192
+ ❌ Overflow: hidden hiding content
193
+ ❌ Position: fixed without mobile consideration
194
+ ```
195
+
196
+ ## Tailwind Responsive Patterns
197
+
198
+ ```html
199
+ <!-- Mobile-first stacking -->
200
+ <div class="flex flex-col md:flex-row gap-4">
201
+
202
+ <!-- Responsive text -->
203
+ <h1 class="text-2xl sm:text-3xl md:text-4xl lg:text-5xl">
204
+
205
+ <!-- Responsive padding -->
206
+ <section class="px-4 sm:px-6 lg:px-8 py-12 md:py-20">
207
+
208
+ <!-- Hide/show -->
209
+ <div class="hidden md:block">Desktop only</div>
210
+ <div class="md:hidden">Mobile only</div>
211
+
212
+ <!-- Responsive grid -->
213
+ <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
214
+ ```
215
+
216
+ ## I Test At These Widths
217
+
218
+ 1. **320px** - Does it fit? Is text readable?
219
+ 2. **375px** - Standard mobile, should look good
220
+ 3. **768px** - Tablet, layout should adapt
221
+ 4. **1024px** - Small desktop, full features
222
+ 5. **1440px** - Standard desktop
223
+ 6. **1920px+** - Should it max-width or fill?
224
+
225
+ ## Output
226
+
227
+ I provide:
228
+ 1. List of issues found
229
+ 2. Specific fixes with code
230
+ 3. Before/after mental model
231
+ 4. Priority order (critical → nice-to-have)
@@ -0,0 +1,284 @@
1
+ ---
2
+ name: retro
3
+ description: "Generate retrospective analytics from git log, session data, and SUMMARY files. Produces a markdown trend report with commits per session, lines added/removed, test ratio, deviation rate, hotspot files, and shipping velocity. Run from any project directory or ~/.claude for cross-project view."
4
+ user-invocable: true
5
+ args:
6
+ - name: weeks
7
+ description: "Number of weeks to analyze (default: 4)"
8
+ required: false
9
+ - name: project
10
+ description: "Specific project name to filter (default: current directory)"
11
+ required: false
12
+ ---
13
+
14
+ # Retrospective Analytics
15
+
16
+ > Team-level shipping analytics. No individual attribution. Outcome-focused.
17
+
18
+ Generate a retrospective report showing how shipping patterns evolve over time. All metrics are aggregate -- no per-developer breakdowns or policing metrics (RETR-05).
19
+
20
+ ## Usage
21
+
22
+ - `/retro` -- Analyze current project, last 4 weeks
23
+ - `/retro --weeks 8` -- Analyze current project, last 8 weeks
24
+ - `/retro --project under` -- Analyze specific project, last 4 weeks
25
+
26
+ ## Data Sources
27
+
28
+ Collect data from three sources. If a source is unavailable, skip it and note "N/A" in the report.
29
+
30
+ ### Source 1: Git Log
31
+
32
+ Run from the current project directory (or the project specified by `--project`):
33
+
34
+ ```bash
35
+ # Commits in date range
36
+ git log --since="{WEEKS} weeks ago" --format="%H|%aI|%s" --no-merges
37
+
38
+ # Lines added/removed per commit
39
+ git log --since="{WEEKS} weeks ago" --format="%H" --no-merges | while read hash; do
40
+ git diff --shortstat "${hash}^..${hash}" 2>/dev/null
41
+ done
42
+
43
+ # File change frequency (hotspots)
44
+ git log --since="{WEEKS} weeks ago" --name-only --format="" --no-merges | sort | uniq -c | sort -rn | head -15
45
+
46
+ # Test file vs source file ratio in commits
47
+ git log --since="{WEEKS} weeks ago" --name-only --format="" --no-merges | grep -c '\.test\.\|\.spec\.\|test_\|_test\.'
48
+ git log --since="{WEEKS} weeks ago" --name-only --format="" --no-merges | grep -c '\.\(ts\|tsx\|js\|jsx\|py\)$'
49
+ ```
50
+
51
+ ### Source 2: Session Data
52
+
53
+ Read session JSON files from `~/.claude/session-env/session_*.json`:
54
+
55
+ ```bash
56
+ # List all session files
57
+ ls -t ~/.claude/session-env/session_*.json
58
+
59
+ # Each file contains: timestamp, project, branch, files_changed, summary
60
+ # Parse with jq or grep to extract metrics
61
+ ```
62
+
63
+ Also read `~/.claude/knowledge/session-digest.md` for the rolling session log (pipe-delimited table with date, project, branch, files_changed, summary).
64
+
65
+ **Session detection heuristic:** Each `session_*.json` file = one session. Count files matching the date range.
66
+
67
+ ### Source 3: SUMMARY Files
68
+
69
+ Scan for SUMMARY files in the current project's `.planning/phases/` directory:
70
+
71
+ ```bash
72
+ # Find all SUMMARY files
73
+ find .planning/phases/ -name "*-SUMMARY.md" -type f 2>/dev/null
74
+
75
+ # From each SUMMARY, extract:
76
+ # - Duration (from frontmatter or body)
77
+ # - Deviation count (from "## Deviations" or "## Deferred Discoveries" sections)
78
+ # - Task count (from provides/affects lists)
79
+ ```
80
+
81
+ ## Metric Calculations
82
+
83
+ Calculate these 6 metrics from collected data:
84
+
85
+ ### M1: Commits Per Session
86
+ ```
87
+ commits_per_session = total_commits / total_sessions
88
+ ```
89
+ Where `total_sessions` = count of session_*.json files matching the project and date range. If session data unavailable, report "N/A (no session data)".
90
+
91
+ ### M2: Lines Added / Removed
92
+ ```
93
+ lines_added = sum of insertions from git shortstat
94
+ lines_removed = sum of deletions from git shortstat
95
+ net_lines = lines_added - lines_removed
96
+ churn_ratio = lines_removed / lines_added (lower = more additive work)
97
+ ```
98
+
99
+ ### M3: Test Ratio
100
+ ```
101
+ test_ratio = test_file_changes / total_source_file_changes
102
+ ```
103
+ Where test files match `*.test.*`, `*.spec.*`, `test_*`, `_test.*` and source files match `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.py`. Report as percentage: "23% of file changes include tests".
104
+
105
+ ### M4: Deviation Rate
106
+ ```
107
+ deviation_rate = total_deviations / total_tasks_completed
108
+ ```
109
+ Parse from SUMMARY files. Deviations appear under `## Deviations` or `## Deferred Discoveries` sections. If no SUMMARY files exist, report "N/A (no planning data)".
110
+
111
+ ### M5: Hotspot Files
112
+ Top 10 most frequently changed files in the period. Flag files with >5 changes as "high churn" -- these may indicate architectural issues or high-risk areas.
113
+
114
+ ### M6: Shipping Velocity
115
+ ```
116
+ plans_per_week = completed_plans / weeks_analyzed
117
+ commits_per_week = total_commits / weeks_analyzed
118
+ ```
119
+ Completed plans = count of SUMMARY files created in the date range (by file modification time). Commits per week from git log.
120
+
121
+ ## Report Template
122
+
123
+ Generate the report in this exact format:
124
+
125
+ ```markdown
126
+ # Retrospective Report
127
+
128
+ **Project:** {project_name}
129
+ **Period:** {start_date} to {end_date} ({weeks} weeks)
130
+ **Generated:** {current_date}
131
+
132
+ ## Metrics Summary
133
+
134
+ | Metric | Value | vs Last |
135
+ |--------|-------|---------|
136
+ | Commits/Session | {value} | {computed_trend} |
137
+ | Lines Added | {value} | {computed_trend} |
138
+ | Lines Removed | {value} | {computed_trend} |
139
+ | Net Lines | {value} | {computed_trend} |
140
+ | Test Ratio | {value}% | {computed_trend} |
141
+ | Deviation Rate | {value}% | {computed_trend} |
142
+ | Plans/Week | {value} | {computed_trend} |
143
+ | Commits/Week | {value} | {computed_trend} |
144
+
145
+ ## Hotspot Files
146
+
147
+ | Rank | File | Changes | Status |
148
+ |------|------|---------|--------|
149
+ | 1 | {file} | {count} | {normal|high churn} |
150
+ | ... | ... | ... | ... |
151
+
152
+ ## Observations
153
+
154
+ {Auto-generated observations based on data:}
155
+ - {If test ratio < 20%: "Low test coverage in commits -- consider TDD for new features"}
156
+ - {If churn_ratio > 0.5: "High code churn -- significant rewrites happening"}
157
+ - {If any hotspot > 10 changes: "{file} is a hotspot with {N} changes -- consider splitting"}
158
+ - {If deviation_rate > 30%: "High deviation rate -- plans may need better scoping"}
159
+ - {If commits_per_session < 1: "Low commit frequency -- consider more atomic commits"}
160
+
161
+ ## Raw Data
162
+
163
+ <details>
164
+ <summary>Data sources used</summary>
165
+
166
+ - Git log: {commit_count} commits analyzed
167
+ - Sessions: {session_count} sessions found
168
+ - SUMMARYs: {summary_count} plan summaries parsed
169
+ </details>
170
+ ```
171
+
172
+ The "vs Last" column shows week-over-week deltas computed from prior JSON snapshots in `~/.claude/knowledge/retros/`. First run shows "---" for all trends.
173
+
174
+ ## Snapshot Storage
175
+
176
+ After generating the report, save a JSON snapshot for trend tracking:
177
+
178
+ ```bash
179
+ mkdir -p ~/.claude/knowledge/retros
180
+ ```
181
+
182
+ Save to `~/.claude/knowledge/retros/retro_{project}_{YYYYMMDD}.json`:
183
+
184
+ ```json
185
+ {
186
+ "project": "{project_name}",
187
+ "date": "{YYYY-MM-DD}",
188
+ "period_weeks": {weeks},
189
+ "metrics": {
190
+ "commits_per_session": {value},
191
+ "lines_added": {value},
192
+ "lines_removed": {value},
193
+ "net_lines": {value},
194
+ "test_ratio": {value},
195
+ "deviation_rate": {value},
196
+ "plans_per_week": {value},
197
+ "commits_per_week": {value}
198
+ },
199
+ "hotspots": [
200
+ {"file": "{path}", "changes": {count}}
201
+ ]
202
+ }
203
+ ```
204
+
205
+ This snapshot is consumed by week-over-week trend analysis (see below).
206
+
207
+ ## Week-over-Week Trend Analysis
208
+
209
+ After collecting current metrics, load prior snapshots to compute deltas (RETR-03).
210
+
211
+ ### Loading Prior Snapshots
212
+
213
+ ```bash
214
+ # Find the most recent prior snapshot for this project
215
+ ls -t ~/.claude/knowledge/retros/retro_{project}_*.json 2>/dev/null | head -2
216
+ ```
217
+
218
+ Read the **second most recent** snapshot (the most recent will be the one about to be saved). If no prior snapshot exists, set all trends to "---" (first run, no comparison available).
219
+
220
+ ### Computing Deltas
221
+
222
+ For each metric, calculate:
223
+
224
+ ```
225
+ delta = current_value - prior_value
226
+ delta_pct = ((current_value - prior_value) / prior_value) * 100
227
+ ```
228
+
229
+ ### Trend Formatting
230
+
231
+ Format each trend using direction arrow + magnitude:
232
+
233
+ | Condition | Format | Example |
234
+ |-----------|--------|---------|
235
+ | delta_pct > 10% | {arrow_up} +{delta_pct}% | ^ +25% |
236
+ | delta_pct between -10% and +10% | {arrow_right} ~{delta_pct}% | ~ ~3% |
237
+ | delta_pct < -10% | {arrow_down} {delta_pct}% | v -15% |
238
+ | No prior data | --- | --- |
239
+ | Prior value was 0 | NEW | NEW |
240
+
241
+ Use text arrows: `^` for up, `v` for down, `~` for flat. Do NOT use unicode arrows (they render inconsistently in terminals).
242
+
243
+ **Trend interpretation context (add after each metric in the report):**
244
+
245
+ - Commits/Session: higher is neutral (more granular work), lower is neutral (bigger chunks)
246
+ - Lines Added: higher may mean new features, lower may mean maintenance mode
247
+ - Lines Removed: higher means cleanup/refactoring is happening
248
+ - Test Ratio: higher is GOOD (more testing), lower is CONCERNING
249
+ - Deviation Rate: lower is GOOD (better planning), higher is CONCERNING
250
+ - Plans/Week: higher means faster shipping velocity
251
+ - Commits/Week: higher is neutral (activity indicator only)
252
+
253
+ ### Trend Summary
254
+
255
+ Add a "## Trend Summary" section to the report, after the metrics table:
256
+
257
+ ```markdown
258
+ ## Trend Summary
259
+
260
+ **Compared to:** {prior_snapshot_date}
261
+
262
+ **Positive signals:**
263
+ - {List metrics trending in desirable direction, e.g., "Test ratio up 15% -- more tests being written"}
264
+
265
+ **Watch items:**
266
+ - {List metrics trending in concerning direction, e.g., "Deviation rate up 20% -- plans may need better scoping"}
267
+
268
+ **Stable:**
269
+ - {List metrics within +/-10%}
270
+ ```
271
+
272
+ If no prior snapshot exists, replace the Trend Summary with:
273
+
274
+ ```markdown
275
+ ## Trend Summary
276
+
277
+ First retrospective run -- no prior data for comparison. Run `/retro` again next week to see trends.
278
+ ```
279
+
280
+ ## Guardrails
281
+
282
+ - **No individual attribution:** Never break down metrics by author. All metrics are project-level aggregate (RETR-05).
283
+ - **Graceful degradation:** If git log fails (not a git repo), report only session data. If session data missing, report only git data. If both missing, report error with instructions.
284
+ - **No policing metrics:** No "lines per hour", "commits per day per person", or productivity scoring. Focus on outcomes: what shipped, what's changing, what needs attention.
@@ -0,0 +1,136 @@
1
+ ---
2
+ name: sakani-conventions
3
+ description: "Sakani project conventions — monorepo structure, shared types, error codes, entity naming, role definitions, and domain rules from SRS V1.14. Use this skill whenever working on the Sakani project, including backend, mobile, admin console, or any shared code. Trigger on: sakani, building management, property management, tenant, owner, guard, building manager, dues, ledger, or any reference to the Sakani codebase."
4
+ tags: [sakani, conventions, domain, property-management]
5
+ ---
6
+
7
+ # Sakani Project Conventions
8
+
9
+ Sakani is a property management platform for Jordan. Native iOS/Android app (React Native Expo) + NestJS backend + Next.js staff admin console + Supabase (Postgres). This skill defines project-wide conventions that all other skills reference.
10
+
11
+ ## Monorepo Structure
12
+
13
+ ```
14
+ sakani/
15
+ ├── apps/
16
+ │ ├── mobile/ # React Native Expo (iOS + Android)
17
+ │ ├── api/ # NestJS backend
18
+ │ └── admin/ # Next.js staff admin console
19
+ ├── packages/
20
+ │ ├── shared/ # Shared types, constants, validation
21
+ │ │ ├── src/
22
+ │ │ │ ├── types/ # Domain entity types
23
+ │ │ │ ├── constants/ # Error codes, role definitions, enums
24
+ │ │ │ ├── validation/ # Zod schemas shared across apps
25
+ │ │ │ └── utils/ # Pure utility functions
26
+ │ │ └── package.json
27
+ │ └── config/ # Shared ESLint, TS configs
28
+ ├── supabase/
29
+ │ ├── migrations/ # SQL migrations (source of truth)
30
+ │ └── functions/ # Edge Functions (background jobs)
31
+ ├── docs/ # Reference docs (gitignored)
32
+ ├── turbo.json
33
+ ├── package.json
34
+ └── .gitignore
35
+ ```
36
+
37
+ Import convention: `@sakani/shared` resolves to `packages/shared`. All apps import domain types and validation from here — never duplicate type definitions across apps.
38
+
39
+ ## User Roles
40
+
41
+ 8 roles with RBAC+ABAC hybrid. Deny-by-default — every action requires explicit grant.
42
+
43
+ | Role | Code | Scope | Description |
44
+ |------|------|-------|-------------|
45
+ | Staff Admin | `STAFF_ADMIN` | Global | Verification governance, audited overrides |
46
+ | BM Candidate | `BM_CANDIDATE` | Building | Initial building manager, pre-verification |
47
+ | BM Verified | `BM_VERIFIED` | Building | Verified building manager, full ops access |
48
+ | Owner Unverified | `OWNER_UNVERIFIED` | Unit | Pending ownership verification |
49
+ | Owner Verified | `OWNER_VERIFIED` | Unit | Verified owner (one per unit) |
50
+ | Tenant | `TENANT` | Unit | Invite-only, unit-scoped, cannot browse |
51
+ | Guard | `GUARD` | Building | Building ops, timed tasks, calendar |
52
+ | Dev Admin | `DEV_ADMIN` | Building | Pre-handover only, identity doc access |
53
+
54
+ Scopes: `S` (self), `U` (unit), `B` (building), `G` (global). Server-side predicates enforce all scope rules — UI conventions are display-only, never security boundaries.
55
+
56
+ ## Entity Naming
57
+
58
+ All entities use `snake_case` in the database and API. TypeScript types use `PascalCase`. Properties use `camelCase` in TypeScript, `snake_case` in API responses.
59
+
60
+ ### Core Entities
61
+
62
+ Read `references/entities.md` for the full entity list with field definitions. Key entities:
63
+
64
+ **Identity:** `building`, `unit`, `unit_claim_request`, `building_setup_request`, `unit_membership`, `building_role_assignment`, `document`
65
+
66
+ **Finance:** `dues_cycle`, `dues_config`, `dues_obligation`, `ledger_entry`, `credit_topup_request`, `settlement_entry`, `expense`
67
+
68
+ **Subscription:** `subscription_entitlement`, `subscription_plan`, `subscription_pricing_tier`, `subscription_price_quote`, `subscription_checkout_session`, `promo_code`, `promo_redemption`, `reimbursement_obligation`
69
+
70
+ **Operations:** `guard_invite`, `guard_assignment`, `guard_task`, `task_template`, `task_instance`, `ticket`
71
+
72
+ **Audit:** `audit_log`, `statement_version`
73
+
74
+ ## Error Contract
75
+
76
+ All API errors follow a standardized shape. 44 error codes defined in V1.14 (EH-6.02 through EH-6.44).
77
+
78
+ ```typescript
79
+ interface ApiError {
80
+ http_status: number;
81
+ error_code: string; // e.g., "BUILDING_NOT_FOUND"
82
+ message_key: string; // i18n key, e.g., "error.building.not_found"
83
+ request_id: string; // UUID correlation
84
+ details?: Record<string, unknown>; // safe details only
85
+ }
86
+ ```
87
+
88
+ **Safe-details rule:** Never include `building_key_v1`, `unit_key_v1`, identity values, or extracted document text in error responses. This prevents entity enumeration.
89
+
90
+ Read `references/error-codes.md` for the full mapping of all 44 error codes with HTTP status codes.
91
+
92
+ ## Financial Rules
93
+
94
+ These are non-negotiable domain rules that every piece of code touching money must follow:
95
+
96
+ - **Append-only ledger.** Never update or delete a `ledger_entry`. Corrections use `REVERSAL` entries only.
97
+ - **Idempotency keys** on every financial write operation. Duplicate requests with same idempotency key return the original result.
98
+ - **FIFO credit settlement.** No partial settlement — credit either covers the full obligation or doesn't apply.
99
+ - **7 entry types only:** `CREDIT_TOPUP`, `MANUAL_UNIT_INCOME`, `OPENING_BALANCE`, `EXPENSE`, `SUBSCRIPTION_FEE`, `AUTOSETTLEMENT_APPLIED`, `REVERSAL`.
100
+ - **Monetary values** always stored as `{ amount: number, currency: string }` with ISO 4217 currency code (JOD for Jordan).
101
+ - **Daily auto-settlement** at 07:00 Asia/Amman — atomically applies credit to cover obligations.
102
+
103
+ ## Timestamps & Localization
104
+
105
+ - All timestamps stored in UTC. Presented in `Asia/Amman` for Jordan buildings.
106
+ - Numerals display as `0-9` (Western Arabic), not `٠-٩`.
107
+ - Arabic (RTL) + English. Every user-facing string uses a `message_key` — no hardcoded labels in backend responses.
108
+ - All `reason_code` values are stable identifiers, not display text.
109
+
110
+ ## Database Conventions
111
+
112
+ - Every table has `id` (UUID), `created_at` (timestamptz), `updated_at` (timestamptz).
113
+ - Every request carries a `request_id` (UUID) for audit correlation.
114
+ - RLS policies on every table — no exceptions.
115
+ - `building_key_v1` and `unit_key_v1` are opaque canonical keys for deterministic matching. Never expose in API responses or logs.
116
+
117
+ ## Authentication
118
+
119
+ OTP-based login via SMS. Access/refresh token rotation with server-side session enforcement. No password-based auth.
120
+
121
+ ## Subscription States
122
+
123
+ Per-building subscription: `TRIAL` (30 days) → `ACTIVE` → `INACTIVE`. Paywall gates most features when `INACTIVE`, but identity documents remain accessible.
124
+
125
+ ## Commit Convention
126
+
127
+ All commits within Sakani follow: `{type}({phase}-{plan}): {description}` during Qualia execution, or `{type}(sakani): {description}` for standalone changes.
128
+
129
+ ## When to Read References
130
+
131
+ | You're working on... | Read |
132
+ |---|---|
133
+ | Any entity CRUD, schema design | `references/entities.md` |
134
+ | Error handling, API responses | `references/error-codes.md` |
135
+ | Permission checks, role guards | This file (Roles table above) |
136
+ | Financial logic, ledger ops | This file (Financial Rules above) |
@@ -0,0 +1,23 @@
1
+ {
2
+ "skill_name": "sakani-conventions",
3
+ "evals": [
4
+ {
5
+ "id": 1,
6
+ "prompt": "I need to create the NestJS DTOs and Supabase migration for the credit top-up request feature. Owner submits a top-up with evidence (CliQ screenshot), BM approves or rejects. Create the migration SQL file and the TypeScript types.",
7
+ "expected_output": "Should produce: migration with correct table schema matching entities.md (idempotency_key, evidence_document_id FK, status enum, etc.), TypeScript types with snake_case DB fields and camelCase TS properties, error handling using the exact SAKANI_ERRORS codes (DUPLICATE_TOPUP_REQUEST, TOPUP_ALREADY_REVIEWED), and the ledger_entry for CREDIT_TOPUP type following append-only rules.",
8
+ "files": []
9
+ },
10
+ {
11
+ "id": 2,
12
+ "prompt": "Write the guard invite API endpoint for Sakani. BM invites a guard to the building by phone number. The invite expires after 7 days and is single-use. Only one active guard per building.",
13
+ "expected_output": "Should produce: NestJS controller/service following monorepo import pattern (@sakani/shared), correct error codes (GUARD_INVITE_EXPIRED, GUARD_INVITE_REVOKED, GUARD_ALREADY_ACTIVE), proper role check (BM_VERIFIED only), idempotency handling, and the API error response shape matching the ApiError interface exactly.",
14
+ "files": []
15
+ },
16
+ {
17
+ "id": 3,
18
+ "prompt": "Create the Supabase RLS policies for the ticket table. Owners and tenants can create tickets for their unit. BMs can see all tickets in their building. Guards can see tickets assigned to them. Staff admins can see everything.",
19
+ "expected_output": "Should produce: RLS policies using auth.uid() with correct role checks against building_role_assignment and unit_membership tables, proper scope enforcement (unit-scoped for owners/tenants, building-scoped for BM/guard, global for staff), and deny-by-default approach (no permissive policies without role check).",
20
+ "files": []
21
+ }
22
+ ]
23
+ }