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,73 @@
|
|
|
1
|
+
# Rust Project Guide
|
|
2
|
+
|
|
3
|
+
> **Audience:** agents writing or reviewing Rust services/tools. **Scope:**
|
|
4
|
+
> current edition, idioms, structure, testing, performance, and pitfalls for
|
|
5
|
+
> 2026. Versions verified 2026-06-10 (see sources at the end).
|
|
6
|
+
|
|
7
|
+
## Recommended stack (2026)
|
|
8
|
+
|
|
9
|
+
- **Toolchain:** latest stable Rust on **edition 2024** (stabilized in Rust
|
|
10
|
+
1.85.0, 2025-02-20). Set `edition = "2024"` in `Cargo.toml`. Pin with
|
|
11
|
+
`rust-toolchain.toml`.
|
|
12
|
+
- **Async runtime:** **Tokio** (de-facto standard) — multi-threaded scheduler,
|
|
13
|
+
timers, I/O, sync primitives.
|
|
14
|
+
- **Web:** **Axum** (Tower-based, ergonomic) or Actix-Web (max throughput).
|
|
15
|
+
- **Data:** **SQLx** (async, compile-time-checked SQL) or SeaORM/Diesel for an
|
|
16
|
+
ORM. `serde` + `serde_json` for serialization.
|
|
17
|
+
- **Errors:** `thiserror` for library error enums; `anyhow` for application-level
|
|
18
|
+
error context. Avoid `unwrap()`/`expect()` outside tests and provably-infallible spots.
|
|
19
|
+
- **Testing:** built-in `#[test]` + `assert_*`; `tokio::test` for async;
|
|
20
|
+
`proptest` for property tests; `criterion` for benchmarks; `testcontainers` for
|
|
21
|
+
integration.
|
|
22
|
+
- **Quality:** `cargo clippy -- -D warnings`, `cargo fmt`, `cargo deny` (license/
|
|
23
|
+
advisory), and `cargo audit` for the RustSec advisory DB.
|
|
24
|
+
|
|
25
|
+
## Idioms (edition 2024)
|
|
26
|
+
|
|
27
|
+
- **Ownership & borrowing** drive the design: prefer owned data at boundaries,
|
|
28
|
+
borrow for reads; reach for `Arc`/`Mutex` only when shared mutable state is
|
|
29
|
+
unavoidable. Favor message passing (`tokio::mpsc`) over shared locks.
|
|
30
|
+
- Model domain states with `enum`s and exhaustive `match`; use the newtype
|
|
31
|
+
pattern for type-safe identifiers.
|
|
32
|
+
- `Result<T, E>` + the `?` operator for fallible flows; convert errors with
|
|
33
|
+
`From`/`thiserror`. Use `Option` combinators (`map`, `and_then`, `ok_or`).
|
|
34
|
+
- **Async closures** (`async || {}`) are stable as of edition 2024 — use them for
|
|
35
|
+
combinator-style async code.
|
|
36
|
+
- `unsafe` only behind a safe, documented abstraction with an explicit invariant
|
|
37
|
+
comment; edition 2024 requires `unsafe extern` blocks and `unsafe` attributes.
|
|
38
|
+
|
|
39
|
+
## Project structure
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
Cargo.toml [workspace] for multi-crate; edition = "2024"
|
|
43
|
+
src/
|
|
44
|
+
main.rs | lib.rs binary vs library crate root
|
|
45
|
+
domain/ pure types + logic (no I/O)
|
|
46
|
+
infra/ db, http clients, adapters
|
|
47
|
+
api/ axum routers/handlers
|
|
48
|
+
tests/ integration tests (separate crate)
|
|
49
|
+
benches/ criterion benchmarks
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Split a workspace into a `lib` crate (testable core) + thin `bin` crate.
|
|
53
|
+
|
|
54
|
+
## Performance & ops
|
|
55
|
+
|
|
56
|
+
- Build with `--release`; tune `[profile.release]` (`lto = "thin"`,
|
|
57
|
+
`codegen-units = 1`, `panic = "abort"` for smallest/fastest binaries).
|
|
58
|
+
- Profile before optimizing (`cargo flamegraph`, `perf`); avoid premature
|
|
59
|
+
`clone()`; prefer borrowing and `&str`/`&[T]` in hot paths.
|
|
60
|
+
- Observe with `tracing` + `tracing-opentelemetry`; structured spans over `println!`.
|
|
61
|
+
|
|
62
|
+
## Common pitfalls
|
|
63
|
+
|
|
64
|
+
- Fighting the borrow checker by sprinkling `clone()`/`Arc<Mutex<…>>` — usually a
|
|
65
|
+
design smell; restructure ownership instead.
|
|
66
|
+
- Blocking calls inside async tasks — use `tokio::task::spawn_blocking`.
|
|
67
|
+
- `.unwrap()` in library/production code; panics across FFI boundaries.
|
|
68
|
+
- Holding a `MutexGuard` across an `.await` (can deadlock) — drop it first.
|
|
69
|
+
|
|
70
|
+
## Sources (verified 2026-06-10)
|
|
71
|
+
- Rust 1.85.0 + 2024 edition announcement: <https://blog.rust-lang.org/2025/02/20/Rust-1.85.0/>
|
|
72
|
+
- Rust 2024 edition guide: <https://doc.rust-lang.org/edition-guide/rust-2024/index.html>
|
|
73
|
+
- RustSec advisory DB (`cargo audit`): <https://rustsec.org/>
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# Guide: Compliance & Audit Logging
|
|
2
|
+
<!-- GDPR, SOC2, HIPAA, and Security Auditing Standards -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Overview
|
|
7
|
+
|
|
8
|
+
Compliance is not just about checking boxes; it's about **traceability** and **privacy**. This guide defines how to implement audit logging, handle PII (Personally Identifiable Information), and meet regulatory requirements (GDPR, CCPA, SOC2, HIPAA) across our tech stacks.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 1. The Audit Log Standard
|
|
13
|
+
|
|
14
|
+
Every mutation of regulated data MUST be logged. Identifying *who* did *what* to *whom* and *when*.
|
|
15
|
+
|
|
16
|
+
### The 5 Ws of Audit Logging
|
|
17
|
+
1. **Who:** `actor_id` (User UUID, Service Account, or API Key ID)
|
|
18
|
+
2. **What:** `action` (CREATE, UPDATE, DELETE, VIEW, EXPORT)
|
|
19
|
+
3. **When:** `timestamp` (ISO 8601 UTC)
|
|
20
|
+
4. **Where:** `ip_address`, `user_agent`, `resource_id` (Target entity)
|
|
21
|
+
5. **Why:** `context` (Request ID, Reason code)
|
|
22
|
+
|
|
23
|
+
### Audit Log Schema (JSON)
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"timestamp": "2023-10-27T10:00:00Z",
|
|
28
|
+
"event_id": "evt_123456789",
|
|
29
|
+
"actor": {
|
|
30
|
+
"id": "usr_987654321",
|
|
31
|
+
"type": "user",
|
|
32
|
+
"ip": "203.0.113.1",
|
|
33
|
+
"email": "alice@example.com"
|
|
34
|
+
},
|
|
35
|
+
"action": "user.password_reset",
|
|
36
|
+
"target": {
|
|
37
|
+
"id": "usr_987654321",
|
|
38
|
+
"type": "user"
|
|
39
|
+
},
|
|
40
|
+
"changes": {
|
|
41
|
+
"prev": null,
|
|
42
|
+
"next": null // Never log secrets/passwords!
|
|
43
|
+
},
|
|
44
|
+
"metadata": {
|
|
45
|
+
"trace_id": "trc_abc123",
|
|
46
|
+
"status": "success"
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## 2. GDPR & Privacy Engineering
|
|
54
|
+
|
|
55
|
+
### PII Classification
|
|
56
|
+
* **Public:** Product names, doc content. -> *No redaction needed.*
|
|
57
|
+
* **Internal:** Internal IDs, non-sensitive configs. -> *Log freely.*
|
|
58
|
+
* **Confidential (PII):** Email, IP, Phone, Name. -> *Mask in app logs, encrypt in DB.*
|
|
59
|
+
* **Restricted (Sensitive PII):** SSN, Passport, Credit Card (PAN), Health Data. -> *Tokenize, strict access control, never log.*
|
|
60
|
+
|
|
61
|
+
### Data Subject Rights
|
|
62
|
+
* **Right to Access (DSAR):** System must be able to export ALL data for a `user_id` (JSON export).
|
|
63
|
+
* **Right to Verification:** Logs must prove data hasn't been tampered with.
|
|
64
|
+
* **Right to Erasure (RTBF):**
|
|
65
|
+
* **Hard Delete:** Delete row. (Data gone).
|
|
66
|
+
* **Soft Delete:** RESTRICTED method. (Marked `deleted_at`).
|
|
67
|
+
* **Anonymization:** Overwrite PII with `REDACTED`. **Preferred for audit logs.**
|
|
68
|
+
* *Note:* You CANNOT delete Audit Logs for security reasons (legitimate interest), but you MUST anonymize the PII within them if requested and retention period passed.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## 3. Implementation Strategies
|
|
73
|
+
|
|
74
|
+
### Node.js / TypeScript
|
|
75
|
+
**Libraries:** `pino` (logging), `open-telemetry` (tracing)
|
|
76
|
+
|
|
77
|
+
```typescript
|
|
78
|
+
import pino from 'pino';
|
|
79
|
+
|
|
80
|
+
const auditLogger = pino({
|
|
81
|
+
base: { service: 'user-service' },
|
|
82
|
+
redact: {
|
|
83
|
+
paths: ['email', 'password', 'token'],
|
|
84
|
+
censor: '[REDACTED]'
|
|
85
|
+
}
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
function logAudit(actor: Actor, action: string, target: Entity) {
|
|
89
|
+
auditLogger.info({
|
|
90
|
+
type: 'audit', // Differentiates from debug/app logs
|
|
91
|
+
actor_id: actor.id,
|
|
92
|
+
action,
|
|
93
|
+
target_id: target.id,
|
|
94
|
+
target_type: target.constructor.name
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Python / FastAPI
|
|
100
|
+
**Libraries:** `structlog` (structured logging)
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
import structlog
|
|
104
|
+
|
|
105
|
+
logger = structlog.get_logger()
|
|
106
|
+
|
|
107
|
+
# Middleware for Audit
|
|
108
|
+
async def audit_middleware(request: Request, call_next):
|
|
109
|
+
response = await call_next(request)
|
|
110
|
+
if request.method in ["POST", "PUT", "DELETE"]:
|
|
111
|
+
await logger.info(
|
|
112
|
+
"audit_event",
|
|
113
|
+
actor_id=request.state.user.id,
|
|
114
|
+
action=f"{request.method} {request.url.path}",
|
|
115
|
+
status=response.status_code
|
|
116
|
+
)
|
|
117
|
+
return response
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### PHP / Laravel
|
|
121
|
+
**Libraries:** `spatie/laravel-activitylog`
|
|
122
|
+
|
|
123
|
+
```php
|
|
124
|
+
activity()
|
|
125
|
+
->performedOn($order)
|
|
126
|
+
->causedBy($user)
|
|
127
|
+
->withProperties(['amount' => 100])
|
|
128
|
+
->log('Order placed');
|
|
129
|
+
|
|
130
|
+
// In model
|
|
131
|
+
protected $logAttributes = ['status', 'total']; // Only log safe attributes
|
|
132
|
+
protected $logOnlyDirty = true;
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 4. Security Monitoring (SIEM)
|
|
138
|
+
|
|
139
|
+
### What to Alert On
|
|
140
|
+
1. **Authentication Failures:** > 5 failures in 1 minute from single IP.
|
|
141
|
+
2. **Privilege Escalation:** User added to `admin` group.
|
|
142
|
+
3. **Mass Export:** User exports > 100 records (DLP monitoring).
|
|
143
|
+
4. **Sensitive Access:** Access to "Break Glass" accounts.
|
|
144
|
+
5. **Configuration Change:** Production ENV vars changed.
|
|
145
|
+
|
|
146
|
+
### Log retention (Standard)
|
|
147
|
+
* **App Logs (Debug/Info):** 7-30 days.
|
|
148
|
+
* **Audit Logs (Security):** 1 year (Hot/Cold storage).
|
|
149
|
+
* **Archive:** 6 years (HIPAA/Financial).
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 5. Compliance Checklist (Quick Reference)
|
|
154
|
+
|
|
155
|
+
* [ ] **Encryption:** TLS 1.2+ in transit, AES-256 at rest.
|
|
156
|
+
* [ ] **Access Control:** RBAC implemented + MFA for admins.
|
|
157
|
+
* [ ] **Audit Trails:** Immutable logs for all writes.
|
|
158
|
+
* [ ] **Backups:** Encrypted and tested quarterly.
|
|
159
|
+
* [ ] **Vulnerability Scanning:** Automated SAST/DAST in CI/CD.
|
|
160
|
+
* [ ] **Privacy Policy:** Accessible and accurate.
|
|
161
|
+
* [ ] **Incident Response:** Plan tested annually.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Output for Auditor
|
|
166
|
+
When an auditor asks "Show me evidence of Access Control", providing the `core/AUDIT_LOG_TEMPLATE.md` (for Loki/Dev) or the SIEM dashboard screenshots (for Prod) is standard proof.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## 6. Relevant Skills
|
|
171
|
+
|
|
172
|
+
| Skill | Purpose |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `access-control` | Implements RBAC/ABAC and Identity Management. |
|
|
175
|
+
| `data-governance` | Enforces Data Classification (PII tags) and Lineage. |
|
|
176
|
+
| `security-audit` | Checks for hardcoded secrets and known vulnerabilities. |
|
|
177
|
+
| `privacy-audit` | Maps PII data flow and checks for GDPR compliance. |
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Cost Optimization & FinOps Guide
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
Financial Operations (FinOps) is the operating model for the cloud, bringing financial accountability to the variable spend model of cloud computing. This guide provides the philosophical and technical strategies to maximize business value from your architecture.
|
|
5
|
+
|
|
6
|
+
## Principles of FinOps
|
|
7
|
+
1. **Teams need to collaborate**: Finance, engineering, and product teams must work together in near-real time.
|
|
8
|
+
2. **Decisions are driven by business value**: Unit economics (e.g., cost per transaction, cost per user) drive decisions, not just aggregate spend.
|
|
9
|
+
3. **Everyone takes ownership**: Engineers are responsible for the costs their architectures generate.
|
|
10
|
+
4. **Data must be accessible and timely**: Feedback loops on cost must be immediate to allow for quick corrections.
|
|
11
|
+
|
|
12
|
+
## Architectural Strategies for Cost Optimization
|
|
13
|
+
|
|
14
|
+
| Strategy | Description | Implementation Examples |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| **Right-Sizing** | Continuously matching instance types and sizes to workload performance and capacity requirements. | Use predictive scaling; downsize underutilized EC2/RDS instances; utilize ARM-based instances (like Graviton). |
|
|
17
|
+
| **Commitment Discounts** | Utilizing financial instruments for baseline loads. | Reserved Instances (RIs), Savings Plans, committed use discounts. |
|
|
18
|
+
| **Auto-Scaling & Elasticity** | Matching provisioned resources dynamically to actual demand. | Kubernetes HPA (Horizontal Pod Autoscaler), scaling down non-prod environments off-hours. |
|
|
19
|
+
| **Serverless Architectures** | Paying strictly for execution time rather than idle capacity. | Adopting AWS Lambda, Azure Functions, Cloud Run, DynamoDB (On-Demand). |
|
|
20
|
+
| **Storage Tiering** | Moving data to cheaper storage classes based on access frequency. | S3 Lifecycle policies (Standard -> Infrequent Access -> Glacier). |
|
|
21
|
+
| **Spot Instances** | Using surplus compute capacity at steep discounts for fault-tolerant workloads. | Running stateless background workers, CI/CD pipelines, or big-data processing on Spot. |
|
|
22
|
+
|
|
23
|
+
## The FinOps Lifecycle
|
|
24
|
+
1. **Inform**: Visibility and allocation. Implement strict resource tagging schemas. Showback/chargeback to specific business units.
|
|
25
|
+
2. **Optimize**: Identify specific optimizations (rightsizing, spot usage, terminating zombies).
|
|
26
|
+
3. **Operate**: Automate the FinOps practices. Build continuous checks into the CI/CD pipeline.
|
|
27
|
+
|
|
28
|
+
## LLM & Agentic Cost Control (the agent's own spend)
|
|
29
|
+
|
|
30
|
+
The largest variable cost of an agentic system is LLM tokens. GABBE controls this with four levers, all enforceable through the platform-control layer (`gabbe budget` / `route` / `forecast`).
|
|
31
|
+
|
|
32
|
+
### 1. Prompt caching — the highest-leverage lever
|
|
33
|
+
Reusing a stable prompt prefix avoids re-billing it on every call. Sources verified 2026-06-10.
|
|
34
|
+
|
|
35
|
+
- **OpenAI-compatible endpoints (GABBE default):** caching is **automatic** for prefixes ≥ **1,024 tokens** — no code change. Cached input is discounted **~50%** (more on some newer models). Cache hits appear in `usage.prompt_tokens_details.cached_tokens`. Caches expire after ~5–10 min idle (≤1h). (openai.com/index/api-prompt-caching; developers.openai.com/api/docs/guides/prompt-caching)
|
|
36
|
+
- **Anthropic endpoints:** opt in with `cache_control: {"type": "ephemeral"}` (5-min TTL) or `{"ttl": "1h"}`. Cache **write** costs 1.25× (5m)/2× (1h) base input; cache **read** ~**0.1×**. ≤4 breakpoints; verify via `usage.cache_read_input_tokens`. (platform.claude.com/docs/en/build-with-claude/prompt-caching)
|
|
37
|
+
- **Make caching work:** keep the stable content (system prompt, tool list, frozen context) FIRST and byte-identical; put volatile content (timestamps, IDs, the user's question) LAST. Silent cache-busters: `datetime.now()`/UUIDs in the system prompt, unsorted `json.dumps`, per-user IDs in the prefix, changing the tool set mid-session.
|
|
38
|
+
- GABBE accounts for cache hits in `gabbe/budget.py` (cached tokens billed at the cache-read rate), so `gabbe forecast` reflects the real discounted cost.
|
|
39
|
+
|
|
40
|
+
### 2. Context-window budgeting via `context_cost`
|
|
41
|
+
Every skill declares `context_cost: low | medium | high` (low <2k tokens, medium 2–8k, high >8k). Load the **minimum** skills/guides needed; prefer `low`-cost skills; only pull `high`-cost context when the task demands it. This caps the input tokens an agent pays for per step.
|
|
42
|
+
|
|
43
|
+
### 3. Model tiering (route cheap → escalate)
|
|
44
|
+
Match model power to task difficulty. `gabbe route` decides LOCAL (free/cheap local model) vs REMOTE (SOTA) by complexity + PII. Reserve the most expensive model for genuinely hard, correctness-critical work; default to the cheapest reliable tier (per the AGENTS.md *Default Cost & Budget Optimization* mandate and CONSTITUTION cost article).
|
|
45
|
+
|
|
46
|
+
### 4. Batching & off-peak
|
|
47
|
+
For non-latency-sensitive bulk work, async batch APIs run at **−50%** (e.g. Anthropic Message Batches). Schedule large non-interactive runs (audits, migrations, regen) as batches.
|
|
48
|
+
|
|
49
|
+
### Hard guardrails (never disabled)
|
|
50
|
+
`GABBE_MAX_COST_USD`, token/iteration/wall-time budgets, and hard stops bound a runaway loop regardless of the optimizations above — cost control must never weaken the quality gates, the 10-phase SDLC, or human-in-the-loop escalation.
|
|
51
|
+
|
|
52
|
+
## Automation & Agentic Checks
|
|
53
|
+
Use the `cost-optimization.skill.md` to autonomously:
|
|
54
|
+
- Generate `COST_OPTIMIZATION_REPORT_TEMPLATE.md`.
|
|
55
|
+
- Analyze IaC (Terraform/CloudFormation) for untagged resources or over-provisioned defaults.
|
|
56
|
+
- Recommend architectural shifts (e.g., "This cron job runs 24/7 on EC2; moving to Serverless framework will save 80%").
|
|
57
|
+
- Audit AI/LLM costs using the [Performant AI Skill](../../skills/coding/performant-ai.skill.md), applying the four LLM levers above.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Development Environments Guide: Local vs. Remote vs. Outer Loop
|
|
2
|
+
|
|
3
|
+
Choosing the right development environment strategy is critical for velocity. In 2025, we have moved beyond "everything on localhost".
|
|
4
|
+
|
|
5
|
+
## 1. Strategies Overview
|
|
6
|
+
|
|
7
|
+
| Strategy | Where Code Runs | Where Deps Run | Best For | Tools |
|
|
8
|
+
|---|---|---|---|---|
|
|
9
|
+
| **Local Native** | Local OS | Local (Docker) | Simple Microservices, Monoliths | Node, Go, Docker Compose |
|
|
10
|
+
| **Local Container**| DevContainer | Docker | Team Consistency, Onboarding | VS Code DevContainers |
|
|
11
|
+
| **Remote Bridge**| Local OS | Remote K8s | Microservices dependent on Cloud | Telepresence |
|
|
12
|
+
| **Remote Native** | Remote K8s | Remote K8s | Huge Apps, Low-Power Laptops | Okteto, DevSpace, Coder |
|
|
13
|
+
|
|
14
|
+
## 2. Local Development (Inner Loop)
|
|
15
|
+
|
|
16
|
+
**The Gold Standard**: `Docker Compose Watch`
|
|
17
|
+
- **Why**: It syncs files to running containers *instantly* without rebuilding.
|
|
18
|
+
- **Config**:
|
|
19
|
+
```yaml
|
|
20
|
+
services:
|
|
21
|
+
web:
|
|
22
|
+
build: .
|
|
23
|
+
develop:
|
|
24
|
+
watch:
|
|
25
|
+
- action: sync
|
|
26
|
+
path: ./web
|
|
27
|
+
target: /app/web
|
|
28
|
+
- action: rebuild
|
|
29
|
+
path: package.json
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**DevContainers**:
|
|
33
|
+
- **Why**: "It works on my machine" is solved forever. The IDE definitions *are* the environment.
|
|
34
|
+
- **Pro Tip**: Include your linters and extensions in `devcontainer.json`.
|
|
35
|
+
|
|
36
|
+
## 3. Remote Development (Hybrid Inner Loop)
|
|
37
|
+
|
|
38
|
+
**When Localhost Fails**:
|
|
39
|
+
- Your app needs 32GB RAM but your laptop has 16GB.
|
|
40
|
+
- You need to talk to 15 downstream microservices.
|
|
41
|
+
- You need proprietary cloud hardware (GPUs).
|
|
42
|
+
|
|
43
|
+
**Telepresence**:
|
|
44
|
+
- Routes traffic from the cluster *to your laptop*.
|
|
45
|
+
- Allows you to debug a service locally while it thinks it's in the cluster.
|
|
46
|
+
- **Command**: `telepresence intercept my-service --port 8080:8080`
|
|
47
|
+
|
|
48
|
+
## 4. Outer Loop (Deployment)
|
|
49
|
+
|
|
50
|
+
This is the CI/CD world.
|
|
51
|
+
|
|
52
|
+
**Shift Left with Previews**:
|
|
53
|
+
- **Vercel/Railway**: Every Pull Request gets a live URL (`pr-123.myapp.com`).
|
|
54
|
+
- **Value**: QA and Product can test *before* merge.
|
|
55
|
+
|
|
56
|
+
**Infrastructure as Code**:
|
|
57
|
+
- Never change settings in the AWS Console manually.
|
|
58
|
+
- Use **SST** or **Terraform** so your infrastructure is versioned with your code.
|
|
59
|
+
|
|
60
|
+
## 5. Recommendation Matrix
|
|
61
|
+
|
|
62
|
+
| Scenario | Recommend |
|
|
63
|
+
|---|---|
|
|
64
|
+
| **New Project / MVP** | **Local Native** (Speed is king) |
|
|
65
|
+
| **Team > 5 Devs** | **DevContainers** (Consistency is king) |
|
|
66
|
+
| **Microservices > 10** | **Remote Bridge** (Resources are bottleneck) |
|
|
67
|
+
| **AI / Machine Learning**| **Remote Native** (Need GPUs) |
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Developer Workflow & Documentation
|
|
2
|
+
|
|
3
|
+
> **Source Origin**: Distilled from Matteo Collina's workflow skills (`octocat`, `documentation`, `snipgrapher`).
|
|
4
|
+
|
|
5
|
+
This guide standardizes how GABBE agents execute Git operations and format project documentation.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Documentation Framework (Diátaxis)
|
|
10
|
+
|
|
11
|
+
When researching, authoring, or rewriting documentation, strictly adhere to the **Diátaxis** framework, which divides technical documentation into four distinct quadrants. Never mix these concerns in the same file without clear separation.
|
|
12
|
+
|
|
13
|
+
1. **Tutorials** (Learning-oriented):
|
|
14
|
+
- *Goal*: Allow the newcomer to achieve a basic outcome.
|
|
15
|
+
- *Style*: Step-by-step, pedagogical, conversational. Do not explain *why*, just show *how*.
|
|
16
|
+
2. **How-To Guides** (Problem-oriented):
|
|
17
|
+
- *Goal*: Help the user solve a specific real-world problem.
|
|
18
|
+
- *Style*: Recipe-like, practical, focused. Assume the user already knows the basics.
|
|
19
|
+
3. **Reference** (Information-oriented):
|
|
20
|
+
- *Goal*: Accurately describe the machinery (API specs, configs, CLI flags).
|
|
21
|
+
- *Style*: Austere, complete, structured. No explanations or tutorials—just facts.
|
|
22
|
+
4. **Explanation** (Understanding-oriented):
|
|
23
|
+
- *Goal*: Clarify architecture, design decisions, and underlying concepts.
|
|
24
|
+
- *Style*: Discursive, theoretical, big-picture. (e.g., "Why we chose Fastify over Express").
|
|
25
|
+
|
|
26
|
+
## 2. Advanced Git & GitHub Operations (Octocat)
|
|
27
|
+
|
|
28
|
+
Agents performing version control must operate as Git/GitHub wizards using both local git and the `gh` CLI.
|
|
29
|
+
|
|
30
|
+
- **Commit Hygiene**: Use Conventional Commits (`feat(scope): message`, `fix(api): message`). Each commit must represent a single logical unit.
|
|
31
|
+
- **Branching Strategy**: Use short-lived feature branches (`feat/name`, `fix/name`, `docs/name`). Never commit directly to `main` without merging via PR.
|
|
32
|
+
- **Rebasing over Merging**: Keep linear histories. Prefer `git pull --rebase` and interactive rebasing to squash fixup commits before opening a PR.
|
|
33
|
+
- **GitHub CLI**: Leverage `gh` for PR creation (`gh pr create`), status checks (`gh pr checks`), and issue tracking (`gh issue list`).
|
|
34
|
+
|
|
35
|
+
## 3. Visual Aids & Snippets (Snipgrapher)
|
|
36
|
+
|
|
37
|
+
When preparing documentation intended for presentation or social reading (like blog posts or internal showcase PRs):
|
|
38
|
+
- Use polished code snippet graphics (like those generated by `snipgrapher`).
|
|
39
|
+
- Ensure syntax highlighting perfectly matches the provided code.
|
|
40
|
+
- Maintain visual contrast and accessibility.
|
|
41
|
+
- Keep the code snippet concise and focused strictly on the subject matter being highlighted.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
*For AI Agents: Ensure all documentation updates generated explicitly identify which Diátaxis quadrant they belong to. All git operations must comply with the Octocat standards prior to SDLC S08 (Review).*
|
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
# GABBE CLI Workflows Reference (Optional)
|
|
2
|
+
|
|
3
|
+
> **For Agents**: This guide documents the optional `gabbe` CLI commands, platform controls, and recommended workflows. **The CLI is NOT required** — agents can fully operate via markdown inference without it.
|
|
4
|
+
|
|
5
|
+
## Integration Modes
|
|
6
|
+
|
|
7
|
+
The GABBE CLI can run in three modes, configured during `python3 scripts/init.py`:
|
|
8
|
+
|
|
9
|
+
| Mode | Who Uses It | How |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| **Disabled** (default) | Nobody | CLI not installed. Agents use markdown inference only. |
|
|
12
|
+
| **Manual** | Human only | Human runs `gabbe` commands directly when needed. Agents are NOT required to use them but may reference them. |
|
|
13
|
+
| **MCP Enforced** | Agent via MCP | All `gabbe` commands flow through `gabbe serve-mcp`. Agents MUST use the MCP JSON-RPC `tools/call` interface. Direct CLI calls are not used by agents. |
|
|
14
|
+
|
|
15
|
+
> [!NOTE]
|
|
16
|
+
> When **Disabled**, the GABBE CLI Workflows section is removed from `AGENTS.md` during project initialization. Agents will not see CLI commands and operate purely via the markdown-based skill/guide system.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Quick Reference: All CLI Commands
|
|
21
|
+
|
|
22
|
+
| Command | Purpose | Requires API Key |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `gabbe init` | Initialize DB (`project/state.db`) | No |
|
|
25
|
+
| `gabbe db --init` | Alias for `gabbe init` | No |
|
|
26
|
+
| `gabbe sync` | Bidirectional sync: `project/TASKS.md` ↔ SQLite | No |
|
|
27
|
+
| `gabbe status` | Project dashboard (phase, tasks, progress) | No |
|
|
28
|
+
| `gabbe verify` | Integrity checks (files, lint, tests, security) | No |
|
|
29
|
+
| `gabbe route "<prompt>"` | Route prompt to LOCAL or REMOTE LLM | No |
|
|
30
|
+
| `gabbe brain activate` | Active Inference Loop (observe → decide → act) | **Yes** |
|
|
31
|
+
| `gabbe brain evolve --skill <name>` | Evolutionary Prompt Optimization | **Yes** |
|
|
32
|
+
| `gabbe brain heal` | Self-Healing Watchdog | No |
|
|
33
|
+
| `gabbe forecast` | Strategic cost/token forecast | No |
|
|
34
|
+
| `gabbe serve-mcp` | Zero-dependency MCP JSON-RPC server | No |
|
|
35
|
+
| `gabbe runs [--status S] [--limit N]` | List recent agent runs | No |
|
|
36
|
+
| `gabbe audit <run-id> [--format json]` | Structured audit trace for a run | No |
|
|
37
|
+
| `gabbe replay <run-id> [--from-step N]` | Deterministic replay from checkpoints | No |
|
|
38
|
+
| `gabbe resume <run-id>` | Resume a paused/escalated run | No |
|
|
39
|
+
|
|
40
|
+
### Global Flags
|
|
41
|
+
- `--version` — Print version and exit
|
|
42
|
+
- `--debug` — Enable DEBUG logging and full stack traces
|
|
43
|
+
- `--help` / `-h` — Help for any command
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Standard Workflows
|
|
48
|
+
|
|
49
|
+
### 1. Project Setup (First Time)
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Step 1: Generate context configs (interactive wizard)
|
|
53
|
+
python3 scripts/init.py
|
|
54
|
+
|
|
55
|
+
# Step 2: Initialize the database
|
|
56
|
+
gabbe init
|
|
57
|
+
|
|
58
|
+
# Step 3: Verify everything is set up
|
|
59
|
+
gabbe verify
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**What happens**: Creates `project/state.db` with all required tables (`tasks`, `runs`, `audit_spans`, `checkpoints`, `pending_escalations`, `genes`, `forecast_snapshots`, `pricing_registry`, `budget_snapshots`).
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
### 2. Daily Development Workflow
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# Check project status
|
|
70
|
+
gabbe status
|
|
71
|
+
|
|
72
|
+
# Sync tasks (after manual TASKS.md edits)
|
|
73
|
+
gabbe sync
|
|
74
|
+
|
|
75
|
+
# Run integrity checks
|
|
76
|
+
gabbe verify
|
|
77
|
+
|
|
78
|
+
# Route a prompt through the cost-effective router
|
|
79
|
+
gabbe route "Fix the typo in utils.py"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Sync behaviour**:
|
|
83
|
+
- File newer → imports tasks from `project/TASKS.md` into DB
|
|
84
|
+
- DB newer → exports tasks from DB to `project/TASKS.md`
|
|
85
|
+
- Uses `<!-- GABBE:TASKS:START -->` / `<!-- GABBE:TASKS:END -->` markers
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
### 3. Brain Mode Workflow (Requires `GABBE_API_KEY`)
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# Activate the Active Inference Loop
|
|
93
|
+
gabbe brain activate
|
|
94
|
+
|
|
95
|
+
# Optimize a skill's prompt via EPO
|
|
96
|
+
gabbe brain evolve --skill tdd-cycle
|
|
97
|
+
|
|
98
|
+
# Run self-healing checks (no API key needed)
|
|
99
|
+
gabbe brain heal
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**Brain activate flow**: Observe tasks → Send state to LLM → Receive recommended action → Record run in `runs` table → Record audit spans.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
### 4. Observability & Debugging Workflow
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
# See cost/token forecast
|
|
110
|
+
gabbe forecast
|
|
111
|
+
|
|
112
|
+
# List recent runs
|
|
113
|
+
gabbe runs
|
|
114
|
+
gabbe runs --status completed
|
|
115
|
+
gabbe runs --status error --limit 5
|
|
116
|
+
|
|
117
|
+
# Inspect a specific run
|
|
118
|
+
gabbe audit <run-id>
|
|
119
|
+
gabbe audit <run-id> --format json
|
|
120
|
+
|
|
121
|
+
# Replay a past run from checkpoints
|
|
122
|
+
gabbe replay <run-id>
|
|
123
|
+
gabbe replay <run-id> --from-step 3
|
|
124
|
+
|
|
125
|
+
# Resume a paused run
|
|
126
|
+
gabbe resume <run-id>
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
### 5. MCP Server Workflow
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
# Start the MCP JSON-RPC server (stdin/stdout)
|
|
135
|
+
gabbe serve-mcp
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**Protocol**: JSON-RPC 2.0 over stdin/stdout. Methods: `initialize`, `tools/list`, `tools/call`.
|
|
139
|
+
|
|
140
|
+
**Security controls**:
|
|
141
|
+
- `GABBE_MCP_TOKEN` — If set, clients must send this in `initialize` params
|
|
142
|
+
- `GABBE_MCP_ALLOWED_COMMANDS` — Comma-separated allowlist (e.g., `pytest,ruff,bandit`)
|
|
143
|
+
- All commands run with `shell=False` (no injection)
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Platform Controls (Active During All Runs)
|
|
148
|
+
|
|
149
|
+
Every `gabbe brain activate` and `gabbe serve-mcp` session wraps execution in a `RunContext` with the following controls:
|
|
150
|
+
|
|
151
|
+
### Budget Enforcement
|
|
152
|
+
| Dimension | Env Var | Default |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| Tokens | `GABBE_MAX_TOKENS_PER_RUN` | 100,000 |
|
|
155
|
+
| Tool calls | `GABBE_MAX_TOOL_CALLS_PER_RUN` | 50 |
|
|
156
|
+
| Iterations | `GABBE_MAX_ITERATIONS` | 25 |
|
|
157
|
+
| Wall time | `GABBE_MAX_WALL_TIME` | 300s |
|
|
158
|
+
| Cost (USD) | `GABBE_MAX_COST_USD` | $5.00 |
|
|
159
|
+
|
|
160
|
+
### Hard Stops
|
|
161
|
+
Absolute guards that **cannot** be loosened at runtime. Raises `MaxIterationsExceeded`, `MaxDepthExceeded`, or `TimeoutExceeded`.
|
|
162
|
+
|
|
163
|
+
### Policy Engine (`project/policies.yml`)
|
|
164
|
+
```yaml
|
|
165
|
+
version: "1"
|
|
166
|
+
tools:
|
|
167
|
+
allowed: ["call_llm", "run_command"]
|
|
168
|
+
denied: ["run_security_scan"]
|
|
169
|
+
roles:
|
|
170
|
+
brain-mode: ["call_llm"]
|
|
171
|
+
external_agent: ["run_command"]
|
|
172
|
+
content_safety:
|
|
173
|
+
enabled: true
|
|
174
|
+
```
|
|
175
|
+
- **Deny-first**: First policy that denies wins
|
|
176
|
+
- **Secure default**: No policy file → deny-all
|
|
177
|
+
|
|
178
|
+
### Tool Gateway
|
|
179
|
+
All tool execution flows through `ToolGateway.execute()`:
|
|
180
|
+
1. Tool registration check → 2. Policy evaluation → 3. Budget check → 4. Rate limiting → 5. Circuit breaker → 6. Schema validation → 7. Handler execution → 8. Audit span
|
|
181
|
+
|
|
182
|
+
### Escalation Handler
|
|
183
|
+
|
|
184
|
+
| Mode | Env `GABBE_ESCALATION_MODE` | Behaviour |
|
|
185
|
+
|---|---|---|
|
|
186
|
+
| `cli` | Interactive prompt (approve/reject/edit) | Continues after response |
|
|
187
|
+
| `file` | Records to DB, raises `EscalationPaused` | Resume with `gabbe resume` |
|
|
188
|
+
| `silent` | Auto-rejects | Safe for CI/CD |
|
|
189
|
+
|
|
190
|
+
**Triggers**: `BUDGET_EXHAUSTED`, `REPEATED_TOOL_FAILURE`, `AMBIGUOUS_DECISION`, `POLICY_VIOLATION`, `MAX_ITERATIONS`
|
|
191
|
+
|
|
192
|
+
### Audit Trail
|
|
193
|
+
Every event recorded as spans in `audit_spans` table. Inspect with `gabbe audit <run-id>`.
|
|
194
|
+
|
|
195
|
+
### Checkpoints & Replay
|
|
196
|
+
State snapshots saved to `checkpoints` table. Replay with `gabbe replay <run-id>`.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## Environment Variables (Complete)
|
|
201
|
+
|
|
202
|
+
| Variable | Default | Purpose |
|
|
203
|
+
|---|---|---|
|
|
204
|
+
| `GABBE_API_URL` | `https://api.openai.com/v1/...` | LLM endpoint |
|
|
205
|
+
| `GABBE_API_KEY` | *(required for LLM)* | Bearer token |
|
|
206
|
+
| `GABBE_API_MODEL` | `gpt-4o` | Model name |
|
|
207
|
+
| `GABBE_LLM_TEMPERATURE` | `0.7` | Sampling temperature |
|
|
208
|
+
| `GABBE_LLM_TIMEOUT` | `30` | HTTP timeout (seconds) |
|
|
209
|
+
| `GABBE_LLM_MAX_RETRIES` | `3` | LLM retry attempts |
|
|
210
|
+
| `GABBE_ROUTE_THRESHOLD` | `50` | Complexity → LOCAL/REMOTE |
|
|
211
|
+
| `GABBE_LOG_LEVEL` | `INFO` | Logging level |
|
|
212
|
+
| `GABBE_MAX_COST_USD` | `5.0` | Cost budget per run |
|
|
213
|
+
| `GABBE_MAX_TOKENS_PER_RUN` | `100000` | Token limit per run |
|
|
214
|
+
| `GABBE_MAX_TOOL_CALLS_PER_RUN` | `50` | Tool calls per run |
|
|
215
|
+
| `GABBE_MAX_ITERATIONS` | `25` | Brain loop iterations |
|
|
216
|
+
| `GABBE_MAX_WALL_TIME` | `300` | Wall time (seconds) |
|
|
217
|
+
| `GABBE_MAX_RECURSION_DEPTH` | `5` | Recursion depth |
|
|
218
|
+
| `GABBE_POLICY_FILE` | `project/policies.yml` | Policy YAML path |
|
|
219
|
+
| `GABBE_ESCALATION_MODE` | `cli` | `cli` / `file` / `silent` |
|
|
220
|
+
| `GABBE_OTEL_ENABLED` | `false` | OpenTelemetry |
|
|
221
|
+
| `GABBE_SUBPROCESS_TIMEOUT` | `300` | Verify command timeout |
|
|
222
|
+
| `GABBE_MCP_TOKEN` | *(unset)* | MCP auth token |
|
|
223
|
+
| `GABBE_MCP_ALLOWED_COMMANDS` | *(unset)* | MCP command allowlist |
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Database Tables (Schema v3)
|
|
228
|
+
|
|
229
|
+
| Table | Purpose |
|
|
230
|
+
|---|---|
|
|
231
|
+
| `tasks` | Task tracking (title, status, timestamps) |
|
|
232
|
+
| `runs` | One row per agent execution |
|
|
233
|
+
| `audit_spans` | Per-step spans with token/cost data |
|
|
234
|
+
| `budget_snapshots` | Periodic budget state per run |
|
|
235
|
+
| `checkpoints` | State snapshots for replay |
|
|
236
|
+
| `pending_escalations` | Human-review queue |
|
|
237
|
+
| `genes` | EPO evolutionary prompt storage |
|
|
238
|
+
| `forecast_snapshots` | Cost/token projections |
|
|
239
|
+
| `pricing_registry` | Per-model token pricing |
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## Agent Rules
|
|
244
|
+
|
|
245
|
+
1. **Always run `gabbe init` before any other command** in a new project.
|
|
246
|
+
2. **Run `gabbe sync` after editing `project/TASKS.md`** to keep DB in sync.
|
|
247
|
+
3. **Run `gabbe verify` before committing** to catch integrity issues.
|
|
248
|
+
4. **Use `gabbe route` before making LLM calls** to determine LOCAL vs REMOTE.
|
|
249
|
+
5. **Check `gabbe runs` and `gabbe audit`** after brain sessions for cost visibility.
|
|
250
|
+
6. **Respect budget limits** — all runs are bounded by token/cost/time limits.
|
|
251
|
+
7. **Handle escalations** — when `BUDGET_EXHAUSTED` or `POLICY_VIOLATION` occurs, the run pauses for human review.
|
|
252
|
+
8. **Use `gabbe forecast`** to project remaining work before starting large tasks.
|