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,914 @@
1
+ # GABBE (Generative Architectural Brain Base Engine) - Agentic Software R&D Engineering Kit
2
+
3
+ > **Audience:** new users. **Scope:** fast-track common workflows (specs → design → TDD → brain mode) with copy-paste prompts.
4
+
5
+ ## QUICK_GUIDE.md — Everything You Need in One Place
6
+
7
+ > Complete reference sheet for the Agentic Engineering Kit.
8
+ > Bookmark this. Read it before your first session.
9
+
10
+ ---
11
+
12
+ ## Why This Kit Exists — Another Lethal Trifecta
13
+
14
+ AI coding agents suffer from three compounding problems:
15
+
16
+ 1. **Velocity mismatch** — Agents generate code 10-100x faster than humans can review. Without guardrails, they skip critical steps (spec approval, security review, test coverage) and the human only discovers problems after the damage is done.
17
+
18
+ 2. **Non-determinism** — Same prompt, different output every time. Without structured context (AGENTS.md, CONSTITUTION.md, skill constraints), agents make inconsistent architectural decisions across sessions.
19
+
20
+ 3. **Cost asymmetry ("context rot")** — Wrong decisions compound. A missed security check at S01 (Requirements) costs 100x more to fix at S08 (Review). Architectural debt chosen in hour 1 creates exponential rework.
21
+
22
+ **This kit solves all three** through:
23
+ - Explicit context (AGENTS.md — single source of truth for every agent)
24
+ - Deterministic workflows (SDD Lifecycle, TDD Cycle, RARV Loop)
25
+ - Enforced checkpoints (10-Gate Quality System, human-in-the-loop triggers)
26
+ - Persistent memory (SESSION_SNAPSHOT, CONTINUITY.md, AUDIT_LOG.md)
27
+
28
+ **ROI:** Repositories using this approach could see reduction in agent runtime and in token usage through explicit context, cached decisions, and SDLC memory.
29
+
30
+ ---
31
+
32
+ ## 5-Minute Setup Checklist
33
+
34
+ ```bash
35
+ # 1. Download & Run the Installer
36
+ curl -sL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/scripts/init.py | python3 -
37
+
38
+ # OR if you have the repo cloned:
39
+ python3 GABBE/scripts/init.py
40
+
41
+ # 2. Select Install Location
42
+ # - Local (Recommended): Installs to agents/ in your project
43
+ # - Global: Installs to ~/agents/ for all projects
44
+
45
+ # 3. Follow the Interactive Wizard
46
+ # - It configures your Stack, Project Type, and Compliance needs
47
+ # - It generates platform-specific skills:
48
+ # - .cursor/rules/*.mdc (Cursor)
49
+ # - .github/skills/ (VS Code / Copilot)
50
+ # - .claude/skills/ (Claude Code)
51
+ # - .gemini/settings.json (Gemini)
52
+
53
+ ```
54
+ ## 4. Initialize Your Agent with the Mission
55
+ - The script generates `BOOTSTRAP_MISSION.md` (or `SETUP_MISSION.md` if dynamic setup is disabled) in your root.
56
+ - Open the generated file: `BOOTSTRAP_MISSION.md` or `SETUP_MISSION.md`
57
+ - Copy the entire content.
58
+ - Paste it into your AI Agent's chat window (first message).
59
+ - This aligns the agent with your project context immediately.
60
+
61
+ ## 5. Refine Context (The "Human-in-the-Loop" Step)
62
+ - Open `agents/AGENTS.md`: Check `Tech Stack` section.
63
+ - Verify `test_cmd` and `lint_cmd` match your project.
64
+ - Open `agents/CONSTITUTION.md`: Review project laws.
65
+ - Adjust Article I (Directives) if needed.
66
+
67
+ ## 6. Git Tracking (Important)
68
+ - To keep the initial structure of `agents/memory/` and `project/` in your repository but prevent Git from tracking the continuous autonomous modifications your agents will make to them locally, run:
69
+ ```bash
70
+ git ls-files agents/memory/ project/ | xargs git update-index --skip-worktree
71
+ ```
72
+
73
+ ---
74
+
75
+ ## 🚀 GABBE CLI (Experimental)
76
+
77
+ GABBE contains a **Zero-Dependency CLI** (`gabbe`) CLI which powers the "Hybrid Mode". It bridges the gap between flexible Markdown files and a robust SQLite database. It's an experimental work-in-progress and you can do without the whole package only with the rest of the kit.
78
+
79
+ ### Prerequisites
80
+ - Python 3.8+
81
+ - **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
82
+
83
+ **Environment Variables** (full reference in [CLI_REFERENCE.md](CLI_REFERENCE.md#environment-variables)):
84
+
85
+ | Variable | Default | Description |
86
+ |---|---|---|
87
+ | `GABBE_API_URL` | `https://api.openai.com/v1/chat/completions` | OpenAI-compatible endpoint |
88
+ | `GABBE_API_KEY` | *(required for LLM features)* | Bearer token for the LLM API |
89
+ | `GABBE_API_MODEL` | `gpt-4o` | Model name sent in API requests |
90
+ | `GABBE_LLM_TEMPERATURE` | `0.7` | Sampling temperature (0.0–1.0) |
91
+ | `GABBE_LLM_TIMEOUT` | `30` | HTTP timeout in seconds |
92
+ | `GABBE_LLM_MAX_RETRIES` | `3` | Number of LLM retry attempts on transient errors |
93
+ | `GABBE_LLM_CACHE` | `false` | Opt-in: cache identical LLM calls locally (0 tokens on a hit; only for deterministic calls) |
94
+ | `GABBE_LOG_LEVEL` | `INFO` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
95
+ | `GABBE_ROUTE_THRESHOLD` | `50` | Complexity score above which prompts route REMOTE |
96
+ | `GABBE_MAX_COST_USD` | `5.0` | Maximum cost (USD) budget per run |
97
+ | `GABBE_MAX_TOKENS_PER_RUN` | `100000` | Maximum token limit per run |
98
+ | `GABBE_MAX_TOOL_CALLS_PER_RUN` | `50` | Maximum tool calls allowed per run |
99
+ | `GABBE_MAX_ITERATIONS` | `25` | Maximum active-inference iterations per run |
100
+ | `GABBE_MAX_WALL_TIME` | `300` | Maximum wall-clock time (seconds) per run |
101
+ | `GABBE_MAX_RECURSION_DEPTH` | `5` | Maximum agent recursion depth |
102
+ | `GABBE_MAX_RETRIES_PER_TOOL` | `3` | Maximum retries for a single tool call |
103
+ | `GABBE_POLICY_FILE` | `project/policies.yml` | Path to the YAML policy file |
104
+ | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli`, `file`, or `silent` |
105
+ | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout (seconds) for verify sub-commands |
106
+ | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
107
+
108
+ ### Installation
109
+ The CLI is a Python package.
110
+
111
+ ```bash
112
+ # 1. Install locally (Recommended)
113
+ pip install -e .
114
+
115
+ # 2. Verify installation
116
+ gabbe --help
117
+
118
+ # 3. (Optional) Interactively fill the kit's [PLACEHOLDER: ...] markers
119
+ # (project name, stack, conventions) across agents/ in one pass
120
+ python scripts/fill_placeholders.py
121
+ ```
122
+
123
+ ### Core Commands
124
+ | Command | Description |
125
+ |---|---|
126
+ | `gabbe init` | Initialize the SQLite Database (Run this after `python scripts/init.py`). |
127
+ | `gabbe sync` | **Hybrid Sync**: Bidirectional sync between `project/TASKS.md` and SQLite DB. |
128
+ | `gabbe verify`| **Enforcer**: programmable integrity check (files, tests, lint). |
129
+ | `gabbe verify --chaos` | **Resilience**: fault-injection self-checks (fail-closed tool, hard-stop, escalation). |
130
+ | `gabbe eval` | **Skill evals**: deterministic self-check; `--live` scores via the model. |
131
+ | `gabbe doctor` | **Autodetect**: OS/runtimes/agents + post-install MCP next-steps. |
132
+ | `gabbe update` / `gabbe uninstall` | **Reversible install**: additive refresh / manifest-backed removal. |
133
+ | `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
134
+ | `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
135
+ | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key). |
136
+ | `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
137
+ | `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
138
+ | `gabbe runs` | **Run History**: List recent agent runs with status, cost, and timestamps. |
139
+ | `gabbe audit <run-id>` | **Audit Trace**: Display structured span-level trace for a past run (`--format json\|table`). |
140
+ | `gabbe replay <run-id>` | **Deterministic Replay**: Replay a past run from its checkpoints (`--from-step N`). |
141
+ | `gabbe resume <run-id>` | **Escalation Resume**: Approve or reject pending escalations for a paused run. |
142
+
143
+ ### Platform Control Layer
144
+ The experimental `gabbe` CLI supports a **platform control layer**. It covers budget enforcement, cost and token controls, hard stops, policy rules, the tool gateway, audit tracing, human escalation, and deterministic replay. Detailed documentation is available in [`PLATFORM_CONTROLS.md`](PLATFORM_CONTROLS.md).
145
+
146
+ For exhaustive testing of the platform, SDKs, and workflow execution boundaries, consult the [`VERIFICATION_GUIDE.md`](VERIFICATION_GUIDE.md).
147
+
148
+ ### Architecture
149
+ GABBE CLI uses a **Hybrid Architecture** where agents and humans interact via Markdown, but the system of record is SQLite.
150
+
151
+ ```mermaid
152
+ graph TD
153
+ subgraph User["User (Legacy Flow)"]
154
+ Edit[Edit project/TASKS.md]
155
+ end
156
+
157
+ subgraph CLI["GABBE CLI (pip installed)"]
158
+ Sync[gabbe sync]
159
+ Verify[gabbe verify]
160
+ Brain[gabbe brain]
161
+ Router[gabbe route]
162
+ Forecast[gabbe forecast]
163
+ MCP[gabbe serve-mcp]
164
+ end
165
+
166
+ subgraph Storage["Hybrid Memory"]
167
+ MD[Markdown Files]
168
+ DB[(SQLite state.db)]
169
+ end
170
+
171
+ User -->|Manual Edits| MD
172
+ MD <-->|Bi-Directional| Sync
173
+ Sync <--> DB
174
+ Brain -->|Read/Write| DB
175
+ Verify -->|Check| MD
176
+ Verify -->|Check| DB
177
+ Forecast -->|Analyze| DB
178
+ MCP -->|Write Telemetry| DB
179
+ ```
180
+
181
+ ### Text Overview (ASCII)
182
+
183
+ ```text
184
+ [User] --(Manual Edits)--> [Markdown Files] <--(Bi-Directional)--> [gabbe sync] <--> [(SQLite state.db)]
185
+ ^ ^
186
+ [gabbe brain] --(Read/Write)-----------------------------------------------------------+ |
187
+ [gabbe verify] --(Check)--> [Markdown Files] |
188
+ [gabbe verify] --(Check)----------------------------------------------------------------------+
189
+ [gabbe forecast] --(Analyze)------------------------------------------------------------------+
190
+ [gabbe serve-mcp] --(Write Telemetry)---------------------------------------------------------+
191
+ ```
192
+
193
+ ### How to Use
194
+
195
+ #### Setup
196
+ ```bash
197
+ # 1. Generate Context Configs
198
+ python3 scripts/init.py
199
+
200
+ # 2. Initialize Database
201
+ gabbe init
202
+ ```
203
+
204
+ #### Daily Workflow
205
+ ```bash
206
+ # Check status
207
+ gabbe status
208
+
209
+ # Sync tasks (manual edits)
210
+ gabbe sync
211
+
212
+ # Optimize a skill (Requires GABBE_API_KEY)
213
+ gabbe brain evolve --skill tdd-cycle
214
+ ```
215
+
216
+ #### Verification
217
+ ```bash
218
+ gabbe verify
219
+ ```
220
+
221
+ ## 🚀 Common Actions (Copy-Paste Prompts)
222
+
223
+ ### Strategy & Ideation (Step 0)
224
+ ```
225
+ "Use business-case/strategy skills to validate exactly why we are building [description] and who it is for."
226
+ ```
227
+
228
+ ### New Project from Scratch
229
+ ```
230
+ "Read AGENTS.md. I want to build [description]. Start with spec-writer skill."
231
+ ```
232
+ **Flow:** Strategy → Spec → Design → Tasks → TDD Implementation → Security → Deploy
233
+
234
+ ### Resume Existing Project
235
+ ```
236
+ "Read AGENTS.md and agents/memory/PROJECT_STATE.md. Resume the project."
237
+ ```
238
+
239
+ ### Fix a Bug
240
+ ```
241
+ "Read AGENTS.md. Bug: [description]. Use debug skill with TDD."
242
+ ```
243
+ **Flow:** Reproduce → Root Cause → Failing Test → Fix → Green → Regression Check
244
+
245
+ ### Refactor / Pay Tech Debt
246
+ ```
247
+ "Use tech-debt skill on [directory]. Then refactor the top-priority item."
248
+ ```
249
+
250
+ ### Security Audit
251
+ ```
252
+ "Run security-audit skill on the entire codebase."
253
+ ```
254
+
255
+ ### Architecture Review
256
+ ```
257
+ "Run arch-review skill. Check for SOLID violations and coupling."
258
+ ```
259
+ ```
260
+ "Use the performant-nodejs skill to audit the current Node.js architecture for scalability bottlenecks and propose optimizations."
261
+ ```
262
+ ```
263
+ "Use the performant-laravel skill to audit the current Laravel architecture for scalability bottlenecks and propose optimizations."
264
+ ```
265
+ ```
266
+ "Use the performant-python skill to audit the current Python architecture for scalability bottlenecks and propose optimizations."
267
+ ```
268
+ ```
269
+ "Use the performant-go skill to audit the current Go architecture for scalability bottlenecks and propose optimizations."
270
+ ```
271
+ ```
272
+ "Use the performant-ai skill to audit the current AI/LLM architecture for latency and cost bottlenecks."
273
+ ```
274
+
275
+ ### Software Engineering & System Architecture
276
+ ```
277
+ "Act as a Principal Staff Engineer. Review the codebase in [directory] and generate a C4 system architecture diagram (Context and Container levels). Identify any bottlenecks and propose scaling strategies."
278
+ ```
279
+ ```
280
+ "Use the visual-whiteboarding skill. Connect to the Draw.io/Miro MCP and generate a visual spatial architecture diagram for the current microservice layout."
281
+ ```
282
+ ```
283
+ "Use the design-patterns and domain-model skills. We are building a [feature segment]. Propose the optimum architecture pattern (e.g. Event-driven, CQRS, Hexagonal) and define the core domain entities."
284
+ ```
285
+
286
+ ### Vibe-Coding (Creative Frontend)
287
+ ```
288
+ "Use the vibe-coding skill. Build a [component/page] using [framework]. I want it to feel [aesthetic, e.g. glassmorphism, cyberpunk, sleek corporate]. Include micro-animations and smooth transitions. Prioritize visual WOW over generic utility."
289
+ ```
290
+
291
+ ### Activate Brain Mode (Complex Goals)
292
+ ```
293
+ "Activate Brain Mode. Goal: [build X / migrate Y / solve Z]."
294
+ ```
295
+ Uses Active Inference to plan, route between local/remote models, and learn from past outcomes.
296
+
297
+ ### Activate Loki Mode (Large Projects)
298
+
299
+ **Using the CLI:**
300
+ > `gabbe brain activate` (Loki may be triggered autonomously)
301
+ Or activate the swarm skill explicitly:
302
+ > Activate `agents/skills/brain/loki-mode.skill.md` with your goal.
303
+
304
+ **Using Pure Agent Mode (No CLI):**
305
+ > "Activate `agents/skills/brain/loki-mode.skill.md`. Goal: [build X]. Do not ask me for permission unless you hit a mandatory Human Approval Gate or a task requires True A2A Delegation."
306
+
307
+
308
+ ```
309
+ Multi-agent swarm with 30+ specialized personas for projects >5 features or >20 files.
310
+ ```
311
+
312
+ ---
313
+
314
+ ## Kit Structure Overview
315
+
316
+ ```
317
+ GABBE/
318
+ scripts/init.py <- Installer Wizard (Run this first)
319
+ README_FULL.md <- Complete step-by-step guide
320
+ QUICK_GUIDE.md <- This file
321
+ agents/ <- The actual kit payload
322
+ AGENTS.md <- Universal config template
323
+ CONSTITUTION.md <- Immutable project law
324
+ scripts/setup-context.sh <- Internal wiring script (wrapped by scripts/init.py)
325
+ skills/ <- 214 agent capability packages (💯)
326
+ core/ <- (tdd, refactor, debug, git...)
327
+ security/ <- (audit, threat-model...)
328
+ arch/ <- (design, review, patterns...)
329
+ templates/ <- 100 fill-in-the-blank documents
330
+ guides/ <- 86 domain & process guides
331
+ loki/
332
+ docs/
333
+ ```
334
+
335
+ ---
336
+
337
+ ## 🏗️ How to Use Kit Resources
338
+
339
+ ### 1. Guides (`agents/guides/*.md`)
340
+ - **What:** Textbooks for the Agent.
341
+ - **Who:** The AGENT reads them.
342
+ - **When:** At the start of a session or when learning a new stack.
343
+ - **How:** "Read `guides/languages/js-ts-nodejs.md` to understand our stack standards."
344
+
345
+ ### 2. Templates (`agents/templates/**/*.md`)
346
+ - **What:** Forms to be filled out.
347
+ - **Who:** The AGENT fills them out; the HUMAN reviews them.
348
+ - **When:** At specific SDLC gates (e.g., S01 = PRD, S02 = ADR).
349
+ - **How:**
350
+ 1. **Agent Instantiation:** "Create a PRD for [feature] using `templates/product/PRD_TEMPLATE.md`."
351
+ 2. **Manual Instantiation:** You copy the file to `docs/PRD.md` and fill it out yourself. (Rare, but allowed).
352
+
353
+ ### 3. Scripts (`agents/scripts/setup-context.sh`, `scripts/init.py`)
354
+ - **What:** Automation tools.
355
+ - **Who:** The HUMAN runs them.
356
+ - **When:** Once at project start (scripts/init.py) or if symlinks break (setup-context.sh).
357
+ - **How:** Run from terminal: `python3 scripts/init.py`.
358
+
359
+ ### 4. Skills (`agents/skills/**/*.skill.md`)
360
+ - **What:** Procedure manuals ("Standard Operating Procedures").
361
+ - **Who:** The AGENT follows them step-by-step.
362
+ - **When:** Triggered by specific keywords (e.g., "Review this PR" -> code-review.skill).
363
+ - **How:** You say the trigger word, the Agent loads the skill and follows the checklist.
364
+
365
+ ---
366
+
367
+ ## 🤝 Roles & Responsibilities: Who Does What?
368
+
369
+ | Task | Human (You) | Agent (The Machine) |
370
+ |---|---|---|
371
+ | **Strategy** | **Decides "What to build"** and "Why". | Suggests options, researches feasibility. |
372
+ | **Setup** | Runs `scripts/init.py`, feeds `BOOTSTRAP_MISSION.md` or `SETUP_MISSION.md`. | Reads mission, analyzes stack, updates `AGENTS.md`. |
373
+ | **Config** | Edits `AGENTS.md` (Stack, Commands) & `CONSTITUTION.md`. | **Read-Only**. Can propose changes, cannot edit laws. |
374
+ | **Spec** | Reviews and **Approves** `PRD.md`. | **Writes** `PRD.md` using `spec-writer.skill`. |
375
+ | **Arch** | Reviews and **Approves** `PLAN.md`. | **Designs** `PLAN.md` using `arch-design.skill`. |
376
+ | **Tasks** | Reviews and **Approves** `project/TASKS.md`. | **Decomposes** work into 15m tasks. |
377
+ | **Code** | **Reviews PRs**, handles sensitive API keys. | **Writes Code**, Tests, Lints, Commits. |
378
+ | **Fixes** | Provides new context/logs if stuck. | **Self-Heals** (loops 5x), researches, fixes. |
379
+
380
+ **The Golden Rule:** The Agent is the *Engine*; You are the *Steering Wheel*. You define the destination (Spec) and check the map (Review), but the Agent drives the car (Coding).
381
+
382
+
383
+ ---
384
+
385
+ ## Skill Scopes — Global vs Workspace
386
+
387
+ Skills can be installed at two scopes:
388
+
389
+ | Scope | Location | Visible to |
390
+ |---|---|---|
391
+ | **Global** | `~/.claude/skills/` or `~/.agent/skills/` | All projects on this machine |
392
+ | **Workspace** | `.claude/skills/` or `.agent/skills/` in project root | This project only |
393
+
394
+ **Universal Skill Compiler** (what scripts/init.py does):
395
+
396
+ The script detects your selected agents and generates the correct format for each:
397
+
398
+ | Platform | Format | Location |
399
+ |---|---|---|
400
+ | **Cursor** | `.mdc` rules | `.cursor/rules/*.mdc` |
401
+ | **VS Code / Copilot** | Folders + Config | `.github/skills/<slug>/` |
402
+ | **Claude Code** | Symlink | `.claude/skills` → `agents/skills` |
403
+ | **Gemini / Antigravity** | Settings | `.gemini/settings.json` points to `agents/skills` |
404
+
405
+ This means you write a skill once in `agents/skills/` and it runs everywhere.
406
+
407
+ ---
408
+
409
+ ## How to Invoke Skills
410
+
411
+ Skills are invoked by mentioning trigger keywords in conversation.
412
+
413
+ ```
414
+ # By Slash Command (VS Code / GitHub Copilot):
415
+ /code-review -> triggers code-review.skill
416
+ /tdd-cycle -> triggers tdd-cycle.skill
417
+
418
+ # By Trigger Keyword (Claude / Cursor / Gemini):
419
+ "Review this PR for security issues" -> triggers code-review.skill
420
+ "Use TDD to implement the login endpoint" -> triggers tdd-cycle.skill
421
+ "I'm not sure how to use this library" -> triggers knowledge-gap.skill
422
+
423
+ # By Explicit Name:
424
+ "Use the spec-writer skill for this feature"
425
+ "Run the security-audit skill on this codebase"
426
+ ```
427
+
428
+
429
+ All 214 skills are listed in `agents/skills/00-index.md`.
430
+
431
+ ---
432
+
433
+ ## SDD Lifecycle (Spec-Driven Development)
434
+
435
+ The mandatory artifact chain for all new features:
436
+
437
+ ```
438
+ 0. STRATEGY (business-case / design-thinking / systems-thinking)
439
+ -> Validates the "Why" and "Who" before the "What"
440
+ -> Creates BUSINESS_CASE.md or EMPATHY_MAP.md
441
+ -> Feeds directly into the Specification phase
442
+
443
+ 1. SPECIFY (/speckit.specify or spec-writer.skill)
444
+ -> Creates PRD.md with EARS requirements
445
+ -> Invokes ambiguity layer: agent asks clarifying questions
446
+ -> Human reviews and approves
447
+
448
+ 2. CLARIFY (Ambiguity Layer — built into spec-writer.skill)
449
+ -> Agent identifies ambiguous requirements
450
+ -> Asks structured clarifying questions
451
+ -> No assumption is made without explicit answer
452
+
453
+ 3. PLAN (adr-writer.skill + prod-architect persona)
454
+ -> Creates PLAN.md: implementation phases, files, dependencies
455
+ -> Creates C4 architecture diagram
456
+ -> Creates ADRs for significant decisions
457
+ -> Runs threat-model.skill for security features
458
+
459
+ 4. DECOMPOSE (prod-tech-lead persona + 15-Minute Rule)
460
+ -> Creates project/TASKS.md from PLAN.md
461
+ -> Every task: achievable in ~15 minutes, atomic, testable
462
+ -> Tasks have: acceptance criteria, dependency order, status
463
+
464
+ 5. IMPLEMENT (Engineering swarm / single agent, with RARV cycle)
465
+ -> TDD: test first, implement, verify, refactor
466
+ -> RARV: Reason -> Act -> Reflect -> Verify
467
+ -> Security & Compliance gate: scan passes
468
+ -> Self-heal on failure (max 5 attempts)
469
+ -> Audit log entry for each completed task
470
+ ```
471
+
472
+ **The 15-Minute Rule:** If a task takes > 15 minutes, it's too large. Decompose further.
473
+
474
+ **Artifact chain integrity:** spec-analyze.skill checks that spec.md ↔ plan.md ↔ project/TASKS.md are aligned. Run it whenever artifacts change.
475
+
476
+ ---
477
+
478
+ ## TDD Workflows
479
+
480
+ ### Unit TDD Cycle (tdd-cycle.skill)
481
+
482
+ ```
483
+ Red -> Write failing test. Run it. Confirm it FAILS.
484
+ If it passes immediately: the test is broken. Fix the test.
485
+ Green -> Write minimal code to pass the test. Run it. Confirm it PASSES.
486
+ Do not add any code not needed by the test.
487
+ Refactor -> Improve code quality. Run tests. Confirm still GREEN.
488
+ Check: complexity < 10, no duplication, no dead code.
489
+ ```
490
+
491
+ ### Browser-Based Visual TDD (browser-tdd.skill)
492
+
493
+ For frontend UI components where "works" means "looks and behaves correctly":
494
+
495
+ ```
496
+ 1. Write Playwright test: check DOM structure, computed CSS, scroll behavior, viewport position
497
+ 2. Confirm Red: npx playwright test -> MUST FAIL initially
498
+ 3. Implement CSS/component change
499
+ 4. Confirm Green: npx playwright test -> screenshots, CSS values, DOM assertions pass
500
+ 5. If fail: analyze root cause (overflow:hidden parent? z-index stacking? viewport breakpoint?)
501
+ 6. Refactor for readability while keeping test Green
502
+
503
+ Example Playwright assertions:
504
+ - page.locator('nav').evaluate(el => el.getBoundingClientRect().top) === 0 (sticky)
505
+ - page.locator('.card').getByRole('button').toBeVisible() (accessibility)
506
+ - page.screenshot({ fullPage: true }) (visual regression baseline)
507
+ ```
508
+
509
+ ---
510
+
511
+ ## Architecture-Driven Development (ADD)
512
+
513
+ Enforcing layer boundaries with agentic tools:
514
+
515
+ ### Define Rules in AGENTS.md (Section 3)
516
+ ```yaml
517
+ # Example for Clean Architecture:
518
+ layers:
519
+ domain: "src/domain/**" # No imports from outer layers
520
+ application: "src/application/**" # May import domain only
521
+ adapters: "src/adapters/**" # May import domain + application
522
+ infra: "src/infrastructure/**" # May import all inner layers
523
+ ```
524
+
525
+ ### Enforce with agentic-linter.skill
526
+ ```bash
527
+ # On every PR, agent runs:
528
+ npx dependency-cruiser --config .dependency-cruiser.cjs src
529
+ # OR for PHP:
530
+ vendor/bin/deptrac analyse
531
+
532
+ # If violations found: agent proposes Dependency Inversion refactor
533
+ # Never just reports — always provides a concrete fix proposal
534
+ ```
535
+
536
+ ### ADR for Significant Decisions
537
+ ```
538
+ When to create an ADR (Architecture Decision Record):
539
+ - Adopting a new library or framework
540
+ - Choosing between multiple valid architectural approaches
541
+ - Any decision that would be hard to reverse
542
+ - Any decision affecting security or data handling
543
+
544
+ How: "Use adr-writer skill to document the decision to [X] instead of [Y]"
545
+ ```
546
+
547
+ ---
548
+
549
+ ## Memory Architecture — Preventing Amnesia
550
+
551
+ Long sessions and team projects lose context. The 4-layer memory system solves this:
552
+
553
+ | Layer | Location | Contains | Lifetime |
554
+ |---|---|---|---|
555
+ | **Working** | Context window | Current task, recent code | Session |
556
+ | **Episodic** | `agents/memory/episodic/` | Past decisions, failed experiments per session | Project |
557
+ | **Semantic** | `agents/memory/semantic/` | Crystallized facts (auth quirks, schema conventions) | Project |
558
+ | **Procedural** | `skills/*.skill.md` | Immutable how-to guides per task type | Global |
559
+
560
+ ### Key Memory Files
561
+
562
+
563
+
564
+ | File | Purpose |
565
+ |---|---|
566
+ | `agents/memory/PROJECT_STATE.md` | Current SDLC phase, last checkpoint, blockers |
567
+ | `agents/memory/CONTINUITY.md` | **Read every session** — past failures to avoid |
568
+ | `agents/memory/AUDIT_LOG.md` | Append-only log of all decisions and outcomes |
569
+ | `agents/memory/episodic/SESSION_SNAPSHOT/` | Per-milestone state snapshots |
570
+ | `agents/memory/semantic/PROJECT_KNOWLEDGE_TEMPLATE.md` | Crystallized project facts |
571
+
572
+ ### CONTINUITY.md — The Most Important File
573
+ This file prevents agents from repeating failed approaches:
574
+ ```markdown
575
+ ### 2024-03-15 — Bull queue memory leak with Redis cluster
576
+ Context: Tried to use Bull for job processing
577
+ Approach: Standard Bull config with Redis cluster mode
578
+ Why it failed: Bull doesn't support Redis cluster without bull-cluster package
579
+ Resolution: Switched to BullMQ which has native cluster support
580
+ Tags: [library-conflict, redis, job-queue]
581
+ ```
582
+
583
+ ---
584
+
585
+ ## Golden Rules of Agentic Engineering
586
+
587
+ ### Rule 1 — Atomicity
588
+ > Tasks must be achievable in ~15 minutes. Decompose relentlessly.
589
+
590
+ ```
591
+ BAD: "Implement user authentication" (days of work)
592
+ GOOD: "Create User entity with email/password fields in src/domain/user.ts" (15 min)
593
+ "Add UserRepository interface in src/domain/ports/user-repository.ts" (15 min)
594
+ "Implement PrismaUserRepository in src/infrastructure/prisma-user-repo.ts" (15 min)
595
+ ```
596
+
597
+ ### Rule 2 — Explicit Context
598
+ > If it's not in AGENTS.md, it doesn't exist. Common sense is a myth in AI.
599
+
600
+ ```
601
+ BAD: Expecting agents to "know" that you use pnpm, not npm
602
+ GOOD: Specifying in AGENTS.md: install: "pnpm install"
603
+
604
+ BAD: Expecting agents to "know" your architecture layers
605
+ GOOD: Defining layers explicitly in AGENTS.md Section 3
606
+ ```
607
+
608
+ ### Rule 3 — Verification
609
+ > Trust but verify. TDD or Browser loops always. Output is a draft until it passes a test.
610
+
611
+ ```
612
+ No feature is "done" until:
613
+ - Unit test passes (Red -> Green verified)
614
+ - All existing tests still pass (no regressions)
615
+ - Lint and typecheck pass
616
+ - Security scan clean (for security-relevant changes)
617
+ ```
618
+
619
+ ### Rule 4 — Artifacts as Control Interface
620
+ > spec.md/project/TASKS.md are the control interface, not byproducts. Manage artifacts; code follows.
621
+
622
+ ```
623
+ Wrong mental model: "Write code, then document it"
624
+ Right mental model: "Write spec.md -> human approves -> write project/TASKS.md -> code emerges from tasks"
625
+
626
+ The PRD.md is the truth. The spec.md is the truth. The project/TASKS.md is the control panel.
627
+ Code is just the output of working through project/TASKS.md correctly.
628
+ ```
629
+
630
+ ---
631
+
632
+ ## 4-Phase Team Adoption Roadmap
633
+
634
+ ### Phase 1 — Standardization (Week 1-2)
635
+ ```
636
+ Goal: Every repo has an AGENTS.md and CONSTITUTION.md
637
+ Actions:
638
+ - Run `scripts/init.py` to create tool-specific symlinks (commands, architecture rules, forbidden actions)
639
+ - Draft CONSTITUTION.md (at minimum Articles I-VII)
640
+ - Measure: all agents read AGENTS.md before coding
641
+ ```
642
+
643
+ ### Phase 2 — Capability (Week 3-4)
644
+ ```
645
+ Goal: Install and customize skill packs
646
+ Actions:
647
+ - Install skills/ directory for each repo
648
+ - Customize code-review.skill with project-specific rules
649
+ - Customize git-workflow.skill with your PR template
650
+ - Train team on skill invocation patterns
651
+ - Measure: PR review time, bug escape rate
652
+ ```
653
+
654
+ ### Phase 3 — Adoption (Month 2)
655
+ ```
656
+ Goal: Mandate SDD for all new features
657
+ Rule: No code without an approved PRD.md
658
+ Actions:
659
+ - Make spec-writer.skill the entry point for all feature requests
660
+ - Enforce 7-gate quality system in CI/CD
661
+ - Track and repay tech debt with tech-debt.skill
662
+ - Measure: specification-to-code ratio, coverage, architectural violations
663
+ ```
664
+
665
+ ### Phase 4 — Orchestration (Month 3+)
666
+ ```
667
+ Goal: Loki Mode for background autonomous tasks
668
+ Actions:
669
+ - Identify large projects suitable for Loki Mode
670
+ - Set up agents/memory/ for long-running projects
671
+ - Deploy Loki swarm for a pilot project (new feature or migration)
672
+ - Measure: agent-hours per feature, human intervention rate
673
+ ```
674
+
675
+ ---
676
+
677
+ ## MCP Servers — Key Ones to Install
678
+
679
+ | Server | Install | Why |
680
+ |---|---|---|
681
+ | **Context-7** | `npx @context7/mcp-server` | Up-to-date SDK docs (prevents API hallucination) |
682
+ | **Sequential Thinking** | `npx @modelcontextprotocol/server-sequential-thinking` | Chain-of-thought before acting |
683
+ | **GitHub MCP** | `npx @modelcontextprotocol/server-github` | PR review, issues, code search |
684
+ | **PostgreSQL MCP** | `npx @modelcontextprotocol/server-postgres` | Live schema introspection |
685
+ | **Semgrep MCP** | `pip install semgrep-mcp` | In-agent SAST security scanning |
686
+ | **Brave Search MCP** | `npx @modelcontextprotocol/server-brave-search` | Authoritative web research |
687
+ | **Playwright MCP** | `npx @playwright/mcp` | Browser automation for visual TDD |
688
+ | **Sentry MCP** | `npx @sentry/mcp` | Error tracking and bug context |
689
+ | **Qdrant MCP** | `docker run qdrant/qdrant` + MCP server | Long-term semantic memory |
690
+
691
+ See `templates/core/MCP_CONFIG_TEMPLATE.json` for the full catalog with security configuration.
692
+ See [MCP_CONFIGURATIONS.md](MCP_CONFIGURATIONS.md) for per-server setup instructions and API key guides.
693
+
694
+ ---
695
+
696
+ ## Research Policy — Authoritative Sources Only
697
+
698
+ Agents must use authoritative sources. Non-authoritative answers are hallucinations.
699
+
700
+ | Tier | Sources | When to use |
701
+ |---|---|---|
702
+ | **Tier 1** | Official docs (MDN, nodejs.org, laravel.com), RFCs (RFC.editor.org), Security (OWASP, NIST) | Always prefer |
703
+ | **Tier 2** | arXiv, IEEE, ACM, official GitHub repos, release notes | For academic/technical questions |
704
+ | **Tier 3** | AWS docs, GCP docs, Azure docs, Anthropic docs | For cloud/vendor specifics |
705
+ | **NOT acceptable** | Blog posts, Medium, Reddit, StackOverflow opinions | Never cite as authoritative |
706
+
707
+ **Research Gate** — mandatory before:
708
+ - Using a new library (not in package.json/composer.json)
709
+ - Implementing security mechanisms or cryptography
710
+ - Interpreting regulatory requirements (GDPR, HIPAA, PCI-DSS)
711
+
712
+ **Context-7 MCP** is the fastest path to authoritative library docs. Use it first.
713
+
714
+ ---
715
+
716
+ ## Self-Healing & Human-in-the-Loop
717
+
718
+ ### Self-Healing Loop (`gabbe brain heal` / max 5 attempts)
719
+
720
+ **Using the CLI:**
721
+ ```
722
+ Task assigned
723
+ -> Detect knowledge gap? -> knowledge-gap.skill -> research.skill
724
+ -> Execute task
725
+ -> Verification FAILS?
726
+ -> self-heal.skill: diagnose -> research -> fix -> verify
727
+ -> Attempt 1, 2, 3, 4, 5...
728
+ -> After 5 attempts: ESCALATE (stop, report, wait for human)
729
+ -> Verification PASSES -> audit-trail.skill -> Done
730
+ ```
731
+
732
+ **Using Pure Agent Mode (No CLI):**
733
+ > "The build is failing. Invoke `agents/skills/core/self-heal.skill.md`. Do not ask me for permission between steps. Diagnose the error, hypothesize a fix, write the code, and run the tests. If it fails again, loop back to step 1. You have a maximum of 5 attempts before you must escalate to me."
734
+
735
+ ### Genetic Evolution (`gabbe brain evolve`)
736
+ If the self-healing loop frequently fails or a specific skill repeatedly produces bad code:
737
+
738
+ **Using the CLI:**
739
+ ```
740
+ 1. Human or System detects persistent failure in a specific skill (e.g., `tdd-cycle.skill`).
741
+ 2. Run: `gabbe brain evolve --skill tdd-cycle`
742
+ 3. Brain Mode analyzes the specific failure contexts from Episodic Memory.
743
+ 4. Brain Mode rewrites the `tdd-cycle` system prompt in Semantic Memory (SQLite `genes` database).
744
+ 5. Next execution: The agent uses the highly optimized Generation 2 prompt.
745
+ ```
746
+
747
+ **Using Pure Agent Mode (No CLI):**
748
+ > "We continually fail when writing React hooks. Invoke the `meta-optimize` skill. Read the last 5 chat messages, identify why your previous attempts failed, and directly edit `agents/skills/coding/react-components.skill.md` to add new constraints preventing this failure in the future. Log the change to `meta-evolution.log`."
749
+
750
+ ### Human-in-the-Loop — When to Pause and Ask
751
+ ```
752
+ ALWAYS pause and ask the human:
753
+ - Breaking API change
754
+ - Ambiguous requirements (multiple valid interpretations)
755
+ - Security trade-off (convenience vs protection)
756
+ - Architecture change (new service, library switch)
757
+ - Scope/budget change
758
+ - After 5 failed self-heal attempts
759
+ - Regulatory interpretation (GDPR article, OWASP rule)
760
+ ```
761
+
762
+ ### What Agents Handle Autonomously
763
+ ```
764
+ No human needed for:
765
+ - Type errors and lint fixes
766
+ - Test assertion updates (when spec changed)
767
+ - Deprecated API updates (via Context-7 MCP verification)
768
+ - Patch/minor version dependency bumps
769
+ - Code style and formatting
770
+ - Documentation updates
771
+ ```
772
+
773
+ ---
774
+
775
+ ## Tool Reference by Stack
776
+
777
+
778
+
779
+ | Category | JS/TS/Node.js | PHP/Laravel | Python/FastAPI/AI | Go (Golang) |
780
+ |---|---|---|---|---|
781
+ | **Package Manager** | pnpm (preferred) | Composer | `uv` (preferred), Poetry | `go mod` |
782
+ | **Type Checking** | `tsc --noEmit` | PHPStan L9 | `mypy --strict`, Pyright | `go build` |
783
+ | **Linting** | ESLint | Pint, PHP-CS | `ruff` (preferred) | `golangci-lint` |
784
+ | **Unit Testing** | Vitest | Pest, PHPUnit | `pytest` | `Testify` / `testing` |
785
+ | **Integration** | Testcontainers | RefreshDB | `testcontainers-python` | `Testcontainers` |
786
+ | **E2E / Browser** | Playwright | Dusk | `playwright-python` | `Testcontainers` |
787
+ | **ORM** | Prisma | Eloquent | SQLAlchemy, SQLModel | `Ent` / `GORM` |
788
+ | **Validation** | Zod | Spatie Data | Pydantic v2 | `go-playground/validator` |
789
+ | **Arch Lint** | `dep-cruiser` | `deptrac` | `import-linter` | `arch-go` |
790
+ | **SAST** | Semgrep | Enlightn | Bandit, Semgrep | `govulncheck` |
791
+ | **Secrets** | gitleaks | gitleaks | gitleaks | `gitleaks` |
792
+ | **Tech Debt** | SonarQube | PHPMD | `radon`, `xenon` | `golangci-lint` |
793
+ | **Coverage** | v8 / Istanbul | PCOV | `pytest-cov` | `go test -cover` |
794
+
795
+ ## Skill Reference
796
+
797
+ ### Core & Development
798
+ | Skill | Triggers |
799
+ |---|---|
800
+ | `code-review`, `tdd-cycle`, `browser-tdd`, `refactor`, `debug`, `api-design`, `db-migration` | review, test, visual, refactor, bug, API, migration |
801
+ | `git-workflow`, `documentation`, `spec-writer`, `spec-analyze`, `adr-writer`, `secure-coding` | commit, docs, spec, analyze spec, ADR, secure |
802
+ | `agentic-linter`, `clean-coder`, `mobile-dev`, `visual-design`, `vibe-coding`, `ci-autofix`, `performant-nodejs`, `performant-laravel`, `performant-python`, `performant-go`, `performant-ai` | boundary, clean, mobile, design, vibe, fix, nodejs, performance, laravel, python, go, ai, llm |
803
+
804
+ ### Architecture & Design
805
+ | Skill | Triggers |
806
+ |---|---|
807
+ | `arch-design`, `arch-review`, `arch-patterns`, `design-patterns` | design arch, audit arch, architecture, pattern |
808
+ | `diagramming`, `domain-model`, `adaptive-architecture`, `compatibility-design` | diagram, domain, local-first, compatibility |
809
+ | `architecture-governance`, `error-handling-strategy`, `event-governance` | archunit, error handling, schema registry |
810
+ | `microservices`, `monolith`, `api-standards`, `systems-architecture` | decouple, monolith, c4 models, api |
811
+ | `event-driven-architecture`, `system-qualities`, `critical-systems-arch` | async, eda, nfr, do-178c |
812
+ | `enterprise-patterns`, `enterprise-migration-scenario` | saga, bff, strangler fig, migrate |
813
+
814
+ ### Security, Compliance & Quality
815
+ | Skill | Triggers |
816
+ |---|---|
817
+ | `security-audit`, `threat-model`, `privacy-audit`, `compliance-review`, `legal-review` | security, threat, privacy, SOC2, legal |
818
+ | `access-control`, `data-governance`, `backup-recovery`, `queue-management` | rbac, lineage, backup, dlq |
819
+ | `reliability-sre`, `performance`, `performance-audit`, `incident-response`, `system-benchmark`, `cost-optimization` | SRE, perf, profile, incident, load, cost |
820
+ | `accessibility`, `tech-debt`, `arch-debt`, `hazard-analysis`, `production-health`, `dependency-security` | a11y, debt, skew, fmea, tmr, deps |
821
+ | `dev-environments`, `troubleshooting-guide`, `api-security`, `secure-architecture` | devcontainer, diagnose, bola, zero-trust |
822
+ | `privacy-data-protection`, `cryptography-standards` | gdpr, pii, encryption, hashing |
823
+
824
+ ### Strategy & Agentic
825
+ | Skill | Triggers |
826
+ |---|---|
827
+ | `business-case`, `design-thinking`, `systems-thinking`, `research` | ROI, empathy, loops, research |
828
+ | `req-elicitation`, `req-review` | gather reqs, audit specs |
829
+ | `agentic-patterns`, `multi-agent-orch`, `agent-protocol`, `agent-interop`, `swarm-consensus` | agentic, swarm, protocol, connect, vote |
830
+ | `knowledge-gap`, `self-heal`, `session-resume`, `sdlc-checkpoint`, `knowledge-connect` | unsure, fix, resume, checkpoint, RAG |
831
+ | `integrity-check`, `audit-trail`, `system-lifecycle`, `episodic-consolidation` | verify, log, trace, consolidation |
832
+ | `emerging-tech`, `legacy-modernization` | future, legacy |
833
+ | `multi-agent-systems`, `agent-communication`, `beyond-llms` | mas, orchestration, a2a, mcp |
834
+ | `autonomous-swarm-patterns`, `agent-ui`, `actor-agent-frameworks`, `a2ui-protocols` | swarm, langgraph, ui, streams |
835
+
836
+ ## Templates Reference
837
+
838
+ | Category | Templates |
839
+ |---|---|
840
+ | **Core** | `AGENTS`, `MCP_CONFIG`, `DEVCONTAINER`, `DEV_SPACE`, `PLAN`, `TASKS`, `AUDIT_LOG`, `SDLC_TRACKER`, `SESSION_SNAPSHOT`, `SWARM_CONFIG`, `AGENT_HANDSHAKE`, `SYSTEM_ANALYSIS`, `PROJECT_STATE`, `CONTINUITY`, `VOTING_LOG` |
841
+ | **Arch** | `ADR`, `ARCH_DECISION_FRAMEWORK`, `ARCHITECTURE_DECISION_MATRIX`, `ARCHITECTURE_REVIEW`, `ARCHITECTURE_VIEWS`, `C4_ARCHITECTURE`, `CONTEXT_MAP`, `DOMAIN_MODEL`, `SYSTEM_CONTEXT`, `SWARM_ARCHITECTURE`, `DESIGN_PATTERN_USAGE`, `CAPABILITY_MAP`, `LEGACY_AUDIT` |
842
+ | **Reqs** | `PRD`, `SPEC`, `BUSINESS_CASE`, `CAPABILITY_MAP`, `EMPATHY_MAP`, `NFR`, `QUALITY_ATTRIBUTES`, `REQUIREMENTS_REVIEW`, `STAKEHOLDER_REGISTER`, `TRACEABILITY_MATRIX`, `ETHICAL_IMPACT_ASSESSMENT` |
843
+ | **Eng** | `CLEAN_CODE_CHECKLIST`, `SECURITY_CHECKLIST`, `THREAT_MODEL`, `TECH_DEBT`, `TEST_PLAN`, `TEST_CASE`, `INTEGRATION_SPEC`, `DATA_PIPELINE`, `DATABASE_SCHEMA`, `DESIGN_TOKENS`, `E2E_TEST_SUITE`, `SAFETY_POLICY` |
844
+ | **Ops** | `DEPLOY_CONFIG`, `INFRA_PLAN`, `BUG_REPORT`, `INCIDENT_POSTMORTEM`, `LEGACY_AUDIT`, `ADAPTIVE_SYSTEM`, `AGENT_PROFILE`, `COST_OPTIMIZATION_REPORT`, `CAPACITY_PLAN`, `RELEASE_READINESS_REPORT`, `BENCHMARK_REPORT` |
845
+ | **Product** | `USER_STORY_MAP`, `KNOWLEDGE_MAP` |
846
+
847
+ ## Guides Reference
848
+
849
+ | Category | Guides |
850
+ |---|---|
851
+ | **Stack** | `js-ts-nodejs`, `go-lang`, `php-laravel`, `python-fastapi-ai`, `sql-nosql`, `c-sharp` |
852
+ | **Arch** | `systems-architecture`, `critical-systems-arch`, `event-driven-architecture`, `monolith`, `microservices` |
853
+ | **Agentic** | `agentic-patterns`, `multi-agent-systems`, `autonomous-swarm-patterns`, `agent-communication` |
854
+ | **Lifecycle** | `full-system-lifecycle`, `testing-strategy`, `production-health`, `compliance-audit`, `strategic-analysis`, `troubleshooting-guide`, `self-healing-summary` |
855
+ | **Integration** | `enterprise-patterns`, `knowledge-integration`, `no-code-integration`, `api-standards`, `enterprise-migration-scenario` |
856
+ | **Security** | `api-security`, `cryptography-standards`, `privacy-data-protection`, `secure-architecture`, `threat-modeling` |
857
+ | **UI/UX** | `visual-design-system`, `a2ui-protocols`, `agent-ui` |
858
+
859
+ ---
860
+
861
+ ## Quick Command Reference
862
+
863
+ ```bash
864
+ # Initialize kit for a new project
865
+ # Initialize kit for a new project
866
+ python3 GABBE/scripts/init.py
867
+
868
+ # Check project health (run anytime)
869
+ # Tell agent: "Run integrity-check skill"
870
+
871
+ # Start a new feature
872
+ # Tell agent: "Use spec-writer skill for [feature name]"
873
+
874
+ # Fix a bug (TDD approach)
875
+ # Fill: templates/core/BUG_REPORT_TEMPLATE.md
876
+ # Tell agent: "Use debug skill. Bug is described in BUG_REPORT_TEMPLATE.md"
877
+
878
+ # Resume interrupted project
879
+ # Tell agent: "Use session-resume skill to load all project memory"
880
+
881
+ # Security audit before release
882
+ # Tell agent: "Run security-audit skill on this codebase"
883
+
884
+ # Check tech debt
885
+ # Tell agent: "Run tech-debt skill on src/ directory"
886
+
887
+ # Prepare for production deploy
888
+ # Tell agent: "Run integrity-check skill, then safety-scan skill, then deployment skill"
889
+
890
+ # Make it look good (Vibe Coding)
891
+ # Tell agent: "Use vibe-coding skill. Make the landing page feel 'Cyberpunk 2077' but clean."
892
+ ```
893
+
894
+ ---
895
+
896
+ *See README.md for quick reference.*
897
+ *See README_FULL.md for full workflow guides with Mermaid diagrams.*
898
+ *See skills/00-index.md for complete skills registry with installation instructions.*
899
+ *See agents/skills/brain/README_ORCHESTRATORS.md for Loki Mode multi-agent orchestration.*
900
+ *See agents/skills/brain/README.md for complete brain documentation.*
901
+
902
+ ## 🛡️ Security & Guardrails
903
+
904
+ All 214 skills in the GABBE kit feature a heavily enforced **"Security & Guardrails"** section that binds agents to the project's CONSTITUTION.md. The 3-layer security constraints include:
905
+
906
+ 1. **Skill Security**: Tool-specific protection (e.g., preventing command injection or sandbox escapes).
907
+ 2. **System Integration Security**: Safe external integration (e.g., verifying boundary enforcement or ensuring test coverage).
908
+ 3. **LLM/Agent Guardrails**: Protection from AI-specific failures (e.g., confirmation bias, or prompt injection).
909
+
910
+ Agents are explicitly configured to **Fail-Closed**—they must wait for human approval rather than bypassing a guardrail.
911
+
912
+ ---
913
+
914
+ [© 2026 Andrei Nicolae Besleaga. This work is licensed CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)