tribunal-kit 2.4.6 → 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 (250) hide show
  1. package/.agent/ARCHITECTURE.md +99 -99
  2. package/.agent/GEMINI.md +52 -52
  3. package/.agent/agents/accessibility-reviewer.md +139 -86
  4. package/.agent/agents/ai-code-reviewer.md +160 -90
  5. package/.agent/agents/backend-specialist.md +164 -127
  6. package/.agent/agents/code-archaeologist.md +115 -73
  7. package/.agent/agents/database-architect.md +130 -110
  8. package/.agent/agents/debugger.md +137 -97
  9. package/.agent/agents/dependency-reviewer.md +78 -30
  10. package/.agent/agents/devops-engineer.md +161 -118
  11. package/.agent/agents/documentation-writer.md +151 -87
  12. package/.agent/agents/explorer-agent.md +117 -99
  13. package/.agent/agents/frontend-reviewer.md +127 -47
  14. package/.agent/agents/frontend-specialist.md +169 -109
  15. package/.agent/agents/game-developer.md +28 -164
  16. package/.agent/agents/logic-reviewer.md +87 -49
  17. package/.agent/agents/mobile-developer.md +151 -103
  18. package/.agent/agents/mobile-reviewer.md +133 -50
  19. package/.agent/agents/orchestrator.md +121 -110
  20. package/.agent/agents/penetration-tester.md +103 -77
  21. package/.agent/agents/performance-optimizer.md +136 -92
  22. package/.agent/agents/performance-reviewer.md +139 -69
  23. package/.agent/agents/product-manager.md +104 -70
  24. package/.agent/agents/product-owner.md +6 -25
  25. package/.agent/agents/project-planner.md +95 -95
  26. package/.agent/agents/qa-automation-engineer.md +174 -87
  27. package/.agent/agents/security-auditor.md +133 -129
  28. package/.agent/agents/seo-specialist.md +160 -99
  29. package/.agent/agents/sql-reviewer.md +132 -44
  30. package/.agent/agents/supervisor-agent.md +137 -109
  31. package/.agent/agents/swarm-worker-contracts.md +17 -17
  32. package/.agent/agents/swarm-worker-registry.md +46 -46
  33. package/.agent/agents/test-coverage-reviewer.md +132 -53
  34. package/.agent/agents/test-engineer.md +0 -21
  35. package/.agent/agents/type-safety-reviewer.md +143 -33
  36. package/.agent/patterns/generator.md +9 -9
  37. package/.agent/patterns/inversion.md +12 -12
  38. package/.agent/patterns/pipeline.md +9 -9
  39. package/.agent/patterns/reviewer.md +13 -13
  40. package/.agent/patterns/tool-wrapper.md +9 -9
  41. package/.agent/rules/GEMINI.md +63 -63
  42. package/.agent/scripts/__pycache__/auto_preview.cpython-311.pyc +0 -0
  43. package/.agent/scripts/__pycache__/bundle_analyzer.cpython-311.pyc +0 -0
  44. package/.agent/scripts/__pycache__/checklist.cpython-311.pyc +0 -0
  45. package/.agent/scripts/__pycache__/dependency_analyzer.cpython-311.pyc +0 -0
  46. package/.agent/scripts/__pycache__/security_scan.cpython-311.pyc +0 -0
  47. package/.agent/scripts/__pycache__/session_manager.cpython-311.pyc +0 -0
  48. package/.agent/scripts/__pycache__/skill_integrator.cpython-311.pyc +0 -0
  49. package/.agent/scripts/__pycache__/swarm_dispatcher.cpython-311.pyc +0 -0
  50. package/.agent/scripts/__pycache__/test_runner.cpython-311.pyc +0 -0
  51. package/.agent/scripts/__pycache__/verify_all.cpython-311.pyc +0 -0
  52. package/.agent/scripts/compress_skills.py +167 -0
  53. package/.agent/scripts/consolidate_skills.py +173 -0
  54. package/.agent/scripts/deep_compress.py +202 -0
  55. package/.agent/scripts/minify_context.py +80 -0
  56. package/.agent/scripts/security_scan.py +1 -1
  57. package/.agent/scripts/strip_tribunal.py +41 -0
  58. package/.agent/skills/agent-organizer/SKILL.md +60 -100
  59. package/.agent/skills/agentic-patterns/SKILL.md +0 -70
  60. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +108 -53
  61. package/.agent/skills/api-patterns/SKILL.md +197 -257
  62. package/.agent/skills/api-security-auditor/SKILL.md +125 -57
  63. package/.agent/skills/app-builder/SKILL.md +326 -50
  64. package/.agent/skills/app-builder/templates/SKILL.md +13 -15
  65. package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md +16 -16
  66. package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +22 -22
  67. package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md +18 -18
  68. package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +20 -20
  69. package/.agent/skills/app-builder/templates/express-api/TEMPLATE.md +17 -17
  70. package/.agent/skills/app-builder/templates/flutter-app/TEMPLATE.md +18 -18
  71. package/.agent/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +21 -21
  72. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +19 -19
  73. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +26 -26
  74. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +26 -26
  75. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +19 -19
  76. package/.agent/skills/app-builder/templates/python-fastapi/TEMPLATE.md +18 -18
  77. package/.agent/skills/app-builder/templates/react-native-app/TEMPLATE.md +20 -20
  78. package/.agent/skills/appflow-wireframe/SKILL.md +71 -98
  79. package/.agent/skills/architecture/SKILL.md +161 -200
  80. package/.agent/skills/authentication-best-practices/SKILL.md +121 -54
  81. package/.agent/skills/bash-linux/SKILL.md +71 -166
  82. package/.agent/skills/behavioral-modes/SKILL.md +8 -69
  83. package/.agent/skills/brainstorming/SKILL.md +345 -127
  84. package/.agent/skills/building-native-ui/SKILL.md +125 -57
  85. package/.agent/skills/clean-code/SKILL.md +266 -149
  86. package/.agent/skills/code-review-checklist/SKILL.md +0 -62
  87. package/.agent/skills/config-validator/SKILL.md +73 -131
  88. package/.agent/skills/csharp-developer/SKILL.md +434 -73
  89. package/.agent/skills/database-design/SKILL.md +190 -275
  90. package/.agent/skills/deployment-procedures/SKILL.md +81 -158
  91. package/.agent/skills/devops-engineer/SKILL.md +255 -94
  92. package/.agent/skills/devops-incident-responder/SKILL.md +50 -69
  93. package/.agent/skills/doc.md +5 -5
  94. package/.agent/skills/documentation-templates/SKILL.md +19 -63
  95. package/.agent/skills/edge-computing/SKILL.md +75 -165
  96. package/.agent/skills/extract-design-system/SKILL.md +84 -58
  97. package/.agent/skills/framer-motion-expert/SKILL.md +195 -0
  98. package/.agent/skills/frontend-design/SKILL.md +151 -499
  99. package/.agent/skills/game-design-expert/SKILL.md +71 -0
  100. package/.agent/skills/game-engineering-expert/SKILL.md +88 -0
  101. package/.agent/skills/geo-fundamentals/SKILL.md +52 -178
  102. package/.agent/skills/github-operations/SKILL.md +197 -272
  103. package/.agent/skills/gsap-expert/SKILL.md +194 -0
  104. package/.agent/skills/i18n-localization/SKILL.md +60 -172
  105. package/.agent/skills/intelligent-routing/SKILL.md +123 -103
  106. package/.agent/skills/lint-and-validate/SKILL.md +8 -52
  107. package/.agent/skills/llm-engineering/SKILL.md +281 -195
  108. package/.agent/skills/local-first/SKILL.md +76 -159
  109. package/.agent/skills/mcp-builder/SKILL.md +48 -188
  110. package/.agent/skills/mobile-design/SKILL.md +213 -219
  111. package/.agent/skills/motion-engineering/SKILL.md +184 -0
  112. package/.agent/skills/nextjs-react-expert/SKILL.md +184 -203
  113. package/.agent/skills/nodejs-best-practices/SKILL.md +403 -185
  114. package/.agent/skills/observability/SKILL.md +211 -203
  115. package/.agent/skills/parallel-agents/SKILL.md +53 -146
  116. package/.agent/skills/performance-profiling/SKILL.md +171 -151
  117. package/.agent/skills/plan-writing/SKILL.md +49 -153
  118. package/.agent/skills/platform-engineer/SKILL.md +57 -103
  119. package/.agent/skills/playwright-best-practices/SKILL.md +110 -63
  120. package/.agent/skills/powershell-windows/SKILL.md +61 -179
  121. package/.agent/skills/python-patterns/SKILL.md +7 -35
  122. package/.agent/skills/python-pro/SKILL.md +273 -114
  123. package/.agent/skills/react-specialist/SKILL.md +227 -108
  124. package/.agent/skills/readme-builder/SKILL.md +15 -85
  125. package/.agent/skills/realtime-patterns/SKILL.md +216 -243
  126. package/.agent/skills/red-team-tactics/SKILL.md +10 -51
  127. package/.agent/skills/rust-pro/SKILL.md +525 -142
  128. package/.agent/skills/seo-fundamentals/SKILL.md +92 -153
  129. package/.agent/skills/server-management/SKILL.md +110 -166
  130. package/.agent/skills/shadcn-ui-expert/SKILL.md +154 -55
  131. package/.agent/skills/skill-creator/SKILL.md +18 -58
  132. package/.agent/skills/sql-pro/SKILL.md +543 -68
  133. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +28 -68
  134. package/.agent/skills/swiftui-expert/SKILL.md +124 -57
  135. package/.agent/skills/systematic-debugging/SKILL.md +49 -151
  136. package/.agent/skills/tailwind-patterns/SKILL.md +433 -149
  137. package/.agent/skills/tdd-workflow/SKILL.md +63 -169
  138. package/.agent/skills/test-result-analyzer/SKILL.md +33 -73
  139. package/.agent/skills/testing-patterns/SKILL.md +437 -130
  140. package/.agent/skills/trend-researcher/SKILL.md +30 -71
  141. package/.agent/skills/ui-ux-pro-max/SKILL.md +0 -41
  142. package/.agent/skills/ui-ux-researcher/SKILL.md +51 -91
  143. package/.agent/skills/vue-expert/SKILL.md +225 -119
  144. package/.agent/skills/vulnerability-scanner/SKILL.md +264 -226
  145. package/.agent/skills/web-accessibility-auditor/SKILL.md +141 -58
  146. package/.agent/skills/web-design-guidelines/SKILL.md +17 -61
  147. package/.agent/skills/webapp-testing/SKILL.md +71 -196
  148. package/.agent/skills/whimsy-injector/SKILL.md +58 -132
  149. package/.agent/skills/workflow-optimizer/SKILL.md +28 -68
  150. package/.agent/workflows/api-tester.md +96 -224
  151. package/.agent/workflows/audit.md +81 -122
  152. package/.agent/workflows/brainstorm.md +69 -105
  153. package/.agent/workflows/changelog.md +65 -97
  154. package/.agent/workflows/create.md +73 -88
  155. package/.agent/workflows/debug.md +80 -111
  156. package/.agent/workflows/deploy.md +119 -92
  157. package/.agent/workflows/enhance.md +80 -91
  158. package/.agent/workflows/fix.md +68 -97
  159. package/.agent/workflows/generate.md +165 -164
  160. package/.agent/workflows/migrate.md +106 -109
  161. package/.agent/workflows/orchestrate.md +103 -86
  162. package/.agent/workflows/performance-benchmarker.md +77 -268
  163. package/.agent/workflows/plan.md +120 -98
  164. package/.agent/workflows/preview.md +39 -96
  165. package/.agent/workflows/refactor.md +105 -97
  166. package/.agent/workflows/review-ai.md +63 -102
  167. package/.agent/workflows/review.md +71 -110
  168. package/.agent/workflows/session.md +53 -113
  169. package/.agent/workflows/status.md +42 -88
  170. package/.agent/workflows/strengthen-skills.md +90 -51
  171. package/.agent/workflows/swarm.md +114 -129
  172. package/.agent/workflows/test.md +125 -102
  173. package/.agent/workflows/tribunal-backend.md +60 -78
  174. package/.agent/workflows/tribunal-database.md +62 -100
  175. package/.agent/workflows/tribunal-frontend.md +62 -82
  176. package/.agent/workflows/tribunal-full.md +56 -100
  177. package/.agent/workflows/tribunal-mobile.md +65 -94
  178. package/.agent/workflows/tribunal-performance.md +62 -105
  179. package/.agent/workflows/ui-ux-pro-max.md +72 -121
  180. package/README.md +11 -15
  181. package/package.json +1 -1
  182. package/.agent/skills/api-patterns/api-style.md +0 -42
  183. package/.agent/skills/api-patterns/auth.md +0 -24
  184. package/.agent/skills/api-patterns/documentation.md +0 -26
  185. package/.agent/skills/api-patterns/graphql.md +0 -41
  186. package/.agent/skills/api-patterns/rate-limiting.md +0 -31
  187. package/.agent/skills/api-patterns/response.md +0 -37
  188. package/.agent/skills/api-patterns/rest.md +0 -40
  189. package/.agent/skills/api-patterns/security-testing.md +0 -122
  190. package/.agent/skills/api-patterns/trpc.md +0 -41
  191. package/.agent/skills/api-patterns/versioning.md +0 -22
  192. package/.agent/skills/app-builder/agent-coordination.md +0 -71
  193. package/.agent/skills/app-builder/feature-building.md +0 -53
  194. package/.agent/skills/app-builder/project-detection.md +0 -34
  195. package/.agent/skills/app-builder/scaffolding.md +0 -118
  196. package/.agent/skills/app-builder/tech-stack.md +0 -40
  197. package/.agent/skills/architecture/context-discovery.md +0 -43
  198. package/.agent/skills/architecture/examples.md +0 -94
  199. package/.agent/skills/architecture/pattern-selection.md +0 -68
  200. package/.agent/skills/architecture/patterns-reference.md +0 -50
  201. package/.agent/skills/architecture/trade-off-analysis.md +0 -77
  202. package/.agent/skills/brainstorming/dynamic-questioning.md +0 -360
  203. package/.agent/skills/database-design/database-selection.md +0 -43
  204. package/.agent/skills/database-design/indexing.md +0 -39
  205. package/.agent/skills/database-design/migrations.md +0 -48
  206. package/.agent/skills/database-design/optimization.md +0 -36
  207. package/.agent/skills/database-design/orm-selection.md +0 -30
  208. package/.agent/skills/database-design/schema-design.md +0 -56
  209. package/.agent/skills/dotnet-core-expert/SKILL.md +0 -103
  210. package/.agent/skills/framer-motion-animations/SKILL.md +0 -74
  211. package/.agent/skills/frontend-design/animation-guide.md +0 -331
  212. package/.agent/skills/frontend-design/color-system.md +0 -329
  213. package/.agent/skills/frontend-design/decision-trees.md +0 -418
  214. package/.agent/skills/frontend-design/motion-graphics.md +0 -306
  215. package/.agent/skills/frontend-design/typography-system.md +0 -363
  216. package/.agent/skills/frontend-design/ux-psychology.md +0 -1116
  217. package/.agent/skills/frontend-design/visual-effects.md +0 -383
  218. package/.agent/skills/game-development/2d-games/SKILL.md +0 -119
  219. package/.agent/skills/game-development/3d-games/SKILL.md +0 -135
  220. package/.agent/skills/game-development/SKILL.md +0 -236
  221. package/.agent/skills/game-development/game-art/SKILL.md +0 -185
  222. package/.agent/skills/game-development/game-audio/SKILL.md +0 -190
  223. package/.agent/skills/game-development/game-design/SKILL.md +0 -129
  224. package/.agent/skills/game-development/mobile-games/SKILL.md +0 -108
  225. package/.agent/skills/game-development/multiplayer/SKILL.md +0 -132
  226. package/.agent/skills/game-development/pc-games/SKILL.md +0 -144
  227. package/.agent/skills/game-development/vr-ar/SKILL.md +0 -123
  228. package/.agent/skills/game-development/web-games/SKILL.md +0 -150
  229. package/.agent/skills/intelligent-routing/router-manifest.md +0 -65
  230. package/.agent/skills/mobile-design/decision-trees.md +0 -516
  231. package/.agent/skills/mobile-design/mobile-backend.md +0 -491
  232. package/.agent/skills/mobile-design/mobile-color-system.md +0 -420
  233. package/.agent/skills/mobile-design/mobile-debugging.md +0 -122
  234. package/.agent/skills/mobile-design/mobile-design-thinking.md +0 -357
  235. package/.agent/skills/mobile-design/mobile-navigation.md +0 -458
  236. package/.agent/skills/mobile-design/mobile-performance.md +0 -767
  237. package/.agent/skills/mobile-design/mobile-testing.md +0 -356
  238. package/.agent/skills/mobile-design/mobile-typography.md +0 -433
  239. package/.agent/skills/mobile-design/platform-android.md +0 -666
  240. package/.agent/skills/mobile-design/platform-ios.md +0 -561
  241. package/.agent/skills/mobile-design/touch-psychology.md +0 -537
  242. package/.agent/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md +0 -312
  243. package/.agent/skills/nextjs-react-expert/2-bundle-bundle-size-optimization.md +0 -240
  244. package/.agent/skills/nextjs-react-expert/3-server-server-side-performance.md +0 -490
  245. package/.agent/skills/nextjs-react-expert/4-client-client-side-data-fetching.md +0 -264
  246. package/.agent/skills/nextjs-react-expert/5-rerender-re-render-optimization.md +0 -581
  247. package/.agent/skills/nextjs-react-expert/6-rendering-rendering-performance.md +0 -432
  248. package/.agent/skills/nextjs-react-expert/7-js-javascript-performance.md +0 -684
  249. package/.agent/skills/nextjs-react-expert/8-advanced-advanced-patterns.md +0 -150
  250. package/.agent/skills/vulnerability-scanner/checklists.md +0 -121
@@ -1,43 +0,0 @@
1
- # Context Discovery
2
-
3
- > Before suggesting any architecture, gather context.
4
-
5
- ## Question Hierarchy (Ask User FIRST)
6
-
7
- 1. **Scale**
8
- - How many users? (10, 1K, 100K, 1M+)
9
- - Data volume? (MB, GB, TB)
10
- - Transaction rate? (per second/minute)
11
-
12
- 2. **Team**
13
- - Solo developer or team?
14
- - Team size and expertise?
15
- - Distributed or co-located?
16
-
17
- 3. **Timeline**
18
- - MVP/Prototype or long-term product?
19
- - Time to market pressure?
20
-
21
- 4. **Domain**
22
- - CRUD-heavy or business logic complex?
23
- - Real-time requirements?
24
- - Compliance/regulations?
25
-
26
- 5. **Constraints**
27
- - Budget limitations?
28
- - Legacy systems to integrate?
29
- - Technology stack preferences?
30
-
31
- ## Project Classification Matrix
32
-
33
- ```
34
- MVP SaaS Enterprise
35
- ┌─────────────────────────────────────────────────────────────┐
36
- │ Scale │ <1K │ 1K-100K │ 100K+ │
37
- │ Team │ Solo │ 2-10 │ 10+ │
38
- │ Timeline │ Fast (weeks) │ Medium (months)│ Long (years)│
39
- │ Architecture │ Simple │ Modular │ Distributed │
40
- │ Patterns │ Minimal │ Selective │ Comprehensive│
41
- │ Example │ Next.js API │ NestJS │ Microservices│
42
- └─────────────────────────────────────────────────────────────┘
43
- ```
@@ -1,94 +0,0 @@
1
- # Architecture Examples
2
-
3
- > Real-world architecture decisions by project type.
4
-
5
- ---
6
-
7
- ## Example 1: MVP E-commerce (Solo Developer)
8
-
9
- ```yaml
10
- Requirements:
11
- - <1000 users initially
12
- - Solo developer
13
- - Fast to market (8 weeks)
14
- - Budget-conscious
15
-
16
- Architecture Decisions:
17
- App Structure: Monolith (simpler for solo)
18
- Framework: Next.js (full-stack, fast)
19
- Data Layer: Prisma direct (no over-abstraction)
20
- Authentication: JWT (simpler than OAuth)
21
- Payment: Stripe (hosted solution)
22
- Database: PostgreSQL (ACID for orders)
23
-
24
- Trade-offs Accepted:
25
- - Monolith → Can't scale independently (team doesn't justify it)
26
- - No Repository → Less testable (simple CRUD doesn't need it)
27
- - JWT → No social login initially (can add later)
28
-
29
- Future Migration Path:
30
- - Users > 10K → Extract payment service
31
- - Team > 3 → Add Repository pattern
32
- - Social login requested → Add OAuth
33
- ```
34
-
35
- ---
36
-
37
- ## Example 2: SaaS Product (5-10 Developers)
38
-
39
- ```yaml
40
- Requirements:
41
- - 1K-100K users
42
- - 5-10 developers
43
- - Long-term (12+ months)
44
- - Multiple domains (billing, users, core)
45
-
46
- Architecture Decisions:
47
- App Structure: Modular Monolith (team size optimal)
48
- Framework: NestJS (modular by design)
49
- Data Layer: Repository pattern (testing, flexibility)
50
- Domain Model: Partial DDD (rich entities)
51
- Authentication: OAuth + JWT
52
- Caching: Redis
53
- Database: PostgreSQL
54
-
55
- Trade-offs Accepted:
56
- - Modular Monolith → Some module coupling (microservices not justified)
57
- - Partial DDD → No full aggregates (no domain experts)
58
- - RabbitMQ later → Initial synchronous (add when proven needed)
59
-
60
- Migration Path:
61
- - Team > 10 → Consider microservices
62
- - Domains conflict → Extract bounded contexts
63
- - Read performance issues → Add CQRS
64
- ```
65
-
66
- ---
67
-
68
- ## Example 3: Enterprise (100K+ Users)
69
-
70
- ```yaml
71
- Requirements:
72
- - 100K+ users
73
- - 10+ developers
74
- - Multiple business domains
75
- - Different scaling needs
76
- - 24/7 availability
77
-
78
- Architecture Decisions:
79
- App Structure: Microservices (independent scale)
80
- API Gateway: Kong/AWS API GW
81
- Domain Model: Full DDD
82
- Consistency: Event-driven (eventual OK)
83
- Message Bus: Kafka
84
- Authentication: OAuth + SAML (enterprise SSO)
85
- Database: Polyglot (right tool per job)
86
- CQRS: Selected services
87
-
88
- Operational Requirements:
89
- - Service mesh (Istio/Linkerd)
90
- - Distributed tracing (Jaeger/Tempo)
91
- - Centralized logging (ELK/Loki)
92
- - Circuit breakers (Resilience4j)
93
- - Kubernetes/Helm
94
- ```
@@ -1,68 +0,0 @@
1
- # Pattern Selection Guidelines
2
-
3
- > Decision trees for choosing architectural patterns.
4
-
5
- ## Main Decision Tree
6
-
7
- ```
8
- START: What's your MAIN concern?
9
-
10
- ┌─ Data Access Complexity?
11
- │ ├─ HIGH (complex queries, testing needed)
12
- │ │ → Repository Pattern + Unit of Work
13
- │ │ VALIDATE: Will data source change frequently?
14
- │ │ ├─ YES → Repository worth the indirection
15
- │ │ └─ NO → Consider simpler ORM direct access
16
- │ └─ LOW (simple CRUD, single database)
17
- │ → ORM directly (Prisma, Drizzle)
18
- │ Simpler = Better, Faster
19
-
20
- ├─ Business Rules Complexity?
21
- │ ├─ HIGH (domain logic, rules vary by context)
22
- │ │ → Domain-Driven Design
23
- │ │ VALIDATE: Do you have domain experts on team?
24
- │ │ ├─ YES → Full DDD (Aggregates, Value Objects)
25
- │ │ └─ NO → Partial DDD (rich entities, clear boundaries)
26
- │ └─ LOW (mostly CRUD, simple validation)
27
- │ → Transaction Script pattern
28
- │ Simpler = Better, Faster
29
-
30
- ├─ Independent Scaling Needed?
31
- │ ├─ YES (different components scale differently)
32
- │ │ → Microservices WORTH the complexity
33
- │ │ REQUIREMENTS (ALL must be true):
34
- │ │ - Clear domain boundaries
35
- │ │ - Team > 10 developers
36
- │ │ - Different scaling needs per service
37
- │ │ IF NOT ALL MET → Modular Monolith instead
38
- │ └─ NO (everything scales together)
39
- │ → Modular Monolith
40
- │ Can extract services later when proven needed
41
-
42
- └─ Real-time Requirements?
43
- ├─ HIGH (immediate updates, multi-user sync)
44
- │ → Event-Driven Architecture
45
- │ → Message Queue (RabbitMQ, Redis, Kafka)
46
- │ VALIDATE: Can you handle eventual consistency?
47
- │ ├─ YES → Event-driven valid
48
- │ └─ NO → Synchronous with polling
49
- └─ LOW (eventual consistency acceptable)
50
- → Synchronous (REST/GraphQL)
51
- Simpler = Better, Faster
52
- ```
53
-
54
- ## The 3 Questions (Before ANY Pattern)
55
-
56
- 1. **Problem Solved**: What SPECIFIC problem does this pattern solve?
57
- 2. **Simpler Alternative**: Is there a simpler solution?
58
- 3. **Deferred Complexity**: Can we add this LATER when needed?
59
-
60
- ## Red Flags (Anti-patterns)
61
-
62
- | Pattern | Anti-pattern | Simpler Alternative |
63
- |---------|-------------|-------------------|
64
- | Microservices | Premature splitting | Start monolith, extract later |
65
- | Clean/Hexagonal | Over-abstraction | Concrete first, interfaces later |
66
- | Event Sourcing | Over-engineering | Append-only audit log |
67
- | CQRS | Unnecessary complexity | Single model |
68
- | Repository | YAGNI for simple CRUD | ORM direct access |
@@ -1,50 +0,0 @@
1
- # Architecture Patterns Reference
2
-
3
- > Quick reference for common patterns with usage guidance.
4
-
5
- ## Data Access Patterns
6
-
7
- | Pattern | When to Use | When NOT to Use | Complexity |
8
- |---------|-------------|-----------------|------------|
9
- | **Active Record** | Simple CRUD, rapid prototyping | Complex queries, multiple sources | Low |
10
- | **Repository** | Testing needed, multiple sources | Simple CRUD, single database | Medium |
11
- | **Unit of Work** | Complex transactions | Simple operations | High |
12
- | **Data Mapper** | Complex domain, performance | Simple CRUD, rapid dev | High |
13
-
14
- ## Domain Logic Patterns
15
-
16
- | Pattern | When to Use | When NOT to Use | Complexity |
17
- |---------|-------------|-----------------|------------|
18
- | **Transaction Script** | Simple CRUD, procedural | Complex business rules | Low |
19
- | **Table Module** | Record-based logic | Rich behavior needed | Low |
20
- | **Domain Model** | Complex business logic | Simple CRUD | Medium |
21
- | **DDD (Full)** | Complex domain, domain experts | Simple domain, no experts | High |
22
-
23
- ## Distributed System Patterns
24
-
25
- | Pattern | When to Use | When NOT to Use | Complexity |
26
- |---------|-------------|-----------------|------------|
27
- | **Modular Monolith** | Small teams, unclear boundaries | Clear contexts, different scales | Medium |
28
- | **Microservices** | Different scales, large teams | Small teams, simple domain | Very High |
29
- | **Event-Driven** | Real-time, loose coupling | Simple workflows, strong consistency | High |
30
- | **CQRS** | Read/write performance diverges | Simple CRUD, same model | High |
31
- | **Saga** | Distributed transactions | Single database, simple ACID | High |
32
-
33
- ## API Patterns
34
-
35
- | Pattern | When to Use | When NOT to Use | Complexity |
36
- |---------|-------------|-----------------|------------|
37
- | **REST** | Standard CRUD, resources | Real-time, complex queries | Low |
38
- | **GraphQL** | Flexible queries, multiple clients | Simple CRUD, caching needs | Medium |
39
- | **gRPC** | Internal services, performance | Public APIs, browser clients | Medium |
40
- | **WebSocket** | Real-time updates | Simple request/response | Medium |
41
-
42
- ---
43
-
44
- ## Simplicity Principle
45
-
46
- **"Start simple, add complexity only when proven necessary."**
47
-
48
- - You can always add patterns later
49
- - Removing complexity is MUCH harder than adding it
50
- - When in doubt, choose simpler option
@@ -1,77 +0,0 @@
1
- # Trade-off Analysis & ADR
2
-
3
- > Document every architectural decision with trade-offs.
4
-
5
- ## Decision Framework
6
-
7
- For EACH architectural component, document:
8
-
9
- ```markdown
10
- ## Architecture Decision Record
11
-
12
- ### Context
13
- - **Problem**: [What problem are we solving?]
14
- - **Constraints**: [Team size, scale, timeline, budget]
15
-
16
- ### Options Considered
17
-
18
- | Option | Pros | Cons | Complexity | When Valid |
19
- |--------|------|------|------------|-----------|
20
- | Option A | Benefit 1 | Cost 1 | Low | [Conditions] |
21
- | Option B | Benefit 2 | Cost 2 | High | [Conditions] |
22
-
23
- ### Decision
24
- **Chosen**: [Option B]
25
-
26
- ### Rationale
27
- 1. [Reason 1 - tied to constraints]
28
- 2. [Reason 2 - tied to requirements]
29
-
30
- ### Trade-offs Accepted
31
- - [What we're giving up]
32
- - [Why this is acceptable]
33
-
34
- ### Consequences
35
- - **Positive**: [Benefits we gain]
36
- - **Negative**: [Costs/risks we accept]
37
- - **Mitigation**: [How we'll address negatives]
38
-
39
- ### Revisit Trigger
40
- - [When to reconsider this decision]
41
- ```
42
-
43
- ## ADR Template
44
-
45
- ```markdown
46
- # ADR-[XXX]: [Decision Title]
47
-
48
- ## Status
49
- Proposed | Accepted | Deprecated | Superseded by [ADR-YYY]
50
-
51
- ## Context
52
- [What problem? What constraints?]
53
-
54
- ## Decision
55
- [What we chose - be specific]
56
-
57
- ## Rationale
58
- [Why - tie to requirements and constraints]
59
-
60
- ## Trade-offs
61
- [What we're giving up - be honest]
62
-
63
- ## Consequences
64
- - **Positive**: [Benefits]
65
- - **Negative**: [Costs]
66
- - **Mitigation**: [How to address]
67
- ```
68
-
69
- ## ADR Storage
70
-
71
- ```
72
- docs/
73
- └── architecture/
74
- ├── adr-001-use-nextjs.md
75
- ├── adr-002-postgresql-over-mongodb.md
76
- └── adr-003-adopt-repository-pattern.md
77
- ```
@@ -1,360 +0,0 @@
1
- # Dynamic Question Generation
2
-
3
- > **PRINCIPLE:** Questions are not about gathering data—they are about **revealing architectural consequences**.
4
- >
5
- > Every question must connect to a concrete implementation decision that affects cost, complexity, or timeline.
6
-
7
- ---
8
-
9
- ## 🧠 Core Principles
10
-
11
- ### 1. Questions Reveal Consequences
12
-
13
- A good question is not "What color do you want?" but:
14
-
15
- ```markdown
16
- ❌ BAD: "What authentication method?"
17
- ✅ GOOD: "Should users sign up with email/password or social login?
18
-
19
- Impact:
20
- - Email/Pass → Need password reset, hashing, 2FA infrastructure
21
- - Social → OAuth providers, user profile mapping, less control
22
-
23
- Trade-off: Security vs. Development time vs. User friction"
24
- ```
25
-
26
- ### 2. Context Before Content
27
-
28
- First understand **where** this request fits:
29
-
30
- | Context | Question Focus |
31
- |---------|----------------|
32
- | **Greenfield** (new project) | Foundation decisions: stack, hosting, scale |
33
- | **Feature Addition** | Integration points, existing patterns, breaking changes |
34
- | **Refactor** | Why refactor? Performance? Maintainability? What's broken? |
35
- | **Debug** | Symptoms → Root cause → Reproduction path |
36
-
37
- ### 3. Minimum Viable Questions
38
-
39
- **PRINCIPLE:** Each question must eliminate a fork in the implementation road.
40
-
41
- ```
42
- Before Question:
43
- ├── Path A: Do X (5 min)
44
- ├── Path B: Do Y (15 min)
45
- └── Path C: Do Z (1 hour)
46
-
47
- After Question:
48
- └── Path Confirmed: Do X (5 min)
49
- ```
50
-
51
- If a question doesn't reduce implementation paths → **DELETE IT**.
52
-
53
- ### 4. Questions Generate Data, Not Assumptions
54
-
55
- ```markdown
56
- ❌ ASSUMPTION: "User probably wants Stripe for payments"
57
- ✅ QUESTION: "Which payment provider fits your needs?
58
-
59
- Stripe → Best documentation, 2.9% + $0.30, US-centric
60
- LemonSqueezy → Merchant of Record, 5% + $0.50, global taxes
61
- Paddle → Complex pricing, handles EU VAT, enterprise focus"
62
- ```
63
-
64
- ---
65
-
66
- ## 📋 Question Generation Algorithm
67
-
68
- ```
69
- INPUT: User request + Context (greenfield/feature/refactor/debug)
70
-
71
- ├── STEP 1: Parse Request
72
- │ ├── Extract domain (ecommerce, auth, realtime, cms, etc.)
73
- │ ├── Extract features (explicit and implied)
74
- │ └── Extract scale indicators (users, data volume, frequency)
75
-
76
- ├── STEP 2: Identify Decision Points
77
- │ ├── What MUST be decided before coding? (blocking)
78
- │ ├── What COULD be decided later? (deferable)
79
- │ └── What has ARCHITECTURAL impact? (high-leverage)
80
-
81
- ├── STEP 3: Generate Questions (Priority Order)
82
- │ ├── P0: Blocking decisions (cannot proceed without answer)
83
- │ ├── P1: High-leverage (affects >30% of implementation)
84
- │ ├── P2: Medium-leverage (affects specific features)
85
- │ └── P3: Nice-to-have (edge cases, optimization)
86
-
87
- └── STEP 4: Format Each Question
88
- ├── What: Clear question
89
- ├── Why: Impact on implementation
90
- ├── Options: Trade-offs (not just A vs B)
91
- ├── Fun/Superpower Option: Inject at least one highly creative, unconventional approach
92
- └── Default: What happens if user doesn't answer
93
- ```
94
-
95
- ---
96
-
97
- ## 🎯 Domain-Specific Question Banks
98
-
99
- ### E-Commerce
100
-
101
- | Question | Why It Matters | Trade-offs |
102
- |----------|----------------|------------|
103
- | **Single or Multi-vendor?** | Multi-vendor → Commission logic, vendor dashboards, split payments | +Revenue, -Complexity |
104
- | **Inventory Tracking?** | Needs stock tables, reservation logic, low-stock alerts | +Accuracy, -Development time |
105
- | **Digital or Physical Products?** | Digital → Download links, no shipping | Physical → Shipping APIs, tracking |
106
- | **Subscription or One-time?** | Subscription → Recurring billing, dunning, proration | +Revenue, -Complexity |
107
-
108
- ### Authentication
109
-
110
- | Question | Why It Matters | Trade-offs |
111
- |----------|----------------|------------|
112
- | **Social Login Needed?** | OAuth providers vs. password reset infrastructure | +UX, -Control |
113
- | **Role-Based Permissions?** | RBAC tables, policy enforcement, admin UI | +Security, -Development time |
114
- | **2FA Required?** | TOTP/SMI infrastructure, backup codes, recovery flow | +Security, -UX friction |
115
- | **Email Verification?** | Verification tokens, email service, resend logic | +Security, -Sign-up friction |
116
-
117
- ### Real-time
118
-
119
- | Question | Why It Matters | Trade-offs |
120
- |----------|----------------|------------|
121
- | **WebSocket or Polling?** | WS → Server scaling, connection management | Polling → Simpler, higher latency |
122
- | **Expected Concurrent Users?** | <100 → Single server, >1000 → Redis pub/sub, >10k → specialized infra | +Scale, -Complexity |
123
- | **Message Persistence?** | History tables, storage costs, pagination | +UX, -Storage |
124
- | **Ephemeral or Durable?** | Ephemeral → In-memory, Durable → Database write before emit | +Reliability, -Latency |
125
-
126
- ### Content/CMS
127
-
128
- | Question | Why It Matters | Trade-offs |
129
- |----------|----------------|------------|
130
- | **Rich Text or Markdown?** | Rich Text → Sanitization, XSS risks | Markdown → Simple, no WYSIWYG |
131
- | **Draft/Publish Workflow?** | Status field, scheduled jobs, versioning | +Control, -Complexity |
132
- | **Media Handling?** | Upload endpoints, storage, optimization | +Features, -Development time |
133
- | **Multi-language?** | i18n tables, translation UI, fallback logic | +Reach, -Complexity |
134
-
135
- ### Business & Product Strategy
136
-
137
- | Question | Why It Matters | Trade-offs |
138
- |----------|----------------|------------|
139
- | **Monetization Approach?** | Freemium vs. Paywall vs. Ads affects user flow | +Revenue, -User Acquisition |
140
- | **Onboarding CRO?** | Wizard vs. self-serve dictates state management | +Activation, -Dev Time |
141
- | **Competitor Differentiator?** | Must highlight this UI feature above all else | +Standout, -Standardization |
142
- | **Marketing Psychology?** | FOMO (urgency) vs. Trust (social proof) layout | +Conversion, -Aesthetics |
143
-
144
- ---
145
-
146
- ## 📐 Dynamic Question Template
147
-
148
- ```markdown
149
- Based on your request for [DOMAIN] [FEATURE]:
150
-
151
- ## 🔴 CRITICAL (Blocking Decisions)
152
-
153
- ### 1. **[DECISION POINT]**
154
-
155
- **Question:** [Clear, specific question]
156
-
157
- **Why This Matters:**
158
- - [Explain architectural consequence]
159
- - [Affects: cost / complexity / timeline / scale]
160
-
161
- **Options:**
162
- | Option | Pros | Cons | Best For |
163
- |--------|------|------|----------|
164
- | A | [Advantage] | [Disadvantage] | [Use case] |
165
- | B | [Advantage] | [Disadvantage] | [Use case] |
166
-
167
- **If Not Specified:** [Default choice + rationale]
168
-
169
- ---
170
-
171
- ## 🟡 HIGH-LEVERAGE (Affects Implementation)
172
-
173
- ### 2. **[DECISION POINT]**
174
- [Same format]
175
-
176
- ---
177
-
178
- ## 🟢 NICE-TO-HAVE (Edge Cases)
179
-
180
- ### 3. **[DECISION POINT]**
181
- [Same format]
182
- ```
183
-
184
- ---
185
-
186
- ## 🔄 Iterative Questioning
187
-
188
- ### First Pass (3-5 Questions)
189
- Focus on **blocking decisions**. Don't proceed without answers.
190
-
191
- ### Second Pass (After Initial Implementation)
192
- As patterns emerge, ask:
193
- - "This feature implies [X]. Should we handle [edge case] now or defer?"
194
- - "We're using [Pattern A]. Should [Feature B] follow the same pattern?"
195
-
196
- ### Third Pass (Optimization)
197
- When functionality works:
198
- - "Performance bottleneck at [X]. Optimize now or acceptable for now?"
199
- - "Refactor [Y] for maintainability or ship as-is?"
200
-
201
- ---
202
-
203
- ## 🎭 Example: Full Question Generation
204
-
205
- ```
206
- USER REQUEST: "Build an Instagram clone"
207
-
208
- STEP 1: Parse
209
- ├── Domain: Social Media
210
- ├── Features: Photo sharing, engagement (likes/comments), user profiles
211
- ├── Implied: Feed, following, authentication
212
- └── Scale: Potentially high (social apps go viral)
213
-
214
- STEP 2: Decision Points
215
- ├── Blocking: Storage strategy, authentication method, feed type
216
- ├── High-leverage: Real-time notifications, data model complexity
217
- └── Deferable: Analytics, advanced search, reels/video
218
-
219
- STEP 3: Generate Questions (Priority)
220
-
221
- P0 (Blocking):
222
- 1. Storage Strategy → Affects architecture, cost, speed
223
- 2. Feed Algorithm → Affects database queries, complexity
224
- 3. Auth Method → Affects dev time, UX, security
225
-
226
- P1 (High-leverage):
227
- 4. Real-time Notifications → WebSocket vs polling
228
- 5. Media Processing → Client-side vs server-side optimization
229
-
230
- P2 (Deferable):
231
- 6. Story/Reels → Major feature creep, defer to v2
232
- 7. DM/Chat → Separate subsystem, defer to v2
233
-
234
- STEP 4: Format Output
235
- ```
236
-
237
- ---
238
-
239
- ## 📊 Generated Output (Example)
240
-
241
- ```
242
- Based on your Instagram clone request:
243
-
244
- ## 🔴 CRITICAL DECISIONS (Cannot Proceed Without Answers)
245
-
246
- ### 1. **Photo Storage Strategy**
247
-
248
- **Question:** Where will user photos be stored and served?
249
-
250
- **Why This Matters:**
251
- - Affects: Monthly hosting costs, page load speed, CDN complexity
252
- - High-volume social apps: 1000 users × 10 photos × 2MB = 20GB storage
253
-
254
- **Options:**
255
- | Option | Cost | Speed | Complexity | Best For |
256
- |--------|------|-------|------------|----------|
257
- | **Cloudinary** | $89/mo (25GB) | Fast (CDN) | Low | MVP, rapid launch |
258
- | **AWS S3 + CloudFront** | $0.023/GB | Fast (CDN) | Medium | Production, cost-optimized |
259
- | **Supabase Storage** | Free tier 1GB | Medium | Low | Small scale, simple |
260
- | **Local Storage** | Server cost | Slow | Low | Development only |
261
-
262
- **If Not Specified:** Cloudinary (balanced for MVP)
263
-
264
- ---
265
-
266
- ### 2. **Feed Algorithm Choice**
267
-
268
- **Question:** How should the main feed work?
269
-
270
- **Why This Matters:**
271
- - Affects: Database query complexity, caching strategy, development time
272
- - Algorithmic feeds require ML infrastructure, ranking signals
273
-
274
- **Options:**
275
- | Option | Complexity | Database Impact | Best For |
276
- |--------|------------|-----------------|----------|
277
- | **Chronological** | Low | Simple query | Early stage, transparency |
278
- | **Follow-Only** | Medium | JOIN with pagination | Most social apps |
279
- | **Algorithmic** | High | Pre-computed feed tables | Instagram competitor |
280
-
281
- **If Not Specified:** Follow-Only (balanced for social app)
282
-
283
- ---
284
-
285
- ### 3. **Authentication Approach**
286
-
287
- **Question:** How do users sign up and login?
288
-
289
- **Why This Matters:**
290
- - Affects: Development time (2-5 hours), security posture, UX friction
291
-
292
- **Options:**
293
- | Option | Dev Time | Security | UX | Best For |
294
- |--------|----------|----------|-----|----------|
295
- | **Email/Password** | 4-5 hrs | High (if 2FA) | Medium | Full control needed |
296
- | **Social Only** | 1-2 hrs | Provider-dependent | Smooth | B2C, rapid launch |
297
- | **Magic Link** | 2-3 hrs | Medium | Very smooth | Security-focused |
298
- | **Clerk/Auth0** | 1 hr | High | Smooth | Fastest to market |
299
-
300
- **If Not Specified:** Clerk (fastest for MVP)
301
-
302
- ---
303
-
304
- ## 🟡 HIGH-LEVERAGE (Affects Architecture)
305
-
306
- ### 4. **Real-time Notifications**
307
-
308
- **Question:** Do users need instant notifications for likes/comments?
309
-
310
- **Why This Matters:**
311
- - WebSocket adds infrastructure complexity (Redis pub/sub for scaling)
312
- - Polling is simpler but higher latency
313
-
314
- **Options:**
315
- | Option | Complexity | Scale Cost | Best For |
316
- |--------|------------|------------|----------|
317
- | **WebSocket + Redis** | High | $10+/mo | >1000 concurrent users |
318
- | **Polling (30s)** | Low | DB queries | <1000 users |
319
- | **No Real-time** | None | None | MVP, validate first |
320
-
321
- **If Not Specified:** Polling for MVP (defer WebSocket until validated)
322
-
323
- ---
324
-
325
- ## 🟢 NICE-TO-HAVE (Defer to v2)
326
-
327
- ### 5. **Video/Reels Support**
328
- - Major complexity (video processing, streaming infrastructure)
329
- - Recommendation: Launch with photos only, add video after validation
330
-
331
- ### 6. **Direct Messaging**
332
- - Separate subsystem (chat infrastructure different from feed)
333
- - Recommendation: Use Pusher/Stream for real-time or defer entirely
334
-
335
- ---
336
-
337
- ## 📋 Summary
338
-
339
- | Decision | Recommendation | If Changed |
340
- |----------|----------------|------------|
341
- | Storage | Cloudinary | +3 hrs setup |
342
- | Feed | Follow-only | +2 hrs query optimization |
343
- | Auth | Clerk | -3 hrs dev time |
344
- | Real-time | Polling | +5 hrs WebSocket setup |
345
- | Video | Defer to v2 | N/A |
346
- | DM | Defer to v2 | N/A |
347
-
348
- **Total Estimated MVP Time:** 15-20 hours with recommendations above
349
- ```
350
-
351
- ---
352
-
353
- ## 🎯 Principles Recap
354
-
355
- 1. **Every question = Architectural decision** → Not data gathering
356
- 2. **Show trade-offs** → User understands consequences
357
- 3. **Prioritize blocking decisions** → Cannot proceed without
358
- 4. **Provide defaults** → If user doesn't answer, we proceed anyway
359
- 5. **Domain-aware** → Ecommerce questions ≠ Auth questions ≠ Real-time questions
360
- 6. **Iterative** → More questions as patterns emerge during implementation