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
package/README.md ADDED
@@ -0,0 +1,817 @@
1
+ # GABBE (Generative Architectural Brain Base Engine)
2
+ ## Agentic Software R&D Engineering Kit
3
+
4
+ ## Quick Reference
5
+
6
+ ![GABBE Agentic Software R&D Engineering Kit](docs/assets/GABBE.png)
7
+
8
+ ## What is this?
9
+
10
+ - Agentic code development and governance via capability layers and software development cycle gates verifications and alignment (including best practices for security and human-in-the-loop, complete framework).
11
+ - The first published open-source project world-wide that features a complete agentic coding kit/framework with cognitive brain loop, skills, SDLC workflow, etc.
12
+ - Universal kit for Software and AI coding agents: Claude Code, Cursor, Windsurf, Cline, Aider, Devin, Gemini, **Antigravity**, **OpenCode**, **Zed**, **Continue**, **Roo Code**, **Kilo Code**, OpenAI/Codex, GitHub Copilot, VS Code.
13
+ - Drop-in context kit that turns any AI coding agent into a governed engineering team for developing software.
14
+ - Based on Software Engineering & Architecture Practices and Procedures.
15
+ - Works for any project type, new or existing, any language, any team size.
16
+ - **Write Once, Run Everywhere**: SKILLS for Cursor (`.mdc`), VS Code / Copilot (`folder/SKILL.md`), Claude (`.claude/skills`), Gemini, and the universal `.agents/skills/` tree read by Antigravity, OpenCode, and any agentskills.io tool.
17
+ - **Trivially installable**: `npx gabbe-kit init` (Python-independent) or `curl -fsSL …/install.sh | sh`, plus the Python wizard / PyPI. Move work between agents anytime (portable state export/import).
18
+ - **First-class** Observability (decision/cost traces, OTel GenAI conventions), Spec-Driven development (spec → evals → test → code), and a manager-not-operator human↔agent collaboration model.
19
+ - The system features an experimental **Meta-Cognitive Orchestrator "Brain"** (Neurocognitive based architecture derived from Neuroscience, Cognitive Psychology, Epistemology, treating the Software System not as a machine, but as a **Cognitive Entity**), using Active Inference to plan, route, and optimize work.
20
+ - The system features a **Multi-Agent Swarm "Loki" Engineering Team** (30+ specialized agent roles for large projects), providing episodic and semantic memory, project history auditing and checkpoints.
21
+ - Experimental support for budget enforcement, tokens, hard stops, policy rules, cli tool gateway (via MCP server), audit tracing and logs, human escalation, and deterministic replay, with built-in rules for agents to select the best specialized skills/guides, proactively recommend necessary MCP servers, and default to continuous cost & budget optimization—always requiring human approval for expensive operations.
22
+ - **v1.0** extends the framework to a **cradle-to-grave ADLC (S00–S13)** — Day-0 Strategy & Discovery (S00) through the S01–S10 SDLC to Day-2 Operate/Evolve/Decommission (S11–S13), grounded in named industry methods (ADD 3.0, ATAM, Wardley, JTBD, RICE, DORA/SPACE, ADKAR) — and adds an **evals + standards-grounded guardrails layer** (eval-driven development, LLM-as-judge, RAG/trajectory evals, plus prompt-injection-defense and output-validation mapped to OWASP LLM Top 10 / NIST AI RMF / MITRE ATLAS / ISO 42001 / EU AI Act), **advanced testing** (property-based, metamorphic, chaos/fault-injection, and mutation testing; `gabbe verify --chaos`), and **one-command, multi-OS install with autodetect** (`gabbe doctor` reports OS/arch, runtimes, and detected agents; install/update/uninstall are fully reversible via a `.gabbe/manifest.json`). The "world-first" framing stays honest: the **self-evolving "genes" / brain-inference-via-skills** model is a conceptual framing — the production brain is epsilon-greedy with a monotonic success-rate, and evals/PBT **sample and raise confidence, they do not prove**.
23
+
24
+ It contains:
25
+ - **214 Skills** (specialized capabilities)
26
+ - **100 Templates** (standardized documents)
27
+ - **86 Guides** (language & domain expertise)
28
+ - **36 Personas** (specialized roles)
29
+ - **50+ MCP servers** (configuration and guides for AI tools)
30
+ - **Brain Mode** (meta-cognitive orchestration)
31
+ - **Loki Mode** (multi-agent swarm engineering personas team for large projects)
32
+
33
+ > **214 Skills · 100 Templates · 86 Guides · 36 Personas · 50+ MCPs · Loki / Brain Mode CLI**
34
+
35
+ ---
36
+
37
+ *Full documentation: [README_FULL.md](docs/README_FULL.md) · Full quick guide: [QUICK_GUIDE.md](docs/QUICK_GUIDE.md) · Quick commands: [QUICK_COMMANDS.md](docs/QUICK_COMMANDS.md) · CLI reference: [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) · MCP servers: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md) · Platform Controls: [PLATFORM_CONTROLS.md](docs/PLATFORM_CONTROLS.md) · Verification Guide: [VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md)*
38
+
39
+ ---
40
+
41
+ *Online articles: [Medium](https://medium.com/towards-artificial-intelligence/gabbe-the-cognitive-engineering-platform-that-transforms-ai-coding-agents-into-engineering-teams-580226b05373), [Substack](https://andreibesleaga.substack.com/p/gabbe-the-cognitive-engineering-platform), [TechRxiv](https://www.techrxiv.org/users/980097/articles/1391107-gabbe-a-neurocognitive-swarm-architecture-for-agentic-ai-software-engineering)*
42
+
43
+ ---
44
+
45
+ *Example project where GABBE is used: [Agentic AI Medical Imagery Diagnostic Helper](https://github.com/andreibesleaga/AgenticMedicalImagingHelper)*
46
+
47
+ ---
48
+
49
+ ### ⚡ Automated Setup (Recommended)
50
+
51
+ **Universal, Python-independent (one command):**
52
+ ```bash
53
+ npx gabbe-kit init # Node installer — bundles the kit, wires every agent
54
+ npx gabbe-kit init --agents claude,cursor,antigravity,opencode --yes # non-interactive
55
+ # or, without npm:
56
+ curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh | sh
57
+ ```
58
+
59
+ **Python wizard (full interactive, also via PyPI):**
60
+ ```bash
61
+ python3 scripts/init.py # from a checkout
62
+ gabbe setup # if the optional gabbe CLI is installed (pipx/uvx/pip)
63
+ ```
64
+
65
+ The installer is a **Universal Skill Compiler** — it generates the correct format for each AI tool:
66
+ - **Cursor**: `.cursor/rules/*.mdc` (agent-requested rules, intelligently selected by description)
67
+ - **VS Code / Copilot**: `.github/skills/<slug>/SKILL.md`
68
+ - **Claude Code**: `.claude/skills/<slug>/SKILL.md`
69
+ - **Gemini**: `.gemini/settings.json` + `GEMINI.md`
70
+ - **Antigravity / OpenCode** (and any agentskills.io tool): the universal `.agents/skills/<slug>/SKILL.md` tree (+ `opencode.json` for OpenCode)
71
+ - **Zed / Continue / Roo Code / Kilo Code**: root `AGENTS.md` (agents.md standard) + each tool's rules file
72
+ - Every install also writes a root `AGENTS.md` (the agents.md open standard).
73
+
74
+ Steps after running the wizard:
75
+
76
+ 1. **Verify Context**
77
+ - Open `agents/AGENTS.md` and check the `Tech Stack` section and other [PLACEHOLDER] or Optional sections.
78
+ - Open `agents/CONSTITUTION.md` and review project laws.
79
+
80
+ 2. **Feed the Mission**
81
+ - The script generates `BOOTSTRAP_MISSION.md` (or `SETUP_MISSION.md` if dynamic setup is disabled) in your root.
82
+ - **Copy its content** and paste it into your AI Agent's chat window.
83
+ - This aligns the agent with your project context immediately.
84
+
85
+ 3. **Git Tracking**
86
+ - If you want 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:
87
+ ```bash
88
+ git ls-files agents/memory/ project/ | xargs git update-index --skip-worktree
89
+ ```
90
+
91
+ **Manual Setup:**
92
+ ```bash
93
+ cp -r GABBE/agents .
94
+ chmod +x agents/setup-context.sh && agents/setup-context.sh
95
+ ```
96
+
97
+ ### 🌍 Cross-Platform Support
98
+ - **Linux / macOS / WSL:** Native support.
99
+ - **Windows (Native):**
100
+ - Use `python scripts/init.py` (Symlinks automatically fallback to file copies if needed).
101
+ - Use `agents/scripts/setup-context.ps1` instead of `.sh`.
102
+
103
+ ---
104
+
105
+ ## 🚀 Common Actions (Copy-Paste Prompts)
106
+
107
+ ### Strategy & Ideation (Step 0)
108
+ ```
109
+ "Use business-case/strategy skills to validate exactly why we are building [description] and who it is for."
110
+ ```
111
+
112
+ ### New Project from Scratch
113
+ ```
114
+ "Read AGENTS.md. I want to build [description]. Start with spec-writer skill."
115
+ ```
116
+ **Flow:** Strategy → Spec → Design → Tasks → TDD Implementation → Security → Deploy
117
+
118
+ ### Resume Existing Project
119
+ ```
120
+ "Read AGENTS.md and agents/memory/PROJECT_STATE.md. Resume the project."
121
+ ```
122
+
123
+ ### Fix a Bug
124
+ ```
125
+ "Read AGENTS.md. Bug: [description]. Use debug skill with TDD."
126
+ ```
127
+ **Flow:** Reproduce → Root Cause → Failing Test → Fix → Green → Regression Check
128
+
129
+ ### Refactor / Pay Tech Debt
130
+ ```
131
+ "Use tech-debt skill on [directory]. Then refactor the top-priority item."
132
+ ```
133
+
134
+ ### Security Audit
135
+ ```
136
+ "Run security-audit skill on the entire codebase."
137
+ ```
138
+
139
+ ### Architecture Review
140
+ ```
141
+ "Run arch-review skill. Check for SOLID violations and coupling."
142
+ ```
143
+ ```
144
+ "Use the performant-nodejs skill to audit the current Node.js architecture for scalability bottlenecks and propose optimizations."
145
+ ```
146
+ ```
147
+ "Use the performant-laravel skill to audit the current Laravel architecture for scalability bottlenecks and propose optimizations."
148
+ ```
149
+ ```
150
+ "Use the performant-python skill to audit the current Python architecture for scalability bottlenecks and propose optimizations."
151
+ ```
152
+ ```
153
+ "Use the performant-go skill to audit the current Go architecture for scalability bottlenecks and propose optimizations."
154
+ ```
155
+ ```
156
+ "Use the performant-ai skill to audit the current AI/LLM architecture for latency and cost bottlenecks."
157
+ ```
158
+ ```
159
+ "Use the time-complexity skill to scan src/ for Big-O complexity hotspots and identify functions worse than O(n)."
160
+ ```
161
+
162
+ ### Software Engineering & System Architecture
163
+ ```
164
+ "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."
165
+ ```
166
+ ```
167
+ "Use the visual-whiteboarding skill. Connect to the Draw.io/Miro MCP and generate a visual spatial architecture diagram for the current microservice layout."
168
+ ```
169
+ ```
170
+ "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."
171
+ ```
172
+
173
+ ### Vibe-Coding (Creative Frontend)
174
+ ```
175
+ "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."
176
+ ```
177
+
178
+ ### Activate Brain Mode (Complex Goals)
179
+ ```
180
+ "Activate Brain Mode. Goal: [build X / migrate Y / solve Z]."
181
+ ```
182
+ Uses Active Inference to plan, route between local/remote models, and learn from past outcomes.
183
+
184
+ ### Activate Loki Mode (Large Projects)
185
+ **Using Pure Agent Mode (No CLI):**
186
+ > "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."
187
+
188
+ Multi-agent swarm with 30+ specialized personas for projects >5 features or >20 files.
189
+
190
+ ---
191
+
192
+ ## End-to-End Workflow & Architecture
193
+
194
+ ### Visual Overview (Mermaid)
195
+
196
+ ```mermaid
197
+ graph TD
198
+ %% Phase 1: Setup
199
+ subgraph Setup [1. Setup Phase]
200
+ Start([Start]) --> Init[Run init.py]
201
+ Init --> Mission[Feed BOOTSTRAP_MISSION.md or SETUP_MISSION.md]
202
+ Mission --> Config[Edit AGENTS.md]
203
+ end
204
+
205
+ %% Phase 2: Definition
206
+ subgraph Definition [2. Definition Phase]
207
+ Config --> Spec[Trigger: spec-writer.skill]
208
+ Spec --> PRD[Artifact: PRD.md]
209
+ PRD --> Review1{Human Approve?}
210
+ Review1 -- No --> Spec
211
+ end
212
+
213
+ %% Phase 3: Design
214
+ subgraph Design [3. Design Phase]
215
+ Review1 -- Yes --> Plan[Trigger: arch-design.skill]
216
+ Plan --> Arch[Artifact: PLAN.md + C4]
217
+ Arch --> Review2{Human Approve?}
218
+ Review2 -- No --> Plan
219
+ end
220
+
221
+ %% Phase 4: Execution
222
+ subgraph Execution [4. Execution Loop]
223
+ Review2 -- Yes --> Tasks[Trigger: Decompose project/TASKS.md]
224
+ Tasks --> LoopCheck{Tasks Remaining?}
225
+ LoopCheck -- Yes --> Pick[Pick Task]
226
+ Pick --> TDD[Trigger: tdd-cycle.skill]
227
+ TDD --> Red[Test Fails]
228
+ Red --> Green[Implement Pass]
229
+ Green --> Refactor[Refactor]
230
+ Refactor --> Verify[Audit Log]
231
+ Verify --> LoopCheck
232
+ end
233
+
234
+ %% Phase 5: Delivery
235
+ subgraph Delivery [5. Delivery Phase]
236
+ LoopCheck -- No --> Integrity[Trigger: integrity-check.skill]
237
+ Integrity --> Security[Trigger: security-audit.skill]
238
+ Security --> HumanRev{Human Review?}
239
+ HumanRev -- No --> Fix[Fix Issues]
240
+ Fix --> Integrity
241
+ HumanRev -- Yes --> Deploy[Deploy]
242
+ Deploy --> End([Done])
243
+ end
244
+ ```
245
+
246
+ ### Text Overview (ASCII)
247
+
248
+ ```text
249
+ [START]
250
+ |
251
+ [INSTALL] python3 scripts/init.py -> Generates BOOTSTRAP_MISSION.md (or SETUP_MISSION.md)
252
+ |
253
+ [SETUP] Feed Mission to Agent -> Edit AGENTS.md (Stack/Rules)
254
+ |
255
+ [DEFINE] "Start new feature" -> spec-writer.skill -> PRD.md
256
+ | (Human Reviews & Approves PRD)
257
+ v
258
+ [DESIGN] Plan Architecture -> arch-design.skill -> PLAN.md + ADRs
259
+ | (Human Reviews & Approves Plan)
260
+ v
261
+ [TASKS] Decompose to project/TASKS.md (Atomic 15-min units)
262
+ |
263
+ +---> [IMPLEMENTATION LOOP] ----------------------------------+
264
+ | 1. Pick Task from project/TASKS.md |
265
+ | 2. Write Failing Test (Red) |
266
+ | 3. Write Code to Pass (Green) |
267
+ | 4. Refactor & Clean Up |
268
+ | 5. Verify (Tests + Lint) & Log to AUDIT_LOG.md |
269
+ | (Repeat until project/TASKS.md is empty) |
270
+ +-------------------------------------------------------------+
271
+ |
272
+ [VERIFY] integrity-check.skill -> security-audit.skill
273
+ | (Human Final Review)
274
+ v
275
+ [DEPLOY] Merge PR -> Staging -> Production -> [DONE]
276
+ ```
277
+
278
+ ---
279
+
280
+ ## System Architecture
281
+
282
+ How the pieces fit together to create a "Cognitive Entity".
283
+
284
+ ### Visual Architecture (Mermaid)
285
+
286
+ ```mermaid
287
+ graph TB
288
+ subgraph Human ["User (Steering Wheel)"]
289
+ H1[Strategy & Goals]
290
+ H2[Review & Approval]
291
+ end
292
+
293
+ subgraph Agent ["Agent / Brain (Engine)"]
294
+ B1[Active Inference Loop]
295
+ B2[Task Router]
296
+ end
297
+
298
+ subgraph Context ["Project Context"]
299
+ C1[AGENTS.md]
300
+ C2[CONSTITUTION.md]
301
+ end
302
+
303
+ subgraph Tools ["Capability Layer"]
304
+ S[214 Skills]
305
+ T[100 Templates]
306
+ G[86 Guides]
307
+ end
308
+
309
+ subgraph Memory ["Memory System"]
310
+ M1[Working Memory]
311
+ M2["Episodic (Logs)"]
312
+ M3["Semantic (Facts)"]
313
+ end
314
+
315
+ H1 --> B1
316
+ C1 --> B1
317
+ B1 --> B2
318
+ B2 --> S
319
+ S --> T
320
+ S --> M2
321
+ M3 --> B1
322
+ S --> H2
323
+ H2 -- Feedback --> B1
324
+ ```
325
+
326
+ ### Text Architecture (ASCII)
327
+
328
+ ```text
329
+ [HUMAN USER]
330
+ | (Goal/Feedback)
331
+ v
332
+ +-------------------+ +------------------+
333
+ | AGENT BRAIN | <--- | PROJECT CONTEXT |
334
+ | (Active Inference)| | (AGENTS/Rules) |
335
+ +--------+----------+ +------------------+
336
+ |
337
+ v
338
+ [ROUTER & ORCHESTRATOR]
339
+ |
340
+ +--------+--------------------------+
341
+ | |
342
+ [SKILLS] (Function) [MEMORY] (Context)
343
+ | |
344
+ +-> [Coding] +-> [Episodic Logs]
345
+ +-> [Architecture] +-> [Semantic Facts]
346
+ +-> [Security] +-> [Continuity]
347
+ +-> [Ops / SRE] |
348
+ | |
349
+ v v
350
+ [TEMPLATES] (Structured Output) <---+
351
+ ```
352
+
353
+ ---
354
+
355
+ ## Spec-Driven SDLC Lifecycle
356
+
357
+ The "Golden Path" for every feature.
358
+
359
+ ### Visual SDLC (Mermaid)
360
+
361
+ ```mermaid
362
+ flowchart TD
363
+ S0[S00: Strategy] -->|Business Case| S1[S01: Specify]
364
+
365
+ subgraph Definition
366
+ S1 -->|PRD Draft| Ambiguity{Ambiguous?}
367
+ Ambiguity -- Yes --> Clarify[Clarify Questions]
368
+ Clarify --> S1
369
+ Ambiguity -- No --> S2[S02: Plan]
370
+ end
371
+
372
+ subgraph Design
373
+ S2 -->|PLAN.md + C4| Review1{Approved?}
374
+ Review1 -- No --> S2
375
+ Review1 -- Yes --> S3[S04: Tasks]
376
+ end
377
+
378
+ subgraph Execution
379
+ S3 -->|project/TASKS.md| Decomp{Task < 15m?}
380
+ Decomp -- No --> S3
381
+ Decomp -- Yes --> S4[S05: Implement]
382
+
383
+ S4 --> TDD[TDD Cycle]
384
+ TDD --> RARV[RARV: Reason/Act/Reflect/Verify]
385
+ RARV --> Audit[Audit Log]
386
+ end
387
+
388
+ Audit --> Done([Feature Complete])
389
+ ```
390
+
391
+ ### Text SDLC (ASCII)
392
+
393
+ ```text
394
+ 0. STRATEGY
395
+ -> Why are we building this? (Value/ROI)
396
+ v
397
+ 1. SPECIFY (S01)
398
+ -> spec-writer.skill -> PRD.md (EARS Syntax)
399
+ -> (Optional) visual-specs.skill -> Visual Spec Package (UI/Arch from scans)
400
+ -> Human Review & Approval
401
+ v
402
+ 2. PLAN (S02)
403
+ -> arch-design.skill -> PLAN.md + C4 Diagrams
404
+ -> adr-writer.skill -> Architectural Decisions
405
+ v
406
+ 3. DECOMPOSE (S03/S04)
407
+ -> project/TASKS.md -> Atomic steps (<15 mins each)
408
+ v
409
+ 4. IMPLEMENT (S05)
410
+ -> One task at a time
411
+ -> TDD Loop: Red -> Green -> Refactor
412
+ -> RARV Loop: Reason -> Act -> Reflect -> Verify
413
+ v
414
+ 5. VERIFY & SHIP (S06-S10)
415
+ -> Integrity Check -> Security Audit -> Deploy
416
+
417
+ 6. COGNITIVE ORCHESTRATION & HEALING
418
+ -> gabbe brain activate -> Predict bottlenecks & route complexity
419
+ -> gabbe brain evolve -> Meta-optimize failing skills into Semantic Memory
420
+ -> gabbe brain heal -> Recover from environment/DB corruption
421
+ ```
422
+
423
+ ---
424
+
425
+ ## Agents Kit Structure Map
426
+
427
+ ```
428
+ agents/
429
+ ├── AGENTS.md # Universal config (edit per project)
430
+ ├── CONSTITUTION.md # Immutable project law
431
+ ├── skills/ # 214 .skill.md files
432
+ │ ├── 00-index.md # Full skills registry
433
+ │ ├── coding/ # tdd, review, debug, refactor, git...
434
+ │ ├── architecture/ # arch-design, patterns, api-design...
435
+ │ ├── security/ # audit, threat-model, privacy...
436
+ │ ├── ops/ # sre, docker, k8s, deploy, cost...
437
+ │ ├── product/ # spec-writer, req-elicitation...
438
+ │ ├── core/ # research, self-heal, lifecycle...
439
+ │ ├── data/ # data-engineering, db-migration
440
+ │ ├── coordination/ # multi-agent-orch, agent-protocol
441
+ │ └── brain/ # active-inference, consciousness, memory...
442
+ ├── templates/ # 100 fill-in-the-blank documents
443
+ │ ├── 00-index.md # Full templates registry
444
+ │ ├── coding/ # test plans, checklists, devcontainer
445
+ │ ├── architecture/ # ADR, C4, domain model, integration
446
+ │ ├── security/ # threat model, safety case, ethics
447
+ │ ├── ops/ # incident, deploy, capacity, benchmark
448
+ │ ├── product/ # PRD, spec, user story, business case
449
+ │ ├── core/ # plan, tasks, audit log, traceability
450
+ │ ├── coordination/ # agent profiles, swarm config
451
+ │ └── brain/ # inference loop, episodic memory, OODA
452
+ ├── guides/ # 86 language & domain guides
453
+ ├── personas/ # 36 specialized agent roles
454
+ ├── memory/ # Episodic + semantic + project state
455
+ └── docs/ # Whitepapers & research
456
+ ```
457
+
458
+ ---
459
+
460
+ ## 🧠 Brain Mode (Meta-Cognitive Layer)
461
+
462
+ > [!NOTE]
463
+ > **Experimental.** Brain Mode, Loki Mode, Active Inference, Evolutionary Prompt
464
+ > Optimization, the self-healing loop, and forecasting are experimental research
465
+ > runtimes. They are gated behind explicit `gabbe brain …` subcommands (never on
466
+ > by default), covered by the test suite, and deterministically replayable
467
+ > (`gabbe replay`). See [ADR-0002](docs/adr/0002-brain-active-inference-runtime.md)
468
+ > for the design rationale and [docs/VERIFICATION_GUIDE.md](docs/VERIFICATION_GUIDE.md)
469
+ > for how to reproduce each one. Treat outputs as advisory, not production guarantees.
470
+
471
+ Sits **above** Loki. Decides *how* to execute, not just *what* to execute.
472
+
473
+ | Feature | Description |
474
+ |---|---|
475
+ | **Active Inference** | Predict → Act → Observe → Compare → Adapt loop |
476
+ | **Cost Routing** | Simple tasks → local free models, complex → remote SOTA |
477
+ | **Episodic Memory** | Recalls past project outcomes to avoid repeated mistakes |
478
+ | **System 2 Thinking** | Strategic planning before execution |
479
+
480
+ ---
481
+
482
+ ## 🔧 Setup by Project Type
483
+
484
+ ### JavaScript / TypeScript / Node.js
485
+ ```
486
+ Guide: guides/js-ts-nodejs.md
487
+ Stack: Vitest, Zod, Prisma, Playwright, Hono
488
+ Config in AGENTS.md: test_cmd="npx vitest", lint_cmd="npx eslint ."
489
+ ```
490
+
491
+ ### Go (Golang)
492
+ ```
493
+ Guide: guides/go-lang.md
494
+ Stack: Echo/Gin, Ent, Testify, Testcontainers
495
+ Config in AGENTS.md: test_cmd="go test ./...", lint_cmd="golangci-lint run"
496
+ ```
497
+
498
+ ### PHP / Laravel
499
+ ```
500
+ Guide: guides/php-laravel.md
501
+ Stack: DDD, Actions, Pest PHP, PHPStan L9, Enlightn
502
+ Config in AGENTS.md: test_cmd="vendor/bin/pest", lint_cmd="vendor/bin/pint"
503
+ ```
504
+
505
+ ### Python / FastAPI
506
+ ```
507
+ Guide: guides/python-fastapi-ai.md
508
+ Stack: Pydantic, Pytest, Ruff, FastAPI
509
+ Config in AGENTS.md: test_cmd="pytest", lint_cmd="ruff check ."
510
+ ```
511
+
512
+ ---
513
+
514
+ ## 📋 SDLC Phases (10 Gates)
515
+
516
+ | Phase | Gate | Key Artifact |
517
+ |---|---|---|
518
+ | S01 | Requirements | `PRD_TEMPLATE.md` (EARS syntax) |
519
+ | S02 | Design | `ADR_TEMPLATE.md` + C4 diagrams |
520
+ | S03 | Specification | `SPEC_TEMPLATE.md` + API contracts |
521
+ | S04 | Tasks | `TASKS_TEMPLATE.md` (15-min rule) |
522
+ | S05 | Implementation | TDD Red→Green→Refactor + RARV |
523
+ | S06 | Testing | Unit >99% + integration + E2E |
524
+ | S07 | Security | `SECURITY_CHECKLIST.md` + audit |
525
+ | S08 | Review | Human code review |
526
+ | S09 | Staging | Smoke tests + benchmarks |
527
+ | S10 | Production | Rollback plan + monitoring |
528
+
529
+ ---
530
+
531
+ ## 🛠️ Skills Summary (by Category)
532
+
533
+ | Category | Count | Key Skills |
534
+ |---|---|---|
535
+ | **Coding** | 10+ | `tdd-cycle`, `debug`, `refactor`, `code-review`, `git-workflow` |
536
+ | **Architecture** | 15+ | `arch-design`, `microservices`, `systems-architecture`, `system-scalability`, `blockchain-dlt` |
537
+ | **Operations** | 15+ | `reliability-sre`, `production-health`, `dev-environments`, `cost-optimization` |
538
+ | **Security** | 15+ | `security-audit`, `secure-architecture`, `privacy-data-protection`, `api-security` |
539
+ | **Product** | 10+ | `spec-writer`, `req-elicitation`, `visual-specs`, `green-software` |
540
+ | **Core** | 10+ | `research`, `self-heal`, `knowledge-gap`, `meta-optimize` |
541
+ | **Data** | 5+ | `data-engineering`, `db-migration`, `semantic-web` |
542
+ | **Coordination** | 5+ | `multi-agent-orch`, `agent-protocol` |
543
+ | **Brain** | 10+ | `active-inference`, `consciousness-loop`, `cost-benefit-router` |
544
+ | **AI/Swarm** | 5+ | `multi-agent-systems`, `agent-communication`, `beyond-llms` |
545
+ | **Industry** | 5+ | `healthcare-fhir`, `telecom-networks`, `industrial-iot`, `global-standards`, `engineering-standards` |
546
+ | **Loki Modes** | 2+ | `brain-mode`, `loki-mode` |
547
+
548
+ Full catalog: `agents/skills/00-index.md` *(generated by `init.py`)*
549
+
550
+ ---
551
+
552
+ ## 📝 Templates Summary (by Category)
553
+
554
+ | Category | Count | Examples |
555
+ |---|---|---|
556
+ | **Coding** | 5+ | Clean Code Checklist, Test Plan, E2E Suite |
557
+ | **Architecture** | 10+ | ADR, C4, Domain Model, Scalability Plan, Smart Contract |
558
+ | **Ops** | 5+ | Incident Postmortem, Deploy Config, Capacity Plan, FinOps |
559
+ | **Security** | 5+ | Threat Model, Safety Case, Ethical Impact |
560
+ | **Product** | 10+ | PRD, Spec, User Story Map, Visual Spec, Green Software |
561
+ | **Core** | 5+ | Plan, Tasks, Audit Log, Project State, Continuity |
562
+ | **Coordination** | 5+ | Agent Profile, Swarm Config, Handshake, Voting Log |
563
+ | **Brain** | 5+ | Active Inference Loop, Episodic Memory, OODA Trace |
564
+ | **Data** | 5+ | Data Pipeline, Database Schema, OWL Ontology |
565
+ | **Industry** | 5+ | FHIR Interop, IoT Telemetry, Telecom API, Global SDLC Audit |
566
+
567
+ Full catalog: `agents/templates/00-index.md` *(generated by `init.py`)*
568
+
569
+ ---
570
+
571
+ ## 🔌 Essential MCP Servers
572
+
573
+ | Server | Purpose |
574
+ |---|---|
575
+ | **Context-7** | Up-to-date SDK docs (prevents hallucination) |
576
+ | **Sequential Thinking** | Chain-of-thought reasoning |
577
+ | **GitHub MCP** | PR review, code search |
578
+ | **PostgreSQL MCP** | Live schema introspection |
579
+ | **Playwright MCP** | Browser automation / visual TDD |
580
+ | **Brave Search** | Authoritative web research |
581
+ | **Time Complexity** | Local Big-O static analysis via tree-sitter |
582
+ | **Excalidraw** | Programmatic Excalidraw diagram creation |
583
+
584
+ Config: `templates/core/MCP_CONFIG_TEMPLATE.json` · Full guide: [MCP_CONFIGURATIONS.md](docs/MCP_CONFIGURATIONS.md)
585
+
586
+ ---
587
+
588
+ ## 🔄 Self-Healing Loop
589
+
590
+ ```
591
+ Task → Knowledge gap? → research.skill → Execute → Verify
592
+ ↓ FAIL
593
+ self-heal.skill (max 5×)
594
+ ↓ STILL FAIL
595
+ Human escalation report
596
+ ```
597
+
598
+ ---
599
+
600
+ ## 📊 Memory Architecture
601
+
602
+ | Layer | Location | Purpose |
603
+ |---|---|---|
604
+ | **Project State** | `agents/memory/PROJECT_STATE.md` | Current SDLC phase |
605
+ | **Audit Log** | `agents/memory/AUDIT_LOG.md` | Append-only decision history |
606
+ | **Continuity** | `agents/memory/CONTINUITY.md` | Past failures (read every session) |
607
+ | **Episodic** | `agents/memory/episodic/` | Per-session decision logs |
608
+ | **Semantic** | `agents/memory/semantic/` | Crystallized project knowledge |
609
+
610
+ ---
611
+
612
+ ## 🚨 Troubleshooting
613
+
614
+ | Problem | Fix |
615
+ |---|---|
616
+ | Agent ignores AGENTS.md | Run `setup-context.sh` to create symlinks |
617
+ | Agent repeats mistakes | Check `CONTINUITY.md` — tell agent to read it |
618
+ | Tests pass immediately | False positive — test is broken, fix it first |
619
+ | Uses deprecated APIs | Activate Context-7 MCP |
620
+ | Session lost | `"Use session-resume skill to load all memory"` |
621
+ | Context too large | Use `context_cost: low` skills or activate Loki Mode |
622
+
623
+ ---
624
+
625
+ ## 📚 Guides by Stack
626
+
627
+ | Stack | Guide |
628
+ |---|---|
629
+ | JS/TS/Node.js | `guides/languages/js-ts-nodejs.md` |
630
+ | Node.js Advanced & TS | `guides/languages/nodejs-advanced.md` |
631
+ | Go | `guides/languages/go-lang.md` |
632
+ | PHP/Laravel | `guides/languages/php-laravel.md` |
633
+ | Python/FastAPI | `guides/languages/python-fastapi-ai.md` |
634
+ | SQL/NoSQL | `guides/data/sql-nosql.md` |
635
+ | Microservices | `guides/architecture/microservices.md` |
636
+ | Architecture | `guides/architecture/systems-architecture.md` |
637
+ | Testing | `guides/principles/testing-strategy.md` |
638
+ | Design Patterns | `guides/patterns/design-patterns.md` |
639
+ | Agentic AI | `guides/ai/ai-agentic.md` |
640
+ | Multi-Agent Systems | `guides/ai/multi-agent-systems.md` |
641
+ | Security/Compliance | `guides/ops/compliance-audit.md` |
642
+ | API Security | `guides/security/api-security.md` |
643
+ | Cryptography | `guides/security/cryptography-standards.md` |
644
+ | Data Protection | `guides/security/privacy-data-protection.md` |
645
+ | Secure Arch | `guides/security/secure-architecture.md` |
646
+ | Threat Modeling | `guides/security/threat-modeling.md` |
647
+ | DevOps/Environments | `guides/ops/dev-environments.md` |
648
+ | Developer Workflow | `guides/ops/dev-workflow.md` |
649
+ | Legacy/COBOL | `guides/principles/legacy-tech.md` |
650
+ | Future Tech 2030 | `guides/principles/future-tech.md` |
651
+ | C-Sharp / .NET | `guides/languages/c-sharp.md` |
652
+ | Self-Healing | `guides/ai/self-healing-summary.md` |
653
+ | Time Complexity | `guides/patterns/time-complexity-analysis.md` |
654
+ | Troubleshooting | `guides/ops/troubleshooting-guide.md` |
655
+ | Enterprise Migration | `guides/patterns/enterprise-migration-scenario.md` |
656
+
657
+ ---
658
+
659
+ ## 🛡️ Security & Guardrails
660
+
661
+ 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:
662
+
663
+ 1. **Skill Security**: Tool-specific protection (e.g., preventing command injection or sandbox escapes).
664
+ 2. **System Integration Security**: Safe external integration (e.g., verifying boundary enforcement or ensuring test coverage).
665
+ 3. **LLM/Agent Guardrails**: Protection from AI-specific failures (e.g., hallucinated metrics, confirmation bias, or prompt injection).
666
+
667
+ Agents are explicitly configured to **Fail-Closed**—they must wait for human approval rather than bypassing a guardrail.
668
+
669
+ ---
670
+
671
+
672
+ ## 🚀 GABBE CLI (Experimental)
673
+
674
+ GABBE has also an experimental helper, **Zero-Dependency CLI** (`gabbe`) for a "Hybrid Mode" (Markdown files and a SQLite database) and launching different commands. It is a work-in-progress and you can do without it, only with the rest of the kit.
675
+
676
+ ### Prerequisites
677
+ - Python 3.8+
678
+ - **LLM API Key**: For Brain/Route features, set `GABBE_API_KEY` (OpenAI-compatible).
679
+
680
+ **Environment Variables** (full reference in [CLI_REFERENCE.md](docs/CLI_REFERENCE.md)):
681
+
682
+ | Variable | Default | Description |
683
+ |---|---|---|
684
+ | `GABBE_API_URL` | `https://api.openai.com/v1/chat/completions` | OpenAI-compatible endpoint |
685
+ | `GABBE_API_KEY` | *(required for LLM features)* | Bearer token for the LLM API |
686
+ | `GABBE_API_MODEL` | `gpt-4o` | Model name sent in API requests |
687
+ | `GABBE_LLM_TEMPERATURE` | `0.7` | Sampling temperature (0.0–1.0) |
688
+ | `GABBE_LLM_TIMEOUT` | `30` | HTTP timeout in seconds |
689
+ | `GABBE_LLM_MAX_RETRIES` | `3` | Number of LLM retry attempts on transient errors |
690
+ | `GABBE_LLM_CACHE` | `false` | Opt-in: cache identical LLM calls locally (0 tokens on a hit; only for deterministic calls) |
691
+ | `GABBE_LOG_LEVEL` | `INFO` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
692
+ | `GABBE_ROUTE_THRESHOLD` | `50` | Complexity score above which prompts route REMOTE |
693
+ | `GABBE_MAX_COST_USD` | `5.0` | Maximum cost (USD) budget per run |
694
+ | `GABBE_MAX_TOKENS_PER_RUN` | `100000` | Maximum token limit per run |
695
+ | `GABBE_MAX_TOOL_CALLS_PER_RUN` | `50` | Maximum tool calls allowed per run |
696
+ | `GABBE_MAX_ITERATIONS` | `25` | Maximum active-inference iterations per run |
697
+ | `GABBE_MAX_WALL_TIME` | `300` | Maximum wall-clock time (seconds) per run |
698
+ | `GABBE_MAX_RECURSION_DEPTH` | `5` | Maximum agent recursion depth |
699
+ | `GABBE_MAX_RETRIES_PER_TOOL` | `3` | Maximum retries for a single tool call |
700
+ | `GABBE_POLICY_FILE` | `project/policies.yml` | Path to the YAML policy file |
701
+ | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli`, `file`, or `silent` |
702
+ | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout (seconds) for verify sub-commands |
703
+ | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
704
+
705
+ ### Installation
706
+ The CLI is a Python package.
707
+
708
+ ```bash
709
+ # 1. Install locally (Recommended)
710
+ pip install -e .
711
+
712
+ # 2. Verify installation
713
+ gabbe --help
714
+ ```
715
+
716
+ ### Core Commands
717
+ | Command | Description |
718
+ |---|---|
719
+ | `gabbe init` | Initialize the SQLite Database (Run this after `python scripts/init.py`). |
720
+ | `gabbe sync` | **Hybrid Sync**: Bidirectional sync between `project/TASKS.md` and SQLite DB. |
721
+ | `gabbe verify`| **Enforcer**: programmable integrity check (files, tests, lint). |
722
+ | `gabbe status`| **Dashboard**: Visualizes project phase and task progress. |
723
+ | `gabbe brain` | **Meta-Cognition**: Activates Active Inference loop or Evolutionary Prompt Optimization (Requires API Key). |
724
+ | `gabbe route` | **Cost Router**: Arbitrates between Local and Remote LLMs based on task complexity (Requires API Key). |
725
+ | `gabbe forecast`| **Strategic Forecast**: Projects remaining work cost and tokens based on historical run data. |
726
+ | `gabbe serve-mcp` | **MCP Gateway**: Zero-dependency JSON-RPC Model Context Protocol server for standalone agents to access tools safely. |
727
+ | `gabbe runs` | **Run History**: List recent agent runs with status, cost, and timestamps. |
728
+ | `gabbe audit <run-id>` | **Audit Trace**: Display structured span-level trace for a past run (`--format json\|table`). |
729
+ | `gabbe replay <run-id>` | **Deterministic Replay**: Replay a past run from its checkpoints (`--from-step N`). |
730
+ | `gabbe resume <run-id>` | **Escalation Resume**: Approve or reject pending escalations for a paused run. |
731
+ | `gabbe registry publish` | **Publish Skills**: Export the kit's skills as a publish-ready agentskills.io bundle (manifest + agent-card) for universal registries. |
732
+ | `gabbe registry add <source>` | **Import Skills**: Draw an external skill/bundle (path, `.tar.gz`, or URL) — validated + security-scanned + landed namespaced for review. |
733
+ | `gabbe setup` | **Install Wizard**: Run the interactive installer to wire the kit into your coding agents (see also `npx gabbe-kit init`). |
734
+
735
+ ### Platform Control Layer
736
+ 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`](docs/PLATFORM_CONTROLS.md).
737
+
738
+ ### Architecture
739
+ GABBE uses a **Hybrid Architecture** where agents and humans interact via Markdown, but the system of record is SQLite.
740
+
741
+ ```mermaid
742
+ graph TD
743
+ subgraph User["User (Legacy Flow)"]
744
+ Edit[Edit project/TASKS.md]
745
+ end
746
+
747
+ subgraph CLI["GABBE CLI (pip installed)"]
748
+ Sync[gabbe sync]
749
+ Verify[gabbe verify]
750
+ Brain[gabbe brain]
751
+ Router[gabbe route]
752
+ Forecast[gabbe forecast]
753
+ MCP[gabbe serve-mcp]
754
+ end
755
+
756
+ subgraph Storage["Hybrid Memory"]
757
+ MD[Markdown Files]
758
+ DB[(SQLite state.db)]
759
+ end
760
+
761
+ User -->|Manual Edits| MD
762
+ MD <-->|Bi-Directional| Sync
763
+ Sync <--> DB
764
+ Brain -->|Read/Write| DB
765
+ Verify -->|Check| MD
766
+ Verify -->|Check| DB
767
+ Forecast -->|Analyze| DB
768
+ MCP -->|Write Telemetry| DB
769
+ ```
770
+
771
+ ### How to Use
772
+
773
+ #### Setup
774
+ ```bash
775
+ # 1. Generate Context Configs
776
+ python3 scripts/init.py
777
+
778
+ # 2. Initialize Database
779
+ gabbe init
780
+ ```
781
+
782
+ #### Daily Workflow
783
+ ```bash
784
+ # Check status
785
+ gabbe status
786
+
787
+ # Sync tasks (manual edits)
788
+ gabbe sync
789
+
790
+ # Optimize a skill (Requires GABBE_API_KEY)
791
+ gabbe brain evolve --skill tdd-cycle
792
+ ```
793
+
794
+ #### Verification
795
+ ```bash
796
+ gabbe verify
797
+ ```
798
+
799
+ ---
800
+
801
+ ## License
802
+
803
+ GABBE is **dual-licensed** so the executable engine and the knowledge content
804
+ can each use the license appropriate to it:
805
+
806
+ | Part | License | Files |
807
+ | --- | --- | --- |
808
+ | **Code** | [Apache-2.0](LICENSE-CODE) | `gabbe/`, `scripts/`, `agents/scripts/` (all `.py`) |
809
+ | **Content** | [CC BY-SA 4.0](LICENSE) | `agents/` Markdown (skills, templates, guides, personas), `docs/` |
810
+
811
+ SPDX expression: `Apache-2.0 AND CC-BY-SA-4.0`. Apache-2.0 adds an explicit
812
+ patent grant and is OSI-approved, making the CLI safe to embed in downstream
813
+ (including proprietary) projects; the curated Markdown corpus stays
814
+ copyleft under CC BY-SA 4.0. Existing users lose no rights — this is purely
815
+ additive to the prior CC-BY-SA-4.0-only declaration.
816
+
817
+ [© 2026 Andrei Nicolae Besleaga.](https://creativecommons.org/licenses/by-sa/4.0/)