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/docs/SCHEMA.md ADDED
@@ -0,0 +1,164 @@
1
+ # GABBE Emitted-Format Schema
2
+
3
+ > **Audience:** maintainers & downstream consumers. **Scope:** the contract of every emitted client format and its evolution policy.
4
+
5
+ **Audience:** maintainers and downstream consumers who depend on the files
6
+ GABBE writes into a project. **Scope:** the public contract of every artifact
7
+ `scripts/init.py` (and `agents/scripts/compile_skills.py`) emit per AI client.
8
+
9
+ These emitted files — not the Python API — are GABBE's real public surface. A
10
+ project that ran `init.py` consumes these bytes directly, so they evolve under a
11
+ strict **additive-only** policy (see *Compatibility policy* below).
12
+
13
+ > This document describes the emitted format. Items marked **[0.9+]** are the
14
+ > agent-skills standard alignment shipped in 0.9 (Claude `<name>/SKILL.md`
15
+ > directories, Cursor agent-requested rules, `GEMINI.md`, root `AGENTS.md`,
16
+ > and the `gabbe-schema-version` key).
17
+
18
+ ## Source format: `agents/skills/**/*.skill.md`
19
+
20
+ Every skill is a Markdown file with YAML frontmatter:
21
+
22
+ ```yaml
23
+ ---
24
+ name: tdd-cycle # string, required. Human label; slugified for output paths.
25
+ description: Red-green-refactor… # string, required. Used for client-side discovery.
26
+ triggers: [tdd, test-first] # list[str], optional. Activation hints.
27
+ tags: [python, testing] # list[str], optional. Feeds the init.py tech-map.
28
+ context_cost: medium # enum(low|medium|high), optional.
29
+ ---
30
+ <markdown body — the skill instructions>
31
+ ```
32
+
33
+ `name` and `description` are required and validated by
34
+ `agents/scripts/validate_skills.py`. Additional keys are tolerated by all
35
+ consumers. **[0.9+]** the slug derived from `name` is sanitized to
36
+ `[a-z0-9-]+` (path separators, `..`, and control characters are rejected).
37
+
38
+ ## Emitted per-client formats
39
+
40
+ ### Cursor — `.cursor/rules/<slug>.mdc`
41
+
42
+ One rule file per skill. Frontmatter:
43
+
44
+ ```yaml
45
+ ---
46
+ description: <skill description> # string
47
+ globs: # see note
48
+ alwaysApply: false # boolean
49
+ ---
50
+ <skill body>
51
+ ```
52
+
53
+ - Rule type is **Agent-Requested**: `description` present, `alwaysApply: false`.
54
+ - **0.8.x** emitted `globs: *`, which makes the rule auto-attach to every file.
55
+ **[0.9+]** `globs` is omitted so Cursor selects the rule intelligently by
56
+ description (per docs.cursor.com/context/rules).
57
+ - `.cursorrules` (legacy, repo root) is also linked to `agents/AGENTS.md`.
58
+
59
+ ### Claude Code — `.claude/skills/<slug>/SKILL.md` **[0.9+]**
60
+
61
+ - **0.8.x** symlinked `.claude/skills` → `agents/skills` (a tree of
62
+ `<category>/<name>.skill.md` files). Claude Code discovers skills only as
63
+ `<name>/SKILL.md` **directories**, so 0.8.x skills did not load.
64
+ - **[0.9+]** GABBE emits a proper `.claude/skills/<slug>/SKILL.md` directory per
65
+ skill (the agentskills.io open standard, shared with Copilot). `.claude/CLAUDE.md`
66
+ remains linked to `agents/AGENTS.md`.
67
+
68
+ ### GitHub Copilot / VS Code — `.github/skills/<slug>/SKILL.md`
69
+
70
+ - `<slug>/SKILL.md` (the skill body with `name` + `description` frontmatter) —
71
+ conforms to the GitHub agent-skills standard.
72
+ - `<slug>/config.json` (non-standard GABBE metadata; ignored by Copilot):
73
+
74
+ ```json
75
+ { "name": "<slug>", "description": "<desc>", "version": "1.0.0",
76
+ "slashCommands": [ { "name": "<slug>", "description": "<desc>" } ] }
77
+ ```
78
+
79
+ - `.github/copilot-instructions.md` is linked to `agents/AGENTS.md`.
80
+
81
+ ### Gemini CLI — `.gemini/settings.json`
82
+
83
+ ```json
84
+ {
85
+ "agent_instructions_file": "<rel path to agents/AGENTS.md>",
86
+ "skills_directory": "<rel path to agents/skills>",
87
+ "notes": "Managed by init.py"
88
+ }
89
+ ```
90
+
91
+ - `agent_instructions_file`/`skills_directory` are GABBE metadata keys (not part
92
+ of the official Gemini settings schema; harmless). **[0.9+]** a `GEMINI.md`
93
+ context file pointing at `agents/AGENTS.md` is also emitted, which Gemini CLI
94
+ reads natively.
95
+
96
+ ### Codex — `.codex/AGENTS.md`
97
+
98
+ Symlink to `agents/AGENTS.md`. **[0.9+]** a root `AGENTS.md` is also emitted (the
99
+ agents.md open standard, read by Codex, Cursor, Gemini CLI, and Copilot coding
100
+ agent).
101
+
102
+ ### Other clients
103
+
104
+ `.windsurfrules`, `.clinerules`, `.devinrules` (→ `agents/AGENTS.md`),
105
+ `.windsurf/skills`, `.cline/skills`, `.devin/skills` (→ `agents/skills`), and
106
+ `.aider.conf.yml` (`read:` list) are linked/written best-effort.
107
+
108
+ ## Schema versioning — `gabbe-schema-version` **[0.9+]**
109
+
110
+ Every emitted frontmatter block carries `gabbe-schema-version: 1` (and
111
+ `.gemini/settings.json` carries `"gabbe-schema-version": 1`). Consumers that
112
+ ignore the key are unaffected; the key lets future tooling detect the emitted
113
+ schema generation.
114
+
115
+ ## Compatibility policy
116
+
117
+ The emitted contract evolves **additive-only**:
118
+
119
+ - **Allowed:** new emitted files, new optional frontmatter keys, new clients.
120
+ - **Not allowed without a major version bump:** removing an emitted file,
121
+ removing/retyping an existing key, or changing the bytes of an existing
122
+ artifact in a way a consumer could depend on.
123
+
124
+ This is enforced by `scripts/tests/test_golden_emitters.py` (per-platform
125
+ sha256 manifest, additive-only diff) and the gate runner
126
+ `scripts/gates/run_gates.sh` (gate 4). The 0.9 changes marked **[0.9+]** above
127
+ are additive: new directories/files alongside the existing ones, reviewed
128
+ against the golden baseline.
129
+
130
+ ---
131
+
132
+ ## Project policy config: `project/gabbe.config.json` **[0.9+]**
133
+
134
+ > **Direction:** this is an *input* GABBE reads (not an emitted artifact). It is
135
+ > optional and runtime-agnostic — the Markdown agent reads it directly, and the
136
+ > optional `gabbe` CLI surfaces it via `gabbe/config.py`.
137
+
138
+ A per-project policy file letting a team set autonomy, budgets, model tiers,
139
+ enabled MCPs, registries, and protected files **without** editing the kit. All
140
+ keys are optional; each falls back to a safe default. Unknown keys are ignored.
141
+
142
+ ```json
143
+ {
144
+ "autonomy": "hybrid",
145
+ "budgets": { "max_cost_usd": 5.0, "max_tokens_per_run": 100000 },
146
+ "model_tiers": { "cheap": "gpt-4o-mini", "default": "gpt-4o", "sota": "claude-opus-4-8" },
147
+ "enabled_mcps": ["context7", "filesystem"],
148
+ "registries": ["https://skills.sh", "google/skills"],
149
+ "protected_files": ["pyproject.toml", "package.json", "*.lock", "Dockerfile", ".github/**"]
150
+ }
151
+ ```
152
+
153
+ | Key | Type | Default | Meaning |
154
+ |---|---|---|---|
155
+ | `autonomy` | `"ask" \| "auto" \| "hybrid"` | `hybrid` | Autonomy posture. Env `GABBE_AUTONOMY` overrides this. |
156
+ | `budgets` | object | CLI defaults | Per-run cost/token ceilings (advisory to the Markdown agent; enforced by the CLI budget when used). |
157
+ | `model_tiers` | object | provider defaults | Named tiers for cheap/default/SOTA routing (`cost-benefit-router`, `persona-selector`). |
158
+ | `enabled_mcps` | string[] | `[]` | MCP servers the agent may assume are available. |
159
+ | `registries` | string[] | `[]` | Skill registries `update-scan`/`skills-registry` may publish to / import from. |
160
+ | `protected_files` | string[] (globs) | build/IaC/CI/manifests | Files never auto-edited outside the dependency-specific self-heal allowlist. |
161
+
162
+ **Precedence (autonomy):** environment `GABBE_AUTONOMY` > `gabbe.config.json` `autonomy` > default `hybrid`. Invalid values warn and fall back to `hybrid`.
163
+
164
+ **Compatibility:** new optional keys may be added over time (additive). Consumers must ignore unknown keys. `gabbe/config.py` exposes `GABBE_AUTONOMY` (str) and `GABBE_PROJECT_CONFIG` (dict) as additive module globals.
@@ -0,0 +1,144 @@
1
+ <!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
2
+ # GABBE v1.0 Release Checklist
3
+
4
+ A human-runnable release gate that mirrors the v1.0 acceptance matrix in
5
+ `GABBE-v1.0-MASTER-PLAN.md`. Tag `v1.0.0` only when **every** box below is
6
+ ticked on a clean checkout and in CI. No item may be waived.
7
+
8
+ Run all commands from the repository root. Each section maps to one acceptance
9
+ item; commands are shown in fenced blocks so they are not link-checked.
10
+
11
+ > **Honesty note.** Property-based / metamorphic tests and evals **sample** an
12
+ > input space and **raise confidence** — they do not prove correctness.
13
+ > LLM-as-judge is biased-but-useful and calibrated against human labels, never
14
+ > treated as ground truth. The AI-risk standards map documents **coverage, not
15
+ > certification**. These checks establish a verifiable readiness bar, not literal
16
+ > perfection.
17
+
18
+ ---
19
+
20
+ ## 1. Methodology layer valid & self-consistent
21
+
22
+ ```bash
23
+ python3 agents/scripts/validate_skills.py # frontmatter parses; required keys present
24
+ python3 agents/scripts/validate_links.py # zero broken [text](path) links, all files
25
+ python3 agents/scripts/validate_integrity.py # required dirs/structure intact
26
+ python3 agents/scripts/verify_triggers_and_mcps.py # triggers non-empty; referenced MCPs exist
27
+ python3 agents/scripts/verify_use_cases.py # every documented scenario resolves to real skills
28
+ python3 agents/scripts/validate_methodology_graph.py # lifecycle DAG + persona handoffs + memory state coherent
29
+ ```
30
+
31
+ - [ ] `validate_skills.py` exits 0
32
+ - [ ] `validate_links.py` exits 0 (zero broken links, all markdown files)
33
+ - [ ] `validate_integrity.py` exits 0
34
+ - [ ] `verify_triggers_and_mcps.py` exits 0 (triggers non-empty/non-placeholder; referenced MCPs exist)
35
+ - [ ] `verify_use_cases.py` exits 0 (every documented scenario resolves to real skills)
36
+ - [ ] `validate_methodology_graph.py` exits 0 (lifecycle state machine is a valid DAG with human-approval gates; persona handoffs resolve; memory state model coherent; skill shape valid)
37
+ - [ ] Manual cross-check: every `S00`–`S13` phase + every new gate (`S02.5`/`S04.5`/`S06.5`/`S07.5`) references an existing skill/template/persona, and every new skill/template/persona appears in its `00-index.md`
38
+
39
+ ## 2. Backward-compatibility gates green
40
+
41
+ ```bash
42
+ bash scripts/gates/run_gates.sh
43
+ ```
44
+
45
+ - [ ] Gate 1 `api-surface` green (no removed/changed public signatures — additions only)
46
+ - [ ] Gate 2 `cli-help` green (byte-equal; only `cli_help/verify.txt` regenerated for the additive `--chaos` flag, plus any documented additive carve-out for new `uninstall`/`update`/`doctor`/`eval` help)
47
+ - [ ] Gate 3 `config-schema` green (additive only)
48
+ - [ ] Gate 3b `db-schema` green (additive only)
49
+ - [ ] Gate 4 `emitter-vault` green (every prior client's output byte-compatible; new agents add new paths only)
50
+ - [ ] Gate 6 `cve-delta` green (no new CVEs)
51
+
52
+ ## 3. Python suite green (deterministic, per-commit)
53
+
54
+ ```bash
55
+ pip install -e ".[dev]"
56
+ pytest gabbe/tests/ scripts/tests/ -v -m "not slow and not live_llm and not mutation"
57
+ ruff check . && black --check . && mypy gabbe
58
+ ```
59
+
60
+ - [ ] `pytest -m "not slow and not live_llm and not mutation"` passes (includes `test_mcp_contract.py`, `test_brain_invariants.py`, `test_loki_shadow.py`, `test_autodetect.py`, `test_one_command_install.py`, and the assertions-only `eval_skills` subset)
61
+ - [ ] `ruff check .` clean
62
+ - [ ] `black --check .` clean
63
+ - [ ] `mypy gabbe` clean (`--strict` on core modules)
64
+
65
+ ## 4. Self-* capabilities each demonstrated (claim → proof)
66
+
67
+ ```bash
68
+ pytest gabbe/tests/test_brain_properties.py # self-evolving: gene generation increments; reward loop closes
69
+ pytest gabbe/tests/test_route_properties.py # self-adaptive: PII→LOCAL; complexity routing
70
+ pytest gabbe/tests/test_chaos_fault_injection.py # self-healing: escalation/hardstop after repeated failure
71
+ python3 agents/scripts/verify_use_cases.py # dynamic-load-or-ask scenario for dynamic-capability-loading.md
72
+ gabbe verify --chaos # all fault-injection self-checks PASS
73
+ ```
74
+
75
+ - [ ] Self-evolving demonstrated (brain property test: generation increments, reward closes the loop)
76
+ - [ ] Self-adaptive demonstrated (route property test: PII→LOCAL, complexity routing)
77
+ - [ ] Self-healing demonstrated (chaos fault-injection test: escalation/hardstop after repeated failure)
78
+ - [ ] Dynamic-load-or-ask scenario passes for `dynamic-capability-loading.md`
79
+ - [ ] `gabbe verify --chaos` → all fault-injection self-checks PASS
80
+
81
+ ## 5. Compatibility & emission proven (works standalone, every target agent)
82
+
83
+ ```bash
84
+ # For each supported client (claude, cursor, copilot, gemini, codex, + new additive ones):
85
+ python3 agents/scripts/compile_skills.py --platform <client> --skills-dir agents/skills --target-dir /tmp/gabbe-<client>
86
+ python3 scripts/init.py # (or: npx gabbe-kit init) — clean init succeeds end-to-end with new content
87
+ ```
88
+
89
+ - [ ] `compile_skills.py` emits successfully for every supported client (claude, cursor, copilot, gemini, codex, and each additive client)
90
+ - [ ] New skills / personas / templates appear in each client's emitted output
91
+ - [ ] Clean `python3 scripts/init.py` (or `npx gabbe-kit init`) succeeds end-to-end with the new content
92
+
93
+ ## 6. Release mechanics complete
94
+
95
+ - [ ] Version = `1.0.0` in `pyproject.toml`, `package.json`, and `gabbe/__init__.py`
96
+ - [ ] `CHANGELOG.md` has the v1.0.0 entry (dated 2026-06-17) as the top entry
97
+ - [ ] `README.md` and `llms.txt` refreshed (v1.0 line: cradle-to-grave ADLC, evals + guardrails, advanced testing, one-command multi-OS install with autodetect) with honest world-first framing preserved
98
+ - [ ] Full CI green (validate matrix py3.9–3.13 + lint + gates)
99
+
100
+ ## 7. Forward-adaptability proven
101
+
102
+ - [ ] `extension-protocol.md` walkthrough adds a throwaway sample skill/template/persona/MCP, and all validators + gates pass (proving new things can always be added additively); then the sample is reverted
103
+ - [ ] Confirms any future methodology can be absorbed without a breaking change
104
+
105
+ ## 8. Install / update / uninstall reversible & isolated (multi-OS)
106
+
107
+ ```bash
108
+ pytest scripts/tests/test_install_manifest.py scripts/tests/test_uninstall.py \
109
+ scripts/tests/test_install_isolation.py scripts/tests/test_remove_agents.py -v
110
+ ```
111
+
112
+ - [ ] Install-manifest, uninstall, isolation, and remove-agents tests pass
113
+ - [ ] Manual matrix (tmp dirs) for scope ∈ {project, custom-dir, global}: install → only target written (zero writes outside target except `--global`) → `update` (user/preserve files intact) → `uninstall --dry-run` (no change) → `uninstall` → target byte-identical to pre-install state, `.bak` restored
114
+ - [ ] Install verified from each channel (`npx gabbe-kit init` / `pipx install gabbe` / `curl -fsSL …/install.sh | sh` / `git clone` + `python3 scripts/init.py`)
115
+ - [ ] Unselected agents get zero files; `--remove-agents` removes only the named agent
116
+ - [ ] CI `install-matrix` green on {ubuntu, macos, windows} × {npx / pip|pipx / curl|sh | install.ps1}: install → `gabbe doctor` (detects OS/arch, runtimes, agents, scope; all checks PASS) → emit for every detected agent → `update` → `uninstall` → byte-identical restore
117
+
118
+ ## 9. Evals & standards-grounded guardrails proven (Track E)
119
+
120
+ ```bash
121
+ python3 agents/scripts/eval_skills.py # assertions-only subset (per-commit, green)
122
+ # nightly / opt-in:
123
+ GABBE_LIVE_LLM=1 python3 agents/scripts/eval_skills.py --live # scorecard within threshold of baseline (non-blocking)
124
+ ```
125
+
126
+ - [ ] `eval_skills.py` assertions-only subset green per-commit
127
+ - [ ] Nightly `--live` scorecard within threshold of the stored baseline (non-blocking; no prompt-drift regression on the seeded golden set)
128
+ - [ ] `agents/guides/security/ai-risk-standards-map.md` present and validated: **every OWASP LLM01–LLM10 row maps to ≥1 named GABBE skill/gate/persona**
129
+ - [ ] `prompt-injection-defense` + `output-validation` skills registered in `00-index.md` and reachable from `ai-safety-guardrails.skill.md`
130
+
131
+ ## 10. Published library — one-command install, autodetect, multi-OS, reversible (Track E8)
132
+
133
+ ```bash
134
+ pytest scripts/tests/test_autodetect.py scripts/tests/test_one_command_install.py -v
135
+ ```
136
+
137
+ - [ ] `test_autodetect.py` + `test_one_command_install.py` pass (each channel's single command lands the kit into a tmp target; autodetect populates `.gabbe/manifest.json`)
138
+ - [ ] `release-verify` installs the **published** package (npm / PyPI / raw URL) on the OS matrix and passes the same smoke checks (single-command install → `gabbe doctor` → emit → `update` → `uninstall` → byte-identical restore)
139
+ - [ ] Unknown / absent agents are skipped cleanly (never error)
140
+
141
+ ---
142
+
143
+ **Definition of done for v1.0:** items 1–10 all green on a clean checkout and in
144
+ CI. No item may be waived.
@@ -0,0 +1,283 @@
1
+ # GABBE Comprehensive Verification Guide
2
+
3
+ > **Audience:** maintainers verifying an install. **Scope:** how to validate the kit and run the validation scripts.
4
+
5
+ > **Important**: This guide consolidates all testing and verification processes for the GABBE Agentic R&D Engineering Framework into a single, comprehensive source of truth. Use this to explicitly verify the integrity of the framework and its CLI.
6
+
7
+ ---
8
+
9
+ ## 🏗️ 1. Environment & Setup
10
+
11
+ Before running tests or launching verifiers, ensure the project development environment is correctly bootstrapped.
12
+
13
+ ### Prerequisites:
14
+ - **Python:** versions 3.8 to 3.12 support the GABBE framework and test runners.
15
+ - **Node.js**: Expected by specific NPM-based tools or workflows, though Python is the framework root.
16
+
17
+ ### Installation:
18
+ ```bash
19
+ git clone https://github.com/andreibesleaga/GABBE.git
20
+ cd GABBE
21
+ python -m venv .venv
22
+ source .venv/bin/activate # For Windows: .venv\Scripts\activate
23
+ pip install -e ".[dev]"
24
+ ```
25
+
26
+ *Optionally*, establish environment secrets to verify API-driven paths (Required for executing the `gabbe brain`, `gabbe route`, and specific integration scenarios):
27
+ ```bash
28
+ cp .env.example .env
29
+ export GABBE_API_KEY="sk-..." # Add remote LLM keys for deep integration
30
+ ```
31
+
32
+ ---
33
+
34
+ ## 🧪 2. Core Python Unit & Integration Testing
35
+
36
+ The heart of the GABBE orchestration, database integration, memory access, and MCP translation occurs in the `gabbe/` module. The core tests target its routing (`route.py`), budget control (`budget.py`), orchestration logic (`brain.py`), and subprocess checking logic (`verify.py`).
37
+
38
+ **Run the Full Suite (570+ tests):**
39
+ ```bash
40
+ # Discovers all tests in gabbe/tests and scripts/tests
41
+ pytest
42
+ ```
43
+
44
+ **Run a specific test file:**
45
+ ```bash
46
+ pytest gabbe/tests/test_brain.py -v
47
+ pytest gabbe/tests/test_edge_cases.py -v
48
+ pytest scripts/tests/test_init.py -v
49
+ ```
50
+
51
+ ### 2.1 Test File Reference
52
+
53
+ #### `gabbe/tests/` — CLI & Core Module Tests
54
+
55
+ | File | Coverage |
56
+ |---|---|
57
+ | `test_brain.py` | `activate_brain` (empty tasks, LLM none, task stats), `evolve_prompts` (seed, multi-gen, LLM none), `run_healer` (all clear, missing files, DB unreachable) |
58
+ | `test_brain_integration.py` | Brain with `RunContext`, `HardStop`, `Budget`, escalation on LLM error, context passthrough |
59
+ | `test_budget.py` | `Budget.from_config()`, token/cost limits, `BudgetExceeded`, `remaining()` |
60
+ | `test_config.py` | Environment variable loading, path resolution |
61
+ | `test_context.py` | `RunContext` lifecycle, DB run records |
62
+ | `test_database.py` | Schema tables, schema version, unique constraint, row factory, idempotent `init_db` |
63
+ | `test_e2e.py` | Sync import/export, brain evolve, cost router, status dashboard, verify pass/fail, brain activate/heal |
64
+ | `test_e2e_workflow.py` | Full 14-step golden path workflow (init → sync → status → verify → route → brain → forecast → runs → audit → replay → resume → MCP); platform controls (budget, hardstop, policy, gateway, escalation, replay); MCP JSON-RPC protocol |
65
+ | `test_edge_cases.py` | **NEW v0.8.0** — See Section 2.2 |
66
+ | `test_escalation.py` | `EscalationHandler` modes (silent, file, interactive), `EscalationPaused` |
67
+ | `test_forecast.py` | `run_forecast` with history data, empty DB, cost projections |
68
+ | `test_gateway.py` | `ToolGateway` register/execute, policy enforcement |
69
+ | `test_hardstop.py` | `HardStop` max iterations, `should_wrap_up`, `MaxIterationsExceeded` |
70
+ | `test_llm.py` | `call_llm` with mocked API, timeout handling |
71
+ | `test_llm_backoff.py` | Exponential backoff on rate limits |
72
+ | `test_llm_retries.py` | Retry logic on transient API errors |
73
+ | `test_main.py` | CLI dispatch: `--version`, `init`, `db`, `sync`, `verify`, `status`, `route`, `brain activate/evolve/heal`; error handling (EnvironmentError→exit 1, KeyboardInterrupt→exit 130, generic→exit 1) |
74
+ | `test_mcp_server.py` | MCP JSON-RPC: auth token rejection, command allowlist block/permit, empty command |
75
+ | `test_mva_core.py` | MVA platform core behaviour |
76
+ | `test_policy.py` | `ToolAllowlistPolicy`: allow, deny, deny overrides allow |
77
+ | `test_replay.py` | `CheckpointStore`, `ReplayRunner`, `replay --from-step` |
78
+ | `test_route.py` | Simple→LOCAL, complex→REMOTE, threshold, env var override |
79
+ | `test_status.py` | Dashboard sections, empty DB, task counts, 100% progress, progress bar overflow, phase display |
80
+ | `test_sync.py` | `parse_markdown_tasks` (all status variants), `generate_markdown_tasks`, roundtrip, timestamp parsing, `sync_tasks` (import/export/empty/atomic), `_atomic_write` cleanup |
81
+ | `test_sync_fallback.py` | Preamble preservation without markers, fallback append when no task list found |
82
+ | `test_sync_markers.py` | `_generate_task_lines`, legacy parse, marker-bounded parse, reads only marked section |
83
+ | `test_verify.py` | `run_verification` pass/fail, `parse_agents_config`, `run_command` uses shlex not shell |
84
+
85
+ #### `scripts/tests/` — Installer Tests
86
+
87
+ | File | Coverage |
88
+ |---|---|
89
+ | `test_init.py` | Local/global/custom install (first-time, update, reinstallation), legacy modernization, data science AI, other language, missing source dir, same source/target dir |
90
+ | `test_dynamic_setup.py` | Dynamic tech map building, platform-specific skill setup, Cursor rules generation |
91
+
92
+ ---
93
+
94
+ ### 2.2 Edge Case Tests (`gabbe/tests/test_edge_cases.py`) — NEW in v0.8.0
95
+
96
+ Run all edge case tests:
97
+ ```bash
98
+ pytest gabbe/tests/test_edge_cases.py -v
99
+ ```
100
+
101
+ **CLI dispatch — commands not previously unit-tested:**
102
+ ```bash
103
+ pytest gabbe/tests/test_edge_cases.py -v -k "runs or forecast or audit or replay or resume"
104
+ ```
105
+ - `test_runs_command_empty` — `gabbe runs` with no records → "No runs found"
106
+ - `test_runs_command_with_data` — `gabbe runs` lists run ID, command, status
107
+ - `test_runs_command_status_filter` — `gabbe runs --status completed` filters correctly
108
+ - `test_forecast_command_dispatches` — `gabbe forecast` dispatches to `run_forecast`
109
+ - `test_forecast_empty_db_no_crash` — no crash on empty DB
110
+ - `test_audit_command_no_spans` — "No audit spans found" for unknown run ID
111
+ - `test_audit_command_json_format` — `--format json` outputs valid JSON list
112
+ - `test_replay_command_empty` — "No checkpoints to replay" for unknown run
113
+ - `test_resume_command_no_escalations` — "No pending escalations" for unknown run
114
+
115
+ **Memory & Database lifecycle:**
116
+ ```bash
117
+ pytest gabbe/tests/test_edge_cases.py -v -k "memory"
118
+ ```
119
+ - `test_memory_directory_created_on_init` — all schema v3 tables present: `runs`, `audit_spans`, `budget_snapshots`, `checkpoints`, `pending_escalations`, `forecast_snapshots`, `pricing_registry`
120
+ - `test_memory_persists_across_sync_cycles` — import from TASKS.md → verified in DB with correct statuses
121
+
122
+ **Sync edge cases:**
123
+ ```bash
124
+ pytest gabbe/tests/test_edge_cases.py -v -k "sync"
125
+ ```
126
+ - `test_sync_unicode_task_titles` — 🚀, ✅, 中文 characters survive sync roundtrip
127
+ - `test_sync_task_with_special_markdown_chars` — backticks and `[brackets]` survive
128
+ - `test_sync_duplicate_titles_handled` — duplicate task titles don't cause a crash
129
+
130
+ **Brain mode stress:**
131
+ ```bash
132
+ pytest gabbe/tests/test_edge_cases.py -v -k "evolve or heal"
133
+ ```
134
+ - `test_evolve_multi_generation` — 5 successive evolve calls with `success_rate` increments produce ≥6 generations (gen 0 seed + gens 1–5)
135
+ - `test_brain_heal_one_file_missing` — partial file existence: present files shown, missing files flagged, DB still reachable
136
+
137
+ **Status & platform:**
138
+ ```bash
139
+ pytest gabbe/tests/test_edge_cases.py -v -k "status or mcp or unknown"
140
+ ```
141
+ - `test_status_large_mixed_workload` — 100 tasks (50 done/30 todo/20 in-progress) → 50% shown without crash
142
+ - `test_serve_mcp_importable` — `mcp_server.serve` function is callable
143
+ - `test_unknown_command_prints_help` — unknown CLI command → argparse exit code 2
144
+
145
+ ---
146
+
147
+ ## 📁 3. GABBE Agents/Content Integrity Scripts
148
+
149
+ Because GABBE relies heavily on markdown context structures (`/agents/skills`, `/agents/templates`, `/agents/guides`), syntax errors or broken internal paths can critically affect agent behavior.
150
+
151
+ A series of purpose-built Python compilation scripts ensure that your modifications conform precisely to the framework rules. All these scripts are stored in the `agents/scripts/` folder.
152
+
153
+ **Check Structural Integrity:**
154
+ ```bash
155
+ # Checks if skills, templates, guides are valid and that `agents/AGENTS.md` matches `AGENTS_TEMPLATE.md` structures.
156
+ python3 agents/scripts/validate_integrity.py
157
+ ```
158
+
159
+ **Verify Internal Links & Logic Chains:**
160
+ ```bash
161
+ # Asserts that [links](myfile.md) all point to valid files. Critical to prevent autonomous agents from hallucinating paths.
162
+ python3 agents/scripts/validate_links.py
163
+
164
+ # Verifies that skills match the specific schemas and headers expected array mapping
165
+ python3 agents/scripts/validate_skills.py
166
+
167
+ # Maps use cases end-to-end to ensure personas properly bridge triggers across skills -> templates
168
+ python3 agents/scripts/verify_use_cases.py
169
+
170
+ # Traverses Prompts + MCP configs to guarantee external calls fit configured APIs
171
+ python3 agents/scripts/verify_triggers_and_mcps.py
172
+
173
+ # Verifies all skills are referenced in docs, all personas exist and are documented
174
+ python3 agents/scripts/check_skills_docs.py
175
+ python3 agents/scripts/comprehensive_checker.py
176
+ ```
177
+
178
+ **E2E Init Flow Simulation:**
179
+ ```bash
180
+ # Runs 12 permutations: global/local/custom × install/update flows
181
+ python3 agents/scripts/verify_e2e_init_flows.py
182
+
183
+ # Tests symlink creation, tech map building, skill setup for each platform
184
+ python3 agents/scripts/verify_setup_simulation.py
185
+ ```
186
+
187
+ **Run Everything in One Pass:**
188
+ ```bash
189
+ # Umbrella runner aggregating logs across all structural checkers
190
+ bash agents/scripts/setup-context.sh
191
+ ```
192
+
193
+ ---
194
+
195
+ ## 🖥 4. CLI Architecture Testing (`gabbe verify`)
196
+
197
+ The CLI Enforcer serves as a powerful programmable integrity checking tool when building external apps. We must confirm the standalone GABBE CLI commands operate identically within an SDLC checkpoint.
198
+
199
+ **Mock a Workspace Sync & Check Workflow:**
200
+
201
+ ```bash
202
+ # 1. Initialize SQLite memory (Required once per new project map)
203
+ gabbe init
204
+
205
+ # 2. Sync CLI Tasks with your markdown files
206
+ gabbe sync
207
+
208
+ # 3. Test the verify loop.
209
+ # Note: By design, `gabbe verify` will initially FAIL on fresh projects to prevent unauthorized deployment,
210
+ # primarily throwing execution errors until you fill in [PLACEHOLDER] variables inside `project/TASKS.md` or `AGENTS.md`.
211
+ gabbe verify
212
+ ```
213
+ *Expected Behavior:* If `gabbe verify` produces "Verification FAILED" because of `[PLACEHOLDER:]` elements (like `[PLACEHOLDER: pnpm test]`), the verifier is correctly identifying missing human instruction mapping.
214
+
215
+ **Test Additional CLI Commands:**
216
+ ```bash
217
+ # List agent runs (optionally filter by status)
218
+ gabbe runs
219
+ gabbe runs --status completed
220
+
221
+ # Inspect structured audit trace for a run
222
+ gabbe audit <run-id>
223
+ gabbe audit <run-id> --format json
224
+
225
+ # Replay a past run from checkpoints
226
+ gabbe replay <run-id>
227
+ gabbe replay <run-id> --from-step 2
228
+
229
+ # Resume a paused/escalated run
230
+ gabbe resume <run-id>
231
+ ```
232
+
233
+ ---
234
+
235
+ ## 🤖 5. Simulating Agent Workflows
236
+
237
+ The ultimate verification requires simulating the system acting as an intelligent agent running either Loki or Brain orchestration.
238
+
239
+ **Verify Cost Forecaster (CLI):**
240
+ ```bash
241
+ # Ensures history parsing works
242
+ gabbe forecast
243
+ ```
244
+
245
+ **Verify Subprocess Limits:**
246
+ ```bash
247
+ # This forces testing the CLI execution timeouts limit on `gabbe_subprocess_timeout` rules
248
+ export GABBE_SUBPROCESS_TIMEOUT=5
249
+ gabbe verify
250
+ ```
251
+
252
+ **Verify Model Context Protocol (MCP) Bind:**
253
+ ```bash
254
+ # Launches the JSON-RPC local server. It should start listening via STDIN/STDOUT.
255
+ gabbe serve-mcp
256
+ # Cancel using CTRL+C
257
+ ```
258
+
259
+ **Run The Evolutionary Pipeline (EPO):**
260
+ ```bash
261
+ # Note: An active GABBE_API_KEY must be exported in your terminal context to test evolution.
262
+ # Simulates the neural rewiring of a specific skill prompt based on historic error patterns.
263
+ gabbe brain evolve --skill tdd-cycle
264
+ ```
265
+
266
+ ---
267
+
268
+ ## ✅ 6. Verification Checklist
269
+
270
+ Upon passing all elements in this guide, the framework is confirmed 100% operationally verified:
271
+
272
+ | Check | Command | Expected Result |
273
+ |---|---|---|
274
+ | Full test suite | `pytest` | All pass, 0 failures (570+ tests) |
275
+ | Structural integrity | `python3 agents/scripts/validate_integrity.py` | Project integrity check passed |
276
+ | Link validation | `python3 agents/scripts/validate_links.py` | All links valid |
277
+ | Skills validation | `python3 agents/scripts/validate_skills.py` | All 214 skills passed |
278
+ | Use cases | `python3 agents/scripts/verify_use_cases.py` | All 534 assertions PASSED |
279
+ | Triggers & MCPs | `python3 agents/scripts/verify_triggers_and_mcps.py` | All triggers/skills/MCP bindings chained correctly |
280
+ | Skills doc coverage | `python3 agents/scripts/check_skills_docs.py` | 214/214 in index |
281
+ | Personas & quality | `python3 agents/scripts/comprehensive_checker.py` | No corrupted headers, no outdated CLI versions |
282
+ | Setup simulation | `python3 agents/scripts/verify_setup_simulation.py` | Symlink fallback works |
283
+ | E2E init flows | `python3 agents/scripts/verify_e2e_init_flows.py` | All 12 permutations PASSED |
@@ -0,0 +1,26 @@
1
+ # 1. Record architecture decisions
2
+
3
+ - Status: Accepted
4
+ - Date: 2026-06-10
5
+
6
+ ## Context
7
+
8
+ GABBE has accumulated significant architectural decisions (the Universal Skill
9
+ Compiler, the dual runtime modes, the platform-control layer) that are currently
10
+ only discoverable by reading code and long-form docs. New contributors and future
11
+ maintainers need a durable, append-only record of *why* the system is shaped the
12
+ way it is.
13
+
14
+ ## Decision
15
+
16
+ We will use Architecture Decision Records (ADRs), as described by Michael Nygard,
17
+ stored in `docs/adr/` and numbered sequentially. Each ADR captures one decision
18
+ with its context, the decision itself, and consequences. ADRs are immutable once
19
+ accepted; a superseding decision gets a new ADR that references the old one.
20
+
21
+ ## Consequences
22
+
23
+ - Decisions are reviewable in pull requests alongside the code that implements them.
24
+ - The record is append-only; we do not edit accepted ADRs except to mark them
25
+ superseded.
26
+ - Lightweight enough that proposing an ADR is not a barrier to contribution.
@@ -0,0 +1,27 @@
1
+ # 2. Brain Mode uses an Active-Inference control loop
2
+
3
+ - Status: Accepted
4
+ - Date: 2026-06-10
5
+
6
+ ## Context
7
+
8
+ GABBE's "Brain Mode" needs a principled way to decide, at each step, whether to
9
+ act locally (cheap heuristic / local model) or escalate to a remote SOTA model,
10
+ and how to learn from past project outcomes. A purely reactive prompt-chain does
11
+ not capture cost/benefit trade-offs or episodic memory.
12
+
13
+ ## Decision
14
+
15
+ Brain Mode (`gabbe/brain.py`) implements an Active-Inference / OODA control loop:
16
+ Observe (read PROJECT_STATE, audit log, recent outputs) → Orient → Decide (route
17
+ local vs remote via a cost-benefit router) → Act, with evolutionary prompt
18
+ optimization ("genes" persisted in SQLite) and episodic memory recall. This is an
19
+ **experimental** runtime: it is documented as such and gated behind explicit
20
+ `gabbe brain` subcommands, never on by default.
21
+
22
+ ## Consequences
23
+
24
+ - The cost router and budget/hardstop controls are first-class, not bolt-ons.
25
+ - Because it is experimental, claims in the README are marked Experimental and
26
+ link to reproducible examples rather than implying production guarantees.
27
+ - The loop is deterministic enough to be replayed (`gabbe replay`) for audit.