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,251 @@
1
+ # Guide: Go (Golang)
2
+ <!-- Idiomatic Go, Clean Architecture, Echo/Gin, Ent, Testify, Testcontainers -->
3
+
4
+ ---
5
+
6
+ ## Directory Structure — Standard Go Layout (2026)
7
+
8
+ Adheres to `golang-standards/project-layout` but adapted for Agentic Engineering.
9
+
10
+ ```
11
+ cmd/
12
+ api/
13
+ main.go # Entry point (DI container, server start)
14
+ worker/
15
+ main.go # Background worker entry point
16
+
17
+ internal/ # Private application code (Library pattern)
18
+ domain/ # Pure business logic (structs, interfaces)
19
+ user.go # User struct & Repository interfaces
20
+ order.go
21
+ errors.go # Domain errors
22
+
23
+ service/ # Application Logic (Use Cases)
24
+ user_service.go # Orchestrate domain + database
25
+ order_service.go
26
+
27
+ adapter/ # Interface Adapters (Driven & Driving)
28
+ handler/
29
+ http/ # HTTP Handlers (Echo/Gin)
30
+ user_handler.go
31
+ repository/
32
+ ent/ # Ent ORM implementation
33
+ schema/ # Database Schema Definitions
34
+ grpc/ # gRPC implementation
35
+
36
+ config/ # Configuration struct (Viper/Env)
37
+
38
+ pkg/ # Public sharable libraries (Optional)
39
+ logger/ # structured logger (slog/zap)
40
+ utils/
41
+
42
+ tests/
43
+ integration/ # Testcontainers integration tests
44
+ e2e/ # End-to-End API tests
45
+
46
+ go.mod
47
+ go.sum
48
+ Makefile
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Dependency Rules (Idiomatic)
54
+
55
+ ```go
56
+ // internal/domain CANNOT import internal/adapter or internal/service
57
+ // internal/service CAN import internal/domain
58
+ // internal/adapter CAN import internal/domain AND internal/service
59
+ // cmd/api CAN import everything (Composition Root)
60
+
61
+ // CORRECT: Service depends on Repository Interface
62
+ type UseCase struct {
63
+ Repo domain.UserRepository
64
+ }
65
+
66
+ // WRONG: Service depends on Ent implementation directly
67
+ type UseCase struct {
68
+ Repo *ent.Client // Avoid this coupling in Service layer
69
+ }
70
+ ```
71
+
72
+ ---
73
+
74
+ ## AGENTS.md Snippet (Go project)
75
+
76
+ ```yaml
77
+ runtime: Go 1.25+
78
+ language: Go (Strict Linting)
79
+ framework: Echo v4 / Standard Lib
80
+ package_manager: go mod
81
+
82
+ install: go mod download
83
+ dev: air # Live reload
84
+ test: go test -v ./...
85
+ test_coverage: go test -coverprofile=coverage.out ./...
86
+ test_single: go test -v ./internal/service/user_service_test.go
87
+ build: go build -o bin/api cmd/api/main.go
88
+ lint: golangci-lint run
89
+ format: gofumpt -w .
90
+ security_scan: govulncheck ./...
91
+ migrate: go run -mod=mod entgo.io/ent/cmd/ent generate ./internal/adapter/repository/ent/schema
92
+ ```
93
+
94
+ ---
95
+
96
+ ## Tech Stack (2026 Recommended)
97
+
98
+ ### Core
99
+ | Role | Library | Why |
100
+ |---|---|---|
101
+ | Runtime | Go 1.25+ | Generic improvements, range-over-func |
102
+ | HTTP Framework | **Echo** / **Fiber** | Fast, robust middleware, idiomatic context |
103
+ | Router | **Chi** | If employing Standard Lib only (lightweight) |
104
+ | ORM / Data | **Ent** | Type-safe graph, code-generation, great for Agents |
105
+ | Config | **Koanf** / Viper | Modern configuration management |
106
+ | Logging | **Slog** (Std Lib) | Structured logging is now built-in |
107
+
108
+ ### Testing
109
+ | Role | Library | Command |
110
+ |---|---|---|
111
+ | Assertions | **Testify** | `assert.Equal(t, expected, actual)` |
112
+ | BDD (Optional) | **Ginkgo** | For complex behavior specs |
113
+ | Integration DB | **Testcontainers** | Real Docker Postgres in tests |
114
+ | Mocks | **Mockery** | Generate mocks for interfaces |
115
+
116
+ ### Security & Quality
117
+ | Role | Library | Command |
118
+ |---|---|---|
119
+ | Linter | `golangci-lint` | `golangci-lint run` (Aggressive preset) |
120
+ | Vuln Scan | `govulncheck` | Native Go vulnerability DB checker |
121
+ | API Docs | `swag` | Generate OpenAPI from comments |
122
+
123
+ ---
124
+
125
+ ## Code Patterns
126
+
127
+ ### 1. Domain Entity (Rich Model)
128
+
129
+ ```go
130
+ // internal/domain/user.go
131
+ package domain
132
+
133
+ import "errors"
134
+
135
+ var ErrInvalidEmail = errors.New("invalid email domain")
136
+
137
+ type User struct {
138
+ ID string
139
+ Name string
140
+ Email string
141
+ }
142
+
143
+ // Business Rules can live here
144
+ func NewUser(id, name, email string) (*User, error) {
145
+ if email == "" {
146
+ return nil, ErrInvalidEmail
147
+ }
148
+ return &User{ID: id, Name: name, Email: email}, nil
149
+ }
150
+
151
+ type UserRepository interface {
152
+ Save(ctx context.Context, u *User) error
153
+ FindByID(ctx context.Context, id string) (*User, error)
154
+ }
155
+ ```
156
+
157
+ ### 2. Service (Use Case)
158
+
159
+ ```go
160
+ // internal/service/user_service.go
161
+ package service
162
+
163
+ import (
164
+ "context"
165
+ "myapp/internal/domain"
166
+ )
167
+
168
+ type UserService struct {
169
+ repo domain.UserRepository
170
+ }
171
+
172
+ func NewUserService(repo domain.UserRepository) *UserService {
173
+ return &UserService{repo: repo}
174
+ }
175
+
176
+ func (s *UserService) Register(ctx context.Context, name, email string) error {
177
+ // 1. Domain Logic
178
+ u, err := domain.NewUser(domain.NewID(), name, email)
179
+ if err != nil {
180
+ return err
181
+ }
182
+
183
+ // 2. Persist
184
+ return s.repo.Save(ctx, u)
185
+ }
186
+ ```
187
+
188
+ ### 3. HTTP Handler (Echo)
189
+
190
+ ```go
191
+ // internal/adapter/handler/http/user_handler.go
192
+ package http
193
+
194
+ import (
195
+ "net/http"
196
+ "github.com/labstack/echo/v4"
197
+ )
198
+
199
+ type UserHandler struct {
200
+ svc *service.UserService
201
+ }
202
+
203
+ func (h *UserHandler) Register(c echo.Context) error {
204
+ var req struct {
205
+ Name string `json:"name"`
206
+ Email string `json:"email"`
207
+ }
208
+
209
+ if err := c.Bind(&req); err != nil {
210
+ return c.JSON(http.StatusBadRequest, echo.Map{"error": "bad request"})
211
+ }
212
+
213
+ if err := h.svc.Register(c.Request().Context(), req.Name, req.Email); err != nil {
214
+ return c.JSON(http.StatusInternalServerError, echo.Map{"error": err.Error()})
215
+ }
216
+
217
+ return c.NoContent(http.StatusCreated)
218
+ }
219
+ ```
220
+
221
+ ---
222
+
223
+ ## Development Workflow with Agents
224
+
225
+ ### "Scaffold New Feature" prompt:
226
+ > "Agent, create a new 'Product' domain entity in `internal/domain`. Then generate the Ent schema, run `go generate`, implement the repository interface in `internal/adapter/repository`, add a `ProductService`, and expose it via a new Echo handler."
227
+
228
+ ### "Test It" prompt:
229
+ > "Agent, write a specialized integration test in `tests/integration` using Testcontainers to spin up Postgres, migrate the Ent schema, and verify the `ProductService.Create` flow."
230
+
231
+ ---
232
+
233
+ ## Tech Debt & Maintenance
234
+
235
+ ```bash
236
+ # Update dependencies
237
+ go get -u ./...
238
+ go mod tidy
239
+
240
+ # Run formatter (stricter than gofmt)
241
+ gofumpt -w .
242
+
243
+ # Linting
244
+ golangci-lint run --fix
245
+ ```
246
+
247
+ ---
248
+
249
+ ## See Also
250
+ - [Performant Go Skill](../../skills/coding/performant-go.skill.md) — High-performance Go systems.
251
+ - [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — Security best practices for Go.
@@ -0,0 +1,73 @@
1
+ # Java Project Guide
2
+
3
+ > **Audience:** agents writing or reviewing Java services. **Scope:** current
4
+ > stack, idioms, structure, testing, performance, and pitfalls for server-side
5
+ > Java in 2026. Versions verified 2026-06-10 (see sources at the end).
6
+
7
+ ## Recommended stack (2026)
8
+
9
+ - **Runtime:** **Java 25 (LTS)** — released 2025-09-16; the current long-term
10
+ support release. Java 21 (LTS) remains widely deployed; target 25 for new
11
+ work, 21 as the minimum floor. (Java 26 is the latest non-LTS feature release.)
12
+ - **Build:** Gradle (Kotlin DSL) for new projects; Maven where the org standard.
13
+ - **Web:** Spring Boot 3.x (broadest ecosystem) or Quarkus / Helidon (fast
14
+ startup, low memory, GraalVM-friendly).
15
+ - **Persistence:** Spring Data JPA / Hibernate; jOOQ when you want type-safe SQL.
16
+ - **Testing:** JUnit 5 + AssertJ + Mockito; **Testcontainers** for real
17
+ databases/brokers in integration tests.
18
+ - **Quality:** Checkstyle + SpotBugs (or Error Prone) + `./gradlew check`; format
19
+ with Spotless (google-java-format / Palantir).
20
+
21
+ ## Concurrency — use the modern model
22
+
23
+ - **Virtual threads** (finalized in Java 21, JEP 444): for I/O-bound work, run
24
+ each task on a virtual thread instead of pooling platform threads. With Spring
25
+ Boot, enable `spring.threads.virtual.enabled=true`; otherwise use
26
+ `Executors.newVirtualThreadPerTaskExecutor()`. Write straightforward blocking
27
+ code — the runtime unmounts the carrier thread on blocking I/O.
28
+ - **Structured concurrency** (`StructuredTaskScope`) and **scoped values**
29
+ continue to mature across 21→25; prefer them over `ThreadLocal` and ad-hoc
30
+ fan-out for request-scoped concurrency and propagation.
31
+ - Do **not** pool virtual threads, and avoid pinning them inside `synchronized`
32
+ blocks that perform blocking I/O — use `ReentrantLock` there.
33
+
34
+ ## Language idioms (21–25)
35
+
36
+ - **Records** for immutable data carriers; **sealed** interfaces + **pattern
37
+ matching for `switch`** (incl. record deconstruction) for closed type
38
+ hierarchies and exhaustive handling.
39
+ - Prefer immutability and `Optional` over nulls at API boundaries; never use
40
+ `Optional` for fields or method parameters.
41
+ - Use enhanced `switch` expressions and text blocks for readability.
42
+
43
+ ## Project structure
44
+
45
+ ```
46
+ src/main/java/<group>/<app>/ domain · application · infrastructure · api (Clean/Hexagonal)
47
+ src/main/resources/ application.yml, db/migration (Flyway/Liquibase)
48
+ src/test/java/ unit (fast) + integration (Testcontainers)
49
+ build.gradle.kts | pom.xml
50
+ ```
51
+
52
+ Keep the domain free of framework annotations; depend inward (the dependency rule).
53
+
54
+ ## Performance & ops
55
+
56
+ - Start with the G1 GC; consider ZGC/Shenandoah for low-pause, large-heap
57
+ services. Set explicit `-Xmx` / container memory limits.
58
+ - Prefer **CDS / AppCDS** and, for fast cold start, **GraalVM Native Image**
59
+ (Spring AOT / Quarkus) — but verify reflection config and run the native test
60
+ suite.
61
+ - Observe with Micrometer → OpenTelemetry; expose health/readiness via Actuator.
62
+
63
+ ## Common pitfalls
64
+
65
+ - Blocking inside a reactive (`WebFlux`) pipeline — pick one model per service.
66
+ - N+1 queries from lazy JPA associations — fetch-join or use projections.
67
+ - Catch-and-swallow exceptions; leaking checked exceptions across layers.
68
+ - Mutable static state; non-thread-safe `SimpleDateFormat` (use `java.time`).
69
+
70
+ ## Sources (verified 2026-06-10)
71
+ - Java version history & LTS cadence: <https://en.wikipedia.org/wiki/Java_version_history>
72
+ - JDK 25 (LTS) features: <https://openjdk.org/projects/jdk/25/> · <https://www.infoq.com/news/2025/09/java25-released/>
73
+ - Virtual threads (JEP 444): <https://openjdk.org/jeps/444>
@@ -0,0 +1,361 @@
1
+ # Guide: JavaScript / TypeScript / Node.js
2
+ <!-- Clean Architecture with TypeScript, Fastify, Prisma, Vitest, and Playwright -->
3
+
4
+ ---
5
+
6
+ ## Directory Structure — Clean Architecture
7
+
8
+ ```
9
+ src/
10
+ domain/ # Pure business logic — NO framework imports
11
+ entities/ # User.ts, Order.ts — domain entities
12
+ value-objects/ # Email.ts, Money.ts — immutable primitives
13
+ events/ # UserRegistered.ts, OrderCreated.ts
14
+ ports/ # IUserRepository.ts — interfaces only
15
+ errors/ # DomainError.ts, ValidationError.ts
16
+ services/ # Pure domain services (no DB, no HTTP)
17
+
18
+ application/ # Use cases — orchestrates domain
19
+ users/
20
+ create-user.use-case.ts
21
+ create-user.command.ts
22
+ create-user.result.ts
23
+ orders/
24
+ create-order.use-case.ts
25
+
26
+ adapters/ # Interface adapters — translate between layers
27
+ http/
28
+ users.controller.ts # Thin controllers — validate, delegate, respond
29
+ users.dto.ts # Zod schemas for request/response
30
+ presenters/ # Transform domain entities to HTTP response shape
31
+
32
+ infrastructure/ # Framework + external services implementations
33
+ database/
34
+ prisma-user.repository.ts # Implements IUserRepository using Prisma
35
+ email/
36
+ sendgrid-email.service.ts
37
+ cache/
38
+ redis-cache.service.ts
39
+
40
+ main/ # Composition root — wires everything together
41
+ container.ts # DI container setup
42
+ server.ts # Fastify server + plugin registration
43
+ routes.ts # Route registration
44
+
45
+ tests/
46
+ unit/ # Mirror of src/ — fast, no DB, no HTTP
47
+ integration/ # Real DB, Docker Compose
48
+ e2e/ # Full browser tests with Playwright
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Layer Import Rules
54
+
55
+ ```typescript
56
+ // domain/ — MUST NOT import from any other layer
57
+ // application/ — MAY import from domain only
58
+ // adapters/ — MAY import from domain + application
59
+ // infrastructure/ — MAY import from domain (implements interfaces)
60
+ // main/ — MAY import from all layers (composition root only)
61
+
62
+ // CORRECT: infrastructure depends on domain interface
63
+ import type { IUserRepository } from '@/domain/ports/i-user-repository';
64
+
65
+ // WRONG: domain depending on infrastructure
66
+ import { PrismaClient } from '@prisma/client'; // NEVER in domain layer
67
+ ```
68
+
69
+ **Enforce with:** `npx dependency-cruiser --config .dependency-cruiser.cjs src/`
70
+
71
+ ---
72
+
73
+ ## AGENTS.md Snippet (Node.js/TypeScript project)
74
+
75
+ ```yaml
76
+ runtime: Node.js 22
77
+ language: TypeScript 5.x (strict mode)
78
+ framework: Fastify 5.x
79
+ package_manager: pnpm
80
+
81
+ install: pnpm install
82
+ dev: pnpm dev
83
+ test: pnpm vitest run
84
+ test_coverage: pnpm vitest run --coverage
85
+ test_single: pnpm vitest run src/path/to/file.test.ts
86
+ build: pnpm build
87
+ typecheck: pnpm tsc --noEmit
88
+ lint: pnpm eslint . --ext .ts,.tsx
89
+ format: pnpm prettier --write .
90
+ security_scan: pnpm audit --audit-level=moderate
91
+ migrate: pnpm prisma migrate dev
92
+ ```
93
+
94
+ ---
95
+
96
+ ## Tech Stack
97
+
98
+ ### Core
99
+ | Role | Library | Why |
100
+ |---|---|---|
101
+ | Runtime | Node.js 22 (LTS) | Active LTS, native fetch, ES modules |
102
+ | Language | TypeScript 5.x strict | Type safety, better DX |
103
+ | HTTP Framework | Fastify 5.x | Fast, schema validation built-in, plugins |
104
+ | Validation/DTOs | Zod 3.x | Runtime type validation + TypeScript inference |
105
+ | ORM | Prisma 5.x | Type-safe queries, migration-first, great DX |
106
+ | API docs | @scalar/fastify-api-reference | OpenAPI UI |
107
+
108
+ ### Testing
109
+ | Role | Library | Command |
110
+ |---|---|---|
111
+ | Unit + Integration | Vitest | `pnpm vitest run` |
112
+ | HTTP integration | Supertest | Within Vitest |
113
+ | Database integration | `@testcontainers/postgresql` | `pnpm vitest run tests/integration` |
114
+ | Browser/E2E | Playwright | `pnpm playwright test` |
115
+ | Coverage | Vitest Coverage (v8) | `--coverage` flag |
116
+
117
+ ### Security
118
+ | Role | Library | Command |
119
+ |---|---|---|
120
+ | Dep audit | `npm audit` | `pnpm audit --audit-level=moderate` |
121
+ | SAST | Semgrep | `npx semgrep --config=p/security-audit src/` |
122
+ | Secret detection | gitleaks | `gitleaks detect --source=. --verbose` |
123
+ | HTTP security | Helmet.js | `app.register(fastifyHelmet)` |
124
+ | Rate limiting | `@fastify/rate-limit` | `app.register(fastifyRateLimit)` |
125
+ | Input sanitization | validator.js | For specific string validation beyond Zod |
126
+ | Architecture | dependency-cruiser | `npx depcruise src/` |
127
+
128
+ ---
129
+
130
+ ## TypeScript Configuration (strict mode)
131
+
132
+ ```json
133
+ // tsconfig.json
134
+ {
135
+ "compilerOptions": {
136
+ "target": "ES2022",
137
+ "module": "NodeNext",
138
+ "moduleResolution": "NodeNext",
139
+ "strict": true,
140
+ "noUncheckedIndexedAccess": true,
141
+ "noImplicitOverride": true,
142
+ "exactOptionalPropertyTypes": true,
143
+ "paths": {
144
+ "@/*": ["./src/*"]
145
+ }
146
+ }
147
+ }
148
+ ```
149
+
150
+ ---
151
+
152
+ ## Patterns
153
+
154
+ ### Domain Entity with Invariants
155
+
156
+ ```typescript
157
+ // src/domain/entities/user.ts
158
+ import { Email } from '../value-objects/email';
159
+ import { UserId } from '../value-objects/user-id';
160
+ import { UserRegisteredEvent } from '../events/user-registered.event';
161
+ import type { DomainEvent } from '../events/domain-event';
162
+
163
+ export class User {
164
+ private readonly _events: DomainEvent[] = [];
165
+
166
+ private constructor(
167
+ public readonly id: UserId,
168
+ public readonly email: Email,
169
+ public readonly name: string,
170
+ public readonly createdAt: Date,
171
+ ) {}
172
+
173
+ static create(email: Email, name: string): User {
174
+ const user = new User(UserId.generate(), email, name, new Date());
175
+ user._events.push(new UserRegisteredEvent(user.id.value, user.email.value));
176
+ return user;
177
+ }
178
+
179
+ get events(): readonly DomainEvent[] { return this._events; }
180
+ clearEvents(): void { this._events.length = 0; }
181
+ }
182
+ ```
183
+
184
+ ### Value Object
185
+
186
+ ```typescript
187
+ // src/domain/value-objects/email.ts
188
+ import { z } from 'zod';
189
+
190
+ const emailSchema = z.string().email().max(255);
191
+
192
+ export class Email {
193
+ private constructor(public readonly value: string) {}
194
+
195
+ static create(value: string): Email {
196
+ const result = emailSchema.safeParse(value);
197
+ if (!result.success) {
198
+ throw new ValidationError(`Invalid email: ${value}`);
199
+ }
200
+ return new Email(result.data);
201
+ }
202
+
203
+ equals(other: Email): boolean { return this.value === other.value; }
204
+ }
205
+ ```
206
+
207
+ ### Use Case
208
+
209
+ ```typescript
210
+ // src/application/users/create-user.use-case.ts
211
+ import type { IUserRepository } from '@/domain/ports/i-user-repository';
212
+ import type { IEventBus } from '@/domain/ports/i-event-bus';
213
+ import { User } from '@/domain/entities/user';
214
+ import { Email } from '@/domain/value-objects/email';
215
+ import { EmailAlreadyExistsError } from '@/domain/errors/email-already-exists.error';
216
+
217
+ export interface CreateUserCommand {
218
+ email: string;
219
+ name: string;
220
+ }
221
+
222
+ export class CreateUserUseCase {
223
+ constructor(
224
+ private readonly userRepository: IUserRepository,
225
+ private readonly eventBus: IEventBus,
226
+ ) {}
227
+
228
+ async execute(command: CreateUserCommand): Promise<{ id: string }> {
229
+ const email = Email.create(command.email); // validates here
230
+
231
+ const existing = await this.userRepository.findByEmail(email);
232
+ if (existing) throw new EmailAlreadyExistsError(email.value);
233
+
234
+ const user = User.create(email, command.name);
235
+ await this.userRepository.save(user);
236
+ await this.eventBus.publish(user.events);
237
+ user.clearEvents();
238
+
239
+ return { id: user.id.value };
240
+ }
241
+ }
242
+ ```
243
+
244
+ ### Thin Controller (Fastify)
245
+
246
+ ```typescript
247
+ // src/adapters/http/users.controller.ts
248
+ import type { FastifyPluginAsync } from 'fastify';
249
+ import { z } from 'zod';
250
+ import type { CreateUserUseCase } from '@/application/users/create-user.use-case';
251
+
252
+ const CreateUserBody = z.object({
253
+ email: z.string().email(),
254
+ name: z.string().min(1).max(100),
255
+ });
256
+
257
+ export const usersRouter: FastifyPluginAsync = async (app) => {
258
+ app.post('/api/v1/users', {
259
+ schema: { body: CreateUserBody },
260
+ }, async (request, reply) => {
261
+ const result = await request.container.resolve(CreateUserUseCase)
262
+ .execute(request.body);
263
+ return reply.status(201).send(result);
264
+ });
265
+ };
266
+ ```
267
+
268
+ ---
269
+
270
+ ## Error Handling Patterns
271
+
272
+ ```typescript
273
+ // src/domain/errors/domain-error.ts
274
+ export abstract class DomainError extends Error {
275
+ abstract readonly code: string;
276
+ constructor(message: string) {
277
+ super(message);
278
+ this.name = this.constructor.name;
279
+ }
280
+ }
281
+
282
+ // src/adapters/http/error-handler.ts (Fastify global error handler)
283
+ export const errorHandler: FastifyErrorHandler = (error, request, reply) => {
284
+ if (error instanceof DomainError) {
285
+ return reply.status(422).send({
286
+ error: { code: error.code, message: error.message }
287
+ });
288
+ }
289
+ if (error instanceof ValidationError) {
290
+ return reply.status(400).send({
291
+ error: { code: 'VALIDATION_ERROR', message: error.message }
292
+ });
293
+ }
294
+ // Never expose internal errors to clients
295
+ request.log.error(error);
296
+ return reply.status(500).send({ error: { code: 'INTERNAL_ERROR', message: 'Internal server error' } });
297
+ };
298
+ ```
299
+
300
+ ---
301
+
302
+ ## Security Best Practices
303
+
304
+ ```typescript
305
+ // Register security plugins in src/main/server.ts
306
+ import fastifyHelmet from '@fastify/helmet';
307
+ import fastifyRateLimit from '@fastify/rate-limit';
308
+ import fastifyCors from '@fastify/cors';
309
+
310
+ await app.register(fastifyHelmet, {
311
+ contentSecurityPolicy: {
312
+ directives: {
313
+ defaultSrc: ["'self'"],
314
+ scriptSrc: ["'self'"],
315
+ styleSrc: ["'self'", "'unsafe-inline'"],
316
+ }
317
+ }
318
+ });
319
+
320
+ await app.register(fastifyRateLimit, {
321
+ max: 100,
322
+ timeWindow: '1 minute',
323
+ // Stricter for auth endpoints: configure per-route
324
+ });
325
+
326
+ await app.register(fastifyCors, {
327
+ origin: process.env.ALLOWED_ORIGINS?.split(',') ?? ['http://localhost:3000'],
328
+ credentials: true,
329
+ });
330
+
331
+ // NEVER: wildcard CORS for authenticated APIs
332
+ // await app.register(fastifyCors, { origin: '*' }); // WRONG
333
+ ```
334
+
335
+ ---
336
+
337
+ ## Tech Debt Detection Commands
338
+
339
+ ```bash
340
+ # Cyclomatic complexity (flag > 10)
341
+ npx complexity-report --format json src/ | jq '.functions[] | select(.cyclomatic > 10)'
342
+
343
+ # Code duplication
344
+ npx jscpd src/ --min-lines 5 --min-tokens 50
345
+
346
+ # Circular dependencies
347
+ npx madge --circular --extensions ts src/
348
+
349
+ # Outdated dependencies
350
+ pnpm outdated
351
+
352
+ # Architecture violations
353
+ npx dependency-cruiser --config .dependency-cruiser.cjs src/
354
+ ```
355
+
356
+ ---
357
+
358
+ ## See Also
359
+ - [Performant Node.js Skill](../../skills/coding/performant-nodejs.skill.md) — Optimization strategies.
360
+ - [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — Hardening Node.js apps.
361
+ - [Clean Coder Skill](../../skills/coding/clean-coder.skill.md) — Architecture enforcement.