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,241 @@
|
|
|
1
|
+
# Architecture Review Report — [System Name]
|
|
2
|
+
<!-- Created by: arch-review.skill -->
|
|
3
|
+
<!-- Methodology: ATAM-lite (Architecture Tradeoff Analysis Method, adapted for single-agent use) -->
|
|
4
|
+
<!-- Standard: ISO/IEC/IEEE 42010, SEI ATAM -->
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Meta
|
|
9
|
+
|
|
10
|
+
| Field | Value |
|
|
11
|
+
|---|---|
|
|
12
|
+
| **System** | [system name] |
|
|
13
|
+
| **Architecture version / commit** | [reference] |
|
|
14
|
+
| **Review date** | [YYYY-MM-DD] |
|
|
15
|
+
| **Reviewer** | [agent / human] |
|
|
16
|
+
| **Artifacts reviewed** | [list: architecture doc, codebase, ADRs, diagrams] |
|
|
17
|
+
| **Requirements reference** | [PRD.md, SPEC.md] |
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Executive Summary
|
|
22
|
+
|
|
23
|
+
**Architecture Fitness**: SOUND / AT RISK / INADEQUATE
|
|
24
|
+
|
|
25
|
+
[3-5 sentences: overall assessment, most important finding, immediate recommendation]
|
|
26
|
+
|
|
27
|
+
**Most critical issues**:
|
|
28
|
+
1. [Critical issue 1]
|
|
29
|
+
2. [Critical issue 2]
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Architecture as Found
|
|
34
|
+
|
|
35
|
+
> Reconstructed or verified architecture description — this is the ACTUAL architecture,
|
|
36
|
+
> not the intended one. Code is the source of truth if documentation conflicts.
|
|
37
|
+
|
|
38
|
+
### System Context (reconstructed if needed)
|
|
39
|
+
|
|
40
|
+
```mermaid
|
|
41
|
+
C4Context
|
|
42
|
+
[Reconstruct or verify from actual system]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
[Reconstruct or verify Level 1 System Context from actual system]
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Container View (major components / services)
|
|
50
|
+
|
|
51
|
+
```mermaid
|
|
52
|
+
C4Container
|
|
53
|
+
[Actual containers/components as they exist]
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
[Actual Level 2 containers/components as they exist]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Primary Architecture Style
|
|
61
|
+
|
|
62
|
+
**Identified style**: [Layered / Event-Driven / Service-Based / Monolith / etc.]
|
|
63
|
+
**As intended vs as found**: [Does the actual structure match stated intent?]
|
|
64
|
+
**Style consistency**: [Is the style applied consistently, or are there mixed patterns?]
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Quality Attribute Scenario Analysis
|
|
69
|
+
|
|
70
|
+
For each QAS, assess whether the architecture satisfies it:
|
|
71
|
+
|
|
72
|
+
| QAS ID | Quality Attr | Stimulus | Measure | Verdict | Evidence |
|
|
73
|
+
|---|---|---|---|---|---|
|
|
74
|
+
| QAS-P01 | Performance | 1k concurrent users | p99 < 2s | AT RISK | [Synchronous DB calls with no caching] |
|
|
75
|
+
| QAS-R01 | Reliability | DB server failure | Recovery < 30s | VIOLATED | [Single DB instance, no replica] |
|
|
76
|
+
| QAS-S01 | Security | SQL injection attempt | Zero success rate | SATISFIED | [Parameterized queries verified] |
|
|
77
|
+
|
|
78
|
+
**Verdict values**:
|
|
79
|
+
- `SATISFIED`: Architecture demonstrably meets this QAS
|
|
80
|
+
- `AT RISK`: May not meet under stress, failure, or scale
|
|
81
|
+
- `VIOLATED`: Architecturally cannot meet this QAS
|
|
82
|
+
- `UNKNOWN`: Insufficient evidence to assess
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## QAS Details
|
|
87
|
+
|
|
88
|
+
### QAS-P01: Performance — [VERDICT]
|
|
89
|
+
|
|
90
|
+
**Finding**: [What specific architectural element causes concern or provides assurance]
|
|
91
|
+
|
|
92
|
+
**Evidence**:
|
|
93
|
+
- [Specific code location, design element, or measurement]
|
|
94
|
+
- [Load profile or usage data if available]
|
|
95
|
+
|
|
96
|
+
**Risk**: [What happens if this QAS is violated]
|
|
97
|
+
|
|
98
|
+
**Recommendation**: [Specific architectural change to improve this]
|
|
99
|
+
**Effort**: [hours / days / weeks]
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
### QAS-R01: Reliability — [VERDICT]
|
|
104
|
+
|
|
105
|
+
**Finding**:
|
|
106
|
+
**Evidence**:
|
|
107
|
+
**Risk**:
|
|
108
|
+
**Recommendation**:
|
|
109
|
+
**Effort**:
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
<!-- Add one section per QAS -->
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Architecture Smells Catalog
|
|
118
|
+
|
|
119
|
+
### Structural Smells
|
|
120
|
+
|
|
121
|
+
| Smell | Severity | Location | Evidence | Recommendation |
|
|
122
|
+
|---|---|---|---|---|
|
|
123
|
+
| God Component | HIGH | [ComponentX — 45% of all logic] | [import graph shows 23 dependents] | Split by [responsibility boundary] |
|
|
124
|
+
| Cyclic Dependency | HIGH | [Module A → B → C → A] | [madge output] | Extract shared abstraction |
|
|
125
|
+
| Layer Inversion | MEDIUM | [Domain imports Infrastructure] | [file:line] | Invert dependency via interface |
|
|
126
|
+
| Bottleneck | MEDIUM | [SharedUtils — 89% of modules depend on it] | [dependency graph] | Split into specific utilities |
|
|
127
|
+
|
|
128
|
+
### Communication Smells
|
|
129
|
+
|
|
130
|
+
| Smell | Severity | Location | Evidence | Recommendation |
|
|
131
|
+
|---|---|---|---|---|
|
|
132
|
+
| Missing Circuit Breaker | HIGH | [External payment API call] | [No timeout, no fallback in code] | Add circuit breaker pattern |
|
|
133
|
+
| Synchronous Overuse | MEDIUM | [Email sending in request path] | [POST /orders calls email inline] | Move to async worker |
|
|
134
|
+
| Implicit Contract | MEDIUM | [Service A calls Service B's internal URL] | [Hardcoded internal endpoint in code] | Define explicit client interface |
|
|
135
|
+
|
|
136
|
+
### Data Smells
|
|
137
|
+
|
|
138
|
+
| Smell | Severity | Description | Recommendation |
|
|
139
|
+
|---|---|---|---|
|
|
140
|
+
| Shared Mutable State | HIGH | [Global config object mutated across threads] | Immutable config or thread-local |
|
|
141
|
+
| Cross-Module DB Access | HIGH | [Module B queries Module A's tables directly] | Route through Module A's API |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Sensitivity Points
|
|
146
|
+
|
|
147
|
+
> Design decisions that, if changed, would significantly affect one or more quality attributes.
|
|
148
|
+
|
|
149
|
+
| Sensitivity Point | Current Decision | Quality Attributes Affected | Change Impact |
|
|
150
|
+
|---|---|---|---|
|
|
151
|
+
| [Database access pattern] | [Synchronous ORM queries] | Performance, Scalability | HIGH — all latency-sensitive operations affected |
|
|
152
|
+
| [Authentication placement] | [Per-endpoint auth checks] | Security, Performance | MEDIUM — missing one check = security hole |
|
|
153
|
+
| [Message queue reliability] | [Fire-and-forget events] | Reliability, Data Consistency | HIGH — lost events = data inconsistency |
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Tradeoff Points
|
|
158
|
+
|
|
159
|
+
> Design decisions where improving one quality attribute degrades another.
|
|
160
|
+
|
|
161
|
+
| Tradeoff Point | Decision | Improves | Degrades | Assessment |
|
|
162
|
+
|---|---|---|---|---|
|
|
163
|
+
| [Encryption at rest] | [All data encrypted] | Security | Performance (5-10% overhead) | ACCEPTABLE — security requirement dominates |
|
|
164
|
+
| [Synchronous auth check] | [Check on every request] | Security | Latency (+10ms) | ACCEPTABLE — latency impact minimal |
|
|
165
|
+
| [Eventual consistency] | [Async event updates] | Performance, Scalability | Data Consistency | AT RISK — may violate QAS-R01 |
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Risks
|
|
170
|
+
|
|
171
|
+
| Risk ID | Description | Likelihood | Impact | Mitigation |
|
|
172
|
+
|---|---|---|---|---|
|
|
173
|
+
| RISK-001 | Single DB instance — no failover | H | H | Add read replica + automatic failover |
|
|
174
|
+
| RISK-002 | No circuit breaker on payment API | M | H | Implement circuit breaker with fallback |
|
|
175
|
+
| RISK-003 | God component coupling blocks team velocity | H | M | Planned decomposition per ADR-007 |
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Non-Risks (Sound Decisions)
|
|
180
|
+
|
|
181
|
+
> Well-reasoned decisions that may look risky but are actually sound.
|
|
182
|
+
|
|
183
|
+
| Decision | Why it's a non-risk |
|
|
184
|
+
|---|---|
|
|
185
|
+
| [Synchronous auth on all requests] | [Adds < 10ms; eliminates async session complexity; security cannot be eventually consistent] |
|
|
186
|
+
| [Single-process architecture] | [Load profile shows < 500 concurrent users; single process is sufficient and simpler] |
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Fitness Functions
|
|
191
|
+
|
|
192
|
+
> Checks that should be continuously measured to verify the architecture is healthy.
|
|
193
|
+
|
|
194
|
+
| Fitness Function | Status | Measurement | Frequency |
|
|
195
|
+
|---|---|---|---|
|
|
196
|
+
| No cyclic dependencies | EXISTING | `madge --circular src/` | Each PR |
|
|
197
|
+
| Test coverage ≥ 99% | EXISTING | CI coverage report | Each commit |
|
|
198
|
+
| No cross-layer imports | MISSING | dependency-cruiser | Should be: each PR |
|
|
199
|
+
| p99 latency < 500ms | MISSING | Load test in CI | Should be: each release |
|
|
200
|
+
| No CRITICAL CVEs | EXISTING | `npm audit` | Each PR |
|
|
201
|
+
|
|
202
|
+
**Recommended additions**: [list fitness functions to add based on risks found]
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Recommendations (Prioritized)
|
|
207
|
+
|
|
208
|
+
| Priority | Risk/Smell | Recommendation | Effort | ADR Needed |
|
|
209
|
+
|---|---|---|---|---|
|
|
210
|
+
| CRITICAL | RISK-001 — No DB failover | Add read replica and automatic failover | 2-3 days | YES — ADR-NNN |
|
|
211
|
+
| CRITICAL | RISK-002 — No circuit breaker | Implement circuit breaker for external calls | 1 day | NO |
|
|
212
|
+
| HIGH | God Component [X] | Decompose into [A] and [B] by [boundary] | 1 sprint | YES — ADR-NNN |
|
|
213
|
+
| HIGH | Cyclic dependency A→B→C→A | Extract shared abstraction [D] | 3 days | NO |
|
|
214
|
+
| MEDIUM | Missing fitness functions | Add dependency-cruiser + load test to CI | 2 days | NO |
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## Architecture Evolution Recommendations
|
|
219
|
+
|
|
220
|
+
For significant improvements that require phased implementation:
|
|
221
|
+
|
|
222
|
+
### Phase 1 (Immediate — before next release)
|
|
223
|
+
[Critical risk mitigations]
|
|
224
|
+
|
|
225
|
+
### Phase 2 (Next sprint — maintainability)
|
|
226
|
+
[Architecture smell remediation]
|
|
227
|
+
|
|
228
|
+
### Phase 3 (Next quarter — strategic improvement)
|
|
229
|
+
[Structural changes that improve long-term health]
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Review Sign-off
|
|
234
|
+
|
|
235
|
+
**Gate decision**: APPROVED / APPROVED WITH CONDITIONS / BLOCKED
|
|
236
|
+
|
|
237
|
+
**Conditions for BLOCKED or APPROVED WITH CONDITIONS**:
|
|
238
|
+
- [ ] [Specific condition that must be met]
|
|
239
|
+
|
|
240
|
+
**Sign-off**: [human name / date]
|
|
241
|
+
**Next review trigger**: [When should this architecture be reviewed again? Major feature / N months / scale milestone]
|
|
@@ -0,0 +1,353 @@
|
|
|
1
|
+
# Architecture Views — [System Name]
|
|
2
|
+
<!-- Multi-view architecture documentation following 4+1 Views / arc42 structure -->
|
|
3
|
+
<!-- Created by: arch-design.skill (new) or arch-review.skill (reconstructed) -->
|
|
4
|
+
<!-- Diagrams: Mermaid syntax. Render in VS Code (Mermaid Preview), GitHub, or Notion. -->
|
|
5
|
+
<!-- Standard: ISO/IEC/IEEE 42010, arc42, C4 Model, 4+1 Architectural Views -->
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Meta
|
|
10
|
+
|
|
11
|
+
| Field | Value |
|
|
12
|
+
|---|---|
|
|
13
|
+
| **System** | [system name] |
|
|
14
|
+
| **Version** | [1.0] |
|
|
15
|
+
| **Date** | [YYYY-MM-DD] |
|
|
16
|
+
| **Status** | DRAFT / APPROVED |
|
|
17
|
+
| **Approved by** | [human/role] |
|
|
18
|
+
| **QAS reference** | [QUALITY_ATTRIBUTES.md] |
|
|
19
|
+
| **ADRs** | [docs/architecture/decisions/] |
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 1. Introduction and Goals
|
|
24
|
+
|
|
25
|
+
### 1.1 Business Goals
|
|
26
|
+
|
|
27
|
+
[What business problems does this system solve? 3-5 bullet points]
|
|
28
|
+
|
|
29
|
+
### 1.2 Quality Goals (Top 5)
|
|
30
|
+
|
|
31
|
+
| Priority | Quality Attribute | QAS | Measure |
|
|
32
|
+
|---|---|---|---|
|
|
33
|
+
| 1 | [e.g., Reliability] | QAS-R01 | [e.g., 99.9% availability] |
|
|
34
|
+
| 2 | | | |
|
|
35
|
+
|
|
36
|
+
### 1.3 Stakeholders
|
|
37
|
+
|
|
38
|
+
| Role | Expectation from this architecture |
|
|
39
|
+
|---|---|
|
|
40
|
+
| [Product Owner] | [Architecture supports rapid feature addition] |
|
|
41
|
+
| [Operations Team] | [System can be monitored and deployed without downtime] |
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 2. Constraints
|
|
46
|
+
|
|
47
|
+
### 2.1 Technical Constraints
|
|
48
|
+
|
|
49
|
+
| ID | Constraint | Rationale |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| TC-001 | [e.g., Must integrate with [existing system] via REST] | [existing investment] |
|
|
52
|
+
| TC-002 | | |
|
|
53
|
+
|
|
54
|
+
### 2.2 Organizational Constraints
|
|
55
|
+
|
|
56
|
+
| ID | Constraint | Rationale |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| OC-001 | [e.g., Must be operated by a team of ≤ 5 engineers] | [team size] |
|
|
59
|
+
|
|
60
|
+
### 2.3 Regulatory Constraints
|
|
61
|
+
|
|
62
|
+
| ID | Constraint | Standard |
|
|
63
|
+
|---|---|---|
|
|
64
|
+
| RC-001 | [e.g., All personal data encrypted at rest and in transit] | [GDPR Art. 32] |
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 3. Context and Scope (C4 Level 1)
|
|
69
|
+
|
|
70
|
+
> Highest level view: who uses the system and what external systems does it interact with?
|
|
71
|
+
|
|
72
|
+
```mermaid
|
|
73
|
+
C4Context
|
|
74
|
+
title System Context — [System Name]
|
|
75
|
+
|
|
76
|
+
Person(primaryUser, "[Primary User Role]", "[What they do with the system]")
|
|
77
|
+
Person(adminUser, "[Admin Role]", "[What admins do]")
|
|
78
|
+
|
|
79
|
+
System(system, "[System Name]", "[One-sentence system description]")
|
|
80
|
+
|
|
81
|
+
System_Ext(extSystem1, "[External System 1]", "[What it provides]")
|
|
82
|
+
System_Ext(extSystem2, "[External System 2]", "[What it provides]")
|
|
83
|
+
|
|
84
|
+
Rel(primaryUser, system, "Uses", "HTTPS")
|
|
85
|
+
Rel(adminUser, system, "Administers", "HTTPS")
|
|
86
|
+
Rel(system, extSystem1, "[interaction label]", "[protocol]")
|
|
87
|
+
Rel(system, extSystem2, "[interaction label]", "[protocol]")
|
|
88
|
+
|
|
89
|
+
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**Scope definition:**
|
|
93
|
+
- In scope: [what the system handles]
|
|
94
|
+
- Out of scope: [what it explicitly does not handle]
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## 4. Solution Strategy
|
|
99
|
+
|
|
100
|
+
### 4.1 Architecture Style
|
|
101
|
+
|
|
102
|
+
**Primary style**: [Layered / Event-Driven / Microkernel / Service-Based / ...]
|
|
103
|
+
**Rationale**: [Why this style — which quality attributes drive this choice]
|
|
104
|
+
|
|
105
|
+
See: [ADR-001 — Architecture Style Decision]
|
|
106
|
+
|
|
107
|
+
### 4.2 Decomposition Strategy
|
|
108
|
+
|
|
109
|
+
**Approach**: [Domain-driven / Capability-based / Layered]
|
|
110
|
+
**Key decisions**: [summary of major structural decisions]
|
|
111
|
+
|
|
112
|
+
### 4.3 Key Technology Areas (without specific technology selection)
|
|
113
|
+
|
|
114
|
+
| Area | Decision | Rationale |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| Data persistence | [relational / document / event store] | [QAS driven] |
|
|
117
|
+
| Communication style | [synchronous / async / hybrid] | [QAS driven] |
|
|
118
|
+
| API style | [REST / event-based / hybrid] | [consumer needs] |
|
|
119
|
+
| Security approach | [centralized auth / per-service / gateway] | [QAS-S driven] |
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 5. Building Block View (C4 Level 2 — Containers)
|
|
124
|
+
|
|
125
|
+
> What are the major deployable units?
|
|
126
|
+
|
|
127
|
+
```mermaid
|
|
128
|
+
C4Container
|
|
129
|
+
title Container Diagram — [System Name]
|
|
130
|
+
|
|
131
|
+
Person(user, "[User Role]")
|
|
132
|
+
|
|
133
|
+
System_Boundary(system, "[System Name]") {
|
|
134
|
+
Container(webapp, "[Web App / Client]", "[Technology: e.g., Browser SPA]", "[Responsibility]")
|
|
135
|
+
Container(api, "[API / Backend]", "[Technology: e.g., Server process]", "[Responsibility]")
|
|
136
|
+
Container(worker, "[Background Worker]", "[Technology: e.g., Queue consumer]", "[Responsibility]")
|
|
137
|
+
ContainerDb(db, "[Primary Store]", "[Technology: e.g., Relational DB]", "[What data]")
|
|
138
|
+
ContainerDb(cache, "[Cache]", "[Technology: e.g., In-memory store]", "[What's cached]")
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
System_Ext(ext1, "[External System]")
|
|
142
|
+
|
|
143
|
+
Rel(user, webapp, "Uses", "HTTPS")
|
|
144
|
+
Rel(webapp, api, "Calls", "HTTPS/JSON")
|
|
145
|
+
Rel(api, db, "Reads/writes", "TCP")
|
|
146
|
+
Rel(api, cache, "Reads/writes", "TCP")
|
|
147
|
+
Rel(api, ext1, "[interaction]", "[protocol]")
|
|
148
|
+
Rel(api, worker, "Enqueues jobs", "Message Queue")
|
|
149
|
+
Rel(worker, db, "Reads/writes", "TCP")
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Container Responsibilities
|
|
153
|
+
|
|
154
|
+
| Container | Responsibility | Owns | Does NOT own |
|
|
155
|
+
|---|---|---|---|
|
|
156
|
+
| [Web App] | [User interface, client-side logic] | [UI state] | [Business rules] |
|
|
157
|
+
| [API] | [Business logic, orchestration] | [Domain logic] | [UI, raw data storage] |
|
|
158
|
+
| [Worker] | [Async processing, background jobs] | [Job execution] | [Synchronous requests] |
|
|
159
|
+
| [Primary Store] | [Persistent data storage] | [Canonical data] | [Derived/cached data] |
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## 6. Component View (C4 Level 3 — inside one container)
|
|
164
|
+
|
|
165
|
+
> Zoom into the most complex container. Create one diagram per major container if needed.
|
|
166
|
+
|
|
167
|
+
```mermaid
|
|
168
|
+
C4Component
|
|
169
|
+
title Component Diagram — [API Container]
|
|
170
|
+
|
|
171
|
+
Container_Boundary(api, "[API Container]") {
|
|
172
|
+
Component(entrypoint, "[HTTP Router / Entry Point]", "[Type]", "[Routes requests to handlers]")
|
|
173
|
+
Component(auth, "[Authentication Component]", "[Type]", "[Validates identity]")
|
|
174
|
+
Component(authz, "[Authorization Component]", "[Type]", "[Enforces permissions]")
|
|
175
|
+
|
|
176
|
+
Component(featureA, "[Feature A Handler]", "[Type]", "[Handles use case A]")
|
|
177
|
+
Component(featureB, "[Feature B Handler]", "[Type]", "[Handles use case B]")
|
|
178
|
+
|
|
179
|
+
Component(domainA, "[Domain Service A]", "[Type]", "[Core business logic for A]")
|
|
180
|
+
Component(repoA, "[Repository A]", "[Type]", "[Data access for domain A]")
|
|
181
|
+
|
|
182
|
+
Component(ext1client, "[External System Client]", "[Type]", "[Calls external system]")
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
ContainerDb(db, "[Primary Store]")
|
|
186
|
+
System_Ext(ext1, "[External System]")
|
|
187
|
+
|
|
188
|
+
Rel(entrypoint, auth, "All requests through")
|
|
189
|
+
Rel(auth, authz, "Authenticated requests to")
|
|
190
|
+
Rel(authz, featureA, "Authorized requests")
|
|
191
|
+
Rel(featureA, domainA, "Calls")
|
|
192
|
+
Rel(domainA, repoA, "Reads/writes via")
|
|
193
|
+
Rel(repoA, db, "SQL/query")
|
|
194
|
+
Rel(featureA, ext1client, "Calls when needed")
|
|
195
|
+
Rel(ext1client, ext1, "HTTPS API call")
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Component Responsibilities
|
|
199
|
+
|
|
200
|
+
| Component | Responsibility | Layer | Interface |
|
|
201
|
+
|---|---|---|---|
|
|
202
|
+
| [HTTP Router] | [Route HTTP requests, parse input] | Adapter | [HTTP] |
|
|
203
|
+
| [Auth Component] | [Verify identity token] | Adapter | [Internal] |
|
|
204
|
+
| [Feature A Handler] | [Orchestrate use case A] | Application | [Internal] |
|
|
205
|
+
| [Domain Service A] | [Core business rules for A] | Domain | [Internal] |
|
|
206
|
+
| [Repository A] | [Persist/retrieve A's data] | Infrastructure | [Internal] |
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## 7. Runtime View (Process / Behavioral)
|
|
211
|
+
|
|
212
|
+
> How do the components interact for key use cases?
|
|
213
|
+
|
|
214
|
+
### 7.1 [Key Use Case 1 — e.g., User Registration]
|
|
215
|
+
|
|
216
|
+
```mermaid
|
|
217
|
+
sequenceDiagram
|
|
218
|
+
autonumber
|
|
219
|
+
actor User
|
|
220
|
+
participant EntryPoint as HTTP Router
|
|
221
|
+
participant Auth as Auth Component
|
|
222
|
+
participant Handler as [Feature Handler]
|
|
223
|
+
participant Domain as [Domain Service]
|
|
224
|
+
participant Repo as [Repository]
|
|
225
|
+
participant DB as [Primary Store]
|
|
226
|
+
|
|
227
|
+
User->>EntryPoint: [HTTP request with payload]
|
|
228
|
+
EntryPoint->>Auth: [validate / parse]
|
|
229
|
+
Auth-->>EntryPoint: [identity / error]
|
|
230
|
+
EntryPoint->>Handler: [parsed command/query]
|
|
231
|
+
Handler->>Domain: [business operation]
|
|
232
|
+
Domain->>Repo: [persist / retrieve]
|
|
233
|
+
Repo->>DB: [query]
|
|
234
|
+
DB-->>Repo: [result]
|
|
235
|
+
Repo-->>Domain: [domain objects]
|
|
236
|
+
Domain-->>Handler: [result]
|
|
237
|
+
Handler-->>EntryPoint: [response DTO]
|
|
238
|
+
EntryPoint-->>User: [HTTP response]
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### 7.2 [Key Use Case 2 — e.g., Background Job Processing]
|
|
242
|
+
|
|
243
|
+
```mermaid
|
|
244
|
+
sequenceDiagram
|
|
245
|
+
[Add sequence for async/background flows]
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## 8. Deployment View
|
|
251
|
+
|
|
252
|
+
> Where does the system run?
|
|
253
|
+
|
|
254
|
+
```mermaid
|
|
255
|
+
C4Deployment
|
|
256
|
+
title Deployment Diagram — [System Name] — [Environment: Production]
|
|
257
|
+
|
|
258
|
+
Deployment_Node(cloud, "[Cloud Provider / Region]") {
|
|
259
|
+
Deployment_Node(lb, "[Load Balancer]") {
|
|
260
|
+
Container(api1, "[API Instance 1]", "[Container/VM]")
|
|
261
|
+
Container(api2, "[API Instance 2]", "[Container/VM]")
|
|
262
|
+
}
|
|
263
|
+
Deployment_Node(worker_node, "[Worker Node]") {
|
|
264
|
+
Container(worker, "[Worker Process]", "[Container/VM]")
|
|
265
|
+
}
|
|
266
|
+
Deployment_Node(data_node, "[Data Layer]") {
|
|
267
|
+
ContainerDb(db_primary, "[Primary DB]", "[Relational DB]")
|
|
268
|
+
ContainerDb(db_replica, "[Read Replica]", "[Relational DB]")
|
|
269
|
+
ContainerDb(cache, "[Cache]", "[In-memory]")
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
Deployment_Node(cdn, "[CDN]") {
|
|
274
|
+
Container(static, "[Static Assets]")
|
|
275
|
+
}
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
### Deployment Topology
|
|
279
|
+
|
|
280
|
+
| Environment | Description | Key differences from production |
|
|
281
|
+
|---|---|---|
|
|
282
|
+
| Local Dev | [Docker Compose, single instance] | [Single DB, no cache] |
|
|
283
|
+
| Staging | [Cloud, single-node] | [Real integrations, reduced scale] |
|
|
284
|
+
| Production | [Cloud, multi-node, HA] | [Fully redundant] |
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## 9. Cross-Cutting Concepts
|
|
289
|
+
|
|
290
|
+
### 9.1 Security Architecture
|
|
291
|
+
|
|
292
|
+
```
|
|
293
|
+
Authentication: [approach — token-based, session-based, federated]
|
|
294
|
+
Authorization: [approach — RBAC, ABAC, ACL]
|
|
295
|
+
Boundary: [where is auth enforced — gateway, per-component]
|
|
296
|
+
Data security: [encryption at rest / in transit approach]
|
|
297
|
+
Secret mgmt: [where secrets are stored and how accessed]
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
### 9.2 Observability Architecture
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
Logging: [structured log format, where collected]
|
|
304
|
+
Metrics: [what is measured, where surfaced]
|
|
305
|
+
Tracing: [distributed trace approach, correlation IDs]
|
|
306
|
+
Alerting: [what triggers alerts, who is notified]
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### 9.3 Error Handling Strategy
|
|
310
|
+
|
|
311
|
+
```
|
|
312
|
+
System errors: [how internal errors are caught and handled]
|
|
313
|
+
User errors: [how validation and user mistakes are communicated]
|
|
314
|
+
External errors: [how upstream failures are handled — circuit breaker, retry, fallback]
|
|
315
|
+
Error taxonomy: [error classification — transient, permanent, user, system]
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## 10. Architecture Decisions
|
|
321
|
+
|
|
322
|
+
| ADR | Decision | Status |
|
|
323
|
+
|---|---|---|
|
|
324
|
+
| [ADR-001] | [Architecture style choice] | ACCEPTED |
|
|
325
|
+
| [ADR-002] | [Decomposition strategy] | ACCEPTED |
|
|
326
|
+
| [ADR-003] | [Communication pattern] | ACCEPTED |
|
|
327
|
+
|
|
328
|
+
Full ADRs in: `docs/architecture/decisions/`
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
## 11. Quality Requirements Addressed
|
|
333
|
+
|
|
334
|
+
| QAS | How the architecture addresses it |
|
|
335
|
+
|---|---|
|
|
336
|
+
| QAS-P01 [Performance] | [e.g., Caching layer + async worker for heavy operations] |
|
|
337
|
+
| QAS-R01 [Reliability] | [e.g., Active-passive failover + health checks] |
|
|
338
|
+
| QAS-S01 [Security] | [e.g., Centralized auth gateway + input validation layer] |
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## 12. Risks and Technical Debt
|
|
343
|
+
|
|
344
|
+
| Risk | Likelihood | Impact | Mitigation |
|
|
345
|
+
|---|---|---|---|
|
|
346
|
+
| [Risk description] | H/M/L | H/M/L | [What reduces this risk] |
|
|
347
|
+
|
|
348
|
+
See: `docs/architecture/ARCHITECTURE_RISKS.md`
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
*Last updated: [date]*
|
|
353
|
+
*Review trigger: new major feature, team composition change, significant scale change*
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Architecture Decision Framework
|
|
2
|
+
|
|
3
|
+
**Decision Title**: [e.g., Monolith vs Microservices for Order Service]
|
|
4
|
+
**Date**: [YYYY-MM-DD]
|
|
5
|
+
**Status**: [Proposed / Accepted / Rejected]
|
|
6
|
+
|
|
7
|
+
## 1. Context & Problem Statement
|
|
8
|
+
[What are we trying to solve? e.g., "The Order service needs independent scaling for Black Friday."]
|
|
9
|
+
|
|
10
|
+
## 2. Options Considered
|
|
11
|
+
|
|
12
|
+
| Option | Description | Pros | Cons |
|
|
13
|
+
|---|---|---|---|
|
|
14
|
+
| **Option A** | [e.g., Modular Monolith] | - Simple deployment<br>- Zero network latency | - Harder to scale writes independently |
|
|
15
|
+
| **Option B** | [e.g., Microservices] | - Independent scaling<br>- Tech stack freedom | - High operational complexity<br>- Network latency |
|
|
16
|
+
| **Option C** | [e.g., Serverless] | - Pay-per-use<br>- Infinite scaling | - Cold starts<br>- Vendor lock-in |
|
|
17
|
+
|
|
18
|
+
## 3. Decision Drivers (NFRs)
|
|
19
|
+
- **Scalability**: [High/Med/Low importance]
|
|
20
|
+
- **Cost**: [Budget constraints]
|
|
21
|
+
- **Time to Market**: [Urgency]
|
|
22
|
+
- **Maintainability**: [Team skill level]
|
|
23
|
+
|
|
24
|
+
## 4. Final Recommendation
|
|
25
|
+
**Selected Option**: [Option B]
|
|
26
|
+
|
|
27
|
+
**Justification**:
|
|
28
|
+
[Why this option won. e.g., "Scalability is the #1 driver. We accept the operational complexity cost."]
|
|
29
|
+
|
|
30
|
+
## 5. Consequences
|
|
31
|
+
- **Positive**: [e.g., Can scale to 10k TPS]
|
|
32
|
+
- **Negative**: [e.g., Need to implement distributed tracing]
|