gabbe-kit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (502) hide show
  1. package/LICENSE +25 -0
  2. package/LICENSE-CODE +202 -0
  3. package/README.md +817 -0
  4. package/agents/AGENTS.md +542 -0
  5. package/agents/CONSTITUTION.md +188 -0
  6. package/agents/guides/00-index.md +142 -0
  7. package/agents/guides/ai/a2ui-protocols.md +71 -0
  8. package/agents/guides/ai/actor-agent-frameworks.md +82 -0
  9. package/agents/guides/ai/agent-communication.md +146 -0
  10. package/agents/guides/ai/agent-identity-trust.md +69 -0
  11. package/agents/guides/ai/agent-only-cognition.md +73 -0
  12. package/agents/guides/ai/agent-only-swarms.md +70 -0
  13. package/agents/guides/ai/agent-operating-ergonomics.md +52 -0
  14. package/agents/guides/ai/agent-ui.md +106 -0
  15. package/agents/guides/ai/ai-agentic.md +309 -0
  16. package/agents/guides/ai/beyond-llms.md +60 -0
  17. package/agents/guides/ai/dynamic-capability-loading.md +121 -0
  18. package/agents/guides/ai/gabbe-innovations.md +111 -0
  19. package/agents/guides/ai/model-customization-decisions.md +78 -0
  20. package/agents/guides/ai/multi-agent-systems.md +85 -0
  21. package/agents/guides/ai/self-evolving-skills.md +137 -0
  22. package/agents/guides/ai/self-healing-summary.md +21 -0
  23. package/agents/guides/ai/visual-mcp-integration.md +106 -0
  24. package/agents/guides/architecture/api-standards.md +61 -0
  25. package/agents/guides/architecture/blockchain-dlt.md +36 -0
  26. package/agents/guides/architecture/critical-systems-arch.md +66 -0
  27. package/agents/guides/architecture/event-driven-architecture.md +39 -0
  28. package/agents/guides/architecture/microservices.md +292 -0
  29. package/agents/guides/architecture/monolith.md +303 -0
  30. package/agents/guides/architecture/orchestration.md +75 -0
  31. package/agents/guides/architecture/system-qualities.md +51 -0
  32. package/agents/guides/architecture/system-scalability.md +47 -0
  33. package/agents/guides/architecture/systems-architecture.md +506 -0
  34. package/agents/guides/data/semantic-web.md +23 -0
  35. package/agents/guides/data/sql-nosql.md +305 -0
  36. package/agents/guides/industry/engineering-standards.md +36 -0
  37. package/agents/guides/industry/global-standards.md +24 -0
  38. package/agents/guides/industry/healthcare-fhir.md +33 -0
  39. package/agents/guides/industry/industrial-iot.md +33 -0
  40. package/agents/guides/industry/telecom-networks.md +34 -0
  41. package/agents/guides/languages/c-sharp.md +66 -0
  42. package/agents/guides/languages/go-lang.md +251 -0
  43. package/agents/guides/languages/java.md +73 -0
  44. package/agents/guides/languages/js-ts-nodejs.md +361 -0
  45. package/agents/guides/languages/nodejs-advanced.md +56 -0
  46. package/agents/guides/languages/php-laravel.md +376 -0
  47. package/agents/guides/languages/python-fastapi-ai.md +257 -0
  48. package/agents/guides/languages/rust.md +73 -0
  49. package/agents/guides/ops/compliance-audit.md +177 -0
  50. package/agents/guides/ops/cost-optimization.md +57 -0
  51. package/agents/guides/ops/dev-environments.md +67 -0
  52. package/agents/guides/ops/dev-workflow.md +44 -0
  53. package/agents/guides/ops/gabbe-cli-workflows.md +252 -0
  54. package/agents/guides/ops/production-health.md +62 -0
  55. package/agents/guides/ops/troubleshooting-guide.md +69 -0
  56. package/agents/guides/patterns/agentic-design-patterns.md +308 -0
  57. package/agents/guides/patterns/agentic-patterns.md +43 -0
  58. package/agents/guides/patterns/ai-native-scenarios.md +71 -0
  59. package/agents/guides/patterns/autonomous-swarm-patterns.md +42 -0
  60. package/agents/guides/patterns/design-patterns.md +68 -0
  61. package/agents/guides/patterns/enterprise-migration-scenario.md +58 -0
  62. package/agents/guides/patterns/enterprise-patterns.md +56 -0
  63. package/agents/guides/patterns/software-design-patterns.md +106 -0
  64. package/agents/guides/patterns/time-complexity-analysis.md +116 -0
  65. package/agents/guides/planning/product-requirements.md +407 -0
  66. package/agents/guides/planning/strategic-analysis.md +98 -0
  67. package/agents/guides/planning/visual-product-specs.md +162 -0
  68. package/agents/guides/principles/clean-code-standards.md +51 -0
  69. package/agents/guides/principles/computing-foundations.md +87 -0
  70. package/agents/guides/principles/diagramming-standards.md +568 -0
  71. package/agents/guides/principles/evaluation-strategy.md +103 -0
  72. package/agents/guides/principles/future-tech.md +35 -0
  73. package/agents/guides/principles/human-agent-collaboration.md +54 -0
  74. package/agents/guides/principles/legacy-tech.md +61 -0
  75. package/agents/guides/principles/mathematical-foundations.md +103 -0
  76. package/agents/guides/principles/modeling-methods.md +97 -0
  77. package/agents/guides/principles/no-code-integration.md +84 -0
  78. package/agents/guides/principles/testing-strategy.md +97 -0
  79. package/agents/guides/principles/visual-design-system.md +44 -0
  80. package/agents/guides/processes/RARV_CYCLE.md +262 -0
  81. package/agents/guides/processes/extension-protocol.md +183 -0
  82. package/agents/guides/processes/full-system-lifecycle.md +47 -0
  83. package/agents/guides/processes/knowledge-integration.md +82 -0
  84. package/agents/guides/processes/loki-sdlc-phases.md +446 -0
  85. package/agents/guides/product/green-software.md +38 -0
  86. package/agents/guides/product/sustainability-checks.md +29 -0
  87. package/agents/guides/security/ai-risk-standards-map.md +98 -0
  88. package/agents/guides/security/api-security.md +51 -0
  89. package/agents/guides/security/cryptography-standards.md +38 -0
  90. package/agents/guides/security/privacy-data-protection.md +41 -0
  91. package/agents/guides/security/secure-architecture.md +43 -0
  92. package/agents/guides/security/threat-modeling.md +46 -0
  93. package/agents/memory/AUDIT_LOG.md +48 -0
  94. package/agents/memory/CONTINUITY.md +49 -0
  95. package/agents/memory/PROJECT_STATE.md +134 -0
  96. package/agents/memory/RESUME_POINTER.md +15 -0
  97. package/agents/memory/episodic/DECISION_LOG_TEMPLATE.md +104 -0
  98. package/agents/memory/semantic/PROJECT_KNOWLEDGE_TEMPLATE.md +194 -0
  99. package/agents/memory/semantic/VECTOR_DB_CONFIG_TEMPLATE.json +46 -0
  100. package/agents/personas/00-index.md +148 -0
  101. package/agents/personas/biz-compliance.md +112 -0
  102. package/agents/personas/biz-legal.md +131 -0
  103. package/agents/personas/eng-api.md +110 -0
  104. package/agents/personas/eng-backend.md +113 -0
  105. package/agents/personas/eng-data.md +50 -0
  106. package/agents/personas/eng-database.md +95 -0
  107. package/agents/personas/eng-frontend.md +75 -0
  108. package/agents/personas/eng-infra.md +105 -0
  109. package/agents/personas/eng-messaging.md +50 -0
  110. package/agents/personas/eng-ml.md +50 -0
  111. package/agents/personas/eng-mobile.md +75 -0
  112. package/agents/personas/eng-perf.md +90 -0
  113. package/agents/personas/eng-qa.md +125 -0
  114. package/agents/personas/eng-tooling.md +49 -0
  115. package/agents/personas/ops-compliance.md +109 -0
  116. package/agents/personas/ops-cost.md +92 -0
  117. package/agents/personas/ops-devops.md +85 -0
  118. package/agents/personas/ops-incident.md +123 -0
  119. package/agents/personas/ops-monitor.md +89 -0
  120. package/agents/personas/ops-release.md +91 -0
  121. package/agents/personas/ops-security.md +104 -0
  122. package/agents/personas/ops-sre.md +85 -0
  123. package/agents/personas/orch-coordinator.md +140 -0
  124. package/agents/personas/orch-judge.md +135 -0
  125. package/agents/personas/orch-planner.md +114 -0
  126. package/agents/personas/orch-researcher.md +165 -0
  127. package/agents/personas/prod-architect.md +110 -0
  128. package/agents/personas/prod-design.md +112 -0
  129. package/agents/personas/prod-ethicist.md +50 -0
  130. package/agents/personas/prod-integration.md +120 -0
  131. package/agents/personas/prod-pm.md +115 -0
  132. package/agents/personas/prod-product-ops.md +128 -0
  133. package/agents/personas/prod-research.md +49 -0
  134. package/agents/personas/prod-safety-engineer.md +28 -0
  135. package/agents/personas/prod-tech-lead.md +119 -0
  136. package/agents/personas/ui-design.md +81 -0
  137. package/agents/scripts/check_skills_docs.py +120 -0
  138. package/agents/scripts/compile_skills.py +284 -0
  139. package/agents/scripts/comprehensive_checker.py +187 -0
  140. package/agents/scripts/dump-context.sh +37 -0
  141. package/agents/scripts/eval_skills.py +268 -0
  142. package/agents/scripts/preflight_summary.sh +80 -0
  143. package/agents/scripts/report_duplicates.py +125 -0
  144. package/agents/scripts/setup-context.ps1 +250 -0
  145. package/agents/scripts/setup-context.sh +398 -0
  146. package/agents/scripts/state_export.sh +84 -0
  147. package/agents/scripts/state_import.sh +99 -0
  148. package/agents/scripts/validate_integrity.py +98 -0
  149. package/agents/scripts/validate_links.py +96 -0
  150. package/agents/scripts/validate_methodology_graph.py +194 -0
  151. package/agents/scripts/validate_skills.py +81 -0
  152. package/agents/scripts/verify_e2e_init_flows.py +246 -0
  153. package/agents/scripts/verify_setup_simulation.py +104 -0
  154. package/agents/scripts/verify_triggers_and_mcps.py +159 -0
  155. package/agents/scripts/verify_use_cases.py +498 -0
  156. package/agents/skills/00-index.md +322 -0
  157. package/agents/skills/ai/a2ui-protocols.skill.md +31 -0
  158. package/agents/skills/ai/actor-agent-frameworks.skill.md +31 -0
  159. package/agents/skills/ai/agent-communication.skill.md +36 -0
  160. package/agents/skills/ai/agent-ui.skill.md +31 -0
  161. package/agents/skills/ai/autonomous-swarm-patterns.skill.md +31 -0
  162. package/agents/skills/ai/beyond-llms.skill.md +31 -0
  163. package/agents/skills/ai/context-engineering.skill.md +79 -0
  164. package/agents/skills/ai/llm-as-judge.skill.md +97 -0
  165. package/agents/skills/ai/multi-agent-systems.skill.md +31 -0
  166. package/agents/skills/ai/rag-evaluation.skill.md +93 -0
  167. package/agents/skills/ai/reasoning-patterns.skill.md +125 -0
  168. package/agents/skills/architecture/adaptive-architecture.skill.md +51 -0
  169. package/agents/skills/architecture/api-design.skill.md +92 -0
  170. package/agents/skills/architecture/api-standards.skill.md +31 -0
  171. package/agents/skills/architecture/arch-debt.skill.md +180 -0
  172. package/agents/skills/architecture/arch-design.skill.md +304 -0
  173. package/agents/skills/architecture/arch-patterns.skill.md +52 -0
  174. package/agents/skills/architecture/arch-review.skill.md +326 -0
  175. package/agents/skills/architecture/architecture-governance.skill.md +62 -0
  176. package/agents/skills/architecture/attribute-driven-design.skill.md +108 -0
  177. package/agents/skills/architecture/blockchain-dlt.skill.md +28 -0
  178. package/agents/skills/architecture/compatibility-design.skill.md +51 -0
  179. package/agents/skills/architecture/critical-systems-arch.skill.md +31 -0
  180. package/agents/skills/architecture/design-patterns.skill.md +59 -0
  181. package/agents/skills/architecture/diagramming.skill.md +380 -0
  182. package/agents/skills/architecture/domain-model.skill.md +294 -0
  183. package/agents/skills/architecture/enterprise-migration-scenario.skill.md +31 -0
  184. package/agents/skills/architecture/enterprise-patterns.skill.md +31 -0
  185. package/agents/skills/architecture/error-handling-strategy.skill.md +58 -0
  186. package/agents/skills/architecture/event-driven-architecture.skill.md +31 -0
  187. package/agents/skills/architecture/event-governance.skill.md +55 -0
  188. package/agents/skills/architecture/fitness-functions.skill.md +111 -0
  189. package/agents/skills/architecture/graphql-schema.skill.md +64 -0
  190. package/agents/skills/architecture/legacy-modernization.skill.md +51 -0
  191. package/agents/skills/architecture/microservices.skill.md +31 -0
  192. package/agents/skills/architecture/middleware-design.skill.md +59 -0
  193. package/agents/skills/architecture/monolith.skill.md +31 -0
  194. package/agents/skills/architecture/realtime-comm.skill.md +52 -0
  195. package/agents/skills/architecture/state-management.skill.md +72 -0
  196. package/agents/skills/architecture/system-qualities.skill.md +31 -0
  197. package/agents/skills/architecture/system-scalability.skill.md +31 -0
  198. package/agents/skills/architecture/systems-architecture.skill.md +31 -0
  199. package/agents/skills/architecture/visual-whiteboarding.skill.md +33 -0
  200. package/agents/skills/brain/README.md +70 -0
  201. package/agents/skills/brain/active-inference.skill.md +74 -0
  202. package/agents/skills/brain/brain-mode.skill.md +125 -0
  203. package/agents/skills/brain/cognitive-architectures.skill.md +53 -0
  204. package/agents/skills/brain/cognitive-testing.skill.md +62 -0
  205. package/agents/skills/brain/consciousness-loop.skill.md +68 -0
  206. package/agents/skills/brain/cost-benefit-router.skill.md +89 -0
  207. package/agents/skills/brain/episodic-consolidation.skill.md +43 -0
  208. package/agents/skills/brain/epistemology-knowledge.skill.md +54 -0
  209. package/agents/skills/brain/global-workspace.skill.md +77 -0
  210. package/agents/skills/brain/learning-adaptation.skill.md +68 -0
  211. package/agents/skills/brain/loki-mode.skill.md +267 -0
  212. package/agents/skills/brain/neuroscience-foundations.skill.md +52 -0
  213. package/agents/skills/brain/scripts/active_inference_loop.py +92 -0
  214. package/agents/skills/brain/scripts/cognition_test.py +80 -0
  215. package/agents/skills/brain/scripts/global_workspace.py +104 -0
  216. package/agents/skills/brain/self-improvement.skill.md +80 -0
  217. package/agents/skills/brain/sensory-motor.skill.md +61 -0
  218. package/agents/skills/brain/sequential-thinking.skill.md +48 -0
  219. package/agents/skills/brain/working-memory.skill.md +47 -0
  220. package/agents/skills/coding/agent-trajectory-eval.skill.md +92 -0
  221. package/agents/skills/coding/artisan-commands.skill.md +52 -0
  222. package/agents/skills/coding/browser-tdd.skill.md +131 -0
  223. package/agents/skills/coding/chaos-fault-injection.skill.md +116 -0
  224. package/agents/skills/coding/ci-autofix.skill.md +53 -0
  225. package/agents/skills/coding/clean-coder.skill.md +58 -0
  226. package/agents/skills/coding/code-review.skill.md +100 -0
  227. package/agents/skills/coding/debug.skill.md +100 -0
  228. package/agents/skills/coding/documentation.skill.md +149 -0
  229. package/agents/skills/coding/eval-driven-development.skill.md +107 -0
  230. package/agents/skills/coding/evals/code-review.eval.yaml +29 -0
  231. package/agents/skills/coding/excalidraw.skill.md +90 -0
  232. package/agents/skills/coding/file-processing.skill.md +55 -0
  233. package/agents/skills/coding/git-workflow.skill.md +153 -0
  234. package/agents/skills/coding/metamorphic-testing.skill.md +113 -0
  235. package/agents/skills/coding/mobile-dev.skill.md +41 -0
  236. package/agents/skills/coding/nodejs-expert.skill.md +23 -0
  237. package/agents/skills/coding/output-validation.skill.md +57 -0
  238. package/agents/skills/coding/pbt-strategy.skill.md +117 -0
  239. package/agents/skills/coding/performant-ai.skill.md +62 -0
  240. package/agents/skills/coding/performant-go.skill.md +61 -0
  241. package/agents/skills/coding/performant-laravel.skill.md +70 -0
  242. package/agents/skills/coding/performant-nodejs.skill.md +67 -0
  243. package/agents/skills/coding/performant-php.skill.md +53 -0
  244. package/agents/skills/coding/performant-python.skill.md +62 -0
  245. package/agents/skills/coding/refactor.skill.md +124 -0
  246. package/agents/skills/coding/secure-coding.skill.md +57 -0
  247. package/agents/skills/coding/sketch-to-diagram.skill.md +106 -0
  248. package/agents/skills/coding/spec-driven-development.skill.md +110 -0
  249. package/agents/skills/coding/tdd-cycle.skill.md +92 -0
  250. package/agents/skills/coding/testing-strategy.skill.md +74 -0
  251. package/agents/skills/coding/time-complexity.skill.md +112 -0
  252. package/agents/skills/coding/tldraw-canvas.skill.md +109 -0
  253. package/agents/skills/coding/tool-construction.skill.md +47 -0
  254. package/agents/skills/coding/ui-gen.skill.md +64 -0
  255. package/agents/skills/coding/vibe-coding.skill.md +63 -0
  256. package/agents/skills/coding/visual-design.skill.md +65 -0
  257. package/agents/skills/coordination/agent-interop.skill.md +72 -0
  258. package/agents/skills/coordination/agent-protocol.skill.md +62 -0
  259. package/agents/skills/coordination/agent-workflow-patterns.skill.md +123 -0
  260. package/agents/skills/coordination/agentic-linter.skill.md +134 -0
  261. package/agents/skills/coordination/agentic-patterns.skill.md +79 -0
  262. package/agents/skills/coordination/meta-optimize.skill.md +62 -0
  263. package/agents/skills/coordination/meta-prompting.skill.md +46 -0
  264. package/agents/skills/coordination/multi-agent-orch.skill.md +78 -0
  265. package/agents/skills/coordination/persona-selector.skill.md +78 -0
  266. package/agents/skills/coordination/self-optimize.skill.md +81 -0
  267. package/agents/skills/coordination/swarm-consensus.skill.md +52 -0
  268. package/agents/skills/core/agent-analytics.skill.md +74 -0
  269. package/agents/skills/core/audit-trail.skill.md +122 -0
  270. package/agents/skills/core/clarify.skill.md +89 -0
  271. package/agents/skills/core/emerging-tech.skill.md +52 -0
  272. package/agents/skills/core/empirical-methods.skill.md +101 -0
  273. package/agents/skills/core/evals/clarify.eval.yaml +29 -0
  274. package/agents/skills/core/evals/integrity-check.eval.yaml +23 -0
  275. package/agents/skills/core/evals/research.eval.yaml +23 -0
  276. package/agents/skills/core/final-review.skill.md +66 -0
  277. package/agents/skills/core/integrity-check.skill.md +149 -0
  278. package/agents/skills/core/knowledge-connect.skill.md +77 -0
  279. package/agents/skills/core/knowledge-gap.skill.md +123 -0
  280. package/agents/skills/core/preflight.skill.md +106 -0
  281. package/agents/skills/core/research.skill.md +107 -0
  282. package/agents/skills/core/retrospective.skill.md +59 -0
  283. package/agents/skills/core/sdlc-checkpoint.skill.md +151 -0
  284. package/agents/skills/core/self-heal.skill.md +163 -0
  285. package/agents/skills/core/session-resume.skill.md +125 -0
  286. package/agents/skills/core/skills-registry.skill.md +65 -0
  287. package/agents/skills/core/state-portability.skill.md +89 -0
  288. package/agents/skills/core/state-preserve.skill.md +76 -0
  289. package/agents/skills/core/system-lifecycle.skill.md +51 -0
  290. package/agents/skills/core/update-scan.skill.md +92 -0
  291. package/agents/skills/data/data-engineering.skill.md +56 -0
  292. package/agents/skills/data/data-governance.skill.md +49 -0
  293. package/agents/skills/data/db-migration.skill.md +136 -0
  294. package/agents/skills/data/semantic-web.skill.md +28 -0
  295. package/agents/skills/data/sql-optimization.skill.md +78 -0
  296. package/agents/skills/industry/engineering-standards.skill.md +31 -0
  297. package/agents/skills/industry/global-standards.skill.md +30 -0
  298. package/agents/skills/industry/healthcare-fhir.skill.md +28 -0
  299. package/agents/skills/industry/industrial-iot.skill.md +30 -0
  300. package/agents/skills/industry/telecom-networks.skill.md +30 -0
  301. package/agents/skills/ops/caching-strategy.skill.md +77 -0
  302. package/agents/skills/ops/capacity-planning.skill.md +67 -0
  303. package/agents/skills/ops/cloud-deploy.skill.md +55 -0
  304. package/agents/skills/ops/configuration-management.skill.md +107 -0
  305. package/agents/skills/ops/cost-optimization.skill.md +39 -0
  306. package/agents/skills/ops/decommission-sunset.skill.md +64 -0
  307. package/agents/skills/ops/dependency-lifecycle.skill.md +63 -0
  308. package/agents/skills/ops/deployment.skill.md +217 -0
  309. package/agents/skills/ops/dev-environments.skill.md +31 -0
  310. package/agents/skills/ops/dev-workflow.skill.md +28 -0
  311. package/agents/skills/ops/docker-dev.skill.md +52 -0
  312. package/agents/skills/ops/enterprise-integration.skill.md +53 -0
  313. package/agents/skills/ops/feature-flag-management.skill.md +59 -0
  314. package/agents/skills/ops/incident-response.skill.md +40 -0
  315. package/agents/skills/ops/infra-devops.skill.md +53 -0
  316. package/agents/skills/ops/k8s-dev.skill.md +51 -0
  317. package/agents/skills/ops/memory-optimization.skill.md +45 -0
  318. package/agents/skills/ops/observability-stack-setup.skill.md +62 -0
  319. package/agents/skills/ops/performance-audit.skill.md +178 -0
  320. package/agents/skills/ops/performance-optimization.skill.md +51 -0
  321. package/agents/skills/ops/production-health.skill.md +85 -0
  322. package/agents/skills/ops/production-verifier.skill.md +50 -0
  323. package/agents/skills/ops/queue-management.skill.md +52 -0
  324. package/agents/skills/ops/release-management.skill.md +39 -0
  325. package/agents/skills/ops/release-validation.skill.md +51 -0
  326. package/agents/skills/ops/reliability-sre.skill.md +51 -0
  327. package/agents/skills/ops/runbook-authoring.skill.md +64 -0
  328. package/agents/skills/ops/system-benchmark.skill.md +69 -0
  329. package/agents/skills/ops/tech-debt.skill.md +143 -0
  330. package/agents/skills/ops/troubleshooting-guide.skill.md +31 -0
  331. package/agents/skills/product/accessibility.skill.md +143 -0
  332. package/agents/skills/product/adr-writer.skill.md +110 -0
  333. package/agents/skills/product/business-case.skill.md +70 -0
  334. package/agents/skills/product/change-management.skill.md +90 -0
  335. package/agents/skills/product/decompose.skill.md +75 -0
  336. package/agents/skills/product/design-thinking.skill.md +62 -0
  337. package/agents/skills/product/estimation-sizing.skill.md +87 -0
  338. package/agents/skills/product/evals/spec-writer.eval.yaml +22 -0
  339. package/agents/skills/product/financial-governance.skill.md +88 -0
  340. package/agents/skills/product/green-software.skill.md +46 -0
  341. package/agents/skills/product/ideation-facilitation.skill.md +87 -0
  342. package/agents/skills/product/market-analysis.skill.md +56 -0
  343. package/agents/skills/product/opportunity-assessment.skill.md +89 -0
  344. package/agents/skills/product/product-analytics.skill.md +92 -0
  345. package/agents/skills/product/professional-practice.skill.md +105 -0
  346. package/agents/skills/product/req-elicitation.skill.md +292 -0
  347. package/agents/skills/product/req-review.skill.md +280 -0
  348. package/agents/skills/product/spec-analyze.skill.md +98 -0
  349. package/agents/skills/product/spec-writer.skill.md +114 -0
  350. package/agents/skills/product/stakeholder-management.skill.md +54 -0
  351. package/agents/skills/product/sustainability-checks.skill.md +29 -0
  352. package/agents/skills/product/systems-thinking.skill.md +56 -0
  353. package/agents/skills/product/user-research-synthesis.skill.md +85 -0
  354. package/agents/skills/product/user-story-mapping.skill.md +54 -0
  355. package/agents/skills/product/visual-specs.skill.md +112 -0
  356. package/agents/skills/security/access-control.skill.md +45 -0
  357. package/agents/skills/security/agent-sandboxing.skill.md +69 -0
  358. package/agents/skills/security/ai-ethics-compliance.skill.md +46 -0
  359. package/agents/skills/security/ai-red-teaming.skill.md +74 -0
  360. package/agents/skills/security/ai-safety-guardrails.skill.md +60 -0
  361. package/agents/skills/security/api-security.skill.md +31 -0
  362. package/agents/skills/security/backup-recovery.skill.md +49 -0
  363. package/agents/skills/security/compliance-review.skill.md +152 -0
  364. package/agents/skills/security/cryptography-standards.skill.md +31 -0
  365. package/agents/skills/security/dependency-security.skill.md +47 -0
  366. package/agents/skills/security/hazard-analysis.skill.md +53 -0
  367. package/agents/skills/security/legal-review.skill.md +41 -0
  368. package/agents/skills/security/log-analysis.skill.md +68 -0
  369. package/agents/skills/security/network-security.skill.md +64 -0
  370. package/agents/skills/security/privacy-audit.skill.md +137 -0
  371. package/agents/skills/security/privacy-data-protection.skill.md +31 -0
  372. package/agents/skills/security/prompt-injection-defense.skill.md +67 -0
  373. package/agents/skills/security/reliability-engineering.skill.md +47 -0
  374. package/agents/skills/security/safety-scan.skill.md +49 -0
  375. package/agents/skills/security/secrets-management.skill.md +65 -0
  376. package/agents/skills/security/secure-architecture.skill.md +31 -0
  377. package/agents/skills/security/security-audit.skill.md +164 -0
  378. package/agents/skills/security/threat-model.skill.md +120 -0
  379. package/agents/skills/security/traceability-audit.skill.md +48 -0
  380. package/agents/templates/00-index.md +162 -0
  381. package/agents/templates/architecture/ADAPTIVE_SYSTEM_TEMPLATE.md +35 -0
  382. package/agents/templates/architecture/ADD_WORKBOOK_TEMPLATE.md +81 -0
  383. package/agents/templates/architecture/ADR_TEMPLATE.md +136 -0
  384. package/agents/templates/architecture/ARCHITECTURE_DECISION_MATRIX.md +169 -0
  385. package/agents/templates/architecture/ARCHITECTURE_REVIEW_TEMPLATE.md +241 -0
  386. package/agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md +353 -0
  387. package/agents/templates/architecture/ARCH_DECISION_FRAMEWORK.md +32 -0
  388. package/agents/templates/architecture/C4_ARCHITECTURE_TEMPLATE.md +185 -0
  389. package/agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md +153 -0
  390. package/agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md +196 -0
  391. package/agents/templates/architecture/DESIGN_PATTERN_USAGE.md +24 -0
  392. package/agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md +254 -0
  393. package/agents/templates/architecture/FITNESS_FUNCTION_TEMPLATE.md +59 -0
  394. package/agents/templates/architecture/INTEGRATION_SPEC_TEMPLATE.md +38 -0
  395. package/agents/templates/architecture/LEGACY_AUDIT_TEMPLATE.md +34 -0
  396. package/agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md +210 -0
  397. package/agents/templates/architecture/SCALABILITY_ANALYSIS_TEMPLATE.md +46 -0
  398. package/agents/templates/architecture/SMART_CONTRACT_TEMPLATE.md +44 -0
  399. package/agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md +197 -0
  400. package/agents/templates/brain/ACTIVE_INFERENCE_LOOP_TEMPLATE.md +42 -0
  401. package/agents/templates/brain/EPISODIC_MEMORY_LOG_TEMPLATE.md +28 -0
  402. package/agents/templates/brain/GLOBAL_WORKSPACE_CONFIG_TEMPLATE.md +44 -0
  403. package/agents/templates/brain/KNOWLEDGE_MAP_TEMPLATE.md +53 -0
  404. package/agents/templates/brain/OODA_LOOP_TRACE_TEMPLATE.md +44 -0
  405. package/agents/templates/brain/PREDICTION_ERROR_LOG_TEMPLATE.md +33 -0
  406. package/agents/templates/brain/PROJECT_CONTEXT_TEMPLATE.md +36 -0
  407. package/agents/templates/brain/SELF_IMPROVEMENT_LOG_TEMPLATE.md +39 -0
  408. package/agents/templates/brain/WORKING_MEMORY_TEMPLATE.md +34 -0
  409. package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +30 -0
  410. package/agents/templates/coding/DESIGN_TOKENS_TEMPLATE.json +54 -0
  411. package/agents/templates/coding/DEVCONTAINER_TEMPLATE.json +42 -0
  412. package/agents/templates/coding/DEV_SPACE_TEMPLATE.yaml +48 -0
  413. package/agents/templates/coding/E2E_TEST_SUITE_TEMPLATE.md +36 -0
  414. package/agents/templates/coding/EVAL_PLAN_TEMPLATE.md +85 -0
  415. package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +57 -0
  416. package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +73 -0
  417. package/agents/templates/coding/PROPERTY_TEST_CHECKLIST.md +77 -0
  418. package/agents/templates/coding/SKETCH_TO_DIAGRAM_TEMPLATE.md +56 -0
  419. package/agents/templates/coding/TEST_CASE_TEMPLATE.md +28 -0
  420. package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +36 -0
  421. package/agents/templates/coding/TIME_COMPLEXITY_REPORT_TEMPLATE.md +61 -0
  422. package/agents/templates/coordination/AGENTS_TEMPLATE.md +540 -0
  423. package/agents/templates/coordination/AGENT_HANDSHAKE_TEMPLATE.json +37 -0
  424. package/agents/templates/coordination/AGENT_PROFILE_TEMPLATE.md +28 -0
  425. package/agents/templates/coordination/SWARM_ARCHITECTURE_TEMPLATE.md +53 -0
  426. package/agents/templates/coordination/SWARM_CONFIG_TEMPLATE.json +45 -0
  427. package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +75 -0
  428. package/agents/templates/core/BUG_REPORT_TEMPLATE.md +136 -0
  429. package/agents/templates/core/DEPENDENCY_GRAPH_TEMPLATE.md +63 -0
  430. package/agents/templates/core/ESTIMATION_TEMPLATE.md +70 -0
  431. package/agents/templates/core/MCP_CONFIG_TEMPLATE.json +807 -0
  432. package/agents/templates/core/PLAN_TEMPLATE.md +162 -0
  433. package/agents/templates/core/PROJECT_RETROSPECTIVE_TEMPLATE.md +67 -0
  434. package/agents/templates/core/SDLC_TRACKER.md +217 -0
  435. package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +168 -0
  436. package/agents/templates/core/SYSTEM_ANALYSIS_TEMPLATE.md +52 -0
  437. package/agents/templates/core/TASKS_TEMPLATE.md +104 -0
  438. package/agents/templates/core/TRACEABILITY_MATRIX_TEMPLATE.md +18 -0
  439. package/agents/templates/core/WHITEBOARD_DESIGN_TEMPLATE.md +46 -0
  440. package/agents/templates/data/DATABASE_SCHEMA_TEMPLATE.md +38 -0
  441. package/agents/templates/data/DATA_PIPELINE_TEMPLATE.md +44 -0
  442. package/agents/templates/data/ONTOLOGY_TEMPLATE.md +52 -0
  443. package/agents/templates/industry/ENGINEERING_STANDARDS_REVIEW_TEMPLATE.md +43 -0
  444. package/agents/templates/industry/FHIR_INTEGRATION_TEMPLATE.md +53 -0
  445. package/agents/templates/industry/GLOBAL_STANDARDS_AUDIT_TEMPLATE.md +45 -0
  446. package/agents/templates/industry/IOT_TELEMETRY_TEMPLATE.md +59 -0
  447. package/agents/templates/industry/TELECOM_API_TEMPLATE.md +50 -0
  448. package/agents/templates/ops/BENCHMARK_REPORT_TEMPLATE.md +48 -0
  449. package/agents/templates/ops/CAPACITY_PLAN_TEMPLATE.md +41 -0
  450. package/agents/templates/ops/COST_OPTIMIZATION_REPORT_TEMPLATE.md +40 -0
  451. package/agents/templates/ops/DECOMMISSION_PLAN_TEMPLATE.md +102 -0
  452. package/agents/templates/ops/DEPLOY_CONFIG_TEMPLATE.md +88 -0
  453. package/agents/templates/ops/INCIDENT_POSTMORTEM_TEMPLATE.md +39 -0
  454. package/agents/templates/ops/INFRA_PLAN_TEMPLATE.md +37 -0
  455. package/agents/templates/ops/RELEASE_READINESS_REPORT.md +35 -0
  456. package/agents/templates/ops/RUNBOOK_TEMPLATE.md +103 -0
  457. package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +102 -0
  458. package/agents/templates/product/BUSINESS_CASE_TEMPLATE.md +42 -0
  459. package/agents/templates/product/CHANGE_MANAGEMENT_PLAN_TEMPLATE.md +68 -0
  460. package/agents/templates/product/EMPATHY_MAP_TEMPLATE.md +47 -0
  461. package/agents/templates/product/EXPERIMENT_PLAN_TEMPLATE.md +84 -0
  462. package/agents/templates/product/GREEN_SOFTWARE_REPORT_TEMPLATE.md +42 -0
  463. package/agents/templates/product/IDEATION_LOG_TEMPLATE.md +42 -0
  464. package/agents/templates/product/NFR_TEMPLATE.md +31 -0
  465. package/agents/templates/product/PRD_TEMPLATE.md +222 -0
  466. package/agents/templates/product/PROBLEM_STATEMENT_TEMPLATE.md +32 -0
  467. package/agents/templates/product/REQUIREMENTS_REVIEW_TEMPLATE.md +173 -0
  468. package/agents/templates/product/SPEC_TEMPLATE.md +259 -0
  469. package/agents/templates/product/STAKEHOLDER_REGISTER_TEMPLATE.md +127 -0
  470. package/agents/templates/product/USER_STORY_MAP_TEMPLATE.md +35 -0
  471. package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +207 -0
  472. package/agents/templates/security/DATASHEET_TEMPLATE.md +95 -0
  473. package/agents/templates/security/ETHICAL_IMPACT_ASSESSMENT.md +32 -0
  474. package/agents/templates/security/HAZARD_LOG.md +17 -0
  475. package/agents/templates/security/MODEL_CARD_TEMPLATE.md +120 -0
  476. package/agents/templates/security/SAFETY_CASE.md +39 -0
  477. package/agents/templates/security/SAFETY_POLICY.md +25 -0
  478. package/agents/templates/security/SECURITY_CHECKLIST.md +157 -0
  479. package/agents/templates/security/SYSTEM_CARD_TEMPLATE.md +139 -0
  480. package/agents/templates/security/THREAT_MODEL_TEMPLATE.md +171 -0
  481. package/bin/install.js +572 -0
  482. package/docs/CLI_REFERENCE.md +527 -0
  483. package/docs/INSTALL.md +68 -0
  484. package/docs/MCP_CONFIGURATIONS.md +1765 -0
  485. package/docs/PLATFORM_CONTROLS.md +324 -0
  486. package/docs/POST_INSTALL.md +75 -0
  487. package/docs/QUICK_COMMANDS.md +131 -0
  488. package/docs/QUICK_GUIDE.md +914 -0
  489. package/docs/README_FULL.md +1451 -0
  490. package/docs/SCHEMA.md +164 -0
  491. package/docs/V1_RELEASE_CHECKLIST.md +144 -0
  492. package/docs/VERIFICATION_GUIDE.md +283 -0
  493. package/docs/adr/0001-record-architecture-decisions.md +26 -0
  494. package/docs/adr/0002-brain-active-inference-runtime.md +27 -0
  495. package/docs/adr/0003-additive-only-emitter-schema-evolution.md +33 -0
  496. package/docs/assets/GABBE.png +0 -0
  497. package/docs/gabbe.config.example.json +9 -0
  498. package/docs/reports/duplication-report.md +30 -0
  499. package/install.ps1 +90 -0
  500. package/install.sh +89 -0
  501. package/package.json +49 -0
  502. package/scripts/init.py +1036 -0
@@ -0,0 +1,324 @@
1
+ # GABBE Platform Controls (Experimental)
2
+
3
+ > **Audience:** operators enforcing budget/policy. **Scope:** budget, hard stops, policy, gateway, audit, escalation, replay.
4
+
5
+ This document describes the agent platform control layer for the experimental `gabbe` CLI. It covers budget enforcement, hard stops, policy rules, the tool gateway, audit tracing, human escalation, and deterministic replay.
6
+
7
+ ---
8
+
9
+ ## Overview
10
+
11
+ Every `gabbe brain activate` run (and `gabbe serve-mcp` session) is wrapped in a `RunContext` that brings together all platform controls:
12
+
13
+ ```
14
+ RunContext
15
+ ├── Budget — token, cost, tool call, iteration, and wall-time limits
16
+ ├── HardStop — absolute iteration / depth / timeout guards
17
+ ├── PolicyEngine — YAML-driven tool access control (RBAC + allowlists)
18
+ ├── ToolGateway — single mediated execution point for all tools
19
+ ├── AuditTracer — structured spans to SQLite + JSONL + optional OTel
20
+ ├── EscalationHandler — human-in-the-loop when limits are hit
21
+ └── CheckpointStore — state snapshots enabling replay
22
+ ```
23
+
24
+ All state persists to `project/state.db` (schema v3). Required dependencies: `requests`, `PyYAML`, and `jsonschema` (tool-argument validation is fail-closed — the gateway refuses to execute a parameterized tool without schema validation).
25
+
26
+ ---
27
+
28
+ ## Budget (`gabbe/budget.py`)
29
+
30
+ ### What it tracks
31
+
32
+ | Dimension | Config var | Default |
33
+ |---|---|---|
34
+ | Total tokens | `GABBE_MAX_TOKENS_PER_RUN` | 100,000 |
35
+ | Tool calls | `GABBE_MAX_TOOL_CALLS_PER_RUN` | 50 |
36
+ | Iterations | `GABBE_MAX_ITERATIONS` | 25 |
37
+ | Wall time | `GABBE_MAX_WALL_TIME` | 300 s |
38
+ | Cost (USD) | `GABBE_MAX_COST_USD` | $5.00 |
39
+
40
+ ### Cost calculation
41
+
42
+ Pricing is loaded from the `pricing_registry` SQLite table (keyed by `model_id`). Populate it with your model pricing:
43
+
44
+ ```sql
45
+ INSERT OR REPLACE INTO pricing_registry (model_id, input_token_price, output_token_price)
46
+ VALUES ('gpt-4o', 0.0000025, 0.000010);
47
+ ```
48
+
49
+ When pricing is absent for a model, cost stays at $0 (tokens are still counted).
50
+
51
+ ### API
52
+
53
+ ```python
54
+ from gabbe.budget import Budget, BudgetExceeded
55
+
56
+ b = Budget.from_config() # reads env vars
57
+ b.record_tool_call() # increments + checks
58
+ b.record_iteration() # increments + checks
59
+ b.record_llm_usage("gpt-4o", usage_dict) # tokens + cost
60
+ snap = b.snapshot() # current state dict
61
+ rem = b.remaining() # remaining per dimension
62
+ b.check() # raise BudgetExceeded if any limit exceeded
63
+ b.can_afford(estimated_tokens=2000) # pre-step check (non-mutating)
64
+ b.reserve(estimated_cost_usd=0.10) # pre-step reservation gate (returns bool)
65
+
66
+ # Replay reconstruction
67
+ b2 = Budget.from_dict({"max_tokens": 500, "tokens_used": 100})
68
+ ```
69
+
70
+ ---
71
+
72
+ ## HardStop (`gabbe/hardstop.py`)
73
+
74
+ Absolute guards that cannot be loosened at runtime (unlike budgets which check `>`):
75
+
76
+ ```python
77
+ from gabbe.hardstop import HardStop, MaxIterationsExceeded, MaxDepthExceeded, TimeoutExceeded
78
+
79
+ hs = HardStop(max_iterations=10, max_depth=5, timeout_sec=120)
80
+ hs.tick(depth=0) # increments iteration, checks all limits
81
+ hs.remaining_steps() # -> int
82
+ hs.should_wrap_up(threshold=2) # -> bool (true when ≤ 2 steps left)
83
+ ```
84
+
85
+ Config vars: `GABBE_MAX_ITERATIONS`, `GABBE_MAX_RECURSION_DEPTH`, `GABBE_MAX_WALL_TIME`.
86
+
87
+ When `should_wrap_up()` returns `True`, the brain system prompt is a good place to append "Please wrap up your current task."
88
+
89
+ ---
90
+
91
+ ## Policy Engine (`gabbe/policy.py`)
92
+
93
+ ### Configuration (`project/policies.yml`)
94
+
95
+ ```yaml
96
+ version: "1"
97
+
98
+ tools:
99
+ allowed: ["call_llm", "run_command"]
100
+ denied: ["run_security_scan"] # explicit deny overrides allowed
101
+
102
+ roles:
103
+ brain-mode: ["call_llm"]
104
+ external_agent: ["run_command"]
105
+ admin: ["*"]
106
+
107
+ # Enable PII detection to block credentials/emails from remote APIs
108
+ content_safety:
109
+ enabled: true
110
+
111
+ # Numeric parameter bounds (optional)
112
+ parameter_bounds:
113
+ temperature:
114
+ min: 0.0
115
+ max: 1.0
116
+ ```
117
+
118
+ Set `GABBE_POLICY_FILE` to override the path (default: `project/policies.yml`).
119
+
120
+ > **Secure default:** If the policy file is absent, `PolicyEngine.from_yaml()` defaults to **deny-all** (`ToolAllowlistPolicy([], [])`). A warning is logged. Create `project/policies.yml` to configure tool access explicitly.
121
+
122
+ > **Note on `policies.yml` sections:** The parser reads `version`, `tools`, `roles`, `content_safety`, and `parameter_bounds`. The `budgets:` section is informational only (budget limits are enforced by `budget.py` via env vars). The `escalation:` section is currently not parsed — escalation triggers and modes are configured via env vars (`GABBE_ESCALATION_MODE`) and the `EscalationTrigger` enum in code.
123
+
124
+ ### Built-in policies
125
+
126
+ | Class | Purpose |
127
+ |---|---|
128
+ | `ToolAllowlistPolicy` | Allow/deny by tool name or wildcard `*` |
129
+ | `RolePolicy` | Role → allowed tools mapping |
130
+ | `ContentSafetyPolicy` | Blocks PII (emails, credentials, SSNs) in inputs |
131
+ | `ParameterRangePolicy` | Validates numeric params against `min`/`max` bounds |
132
+
133
+ Evaluation is **deny-first**: the first policy that denies wins. Use `engine.evaluate_all()` to get all results for audit logging.
134
+
135
+ ---
136
+
137
+ ## Tool Gateway (`gabbe/gateway.py`)
138
+
139
+ All tool execution flows through `ToolGateway.execute()`, which enforces:
140
+
141
+ 1. Tool registration check
142
+ 2. Policy evaluation (deny-first chain)
143
+ 3. Budget check (`record_tool_call()`)
144
+ 4. Rate limiting (sliding 60s window, configurable per tool)
145
+ 5. Circuit breaker (open after N consecutive failures)
146
+ 6. JSON Schema validation (fail-closed: parameterized tools refuse to execute if `jsonschema` is unavailable)
147
+ 7. Handler execution
148
+ 8. Audit span recorded (start + end)
149
+
150
+ ```python
151
+ from gabbe.gateway import ToolGateway, ToolDefinition
152
+
153
+ gw = ToolGateway()
154
+ gw.register(ToolDefinition(
155
+ name="run_test",
156
+ description="Run project tests",
157
+ parameters={"type": "object", "properties": {"cmd": {"type": "string"}}},
158
+ handler=my_handler,
159
+ allowed_roles={"agent"},
160
+ rate_limit_per_min=10,
161
+ circuit_breaker_threshold=3,
162
+ ))
163
+ result = gw.execute("run_test", {"cmd": "pytest"}, role="agent", run_context=ctx)
164
+ ```
165
+
166
+ ---
167
+
168
+ ## Audit Tracer (`gabbe/audit.py`)
169
+
170
+ Every significant event (LLM call, tool call, policy check) is recorded as a span:
171
+
172
+ ```python
173
+ from gabbe.audit import AuditTracer
174
+
175
+ tracer = AuditTracer(run_id="abc123", db_conn=conn)
176
+
177
+ span = tracer.start_span("llm_call", "brain_observe", {"prompt": "..."})
178
+ tracer.end_span(span, output_data={"response": "..."}, token_usage=usage, cost_usd=0.002, status="ok")
179
+
180
+ tracer.snapshot_budget(step=3, budget=budget)
181
+
182
+ trace = tracer.get_run_trace("abc123") # list of span dicts
183
+ json_str = tracer.export_json("abc123") # full trace as JSON
184
+ ```
185
+
186
+ **Wrapping a function in a span:** use the explicit start/end pair around the call:
187
+
188
+ ```python
189
+ span = tracer.start_span("tool_call", "my_tool", {"args": args})
190
+ try:
191
+ result = my_tool_handler(args)
192
+ tracer.end_span(span, output_data={"result": result}, status="ok")
193
+ except Exception as e:
194
+ tracer.end_span(span, output_data={"error": str(e)}, status="error")
195
+ raise
196
+ ```
197
+
198
+ **Storage destinations:**
199
+ - `project/state.db` → `audit_spans` table
200
+ - `project/logs/run_{run_id}.jsonl` → one JSON line per span
201
+ - OpenTelemetry → set `GABBE_OTEL_ENABLED=true` and configure OTel SDK (soft-fail: if OTel SDK is not installed, a warning is logged and spans fall back to SQLite/JSONL only)
202
+
203
+ **CLI inspection:**
204
+ ```bash
205
+ gabbe audit <run-id> # table view
206
+ gabbe audit <run-id> --format json # raw JSON
207
+ ```
208
+
209
+ ---
210
+
211
+ ## Escalation Handler (`gabbe/escalation.py`)
212
+
213
+ Triggered automatically when the platform detects dangerous conditions:
214
+
215
+ | Trigger | When |
216
+ |---|---|
217
+ | `BUDGET_EXHAUSTED` | Any budget limit exceeded |
218
+ | `REPEATED_TOOL_FAILURE` | Circuit breaker opens |
219
+ | `AMBIGUOUS_DECISION` | Agent cannot determine next action |
220
+ | `POLICY_VIOLATION` | Policy engine denies an action |
221
+ | `MAX_ITERATIONS` | HardStop limit reached |
222
+
223
+ ### Escalation modes
224
+
225
+ Set via `GABBE_ESCALATION_MODE` (default: `cli`):
226
+
227
+ | Mode | Behaviour |
228
+ |---|---|
229
+ | `cli` | Prompts the operator interactively (inline); execution **continues** after the operator responds (`approved`, `rejected`, or `edited`) |
230
+ | `file` | Records to `pending_escalations` table and raises `EscalationPaused`, **suspending execution** until `gabbe resume <run-id>` is called |
231
+ | `silent` | Auto-rejects (safe for CI/CD) |
232
+
233
+ The **CLI mode** interactive prompt offers three choices:
234
+ - **[a]pprove** — allow the action (status `approved`)
235
+ - **[r]eject** — deny the action (status `rejected`)
236
+ - **[e]dit context** — provide JSON overrides or notes; execution continues with `edited` status and the provided notes stored in `pending_escalations.response`
237
+
238
+ **Resuming a paused run:**
239
+ ```bash
240
+ gabbe resume <run-id>
241
+ ```
242
+
243
+ ---
244
+
245
+ ## Replay & Checkpoints (`gabbe/replay.py`)
246
+
247
+ Each run can save state snapshots (checkpoints) for deterministic replay:
248
+
249
+ ```python
250
+ from gabbe.replay import CheckpointStore, ReplayRunner
251
+
252
+ store = CheckpointStore(db_conn=conn)
253
+ cp_id = store.save(run_id, step=1, node_name="observe", state_snapshot={"tasks": 5}, policy_version="v1")
254
+ store.load(cp_id) # deserialize checkpoint
255
+ store.get_history(run_id) # ordered list of checkpoints
256
+
257
+ runner = ReplayRunner(store)
258
+ steps = runner.replay(run_id, from_step=0) # returns list of replayed step dicts
259
+ diff = runner.diff(run_id_a, run_id_b) # compare two run sequences
260
+
261
+ # Reconstruct a RunContext from a checkpoint.
262
+ # NOTE: creates a *new* run_id (fresh UUID) — the replay is tracked as a new run,
263
+ # not a restoration of the original run.
264
+ ctx = RunContext.from_checkpoint(cp_id)
265
+ ```
266
+
267
+ **CLI replay:**
268
+ ```bash
269
+ gabbe replay <run-id>
270
+ gabbe replay <run-id> --from-step 3
271
+ ```
272
+
273
+ ---
274
+
275
+ ## Environment Variables Reference
276
+
277
+ | Variable | Default | Description |
278
+ |---|---|---|
279
+ | `GABBE_MAX_TOKENS_PER_RUN` | `100000` | Token budget per run |
280
+ | `GABBE_MAX_TOOL_CALLS_PER_RUN` | `50` | Tool call budget per run |
281
+ | `GABBE_MAX_ITERATIONS` | `25` | Max brain loop iterations |
282
+ | `GABBE_MAX_WALL_TIME` | `300` | Max wall time in seconds |
283
+ | `GABBE_MAX_RECURSION_DEPTH` | `5` | Max agent recursion depth |
284
+ | `GABBE_MAX_RETRIES_PER_TOOL` | `3` | Max retries per tool call |
285
+ | `GABBE_MAX_COST_USD` | `5.0` | Max cost budget per run |
286
+ | `GABBE_POLICY_FILE` | `project/policies.yml` | Path to YAML policy file |
287
+ | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli`, `file`, or `silent` |
288
+ | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
289
+ | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout for verify shell commands |
290
+ | `GABBE_MCP_TOKEN` | *(unset)* | If set, MCP clients must provide this token in `initialize` params. Leave unset to disable. |
291
+ | `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | Comma-separated executables permitted via `run_command` over MCP. When unset, all commands are blocked. |
292
+
293
+ ---
294
+
295
+ ## Database Tables (v3)
296
+
297
+ | Table | Purpose |
298
+ |---|---|
299
+ | `runs` | One row per agent execution (status, costs, initiator) |
300
+ | `audit_spans` | Per-step spans with token usage, cost, CoT content |
301
+ | `budget_snapshots` | Periodic budget state snapshots per run |
302
+ | `checkpoints` | State snapshots for deterministic replay |
303
+ | `pending_escalations` | Human-review queue |
304
+ | `forecast_snapshots` | Cost/token projections from `gabbe forecast` |
305
+ | `pricing_registry` | Dynamic per-model token pricing |
306
+
307
+ ---
308
+
309
+ ## Quickstart: Running with Tight Limits
310
+
311
+ ```bash
312
+ # Hard stop after 3 iterations
313
+ GABBE_MAX_ITERATIONS=3 gabbe brain activate
314
+
315
+ # Budget cap at 1,000 tokens
316
+ GABBE_MAX_TOKENS_PER_RUN=1000 gabbe brain activate
317
+
318
+ # Silent mode for CI (no interactive prompts)
319
+ GABBE_ESCALATION_MODE=silent gabbe brain activate
320
+
321
+ # Inspect what happened
322
+ gabbe runs
323
+ gabbe audit <run-id>
324
+ ```
@@ -0,0 +1,75 @@
1
+ # Post-Install Setup — Full Environment
2
+
3
+ After `npx gabbe-kit init` (or `gabbe setup` / `curl … | sh`) lands the kit and wires
4
+ your detected agents, run **`gabbe doctor`** for an environment report, then follow
5
+ these steps to finish a full setup. Steps are safe for a human OR an agent to execute.
6
+
7
+ ## 1. Verify the install
8
+
9
+ ```bash
10
+ gabbe doctor # autodetects OS/arch, runtimes, agent clients; prints next steps
11
+ ```
12
+
13
+ All agent clients GABBE detected are already wired. Anything missing is reported.
14
+
15
+ ## 2. Enable MCP servers (the main post-install task)
16
+
17
+ GABBE ships a catalog of **65 MCP servers** in
18
+ `agents/templates/core/MCP_CONFIG_TEMPLATE.json`. Most are opt-in (`"_enabled": false`).
19
+ To enable one: set `"_enabled": true`, fill the listed env vars, and point your agent
20
+ at the config (e.g. `.mcp.json`, `.cursor/mcp.json`, or your client's MCP settings).
21
+
22
+ ### Essential (recommended for every project)
23
+
24
+ | Server | Purpose | Setup |
25
+ |---|---|---|
26
+ | `context7` | Up-to-date SDK docs (prevents API hallucination) | npx; no key |
27
+ | `filesystem` | Read-only project file access (internal RAG) | npx; set root path |
28
+ | `sequential-thinking` | Chain-of-thought reasoning | npx; no key |
29
+ | `github` | PR review, code search, issue mgmt | npx; `GITHUB_TOKEN` |
30
+ | `brave-search` or `tavily` | Authoritative web research | npx; API key |
31
+
32
+ ### Locally-installed servers (clone/build/binary, not a plain npx one-liner)
33
+
34
+ | Server | How to install locally |
35
+ |---|---|
36
+ | `time-complexity` | **GitHub server**: `git clone` the time-complexity-mcp repo, `npm install && npm run build`, then set its `args` to the built `dist/index.js`. Big-O time/space static analysis (tree-sitter, no code execution). Pairs with `coding/time-complexity.skill`. |
37
+ | `semgrep` | `pip install semgrep-mcp`; runs via `python -m semgrep_mcp`. Static security scanning. |
38
+ | `google-genai-toolbox` | Download the `genai-toolbox` (MCP Toolbox for Databases) Go binary from its GitHub releases; run `toolbox --stdio`. |
39
+
40
+ ### Pick servers by lifecycle phase
41
+
42
+ See the **SWEBOK v4 priority map** in `docs/MCP_CONFIGURATIONS.md` for the best
43
+ self-hostable servers per software-engineering area (Requirements/Design,
44
+ Construction, Testing/Quality, Operations, Management, Foundations). Highlights:
45
+ - **Testing/quality:** `sentry`, `snyk`, `semgrep`, `mcp-evals`, `mcp-chaos-rig`
46
+ - **Operations (Day-2):** `pagerduty`, `cloudflare`, `grafana`, `datadog`
47
+ - **Memory/RAG:** `knowledge-graph-memory`, `qdrant`, `chroma`
48
+
49
+ > Security: prod databases must be configured read-only; dev read-write. Keep keys in
50
+ > env vars, never in the committed config. Most servers run locally via Docker/Node so
51
+ > credentials never leave your host.
52
+
53
+ ## 3. Configure GABBE policy + budgets (optional, for the Python CLI)
54
+
55
+ If using the optional `gabbe` CLI, set controls via env or `project/gabbe.config.json`:
56
+ `GABBE_API_KEY`, `GABBE_AUTONOMY` (ask|auto|hybrid), budgets (`GABBE_MAX_COST_USD`,
57
+ `GABBE_MAX_TOKENS_PER_RUN`), and `project/policies.yml` (tool allowlist, fail-closed).
58
+ See `docs/PLATFORM_CONTROLS.md` and `docs/CLI_REFERENCE.md`.
59
+
60
+ ## 4. Validate the setup
61
+
62
+ ```bash
63
+ gabbe verify # files + AGENTS.md commands
64
+ gabbe verify --chaos # fault-injection self-checks (resilience)
65
+ gabbe eval # deterministic skill-eval self-check
66
+ ```
67
+
68
+ ## 5. Updating / uninstalling later
69
+
70
+ ```bash
71
+ gabbe update # additive kit refresh; preserves user files
72
+ gabbe uninstall --dry-run # preview the exact, reversible removal
73
+ ```
74
+
75
+ See `docs/INSTALL.md` for scopes (project / `--global` / `--dir`) and channels.
@@ -0,0 +1,131 @@
1
+ # Quick Commands & Prompts Reference
2
+
3
+ > **Audience:** day-to-day users. **Scope:** copy-paste prompts for the most common tasks.
4
+
5
+ This guide provides a quick reference for the most common commands, setup instructions, and copy-paste prompts used in the GABBE Agentic Engineering Kit.
6
+
7
+ ## 1. Setup Commands
8
+
9
+ | Goal | Command | Description |
10
+ |---|---|---|
11
+ | **Initialize Kit** | `python3 scripts/init.py` | Runs the setup wizard to configure the kit, wire your AI agents (Claude, Cursor, Gemini), and generate `BOOTSTRAP_MISSION.md` (or `SETUP_MISSION.md`) |
12
+ | **Manual Wiring (UNIX)** | `./agents/setup-context.sh` | Manually symlinks the skills into your IDE's agent folder. |
13
+ | **Manual Wiring (Windows)** | `.\agents\setup-context.ps1` | PowerShell equivalent of the manual wiring script. |
14
+ | **Install GABBE CLI (Optional)**| `pip install -e .` | Installs the GABBE CLI locally. |
15
+
16
+ ---
17
+
18
+ ## 2. GABBE CLI Reference (Experimental)
19
+
20
+ | Command | Description |
21
+ |---|---|
22
+ | `gabbe init` | Initializes the SQLite database (run after `scripts/init.py`). |
23
+ | `gabbe sync` | Bidirectional sync between `project/TASKS.md` and SQLite DB. |
24
+ | `gabbe verify` | Programmable integrity check (files, tests, lint). |
25
+ | `gabbe verify --chaos` | Fault-injection resilience self-checks. |
26
+ | `gabbe eval` | Skill-eval self-check (`--live` scores via the model). |
27
+ | `gabbe doctor` | Autodetect OS/runtimes/agents + post-install MCP next-steps. |
28
+ | `gabbe update` / `gabbe uninstall` | Reversible, manifest-backed install management. |
29
+ | `gabbe status` | Visual dashboard of project phase and task progress. |
30
+ | `gabbe brain activate` | Activates Active Inference loop (requires API key). |
31
+ | `gabbe brain evolve --skill NAME` | Evolutionary Prompt Optimization for a named skill. |
32
+ | `gabbe brain heal` | Self-healing watchdog: checks DB and required files. |
33
+ | `gabbe route <prompt>` | Arbitrates prompt between Local and Remote LLMs (requires API key). |
34
+ | `gabbe forecast` | Strategic Forecast projects remaining work cost and tokens. |
35
+ | `gabbe serve-mcp` | Zero-dependency JSON-RPC MCP server for agent integration. |
36
+ | `gabbe runs [--status STATUS] [--limit N]` | List recent agent runs with status, cost, and timestamps. |
37
+ | `gabbe audit <run-id> [--format json\|table]` | Display structured span-level audit trace for a past run. |
38
+ | `gabbe replay <run-id> [--from-step N]` | Replay a past run deterministically from its checkpoints. |
39
+ | `gabbe resume <run-id>` | Approve or reject pending escalations for a paused run. |
40
+ | `gabbe registry publish [--out DIR]` | Export skills as a publish-ready agentskills.io bundle (manifest + agent-card). |
41
+ | `gabbe registry add <source> [--namespace NS] [--apply]` | Import an external skill/bundle (validated + security-scanned + namespaced). |
42
+ | `gabbe setup` | Interactive install wizard (also `npx gabbe-kit init` for a Python-independent install). |
43
+
44
+ ### Platform Control Layer
45
+ The experimental `gabbe` CLI supports a **platform control layer**. It covers budget enforcement, cost and token controls, hard stops, policy rules, the tool gateway, audit tracing, human escalation, and deterministic replay. Detailed documentation is available in [`PLATFORM_CONTROLS.md`](PLATFORM_CONTROLS.md).
46
+
47
+ ---
48
+
49
+ ## 3. Top 15 Essential Skills (Trigger Words)
50
+
51
+ You can invoke these skills directly in your IDE chat (e.g., Cursor, GitHub Copilot) or via Slash Commands (e.g., Claude Code `/tdd-cycle`).
52
+
53
+ | Phase | Skill | Trigger Word | Purpose |
54
+ |---|---|---|---|
55
+ | **Product** | `spec-writer` | "write spec", "spec" | Generates PRD.md with EARS syntax. |
56
+ | **Design** | `arch-design` | "design architecture" | Generates C4 architecture and `PLAN.md`. |
57
+ | **Design** | `threat-model` | "threat model", "stride"| Analyzes security risks using STRIDE. |
58
+ | **Tasks** | *(built-in logic)* | "decompose tasks" | Breaks down `PLAN.md` into 15m tasks. |
59
+ | **Coding** | `tdd-cycle` | "test", "tdd" | Red-Green-Refactor loop. |
60
+ | **Coding** | `debug` | "fix", "debug" | Root Cause Analysis (RCA) and fixing. |
61
+ | **Coding** | `refactor` | "refactor" | Safe code restructuring. |
62
+ | **Coding** | `vibe-coding` | "vibe", "aesthetic" | Creative, high-fidelity frontend coding. |
63
+ | **Review** | `code-review` | "review", "audit" | Security, performance, and style check. |
64
+ | **Security**| `security-audit` | "owasp", "audit" | Comprehensive security review. |
65
+ | **Security**| `safety-scan` | "safety scan" | Pre-commit safety guardrails. |
66
+ | **Core** | `research` | "research", "find" | Deep research using authoritative sources. |
67
+ | **Core** | `self-heal` | "fix error" | Autonomous auto-recovery loop. |
68
+ | **Modes** | `loki-mode` | "loki", "swarm" | 10-phase SDLC orchestration. |
69
+ | **Modes** | `brain-mode` | "brain activate" | Meta-cognitive orchestrator. |
70
+
71
+ *(For the complete 214 skills list, see `agents/skills/00-index.md`)*
72
+
73
+ ---
74
+
75
+ ## 4. Common Actions (Copy-Paste Prompts)
76
+
77
+ Copy and paste these exact prompts into your AI chat window to kick off standard workflows.
78
+
79
+ ### Strategy & Ideation (Step 0)
80
+ > "Use business-case/strategy skills to validate exactly why we are building [description] and who it is for."
81
+
82
+ ### New Project from Scratch
83
+ > "Read AGENTS.md. I want to build [description]. Start with spec-writer skill."
84
+
85
+ **Flow:** Strategy → Spec → Design → Tasks → TDD Implementation → Security → Deploy
86
+
87
+ ### Resume Existing Project
88
+ > "Read AGENTS.md and agents/memory/PROJECT_STATE.md. Resume the project."
89
+
90
+ ### Fix a Bug
91
+ > "Read AGENTS.md. Bug: [description]. Use debug skill with TDD."
92
+
93
+ **Flow:** Reproduce → Root Cause → Failing Test → Fix → Green → Regression Check
94
+
95
+ ### Refactor / Pay Tech Debt
96
+ > "Use tech-debt skill on [directory]. Then refactor the top-priority item."
97
+
98
+ ### Security Audit
99
+ > "Run security-audit skill on the entire codebase."
100
+
101
+ ### Acknowledge Security & Guardrails
102
+ > "Please acknowledge and enforce the Security & Guardrails constraints defined for the current skill."
103
+
104
+ ### Architecture Review
105
+ > "Run arch-review skill. Check for SOLID violations and coupling."
106
+
107
+ > "Use the performant-nodejs skill to audit the current Node.js architecture for scalability bottlenecks and propose optimizations."
108
+
109
+ > "Use the performant-laravel skill to audit the current Laravel architecture for scalability bottlenecks and propose optimizations."
110
+
111
+ > "Use the performant-python skill to audit the current Python architecture for scalability bottlenecks and propose optimizations."
112
+
113
+ > "Use the performant-go skill to audit the current Go architecture for scalability bottlenecks and propose optimizations."
114
+
115
+ > "Use the performant-ai skill to audit the current AI/LLM architecture for latency and cost bottlenecks."
116
+
117
+ ### Software Engineering & System Architecture
118
+ > "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."
119
+
120
+ > "Use the visual-whiteboarding skill. Connect to the Draw.io/Miro MCP and generate a visual spatial architecture diagram for the current microservice layout."
121
+
122
+ > "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."
123
+
124
+ ### Vibe-Coding (Creative Frontend)
125
+ > "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."
126
+
127
+ ### Activate Brain Mode (Complex Goals)
128
+ > "Activate Brain Mode. Goal: [build X / migrate Y / solve Z]."
129
+
130
+ ### Activate Loki Mode (Large Projects)
131
+ > "Activate Loki Mode. Goal: [build X / migrate Y / refactor Z]."