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,62 @@
1
+ # Production Health & Optimization Guide
2
+
3
+ > **Goal**: Keep agentic systems stable, cost-effective, and sane in production.
4
+
5
+ ---
6
+
7
+ ## 1. The Recursion Danger (Agentic Loops)
8
+
9
+ Agents can get stuck in infinite loops ("thought spirals"). The system must detect and break these.
10
+
11
+ **Detection Strategy:**
12
+ 1. **N-Gram Analysis**: Detect if a sequence of tools (e.g., `read_file` -> `edit_file` -> `test`) repeats 3x with same args.
13
+ 2. **Semantic Similarity**: Check if "Thought" content is >95% similar to previous steps.
14
+ 3. **Cost Velocity**: If spend spikes ($1/min), trigger emergency brake.
15
+
16
+ **Remediation:**
17
+ * **Trip Circuit Breaker**: Pause execution.
18
+ * **Inject Human**: Send notification: "Agent stuck in loop. Human help needed."
19
+ * **Backoff**: Exponential backoff (1s, 2s, 4s, 8s...).
20
+
21
+ ---
22
+
23
+ ## 2. System Sleep & Scale-to-Zero
24
+
25
+ Agents shouldn't run 24/7 if no one is watching.
26
+
27
+ **Sleep Patterns:**
28
+ * **Deep Sleep**: No active triggers. Infrastructure logic scales to 0 (Serverless).
29
+ * **Light Sleep**: Polling interval reduced (e.g., check email every 1h instead of 1m).
30
+ * **Wake-on-LAN/Event**: System wakes only on specific high-priority webhooks (e.g., PagerDuty, GitHub PR).
31
+
32
+ **Implementation:**
33
+ * Use `ops/production-health.skill.md` logic hooks.
34
+ * Configure Serverless timeouts (AWS Lambda / Cloud Run).
35
+
36
+ ---
37
+
38
+ ## 3. Cost Optimization (FinOps)
39
+
40
+ **Golden Rules:**
41
+ 1. **Model Cascading**: Try cheap model first. If confidence < 0.8, escalate to smart model.
42
+ 2. **Context Caching**: Cache the "System Prompt" and "Knowledge Base" headers.
43
+ 3. **Summarization**: Don't keep raw logs in context. Summarize logs every 10 steps.
44
+
45
+ **Daily Limits:**
46
+ * Hard Cap: $50/day (System shuts down).
47
+ * Soft Cap: $25/day (Admin alert).
48
+
49
+ ---
50
+
51
+ ## 4. Self-Healing vs. Looping
52
+
53
+ Self-healing is good; infinite retry is bad.
54
+
55
+ **The "5-Attempt Rule":**
56
+ * Attempt 1: Try standard fix.
57
+ * Attempt 2: Try alternative strategy.
58
+ * Attempt 3: Research authoritative docs.
59
+ * Attempt 4: Ask clarifying question.
60
+ * Attempt 5: **STOP**. Report failure to Human.
61
+
62
+ *Never* attempt 6. Attempt 6 is madness.
@@ -0,0 +1,69 @@
1
+ # GABBE Kit Troubleshooting Guide
2
+
3
+ This guide provides solutions to common issues encountered when initializing, configuring, or running the GABBE Agentic Engineering Kit.
4
+
5
+ ## 1. Setup & Installation Issues
6
+
7
+ ### `init.py` fails with "ModuleNotFoundError"
8
+ **Symptoms:** Running `python3 scripts/init.py` throws an error about missing modules.
9
+ **Cause:** Python dependencies might be missing or you're using an older Python version.
10
+ **Solution:**
11
+ 1. Ensure you have Python 3.8+ installed (`python3 --version`).
12
+ 2. Run standard installation procedures: `pip install -r requirements.txt` (if applicable) or use the interactive `python3 scripts/init.py` prompt.
13
+
14
+ ### "File exists" error during setup
15
+ **Symptoms:** `init.py` stops with `mkdir: cannot create directory ‘agents’: File exists`.
16
+ **Cause:** You previously installed the kit in this directory.
17
+ **Solution:** Run `python3 scripts/init.py` and input `y` when asked to "Overwrite/Update it?".
18
+
19
+ ### Symlinks not working (Windows)
20
+ **Symptoms:** `agents/skills` are not visible to the IDE or AI Agent.
21
+ **Cause:** Windows requires Administrator privileges to create symlinks by default.
22
+ **Solution:**
23
+ 1. Open PowerShell **as Administrator**.
24
+ 2. Run `.\agents\setup-context.ps1`.
25
+ 3. Alternatively, enable Developer Mode in Windows Settings (which allows standard users to create symlinks).
26
+
27
+ ## 2. Agent Configuration Issues
28
+
29
+ ### Agent ignores AGENTS.md
30
+ **Symptoms:** The agent generates code in the wrong framework or ignores layer boundaries.
31
+ **Cause:** The symlink from `.cursorrules` or `.claude/CLAUDE.md` to `AGENTS.md` is broken, or the file lacks rules.
32
+ **Solution:**
33
+ 1. Re-run `./agents/setup-context.sh`.
34
+ 2. Check `AGENTS.md` to ensure `[PLACEHOLDER]` fields are filled correctly.
35
+
36
+ ### Skills not triggering
37
+ **Symptoms:** Typing `/tdd-cycle` or asking the agent to use a skill results in generic web search behavior.
38
+ **Cause:** The skill directory is not mounted or the AI tool is misconfigured.
39
+ **Solution:**
40
+ - **Cursor:** Ensure `.mdc` files exist in `.cursor/rules/`.
41
+ - **Claude:** Ensure `.claude/skills` is symlinked to `agents/skills`.
42
+ - **Gemini / Antigravity:** Check `.gemini/settings.json` for the `skills` path.
43
+
44
+ ## 3. Loki orchestration issues
45
+
46
+ ### Self-Heal loop stuck in infinite recursion
47
+ **Symptoms:** Agent continuously tries to fix the same error without escalating.
48
+ **Cause:** Bug in `self-heal.skill.md` constraint evaluation.
49
+ **Solution:** Tell the agent: "Stop. Escalate issue. Read self-heal limit constraints." You can also manually add the failure to `agents/memory/CONTINUITY.md` so the agent skips it next time.
50
+
51
+ ### Tasks getting lost or corrupted
52
+ **Symptoms:** `project/TASKS.md` is out of sync or tasks disappear.
53
+ **Cause:** Concurrent edits by human and agent, or an interrupted session.
54
+ **Solution:**
55
+ 1. Run `gabbe sync` (GABBE CLI).
56
+ 2. Manually review `agents/memory/PROJECT_STATE.md` and edit `project/TASKS.md` to match reality.
57
+
58
+ ## 4. GABBE CLI Issues
59
+
60
+ ### `gabbe route` or `gabbe brain` fails with "API Key Missing"
61
+ **Symptoms:** Commands that require remote LLM models throw an authentication error.
62
+ **Cause:** `GABBE_API_KEY` environment variable is not set.
63
+ **Solution:** Export your OpenAI-compatible API key:
64
+ `export GABBE_API_KEY='your-key-here'`
65
+
66
+ ### SQLite Database locked
67
+ **Symptoms:** Running `gabbe sync` throws a `database is locked` error.
68
+ **Cause:** Multiple terminal windows or an active agent are trying to access `project/state.db` simultaneously.
69
+ **Solution:** Ensure no background processes are running `gabbe` commands. If necessary, delete the `project/state.db-journal` file.
@@ -0,0 +1,308 @@
1
+ # Agentic Design Patterns — Comprehensive Catalog
2
+
3
+ A scannable taxonomy of the design patterns and advanced techniques used to build autonomous
4
+ LLM-based agents. Each entry gives a one- or two-line description, **when to use** it, and the
5
+ GABBE skill (referenced by name in backticks) that implements or operationalizes it. Patterns are
6
+ grouped by the problem they solve; most real systems **compose** several of them.
7
+
8
+ This guide is a map, not an implementation. When an entry names a GABBE skill, that skill is the
9
+ load-bearing artifact — read it before building. Where no dedicated skill exists, the catalog itself
10
+ is the reference.
11
+
12
+ ---
13
+
14
+ ## How to read this catalog
15
+
16
+ Three meta-principles cut across every category below:
17
+
18
+ - **Start simple; add structure only when it pays for itself.** The cheapest correct system that
19
+ meets the bar wins. A single well-prompted call beats a chain; a fixed chain beats an autonomous
20
+ agent; reach for multi-agent only when one agent provably cannot hold the task. Every added
21
+ pattern buys a property (accuracy, parallelism, auditability) and costs another (latency, tokens,
22
+ surface area) — spend deliberately.
23
+ - **Workflows vs. agents.** A *workflow* is a predictable, pre-composed path through known steps
24
+ (you wrote the control flow). An *agent* dynamically decides its own steps and tool calls at
25
+ runtime. Workflows are easier to test, cheaper, and more auditable; agents are more flexible and
26
+ handle open-ended tasks. Prefer the workflow when the steps are knowable in advance.
27
+ - **Reflection needs an external anchor.** Any self-critique loop that scores only its own opinion
28
+ reinforces errors rather than fixing them. Pair every reflective pattern below with a deterministic
29
+ check, a symbolic constraint, or an independent judge. See `agentic-patterns.skill` (grounded
30
+ self-critique) and `llm-as-judge.skill`.
31
+
32
+ ---
33
+
34
+ ## (a) Reasoning patterns
35
+
36
+ Techniques that shape *how a single model thinks* before or while it answers. They trade extra
37
+ tokens/latency for accuracy on hard problems. Implemented and contrasted in `reasoning-patterns.skill`
38
+ and `sequential-thinking.skill`.
39
+
40
+ - **Chain-of-Thought (CoT)** — make the model lay out intermediate reasoning steps before the final
41
+ answer. *Use when:* multi-step arithmetic, logic, or analysis where a one-shot answer is unreliable.
42
+ *Skip when:* trivial lookups (it just adds latency). → `reasoning-patterns.skill`,
43
+ `sequential-thinking.skill`.
44
+ - **Self-Consistency** — sample several independent CoT traces and take the majority answer instead
45
+ of trusting one. *Use when:* a single trace is noisy and a verifiable/aggregable answer exists.
46
+ *Cost:* N× tokens. → `reasoning-patterns.skill`; for the voting mechanics see
47
+ `swarm-consensus.skill`.
48
+ - **Tree-of-Thoughts (ToT)** — explore reasoning as a branching tree, score partial branches with a
49
+ value heuristic, and prune dead ends. *Use when:* problems with search/backtracking structure
50
+ (puzzles, planning, proofs). *Cost:* high — many calls. → `reasoning-patterns.skill`.
51
+ - **Graph-of-Thoughts** — generalize ToT to a DAG so partial results can *merge*, not only branch.
52
+ *Use when:* sub-results recombine (e.g. aggregating sub-summaries). → `reasoning-patterns.skill`.
53
+ - **ReAct (Reason + Act)** — interleave reasoning with tool calls: Thought → Action → Observation →
54
+ repeat, so reasoning is grounded in real observations. *Use when:* the model needs external
55
+ information or to act in an environment (search, DB, APIs). The default loop for tool-using agents.
56
+ → `agentic-patterns.skill`.
57
+ - **Reflexion** — after a failed attempt, write a verbal self-critique into memory and retry with that
58
+ lesson in context; the critique persists across attempts. *Use when:* tasks allow multiple attempts
59
+ with a usable success/failure signal. *Anchor required* (see meta-principles). → `agentic-patterns.skill`
60
+ (reflection), `episodic-consolidation.skill` (persisting the lesson).
61
+ - **Least-to-Most** — first decompose the problem into an ordered list of easier sub-problems, then
62
+ solve them in sequence, each using earlier answers. *Use when:* the hard problem is really a chain of
63
+ dependent easy ones; improves generalization to harder instances. → `reasoning-patterns.skill`.
64
+ - **Step-Back Prompting** — before answering, ask the model to derive the higher-level principle,
65
+ abstraction, or general question, then reason from it. *Use when:* the model rushes to a specific
66
+ wrong answer and a governing concept would steady it. → `reasoning-patterns.skill`.
67
+ - **Dual-Process (System 1 / System 2)** — wrap fast generative output (System 1) in a slower
68
+ evaluative layer (System 2) that checks before committing. *Use when:* fast answers are usually
69
+ right but occasional confident errors are costly. → `reasoning-patterns.skill`,
70
+ `consciousness-loop.skill`.
71
+ - **Test-time compute scaling** — spend more inference compute (longer reasoning, more samples,
72
+ verifier-guided search) on harder instances only. *Use when:* difficulty varies and you can detect
73
+ it; route easy cases to cheap paths. → `reasoning-patterns.skill`, `cost-benefit-router.skill`.
74
+ - **Outcome vs. Process reward (ORM vs. PRM)** — grade only the final answer (ORM) versus grading each
75
+ reasoning step (PRM). PRM catches "right answer, wrong reasoning" and prunes bad traces early.
76
+ *Use when:* you can score steps; it is the antidote to lucky-but-unsound traces. → `agentic-patterns.skill`
77
+ (per-step scoring), `cognitive-testing.skill`.
78
+
79
+ **When NOT to use heavy reasoning:** simple, well-specified, single-fact tasks; latency-critical paths;
80
+ cases where a deterministic tool already gives the answer. Heavy reasoning multiplies cost and can
81
+ *talk itself out of* a correct first answer.
82
+
83
+ ---
84
+
85
+ ## (b) Planning patterns
86
+
87
+ Techniques for turning a goal into an executable sequence of steps. Implemented via
88
+ `sequential-thinking.skill` and the orchestration skills.
89
+
90
+ - **Plan-and-Execute** — generate the full plan up front, then execute steps without re-planning each
91
+ one. *Use when:* you want auditability and predictable cost, and the environment is stable enough
92
+ that the plan won't go stale. *Trade-off:* less adaptive than re-planning every step. → `loki-mode.skill`,
93
+ `multi-agent-orch.skill`.
94
+ - **Plan-Reflect (re-planning loop)** — execute a step, observe, and revise the remaining plan before
95
+ continuing. *Use when:* the environment is dynamic or steps surface new information. *Trade-off:*
96
+ more LLM calls, harder to audit. → `agentic-patterns.skill`.
97
+ - **Task decomposition** — split a large goal into independent or dependent sub-tasks with explicit
98
+ inputs/outputs. The substrate under almost every multi-step pattern. *Use when:* any task too big
99
+ for one focused context. → `multi-agent-orch.skill`, `context-engineering.skill`.
100
+ - **Hierarchical task networks (HTN)** — recursively decompose tasks into sub-tasks until each is
101
+ directly executable, forming a tree of methods. *Use when:* domains with reusable decomposition
102
+ recipes and clear sub-task boundaries. → `multi-agent-orch.skill`.
103
+ - **Plan-as-graph (DAG planning)** — represent the plan as a dependency DAG so independent branches run
104
+ in parallel and ordering constraints are explicit. *Use when:* sub-tasks have a partial order with
105
+ real parallelism to exploit. → `multi-agent-orch.skill`, `agent-workflow-patterns.skill`.
106
+ - **Planner / Worker / Solver factorization (ReWOO-style)** — a planner writes the whole tool-using
107
+ plan once (with variable placeholders), workers execute tools, a solver composes the final answer —
108
+ decoupling reasoning from observations so tool count doesn't blow up call count. *Use when:* many
109
+ tool calls per task and you want to minimize reasoning-model invocations. → `agent-workflow-patterns.skill`.
110
+
111
+ ---
112
+
113
+ ## (c) Workflow patterns (the "effective agents" taxonomy)
114
+
115
+ Predictable, pre-composed control flows. These are the first thing to reach for — they are cheaper and
116
+ more reliable than autonomous agents and solve most problems. Fully operationalized in
117
+ `agent-workflow-patterns.skill`.
118
+
119
+ - **Prompt chaining** — decompose a task into a fixed sequence of LLM calls, each consuming the prior
120
+ output, optionally with programmatic gates between steps. *Use when:* the task cleanly splits into
121
+ ordered sub-tasks (e.g. outline → draft → polish). → `agent-workflow-patterns.skill`.
122
+ - **Routing** — classify the input, then dispatch it to a specialized prompt, tool, or model.
123
+ *Use when:* distinct input categories are handled better separately, or to send easy cases to a
124
+ cheap model and hard ones to a strong one. → `agent-workflow-patterns.skill`, `cost-benefit-router.skill`,
125
+ `persona-selector.skill`.
126
+ - **Parallelization — sectioning** — split a task into independent subtasks run concurrently, then
127
+ combine. *Use when:* parts are genuinely independent (e.g. analyze N documents). → `agent-workflow-patterns.skill`.
128
+ - **Parallelization — voting** — run the *same* task multiple times in parallel and aggregate (majority,
129
+ any-flag, average). *Use when:* you need higher confidence or want diverse attempts (e.g. multiple
130
+ reviewers for code, guardrail screening). → `agent-workflow-patterns.skill`, `swarm-consensus.skill`.
131
+ - **Orchestrator-workers** — a central LLM dynamically decomposes the task, delegates sub-tasks to
132
+ worker LLMs, and synthesizes their results. Unlike sectioning, the sub-tasks are *not* known in
133
+ advance. *Use when:* you can't predict the decomposition (e.g. multi-file code changes, open-ended
134
+ research). → `multi-agent-orch.skill`, `agent-workflow-patterns.skill`.
135
+ - **Evaluator-optimizer** — one LLM generates, a second evaluates against a rubric and returns
136
+ feedback, loop until the bar is met. *Use when:* you have clear evaluation criteria and iterative
137
+ refinement measurably helps (translation, complex search, writing). *Anchor required.* → `agent-workflow-patterns.skill`,
138
+ `llm-as-judge.skill`.
139
+
140
+ ---
141
+
142
+ ## (d) Multi-agent patterns
143
+
144
+ Topologies for coordinating multiple agents. The dominant trade-off and characteristic failure mode of
145
+ each is the deciding factor — see the decision matrix and failure-mode taxonomy in `multi-agent-orch.skill`.
146
+
147
+ - **Supervisor / hierarchical (hub-and-spoke)** — a supervisor decomposes, routes to workers, and
148
+ integrates results. *Buys:* central control, auditability. *Costs:* supervisor bottleneck and
149
+ *command distortion* down deep delegation trees. → `multi-agent-orch.skill`, `loki-mode.skill`.
150
+ - **Blackboard / peer-to-peer** — agents collaborate laterally through a shared state store with no
151
+ central controller. *Buys:* fault tolerance, no single point of failure. *Costs:* poor observability,
152
+ emergent loops/herding/deadlock. → `multi-agent-orch.skill`, `autonomous-swarm-patterns.skill`.
153
+ - **Debate** — multiple agents argue from different priors and a moderator/judge picks or synthesizes.
154
+ *Use when:* contested or subjective questions where surfacing disagreement improves the answer;
155
+ *use a different model family for the judge* to avoid correlated failure. → `swarm-consensus.skill`,
156
+ `llm-as-judge.skill`.
157
+ - **Consensus / voting** — multiple agents answer the same question and the result is aggregated.
158
+ *Buys:* accuracy on hard problems. *Costs:* N× tokens. Use *first-to-ahead-by-k* and discard
159
+ structurally malformed votes. → `swarm-consensus.skill`.
160
+ - **Market / contract-net** — tasks are advertised and agents bid; the awarded agent binds to a
161
+ computational contract (I/O schema, resource budget, eval metric) and may sub-contract. *Use when:*
162
+ heterogeneous workers and tasks that must be matched by capability/cost, or workloads that exceed one
163
+ context. → `multi-agent-orch.skill` (computational-contract delegation).
164
+ - **Round-robin / dispatcher** — cyclically distribute work across interchangeable stateless workers.
165
+ *Use when:* throughput on independent units with no shared state. → `multi-agent-orch.skill`.
166
+ - **Swarm / handoff** — decentralized sequential control transfer: each specialist hands control to the
167
+ next, no central supervisor. *Use when:* a pipeline of specialists where each fully owns its phase.
168
+ → `autonomous-swarm-patterns.skill`, `multi-agent-systems.skill`.
169
+ - **Actor model (message-passing)** — isolated stateful actors with private state communicate only via
170
+ async immutable messages, with "let it crash" supervision and dead-letter queues. *Use when:* you
171
+ need fault isolation, location transparency, and resilient distributed coordination. → `actor-agent-frameworks.skill`,
172
+ `multi-agent-systems.skill`.
173
+ - **Board / state-machine (kanban) coordination** — model the work as tasks moving through explicit
174
+ states (todo → doing → blocked → awaiting-validation → done) on a shared board that is the single
175
+ source of truth. *Use when:* you want observable, resumable, human-reviewable multi-agent work.
176
+ → `multi-agent-orch.skill` (handoffs + HITL checkpoints).
177
+ - **Fan-out / fan-in** — spawn parallel workers, then aggregate their outputs in a single reducer.
178
+ *Use when:* embarrassingly parallel sub-tasks (e.g. many searchers → one writer). → `agent-workflow-patterns.skill`,
179
+ `multi-agent-orch.skill`.
180
+
181
+ **Coordination economics:** coordination overhead grows with agent count and there is a capability
182
+ saturation threshold beyond which adding agents *hurts*. The topology is the constraint — pick the
183
+ simplest one that fits and validate it empirically.
184
+
185
+ ---
186
+
187
+ ## (e) Memory & context patterns
188
+
189
+ Techniques for managing what the agent knows across time and what fits in the window now. Memory
190
+ *mechanics* live in the `brain/` skills; the *budget decisions* live in `context-engineering.skill`.
191
+
192
+ - **Write / Select / Compress / Isolate** — the four context-management strategies: persist durable
193
+ state outside the window, retrieve just-in-time, compact long history, and split concerns across
194
+ focused sub-agents. *Use when:* any agent whose task outgrows a single clean context. → `context-engineering.skill`.
195
+ - **Memory taxonomy (working / episodic / semantic / procedural)** — short-horizon scratch state; past
196
+ experiences/interactions; facts and knowledge; learned how-to skills. *Use when:* designing what an
197
+ agent should remember and where. → `working-memory.skill`, `episodic-consolidation.skill`.
198
+ - **Summarization / compaction** — compress message history into a running summary once it crosses a
199
+ threshold, preserving decisions and constraints. *Use when:* long-running sessions approaching the
200
+ context ceiling. *Keep a recovery path* — compaction is lossy. → `context-engineering.skill`.
201
+ - **Forgetting / decay as a first-class operation** — actively expire or down-weight stale memory rather
202
+ than accumulating forever. *Use when:* unbounded memory growth degrades retrieval relevance. → `episodic-consolidation.skill`,
203
+ `learning-adaptation.skill`.
204
+ - **RAG (retrieval-augmented generation)** — retrieve relevant external documents and condition the
205
+ answer on them instead of relying on parametric memory. *Use when:* answers need current/proprietary
206
+ facts with provenance. Evaluate it. → `knowledge-connect.skill`, `rag-evaluation.skill`.
207
+ - **Agentic RAG (Self-RAG / Corrective-RAG / Adaptive-RAG)** — let the agent decide *whether* to
208
+ retrieve, judge retrieved quality and correct (re-query / fall back to web) when confidence is low,
209
+ and route by question difficulty. *Use when:* retrieval quality is variable and a naive single-shot
210
+ retrieve-then-answer is unreliable. → `knowledge-connect.skill`, `rag-evaluation.skill`.
211
+ - **GraphRAG / knowledge-graph memory** — retrieve over a structured graph (entities + relations)
212
+ instead of flat chunks, enabling multi-hop and global questions. *Use when:* questions span many
213
+ documents or need relational reasoning. → `knowledge-connect.skill`.
214
+ - **Skill acquisition / procedural caching (Voyager-style)** — distill successful solutions into named,
215
+ vector-indexed, callable skills the agent reuses later. *Use when:* recurring sub-tasks worth
216
+ amortizing into a growing skill library. → `self-evolving-skills` guide, `self-improvement.skill`.
217
+
218
+ ---
219
+
220
+ ## (f) Tool & environment patterns
221
+
222
+ How agents act on the world. The agent-computer interface quality matters as much as model quality.
223
+
224
+ - **Tool use / function calling** — expose typed, strictly-schema'd tools the model invokes with
225
+ structured arguments. *Use when:* the agent must do anything beyond producing text. Design atomic,
226
+ well-described, error-proofed tools. → `tool-construction.skill`, `agentic-patterns.skill`.
227
+ - **Parallel tool use / function-calling fan-out** — issue independent tool calls concurrently in one
228
+ turn. *Use when:* multiple independent reads/queries with no ordering dependency. → `agent-workflow-patterns.skill`.
229
+ - **Code execution** — let the agent write and run code in a sandbox as its action space, rather than
230
+ calling fixed tools. *Use when:* tasks needing arbitrary computation, data wrangling, or composition
231
+ of operations. *Sandbox mandatory.* → `agent-sandboxing.skill`, `tool-construction.skill`.
232
+ - **Computer use / GUI control** — drive applications through screenshots and synthesized
233
+ mouse/keyboard actions when no API exists; perceive → act → re-perceive. *Use when:* the only
234
+ interface is a GUI; prefer API/tool calls whenever available (cheaper, more reliable). → `sensory-motor.skill`,
235
+ `agent-sandboxing.skill`.
236
+ - **MCP (model context protocol)** — a standard protocol for exposing tools, resources, and prompts to
237
+ agents over stdio/HTTP, so capabilities are pluggable and portable. *Use when:* you want
238
+ interoperable, reusable tool servers instead of bespoke integrations. → `tool-construction.skill`,
239
+ `agent-protocol.skill`.
240
+ - **A2A (agent-to-agent) protocol** — a standard for agents to discover each other (agent cards) and
241
+ exchange tasks across organizational/runtime boundaries. *Use when:* federating agents built by
242
+ different teams or in different stacks. → `agent-protocol.skill`, `agent-interop.skill`.
243
+ - **Tiered integration hierarchy** — prefer direct tool calls, then MCP gateways, then unified APIs,
244
+ then A2A — climbing tiers only as interoperability needs grow. *Use when:* deciding how an agent
245
+ should reach an external capability. → `tool-construction.skill`.
246
+
247
+ ---
248
+
249
+ ## (g) Reliability & safety patterns
250
+
251
+ Patterns that keep autonomous systems correct, bounded, and accountable. Most agentic failures are
252
+ reliability failures, not capability failures.
253
+
254
+ - **Grounded reflection (external anchor)** — never let a self-critique loop score only its own
255
+ opinion; require a deterministic check, a symbolic constraint, or per-step scoring so the loop
256
+ corrects errors instead of reinforcing them. *Use when:* any reflection/self-review loop. → `agentic-patterns.skill`,
257
+ `cognitive-testing.skill`.
258
+ - **LLM-as-judge / generator-critic** — score outputs with a separate model against an explicit rubric,
259
+ ideally from a different model family to avoid correlated blind spots. *Use when:* automated quality
260
+ gating where deterministic checks can't fully cover the criteria. → `llm-as-judge.skill`.
261
+ - **Guardrails (input/output filtering)** — screen prompts and outputs for injection, jailbreaks,
262
+ policy violations, secret leakage, and unsafe actions, ideally as a parallel voting check. *Use when:*
263
+ any agent exposed to untrusted input or producing consequential output. → `ai-safety-guardrails.skill`,
264
+ `prompt-injection-defense.skill`.
265
+ - **Human-in-the-loop (HITL)** — insert approval/revision checkpoints before consequential actions, with
266
+ confidence-threshold gating so only uncertain or high-impact steps interrupt a human. *Use when:*
267
+ irreversible or high-stakes actions; lower autonomy bands. → `multi-agent-orch.skill`,
268
+ `human-agent-collaboration` guide.
269
+ - **Circuit breaker / loop bounding** — hard caps on iteration depth, token/wall-clock budget, and a
270
+ quality-threshold exit so loops cannot spin forever or exhaust cost. *Use when:* every ReAct,
271
+ reflection, planning, or consensus loop. → `agentic-patterns.skill`, `reliability-engineering.skill`.
272
+ - **Sandboxing / least privilege** — execute tools and code in isolated environments (filesystem,
273
+ network, process, inference) with egress control and scoped credentials, so a vulnerable tool or
274
+ injection has a contained blast radius. *Use when:* any agent that executes code, calls tools, or
275
+ handles untrusted content. → `agent-sandboxing.skill`.
276
+ - **Provenance & audit trail** — tag every input with its source, treat re-read memory and upstream
277
+ handoffs as untrusted data, and keep an append-only record of what the agent wrote/selected/did.
278
+ *Use when:* multi-step or multi-agent systems needing forensic accountability. → `context-engineering.skill`,
279
+ `traceability-audit.skill`.
280
+ - **Confused-deputy / poisoned-handoff defense** — prevent a privileged agent from being steered by a
281
+ malicious user or a compromised upstream peer into actions it shouldn't take. *Use when:* any
282
+ topology where privilege differs across agents. → `multi-agent-orch.skill`, `prompt-injection-defense.skill`.
283
+ - **Spectrum of autonomy** — treat autonomy as a tunable design variable (suggest → confirm → act),
284
+ raising it only as trust and evals accumulate. *Use when:* deciding how much latitude to give an
285
+ agent in production. → `self-optimize.skill`, `human-agent-collaboration` guide.
286
+
287
+ > Classical (non-agentic) software design & architecture patterns — GoF, layered/
288
+ > hexagonal/microservices/event-driven, DDD, enterprise integration — have their own
289
+ > catalog in the `software-design-patterns` guide. Agentic patterns sit on top of them.
290
+
291
+ ---
292
+
293
+ ## Composition cheat-sheet
294
+
295
+ | Goal | Reach for |
296
+ |---|---|
297
+ | One-shot answer is unreliable | CoT → self-consistency → ToT (in that order of cost) |
298
+ | Agent needs live data / to act | ReAct + tool use + sandbox |
299
+ | Steps are knowable in advance | a workflow (chaining / routing / parallelization) — not an agent |
300
+ | Decomposition is unpredictable | orchestrator-workers |
301
+ | Clear rubric, iteration helps | evaluator-optimizer + LLM-as-judge (external anchor) |
302
+ | Hard question, want confidence | consensus/voting or debate (different judge family) |
303
+ | Task outgrows one context | Write/Select/Compress/Isolate + sub-agents |
304
+ | Needs current/proprietary facts | (Agentic) RAG / GraphRAG + RAG evaluation |
305
+ | Irreversible / high-stakes action | HITL gate + circuit breaker + sandbox |
306
+
307
+ When in doubt, build the simplest version, measure it against an eval, and add a pattern only when the
308
+ eval shows you need it.
@@ -0,0 +1,43 @@
1
+ # Advanced Agentic Systems Guide
2
+
3
+ Building AI that can act, plan, and self-correct.
4
+
5
+ ## 1. The Core Loop: ReAct
6
+ **Reason + Act**. The fundamental pattern for autonomous agents.
7
+ 1. **Thought**: The model reasons about the current state.
8
+ 2. **Action**: The model decides to call a tool.
9
+ 3. **Observation**: The tool output is fed back to the model.
10
+ 4. **Repeat**: Until the goal is met.
11
+
12
+ ## 2. Reflection & Self-Correction
13
+ Models are prone to hallucination. Reflection mitigates this.
14
+ - **The Pattern**: `Draft` -> `Critique` -> `Refine`.
15
+ - **Implementation**:
16
+ - Generate a solution.
17
+ - Prompt the model: "Review the solution above for errors in logic or syntax."
18
+ - Prompt the model: "Based on the critique, generate a fixed version."
19
+
20
+ ## 3. Memory Architecture
21
+ Agents need context beyond the immediate prompt.
22
+ - **Short-Term (Working Memory)**: The current context window. Summary management is key here.
23
+ - **Long-Term (Episodic)**: Vector Database (RAG). Stores past interactions.
24
+ - **Semantic (Knowledge)**: Knowledge Graph. Stores facts and relationships.
25
+
26
+ ## 4. Planning (Chain of Thought)
27
+ For complex tasks, "winging it" fails.
28
+ - **Plan-and-Solve**:
29
+ 1. Ask model to generate a step-by-step plan.
30
+ 2. Execute step 1.
31
+ 3. Feed result back.
32
+ 4. Update plan if needed.
33
+
34
+ ## 5. Tools & Function Calling
35
+ The agent's hands.
36
+ - **Safety**: Always validate tool inputs with JSON Schema (Zod/Pydantic).
37
+ - **Granularity**: Atomic tools (`readFile`, `writeFile`) are better than god-tools (`doEverything`).
38
+ - **Feedback**: Tool outputs must be descriptive. "Error: File not found" is better than "Error".
39
+
40
+ ## 6. Multi-Agent Orchestration
41
+ (See `guides/ai/multi-agent-systems.md` for details)
42
+ - **Orchestrator-Worker**: Delegating sub-tasks.
43
+ - **Consensus**: Multiple agents voting on an answer.
@@ -0,0 +1,71 @@
1
+ # Modern AI-Native Engineering Scenarios
2
+
3
+ This guide explores advanced "in the wild" use cases where GABBE 2.0 excels, leveraging the full power of Loki Mode and Brain Mode.
4
+
5
+ ## 1. Vibe-to-Code (Prototype to Production)
6
+
7
+ **The Scenario:** You've used an AI to quickly "vibe-code" a beautiful landing page or dashboard, but now you need to turn it into a production-grade application with types, tests, and clean architecture.
8
+
9
+ ### Workflow:
10
+ 1. **Prompt:**
11
+ > "Use the vibe-coding skill to analyze my existing prototype in `src/vibe`. Now, use the clean-coder and architecture-design skills to refactor it into a Clean Architecture (Domain, Application, Adapters) with 100% test coverage using Vitest."
12
+ 2. **Key Steps:**
13
+ - **Extract Logic:** The agent separates UI-only "vibe" code from business logic.
14
+ - **Apply Types:** Moving from `any` or loose JS to strict TypeScript.
15
+ - **Add Gates:** Setting up `ESLint` and `Pretier` to enforce the style discovered during the "vibe" phase.
16
+
17
+ ---
18
+
19
+ ## 2. Autonomous Security Fixing (Patching at Velocity)
20
+
21
+ **The Scenario:** Your CI pipeline (via Semgrep or Snyk MCP) detects 5 critical vulnerabilities in a large legacy codebase. You want the agent to fix them autonomously without human hand-holding for every line.
22
+
23
+ ### Workflow:
24
+ 1. **Prompt:**
25
+ > "Run the safety-scan skill on the entire codebase. For every vulnerability found, invoke the self-heal skill. Apply fixes that adhere to OWASP Top 10 standards. Only escalate to me if a fix requires a breaking architecture change."
26
+ 2. **Key Steps:**
27
+ - **Triage:** Agent categorizes vulnerabilities (e.g., SQL Injection, XSS).
28
+ - **TDD Fix:** Agent writes a failing security test that reproduces the vulnerability, then writes the fix.
29
+ - **Regression Check:** Agent runs the full test suite to ensure the security fix didn't break functionality.
30
+
31
+ ---
32
+
33
+ ## 3. Agentic Database Refactoring (Scaling Schema)
34
+
35
+ **The Scenario:** You started with a simple flat-file database or a non-normalized SQLite table. Now you need to migrate to a normalized PostgreSQL schema with relations and indices.
36
+
37
+ ### Workflow:
38
+ 1. **Prompt:**
39
+ > "Use the data-engineering and sql-optimization skills. Analyze my current `database.sqlite` schema. Design a normalized PostgreSQL schema that supports [describe new relationships]. Generate a Sequelize/Prisma migration and the data-porting script."
40
+ 2. **Key Steps:**
41
+ - **Normalization:** Agent identifies redundancy and creates 3NF relations.
42
+ - **Migration Logic:** Agent generates the `UP` and `DOWN` migration files.
43
+ - **Verification:** Agent spins up a local Postgres container (via docker-dev.skill) and runs the migration to verify it passes.
44
+
45
+ ---
46
+
47
+ ## 4. Multi-Agent Competitive Design (Brain Mode)
48
+
49
+ **The Scenario:** You have a high-stakes architectural decision (e.g., GraphQL vs REST for a high-traffic API) and want the agent to simulate a debate between two विशेषज्ञ (specialist) personas.
50
+
51
+ ### Workflow:
52
+ 1. **Prompt:**
53
+ > "Activate Brain Mode. Goal: Decide between GraphQL and REST for our mobile backend. Run a competitive simulation between `arch-architect` (GraphQL proponent) and `ops-sre` (REST proponent). Present a weighted decision matrix in `ARCHITECTURE_DECISION_MATRIX.md`."
54
+ 2. **Key Steps:**
55
+ - **Debate:** The orchestrator runs 2-3 passes of debate, synthesizing the pros/cons.
56
+ - **Simulation:** Agent creates minimal benchmarks for both approaches.
57
+ - **Conclusion:** A final recommendation based on the project's specific constraints (e.g., bandwidth, latency).
58
+
59
+ ---
60
+
61
+ ## 5. Knowledge Distillation (Legacy to Modern)
62
+
63
+ **The Scenario:** You are inheriting a project with zero documentation but 10,000 lines of complex code. You need to understand it *today*.
64
+
65
+ ### Workflow:
66
+ 1. **Prompt:**
67
+ > "Use the research and documentation skills. Recursively analyze the `src/` directory. Create a high-level README_INTERNAL.md explaining the domain model, a C4 component diagram of the wiring, and a list of all known 'gotchas' in `agents/memory/semantic/PROJECT_KNOWLEDGE.md`."
68
+ 2. **Key Steps:**
69
+ - **Ingestion:** Agent reads the code for patterns (not just comments).
70
+ - **Mapping:** Agent uses `diagramming.skill` to visualize the hidden relationships.
71
+ - **Crystallization:** Saving findings in the permanent memory layer for future sessions.
@@ -0,0 +1,42 @@
1
+ # Autonomous Swarm Patterns
2
+
3
+ This guide defines advanced patterns for multi-agent collaboration, self-correction, and tool building.
4
+
5
+ ## 1. The Consensus Pattern (Voting)
6
+ When agents disagree, use `coordination/swarm-consensus.skill.md`.
7
+
8
+ ### Protocol
9
+ 1. **Coordinator** detects conflict (e.g., `prod-architect` wants Microservices, `ops-cost` wants Monolith).
10
+ 2. **Coordinator** calls for a vote using `weighted` protocol.
11
+ 3. **Agents** cast votes based on their persona constraints.
12
+ 4. **Coordinator** logs result to `core/AUDIT_LOG_TEMPLATE.md` and enforces the decision.
13
+
14
+ ## 2. The Toolsmith Pattern (Self-Expansion)
15
+ When the swarm lacks a capability, it builds it.
16
+
17
+ ### Workflow
18
+ 1. **Detection**: Agent fails to perform task due to missing tool.
19
+ 2. **Request**: Agent invokes `eng-tooling`. "Build a script to parse this binary format."
20
+ 3. **Build**: `eng-tooling` writes `tools/parser.py` and validates it.
21
+ 4. **Usage**: The original agent uses the new tool to complete the task.
22
+
23
+ ## 3. The Meta-Cognition Loop (Reflection)
24
+ Agents should think before acting, and reflect after acting.
25
+
26
+ ### Pre-Action (Planning)
27
+ - "I am about to edit 5 files. Is this the safest way? Let me simulate the outcome."
28
+
29
+ ### Post-Action (Reflection)
30
+ - "I edited the file. Did I break the tests? Let me run `integrity-check`."
31
+
32
+ ## 4. Memory Optimization
33
+ - Context windows are finite.
34
+ - Use `ops/memory-optimization.skill.md` to:
35
+ - Summarize completed tasks into `core/AUDIT_LOG_TEMPLATE.md`.
36
+ - "Forget" detailed code snippets once the file is saved.
37
+ - Keep only the "High-Level Plan" in active memory.
38
+
39
+ ## 5. Swarm Topology
40
+ - **Hierarchical**: `orch-coordinator` commands `eng-*` agents. (Standard).
41
+ - **Parliamentary**: All agents vote on decisions. (Use for Architecture/Strategy).
42
+ - **Relay**: Agent A passes output to Agent B (e.g., `spec-writer` -> `eng-backend` -> `eng-qa`).