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,56 @@
1
+ # Node.js & Advanced TypeScript Mastery
2
+
3
+ > **Source Origin**: Distilled from Matteo Collina's expert capabilities (`fastify`, `nodejs-core`, `typescript-magician`, `node`, `oauth`, `linting-neostandard-eslint9`).
4
+
5
+ This guide enforces the highest tier of architecture, performance, and type-safety standards for Node.js development in the GABBE environment.
6
+
7
+ ---
8
+
9
+ ## 1. Fastify & Architecture Best Practices
10
+
11
+ Fastify is optimized for speed and low overhead. When working with Fastify:
12
+
13
+ - **Encapsulation**: Leverage Fastify's plugin system (`fastify-plugin`) to logically separate routes, decorators, and hooks. Never attach global state tightly.
14
+ - **Schema-First Design**: Always define JSON Schemas (`typebox` or `fluent-json-schema`) for route validation (body, querystring, params, headers) and serialization (response). Fastify compiles these to highly optimized code.
15
+ - **Async/Await Hooks**: Utilize `onRequest`, `preParsing`, `preValidation`, `preHandler`, etc., avoiding legacy callbacks.
16
+ - **Inject Testing**: Test HTTP completely in-memory using `app.inject()`. Never run a live server on a port for unit or integration testing of route handlers.
17
+ - **Logging**: Use `pino` (Fastify's default). Avoid `console.log` in production routines.
18
+ - **Error Handling**: Create centralized custom error handlers (`fastify.setErrorHandler`). Do not leak stack traces in 5xx HTTP responses.
19
+
20
+ ## 2. Node.js Core & Internals
21
+
22
+ Deep structural knowledge is critical for scaling.
23
+
24
+ - **Event Loop Mechanics**: Understand the phases (timers, pending callbacks, idle/prepare, poll, check, close callbacks). Do not block the event loop (avoid `fs.readFileSync` or CPU-heavy sync crypto).
25
+ - **Worker Threads**: Use `worker_threads` for CPU-bound tasks, not for I/O. Use `SharedArrayBuffer` with `Atomics` for high-performance intra-thread communication.
26
+ - **V8 & Memory Management**:
27
+ - Keep object shapes (hidden classes) stable to enable V8 TurboFan optimizations (Inline Caching).
28
+ - Avoid memory leaks by managing closures properly and nullifying large unused references.
29
+ - Use `v8` heap snapshots and `llnode` or Chrome DevTools for native memory analysis.
30
+ - **Native Addons**: When writing C++ addons, always use `N-API` (`node-addon-api`) to achieve ABI stability across Node versions. Mind memory transitions across the JS/C++ boundary.
31
+ - **Streams**: Favor the Pipeline API (`stream/promises`) for backpressure management instead of `.pipe()`.
32
+
33
+ ## 3. TypeScript "Magician" Level (Zero `any`)
34
+
35
+ TypeScript is a superpower, not a constraint. `any` must be completely eradicated.
36
+
37
+ - **No `any`**: If a type is unknown at runtime, use `unknown` and narrow it via type guards (`typeof`, `instanceof`, or custom type predicates like `isMyType(val: unknown): val is MyType`).
38
+ - **Advanced Generics**: Leverage generic constraints (`T extends B`), conditional types (`T extends U ? X : Y`), and `infer` keyword to pull types out of complex structures.
39
+ - **Utility Types**: Master `Awaited<T>`, `Parameters<T>`, `ReturnType<T>`, `Record<K, V>`, `Omit<T, K>`, and `Pick<T, K>`.
40
+ - **Mapped & Template Literal Types**: Use `[K in keyof T]: ...` and `\${string}_\${string}` for stringent state modeling.
41
+ - **Discriminated Unions**: Model states explicitly (e.g., `{ status: 'success', data: Data } | { status: 'error', error: Error }`) rather than optional properties.
42
+ - **Opaque / Brand Types**: Differentiate simple primitives (like IDs) logically at compile time (e.g., `type UserId = string & { readonly __brand: unique symbol }`).
43
+
44
+ ## 4. OAuth & Security Workflow
45
+
46
+ - **Strict RFC Compliance**: Strictly implement OAuth 2.0/2.1 flows (PKCE for SPAs/mobile, Client Credentials for machine-to-machine).
47
+ - **Token Handling**: Never store access tokens in `localStorage`. Use secure, `HttpOnly`, `SameSite=Strict` cookies or transient in-memory states.
48
+ - **Validation**: Validate all JWT scopes, audiences (`aud`), and issuers (`iss`) at the API edge natively through Fastify hooks.
49
+
50
+ ## 5. Modern Linting
51
+
52
+ - **ESLint v9 + Neostandard**: Utilize Flat Config (`eslint.config.js`).
53
+ - Enforce stylistic guarantees automatically and treat linting issues as build failures (warnings are errors in CI).
54
+
55
+ ---
56
+ *For AI Agents: By reading this guide, you are contractually bound under the project CONSTITUTION.md to enforce strict typing (zero any), Fastify schemas, and non-blocking I/O.*
@@ -0,0 +1,376 @@
1
+ # Guide: PHP / Laravel
2
+ <!-- DDD with Laravel, Actions pattern, Pest PHP, PHPStan Level 9 -->
3
+
4
+ ---
5
+
6
+ ## Directory Structure — DDD + Actions Pattern
7
+
8
+ ```
9
+ app/
10
+ Domain/ # Business logic — NO Laravel imports
11
+ User/
12
+ Entities/
13
+ User.php # Domain entity with invariants
14
+ ValueObjects/
15
+ Email.php # Typed value object
16
+ UserId.php
17
+ Events/
18
+ UserRegistered.php # Domain event
19
+ Repositories/
20
+ IUserRepository.php # Interface — implemented in Infrastructure
21
+ Exceptions/
22
+ EmailAlreadyExistsException.php
23
+
24
+ Application/ # Orchestrates domain — Actions pattern
25
+ User/
26
+ CreateUser/
27
+ CreateUserAction.php # Single-responsibility action
28
+ CreateUserData.php # Typed DTO (Spatie Laravel Data)
29
+ CreateUserResult.php # Return DTO
30
+ GetUser/
31
+ GetUserAction.php
32
+
33
+ Infrastructure/ # Laravel implementations
34
+ Database/
35
+ User/
36
+ EloquentUserRepository.php # Implements IUserRepository
37
+ UserModel.php # Eloquent model (infrastructure concern)
38
+ Migrations/
39
+ Mail/
40
+ WelcomeEmail.php
41
+ Queue/
42
+ SendWelcomeEmailJob.php
43
+
44
+ Http/ # Laravel HTTP layer — thin
45
+ Controllers/
46
+ Api/
47
+ UserController.php # Delegates to Application layer actions
48
+ Requests/
49
+ CreateUserRequest.php # FormRequest validation
50
+ Resources/
51
+ UserResource.php # API response formatting (JsonResource)
52
+
53
+ tests/
54
+ Unit/ # Domain + Application tests (no DB)
55
+ Feature/ # HTTP + Database tests (RefreshDatabase)
56
+ Browser/ # Dusk browser tests (or Pest Browser)
57
+ ```
58
+
59
+ ---
60
+
61
+ ## AGENTS.md Snippet (Laravel project)
62
+
63
+ ```yaml
64
+ runtime: PHP 8.4 # 8.5 current stable (verified 2026-06)
65
+ language: PHP (typed, strict)
66
+ framework: Laravel 12.x # min PHP 8.2
67
+ package_manager: Composer 2.x
68
+
69
+ install: composer install
70
+ dev: php artisan serve
71
+ test: php artisan test
72
+ test_coverage: php artisan test --coverage
73
+ test_single: vendor/bin/pest tests/Unit/Domain/UserTest.php
74
+ build: composer install --no-dev --optimize-autoloader
75
+ typecheck: vendor/bin/phpstan analyse --level=9
76
+ lint: vendor/bin/pint --test
77
+ format: vendor/bin/pint
78
+ security_scan: composer audit
79
+ migrate: php artisan migrate
80
+ ```
81
+
82
+ ---
83
+
84
+ ## Tech Stack
85
+
86
+ ### Core
87
+ | Role | Library | Why |
88
+ |---|---|---|
89
+ | Framework | Laravel 12.x | Full-stack, mature ecosystem (min PHP 8.2) |
90
+ | DTOs | `spatie/laravel-data` | Typed DTOs with casting + validation |
91
+ | State Machine | `spatie/laravel-model-states` | Enum-like states with transitions |
92
+ | Query Builder | Eloquent (with Spatie QueryBuilder) | Flexible, typed |
93
+ | API docs | Scribe (`knuckleswtf/scribe`) | Auto-generates from controllers |
94
+
95
+ ### Testing
96
+ | Role | Library | Command |
97
+ |---|---|---|
98
+ | Unit + Feature | Pest PHP | `php artisan test` or `vendor/bin/pest` |
99
+ | Browser | Pest Browser plugin or Laravel Dusk | `php artisan dusk` |
100
+ | Coverage | Xdebug + PCOV | `php artisan test --coverage` |
101
+ | HTTP mocking | Laravel's `Http::fake()` | Built-in |
102
+
103
+ ### Security
104
+ | Role | Library | Command |
105
+ |---|---|---|
106
+ | Dep audit | `composer audit` | Built-in Composer 2.4+ |
107
+ | SAST/Security | Enlightn | `php artisan enlightn` |
108
+ | Static analysis | PHPStan Level 9 | `vendor/bin/phpstan analyse` |
109
+ | Vulnerability db | `roave/security-advisories` | Added to composer.json (blocks installs) |
110
+ | Secret detection | gitleaks | `gitleaks detect --source=.` |
111
+ | Architecture | deptrac | `vendor/bin/deptrac analyse` |
112
+
113
+ ---
114
+
115
+ ## Patterns
116
+
117
+ ### Domain Entity
118
+
119
+ ```php
120
+ // app/Domain/User/Entities/User.php
121
+ declare(strict_types=1);
122
+
123
+ namespace App\Domain\User\Entities;
124
+
125
+ use App\Domain\User\ValueObjects\Email;
126
+ use App\Domain\User\ValueObjects\UserId;
127
+ use App\Domain\User\Events\UserRegistered;
128
+
129
+ final class User
130
+ {
131
+ /** @var list<object> */
132
+ private array $events = [];
133
+
134
+ private function __construct(
135
+ public readonly UserId $id,
136
+ public readonly Email $email,
137
+ public readonly string $name,
138
+ public readonly \DateTimeImmutable $createdAt,
139
+ ) {}
140
+
141
+ public static function create(Email $email, string $name): self
142
+ {
143
+ $user = new self(UserId::generate(), $email, $name, new \DateTimeImmutable());
144
+ $user->events[] = new UserRegistered($user->id->value, $user->email->value);
145
+ return $user;
146
+ }
147
+
148
+ /** @return list<object> */
149
+ public function releaseEvents(): array
150
+ {
151
+ $events = $this->events;
152
+ $this->events = [];
153
+ return $events;
154
+ }
155
+ }
156
+ ```
157
+
158
+ ### Value Object
159
+
160
+ ```php
161
+ // app/Domain/User/ValueObjects/Email.php
162
+ declare(strict_types=1);
163
+
164
+ namespace App\Domain\User\ValueObjects;
165
+
166
+ use App\Domain\User\Exceptions\InvalidEmailException;
167
+
168
+ final readonly class Email
169
+ {
170
+ public string $value;
171
+
172
+ private function __construct(string $value)
173
+ {
174
+ $this->value = $value;
175
+ }
176
+
177
+ public static function create(string $value): self
178
+ {
179
+ if (!filter_var($value, FILTER_VALIDATE_EMAIL) || strlen($value) > 255) {
180
+ throw new InvalidEmailException("Invalid email: {$value}");
181
+ }
182
+ return new self(strtolower(trim($value)));
183
+ }
184
+
185
+ public function equals(self $other): bool
186
+ {
187
+ return $this->value === $other->value;
188
+ }
189
+ }
190
+ ```
191
+
192
+ ### Typed DTO (Spatie Laravel Data)
193
+
194
+ ```php
195
+ // app/Application/User/CreateUser/CreateUserData.php
196
+ declare(strict_types=1);
197
+
198
+ namespace App\Application\User\CreateUser;
199
+
200
+ use Spatie\LaravelData\Attributes\Validation\Email;
201
+ use Spatie\LaravelData\Attributes\Validation\Max;
202
+ use Spatie\LaravelData\Attributes\Validation\Min;
203
+ use Spatie\LaravelData\Data;
204
+
205
+ final class CreateUserData extends Data
206
+ {
207
+ public function __construct(
208
+ #[Email, Max(255)]
209
+ public readonly string $email,
210
+
211
+ #[Min(1), Max(100)]
212
+ public readonly string $name,
213
+ ) {}
214
+ }
215
+ ```
216
+
217
+ ### Single-Responsibility Action
218
+
219
+ ```php
220
+ // app/Application/User/CreateUser/CreateUserAction.php
221
+ declare(strict_types=1);
222
+
223
+ namespace App\Application\User\CreateUser;
224
+
225
+ use App\Domain\User\Entities\User;
226
+ use App\Domain\User\Repositories\IUserRepository;
227
+ use App\Domain\User\ValueObjects\Email;
228
+ use App\Domain\User\Exceptions\EmailAlreadyExistsException;
229
+ use Illuminate\Contracts\Events\Dispatcher;
230
+
231
+ final class CreateUserAction
232
+ {
233
+ public function __construct(
234
+ private readonly IUserRepository $userRepository,
235
+ private readonly Dispatcher $eventDispatcher,
236
+ ) {}
237
+
238
+ public function execute(CreateUserData $data): CreateUserResult
239
+ {
240
+ $email = Email::create($data->email);
241
+
242
+ if ($this->userRepository->findByEmail($email) !== null) {
243
+ throw new EmailAlreadyExistsException($email->value);
244
+ }
245
+
246
+ $user = User::create($email, $data->name);
247
+ $this->userRepository->save($user);
248
+
249
+ foreach ($user->releaseEvents() as $event) {
250
+ $this->eventDispatcher->dispatch($event);
251
+ }
252
+
253
+ return new CreateUserResult(id: $user->id->value);
254
+ }
255
+ }
256
+ ```
257
+
258
+ ### Thin Controller
259
+
260
+ ```php
261
+ // app/Http/Controllers/Api/UserController.php
262
+ declare(strict_types=1);
263
+
264
+ namespace App\Http\Controllers\Api;
265
+
266
+ use App\Application\User\CreateUser\CreateUserAction;
267
+ use App\Application\User\CreateUser\CreateUserData;
268
+ use App\Http\Resources\UserResource;
269
+ use Illuminate\Http\JsonResponse;
270
+ use Illuminate\Http\Request;
271
+
272
+ final class UserController
273
+ {
274
+ public function store(Request $request, CreateUserAction $action): JsonResponse
275
+ {
276
+ $result = $action->execute(CreateUserData::from($request->validated()));
277
+ return response()->json(['id' => $result->id], 201);
278
+ }
279
+ }
280
+ ```
281
+
282
+ ---
283
+
284
+ ## Security Best Practices
285
+
286
+ ```php
287
+ // config/security-headers.php (or via middleware)
288
+ // Use spatie/laravel-csp for Content Security Policy
289
+
290
+ // NEVER: raw user input in queries
291
+ $users = DB::select("SELECT * FROM users WHERE email = '{$request->email}'"); // SQL INJECTION!
292
+
293
+ // CORRECT: Eloquent or parameterized
294
+ $user = User::where('email', $request->email)->first();
295
+ // OR: parameterized
296
+ $users = DB::select('SELECT * FROM users WHERE email = ?', [$request->email]);
297
+
298
+ // Mass assignment protection
299
+ protected $fillable = ['name', 'email']; // Explicit allowlist
300
+ // NEVER: protected $guarded = []; (disables protection)
301
+
302
+ // Rate limiting (in RouteServiceProvider or routes)
303
+ Route::middleware(['throttle:5,1'])->group(function () {
304
+ Route::post('/auth/login', [AuthController::class, 'login']);
305
+ });
306
+ ```
307
+
308
+ ---
309
+
310
+ ## Tech Debt Detection
311
+
312
+ ```bash
313
+ # PHPStan (type safety) — Level 9 is maximum
314
+ vendor/bin/phpstan analyse app/ --level=9
315
+
316
+ # PHP Mess Detector (complexity, duplication)
317
+ vendor/bin/phpmd app/ text cleancode,codesize,controversial,design,naming,unusedcode
318
+
319
+ # PHP Code Sniffer (code style)
320
+ vendor/bin/phpcs --standard=PSR12 app/
321
+
322
+ # Deptrac (architecture layer enforcement)
323
+ vendor/bin/deptrac analyse --config-file deptrac.yaml
324
+
325
+ # Check for outdated dependencies
326
+ composer outdated
327
+
328
+ # Security vulnerabilities
329
+ composer audit
330
+ ```
331
+
332
+ ---
333
+
334
+ ## deptrac.yaml (Architecture Enforcement)
335
+
336
+ ```yaml
337
+ # deptrac.yaml
338
+ parameters:
339
+ paths:
340
+ - ./app
341
+ layers:
342
+ - name: Domain
343
+ collectors:
344
+ - type: directory
345
+ value: Domain/.*
346
+ - name: Application
347
+ collectors:
348
+ - type: directory
349
+ value: Application/.*
350
+ - name: Infrastructure
351
+ collectors:
352
+ - type: directory
353
+ value: Infrastructure/.*
354
+ - name: Http
355
+ collectors:
356
+ - type: directory
357
+ value: Http/.*
358
+ ruleset:
359
+ Domain: # Domain can only depend on itself
360
+ - ~Application
361
+ - ~Infrastructure
362
+ - ~Http
363
+ Application: # Application can use Domain
364
+ - Domain
365
+ Infrastructure: # Infrastructure implements Domain interfaces
366
+ - Domain
367
+ Http: # HTTP can use Application (not Domain directly)
368
+ - Application
369
+ ```
370
+
371
+ ---
372
+
373
+ ## See Also
374
+ - [Performant Laravel Skill](../../skills/coding/performant-laravel.skill.md) — High-performance Laravel.
375
+ - [Artisan Commands Skill](../../skills/coding/artisan-commands.skill.md) — Laravel task automation.
376
+ - [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — OWASP Top 10 for Laravel.
@@ -0,0 +1,257 @@
1
+ # Guide: Python / FastAPI / AI
2
+ <!-- Clean Architecture with Python 3.12+, FastAPI, SQLAlchemy, Pydantic, and AI Agents -->
3
+
4
+ ---
5
+
6
+ ## Directory Structure — Clean Architecture
7
+
8
+ ```
9
+ src/
10
+ domain/ # Pure business logic — NO framework imports
11
+ entities/ # user.py, order.py — domain entities (Pydantic/Dataclasses)
12
+ value_objects/ # email.py, money.py — immutable primitives
13
+ events/ # user_registered.py — domain events
14
+ ports/ # i_user_repository.py — interfaces only (Protocol)
15
+ exceptions/ # domain_error.py — base exceptions
16
+ services/ # Pure domain services
17
+
18
+ application/ # Use cases — orchestrates domain
19
+ users/
20
+ create_user_use_case.py
21
+ create_user_command.py
22
+ create_user_result.py
23
+
24
+ adapters/ # Interface adapters
25
+ api/ # FastAPI routers & controllers
26
+ users_router.py
27
+ users_schema.py # Pydantic schemas for request/response
28
+ presenters/ # Formatters
29
+
30
+ infrastructure/ # Framework + external services
31
+ database/
32
+ sqlalchemy_user_repository.py
33
+ llm/ # AI Model implementations
34
+ openai_service.py
35
+ langchain_adapter.py
36
+ vector_store/
37
+ qdrant_service.py
38
+
39
+ main/ # Composition root
40
+ container.py # Dependency Injection (Dependency Injector or fast_depends)
41
+ main.py # FastAPI app entrypoint
42
+
43
+ tests/
44
+ unit/ # Fast, no I/O
45
+ integration/ # Docker containers (Testcontainers)
46
+ e2e/ # Full API tests
47
+ ```
48
+
49
+ ---
50
+
51
+ ## Layer Import Rules
52
+
53
+ ```python
54
+ # domain/ — MUST NOT import from any other layer
55
+ # application/ — MAY import from domain only
56
+ # adapters/ — MAY import from domain + application
57
+ # infrastructure/ — MAY import from domain (implements interfaces)
58
+ # main/ — MAY import from all layers (composition root)
59
+
60
+ # CORRECT: infrastructure depends on domain interface
61
+ from src.domain.ports.i_user_repository import IUserRepository
62
+
63
+ # WRONG: domain depending on infrastructure
64
+ from src.infrastructure.database.models import UserModel # NEVER in domain
65
+ ```
66
+
67
+ **Enforce with:** `import-linter`
68
+
69
+ ---
70
+
71
+ ## AGENTS.md Snippet (Python Project)
72
+
73
+ ```yaml
74
+ runtime: Python 3.12+
75
+ language: Python (Strict Typing)
76
+ framework: FastAPI
77
+ package_manager: uv (preferred) | poetry
78
+
79
+ install: uv sync
80
+ dev: uv run fastapi dev src/main/main.py
81
+ test: uv run pytest
82
+ test_coverage: uv run pytest --cov=src
83
+ test_single: uv run pytest tests/path/to/test.py
84
+ typecheck: uv run mypy src
85
+ lint: uv run ruff check src
86
+ format: uv run ruff format src
87
+ security_scan: uv run bandit -r src
88
+ migrate: uv run alembic upgrade head
89
+ ```
90
+
91
+ ---
92
+
93
+ ## Tech Stack
94
+
95
+ ### Core
96
+ | Role | Library | Why |
97
+ |---|---|---|
98
+ | Runtime | Python 3.12+ | Performance improvements, better typing |
99
+ | Web Framework | FastAPI | Async, Pydantic integration, auto-docs |
100
+ | Validation | Pydantic v2 | Rust-based speed, strict validation |
101
+ | ORM | SQLAlchemy 2.0 | Async support, robust |
102
+ | Dependency Inj. | `fast_depends` / `dishka` | Decoupling layers |
103
+
104
+ ### AI / Agentic
105
+ | Role | Library | Why |
106
+ |---|---|---|
107
+ | Orchestration | LangChain / LangGraph | State management, tool calling |
108
+ | LLM Client | `openai` / `anthropic` | Official SDKs |
109
+ | Vector DB | Qdrant / Chroma | Efficient similarity search |
110
+ | Evaluation | Ragas / DeepEval | RAG pipeline evaluation |
111
+ | Tracing | LangSmith / Arize Phoenix | Observability for chains |
112
+
113
+ ### Testing & Quality
114
+ | Role | Library | Command |
115
+ |---|---|---|
116
+ | Test Runner | Pytest | `pytest` |
117
+ | Integration | Testcontainers | Real DB/service tests in Docker |
118
+ | Linting | Ruff | `ruff check` (Replacing Flake8/Isort) |
119
+ | Type Checking | Mypy | `mypy --strict` |
120
+ | Mutation Test | Mutmut | Verify test quality |
121
+
122
+ ---
123
+
124
+ ## Patterns
125
+
126
+ ### Domain Entity (Pydantic v2)
127
+
128
+ ```python
129
+ # src/domain/entities/user.py
130
+ from pydantic import BaseModel, Field, EmailStr
131
+ from uuid import UUID, uuid4
132
+ from datetime import datetime
133
+
134
+ class User(BaseModel):
135
+ id: UUID = Field(default_factory=uuid4)
136
+ email: EmailStr
137
+ name: str = Field(min_length=1)
138
+ created_at: datetime = Field(default_factory=datetime.now)
139
+
140
+ class Config:
141
+ frozen = True # Immutable pattern
142
+ ```
143
+
144
+ ### Protocol (Interface)
145
+
146
+ ```python
147
+ # src/domain/ports/i_user_repository.py
148
+ from typing import Protocol
149
+ from src.domain.entities.user import User
150
+
151
+ class IUserRepository(Protocol):
152
+ async def save(self, user: User) -> None:
153
+ ...
154
+
155
+ async def find_by_email(self, email: str) -> User | None:
156
+ ...
157
+ ```
158
+
159
+ ### Use Case
160
+
161
+ ```python
162
+ # src/application/users/create_user_use_case.py
163
+ from dataclasses import dataclass
164
+ from src.domain.ports.i_user_repository import IUserRepository
165
+ from src.domain.entities.user import User
166
+
167
+ @dataclass
168
+ class CreateUserCommand:
169
+ email: str
170
+ name: str
171
+
172
+ class CreateUserUseCase:
173
+ def __init__(self, repo: IUserRepository):
174
+ self.repo = repo
175
+
176
+ async def execute(self, command: CreateUserCommand) -> User:
177
+ # Business rules
178
+ existing = await self.repo.find_by_email(command.email)
179
+ if existing:
180
+ raise ValueError("Email already exists")
181
+
182
+ user = User(email=command.email, name=command.name)
183
+ await self.repo.save(user)
184
+ return user
185
+ ```
186
+
187
+ ### FastAPI Router (Adapter)
188
+
189
+ ```python
190
+ # src/adapters/api/users_router.py
191
+ from fastapi import APIRouter, Depends
192
+ from typing import Annotated
193
+ from src.main.container import get_create_user_use_case
194
+ from src.application.users.create_user_use_case import CreateUserUseCase, CreateUserCommand
195
+
196
+ router = APIRouter()
197
+
198
+ @router.post("/users")
199
+ async def create_user(
200
+ cmd: CreateUserCommand,
201
+ use_case: Annotated[CreateUserUseCase, Depends(get_create_user_use_case)]
202
+ ):
203
+ try:
204
+ user = await use_case.execute(cmd)
205
+ return {"id": str(user.id), "email": user.email}
206
+ except ValueError as e:
207
+ return {"error": str(e)}, 400
208
+ ```
209
+
210
+ ---
211
+
212
+ ## AI Agent Specifics
213
+
214
+ ### Tool Definition Pattern
215
+ When exposing tools to LLMs (Function Calling):
216
+
217
+ ```python
218
+ # src/infrastructure/llm/tools/calculator.py
219
+ from pydantic import BaseModel, Field
220
+ from typing import Callable
221
+
222
+ class AddInput(BaseModel):
223
+ a: int = Field(..., description="First number")
224
+ b: int = Field(..., description="Second number")
225
+
226
+ def add(a: int, b: int) -> int:
227
+ """Adds two numbers."""
228
+ return a + b
229
+
230
+ # LangChain / OpenAI format
231
+ tool_definition = {
232
+ "type": "function",
233
+ "function": {
234
+ "name": "add",
235
+ "description": "Adds two numbers",
236
+ "parameters": AddInput.model_json_schema()
237
+ }
238
+ }
239
+ ```
240
+
241
+ ### RAG implementation Tip
242
+ Keep embedding logic in `infrastructure`:
243
+
244
+ ```python
245
+ # src/infrastructure/vector_store/qdrant_service.py
246
+ class QdrantRetrievalService(IRetrievalService):
247
+ def __init__(self, client: QdrantClient, verify_ssl: bool = True):
248
+ self.client = client
249
+ # ... implementation details ...
250
+ ```
251
+
252
+ ---
253
+
254
+ ## See Also
255
+ - [Performant Python Skill](../../skills/coding/performant-python.skill.md) — FastAPI & Async optimization.
256
+ - [Performant AI Skill](../../skills/coding/performant-ai.skill.md) — LLM context & cost management.
257
+ - [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — Hardening Python APIs.