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,527 @@
1
+ # GABBE CLI Reference (experimental)
2
+
3
+ > **Audience:** operators of the `gabbe` CLI. **Scope:** every command, flag, and environment variable.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install -e ".[dev]" # development / editable
9
+ pip install . # production
10
+ ```
11
+
12
+ Entry point: `gabbe` (defined in `pyproject.toml → [project.scripts]`)
13
+
14
+ ---
15
+
16
+ ## Environment Variables
17
+
18
+ | Variable | Default | Description |
19
+ |---|---|---|
20
+ | `GABBE_API_URL` | `https://api.openai.com/v1/chat/completions` | OpenAI-compatible endpoint |
21
+ | `GABBE_API_KEY` | *(required for LLM features)* | Bearer token for the LLM API |
22
+ | `GABBE_API_MODEL` | `gpt-4o` | Model name sent in API requests |
23
+ | `GABBE_LLM_TEMPERATURE` | `0.7` | Sampling temperature (0.0–1.0) |
24
+ | `GABBE_LLM_TIMEOUT` | `30` | HTTP timeout for LLM calls (seconds) |
25
+ | `GABBE_ROUTE_THRESHOLD` | `50` | Complexity score above which a prompt routes REMOTE |
26
+ | `GABBE_LLM_MAX_RETRIES`| `3` | (Internal) Number of retry attempts for LLM calls |
27
+ | `GABBE_LLM_CACHE` | `false` | Opt-in: cache identical LLM calls locally (0 tokens on a hit; only for deterministic calls) |
28
+ | `GABBE_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
29
+ | `GABBE_MAX_COST_USD` | `5.0` | Maximum cost (USD) budget per run |
30
+ | `GABBE_MAX_TOKENS_PER_RUN` | `100000` | Maximum token limit per run |
31
+ | `GABBE_MAX_TOOL_CALLS_PER_RUN` | `50` | Maximum tool calls per run |
32
+ | `GABBE_MAX_ITERATIONS` | `25` | Maximum brain loop iterations per run |
33
+ | `GABBE_MAX_WALL_TIME` | `300` | Maximum wall-clock time per run (seconds) |
34
+ | `GABBE_MAX_RECURSION_DEPTH` | `5` | Maximum agent recursion depth |
35
+ | `GABBE_MAX_RETRIES_PER_TOOL` | `3` | Maximum retries per tool call |
36
+ | `GABBE_SUBPROCESS_TIMEOUT` | `300` | Timeout for verify shell commands (seconds) |
37
+ | `GABBE_AUTONOMY` | `hybrid` | Autonomy mode: `manual`, `hybrid`, or `autonomous` (env > project config > default; invalid values warn and fall back to `hybrid`) |
38
+ | `GABBE_POLICY_FILE` | `project/policies.yml` | Path to YAML policy file for tool access control |
39
+ | `GABBE_ESCALATION_MODE` | `cli` | Escalation mode: `cli` (interactive), `file` (pause), `silent` (auto-reject) |
40
+ | `GABBE_OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
41
+ | `GABBE_OTEL_CAPTURE_CONTENT` | `false` | Opt-in: capture prompt/response content on GenAI spans (off by default — content may contain PII/secrets) |
42
+ | `GABBE_MCP_TOKEN` | *(unset)* | If set, MCP clients must send this token in `initialize` params (constant-time compared). Leave unset to disable authentication. |
43
+ | `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | Comma-separated list of allowed executables for `run_command` via MCP, matched by exact command or basename (a directory entry is **not** a wildcard). When unset, all commands are blocked. Example: `pytest,ruff,bandit` |
44
+ | `GABBE_MCP_INSECURE` | *(unset)* | Set to `1`/`true` to restore legacy permissive MCP mode (no auth, all commands allowed). Trusted, isolated hosts only. |
45
+ | `GABBE_MCP_COMMAND_TIMEOUT` | `300` | Timeout (seconds) for a command executed via the MCP `run_command` tool |
46
+
47
+ ---
48
+
49
+ ## Global Flags
50
+
51
+ | Flag | Description |
52
+ |---|---|
53
+ | `--help` / `-h` | Show help for the command or sub-command and exit |
54
+ | `--version` | Print the installed version (`gabbe x.y.z`) and exit |
55
+ | `--debug` | Enable DEBUG-level logging and full stack traces |
56
+
57
+ ---
58
+
59
+ ## Commands
60
+
61
+ ### `gabbe init`
62
+
63
+ Initialize (or migrate) the SQLite database in `project/state.db`.
64
+
65
+ ```bash
66
+ gabbe init
67
+ ```
68
+
69
+ **Exit codes:**
70
+ - `0` — success
71
+ - `1` — configuration or filesystem error
72
+
73
+ ---
74
+
75
+ ### `gabbe db --init`
76
+
77
+ Alias for `gabbe init`.
78
+
79
+ ```bash
80
+ gabbe db --init
81
+ ```
82
+
83
+ ---
84
+
85
+ ### `gabbe sync`
86
+
87
+ Bidirectional sync between `project/TASKS.md` and the SQLite `tasks` table.
88
+
89
+ **Logic:**
90
+ 1. **Marker-Based Sync**: Looks for `<!-- GABBE:TASKS:START -->` and `<!-- GABBE:TASKS:END -->`.
91
+ - If found, ONLY updates the content between these markers.
92
+ - Preserves all other content (notes, headers) in `project/TASKS.md`.
93
+ 2. **Legacy Fallback**: If no markers are found, it behaves as a full-file overwrite (or wraps content in markers on first export).
94
+ 3. **Conflict Resolution**:
95
+ - File newer than DB → Import tasks between markers.
96
+ - DB newer than file → Export tasks between markers (atomic write).
97
+
98
+ ```bash
99
+ gabbe sync
100
+ ```
101
+
102
+ ---
103
+
104
+ ### `gabbe status`
105
+
106
+ Display the project dashboard: phase, task counts, progress bar.
107
+
108
+ The phase is read from `project_state` (key `current_phase`).
109
+ Set it with:
110
+
111
+ ```bash
112
+ sqlite3 project/state.db "INSERT OR REPLACE INTO project_state (key, value) VALUES ('current_phase', 'S03_ARCH');"
113
+ ```
114
+
115
+ ---
116
+
117
+ ### `gabbe verify [--chaos]`
118
+
119
+ Run project integrity checks:
120
+
121
+ 1. Check required files exist (`agents/AGENTS.md`, `agents/CONSTITUTION.md`, `project/TASKS.md`)
122
+ 2. Warn if `project/state.db` is missing
123
+ 3. Read `## Commands` section of `agents/AGENTS.md` and run `test`, `lint`, `security_scan` commands
124
+
125
+ `--chaos` instead runs fault-injection self-checks (Track B): it injects faults and
126
+ asserts GABBE's resilience mechanisms recover safely — the MCP tool stays
127
+ fail-closed without an allowlist, the hard-stop caps a runaway loop, PII forces
128
+ LOCAL routing, and escalation degrades gracefully under an injected DB fault.
129
+ Read-only; exits non-zero if any self-check fails.
130
+
131
+ **`AGENTS.md` Commands section format:**
132
+ ```markdown
133
+ ## Commands
134
+ test: pytest gabbe/tests/ scripts/tests/ -v
135
+ lint: ruff check .
136
+ security_scan: bandit -r gabbe/
137
+ ```
138
+
139
+ Only lines inside `## Commands` (until the next `##` heading) are parsed.
140
+
141
+ **Parsing rules:**
142
+ - Section header matching is **case-insensitive** (`## Commands` and `## commands` both work)
143
+ - Supported command keys: `test`, `lint`, `security_scan`, `build`
144
+ - Values are stripped of surrounding single/double quotes
145
+ - Commands are executed with `shell=False` (no shell expansion)
146
+
147
+ **Exit codes:** `0` = all passed, `1` = at least one check failed
148
+
149
+ ---
150
+
151
+ ### `gabbe route <prompt>`
152
+
153
+ Route a prompt to LOCAL or REMOTE LLM based on complexity and PII detection.
154
+
155
+ ```bash
156
+ gabbe route "Fix the typo in utils.py"
157
+ gabbe route "Architect a new distributed caching layer"
158
+ ```
159
+
160
+ **PII detection:** Email addresses, US phone numbers, SSNs, credit card numbers,
161
+ and patterns like `password: ...` or `api_key=...` force LOCAL routing.
162
+
163
+ **Output:** `LOCAL` or `REMOTE`
164
+
165
+ ---
166
+
167
+ ### `gabbe brain activate`
168
+
169
+ Run one cycle of the Active Inference Loop:
170
+ 1. Observe task statistics from DB
171
+ 2. Send state description to LLM
172
+ 3. Print recommended next action
173
+
174
+ Requires `GABBE_API_KEY`.
175
+
176
+ ---
177
+
178
+ ### `gabbe brain evolve --skill <name>`
179
+
180
+ Evolutionary Prompt Optimization for a skill:
181
+ 1. Fetch current best gene from `genes` table
182
+ 2. Ask LLM to mutate/improve the prompt
183
+ 3. Store new generation in `genes` table
184
+
185
+ ```bash
186
+ gabbe brain evolve --skill code-review
187
+ ```
188
+
189
+ Requires `GABBE_API_KEY`.
190
+
191
+ ---
192
+
193
+ ### `gabbe brain heal`
194
+
195
+ Run the Self-Healing Watchdog:
196
+ 1. Verify DB connectivity
197
+ 2. Check required project files exist
198
+ 3. Print health report
199
+
200
+ Does **not** require `GABBE_API_KEY`.
201
+
202
+ ---
203
+
204
+ ### `gabbe forecast`
205
+
206
+ Run a strategic forecast evaluating remaining tasks and projecting future costs and token usage based on historical run data. Captures a snapshot to `forecast_snapshots`.
207
+
208
+ ---
209
+
210
+ ### `gabbe serve-mcp`
211
+
212
+ Starts a zero-dependency JSON-RPC Model Context Protocol (MCP) server on `stdin`/`stdout`. It wraps internal tools in the `ToolGateway` for strict budget, role, and rate-limit enforcement. Includes telemetry and context tracing.
213
+
214
+ ---
215
+
216
+ ## Platform Control Layer
217
+
218
+ 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).
219
+
220
+ ---
221
+
222
+ ## Database Schema
223
+
224
+ Located at `project/state.db` (SQLite 3).
225
+
226
+ ### `schema_version`
227
+ | Column | Type | Description |
228
+ |---|---|---|
229
+ | `version` | INTEGER | Current schema version (incremented on migrations) |
230
+
231
+ ### `tasks`
232
+ | Column | Type | Description |
233
+ |---|---|---|
234
+ | `id` | INTEGER PK | Auto-increment ID |
235
+ | `title` | TEXT NOT NULL UNIQUE | Task description (unique — used as upsert key) |
236
+ | `status` | TEXT | `TODO`, `IN_PROGRESS`, or `DONE` |
237
+ | `tags` | TEXT | Optional comma-separated tags |
238
+ | `created_at` | DATETIME | Creation timestamp (UTC) |
239
+ | `updated_at` | DATETIME | Last modification timestamp (UTC) |
240
+
241
+ ### `project_state`
242
+ | Column | Type | Description |
243
+ |---|---|---|
244
+ | `key` | TEXT PK | State key (e.g., `current_phase`) |
245
+ | `value` | TEXT | State value |
246
+ | `updated_at` | DATETIME | Last modification timestamp |
247
+
248
+ ### `events`
249
+ | Column | Type | Description |
250
+ |---|---|---|
251
+ | `id` | INTEGER PK | Auto-increment ID |
252
+ | `timestamp` | DATETIME | Event time |
253
+ | `actor` | TEXT | Who generated the event |
254
+ | `action` | TEXT | Action type |
255
+ | `message` | TEXT | Human-readable description |
256
+ | `context_summary` | TEXT | Optional context snapshot |
257
+
258
+ ### `genes`
259
+ | Column | Type | Description |
260
+ |---|---|---|
261
+ | `id` | INTEGER PK | Auto-increment ID |
262
+ | `skill_name` | TEXT | Skill this gene belongs to |
263
+ | `prompt_content` | TEXT | Prompt text |
264
+ | `success_rate` | REAL | Score 0.0–1.0 (updated externally) |
265
+ | `generation` | INTEGER | Evolution generation counter |
266
+ | `created_at` | DATETIME | Creation timestamp |
267
+
268
+ ### `pricing_registry` (v3)
269
+ | Column | Type | Description |
270
+ |---|---|---|
271
+ | `model_id` | TEXT PK | LLM Model Identifier (e.g. gpt-4o) |
272
+ | `input_token_price` | REAL | Cost per input token |
273
+ | `output_token_price` | REAL | Cost per output token |
274
+ | `reasoning_token_price` | REAL | Cost per reasoning token |
275
+ | `cache_creation_price` | REAL | Cost per cache token |
276
+ | `cache_read_price` | REAL | Cost per cache read token |
277
+
278
+ ### `runs` (v3 updates)
279
+ | Column | Type | Description |
280
+ |---|---|---|
281
+ | `id` | TEXT PK | Run ID (UUID) |
282
+ | `command` | TEXT | CLI command executed |
283
+ | `started_at` | DATETIME | Run start timestamp |
284
+ | `ended_at` | DATETIME | Run end timestamp (NULL while running) |
285
+ | `status` | TEXT | `running`, `completed`, `error`, `budget_exceeded`, `escalated` |
286
+ | `stop_reason` | TEXT | Human-readable reason if run was stopped early |
287
+ | `initiator` | TEXT | Initiator type: `cli`, `mcp`, or `replay` |
288
+ | `agent_persona` | TEXT | Active agent persona name (if set) |
289
+ | `total_tokens_used` | INTEGER | Aggregated token count |
290
+ | `total_cost_usd` | REAL | Aggregated cost in USD |
291
+ | `config_snapshot` | TEXT | JSON snapshot of config at run start |
292
+
293
+ ### `audit_spans` (v3)
294
+ | Column | Type | Description |
295
+ |---|---|---|
296
+ | `id` | INTEGER PK | Span auto-increment ID |
297
+ | `run_id` | TEXT | FK to `runs.id` |
298
+ | `span_id` | TEXT | Unique span identifier |
299
+ | `parent_span_id` | TEXT | Parent span for nested traces |
300
+ | `timestamp` | DATETIME | Span start time |
301
+ | `event_type` | TEXT | e.g. `tool_call`, `llm_call` |
302
+ | `node_name` | TEXT | Logical node / tool name |
303
+ | `input_data` | TEXT | JSON-serialised input |
304
+ | `output_data` | TEXT | JSON-serialised output |
305
+ | `reasoning_content` | TEXT | Chain-of-Thought content |
306
+ | `model_name` | TEXT | Model used for LLM spans |
307
+ | `prompt_tokens` | INTEGER | Input token count |
308
+ | `completion_tokens` | INTEGER | Output token count |
309
+ | `reasoning_tokens` | INTEGER | Reasoning token count (o-series) |
310
+ | `cache_hit_tokens` | INTEGER | Cached prompt tokens |
311
+ | `cost_usd` | REAL | Cost of this span in USD |
312
+ | `duration_ms` | REAL | Wall-clock execution time (ms) |
313
+ | `status` | TEXT | `ok` or `error` |
314
+ | `metadata` | TEXT | JSON extra fields |
315
+
316
+ ### `budget_snapshots` (v3)
317
+ | Column | Type | Description |
318
+ |---|---|---|
319
+ | `id` | INTEGER PK | Auto-increment ID |
320
+ | `run_id` | TEXT | FK to `runs.id` |
321
+ | `step` | INTEGER | Brain loop step number |
322
+ | `tokens_used` | INTEGER | Tokens used at this snapshot |
323
+ | `tool_calls_used` | INTEGER | Tool calls used at this snapshot |
324
+ | `wall_time_sec` | REAL | Wall time elapsed (seconds) |
325
+ | `iterations` | INTEGER | Iterations completed at this snapshot |
326
+ | `timestamp` | DATETIME | Snapshot timestamp |
327
+
328
+ ### `checkpoints` (v3)
329
+ | Column | Type | Description |
330
+ |---|---|---|
331
+ | `id` | INTEGER PK | Auto-increment ID |
332
+ | `run_id` | TEXT | FK to `runs.id` |
333
+ | `step` | INTEGER | Step number when checkpoint was saved |
334
+ | `node_name` | TEXT | Logical node (e.g., `observe`, `plan`) |
335
+ | `state_snapshot` | TEXT | JSON-serialised state at this checkpoint |
336
+ | `policy_version` | TEXT | Policy version active at checkpoint time |
337
+ | `parent_checkpoint_id` | INTEGER | FK to previous checkpoint (chain) |
338
+ | `created_at` | DATETIME | Checkpoint creation timestamp |
339
+
340
+ ### `pending_escalations` (v3)
341
+ | Column | Type | Description |
342
+ |---|---|---|
343
+ | `id` | INTEGER PK | Auto-increment ID |
344
+ | `run_id` | TEXT | FK to `runs.id` |
345
+ | `step` | INTEGER | Step number that triggered escalation |
346
+ | `trigger` | TEXT | `EscalationTrigger` value (e.g., `BUDGET_EXHAUSTED`) |
347
+ | `context` | TEXT | JSON context dict at time of escalation |
348
+ | `status` | TEXT | `pending`, `approved`, `rejected`, or `edited` |
349
+ | `response` | TEXT | Human response/notes (if approved or edited) |
350
+ | `created_at` | DATETIME | When escalation was created |
351
+ | `resolved_at` | DATETIME | When escalation was resolved (NULL if pending) |
352
+
353
+ ### `forecast_snapshots` (v3)
354
+ | Column | Type | Description |
355
+ |---|---|---|
356
+ | `id` | INTEGER PK | Auto-increment ID |
357
+ | `run_id` | TEXT | FK to `runs.id` |
358
+ | `step` | INTEGER | Forecast step |
359
+ | `projected_tokens` | INTEGER | Projected total token usage |
360
+ | `projected_cost` | REAL | Projected total cost (USD) |
361
+ | `current_error_rate` | REAL | Error rate at time of forecast |
362
+ | `timestamp` | DATETIME | Forecast snapshot timestamp |
363
+
364
+ ---
365
+
366
+ ### `gabbe runs [--status STATUS] [--limit N]`
367
+
368
+ List recent agent runs from the `runs` table.
369
+
370
+ ```bash
371
+ gabbe runs # all runs, newest first (max 20)
372
+ gabbe runs --status completed # only completed runs
373
+ gabbe runs --status budget_exceeded # runs stopped by budget
374
+ gabbe runs --limit 5 # show only 5 rows
375
+ ```
376
+
377
+ **Status values:** `running`, `completed`, `error`, `budget_exceeded`, `escalated`
378
+
379
+ ---
380
+
381
+ ### `gabbe audit <run-id> [--format json|table]`
382
+
383
+ Display the structured audit trace for a run.
384
+
385
+ ```bash
386
+ gabbe audit abc123-... # table view (default)
387
+ gabbe audit abc123-... --format json # full JSON trace
388
+ ```
389
+
390
+ Reads from `audit_spans` table. Columns shown in table mode: event type, node name, duration (ms), cost (USD), status.
391
+
392
+ ---
393
+
394
+ ### `gabbe replay <run-id> [--from-step N]`
395
+
396
+ Replay a past run from its checkpoints, substituting recorded tool outputs.
397
+
398
+ ```bash
399
+ gabbe replay abc123-... # replay from step 0
400
+ gabbe replay abc123-... --from-step 3 # skip first 3 steps
401
+ ```
402
+
403
+ Requires that `checkpoints` rows exist for the run. Use `gabbe brain activate` with checkpoint saving enabled.
404
+
405
+ ---
406
+
407
+ ### `gabbe resume <run-id>`
408
+
409
+ Resume a run that was paused by the escalation handler (file mode).
410
+
411
+ ```bash
412
+ gabbe resume abc123-...
413
+ ```
414
+
415
+ Lists all pending escalations for the run, prompts for approve/reject per item, and updates the `pending_escalations` table.
416
+
417
+ ---
418
+
419
+ ### `gabbe registry publish [--out DIR]`
420
+
421
+ Export the kit's skills as a publish-ready, agentskills.io-standard bundle
422
+ (`<slug>/SKILL.md` tree + `manifest.json` + an A2A-style `agent-card.json`) for
423
+ universal skill registries. The maintainer performs the actual publish.
424
+
425
+ ```bash
426
+ gabbe registry publish --out dist/registry
427
+ ```
428
+
429
+ ### `gabbe registry add <source> [--namespace NS] [--apply]`
430
+
431
+ Import an external skill/bundle (local path, `.tar.gz`, or `http(s)` URL) into
432
+ `agents/skills/<namespace>/`. Every candidate is validated (real-YAML frontmatter
433
+ + safe-slug + path-traversal + egress/secret/executable-payload scan) and landed
434
+ namespaced for review. Dry-run by default; pass `--apply` to write.
435
+
436
+ ```bash
437
+ gabbe registry add ./bundle --namespace ext # dry run
438
+ gabbe registry add https://example/skill.skill.md --apply
439
+ ```
440
+
441
+ ### `gabbe setup`
442
+
443
+ Run the interactive install wizard (`scripts/init.py`) to wire the kit into your
444
+ coding agents. (For a Python-independent install, use `npx gabbe-kit init` or
445
+ `curl -fsSL .../install.sh | sh`.)
446
+
447
+ ```bash
448
+ gabbe setup
449
+ ```
450
+
451
+ ---
452
+
453
+ ### `gabbe eval [--live] [--out FILE]`
454
+
455
+ Run the skill eval suites (`agents/skills/<category>/evals/*.eval.yaml`) via the
456
+ kit-layer harness (`agents/scripts/eval_skills.py`). The default deterministic
457
+ self-check lints every suite and self-tests the assertion evaluators with **no
458
+ model** (safe per-commit). `--live` renders each prompt, scores outputs against
459
+ the model, and writes a JSON scorecard (nightly; needs `GABBE_LIVE_LLM=1`).
460
+
461
+ ```bash
462
+ gabbe eval # deterministic self-check
463
+ GABBE_LIVE_LLM=1 gabbe eval --live --out scorecard.json
464
+ ```
465
+
466
+ Evals sample the input space and raise confidence — they do not prove correctness.
467
+
468
+ ---
469
+
470
+ ### `gabbe doctor`
471
+
472
+ Read-only environment & install report. Auto-detects the OS/arch, the available
473
+ runtimes/package managers (`python3`, `pip`, `pipx`, `node`, `npm`, `npx`, `git`,
474
+ `curl`), and which agent clients are present in the target (Claude Code, Cursor,
475
+ Copilot, Gemini, Codex, Windsurf, Cline, Aider, Zed, Antigravity, OpenCode,
476
+ Continue, Roo, Kilo), then prints a PASS/WARN per check. Used by the multi-OS
477
+ `install-matrix` and post-publish `release-verify` CI jobs to confirm a
478
+ one-command install succeeded.
479
+
480
+ ```bash
481
+ gabbe doctor
482
+ ```
483
+
484
+ ---
485
+
486
+ ### `gabbe update [--agents LIST] [--global] [--dir PATH]`
487
+
488
+ Additively refresh the installed kit from source: updates kit files, prunes
489
+ orphaned emitted files, and preserves user/preserve files (`CONSTITUTION.md`,
490
+ `policies.yml`). Target resolution: `--dir` > `--global` > project (cwd).
491
+
492
+ ```bash
493
+ gabbe update
494
+ ```
495
+
496
+ ---
497
+
498
+ ### `gabbe uninstall [--agents LIST] [--dry-run] [--purge] [--global] [--dir PATH]`
499
+
500
+ Reverse a GABBE install using its `.gabbe/manifest.json`: removes exactly what was
501
+ installed, restores any `.bak` backups, prunes now-empty dirs, and never touches
502
+ unrelated files. `--agents` deselects specific agents only; `--dry-run` prints the
503
+ plan without changing anything; `--purge` also removes the `agents/` kit and
504
+ `.gabbe/`. Idempotent and isolated (never writes outside the target).
505
+
506
+ ```bash
507
+ gabbe uninstall --dry-run
508
+ gabbe uninstall
509
+ ```
510
+
511
+ ---
512
+
513
+ ## Troubleshooting
514
+
515
+ **`EnvironmentError: GABBE_API_KEY is not set`**
516
+ Set the env var: `export GABBE_API_KEY=sk-...` before running LLM-dependent commands.
517
+
518
+ **`Database not initialized`**
519
+ Run `gabbe init` first.
520
+
521
+ **`project/TASKS.md` always re-importing on every `gabbe sync`**
522
+ Check that `updated_at` is being written correctly to the DB.
523
+ The DB timestamp (from `MAX(updated_at) FROM tasks`) must be ≥ the file mtime after an import.
524
+
525
+ **CI: `validate_skills.py` not found**
526
+ The `agents/scripts/` directory contains project-specific validators generated by `scripts/init.py`.
527
+ Run `python3 scripts/init.py` once to generate them before CI runs.
@@ -0,0 +1,68 @@
1
+ # Installing, Updating & Uninstalling GABBE
2
+
3
+ GABBE installs are **manifest-backed, reversible, and isolated**: every install
4
+ records exactly what it created in `.gabbe/manifest.json`, so `update` and
5
+ `uninstall` are precise and never touch unrelated files. Nothing is ever written
6
+ outside the chosen target unless you pass `--global`.
7
+
8
+ ## One-command install (every channel)
9
+
10
+ | Channel | Command | Notes |
11
+ |---|---|---|
12
+ | npm / Node | `npx gabbe-kit init` | Python-independent; bundles the kit and wires detected agents |
13
+ | PyPI | `pipx install gabbe && gabbe setup` (or `pip install gabbe`) | adds the `gabbe` CLI |
14
+ | Shell bootstrap | `curl -fsSL https://raw.githubusercontent.com/andreibesleaga/GABBE/main/install.sh \| sh` | picks the best available installer |
15
+ | Git checkout | `git clone … && python3 scripts/init.py` | the interactive wizard |
16
+
17
+ After installing, run `gabbe doctor` to print an environment + install report
18
+ (detected OS/arch, runtimes, agent clients, and per-check PASS/WARN). It also prints
19
+ **post-install next steps** — which MCP servers to enable and how. For the full
20
+ environment-setup walkthrough (MCP servers, local-GitHub servers, policy/budgets,
21
+ validation), see `docs/POST_INSTALL.md`.
22
+
23
+ ## Install scopes (targets)
24
+
25
+ - **Project (default):** the current directory. Nothing is written elsewhere.
26
+ - **Global:** `--global` → `$XDG_DATA_HOME/gabbe` (falls back to `~/.local/share/gabbe`).
27
+ - **Custom:** `--dir <path>` → an explicit directory.
28
+
29
+ Resolution order for `update` / `uninstall`: `--dir` > `--global` > project (cwd).
30
+
31
+ ## Updating
32
+
33
+ ```bash
34
+ gabbe update # additive refresh of kit files; prunes orphans
35
+ ```
36
+
37
+ `update` preserves user/preserve files (`CONSTITUTION.md`, `policies.yml`) and
38
+ your memory/project files; it only refreshes managed kit artifacts and removes
39
+ ones that are no longer emitted.
40
+
41
+ ## Uninstalling (fully reversible)
42
+
43
+ ```bash
44
+ gabbe uninstall --dry-run # print exactly what would be removed
45
+ gabbe uninstall # remove it; restore any .bak backups
46
+ gabbe uninstall --agents cursor # deselect one agent's wiring only
47
+ gabbe uninstall --purge # also remove the agents/ kit and .gabbe/
48
+ ```
49
+
50
+ Or use the bootstrap scripts when the CLI is not on `PATH`:
51
+
52
+ ```bash
53
+ sh uninstall.sh --dry-run # POSIX
54
+ pwsh ./uninstall.ps1 -DryRun # Windows / PowerShell
55
+ ```
56
+
57
+ Uninstall reads `.gabbe/manifest.json`, removes **exactly** what was installed,
58
+ restores any shadowed user files from their `.bak`, prunes now-empty directories,
59
+ and is idempotent (safe to run twice). The result is byte-identical to the
60
+ pre-install state.
61
+
62
+ ## Verification
63
+
64
+ The reversibility and isolation guarantees are regression-tested
65
+ (`scripts/tests/test_install_manifest.py`, `test_uninstall.py`,
66
+ `test_install_isolation.py`, `test_remove_agents.py`) and exercised across
67
+ `{ubuntu, macos, windows}` by the CI `install-matrix` job plus the post-publish
68
+ `release-verify` job (which installs the published package and runs `gabbe doctor`).