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,51 @@
|
|
|
1
|
+
# System Qualities: The "Ilities" Guide
|
|
2
|
+
|
|
3
|
+
Building software is easy. Building software that *lasts*, *scales*, and *adapts* is hard.
|
|
4
|
+
|
|
5
|
+
> **Standard:** align quality attributes to **ISO/IEC 25010:2023** (Ed. 2) — the
|
|
6
|
+
> nine product-quality characteristics: Functional Suitability, Performance
|
|
7
|
+
> Efficiency, Compatibility, **Interaction Capability** (was Usability),
|
|
8
|
+
> Reliability, **Safety** (new in 2023), Security, Maintainability, and
|
|
9
|
+
> **Flexibility** (was Portability). Use these as the canonical NFR checklist.
|
|
10
|
+
> Source: <https://www.iso.org/standard/78176.html> (verified 2026-06-10).
|
|
11
|
+
|
|
12
|
+
## 1. Reliability & SRE
|
|
13
|
+
*Reliability is the most important feature. If it's down, it doesn't matter how fast it is.*
|
|
14
|
+
|
|
15
|
+
- **SLOs (Service Level Objectives)**: Set a target (e.g., 99.9%). Don't aim for 100%.
|
|
16
|
+
- **Error Budgets**: Use the remaining 0.1% to take risks. If you burn the budget, stop shipping features.
|
|
17
|
+
- **Chaos Engineering**: Break things on purpose. If you don't test failover, it won't work when you need it.
|
|
18
|
+
|
|
19
|
+
## 2. Scalability & Performance
|
|
20
|
+
*Performance is not about being "fast". It's about being "consistent" under load.*
|
|
21
|
+
|
|
22
|
+
- **Caching**: The fastest query is the one you don't make. Use **Cache-Aside** for most cases.
|
|
23
|
+
- **Async Processing**: Don't make the user wait for email sending. Use a Queue (RabbitMQ / SQS).
|
|
24
|
+
- **Database First**: Optimize your SQL queries and Indices before rewriting the app in Rust.
|
|
25
|
+
|
|
26
|
+
## 3. Compatibility & Evolution
|
|
27
|
+
*Change is constant. Breaking things is optional.*
|
|
28
|
+
|
|
29
|
+
- **Expand & Contract**: The Golden Rule of Zero Downtime Migrations.
|
|
30
|
+
1. **Add** the new thing.
|
|
31
|
+
2. **Support** both old and new.
|
|
32
|
+
3. **Delete** the old thing.
|
|
33
|
+
- **Tolerant Readers**: Follow Postel's Law. Be strict in what you send, but liberal in what you accept.
|
|
34
|
+
- **Forward Compatibility**: Design today's system to ignore tomorrow's unknown fields.
|
|
35
|
+
|
|
36
|
+
## 4. Observability
|
|
37
|
+
*You can't fix what you can't see.*
|
|
38
|
+
|
|
39
|
+
- **Logs**: "What happened?" (Events)
|
|
40
|
+
- **Metrics**: "Is it healthy?" (Aggregates)
|
|
41
|
+
- **Traces**: "Where did it happen?" (Context)
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Core Performance Skills
|
|
46
|
+
- [Performant Node.js](../../skills/coding/performant-nodejs.skill.md)
|
|
47
|
+
- [Performant Laravel](../../skills/coding/performant-laravel.skill.md)
|
|
48
|
+
- [Performant Python](../../skills/coding/performant-python.skill.md)
|
|
49
|
+
- [Performant Go](../../skills/coding/performant-go.skill.md)
|
|
50
|
+
- [Performant AI](../../skills/coding/performant-ai.skill.md)
|
|
51
|
+
- [Performance Optimization](../../skills/ops/performance-optimization.skill.md)
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# System Scalability Guide
|
|
2
|
+
|
|
3
|
+
## 1. Introduction
|
|
4
|
+
Scalability is the property of a system to handle a growing amount of work by adding resources to the system. This guide defines standard approaches to both vertical and horizontal scaling.
|
|
5
|
+
|
|
6
|
+
## 2. The Scaling Axes (The Scale Cube)
|
|
7
|
+
|
|
8
|
+
### X-Axis: Horizontal Duplication (Cloning)
|
|
9
|
+
- **Concept:** Running multiple identical copies of the application behind a load balancer.
|
|
10
|
+
- **Prerequisites:** The application must be stateless. Any session data or cached data must be externalized to a shared store (like Redis or Memcached).
|
|
11
|
+
- **Pros:** Conceptually simple, highly available.
|
|
12
|
+
- **Cons:** Can be expensive if resources are underutilized; database becomes the bottleneck quickly.
|
|
13
|
+
|
|
14
|
+
### Y-Axis: Functional Decomposition (Microservices)
|
|
15
|
+
- **Concept:** Splitting a monolithic application into multiple, distinct, independent services based on business boundaries.
|
|
16
|
+
- **Pros:** Allows independent scaling of high-load features (e.g., scaling the Checkout service independently of the Catalog service).
|
|
17
|
+
- **Cons:** High operational complexity, data consistency challenges (requires Sagas or Event Sourcing).
|
|
18
|
+
|
|
19
|
+
### Z-Axis: Data Partitioning (Sharding)
|
|
20
|
+
- **Concept:** Partitioning a database where each instance handles only a subset of the data (e.g., routing users A-M to Database 1, and N-Z to Database 2).
|
|
21
|
+
- **Pros:** Solves infinite data growth.
|
|
22
|
+
- **Cons:** Extremely complex application logic; cross-shard joins are nearly impossible.
|
|
23
|
+
|
|
24
|
+
## 3. Vertical Scaling (Scale Up)
|
|
25
|
+
- **Concept:** Adding more CPU, RAM, or faster Disks (IOPS) to a single machine.
|
|
26
|
+
- **When to use:** Early in a project's lifecycle, or for systems like relational databases (up to a certain physical limit) where horizontal scaling is too expensive to re-architect.
|
|
27
|
+
- **Limits:** Hard physical caps on hardware; requires downtime to upgrade.
|
|
28
|
+
|
|
29
|
+
## 4. Cache Everything
|
|
30
|
+
Before complex scaling, utilize aggressive caching:
|
|
31
|
+
1. **CDN / Edge Caching:** Static assets and full HTML pages.
|
|
32
|
+
2. **API Caching:** HTTP Cache-Control headers.
|
|
33
|
+
3. **App Level Caching:** Redis/Memcached for frequent DB queries.
|
|
34
|
+
|
|
35
|
+
## 5. Agentic Implementation
|
|
36
|
+
When working with agents on scalability problems:
|
|
37
|
+
- Invoke the `system-scalability` skill.
|
|
38
|
+
- The agent will evaluate the system and generate a `SCALABILITY_ANALYSIS_TEMPLATE.md` to map out exactly which axis is best suited to the current bottleneck.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Technical Performance Skills
|
|
43
|
+
- [Performant Node.js](../../skills/coding/performant-nodejs.skill.md)
|
|
44
|
+
- [Performant Laravel](../../skills/coding/performant-laravel.skill.md)
|
|
45
|
+
- [Performant Python](../../skills/coding/performant-python.skill.md)
|
|
46
|
+
- [Performant Go](../../skills/coding/performant-go.skill.md)
|
|
47
|
+
- [Performant AI](../../skills/coding/performant-ai.skill.md)
|
|
@@ -0,0 +1,506 @@
|
|
|
1
|
+
# Guide: Systems Architecture
|
|
2
|
+
<!-- Architecture frameworks, quality attributes, styles, documentation standards -->
|
|
3
|
+
<!-- Technology-agnostic. Principles apply across all platforms and languages. -->
|
|
4
|
+
<!-- Standards: ISO/IEC/IEEE 42010, arc42, 4+1 views, C4 model, SEI ATAM -->
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## What is Architecture?
|
|
9
|
+
|
|
10
|
+
Architecture is the set of **structures** needed to reason about the system — the
|
|
11
|
+
components, their relationships, and the properties of both components and relationships.
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
Good architecture:
|
|
15
|
+
- Makes the important decisions explicit and visible
|
|
16
|
+
- Makes the wrong thing HARD to do (bad pattern → visible violation)
|
|
17
|
+
- Enables independent evolution of parts without breaking the whole
|
|
18
|
+
- Satisfies the system's quality attribute requirements
|
|
19
|
+
|
|
20
|
+
Architecture is NOT:
|
|
21
|
+
- Technology selection (that's a design decision following architecture)
|
|
22
|
+
- The "big upfront design" — architecture should evolve with the system
|
|
23
|
+
- A single diagram — multiple views are needed to represent a system
|
|
24
|
+
- Just the "happy path" — architecture must address failure modes
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Architecture Fundamentals
|
|
30
|
+
|
|
31
|
+
### Quality Attributes Drive Architecture
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
Every architecture decision is a tradeoff between quality attributes.
|
|
35
|
+
The quality attribute requirements (QAS) DETERMINE the architecture style and tactics.
|
|
36
|
+
|
|
37
|
+
Process:
|
|
38
|
+
1. Identify quality attribute priorities (what matters most for this system)
|
|
39
|
+
2. Define measurable QAS for top 3-5 attributes
|
|
40
|
+
3. Select architecture style that supports those QAS
|
|
41
|
+
4. Apply architectural tactics for specific QAS
|
|
42
|
+
5. Validate architecture against QAS (ATAM review)
|
|
43
|
+
|
|
44
|
+
If you don't know the quality priorities → you cannot make good architecture decisions.
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### ISO 25010 Quality Attributes
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
Performance Efficiency
|
|
51
|
+
Time behavior: How fast (response time, throughput)
|
|
52
|
+
Resource utilization: How efficiently resources are used
|
|
53
|
+
Capacity: How much load can be sustained
|
|
54
|
+
|
|
55
|
+
Reliability
|
|
56
|
+
Availability: % of time system is operable
|
|
57
|
+
Fault tolerance: Operation despite component failures
|
|
58
|
+
Recoverability: Speed and completeness of recovery from failure
|
|
59
|
+
|
|
60
|
+
Security
|
|
61
|
+
Confidentiality: Data protected from unauthorized disclosure
|
|
62
|
+
Integrity: Data protected from unauthorized modification
|
|
63
|
+
Non-repudiation: Actions attributable to actors
|
|
64
|
+
Authenticity: Actors and data are genuine
|
|
65
|
+
|
|
66
|
+
Usability
|
|
67
|
+
Appropriateness: Supports task completion
|
|
68
|
+
Learnability: Users learn to use efficiently
|
|
69
|
+
Accessibility: Usable by people with disabilities
|
|
70
|
+
|
|
71
|
+
Maintainability
|
|
72
|
+
Modularity: Changes confined to minimal components
|
|
73
|
+
Reusability: Components usable in other contexts
|
|
74
|
+
Analyzability: Diagnosable efficiently
|
|
75
|
+
Modifiability: Modified without introducing defects
|
|
76
|
+
Testability: Test criteria established and executable
|
|
77
|
+
|
|
78
|
+
Portability
|
|
79
|
+
Adaptability: Works in different environments
|
|
80
|
+
Installability: Can be installed/uninstalled
|
|
81
|
+
Replaceability: Can replace other equivalent software
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Architecture Styles
|
|
87
|
+
|
|
88
|
+
### Layered Architecture
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
Structure:
|
|
92
|
+
Layer N (Presentation / Interface)
|
|
93
|
+
↓ depends on
|
|
94
|
+
Layer N-1 (Application / Use Cases)
|
|
95
|
+
↓ depends on
|
|
96
|
+
Layer N-2 (Domain / Business Logic)
|
|
97
|
+
↓ depends on
|
|
98
|
+
Layer N-3 (Infrastructure / Data)
|
|
99
|
+
|
|
100
|
+
Rules:
|
|
101
|
+
- Each layer depends only on the layer directly below it
|
|
102
|
+
- Inner layers have no knowledge of outer layers
|
|
103
|
+
- Cross-layer skipping is an architectural violation
|
|
104
|
+
|
|
105
|
+
Quality strengths: Maintainability, Testability, Modifiability
|
|
106
|
+
Quality weaknesses: Performance (pass-through layers), Scalability
|
|
107
|
+
|
|
108
|
+
Use when:
|
|
109
|
+
- General-purpose business application
|
|
110
|
+
- Small to medium team
|
|
111
|
+
- Maintainability is a dominant quality attribute
|
|
112
|
+
- Not extreme scalability or fault tolerance required
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Event-Driven Architecture
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
Structure:
|
|
119
|
+
Components communicate by publishing and subscribing to events.
|
|
120
|
+
No direct coupling between producers and consumers.
|
|
121
|
+
|
|
122
|
+
Producer → [Event Bus] → Consumer(s)
|
|
123
|
+
|
|
124
|
+
Event Bus implementations (technology-agnostic terms):
|
|
125
|
+
Synchronous event: In-process observer pattern
|
|
126
|
+
Async message queue: Persistent queue (at-least-once delivery)
|
|
127
|
+
Event stream: Ordered, replayable log of events
|
|
128
|
+
|
|
129
|
+
Patterns within event-driven:
|
|
130
|
+
Event Notification: Notify that something happened (no payload needed — consumer queries)
|
|
131
|
+
Event-Carried State: Carry all relevant data in the event (consumer needs nothing else)
|
|
132
|
+
Event Sourcing: Events ARE the system of record (state derived from event replay)
|
|
133
|
+
|
|
134
|
+
Quality strengths: Decoupling, Scalability, Auditability, Extensibility
|
|
135
|
+
Quality weaknesses: Complexity, Eventual consistency, Debugging difficulty
|
|
136
|
+
|
|
137
|
+
Use when:
|
|
138
|
+
- High decoupling between components is required
|
|
139
|
+
- Multiple consumers react to the same business event
|
|
140
|
+
- Audit trail of all changes needed
|
|
141
|
+
- System must scale producers and consumers independently
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Microkernel (Plugin) Architecture
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
Structure:
|
|
148
|
+
Core system (kernel): minimal, stable feature set
|
|
149
|
+
Plug-in modules: extend core without modifying it
|
|
150
|
+
|
|
151
|
+
[Plug-in A] ──→
|
|
152
|
+
[Plug-in B] ──→ [Core System] ←── [Plug-in Registry]
|
|
153
|
+
[Plug-in C] ──→
|
|
154
|
+
|
|
155
|
+
Quality strengths: Extensibility, Customizability, Isolation
|
|
156
|
+
Quality weaknesses: Plug-in API design complexity, Registry management
|
|
157
|
+
|
|
158
|
+
Use when:
|
|
159
|
+
- Product with many optional features or configurations
|
|
160
|
+
- Third-party extension is a business requirement
|
|
161
|
+
- Multi-tenant SaaS with per-tenant customization
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Service-Based Architecture
|
|
165
|
+
|
|
166
|
+
```
|
|
167
|
+
Structure:
|
|
168
|
+
Coarse-grained services aligned to domain capabilities.
|
|
169
|
+
Shared infrastructure (database, auth, logging) but independent service logic.
|
|
170
|
+
Typically 4-12 services (between monolith and microservices complexity).
|
|
171
|
+
|
|
172
|
+
[User Service] [Order Service] [Payment Service]
|
|
173
|
+
↓ ↓ ↓
|
|
174
|
+
[Shared Database / Shared Cache / Shared Message Bus]
|
|
175
|
+
|
|
176
|
+
Quality strengths: Domain alignment, Team independence, Deployability
|
|
177
|
+
Quality weaknesses: Shared infrastructure coupling, Distributed transaction complexity
|
|
178
|
+
|
|
179
|
+
Use when:
|
|
180
|
+
- Multiple distinct business domains need independence
|
|
181
|
+
- Teams own specific domains (team per service)
|
|
182
|
+
- Microservices overhead not yet justified
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Space-Based Architecture
|
|
186
|
+
|
|
187
|
+
```
|
|
188
|
+
Structure:
|
|
189
|
+
Processing units: stateful components with in-memory data grids
|
|
190
|
+
No central database in the request path
|
|
191
|
+
Data virtualization layer synchronizes to persistence asynchronously
|
|
192
|
+
|
|
193
|
+
[Client] → [Processing Unit 1 + local grid]
|
|
194
|
+
[Processing Unit 2 + local grid] ← replicated grid
|
|
195
|
+
[Processing Unit N + local grid]
|
|
196
|
+
↓ async
|
|
197
|
+
[Persistence Layer]
|
|
198
|
+
|
|
199
|
+
Quality strengths: Extreme scalability, Fault tolerance
|
|
200
|
+
Quality weaknesses: Data consistency complexity, High implementation cost
|
|
201
|
+
|
|
202
|
+
Use when:
|
|
203
|
+
- Extremely high and unpredictable load spikes
|
|
204
|
+
- Elastic scaling is a primary requirement
|
|
205
|
+
- Financial trading systems, ticketing systems
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## Architectural Tactics
|
|
211
|
+
|
|
212
|
+
Tactics are design moves to improve a specific quality attribute.
|
|
213
|
+
|
|
214
|
+
### Performance Tactics
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
Manage demand:
|
|
218
|
+
Manage event arrival: Limit incoming requests (rate limiting, throttling)
|
|
219
|
+
Manage sampling rate: Sample/skip non-critical work under load
|
|
220
|
+
Prioritize events: Process high-priority events first
|
|
221
|
+
|
|
222
|
+
Manage resources:
|
|
223
|
+
Increase resources: Scale vertically or horizontally
|
|
224
|
+
Introduce concurrency: Process requests in parallel (threads, async)
|
|
225
|
+
Reduce overhead: Minimize unnecessary operations in critical path
|
|
226
|
+
Bound execution: Time-bound all operations (timeouts everywhere)
|
|
227
|
+
Increase efficiency: Cache results; reduce recomputation; lazy loading
|
|
228
|
+
|
|
229
|
+
Arbitrate:
|
|
230
|
+
Scheduling policy: FIFO, round-robin, priority queue
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Reliability Tactics
|
|
234
|
+
|
|
235
|
+
```
|
|
236
|
+
Detect faults:
|
|
237
|
+
Monitor: Heartbeat, ping/echo, health check endpoints
|
|
238
|
+
Exceptions: Exception-based detection with classification
|
|
239
|
+
|
|
240
|
+
Recover from faults:
|
|
241
|
+
Preparation: Active redundancy (hot standby), passive redundancy (warm standby)
|
|
242
|
+
Retry: Automatic retry with exponential backoff
|
|
243
|
+
Ignore: Ignore non-critical fault if processing can continue
|
|
244
|
+
Degraded mode: Reduce functionality but keep core running
|
|
245
|
+
Reconfigure: Remove failed component, redistribute load
|
|
246
|
+
|
|
247
|
+
Prevent faults:
|
|
248
|
+
Removal from service: Take component offline for maintenance without system failure
|
|
249
|
+
Transactions: Atomic operations to prevent partial failure
|
|
250
|
+
Circuit breaker: Open circuit on repeated failures; prevent cascade
|
|
251
|
+
|
|
252
|
+
Recovery objectives:
|
|
253
|
+
RTO (Recovery Time Objective): Maximum acceptable downtime after failure
|
|
254
|
+
RPO (Recovery Point Objective): Maximum acceptable data loss (in time)
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
### Security Tactics
|
|
258
|
+
|
|
259
|
+
```
|
|
260
|
+
Detect attacks:
|
|
261
|
+
Detect intrusion: Monitor for known attack patterns
|
|
262
|
+
Detect service denial: Identify DoS/DDoS traffic patterns
|
|
263
|
+
|
|
264
|
+
Resist attacks:
|
|
265
|
+
Identify actors: Authentication (verify identity before granting access)
|
|
266
|
+
Authorize actors: Authorization (enforce permissions after identity established)
|
|
267
|
+
Limit exposure: Minimize attack surface (principle of least privilege)
|
|
268
|
+
Encrypt data: Confidentiality in transit and at rest
|
|
269
|
+
Separate entities: Isolate sensitive components (blast radius reduction)
|
|
270
|
+
Validate input: Reject malformed input at system boundaries
|
|
271
|
+
|
|
272
|
+
React to attacks:
|
|
273
|
+
Revoke access: Terminate sessions, invalidate tokens on detection
|
|
274
|
+
Limit access: Rate limiting, account lockout
|
|
275
|
+
Inform actors: Log and alert on detected attacks
|
|
276
|
+
|
|
277
|
+
Recovery:
|
|
278
|
+
Restore: Recover from known-good state
|
|
279
|
+
Audit: Forensic trail to understand what happened
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Maintainability Tactics
|
|
283
|
+
|
|
284
|
+
```
|
|
285
|
+
Reduce coupling:
|
|
286
|
+
Encapsulate: Hide implementation behind stable interfaces
|
|
287
|
+
Use intermediary: Mediator, broker, or adapter between components
|
|
288
|
+
Restrict dependencies: Enforce import/dependency rules (layering)
|
|
289
|
+
Defer binding: Configuration, feature flags, plugin loading
|
|
290
|
+
|
|
291
|
+
Increase cohesion:
|
|
292
|
+
Separate concerns: Single responsibility per module/component
|
|
293
|
+
Abstract common services: Move shared behavior to a clearly defined service
|
|
294
|
+
|
|
295
|
+
Improve testability:
|
|
296
|
+
Control and observe: Inject dependencies (no hardcoded collaborators)
|
|
297
|
+
Sandbox: Isolate components for testing (test doubles, stubs)
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Architecture Documentation Standards
|
|
303
|
+
|
|
304
|
+
### The 4+1 Architectural Views
|
|
305
|
+
|
|
306
|
+
```
|
|
307
|
+
Logical View (structural — what the system IS):
|
|
308
|
+
Audience: developers, architects
|
|
309
|
+
Shows: Major abstractions, components, their responsibilities and relationships
|
|
310
|
+
Diagrams: Component diagram, class/entity diagram
|
|
311
|
+
|
|
312
|
+
Process View (behavioral — what the system DOES):
|
|
313
|
+
Audience: developers, performance engineers
|
|
314
|
+
Shows: How components interact at runtime for key use cases
|
|
315
|
+
Concurrency model, processes, threads
|
|
316
|
+
Diagrams: Sequence diagram, activity diagram, state machine diagram
|
|
317
|
+
|
|
318
|
+
Development View (code organization — how the system is BUILT):
|
|
319
|
+
Audience: developers, build engineers
|
|
320
|
+
Shows: Module/package organization, build dependencies, code ownership
|
|
321
|
+
Diagrams: Package diagram, module dependency diagram
|
|
322
|
+
|
|
323
|
+
Deployment View (infrastructure — where the system RUNS):
|
|
324
|
+
Audience: operators, DevOps, architects
|
|
325
|
+
Shows: Mapping of components to physical/virtual infrastructure
|
|
326
|
+
Network topology, hardware, cloud resources
|
|
327
|
+
Diagrams: Deployment diagram, infrastructure diagram
|
|
328
|
+
|
|
329
|
+
Scenarios (+1 view — use cases as validation):
|
|
330
|
+
Audience: all
|
|
331
|
+
Shows: How the 4 views combine for 3-5 key scenarios
|
|
332
|
+
Purpose: Validates that the architecture satisfies the requirements
|
|
333
|
+
Format: Walk-through of a use case across all 4 views
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### arc42 Architecture Documentation Template
|
|
337
|
+
|
|
338
|
+
```
|
|
339
|
+
arc42 is a standard template for architecture documentation:
|
|
340
|
+
|
|
341
|
+
Section 1: Introduction and Goals (quality goals, stakeholders)
|
|
342
|
+
Section 2: Constraints (technical, organizational, regulatory)
|
|
343
|
+
Section 3: System Scope and Context (Context + Container level)
|
|
344
|
+
Section 4: Solution Strategy (key decisions and approach)
|
|
345
|
+
Section 5: Building Block View (component decomposition)
|
|
346
|
+
Section 6: Runtime View (sequence/activity diagrams per scenario)
|
|
347
|
+
Section 7: Deployment View (infrastructure and deployment)
|
|
348
|
+
Section 8: Cross-Cutting Concepts (patterns applied system-wide)
|
|
349
|
+
Section 9: Architecture Decisions (ADR list)
|
|
350
|
+
Section 10: Quality Requirements (QAS)
|
|
351
|
+
Section 11: Risks and Technical Debt
|
|
352
|
+
Section 12: Glossary
|
|
353
|
+
|
|
354
|
+
Use: templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md (follows this structure)
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
### Architecture Decision Records (ADR)
|
|
358
|
+
|
|
359
|
+
```
|
|
360
|
+
Every significant architectural decision must be recorded in an ADR.
|
|
361
|
+
ADRs are permanent — even when superseded, they document WHY the change was made.
|
|
362
|
+
|
|
363
|
+
When to write an ADR:
|
|
364
|
+
- Choosing between 2+ viable architectural approaches
|
|
365
|
+
- Technology choice with significant implications
|
|
366
|
+
- Trade-off decision affecting multiple quality attributes
|
|
367
|
+
- Decision that will be hard to reverse
|
|
368
|
+
- Decision that future engineers will question
|
|
369
|
+
|
|
370
|
+
ADR content:
|
|
371
|
+
Title: Short phrase naming the decision
|
|
372
|
+
Context: Problem and forces at play
|
|
373
|
+
Decision: What was decided
|
|
374
|
+
Status: Proposed / Accepted / Deprecated / Superseded
|
|
375
|
+
Rationale: Why this option was chosen (cite quality attributes, constraints)
|
|
376
|
+
Options: Alternatives considered (with pros/cons)
|
|
377
|
+
Consequences: Positive and negative results of the decision
|
|
378
|
+
|
|
379
|
+
Use: adr-writer.skill and templates/architecture/ADR_TEMPLATE.md
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
---
|
|
383
|
+
|
|
384
|
+
## Architecture Review (ATAM-Lite)
|
|
385
|
+
|
|
386
|
+
```
|
|
387
|
+
Architecture Tradeoff Analysis Method (ATAM) — adapted for single-team use:
|
|
388
|
+
|
|
389
|
+
1. Understand the architecture:
|
|
390
|
+
- What style was chosen and why?
|
|
391
|
+
- What are the major components?
|
|
392
|
+
- How do they interact?
|
|
393
|
+
|
|
394
|
+
2. Enumerate quality attribute scenarios (QAS):
|
|
395
|
+
- Collect QAS from requirements and stakeholders
|
|
396
|
+
- Prioritize top 5-10
|
|
397
|
+
|
|
398
|
+
3. Analyze architectural approaches:
|
|
399
|
+
- For each QAS: does the architecture satisfy it?
|
|
400
|
+
- Identify sensitivity points (decisions with high leverage)
|
|
401
|
+
- Identify tradeoff points (decisions affecting competing QAS)
|
|
402
|
+
|
|
403
|
+
4. Identify risks and non-risks:
|
|
404
|
+
- Risk: a decision that may lead to a QAS violation
|
|
405
|
+
- Non-risk: a well-reasoned decision
|
|
406
|
+
|
|
407
|
+
5. Create fitness functions:
|
|
408
|
+
- Automated checks that verify architecture health over time
|
|
409
|
+
- Add to CI pipeline
|
|
410
|
+
|
|
411
|
+
Use: arch-review.skill and templates/architecture/ARCHITECTURE_REVIEW_TEMPLATE.md
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Common Architecture Anti-Patterns
|
|
417
|
+
|
|
418
|
+
```
|
|
419
|
+
Big Ball of Mud:
|
|
420
|
+
No discernible structure. Everything depends on everything.
|
|
421
|
+
Fix: Define module boundaries; enforce with dependency analysis tools.
|
|
422
|
+
|
|
423
|
+
God Object / God Module:
|
|
424
|
+
One component with too many responsibilities.
|
|
425
|
+
Signal: > 30% of all code in one file/module, or imported by nearly everything.
|
|
426
|
+
Fix: Split by Single Responsibility Principle — one reason to change.
|
|
427
|
+
|
|
428
|
+
Lava Flow:
|
|
429
|
+
Dead code, unused variables, obsolete designs that cannot be removed because
|
|
430
|
+
no one understands what they do or is afraid to touch them.
|
|
431
|
+
Fix: Characterization tests → understand behavior → refactor safely.
|
|
432
|
+
|
|
433
|
+
Inner Platform Effect:
|
|
434
|
+
Building a framework within the system that reimplements existing platform capabilities.
|
|
435
|
+
Fix: Use the platform. Only abstract what you genuinely need to abstract.
|
|
436
|
+
|
|
437
|
+
Accidental Complexity:
|
|
438
|
+
Complexity introduced by the implementation (incidental) rather than inherent
|
|
439
|
+
in the problem (essential).
|
|
440
|
+
Fix: Continuously ask "is this complexity necessary to solve the problem?"
|
|
441
|
+
|
|
442
|
+
Distributed Monolith:
|
|
443
|
+
Multiple services that are so tightly coupled they must be deployed together.
|
|
444
|
+
Worst of both worlds: complexity of distributed systems + coupling of monolith.
|
|
445
|
+
Fix: Establish true independence (separate data stores, independent deployments).
|
|
446
|
+
|
|
447
|
+
Chatty Services:
|
|
448
|
+
Services making many fine-grained synchronous calls to each other.
|
|
449
|
+
Fix: Coarser-grained interfaces; combine related calls; async for non-critical paths.
|
|
450
|
+
|
|
451
|
+
Shared Database Anti-Pattern:
|
|
452
|
+
Multiple services sharing tables in the same database.
|
|
453
|
+
Fix: Each service owns its data; cross-service access via API.
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
---
|
|
457
|
+
|
|
458
|
+
## Fitness Functions — Continuous Architecture Verification
|
|
459
|
+
|
|
460
|
+
```
|
|
461
|
+
A fitness function is a test that verifies an architectural property is maintained.
|
|
462
|
+
Run in CI. Fail the build if the architectural property is violated.
|
|
463
|
+
|
|
464
|
+
Structural fitness functions:
|
|
465
|
+
"No module in [layer A] shall import from [layer B]"
|
|
466
|
+
Tool: dependency-cruiser, deptrac, ArchUnit
|
|
467
|
+
"No circular dependencies"
|
|
468
|
+
Tool: madge --circular
|
|
469
|
+
"No class/module with cyclomatic complexity > 10"
|
|
470
|
+
Tool: SonarQube, complexity-report
|
|
471
|
+
|
|
472
|
+
Behavioral fitness functions:
|
|
473
|
+
"All public API endpoints respond within [N]ms at [load]"
|
|
474
|
+
Tool: load test in CI (k6, Gatling)
|
|
475
|
+
"Test coverage never falls below [N]%"
|
|
476
|
+
Tool: coverage reporter in CI
|
|
477
|
+
|
|
478
|
+
Security fitness functions:
|
|
479
|
+
"No high/critical dependency CVEs"
|
|
480
|
+
Tool: npm audit, Snyk in CI
|
|
481
|
+
"No secrets in codebase"
|
|
482
|
+
Tool: gitleaks pre-commit hook
|
|
483
|
+
|
|
484
|
+
Define fitness functions for every identified architecture RISK.
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
---
|
|
488
|
+
|
|
489
|
+
## Checklist: Is the Architecture Ready for Implementation?
|
|
490
|
+
|
|
491
|
+
```
|
|
492
|
+
□ Quality attributes prioritized (top 5 with measurable QAS)
|
|
493
|
+
□ Architecture style selected with documented rationale (ADR)
|
|
494
|
+
□ System context established (C4 Level 1 — actors and external systems)
|
|
495
|
+
□ Container decomposition complete (C4 Level 2)
|
|
496
|
+
□ Component view for complex containers (C4 Level 3)
|
|
497
|
+
□ All component interfaces documented
|
|
498
|
+
□ Key scenarios as sequence diagrams (at least 3)
|
|
499
|
+
□ Deployment view documented
|
|
500
|
+
□ Security architecture documented
|
|
501
|
+
□ At least one ADR per major decision
|
|
502
|
+
□ Architecture reviewed against QAS (arch-review.skill)
|
|
503
|
+
□ Risks identified and mitigation strategies defined
|
|
504
|
+
□ Fitness functions defined for architecture risks
|
|
505
|
+
□ Human approval obtained (S02 gate)
|
|
506
|
+
```
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Semantic Web & Meta-Knowledge Guide
|
|
2
|
+
|
|
3
|
+
## 1. Introduction
|
|
4
|
+
The Semantic Web (Web 3.0 W3C standards, not to be confused with crypto-Web3) provides a common framework that allows data to be shared and reused across application, enterprise, and community boundaries. It enables the creation of Enterprise Knowledge Graphs (EKGs) that machines and AI agents can query and reason over.
|
|
5
|
+
|
|
6
|
+
## 2. Core Technologies
|
|
7
|
+
Rather than storing data in isolated tables (Relational DBs) or documents (NoSQL), Semantic Web technologies store data as a graph of facts.
|
|
8
|
+
|
|
9
|
+
- **RDF (Resource Description Framework)**: The base data model. Data is stored in "Triples" defining a Subject, Predicate, and Object (e.g., `Employee_123` -> `worksFor` -> `Engineering`).
|
|
10
|
+
- **OWL (Web Ontology Language)**: The schema layer. It defines classes, properties, and relationships. It allows for logical deduction (e.g., if X is a Manager of Y, and Y works in Z, then X represents Z).
|
|
11
|
+
- **SPARQL**: The query language for RDF graphs (similar to SQL for relational data).
|
|
12
|
+
|
|
13
|
+
## 3. Why Use It?
|
|
14
|
+
1. **Data Silo Elimination**: Merging two relational databases requires complex ETL schemas. Merging two RDF graphs simply requires joining the identical URIs.
|
|
15
|
+
2. **AI Interoperability**: AI Agents (via MCP or A2A) require context. A semantic knowledge graph provides perfectly clean, relationship-mapped context for LLMs, eliminating hallucination in RAG deployments (GraphRAG).
|
|
16
|
+
3. **Inference**: Reasoners can infer new facts without them being explicitly stated in the database.
|
|
17
|
+
|
|
18
|
+
## 4. Ontological Design Principles
|
|
19
|
+
- **Reusability**: Never invent a new property if an existing standard exists. Use `schema.org` for common entities (Person, Organization), `FOAF` for social structures, and `Dublin Core` for document metadata.
|
|
20
|
+
- **URIs as Identifiers**: Every entity and property is a Unique Resource Identifier (URI), ensuring global uniqueness.
|
|
21
|
+
|
|
22
|
+
## 5. Agentic Implementation
|
|
23
|
+
Invoke the `semantic-web` skill when designing complex AI knowledge retrieval mechanisms or when unifying large enterprise datasets. Unstructured data (text/PDFs) is first parsed by an agent, transformed into RDF triples based on the `ONTOLOGY_TEMPLATE.md`, and stored in a Triplestore/Graph Database (like Neo4j or Amazon Neptune).
|