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,73 @@
1
+ # Rust Project Guide
2
+
3
+ > **Audience:** agents writing or reviewing Rust services/tools. **Scope:**
4
+ > current edition, idioms, structure, testing, performance, and pitfalls for
5
+ > 2026. Versions verified 2026-06-10 (see sources at the end).
6
+
7
+ ## Recommended stack (2026)
8
+
9
+ - **Toolchain:** latest stable Rust on **edition 2024** (stabilized in Rust
10
+ 1.85.0, 2025-02-20). Set `edition = "2024"` in `Cargo.toml`. Pin with
11
+ `rust-toolchain.toml`.
12
+ - **Async runtime:** **Tokio** (de-facto standard) — multi-threaded scheduler,
13
+ timers, I/O, sync primitives.
14
+ - **Web:** **Axum** (Tower-based, ergonomic) or Actix-Web (max throughput).
15
+ - **Data:** **SQLx** (async, compile-time-checked SQL) or SeaORM/Diesel for an
16
+ ORM. `serde` + `serde_json` for serialization.
17
+ - **Errors:** `thiserror` for library error enums; `anyhow` for application-level
18
+ error context. Avoid `unwrap()`/`expect()` outside tests and provably-infallible spots.
19
+ - **Testing:** built-in `#[test]` + `assert_*`; `tokio::test` for async;
20
+ `proptest` for property tests; `criterion` for benchmarks; `testcontainers` for
21
+ integration.
22
+ - **Quality:** `cargo clippy -- -D warnings`, `cargo fmt`, `cargo deny` (license/
23
+ advisory), and `cargo audit` for the RustSec advisory DB.
24
+
25
+ ## Idioms (edition 2024)
26
+
27
+ - **Ownership & borrowing** drive the design: prefer owned data at boundaries,
28
+ borrow for reads; reach for `Arc`/`Mutex` only when shared mutable state is
29
+ unavoidable. Favor message passing (`tokio::mpsc`) over shared locks.
30
+ - Model domain states with `enum`s and exhaustive `match`; use the newtype
31
+ pattern for type-safe identifiers.
32
+ - `Result<T, E>` + the `?` operator for fallible flows; convert errors with
33
+ `From`/`thiserror`. Use `Option` combinators (`map`, `and_then`, `ok_or`).
34
+ - **Async closures** (`async || {}`) are stable as of edition 2024 — use them for
35
+ combinator-style async code.
36
+ - `unsafe` only behind a safe, documented abstraction with an explicit invariant
37
+ comment; edition 2024 requires `unsafe extern` blocks and `unsafe` attributes.
38
+
39
+ ## Project structure
40
+
41
+ ```
42
+ Cargo.toml [workspace] for multi-crate; edition = "2024"
43
+ src/
44
+ main.rs | lib.rs binary vs library crate root
45
+ domain/ pure types + logic (no I/O)
46
+ infra/ db, http clients, adapters
47
+ api/ axum routers/handlers
48
+ tests/ integration tests (separate crate)
49
+ benches/ criterion benchmarks
50
+ ```
51
+
52
+ Split a workspace into a `lib` crate (testable core) + thin `bin` crate.
53
+
54
+ ## Performance & ops
55
+
56
+ - Build with `--release`; tune `[profile.release]` (`lto = "thin"`,
57
+ `codegen-units = 1`, `panic = "abort"` for smallest/fastest binaries).
58
+ - Profile before optimizing (`cargo flamegraph`, `perf`); avoid premature
59
+ `clone()`; prefer borrowing and `&str`/`&[T]` in hot paths.
60
+ - Observe with `tracing` + `tracing-opentelemetry`; structured spans over `println!`.
61
+
62
+ ## Common pitfalls
63
+
64
+ - Fighting the borrow checker by sprinkling `clone()`/`Arc<Mutex<…>>` — usually a
65
+ design smell; restructure ownership instead.
66
+ - Blocking calls inside async tasks — use `tokio::task::spawn_blocking`.
67
+ - `.unwrap()` in library/production code; panics across FFI boundaries.
68
+ - Holding a `MutexGuard` across an `.await` (can deadlock) — drop it first.
69
+
70
+ ## Sources (verified 2026-06-10)
71
+ - Rust 1.85.0 + 2024 edition announcement: <https://blog.rust-lang.org/2025/02/20/Rust-1.85.0/>
72
+ - Rust 2024 edition guide: <https://doc.rust-lang.org/edition-guide/rust-2024/index.html>
73
+ - RustSec advisory DB (`cargo audit`): <https://rustsec.org/>
@@ -0,0 +1,177 @@
1
+ # Guide: Compliance & Audit Logging
2
+ <!-- GDPR, SOC2, HIPAA, and Security Auditing Standards -->
3
+
4
+ ---
5
+
6
+ ## Overview
7
+
8
+ Compliance is not just about checking boxes; it's about **traceability** and **privacy**. This guide defines how to implement audit logging, handle PII (Personally Identifiable Information), and meet regulatory requirements (GDPR, CCPA, SOC2, HIPAA) across our tech stacks.
9
+
10
+ ---
11
+
12
+ ## 1. The Audit Log Standard
13
+
14
+ Every mutation of regulated data MUST be logged. Identifying *who* did *what* to *whom* and *when*.
15
+
16
+ ### The 5 Ws of Audit Logging
17
+ 1. **Who:** `actor_id` (User UUID, Service Account, or API Key ID)
18
+ 2. **What:** `action` (CREATE, UPDATE, DELETE, VIEW, EXPORT)
19
+ 3. **When:** `timestamp` (ISO 8601 UTC)
20
+ 4. **Where:** `ip_address`, `user_agent`, `resource_id` (Target entity)
21
+ 5. **Why:** `context` (Request ID, Reason code)
22
+
23
+ ### Audit Log Schema (JSON)
24
+
25
+ ```json
26
+ {
27
+ "timestamp": "2023-10-27T10:00:00Z",
28
+ "event_id": "evt_123456789",
29
+ "actor": {
30
+ "id": "usr_987654321",
31
+ "type": "user",
32
+ "ip": "203.0.113.1",
33
+ "email": "alice@example.com"
34
+ },
35
+ "action": "user.password_reset",
36
+ "target": {
37
+ "id": "usr_987654321",
38
+ "type": "user"
39
+ },
40
+ "changes": {
41
+ "prev": null,
42
+ "next": null // Never log secrets/passwords!
43
+ },
44
+ "metadata": {
45
+ "trace_id": "trc_abc123",
46
+ "status": "success"
47
+ }
48
+ }
49
+ ```
50
+
51
+ ---
52
+
53
+ ## 2. GDPR & Privacy Engineering
54
+
55
+ ### PII Classification
56
+ * **Public:** Product names, doc content. -> *No redaction needed.*
57
+ * **Internal:** Internal IDs, non-sensitive configs. -> *Log freely.*
58
+ * **Confidential (PII):** Email, IP, Phone, Name. -> *Mask in app logs, encrypt in DB.*
59
+ * **Restricted (Sensitive PII):** SSN, Passport, Credit Card (PAN), Health Data. -> *Tokenize, strict access control, never log.*
60
+
61
+ ### Data Subject Rights
62
+ * **Right to Access (DSAR):** System must be able to export ALL data for a `user_id` (JSON export).
63
+ * **Right to Verification:** Logs must prove data hasn't been tampered with.
64
+ * **Right to Erasure (RTBF):**
65
+ * **Hard Delete:** Delete row. (Data gone).
66
+ * **Soft Delete:** RESTRICTED method. (Marked `deleted_at`).
67
+ * **Anonymization:** Overwrite PII with `REDACTED`. **Preferred for audit logs.**
68
+ * *Note:* You CANNOT delete Audit Logs for security reasons (legitimate interest), but you MUST anonymize the PII within them if requested and retention period passed.
69
+
70
+ ---
71
+
72
+ ## 3. Implementation Strategies
73
+
74
+ ### Node.js / TypeScript
75
+ **Libraries:** `pino` (logging), `open-telemetry` (tracing)
76
+
77
+ ```typescript
78
+ import pino from 'pino';
79
+
80
+ const auditLogger = pino({
81
+ base: { service: 'user-service' },
82
+ redact: {
83
+ paths: ['email', 'password', 'token'],
84
+ censor: '[REDACTED]'
85
+ }
86
+ });
87
+
88
+ function logAudit(actor: Actor, action: string, target: Entity) {
89
+ auditLogger.info({
90
+ type: 'audit', // Differentiates from debug/app logs
91
+ actor_id: actor.id,
92
+ action,
93
+ target_id: target.id,
94
+ target_type: target.constructor.name
95
+ });
96
+ }
97
+ ```
98
+
99
+ ### Python / FastAPI
100
+ **Libraries:** `structlog` (structured logging)
101
+
102
+ ```python
103
+ import structlog
104
+
105
+ logger = structlog.get_logger()
106
+
107
+ # Middleware for Audit
108
+ async def audit_middleware(request: Request, call_next):
109
+ response = await call_next(request)
110
+ if request.method in ["POST", "PUT", "DELETE"]:
111
+ await logger.info(
112
+ "audit_event",
113
+ actor_id=request.state.user.id,
114
+ action=f"{request.method} {request.url.path}",
115
+ status=response.status_code
116
+ )
117
+ return response
118
+ ```
119
+
120
+ ### PHP / Laravel
121
+ **Libraries:** `spatie/laravel-activitylog`
122
+
123
+ ```php
124
+ activity()
125
+ ->performedOn($order)
126
+ ->causedBy($user)
127
+ ->withProperties(['amount' => 100])
128
+ ->log('Order placed');
129
+
130
+ // In model
131
+ protected $logAttributes = ['status', 'total']; // Only log safe attributes
132
+ protected $logOnlyDirty = true;
133
+ ```
134
+
135
+ ---
136
+
137
+ ## 4. Security Monitoring (SIEM)
138
+
139
+ ### What to Alert On
140
+ 1. **Authentication Failures:** > 5 failures in 1 minute from single IP.
141
+ 2. **Privilege Escalation:** User added to `admin` group.
142
+ 3. **Mass Export:** User exports > 100 records (DLP monitoring).
143
+ 4. **Sensitive Access:** Access to "Break Glass" accounts.
144
+ 5. **Configuration Change:** Production ENV vars changed.
145
+
146
+ ### Log retention (Standard)
147
+ * **App Logs (Debug/Info):** 7-30 days.
148
+ * **Audit Logs (Security):** 1 year (Hot/Cold storage).
149
+ * **Archive:** 6 years (HIPAA/Financial).
150
+
151
+ ---
152
+
153
+ ## 5. Compliance Checklist (Quick Reference)
154
+
155
+ * [ ] **Encryption:** TLS 1.2+ in transit, AES-256 at rest.
156
+ * [ ] **Access Control:** RBAC implemented + MFA for admins.
157
+ * [ ] **Audit Trails:** Immutable logs for all writes.
158
+ * [ ] **Backups:** Encrypted and tested quarterly.
159
+ * [ ] **Vulnerability Scanning:** Automated SAST/DAST in CI/CD.
160
+ * [ ] **Privacy Policy:** Accessible and accurate.
161
+ * [ ] **Incident Response:** Plan tested annually.
162
+
163
+ ---
164
+
165
+ ## Output for Auditor
166
+ When an auditor asks "Show me evidence of Access Control", providing the `core/AUDIT_LOG_TEMPLATE.md` (for Loki/Dev) or the SIEM dashboard screenshots (for Prod) is standard proof.
167
+
168
+ ---
169
+
170
+ ## 6. Relevant Skills
171
+
172
+ | Skill | Purpose |
173
+ |---|---|
174
+ | `access-control` | Implements RBAC/ABAC and Identity Management. |
175
+ | `data-governance` | Enforces Data Classification (PII tags) and Lineage. |
176
+ | `security-audit` | Checks for hardcoded secrets and known vulnerabilities. |
177
+ | `privacy-audit` | Maps PII data flow and checks for GDPR compliance. |
@@ -0,0 +1,57 @@
1
+ # Cost Optimization & FinOps Guide
2
+
3
+ ## Overview
4
+ Financial Operations (FinOps) is the operating model for the cloud, bringing financial accountability to the variable spend model of cloud computing. This guide provides the philosophical and technical strategies to maximize business value from your architecture.
5
+
6
+ ## Principles of FinOps
7
+ 1. **Teams need to collaborate**: Finance, engineering, and product teams must work together in near-real time.
8
+ 2. **Decisions are driven by business value**: Unit economics (e.g., cost per transaction, cost per user) drive decisions, not just aggregate spend.
9
+ 3. **Everyone takes ownership**: Engineers are responsible for the costs their architectures generate.
10
+ 4. **Data must be accessible and timely**: Feedback loops on cost must be immediate to allow for quick corrections.
11
+
12
+ ## Architectural Strategies for Cost Optimization
13
+
14
+ | Strategy | Description | Implementation Examples |
15
+ |---|---|---|
16
+ | **Right-Sizing** | Continuously matching instance types and sizes to workload performance and capacity requirements. | Use predictive scaling; downsize underutilized EC2/RDS instances; utilize ARM-based instances (like Graviton). |
17
+ | **Commitment Discounts** | Utilizing financial instruments for baseline loads. | Reserved Instances (RIs), Savings Plans, committed use discounts. |
18
+ | **Auto-Scaling & Elasticity** | Matching provisioned resources dynamically to actual demand. | Kubernetes HPA (Horizontal Pod Autoscaler), scaling down non-prod environments off-hours. |
19
+ | **Serverless Architectures** | Paying strictly for execution time rather than idle capacity. | Adopting AWS Lambda, Azure Functions, Cloud Run, DynamoDB (On-Demand). |
20
+ | **Storage Tiering** | Moving data to cheaper storage classes based on access frequency. | S3 Lifecycle policies (Standard -> Infrequent Access -> Glacier). |
21
+ | **Spot Instances** | Using surplus compute capacity at steep discounts for fault-tolerant workloads. | Running stateless background workers, CI/CD pipelines, or big-data processing on Spot. |
22
+
23
+ ## The FinOps Lifecycle
24
+ 1. **Inform**: Visibility and allocation. Implement strict resource tagging schemas. Showback/chargeback to specific business units.
25
+ 2. **Optimize**: Identify specific optimizations (rightsizing, spot usage, terminating zombies).
26
+ 3. **Operate**: Automate the FinOps practices. Build continuous checks into the CI/CD pipeline.
27
+
28
+ ## LLM & Agentic Cost Control (the agent's own spend)
29
+
30
+ The largest variable cost of an agentic system is LLM tokens. GABBE controls this with four levers, all enforceable through the platform-control layer (`gabbe budget` / `route` / `forecast`).
31
+
32
+ ### 1. Prompt caching — the highest-leverage lever
33
+ Reusing a stable prompt prefix avoids re-billing it on every call. Sources verified 2026-06-10.
34
+
35
+ - **OpenAI-compatible endpoints (GABBE default):** caching is **automatic** for prefixes ≥ **1,024 tokens** — no code change. Cached input is discounted **~50%** (more on some newer models). Cache hits appear in `usage.prompt_tokens_details.cached_tokens`. Caches expire after ~5–10 min idle (≤1h). (openai.com/index/api-prompt-caching; developers.openai.com/api/docs/guides/prompt-caching)
36
+ - **Anthropic endpoints:** opt in with `cache_control: {"type": "ephemeral"}` (5-min TTL) or `{"ttl": "1h"}`. Cache **write** costs 1.25× (5m)/2× (1h) base input; cache **read** ~**0.1×**. ≤4 breakpoints; verify via `usage.cache_read_input_tokens`. (platform.claude.com/docs/en/build-with-claude/prompt-caching)
37
+ - **Make caching work:** keep the stable content (system prompt, tool list, frozen context) FIRST and byte-identical; put volatile content (timestamps, IDs, the user's question) LAST. Silent cache-busters: `datetime.now()`/UUIDs in the system prompt, unsorted `json.dumps`, per-user IDs in the prefix, changing the tool set mid-session.
38
+ - GABBE accounts for cache hits in `gabbe/budget.py` (cached tokens billed at the cache-read rate), so `gabbe forecast` reflects the real discounted cost.
39
+
40
+ ### 2. Context-window budgeting via `context_cost`
41
+ Every skill declares `context_cost: low | medium | high` (low <2k tokens, medium 2–8k, high >8k). Load the **minimum** skills/guides needed; prefer `low`-cost skills; only pull `high`-cost context when the task demands it. This caps the input tokens an agent pays for per step.
42
+
43
+ ### 3. Model tiering (route cheap → escalate)
44
+ Match model power to task difficulty. `gabbe route` decides LOCAL (free/cheap local model) vs REMOTE (SOTA) by complexity + PII. Reserve the most expensive model for genuinely hard, correctness-critical work; default to the cheapest reliable tier (per the AGENTS.md *Default Cost & Budget Optimization* mandate and CONSTITUTION cost article).
45
+
46
+ ### 4. Batching & off-peak
47
+ For non-latency-sensitive bulk work, async batch APIs run at **−50%** (e.g. Anthropic Message Batches). Schedule large non-interactive runs (audits, migrations, regen) as batches.
48
+
49
+ ### Hard guardrails (never disabled)
50
+ `GABBE_MAX_COST_USD`, token/iteration/wall-time budgets, and hard stops bound a runaway loop regardless of the optimizations above — cost control must never weaken the quality gates, the 10-phase SDLC, or human-in-the-loop escalation.
51
+
52
+ ## Automation & Agentic Checks
53
+ Use the `cost-optimization.skill.md` to autonomously:
54
+ - Generate `COST_OPTIMIZATION_REPORT_TEMPLATE.md`.
55
+ - Analyze IaC (Terraform/CloudFormation) for untagged resources or over-provisioned defaults.
56
+ - Recommend architectural shifts (e.g., "This cron job runs 24/7 on EC2; moving to Serverless framework will save 80%").
57
+ - Audit AI/LLM costs using the [Performant AI Skill](../../skills/coding/performant-ai.skill.md), applying the four LLM levers above.
@@ -0,0 +1,67 @@
1
+ # Development Environments Guide: Local vs. Remote vs. Outer Loop
2
+
3
+ Choosing the right development environment strategy is critical for velocity. In 2025, we have moved beyond "everything on localhost".
4
+
5
+ ## 1. Strategies Overview
6
+
7
+ | Strategy | Where Code Runs | Where Deps Run | Best For | Tools |
8
+ |---|---|---|---|---|
9
+ | **Local Native** | Local OS | Local (Docker) | Simple Microservices, Monoliths | Node, Go, Docker Compose |
10
+ | **Local Container**| DevContainer | Docker | Team Consistency, Onboarding | VS Code DevContainers |
11
+ | **Remote Bridge**| Local OS | Remote K8s | Microservices dependent on Cloud | Telepresence |
12
+ | **Remote Native** | Remote K8s | Remote K8s | Huge Apps, Low-Power Laptops | Okteto, DevSpace, Coder |
13
+
14
+ ## 2. Local Development (Inner Loop)
15
+
16
+ **The Gold Standard**: `Docker Compose Watch`
17
+ - **Why**: It syncs files to running containers *instantly* without rebuilding.
18
+ - **Config**:
19
+ ```yaml
20
+ services:
21
+ web:
22
+ build: .
23
+ develop:
24
+ watch:
25
+ - action: sync
26
+ path: ./web
27
+ target: /app/web
28
+ - action: rebuild
29
+ path: package.json
30
+ ```
31
+
32
+ **DevContainers**:
33
+ - **Why**: "It works on my machine" is solved forever. The IDE definitions *are* the environment.
34
+ - **Pro Tip**: Include your linters and extensions in `devcontainer.json`.
35
+
36
+ ## 3. Remote Development (Hybrid Inner Loop)
37
+
38
+ **When Localhost Fails**:
39
+ - Your app needs 32GB RAM but your laptop has 16GB.
40
+ - You need to talk to 15 downstream microservices.
41
+ - You need proprietary cloud hardware (GPUs).
42
+
43
+ **Telepresence**:
44
+ - Routes traffic from the cluster *to your laptop*.
45
+ - Allows you to debug a service locally while it thinks it's in the cluster.
46
+ - **Command**: `telepresence intercept my-service --port 8080:8080`
47
+
48
+ ## 4. Outer Loop (Deployment)
49
+
50
+ This is the CI/CD world.
51
+
52
+ **Shift Left with Previews**:
53
+ - **Vercel/Railway**: Every Pull Request gets a live URL (`pr-123.myapp.com`).
54
+ - **Value**: QA and Product can test *before* merge.
55
+
56
+ **Infrastructure as Code**:
57
+ - Never change settings in the AWS Console manually.
58
+ - Use **SST** or **Terraform** so your infrastructure is versioned with your code.
59
+
60
+ ## 5. Recommendation Matrix
61
+
62
+ | Scenario | Recommend |
63
+ |---|---|
64
+ | **New Project / MVP** | **Local Native** (Speed is king) |
65
+ | **Team > 5 Devs** | **DevContainers** (Consistency is king) |
66
+ | **Microservices > 10** | **Remote Bridge** (Resources are bottleneck) |
67
+ | **AI / Machine Learning**| **Remote Native** (Need GPUs) |
@@ -0,0 +1,44 @@
1
+ # Developer Workflow & Documentation
2
+
3
+ > **Source Origin**: Distilled from Matteo Collina's workflow skills (`octocat`, `documentation`, `snipgrapher`).
4
+
5
+ This guide standardizes how GABBE agents execute Git operations and format project documentation.
6
+
7
+ ---
8
+
9
+ ## 1. Documentation Framework (Diátaxis)
10
+
11
+ When researching, authoring, or rewriting documentation, strictly adhere to the **Diátaxis** framework, which divides technical documentation into four distinct quadrants. Never mix these concerns in the same file without clear separation.
12
+
13
+ 1. **Tutorials** (Learning-oriented):
14
+ - *Goal*: Allow the newcomer to achieve a basic outcome.
15
+ - *Style*: Step-by-step, pedagogical, conversational. Do not explain *why*, just show *how*.
16
+ 2. **How-To Guides** (Problem-oriented):
17
+ - *Goal*: Help the user solve a specific real-world problem.
18
+ - *Style*: Recipe-like, practical, focused. Assume the user already knows the basics.
19
+ 3. **Reference** (Information-oriented):
20
+ - *Goal*: Accurately describe the machinery (API specs, configs, CLI flags).
21
+ - *Style*: Austere, complete, structured. No explanations or tutorials—just facts.
22
+ 4. **Explanation** (Understanding-oriented):
23
+ - *Goal*: Clarify architecture, design decisions, and underlying concepts.
24
+ - *Style*: Discursive, theoretical, big-picture. (e.g., "Why we chose Fastify over Express").
25
+
26
+ ## 2. Advanced Git & GitHub Operations (Octocat)
27
+
28
+ Agents performing version control must operate as Git/GitHub wizards using both local git and the `gh` CLI.
29
+
30
+ - **Commit Hygiene**: Use Conventional Commits (`feat(scope): message`, `fix(api): message`). Each commit must represent a single logical unit.
31
+ - **Branching Strategy**: Use short-lived feature branches (`feat/name`, `fix/name`, `docs/name`). Never commit directly to `main` without merging via PR.
32
+ - **Rebasing over Merging**: Keep linear histories. Prefer `git pull --rebase` and interactive rebasing to squash fixup commits before opening a PR.
33
+ - **GitHub CLI**: Leverage `gh` for PR creation (`gh pr create`), status checks (`gh pr checks`), and issue tracking (`gh issue list`).
34
+
35
+ ## 3. Visual Aids & Snippets (Snipgrapher)
36
+
37
+ When preparing documentation intended for presentation or social reading (like blog posts or internal showcase PRs):
38
+ - Use polished code snippet graphics (like those generated by `snipgrapher`).
39
+ - Ensure syntax highlighting perfectly matches the provided code.
40
+ - Maintain visual contrast and accessibility.
41
+ - Keep the code snippet concise and focused strictly on the subject matter being highlighted.
42
+
43
+ ---
44
+ *For AI Agents: Ensure all documentation updates generated explicitly identify which Diátaxis quadrant they belong to. All git operations must comply with the Octocat standards prior to SDLC S08 (Review).*
@@ -0,0 +1,252 @@
1
+ # GABBE CLI Workflows Reference (Optional)
2
+
3
+ > **For Agents**: This guide documents the optional `gabbe` CLI commands, platform controls, and recommended workflows. **The CLI is NOT required** — agents can fully operate via markdown inference without it.
4
+
5
+ ## Integration Modes
6
+
7
+ The GABBE CLI can run in three modes, configured during `python3 scripts/init.py`:
8
+
9
+ | Mode | Who Uses It | How |
10
+ |---|---|---|
11
+ | **Disabled** (default) | Nobody | CLI not installed. Agents use markdown inference only. |
12
+ | **Manual** | Human only | Human runs `gabbe` commands directly when needed. Agents are NOT required to use them but may reference them. |
13
+ | **MCP Enforced** | Agent via MCP | All `gabbe` commands flow through `gabbe serve-mcp`. Agents MUST use the MCP JSON-RPC `tools/call` interface. Direct CLI calls are not used by agents. |
14
+
15
+ > [!NOTE]
16
+ > When **Disabled**, the GABBE CLI Workflows section is removed from `AGENTS.md` during project initialization. Agents will not see CLI commands and operate purely via the markdown-based skill/guide system.
17
+
18
+ ---
19
+
20
+ ## Quick Reference: All CLI Commands
21
+
22
+ | Command | Purpose | Requires API Key |
23
+ |---|---|---|
24
+ | `gabbe init` | Initialize DB (`project/state.db`) | No |
25
+ | `gabbe db --init` | Alias for `gabbe init` | No |
26
+ | `gabbe sync` | Bidirectional sync: `project/TASKS.md` ↔ SQLite | No |
27
+ | `gabbe status` | Project dashboard (phase, tasks, progress) | No |
28
+ | `gabbe verify` | Integrity checks (files, lint, tests, security) | No |
29
+ | `gabbe route "<prompt>"` | Route prompt to LOCAL or REMOTE LLM | No |
30
+ | `gabbe brain activate` | Active Inference Loop (observe → decide → act) | **Yes** |
31
+ | `gabbe brain evolve --skill <name>` | Evolutionary Prompt Optimization | **Yes** |
32
+ | `gabbe brain heal` | Self-Healing Watchdog | No |
33
+ | `gabbe forecast` | Strategic cost/token forecast | No |
34
+ | `gabbe serve-mcp` | Zero-dependency MCP JSON-RPC server | No |
35
+ | `gabbe runs [--status S] [--limit N]` | List recent agent runs | No |
36
+ | `gabbe audit <run-id> [--format json]` | Structured audit trace for a run | No |
37
+ | `gabbe replay <run-id> [--from-step N]` | Deterministic replay from checkpoints | No |
38
+ | `gabbe resume <run-id>` | Resume a paused/escalated run | No |
39
+
40
+ ### Global Flags
41
+ - `--version` — Print version and exit
42
+ - `--debug` — Enable DEBUG logging and full stack traces
43
+ - `--help` / `-h` — Help for any command
44
+
45
+ ---
46
+
47
+ ## Standard Workflows
48
+
49
+ ### 1. Project Setup (First Time)
50
+
51
+ ```bash
52
+ # Step 1: Generate context configs (interactive wizard)
53
+ python3 scripts/init.py
54
+
55
+ # Step 2: Initialize the database
56
+ gabbe init
57
+
58
+ # Step 3: Verify everything is set up
59
+ gabbe verify
60
+ ```
61
+
62
+ **What happens**: Creates `project/state.db` with all required tables (`tasks`, `runs`, `audit_spans`, `checkpoints`, `pending_escalations`, `genes`, `forecast_snapshots`, `pricing_registry`, `budget_snapshots`).
63
+
64
+ ---
65
+
66
+ ### 2. Daily Development Workflow
67
+
68
+ ```bash
69
+ # Check project status
70
+ gabbe status
71
+
72
+ # Sync tasks (after manual TASKS.md edits)
73
+ gabbe sync
74
+
75
+ # Run integrity checks
76
+ gabbe verify
77
+
78
+ # Route a prompt through the cost-effective router
79
+ gabbe route "Fix the typo in utils.py"
80
+ ```
81
+
82
+ **Sync behaviour**:
83
+ - File newer → imports tasks from `project/TASKS.md` into DB
84
+ - DB newer → exports tasks from DB to `project/TASKS.md`
85
+ - Uses `<!-- GABBE:TASKS:START -->` / `<!-- GABBE:TASKS:END -->` markers
86
+
87
+ ---
88
+
89
+ ### 3. Brain Mode Workflow (Requires `GABBE_API_KEY`)
90
+
91
+ ```bash
92
+ # Activate the Active Inference Loop
93
+ gabbe brain activate
94
+
95
+ # Optimize a skill's prompt via EPO
96
+ gabbe brain evolve --skill tdd-cycle
97
+
98
+ # Run self-healing checks (no API key needed)
99
+ gabbe brain heal
100
+ ```
101
+
102
+ **Brain activate flow**: Observe tasks → Send state to LLM → Receive recommended action → Record run in `runs` table → Record audit spans.
103
+
104
+ ---
105
+
106
+ ### 4. Observability & Debugging Workflow
107
+
108
+ ```bash
109
+ # See cost/token forecast
110
+ gabbe forecast
111
+
112
+ # List recent runs
113
+ gabbe runs
114
+ gabbe runs --status completed
115
+ gabbe runs --status error --limit 5
116
+
117
+ # Inspect a specific run
118
+ gabbe audit <run-id>
119
+ gabbe audit <run-id> --format json
120
+
121
+ # Replay a past run from checkpoints
122
+ gabbe replay <run-id>
123
+ gabbe replay <run-id> --from-step 3
124
+
125
+ # Resume a paused run
126
+ gabbe resume <run-id>
127
+ ```
128
+
129
+ ---
130
+
131
+ ### 5. MCP Server Workflow
132
+
133
+ ```bash
134
+ # Start the MCP JSON-RPC server (stdin/stdout)
135
+ gabbe serve-mcp
136
+ ```
137
+
138
+ **Protocol**: JSON-RPC 2.0 over stdin/stdout. Methods: `initialize`, `tools/list`, `tools/call`.
139
+
140
+ **Security controls**:
141
+ - `GABBE_MCP_TOKEN` — If set, clients must send this in `initialize` params
142
+ - `GABBE_MCP_ALLOWED_COMMANDS` — Comma-separated allowlist (e.g., `pytest,ruff,bandit`)
143
+ - All commands run with `shell=False` (no injection)
144
+
145
+ ---
146
+
147
+ ## Platform Controls (Active During All Runs)
148
+
149
+ Every `gabbe brain activate` and `gabbe serve-mcp` session wraps execution in a `RunContext` with the following controls:
150
+
151
+ ### Budget Enforcement
152
+ | Dimension | Env Var | Default |
153
+ |---|---|---|
154
+ | Tokens | `GABBE_MAX_TOKENS_PER_RUN` | 100,000 |
155
+ | Tool calls | `GABBE_MAX_TOOL_CALLS_PER_RUN` | 50 |
156
+ | Iterations | `GABBE_MAX_ITERATIONS` | 25 |
157
+ | Wall time | `GABBE_MAX_WALL_TIME` | 300s |
158
+ | Cost (USD) | `GABBE_MAX_COST_USD` | $5.00 |
159
+
160
+ ### Hard Stops
161
+ Absolute guards that **cannot** be loosened at runtime. Raises `MaxIterationsExceeded`, `MaxDepthExceeded`, or `TimeoutExceeded`.
162
+
163
+ ### Policy Engine (`project/policies.yml`)
164
+ ```yaml
165
+ version: "1"
166
+ tools:
167
+ allowed: ["call_llm", "run_command"]
168
+ denied: ["run_security_scan"]
169
+ roles:
170
+ brain-mode: ["call_llm"]
171
+ external_agent: ["run_command"]
172
+ content_safety:
173
+ enabled: true
174
+ ```
175
+ - **Deny-first**: First policy that denies wins
176
+ - **Secure default**: No policy file → deny-all
177
+
178
+ ### Tool Gateway
179
+ All tool execution flows through `ToolGateway.execute()`:
180
+ 1. Tool registration check → 2. Policy evaluation → 3. Budget check → 4. Rate limiting → 5. Circuit breaker → 6. Schema validation → 7. Handler execution → 8. Audit span
181
+
182
+ ### Escalation Handler
183
+
184
+ | Mode | Env `GABBE_ESCALATION_MODE` | Behaviour |
185
+ |---|---|---|
186
+ | `cli` | Interactive prompt (approve/reject/edit) | Continues after response |
187
+ | `file` | Records to DB, raises `EscalationPaused` | Resume with `gabbe resume` |
188
+ | `silent` | Auto-rejects | Safe for CI/CD |
189
+
190
+ **Triggers**: `BUDGET_EXHAUSTED`, `REPEATED_TOOL_FAILURE`, `AMBIGUOUS_DECISION`, `POLICY_VIOLATION`, `MAX_ITERATIONS`
191
+
192
+ ### Audit Trail
193
+ Every event recorded as spans in `audit_spans` table. Inspect with `gabbe audit <run-id>`.
194
+
195
+ ### Checkpoints & Replay
196
+ State snapshots saved to `checkpoints` table. Replay with `gabbe replay <run-id>`.
197
+
198
+ ---
199
+
200
+ ## Environment Variables (Complete)
201
+
202
+ | Variable | Default | Purpose |
203
+ |---|---|---|
204
+ | `GABBE_API_URL` | `https://api.openai.com/v1/...` | LLM endpoint |
205
+ | `GABBE_API_KEY` | *(required for LLM)* | Bearer token |
206
+ | `GABBE_API_MODEL` | `gpt-4o` | Model name |
207
+ | `GABBE_LLM_TEMPERATURE` | `0.7` | Sampling temperature |
208
+ | `GABBE_LLM_TIMEOUT` | `30` | HTTP timeout (seconds) |
209
+ | `GABBE_LLM_MAX_RETRIES` | `3` | LLM retry attempts |
210
+ | `GABBE_ROUTE_THRESHOLD` | `50` | Complexity → LOCAL/REMOTE |
211
+ | `GABBE_LOG_LEVEL` | `INFO` | Logging level |
212
+ | `GABBE_MAX_COST_USD` | `5.0` | Cost budget per run |
213
+ | `GABBE_MAX_TOKENS_PER_RUN` | `100000` | Token limit per run |
214
+ | `GABBE_MAX_TOOL_CALLS_PER_RUN` | `50` | Tool calls per run |
215
+ | `GABBE_MAX_ITERATIONS` | `25` | Brain loop iterations |
216
+ | `GABBE_MAX_WALL_TIME` | `300` | Wall time (seconds) |
217
+ | `GABBE_MAX_RECURSION_DEPTH` | `5` | Recursion depth |
218
+ | `GABBE_POLICY_FILE` | `project/policies.yml` | Policy YAML path |
219
+ | `GABBE_ESCALATION_MODE` | `cli` | `cli` / `file` / `silent` |
220
+ | `GABBE_OTEL_ENABLED` | `false` | OpenTelemetry |
221
+ | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Verify command timeout |
222
+ | `GABBE_MCP_TOKEN` | *(unset)* | MCP auth token |
223
+ | `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | MCP command allowlist |
224
+
225
+ ---
226
+
227
+ ## Database Tables (Schema v3)
228
+
229
+ | Table | Purpose |
230
+ |---|---|
231
+ | `tasks` | Task tracking (title, status, timestamps) |
232
+ | `runs` | One row per agent execution |
233
+ | `audit_spans` | Per-step spans with token/cost data |
234
+ | `budget_snapshots` | Periodic budget state per run |
235
+ | `checkpoints` | State snapshots for replay |
236
+ | `pending_escalations` | Human-review queue |
237
+ | `genes` | EPO evolutionary prompt storage |
238
+ | `forecast_snapshots` | Cost/token projections |
239
+ | `pricing_registry` | Per-model token pricing |
240
+
241
+ ---
242
+
243
+ ## Agent Rules
244
+
245
+ 1. **Always run `gabbe init` before any other command** in a new project.
246
+ 2. **Run `gabbe sync` after editing `project/TASKS.md`** to keep DB in sync.
247
+ 3. **Run `gabbe verify` before committing** to catch integrity issues.
248
+ 4. **Use `gabbe route` before making LLM calls** to determine LOCAL vs REMOTE.
249
+ 5. **Check `gabbe runs` and `gabbe audit`** after brain sessions for cost visibility.
250
+ 6. **Respect budget limits** — all runs are bounded by token/cost/time limits.
251
+ 7. **Handle escalations** — when `BUDGET_EXHAUSTED` or `POLICY_VIOLATION` occurs, the run pauses for human review.
252
+ 8. **Use `gabbe forecast`** to project remaining work before starting large tasks.