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,56 @@
|
|
|
1
|
+
# Node.js & Advanced TypeScript Mastery
|
|
2
|
+
|
|
3
|
+
> **Source Origin**: Distilled from Matteo Collina's expert capabilities (`fastify`, `nodejs-core`, `typescript-magician`, `node`, `oauth`, `linting-neostandard-eslint9`).
|
|
4
|
+
|
|
5
|
+
This guide enforces the highest tier of architecture, performance, and type-safety standards for Node.js development in the GABBE environment.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Fastify & Architecture Best Practices
|
|
10
|
+
|
|
11
|
+
Fastify is optimized for speed and low overhead. When working with Fastify:
|
|
12
|
+
|
|
13
|
+
- **Encapsulation**: Leverage Fastify's plugin system (`fastify-plugin`) to logically separate routes, decorators, and hooks. Never attach global state tightly.
|
|
14
|
+
- **Schema-First Design**: Always define JSON Schemas (`typebox` or `fluent-json-schema`) for route validation (body, querystring, params, headers) and serialization (response). Fastify compiles these to highly optimized code.
|
|
15
|
+
- **Async/Await Hooks**: Utilize `onRequest`, `preParsing`, `preValidation`, `preHandler`, etc., avoiding legacy callbacks.
|
|
16
|
+
- **Inject Testing**: Test HTTP completely in-memory using `app.inject()`. Never run a live server on a port for unit or integration testing of route handlers.
|
|
17
|
+
- **Logging**: Use `pino` (Fastify's default). Avoid `console.log` in production routines.
|
|
18
|
+
- **Error Handling**: Create centralized custom error handlers (`fastify.setErrorHandler`). Do not leak stack traces in 5xx HTTP responses.
|
|
19
|
+
|
|
20
|
+
## 2. Node.js Core & Internals
|
|
21
|
+
|
|
22
|
+
Deep structural knowledge is critical for scaling.
|
|
23
|
+
|
|
24
|
+
- **Event Loop Mechanics**: Understand the phases (timers, pending callbacks, idle/prepare, poll, check, close callbacks). Do not block the event loop (avoid `fs.readFileSync` or CPU-heavy sync crypto).
|
|
25
|
+
- **Worker Threads**: Use `worker_threads` for CPU-bound tasks, not for I/O. Use `SharedArrayBuffer` with `Atomics` for high-performance intra-thread communication.
|
|
26
|
+
- **V8 & Memory Management**:
|
|
27
|
+
- Keep object shapes (hidden classes) stable to enable V8 TurboFan optimizations (Inline Caching).
|
|
28
|
+
- Avoid memory leaks by managing closures properly and nullifying large unused references.
|
|
29
|
+
- Use `v8` heap snapshots and `llnode` or Chrome DevTools for native memory analysis.
|
|
30
|
+
- **Native Addons**: When writing C++ addons, always use `N-API` (`node-addon-api`) to achieve ABI stability across Node versions. Mind memory transitions across the JS/C++ boundary.
|
|
31
|
+
- **Streams**: Favor the Pipeline API (`stream/promises`) for backpressure management instead of `.pipe()`.
|
|
32
|
+
|
|
33
|
+
## 3. TypeScript "Magician" Level (Zero `any`)
|
|
34
|
+
|
|
35
|
+
TypeScript is a superpower, not a constraint. `any` must be completely eradicated.
|
|
36
|
+
|
|
37
|
+
- **No `any`**: If a type is unknown at runtime, use `unknown` and narrow it via type guards (`typeof`, `instanceof`, or custom type predicates like `isMyType(val: unknown): val is MyType`).
|
|
38
|
+
- **Advanced Generics**: Leverage generic constraints (`T extends B`), conditional types (`T extends U ? X : Y`), and `infer` keyword to pull types out of complex structures.
|
|
39
|
+
- **Utility Types**: Master `Awaited<T>`, `Parameters<T>`, `ReturnType<T>`, `Record<K, V>`, `Omit<T, K>`, and `Pick<T, K>`.
|
|
40
|
+
- **Mapped & Template Literal Types**: Use `[K in keyof T]: ...` and `\${string}_\${string}` for stringent state modeling.
|
|
41
|
+
- **Discriminated Unions**: Model states explicitly (e.g., `{ status: 'success', data: Data } | { status: 'error', error: Error }`) rather than optional properties.
|
|
42
|
+
- **Opaque / Brand Types**: Differentiate simple primitives (like IDs) logically at compile time (e.g., `type UserId = string & { readonly __brand: unique symbol }`).
|
|
43
|
+
|
|
44
|
+
## 4. OAuth & Security Workflow
|
|
45
|
+
|
|
46
|
+
- **Strict RFC Compliance**: Strictly implement OAuth 2.0/2.1 flows (PKCE for SPAs/mobile, Client Credentials for machine-to-machine).
|
|
47
|
+
- **Token Handling**: Never store access tokens in `localStorage`. Use secure, `HttpOnly`, `SameSite=Strict` cookies or transient in-memory states.
|
|
48
|
+
- **Validation**: Validate all JWT scopes, audiences (`aud`), and issuers (`iss`) at the API edge natively through Fastify hooks.
|
|
49
|
+
|
|
50
|
+
## 5. Modern Linting
|
|
51
|
+
|
|
52
|
+
- **ESLint v9 + Neostandard**: Utilize Flat Config (`eslint.config.js`).
|
|
53
|
+
- Enforce stylistic guarantees automatically and treat linting issues as build failures (warnings are errors in CI).
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
*For AI Agents: By reading this guide, you are contractually bound under the project CONSTITUTION.md to enforce strict typing (zero any), Fastify schemas, and non-blocking I/O.*
|
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
# Guide: PHP / Laravel
|
|
2
|
+
<!-- DDD with Laravel, Actions pattern, Pest PHP, PHPStan Level 9 -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Directory Structure — DDD + Actions Pattern
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
app/
|
|
10
|
+
Domain/ # Business logic — NO Laravel imports
|
|
11
|
+
User/
|
|
12
|
+
Entities/
|
|
13
|
+
User.php # Domain entity with invariants
|
|
14
|
+
ValueObjects/
|
|
15
|
+
Email.php # Typed value object
|
|
16
|
+
UserId.php
|
|
17
|
+
Events/
|
|
18
|
+
UserRegistered.php # Domain event
|
|
19
|
+
Repositories/
|
|
20
|
+
IUserRepository.php # Interface — implemented in Infrastructure
|
|
21
|
+
Exceptions/
|
|
22
|
+
EmailAlreadyExistsException.php
|
|
23
|
+
|
|
24
|
+
Application/ # Orchestrates domain — Actions pattern
|
|
25
|
+
User/
|
|
26
|
+
CreateUser/
|
|
27
|
+
CreateUserAction.php # Single-responsibility action
|
|
28
|
+
CreateUserData.php # Typed DTO (Spatie Laravel Data)
|
|
29
|
+
CreateUserResult.php # Return DTO
|
|
30
|
+
GetUser/
|
|
31
|
+
GetUserAction.php
|
|
32
|
+
|
|
33
|
+
Infrastructure/ # Laravel implementations
|
|
34
|
+
Database/
|
|
35
|
+
User/
|
|
36
|
+
EloquentUserRepository.php # Implements IUserRepository
|
|
37
|
+
UserModel.php # Eloquent model (infrastructure concern)
|
|
38
|
+
Migrations/
|
|
39
|
+
Mail/
|
|
40
|
+
WelcomeEmail.php
|
|
41
|
+
Queue/
|
|
42
|
+
SendWelcomeEmailJob.php
|
|
43
|
+
|
|
44
|
+
Http/ # Laravel HTTP layer — thin
|
|
45
|
+
Controllers/
|
|
46
|
+
Api/
|
|
47
|
+
UserController.php # Delegates to Application layer actions
|
|
48
|
+
Requests/
|
|
49
|
+
CreateUserRequest.php # FormRequest validation
|
|
50
|
+
Resources/
|
|
51
|
+
UserResource.php # API response formatting (JsonResource)
|
|
52
|
+
|
|
53
|
+
tests/
|
|
54
|
+
Unit/ # Domain + Application tests (no DB)
|
|
55
|
+
Feature/ # HTTP + Database tests (RefreshDatabase)
|
|
56
|
+
Browser/ # Dusk browser tests (or Pest Browser)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## AGENTS.md Snippet (Laravel project)
|
|
62
|
+
|
|
63
|
+
```yaml
|
|
64
|
+
runtime: PHP 8.4 # 8.5 current stable (verified 2026-06)
|
|
65
|
+
language: PHP (typed, strict)
|
|
66
|
+
framework: Laravel 12.x # min PHP 8.2
|
|
67
|
+
package_manager: Composer 2.x
|
|
68
|
+
|
|
69
|
+
install: composer install
|
|
70
|
+
dev: php artisan serve
|
|
71
|
+
test: php artisan test
|
|
72
|
+
test_coverage: php artisan test --coverage
|
|
73
|
+
test_single: vendor/bin/pest tests/Unit/Domain/UserTest.php
|
|
74
|
+
build: composer install --no-dev --optimize-autoloader
|
|
75
|
+
typecheck: vendor/bin/phpstan analyse --level=9
|
|
76
|
+
lint: vendor/bin/pint --test
|
|
77
|
+
format: vendor/bin/pint
|
|
78
|
+
security_scan: composer audit
|
|
79
|
+
migrate: php artisan migrate
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Tech Stack
|
|
85
|
+
|
|
86
|
+
### Core
|
|
87
|
+
| Role | Library | Why |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| Framework | Laravel 12.x | Full-stack, mature ecosystem (min PHP 8.2) |
|
|
90
|
+
| DTOs | `spatie/laravel-data` | Typed DTOs with casting + validation |
|
|
91
|
+
| State Machine | `spatie/laravel-model-states` | Enum-like states with transitions |
|
|
92
|
+
| Query Builder | Eloquent (with Spatie QueryBuilder) | Flexible, typed |
|
|
93
|
+
| API docs | Scribe (`knuckleswtf/scribe`) | Auto-generates from controllers |
|
|
94
|
+
|
|
95
|
+
### Testing
|
|
96
|
+
| Role | Library | Command |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| Unit + Feature | Pest PHP | `php artisan test` or `vendor/bin/pest` |
|
|
99
|
+
| Browser | Pest Browser plugin or Laravel Dusk | `php artisan dusk` |
|
|
100
|
+
| Coverage | Xdebug + PCOV | `php artisan test --coverage` |
|
|
101
|
+
| HTTP mocking | Laravel's `Http::fake()` | Built-in |
|
|
102
|
+
|
|
103
|
+
### Security
|
|
104
|
+
| Role | Library | Command |
|
|
105
|
+
|---|---|---|
|
|
106
|
+
| Dep audit | `composer audit` | Built-in Composer 2.4+ |
|
|
107
|
+
| SAST/Security | Enlightn | `php artisan enlightn` |
|
|
108
|
+
| Static analysis | PHPStan Level 9 | `vendor/bin/phpstan analyse` |
|
|
109
|
+
| Vulnerability db | `roave/security-advisories` | Added to composer.json (blocks installs) |
|
|
110
|
+
| Secret detection | gitleaks | `gitleaks detect --source=.` |
|
|
111
|
+
| Architecture | deptrac | `vendor/bin/deptrac analyse` |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Patterns
|
|
116
|
+
|
|
117
|
+
### Domain Entity
|
|
118
|
+
|
|
119
|
+
```php
|
|
120
|
+
// app/Domain/User/Entities/User.php
|
|
121
|
+
declare(strict_types=1);
|
|
122
|
+
|
|
123
|
+
namespace App\Domain\User\Entities;
|
|
124
|
+
|
|
125
|
+
use App\Domain\User\ValueObjects\Email;
|
|
126
|
+
use App\Domain\User\ValueObjects\UserId;
|
|
127
|
+
use App\Domain\User\Events\UserRegistered;
|
|
128
|
+
|
|
129
|
+
final class User
|
|
130
|
+
{
|
|
131
|
+
/** @var list<object> */
|
|
132
|
+
private array $events = [];
|
|
133
|
+
|
|
134
|
+
private function __construct(
|
|
135
|
+
public readonly UserId $id,
|
|
136
|
+
public readonly Email $email,
|
|
137
|
+
public readonly string $name,
|
|
138
|
+
public readonly \DateTimeImmutable $createdAt,
|
|
139
|
+
) {}
|
|
140
|
+
|
|
141
|
+
public static function create(Email $email, string $name): self
|
|
142
|
+
{
|
|
143
|
+
$user = new self(UserId::generate(), $email, $name, new \DateTimeImmutable());
|
|
144
|
+
$user->events[] = new UserRegistered($user->id->value, $user->email->value);
|
|
145
|
+
return $user;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** @return list<object> */
|
|
149
|
+
public function releaseEvents(): array
|
|
150
|
+
{
|
|
151
|
+
$events = $this->events;
|
|
152
|
+
$this->events = [];
|
|
153
|
+
return $events;
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Value Object
|
|
159
|
+
|
|
160
|
+
```php
|
|
161
|
+
// app/Domain/User/ValueObjects/Email.php
|
|
162
|
+
declare(strict_types=1);
|
|
163
|
+
|
|
164
|
+
namespace App\Domain\User\ValueObjects;
|
|
165
|
+
|
|
166
|
+
use App\Domain\User\Exceptions\InvalidEmailException;
|
|
167
|
+
|
|
168
|
+
final readonly class Email
|
|
169
|
+
{
|
|
170
|
+
public string $value;
|
|
171
|
+
|
|
172
|
+
private function __construct(string $value)
|
|
173
|
+
{
|
|
174
|
+
$this->value = $value;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
public static function create(string $value): self
|
|
178
|
+
{
|
|
179
|
+
if (!filter_var($value, FILTER_VALIDATE_EMAIL) || strlen($value) > 255) {
|
|
180
|
+
throw new InvalidEmailException("Invalid email: {$value}");
|
|
181
|
+
}
|
|
182
|
+
return new self(strtolower(trim($value)));
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
public function equals(self $other): bool
|
|
186
|
+
{
|
|
187
|
+
return $this->value === $other->value;
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Typed DTO (Spatie Laravel Data)
|
|
193
|
+
|
|
194
|
+
```php
|
|
195
|
+
// app/Application/User/CreateUser/CreateUserData.php
|
|
196
|
+
declare(strict_types=1);
|
|
197
|
+
|
|
198
|
+
namespace App\Application\User\CreateUser;
|
|
199
|
+
|
|
200
|
+
use Spatie\LaravelData\Attributes\Validation\Email;
|
|
201
|
+
use Spatie\LaravelData\Attributes\Validation\Max;
|
|
202
|
+
use Spatie\LaravelData\Attributes\Validation\Min;
|
|
203
|
+
use Spatie\LaravelData\Data;
|
|
204
|
+
|
|
205
|
+
final class CreateUserData extends Data
|
|
206
|
+
{
|
|
207
|
+
public function __construct(
|
|
208
|
+
#[Email, Max(255)]
|
|
209
|
+
public readonly string $email,
|
|
210
|
+
|
|
211
|
+
#[Min(1), Max(100)]
|
|
212
|
+
public readonly string $name,
|
|
213
|
+
) {}
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Single-Responsibility Action
|
|
218
|
+
|
|
219
|
+
```php
|
|
220
|
+
// app/Application/User/CreateUser/CreateUserAction.php
|
|
221
|
+
declare(strict_types=1);
|
|
222
|
+
|
|
223
|
+
namespace App\Application\User\CreateUser;
|
|
224
|
+
|
|
225
|
+
use App\Domain\User\Entities\User;
|
|
226
|
+
use App\Domain\User\Repositories\IUserRepository;
|
|
227
|
+
use App\Domain\User\ValueObjects\Email;
|
|
228
|
+
use App\Domain\User\Exceptions\EmailAlreadyExistsException;
|
|
229
|
+
use Illuminate\Contracts\Events\Dispatcher;
|
|
230
|
+
|
|
231
|
+
final class CreateUserAction
|
|
232
|
+
{
|
|
233
|
+
public function __construct(
|
|
234
|
+
private readonly IUserRepository $userRepository,
|
|
235
|
+
private readonly Dispatcher $eventDispatcher,
|
|
236
|
+
) {}
|
|
237
|
+
|
|
238
|
+
public function execute(CreateUserData $data): CreateUserResult
|
|
239
|
+
{
|
|
240
|
+
$email = Email::create($data->email);
|
|
241
|
+
|
|
242
|
+
if ($this->userRepository->findByEmail($email) !== null) {
|
|
243
|
+
throw new EmailAlreadyExistsException($email->value);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
$user = User::create($email, $data->name);
|
|
247
|
+
$this->userRepository->save($user);
|
|
248
|
+
|
|
249
|
+
foreach ($user->releaseEvents() as $event) {
|
|
250
|
+
$this->eventDispatcher->dispatch($event);
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
return new CreateUserResult(id: $user->id->value);
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Thin Controller
|
|
259
|
+
|
|
260
|
+
```php
|
|
261
|
+
// app/Http/Controllers/Api/UserController.php
|
|
262
|
+
declare(strict_types=1);
|
|
263
|
+
|
|
264
|
+
namespace App\Http\Controllers\Api;
|
|
265
|
+
|
|
266
|
+
use App\Application\User\CreateUser\CreateUserAction;
|
|
267
|
+
use App\Application\User\CreateUser\CreateUserData;
|
|
268
|
+
use App\Http\Resources\UserResource;
|
|
269
|
+
use Illuminate\Http\JsonResponse;
|
|
270
|
+
use Illuminate\Http\Request;
|
|
271
|
+
|
|
272
|
+
final class UserController
|
|
273
|
+
{
|
|
274
|
+
public function store(Request $request, CreateUserAction $action): JsonResponse
|
|
275
|
+
{
|
|
276
|
+
$result = $action->execute(CreateUserData::from($request->validated()));
|
|
277
|
+
return response()->json(['id' => $result->id], 201);
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## Security Best Practices
|
|
285
|
+
|
|
286
|
+
```php
|
|
287
|
+
// config/security-headers.php (or via middleware)
|
|
288
|
+
// Use spatie/laravel-csp for Content Security Policy
|
|
289
|
+
|
|
290
|
+
// NEVER: raw user input in queries
|
|
291
|
+
$users = DB::select("SELECT * FROM users WHERE email = '{$request->email}'"); // SQL INJECTION!
|
|
292
|
+
|
|
293
|
+
// CORRECT: Eloquent or parameterized
|
|
294
|
+
$user = User::where('email', $request->email)->first();
|
|
295
|
+
// OR: parameterized
|
|
296
|
+
$users = DB::select('SELECT * FROM users WHERE email = ?', [$request->email]);
|
|
297
|
+
|
|
298
|
+
// Mass assignment protection
|
|
299
|
+
protected $fillable = ['name', 'email']; // Explicit allowlist
|
|
300
|
+
// NEVER: protected $guarded = []; (disables protection)
|
|
301
|
+
|
|
302
|
+
// Rate limiting (in RouteServiceProvider or routes)
|
|
303
|
+
Route::middleware(['throttle:5,1'])->group(function () {
|
|
304
|
+
Route::post('/auth/login', [AuthController::class, 'login']);
|
|
305
|
+
});
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Tech Debt Detection
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
# PHPStan (type safety) — Level 9 is maximum
|
|
314
|
+
vendor/bin/phpstan analyse app/ --level=9
|
|
315
|
+
|
|
316
|
+
# PHP Mess Detector (complexity, duplication)
|
|
317
|
+
vendor/bin/phpmd app/ text cleancode,codesize,controversial,design,naming,unusedcode
|
|
318
|
+
|
|
319
|
+
# PHP Code Sniffer (code style)
|
|
320
|
+
vendor/bin/phpcs --standard=PSR12 app/
|
|
321
|
+
|
|
322
|
+
# Deptrac (architecture layer enforcement)
|
|
323
|
+
vendor/bin/deptrac analyse --config-file deptrac.yaml
|
|
324
|
+
|
|
325
|
+
# Check for outdated dependencies
|
|
326
|
+
composer outdated
|
|
327
|
+
|
|
328
|
+
# Security vulnerabilities
|
|
329
|
+
composer audit
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## deptrac.yaml (Architecture Enforcement)
|
|
335
|
+
|
|
336
|
+
```yaml
|
|
337
|
+
# deptrac.yaml
|
|
338
|
+
parameters:
|
|
339
|
+
paths:
|
|
340
|
+
- ./app
|
|
341
|
+
layers:
|
|
342
|
+
- name: Domain
|
|
343
|
+
collectors:
|
|
344
|
+
- type: directory
|
|
345
|
+
value: Domain/.*
|
|
346
|
+
- name: Application
|
|
347
|
+
collectors:
|
|
348
|
+
- type: directory
|
|
349
|
+
value: Application/.*
|
|
350
|
+
- name: Infrastructure
|
|
351
|
+
collectors:
|
|
352
|
+
- type: directory
|
|
353
|
+
value: Infrastructure/.*
|
|
354
|
+
- name: Http
|
|
355
|
+
collectors:
|
|
356
|
+
- type: directory
|
|
357
|
+
value: Http/.*
|
|
358
|
+
ruleset:
|
|
359
|
+
Domain: # Domain can only depend on itself
|
|
360
|
+
- ~Application
|
|
361
|
+
- ~Infrastructure
|
|
362
|
+
- ~Http
|
|
363
|
+
Application: # Application can use Domain
|
|
364
|
+
- Domain
|
|
365
|
+
Infrastructure: # Infrastructure implements Domain interfaces
|
|
366
|
+
- Domain
|
|
367
|
+
Http: # HTTP can use Application (not Domain directly)
|
|
368
|
+
- Application
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
## See Also
|
|
374
|
+
- [Performant Laravel Skill](../../skills/coding/performant-laravel.skill.md) — High-performance Laravel.
|
|
375
|
+
- [Artisan Commands Skill](../../skills/coding/artisan-commands.skill.md) — Laravel task automation.
|
|
376
|
+
- [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — OWASP Top 10 for Laravel.
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# Guide: Python / FastAPI / AI
|
|
2
|
+
<!-- Clean Architecture with Python 3.12+, FastAPI, SQLAlchemy, Pydantic, and AI Agents -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Directory Structure — Clean Architecture
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
src/
|
|
10
|
+
domain/ # Pure business logic — NO framework imports
|
|
11
|
+
entities/ # user.py, order.py — domain entities (Pydantic/Dataclasses)
|
|
12
|
+
value_objects/ # email.py, money.py — immutable primitives
|
|
13
|
+
events/ # user_registered.py — domain events
|
|
14
|
+
ports/ # i_user_repository.py — interfaces only (Protocol)
|
|
15
|
+
exceptions/ # domain_error.py — base exceptions
|
|
16
|
+
services/ # Pure domain services
|
|
17
|
+
|
|
18
|
+
application/ # Use cases — orchestrates domain
|
|
19
|
+
users/
|
|
20
|
+
create_user_use_case.py
|
|
21
|
+
create_user_command.py
|
|
22
|
+
create_user_result.py
|
|
23
|
+
|
|
24
|
+
adapters/ # Interface adapters
|
|
25
|
+
api/ # FastAPI routers & controllers
|
|
26
|
+
users_router.py
|
|
27
|
+
users_schema.py # Pydantic schemas for request/response
|
|
28
|
+
presenters/ # Formatters
|
|
29
|
+
|
|
30
|
+
infrastructure/ # Framework + external services
|
|
31
|
+
database/
|
|
32
|
+
sqlalchemy_user_repository.py
|
|
33
|
+
llm/ # AI Model implementations
|
|
34
|
+
openai_service.py
|
|
35
|
+
langchain_adapter.py
|
|
36
|
+
vector_store/
|
|
37
|
+
qdrant_service.py
|
|
38
|
+
|
|
39
|
+
main/ # Composition root
|
|
40
|
+
container.py # Dependency Injection (Dependency Injector or fast_depends)
|
|
41
|
+
main.py # FastAPI app entrypoint
|
|
42
|
+
|
|
43
|
+
tests/
|
|
44
|
+
unit/ # Fast, no I/O
|
|
45
|
+
integration/ # Docker containers (Testcontainers)
|
|
46
|
+
e2e/ # Full API tests
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Layer Import Rules
|
|
52
|
+
|
|
53
|
+
```python
|
|
54
|
+
# domain/ — MUST NOT import from any other layer
|
|
55
|
+
# application/ — MAY import from domain only
|
|
56
|
+
# adapters/ — MAY import from domain + application
|
|
57
|
+
# infrastructure/ — MAY import from domain (implements interfaces)
|
|
58
|
+
# main/ — MAY import from all layers (composition root)
|
|
59
|
+
|
|
60
|
+
# CORRECT: infrastructure depends on domain interface
|
|
61
|
+
from src.domain.ports.i_user_repository import IUserRepository
|
|
62
|
+
|
|
63
|
+
# WRONG: domain depending on infrastructure
|
|
64
|
+
from src.infrastructure.database.models import UserModel # NEVER in domain
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**Enforce with:** `import-linter`
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## AGENTS.md Snippet (Python Project)
|
|
72
|
+
|
|
73
|
+
```yaml
|
|
74
|
+
runtime: Python 3.12+
|
|
75
|
+
language: Python (Strict Typing)
|
|
76
|
+
framework: FastAPI
|
|
77
|
+
package_manager: uv (preferred) | poetry
|
|
78
|
+
|
|
79
|
+
install: uv sync
|
|
80
|
+
dev: uv run fastapi dev src/main/main.py
|
|
81
|
+
test: uv run pytest
|
|
82
|
+
test_coverage: uv run pytest --cov=src
|
|
83
|
+
test_single: uv run pytest tests/path/to/test.py
|
|
84
|
+
typecheck: uv run mypy src
|
|
85
|
+
lint: uv run ruff check src
|
|
86
|
+
format: uv run ruff format src
|
|
87
|
+
security_scan: uv run bandit -r src
|
|
88
|
+
migrate: uv run alembic upgrade head
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Tech Stack
|
|
94
|
+
|
|
95
|
+
### Core
|
|
96
|
+
| Role | Library | Why |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| Runtime | Python 3.12+ | Performance improvements, better typing |
|
|
99
|
+
| Web Framework | FastAPI | Async, Pydantic integration, auto-docs |
|
|
100
|
+
| Validation | Pydantic v2 | Rust-based speed, strict validation |
|
|
101
|
+
| ORM | SQLAlchemy 2.0 | Async support, robust |
|
|
102
|
+
| Dependency Inj. | `fast_depends` / `dishka` | Decoupling layers |
|
|
103
|
+
|
|
104
|
+
### AI / Agentic
|
|
105
|
+
| Role | Library | Why |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| Orchestration | LangChain / LangGraph | State management, tool calling |
|
|
108
|
+
| LLM Client | `openai` / `anthropic` | Official SDKs |
|
|
109
|
+
| Vector DB | Qdrant / Chroma | Efficient similarity search |
|
|
110
|
+
| Evaluation | Ragas / DeepEval | RAG pipeline evaluation |
|
|
111
|
+
| Tracing | LangSmith / Arize Phoenix | Observability for chains |
|
|
112
|
+
|
|
113
|
+
### Testing & Quality
|
|
114
|
+
| Role | Library | Command |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| Test Runner | Pytest | `pytest` |
|
|
117
|
+
| Integration | Testcontainers | Real DB/service tests in Docker |
|
|
118
|
+
| Linting | Ruff | `ruff check` (Replacing Flake8/Isort) |
|
|
119
|
+
| Type Checking | Mypy | `mypy --strict` |
|
|
120
|
+
| Mutation Test | Mutmut | Verify test quality |
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Patterns
|
|
125
|
+
|
|
126
|
+
### Domain Entity (Pydantic v2)
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
# src/domain/entities/user.py
|
|
130
|
+
from pydantic import BaseModel, Field, EmailStr
|
|
131
|
+
from uuid import UUID, uuid4
|
|
132
|
+
from datetime import datetime
|
|
133
|
+
|
|
134
|
+
class User(BaseModel):
|
|
135
|
+
id: UUID = Field(default_factory=uuid4)
|
|
136
|
+
email: EmailStr
|
|
137
|
+
name: str = Field(min_length=1)
|
|
138
|
+
created_at: datetime = Field(default_factory=datetime.now)
|
|
139
|
+
|
|
140
|
+
class Config:
|
|
141
|
+
frozen = True # Immutable pattern
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Protocol (Interface)
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
# src/domain/ports/i_user_repository.py
|
|
148
|
+
from typing import Protocol
|
|
149
|
+
from src.domain.entities.user import User
|
|
150
|
+
|
|
151
|
+
class IUserRepository(Protocol):
|
|
152
|
+
async def save(self, user: User) -> None:
|
|
153
|
+
...
|
|
154
|
+
|
|
155
|
+
async def find_by_email(self, email: str) -> User | None:
|
|
156
|
+
...
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Use Case
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
# src/application/users/create_user_use_case.py
|
|
163
|
+
from dataclasses import dataclass
|
|
164
|
+
from src.domain.ports.i_user_repository import IUserRepository
|
|
165
|
+
from src.domain.entities.user import User
|
|
166
|
+
|
|
167
|
+
@dataclass
|
|
168
|
+
class CreateUserCommand:
|
|
169
|
+
email: str
|
|
170
|
+
name: str
|
|
171
|
+
|
|
172
|
+
class CreateUserUseCase:
|
|
173
|
+
def __init__(self, repo: IUserRepository):
|
|
174
|
+
self.repo = repo
|
|
175
|
+
|
|
176
|
+
async def execute(self, command: CreateUserCommand) -> User:
|
|
177
|
+
# Business rules
|
|
178
|
+
existing = await self.repo.find_by_email(command.email)
|
|
179
|
+
if existing:
|
|
180
|
+
raise ValueError("Email already exists")
|
|
181
|
+
|
|
182
|
+
user = User(email=command.email, name=command.name)
|
|
183
|
+
await self.repo.save(user)
|
|
184
|
+
return user
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### FastAPI Router (Adapter)
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
# src/adapters/api/users_router.py
|
|
191
|
+
from fastapi import APIRouter, Depends
|
|
192
|
+
from typing import Annotated
|
|
193
|
+
from src.main.container import get_create_user_use_case
|
|
194
|
+
from src.application.users.create_user_use_case import CreateUserUseCase, CreateUserCommand
|
|
195
|
+
|
|
196
|
+
router = APIRouter()
|
|
197
|
+
|
|
198
|
+
@router.post("/users")
|
|
199
|
+
async def create_user(
|
|
200
|
+
cmd: CreateUserCommand,
|
|
201
|
+
use_case: Annotated[CreateUserUseCase, Depends(get_create_user_use_case)]
|
|
202
|
+
):
|
|
203
|
+
try:
|
|
204
|
+
user = await use_case.execute(cmd)
|
|
205
|
+
return {"id": str(user.id), "email": user.email}
|
|
206
|
+
except ValueError as e:
|
|
207
|
+
return {"error": str(e)}, 400
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## AI Agent Specifics
|
|
213
|
+
|
|
214
|
+
### Tool Definition Pattern
|
|
215
|
+
When exposing tools to LLMs (Function Calling):
|
|
216
|
+
|
|
217
|
+
```python
|
|
218
|
+
# src/infrastructure/llm/tools/calculator.py
|
|
219
|
+
from pydantic import BaseModel, Field
|
|
220
|
+
from typing import Callable
|
|
221
|
+
|
|
222
|
+
class AddInput(BaseModel):
|
|
223
|
+
a: int = Field(..., description="First number")
|
|
224
|
+
b: int = Field(..., description="Second number")
|
|
225
|
+
|
|
226
|
+
def add(a: int, b: int) -> int:
|
|
227
|
+
"""Adds two numbers."""
|
|
228
|
+
return a + b
|
|
229
|
+
|
|
230
|
+
# LangChain / OpenAI format
|
|
231
|
+
tool_definition = {
|
|
232
|
+
"type": "function",
|
|
233
|
+
"function": {
|
|
234
|
+
"name": "add",
|
|
235
|
+
"description": "Adds two numbers",
|
|
236
|
+
"parameters": AddInput.model_json_schema()
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### RAG implementation Tip
|
|
242
|
+
Keep embedding logic in `infrastructure`:
|
|
243
|
+
|
|
244
|
+
```python
|
|
245
|
+
# src/infrastructure/vector_store/qdrant_service.py
|
|
246
|
+
class QdrantRetrievalService(IRetrievalService):
|
|
247
|
+
def __init__(self, client: QdrantClient, verify_ssl: bool = True):
|
|
248
|
+
self.client = client
|
|
249
|
+
# ... implementation details ...
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## See Also
|
|
255
|
+
- [Performant Python Skill](../../skills/coding/performant-python.skill.md) — FastAPI & Async optimization.
|
|
256
|
+
- [Performant AI Skill](../../skills/coding/performant-ai.skill.md) — LLM context & cost management.
|
|
257
|
+
- [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — Hardening Python APIs.
|