gabbe-kit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (502) hide show
  1. package/LICENSE +25 -0
  2. package/LICENSE-CODE +202 -0
  3. package/README.md +817 -0
  4. package/agents/AGENTS.md +542 -0
  5. package/agents/CONSTITUTION.md +188 -0
  6. package/agents/guides/00-index.md +142 -0
  7. package/agents/guides/ai/a2ui-protocols.md +71 -0
  8. package/agents/guides/ai/actor-agent-frameworks.md +82 -0
  9. package/agents/guides/ai/agent-communication.md +146 -0
  10. package/agents/guides/ai/agent-identity-trust.md +69 -0
  11. package/agents/guides/ai/agent-only-cognition.md +73 -0
  12. package/agents/guides/ai/agent-only-swarms.md +70 -0
  13. package/agents/guides/ai/agent-operating-ergonomics.md +52 -0
  14. package/agents/guides/ai/agent-ui.md +106 -0
  15. package/agents/guides/ai/ai-agentic.md +309 -0
  16. package/agents/guides/ai/beyond-llms.md +60 -0
  17. package/agents/guides/ai/dynamic-capability-loading.md +121 -0
  18. package/agents/guides/ai/gabbe-innovations.md +111 -0
  19. package/agents/guides/ai/model-customization-decisions.md +78 -0
  20. package/agents/guides/ai/multi-agent-systems.md +85 -0
  21. package/agents/guides/ai/self-evolving-skills.md +137 -0
  22. package/agents/guides/ai/self-healing-summary.md +21 -0
  23. package/agents/guides/ai/visual-mcp-integration.md +106 -0
  24. package/agents/guides/architecture/api-standards.md +61 -0
  25. package/agents/guides/architecture/blockchain-dlt.md +36 -0
  26. package/agents/guides/architecture/critical-systems-arch.md +66 -0
  27. package/agents/guides/architecture/event-driven-architecture.md +39 -0
  28. package/agents/guides/architecture/microservices.md +292 -0
  29. package/agents/guides/architecture/monolith.md +303 -0
  30. package/agents/guides/architecture/orchestration.md +75 -0
  31. package/agents/guides/architecture/system-qualities.md +51 -0
  32. package/agents/guides/architecture/system-scalability.md +47 -0
  33. package/agents/guides/architecture/systems-architecture.md +506 -0
  34. package/agents/guides/data/semantic-web.md +23 -0
  35. package/agents/guides/data/sql-nosql.md +305 -0
  36. package/agents/guides/industry/engineering-standards.md +36 -0
  37. package/agents/guides/industry/global-standards.md +24 -0
  38. package/agents/guides/industry/healthcare-fhir.md +33 -0
  39. package/agents/guides/industry/industrial-iot.md +33 -0
  40. package/agents/guides/industry/telecom-networks.md +34 -0
  41. package/agents/guides/languages/c-sharp.md +66 -0
  42. package/agents/guides/languages/go-lang.md +251 -0
  43. package/agents/guides/languages/java.md +73 -0
  44. package/agents/guides/languages/js-ts-nodejs.md +361 -0
  45. package/agents/guides/languages/nodejs-advanced.md +56 -0
  46. package/agents/guides/languages/php-laravel.md +376 -0
  47. package/agents/guides/languages/python-fastapi-ai.md +257 -0
  48. package/agents/guides/languages/rust.md +73 -0
  49. package/agents/guides/ops/compliance-audit.md +177 -0
  50. package/agents/guides/ops/cost-optimization.md +57 -0
  51. package/agents/guides/ops/dev-environments.md +67 -0
  52. package/agents/guides/ops/dev-workflow.md +44 -0
  53. package/agents/guides/ops/gabbe-cli-workflows.md +252 -0
  54. package/agents/guides/ops/production-health.md +62 -0
  55. package/agents/guides/ops/troubleshooting-guide.md +69 -0
  56. package/agents/guides/patterns/agentic-design-patterns.md +308 -0
  57. package/agents/guides/patterns/agentic-patterns.md +43 -0
  58. package/agents/guides/patterns/ai-native-scenarios.md +71 -0
  59. package/agents/guides/patterns/autonomous-swarm-patterns.md +42 -0
  60. package/agents/guides/patterns/design-patterns.md +68 -0
  61. package/agents/guides/patterns/enterprise-migration-scenario.md +58 -0
  62. package/agents/guides/patterns/enterprise-patterns.md +56 -0
  63. package/agents/guides/patterns/software-design-patterns.md +106 -0
  64. package/agents/guides/patterns/time-complexity-analysis.md +116 -0
  65. package/agents/guides/planning/product-requirements.md +407 -0
  66. package/agents/guides/planning/strategic-analysis.md +98 -0
  67. package/agents/guides/planning/visual-product-specs.md +162 -0
  68. package/agents/guides/principles/clean-code-standards.md +51 -0
  69. package/agents/guides/principles/computing-foundations.md +87 -0
  70. package/agents/guides/principles/diagramming-standards.md +568 -0
  71. package/agents/guides/principles/evaluation-strategy.md +103 -0
  72. package/agents/guides/principles/future-tech.md +35 -0
  73. package/agents/guides/principles/human-agent-collaboration.md +54 -0
  74. package/agents/guides/principles/legacy-tech.md +61 -0
  75. package/agents/guides/principles/mathematical-foundations.md +103 -0
  76. package/agents/guides/principles/modeling-methods.md +97 -0
  77. package/agents/guides/principles/no-code-integration.md +84 -0
  78. package/agents/guides/principles/testing-strategy.md +97 -0
  79. package/agents/guides/principles/visual-design-system.md +44 -0
  80. package/agents/guides/processes/RARV_CYCLE.md +262 -0
  81. package/agents/guides/processes/extension-protocol.md +183 -0
  82. package/agents/guides/processes/full-system-lifecycle.md +47 -0
  83. package/agents/guides/processes/knowledge-integration.md +82 -0
  84. package/agents/guides/processes/loki-sdlc-phases.md +446 -0
  85. package/agents/guides/product/green-software.md +38 -0
  86. package/agents/guides/product/sustainability-checks.md +29 -0
  87. package/agents/guides/security/ai-risk-standards-map.md +98 -0
  88. package/agents/guides/security/api-security.md +51 -0
  89. package/agents/guides/security/cryptography-standards.md +38 -0
  90. package/agents/guides/security/privacy-data-protection.md +41 -0
  91. package/agents/guides/security/secure-architecture.md +43 -0
  92. package/agents/guides/security/threat-modeling.md +46 -0
  93. package/agents/memory/AUDIT_LOG.md +48 -0
  94. package/agents/memory/CONTINUITY.md +49 -0
  95. package/agents/memory/PROJECT_STATE.md +134 -0
  96. package/agents/memory/RESUME_POINTER.md +15 -0
  97. package/agents/memory/episodic/DECISION_LOG_TEMPLATE.md +104 -0
  98. package/agents/memory/semantic/PROJECT_KNOWLEDGE_TEMPLATE.md +194 -0
  99. package/agents/memory/semantic/VECTOR_DB_CONFIG_TEMPLATE.json +46 -0
  100. package/agents/personas/00-index.md +148 -0
  101. package/agents/personas/biz-compliance.md +112 -0
  102. package/agents/personas/biz-legal.md +131 -0
  103. package/agents/personas/eng-api.md +110 -0
  104. package/agents/personas/eng-backend.md +113 -0
  105. package/agents/personas/eng-data.md +50 -0
  106. package/agents/personas/eng-database.md +95 -0
  107. package/agents/personas/eng-frontend.md +75 -0
  108. package/agents/personas/eng-infra.md +105 -0
  109. package/agents/personas/eng-messaging.md +50 -0
  110. package/agents/personas/eng-ml.md +50 -0
  111. package/agents/personas/eng-mobile.md +75 -0
  112. package/agents/personas/eng-perf.md +90 -0
  113. package/agents/personas/eng-qa.md +125 -0
  114. package/agents/personas/eng-tooling.md +49 -0
  115. package/agents/personas/ops-compliance.md +109 -0
  116. package/agents/personas/ops-cost.md +92 -0
  117. package/agents/personas/ops-devops.md +85 -0
  118. package/agents/personas/ops-incident.md +123 -0
  119. package/agents/personas/ops-monitor.md +89 -0
  120. package/agents/personas/ops-release.md +91 -0
  121. package/agents/personas/ops-security.md +104 -0
  122. package/agents/personas/ops-sre.md +85 -0
  123. package/agents/personas/orch-coordinator.md +140 -0
  124. package/agents/personas/orch-judge.md +135 -0
  125. package/agents/personas/orch-planner.md +114 -0
  126. package/agents/personas/orch-researcher.md +165 -0
  127. package/agents/personas/prod-architect.md +110 -0
  128. package/agents/personas/prod-design.md +112 -0
  129. package/agents/personas/prod-ethicist.md +50 -0
  130. package/agents/personas/prod-integration.md +120 -0
  131. package/agents/personas/prod-pm.md +115 -0
  132. package/agents/personas/prod-product-ops.md +128 -0
  133. package/agents/personas/prod-research.md +49 -0
  134. package/agents/personas/prod-safety-engineer.md +28 -0
  135. package/agents/personas/prod-tech-lead.md +119 -0
  136. package/agents/personas/ui-design.md +81 -0
  137. package/agents/scripts/check_skills_docs.py +120 -0
  138. package/agents/scripts/compile_skills.py +284 -0
  139. package/agents/scripts/comprehensive_checker.py +187 -0
  140. package/agents/scripts/dump-context.sh +37 -0
  141. package/agents/scripts/eval_skills.py +268 -0
  142. package/agents/scripts/preflight_summary.sh +80 -0
  143. package/agents/scripts/report_duplicates.py +125 -0
  144. package/agents/scripts/setup-context.ps1 +250 -0
  145. package/agents/scripts/setup-context.sh +398 -0
  146. package/agents/scripts/state_export.sh +84 -0
  147. package/agents/scripts/state_import.sh +99 -0
  148. package/agents/scripts/validate_integrity.py +98 -0
  149. package/agents/scripts/validate_links.py +96 -0
  150. package/agents/scripts/validate_methodology_graph.py +194 -0
  151. package/agents/scripts/validate_skills.py +81 -0
  152. package/agents/scripts/verify_e2e_init_flows.py +246 -0
  153. package/agents/scripts/verify_setup_simulation.py +104 -0
  154. package/agents/scripts/verify_triggers_and_mcps.py +159 -0
  155. package/agents/scripts/verify_use_cases.py +498 -0
  156. package/agents/skills/00-index.md +322 -0
  157. package/agents/skills/ai/a2ui-protocols.skill.md +31 -0
  158. package/agents/skills/ai/actor-agent-frameworks.skill.md +31 -0
  159. package/agents/skills/ai/agent-communication.skill.md +36 -0
  160. package/agents/skills/ai/agent-ui.skill.md +31 -0
  161. package/agents/skills/ai/autonomous-swarm-patterns.skill.md +31 -0
  162. package/agents/skills/ai/beyond-llms.skill.md +31 -0
  163. package/agents/skills/ai/context-engineering.skill.md +79 -0
  164. package/agents/skills/ai/llm-as-judge.skill.md +97 -0
  165. package/agents/skills/ai/multi-agent-systems.skill.md +31 -0
  166. package/agents/skills/ai/rag-evaluation.skill.md +93 -0
  167. package/agents/skills/ai/reasoning-patterns.skill.md +125 -0
  168. package/agents/skills/architecture/adaptive-architecture.skill.md +51 -0
  169. package/agents/skills/architecture/api-design.skill.md +92 -0
  170. package/agents/skills/architecture/api-standards.skill.md +31 -0
  171. package/agents/skills/architecture/arch-debt.skill.md +180 -0
  172. package/agents/skills/architecture/arch-design.skill.md +304 -0
  173. package/agents/skills/architecture/arch-patterns.skill.md +52 -0
  174. package/agents/skills/architecture/arch-review.skill.md +326 -0
  175. package/agents/skills/architecture/architecture-governance.skill.md +62 -0
  176. package/agents/skills/architecture/attribute-driven-design.skill.md +108 -0
  177. package/agents/skills/architecture/blockchain-dlt.skill.md +28 -0
  178. package/agents/skills/architecture/compatibility-design.skill.md +51 -0
  179. package/agents/skills/architecture/critical-systems-arch.skill.md +31 -0
  180. package/agents/skills/architecture/design-patterns.skill.md +59 -0
  181. package/agents/skills/architecture/diagramming.skill.md +380 -0
  182. package/agents/skills/architecture/domain-model.skill.md +294 -0
  183. package/agents/skills/architecture/enterprise-migration-scenario.skill.md +31 -0
  184. package/agents/skills/architecture/enterprise-patterns.skill.md +31 -0
  185. package/agents/skills/architecture/error-handling-strategy.skill.md +58 -0
  186. package/agents/skills/architecture/event-driven-architecture.skill.md +31 -0
  187. package/agents/skills/architecture/event-governance.skill.md +55 -0
  188. package/agents/skills/architecture/fitness-functions.skill.md +111 -0
  189. package/agents/skills/architecture/graphql-schema.skill.md +64 -0
  190. package/agents/skills/architecture/legacy-modernization.skill.md +51 -0
  191. package/agents/skills/architecture/microservices.skill.md +31 -0
  192. package/agents/skills/architecture/middleware-design.skill.md +59 -0
  193. package/agents/skills/architecture/monolith.skill.md +31 -0
  194. package/agents/skills/architecture/realtime-comm.skill.md +52 -0
  195. package/agents/skills/architecture/state-management.skill.md +72 -0
  196. package/agents/skills/architecture/system-qualities.skill.md +31 -0
  197. package/agents/skills/architecture/system-scalability.skill.md +31 -0
  198. package/agents/skills/architecture/systems-architecture.skill.md +31 -0
  199. package/agents/skills/architecture/visual-whiteboarding.skill.md +33 -0
  200. package/agents/skills/brain/README.md +70 -0
  201. package/agents/skills/brain/active-inference.skill.md +74 -0
  202. package/agents/skills/brain/brain-mode.skill.md +125 -0
  203. package/agents/skills/brain/cognitive-architectures.skill.md +53 -0
  204. package/agents/skills/brain/cognitive-testing.skill.md +62 -0
  205. package/agents/skills/brain/consciousness-loop.skill.md +68 -0
  206. package/agents/skills/brain/cost-benefit-router.skill.md +89 -0
  207. package/agents/skills/brain/episodic-consolidation.skill.md +43 -0
  208. package/agents/skills/brain/epistemology-knowledge.skill.md +54 -0
  209. package/agents/skills/brain/global-workspace.skill.md +77 -0
  210. package/agents/skills/brain/learning-adaptation.skill.md +68 -0
  211. package/agents/skills/brain/loki-mode.skill.md +267 -0
  212. package/agents/skills/brain/neuroscience-foundations.skill.md +52 -0
  213. package/agents/skills/brain/scripts/active_inference_loop.py +92 -0
  214. package/agents/skills/brain/scripts/cognition_test.py +80 -0
  215. package/agents/skills/brain/scripts/global_workspace.py +104 -0
  216. package/agents/skills/brain/self-improvement.skill.md +80 -0
  217. package/agents/skills/brain/sensory-motor.skill.md +61 -0
  218. package/agents/skills/brain/sequential-thinking.skill.md +48 -0
  219. package/agents/skills/brain/working-memory.skill.md +47 -0
  220. package/agents/skills/coding/agent-trajectory-eval.skill.md +92 -0
  221. package/agents/skills/coding/artisan-commands.skill.md +52 -0
  222. package/agents/skills/coding/browser-tdd.skill.md +131 -0
  223. package/agents/skills/coding/chaos-fault-injection.skill.md +116 -0
  224. package/agents/skills/coding/ci-autofix.skill.md +53 -0
  225. package/agents/skills/coding/clean-coder.skill.md +58 -0
  226. package/agents/skills/coding/code-review.skill.md +100 -0
  227. package/agents/skills/coding/debug.skill.md +100 -0
  228. package/agents/skills/coding/documentation.skill.md +149 -0
  229. package/agents/skills/coding/eval-driven-development.skill.md +107 -0
  230. package/agents/skills/coding/evals/code-review.eval.yaml +29 -0
  231. package/agents/skills/coding/excalidraw.skill.md +90 -0
  232. package/agents/skills/coding/file-processing.skill.md +55 -0
  233. package/agents/skills/coding/git-workflow.skill.md +153 -0
  234. package/agents/skills/coding/metamorphic-testing.skill.md +113 -0
  235. package/agents/skills/coding/mobile-dev.skill.md +41 -0
  236. package/agents/skills/coding/nodejs-expert.skill.md +23 -0
  237. package/agents/skills/coding/output-validation.skill.md +57 -0
  238. package/agents/skills/coding/pbt-strategy.skill.md +117 -0
  239. package/agents/skills/coding/performant-ai.skill.md +62 -0
  240. package/agents/skills/coding/performant-go.skill.md +61 -0
  241. package/agents/skills/coding/performant-laravel.skill.md +70 -0
  242. package/agents/skills/coding/performant-nodejs.skill.md +67 -0
  243. package/agents/skills/coding/performant-php.skill.md +53 -0
  244. package/agents/skills/coding/performant-python.skill.md +62 -0
  245. package/agents/skills/coding/refactor.skill.md +124 -0
  246. package/agents/skills/coding/secure-coding.skill.md +57 -0
  247. package/agents/skills/coding/sketch-to-diagram.skill.md +106 -0
  248. package/agents/skills/coding/spec-driven-development.skill.md +110 -0
  249. package/agents/skills/coding/tdd-cycle.skill.md +92 -0
  250. package/agents/skills/coding/testing-strategy.skill.md +74 -0
  251. package/agents/skills/coding/time-complexity.skill.md +112 -0
  252. package/agents/skills/coding/tldraw-canvas.skill.md +109 -0
  253. package/agents/skills/coding/tool-construction.skill.md +47 -0
  254. package/agents/skills/coding/ui-gen.skill.md +64 -0
  255. package/agents/skills/coding/vibe-coding.skill.md +63 -0
  256. package/agents/skills/coding/visual-design.skill.md +65 -0
  257. package/agents/skills/coordination/agent-interop.skill.md +72 -0
  258. package/agents/skills/coordination/agent-protocol.skill.md +62 -0
  259. package/agents/skills/coordination/agent-workflow-patterns.skill.md +123 -0
  260. package/agents/skills/coordination/agentic-linter.skill.md +134 -0
  261. package/agents/skills/coordination/agentic-patterns.skill.md +79 -0
  262. package/agents/skills/coordination/meta-optimize.skill.md +62 -0
  263. package/agents/skills/coordination/meta-prompting.skill.md +46 -0
  264. package/agents/skills/coordination/multi-agent-orch.skill.md +78 -0
  265. package/agents/skills/coordination/persona-selector.skill.md +78 -0
  266. package/agents/skills/coordination/self-optimize.skill.md +81 -0
  267. package/agents/skills/coordination/swarm-consensus.skill.md +52 -0
  268. package/agents/skills/core/agent-analytics.skill.md +74 -0
  269. package/agents/skills/core/audit-trail.skill.md +122 -0
  270. package/agents/skills/core/clarify.skill.md +89 -0
  271. package/agents/skills/core/emerging-tech.skill.md +52 -0
  272. package/agents/skills/core/empirical-methods.skill.md +101 -0
  273. package/agents/skills/core/evals/clarify.eval.yaml +29 -0
  274. package/agents/skills/core/evals/integrity-check.eval.yaml +23 -0
  275. package/agents/skills/core/evals/research.eval.yaml +23 -0
  276. package/agents/skills/core/final-review.skill.md +66 -0
  277. package/agents/skills/core/integrity-check.skill.md +149 -0
  278. package/agents/skills/core/knowledge-connect.skill.md +77 -0
  279. package/agents/skills/core/knowledge-gap.skill.md +123 -0
  280. package/agents/skills/core/preflight.skill.md +106 -0
  281. package/agents/skills/core/research.skill.md +107 -0
  282. package/agents/skills/core/retrospective.skill.md +59 -0
  283. package/agents/skills/core/sdlc-checkpoint.skill.md +151 -0
  284. package/agents/skills/core/self-heal.skill.md +163 -0
  285. package/agents/skills/core/session-resume.skill.md +125 -0
  286. package/agents/skills/core/skills-registry.skill.md +65 -0
  287. package/agents/skills/core/state-portability.skill.md +89 -0
  288. package/agents/skills/core/state-preserve.skill.md +76 -0
  289. package/agents/skills/core/system-lifecycle.skill.md +51 -0
  290. package/agents/skills/core/update-scan.skill.md +92 -0
  291. package/agents/skills/data/data-engineering.skill.md +56 -0
  292. package/agents/skills/data/data-governance.skill.md +49 -0
  293. package/agents/skills/data/db-migration.skill.md +136 -0
  294. package/agents/skills/data/semantic-web.skill.md +28 -0
  295. package/agents/skills/data/sql-optimization.skill.md +78 -0
  296. package/agents/skills/industry/engineering-standards.skill.md +31 -0
  297. package/agents/skills/industry/global-standards.skill.md +30 -0
  298. package/agents/skills/industry/healthcare-fhir.skill.md +28 -0
  299. package/agents/skills/industry/industrial-iot.skill.md +30 -0
  300. package/agents/skills/industry/telecom-networks.skill.md +30 -0
  301. package/agents/skills/ops/caching-strategy.skill.md +77 -0
  302. package/agents/skills/ops/capacity-planning.skill.md +67 -0
  303. package/agents/skills/ops/cloud-deploy.skill.md +55 -0
  304. package/agents/skills/ops/configuration-management.skill.md +107 -0
  305. package/agents/skills/ops/cost-optimization.skill.md +39 -0
  306. package/agents/skills/ops/decommission-sunset.skill.md +64 -0
  307. package/agents/skills/ops/dependency-lifecycle.skill.md +63 -0
  308. package/agents/skills/ops/deployment.skill.md +217 -0
  309. package/agents/skills/ops/dev-environments.skill.md +31 -0
  310. package/agents/skills/ops/dev-workflow.skill.md +28 -0
  311. package/agents/skills/ops/docker-dev.skill.md +52 -0
  312. package/agents/skills/ops/enterprise-integration.skill.md +53 -0
  313. package/agents/skills/ops/feature-flag-management.skill.md +59 -0
  314. package/agents/skills/ops/incident-response.skill.md +40 -0
  315. package/agents/skills/ops/infra-devops.skill.md +53 -0
  316. package/agents/skills/ops/k8s-dev.skill.md +51 -0
  317. package/agents/skills/ops/memory-optimization.skill.md +45 -0
  318. package/agents/skills/ops/observability-stack-setup.skill.md +62 -0
  319. package/agents/skills/ops/performance-audit.skill.md +178 -0
  320. package/agents/skills/ops/performance-optimization.skill.md +51 -0
  321. package/agents/skills/ops/production-health.skill.md +85 -0
  322. package/agents/skills/ops/production-verifier.skill.md +50 -0
  323. package/agents/skills/ops/queue-management.skill.md +52 -0
  324. package/agents/skills/ops/release-management.skill.md +39 -0
  325. package/agents/skills/ops/release-validation.skill.md +51 -0
  326. package/agents/skills/ops/reliability-sre.skill.md +51 -0
  327. package/agents/skills/ops/runbook-authoring.skill.md +64 -0
  328. package/agents/skills/ops/system-benchmark.skill.md +69 -0
  329. package/agents/skills/ops/tech-debt.skill.md +143 -0
  330. package/agents/skills/ops/troubleshooting-guide.skill.md +31 -0
  331. package/agents/skills/product/accessibility.skill.md +143 -0
  332. package/agents/skills/product/adr-writer.skill.md +110 -0
  333. package/agents/skills/product/business-case.skill.md +70 -0
  334. package/agents/skills/product/change-management.skill.md +90 -0
  335. package/agents/skills/product/decompose.skill.md +75 -0
  336. package/agents/skills/product/design-thinking.skill.md +62 -0
  337. package/agents/skills/product/estimation-sizing.skill.md +87 -0
  338. package/agents/skills/product/evals/spec-writer.eval.yaml +22 -0
  339. package/agents/skills/product/financial-governance.skill.md +88 -0
  340. package/agents/skills/product/green-software.skill.md +46 -0
  341. package/agents/skills/product/ideation-facilitation.skill.md +87 -0
  342. package/agents/skills/product/market-analysis.skill.md +56 -0
  343. package/agents/skills/product/opportunity-assessment.skill.md +89 -0
  344. package/agents/skills/product/product-analytics.skill.md +92 -0
  345. package/agents/skills/product/professional-practice.skill.md +105 -0
  346. package/agents/skills/product/req-elicitation.skill.md +292 -0
  347. package/agents/skills/product/req-review.skill.md +280 -0
  348. package/agents/skills/product/spec-analyze.skill.md +98 -0
  349. package/agents/skills/product/spec-writer.skill.md +114 -0
  350. package/agents/skills/product/stakeholder-management.skill.md +54 -0
  351. package/agents/skills/product/sustainability-checks.skill.md +29 -0
  352. package/agents/skills/product/systems-thinking.skill.md +56 -0
  353. package/agents/skills/product/user-research-synthesis.skill.md +85 -0
  354. package/agents/skills/product/user-story-mapping.skill.md +54 -0
  355. package/agents/skills/product/visual-specs.skill.md +112 -0
  356. package/agents/skills/security/access-control.skill.md +45 -0
  357. package/agents/skills/security/agent-sandboxing.skill.md +69 -0
  358. package/agents/skills/security/ai-ethics-compliance.skill.md +46 -0
  359. package/agents/skills/security/ai-red-teaming.skill.md +74 -0
  360. package/agents/skills/security/ai-safety-guardrails.skill.md +60 -0
  361. package/agents/skills/security/api-security.skill.md +31 -0
  362. package/agents/skills/security/backup-recovery.skill.md +49 -0
  363. package/agents/skills/security/compliance-review.skill.md +152 -0
  364. package/agents/skills/security/cryptography-standards.skill.md +31 -0
  365. package/agents/skills/security/dependency-security.skill.md +47 -0
  366. package/agents/skills/security/hazard-analysis.skill.md +53 -0
  367. package/agents/skills/security/legal-review.skill.md +41 -0
  368. package/agents/skills/security/log-analysis.skill.md +68 -0
  369. package/agents/skills/security/network-security.skill.md +64 -0
  370. package/agents/skills/security/privacy-audit.skill.md +137 -0
  371. package/agents/skills/security/privacy-data-protection.skill.md +31 -0
  372. package/agents/skills/security/prompt-injection-defense.skill.md +67 -0
  373. package/agents/skills/security/reliability-engineering.skill.md +47 -0
  374. package/agents/skills/security/safety-scan.skill.md +49 -0
  375. package/agents/skills/security/secrets-management.skill.md +65 -0
  376. package/agents/skills/security/secure-architecture.skill.md +31 -0
  377. package/agents/skills/security/security-audit.skill.md +164 -0
  378. package/agents/skills/security/threat-model.skill.md +120 -0
  379. package/agents/skills/security/traceability-audit.skill.md +48 -0
  380. package/agents/templates/00-index.md +162 -0
  381. package/agents/templates/architecture/ADAPTIVE_SYSTEM_TEMPLATE.md +35 -0
  382. package/agents/templates/architecture/ADD_WORKBOOK_TEMPLATE.md +81 -0
  383. package/agents/templates/architecture/ADR_TEMPLATE.md +136 -0
  384. package/agents/templates/architecture/ARCHITECTURE_DECISION_MATRIX.md +169 -0
  385. package/agents/templates/architecture/ARCHITECTURE_REVIEW_TEMPLATE.md +241 -0
  386. package/agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md +353 -0
  387. package/agents/templates/architecture/ARCH_DECISION_FRAMEWORK.md +32 -0
  388. package/agents/templates/architecture/C4_ARCHITECTURE_TEMPLATE.md +185 -0
  389. package/agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md +153 -0
  390. package/agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md +196 -0
  391. package/agents/templates/architecture/DESIGN_PATTERN_USAGE.md +24 -0
  392. package/agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md +254 -0
  393. package/agents/templates/architecture/FITNESS_FUNCTION_TEMPLATE.md +59 -0
  394. package/agents/templates/architecture/INTEGRATION_SPEC_TEMPLATE.md +38 -0
  395. package/agents/templates/architecture/LEGACY_AUDIT_TEMPLATE.md +34 -0
  396. package/agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md +210 -0
  397. package/agents/templates/architecture/SCALABILITY_ANALYSIS_TEMPLATE.md +46 -0
  398. package/agents/templates/architecture/SMART_CONTRACT_TEMPLATE.md +44 -0
  399. package/agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md +197 -0
  400. package/agents/templates/brain/ACTIVE_INFERENCE_LOOP_TEMPLATE.md +42 -0
  401. package/agents/templates/brain/EPISODIC_MEMORY_LOG_TEMPLATE.md +28 -0
  402. package/agents/templates/brain/GLOBAL_WORKSPACE_CONFIG_TEMPLATE.md +44 -0
  403. package/agents/templates/brain/KNOWLEDGE_MAP_TEMPLATE.md +53 -0
  404. package/agents/templates/brain/OODA_LOOP_TRACE_TEMPLATE.md +44 -0
  405. package/agents/templates/brain/PREDICTION_ERROR_LOG_TEMPLATE.md +33 -0
  406. package/agents/templates/brain/PROJECT_CONTEXT_TEMPLATE.md +36 -0
  407. package/agents/templates/brain/SELF_IMPROVEMENT_LOG_TEMPLATE.md +39 -0
  408. package/agents/templates/brain/WORKING_MEMORY_TEMPLATE.md +34 -0
  409. package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +30 -0
  410. package/agents/templates/coding/DESIGN_TOKENS_TEMPLATE.json +54 -0
  411. package/agents/templates/coding/DEVCONTAINER_TEMPLATE.json +42 -0
  412. package/agents/templates/coding/DEV_SPACE_TEMPLATE.yaml +48 -0
  413. package/agents/templates/coding/E2E_TEST_SUITE_TEMPLATE.md +36 -0
  414. package/agents/templates/coding/EVAL_PLAN_TEMPLATE.md +85 -0
  415. package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +57 -0
  416. package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +73 -0
  417. package/agents/templates/coding/PROPERTY_TEST_CHECKLIST.md +77 -0
  418. package/agents/templates/coding/SKETCH_TO_DIAGRAM_TEMPLATE.md +56 -0
  419. package/agents/templates/coding/TEST_CASE_TEMPLATE.md +28 -0
  420. package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +36 -0
  421. package/agents/templates/coding/TIME_COMPLEXITY_REPORT_TEMPLATE.md +61 -0
  422. package/agents/templates/coordination/AGENTS_TEMPLATE.md +540 -0
  423. package/agents/templates/coordination/AGENT_HANDSHAKE_TEMPLATE.json +37 -0
  424. package/agents/templates/coordination/AGENT_PROFILE_TEMPLATE.md +28 -0
  425. package/agents/templates/coordination/SWARM_ARCHITECTURE_TEMPLATE.md +53 -0
  426. package/agents/templates/coordination/SWARM_CONFIG_TEMPLATE.json +45 -0
  427. package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +75 -0
  428. package/agents/templates/core/BUG_REPORT_TEMPLATE.md +136 -0
  429. package/agents/templates/core/DEPENDENCY_GRAPH_TEMPLATE.md +63 -0
  430. package/agents/templates/core/ESTIMATION_TEMPLATE.md +70 -0
  431. package/agents/templates/core/MCP_CONFIG_TEMPLATE.json +807 -0
  432. package/agents/templates/core/PLAN_TEMPLATE.md +162 -0
  433. package/agents/templates/core/PROJECT_RETROSPECTIVE_TEMPLATE.md +67 -0
  434. package/agents/templates/core/SDLC_TRACKER.md +217 -0
  435. package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +168 -0
  436. package/agents/templates/core/SYSTEM_ANALYSIS_TEMPLATE.md +52 -0
  437. package/agents/templates/core/TASKS_TEMPLATE.md +104 -0
  438. package/agents/templates/core/TRACEABILITY_MATRIX_TEMPLATE.md +18 -0
  439. package/agents/templates/core/WHITEBOARD_DESIGN_TEMPLATE.md +46 -0
  440. package/agents/templates/data/DATABASE_SCHEMA_TEMPLATE.md +38 -0
  441. package/agents/templates/data/DATA_PIPELINE_TEMPLATE.md +44 -0
  442. package/agents/templates/data/ONTOLOGY_TEMPLATE.md +52 -0
  443. package/agents/templates/industry/ENGINEERING_STANDARDS_REVIEW_TEMPLATE.md +43 -0
  444. package/agents/templates/industry/FHIR_INTEGRATION_TEMPLATE.md +53 -0
  445. package/agents/templates/industry/GLOBAL_STANDARDS_AUDIT_TEMPLATE.md +45 -0
  446. package/agents/templates/industry/IOT_TELEMETRY_TEMPLATE.md +59 -0
  447. package/agents/templates/industry/TELECOM_API_TEMPLATE.md +50 -0
  448. package/agents/templates/ops/BENCHMARK_REPORT_TEMPLATE.md +48 -0
  449. package/agents/templates/ops/CAPACITY_PLAN_TEMPLATE.md +41 -0
  450. package/agents/templates/ops/COST_OPTIMIZATION_REPORT_TEMPLATE.md +40 -0
  451. package/agents/templates/ops/DECOMMISSION_PLAN_TEMPLATE.md +102 -0
  452. package/agents/templates/ops/DEPLOY_CONFIG_TEMPLATE.md +88 -0
  453. package/agents/templates/ops/INCIDENT_POSTMORTEM_TEMPLATE.md +39 -0
  454. package/agents/templates/ops/INFRA_PLAN_TEMPLATE.md +37 -0
  455. package/agents/templates/ops/RELEASE_READINESS_REPORT.md +35 -0
  456. package/agents/templates/ops/RUNBOOK_TEMPLATE.md +103 -0
  457. package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +102 -0
  458. package/agents/templates/product/BUSINESS_CASE_TEMPLATE.md +42 -0
  459. package/agents/templates/product/CHANGE_MANAGEMENT_PLAN_TEMPLATE.md +68 -0
  460. package/agents/templates/product/EMPATHY_MAP_TEMPLATE.md +47 -0
  461. package/agents/templates/product/EXPERIMENT_PLAN_TEMPLATE.md +84 -0
  462. package/agents/templates/product/GREEN_SOFTWARE_REPORT_TEMPLATE.md +42 -0
  463. package/agents/templates/product/IDEATION_LOG_TEMPLATE.md +42 -0
  464. package/agents/templates/product/NFR_TEMPLATE.md +31 -0
  465. package/agents/templates/product/PRD_TEMPLATE.md +222 -0
  466. package/agents/templates/product/PROBLEM_STATEMENT_TEMPLATE.md +32 -0
  467. package/agents/templates/product/REQUIREMENTS_REVIEW_TEMPLATE.md +173 -0
  468. package/agents/templates/product/SPEC_TEMPLATE.md +259 -0
  469. package/agents/templates/product/STAKEHOLDER_REGISTER_TEMPLATE.md +127 -0
  470. package/agents/templates/product/USER_STORY_MAP_TEMPLATE.md +35 -0
  471. package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +207 -0
  472. package/agents/templates/security/DATASHEET_TEMPLATE.md +95 -0
  473. package/agents/templates/security/ETHICAL_IMPACT_ASSESSMENT.md +32 -0
  474. package/agents/templates/security/HAZARD_LOG.md +17 -0
  475. package/agents/templates/security/MODEL_CARD_TEMPLATE.md +120 -0
  476. package/agents/templates/security/SAFETY_CASE.md +39 -0
  477. package/agents/templates/security/SAFETY_POLICY.md +25 -0
  478. package/agents/templates/security/SECURITY_CHECKLIST.md +157 -0
  479. package/agents/templates/security/SYSTEM_CARD_TEMPLATE.md +139 -0
  480. package/agents/templates/security/THREAT_MODEL_TEMPLATE.md +171 -0
  481. package/bin/install.js +572 -0
  482. package/docs/CLI_REFERENCE.md +527 -0
  483. package/docs/INSTALL.md +68 -0
  484. package/docs/MCP_CONFIGURATIONS.md +1765 -0
  485. package/docs/PLATFORM_CONTROLS.md +324 -0
  486. package/docs/POST_INSTALL.md +75 -0
  487. package/docs/QUICK_COMMANDS.md +131 -0
  488. package/docs/QUICK_GUIDE.md +914 -0
  489. package/docs/README_FULL.md +1451 -0
  490. package/docs/SCHEMA.md +164 -0
  491. package/docs/V1_RELEASE_CHECKLIST.md +144 -0
  492. package/docs/VERIFICATION_GUIDE.md +283 -0
  493. package/docs/adr/0001-record-architecture-decisions.md +26 -0
  494. package/docs/adr/0002-brain-active-inference-runtime.md +27 -0
  495. package/docs/adr/0003-additive-only-emitter-schema-evolution.md +33 -0
  496. package/docs/assets/GABBE.png +0 -0
  497. package/docs/gabbe.config.example.json +9 -0
  498. package/docs/reports/duplication-report.md +30 -0
  499. package/install.ps1 +90 -0
  500. package/install.sh +89 -0
  501. package/package.json +49 -0
  502. package/scripts/init.py +1036 -0
@@ -0,0 +1,292 @@
1
+ # Guide: Microservices & Distributed Systems
2
+ <!-- Bounded contexts, event-driven, contract testing, service mesh -->
3
+
4
+ ---
5
+
6
+ ## When to Use Microservices
7
+
8
+ **Use microservices when:**
9
+ - Teams can own and deploy services independently
10
+ - Services have clearly different scaling needs
11
+ - Services have fundamentally different technology requirements
12
+ - Organization is large enough to support operational overhead
13
+
14
+ **Do NOT use microservices when:**
15
+ - Team < 10 engineers (start with modular monolith)
16
+ - Domain is not well understood yet (boundaries will be wrong)
17
+ - Operational maturity is not there (monitoring, tracing, CI/CD)
18
+
19
+ **Start with a modular monolith. Extract services when boundaries are proven.**
20
+
21
+ ---
22
+
23
+ ## Service Decomposition — DDD Bounded Contexts
24
+
25
+ ```
26
+ Decompose by business capability, not technical layer:
27
+
28
+ Good decomposition:
29
+ user-service → Registration, authentication, profile management
30
+ order-service → Order lifecycle, items, pricing
31
+ payment-service → Payment processing, refunds, invoicing
32
+ notification-service → Emails, SMS, push notifications
33
+ inventory-service → Stock management, reservations
34
+
35
+ Bad decomposition (technical layers):
36
+ database-service → No! Databases are infrastructure
37
+ api-gateway-service → No! API gateway is infrastructure
38
+ validation-service → No! Validation belongs in each service
39
+ ```
40
+
41
+ ### Service Boundaries Checklist
42
+
43
+ ```
44
+ A good service boundary:
45
+ [ ] Owns its own data (no shared database between services)
46
+ [ ] Can be deployed independently (no coordinated releases required)
47
+ [ ] Has a clear single business capability
48
+ [ ] Changes don't require simultaneous changes in other services
49
+ [ ] Could use a different technology if needed
50
+ ```
51
+
52
+ ---
53
+
54
+ ## Inter-Service Communication
55
+
56
+ ### Synchronous (HTTP/gRPC) — for queries and commands needing immediate response
57
+
58
+ ```typescript
59
+ // HTTP REST: use for simple CRUD, external-facing APIs
60
+ // Response within: < 500ms (otherwise consider async)
61
+
62
+ // gRPC: use for internal service communication needing strong typing
63
+ // Better for: high-throughput, low-latency, streaming scenarios
64
+ // Use: Protocol Buffers (.proto) for schema definition
65
+
66
+ // Circuit Breaker pattern (prevent cascade failures)
67
+ const circuitBreaker = new CircuitBreaker(callUserService, {
68
+ timeout: 3000, // 3 second timeout
69
+ errorThresholdPercentage: 50, // Open after 50% failures
70
+ resetTimeout: 30000, // Try again after 30 seconds
71
+ });
72
+ ```
73
+
74
+ ### Asynchronous (Message Queues) — for events and commands not needing immediate response
75
+
76
+ ```typescript
77
+ // Event-driven: services react to events, no direct coupling
78
+ // Producer:
79
+ await eventBus.publish({
80
+ type: 'order.created',
81
+ payload: { orderId, userId, total },
82
+ occurredAt: new Date().toISOString(),
83
+ });
84
+
85
+ // Consumer (in notification-service):
86
+ eventBus.subscribe('order.created', async (event) => {
87
+ await sendOrderConfirmationEmail(event.payload.userId);
88
+ });
89
+
90
+ // Message queues: RabbitMQ, Apache Kafka, AWS SQS, Azure Service Bus
91
+ // Choose based on: throughput, ordering guarantees, replay needs
92
+ ```
93
+
94
+ ### Outbox Pattern (ensure at-least-once delivery)
95
+
96
+ ```sql
97
+ -- Save event to outbox table in same DB transaction as business operation
98
+ BEGIN;
99
+ INSERT INTO orders (id, user_id, total) VALUES ($1, $2, $3);
100
+ INSERT INTO outbox_events (type, payload) VALUES ('order.created', $4);
101
+ COMMIT;
102
+ -- Separate process reads outbox and publishes to message broker
103
+ -- Delete from outbox only after confirmed published
104
+ ```
105
+
106
+ ---
107
+
108
+ ## AGENTS.md for Monorepos with Multiple Services
109
+
110
+ ```yaml
111
+ # Root AGENTS.md (global rules)
112
+ project_name: "MyPlatform Monorepo"
113
+ structure: "Multi-service monorepo"
114
+
115
+ # Service-specific AGENTS.md files override root:
116
+ # services/user-service/AGENTS.md
117
+ # services/order-service/AGENTS.md
118
+
119
+ global_rules:
120
+ - "All inter-service HTTP calls must go through the service's client module"
121
+ - "No service may directly query another service's database"
122
+ - "All API contracts defined in services/[name]/openapi.yaml"
123
+ - "All services must expose GET /health returning 200 OK"
124
+ - "All services must emit structured logs in JSON format"
125
+
126
+ global_commands:
127
+ test_all: "pnpm turbo run test"
128
+ build_all: "pnpm turbo run build"
129
+ lint_all: "pnpm turbo run lint"
130
+ ```
131
+
132
+ ---
133
+
134
+ ## Contract Testing with Pact
135
+
136
+ ```typescript
137
+ // Consumer-driven contract testing — consumer defines expectations
138
+ // Provider verifies it meets all consumer contracts
139
+
140
+ // Consumer (order-service) defines contract:
141
+ // pact.spec.ts in order-service
142
+ const provider = new PactV3({
143
+ consumer: 'order-service',
144
+ provider: 'user-service',
145
+ });
146
+
147
+ await provider.addInteraction({
148
+ uponReceiving: 'a request for user profile',
149
+ withRequest: {
150
+ method: 'GET',
151
+ path: '/api/v1/users/123',
152
+ headers: { Authorization: like('Bearer token') },
153
+ },
154
+ willRespondWith: {
155
+ status: 200,
156
+ body: { id: '123', email: like('user@example.com'), name: like('Alice') },
157
+ },
158
+ });
159
+
160
+ // Provider (user-service) verifies it satisfies all consumer contracts:
161
+ // In CI: pact-broker publish → user-service CI fetches and verifies contracts
162
+ ```
163
+
164
+ ---
165
+
166
+ ## Distributed Tracing
167
+
168
+ ```typescript
169
+ // Use OpenTelemetry — standard across all services
170
+ import { trace, context, propagation } from '@opentelemetry/api';
171
+
172
+ // In API gateway / first service — create root trace
173
+ const tracer = trace.getTracer('order-service');
174
+ const span = tracer.startSpan('createOrder');
175
+
176
+ // Propagate trace context to downstream services
177
+ const carrier = {};
178
+ propagation.inject(context.active(), carrier);
179
+ // Add carrier headers to HTTP request to next service
180
+
181
+ // In downstream service — extract and continue trace
182
+ const ctx = propagation.extract(context.active(), incomingHeaders);
183
+ const childSpan = tracer.startSpan('validatePayment', {}, ctx);
184
+ ```
185
+
186
+ **Tools:** Jaeger, Zipkin, AWS X-Ray, Datadog APM, Grafana Tempo
187
+
188
+ ---
189
+
190
+ ## Event Sourcing & CQRS
191
+
192
+ ```typescript
193
+ // Event Sourcing: store events, derive state
194
+ // CQRS: separate read model from write model
195
+
196
+ // Write side: append events
197
+ interface OrderEvent {
198
+ type: 'ORDER_CREATED' | 'ORDER_ITEM_ADDED' | 'ORDER_PAID' | 'ORDER_CANCELLED';
199
+ aggregateId: string;
200
+ sequenceNumber: number;
201
+ occurredAt: Date;
202
+ payload: unknown;
203
+ }
204
+
205
+ // Append to event store (never update/delete)
206
+ await eventStore.append(orderId, [
207
+ { type: 'ORDER_CREATED', payload: { userId, items } }
208
+ ]);
209
+
210
+ // Read side: project events into read model (denormalized for fast reads)
211
+ // Rebuilt from events at any point in time — enables time travel debugging
212
+ ```
213
+
214
+ **When to use:** Financial systems, audit-required systems, complex undo/redo
215
+
216
+ ---
217
+
218
+ ## Service Mesh Patterns
219
+
220
+ ```yaml
221
+ # Kubernetes + Istio/Linkerd for:
222
+ # - mTLS between all services (zero-trust networking)
223
+ # - Load balancing and circuit breaking at infrastructure level
224
+ # - Traffic splitting for canary deployments
225
+
226
+ # Example: Canary deployment via Istio VirtualService
227
+ apiVersion: networking.istio.io/v1alpha3
228
+ kind: VirtualService
229
+ metadata:
230
+ name: user-service
231
+ spec:
232
+ http:
233
+ - route:
234
+ - destination:
235
+ host: user-service
236
+ subset: stable
237
+ weight: 90
238
+ - destination:
239
+ host: user-service
240
+ subset: canary
241
+ weight: 10 # 10% to new version
242
+ ```
243
+
244
+ ---
245
+
246
+ ## Testing Strategy for Microservices
247
+
248
+ | Test Type | Scope | Tools | When |
249
+ |---|---|---|---|
250
+ | Unit | Single function/class | Vitest, Jest, Pest | Every commit |
251
+ | Integration | Single service + DB | Testcontainers, Docker Compose | Every commit |
252
+ | Contract | Consumer/Provider contracts | Pact | Every commit to shared APIs |
253
+ | E2E | Full user flow across services | Playwright + real stack | Before release |
254
+ | Chaos | Resilience to failures | Chaos Monkey, Gremlin | Scheduled |
255
+ | Load | Performance under load | k6, Gatling | Pre-release |
256
+
257
+ ---
258
+
259
+ ## API Gateway Pattern
260
+
261
+ ```
262
+ External clients → API Gateway → Services
263
+
264
+ API Gateway responsibilities:
265
+ - Authentication (validate JWT, session)
266
+ - Rate limiting (per client, per IP)
267
+ - Request routing (path-based, header-based)
268
+ - SSL termination
269
+ - Request/response transformation (if needed)
270
+ - CORS headers
271
+ - Logging / tracing injection
272
+
273
+ API Gateway does NOT:
274
+ - Business logic
275
+ - Database queries
276
+ - Service orchestration (use saga pattern in service layer)
277
+ ```
278
+
279
+ ---
280
+
281
+ ## Key Patterns Summary
282
+
283
+ | Pattern | Problem Solved | When to Use |
284
+ |---|---|---|
285
+ | API Gateway | External routing, auth, rate limiting | Always |
286
+ | Circuit Breaker | Cascade failures | Synchronous calls between services |
287
+ | Outbox | At-least-once event delivery | Critical events (payments, orders) |
288
+ | Saga | Distributed transactions | Multi-service operations |
289
+ | CQRS | Read/write model separation | High-read systems |
290
+ | Event Sourcing | Complete audit trail, time travel | Financial, regulated systems |
291
+ | Strangler Fig | Incremental migration from monolith | Legacy modernization |
292
+ | BFF | Per-client API tailoring | Mobile + Web with different needs |
@@ -0,0 +1,303 @@
1
+ # Guide: Monolith & Modular Monolith
2
+ <!-- Vertical slice architecture, module boundaries, Strangler Fig migration -->
3
+
4
+ ---
5
+
6
+ ## Monolith vs Modular Monolith vs Microservices
7
+
8
+ ```
9
+ Traditional Monolith:
10
+ One codebase, tightly coupled, no module boundaries
11
+ Fast to start, impossible to scale teams beyond ~5 engineers
12
+ Avoid for new projects unless extremely time-constrained
13
+
14
+ Modular Monolith (recommended starting point):
15
+ One codebase, modules with enforced boundaries
16
+ Modules can be extracted to services when needed (Strangler Fig)
17
+ Best for: < 50 engineers, domain not fully understood yet
18
+
19
+ Microservices:
20
+ Multiple codebases, independent deployments
21
+ Best for: > 50 engineers, proven domain boundaries, strong DevOps
22
+ See: guides/architecture/microservices.md
23
+ ```
24
+
25
+ **Start with modular monolith. Extract microservices only when boundaries are proven and scale demands it.**
26
+
27
+ ---
28
+
29
+ ## Modular Monolith — Vertical Slice Architecture
30
+
31
+ ```
32
+ src/
33
+ modules/ # Each module = bounded context
34
+ users/
35
+ domain/ # Pure business logic
36
+ user.entity.ts
37
+ user.repository.ts # Interface
38
+ application/
39
+ create-user.use-case.ts
40
+ get-user.use-case.ts
41
+ infrastructure/
42
+ prisma-user.repository.ts
43
+ http/
44
+ users.controller.ts
45
+ users.routes.ts
46
+ index.ts # Public API: what this module exports
47
+ # Everything else is private to this module
48
+
49
+ orders/
50
+ domain/
51
+ order.entity.ts
52
+ order-item.entity.ts
53
+ application/
54
+ create-order.use-case.ts
55
+ infrastructure/
56
+ prisma-order.repository.ts
57
+ http/
58
+ orders.controller.ts
59
+ index.ts
60
+
61
+ payments/
62
+ domain/
63
+ application/
64
+ infrastructure/
65
+ index.ts
66
+
67
+ shared/ # ONLY for truly shared utilities
68
+ domain/
69
+ value-objects/ # Money.ts, Address.ts (used by multiple modules)
70
+ infrastructure/
71
+ database/ # Prisma client singleton
72
+ cache/ # Redis client
73
+ lib/
74
+ result.ts # Result<T, E> type
75
+ logger.ts # Logger configuration
76
+
77
+ main/ # Bootstrap — wires modules together
78
+ server.ts
79
+ container.ts
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Module Boundary Rules
85
+
86
+ ```typescript
87
+ // RULE: Modules communicate ONLY through their public API (index.ts)
88
+ // Internal types are module-private — not imported directly
89
+
90
+ // users/index.ts — public API
91
+ export type { UserId, UserDto } from './domain/user.entity';
92
+ export { CreateUserUseCase } from './application/create-user.use-case';
93
+ export type { IUserRepository } from './domain/user.repository';
94
+
95
+ // orders module can use users public API:
96
+ import type { UserId } from '@/modules/users'; // CORRECT — through public API
97
+
98
+ // orders module CANNOT:
99
+ import { User } from '@/modules/users/domain/user.entity'; // WRONG — internal type
100
+ import { PrismaUserRepository } from '@/modules/users/infrastructure/...'; // WRONG
101
+ ```
102
+
103
+ ### Enforce with dependency-cruiser
104
+
105
+ ```javascript
106
+ // .dependency-cruiser.cjs
107
+ module.exports = {
108
+ forbidden: [
109
+ {
110
+ name: 'no-cross-module-internal-access',
111
+ severity: 'error',
112
+ from: { path: '^src/modules/([^/]+)' },
113
+ to: {
114
+ path: '^src/modules/([^/]+)/(domain|application|infrastructure)',
115
+ // Allow if module names match (accessing own internals)
116
+ pathNot: '^src/modules/$1'
117
+ }
118
+ },
119
+ {
120
+ name: 'no-cross-module-imports',
121
+ severity: 'error',
122
+ from: { path: '^src/modules/([^/]+)' },
123
+ to: { path: '^src/modules/([^/]+)' },
124
+ // Must go through the public index, not internal paths
125
+ }
126
+ ]
127
+ };
128
+ ```
129
+
130
+ ---
131
+
132
+ ## Module Communication Patterns
133
+
134
+ ### Direct (In-Process)
135
+ ```typescript
136
+ // Same process — inject use case across modules
137
+ // Orders module depends on Users module public API
138
+
139
+ class CreateOrderUseCase {
140
+ constructor(
141
+ private readonly orderRepo: IOrderRepository,
142
+ private readonly getUser: GetUserUseCase, // From users module
143
+ ) {}
144
+
145
+ async execute(command: CreateOrderCommand) {
146
+ const user = await this.getUser.execute({ id: command.userId });
147
+ if (!user) throw new UserNotFoundError(command.userId);
148
+ // ... create order
149
+ }
150
+ }
151
+ ```
152
+
153
+ ### Event-Driven (In-Process Event Bus)
154
+ ```typescript
155
+ // Loose coupling within the monolith — modules don't know about each other
156
+ // Best for: side effects (notifications, analytics, audit log)
157
+
158
+ // Orders module publishes
159
+ eventBus.publish(new OrderCreatedEvent(order.id, order.userId));
160
+
161
+ // Notifications module subscribes
162
+ eventBus.subscribe(OrderCreatedEvent, async (event) => {
163
+ await sendOrderConfirmationEmail(event.userId);
164
+ });
165
+ ```
166
+
167
+ ### Shared Database (with Module-Scoped Tables)
168
+ ```sql
169
+ -- Even in a monolith, namespace tables by module:
170
+ users_accounts -- users module
171
+ users_sessions -- users module
172
+ orders_orders -- orders module
173
+ orders_items -- orders module
174
+ payments_invoices -- payments module
175
+
176
+ -- Module-scoped: orders module NEVER queries users_* tables directly
177
+ -- It uses the users module's public API (use case or repository interface)
178
+ ```
179
+
180
+ ---
181
+
182
+ ## Feature Flagging for Safe Rollout
183
+
184
+ ```typescript
185
+ // Use feature flags to deploy new code safely
186
+ // LaunchDarkly, Flipt, Growthbook, or simple env-var-based
187
+
188
+ async function getCheckoutPage(user: User): Promise<CheckoutPage> {
189
+ const isNewCheckoutEnabled = await featureFlags.isEnabled(
190
+ 'new-checkout-flow',
191
+ { userId: user.id, email: user.email }
192
+ );
193
+
194
+ if (isNewCheckoutEnabled) {
195
+ return newCheckoutService.render(user);
196
+ }
197
+ return legacyCheckoutService.render(user);
198
+ }
199
+ ```
200
+
201
+ ---
202
+
203
+ ## Testing Strategy for Monolith
204
+
205
+ ```
206
+ Unit tests (fast — no I/O):
207
+ Test domain entities and use cases in isolation
208
+ Mock repositories and external services
209
+ ~300ms for full suite
210
+
211
+ Module integration tests:
212
+ Test each module against real database (test schema)
213
+ Use Testcontainers for ephemeral PostgreSQL
214
+ Test: full flow from HTTP request → database
215
+
216
+ Cross-module integration tests:
217
+ Test interactions between modules
218
+ Verify that module public APIs work as expected
219
+ Test event-driven side effects
220
+
221
+ E2E tests (slow — real browser):
222
+ Happy path user journeys
223
+ Critical business flows only
224
+ Run in CI before release
225
+ ```
226
+
227
+ ---
228
+
229
+ ## Strangler Fig Pattern — Extracting Services
230
+
231
+ When a module needs to become its own microservice:
232
+
233
+ ```
234
+ Phase 1: Identify the extraction target
235
+ - Module with different scaling needs
236
+ - Module with its own team
237
+ - Module with proven boundaries
238
+
239
+ Phase 2: Add a facade
240
+ - Create an HTTP client interface in front of the module
241
+ - Other modules use the client (not internal module)
242
+ - Initially the client calls the local module (no network hop)
243
+
244
+ Phase 3: Extract to separate service
245
+ - Deploy the module as a separate service
246
+ - Update the client to make real HTTP calls
247
+ - Other modules require zero changes
248
+
249
+ Phase 4: Remove from monolith
250
+ - Once all traffic goes through the external service
251
+ - Delete the module from the monolith
252
+
253
+ Each phase: fully tested, independently deployable, zero downtime
254
+ ```
255
+
256
+ ```typescript
257
+ // Phase 2: Facade (local call, same process)
258
+ class UserServiceClient {
259
+ constructor(private readonly getUserUseCase: GetUserUseCase) {}
260
+
261
+ async getUser(id: string): Promise<UserDto | null> {
262
+ return this.getUserUseCase.execute({ id }); // Local call
263
+ }
264
+ }
265
+
266
+ // Phase 3: Facade updated (remote HTTP call, no changes to consumers)
267
+ class UserServiceClient {
268
+ async getUser(id: string): Promise<UserDto | null> {
269
+ const response = await fetch(`${USER_SERVICE_URL}/api/v1/users/${id}`);
270
+ if (response.status === 404) return null;
271
+ return response.json();
272
+ }
273
+ }
274
+ ```
275
+
276
+ ---
277
+
278
+ ## Monolith Health Indicators
279
+
280
+ Track these metrics to know when to consider extraction:
281
+
282
+ ```
283
+ Coupling metrics:
284
+ - Afferent coupling (Ca) per module — how many other modules depend on it
285
+ - Build time increasing despite unchanged code (coupling growing)
286
+ - Test suite > 10 minutes (usually coupling + lack of isolation)
287
+
288
+ Deployment metrics:
289
+ - Small changes require full regression test suite
290
+ - Two teams waiting on each other's deployments
291
+ - Rollback of one feature requires reverting unrelated code
292
+
293
+ Team metrics:
294
+ - > 5 engineers modifying same module regularly
295
+ - "Stepping on each other's toes" incidents
296
+ - Code reviews involving people outside the feature's team
297
+
298
+ Scale metrics:
299
+ - Can't scale one part without scaling everything
300
+ - One heavy process (video processing, ML inference) starving HTTP handlers
301
+ ```
302
+
303
+ When you see 3+ of these: it's time to extract the most independent module.
@@ -0,0 +1,75 @@
1
+ # Loki & Brain — Agentic Orchestration
2
+
3
+ This directory contains the **High-Level Orchestrators** for the Agentic Engineering Kit.
4
+
5
+ ## Modes
6
+
7
+ ### 1. 🧠 Brain Mode (`brain-mode.skill.md`)
8
+ > **The Strategist (System 2)**
9
+
10
+ - **Role**: Meta-Cognitive Orchestrator.
11
+ - **Function**: Plans, Routes, and Optimizes.
12
+ - **Logic**: Active Inference (Free Energy Principle).
13
+ - **Use Case**: Complex, ambiguous, or high-stakes projects.
14
+ - **Key Feature**: **Dynamic Cost Routing** (Local vs Remote).
15
+
16
+ **Trigger**: `brain activate`, `supermode`
17
+
18
+ ---
19
+
20
+ ### 2. ⚡ Loki Mode (`loki-mode.skill.md`)
21
+ > **The Executor (System 1)**
22
+
23
+ - **Role**: SDLC Orchestrator.
24
+ - **Function**: Executes the 10-Phase Engineering Lifecycle.
25
+ - **Logic**: Deterministic Workflow (S01 -> S10).
26
+ - **Use Case**: Building software with strict process requirements.
27
+ - **Key Feature**: **Human-in-the-Loop Gates**.
28
+
29
+ **Trigger**: `loki`, `orchestrate`
30
+
31
+ ---
32
+
33
+ ## How they work together
34
+
35
+ Brain Mode **wraps** Loki Mode.
36
+
37
+ 1. **Brain Mode** receives a request ("Build X").
38
+ 2. It analyzes complexity and budget.
39
+ 3. It spins up **Loki Mode** to handle the SDLC.
40
+ 4. It monitors Loki's progress, intervening if:
41
+ - Costs spike.
42
+ - Errors loop.
43
+ - Requirements drift.
44
+
45
+ ```mermaid
46
+ graph TD
47
+ User -->|Request| Brain[🧠 Brain Mode]
48
+ Brain -->|Route: Complex| Loki[⚡ Loki Exec Layer]
49
+ Brain -->|Route: Simple| Local[💻 Local Script]
50
+ Loki -->|Phase S01-S10| Artifacts[📂 Project Files]
51
+ Brain -.->|Monitor| Loki
52
+ ```
53
+
54
+ ```text
55
+ [User] --(Request)--> [Brain Mode 🧠]
56
+ |
57
+ +--(Route: Complex)--> [Loki Exec Layer ⚡] --(Phase S01-S10)--> [Project Files 📂]
58
+ | ^
59
+ | | (Monitor)
60
+ | |
61
+ +--(Route: Simple)---- [Local Script 💻]
62
+ ```
63
+
64
+ ---
65
+
66
+ ## CLI Reference
67
+
68
+ In addition to Agent slash commands, you can orchestrate these modes via the GABBE CLI:
69
+
70
+ | Mode | CLI Command | Purpose |
71
+ |---|---|---|
72
+ | **Brain** | `gabbe brain` | Activates Active Inference and Cost Routing. |
73
+ | **Loki** | `gabbe status` | Visualizes swarm progress and SDLC phase. |
74
+ | **Sync** | `gabbe sync` | Ensures Markdown memory and SQLite stays in sync. |
75
+ | **Verify** | `gabbe verify` | Runs the automated gate checks for the current phase. |