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,292 @@
|
|
|
1
|
+
# Guide: Microservices & Distributed Systems
|
|
2
|
+
<!-- Bounded contexts, event-driven, contract testing, service mesh -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## When to Use Microservices
|
|
7
|
+
|
|
8
|
+
**Use microservices when:**
|
|
9
|
+
- Teams can own and deploy services independently
|
|
10
|
+
- Services have clearly different scaling needs
|
|
11
|
+
- Services have fundamentally different technology requirements
|
|
12
|
+
- Organization is large enough to support operational overhead
|
|
13
|
+
|
|
14
|
+
**Do NOT use microservices when:**
|
|
15
|
+
- Team < 10 engineers (start with modular monolith)
|
|
16
|
+
- Domain is not well understood yet (boundaries will be wrong)
|
|
17
|
+
- Operational maturity is not there (monitoring, tracing, CI/CD)
|
|
18
|
+
|
|
19
|
+
**Start with a modular monolith. Extract services when boundaries are proven.**
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Service Decomposition — DDD Bounded Contexts
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
Decompose by business capability, not technical layer:
|
|
27
|
+
|
|
28
|
+
Good decomposition:
|
|
29
|
+
user-service → Registration, authentication, profile management
|
|
30
|
+
order-service → Order lifecycle, items, pricing
|
|
31
|
+
payment-service → Payment processing, refunds, invoicing
|
|
32
|
+
notification-service → Emails, SMS, push notifications
|
|
33
|
+
inventory-service → Stock management, reservations
|
|
34
|
+
|
|
35
|
+
Bad decomposition (technical layers):
|
|
36
|
+
database-service → No! Databases are infrastructure
|
|
37
|
+
api-gateway-service → No! API gateway is infrastructure
|
|
38
|
+
validation-service → No! Validation belongs in each service
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Service Boundaries Checklist
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
A good service boundary:
|
|
45
|
+
[ ] Owns its own data (no shared database between services)
|
|
46
|
+
[ ] Can be deployed independently (no coordinated releases required)
|
|
47
|
+
[ ] Has a clear single business capability
|
|
48
|
+
[ ] Changes don't require simultaneous changes in other services
|
|
49
|
+
[ ] Could use a different technology if needed
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Inter-Service Communication
|
|
55
|
+
|
|
56
|
+
### Synchronous (HTTP/gRPC) — for queries and commands needing immediate response
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
// HTTP REST: use for simple CRUD, external-facing APIs
|
|
60
|
+
// Response within: < 500ms (otherwise consider async)
|
|
61
|
+
|
|
62
|
+
// gRPC: use for internal service communication needing strong typing
|
|
63
|
+
// Better for: high-throughput, low-latency, streaming scenarios
|
|
64
|
+
// Use: Protocol Buffers (.proto) for schema definition
|
|
65
|
+
|
|
66
|
+
// Circuit Breaker pattern (prevent cascade failures)
|
|
67
|
+
const circuitBreaker = new CircuitBreaker(callUserService, {
|
|
68
|
+
timeout: 3000, // 3 second timeout
|
|
69
|
+
errorThresholdPercentage: 50, // Open after 50% failures
|
|
70
|
+
resetTimeout: 30000, // Try again after 30 seconds
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Asynchronous (Message Queues) — for events and commands not needing immediate response
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
// Event-driven: services react to events, no direct coupling
|
|
78
|
+
// Producer:
|
|
79
|
+
await eventBus.publish({
|
|
80
|
+
type: 'order.created',
|
|
81
|
+
payload: { orderId, userId, total },
|
|
82
|
+
occurredAt: new Date().toISOString(),
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
// Consumer (in notification-service):
|
|
86
|
+
eventBus.subscribe('order.created', async (event) => {
|
|
87
|
+
await sendOrderConfirmationEmail(event.payload.userId);
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
// Message queues: RabbitMQ, Apache Kafka, AWS SQS, Azure Service Bus
|
|
91
|
+
// Choose based on: throughput, ordering guarantees, replay needs
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Outbox Pattern (ensure at-least-once delivery)
|
|
95
|
+
|
|
96
|
+
```sql
|
|
97
|
+
-- Save event to outbox table in same DB transaction as business operation
|
|
98
|
+
BEGIN;
|
|
99
|
+
INSERT INTO orders (id, user_id, total) VALUES ($1, $2, $3);
|
|
100
|
+
INSERT INTO outbox_events (type, payload) VALUES ('order.created', $4);
|
|
101
|
+
COMMIT;
|
|
102
|
+
-- Separate process reads outbox and publishes to message broker
|
|
103
|
+
-- Delete from outbox only after confirmed published
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## AGENTS.md for Monorepos with Multiple Services
|
|
109
|
+
|
|
110
|
+
```yaml
|
|
111
|
+
# Root AGENTS.md (global rules)
|
|
112
|
+
project_name: "MyPlatform Monorepo"
|
|
113
|
+
structure: "Multi-service monorepo"
|
|
114
|
+
|
|
115
|
+
# Service-specific AGENTS.md files override root:
|
|
116
|
+
# services/user-service/AGENTS.md
|
|
117
|
+
# services/order-service/AGENTS.md
|
|
118
|
+
|
|
119
|
+
global_rules:
|
|
120
|
+
- "All inter-service HTTP calls must go through the service's client module"
|
|
121
|
+
- "No service may directly query another service's database"
|
|
122
|
+
- "All API contracts defined in services/[name]/openapi.yaml"
|
|
123
|
+
- "All services must expose GET /health returning 200 OK"
|
|
124
|
+
- "All services must emit structured logs in JSON format"
|
|
125
|
+
|
|
126
|
+
global_commands:
|
|
127
|
+
test_all: "pnpm turbo run test"
|
|
128
|
+
build_all: "pnpm turbo run build"
|
|
129
|
+
lint_all: "pnpm turbo run lint"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Contract Testing with Pact
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
// Consumer-driven contract testing — consumer defines expectations
|
|
138
|
+
// Provider verifies it meets all consumer contracts
|
|
139
|
+
|
|
140
|
+
// Consumer (order-service) defines contract:
|
|
141
|
+
// pact.spec.ts in order-service
|
|
142
|
+
const provider = new PactV3({
|
|
143
|
+
consumer: 'order-service',
|
|
144
|
+
provider: 'user-service',
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
await provider.addInteraction({
|
|
148
|
+
uponReceiving: 'a request for user profile',
|
|
149
|
+
withRequest: {
|
|
150
|
+
method: 'GET',
|
|
151
|
+
path: '/api/v1/users/123',
|
|
152
|
+
headers: { Authorization: like('Bearer token') },
|
|
153
|
+
},
|
|
154
|
+
willRespondWith: {
|
|
155
|
+
status: 200,
|
|
156
|
+
body: { id: '123', email: like('user@example.com'), name: like('Alice') },
|
|
157
|
+
},
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
// Provider (user-service) verifies it satisfies all consumer contracts:
|
|
161
|
+
// In CI: pact-broker publish → user-service CI fetches and verifies contracts
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Distributed Tracing
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
// Use OpenTelemetry — standard across all services
|
|
170
|
+
import { trace, context, propagation } from '@opentelemetry/api';
|
|
171
|
+
|
|
172
|
+
// In API gateway / first service — create root trace
|
|
173
|
+
const tracer = trace.getTracer('order-service');
|
|
174
|
+
const span = tracer.startSpan('createOrder');
|
|
175
|
+
|
|
176
|
+
// Propagate trace context to downstream services
|
|
177
|
+
const carrier = {};
|
|
178
|
+
propagation.inject(context.active(), carrier);
|
|
179
|
+
// Add carrier headers to HTTP request to next service
|
|
180
|
+
|
|
181
|
+
// In downstream service — extract and continue trace
|
|
182
|
+
const ctx = propagation.extract(context.active(), incomingHeaders);
|
|
183
|
+
const childSpan = tracer.startSpan('validatePayment', {}, ctx);
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**Tools:** Jaeger, Zipkin, AWS X-Ray, Datadog APM, Grafana Tempo
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Event Sourcing & CQRS
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
// Event Sourcing: store events, derive state
|
|
194
|
+
// CQRS: separate read model from write model
|
|
195
|
+
|
|
196
|
+
// Write side: append events
|
|
197
|
+
interface OrderEvent {
|
|
198
|
+
type: 'ORDER_CREATED' | 'ORDER_ITEM_ADDED' | 'ORDER_PAID' | 'ORDER_CANCELLED';
|
|
199
|
+
aggregateId: string;
|
|
200
|
+
sequenceNumber: number;
|
|
201
|
+
occurredAt: Date;
|
|
202
|
+
payload: unknown;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// Append to event store (never update/delete)
|
|
206
|
+
await eventStore.append(orderId, [
|
|
207
|
+
{ type: 'ORDER_CREATED', payload: { userId, items } }
|
|
208
|
+
]);
|
|
209
|
+
|
|
210
|
+
// Read side: project events into read model (denormalized for fast reads)
|
|
211
|
+
// Rebuilt from events at any point in time — enables time travel debugging
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**When to use:** Financial systems, audit-required systems, complex undo/redo
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Service Mesh Patterns
|
|
219
|
+
|
|
220
|
+
```yaml
|
|
221
|
+
# Kubernetes + Istio/Linkerd for:
|
|
222
|
+
# - mTLS between all services (zero-trust networking)
|
|
223
|
+
# - Load balancing and circuit breaking at infrastructure level
|
|
224
|
+
# - Traffic splitting for canary deployments
|
|
225
|
+
|
|
226
|
+
# Example: Canary deployment via Istio VirtualService
|
|
227
|
+
apiVersion: networking.istio.io/v1alpha3
|
|
228
|
+
kind: VirtualService
|
|
229
|
+
metadata:
|
|
230
|
+
name: user-service
|
|
231
|
+
spec:
|
|
232
|
+
http:
|
|
233
|
+
- route:
|
|
234
|
+
- destination:
|
|
235
|
+
host: user-service
|
|
236
|
+
subset: stable
|
|
237
|
+
weight: 90
|
|
238
|
+
- destination:
|
|
239
|
+
host: user-service
|
|
240
|
+
subset: canary
|
|
241
|
+
weight: 10 # 10% to new version
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Testing Strategy for Microservices
|
|
247
|
+
|
|
248
|
+
| Test Type | Scope | Tools | When |
|
|
249
|
+
|---|---|---|---|
|
|
250
|
+
| Unit | Single function/class | Vitest, Jest, Pest | Every commit |
|
|
251
|
+
| Integration | Single service + DB | Testcontainers, Docker Compose | Every commit |
|
|
252
|
+
| Contract | Consumer/Provider contracts | Pact | Every commit to shared APIs |
|
|
253
|
+
| E2E | Full user flow across services | Playwright + real stack | Before release |
|
|
254
|
+
| Chaos | Resilience to failures | Chaos Monkey, Gremlin | Scheduled |
|
|
255
|
+
| Load | Performance under load | k6, Gatling | Pre-release |
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## API Gateway Pattern
|
|
260
|
+
|
|
261
|
+
```
|
|
262
|
+
External clients → API Gateway → Services
|
|
263
|
+
|
|
264
|
+
API Gateway responsibilities:
|
|
265
|
+
- Authentication (validate JWT, session)
|
|
266
|
+
- Rate limiting (per client, per IP)
|
|
267
|
+
- Request routing (path-based, header-based)
|
|
268
|
+
- SSL termination
|
|
269
|
+
- Request/response transformation (if needed)
|
|
270
|
+
- CORS headers
|
|
271
|
+
- Logging / tracing injection
|
|
272
|
+
|
|
273
|
+
API Gateway does NOT:
|
|
274
|
+
- Business logic
|
|
275
|
+
- Database queries
|
|
276
|
+
- Service orchestration (use saga pattern in service layer)
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## Key Patterns Summary
|
|
282
|
+
|
|
283
|
+
| Pattern | Problem Solved | When to Use |
|
|
284
|
+
|---|---|---|
|
|
285
|
+
| API Gateway | External routing, auth, rate limiting | Always |
|
|
286
|
+
| Circuit Breaker | Cascade failures | Synchronous calls between services |
|
|
287
|
+
| Outbox | At-least-once event delivery | Critical events (payments, orders) |
|
|
288
|
+
| Saga | Distributed transactions | Multi-service operations |
|
|
289
|
+
| CQRS | Read/write model separation | High-read systems |
|
|
290
|
+
| Event Sourcing | Complete audit trail, time travel | Financial, regulated systems |
|
|
291
|
+
| Strangler Fig | Incremental migration from monolith | Legacy modernization |
|
|
292
|
+
| BFF | Per-client API tailoring | Mobile + Web with different needs |
|
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
# Guide: Monolith & Modular Monolith
|
|
2
|
+
<!-- Vertical slice architecture, module boundaries, Strangler Fig migration -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Monolith vs Modular Monolith vs Microservices
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
Traditional Monolith:
|
|
10
|
+
One codebase, tightly coupled, no module boundaries
|
|
11
|
+
Fast to start, impossible to scale teams beyond ~5 engineers
|
|
12
|
+
Avoid for new projects unless extremely time-constrained
|
|
13
|
+
|
|
14
|
+
Modular Monolith (recommended starting point):
|
|
15
|
+
One codebase, modules with enforced boundaries
|
|
16
|
+
Modules can be extracted to services when needed (Strangler Fig)
|
|
17
|
+
Best for: < 50 engineers, domain not fully understood yet
|
|
18
|
+
|
|
19
|
+
Microservices:
|
|
20
|
+
Multiple codebases, independent deployments
|
|
21
|
+
Best for: > 50 engineers, proven domain boundaries, strong DevOps
|
|
22
|
+
See: guides/architecture/microservices.md
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**Start with modular monolith. Extract microservices only when boundaries are proven and scale demands it.**
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Modular Monolith — Vertical Slice Architecture
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
src/
|
|
33
|
+
modules/ # Each module = bounded context
|
|
34
|
+
users/
|
|
35
|
+
domain/ # Pure business logic
|
|
36
|
+
user.entity.ts
|
|
37
|
+
user.repository.ts # Interface
|
|
38
|
+
application/
|
|
39
|
+
create-user.use-case.ts
|
|
40
|
+
get-user.use-case.ts
|
|
41
|
+
infrastructure/
|
|
42
|
+
prisma-user.repository.ts
|
|
43
|
+
http/
|
|
44
|
+
users.controller.ts
|
|
45
|
+
users.routes.ts
|
|
46
|
+
index.ts # Public API: what this module exports
|
|
47
|
+
# Everything else is private to this module
|
|
48
|
+
|
|
49
|
+
orders/
|
|
50
|
+
domain/
|
|
51
|
+
order.entity.ts
|
|
52
|
+
order-item.entity.ts
|
|
53
|
+
application/
|
|
54
|
+
create-order.use-case.ts
|
|
55
|
+
infrastructure/
|
|
56
|
+
prisma-order.repository.ts
|
|
57
|
+
http/
|
|
58
|
+
orders.controller.ts
|
|
59
|
+
index.ts
|
|
60
|
+
|
|
61
|
+
payments/
|
|
62
|
+
domain/
|
|
63
|
+
application/
|
|
64
|
+
infrastructure/
|
|
65
|
+
index.ts
|
|
66
|
+
|
|
67
|
+
shared/ # ONLY for truly shared utilities
|
|
68
|
+
domain/
|
|
69
|
+
value-objects/ # Money.ts, Address.ts (used by multiple modules)
|
|
70
|
+
infrastructure/
|
|
71
|
+
database/ # Prisma client singleton
|
|
72
|
+
cache/ # Redis client
|
|
73
|
+
lib/
|
|
74
|
+
result.ts # Result<T, E> type
|
|
75
|
+
logger.ts # Logger configuration
|
|
76
|
+
|
|
77
|
+
main/ # Bootstrap — wires modules together
|
|
78
|
+
server.ts
|
|
79
|
+
container.ts
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Module Boundary Rules
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
// RULE: Modules communicate ONLY through their public API (index.ts)
|
|
88
|
+
// Internal types are module-private — not imported directly
|
|
89
|
+
|
|
90
|
+
// users/index.ts — public API
|
|
91
|
+
export type { UserId, UserDto } from './domain/user.entity';
|
|
92
|
+
export { CreateUserUseCase } from './application/create-user.use-case';
|
|
93
|
+
export type { IUserRepository } from './domain/user.repository';
|
|
94
|
+
|
|
95
|
+
// orders module can use users public API:
|
|
96
|
+
import type { UserId } from '@/modules/users'; // CORRECT — through public API
|
|
97
|
+
|
|
98
|
+
// orders module CANNOT:
|
|
99
|
+
import { User } from '@/modules/users/domain/user.entity'; // WRONG — internal type
|
|
100
|
+
import { PrismaUserRepository } from '@/modules/users/infrastructure/...'; // WRONG
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Enforce with dependency-cruiser
|
|
104
|
+
|
|
105
|
+
```javascript
|
|
106
|
+
// .dependency-cruiser.cjs
|
|
107
|
+
module.exports = {
|
|
108
|
+
forbidden: [
|
|
109
|
+
{
|
|
110
|
+
name: 'no-cross-module-internal-access',
|
|
111
|
+
severity: 'error',
|
|
112
|
+
from: { path: '^src/modules/([^/]+)' },
|
|
113
|
+
to: {
|
|
114
|
+
path: '^src/modules/([^/]+)/(domain|application|infrastructure)',
|
|
115
|
+
// Allow if module names match (accessing own internals)
|
|
116
|
+
pathNot: '^src/modules/$1'
|
|
117
|
+
}
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
name: 'no-cross-module-imports',
|
|
121
|
+
severity: 'error',
|
|
122
|
+
from: { path: '^src/modules/([^/]+)' },
|
|
123
|
+
to: { path: '^src/modules/([^/]+)' },
|
|
124
|
+
// Must go through the public index, not internal paths
|
|
125
|
+
}
|
|
126
|
+
]
|
|
127
|
+
};
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Module Communication Patterns
|
|
133
|
+
|
|
134
|
+
### Direct (In-Process)
|
|
135
|
+
```typescript
|
|
136
|
+
// Same process — inject use case across modules
|
|
137
|
+
// Orders module depends on Users module public API
|
|
138
|
+
|
|
139
|
+
class CreateOrderUseCase {
|
|
140
|
+
constructor(
|
|
141
|
+
private readonly orderRepo: IOrderRepository,
|
|
142
|
+
private readonly getUser: GetUserUseCase, // From users module
|
|
143
|
+
) {}
|
|
144
|
+
|
|
145
|
+
async execute(command: CreateOrderCommand) {
|
|
146
|
+
const user = await this.getUser.execute({ id: command.userId });
|
|
147
|
+
if (!user) throw new UserNotFoundError(command.userId);
|
|
148
|
+
// ... create order
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Event-Driven (In-Process Event Bus)
|
|
154
|
+
```typescript
|
|
155
|
+
// Loose coupling within the monolith — modules don't know about each other
|
|
156
|
+
// Best for: side effects (notifications, analytics, audit log)
|
|
157
|
+
|
|
158
|
+
// Orders module publishes
|
|
159
|
+
eventBus.publish(new OrderCreatedEvent(order.id, order.userId));
|
|
160
|
+
|
|
161
|
+
// Notifications module subscribes
|
|
162
|
+
eventBus.subscribe(OrderCreatedEvent, async (event) => {
|
|
163
|
+
await sendOrderConfirmationEmail(event.userId);
|
|
164
|
+
});
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Shared Database (with Module-Scoped Tables)
|
|
168
|
+
```sql
|
|
169
|
+
-- Even in a monolith, namespace tables by module:
|
|
170
|
+
users_accounts -- users module
|
|
171
|
+
users_sessions -- users module
|
|
172
|
+
orders_orders -- orders module
|
|
173
|
+
orders_items -- orders module
|
|
174
|
+
payments_invoices -- payments module
|
|
175
|
+
|
|
176
|
+
-- Module-scoped: orders module NEVER queries users_* tables directly
|
|
177
|
+
-- It uses the users module's public API (use case or repository interface)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Feature Flagging for Safe Rollout
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
// Use feature flags to deploy new code safely
|
|
186
|
+
// LaunchDarkly, Flipt, Growthbook, or simple env-var-based
|
|
187
|
+
|
|
188
|
+
async function getCheckoutPage(user: User): Promise<CheckoutPage> {
|
|
189
|
+
const isNewCheckoutEnabled = await featureFlags.isEnabled(
|
|
190
|
+
'new-checkout-flow',
|
|
191
|
+
{ userId: user.id, email: user.email }
|
|
192
|
+
);
|
|
193
|
+
|
|
194
|
+
if (isNewCheckoutEnabled) {
|
|
195
|
+
return newCheckoutService.render(user);
|
|
196
|
+
}
|
|
197
|
+
return legacyCheckoutService.render(user);
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
## Testing Strategy for Monolith
|
|
204
|
+
|
|
205
|
+
```
|
|
206
|
+
Unit tests (fast — no I/O):
|
|
207
|
+
Test domain entities and use cases in isolation
|
|
208
|
+
Mock repositories and external services
|
|
209
|
+
~300ms for full suite
|
|
210
|
+
|
|
211
|
+
Module integration tests:
|
|
212
|
+
Test each module against real database (test schema)
|
|
213
|
+
Use Testcontainers for ephemeral PostgreSQL
|
|
214
|
+
Test: full flow from HTTP request → database
|
|
215
|
+
|
|
216
|
+
Cross-module integration tests:
|
|
217
|
+
Test interactions between modules
|
|
218
|
+
Verify that module public APIs work as expected
|
|
219
|
+
Test event-driven side effects
|
|
220
|
+
|
|
221
|
+
E2E tests (slow — real browser):
|
|
222
|
+
Happy path user journeys
|
|
223
|
+
Critical business flows only
|
|
224
|
+
Run in CI before release
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## Strangler Fig Pattern — Extracting Services
|
|
230
|
+
|
|
231
|
+
When a module needs to become its own microservice:
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
Phase 1: Identify the extraction target
|
|
235
|
+
- Module with different scaling needs
|
|
236
|
+
- Module with its own team
|
|
237
|
+
- Module with proven boundaries
|
|
238
|
+
|
|
239
|
+
Phase 2: Add a facade
|
|
240
|
+
- Create an HTTP client interface in front of the module
|
|
241
|
+
- Other modules use the client (not internal module)
|
|
242
|
+
- Initially the client calls the local module (no network hop)
|
|
243
|
+
|
|
244
|
+
Phase 3: Extract to separate service
|
|
245
|
+
- Deploy the module as a separate service
|
|
246
|
+
- Update the client to make real HTTP calls
|
|
247
|
+
- Other modules require zero changes
|
|
248
|
+
|
|
249
|
+
Phase 4: Remove from monolith
|
|
250
|
+
- Once all traffic goes through the external service
|
|
251
|
+
- Delete the module from the monolith
|
|
252
|
+
|
|
253
|
+
Each phase: fully tested, independently deployable, zero downtime
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
```typescript
|
|
257
|
+
// Phase 2: Facade (local call, same process)
|
|
258
|
+
class UserServiceClient {
|
|
259
|
+
constructor(private readonly getUserUseCase: GetUserUseCase) {}
|
|
260
|
+
|
|
261
|
+
async getUser(id: string): Promise<UserDto | null> {
|
|
262
|
+
return this.getUserUseCase.execute({ id }); // Local call
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
// Phase 3: Facade updated (remote HTTP call, no changes to consumers)
|
|
267
|
+
class UserServiceClient {
|
|
268
|
+
async getUser(id: string): Promise<UserDto | null> {
|
|
269
|
+
const response = await fetch(`${USER_SERVICE_URL}/api/v1/users/${id}`);
|
|
270
|
+
if (response.status === 404) return null;
|
|
271
|
+
return response.json();
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Monolith Health Indicators
|
|
279
|
+
|
|
280
|
+
Track these metrics to know when to consider extraction:
|
|
281
|
+
|
|
282
|
+
```
|
|
283
|
+
Coupling metrics:
|
|
284
|
+
- Afferent coupling (Ca) per module — how many other modules depend on it
|
|
285
|
+
- Build time increasing despite unchanged code (coupling growing)
|
|
286
|
+
- Test suite > 10 minutes (usually coupling + lack of isolation)
|
|
287
|
+
|
|
288
|
+
Deployment metrics:
|
|
289
|
+
- Small changes require full regression test suite
|
|
290
|
+
- Two teams waiting on each other's deployments
|
|
291
|
+
- Rollback of one feature requires reverting unrelated code
|
|
292
|
+
|
|
293
|
+
Team metrics:
|
|
294
|
+
- > 5 engineers modifying same module regularly
|
|
295
|
+
- "Stepping on each other's toes" incidents
|
|
296
|
+
- Code reviews involving people outside the feature's team
|
|
297
|
+
|
|
298
|
+
Scale metrics:
|
|
299
|
+
- Can't scale one part without scaling everything
|
|
300
|
+
- One heavy process (video processing, ML inference) starving HTTP handlers
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
When you see 3+ of these: it's time to extract the most independent module.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Loki & Brain — Agentic Orchestration
|
|
2
|
+
|
|
3
|
+
This directory contains the **High-Level Orchestrators** for the Agentic Engineering Kit.
|
|
4
|
+
|
|
5
|
+
## Modes
|
|
6
|
+
|
|
7
|
+
### 1. 🧠 Brain Mode (`brain-mode.skill.md`)
|
|
8
|
+
> **The Strategist (System 2)**
|
|
9
|
+
|
|
10
|
+
- **Role**: Meta-Cognitive Orchestrator.
|
|
11
|
+
- **Function**: Plans, Routes, and Optimizes.
|
|
12
|
+
- **Logic**: Active Inference (Free Energy Principle).
|
|
13
|
+
- **Use Case**: Complex, ambiguous, or high-stakes projects.
|
|
14
|
+
- **Key Feature**: **Dynamic Cost Routing** (Local vs Remote).
|
|
15
|
+
|
|
16
|
+
**Trigger**: `brain activate`, `supermode`
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
### 2. ⚡ Loki Mode (`loki-mode.skill.md`)
|
|
21
|
+
> **The Executor (System 1)**
|
|
22
|
+
|
|
23
|
+
- **Role**: SDLC Orchestrator.
|
|
24
|
+
- **Function**: Executes the 10-Phase Engineering Lifecycle.
|
|
25
|
+
- **Logic**: Deterministic Workflow (S01 -> S10).
|
|
26
|
+
- **Use Case**: Building software with strict process requirements.
|
|
27
|
+
- **Key Feature**: **Human-in-the-Loop Gates**.
|
|
28
|
+
|
|
29
|
+
**Trigger**: `loki`, `orchestrate`
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## How they work together
|
|
34
|
+
|
|
35
|
+
Brain Mode **wraps** Loki Mode.
|
|
36
|
+
|
|
37
|
+
1. **Brain Mode** receives a request ("Build X").
|
|
38
|
+
2. It analyzes complexity and budget.
|
|
39
|
+
3. It spins up **Loki Mode** to handle the SDLC.
|
|
40
|
+
4. It monitors Loki's progress, intervening if:
|
|
41
|
+
- Costs spike.
|
|
42
|
+
- Errors loop.
|
|
43
|
+
- Requirements drift.
|
|
44
|
+
|
|
45
|
+
```mermaid
|
|
46
|
+
graph TD
|
|
47
|
+
User -->|Request| Brain[🧠 Brain Mode]
|
|
48
|
+
Brain -->|Route: Complex| Loki[⚡ Loki Exec Layer]
|
|
49
|
+
Brain -->|Route: Simple| Local[💻 Local Script]
|
|
50
|
+
Loki -->|Phase S01-S10| Artifacts[📂 Project Files]
|
|
51
|
+
Brain -.->|Monitor| Loki
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
[User] --(Request)--> [Brain Mode 🧠]
|
|
56
|
+
|
|
|
57
|
+
+--(Route: Complex)--> [Loki Exec Layer ⚡] --(Phase S01-S10)--> [Project Files 📂]
|
|
58
|
+
| ^
|
|
59
|
+
| | (Monitor)
|
|
60
|
+
| |
|
|
61
|
+
+--(Route: Simple)---- [Local Script 💻]
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## CLI Reference
|
|
67
|
+
|
|
68
|
+
In addition to Agent slash commands, you can orchestrate these modes via the GABBE CLI:
|
|
69
|
+
|
|
70
|
+
| Mode | CLI Command | Purpose |
|
|
71
|
+
|---|---|---|
|
|
72
|
+
| **Brain** | `gabbe brain` | Activates Active Inference and Cost Routing. |
|
|
73
|
+
| **Loki** | `gabbe status` | Visualizes swarm progress and SDLC phase. |
|
|
74
|
+
| **Sync** | `gabbe sync` | Ensures Markdown memory and SQLite stays in sync. |
|
|
75
|
+
| **Verify** | `gabbe verify` | Runs the automated gate checks for the current phase. |
|