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,78 @@
|
|
|
1
|
+
# Model Customization Decisions: Prompt Engineering vs RAG vs Fine-Tuning
|
|
2
|
+
|
|
3
|
+
## 1. What This Guide Decides
|
|
4
|
+
|
|
5
|
+
This is the **build-time** decision: given a task, how do you make a model good enough at it? The three primary levers — prompt engineering, retrieval-augmented generation (RAG), and fine-tuning — solve different problems, and reaching for the wrong one wastes time and money. This guide complements `cost-benefit-router.skill`, which handles the *runtime* local/remote routing decision; here we choose *how the model is customized in the first place*, before any request is routed.
|
|
6
|
+
|
|
7
|
+
Honest note up front: do not fine-tune prematurely. Most teams that think they need a fine-tune actually need a better prompt or better retrieval. Measure on your own evals (`eval-driven-development.skill`) before and after any change — a customization that does not move your eval numbers is cost without benefit.
|
|
8
|
+
|
|
9
|
+
## 2. The Decision Ladder
|
|
10
|
+
|
|
11
|
+
Climb the ladder in order. Stop at the first rung that meets your eval bar; only climb when you have measured that the current rung is insufficient.
|
|
12
|
+
|
|
13
|
+
1. **Start with prompt engineering.** Cheapest, fastest to iterate, no training pipeline. Clarify the instruction, add few-shot examples, structure the output, and decompose the task. A large fraction of "the model can't do this" problems dissolve here.
|
|
14
|
+
2. **Add RAG when the problem is *knowledge*.** If the model fails because it lacks fresh, proprietary, or long-tail facts — not because it lacks skill — give it the right context at inference time via retrieval. RAG keeps knowledge external, updatable without retraining, and citable. Use it for anything that changes (docs, policies, catalogs, tickets) or that the base model never saw.
|
|
15
|
+
3. **Fine-tune when the problem is *behavior, format, or latency*.** If the model knows the facts and has the context but still won't reliably produce the *style*, *structure*, *tone*, or *decision pattern* you need — or you need to bake a capability into a smaller, cheaper, faster model — fine-tune. Fine-tuning teaches *how* to respond, not *what* facts to know.
|
|
16
|
+
|
|
17
|
+
**Combine them.** These are not mutually exclusive. A common strong pattern is a fine-tuned model (for format/behavior and tool-calling reliability) that is fed retrieved context (RAG, for fresh knowledge) under a carefully engineered prompt. Prompt + RAG + fine-tune is the upper end, not three competing options.
|
|
18
|
+
|
|
19
|
+
## 3. When Each Is the Right Tool
|
|
20
|
+
|
|
21
|
+
| Symptom | Likely fix | Why |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| Output is close but wrong shape/tone | Prompt engineering | Instruction/format problem, not capability |
|
|
24
|
+
| Model lacks current or private facts | RAG | Knowledge is external and changes |
|
|
25
|
+
| Answers must be grounded and citable | RAG | Retrieval gives source attribution |
|
|
26
|
+
| Model knows facts but won't follow the pattern reliably | Fine-tune | Behavior must be learned, not instructed |
|
|
27
|
+
| Need a smaller/cheaper/faster model to match a big one on a narrow task | Fine-tune (often via distillation) | Specialize capability into a small model |
|
|
28
|
+
| Domain jargon or output schema the base model fumbles | Fine-tune | Format/behavior specialization |
|
|
29
|
+
| Task is broad and open-ended | Larger base model + prompt + RAG | Specialization would over-narrow |
|
|
30
|
+
|
|
31
|
+
## 4. Model Routing and Cascades
|
|
32
|
+
|
|
33
|
+
You rarely need one model for everything. Route by difficulty:
|
|
34
|
+
|
|
35
|
+
- **Cascade (cheap-first, escalate-on-low-confidence)**: try a cheap, fast model first; if its confidence or a verifier check is low, escalate the request to a stronger, more expensive model. Most traffic is easy and never escalates, so the average cost approaches the cheap model while quality on hard cases approaches the strong model.
|
|
36
|
+
- **Confidence signals**: use self-reported confidence, a verifier/judge pass, output-validation failure, or retrieval-grounding checks as the escalation trigger. Calibrate the threshold on your evals — too eager an escalation erodes the savings.
|
|
37
|
+
- **Relationship to runtime routing**: the cascade is the build-time *design*; the live cheap-vs-capable and local-vs-remote dispatch is owned by `cost-benefit-router.skill`. Design the cascade here, let the router execute it at runtime.
|
|
38
|
+
|
|
39
|
+
## 5. Small Language Models (SLMs) for Agentic Subtasks
|
|
40
|
+
|
|
41
|
+
In an agentic system, most steps are narrow: parse this, call that tool, classify this, extract those fields. Narrow steps rarely need a frontier model.
|
|
42
|
+
|
|
43
|
+
- **Why SLMs**: a small, specialized model is often roughly 10–30x cheaper per call and lower latency than a frontier model, and for a narrow, well-defined role (especially structured tool-calling and classification) it can match the big model's task quality after light fine-tuning.
|
|
44
|
+
- **Heterogeneous systems**: prefer a mix — SLMs for the high-volume narrow roles, a frontier model reserved for genuinely hard planning/reasoning steps. This is usually the dominant cost lever in an agent, because the narrow steps are the high-volume ones.
|
|
45
|
+
- **Fit check**: an SLM is a good fit when the role has a tight input/output contract and a clear eval; it is a poor fit for open-ended reasoning, long-horizon planning, or tasks where the failure mode is subtle.
|
|
46
|
+
|
|
47
|
+
## 6. Distillation and Quantization
|
|
48
|
+
|
|
49
|
+
- **Distillation**: train a small "student" model to imitate a large "teacher" (or the teacher's outputs) on your task distribution. This is the standard route to an SLM that punches above its size on a narrow task — you transfer the teacher's behavior into a cheaper-to-run model.
|
|
50
|
+
- **Quantization**: reduce the numerical precision of a model's weights (and sometimes activations) to shrink memory and speed up inference, typically with a small, measurable quality cost. Use it to fit a model on smaller/cheaper hardware or on-device.
|
|
51
|
+
- **Always re-measure**: both techniques trade some quality for cost/latency. The trade is only acceptable if it holds on *your* evals, not on a generic benchmark.
|
|
52
|
+
|
|
53
|
+
## 7. On-Device / Local Tradeoffs
|
|
54
|
+
|
|
55
|
+
Running a model locally or on-device buys privacy (data never leaves the device), offline capability, and zero per-call API cost — at the price of a capability ceiling (you can only run models that fit the hardware), upgrade friction, and the engineering cost of local serving. Local is attractive for privacy-sensitive, high-volume, or offline-required workloads, and is usually paired with quantized SLMs. The live local-vs-remote dispatch decision belongs to `cost-benefit-router.skill`; this guide's job is to decide *whether you have built a local-capable model worth dispatching to*.
|
|
56
|
+
|
|
57
|
+
## 8. Cost / Latency / Quality Tradeoff
|
|
58
|
+
|
|
59
|
+
| Approach | Setup cost | Per-call cost | Latency | Quality ceiling | Knowledge freshness |
|
|
60
|
+
|---|---|---|---|---|---|
|
|
61
|
+
| Prompt engineering | Very low | Base model rate | Base | Bounded by base model | Static (model's cutoff) |
|
|
62
|
+
| RAG | Low–medium | Base + retrieval | Base + retrieval | High on grounded facts | Live / updatable |
|
|
63
|
+
| Fine-tuning | High (training) | Often lower (smaller model) | Often lower | High on the trained behavior | Static unless paired with RAG |
|
|
64
|
+
| SLM (often distilled) | Medium | Very low (~10–30x cheaper) | Low | High on narrow role only | Static unless paired with RAG |
|
|
65
|
+
| Quantized / on-device | Medium | Near zero | Low–medium | Hardware-bounded | Static unless paired with RAG |
|
|
66
|
+
| Cascade (cheap→strong) | Medium | Near cheap-model average | Variable | Near strong-model on hard cases | Depends on members |
|
|
67
|
+
|
|
68
|
+
Note: the per-call and latency figures are directional — measure the actual numbers on your workload and hardware before committing.
|
|
69
|
+
|
|
70
|
+
## 9. Decision Checklist
|
|
71
|
+
|
|
72
|
+
- Have you exhausted prompt engineering before reaching for anything heavier? Most "model can't" problems are prompt problems.
|
|
73
|
+
- Is the failure a *knowledge* gap (→ RAG) or a *behavior/format/latency* gap (→ fine-tune)? Name it before choosing.
|
|
74
|
+
- Can a small or distilled model cover this narrow role at a fraction of the cost? Default agentic subtasks to SLMs.
|
|
75
|
+
- Have you designed a cheap-first cascade so frontier-model calls are the exception, not the rule?
|
|
76
|
+
- Did you re-run your evals (`eval-driven-development.skill`) before and after every customization, and confirm the change actually moved the numbers?
|
|
77
|
+
- For local/on-device, did you confirm the quantized model still clears your eval bar?
|
|
78
|
+
- Have you avoided fine-tuning until prompt + RAG were measurably insufficient?
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Multi-Agent Systems (MAS) Development Guide
|
|
2
|
+
|
|
3
|
+
## 1. Introduction
|
|
4
|
+
This guide provides a structured approach to building Multi-Agent Systems (MAS) using the `agents` kit. MAS architectures allow specialized agents to collaborate on complex tasks, overcoming the limitations of single-context windows.
|
|
5
|
+
|
|
6
|
+
## 2. Core Concepts
|
|
7
|
+
- **Specialization**: Each agent has a distinct "persona" and set of tools.
|
|
8
|
+
- **Orchestration**: How agents specific tasks are assigned and coordinated.
|
|
9
|
+
- **Protocol**: The agreed-upon format for inter-agent communication.
|
|
10
|
+
- **State**: How context and memory are shared (or isolated) between agents.
|
|
11
|
+
|
|
12
|
+
## 3. Common Architectures
|
|
13
|
+
|
|
14
|
+
### A. Orchestrator-Worker (Star Topology)
|
|
15
|
+
Best for: Task delegation where a central "brain" manages "hands".
|
|
16
|
+
- **Orchestrator**: Plans high-level steps, delegates to workers.
|
|
17
|
+
- **Workers**: Execute specific sub-tasks (e.g., "Research", "Code", "Test").
|
|
18
|
+
- **Flow**: User -> Orchestrator -> Worker -> Orchestrator -> User.
|
|
19
|
+
|
|
20
|
+
### B. Sequential (Pipeline)
|
|
21
|
+
Best for: Deterministic workflows like data processing chains.
|
|
22
|
+
- **Flow**: Agent A (Draft) -> Agent B (Review) -> Agent C (Publish).
|
|
23
|
+
- **Handoff**: Strict output schema from A becomes input schema for B.
|
|
24
|
+
|
|
25
|
+
### C. Hierarchical (Tree)
|
|
26
|
+
Best for: Complex problems needing breakdown.
|
|
27
|
+
- **Manager**: Breaks down "Epics" into "Stories".
|
|
28
|
+
- **Team Leads**: Break down "Stories" into "Tasks".
|
|
29
|
+
- **Developers**: Execute "Tasks".
|
|
30
|
+
|
|
31
|
+
## 4. Implementation Stack
|
|
32
|
+
|
|
33
|
+
### Python (The Brain)
|
|
34
|
+
Python is the standard for agent logic due to libraries like LangGraph, CrewAI, and AutoGen.
|
|
35
|
+
- **Role**: Running the LLM loop, managing context, executing tools.
|
|
36
|
+
- **Key Libs**: `langgraph`, `crewai`, `autogen`.
|
|
37
|
+
|
|
38
|
+
### Node.js (The Nervous System)
|
|
39
|
+
Node.js excels at I/O, websockets, and serving the API.
|
|
40
|
+
- **Role**: API Gateway, WebSocket server for real-time updates.
|
|
41
|
+
- **Integration**: Expose Python agents via REST/gRPC to Node.js.
|
|
42
|
+
|
|
43
|
+
### React (The Face)
|
|
44
|
+
- **Role**: User Interface for chatting with agents and visualizing swarm state.
|
|
45
|
+
- **Pattern**: Use WebSockets to stream partial updates from the swarm.
|
|
46
|
+
|
|
47
|
+
## 5. Development Workflow
|
|
48
|
+
|
|
49
|
+
1. **Define Roles**: Use `coordination/AGENT_PROFILE_TEMPLATE.md` to define each agent.
|
|
50
|
+
2. **Design Topology**: Use `coordination/SWARM_ARCHITECTURE_TEMPLATE.md` to map interactions.
|
|
51
|
+
3. **Establish Protocol**: Use `coordination/agent-protocol.skill.md` to define JSON schemas.
|
|
52
|
+
4. **Implement**:
|
|
53
|
+
- Start with the Orchestrator.
|
|
54
|
+
- Mock the Workers.
|
|
55
|
+
- Implement connectivity (A2A).
|
|
56
|
+
5. **Test**: Verified with `coordination/multi-agent-orch.skill.md`.
|
|
57
|
+
|
|
58
|
+
## 6. Testing Strategies
|
|
59
|
+
- **Mocking**: specific agents to isolate behavior.
|
|
60
|
+
- **Simulation**: Run the swarm against a set of predefined scenarios.
|
|
61
|
+
- **Evals**: Use an "Evaluator Agent" to grade the output of the swarm.
|
|
62
|
+
|
|
63
|
+
## 7. Advanced Loki Patterns (Optimization)
|
|
64
|
+
|
|
65
|
+
### A. RAG-Augmented Swarms
|
|
66
|
+
Loki Mode now integrates with `knowledge-connect.skill` to give agents "Long-Term Semantic Memory".
|
|
67
|
+
1. **Configure**: Fill `core/MCP_CONFIG_TEMPLATE.json`.
|
|
68
|
+
2. **Indexing**: Run `knowledge-connect` to ingest docs/codebase into Vector DB.
|
|
69
|
+
3. **Retrieval**: During Phase S05, Loki automatically queries the DB for implementation guides relevant to the current task.
|
|
70
|
+
|
|
71
|
+
### B. Parallel Execution (Batching)
|
|
72
|
+
Standard sequential chains are slow. Loki optimizes S05 via "Task Batching":
|
|
73
|
+
1. **Decomposition**: `orch-planner` tags tasks as `[PARALLEL]` if they have no dependencies.
|
|
74
|
+
2. **Execution**: Agents pick up a *batch* of tasks (e.g., T-101, T-102, T-103) and execute them concurrently.
|
|
75
|
+
3. **Merge**: Results are merged, and the dependency graph is updated.
|
|
76
|
+
|
|
77
|
+
### C. Hybrid Swarms (A2A)
|
|
78
|
+
Loki allows delegation to external specialized swarms:
|
|
79
|
+
- **Internal**: "Build the API" (Loki Persona `backend-coder`)
|
|
80
|
+
- **External**: "Audit for vulnerabilities" -> Delegates to `Sec-Swarm-1` via `agent-interop.skill`.
|
|
81
|
+
|
|
82
|
+
### D. Cognitive Architectures (Global Workspace)
|
|
83
|
+
For highly dynamic environments, use the **Global Workspace** pattern ([`global-workspace.skill`](../../skills/brain/global-workspace.skill.md)).
|
|
84
|
+
- **Concept**: Agents "compete" for attention rather than following a rigid pipeline.
|
|
85
|
+
- **Use Case**: When the next step is ambiguous and requires the "most confident" agent to take over.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# How GABBE Self-Evolves: The Gene Pool and the Reward Loop
|
|
2
|
+
|
|
3
|
+
GABBE includes a small, real, self-improving loop for its own prompts. This guide explains
|
|
4
|
+
exactly what that loop is, what part of it is working code, and what part of it is conceptual
|
|
5
|
+
framing — because the difference matters and overclaiming it would be dishonest.
|
|
6
|
+
|
|
7
|
+
## The short, honest version
|
|
8
|
+
|
|
9
|
+
GABBE evolves its prompts with an **epsilon-greedy bandit over prompt variants, rewarded by a
|
|
10
|
+
success rate**. That is the whole mechanism. The code that does this lives in `gabbe/brain.py`.
|
|
11
|
+
Around that mechanism sits a richer vocabulary — "Active Inference", "minimize free energy",
|
|
12
|
+
"Meta-Cognitive Brain" — which is **framing, not math**. There is no free-energy functional
|
|
13
|
+
being minimized anywhere in the code. When you read "Active Inference" in the brain prompts,
|
|
14
|
+
read it as an intent ("think before acting, prefer actions that reduce surprise about project
|
|
15
|
+
state"), not as an implemented variational-inference algorithm. Being clear about this is the
|
|
16
|
+
point of the guide.
|
|
17
|
+
|
|
18
|
+
## The gene pool (real code)
|
|
19
|
+
|
|
20
|
+
Each evolvable prompt is a **gene**. A gene is a row in the `genes` table with at least:
|
|
21
|
+
|
|
22
|
+
- `skill_name` — which prompt this gene is a variant of (e.g. `brain-activate`)
|
|
23
|
+
- `prompt_content` — the actual prompt text
|
|
24
|
+
- `generation` — how many mutation rounds produced it (0 is the seed)
|
|
25
|
+
- `success_rate` — its accumulated fitness, a float that only ever goes up, capped at 1.0
|
|
26
|
+
|
|
27
|
+
A "gene pool" is therefore just all the rows for a given `skill_name`: several competing
|
|
28
|
+
prompt variants of the same skill, each with its own fitness so far.
|
|
29
|
+
|
|
30
|
+
## Selection: epsilon-greedy (real code)
|
|
31
|
+
|
|
32
|
+
When the brain needs a prompt, `_get_best_gene()` picks one with a classic epsilon-greedy
|
|
33
|
+
policy:
|
|
34
|
+
|
|
35
|
+
- **80% of the time (exploit):** take the gene with the highest `success_rate`, breaking ties
|
|
36
|
+
by newest `generation`.
|
|
37
|
+
- **20% of the time (explore):** ignore fitness entirely and take the newest generation, so a
|
|
38
|
+
freshly mutated variant gets a chance to prove itself even though its `success_rate` is still 0.
|
|
39
|
+
|
|
40
|
+
That 20% exploration rate is a literal `if random.random() < 0.2` in the code. This is a
|
|
41
|
+
multi-armed bandit, not a search over a fitness landscape with crossover — there is no
|
|
42
|
+
crossover and no population culling. It is deliberately simple.
|
|
43
|
+
|
|
44
|
+
## Reward: monotonic success rate (real code)
|
|
45
|
+
|
|
46
|
+
The loop closes in `activate_brain()`. The flow is:
|
|
47
|
+
|
|
48
|
+
1. Read project state from the database (counts of TODO / IN_PROGRESS / DONE tasks). This is
|
|
49
|
+
the "Observation" step.
|
|
50
|
+
2. Fetch the best gene for the `brain-activate` skill and use its `prompt_content` as the system
|
|
51
|
+
prompt. If no gene exists, fall back to a hard-coded default prompt.
|
|
52
|
+
3. Call the LLM through the gateway to get a suggested next action.
|
|
53
|
+
4. **If the call produced a result, reward the gene** that produced it: `_update_gene_success_rate()`
|
|
54
|
+
does `success_rate = MIN(1.0, success_rate + 0.1)`.
|
|
55
|
+
|
|
56
|
+
So "reward" here means: a gene that yields a non-empty LLM response gets +0.1 fitness, up to a
|
|
57
|
+
ceiling of 1.0. It is **monotonic** — fitness never decreases. Be honest about what this implies:
|
|
58
|
+
the reward signal is "the call returned something", not "the suggested action was actually good".
|
|
59
|
+
There is no human-judged or outcome-judged reward feeding back in yet. A gene that reliably
|
|
60
|
+
produces *plausible* output will climb to 1.0 regardless of whether its suggestions were wise.
|
|
61
|
+
This is a genuine limitation, not a hidden feature.
|
|
62
|
+
|
|
63
|
+
## Mutation: Evolutionary Prompt Optimization (real code)
|
|
64
|
+
|
|
65
|
+
New genes are born in `evolve_prompts(skill_name)`, labeled in the code as **EPO (Evolutionary
|
|
66
|
+
Prompt Optimization)**:
|
|
67
|
+
|
|
68
|
+
1. Fetch the current best gene for the skill (or seed a generic default if the pool is empty).
|
|
69
|
+
2. Ask an LLM, acting as an "Expert Prompt Engineer", to rewrite that prompt to be more
|
|
70
|
+
effective, precise, and robust.
|
|
71
|
+
3. Insert the rewrite as a new gene at `generation + 1`, with `success_rate` starting at 0.0.
|
|
72
|
+
|
|
73
|
+
So mutation is **LLM-driven rewriting**, not random token perturbation or genetic crossover.
|
|
74
|
+
A new generation starts unproven (fitness 0) and only earns fitness through the explore path of
|
|
75
|
+
selection plus the reward loop above. Over repeated `gabbe brain activate` runs, the genes that
|
|
76
|
+
keep producing results accumulate fitness and get exploited more often.
|
|
77
|
+
|
|
78
|
+
## Putting the loop together
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
evolve_prompts() → adds a new, unproven prompt variant (generation+1, fitness 0)
|
|
82
|
+
│
|
|
83
|
+
▼
|
|
84
|
+
activate_brain() → epsilon-greedy picks a gene (80% best, 20% newest)
|
|
85
|
+
│ → runs it through the LLM via the gateway
|
|
86
|
+
▼
|
|
87
|
+
_update_gene_success_rate() → +0.1 fitness if the call returned something (capped at 1.0)
|
|
88
|
+
│
|
|
89
|
+
▼
|
|
90
|
+
(next activate_brain) → the now-fitter gene is more likely to be exploited
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Run `evolve_prompts` occasionally to inject variation; run `activate_brain` repeatedly to let
|
|
94
|
+
selection and reward sort the variants. That is the entire self-evolution mechanism.
|
|
95
|
+
|
|
96
|
+
## The "brain inference via skills" framing, stated honestly
|
|
97
|
+
|
|
98
|
+
GABBE's headline framing is that its intelligence "lives in the skill markdown" and that the
|
|
99
|
+
brain performs "Active Inference". Here is the honest accounting:
|
|
100
|
+
|
|
101
|
+
- **What is real:** the epsilon-greedy gene selection, the LLM-driven mutation, and the
|
|
102
|
+
monotonic success-rate reward are all working Python in `gabbe/brain.py`, backed by a SQLite
|
|
103
|
+
`genes` table. The markdown skills are real and are what an agent actually loads and follows.
|
|
104
|
+
- **What is conceptual:** "Active Inference" and "minimize free energy/surprise" are *names for
|
|
105
|
+
an intent* placed in the default brain system prompt. No variational free energy, generative
|
|
106
|
+
model, or belief-updating math is computed. Treat these terms as a design philosophy ("predict
|
|
107
|
+
the likely outcome of the current trajectory, then pick an action that reduces uncertainty
|
|
108
|
+
about project state"), not as an implemented algorithm.
|
|
109
|
+
|
|
110
|
+
If you describe GABBE to others, the truthful claim is: *"a self-improving prompt loop using an
|
|
111
|
+
epsilon-greedy bandit with a success-rate reward, plus LLM-driven prompt mutation."* The truthful
|
|
112
|
+
claim is **not** "it performs active inference" or "it minimizes free energy mathematically".
|
|
113
|
+
|
|
114
|
+
## How the meta-optimize and self-improvement skills fit
|
|
115
|
+
|
|
116
|
+
Two skills give an agent a CLI-free way to drive the same loop by following markdown instead of
|
|
117
|
+
running Python:
|
|
118
|
+
|
|
119
|
+
- `meta-optimize.skill` (in `coordination/`) is the agent-prompt analogue of `evolve_prompts`:
|
|
120
|
+
it asks the agent to critique and rewrite a prompt/skill, producing the next-generation variant
|
|
121
|
+
by reasoning rather than by calling the `gabbe` CLI.
|
|
122
|
+
- `self-improvement.skill` (in `brain/`) frames the broader improvement intent — observe outcomes,
|
|
123
|
+
propose a better prompt or process, and feed the result back — so the same evolutionary idea
|
|
124
|
+
works in a pure-markdown runtime with no database.
|
|
125
|
+
|
|
126
|
+
Both are the conceptual, runtime-agnostic mirror of the concrete code in `brain.py`. The code
|
|
127
|
+
path is what gives you persistence and measurable fitness; the skill path is what lets the same
|
|
128
|
+
evolution happen inside any coding agent that can read markdown. Neither path adds free-energy
|
|
129
|
+
math — they both implement "try a variant, keep what works".
|
|
130
|
+
|
|
131
|
+
## What you can rely on
|
|
132
|
+
|
|
133
|
+
- The gene pool, epsilon-greedy selection, and monotonic reward exist and work.
|
|
134
|
+
- The reward currently means "the LLM call returned output", not "the output was good" — improving
|
|
135
|
+
this (outcome- or judge-based reward) is open work, and you should not assume otherwise.
|
|
136
|
+
- "Active Inference" / "free energy" are framing words; there is no such computation in the code.
|
|
137
|
+
- The mutation step depends on an LLM call; with no API access, no new genes are produced.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Self-Healing Loop Summary
|
|
2
|
+
|
|
3
|
+
The Self-Healing Loop is a core autonomous mechanism in GABBE (detailed in `core/self-heal.skill.md`). It allows agents to diagnose, research, fix, and verify failures autonomously, minimizing human intervention for routine errors.
|
|
4
|
+
|
|
5
|
+
## Operation Summary
|
|
6
|
+
|
|
7
|
+
1. **Pre-Healing (Memory Check)**: Before attempting a fix, the agent reads `agents/memory/CONTINUITY.md`. If the error and its resolution are already documented, the agent applies the known fix immediately, preventing repeated failed attempts ("learning").
|
|
8
|
+
2. **Safety Check**: The agent ensures it is not in an infinite loop (e.g., trying the exact same fix for the 3rd time, or recursion depth > 10).
|
|
9
|
+
3. **Diagnosis & Classification**: The agent classifies the error (Type, Test, Import, Runtime, Build, Unknown).
|
|
10
|
+
- *Autonomous fixes allowed*: Lint/type errors, test assertions (if spec changed), minor version bumps, formatting.
|
|
11
|
+
- *Human escalation required immediately*: Architecture changes, breaking API changes, security changes, major version bumps.
|
|
12
|
+
4. **Research (If Unknown)**: The agent invokes `research.skill` to find authoritative solutions (Context-7 MCP or Tavily/Brave Search).
|
|
13
|
+
5. **Hypothesize & Fix**: The agent states a hypothesis and applies the *minimal* required change.
|
|
14
|
+
6. **Verify & Iterate**: The agent runs tests/builds. If it passes, it logs to `AUDIT_LOG.md`. If it fails, it increments the attempt counter (Max 5 attempts).
|
|
15
|
+
7. **Escalation (Attempt 5)**: If 5 attempts fail, autonomous action stops. An escalation report is generated detailing all attempts, research findings, and options for human decision. The task status becomes `BLOCKED`.
|
|
16
|
+
|
|
17
|
+
## Agent Execution & Verification
|
|
18
|
+
This loop is triggered automatically during Phase S05 (Implementation) of Loki mode when the `VERIFY` step (tests, typecheck, lint) fails. Agents are instructed to invoke `self-heal.skill` dynamically before escalating. This ensures that the system is resilient to minor regressions and only bothers the human architect with high-level decisions.
|
|
19
|
+
|
|
20
|
+
## Refresh: The Loop at a Glance
|
|
21
|
+
In short, the capability is a bounded **5-attempt self-heal loop** (diagnose → hypothesize → minimal fix → verify, capped to prevent runaway compute) backed by `self-heal.skill`. In CI it is paired with `ci-autofix.skill`, which applies the same diagnose-and-fix loop to red pipeline runs (lint, type, formatting, simple test breaks). Both honor the same guardrails: a **hardstop** halts autonomous action when an error is classed as high-risk (architecture, security, breaking API, or major version bumps), and **escalation** fires after the 5th failed attempt — generating a report and marking the task `BLOCKED` for human decision rather than guessing further.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Guide: Visual AI vs Text AI Diagramming
|
|
2
|
+
|
|
3
|
+
When agents operate inside of a project, determining how to communicate architectural designs is critical. The GABBE Kit supports both traditional **Text-based rendering** (Mermaid, PlantUML via markdown) and **Visual Canvas rendering** (Draw.io, Miro via MCP servers).
|
|
4
|
+
|
|
5
|
+
This guide dictates when an agent should use which method.
|
|
6
|
+
|
|
7
|
+
## 1. The Default: Text-Based Diagramming (Mermaid)
|
|
8
|
+
By default, the agent **MUST** prioritize text-based diagramming. It is deterministic, version-controllable, easily refactored by other LLMs, and does not require complex spatial reasoning.
|
|
9
|
+
|
|
10
|
+
**Use Mermaid/Markdown when:**
|
|
11
|
+
* Generating initial PRDs (`PRD_TEMPLATE.md`).
|
|
12
|
+
* Writing out standard architectural patterns.
|
|
13
|
+
* Documenting sequential workflows or logic inside a README.
|
|
14
|
+
* The system complexity is low-to-medium (Under 15 nodes).
|
|
15
|
+
* The primary consumer is another developer or agent reading markdown.
|
|
16
|
+
|
|
17
|
+
## 2. The Exception: Visual Canvas Integrations (MCP Servers)
|
|
18
|
+
Visual canvases are exceptional tools for high-level human collaboration, non-technical stakeholders, or massive ecosystem maps that become unreadable in Mermaid text blocks. To use these, the corresponding [Miro, Draw.io, Figma] MCP server must be enabled.
|
|
19
|
+
|
|
20
|
+
**Use Visual Canvases when:**
|
|
21
|
+
* **Explicit Human Request**: The user specifically says "Draw this in Miro" or "Generate a Draw.io XML file."
|
|
22
|
+
* **Extreme Complexity**: The system has \>15 interconnected microservices, rendering a Mermaid graph unreadable (the "spaghetti" effect).
|
|
23
|
+
* **Spatial Requirements**: The problem requires physical grouping, swimlanes, or free-form whiteboarding (e.g., Event storming sessions).
|
|
24
|
+
* **Cross-Functional Output**: The result must be consumed by Product Managers, Designers, or Executives who do not use Markdown renderers.
|
|
25
|
+
|
|
26
|
+
## 3. Operations Guardrails for Visual Tools
|
|
27
|
+
If the agent triggers a Visual tool (Draw.io, Miro, Excalidraw):
|
|
28
|
+
1. **Coordinate Mapping**: The agent must pre-map the geometry. Use the `WHITEBOARD_DESIGN_TEMPLATE.md` to establish an X/Y grid. LLMs are poor at spatial arrangement; pre-calculating coordinates mathematically guarantees a legible graph.
|
|
29
|
+
2. **State Syncing**: If an agent updates an architecture in Miro or Excalidraw, it MUST also reflect the structural changes back into the text-based `PLAN.md` or `SYSTEM_ANALYSIS_TEMPLATE.md` to ensure the project's internal semantic memory is updated. A picture is not searchable by default RAG tools; the metadata must stay in text.
|
|
30
|
+
3. **Authentication Constraints**: Visual MCP servers require OAuth or Bearer Tokens (Miro, Figma). Excalidraw and Draw.io are local-only and need no authentication. The agent must verify connectivity by calling a read operation (e.g., `get_board`) before attempting to dump 50 nodes into a massive write operation.
|
|
31
|
+
|
|
32
|
+
## 4. Excalidraw Integration
|
|
33
|
+
|
|
34
|
+
Excalidraw provides a hand-drawn aesthetic ideal for architecture diagrams, flowcharts, and wireframes. The `@cmd8/excalidraw-mcp` server enables programmatic diagram creation.
|
|
35
|
+
|
|
36
|
+
**MCP Config:**
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"excalidraw": {
|
|
40
|
+
"command": "npx",
|
|
41
|
+
"args": ["-y", "@cmd8/excalidraw-mcp", "--diagram", "./docs/architecture.excalidraw"]
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Tools:** `createNode`, `createEdge`, `deleteElement`, `getFullDiagramState`
|
|
47
|
+
|
|
48
|
+
**When to use Excalidraw over Draw.io/Miro:**
|
|
49
|
+
- Hand-drawn aesthetic is desired (informal collaboration, brainstorming)
|
|
50
|
+
- No authentication or cloud service needed (fully local)
|
|
51
|
+
- Quick architecture sketches during specs or PRD phase
|
|
52
|
+
- The diagram will be committed to git (`.excalidraw` is JSON-based, diffable)
|
|
53
|
+
|
|
54
|
+
**See:** `coding/excalidraw.skill.md` for full usage.
|
|
55
|
+
|
|
56
|
+
## 5. tldraw Integration
|
|
57
|
+
|
|
58
|
+
tldraw provides a persistent visual canvas ideal for UI wireframing, rapid prototyping, and visual scratchpads. The `@talhaorak/tldraw-mcp` server offers 9 tools for full canvas CRUD.
|
|
59
|
+
|
|
60
|
+
**MCP Config:**
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"tldraw": {
|
|
64
|
+
"command": "npx",
|
|
65
|
+
"args": ["-y", "@talhaorak/tldraw-mcp"]
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Tools:** `tldraw_create`, `tldraw_read`, `tldraw_write`, `tldraw_list`, `tldraw_search`, `tldraw_get_shapes`, `tldraw_add_shape`, `tldraw_update_shape`, `tldraw_delete_shape`
|
|
71
|
+
|
|
72
|
+
**When to use tldraw over Excalidraw/Draw.io:**
|
|
73
|
+
- UI wireframing and rapid prototype sketching
|
|
74
|
+
- Persistent visual scratchpad the agent can read and search later
|
|
75
|
+
- Full shape CRUD with fine-grained control (9 tools vs 4)
|
|
76
|
+
- Canvas files viewable at [tldraw.com](https://www.tldraw.com) or VS Code extension
|
|
77
|
+
|
|
78
|
+
**See:** `coding/tldraw-canvas.skill.md` for full usage.
|
|
79
|
+
|
|
80
|
+
## 6. Sketch-to-Diagram Pipeline
|
|
81
|
+
|
|
82
|
+
For converting **hand-drawn sketches** (whiteboard photos, napkin drawings) into formal diagrams, the GABBE kit supports a **Sketch → Recognize → Redraw** pipeline using two MCP servers:
|
|
83
|
+
|
|
84
|
+
1. **`image-recognition` MCP**: Sends the sketch image to a vision API (Anthropic/OpenAI/Cloudflare) which describes all visible elements, connections, and labels.
|
|
85
|
+
2. **Output MCP** (choice of):
|
|
86
|
+
- `excalidraw` → `.excalidraw` file
|
|
87
|
+
- `drawio` → Draw.io XML
|
|
88
|
+
- None → Mermaid text (no MCP needed)
|
|
89
|
+
|
|
90
|
+
**Workflow:**
|
|
91
|
+
```
|
|
92
|
+
Photo/Scan → image-recognition MCP → Structured Element List → Human Verification → Formal Diagram
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**Security note:** Sketch images are sent to external vision APIs. For sensitive diagrams (internal architecture, credentials on whiteboards), use local OCR (Tesseract) or have the user describe the diagram verbally instead.
|
|
96
|
+
|
|
97
|
+
**See:** `coding/sketch-to-diagram.skill.md` for full usage.
|
|
98
|
+
**Template:** `coding/SKETCH_TO_DIAGRAM_TEMPLATE.md` for structured output.
|
|
99
|
+
|
|
100
|
+
## 7. Visual Product Design Phase
|
|
101
|
+
|
|
102
|
+
For a complete end-to-end workflow that processes visual inputs (scanned sketches, architecture diagrams, wireframes) into structured product specifications before implementation, see:
|
|
103
|
+
|
|
104
|
+
- **Guide:** `planning/visual-product-specs.md` — input catalogue, recognition pipeline, output mapping, design readiness gate
|
|
105
|
+
- **Skill:** `product/visual-specs.skill.md` — 5-phase workflow from visual inputs to Visual Spec Package
|
|
106
|
+
- **Template:** `product/VISUAL_SPEC_PACKAGE_TEMPLATE.md` — collects all visual design artifacts with readiness checklist
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Enterprise API Standards & Governance
|
|
2
|
+
|
|
3
|
+
Consistent APIs are the backbone of a scalable enterprise. This guide defines the standards for all internal and external APIs.
|
|
4
|
+
|
|
5
|
+
## 1. API Architecture Styles
|
|
6
|
+
|
|
7
|
+
| Style | Use Case | Pros | Cons |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| **REST** | General purpose, Public APIs | Standard, Cacheable, Simple | Over-fetching, N+1 issues |
|
|
10
|
+
| **GraphQL** | Frontend-Heavy, Complex Graphs | Flexible queries, Single round-trip | Complexity, Caching hard |
|
|
11
|
+
| **gRPC** | Internal Microservices | High perf, Type-safe | Human-unreadable, Browser support |
|
|
12
|
+
| **AsyncAPI** | Event-Driven / Webhooks | Models events explicitly | Newer tooling ecosystem |
|
|
13
|
+
|
|
14
|
+
## 2. Resource Naming (REST)
|
|
15
|
+
- **Plural Nouns**: `/users`, `/orders`.
|
|
16
|
+
- **Kebab-case URLs**: `/product-categories` (NOT `/productCategories`).
|
|
17
|
+
- **Nesting**: limit to 2 levels. `/users/123/orders` (Good). `/users/123/orders/456/items/789` (Bad -> flatten to `/orders/456/items`).
|
|
18
|
+
|
|
19
|
+
## 3. Versioning Strategy
|
|
20
|
+
**Rule**: Making a breaking change? You MUST introduce a new version.
|
|
21
|
+
|
|
22
|
+
### Methods
|
|
23
|
+
1. **URI Versioning** (Standard): `GET /v1/users`
|
|
24
|
+
- *Pros*: Explicit, Easy to debug/cache.
|
|
25
|
+
- *Cons*: "Pollutes" URI.
|
|
26
|
+
2. **Header Versioning**: `Accept: application/vnd.company.v1+json`
|
|
27
|
+
- *Pros*: Clean URI. Implementation hiding.
|
|
28
|
+
- *Cons*: Harder to test in browser.
|
|
29
|
+
|
|
30
|
+
## 4. Standard Response Envelope
|
|
31
|
+
Consistency allows shared client libraries.
|
|
32
|
+
|
|
33
|
+
### Success
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"data": { ... },
|
|
37
|
+
"meta": { "page": 1, "total": 100 }
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Error (RFC 7807)
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"error": {
|
|
45
|
+
"code": "resource_not_found",
|
|
46
|
+
"message": "User 123 not found",
|
|
47
|
+
"traceId": "abc-123"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 5. Security & Governance
|
|
53
|
+
- **Authentication**: Bearer Token (JWT) in Header.
|
|
54
|
+
- **Rate Limiting**: Return `429 Too Many Requests` with `Retry-After` header.
|
|
55
|
+
- **Idempotency**: `POST` requests should accept `Idempotency-Key` header to prevent double-billing on network retry.
|
|
56
|
+
- **Documentation**: OpenAPI 3.0+ required for ALL APIs.
|
|
57
|
+
|
|
58
|
+
## 6. Deprecation Policy
|
|
59
|
+
1. Mark endpoint `Deprecated: true` in OpenAPI.
|
|
60
|
+
2. Add `Warning: 299 - "Deprecated API"` header.
|
|
61
|
+
3. Sunset period: Minimum 6 months for internal, 12 months for public APIs.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Blockchain & Distributed Ledger Technology (DLT) Guide
|
|
2
|
+
|
|
3
|
+
## 1. Introduction
|
|
4
|
+
Distributed Ledgers and Blockchains are revolutionary architectures for applications where no single party holds ultimate trust. Unlike traditional databases (which are controlled by central authorities), DLT ensures that data is immutable, transparent, and agreed upon by consensus.
|
|
5
|
+
|
|
6
|
+
## 2. Choosing the Right Network
|
|
7
|
+
Not all problems require a blockchain. If trust exists centrally, use a database. If not, choose the right ledger:
|
|
8
|
+
|
|
9
|
+
### Public Blockchains (Ethereum, Polygon, Solana)
|
|
10
|
+
- **Use Case**: Decentralized Finance (DeFi), global asset tokenization, DAOs, public registries.
|
|
11
|
+
- **Trust Model**: Zero trust (Trustless). Anyone can participate.
|
|
12
|
+
- **Throughput**: Lower (ranges from 15 to 65,000 TPS computationally depending on the chain/L2).
|
|
13
|
+
- **Consensus**: Proof of Stake (PoS), Proof of Work (PoW).
|
|
14
|
+
|
|
15
|
+
### Enterprise DLT (Hyperledger Fabric, R3 Corda)
|
|
16
|
+
- **Use Case**: Supply chain tracking, inter-bank settlements, secure corporate consortiums.
|
|
17
|
+
- **Trust Model**: Permissioned (Known participants).
|
|
18
|
+
- **Throughput**: High (designed for enterprise speeds).
|
|
19
|
+
- **Consensus**: Raft, PBFT (Practical Byzantine Fault Tolerance).
|
|
20
|
+
|
|
21
|
+
## 3. Smart Contract Architecture
|
|
22
|
+
Smart contracts are state machines deployed to the ledger. They dictate the rules of engagement.
|
|
23
|
+
|
|
24
|
+
### Key Considerations
|
|
25
|
+
1. **Immutability vs Upgradability**: Code deployed is final. Bug fixes require deploying entirely new contracts. To circumvent this, use the **Proxy Pattern** (separating the logic contract from the state-holding proxy contract).
|
|
26
|
+
2. **Determinism**: Smart contracts cannot compute random numbers securely or make external HTTP calls.
|
|
27
|
+
3. **Oracles**: To get real-world data (e.g., the price of AAPL stock, or current weather) inside a blockchain, you must use Decentralized Oracles (like Chainlink).
|
|
28
|
+
|
|
29
|
+
## 4. Security is Paramount
|
|
30
|
+
A bug in a traditional web server might cause downtime; a bug in a smart contract can cause the immediate, irreversible loss of millions of dollars.
|
|
31
|
+
- Always use established libraries like **OpenZeppelin** for ERC standards and mathematical operators.
|
|
32
|
+
- Enforce the **Checks-Effects-Interactions** pattern to prevent reentrancy attacks.
|
|
33
|
+
- Have code audited professionally.
|
|
34
|
+
|
|
35
|
+
## 5. Agentic Implementation
|
|
36
|
+
When working on web3 architectures, invoke the `blockchain-dlt` skill. The agent will assess the requirements, choose an appropriate network, and generate a robust `SMART_CONTRACT_TEMPLATE.md` ensuring security best practices are baked into the design phase.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Critical Systems Architecture
|
|
2
|
+
|
|
3
|
+
**Architecting for Safety: Aviation, Health, and High-Assurance Domains.**
|
|
4
|
+
|
|
5
|
+
This guide details how to apply **Agentic Engineering** to domains governed by standards like **DO-178C** (Airborne) and **IEC 62304** (Medical).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. The Core Standards (2026)
|
|
10
|
+
|
|
11
|
+
| Domain | Standard | Key Concept | Agentic Implication |
|
|
12
|
+
|---|---|---|---|
|
|
13
|
+
| **Aviation** | **DO-178C** | Design Assurance Levels (DAL A-E) | Agents must produce **Traceability** artifacts. |
|
|
14
|
+
| **Medical** | **IEC 62304** | Safety Classes (A, B, C) | Agents must verify **Segregation** of critical units. |
|
|
15
|
+
| **Auto** | **ISO 26262** | ASIL | Agents must perform **HARA** (Hazard Analysis). |
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 2. Architectural Patterns for Safety
|
|
20
|
+
|
|
21
|
+
### 2.1 The "Simplex" and "Monitor" Pattern (Runtime Assurance)
|
|
22
|
+
You cannot trust an AI Agent to control a plane directly ("The Black Box Problem").
|
|
23
|
+
**Solution:** **Runtime Assurance (RTA)** arch.
|
|
24
|
+
* **Complex Channel (AI):** Optimizes flight path (High Performance, Low Trust).
|
|
25
|
+
* **Safety Monitor (Deterministic):** Checks limits ($$ G < 4.0 $$, $$ Alt > 500 $$).
|
|
26
|
+
* **Switch:** If Monitor triggers, revert to distinct "Safe Core" code.
|
|
27
|
+
|
|
28
|
+
### 2.2 Integration with Domain-Driven Design (DDD)
|
|
29
|
+
DDD is crucial for managing the complexity of critical domains.
|
|
30
|
+
* **Ubiquitous Language:** The Agent must speak "Pilot", "Doctor", not "variable".
|
|
31
|
+
* **Bounded Contexts:** Use strict boundaries to isolate Safety-Critical Contexts from Analytics Contexts.
|
|
32
|
+
* *Pattern:* `Context Map` with **Anti-Corruption Layers (ACL)**.
|
|
33
|
+
|
|
34
|
+
### 2.3 Hexagonal (Ports & Adapters)
|
|
35
|
+
Isolates the "Domain Logic" (The Heart) from the "Infrastructure".
|
|
36
|
+
* Agents are excellent at generating the **Adapters**, leaving the **Domain** pure and testable.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 3. Agentic Workflows for Certification
|
|
41
|
+
|
|
42
|
+
In a regulated environment, the Agent's primary job is **Evidence Generation**.
|
|
43
|
+
|
|
44
|
+
1. **Traceability Matrix Generation:**
|
|
45
|
+
* Agent scans `REQUIREMENTS.md` and `CODE`.
|
|
46
|
+
* Generates a matrix: "Req 1.2 is implemented in `flight_control.go:45` and tested in `test_flight.go:12`".
|
|
47
|
+
2. **Segregation Verification:**
|
|
48
|
+
* Agent analyzes import graphs.
|
|
49
|
+
* Alerts if "Class C" (Critical) code imports "Class A" (UI) code.
|
|
50
|
+
3. **Hazard Analysis (FMEA/STPA):**
|
|
51
|
+
* Agent brainstorms "What if?" scenarios ("What if the GPS sensor sends NaN?").
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 4. The "Lethal Trifecta" in Critical Ops
|
|
56
|
+
Avoid these three at all costs:
|
|
57
|
+
1. **Unbounded Loops:** Control loops must be deterministic.
|
|
58
|
+
2. **Dynamic Memory Allocation:** Critical C/C++ often forbids `malloc` after init.
|
|
59
|
+
3. **Deadlocks:** Actors/Agents must have proven liveness.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## 5. References
|
|
64
|
+
* [DO-178C / ED-12C Software Considerations]
|
|
65
|
+
* [IEC 62304 Medical Device Software]
|
|
66
|
+
* [CAST-32A Multi-Core Processors]
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Event-Driven Architecture (EDA) Guide
|
|
2
|
+
|
|
3
|
+
A dominant pattern for 2025 systems requiring high scalability and decoupling.
|
|
4
|
+
|
|
5
|
+
## 1. Core Concept
|
|
6
|
+
Components communicate by emitting **events** (facts that happened) rather than sending **commands** (requests to do something).
|
|
7
|
+
- **Command**: "Create Order" (Expects response, tight coupling).
|
|
8
|
+
- **Event**: "Order Created" (Fire and forget, loose coupling).
|
|
9
|
+
|
|
10
|
+
## 2. Key Components
|
|
11
|
+
- **Producer**: Emits events (e.g., Checkout Service).
|
|
12
|
+
- **Broker**: Transports events (e.g., Kafka, RabbitMQ, SNS/SQS).
|
|
13
|
+
- **Consumer**: Reacts to events (e.g., Shipping Service, Inventory Service).
|
|
14
|
+
|
|
15
|
+
## 3. Patterns
|
|
16
|
+
|
|
17
|
+
### Event Notification
|
|
18
|
+
- Producer sends a minimal event: `{"order_id": 123, "event": "created"}`.
|
|
19
|
+
- Consumer calls back updates state: `GET /orders/123`.
|
|
20
|
+
- **Pros**: Low payload size.
|
|
21
|
+
- **Cons**: Chatty (callback required).
|
|
22
|
+
|
|
23
|
+
### Event-Carried State Transfer
|
|
24
|
+
- Producer sends full state: `{"order_id": 123, "items": [...], "customer": ...}`.
|
|
25
|
+
- Consumer updates its own local cache/DB.
|
|
26
|
+
- **Pros**: Decoupled (no callback needed), high resilience.
|
|
27
|
+
- **Cons**: Data replication/consistency challenges.
|
|
28
|
+
|
|
29
|
+
### Event Sourcing
|
|
30
|
+
- Store the *events* as the source of truth, not the current state.
|
|
31
|
+
- The current state is derived by replaying events.
|
|
32
|
+
- **Pros**: Perfect audit trail, temporal queries, easy debugging.
|
|
33
|
+
- **Cons**: High complexity, snapshots required for performance.
|
|
34
|
+
|
|
35
|
+
## 4. Best Practices
|
|
36
|
+
- **Idempotency**: Consumers must handle receiving the same event twice safely.
|
|
37
|
+
- **Schema Registry**: Rigidly define event schemas (Avro, Protobuf, JSON Schema) to prevent breaking consumers.
|
|
38
|
+
- **Dead Letter Queues (DLQ)**: Where failed events go to die (and be analyzed).
|
|
39
|
+
- **Async First**: EDA is asynchronous. Don't try to force synchronous request-response flow over messaging.
|