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,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: output-validation
|
|
3
|
+
description: Make LLM and agent outputs safe and machine-reliable via schema validation and PII masking.
|
|
4
|
+
triggers: [output validation, schema validation, structured output, retry on validation, PII masking, Presidio, improper output handling]
|
|
5
|
+
tags: [coding]
|
|
6
|
+
core: false
|
|
7
|
+
context_cost: medium
|
|
8
|
+
---
|
|
9
|
+
# Output Validation Skill
|
|
10
|
+
|
|
11
|
+
## Goal
|
|
12
|
+
Make LLM/agent outputs safe and machine-reliable through schema validation and PII masking BEFORE they are used downstream or written to logs. Structured outputs must be typed and validated so a side-effecting tool never acts on malformed model text, and PII must be masked before it crosses a trust boundary (external API, log, or observability sink). Grounded in OWASP LLM05:2025 (Improper Output Handling) and LLM02:2025 (Sensitive Information Disclosure).
|
|
13
|
+
|
|
14
|
+
## Steps
|
|
15
|
+
|
|
16
|
+
1. **Define an output schema for every structured output**
|
|
17
|
+
- Pydantic in Python, Zod in TypeScript, or JSON Schema as the language-neutral contract.
|
|
18
|
+
- The schema is the boundary contract — no structured output leaves the model layer without one.
|
|
19
|
+
|
|
20
|
+
2. **Prefer constrained / native structured output**
|
|
21
|
+
- Use constrained decoding, native structured-output modes, or tool-calling so the model is guided toward valid output at generation time rather than corrected after the fact.
|
|
22
|
+
|
|
23
|
+
3. **Validate, then retry-on-validation-failure (bounded)**
|
|
24
|
+
- Validate the raw output against the schema.
|
|
25
|
+
- On failure, run a RETRY-ON-VALIDATION-FAILURE loop: feed the validation error plus the schema back to the model and regenerate, with a bounded retry count.
|
|
26
|
+
- Only after exhausting retries do you surface an error — never pass invalid output downstream.
|
|
27
|
+
|
|
28
|
+
4. **Mask PII before external APIs and before logging**
|
|
29
|
+
- Before sending data to an external API, and before writing to logs/observability, detect and mask PII with a regex + NER hybrid (named example: Microsoft Presidio).
|
|
30
|
+
- State the FALSE-NEGATIVE caveat explicitly: NER misses names and locations in unfamiliar contexts. Use confidence thresholds and tune for recall on the highest-sensitivity entity types.
|
|
31
|
+
|
|
32
|
+
5. **Choose a masking strategy by sensitivity**
|
|
33
|
+
- Redact (drop), hash, salted-hash (de-dup without reversibility), or placeholder/format-preserving — selected per entity by how sensitive it is and whether downstream needs join-ability.
|
|
34
|
+
|
|
35
|
+
## Constraints
|
|
36
|
+
- NEVER act on unvalidated LLM output that drives a side-effecting tool (file write, API call, transaction, command).
|
|
37
|
+
- NEVER log unmasked PII — masking happens before the data reaches the log/observability layer, not after.
|
|
38
|
+
- Schema validation catches STRUCTURE, not semantic correctness: a value can be well-typed and still wrong. Validation is necessary, not sufficient.
|
|
39
|
+
- PII masking has false negatives by design; treat masked output as risk-reduced, not PII-free, and keep confidence thresholds tuned for the sensitivity of the sink.
|
|
40
|
+
|
|
41
|
+
## Output Format
|
|
42
|
+
- A validated, typed object (the schema-conformant result) ready for downstream use.
|
|
43
|
+
- A validation report: passed / failed / number of retries, and the PII entities detected and masked (type and masking strategy, never the raw value).
|
|
44
|
+
|
|
45
|
+
## Security & Guardrails
|
|
46
|
+
|
|
47
|
+
### 1. Skill Security (Output Validation)
|
|
48
|
+
- **Improper output handling enabling downstream injection**: Unvalidated model output flowing into a SQL query, shell command, HTML sink, or template is a classic OWASP LLM05 path to SQLi/XSS/command injection. Validation MUST run before any side-effecting use, and the consuming sink MUST still apply its own context-appropriate encoding/parameterization — schema validation does not replace output encoding.
|
|
49
|
+
- **Retry-loop resource exhaustion**: The retry-on-validation-failure loop is itself a denial-of-service surface if unbounded — a model stuck producing invalid output burns tokens and budget indefinitely. The retry count, total token spend, and wall-clock per output MUST be hard-capped, failing closed to an error rather than looping.
|
|
50
|
+
|
|
51
|
+
### 2. System Integration Security
|
|
52
|
+
- **PII leakage into logs / observability (OWASP LLM02)**: Logs, traces, and error payloads are the most common accidental PII exfiltration sink because they are shipped to third-party observability platforms. Masking MUST occur on the path to every external sink, and raw-value fields MUST be excluded from structured logs by schema, not by hoping the logger redacts them.
|
|
53
|
+
- **Masking false-negatives reaching external APIs**: Because the regex+NER hybrid (e.g. `Presidio`) misses entities in unfamiliar contexts, sending "masked" data to an external LLM/API can still leak real PII. High-sensitivity flows MUST set recall-favoring confidence thresholds and, where the sink is untrusted, prefer redaction over placeholder so a missed entity is the exception, not the norm.
|
|
54
|
+
|
|
55
|
+
### 3. LLM & Agent Guardrails
|
|
56
|
+
- **Schema-valid but semantically false output**: A well-typed object can encode a hallucinated or adversarial value (a fabricated account number, an injected URL). Downstream consumers MUST NOT treat schema-validity as authorization or truth; trifecta-complete or irreversible actions still require independent verification and human approval per `prompt-injection-defense.skill` and `ai-safety-guardrails.skill`.
|
|
57
|
+
- **Validation feedback as an injection vector**: Echoing the model's invalid output and validation error back into the retry prompt can re-inject attacker-controlled content. Feed back only the structured schema/error description, not the raw rejected payload verbatim, so the retry turn cannot be steered by the failed output.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pbt-strategy
|
|
3
|
+
description: Property-based testing with Python Hypothesis — find invariants, write @given strategies, and model stateful systems with RuleBasedStateMachine.
|
|
4
|
+
triggers: [write property based tests, find invariants for testing, use hypothesis given strategies, build a rulebasedstatemachine, fuzz json against a schema, shrink to a minimal counterexample]
|
|
5
|
+
tags: [coding, testing, hypothesis, property-based-testing, python]
|
|
6
|
+
core: false
|
|
7
|
+
context_cost: medium
|
|
8
|
+
---
|
|
9
|
+
# Property-Based Testing Strategy (Hypothesis)
|
|
10
|
+
|
|
11
|
+
## Goal
|
|
12
|
+
Stop hand-picking a few example inputs and instead state the *properties* that must hold for
|
|
13
|
+
*all* inputs, then let Hypothesis generate hundreds of diverse cases to attack them. A
|
|
14
|
+
property-based test asserts an invariant ("the output is always sorted", "decode(encode(x))
|
|
15
|
+
== x") rather than a single example. When it finds a failure, Hypothesis *shrinks* the
|
|
16
|
+
counterexample to the smallest input that still breaks the property, handing you a minimal
|
|
17
|
+
reproduction. The output of this skill is a **property test plan**: the invariants you will
|
|
18
|
+
check, the strategies that generate inputs for them, and — for stateful systems — the state
|
|
19
|
+
machine that drives them. Be clear from the start: PBT *samples* the input space to raise
|
|
20
|
+
confidence; it does not enumerate it and does not prove correctness.
|
|
21
|
+
|
|
22
|
+
## Steps
|
|
23
|
+
1. **Find the invariants.** Look for properties that hold regardless of the specific input. The
|
|
24
|
+
common families:
|
|
25
|
+
- **Round-trip**: `decode(encode(x)) == x`, `parse(serialize(x)) == x`.
|
|
26
|
+
- **Idempotence**: `f(f(x)) == f(x)` (normalize, dedupe, clamp).
|
|
27
|
+
- **Oracle/equivalence**: a slow-but-obviously-correct reference agrees with the optimized
|
|
28
|
+
implementation; or two code paths that must agree.
|
|
29
|
+
- **Invariant preservation**: an operation never violates a structural rule (a balanced tree
|
|
30
|
+
stays balanced; a total never goes negative; output length never exceeds input).
|
|
31
|
+
- **Metamorphic relations** when there is no oracle for the absolute output — delegate those
|
|
32
|
+
to `metamorphic-testing.skill`.
|
|
33
|
+
2. **Write the `@given` strategies.** Generate inputs with Hypothesis strategies
|
|
34
|
+
(`integers()`, `text()`, `lists()`, `dictionaries()`, `builds()`, `composite`). Constrain to
|
|
35
|
+
the *valid* domain with `.filter()` sparingly and `.map()`/`assume()` so generation stays
|
|
36
|
+
efficient — over-filtering makes Hypothesis give up. Compose custom strategies with
|
|
37
|
+
`@composite` for domain objects. Keep each test focused on one invariant.
|
|
38
|
+
3. **Fuzz structured data against its schema.** For JSON APIs and configs, use
|
|
39
|
+
`hypothesis-jsonschema`'s `from_schema()` to generate inputs that conform to a JSON Schema,
|
|
40
|
+
then assert your handler never crashes and always returns schema-valid output. This catches
|
|
41
|
+
the edge cases hand-written fixtures miss (empty arrays, unicode, boundary numbers, missing
|
|
42
|
+
optional fields).
|
|
43
|
+
4. **Model stateful systems with `RuleBasedStateMachine`.** When behavior depends on a sequence
|
|
44
|
+
of operations (a cache, a queue, a connection pool, a small DB), subclass
|
|
45
|
+
`RuleBasedStateMachine` and let Hypothesis generate *sequences* of actions:
|
|
46
|
+
- `@initialize` seeds starting state once per run.
|
|
47
|
+
- `@rule` defines an action; Hypothesis picks rules and arguments to build random valid
|
|
48
|
+
sequences.
|
|
49
|
+
- `Bundle` holds values produced by one rule (e.g. a created handle) to feed as input to
|
|
50
|
+
later rules, so generated sequences are realistic.
|
|
51
|
+
- `@precondition` gates a rule so it only fires in valid states.
|
|
52
|
+
- `@invariant` is checked after *every* step — the core safety property that must always hold.
|
|
53
|
+
Run it as a normal test; Hypothesis searches for an action sequence that breaks an invariant.
|
|
54
|
+
5. **Use shrinking and the example database.** On failure, let Hypothesis shrink to the minimal
|
|
55
|
+
counterexample and read it as your bug report. Pin a found failure with `@example(...)` so it
|
|
56
|
+
becomes a permanent regression case. Keep Hypothesis's example database in CI so previously
|
|
57
|
+
failing inputs are replayed first.
|
|
58
|
+
6. **Tune effort honestly.** Set `max_examples` and `deadline` for the time budget; more examples
|
|
59
|
+
= more confidence, never certainty. In CI, raise `max_examples` for critical properties and
|
|
60
|
+
use `derandomize`/a fixed seed only when you need reproducible runs (knowing it narrows the
|
|
61
|
+
search).
|
|
62
|
+
|
|
63
|
+
## Constraints
|
|
64
|
+
- PBT **samples** the input space and **raises confidence**; it does **NOT prove correctness**.
|
|
65
|
+
Unlike formal methods (model checking, proof assistants) which reason over *all* states, a
|
|
66
|
+
passing property test means "no counterexample was found in N sampled cases." State this limit
|
|
67
|
+
in the plan and never claim a property is "proven."
|
|
68
|
+
- A property is only as good as its strategy: if the generator never produces the bad input, the
|
|
69
|
+
bug hides. Check the strategy actually covers the domain (use `target()`/coverage if unsure).
|
|
70
|
+
- Over-constrained strategies (heavy `.filter()`/`assume()`) cause Hypothesis to abandon
|
|
71
|
+
generation; build valid data directly with `@composite` instead.
|
|
72
|
+
- Flaky properties (depending on time, randomness, ordering of external systems) produce
|
|
73
|
+
non-reproducing failures; make the system-under-test deterministic for the test or inject seams.
|
|
74
|
+
- Stateful tests grow expensive fast; keep the rule set minimal and the invariant sharp.
|
|
75
|
+
|
|
76
|
+
## Output Format
|
|
77
|
+
Produce a **property test plan** containing:
|
|
78
|
+
- The list of invariants, each tagged by family (round-trip / idempotence / oracle /
|
|
79
|
+
invariant-preservation / metamorphic-handoff).
|
|
80
|
+
- For each invariant: the Hypothesis strategy (or `from_schema` reference) that generates its
|
|
81
|
+
inputs, and the assertion.
|
|
82
|
+
- For stateful components: the `RuleBasedStateMachine` design — rules, bundles, preconditions,
|
|
83
|
+
initialize, and the `@invariant`(s).
|
|
84
|
+
- The effort settings (`max_examples`, `deadline`) and any pinned `@example` regression cases.
|
|
85
|
+
- An explicit honesty note: the suite samples inputs and raises confidence; it does not prove
|
|
86
|
+
correctness. Cross-reference `metamorphic-testing.skill` for oracle-free relations.
|
|
87
|
+
|
|
88
|
+
## Security & Guardrails
|
|
89
|
+
|
|
90
|
+
### 1. Skill Security
|
|
91
|
+
- **Risk**: A green property suite is reported as a correctness proof, giving false assurance for
|
|
92
|
+
safety- or security-critical code. Mitigation: every report MUST state PBT samples and does not
|
|
93
|
+
prove; the agent MUST NOT use "property passed" to mean "cannot fail," and MUST recommend formal
|
|
94
|
+
methods where a real proof is required.
|
|
95
|
+
- **Risk**: A weak or over-filtered strategy never generates the dangerous input, so the test
|
|
96
|
+
passes vacuously. Mitigation: the agent MUST sanity-check coverage of the strategy (it produces
|
|
97
|
+
edge/boundary/empty/unicode values) and flag any property whose generator cannot reach the
|
|
98
|
+
failure region as low-value.
|
|
99
|
+
|
|
100
|
+
### 2. System Integration Security
|
|
101
|
+
- **Risk**: A stateful or schema-fuzzing test executes real side effects (writes a real DB,
|
|
102
|
+
calls a paid/external API, mutates shared state) and corrupts data or runs up cost. Mitigation:
|
|
103
|
+
run PBT against isolated fixtures, in-memory/transactional fakes, or sandboxes; never point
|
|
104
|
+
generators at production resources, and bound `max_examples` to control blast radius and spend.
|
|
105
|
+
- **Risk**: `hypothesis-jsonschema` generates pathological payloads (huge strings, deep nesting)
|
|
106
|
+
that exhaust memory or hang the handler. Mitigation: set `deadline`/size limits in strategies
|
|
107
|
+
and treat resource exhaustion as a finding to fix (input validation), not a test to silence.
|
|
108
|
+
|
|
109
|
+
### 3. LLM & Agent Guardrails
|
|
110
|
+
- **Risk**: The agent invents a plausible but false invariant (asserting a property the spec
|
|
111
|
+
never required), turning the test green while masking real behavior. Mitigation: each invariant
|
|
112
|
+
MUST trace to a stated requirement or contract; the agent MUST mark agent-derived invariants as
|
|
113
|
+
proposed and ask for confirmation before trusting them.
|
|
114
|
+
- **Risk**: The agent hallucinates Hypothesis API surface (non-existent strategies or state-machine
|
|
115
|
+
decorators) that errors or silently skips. Mitigation: emit only real, current Hypothesis APIs
|
|
116
|
+
(`@given`, `@rule`, `@initialize`, `@precondition`, `@invariant`, `Bundle`, `from_schema`); the
|
|
117
|
+
agent MUST verify the test actually runs and can fail before presenting it as coverage.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performant-ai
|
|
3
|
+
description: Strategies for high-performance AI/LLM systems (Context Management, Prompt Engineering, RAG, Inference Tuning).
|
|
4
|
+
triggers: [ai, llm, performance, context window, tokens, prompt engineering, rag, inference, latency]
|
|
5
|
+
tags: [coding, ai, architecture]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Performant AI Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Optimizing the interaction, speed, and cost-effectiveness of LLM-based systems by mastering context management and inference strategies.
|
|
12
|
+
|
|
13
|
+
## Capabilities
|
|
14
|
+
|
|
15
|
+
### 1. Context Window Engineering
|
|
16
|
+
- **Context Pruning**: Implement logic to remove irrelevant or redundant tokens from the prompt to fit within limits and reduce cost.
|
|
17
|
+
- **Summarization Chains**: Use "recursive summarization" for long conversations or documents.
|
|
18
|
+
- **Observation Masking**: Hide older or less critical data to keep the attention of the model on the immediate task.
|
|
19
|
+
|
|
20
|
+
### 2. Efficient Prompting (Latency & Cost)
|
|
21
|
+
- **Few-Shot Optimization**: Minimize the number of examples to the bare minimum needed for accuracy.
|
|
22
|
+
- **Output Structuring**: Use JSON mode or structured outputs to reduce parsing errors and retry loops.
|
|
23
|
+
- **Prompt Compression**: Use tools or manual techniques to shorten instructions without losing semantic meaning.
|
|
24
|
+
|
|
25
|
+
### 3. RAG Optimization (Retrieval-Augmented Generation)
|
|
26
|
+
- **Chunking Strategy**: Optimize chunk sizes and overlap for the specific domain (e.g., small chunks for semantic search, large for summaries).
|
|
27
|
+
- **Hybrid Search**: Combine Vector search (semantic) with Keyword search (BM25) for higher precision.
|
|
28
|
+
- **Re-ranking**: Use a secondary, smaller model to re-rank the top-K results before sending them to the expensive LLM.
|
|
29
|
+
|
|
30
|
+
### 4. Inference & Routing Strategies
|
|
31
|
+
- **Brain Mode Routing**: Arbitrate between "Local" models (faster/cheaper) and "Remote" models (complex/slower) based on task difficulty.
|
|
32
|
+
- **Speculative Decoding**: (Where possible) use smaller models to draft tokens for larger models to verify, speeding up generation.
|
|
33
|
+
- **Cache Hits**: Implement semantic caching (Redis) to reuse LLM responses for similar queries.
|
|
34
|
+
|
|
35
|
+
### 5. Architectural Patterns
|
|
36
|
+
- **Self-Correction Loops**: Build reflection phases into the agent flow to catch errors early.
|
|
37
|
+
- **Asynchronous Agents**: Run independent research or tool calls in parallel to reduce perceived latency (Loki Mode).
|
|
38
|
+
|
|
39
|
+
## Steps
|
|
40
|
+
1. **Token Audit**: Trace the token count of typical requests to find "bloat" in systemic prompts.
|
|
41
|
+
2. **Latency Mapping**: Break down Time-to-First-Token (TTFT) and Total Generation Time.
|
|
42
|
+
3. **Retrieval Benchmark**: Measure the Hit Rate and Recall of the RAG pipeline.
|
|
43
|
+
4. **Cost Projection**: Estimate monthly burn based on different model providers and context sizes.
|
|
44
|
+
|
|
45
|
+
## Deliverables
|
|
46
|
+
- `COST_OPTIMIZATION_REPORT_TEMPLATE.md`: Analysis of prompt efficiency and LLM token usage.
|
|
47
|
+
- `ARCHITECTURE_REVIEW_TEMPLATE.md`: Configuration for vector DB, chunking, and search weights.
|
|
48
|
+
- `SCALABILITY_ANALYSIS_TEMPLATE.md`: Logic table for local vs remote model selection and context scaling.
|
|
49
|
+
|
|
50
|
+
## Security & Guardrails
|
|
51
|
+
|
|
52
|
+
### 1. Data Privacy
|
|
53
|
+
- **PII Masking**: Ensure no Personally Identifiable Information is sent to remote LLM providers without encryption or redaction.
|
|
54
|
+
- **Data Leakage**: Verify that RAG sources do not inadvertently expose unauthorized documents to the user.
|
|
55
|
+
|
|
56
|
+
### 2. Reliability
|
|
57
|
+
- **Hallucination Checks**: Mandatory verification step for critical facts generated by the LLM.
|
|
58
|
+
- **Fallback Logic**: Always have a "conservative" fallback if the primary LLM fails or hits rate limits.
|
|
59
|
+
|
|
60
|
+
### 3. Agent Guardrails
|
|
61
|
+
- **No Infinite Loops**: Implement strict limits on agent reflection or self-healing cycles (Max 5 attempts).
|
|
62
|
+
- **Cost Ceiling**: Set token or dollar limits per session to prevent runaway autonomous spending.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performant-go
|
|
3
|
+
description: Strategies for high-performance Go systems (Goroutines, Channels, Pprof, Memory Alignment).
|
|
4
|
+
triggers: [go, golang, performance, goroutines, channels, pprof, gc, scalability]
|
|
5
|
+
tags: [coding, go, architecture]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Performant Go Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Harnessing Go's concurrency primitives and runtime efficiency to build systems capable of handling millions of requests with minimal memory overhead.
|
|
12
|
+
|
|
13
|
+
## Capabilities
|
|
14
|
+
|
|
15
|
+
### 1. Concurrency & Parallelism
|
|
16
|
+
- **Goroutine Leak Prevention**: Always ensure goroutines have a well-defined lifecycle and termination signal (using `context.Context`).
|
|
17
|
+
- **Channel Optimization**: Use buffered channels where appropriate to prevent blocking. Prefer `select` for non-blocking communication.
|
|
18
|
+
- **Sync.Pool**: Implement `sync.Pool` to reuse objects (like buffers or structs) and reduce Garbage Collector (GC) pressure.
|
|
19
|
+
|
|
20
|
+
### 2. Memory & Layout
|
|
21
|
+
- **Memory Alignment**: Structure fields in structs from largest to smallest to minimize padding and reduce memory footprint.
|
|
22
|
+
- **Allocation Minimization**: Use pointers to avoid copying large structs, but be mindful of "escape analysis" pushing objects to the heap.
|
|
23
|
+
- **Pre-allocation**: Always pre-allocate slices and maps using `make([]T, 0, capacity)` when the target size is known.
|
|
24
|
+
|
|
25
|
+
### 3. Standard Library & Alternatives
|
|
26
|
+
- **JSON Encoding**: Use `segmentio/encoding/json` or `json-iterator` if the standard lib `encoding/json` proves to be a bottleneck.
|
|
27
|
+
- **Fast I/O**: Use `bufio.Writer` and `bufio.Reader` for disk and network operations.
|
|
28
|
+
- **Zero-Copy**: Leverage `unsafe` pointers or specific libraries (like `fasthttp`) only for the most extreme hot paths.
|
|
29
|
+
|
|
30
|
+
### 4. Profiling & Runtime Tuning
|
|
31
|
+
- **Pprof Utilization**: Use `net/http/pprof` to profile CPU, Heap, and Goroutine usage in real-time.
|
|
32
|
+
- **GC Tuning**: Adjust `GOGC` or `GOMEMLIMIT` (Go 1.19+) for memory-intensive applications.
|
|
33
|
+
- **PGO (Profile-Guided Optimization)**: Collect production profiles and use them during build time (`go build -pgo=...`) for automatic optimizations.
|
|
34
|
+
|
|
35
|
+
### 5. Architectural Patterns
|
|
36
|
+
- **Worker Pools**: Implement worker pool patterns to limit concurrency and prevent resource exhaustion.
|
|
37
|
+
- **Streaming**: Process data using `io.Reader` and `io.Writer` interfaces to handle large payloads with constant memory.
|
|
38
|
+
|
|
39
|
+
## Steps
|
|
40
|
+
1. **Baseline Benchmarks**: Write sub-benchmarks using `testing.B` for critical functions.
|
|
41
|
+
2. **Heap Audit**: Run `go tool pprof -alloc_objects` to find the biggest allocators.
|
|
42
|
+
3. **Escape Analysis**: Run `go build -gcflags="-m"` to see what variables move to the heap.
|
|
43
|
+
4. **Identify Contention**: Use the Race Detector (`-race`) and look for Mutex contention in pprof.
|
|
44
|
+
|
|
45
|
+
## Deliverables
|
|
46
|
+
- `ARCHITECTURE_REVIEW_TEMPLATE.md`: Visualizations and analysis of CPU/Memory bottlenecks.
|
|
47
|
+
- `BENCHMARK_REPORT_TEMPLATE.md`: Results from `go test -bench . -benchmem`.
|
|
48
|
+
- `SCALABILITY_ANALYSIS_TEMPLATE.md`: Strategy for minimizing heap allocations and scaling goroutines.
|
|
49
|
+
|
|
50
|
+
## Security & Guardrails
|
|
51
|
+
|
|
52
|
+
### 1. Concurrency Safety
|
|
53
|
+
- **Race Conditions**: MUST run tests with the `-race` flag. Never share memory without synchronization (Mutex/Channels).
|
|
54
|
+
- **Deadlock Detection**: Ensure no circular dependencies between channels or locks.
|
|
55
|
+
|
|
56
|
+
### 2. CGO Cautions
|
|
57
|
+
- **Overhead**: Be aware that CGO calls are significantly slower than native Go. Avoid calling C code in tight loops.
|
|
58
|
+
|
|
59
|
+
### 3. Agent Guardrails
|
|
60
|
+
- **No Premature Fasthttp**: Do not recommend `fasthttp` over `net/http` unless the standard library is proven insufficient, as `fasthttp` breaks many HTTP features.
|
|
61
|
+
- **Simplicity First**: Favor clean, readable Go over "clever" pointer arithmetic or `unsafe` hackery unless absolutely necessary.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performant-laravel
|
|
3
|
+
description: Strategies for high-performance, scalable Laravel systems (Octane, DB Optimization, Redis, Microservices).
|
|
4
|
+
triggers: [laravel, performance, scalability, octane, frankenphp, redis, eloquent, microservices]
|
|
5
|
+
tags: [coding, laravel, architecture]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Performant Laravel Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Optimize Laravel applications for high-throughput, sub-100ms response times, and horizontal scalability using modern runtimes and efficient data patterns.
|
|
12
|
+
|
|
13
|
+
## Capabilities
|
|
14
|
+
|
|
15
|
+
### 1. Database Performance (Eloquent & Query Builder)
|
|
16
|
+
- **Zero N+1 Policy**: Mandatory use of eager loading (`with()`) for all relationships. Use `preventLazyLoading()` in development.
|
|
17
|
+
- **Data Selection**: Use `select()` to retrieve only required columns. Never use `*` for large tables.
|
|
18
|
+
- **Large Dataset Handling**: Use `chunk()` or `lazy()` for processing large records. Use `cursorPaginate()` for infinite scroll or high-offset pagination.
|
|
19
|
+
- **Indexing Strategy**: Ensure all foreign keys and columns used in `WHERE`, `ORDER BY`, and `GROUP BY` are appropriately indexed.
|
|
20
|
+
|
|
21
|
+
### 2. High-Performance Runtimes
|
|
22
|
+
- **Laravel Octane**: Power applications with Swoole or RoadRunner to eliminate the boot overhead of traditional PHP-FPM.
|
|
23
|
+
- **FrankenPHP**: Use the modern PHP app server (Go-based) with 103 Early Hints and worker mode support.
|
|
24
|
+
- **OPcache & Preloading**: Ensure OPcache is tuned and use PHP 7.4+ preloading to keep the framework in memory.
|
|
25
|
+
|
|
26
|
+
### 3. Caching & State
|
|
27
|
+
- **Granular Caching**: Use the `Cache` facade with Redis/Memcached. Favor `tags()` for complex invalidation.
|
|
28
|
+
- **Infrastructure Caching**: Always run `php artisan config:cache`, `route:cache`, and `view:cache` in production deployments.
|
|
29
|
+
- **Stateless Design**: Avoid session-based state for APIs; use JWT or Sanctum with token caching.
|
|
30
|
+
|
|
31
|
+
### 4. Background Processing & Scalability
|
|
32
|
+
- **Horizontal Scaling**: Use Laravel Horizon for managing Redis queues with auto-scaling workers.
|
|
33
|
+
- **Event-Driven Microservices**: Decouple heavy operations (Image processing, Exports) using queues. Implement the Outbox pattern for reliable cross-service communication.
|
|
34
|
+
- **Cloud-Native Integration**: Leverage CDN for static assets and object storage (S3) for file management.
|
|
35
|
+
|
|
36
|
+
### 5. Architectural Patterns
|
|
37
|
+
- **Service Layers**: Extract business logic from controllers into dedicated Services or Actions.
|
|
38
|
+
- **Repository Pattern**: Abstract data access for easier testing and optimization.
|
|
39
|
+
- **Hexagonal/DDD**: Structure large Laravel apps to separate the domain from infrastructure (Eloquent).
|
|
40
|
+
|
|
41
|
+
### 6. Observability & Monitoring
|
|
42
|
+
- **Laravel Telescope**: Use for local debugging of queries, requests, and entries.
|
|
43
|
+
- **APM Integration**: Integrate with New Relic, Datadog, or Blackfire for production bottleneck analysis.
|
|
44
|
+
- **Slow Query Logging**: Enable and monitor slow query logs (`DB::listen`).
|
|
45
|
+
|
|
46
|
+
## Steps
|
|
47
|
+
1. **Benchmark Baseline**: Use `k6` or `ab` to get the current Request/Second and p99 latency.
|
|
48
|
+
2. **Standardize Autoloading**: Ensure `composer install --optimize-autoloader --no-dev` is used.
|
|
49
|
+
3. **Audit Eloquent**: Use Telescope to identify N+1 queries and high memory consumption.
|
|
50
|
+
4. **Tune Environment**: Configure Redis for session/cache and ensure OPcache is optimized.
|
|
51
|
+
|
|
52
|
+
## Deliverables
|
|
53
|
+
- `BENCHMARK_REPORT_TEMPLATE.md`: Bottleneck analysis and Octane/FPM load comparisons.
|
|
54
|
+
- `ARCHITECTURE_REVIEW_TEMPLATE.md`: Definition of cached keys and invalidation logic.
|
|
55
|
+
- `SCALABILITY_ANALYSIS_TEMPLATE.md`: Queue worker strategy and database replica plan.
|
|
56
|
+
|
|
57
|
+
## Security & Guardrails
|
|
58
|
+
|
|
59
|
+
### 1. Skill Security
|
|
60
|
+
- **Safe Evaluation**: Be cautious with raw SQL (`DB::raw`). Ensure all user inputs are parameterized.
|
|
61
|
+
- **Cache Poisoning**: Validate and sanitize data before storing it in the cache to prevent injection.
|
|
62
|
+
|
|
63
|
+
### 2. System Integration Security
|
|
64
|
+
- **Rate Limiting**: Use Laravel's `RateLimiter` to protect APIs from abuse and DoS.
|
|
65
|
+
- **Secrets Management**: Never use `env()` outside of config files. Ensure all secrets are pulled from the environment.
|
|
66
|
+
|
|
67
|
+
### 3. LLM & Agent Guardrails
|
|
68
|
+
- **No Premature Octane**: Do not recommend Laravel Octane for simple, low-traffic apps due to the complexity of managing persistent state.
|
|
69
|
+
- **Index Balance**: Warn against over-indexing which degrades write performance.
|
|
70
|
+
- **Legacy Awareness**: When optimizing older Laravel apps, check compatibility before using modern primitives like `cursorPaginate`.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performant-nodejs
|
|
3
|
+
description: Strategies for high-performance, scalable Node.js systems (Worker Threads, ESM, Observability, Clean Architecture).
|
|
4
|
+
triggers: [nodejs, performance, scalability, worker threads, clustering, esm, observability, hexagonal architecture]
|
|
5
|
+
tags: [coding, nodejs, architecture]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Performant Node.js Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Build and maintain high-throughput, low-latency, and horizontally scalable Node.js systems using modern primitives and architectural patterns.
|
|
12
|
+
|
|
13
|
+
## Capabilities
|
|
14
|
+
|
|
15
|
+
### 1. Concurrency & Parallelism
|
|
16
|
+
- **Clustering**: Scale vertically by spawning a process per CPU core using the `cluster` module.
|
|
17
|
+
- **Worker Threads**: Offload CPU-intensive tasks (encryption, compression, heavy logic) to separate threads using `worker_threads` to avoid blocking the Event Loop.
|
|
18
|
+
- **Event Loop Management**: Prevent starvation by avoiding long-running synchronous operations and heavy JSON parsing on the main thread.
|
|
19
|
+
|
|
20
|
+
### 2. Modern Standards & Async
|
|
21
|
+
- **ES Modules (ESM)**: Favor ESM for new projects for better tree-shaking, top-level await, and future-proofing.
|
|
22
|
+
- **AsyncLocalStorage**: Use for context propagation (trace IDs, user sessions) across asynchronous boundaries without manual passing.
|
|
23
|
+
- **Concurrency Control**: Use libraries like `p-limit` or custom semaphores to prevent resource exhaustion when calling external APIs or databases.
|
|
24
|
+
|
|
25
|
+
### 3. High-Performance Streams
|
|
26
|
+
- **Backpressure Handling**: Efficiently stream large files or data sets using `stream.pipeline` to manage memory usage.
|
|
27
|
+
- **HTTP Streaming**: Implement streaming responses for real-time data processing and low TTFB (Time To First Byte).
|
|
28
|
+
|
|
29
|
+
### 4. Observability & Monitoring
|
|
30
|
+
- **Structured Logging**: Use `pino` for low-overhead, JSON-based logging.
|
|
31
|
+
- **GC Insight**: Monitor Garbage Collection pauses and memory leaks using `v8` and `inspector` modules.
|
|
32
|
+
- **Distributed Tracing**: Implement OpenTelemetry for cross-service visibility.
|
|
33
|
+
|
|
34
|
+
### 5. Architectural Patterns
|
|
35
|
+
- **Hexagonal Architecture (Ports & Adapters)**: Decouple business logic from external dependencies (DB, APIs) for better testability and evolution.
|
|
36
|
+
- **CQRS (Command Query Responsibility Segregation)**: Separate read and write models for performance optimization.
|
|
37
|
+
- **Outbox/Saga Patterns**: Ensure eventual consistency in distributed systems without distributed transactions.
|
|
38
|
+
|
|
39
|
+
### 6. Security & Hardening
|
|
40
|
+
- **Helmet**: Use for setting secure HTTP headers (CSP, HSTS, etc.).
|
|
41
|
+
- **Input Validation**: Mandatory use of `zod` or `ajv` for schema-first validation.
|
|
42
|
+
- **Graceful Shutdown**: Properly handle `SIGTERM` and `SIGINT` to close DB connections and finish in-flight requests.
|
|
43
|
+
|
|
44
|
+
## Steps
|
|
45
|
+
1. **Profile First**: Use `node --inspect` or `0x` to generate flamegraphs before any optimization.
|
|
46
|
+
2. **Standardize**: Ensure ESM is used and dependencies are audited using `npm audit`.
|
|
47
|
+
3. **Analyze Concurrency**: Determine if the bottleneck is CPU-bound (needs Workers) or I/O-bound (needs better async flow/caching).
|
|
48
|
+
4. **Implement Observability**: Add structured logs and basic metrics as the first step of any performance task.
|
|
49
|
+
|
|
50
|
+
## Deliverables
|
|
51
|
+
- `BENCHMARK_REPORT_TEMPLATE.md`: Flamegraph analysis and latency baseline.
|
|
52
|
+
- `SCALABILITY_ANALYSIS_TEMPLATE.md`: Strategy for clustering, sharding, or worker usage.
|
|
53
|
+
- `ARCHITECTURE_REVIEW_TEMPLATE.md`: Standardized logging, tracing configuration, and architecture review.
|
|
54
|
+
|
|
55
|
+
## Security & Guardrails
|
|
56
|
+
|
|
57
|
+
### 1. Skill Security
|
|
58
|
+
- **Worker Isolation**: Do not pass sensitive objects (like raw DB connections or secrets) directly to workers if they run untrusted code.
|
|
59
|
+
- **Stream Injection**: Validate input before piping to file systems or external sinks to prevent injection attacks.
|
|
60
|
+
|
|
61
|
+
### 2. System Integration Security
|
|
62
|
+
- **Rate Limiting**: Always implement at the gateway or app level to prevent DoS when scaling.
|
|
63
|
+
- **Schema-First**: Never trust raw JSON; always validate against a strict schema (e.g., Zod).
|
|
64
|
+
|
|
65
|
+
### 3. LLM & Agent Guardrails
|
|
66
|
+
- **Avoid Micro-optimizations**: Refuse to optimize code that isn't on the critical path or hasn't been profiled as a bottleneck.
|
|
67
|
+
- **Clustering awareness**: Remind the user that `cluster` and `worker_threads` change state management (no shared memory in clusters).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performant-php
|
|
3
|
+
description: High-performance modern PHP — PHP 8.4/8.5, OPcache+JIT, FrankenPHP workers, Composer, Symfony/Laravel, PHPStan/Psalm, Pest.
|
|
4
|
+
triggers: [php, php 8.4, php 8.5, composer, symfony, laravel, frankenphp, opcache, jit, phpstan, psalm, pest, phpunit, php performance]
|
|
5
|
+
tags: [coding, php, architecture]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Performant PHP Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Build fast, type-safe, maintainable PHP services using the current ecosystem (versions verified 2026-06-10). This is the language-level companion to `performant-laravel.skill.md`; use it for general PHP, Symfony, and framework-agnostic work.
|
|
12
|
+
|
|
13
|
+
## Capabilities
|
|
14
|
+
|
|
15
|
+
### 1. Modern language baseline
|
|
16
|
+
- **Target PHP 8.4+ (8.5 current stable).** Use **property hooks** and **asymmetric visibility** (8.4) to remove boilerplate getters/setters; **lazy objects** (8.4) for deferred initialization; PDO driver-specific subclasses. On 8.5, the **pipe operator `|>`** chains callables and the built-in **URI extension** parses/normalizes URLs (RFC 3986 / WHATWG).
|
|
17
|
+
- Always `declare(strict_types=1);`. Use `readonly` classes/properties, enums (backed where serialized), first-class callable syntax, and constructor property promotion.
|
|
18
|
+
|
|
19
|
+
### 2. Runtime performance
|
|
20
|
+
- **OPcache** must be enabled in production; tune `opcache.memory_consumption`, `opcache.max_accelerated_files`, and `opcache.validate_timestamps=0` (with deploy-time cache reset).
|
|
21
|
+
- **JIT** (available 8.3+) more than doubles throughput on CPU-bound work (benchmarks ~+110%); negligible/negative for typical I/O-bound web requests — enable and measure, don't assume.
|
|
22
|
+
- **FrankenPHP worker mode** (Caddy-based app server) keeps the framework booted between requests — large latency wins for Laravel/Symfony; also gives Early Hints and real-time (Mercure). Alternative: RoadRunner or Swoole/OpenSwoole.
|
|
23
|
+
- Use `preload` for hot framework classes.
|
|
24
|
+
|
|
25
|
+
### 3. Database & I/O
|
|
26
|
+
- Eliminate N+1: eager-load (Eloquent `with()`, Doctrine fetch joins); add covering indexes; use `EXPLAIN`.
|
|
27
|
+
- Stream large results with generators (`yield`) to keep memory constant; chunk batch jobs.
|
|
28
|
+
- Cache with Redis (PSR-6/PSR-16); use tags and explicit invalidation; queue slow work (Horizon / Symfony Messenger).
|
|
29
|
+
|
|
30
|
+
### 4. Type safety & quality gates
|
|
31
|
+
- **PHPStan** (aim level 8–9) or **Psalm** for static analysis; **Rector** for automated upgrades/refactors.
|
|
32
|
+
- **Pint** / PHP-CS-Fixer (PSR-12) for formatting; **Deptrac** for architectural layer enforcement.
|
|
33
|
+
- **composer audit** + `roave/security-advisories` to block vulnerable dependencies.
|
|
34
|
+
|
|
35
|
+
### 5. Testing
|
|
36
|
+
- **Pest** (or PHPUnit) for unit + feature tests; PCOV/Xdebug for coverage; HTTP fakes for external calls; Testcontainers / sqlite-in-memory for integration.
|
|
37
|
+
|
|
38
|
+
### 6. Frameworks
|
|
39
|
+
- **Laravel 12** (min PHP 8.2) — see `performant-laravel.skill.md` for Octane/Eloquent specifics.
|
|
40
|
+
- **Symfony 7.4 (LTS, supported to 2028/2029)** — autowiring, attributes, Messenger for async, API Platform for APIs; latest line is Symfony 8.x.
|
|
41
|
+
|
|
42
|
+
## Steps
|
|
43
|
+
1. **Baseline**: profile a representative request (Blackfire / Xdebug profiler / `phpbench`) before changing anything.
|
|
44
|
+
2. **Enable OPcache + JIT**, measure, then add worker mode (FrankenPHP/RoadRunner) if request boot dominates.
|
|
45
|
+
3. **Kill N+1 and add indexes**; cache the verified-hot, rarely-changing reads.
|
|
46
|
+
4. **Raise the static-analysis level** (PHPStan/Psalm) and let it fail CI; apply Rector for safe upgrades.
|
|
47
|
+
5. **Re-profile** and record the before/after numbers.
|
|
48
|
+
|
|
49
|
+
## Sources (verified 2026-06-10)
|
|
50
|
+
- PHP 8.5 / 8.4 features: <https://www.php.net/releases/8.5/en.php> · <https://php.watch/versions>
|
|
51
|
+
- Laravel 12: <https://laravel.com/docs/12.x/releases>
|
|
52
|
+
- Symfony 7.4 LTS: <https://symfony.com/releases>
|
|
53
|
+
- FrankenPHP: <https://frankenphp.dev/>
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: performant-python
|
|
3
|
+
description: Strategies for high-performance Python systems (FastAPI, Asyncio, UVloop, Memory Optimization).
|
|
4
|
+
triggers: [python, fastapi, performance, asyncio, uvloop, pydantic, scalability, profiling]
|
|
5
|
+
tags: [coding, python, architecture]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Performant Python Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Building high-concurrency, low-latency Python services by leveraging asynchronous patterns, optimized runtimes, and efficient memory management.
|
|
12
|
+
|
|
13
|
+
## Capabilities
|
|
14
|
+
|
|
15
|
+
### 1. Asynchronous Mastery (Asyncio & FastAPI)
|
|
16
|
+
- **Non-blocking I/O**: Use `async`/`await` for all network and disk I/O. Use `run_in_executor` for CPU-bound tasks to avoid blocking the event loop.
|
|
17
|
+
- **Event Loop Tuning**: Use `uvloop` as the drop-in replacement for the default asyncio loop for significant speedups.
|
|
18
|
+
- **Concurrent Execution**: Use `asyncio.gather()` or `asyncio.TaskGroup` (Python 3.11+) for parallel I/O operations.
|
|
19
|
+
|
|
20
|
+
### 2. Database & Data Handling
|
|
21
|
+
- **Async Drivers**: Use `asyncpg` for PostgreSQL or `aiomysql`. Use SQLAlchemy/Tortoise with async support.
|
|
22
|
+
- **Serialization**: Use `ORJSONResponse` or `UJSONResponse` in FastAPI for faster JSON encoding/decoding.
|
|
23
|
+
- **Efficient Models**: Use Pydantic v2 for its Rust-based speed. Use `.model_dump(include={...})` to minimize data transfer.
|
|
24
|
+
|
|
25
|
+
### 3. Memory & Resource Optimization
|
|
26
|
+
- **Slot Classes**: Use `__slots__` in frequently instantiated classes to reduce memory footprint and increase attribute access speed.
|
|
27
|
+
- **Generator Patterns**: Use `generators` and `yield` for processing large datasets to keep memory usage constant (O(1)).
|
|
28
|
+
- **Garbage Collection**: Tune `gc` thresholds if necessary, but prioritize object reuse to minimize pressure.
|
|
29
|
+
|
|
30
|
+
### 4. Deployment & Performance Runtimes
|
|
31
|
+
- **Process Management**: Use Gunicorn with `UvicornWorker` to scale across CPU cores.
|
|
32
|
+
- **Connection Pooling**: Always implement pooling for DB and HTTP clients (e.g., `httpx` instead of `requests`).
|
|
33
|
+
- **Middleware Overhead**: Audit and minimize middleware; each layer adds latency to every request.
|
|
34
|
+
|
|
35
|
+
### 5. Profiling & Monitoring
|
|
36
|
+
- **Deterministic Profiling**: Use `cProfile` for code path analysis.
|
|
37
|
+
- **Sampling Profiling**: Use `Py-Spy` or `Scalene` for production-safe, low-overhead profiling.
|
|
38
|
+
- **APM**: Integrate with Prometheus/Grafana or Datadog for real-time latency and throughput tracking.
|
|
39
|
+
|
|
40
|
+
## Steps
|
|
41
|
+
1. **Identify Blockers**: Use `Py-Spy` to find the hot paths in a running process.
|
|
42
|
+
2. **Async Audit**: Ensure no synchronous libraries (like `requests` or standard `psycopg2`) are used in an async context.
|
|
43
|
+
3. **Pydantic Check**: Upgrade to V2 and optimize model validation constraints.
|
|
44
|
+
4. **Benchmark**: Use `Locust` or `k6` to verify speed improvements under load.
|
|
45
|
+
|
|
46
|
+
## Deliverables
|
|
47
|
+
- `ARCHITECTURE_REVIEW_TEMPLATE.md`: Analysis of blocking calls and memory architecture.
|
|
48
|
+
- `SCALABILITY_ANALYSIS_TEMPLATE.md`: Roadmap for converting sync logic to async.
|
|
49
|
+
- `BENCHMARK_REPORT_TEMPLATE.md`: Response time comparisons (Before/After load testing).
|
|
50
|
+
|
|
51
|
+
## Security & Guardrails
|
|
52
|
+
|
|
53
|
+
### 1. Async Hazards
|
|
54
|
+
- **Race Conditions**: Be cautious with shared state (globals) in async contexts; use `asyncio.Lock` where necessary.
|
|
55
|
+
- **Loop Blocking**: Never run `time.sleep()` or heavy math in the main thread of an async app.
|
|
56
|
+
|
|
57
|
+
### 2. Data Security
|
|
58
|
+
- **Parameterization**: Ensure all DB queries are parameterized, especially when using raw SQL via async drivers.
|
|
59
|
+
|
|
60
|
+
### 3. Agent Guardrails
|
|
61
|
+
- **No Over-optimization**: Don't use `cython` or `numba` unless the pure Python/FastAPI path is fully optimized and still proves insufficient.
|
|
62
|
+
- **Versioning**: Ensure compatibility with Python 3.9+ for modern async features.
|