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.
- package/README.md +50 -0
- package/bin/cli.js +519 -0
- package/framework/agents/architecture-strategist.md +53 -0
- package/framework/agents/backend-agent.md +150 -0
- package/framework/agents/code-simplicity-reviewer.md +86 -0
- package/framework/agents/frontend-agent.md +111 -0
- package/framework/agents/kieran-typescript-reviewer.md +96 -0
- package/framework/agents/performance-oracle.md +111 -0
- package/framework/agents/qualia-codebase-mapper.md +760 -0
- package/framework/agents/qualia-debugger.md +1203 -0
- package/framework/agents/qualia-executor.md +881 -0
- package/framework/agents/qualia-integration-checker.md +423 -0
- package/framework/agents/qualia-phase-researcher.md +453 -0
- package/framework/agents/qualia-plan-checker.md +699 -0
- package/framework/agents/qualia-planner.md +1241 -0
- package/framework/agents/qualia-project-researcher.md +602 -0
- package/framework/agents/qualia-research-synthesizer.md +236 -0
- package/framework/agents/qualia-roadmapper.md +605 -0
- package/framework/agents/qualia-verifier.md +685 -0
- package/framework/agents/team-orchestrator.md +228 -0
- package/framework/agents/teams/full-stack-team.md +48 -0
- package/framework/agents/teams/optimize-team.md +53 -0
- package/framework/agents/teams/review-team.md +62 -0
- package/framework/agents/teams/ship-team.md +86 -0
- package/framework/agents/test-agent.md +182 -0
- package/framework/askpass.sh +2 -0
- package/framework/commands/design.md +53 -0
- package/framework/commands/quick-db.md +22 -0
- package/framework/config/retention.json +35 -0
- package/framework/core/PRINCIPLES.md +77 -0
- package/framework/hooks/auto-format.sh +45 -0
- package/framework/hooks/block-env-edit.sh +42 -0
- package/framework/hooks/branch-guard.sh +46 -0
- package/framework/hooks/confirm-delete.sh +56 -0
- package/framework/hooks/migration-validate.sh +68 -0
- package/framework/hooks/notification-speak.sh +15 -0
- package/framework/hooks/pre-commit.sh +80 -0
- package/framework/hooks/pre-compact.sh +55 -0
- package/framework/hooks/pre-deploy-gate.sh +151 -0
- package/framework/hooks/qualia-colors.sh +32 -0
- package/framework/hooks/retention-cleanup.sh +43 -0
- package/framework/hooks/save-session-state.sh +153 -0
- package/framework/hooks/session-context-loader.sh +28 -0
- package/framework/hooks/session-learn.sh +30 -0
- package/framework/knowledge/claudecode-bible.md +1384 -0
- package/framework/knowledge/client-prefs.md +22 -0
- package/framework/knowledge/common-fixes.md +25 -0
- package/framework/knowledge/deployment-map.md +35 -0
- package/framework/knowledge/email-signature.html +1 -0
- package/framework/knowledge/employees.md +8 -0
- package/framework/knowledge/learned-patterns.md +51 -0
- package/framework/knowledge/optimization-research-2026.md +137 -0
- package/framework/knowledge/qualia-context.md +67 -0
- package/framework/knowledge/supabase-patterns.md +50 -0
- package/framework/knowledge/voice-agent-patterns.md +46 -0
- package/framework/qualia-engine/VERSION +1 -0
- package/framework/qualia-engine/bin/qualia-tools.js +2160 -0
- package/framework/qualia-engine/bin/qualia-tools.test.js +1054 -0
- package/framework/qualia-engine/references/checkpoints.md +775 -0
- package/framework/qualia-engine/references/continuation-format.md +249 -0
- package/framework/qualia-engine/references/decimal-phase-calculation.md +65 -0
- package/framework/qualia-engine/references/design-quality.md +56 -0
- package/framework/qualia-engine/references/git-integration.md +254 -0
- package/framework/qualia-engine/references/git-planning-commit.md +50 -0
- package/framework/qualia-engine/references/model-profile-resolution.md +32 -0
- package/framework/qualia-engine/references/model-profiles.md +73 -0
- package/framework/qualia-engine/references/phase-argument-parsing.md +61 -0
- package/framework/qualia-engine/references/planning-config.md +195 -0
- package/framework/qualia-engine/references/questioning.md +141 -0
- package/framework/qualia-engine/references/tdd.md +263 -0
- package/framework/qualia-engine/references/ui-brand.md +160 -0
- package/framework/qualia-engine/references/verification-patterns.md +612 -0
- package/framework/qualia-engine/templates/DEBUG.md +159 -0
- package/framework/qualia-engine/templates/DESIGN.md +81 -0
- package/framework/qualia-engine/templates/UAT.md +247 -0
- package/framework/qualia-engine/templates/codebase/architecture.md +255 -0
- package/framework/qualia-engine/templates/codebase/concerns.md +310 -0
- package/framework/qualia-engine/templates/codebase/conventions.md +307 -0
- package/framework/qualia-engine/templates/codebase/integrations.md +280 -0
- package/framework/qualia-engine/templates/codebase/stack.md +186 -0
- package/framework/qualia-engine/templates/codebase/structure.md +285 -0
- package/framework/qualia-engine/templates/codebase/testing.md +480 -0
- package/framework/qualia-engine/templates/config.json +35 -0
- package/framework/qualia-engine/templates/context.md +283 -0
- package/framework/qualia-engine/templates/continue-here.md +78 -0
- package/framework/qualia-engine/templates/debug-subagent-prompt.md +91 -0
- package/framework/qualia-engine/templates/discovery.md +146 -0
- package/framework/qualia-engine/templates/milestone-archive.md +123 -0
- package/framework/qualia-engine/templates/milestone.md +115 -0
- package/framework/qualia-engine/templates/phase-prompt.md +567 -0
- package/framework/qualia-engine/templates/planner-subagent-prompt.md +117 -0
- package/framework/qualia-engine/templates/project.md +184 -0
- package/framework/qualia-engine/templates/projects/ai-agent.md +156 -0
- package/framework/qualia-engine/templates/projects/mobile-app.md +181 -0
- package/framework/qualia-engine/templates/projects/voice-agent.md +134 -0
- package/framework/qualia-engine/templates/projects/website.md +137 -0
- package/framework/qualia-engine/templates/requirements.md +231 -0
- package/framework/qualia-engine/templates/research-project/ARCHITECTURE.md +204 -0
- package/framework/qualia-engine/templates/research-project/FEATURES.md +147 -0
- package/framework/qualia-engine/templates/research-project/PITFALLS.md +200 -0
- package/framework/qualia-engine/templates/research-project/STACK.md +120 -0
- package/framework/qualia-engine/templates/research-project/SUMMARY.md +170 -0
- package/framework/qualia-engine/templates/research.md +552 -0
- package/framework/qualia-engine/templates/roadmap.md +202 -0
- package/framework/qualia-engine/templates/state.md +176 -0
- package/framework/qualia-engine/templates/summary-complex.md +59 -0
- package/framework/qualia-engine/templates/summary-minimal.md +41 -0
- package/framework/qualia-engine/templates/summary-standard.md +48 -0
- package/framework/qualia-engine/templates/summary.md +246 -0
- package/framework/qualia-engine/templates/user-setup.md +311 -0
- package/framework/qualia-engine/templates/verification-report.md +322 -0
- package/framework/qualia-engine/workflows/add-phase.md +179 -0
- package/framework/qualia-engine/workflows/add-todo.md +157 -0
- package/framework/qualia-engine/workflows/audit-milestone.md +241 -0
- package/framework/qualia-engine/workflows/check-todos.md +176 -0
- package/framework/qualia-engine/workflows/complete-milestone.md +858 -0
- package/framework/qualia-engine/workflows/diagnose-issues.md +219 -0
- package/framework/qualia-engine/workflows/discovery-phase.md +289 -0
- package/framework/qualia-engine/workflows/discuss-phase.md +534 -0
- package/framework/qualia-engine/workflows/execute-phase.md +559 -0
- package/framework/qualia-engine/workflows/execute-plan.md +438 -0
- package/framework/qualia-engine/workflows/help.md +470 -0
- package/framework/qualia-engine/workflows/insert-phase.md +220 -0
- package/framework/qualia-engine/workflows/list-phase-assumptions.md +178 -0
- package/framework/qualia-engine/workflows/map-codebase.md +327 -0
- package/framework/qualia-engine/workflows/new-milestone.md +363 -0
- package/framework/qualia-engine/workflows/new-project.md +1037 -0
- package/framework/qualia-engine/workflows/pause-work.md +122 -0
- package/framework/qualia-engine/workflows/plan-milestone-gaps.md +256 -0
- package/framework/qualia-engine/workflows/plan-phase.md +422 -0
- package/framework/qualia-engine/workflows/progress.md +354 -0
- package/framework/qualia-engine/workflows/quick.md +252 -0
- package/framework/qualia-engine/workflows/remove-phase.md +326 -0
- package/framework/qualia-engine/workflows/research-phase.md +74 -0
- package/framework/qualia-engine/workflows/resume-project.md +306 -0
- package/framework/qualia-engine/workflows/set-profile.md +80 -0
- package/framework/qualia-engine/workflows/settings.md +145 -0
- package/framework/qualia-engine/workflows/transition.md +556 -0
- package/framework/qualia-engine/workflows/update.md +197 -0
- package/framework/qualia-engine/workflows/verify-phase.md +195 -0
- package/framework/qualia-engine/workflows/verify-work.md +625 -0
- package/framework/rules/context7.md +11 -0
- package/framework/rules/deployment.md +29 -0
- package/framework/rules/frontend.md +33 -0
- package/framework/rules/security.md +12 -0
- package/framework/rules/speed.md +20 -0
- package/framework/scripts/__pycache__/say.cpython-314.pyc +0 -0
- package/framework/scripts/apply-retention.sh +120 -0
- package/framework/scripts/bootstrap-pop-os.sh +354 -0
- package/framework/scripts/claude-voice +13 -0
- package/framework/scripts/cleanup.sh +131 -0
- package/framework/scripts/cowork-mode.sh +141 -0
- package/framework/scripts/generate-project-claude-md.sh +153 -0
- package/framework/scripts/load-test-webhook.js +172 -0
- package/framework/scripts/say.py +236 -0
- package/framework/scripts/showcase-video-recorder/ffmpeg-builder.js +167 -0
- package/framework/scripts/showcase-video-recorder/playwright-helpers.js +216 -0
- package/framework/scripts/speak.py +55 -0
- package/framework/scripts/speak.sh +18 -0
- package/framework/scripts/status.sh +138 -0
- package/framework/scripts/sync-to-framework.sh +65 -0
- package/framework/scripts/voice-hotkey.py +227 -0
- package/framework/scripts/voice-input.sh +51 -0
- package/framework/skills/animate/SKILL.md +202 -0
- package/framework/skills/bolder/SKILL.md +144 -0
- package/framework/skills/browser-qa/SKILL.md +536 -0
- package/framework/skills/clarify/SKILL.md +179 -0
- package/framework/skills/colorize/SKILL.md +170 -0
- package/framework/skills/critique/SKILL.md +126 -0
- package/framework/skills/deep-research/SKILL.md +271 -0
- package/framework/skills/delight/SKILL.md +329 -0
- package/framework/skills/deploy/SKILL.md +261 -0
- package/framework/skills/deploy-verify/SKILL.md +377 -0
- package/framework/skills/deploy-verify/scripts/canary-check.sh +206 -0
- package/framework/skills/deploy-verify/scripts/check-console-errors.js +147 -0
- package/framework/skills/deploy-verify/scripts/check-cwv.js +139 -0
- package/framework/skills/deploy-verify/scripts/project-detect.sh +84 -0
- package/framework/skills/deploy-verify/scripts/verify.sh +548 -0
- package/framework/skills/design-quieter/SKILL.md +130 -0
- package/framework/skills/distill/SKILL.md +149 -0
- package/framework/skills/docs-lookup/SKILL.md +78 -0
- package/framework/skills/fcm-notifications/SKILL.md +125 -0
- package/framework/skills/financial-ledger/SKILL.md +1039 -0
- package/framework/skills/frontend-master/NOTICE.md +4 -0
- package/framework/skills/frontend-master/SKILL.md +127 -0
- package/framework/skills/frontend-master/reference/color-and-contrast.md +132 -0
- package/framework/skills/frontend-master/reference/interaction-design.md +123 -0
- package/framework/skills/frontend-master/reference/motion-design.md +99 -0
- package/framework/skills/frontend-master/reference/responsive-design.md +114 -0
- package/framework/skills/frontend-master/reference/spatial-design.md +100 -0
- package/framework/skills/frontend-master/reference/typography.md +131 -0
- package/framework/skills/frontend-master/reference/ux-writing.md +107 -0
- package/framework/skills/harden/SKILL.md +357 -0
- package/framework/skills/i18n-rtl/SKILL.md +752 -0
- package/framework/skills/learn/SKILL.md +71 -0
- package/framework/skills/memory/SKILL.md +50 -0
- package/framework/skills/mobile-expo/SKILL.md +864 -0
- package/framework/skills/mobile-expo/references/store-checklist.md +550 -0
- package/framework/skills/nestjs-backend/README.md +73 -0
- package/framework/skills/nestjs-backend/SKILL.md +446 -0
- package/framework/skills/nestjs-backend/references/templates.md +1173 -0
- package/framework/skills/normalize/SKILL.md +79 -0
- package/framework/skills/onboard/SKILL.md +242 -0
- package/framework/skills/polish/SKILL.md +209 -0
- package/framework/skills/pr/SKILL.md +66 -0
- package/framework/skills/qualia/SKILL.md +153 -0
- package/framework/skills/qualia-add-todo/SKILL.md +68 -0
- package/framework/skills/qualia-audit-milestone/SKILL.md +92 -0
- package/framework/skills/qualia-check-todos/SKILL.md +55 -0
- package/framework/skills/qualia-complete-milestone/SKILL.md +108 -0
- package/framework/skills/qualia-debug/SKILL.md +149 -0
- package/framework/skills/qualia-design/SKILL.md +203 -0
- package/framework/skills/qualia-discuss-phase/SKILL.md +72 -0
- package/framework/skills/qualia-execute-phase/SKILL.md +86 -0
- package/framework/skills/qualia-help/SKILL.md +67 -0
- package/framework/skills/qualia-idk/SKILL.md +352 -0
- package/framework/skills/qualia-list-phase-assumptions/SKILL.md +67 -0
- package/framework/skills/qualia-new-milestone/SKILL.md +72 -0
- package/framework/skills/qualia-new-project/SKILL.md +92 -0
- package/framework/skills/qualia-optimize/SKILL.md +417 -0
- package/framework/skills/qualia-pause-work/SKILL.md +96 -0
- package/framework/skills/qualia-plan-milestone-gaps/SKILL.md +57 -0
- package/framework/skills/qualia-plan-phase/SKILL.md +101 -0
- package/framework/skills/qualia-progress/SKILL.md +53 -0
- package/framework/skills/qualia-quick/SKILL.md +89 -0
- package/framework/skills/qualia-research-phase/SKILL.md +88 -0
- package/framework/skills/qualia-resume-work/SKILL.md +62 -0
- package/framework/skills/qualia-review/SKILL.md +263 -0
- package/framework/skills/qualia-start/SKILL.md +182 -0
- package/framework/skills/qualia-verify-work/SKILL.md +105 -0
- package/framework/skills/qualia-workflow/SKILL.md +130 -0
- package/framework/skills/rag/SKILL.md +750 -0
- package/framework/skills/responsive/SKILL.md +231 -0
- package/framework/skills/retro/SKILL.md +284 -0
- package/framework/skills/sakani-conventions/SKILL.md +136 -0
- package/framework/skills/sakani-conventions/evals/evals.json +23 -0
- package/framework/skills/sakani-conventions/references/entities.md +365 -0
- package/framework/skills/sakani-conventions/references/error-codes.md +95 -0
- package/framework/skills/seo-master/SKILL.md +490 -0
- package/framework/skills/seo-master/references/checklist.md +199 -0
- package/framework/skills/seo-master/references/structured-data.md +609 -0
- package/framework/skills/ship/SKILL.md +202 -0
- package/framework/skills/stack-researcher/SKILL.md +215 -0
- package/framework/skills/status/SKILL.md +154 -0
- package/framework/skills/status/scripts/health-check.sh +562 -0
- package/framework/skills/subscription-payments/SKILL.md +250 -0
- package/framework/skills/supabase/SKILL.md +973 -0
- package/framework/skills/supabase/references/templates.md +159 -0
- package/framework/skills/team/SKILL.md +67 -0
- package/framework/skills/test-runner/SKILL.md +202 -0
- package/framework/skills/voice-agent/SKILL.md +407 -0
- package/framework/skills/zoho-workflow/SKILL.md +51 -0
- package/framework/statusline-command.sh +117 -0
- package/package.json +24 -0
- package/profiles/fawzi.json +16 -0
- package/profiles/hasan.json +16 -0
- package/profiles/moayad.json +16 -0
- package/templates/CLAUDE-owner.md +52 -0
- package/templates/CLAUDE.md.hbs +58 -0
- package/templates/env.claude.template +12 -0
- 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
|
+
}
|