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,188 @@
|
|
|
1
|
+
# CONSTITUTION.md — Project Law Template
|
|
2
|
+
|
|
3
|
+
> These are the immutable rules of this project.
|
|
4
|
+
> Agents may NOT violate these rules — not even to fix a bug, meet a deadline, or follow a user request.
|
|
5
|
+
> Only humans may amend the Constitution, with team consensus.
|
|
6
|
+
> Agents must escalate any request that would require violating these articles.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## How to Use This Template
|
|
11
|
+
|
|
12
|
+
1. **Keep or adapt** the articles below — they represent proven engineering principles
|
|
13
|
+
2. **Add** project-specific articles in Section 2
|
|
14
|
+
3. **Remove** articles that don't apply to your project type
|
|
15
|
+
4. **Never** let agents auto-amend this file
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Section 1 — Universal Articles (Core Engineering Law)
|
|
20
|
+
|
|
21
|
+
### Article I — Test-First Mandate
|
|
22
|
+
|
|
23
|
+
> No production code without a failing test.
|
|
24
|
+
|
|
25
|
+
- Every feature, every bug fix, every refactor: **write the failing test first**
|
|
26
|
+
- The test must fail before any implementation is written (Red phase)
|
|
27
|
+
- A test that passes immediately with no implementation is a broken test — fix the test
|
|
28
|
+
- Minimum test coverage: **99% line coverage** for all non-trivial code
|
|
29
|
+
- Integration points (database, external APIs, message queues) must have integration tests
|
|
30
|
+
- Violations: No PR merges without this — ever
|
|
31
|
+
- **Spec-Driven (first-class):** work flows **spec → evals → test → code** (evals = the acceptance criteria, defined before implementation — see `guides/principles/testing-strategy.md` Level 5). Non-trivial features start from an **EARS** spec (`WHEN [event] THE SYSTEM SHALL [response]`); maintain a **golden thread** of traceability (requirement → spec → test → code → audit). No requirement without a test; resolve ambiguity in the spec, not the code.
|
|
32
|
+
|
|
33
|
+
<!-- OPTIONAL: EARS Example -> WHEN [event] THE SYSTEM SHALL [response] -->
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
### Article II — Library-First Architecture
|
|
38
|
+
|
|
39
|
+
> Business logic lives in framework-agnostic libraries, never in the UI or framework layer.
|
|
40
|
+
|
|
41
|
+
- Framework = delivery mechanism (HTTP handler, CLI command, queue consumer)
|
|
42
|
+
- Business rules must be testable without starting a server or touching a database
|
|
43
|
+
- Domain entities must not import from web frameworks, ORMs, or HTTP libraries
|
|
44
|
+
- **Clean Architecture enforcement:** domain → application → adapters → infrastructure → main
|
|
45
|
+
- No circular dependencies between modules (enforced by agentic-linter on every PR)
|
|
46
|
+
|
|
47
|
+
<!-- OPTIONAL: Anti-patterns (forbidden) -> e.g. Business logic in controllers. Instead delegate to explicit use cases. -->
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
### Article III — Simplicity Over Cleverness
|
|
52
|
+
|
|
53
|
+
> Prefer duplication over premature abstraction. Rule of Three.
|
|
54
|
+
|
|
55
|
+
- Do not abstract until you have three concrete usages of the same pattern
|
|
56
|
+
- Clever code that requires comments to understand is wrong — simplify the code
|
|
57
|
+
- No abstraction for "hypothetical future requirements"
|
|
58
|
+
- Prefer explicit over implicit (named functions over anonymous lambdas for complex logic)
|
|
59
|
+
- Maximum file length: **300 lines** (excluding tests). Split larger files by responsibility
|
|
60
|
+
- Maximum function length: **30 lines**. Extract smaller functions for complex logic
|
|
61
|
+
- Cyclomatic complexity limit: **10** per function. Exceed this → refactor required
|
|
62
|
+
|
|
63
|
+
<!-- OPTIONAL: Rule of Three Concept -> Keep inline -> inline again -> extract into abstraction on the 3rd time -->
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
### Article IV — Privacy by Design
|
|
68
|
+
|
|
69
|
+
> No PII (Personally Identifiable Information) in logs, error messages, analytics, or debug output.
|
|
70
|
+
|
|
71
|
+
- **Encryption required:** All personal data encrypted at rest (AES-256) and in transit (TLS 1.3+)
|
|
72
|
+
- **Consent before collection:** Explicit user consent required before collecting any personal data
|
|
73
|
+
- **Data minimization:** Collect only the minimum data necessary for the stated purpose
|
|
74
|
+
- **Right to deletion:** All personal data must be deletable on request
|
|
75
|
+
- **Data retention:** Define explicit retention periods — no indefinite storage of PII
|
|
76
|
+
- **PII definition includes:** names, emails, phone numbers, IP addresses, device IDs, location data, behavioral data that can identify individuals
|
|
77
|
+
|
|
78
|
+
<!-- OPTIONAL: Logging Examples -> DO NOT log email/device IDs/PAN. Instead log DB IDs or last 4 digits. -->
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
### Article V — Security by Default
|
|
83
|
+
|
|
84
|
+
> Security is not a feature — it is a prerequisite.
|
|
85
|
+
|
|
86
|
+
- **Skill Guardrails Mandate:** Agents must explicitly follow the 3-layer **Security & Guardrails** section embedded within every executing skill.
|
|
87
|
+
- **Threat model required** before implementing any: authentication, authorization, data storage, file upload, payment processing, or external API integration
|
|
88
|
+
- **Input validation** at all system boundaries (HTTP, queue consumers, file parsers, CLI args)
|
|
89
|
+
- **Output encoding** for all user-controlled data rendered in HTML/SQL/commands
|
|
90
|
+
- **Principle of least privilege:** services, database users, and API keys get only the permissions they need
|
|
91
|
+
- **No secrets in code or git history:** use environment variables + secrets manager
|
|
92
|
+
- **Dependency audit** must pass with no critical or high CVEs before any release
|
|
93
|
+
- **Authentication:** sessions expire, tokens are short-lived, MFA for admin operations
|
|
94
|
+
|
|
95
|
+
**The Security Checklist (templates/security/SECURITY_CHECKLIST.md) must be completed before every production release.**
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
### Article VI — Ethical & Sustainable Operations
|
|
100
|
+
|
|
101
|
+
> "First, do no harm." Systems must be safe, fair, and green.
|
|
102
|
+
|
|
103
|
+
- **Bias Audits:** All logic affecting human users must pass a bias review (`ai-ethics-compliance`) before release.
|
|
104
|
+
- **Transparency:** AI-generated content must be clearly labeled as such to the end-user.
|
|
105
|
+
- **Observability (first-class):** Every run, decision, model call, and tool call must be observable — a decision/span trace with token usage and **cost attribution** per step, tagged with the OpenTelemetry GenAI semantic conventions. No black-box actions. Prompt/response content is redacted by default (privacy); the Markdown audit trail (`AUDIT_LOG.md`) is authoritative even without the CLI.
|
|
106
|
+
- **Sustainability:** Architecture choices must minimize carbon footprint. Scale to zero when idle.
|
|
107
|
+
- **Safety Measures:** Input guardrails (`ai-safety-guardrails`) are mandatory for all LLM integration points.
|
|
108
|
+
- **Human-in-the-Loop:** High-stakes decisions (financial, legal, health) require human confirmation.
|
|
109
|
+
- **Human–Agent Collaboration (Manager, not Operator):** The human is a **manager, not an operator** — delegate the objective, observe progress, intervene on exceptions. The system must keep the human able to answer three questions at all times: **Purpose** (bounded goal + non-goals — via spec/scope), **Transparency** (legible reasoning/tools/cost — via observability), **Control** (affordances to pause/correct/approve — via HITL gates). No autonomy is trustworthy without all three. See `guides/principles/human-agent-collaboration.md`.
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
### Article VII — Tech Debt Hygiene
|
|
114
|
+
|
|
115
|
+
> Technical debt is a liability. It must be visible, tracked, and planned.
|
|
116
|
+
|
|
117
|
+
- Any code with **Cyclomatic Complexity > 10** must be refactored before merging
|
|
118
|
+
- **TODO/FIXME/HACK** markers in code must have an associated task ticket (or be resolved immediately)
|
|
119
|
+
- No "dead code" in production branches (unreachable code, unused exports, commented-out blocks)
|
|
120
|
+
- **Dependency freshness:** critical security patches applied within 7 days; minor updates within 30 days
|
|
121
|
+
- Tech debt items discovered during development must be logged in **TECH_DEBT_TEMPLATE.md**
|
|
122
|
+
- Tech debt backlog reviewed and prioritized at the start of each development cycle
|
|
123
|
+
- **Boy Scout Rule:** leave the code better than you found it (but scope improvements to the task at hand)
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
### Article VIII — Architecture Integrity
|
|
128
|
+
|
|
129
|
+
> The architecture is the plan. Deviating from the plan requires a decision record.
|
|
130
|
+
|
|
131
|
+
- **No circular dependencies** between modules (zero tolerance — enforced by CI)
|
|
132
|
+
- **Layer import rules** enforced by agentic-linter on every PR (see AGENTS.md Section 3)
|
|
133
|
+
- **Architectural changes** (adding a service, changing a database, switching a library) require an ADR (Architecture Decision Record) before implementation
|
|
134
|
+
- **God objects forbidden:** classes/modules with > 500 lines or > 20 public methods must be split
|
|
135
|
+
- **Strangler Fig pattern** for migrating away from monolithic components (never big-bang rewrites)
|
|
136
|
+
- **API contracts** are frozen once published — breaking changes require versioning and deprecation period
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
### Article IX — Optimal Context & Skill Selection Mandate
|
|
141
|
+
|
|
142
|
+
> Agents must proactively load the most relevant context and specialized capabilities for every task.
|
|
143
|
+
|
|
144
|
+
- Agents **must always select** (and ask the user to select or confirm) the best guides, skills, and templates for the specific tasks, user queries, prompts, actions, gate passing, or system workflows they are executing.
|
|
145
|
+
- Before beginning any action, verify which specialized `/skills/` and `/guides/` are most appropriate and explicitly load them.
|
|
146
|
+
- If multiple skills or guides seem applicable, ask the user to disambiguate or confirm the selection to ensure optimal task execution.
|
|
147
|
+
- **MCP Server Recommendations**: Agents must actively evaluate if specific MCP (Model Context Protocol) servers (either universal or task-specific) are needed or highly beneficial for the task but are not currently enabled. If so, they must proactively recommend that the user enable them before continuing.
|
|
148
|
+
- This applies universally across all workflows, SDLC phases, and orchestrators.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
### Article X — Default Cost & Budget Optimization Mandate
|
|
153
|
+
|
|
154
|
+
> Cost efficiency is a continuous requirement, not an afterthought.
|
|
155
|
+
|
|
156
|
+
- **Default to Frugality**: Agents must continuously optimize for cost and token budget across all planning and execution phases. Choose the lowest-cost model, tool, or path that reliably meets the technical requirements of the task.
|
|
157
|
+
- **Human Approval for High Cost**: If a subtask strictly requires a more expensive SOTA (State of the Art) model, extensive search, elevated token contexts, or otherwise significantly increased costs, agents *must explicitly ask the human user for approval* before proceeding.
|
|
158
|
+
- **Explain Trade-offs**: When requesting a budget increase or expensive resource allocation, briefly explain why the cheaper approach will fail or carry unacceptable risk.
|
|
159
|
+
- **Configurable Autonomy (`GABBE_AUTONOMY`)**: Operate under the configured posture — `ask` | `auto` | `hybrid` (default **hybrid**: auto-select the best option within budget; pause and ask for expensive / SOTA / irreversible choices). Regardless of posture, expensive, SOTA, irreversible, or externally-sourced-code actions **always** require human approval.
|
|
160
|
+
- **Bounded Self-Evolution**: The system may keep itself current and improve (new/better skills, tools, MCPs, models) only within cost + permission bounds, learning from **successful** outcomes only (never amplifying failed trajectories), with validation, audit logging, and easy rollback. Never auto-edit protected files (build/IaC/CI/dependency manifests, CONSTITUTION) outside the explicit self-heal allowlist.
|
|
161
|
+
- **State Preservation & Portability**: Progress must never be lost to a token limit, time cutoff, or crash. Agents must persist working state continuously (resume pointer + memory) so any future session — in this or **any other** coding agent/LLM — can resume losslessly via a fully compatible state export/import.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Section 2 — Project-Specific Articles
|
|
166
|
+
|
|
167
|
+
> Add project-specific constitutional rules below.
|
|
168
|
+
> Each article should: state the rule, explain why it exists, give an example.
|
|
169
|
+
|
|
170
|
+
### Article XI — [User Defined]
|
|
171
|
+
<!-- This section is reserved for project-specific rules added by the user or init.py -->
|
|
172
|
+
<!-- Example: Tenant Isolation, Audit Trails, or Performance Budgets -->
|
|
173
|
+
|
|
174
|
+
<!-- OPTIONAL: Example Articles -> E.g. Multi-tenant rules, Audit trailing for regulated sectors, P99 payload latency strictness -->
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
<!-- OPTIONAL BOILERPLATE: EARS Syntax Quick Reference -> Refer to guides/planning/product-requirements.md or PRD_TEMPLATE.md for usage and implementation details of EARS (Ubiquitous, Event-Driven, State-Driven, Optional, Unwanted Behavior constraint formats). -->
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
*This Constitution was established on: [DATE]*
|
|
183
|
+
*Last amended: [DATE]*
|
|
184
|
+
*Amended by: [team member name]*
|
|
185
|
+
*Reason for amendment: [brief explanation]*
|
|
186
|
+
|
|
187
|
+
*GABBE Kit version: 0.9.6*
|
|
188
|
+
*This file is maintained by the team and updated when project conventions change.*
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Guides Registry — 00-index.md
|
|
2
|
+
|
|
3
|
+
> Complete catalog of all available domain, language, and architectural guides.
|
|
4
|
+
> Guides = Best practices, architectural standards, and specialized knowledge references.
|
|
5
|
+
> Usage: Agents reference these to understand *how* to build things in specific domains.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
> **Total Guides**: 86
|
|
10
|
+
> *Registry categorized by domain.*
|
|
11
|
+
|
|
12
|
+
## Guides Registry
|
|
13
|
+
|
|
14
|
+
### 1. Artificial Intelligence (`ai/`)
|
|
15
|
+
| Guide | File | Purpose |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| A2UI Protocols | `ai/a2ui-protocols.md` | Agent-to-User Interface protocols |
|
|
18
|
+
| Actor Frameworks | `ai/actor-agent-frameworks.md` | Multi-agent framework comparison |
|
|
19
|
+
| Agent Comm. | `ai/agent-communication.md` | Protocols for agent communication |
|
|
20
|
+
| Agent Ergonomics | `ai/agent-operating-ergonomics.md` | How a coding agent works optimally with GABBE + failure modes |
|
|
21
|
+
| Agent UI | `ai/agent-ui.md` | Designing UIs for autonomous agents |
|
|
22
|
+
| AI Agentic | `ai/ai-agentic.md` | Core principles of agentic engineering |
|
|
23
|
+
| Beyond LLMs | `ai/beyond-llms.md` | Advanced AI paradigms beyond text gen |
|
|
24
|
+
| Multi-Agent | `ai/multi-agent-systems.md` | Orchestrating swarms and agent topologies |
|
|
25
|
+
| Self-Healing | `ai/self-healing-summary.md` | Overview of system self-healing loops |
|
|
26
|
+
| Agent-Only Cognition | `ai/agent-only-cognition.md` | Cognition patterns for agent-only systems |
|
|
27
|
+
| Agent-Only Swarms | `ai/agent-only-swarms.md` | Swarm topologies without humans in the loop |
|
|
28
|
+
| Visual Integration | `ai/visual-mcp-integration.md` | Guide on Mermaid vs Canvas tools |
|
|
29
|
+
| Agent Identity & Trust | `ai/agent-identity-trust.md` | Agent identity, auth, KYA, signed mandates |
|
|
30
|
+
| Model Customization | `ai/model-customization-decisions.md` | Prompt vs RAG vs fine-tune; SLMs; routing |
|
|
31
|
+
| Dynamic Capability Loading | `ai/dynamic-capability-loading.md` | Loading skills/capabilities at runtime |
|
|
32
|
+
| GABBE Innovations | `ai/gabbe-innovations.md` | Novel techniques introduced by GABBE |
|
|
33
|
+
| Self-Evolving Skills | `ai/self-evolving-skills.md` | Skills that improve themselves over time |
|
|
34
|
+
|
|
35
|
+
### 1b. Processes (`processes/`)
|
|
36
|
+
| Guide | File | Purpose |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| RARV Cycle | `processes/RARV_CYCLE.md` | Reason Act Reflect Verify loop |
|
|
39
|
+
| Loki SDLC Phases | `processes/loki-sdlc-phases.md` | Detailed S01–S10 phase specs (referenced by loki-mode) |
|
|
40
|
+
| System Lifecycle | `processes/full-system-lifecycle.md` | SDLC and traceability |
|
|
41
|
+
| Knowledge Integration | `processes/knowledge-integration.md` | Connectors and RAG overview |
|
|
42
|
+
| Extension Protocol | `processes/extension-protocol.md` | How to extend the kit with new capabilities |
|
|
43
|
+
|
|
44
|
+
### 2. Architecture (`architecture/`)
|
|
45
|
+
| Guide | File | Purpose |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| API Standards | `architecture/api-standards.md` | REST, GraphQL, and RPC standards |
|
|
48
|
+
| Critical Systems | `architecture/critical-systems-arch.md` | High availability & fault tolerance |
|
|
49
|
+
| Event-Driven | `architecture/event-driven-architecture.md` | Event sourcing, CQRS context |
|
|
50
|
+
| Microservices | `architecture/microservices.md` | Service isolation and scaling |
|
|
51
|
+
| Monolith | `architecture/monolith.md` | Modular monolithic design |
|
|
52
|
+
| System Qualities| `architecture/system-qualities.md` | NFRs, SLAs, SLOs |
|
|
53
|
+
| Systems Arch. | `architecture/systems-architecture.md` | General system architecture primer |
|
|
54
|
+
| Orchestration | `architecture/orchestration.md` | Service & Agent orchestration |
|
|
55
|
+
| Scalability | `architecture/system-scalability.md` | Vertical and Horizontal scaling |
|
|
56
|
+
| Blockchain | `architecture/blockchain-dlt.md` | DLT and Decentralized Systems |
|
|
57
|
+
|
|
58
|
+
### 3. Data Engineering (`data/`)
|
|
59
|
+
| Guide | File | Purpose |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| SQL vs NoSQL | `data/sql-nosql.md` | Database selection criteria |
|
|
62
|
+
| Semantic Web | `data/semantic-web.md` | RDF, SPARQL, and Ontology usage |
|
|
63
|
+
|
|
64
|
+
### 4. Language Stacks (`languages/`)
|
|
65
|
+
| Guide | File | Purpose |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| C# / .NET | `languages/c-sharp.md` | C# enterprise patterns and tooling |
|
|
68
|
+
| Go (Golang) | `languages/go-lang.md` | Go standard project layouts |
|
|
69
|
+
| Java | `languages/java.md` | Maven/Gradle Spring standard |
|
|
70
|
+
| JS/TS & Node.js | `languages/js-ts-nodejs.md` | Clean Architecture in TS |
|
|
71
|
+
| Node.js Advanced | `languages/nodejs-advanced.md` | Node internals, libuv, Fastify, perf |
|
|
72
|
+
| PHP / Laravel | `languages/php-laravel.md` | DDD + Actions in Laravel |
|
|
73
|
+
| Python / FastAPI| `languages/python-fastapi-ai.md` | AI-first FastAPI architecture |
|
|
74
|
+
| Rust | `languages/rust.md` | Safe, concurrent systems |
|
|
75
|
+
|
|
76
|
+
### 5. Operations & DevOps (`ops/`)
|
|
77
|
+
| Guide | File | Purpose |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| Compliance | `ops/compliance-audit.md` | Pre-flight security/compliance checks |
|
|
80
|
+
| Dev Environments| `ops/dev-environments.md` | Local setup definitions |
|
|
81
|
+
| Prod Health | `ops/production-health.md` | Observability and alerting |
|
|
82
|
+
| Troubleshooting | `ops/troubleshooting-guide.md` | Standard operating procedures for incidents |
|
|
83
|
+
| Cost Opt. | `ops/cost-optimization.md` | FinOps & Resource reduction |
|
|
84
|
+
| Dev Workflow | `ops/dev-workflow.md` | Git/GitHub ops + Diátaxis docs |
|
|
85
|
+
| GABBE CLI Workflows | `ops/gabbe-cli-workflows.md` | Using the gabbe CLI platform controls |
|
|
86
|
+
|
|
87
|
+
### 6. Implementation Patterns (`patterns/`)
|
|
88
|
+
| Guide | File | Purpose |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| Agentic Patterns| `patterns/agentic-patterns.md` | Implementation paths for swarms |
|
|
91
|
+
| Agentic Design Patterns | `patterns/agentic-design-patterns.md` | Full pattern catalog: reasoning/planning/workflow/multi-agent/memory/safety |
|
|
92
|
+
| Software Design Patterns | `patterns/software-design-patterns.md` | Classical catalog: GoF + architectural + DDD + enterprise/distributed |
|
|
93
|
+
| AI Scenarios | `patterns/ai-native-scenarios.md` | Real-world AI integrations |
|
|
94
|
+
| Autonomous Swarm| `patterns/autonomous-swarm-patterns.md` | Inter-agent negotiation |
|
|
95
|
+
| Design Patterns | `patterns/design-patterns.md` | GoF and modern code patterns |
|
|
96
|
+
| Ent. Migration | `patterns/enterprise-migration-scenario.md` | Legacy to modern code paths |
|
|
97
|
+
| Ent. Patterns | `patterns/enterprise-patterns.md` | CQRS, Saga, and bounded contexts |
|
|
98
|
+
| Time Complexity | `patterns/time-complexity-analysis.md` | Big-O detection and remediation |
|
|
99
|
+
|
|
100
|
+
### 7. Product Planning (`planning/` + `product/`)
|
|
101
|
+
| Guide | File | Purpose |
|
|
102
|
+
|---|---|---|
|
|
103
|
+
| Product Reqs. | `planning/product-requirements.md` | EARS syntax and req. engineering |
|
|
104
|
+
| Visual Product Specs | `planning/visual-product-specs.md` | Visual inputs → specs pipeline |
|
|
105
|
+
| Strategic Anal. | `planning/strategic-analysis.md` | Pre-development strategic analysis |
|
|
106
|
+
| Green Software | `product/green-software.md` | Sustainable/green software engineering (SCI) |
|
|
107
|
+
| Sustainability Checks | `product/sustainability-checks.md` | ESG / carbon-intensity review checklist |
|
|
108
|
+
|
|
109
|
+
### 8. Principles & Standards (`principles/`)
|
|
110
|
+
| Guide | File | Purpose |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| Clean Code | `principles/clean-code-standards.md` | SOLID, DRY, KISS standards |
|
|
113
|
+
| Human–Agent Collab | `principles/human-agent-collaboration.md` | Manager-not-operator stance; purpose/transparency/control |
|
|
114
|
+
| Diagramming | `principles/diagramming-standards.md` | C4, UML, and Mermaid guidelines |
|
|
115
|
+
| Future Tech | `principles/future-tech.md` | Integrating cutting-edge frameworks |
|
|
116
|
+
| Legacy Tech | `principles/legacy-tech.md` | Handling deprecated codebases |
|
|
117
|
+
| No-Code Integ. | `principles/no-code-integration.md` | Connecting no-code platforms |
|
|
118
|
+
| Testing Strat. | `principles/testing-strategy.md` | The testing pyramid and mocks |
|
|
119
|
+
| Evaluation Strat. | `principles/evaluation-strategy.md` | Evals vs tests; eval pyramid; eval-driven CI |
|
|
120
|
+
| Mathematical Foundations | `principles/mathematical-foundations.md` | Logic, sets, graphs, probability/statistics (SWEBOK v4) |
|
|
121
|
+
| Computing Foundations | `principles/computing-foundations.md` | CS fundamentals → engineering decisions (SWEBOK v4) |
|
|
122
|
+
| Modeling Methods | `principles/modeling-methods.md` | Model types + formal/semi-formal method selection (SWEBOK v4) |
|
|
123
|
+
| Visual Design | `principles/visual-design-system.md` | Design tokens and accessibility |
|
|
124
|
+
|
|
125
|
+
### 9. Security & Privacy (`security/`)
|
|
126
|
+
| Guide | File | Purpose |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| API Security | `security/api-security.md` | OAuth, JWT, and input validation |
|
|
129
|
+
| Cryptography | `security/cryptography-standards.md` | Encryption transit/rest |
|
|
130
|
+
| Privacy Data | `security/privacy-data-protection.md` | GDPR, HIPAA handling |
|
|
131
|
+
| Secure Arch. | `security/secure-architecture.md` | Defense in depth |
|
|
132
|
+
| Threat Modeling | `security/threat-modeling.md` | STRIDE analysis methodology |
|
|
133
|
+
| AI Risk Standards Map | `security/ai-risk-standards-map.md` | OWASP LLM Top 10 / NIST AI RMF / MITRE ATLAS / ISO 42001 / EU AI Act mapping |
|
|
134
|
+
|
|
135
|
+
### 10. Industry Domains (`industry/`)
|
|
136
|
+
| Guide | File | Purpose |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| Engineering Std. | `industry/engineering-standards.md` | IEEE/ISO code quality levels |
|
|
139
|
+
| Global Standards | `industry/global-standards.md` | Regulatory & SDLC compliance |
|
|
140
|
+
| Healthcare FHIR | `industry/healthcare-fhir.md` | Medical data interoperability |
|
|
141
|
+
| Industrial IoT | `industry/industrial-iot.md` | OT/IT connectivity standards |
|
|
142
|
+
| Telecom Networks | `industry/telecom-networks.md` | 5G/OSS/BSS architectural patterns |
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# A2UI & Generative UI Protocols
|
|
2
|
+
|
|
3
|
+
**Standardizing how Agents draw Interfaces.**
|
|
4
|
+
|
|
5
|
+
This guide covers the **A2UI (Agent-to-User Interface)** protocol and related standards for 2026.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. What is A2UI?
|
|
10
|
+
|
|
11
|
+
A2UI is a **Declarative JSON Protocol** that allows an AI Agent to describe a UI without writing executable code (JS/Swift).
|
|
12
|
+
* **Security:** Agent cannot execute arbitrary scripts (XSS protection).
|
|
13
|
+
* **Native:** The Client (Web, iOS, Flutter) decides how to render the JSON.
|
|
14
|
+
|
|
15
|
+
### The A2UI Payload Structure
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"type": "column",
|
|
19
|
+
"children": [
|
|
20
|
+
{ "type": "text", "content": "System Status", "style": "h1" },
|
|
21
|
+
{ "type": "card", "status": "critical", "children": [
|
|
22
|
+
{ "type": "text", "content": "Database Latency High" },
|
|
23
|
+
{ "type": "button", "action": "restart_db", "label": "Fix it" }
|
|
24
|
+
]}
|
|
25
|
+
]
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 2. AG-UI (Agent-User Interaction)
|
|
32
|
+
|
|
33
|
+
While A2UI defines the *View*, AG-UI defines the *Transport*.
|
|
34
|
+
* **Streaming:** AG-UI supports JSON-Patch streaming, so the UI builds up token-by-token.
|
|
35
|
+
* **Events:** How the "Click" on the UI gets sent back to the Agent.
|
|
36
|
+
|
|
37
|
+
**Flow:**
|
|
38
|
+
1. User clicks "Fix it" (Client).
|
|
39
|
+
2. AG-UI sends event `{"action": "restart_db"}` to Agent.
|
|
40
|
+
3. Agent processes, tool calls, and sends new A2UI patch `{"op": "replace", "path": "/card/status", "value": "healthy"}`.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## 3. Implementation Strategies
|
|
45
|
+
|
|
46
|
+
### Strategy A: Vercel AI SDK (RSC)
|
|
47
|
+
* **Tech:** React Server Components.
|
|
48
|
+
* **Mechanism:** Agent streams actual React Components.
|
|
49
|
+
* **Pros:** Full power of React.
|
|
50
|
+
* **Cons:** Web only (React).
|
|
51
|
+
|
|
52
|
+
### Strategy B: Google A2UI (JSON)
|
|
53
|
+
* **Tech:** JSON Schema.
|
|
54
|
+
* **Mechanism:** Agent streams JSON, Client maps to Flutter/Swift/DOM.
|
|
55
|
+
* **Pros:** True Cross-Platform (Mobile/Web/CLI).
|
|
56
|
+
* **Cons:** Limited to supported primitives.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 4. Designing for A2UI
|
|
61
|
+
|
|
62
|
+
When building skills for A2UI (like `coding/ui-gen.skill.md`), teach the Agent to:
|
|
63
|
+
1. **Prefer Semantics:** Use "Card", "Alert", "List" (A2UI types) instead of `div` or `span`.
|
|
64
|
+
2. **Statelessness:** Assume the UI is projected state. Don't ask the UI to remember things; the Agent remembers.
|
|
65
|
+
3. **Progressive Disclosure:** Start with a summary, offer a "Drill Down" action.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 5. Future 2027+
|
|
70
|
+
* **Generative ASM (App State Matrix):** Agents controlling the entire app state via Redux/MobX updates.
|
|
71
|
+
* **Neuro-Symbolic UI:** UI elements that adapt their layout based on the user's cognitive load (sensed via webcam/biometrics).
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Actor Models & Agent Frameworks
|
|
2
|
+
|
|
3
|
+
**Bridging Classic Distributed Systems with Modern AI Agents.**
|
|
4
|
+
|
|
5
|
+
This guide explains the theoretical and practical convergence of the **Actor Model** (1973) and **Agentic AI** (2026).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. The Convergence
|
|
10
|
+
|
|
11
|
+
| Concept | Classic Actor (Akka/Erlang) | Modern AI Agent (LangGraph/Loki) |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| **Unit of Comp** | Actor (Process) | Agent (Loki Persona) |
|
|
14
|
+
| **Communication** | Async Messages (Mailbox) | Prompts / Structured JSON |
|
|
15
|
+
| **State** | Private, Mutable (in RAM) | Context Window / Vector DB |
|
|
16
|
+
| **Failure** | "Let it Crash" (Supervisors) | Self-Correction / Retries |
|
|
17
|
+
| **Topology** | Mesh / Tree | Graph / Swarm |
|
|
18
|
+
|
|
19
|
+
**Key Insight:** AI Agents *are* Actors, but with a probabilistic brain instead of a deterministic script.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 2. Framework Comparison
|
|
24
|
+
|
|
25
|
+
### Classic (Infrastructure Layer)
|
|
26
|
+
* **Erlang/Elixir (OTP):** The gold standard for "99.9999999% uptime". Perfect for the *control plane* of a swarm.
|
|
27
|
+
* **Akka (Scala/Java):** JVM-based actor system. Good for high-throughput data processing.
|
|
28
|
+
* **Proto.actor (Go/C#):** Lightweight, cross-platform actors.
|
|
29
|
+
|
|
30
|
+
### Modern (Cognitive Layer)
|
|
31
|
+
* **LangGraph:** Adds "State Machines" and "Cyclic Graphs" to Agents. Best for reasoning loops.
|
|
32
|
+
* **Microsoft AutoGen:** Explicitly uses "Conversational Agents" which act like Actors sending text messages.
|
|
33
|
+
* **Loki (This Kit):** Uses a **Swarm Topology** where the "Orchestrator" is the Supervisor Actor.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 3. Implementing the Hybrid Architecture
|
|
38
|
+
|
|
39
|
+
The strongest systems in 2026 use **Actors for Plumbing** and **Agents for Reasoning**.
|
|
40
|
+
|
|
41
|
+
### Pattern: The "Shell & Brain"
|
|
42
|
+
* **The Shell (Go/Elixir Actor):** Handles networking, mailbox, retries, and determining "Is the agent alive?".
|
|
43
|
+
* **The Brain (Python/LLM Agent):** The internal logic function called by the Shell when a message arrives.
|
|
44
|
+
|
|
45
|
+
```mermaid
|
|
46
|
+
graph TD
|
|
47
|
+
A[Akka Supervisor] -->|Restarts| B[Agent Actor Shell]
|
|
48
|
+
B -->|Sends Prompt| C[LLM Brain]
|
|
49
|
+
C -->|Returns Action| B
|
|
50
|
+
B -->|Side Effect| D[Database/API]
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
[Akka Supervisor]
|
|
55
|
+
| (Restarts)
|
|
56
|
+
v
|
|
57
|
+
[Agent Actor Shell] --(Sends Prompt)--> [LLM Brain]
|
|
58
|
+
| |
|
|
59
|
+
|<-------(Returns Action)------------+
|
|
60
|
+
|
|
|
61
|
+
(Side Effect)
|
|
62
|
+
|
|
|
63
|
+
v
|
|
64
|
+
[(Database/API)]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 4. Best Practices
|
|
70
|
+
|
|
71
|
+
1. **Mailboxes:** Agents are slow. Your Actor system must have *large* mailboxes or backpressure to handle the speed mismatch (ms vs sec).
|
|
72
|
+
2. **Supervision Strategies:**
|
|
73
|
+
* *Hallucination Exception:* -> **Restart** (Clear context, try again).
|
|
74
|
+
* *Tool Error:* -> **Resume** (Keep context, try different tool).
|
|
75
|
+
3. **Addressability:** Give every Agent a stable URL or PID (e.g., `actor://swarm/eng-backend/ipv4`).
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 5. References
|
|
80
|
+
* [The Actor Model (Hewitt, 1973)]
|
|
81
|
+
* [Erlang OT Design Principles]
|
|
82
|
+
* [LangGraph Documentation]
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Agent Communication Guide: MCP, A2A, & Swarms
|
|
2
|
+
|
|
3
|
+
> **Goal**: Enable agents to stop being lonely chatbots and start working as a cohesive, multi-agent system (MAS).
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. The Communication Stack
|
|
8
|
+
|
|
9
|
+
Just like the OSI model for networking, Agentic Systems have layers:
|
|
10
|
+
|
|
11
|
+
| Layer | Protocol | Purpose | Example |
|
|
12
|
+
|---|---|---|---|
|
|
13
|
+
| **L7 Application** | **MCP** / **A2A** | Semantics (Tools vs Tasks) | "Use tool X" / "Do task Y" |
|
|
14
|
+
| **L6 Presentation** | JSON / MsgPack | Serialization format | `{"jsonrpc": "2.0"}` |
|
|
15
|
+
| **L5 Session** | **Handshake** | Identity & Capability verify | `AGENT_HANDSHAKE_TEMPLATE` |
|
|
16
|
+
| **L4 Transport** | HTTP / SSE / Stdio | Moving bytes | `POST /rpc` |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## 2. Protocol Breakdown
|
|
21
|
+
|
|
22
|
+
### A. Model Context Protocol (MCP)
|
|
23
|
+
**Best for**: "Headless" Tool Use & Resource Access.
|
|
24
|
+
* **Role**: Client (LLM) <-> Server (Tools/Data).
|
|
25
|
+
* **Transport**: Stdio (Local), SSE (Remote).
|
|
26
|
+
* **Use Case**: Agent needs to read a file, query a database, or search the web.
|
|
27
|
+
* **Key Concept**: It's about *capabilities*, not high-level reasoning.
|
|
28
|
+
|
|
29
|
+
### B. Agent-to-Agent (A2A) Protocol
|
|
30
|
+
**Best for**: Task Delegation & collaboration.
|
|
31
|
+
* **Role**: Peer <-> Peer.
|
|
32
|
+
* **Transport**: HTTP, WebSockets, or Message Queue (RabbitMQ).
|
|
33
|
+
* **Use Case**: "Frontend Agent" asks "Backend Agent" to design an API.
|
|
34
|
+
* **Key Concept**: It's about *goals* and *outcomes*.
|
|
35
|
+
|
|
36
|
+
### C. Agent Communication Protocol (ACP / FIPA-ACL)
|
|
37
|
+
**Best for**: Complex negotiation and belief sharing (Academic/Enterprise).
|
|
38
|
+
* **Structure**: Performative (Request/Inform/Propose) + Content.
|
|
39
|
+
* **Use Case**: "I propose doing X for price Y." -> "Accepted."
|
|
40
|
+
|
|
41
|
+
### D. Convergence & Governance (2025-2026)
|
|
42
|
+
The protocol landscape consolidated under open governance — design for it:
|
|
43
|
+
* **A2A** moved to the **Linux Foundation** (2025) as a vendor-neutral open project (150+ orgs); the earlier IBM/BeeAI **ACP** effort converged into A2A. Treat A2A as the standard agent-to-agent task layer.
|
|
44
|
+
* **AGNTCY / "Internet of Agents"** (Cisco → Linux Foundation, 2025) adds the cross-framework substrate: agent **discovery/directory**, **identity**, **secure messaging**, and **observability** — interoperable with both **A2A** and **MCP**. See `agent-identity-trust.md`.
|
|
45
|
+
* **MCP authorization**: recent MCP specs define an OAuth **resource-server** model — scope tool access with short-lived, least-privilege tokens (see `agent-sandboxing.skill` and `prompt-injection-defense.skill`).
|
|
46
|
+
|
|
47
|
+
Practical stance: **MCP** for agent→tool/data, **A2A** for agent→agent tasks, **AGNTCY** for discovery/identity/observability across frameworks. These are evolving; keep bindings additive.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. Topologies
|
|
52
|
+
|
|
53
|
+
### Local Swarm (Loki Mode)
|
|
54
|
+
* **Type**: **Star Topology** (Hub & Spoke).
|
|
55
|
+
* **Hub**: `loki-mode.skill` (The Orchestrator).
|
|
56
|
+
* **Nodes**: Ephemeral personas (Coder, Reviewer).
|
|
57
|
+
* **Transport**: Function Calls (in-memory) or Stdio.
|
|
58
|
+
* **Pros**: Fast, simple context sharing. **Cons**: Single point of failure.
|
|
59
|
+
|
|
60
|
+
### Remote Mesh (Micro-Agents)
|
|
61
|
+
* **Type**: **Mesh Topology**.
|
|
62
|
+
* **Nodes**: Independent services (containers/lambda).
|
|
63
|
+
* **Transport**: HTTP/REST or gRPC.
|
|
64
|
+
* **Service Discovery**: Consul / K8s DNS.
|
|
65
|
+
* **Pros**: Scalable, resilient. **Cons**: Complexity, network latency.
|
|
66
|
+
|
|
67
|
+
### Hybrid (The "Pod" Model)
|
|
68
|
+
* **Structure**: Local pods of 3-4 agents (Dev Pod, QA Pod) talking internally via Stdio, externally via HTTP.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 4. Implementation Patterns
|
|
73
|
+
|
|
74
|
+
### Pattern 1: The "Handshake" (Trust but Verify)
|
|
75
|
+
Before exchanging tasks, agents MUST introduce themselves using `coordination/AGENT_HANDSHAKE_TEMPLATE.json`.
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
// Agent A sends:
|
|
79
|
+
{
|
|
80
|
+
"identity": {"role": "planner", "id": "uuid-1"},
|
|
81
|
+
"protocols": ["mcp", "a2a"]
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// Agent B replies:
|
|
85
|
+
{
|
|
86
|
+
"status": "accepted",
|
|
87
|
+
"identity": {"role": "coder", "id": "uuid-2"}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Pattern 2: The "Contract Net" (Marketplace)
|
|
92
|
+
1. **Manager**: Broadcasts: "Who can build a React component?"
|
|
93
|
+
2. **Worker A**: "I can. (Cost: Low, Speed: Fast)"
|
|
94
|
+
3. **Worker B**: "I can. (Cost: High, Speed: Medium)"
|
|
95
|
+
4. **Manager**: Awards task to Worker A.
|
|
96
|
+
|
|
97
|
+
### Pattern 3: The "Blackboard" (Shared State)
|
|
98
|
+
Agents don't talk directly; they write to a shared "Blackboard" (Redis/Database).
|
|
99
|
+
* **Writer**: Puts "Draft Spec" on board.
|
|
100
|
+
* **Reviewer**: Sees new "Draft Spec", critiques it, writes "Review".
|
|
101
|
+
* **Writer**: Sees "Review", updates Spec.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 5. Generic A2A Server Example (Python)
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from fastapi import FastAPI, Request
|
|
109
|
+
from pydantic import BaseModel
|
|
110
|
+
|
|
111
|
+
app = FastAPI()
|
|
112
|
+
|
|
113
|
+
class AgentMessage(BaseModel):
|
|
114
|
+
sender: str
|
|
115
|
+
content: str
|
|
116
|
+
type: str = "inform" # request, query, propose
|
|
117
|
+
|
|
118
|
+
@app.post("/a2a/message")
|
|
119
|
+
async def receive_message(msg: AgentMessage):
|
|
120
|
+
# 1. Validate Sender
|
|
121
|
+
if not is_authorized(msg.sender):
|
|
122
|
+
return {"error": "Unauthorized"}
|
|
123
|
+
|
|
124
|
+
# 2. Process Protocol
|
|
125
|
+
if msg.type == "request":
|
|
126
|
+
# ... trigger internal reasoning ...
|
|
127
|
+
response = agent_core.think(msg.content)
|
|
128
|
+
return {"status": "success", "response": response}
|
|
129
|
+
|
|
130
|
+
return {"status": "received"}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 6. Integrating with Loki (This Kit)
|
|
136
|
+
|
|
137
|
+
1. **Define Peers**: Add them to `coordination/SWARM_CONFIG_TEMPLATE.json`.
|
|
138
|
+
2. **Connect**: Use `agent-interop.skill` to establish the link.
|
|
139
|
+
3. **Collaborate**:
|
|
140
|
+
* *Human*: "Ask the Security Agent to review this."
|
|
141
|
+
* *Loki*:
|
|
142
|
+
1. Loads `agent-interop`.
|
|
143
|
+
2. Connects to `http://security-agent:8080`.
|
|
144
|
+
3. Sends A2A "Review Request".
|
|
145
|
+
4. Awaits response.
|
|
146
|
+
5. Integrates feedback into context.
|