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,251 @@
|
|
|
1
|
+
# Guide: Go (Golang)
|
|
2
|
+
<!-- Idiomatic Go, Clean Architecture, Echo/Gin, Ent, Testify, Testcontainers -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Directory Structure — Standard Go Layout (2026)
|
|
7
|
+
|
|
8
|
+
Adheres to `golang-standards/project-layout` but adapted for Agentic Engineering.
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
cmd/
|
|
12
|
+
api/
|
|
13
|
+
main.go # Entry point (DI container, server start)
|
|
14
|
+
worker/
|
|
15
|
+
main.go # Background worker entry point
|
|
16
|
+
|
|
17
|
+
internal/ # Private application code (Library pattern)
|
|
18
|
+
domain/ # Pure business logic (structs, interfaces)
|
|
19
|
+
user.go # User struct & Repository interfaces
|
|
20
|
+
order.go
|
|
21
|
+
errors.go # Domain errors
|
|
22
|
+
|
|
23
|
+
service/ # Application Logic (Use Cases)
|
|
24
|
+
user_service.go # Orchestrate domain + database
|
|
25
|
+
order_service.go
|
|
26
|
+
|
|
27
|
+
adapter/ # Interface Adapters (Driven & Driving)
|
|
28
|
+
handler/
|
|
29
|
+
http/ # HTTP Handlers (Echo/Gin)
|
|
30
|
+
user_handler.go
|
|
31
|
+
repository/
|
|
32
|
+
ent/ # Ent ORM implementation
|
|
33
|
+
schema/ # Database Schema Definitions
|
|
34
|
+
grpc/ # gRPC implementation
|
|
35
|
+
|
|
36
|
+
config/ # Configuration struct (Viper/Env)
|
|
37
|
+
|
|
38
|
+
pkg/ # Public sharable libraries (Optional)
|
|
39
|
+
logger/ # structured logger (slog/zap)
|
|
40
|
+
utils/
|
|
41
|
+
|
|
42
|
+
tests/
|
|
43
|
+
integration/ # Testcontainers integration tests
|
|
44
|
+
e2e/ # End-to-End API tests
|
|
45
|
+
|
|
46
|
+
go.mod
|
|
47
|
+
go.sum
|
|
48
|
+
Makefile
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Dependency Rules (Idiomatic)
|
|
54
|
+
|
|
55
|
+
```go
|
|
56
|
+
// internal/domain CANNOT import internal/adapter or internal/service
|
|
57
|
+
// internal/service CAN import internal/domain
|
|
58
|
+
// internal/adapter CAN import internal/domain AND internal/service
|
|
59
|
+
// cmd/api CAN import everything (Composition Root)
|
|
60
|
+
|
|
61
|
+
// CORRECT: Service depends on Repository Interface
|
|
62
|
+
type UseCase struct {
|
|
63
|
+
Repo domain.UserRepository
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// WRONG: Service depends on Ent implementation directly
|
|
67
|
+
type UseCase struct {
|
|
68
|
+
Repo *ent.Client // Avoid this coupling in Service layer
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## AGENTS.md Snippet (Go project)
|
|
75
|
+
|
|
76
|
+
```yaml
|
|
77
|
+
runtime: Go 1.25+
|
|
78
|
+
language: Go (Strict Linting)
|
|
79
|
+
framework: Echo v4 / Standard Lib
|
|
80
|
+
package_manager: go mod
|
|
81
|
+
|
|
82
|
+
install: go mod download
|
|
83
|
+
dev: air # Live reload
|
|
84
|
+
test: go test -v ./...
|
|
85
|
+
test_coverage: go test -coverprofile=coverage.out ./...
|
|
86
|
+
test_single: go test -v ./internal/service/user_service_test.go
|
|
87
|
+
build: go build -o bin/api cmd/api/main.go
|
|
88
|
+
lint: golangci-lint run
|
|
89
|
+
format: gofumpt -w .
|
|
90
|
+
security_scan: govulncheck ./...
|
|
91
|
+
migrate: go run -mod=mod entgo.io/ent/cmd/ent generate ./internal/adapter/repository/ent/schema
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Tech Stack (2026 Recommended)
|
|
97
|
+
|
|
98
|
+
### Core
|
|
99
|
+
| Role | Library | Why |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| Runtime | Go 1.25+ | Generic improvements, range-over-func |
|
|
102
|
+
| HTTP Framework | **Echo** / **Fiber** | Fast, robust middleware, idiomatic context |
|
|
103
|
+
| Router | **Chi** | If employing Standard Lib only (lightweight) |
|
|
104
|
+
| ORM / Data | **Ent** | Type-safe graph, code-generation, great for Agents |
|
|
105
|
+
| Config | **Koanf** / Viper | Modern configuration management |
|
|
106
|
+
| Logging | **Slog** (Std Lib) | Structured logging is now built-in |
|
|
107
|
+
|
|
108
|
+
### Testing
|
|
109
|
+
| Role | Library | Command |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| Assertions | **Testify** | `assert.Equal(t, expected, actual)` |
|
|
112
|
+
| BDD (Optional) | **Ginkgo** | For complex behavior specs |
|
|
113
|
+
| Integration DB | **Testcontainers** | Real Docker Postgres in tests |
|
|
114
|
+
| Mocks | **Mockery** | Generate mocks for interfaces |
|
|
115
|
+
|
|
116
|
+
### Security & Quality
|
|
117
|
+
| Role | Library | Command |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| Linter | `golangci-lint` | `golangci-lint run` (Aggressive preset) |
|
|
120
|
+
| Vuln Scan | `govulncheck` | Native Go vulnerability DB checker |
|
|
121
|
+
| API Docs | `swag` | Generate OpenAPI from comments |
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Code Patterns
|
|
126
|
+
|
|
127
|
+
### 1. Domain Entity (Rich Model)
|
|
128
|
+
|
|
129
|
+
```go
|
|
130
|
+
// internal/domain/user.go
|
|
131
|
+
package domain
|
|
132
|
+
|
|
133
|
+
import "errors"
|
|
134
|
+
|
|
135
|
+
var ErrInvalidEmail = errors.New("invalid email domain")
|
|
136
|
+
|
|
137
|
+
type User struct {
|
|
138
|
+
ID string
|
|
139
|
+
Name string
|
|
140
|
+
Email string
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
// Business Rules can live here
|
|
144
|
+
func NewUser(id, name, email string) (*User, error) {
|
|
145
|
+
if email == "" {
|
|
146
|
+
return nil, ErrInvalidEmail
|
|
147
|
+
}
|
|
148
|
+
return &User{ID: id, Name: name, Email: email}, nil
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
type UserRepository interface {
|
|
152
|
+
Save(ctx context.Context, u *User) error
|
|
153
|
+
FindByID(ctx context.Context, id string) (*User, error)
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### 2. Service (Use Case)
|
|
158
|
+
|
|
159
|
+
```go
|
|
160
|
+
// internal/service/user_service.go
|
|
161
|
+
package service
|
|
162
|
+
|
|
163
|
+
import (
|
|
164
|
+
"context"
|
|
165
|
+
"myapp/internal/domain"
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
type UserService struct {
|
|
169
|
+
repo domain.UserRepository
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
func NewUserService(repo domain.UserRepository) *UserService {
|
|
173
|
+
return &UserService{repo: repo}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
func (s *UserService) Register(ctx context.Context, name, email string) error {
|
|
177
|
+
// 1. Domain Logic
|
|
178
|
+
u, err := domain.NewUser(domain.NewID(), name, email)
|
|
179
|
+
if err != nil {
|
|
180
|
+
return err
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// 2. Persist
|
|
184
|
+
return s.repo.Save(ctx, u)
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### 3. HTTP Handler (Echo)
|
|
189
|
+
|
|
190
|
+
```go
|
|
191
|
+
// internal/adapter/handler/http/user_handler.go
|
|
192
|
+
package http
|
|
193
|
+
|
|
194
|
+
import (
|
|
195
|
+
"net/http"
|
|
196
|
+
"github.com/labstack/echo/v4"
|
|
197
|
+
)
|
|
198
|
+
|
|
199
|
+
type UserHandler struct {
|
|
200
|
+
svc *service.UserService
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
func (h *UserHandler) Register(c echo.Context) error {
|
|
204
|
+
var req struct {
|
|
205
|
+
Name string `json:"name"`
|
|
206
|
+
Email string `json:"email"`
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
if err := c.Bind(&req); err != nil {
|
|
210
|
+
return c.JSON(http.StatusBadRequest, echo.Map{"error": "bad request"})
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
if err := h.svc.Register(c.Request().Context(), req.Name, req.Email); err != nil {
|
|
214
|
+
return c.JSON(http.StatusInternalServerError, echo.Map{"error": err.Error()})
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
return c.NoContent(http.StatusCreated)
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Development Workflow with Agents
|
|
224
|
+
|
|
225
|
+
### "Scaffold New Feature" prompt:
|
|
226
|
+
> "Agent, create a new 'Product' domain entity in `internal/domain`. Then generate the Ent schema, run `go generate`, implement the repository interface in `internal/adapter/repository`, add a `ProductService`, and expose it via a new Echo handler."
|
|
227
|
+
|
|
228
|
+
### "Test It" prompt:
|
|
229
|
+
> "Agent, write a specialized integration test in `tests/integration` using Testcontainers to spin up Postgres, migrate the Ent schema, and verify the `ProductService.Create` flow."
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Tech Debt & Maintenance
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
# Update dependencies
|
|
237
|
+
go get -u ./...
|
|
238
|
+
go mod tidy
|
|
239
|
+
|
|
240
|
+
# Run formatter (stricter than gofmt)
|
|
241
|
+
gofumpt -w .
|
|
242
|
+
|
|
243
|
+
# Linting
|
|
244
|
+
golangci-lint run --fix
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## See Also
|
|
250
|
+
- [Performant Go Skill](../../skills/coding/performant-go.skill.md) — High-performance Go systems.
|
|
251
|
+
- [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — Security best practices for Go.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Java Project Guide
|
|
2
|
+
|
|
3
|
+
> **Audience:** agents writing or reviewing Java services. **Scope:** current
|
|
4
|
+
> stack, idioms, structure, testing, performance, and pitfalls for server-side
|
|
5
|
+
> Java in 2026. Versions verified 2026-06-10 (see sources at the end).
|
|
6
|
+
|
|
7
|
+
## Recommended stack (2026)
|
|
8
|
+
|
|
9
|
+
- **Runtime:** **Java 25 (LTS)** — released 2025-09-16; the current long-term
|
|
10
|
+
support release. Java 21 (LTS) remains widely deployed; target 25 for new
|
|
11
|
+
work, 21 as the minimum floor. (Java 26 is the latest non-LTS feature release.)
|
|
12
|
+
- **Build:** Gradle (Kotlin DSL) for new projects; Maven where the org standard.
|
|
13
|
+
- **Web:** Spring Boot 3.x (broadest ecosystem) or Quarkus / Helidon (fast
|
|
14
|
+
startup, low memory, GraalVM-friendly).
|
|
15
|
+
- **Persistence:** Spring Data JPA / Hibernate; jOOQ when you want type-safe SQL.
|
|
16
|
+
- **Testing:** JUnit 5 + AssertJ + Mockito; **Testcontainers** for real
|
|
17
|
+
databases/brokers in integration tests.
|
|
18
|
+
- **Quality:** Checkstyle + SpotBugs (or Error Prone) + `./gradlew check`; format
|
|
19
|
+
with Spotless (google-java-format / Palantir).
|
|
20
|
+
|
|
21
|
+
## Concurrency — use the modern model
|
|
22
|
+
|
|
23
|
+
- **Virtual threads** (finalized in Java 21, JEP 444): for I/O-bound work, run
|
|
24
|
+
each task on a virtual thread instead of pooling platform threads. With Spring
|
|
25
|
+
Boot, enable `spring.threads.virtual.enabled=true`; otherwise use
|
|
26
|
+
`Executors.newVirtualThreadPerTaskExecutor()`. Write straightforward blocking
|
|
27
|
+
code — the runtime unmounts the carrier thread on blocking I/O.
|
|
28
|
+
- **Structured concurrency** (`StructuredTaskScope`) and **scoped values**
|
|
29
|
+
continue to mature across 21→25; prefer them over `ThreadLocal` and ad-hoc
|
|
30
|
+
fan-out for request-scoped concurrency and propagation.
|
|
31
|
+
- Do **not** pool virtual threads, and avoid pinning them inside `synchronized`
|
|
32
|
+
blocks that perform blocking I/O — use `ReentrantLock` there.
|
|
33
|
+
|
|
34
|
+
## Language idioms (21–25)
|
|
35
|
+
|
|
36
|
+
- **Records** for immutable data carriers; **sealed** interfaces + **pattern
|
|
37
|
+
matching for `switch`** (incl. record deconstruction) for closed type
|
|
38
|
+
hierarchies and exhaustive handling.
|
|
39
|
+
- Prefer immutability and `Optional` over nulls at API boundaries; never use
|
|
40
|
+
`Optional` for fields or method parameters.
|
|
41
|
+
- Use enhanced `switch` expressions and text blocks for readability.
|
|
42
|
+
|
|
43
|
+
## Project structure
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
src/main/java/<group>/<app>/ domain · application · infrastructure · api (Clean/Hexagonal)
|
|
47
|
+
src/main/resources/ application.yml, db/migration (Flyway/Liquibase)
|
|
48
|
+
src/test/java/ unit (fast) + integration (Testcontainers)
|
|
49
|
+
build.gradle.kts | pom.xml
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Keep the domain free of framework annotations; depend inward (the dependency rule).
|
|
53
|
+
|
|
54
|
+
## Performance & ops
|
|
55
|
+
|
|
56
|
+
- Start with the G1 GC; consider ZGC/Shenandoah for low-pause, large-heap
|
|
57
|
+
services. Set explicit `-Xmx` / container memory limits.
|
|
58
|
+
- Prefer **CDS / AppCDS** and, for fast cold start, **GraalVM Native Image**
|
|
59
|
+
(Spring AOT / Quarkus) — but verify reflection config and run the native test
|
|
60
|
+
suite.
|
|
61
|
+
- Observe with Micrometer → OpenTelemetry; expose health/readiness via Actuator.
|
|
62
|
+
|
|
63
|
+
## Common pitfalls
|
|
64
|
+
|
|
65
|
+
- Blocking inside a reactive (`WebFlux`) pipeline — pick one model per service.
|
|
66
|
+
- N+1 queries from lazy JPA associations — fetch-join or use projections.
|
|
67
|
+
- Catch-and-swallow exceptions; leaking checked exceptions across layers.
|
|
68
|
+
- Mutable static state; non-thread-safe `SimpleDateFormat` (use `java.time`).
|
|
69
|
+
|
|
70
|
+
## Sources (verified 2026-06-10)
|
|
71
|
+
- Java version history & LTS cadence: <https://en.wikipedia.org/wiki/Java_version_history>
|
|
72
|
+
- JDK 25 (LTS) features: <https://openjdk.org/projects/jdk/25/> · <https://www.infoq.com/news/2025/09/java25-released/>
|
|
73
|
+
- Virtual threads (JEP 444): <https://openjdk.org/jeps/444>
|
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
# Guide: JavaScript / TypeScript / Node.js
|
|
2
|
+
<!-- Clean Architecture with TypeScript, Fastify, Prisma, Vitest, and Playwright -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Directory Structure — Clean Architecture
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
src/
|
|
10
|
+
domain/ # Pure business logic — NO framework imports
|
|
11
|
+
entities/ # User.ts, Order.ts — domain entities
|
|
12
|
+
value-objects/ # Email.ts, Money.ts — immutable primitives
|
|
13
|
+
events/ # UserRegistered.ts, OrderCreated.ts
|
|
14
|
+
ports/ # IUserRepository.ts — interfaces only
|
|
15
|
+
errors/ # DomainError.ts, ValidationError.ts
|
|
16
|
+
services/ # Pure domain services (no DB, no HTTP)
|
|
17
|
+
|
|
18
|
+
application/ # Use cases — orchestrates domain
|
|
19
|
+
users/
|
|
20
|
+
create-user.use-case.ts
|
|
21
|
+
create-user.command.ts
|
|
22
|
+
create-user.result.ts
|
|
23
|
+
orders/
|
|
24
|
+
create-order.use-case.ts
|
|
25
|
+
|
|
26
|
+
adapters/ # Interface adapters — translate between layers
|
|
27
|
+
http/
|
|
28
|
+
users.controller.ts # Thin controllers — validate, delegate, respond
|
|
29
|
+
users.dto.ts # Zod schemas for request/response
|
|
30
|
+
presenters/ # Transform domain entities to HTTP response shape
|
|
31
|
+
|
|
32
|
+
infrastructure/ # Framework + external services implementations
|
|
33
|
+
database/
|
|
34
|
+
prisma-user.repository.ts # Implements IUserRepository using Prisma
|
|
35
|
+
email/
|
|
36
|
+
sendgrid-email.service.ts
|
|
37
|
+
cache/
|
|
38
|
+
redis-cache.service.ts
|
|
39
|
+
|
|
40
|
+
main/ # Composition root — wires everything together
|
|
41
|
+
container.ts # DI container setup
|
|
42
|
+
server.ts # Fastify server + plugin registration
|
|
43
|
+
routes.ts # Route registration
|
|
44
|
+
|
|
45
|
+
tests/
|
|
46
|
+
unit/ # Mirror of src/ — fast, no DB, no HTTP
|
|
47
|
+
integration/ # Real DB, Docker Compose
|
|
48
|
+
e2e/ # Full browser tests with Playwright
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Layer Import Rules
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
// domain/ — MUST NOT import from any other layer
|
|
57
|
+
// application/ — MAY import from domain only
|
|
58
|
+
// adapters/ — MAY import from domain + application
|
|
59
|
+
// infrastructure/ — MAY import from domain (implements interfaces)
|
|
60
|
+
// main/ — MAY import from all layers (composition root only)
|
|
61
|
+
|
|
62
|
+
// CORRECT: infrastructure depends on domain interface
|
|
63
|
+
import type { IUserRepository } from '@/domain/ports/i-user-repository';
|
|
64
|
+
|
|
65
|
+
// WRONG: domain depending on infrastructure
|
|
66
|
+
import { PrismaClient } from '@prisma/client'; // NEVER in domain layer
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Enforce with:** `npx dependency-cruiser --config .dependency-cruiser.cjs src/`
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## AGENTS.md Snippet (Node.js/TypeScript project)
|
|
74
|
+
|
|
75
|
+
```yaml
|
|
76
|
+
runtime: Node.js 22
|
|
77
|
+
language: TypeScript 5.x (strict mode)
|
|
78
|
+
framework: Fastify 5.x
|
|
79
|
+
package_manager: pnpm
|
|
80
|
+
|
|
81
|
+
install: pnpm install
|
|
82
|
+
dev: pnpm dev
|
|
83
|
+
test: pnpm vitest run
|
|
84
|
+
test_coverage: pnpm vitest run --coverage
|
|
85
|
+
test_single: pnpm vitest run src/path/to/file.test.ts
|
|
86
|
+
build: pnpm build
|
|
87
|
+
typecheck: pnpm tsc --noEmit
|
|
88
|
+
lint: pnpm eslint . --ext .ts,.tsx
|
|
89
|
+
format: pnpm prettier --write .
|
|
90
|
+
security_scan: pnpm audit --audit-level=moderate
|
|
91
|
+
migrate: pnpm prisma migrate dev
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Tech Stack
|
|
97
|
+
|
|
98
|
+
### Core
|
|
99
|
+
| Role | Library | Why |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| Runtime | Node.js 22 (LTS) | Active LTS, native fetch, ES modules |
|
|
102
|
+
| Language | TypeScript 5.x strict | Type safety, better DX |
|
|
103
|
+
| HTTP Framework | Fastify 5.x | Fast, schema validation built-in, plugins |
|
|
104
|
+
| Validation/DTOs | Zod 3.x | Runtime type validation + TypeScript inference |
|
|
105
|
+
| ORM | Prisma 5.x | Type-safe queries, migration-first, great DX |
|
|
106
|
+
| API docs | @scalar/fastify-api-reference | OpenAPI UI |
|
|
107
|
+
|
|
108
|
+
### Testing
|
|
109
|
+
| Role | Library | Command |
|
|
110
|
+
|---|---|---|
|
|
111
|
+
| Unit + Integration | Vitest | `pnpm vitest run` |
|
|
112
|
+
| HTTP integration | Supertest | Within Vitest |
|
|
113
|
+
| Database integration | `@testcontainers/postgresql` | `pnpm vitest run tests/integration` |
|
|
114
|
+
| Browser/E2E | Playwright | `pnpm playwright test` |
|
|
115
|
+
| Coverage | Vitest Coverage (v8) | `--coverage` flag |
|
|
116
|
+
|
|
117
|
+
### Security
|
|
118
|
+
| Role | Library | Command |
|
|
119
|
+
|---|---|---|
|
|
120
|
+
| Dep audit | `npm audit` | `pnpm audit --audit-level=moderate` |
|
|
121
|
+
| SAST | Semgrep | `npx semgrep --config=p/security-audit src/` |
|
|
122
|
+
| Secret detection | gitleaks | `gitleaks detect --source=. --verbose` |
|
|
123
|
+
| HTTP security | Helmet.js | `app.register(fastifyHelmet)` |
|
|
124
|
+
| Rate limiting | `@fastify/rate-limit` | `app.register(fastifyRateLimit)` |
|
|
125
|
+
| Input sanitization | validator.js | For specific string validation beyond Zod |
|
|
126
|
+
| Architecture | dependency-cruiser | `npx depcruise src/` |
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## TypeScript Configuration (strict mode)
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
// tsconfig.json
|
|
134
|
+
{
|
|
135
|
+
"compilerOptions": {
|
|
136
|
+
"target": "ES2022",
|
|
137
|
+
"module": "NodeNext",
|
|
138
|
+
"moduleResolution": "NodeNext",
|
|
139
|
+
"strict": true,
|
|
140
|
+
"noUncheckedIndexedAccess": true,
|
|
141
|
+
"noImplicitOverride": true,
|
|
142
|
+
"exactOptionalPropertyTypes": true,
|
|
143
|
+
"paths": {
|
|
144
|
+
"@/*": ["./src/*"]
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Patterns
|
|
153
|
+
|
|
154
|
+
### Domain Entity with Invariants
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
// src/domain/entities/user.ts
|
|
158
|
+
import { Email } from '../value-objects/email';
|
|
159
|
+
import { UserId } from '../value-objects/user-id';
|
|
160
|
+
import { UserRegisteredEvent } from '../events/user-registered.event';
|
|
161
|
+
import type { DomainEvent } from '../events/domain-event';
|
|
162
|
+
|
|
163
|
+
export class User {
|
|
164
|
+
private readonly _events: DomainEvent[] = [];
|
|
165
|
+
|
|
166
|
+
private constructor(
|
|
167
|
+
public readonly id: UserId,
|
|
168
|
+
public readonly email: Email,
|
|
169
|
+
public readonly name: string,
|
|
170
|
+
public readonly createdAt: Date,
|
|
171
|
+
) {}
|
|
172
|
+
|
|
173
|
+
static create(email: Email, name: string): User {
|
|
174
|
+
const user = new User(UserId.generate(), email, name, new Date());
|
|
175
|
+
user._events.push(new UserRegisteredEvent(user.id.value, user.email.value));
|
|
176
|
+
return user;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
get events(): readonly DomainEvent[] { return this._events; }
|
|
180
|
+
clearEvents(): void { this._events.length = 0; }
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Value Object
|
|
185
|
+
|
|
186
|
+
```typescript
|
|
187
|
+
// src/domain/value-objects/email.ts
|
|
188
|
+
import { z } from 'zod';
|
|
189
|
+
|
|
190
|
+
const emailSchema = z.string().email().max(255);
|
|
191
|
+
|
|
192
|
+
export class Email {
|
|
193
|
+
private constructor(public readonly value: string) {}
|
|
194
|
+
|
|
195
|
+
static create(value: string): Email {
|
|
196
|
+
const result = emailSchema.safeParse(value);
|
|
197
|
+
if (!result.success) {
|
|
198
|
+
throw new ValidationError(`Invalid email: ${value}`);
|
|
199
|
+
}
|
|
200
|
+
return new Email(result.data);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
equals(other: Email): boolean { return this.value === other.value; }
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Use Case
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
// src/application/users/create-user.use-case.ts
|
|
211
|
+
import type { IUserRepository } from '@/domain/ports/i-user-repository';
|
|
212
|
+
import type { IEventBus } from '@/domain/ports/i-event-bus';
|
|
213
|
+
import { User } from '@/domain/entities/user';
|
|
214
|
+
import { Email } from '@/domain/value-objects/email';
|
|
215
|
+
import { EmailAlreadyExistsError } from '@/domain/errors/email-already-exists.error';
|
|
216
|
+
|
|
217
|
+
export interface CreateUserCommand {
|
|
218
|
+
email: string;
|
|
219
|
+
name: string;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
export class CreateUserUseCase {
|
|
223
|
+
constructor(
|
|
224
|
+
private readonly userRepository: IUserRepository,
|
|
225
|
+
private readonly eventBus: IEventBus,
|
|
226
|
+
) {}
|
|
227
|
+
|
|
228
|
+
async execute(command: CreateUserCommand): Promise<{ id: string }> {
|
|
229
|
+
const email = Email.create(command.email); // validates here
|
|
230
|
+
|
|
231
|
+
const existing = await this.userRepository.findByEmail(email);
|
|
232
|
+
if (existing) throw new EmailAlreadyExistsError(email.value);
|
|
233
|
+
|
|
234
|
+
const user = User.create(email, command.name);
|
|
235
|
+
await this.userRepository.save(user);
|
|
236
|
+
await this.eventBus.publish(user.events);
|
|
237
|
+
user.clearEvents();
|
|
238
|
+
|
|
239
|
+
return { id: user.id.value };
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Thin Controller (Fastify)
|
|
245
|
+
|
|
246
|
+
```typescript
|
|
247
|
+
// src/adapters/http/users.controller.ts
|
|
248
|
+
import type { FastifyPluginAsync } from 'fastify';
|
|
249
|
+
import { z } from 'zod';
|
|
250
|
+
import type { CreateUserUseCase } from '@/application/users/create-user.use-case';
|
|
251
|
+
|
|
252
|
+
const CreateUserBody = z.object({
|
|
253
|
+
email: z.string().email(),
|
|
254
|
+
name: z.string().min(1).max(100),
|
|
255
|
+
});
|
|
256
|
+
|
|
257
|
+
export const usersRouter: FastifyPluginAsync = async (app) => {
|
|
258
|
+
app.post('/api/v1/users', {
|
|
259
|
+
schema: { body: CreateUserBody },
|
|
260
|
+
}, async (request, reply) => {
|
|
261
|
+
const result = await request.container.resolve(CreateUserUseCase)
|
|
262
|
+
.execute(request.body);
|
|
263
|
+
return reply.status(201).send(result);
|
|
264
|
+
});
|
|
265
|
+
};
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## Error Handling Patterns
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
// src/domain/errors/domain-error.ts
|
|
274
|
+
export abstract class DomainError extends Error {
|
|
275
|
+
abstract readonly code: string;
|
|
276
|
+
constructor(message: string) {
|
|
277
|
+
super(message);
|
|
278
|
+
this.name = this.constructor.name;
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// src/adapters/http/error-handler.ts (Fastify global error handler)
|
|
283
|
+
export const errorHandler: FastifyErrorHandler = (error, request, reply) => {
|
|
284
|
+
if (error instanceof DomainError) {
|
|
285
|
+
return reply.status(422).send({
|
|
286
|
+
error: { code: error.code, message: error.message }
|
|
287
|
+
});
|
|
288
|
+
}
|
|
289
|
+
if (error instanceof ValidationError) {
|
|
290
|
+
return reply.status(400).send({
|
|
291
|
+
error: { code: 'VALIDATION_ERROR', message: error.message }
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
// Never expose internal errors to clients
|
|
295
|
+
request.log.error(error);
|
|
296
|
+
return reply.status(500).send({ error: { code: 'INTERNAL_ERROR', message: 'Internal server error' } });
|
|
297
|
+
};
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Security Best Practices
|
|
303
|
+
|
|
304
|
+
```typescript
|
|
305
|
+
// Register security plugins in src/main/server.ts
|
|
306
|
+
import fastifyHelmet from '@fastify/helmet';
|
|
307
|
+
import fastifyRateLimit from '@fastify/rate-limit';
|
|
308
|
+
import fastifyCors from '@fastify/cors';
|
|
309
|
+
|
|
310
|
+
await app.register(fastifyHelmet, {
|
|
311
|
+
contentSecurityPolicy: {
|
|
312
|
+
directives: {
|
|
313
|
+
defaultSrc: ["'self'"],
|
|
314
|
+
scriptSrc: ["'self'"],
|
|
315
|
+
styleSrc: ["'self'", "'unsafe-inline'"],
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
});
|
|
319
|
+
|
|
320
|
+
await app.register(fastifyRateLimit, {
|
|
321
|
+
max: 100,
|
|
322
|
+
timeWindow: '1 minute',
|
|
323
|
+
// Stricter for auth endpoints: configure per-route
|
|
324
|
+
});
|
|
325
|
+
|
|
326
|
+
await app.register(fastifyCors, {
|
|
327
|
+
origin: process.env.ALLOWED_ORIGINS?.split(',') ?? ['http://localhost:3000'],
|
|
328
|
+
credentials: true,
|
|
329
|
+
});
|
|
330
|
+
|
|
331
|
+
// NEVER: wildcard CORS for authenticated APIs
|
|
332
|
+
// await app.register(fastifyCors, { origin: '*' }); // WRONG
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## Tech Debt Detection Commands
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
# Cyclomatic complexity (flag > 10)
|
|
341
|
+
npx complexity-report --format json src/ | jq '.functions[] | select(.cyclomatic > 10)'
|
|
342
|
+
|
|
343
|
+
# Code duplication
|
|
344
|
+
npx jscpd src/ --min-lines 5 --min-tokens 50
|
|
345
|
+
|
|
346
|
+
# Circular dependencies
|
|
347
|
+
npx madge --circular --extensions ts src/
|
|
348
|
+
|
|
349
|
+
# Outdated dependencies
|
|
350
|
+
pnpm outdated
|
|
351
|
+
|
|
352
|
+
# Architecture violations
|
|
353
|
+
npx dependency-cruiser --config .dependency-cruiser.cjs src/
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## See Also
|
|
359
|
+
- [Performant Node.js Skill](../../skills/coding/performant-nodejs.skill.md) — Optimization strategies.
|
|
360
|
+
- [Secure Coding Skill](../../skills/coding/secure-coding.skill.md) — Hardening Node.js apps.
|
|
361
|
+
- [Clean Coder Skill](../../skills/coding/clean-coder.skill.md) — Architecture enforcement.
|