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.
- package/LICENSE +25 -0
- package/LICENSE-CODE +202 -0
- package/README.md +817 -0
- package/agents/AGENTS.md +542 -0
- package/agents/CONSTITUTION.md +188 -0
- package/agents/guides/00-index.md +142 -0
- package/agents/guides/ai/a2ui-protocols.md +71 -0
- package/agents/guides/ai/actor-agent-frameworks.md +82 -0
- package/agents/guides/ai/agent-communication.md +146 -0
- package/agents/guides/ai/agent-identity-trust.md +69 -0
- package/agents/guides/ai/agent-only-cognition.md +73 -0
- package/agents/guides/ai/agent-only-swarms.md +70 -0
- package/agents/guides/ai/agent-operating-ergonomics.md +52 -0
- package/agents/guides/ai/agent-ui.md +106 -0
- package/agents/guides/ai/ai-agentic.md +309 -0
- package/agents/guides/ai/beyond-llms.md +60 -0
- package/agents/guides/ai/dynamic-capability-loading.md +121 -0
- package/agents/guides/ai/gabbe-innovations.md +111 -0
- package/agents/guides/ai/model-customization-decisions.md +78 -0
- package/agents/guides/ai/multi-agent-systems.md +85 -0
- package/agents/guides/ai/self-evolving-skills.md +137 -0
- package/agents/guides/ai/self-healing-summary.md +21 -0
- package/agents/guides/ai/visual-mcp-integration.md +106 -0
- package/agents/guides/architecture/api-standards.md +61 -0
- package/agents/guides/architecture/blockchain-dlt.md +36 -0
- package/agents/guides/architecture/critical-systems-arch.md +66 -0
- package/agents/guides/architecture/event-driven-architecture.md +39 -0
- package/agents/guides/architecture/microservices.md +292 -0
- package/agents/guides/architecture/monolith.md +303 -0
- package/agents/guides/architecture/orchestration.md +75 -0
- package/agents/guides/architecture/system-qualities.md +51 -0
- package/agents/guides/architecture/system-scalability.md +47 -0
- package/agents/guides/architecture/systems-architecture.md +506 -0
- package/agents/guides/data/semantic-web.md +23 -0
- package/agents/guides/data/sql-nosql.md +305 -0
- package/agents/guides/industry/engineering-standards.md +36 -0
- package/agents/guides/industry/global-standards.md +24 -0
- package/agents/guides/industry/healthcare-fhir.md +33 -0
- package/agents/guides/industry/industrial-iot.md +33 -0
- package/agents/guides/industry/telecom-networks.md +34 -0
- package/agents/guides/languages/c-sharp.md +66 -0
- package/agents/guides/languages/go-lang.md +251 -0
- package/agents/guides/languages/java.md +73 -0
- package/agents/guides/languages/js-ts-nodejs.md +361 -0
- package/agents/guides/languages/nodejs-advanced.md +56 -0
- package/agents/guides/languages/php-laravel.md +376 -0
- package/agents/guides/languages/python-fastapi-ai.md +257 -0
- package/agents/guides/languages/rust.md +73 -0
- package/agents/guides/ops/compliance-audit.md +177 -0
- package/agents/guides/ops/cost-optimization.md +57 -0
- package/agents/guides/ops/dev-environments.md +67 -0
- package/agents/guides/ops/dev-workflow.md +44 -0
- package/agents/guides/ops/gabbe-cli-workflows.md +252 -0
- package/agents/guides/ops/production-health.md +62 -0
- package/agents/guides/ops/troubleshooting-guide.md +69 -0
- package/agents/guides/patterns/agentic-design-patterns.md +308 -0
- package/agents/guides/patterns/agentic-patterns.md +43 -0
- package/agents/guides/patterns/ai-native-scenarios.md +71 -0
- package/agents/guides/patterns/autonomous-swarm-patterns.md +42 -0
- package/agents/guides/patterns/design-patterns.md +68 -0
- package/agents/guides/patterns/enterprise-migration-scenario.md +58 -0
- package/agents/guides/patterns/enterprise-patterns.md +56 -0
- package/agents/guides/patterns/software-design-patterns.md +106 -0
- package/agents/guides/patterns/time-complexity-analysis.md +116 -0
- package/agents/guides/planning/product-requirements.md +407 -0
- package/agents/guides/planning/strategic-analysis.md +98 -0
- package/agents/guides/planning/visual-product-specs.md +162 -0
- package/agents/guides/principles/clean-code-standards.md +51 -0
- package/agents/guides/principles/computing-foundations.md +87 -0
- package/agents/guides/principles/diagramming-standards.md +568 -0
- package/agents/guides/principles/evaluation-strategy.md +103 -0
- package/agents/guides/principles/future-tech.md +35 -0
- package/agents/guides/principles/human-agent-collaboration.md +54 -0
- package/agents/guides/principles/legacy-tech.md +61 -0
- package/agents/guides/principles/mathematical-foundations.md +103 -0
- package/agents/guides/principles/modeling-methods.md +97 -0
- package/agents/guides/principles/no-code-integration.md +84 -0
- package/agents/guides/principles/testing-strategy.md +97 -0
- package/agents/guides/principles/visual-design-system.md +44 -0
- package/agents/guides/processes/RARV_CYCLE.md +262 -0
- package/agents/guides/processes/extension-protocol.md +183 -0
- package/agents/guides/processes/full-system-lifecycle.md +47 -0
- package/agents/guides/processes/knowledge-integration.md +82 -0
- package/agents/guides/processes/loki-sdlc-phases.md +446 -0
- package/agents/guides/product/green-software.md +38 -0
- package/agents/guides/product/sustainability-checks.md +29 -0
- package/agents/guides/security/ai-risk-standards-map.md +98 -0
- package/agents/guides/security/api-security.md +51 -0
- package/agents/guides/security/cryptography-standards.md +38 -0
- package/agents/guides/security/privacy-data-protection.md +41 -0
- package/agents/guides/security/secure-architecture.md +43 -0
- package/agents/guides/security/threat-modeling.md +46 -0
- package/agents/memory/AUDIT_LOG.md +48 -0
- package/agents/memory/CONTINUITY.md +49 -0
- package/agents/memory/PROJECT_STATE.md +134 -0
- package/agents/memory/RESUME_POINTER.md +15 -0
- package/agents/memory/episodic/DECISION_LOG_TEMPLATE.md +104 -0
- package/agents/memory/semantic/PROJECT_KNOWLEDGE_TEMPLATE.md +194 -0
- package/agents/memory/semantic/VECTOR_DB_CONFIG_TEMPLATE.json +46 -0
- package/agents/personas/00-index.md +148 -0
- package/agents/personas/biz-compliance.md +112 -0
- package/agents/personas/biz-legal.md +131 -0
- package/agents/personas/eng-api.md +110 -0
- package/agents/personas/eng-backend.md +113 -0
- package/agents/personas/eng-data.md +50 -0
- package/agents/personas/eng-database.md +95 -0
- package/agents/personas/eng-frontend.md +75 -0
- package/agents/personas/eng-infra.md +105 -0
- package/agents/personas/eng-messaging.md +50 -0
- package/agents/personas/eng-ml.md +50 -0
- package/agents/personas/eng-mobile.md +75 -0
- package/agents/personas/eng-perf.md +90 -0
- package/agents/personas/eng-qa.md +125 -0
- package/agents/personas/eng-tooling.md +49 -0
- package/agents/personas/ops-compliance.md +109 -0
- package/agents/personas/ops-cost.md +92 -0
- package/agents/personas/ops-devops.md +85 -0
- package/agents/personas/ops-incident.md +123 -0
- package/agents/personas/ops-monitor.md +89 -0
- package/agents/personas/ops-release.md +91 -0
- package/agents/personas/ops-security.md +104 -0
- package/agents/personas/ops-sre.md +85 -0
- package/agents/personas/orch-coordinator.md +140 -0
- package/agents/personas/orch-judge.md +135 -0
- package/agents/personas/orch-planner.md +114 -0
- package/agents/personas/orch-researcher.md +165 -0
- package/agents/personas/prod-architect.md +110 -0
- package/agents/personas/prod-design.md +112 -0
- package/agents/personas/prod-ethicist.md +50 -0
- package/agents/personas/prod-integration.md +120 -0
- package/agents/personas/prod-pm.md +115 -0
- package/agents/personas/prod-product-ops.md +128 -0
- package/agents/personas/prod-research.md +49 -0
- package/agents/personas/prod-safety-engineer.md +28 -0
- package/agents/personas/prod-tech-lead.md +119 -0
- package/agents/personas/ui-design.md +81 -0
- package/agents/scripts/check_skills_docs.py +120 -0
- package/agents/scripts/compile_skills.py +284 -0
- package/agents/scripts/comprehensive_checker.py +187 -0
- package/agents/scripts/dump-context.sh +37 -0
- package/agents/scripts/eval_skills.py +268 -0
- package/agents/scripts/preflight_summary.sh +80 -0
- package/agents/scripts/report_duplicates.py +125 -0
- package/agents/scripts/setup-context.ps1 +250 -0
- package/agents/scripts/setup-context.sh +398 -0
- package/agents/scripts/state_export.sh +84 -0
- package/agents/scripts/state_import.sh +99 -0
- package/agents/scripts/validate_integrity.py +98 -0
- package/agents/scripts/validate_links.py +96 -0
- package/agents/scripts/validate_methodology_graph.py +194 -0
- package/agents/scripts/validate_skills.py +81 -0
- package/agents/scripts/verify_e2e_init_flows.py +246 -0
- package/agents/scripts/verify_setup_simulation.py +104 -0
- package/agents/scripts/verify_triggers_and_mcps.py +159 -0
- package/agents/scripts/verify_use_cases.py +498 -0
- package/agents/skills/00-index.md +322 -0
- package/agents/skills/ai/a2ui-protocols.skill.md +31 -0
- package/agents/skills/ai/actor-agent-frameworks.skill.md +31 -0
- package/agents/skills/ai/agent-communication.skill.md +36 -0
- package/agents/skills/ai/agent-ui.skill.md +31 -0
- package/agents/skills/ai/autonomous-swarm-patterns.skill.md +31 -0
- package/agents/skills/ai/beyond-llms.skill.md +31 -0
- package/agents/skills/ai/context-engineering.skill.md +79 -0
- package/agents/skills/ai/llm-as-judge.skill.md +97 -0
- package/agents/skills/ai/multi-agent-systems.skill.md +31 -0
- package/agents/skills/ai/rag-evaluation.skill.md +93 -0
- package/agents/skills/ai/reasoning-patterns.skill.md +125 -0
- package/agents/skills/architecture/adaptive-architecture.skill.md +51 -0
- package/agents/skills/architecture/api-design.skill.md +92 -0
- package/agents/skills/architecture/api-standards.skill.md +31 -0
- package/agents/skills/architecture/arch-debt.skill.md +180 -0
- package/agents/skills/architecture/arch-design.skill.md +304 -0
- package/agents/skills/architecture/arch-patterns.skill.md +52 -0
- package/agents/skills/architecture/arch-review.skill.md +326 -0
- package/agents/skills/architecture/architecture-governance.skill.md +62 -0
- package/agents/skills/architecture/attribute-driven-design.skill.md +108 -0
- package/agents/skills/architecture/blockchain-dlt.skill.md +28 -0
- package/agents/skills/architecture/compatibility-design.skill.md +51 -0
- package/agents/skills/architecture/critical-systems-arch.skill.md +31 -0
- package/agents/skills/architecture/design-patterns.skill.md +59 -0
- package/agents/skills/architecture/diagramming.skill.md +380 -0
- package/agents/skills/architecture/domain-model.skill.md +294 -0
- package/agents/skills/architecture/enterprise-migration-scenario.skill.md +31 -0
- package/agents/skills/architecture/enterprise-patterns.skill.md +31 -0
- package/agents/skills/architecture/error-handling-strategy.skill.md +58 -0
- package/agents/skills/architecture/event-driven-architecture.skill.md +31 -0
- package/agents/skills/architecture/event-governance.skill.md +55 -0
- package/agents/skills/architecture/fitness-functions.skill.md +111 -0
- package/agents/skills/architecture/graphql-schema.skill.md +64 -0
- package/agents/skills/architecture/legacy-modernization.skill.md +51 -0
- package/agents/skills/architecture/microservices.skill.md +31 -0
- package/agents/skills/architecture/middleware-design.skill.md +59 -0
- package/agents/skills/architecture/monolith.skill.md +31 -0
- package/agents/skills/architecture/realtime-comm.skill.md +52 -0
- package/agents/skills/architecture/state-management.skill.md +72 -0
- package/agents/skills/architecture/system-qualities.skill.md +31 -0
- package/agents/skills/architecture/system-scalability.skill.md +31 -0
- package/agents/skills/architecture/systems-architecture.skill.md +31 -0
- package/agents/skills/architecture/visual-whiteboarding.skill.md +33 -0
- package/agents/skills/brain/README.md +70 -0
- package/agents/skills/brain/active-inference.skill.md +74 -0
- package/agents/skills/brain/brain-mode.skill.md +125 -0
- package/agents/skills/brain/cognitive-architectures.skill.md +53 -0
- package/agents/skills/brain/cognitive-testing.skill.md +62 -0
- package/agents/skills/brain/consciousness-loop.skill.md +68 -0
- package/agents/skills/brain/cost-benefit-router.skill.md +89 -0
- package/agents/skills/brain/episodic-consolidation.skill.md +43 -0
- package/agents/skills/brain/epistemology-knowledge.skill.md +54 -0
- package/agents/skills/brain/global-workspace.skill.md +77 -0
- package/agents/skills/brain/learning-adaptation.skill.md +68 -0
- package/agents/skills/brain/loki-mode.skill.md +267 -0
- package/agents/skills/brain/neuroscience-foundations.skill.md +52 -0
- package/agents/skills/brain/scripts/active_inference_loop.py +92 -0
- package/agents/skills/brain/scripts/cognition_test.py +80 -0
- package/agents/skills/brain/scripts/global_workspace.py +104 -0
- package/agents/skills/brain/self-improvement.skill.md +80 -0
- package/agents/skills/brain/sensory-motor.skill.md +61 -0
- package/agents/skills/brain/sequential-thinking.skill.md +48 -0
- package/agents/skills/brain/working-memory.skill.md +47 -0
- package/agents/skills/coding/agent-trajectory-eval.skill.md +92 -0
- package/agents/skills/coding/artisan-commands.skill.md +52 -0
- package/agents/skills/coding/browser-tdd.skill.md +131 -0
- package/agents/skills/coding/chaos-fault-injection.skill.md +116 -0
- package/agents/skills/coding/ci-autofix.skill.md +53 -0
- package/agents/skills/coding/clean-coder.skill.md +58 -0
- package/agents/skills/coding/code-review.skill.md +100 -0
- package/agents/skills/coding/debug.skill.md +100 -0
- package/agents/skills/coding/documentation.skill.md +149 -0
- package/agents/skills/coding/eval-driven-development.skill.md +107 -0
- package/agents/skills/coding/evals/code-review.eval.yaml +29 -0
- package/agents/skills/coding/excalidraw.skill.md +90 -0
- package/agents/skills/coding/file-processing.skill.md +55 -0
- package/agents/skills/coding/git-workflow.skill.md +153 -0
- package/agents/skills/coding/metamorphic-testing.skill.md +113 -0
- package/agents/skills/coding/mobile-dev.skill.md +41 -0
- package/agents/skills/coding/nodejs-expert.skill.md +23 -0
- package/agents/skills/coding/output-validation.skill.md +57 -0
- package/agents/skills/coding/pbt-strategy.skill.md +117 -0
- package/agents/skills/coding/performant-ai.skill.md +62 -0
- package/agents/skills/coding/performant-go.skill.md +61 -0
- package/agents/skills/coding/performant-laravel.skill.md +70 -0
- package/agents/skills/coding/performant-nodejs.skill.md +67 -0
- package/agents/skills/coding/performant-php.skill.md +53 -0
- package/agents/skills/coding/performant-python.skill.md +62 -0
- package/agents/skills/coding/refactor.skill.md +124 -0
- package/agents/skills/coding/secure-coding.skill.md +57 -0
- package/agents/skills/coding/sketch-to-diagram.skill.md +106 -0
- package/agents/skills/coding/spec-driven-development.skill.md +110 -0
- package/agents/skills/coding/tdd-cycle.skill.md +92 -0
- package/agents/skills/coding/testing-strategy.skill.md +74 -0
- package/agents/skills/coding/time-complexity.skill.md +112 -0
- package/agents/skills/coding/tldraw-canvas.skill.md +109 -0
- package/agents/skills/coding/tool-construction.skill.md +47 -0
- package/agents/skills/coding/ui-gen.skill.md +64 -0
- package/agents/skills/coding/vibe-coding.skill.md +63 -0
- package/agents/skills/coding/visual-design.skill.md +65 -0
- package/agents/skills/coordination/agent-interop.skill.md +72 -0
- package/agents/skills/coordination/agent-protocol.skill.md +62 -0
- package/agents/skills/coordination/agent-workflow-patterns.skill.md +123 -0
- package/agents/skills/coordination/agentic-linter.skill.md +134 -0
- package/agents/skills/coordination/agentic-patterns.skill.md +79 -0
- package/agents/skills/coordination/meta-optimize.skill.md +62 -0
- package/agents/skills/coordination/meta-prompting.skill.md +46 -0
- package/agents/skills/coordination/multi-agent-orch.skill.md +78 -0
- package/agents/skills/coordination/persona-selector.skill.md +78 -0
- package/agents/skills/coordination/self-optimize.skill.md +81 -0
- package/agents/skills/coordination/swarm-consensus.skill.md +52 -0
- package/agents/skills/core/agent-analytics.skill.md +74 -0
- package/agents/skills/core/audit-trail.skill.md +122 -0
- package/agents/skills/core/clarify.skill.md +89 -0
- package/agents/skills/core/emerging-tech.skill.md +52 -0
- package/agents/skills/core/empirical-methods.skill.md +101 -0
- package/agents/skills/core/evals/clarify.eval.yaml +29 -0
- package/agents/skills/core/evals/integrity-check.eval.yaml +23 -0
- package/agents/skills/core/evals/research.eval.yaml +23 -0
- package/agents/skills/core/final-review.skill.md +66 -0
- package/agents/skills/core/integrity-check.skill.md +149 -0
- package/agents/skills/core/knowledge-connect.skill.md +77 -0
- package/agents/skills/core/knowledge-gap.skill.md +123 -0
- package/agents/skills/core/preflight.skill.md +106 -0
- package/agents/skills/core/research.skill.md +107 -0
- package/agents/skills/core/retrospective.skill.md +59 -0
- package/agents/skills/core/sdlc-checkpoint.skill.md +151 -0
- package/agents/skills/core/self-heal.skill.md +163 -0
- package/agents/skills/core/session-resume.skill.md +125 -0
- package/agents/skills/core/skills-registry.skill.md +65 -0
- package/agents/skills/core/state-portability.skill.md +89 -0
- package/agents/skills/core/state-preserve.skill.md +76 -0
- package/agents/skills/core/system-lifecycle.skill.md +51 -0
- package/agents/skills/core/update-scan.skill.md +92 -0
- package/agents/skills/data/data-engineering.skill.md +56 -0
- package/agents/skills/data/data-governance.skill.md +49 -0
- package/agents/skills/data/db-migration.skill.md +136 -0
- package/agents/skills/data/semantic-web.skill.md +28 -0
- package/agents/skills/data/sql-optimization.skill.md +78 -0
- package/agents/skills/industry/engineering-standards.skill.md +31 -0
- package/agents/skills/industry/global-standards.skill.md +30 -0
- package/agents/skills/industry/healthcare-fhir.skill.md +28 -0
- package/agents/skills/industry/industrial-iot.skill.md +30 -0
- package/agents/skills/industry/telecom-networks.skill.md +30 -0
- package/agents/skills/ops/caching-strategy.skill.md +77 -0
- package/agents/skills/ops/capacity-planning.skill.md +67 -0
- package/agents/skills/ops/cloud-deploy.skill.md +55 -0
- package/agents/skills/ops/configuration-management.skill.md +107 -0
- package/agents/skills/ops/cost-optimization.skill.md +39 -0
- package/agents/skills/ops/decommission-sunset.skill.md +64 -0
- package/agents/skills/ops/dependency-lifecycle.skill.md +63 -0
- package/agents/skills/ops/deployment.skill.md +217 -0
- package/agents/skills/ops/dev-environments.skill.md +31 -0
- package/agents/skills/ops/dev-workflow.skill.md +28 -0
- package/agents/skills/ops/docker-dev.skill.md +52 -0
- package/agents/skills/ops/enterprise-integration.skill.md +53 -0
- package/agents/skills/ops/feature-flag-management.skill.md +59 -0
- package/agents/skills/ops/incident-response.skill.md +40 -0
- package/agents/skills/ops/infra-devops.skill.md +53 -0
- package/agents/skills/ops/k8s-dev.skill.md +51 -0
- package/agents/skills/ops/memory-optimization.skill.md +45 -0
- package/agents/skills/ops/observability-stack-setup.skill.md +62 -0
- package/agents/skills/ops/performance-audit.skill.md +178 -0
- package/agents/skills/ops/performance-optimization.skill.md +51 -0
- package/agents/skills/ops/production-health.skill.md +85 -0
- package/agents/skills/ops/production-verifier.skill.md +50 -0
- package/agents/skills/ops/queue-management.skill.md +52 -0
- package/agents/skills/ops/release-management.skill.md +39 -0
- package/agents/skills/ops/release-validation.skill.md +51 -0
- package/agents/skills/ops/reliability-sre.skill.md +51 -0
- package/agents/skills/ops/runbook-authoring.skill.md +64 -0
- package/agents/skills/ops/system-benchmark.skill.md +69 -0
- package/agents/skills/ops/tech-debt.skill.md +143 -0
- package/agents/skills/ops/troubleshooting-guide.skill.md +31 -0
- package/agents/skills/product/accessibility.skill.md +143 -0
- package/agents/skills/product/adr-writer.skill.md +110 -0
- package/agents/skills/product/business-case.skill.md +70 -0
- package/agents/skills/product/change-management.skill.md +90 -0
- package/agents/skills/product/decompose.skill.md +75 -0
- package/agents/skills/product/design-thinking.skill.md +62 -0
- package/agents/skills/product/estimation-sizing.skill.md +87 -0
- package/agents/skills/product/evals/spec-writer.eval.yaml +22 -0
- package/agents/skills/product/financial-governance.skill.md +88 -0
- package/agents/skills/product/green-software.skill.md +46 -0
- package/agents/skills/product/ideation-facilitation.skill.md +87 -0
- package/agents/skills/product/market-analysis.skill.md +56 -0
- package/agents/skills/product/opportunity-assessment.skill.md +89 -0
- package/agents/skills/product/product-analytics.skill.md +92 -0
- package/agents/skills/product/professional-practice.skill.md +105 -0
- package/agents/skills/product/req-elicitation.skill.md +292 -0
- package/agents/skills/product/req-review.skill.md +280 -0
- package/agents/skills/product/spec-analyze.skill.md +98 -0
- package/agents/skills/product/spec-writer.skill.md +114 -0
- package/agents/skills/product/stakeholder-management.skill.md +54 -0
- package/agents/skills/product/sustainability-checks.skill.md +29 -0
- package/agents/skills/product/systems-thinking.skill.md +56 -0
- package/agents/skills/product/user-research-synthesis.skill.md +85 -0
- package/agents/skills/product/user-story-mapping.skill.md +54 -0
- package/agents/skills/product/visual-specs.skill.md +112 -0
- package/agents/skills/security/access-control.skill.md +45 -0
- package/agents/skills/security/agent-sandboxing.skill.md +69 -0
- package/agents/skills/security/ai-ethics-compliance.skill.md +46 -0
- package/agents/skills/security/ai-red-teaming.skill.md +74 -0
- package/agents/skills/security/ai-safety-guardrails.skill.md +60 -0
- package/agents/skills/security/api-security.skill.md +31 -0
- package/agents/skills/security/backup-recovery.skill.md +49 -0
- package/agents/skills/security/compliance-review.skill.md +152 -0
- package/agents/skills/security/cryptography-standards.skill.md +31 -0
- package/agents/skills/security/dependency-security.skill.md +47 -0
- package/agents/skills/security/hazard-analysis.skill.md +53 -0
- package/agents/skills/security/legal-review.skill.md +41 -0
- package/agents/skills/security/log-analysis.skill.md +68 -0
- package/agents/skills/security/network-security.skill.md +64 -0
- package/agents/skills/security/privacy-audit.skill.md +137 -0
- package/agents/skills/security/privacy-data-protection.skill.md +31 -0
- package/agents/skills/security/prompt-injection-defense.skill.md +67 -0
- package/agents/skills/security/reliability-engineering.skill.md +47 -0
- package/agents/skills/security/safety-scan.skill.md +49 -0
- package/agents/skills/security/secrets-management.skill.md +65 -0
- package/agents/skills/security/secure-architecture.skill.md +31 -0
- package/agents/skills/security/security-audit.skill.md +164 -0
- package/agents/skills/security/threat-model.skill.md +120 -0
- package/agents/skills/security/traceability-audit.skill.md +48 -0
- package/agents/templates/00-index.md +162 -0
- package/agents/templates/architecture/ADAPTIVE_SYSTEM_TEMPLATE.md +35 -0
- package/agents/templates/architecture/ADD_WORKBOOK_TEMPLATE.md +81 -0
- package/agents/templates/architecture/ADR_TEMPLATE.md +136 -0
- package/agents/templates/architecture/ARCHITECTURE_DECISION_MATRIX.md +169 -0
- package/agents/templates/architecture/ARCHITECTURE_REVIEW_TEMPLATE.md +241 -0
- package/agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md +353 -0
- package/agents/templates/architecture/ARCH_DECISION_FRAMEWORK.md +32 -0
- package/agents/templates/architecture/C4_ARCHITECTURE_TEMPLATE.md +185 -0
- package/agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md +153 -0
- package/agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md +196 -0
- package/agents/templates/architecture/DESIGN_PATTERN_USAGE.md +24 -0
- package/agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md +254 -0
- package/agents/templates/architecture/FITNESS_FUNCTION_TEMPLATE.md +59 -0
- package/agents/templates/architecture/INTEGRATION_SPEC_TEMPLATE.md +38 -0
- package/agents/templates/architecture/LEGACY_AUDIT_TEMPLATE.md +34 -0
- package/agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md +210 -0
- package/agents/templates/architecture/SCALABILITY_ANALYSIS_TEMPLATE.md +46 -0
- package/agents/templates/architecture/SMART_CONTRACT_TEMPLATE.md +44 -0
- package/agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md +197 -0
- package/agents/templates/brain/ACTIVE_INFERENCE_LOOP_TEMPLATE.md +42 -0
- package/agents/templates/brain/EPISODIC_MEMORY_LOG_TEMPLATE.md +28 -0
- package/agents/templates/brain/GLOBAL_WORKSPACE_CONFIG_TEMPLATE.md +44 -0
- package/agents/templates/brain/KNOWLEDGE_MAP_TEMPLATE.md +53 -0
- package/agents/templates/brain/OODA_LOOP_TRACE_TEMPLATE.md +44 -0
- package/agents/templates/brain/PREDICTION_ERROR_LOG_TEMPLATE.md +33 -0
- package/agents/templates/brain/PROJECT_CONTEXT_TEMPLATE.md +36 -0
- package/agents/templates/brain/SELF_IMPROVEMENT_LOG_TEMPLATE.md +39 -0
- package/agents/templates/brain/WORKING_MEMORY_TEMPLATE.md +34 -0
- package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +30 -0
- package/agents/templates/coding/DESIGN_TOKENS_TEMPLATE.json +54 -0
- package/agents/templates/coding/DEVCONTAINER_TEMPLATE.json +42 -0
- package/agents/templates/coding/DEV_SPACE_TEMPLATE.yaml +48 -0
- package/agents/templates/coding/E2E_TEST_SUITE_TEMPLATE.md +36 -0
- package/agents/templates/coding/EVAL_PLAN_TEMPLATE.md +85 -0
- package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +57 -0
- package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +73 -0
- package/agents/templates/coding/PROPERTY_TEST_CHECKLIST.md +77 -0
- package/agents/templates/coding/SKETCH_TO_DIAGRAM_TEMPLATE.md +56 -0
- package/agents/templates/coding/TEST_CASE_TEMPLATE.md +28 -0
- package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +36 -0
- package/agents/templates/coding/TIME_COMPLEXITY_REPORT_TEMPLATE.md +61 -0
- package/agents/templates/coordination/AGENTS_TEMPLATE.md +540 -0
- package/agents/templates/coordination/AGENT_HANDSHAKE_TEMPLATE.json +37 -0
- package/agents/templates/coordination/AGENT_PROFILE_TEMPLATE.md +28 -0
- package/agents/templates/coordination/SWARM_ARCHITECTURE_TEMPLATE.md +53 -0
- package/agents/templates/coordination/SWARM_CONFIG_TEMPLATE.json +45 -0
- package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +75 -0
- package/agents/templates/core/BUG_REPORT_TEMPLATE.md +136 -0
- package/agents/templates/core/DEPENDENCY_GRAPH_TEMPLATE.md +63 -0
- package/agents/templates/core/ESTIMATION_TEMPLATE.md +70 -0
- package/agents/templates/core/MCP_CONFIG_TEMPLATE.json +807 -0
- package/agents/templates/core/PLAN_TEMPLATE.md +162 -0
- package/agents/templates/core/PROJECT_RETROSPECTIVE_TEMPLATE.md +67 -0
- package/agents/templates/core/SDLC_TRACKER.md +217 -0
- package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +168 -0
- package/agents/templates/core/SYSTEM_ANALYSIS_TEMPLATE.md +52 -0
- package/agents/templates/core/TASKS_TEMPLATE.md +104 -0
- package/agents/templates/core/TRACEABILITY_MATRIX_TEMPLATE.md +18 -0
- package/agents/templates/core/WHITEBOARD_DESIGN_TEMPLATE.md +46 -0
- package/agents/templates/data/DATABASE_SCHEMA_TEMPLATE.md +38 -0
- package/agents/templates/data/DATA_PIPELINE_TEMPLATE.md +44 -0
- package/agents/templates/data/ONTOLOGY_TEMPLATE.md +52 -0
- package/agents/templates/industry/ENGINEERING_STANDARDS_REVIEW_TEMPLATE.md +43 -0
- package/agents/templates/industry/FHIR_INTEGRATION_TEMPLATE.md +53 -0
- package/agents/templates/industry/GLOBAL_STANDARDS_AUDIT_TEMPLATE.md +45 -0
- package/agents/templates/industry/IOT_TELEMETRY_TEMPLATE.md +59 -0
- package/agents/templates/industry/TELECOM_API_TEMPLATE.md +50 -0
- package/agents/templates/ops/BENCHMARK_REPORT_TEMPLATE.md +48 -0
- package/agents/templates/ops/CAPACITY_PLAN_TEMPLATE.md +41 -0
- package/agents/templates/ops/COST_OPTIMIZATION_REPORT_TEMPLATE.md +40 -0
- package/agents/templates/ops/DECOMMISSION_PLAN_TEMPLATE.md +102 -0
- package/agents/templates/ops/DEPLOY_CONFIG_TEMPLATE.md +88 -0
- package/agents/templates/ops/INCIDENT_POSTMORTEM_TEMPLATE.md +39 -0
- package/agents/templates/ops/INFRA_PLAN_TEMPLATE.md +37 -0
- package/agents/templates/ops/RELEASE_READINESS_REPORT.md +35 -0
- package/agents/templates/ops/RUNBOOK_TEMPLATE.md +103 -0
- package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +102 -0
- package/agents/templates/product/BUSINESS_CASE_TEMPLATE.md +42 -0
- package/agents/templates/product/CHANGE_MANAGEMENT_PLAN_TEMPLATE.md +68 -0
- package/agents/templates/product/EMPATHY_MAP_TEMPLATE.md +47 -0
- package/agents/templates/product/EXPERIMENT_PLAN_TEMPLATE.md +84 -0
- package/agents/templates/product/GREEN_SOFTWARE_REPORT_TEMPLATE.md +42 -0
- package/agents/templates/product/IDEATION_LOG_TEMPLATE.md +42 -0
- package/agents/templates/product/NFR_TEMPLATE.md +31 -0
- package/agents/templates/product/PRD_TEMPLATE.md +222 -0
- package/agents/templates/product/PROBLEM_STATEMENT_TEMPLATE.md +32 -0
- package/agents/templates/product/REQUIREMENTS_REVIEW_TEMPLATE.md +173 -0
- package/agents/templates/product/SPEC_TEMPLATE.md +259 -0
- package/agents/templates/product/STAKEHOLDER_REGISTER_TEMPLATE.md +127 -0
- package/agents/templates/product/USER_STORY_MAP_TEMPLATE.md +35 -0
- package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +207 -0
- package/agents/templates/security/DATASHEET_TEMPLATE.md +95 -0
- package/agents/templates/security/ETHICAL_IMPACT_ASSESSMENT.md +32 -0
- package/agents/templates/security/HAZARD_LOG.md +17 -0
- package/agents/templates/security/MODEL_CARD_TEMPLATE.md +120 -0
- package/agents/templates/security/SAFETY_CASE.md +39 -0
- package/agents/templates/security/SAFETY_POLICY.md +25 -0
- package/agents/templates/security/SECURITY_CHECKLIST.md +157 -0
- package/agents/templates/security/SYSTEM_CARD_TEMPLATE.md +139 -0
- package/agents/templates/security/THREAT_MODEL_TEMPLATE.md +171 -0
- package/bin/install.js +572 -0
- package/docs/CLI_REFERENCE.md +527 -0
- package/docs/INSTALL.md +68 -0
- package/docs/MCP_CONFIGURATIONS.md +1765 -0
- package/docs/PLATFORM_CONTROLS.md +324 -0
- package/docs/POST_INSTALL.md +75 -0
- package/docs/QUICK_COMMANDS.md +131 -0
- package/docs/QUICK_GUIDE.md +914 -0
- package/docs/README_FULL.md +1451 -0
- package/docs/SCHEMA.md +164 -0
- package/docs/V1_RELEASE_CHECKLIST.md +144 -0
- package/docs/VERIFICATION_GUIDE.md +283 -0
- package/docs/adr/0001-record-architecture-decisions.md +26 -0
- package/docs/adr/0002-brain-active-inference-runtime.md +27 -0
- package/docs/adr/0003-additive-only-emitter-schema-evolution.md +33 -0
- package/docs/assets/GABBE.png +0 -0
- package/docs/gabbe.config.example.json +9 -0
- package/docs/reports/duplication-report.md +30 -0
- package/install.ps1 +90 -0
- package/install.sh +89 -0
- package/package.json +49 -0
- 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`).
|