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,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: refactor
|
|
3
|
+
description: Safe refactoring with test guard — improve code quality without changing behavior
|
|
4
|
+
triggers: [refactor, cleanup, restructure, simplify, extract function, improve code quality]
|
|
5
|
+
tags: [coding]
|
|
6
|
+
core: true
|
|
7
|
+
context_cost: low
|
|
8
|
+
---
|
|
9
|
+
# Refactor Skill
|
|
10
|
+
|
|
11
|
+
## Goal
|
|
12
|
+
Improve code structure, readability, or maintainability while guaranteeing that all existing behavior is preserved. Tests are the safety net — if they fail after refactoring, the refactor was incorrect.
|
|
13
|
+
|
|
14
|
+
## Steps
|
|
15
|
+
|
|
16
|
+
1. **Establish the safety net**
|
|
17
|
+
- Run the full test suite: `[test command from AGENTS.md]`
|
|
18
|
+
- If tests fail before you start: STOP — fix the failing tests first (they're not a safe net)
|
|
19
|
+
- Record baseline: number of passing tests, coverage %
|
|
20
|
+
|
|
21
|
+
2. **Identify the refactoring target**
|
|
22
|
+
- What specific code smell is being addressed?
|
|
23
|
+
- Common targets:
|
|
24
|
+
- Function too long (> 30 lines) → Extract Function
|
|
25
|
+
- Class too large (> 500 lines) → Extract Class / Split by Responsibility
|
|
26
|
+
- Duplicated logic (> 3 occurrences) → Extract Method/Module
|
|
27
|
+
- Magic numbers/strings → Extract Constants
|
|
28
|
+
- Deep nesting (> 3 levels) → Early Returns / Extract Method
|
|
29
|
+
- God class → Decompose to smaller, focused classes
|
|
30
|
+
- Long parameter list → Introduce Parameter Object
|
|
31
|
+
|
|
32
|
+
3. **Apply ONE refactoring at a time**
|
|
33
|
+
- Make the smallest possible change
|
|
34
|
+
- Run tests immediately after each change
|
|
35
|
+
- If tests fail: REVERT the change (don't try to fix tests and refactor simultaneously)
|
|
36
|
+
|
|
37
|
+
4. **Common refactoring patterns**
|
|
38
|
+
|
|
39
|
+
**Extract Function:**
|
|
40
|
+
```typescript
|
|
41
|
+
// Before: complex inline logic
|
|
42
|
+
function processOrder(order) {
|
|
43
|
+
// 40 lines of validation + calculation + notification
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// After: extracted with clear names
|
|
47
|
+
function processOrder(order) {
|
|
48
|
+
validateOrder(order);
|
|
49
|
+
const total = calculateTotal(order);
|
|
50
|
+
notifyUser(order, total);
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Early Returns (reduce nesting):**
|
|
55
|
+
```typescript
|
|
56
|
+
// Before: deeply nested
|
|
57
|
+
function getDiscount(user) {
|
|
58
|
+
if (user) {
|
|
59
|
+
if (user.isPremium) {
|
|
60
|
+
if (user.yearsActive > 5) {
|
|
61
|
+
return 0.3;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return 0;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// After: early returns
|
|
69
|
+
function getDiscount(user) {
|
|
70
|
+
if (!user) return 0;
|
|
71
|
+
if (!user.isPremium) return 0;
|
|
72
|
+
if (user.yearsActive <= 5) return 0;
|
|
73
|
+
return 0.3;
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Extract Constants:**
|
|
78
|
+
```typescript
|
|
79
|
+
// Before: magic numbers
|
|
80
|
+
if (attempts > 3) lockAccount(15 * 60 * 1000);
|
|
81
|
+
|
|
82
|
+
// After: named constants
|
|
83
|
+
const MAX_LOGIN_ATTEMPTS = 3;
|
|
84
|
+
const LOCKOUT_DURATION_MS = 15 * 60 * 1000; // 15 minutes
|
|
85
|
+
if (attempts > MAX_LOGIN_ATTEMPTS) lockAccount(LOCKOUT_DURATION_MS);
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
5. **After each refactoring step**
|
|
89
|
+
- Run: `[test command]` → must pass
|
|
90
|
+
- Run: `[typecheck command]` → must pass
|
|
91
|
+
- Run: `[lint command]` → must pass
|
|
92
|
+
- Check: complexity still < 10? Length still < 30 lines?
|
|
93
|
+
|
|
94
|
+
6. **Check architecture boundaries** (agentic-linter)
|
|
95
|
+
- After significant structural changes: run agentic-linter skill
|
|
96
|
+
- Ensure no new circular dependencies introduced
|
|
97
|
+
|
|
98
|
+
7. **Final verification**
|
|
99
|
+
- Baseline tests passing count matches post-refactor count
|
|
100
|
+
- Coverage has not decreased
|
|
101
|
+
- No new lint errors or type errors
|
|
102
|
+
|
|
103
|
+
## Constraints
|
|
104
|
+
- NEVER change behavior during refactoring (only structure)
|
|
105
|
+
- NEVER refactor without a passing test suite as safety net
|
|
106
|
+
- NEVER combine refactoring with feature addition in the same commit
|
|
107
|
+
- If a refactor requires fixing tests: stop, analyze whether the tests or the logic is wrong
|
|
108
|
+
|
|
109
|
+
## Output Format
|
|
110
|
+
Report: "Refactored [target]. All [N] tests still passing. Coverage: [X]%. Complexity reduced from [A] to [B]."
|
|
111
|
+
|
|
112
|
+
## Security & Guardrails
|
|
113
|
+
|
|
114
|
+
### 1. Skill Security (Refactor)
|
|
115
|
+
- **Security Check Evasion**: When applying "Extract Function" (Step 4), the agent might accidentally extract a sensitive business operation *outside* of its surrounding authorization boundary (e.g., moving a data fetch out of an `if (isAdmin)` block). The agent must mathematically guarantee that any extracted logic remains strictly within the exact same structural authorization context as its pre-refactored state.
|
|
116
|
+
- **Test Suite Over-Reliance (The Blind Net)**: Step 1 establishes tests as the "safety net." If the existing test suite has poor coverage of critical security paths (e.g., only testing the "Happy Path" of user login), refactoring the code might silently introduce a vulnerability (like bypassing rate limits) that the tests won't catch. The agent must verify that Security/Audit tests explicitly exist and pass before using them as a justification that a refactor is "safe."
|
|
117
|
+
|
|
118
|
+
### 2. System Integration Security
|
|
119
|
+
- **Data Exposure via De-Nesting**: During "Early Returns" refactoring (Step 4), the agent attempts to flatten deep nesting. A poorly executed early return might inadvertently leak information via timing differences or distinct error messages (e.g., changing from a generic "Auth Failed" to explicitly returning exactly which condition failed first). The agent must ensure that early returns in security-critical paths do not introduce Oracle vulnerabilities or alter the established generic failure contract.
|
|
120
|
+
- **Log Forgetting (The Silent Refactor)**: When decomposing a "God Class" (Step 2), the agent might successfully migrate the core logic but forget to migrate the associated audit logging or SIEM (Security Information and Event Management) telemetry calls into the new, decomposed classes. The agent must execute a specific AST-based diff to guarantee 100% preservation of all `.log`, `.audit`, and `.trace` calls.
|
|
121
|
+
|
|
122
|
+
### 3. LLM & Agent Guardrails
|
|
123
|
+
- **The "Clever Code" Hallucination**: The LLM might refactor a highly readable, straightforward function into a hyper-dense, "clever" one-liner (e.g., using complex regex or bitwise operators) to satisfy the "minimize lines" heuristic. This destroys auditability and hides potential logical flaws from human reviewers. The agent's linting step (Step 5) must penalize excessive cognitive complexity, forcing the LLM to prioritize readability over brevity.
|
|
124
|
+
- **Silent Behavior Mutation**: The skill dictates "NEVER change behavior" (Constraints). However, LLMs struggle with edge cases. If refactoring a sorting algorithm, the LLM might change it from a stable to an unstable sort, which passes basic tests but causes catastrophic layout shifts in the UI. The agent must generate property-based or fuzz tests *prior* to refactoring complex algorithms to mathematically prove behavioral equivalence.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: secure-coding
|
|
3
|
+
description: Implementing OWASP Proactive Controls (Input Validation, Output Encoding, AuthZ/AuthN).
|
|
4
|
+
triggers: [secure coding]
|
|
5
|
+
tags: [coding]
|
|
6
|
+
core: true
|
|
7
|
+
role: ops-security, eng-backend
|
|
8
|
+
context_cost: low
|
|
9
|
+
---
|
|
10
|
+
# secure-coding Skill
|
|
11
|
+
|
|
12
|
+
## Goal
|
|
13
|
+
This skill guides the implementation of security controls *during* development (Shift Left).
|
|
14
|
+
|
|
15
|
+
## Steps
|
|
16
|
+
## 1. Input Validation (Defense)
|
|
17
|
+
> "Never trust input."
|
|
18
|
+
|
|
19
|
+
- **Syntactic Validation**: Is it an email? Is it a number? (Use Zod/Pydantic).
|
|
20
|
+
- **Semantic Validation**: Is `start_date` before `end_date`? Is `transfer_amount` > 0?
|
|
21
|
+
- **Allow-list**: Only accept known bad characters (e.g., `[a-zA-Z0-9]`). Block everything else.
|
|
22
|
+
|
|
23
|
+
## 2. Output Encoding (Defense)
|
|
24
|
+
> "Context matters."
|
|
25
|
+
|
|
26
|
+
- **HTML Context**: Escape `<` -> `<`. (Prevent XSS).
|
|
27
|
+
- **SQL Context**: Use Parameterized Queries. (Prevent SQLi).
|
|
28
|
+
- **JSON Context**: Ensure valid JSON structure.
|
|
29
|
+
|
|
30
|
+
## 3. Authentication & Authorization
|
|
31
|
+
- **NIST Guidelines**:
|
|
32
|
+
- Passwords: Min 12 chars, no complexity rules, check against pwned passwords.
|
|
33
|
+
- MFA: Required for admin/privileged actions.
|
|
34
|
+
- Sessions: Absolute timeout (e.g., 12 hours) + Idle timeout (e.g., 30 mins).
|
|
35
|
+
- **Authorization**:
|
|
36
|
+
- **Broken**: `if (user.isAdmin)` (Client-side check).
|
|
37
|
+
- **Fixed**: `if (ctx.user.hasPermission('delete:user'))` (Server-side check).
|
|
38
|
+
|
|
39
|
+
## 4. Cryptography
|
|
40
|
+
- **At Rest**: Use AES-256-GCM (Authenticated Encryption).
|
|
41
|
+
- **In Transit**: TLS 1.3 only.
|
|
42
|
+
- **Hashing**: Argon2id or bcrypt (work factor > 12).
|
|
43
|
+
- **Secrets**: Never hardcode. Use `process.env`.
|
|
44
|
+
|
|
45
|
+
## Security & Guardrails
|
|
46
|
+
|
|
47
|
+
### 1. Skill Security (Secure Coding)
|
|
48
|
+
- **Validation Bypass via Type Coercion**: In Step 1 (Input Validation), the agent might rely on loose checking (`==`) instead of strict type checking (`===`), or use a validation library improperly (e.g., forgetting to cast string digits to actual integers before enforcing a `>= 0` rule). An attacker can exploit this loose coercion to bypass semantic validation. The agent must enforce strict type bindings and immutable schemas (e.g., `z.strict()`) at all system boundaries.
|
|
49
|
+
- **Context-Confused Encoding (XSS Mutation)**: In Step 2 (Output Encoding), the agent might correctly encode data for an HTML body but mistakenly use that same encoded string inside an inline Javascript block (`<script> var name = "ENCODED_DATA"; </script>`), which requires entirely different escaping rules. The agent must rigidly track the *destination context* of the tainted data and apply the exact encoding algorithm mandated for that specific DOM or SQL context.
|
|
50
|
+
|
|
51
|
+
### 2. System Integration Security
|
|
52
|
+
- **Hardcoded Secret Regression**: Step 4 states "Never hardcode. Use `process.env`." If the agent is refactoring a legacy file that currently has a hardcoded secret, it might attempt to "fix" it by moving the secret into a standard constant variable at the top of the file, completely failing the objective. The agent must integrate with the environment's Secrets Management pipeline (e.g., AWS Secrets Manager, Doppler) and physically remove the secret string from the codebase.
|
|
53
|
+
- **Crypto Downgrade via Fallback**: When configuring TLS or hashing (Step 4), the LLM might include "fallback" mechanisms to support legacy clients (e.g., allowing TLS 1.2 or MD5 if the primary fails). This enables Man-in-the-Middle downgrade attacks. The agent must enforce strict, configuration-level prohibition of deprecated cryptographic protocols, crashing the application rather than defaulting to insecure algorithms.
|
|
54
|
+
|
|
55
|
+
### 3. LLM & Agent Guardrails
|
|
56
|
+
- **Hallucinated "Safe" Libraries**: An LLM might confidently suggest using a third-party library to handle input sanitization (e.g., `import sanitizeHtml from 'random-npm-package'`) that is actually abandoned or known to be vulnerable. The agent must strictly limit security-critical implementations (Crypto, Auth, Sanitization) to a globally approved, architecturally verified list of standard libraries (e.g., `DOMPurify`, `bcrypt`, `crypto`).
|
|
57
|
+
- **Authorization Drift**: Over long contexts, the LLM might forget the nuanced difference between Authentication (AuthN - "Who are you?") and Authorization (AuthZ - "What can you do?"). It might write code that says `if (user.isAuthenticated()) { deleteDatabase(); }`. The agent's internal prompt pipeline must forcibly inject the `AuthZ != AuthN` constraint immediately before generating any route-handling or controller logic.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sketch-to-diagram
|
|
3
|
+
description: Convert hand-drawn sketches and photos into formal digital diagrams using image recognition + diagram generation.
|
|
4
|
+
triggers: [sketch, hand-drawn, whiteboard photo, napkin, wireframe scan, recognize diagram]
|
|
5
|
+
tags: [coding, architecture, visual, recognition, AI]
|
|
6
|
+
context_cost: high
|
|
7
|
+
---
|
|
8
|
+
# Sketch-to-Diagram Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
Transform hand-drawn sketches (whiteboard photos, napkin drawings, paper wireframes) into formal, editable digital diagrams using the **Sketch → Recognize → Redraw** pipeline:
|
|
12
|
+
1. **Recognize**: Image recognition MCP describes elements, connections, and labels from the sketch
|
|
13
|
+
2. **Structure**: Agent organizes recognized elements into a structured diagram description
|
|
14
|
+
3. **Redraw**: Agent generates formal diagram via Excalidraw MCP, Mermaid code, or Draw.io XML
|
|
15
|
+
|
|
16
|
+
## Prerequisites
|
|
17
|
+
- **Image Recognition MCP**: `image-recognition` must be configured (requires `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`)
|
|
18
|
+
- **Output MCP** (at least one):
|
|
19
|
+
- `excalidraw` — for `.excalidraw` output
|
|
20
|
+
- `drawio` — for Draw.io XML output
|
|
21
|
+
- Or none — for Mermaid text output (no MCP needed)
|
|
22
|
+
- **Optional**: Tesseract OCR installed for text extraction from noisy images
|
|
23
|
+
|
|
24
|
+
## Supported Input Types
|
|
25
|
+
| Input | Examples |
|
|
26
|
+
|---|---|
|
|
27
|
+
| **Whiteboard photos** | Architecture sketches, event storming boards, sprint planning |
|
|
28
|
+
| **Napkin drawings** | Quick flowcharts, ER diagrams, state machines |
|
|
29
|
+
| **Paper wireframes** | UI layouts, page flows, component hierarchies |
|
|
30
|
+
| **Screenshot mockups** | Existing diagram screenshots to recreate as editable |
|
|
31
|
+
| **Hand-drawn charts** | Bar charts, timelines, Gantt outlines |
|
|
32
|
+
| **Annotated screenshots** | Marked-up UIs with arrows and notes |
|
|
33
|
+
|
|
34
|
+
## Steps
|
|
35
|
+
|
|
36
|
+
### Phase 1: Capture & Recognize
|
|
37
|
+
1. **Receive the image** — user provides a file path or base64-encoded image
|
|
38
|
+
2. **Call image-recognition MCP** — send image for analysis:
|
|
39
|
+
- Describe all shapes (rectangles, circles, diamonds, arrows)
|
|
40
|
+
- Identify text labels on each shape
|
|
41
|
+
- Map connections (which arrows connect which shapes)
|
|
42
|
+
- Note colors, groupings, and spatial layout
|
|
43
|
+
3. **Extract text** (optional) — if handwriting is unclear, use Tesseract OCR
|
|
44
|
+
|
|
45
|
+
### Phase 2: Structure
|
|
46
|
+
4. **Build element list** — organize recognized elements into:
|
|
47
|
+
- Nodes: `{id, label, shape, position, color, group}`
|
|
48
|
+
- Edges: `{source, target, label, direction}`
|
|
49
|
+
- Frames/Groups: `{name, children[]}`
|
|
50
|
+
5. **Validate** — check for unconnected nodes, duplicate labels, missing edges
|
|
51
|
+
6. **Present to user** — show structured description for approval before redrawing
|
|
52
|
+
|
|
53
|
+
### Phase 3: Redraw
|
|
54
|
+
7. **Choose output format** based on user preference or diagram complexity:
|
|
55
|
+
- **Excalidraw** (visual, hand-drawn style): Use `excalidraw` MCP tools
|
|
56
|
+
- **Mermaid** (text-based, version-controllable): Generate Mermaid syntax
|
|
57
|
+
- **Draw.io** (enterprise, XML): Use `drawio` MCP tools
|
|
58
|
+
8. **Create diagram** — generate the formal diagram using chosen tool
|
|
59
|
+
9. **Document** — fill `SKETCH_TO_DIAGRAM_TEMPLATE.md` with results
|
|
60
|
+
|
|
61
|
+
## Output Formats
|
|
62
|
+
|
|
63
|
+
| Format | When to Use | MCP Required |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| Excalidraw (`.excalidraw`) | Visual collaboration, hand-drawn aesthetic | `excalidraw` |
|
|
66
|
+
| Mermaid (`.md`) | Version-controlled docs, PRDs, READMEs | None |
|
|
67
|
+
| Draw.io (`.drawio`) | Enterprise docs, Confluence, detailed layouts | `drawio` |
|
|
68
|
+
| PNG/SVG export | Static documentation, presentations | Depends on source |
|
|
69
|
+
|
|
70
|
+
## Usage Examples
|
|
71
|
+
|
|
72
|
+
### Whiteboard photo to architecture diagram
|
|
73
|
+
```
|
|
74
|
+
> "Here's a photo of our whiteboard architecture sketch. Convert it to an Excalidraw diagram."
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Napkin flowchart to Mermaid
|
|
78
|
+
```
|
|
79
|
+
> "I drew this flowchart on paper [image]. Convert it to Mermaid syntax for our README."
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### UI wireframe to diagram
|
|
83
|
+
```
|
|
84
|
+
> "Recognize this hand-drawn wireframe and create a component hierarchy diagram."
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Event storming board to formal diagram
|
|
88
|
+
```
|
|
89
|
+
> "Here's a photo of our event storming session. Extract all events, commands, and aggregates into a structured diagram."
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Deliverables
|
|
93
|
+
- `SKETCH_TO_DIAGRAM_TEMPLATE.md`: Structured report with original image description, recognized elements, and generated diagram
|
|
94
|
+
- Generated diagram file (`.excalidraw`, `.md` with Mermaid, or `.drawio`)
|
|
95
|
+
|
|
96
|
+
## Security & Guardrails
|
|
97
|
+
|
|
98
|
+
### 1. Image Processing Security
|
|
99
|
+
- **Vision API Only**: Images are sent to the configured vision API (Anthropic/OpenAI/Cloudflare) for description. No images are stored or transmitted elsewhere.
|
|
100
|
+
- **Sensitive Content**: If the sketch contains sensitive information (credentials, internal IPs, PII), warn the user before sending to external vision APIs.
|
|
101
|
+
- **Local Alternatives**: For sensitive sketches, use Tesseract OCR (local, no network) for text extraction and have the agent infer structure from text + basic shape description.
|
|
102
|
+
|
|
103
|
+
### 2. Agent Guardrails
|
|
104
|
+
- **Human Verification**: Always present the structured element list to the user before redrawing. Recognition may miss or misinterpret elements.
|
|
105
|
+
- **Iterative Refinement**: After first redraw, ask user to verify and suggest corrections.
|
|
106
|
+
- **Fallback**: If recognition quality is poor (blurry image, complex overlapping), ask the user to describe the diagram verbally and generate from that.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-driven-development
|
|
3
|
+
description: Spec-first workflow where an executable, testable specification is written before code and becomes the single source of truth that tests verify against, flowing spec → acceptance criteria → tasks → implementation.
|
|
4
|
+
triggers: [write the spec before the code, run a spec-first workflow, derive acceptance criteria from a spec, decompose a spec into tasks, make the spec the source of truth, spec kit style development]
|
|
5
|
+
tags: [coding, process, spec-driven, sdlc, requirements]
|
|
6
|
+
core: false
|
|
7
|
+
context_cost: medium
|
|
8
|
+
---
|
|
9
|
+
# Spec-Driven Development
|
|
10
|
+
|
|
11
|
+
## Goal
|
|
12
|
+
Invert the usual order: write the specification *first*, make it concrete and testable, and
|
|
13
|
+
treat it as the single source of truth that the implementation must satisfy and the tests must
|
|
14
|
+
verify against. In a spec-driven (Spec Kit-style) workflow the spec is not prose that rots in a
|
|
15
|
+
wiki — it is an executable contract. Work flows spec → acceptance criteria → tasks →
|
|
16
|
+
implementation, mapping onto the project phases S01 (Requirements) → S02 (Design) → S03
|
|
17
|
+
(Specification) → S04 (Tasks) before S05 (Implementation). The deliverable is a **spec-driven
|
|
18
|
+
workflow plan**: the spec, the acceptance criteria derived from it, the task decomposition, and
|
|
19
|
+
the verification linkage that keeps code, tests, and spec in agreement.
|
|
20
|
+
|
|
21
|
+
## Steps
|
|
22
|
+
1. **Capture requirements as the spec's intent (S01).** Before writing the spec, pin down *what*
|
|
23
|
+
and *why* — the user need, scope, and non-goals — separate from *how*. This anchors the spec
|
|
24
|
+
so it specifies behavior, not a premature implementation. Record explicit out-of-scope items
|
|
25
|
+
so the spec can't quietly expand.
|
|
26
|
+
2. **Resolve design constraints (S02).** Settle the architectural decisions and constraints the
|
|
27
|
+
spec must respect (interfaces, quality attributes, tech constraints) via `arch-design.skill`,
|
|
28
|
+
so the specification is grounded in a feasible design rather than wishful behavior.
|
|
29
|
+
3. **Write the executable/testable specification (S03).** Make the spec *verifiable*: every
|
|
30
|
+
requirement stated so a test can pass or fail against it. Prefer concrete, observable behavior
|
|
31
|
+
(inputs, outputs, error cases, edge cases, invariants) over adjectives. Where possible express
|
|
32
|
+
it in an executable form — given/when/then scenarios, contract/schema definitions, or runnable
|
|
33
|
+
examples — so the spec itself can be checked, not just read. This spec is now the single source
|
|
34
|
+
of truth.
|
|
35
|
+
4. **Derive acceptance criteria from the spec.** Turn each spec requirement into explicit,
|
|
36
|
+
binary acceptance criteria ("given X, when Y, the system returns Z"; "rejects W with error E").
|
|
37
|
+
Acceptance criteria are the bridge between the spec and the tests — each criterion becomes one
|
|
38
|
+
or more verifications. No criterion may introduce behavior absent from the spec; if it must,
|
|
39
|
+
the spec is amended first.
|
|
40
|
+
5. **Decompose into tasks (S04).** Break the spec + acceptance criteria into atomic, independently
|
|
41
|
+
verifiable tasks (small units, each traceable to specific criteria). Every task carries a link
|
|
42
|
+
back to the spec section and acceptance criteria it fulfills, so the traceability is explicit
|
|
43
|
+
and gaps are visible.
|
|
44
|
+
6. **Implement against the spec (S05).** Write code and tests to satisfy the acceptance criteria.
|
|
45
|
+
Tests verify *against the spec* — they assert the specified behavior, so a passing suite means
|
|
46
|
+
"matches the spec," and a spec change forces a test change. Pair with `tdd-cycle.skill` to write
|
|
47
|
+
the criterion's test before its code.
|
|
48
|
+
7. **Keep the spec authoritative.** When reality diverges (a missed case, a changed requirement,
|
|
49
|
+
an impossible criterion), update the *spec first*, then propagate to acceptance criteria,
|
|
50
|
+
tasks, tests, and code. Code that drifts from the spec is a defect in one of the two — never
|
|
51
|
+
let undocumented behavior accumulate. Maintain the spec→criteria→task→test traceability as the
|
|
52
|
+
record that the system does what it claims.
|
|
53
|
+
|
|
54
|
+
## Constraints
|
|
55
|
+
- The spec is the **single source of truth**. When code and spec disagree, one of them is wrong;
|
|
56
|
+
resolve by amending the spec deliberately, never by silently letting code define behavior.
|
|
57
|
+
- A spec is only useful if it is **testable**. Requirements that cannot be turned into a
|
|
58
|
+
pass/fail criterion are aspirations, not spec — rewrite them as observable behavior or remove
|
|
59
|
+
them.
|
|
60
|
+
- Tests verify *against the spec*, so a green suite means "conforms to the current spec," **not**
|
|
61
|
+
"is correct" — the spec itself can be wrong or incomplete. State this honestly; spec-driven
|
|
62
|
+
development moves correctness questions up to spec review, it does not eliminate them.
|
|
63
|
+
- Every acceptance criterion and task MUST trace to a spec section; untraced work is either
|
|
64
|
+
gold-plating or a spec gap. Surface both rather than absorbing them.
|
|
65
|
+
- Changes flow spec → criteria → tasks → tests → code, never the reverse. A code change that
|
|
66
|
+
alters behavior without a spec update is an undocumented divergence to flag.
|
|
67
|
+
|
|
68
|
+
## Output Format
|
|
69
|
+
Produce a **spec-driven workflow plan** containing:
|
|
70
|
+
- The specification: requirements and non-goals (S01), respected design constraints (S02), and
|
|
71
|
+
the executable/testable behavior statements (S03) — inputs, outputs, error and edge cases,
|
|
72
|
+
invariants.
|
|
73
|
+
- The acceptance criteria derived from each spec requirement, each binary and observable.
|
|
74
|
+
- The task decomposition (S04), each task linked to its spec section and acceptance criteria.
|
|
75
|
+
- The verification linkage: which test verifies which criterion, and the spec→criteria→task→test
|
|
76
|
+
traceability map.
|
|
77
|
+
- An honesty note: tests confirm conformance to the spec, not absolute correctness; the spec must
|
|
78
|
+
be reviewed on its own merits. Cross-reference `tdd-cycle.skill` for the test-first inner loop
|
|
79
|
+
and `arch-design.skill` for the design phase.
|
|
80
|
+
|
|
81
|
+
## Security & Guardrails
|
|
82
|
+
|
|
83
|
+
### 1. Skill Security
|
|
84
|
+
- **Risk**: "Tests pass" is reported as "the system is correct," when it only means the code
|
|
85
|
+
conforms to a spec that may itself be wrong or incomplete. Mitigation: every report MUST scope
|
|
86
|
+
the claim to spec-conformance and require the spec to be reviewed independently; the agent MUST
|
|
87
|
+
NOT present spec conformance as proof of correctness.
|
|
88
|
+
- **Risk**: The spec is silently weakened to make a failing test pass. Mitigation: spec changes
|
|
89
|
+
MUST be explicit, reviewed, and version-controlled like code; the agent MUST refuse to edit the
|
|
90
|
+
spec merely to accommodate broken code without surfacing the change for human approval.
|
|
91
|
+
|
|
92
|
+
### 2. System Integration Security
|
|
93
|
+
- **Risk**: Security and compliance requirements live only in the implementation and never enter
|
|
94
|
+
the spec, so they are untested and can be dropped in a refactor. Mitigation: require security,
|
|
95
|
+
authz, data-handling, and compliance requirements to be first-class, testable spec items with
|
|
96
|
+
their own acceptance criteria and traceable tests.
|
|
97
|
+
- **Risk**: Implementation adds undocumented behavior (a hidden endpoint, an extra side effect)
|
|
98
|
+
not in the spec, expanding attack surface invisibly. Mitigation: treat any behavior absent from
|
|
99
|
+
the spec as a divergence to flag; the traceability map MUST expose code paths that map to no
|
|
100
|
+
spec section.
|
|
101
|
+
|
|
102
|
+
### 3. LLM & Agent Guardrails
|
|
103
|
+
- **Risk**: The agent invents acceptance criteria or tasks describing behavior the spec never
|
|
104
|
+
stated, then builds and tests to its own fiction. Mitigation: every criterion and task MUST
|
|
105
|
+
trace to a spec section; the agent MUST amend the spec first (with human review) before adding
|
|
106
|
+
derived behavior, and MUST mark agent-proposed requirements as unconfirmed.
|
|
107
|
+
- **Risk**: The agent writes tests that assert the implementation it just wrote rather than the
|
|
108
|
+
spec, making them tautological and unable to catch spec violations. Mitigation: tests MUST be
|
|
109
|
+
derived from acceptance criteria/spec, not reverse-engineered from the code; the agent MUST
|
|
110
|
+
verify each test would fail if the specified behavior were violated.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tdd-cycle
|
|
3
|
+
description: Red-Green-Refactor TDD loop with mandatory false-positive check
|
|
4
|
+
triggers: [test, TDD, red-green, failing test, write test first, test-driven]
|
|
5
|
+
tags: [typescript, javascript, python, php, go, rust, java, core]
|
|
6
|
+
core: true
|
|
7
|
+
context_cost: low
|
|
8
|
+
---
|
|
9
|
+
# TDD Cycle Skill
|
|
10
|
+
|
|
11
|
+
## Goal
|
|
12
|
+
Implement any feature using strict Test-Driven Development: write the failing test first, implement minimal code to pass it, then refactor. The false-positive check is mandatory.
|
|
13
|
+
|
|
14
|
+
## Steps
|
|
15
|
+
|
|
16
|
+
### Phase 1 — Red (Failing Test)
|
|
17
|
+
|
|
18
|
+
1. **Understand the requirement**
|
|
19
|
+
- Read the relevant task from project/TASKS.md or the user's description
|
|
20
|
+
- Identify the expected behavior as a verifiable predicate
|
|
21
|
+
- Write the requirement in EARS format if not already: "WHEN [X] THE SYSTEM SHALL [Y]"
|
|
22
|
+
|
|
23
|
+
2. **Write the failing test**
|
|
24
|
+
- Create the test file if it doesn't exist (mirrors source file path in tests/ directory)
|
|
25
|
+
- Write the minimal test that captures the expected behavior
|
|
26
|
+
- Use descriptive test names: `"should return 422 when email is invalid"`
|
|
27
|
+
- Test ONE behavior per test case (single assertion focus)
|
|
28
|
+
|
|
29
|
+
3. **Run the test — MUST FAIL**
|
|
30
|
+
- Run: `[test command from AGENTS.md]`
|
|
31
|
+
- Confirm the test fails with the expected error (not a different error)
|
|
32
|
+
- **FALSE POSITIVE CHECK:** If the test passes immediately with NO implementation → the test is broken
|
|
33
|
+
- Common causes: wrong file path, wrong import, test assertion always true
|
|
34
|
+
- Fix the test until it genuinely fails for the right reason
|
|
35
|
+
- Record: what error message confirms the correct failure
|
|
36
|
+
|
|
37
|
+
### Phase 2 — Green (Minimal Implementation)
|
|
38
|
+
|
|
39
|
+
4. **Write minimal implementation**
|
|
40
|
+
- Write only the code needed to make the failing test pass
|
|
41
|
+
- Do NOT add code for features not tested yet
|
|
42
|
+
- Do NOT optimize prematurely
|
|
43
|
+
- If implementation requires new dependencies: invoke knowledge-gap.skill first
|
|
44
|
+
|
|
45
|
+
5. **Run the test — MUST PASS**
|
|
46
|
+
- Run: `[test command from AGENTS.md]`
|
|
47
|
+
- Confirm the specific test now passes
|
|
48
|
+
- Confirm ALL other tests still pass (no regressions)
|
|
49
|
+
- If tests fail: invoke self-heal.skill (max 5 attempts before escalation)
|
|
50
|
+
|
|
51
|
+
### Phase 3 — Refactor
|
|
52
|
+
|
|
53
|
+
6. **Refactor while green**
|
|
54
|
+
- Improve code quality: extract long functions, improve naming, remove duplication
|
|
55
|
+
- Check: Cyclomatic complexity < 10
|
|
56
|
+
- Check: function length < 30 lines
|
|
57
|
+
- Check: no dead code introduced
|
|
58
|
+
- Run tests after EVERY change — must stay green throughout
|
|
59
|
+
|
|
60
|
+
7. **Verify final state**
|
|
61
|
+
- Run: `[test command]` → all pass
|
|
62
|
+
- Run: `[typecheck command]` → zero errors
|
|
63
|
+
- Run: `[lint command]` → zero errors
|
|
64
|
+
- Run: `agentic-linter` boundary check → no violations
|
|
65
|
+
|
|
66
|
+
8. **Mark done**
|
|
67
|
+
- Update task status in project/TASKS.md → DONE
|
|
68
|
+
- Write entry to AUDIT_LOG.md: what was implemented and verified
|
|
69
|
+
|
|
70
|
+
## Constraints
|
|
71
|
+
- NEVER write implementation before the failing test exists
|
|
72
|
+
- NEVER skip the false-positive check
|
|
73
|
+
- NEVER mark a task DONE if tests are red or lint fails
|
|
74
|
+
- NEVER implement more than what is tested
|
|
75
|
+
|
|
76
|
+
## Output Format
|
|
77
|
+
Working implementation with passing tests. Test file and source file updated.
|
|
78
|
+
Report: "DONE — [test name] passes. All [N] tests passing. Coverage: [X]%"
|
|
79
|
+
|
|
80
|
+
## Security & Guardrails
|
|
81
|
+
|
|
82
|
+
### 1. Skill Security (TDD Cycle)
|
|
83
|
+
- **Trivial Red Phase (The Illusion of Failure)**: In Phase 1, the agent must write a failing test. If the agent writes a test that expects a specific specific string error ("Invalid email format"), but the code fails by throwing a generic NullPointerException, the test is "Red," but for the *wrong reason*. The agent must semantically verify that the Red state directly maps to the exact EARS requirement, rejecting tests that fail due to arbitrary syntax or unrelated setup errors.
|
|
84
|
+
- **The "Over-Mocked" Green Phase**: To achieve the "Green" state quickly (Phase 2), the agent might rely entirely on deeply mocking the surrounding architecture (mocking the DB, mocking the auth layer, mocking the validation). While this passes the unit test, it creates a massive blind spot where integration vulnerabilities (like SQL injection) emerge in reality. The agent must limit mocking to true external boundaries, testing business logic against real or purely in-memory data structures whenever possible.
|
|
85
|
+
|
|
86
|
+
### 2. System Integration Security
|
|
87
|
+
- **Test-Induced State Ruin**: When running tests locally or in a shared CI environment, a poorly written failing test might permanently mutate a shared development database or leave dangling file locks, disrupting other team members or parallel sub-agents. The agent must rigorously implement setup/teardown hooks (`beforeEach`/`afterEach`) that cryptographically guarantee environmental state isolation and cleanup, regardless of whether the test passes or fails.
|
|
88
|
+
- **Coverage Masking**: In Phase 2, the agent might write the minimum code to pass. If the test only checks the "Happy Path," the "minimal" implementation will completely omit error handling, input validation, and boundary checks. This artificially inflates test coverage while leaving the application highly vulnerable. The agent must be forced to write separate, explicit "Red" tests for edge cases, null states, and malicious inputs before the TDD cycle is considered complete for a feature.
|
|
89
|
+
|
|
90
|
+
### 3. LLM & Agent Guardrails
|
|
91
|
+
- **The Self-Heal Infinite Loop**: In Phase 2 (Step 5), if tests fail, `self-heal.skill` is invoked. An LLM stuck on a logical error might enter a loop of tweaking variables, running tests, failing, and tweaking again without understanding the underlying math or architecture. The orchestrator must strictly enforce the `max 5 attempts` limit. Upon hitting the limit, the agent must physically lock the task and immediately escalate to human review.
|
|
92
|
+
- **Hallucinated Test Framework Syntax**: The LLM might confidently generate test syntax that belongs to a different framework (e.g., writing Jest assertions in a Pytest file, or attempting to use `.resolves` on a synchronous function). This creates a syntax error rather than a genuine "Red" test failure. The agent must strictly validate its generated test syntax against the project's explicit testing ecosystem (Vitest/Jest/Pest) before classifying the failure state.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: testing-strategy
|
|
3
|
+
description: Formulates a comprehensive testing strategy (Pyramid vs Trophy) and selects appropriate tools.
|
|
4
|
+
triggers: [test plan, testing strategy, qa strategy, e2e testing, integration testing, contract testing]
|
|
5
|
+
tags: [coding]
|
|
6
|
+
context_cost: medium
|
|
7
|
+
---
|
|
8
|
+
# Testing Strategy Skill
|
|
9
|
+
|
|
10
|
+
## Goal
|
|
11
|
+
To help the user or agent define *what* to test, *how* to test it, and *where* to focus effort based on the project architecture.
|
|
12
|
+
|
|
13
|
+
## Strategies
|
|
14
|
+
|
|
15
|
+
### 1. The Testing Pyramid (Classic)
|
|
16
|
+
**Best for**: Monoliths, Backend-heavy apps.
|
|
17
|
+
- **Structure**: 70% Unit, 20% Integration, 10% E2E.
|
|
18
|
+
- **Focus**: Fast feedback loop at the unit level.
|
|
19
|
+
- **Tools**: Jest/Vitest (Unit), Supertest (Int), Playwright (E2E).
|
|
20
|
+
|
|
21
|
+
### 2. The Testing Trophy (Modern / Frontend-heavy)
|
|
22
|
+
**Best for**: React/Next.js apps, Microservices.
|
|
23
|
+
- **Structure**: Static Analysis (Base) -> Unit -> **Integration (Big)** -> E2E (Top).
|
|
24
|
+
- **Focus**: "Write tests. Not too many. Mostly integration." (Kent C. Dodds).
|
|
25
|
+
- **Rationale**: Integration tests give the most confidence per dollar.
|
|
26
|
+
|
|
27
|
+
### 3. Contract Testing (Microservices)
|
|
28
|
+
**Best for**: Distributed systems where teams work independently.
|
|
29
|
+
- **Focus**: Verifying API contracts between Consumer and Provider.
|
|
30
|
+
- **Tools**: Pact.
|
|
31
|
+
|
|
32
|
+
## Advanced Tiers (Beyond the Pyramid)
|
|
33
|
+
|
|
34
|
+
Example-based unit/integration tests only exercise the cases a human thought to write.
|
|
35
|
+
The following four tiers attack the gaps — covering input spaces, relations, failure
|
|
36
|
+
modes, and the quality of the tests themselves.
|
|
37
|
+
|
|
38
|
+
- **Property-Based Testing** (`pbt-strategy.skill`): Instead of asserting on hand-picked examples, declare *properties* (invariants) that must hold for all inputs, then let a generator (Hypothesis, fast-check) throw thousands of randomized cases at the function and **shrink** any counterexample to its minimal form. Best for parsers, serializers, encoders/decoders (round-trip properties), and pure business logic where you can state "for all X, this must be true."
|
|
39
|
+
- **Metamorphic Testing** (`metamorphic-testing.skill`): For systems with no easy oracle (ML models, search ranking, numerical/optimization code, LLM pipelines), you cannot assert the exact output — but you *can* assert **relations between related inputs**. E.g. "translating A→B→A preserves meaning," "adding an irrelevant doc must not change the top result," "scaling all prices by 2x doubles the total." Metamorphic relations turn an unknowable correct answer into a checkable consistency rule.
|
|
40
|
+
- **Chaos / Fault-Injection** (`chaos-fault-injection.skill`): Verify resilience by *deliberately injecting failures* — kill processes, drop network packets, inject latency, exhaust disk/memory, return 500s from dependencies — and assert the system degrades gracefully (circuit breakers trip, retries back off, no data loss). Tests the failure paths that happy-path suites never touch; tools include Toxiproxy, Chaos Mesh, and `pytest`-level dependency stubs that raise on demand.
|
|
41
|
+
- **Mutation Testing**: Measures *test-suite quality* rather than code behavior. A mutation tool (e.g. **mutmut** for Python, Stryker for JS) introduces small faults ("mutants") into the source — flip a `<` to `<=`, swap `+` for `-`, drop a statement — and re-runs the tests. A mutant that survives means no test detected the change, exposing a coverage blind spot. The **mutation score** (killed mutants ÷ total mutants) is a far stronger signal of test effectiveness than line coverage, which the "100% Coverage" Fallacy below warns against.
|
|
42
|
+
|
|
43
|
+
Tests verify determinism; **evals** score probabilistic quality — see `eval-driven-development.skill`.
|
|
44
|
+
|
|
45
|
+
## Steps
|
|
46
|
+
1. **Analyze Project**:
|
|
47
|
+
- Is it a monolith or microservices?
|
|
48
|
+
- Is it UI-heavy or API-heavy?
|
|
49
|
+
2. **Select Strategy**:
|
|
50
|
+
- *UI-Heavy* -> Recommend **Testing Trophy** (Focus on component integration tests).
|
|
51
|
+
- *Complex Business Logic* -> Recommend **Pyramid** (Heavy unit testing).
|
|
52
|
+
- *Microservices* -> Add **Contract Testing**.
|
|
53
|
+
3. **Define Tool Stack**:
|
|
54
|
+
- **Unit/Int**: Vitest (JS/TS), Pytest (Python), PHPUnit (PHP).
|
|
55
|
+
- **E2E**: Playwright (Recommended) or Cypress.
|
|
56
|
+
- **Visual**: Percy, Chromatic.
|
|
57
|
+
|
|
58
|
+
## deliverables
|
|
59
|
+
- Generate a `TEST_PLAN.md` using `templates/coding/TEST_PLAN_TEMPLATE.md`.
|
|
60
|
+
- Configure CI/CD pipelines to run tests in the correct order (Fastest -> Slowest).
|
|
61
|
+
|
|
62
|
+
## Security & Guardrails
|
|
63
|
+
|
|
64
|
+
### 1. Skill Security (Testing Strategy)
|
|
65
|
+
- **Malicious Test De-prioritization**: An attacker might subtly attempt to convince the LLM or developer to abandon the "Testing Trophy" or Contract Testing in favor of an unbalanced, unit-test-only strategy. This intentionally creates systemic blind spots at the integration boundaries, where complex authentication and data-flow vulnerabilities typically reside. The agent must firmly reject any generated `TEST_PLAN.md` that completely omits Integration or E2E coverage for mission-critical paths.
|
|
66
|
+
- **Test Environment Data Exfiltration**: When defining the Tool Stack (Step 3), the agent might recommend tools or SaaS platforms (like cloud-based browser testing or visual regression services) without considering data sovereignty. If the E2E tests process actual production data replicas, routing that data through third-party CI environments constitutes a massive data breach. The strategy MUST mandate data sanitization protocols prior to any data entering the testing ecosystem.
|
|
67
|
+
|
|
68
|
+
### 2. System Integration Security
|
|
69
|
+
- **Symmetrical Vulnerability Injection**: If the agent uses the same LLM context to write both the implementation code and the security tests for that code, the LLM will likely suffer from systemic blind spots, writing tests that perfectly mirror the flaws in its implementation. To break this symmetry, the Testing Strategy must advocate for *adversarial test generation*, where a separate agent persona (e.g., `ops-security`), using a different prompt or model, is responsible for writing the vulnerability tests.
|
|
70
|
+
- **CI/CD Pipeline DoS**: The agent instructs configuring CI/CD pipelines (Deliverables). If the agent recommends a strategy that triggers thousands of Heavy E2E browser tests on every single micro-commit, it will effectively execute a Denial of Service against the organization's CI infrastructure and drastically increase compute costs. The strategy must enforce strict "Test Tiering" (e.g., running slow E2E tests only on PR merge or nightly, while keeping pre-commit hooks fast).
|
|
71
|
+
|
|
72
|
+
### 3. LLM & Agent Guardrails
|
|
73
|
+
- **Hallucinated Testing Frameworks**: The LLM might recommend a trendy but immature or unmaintained testing framework it saw briefly in its training data (e.g., an obscure Selenium wrapper). The agent must strictly bind its tool recommendations (Step 3) to the "Approved Tool Stack" defined in the project's architectural CONSTITUTION, rejecting hallucinated or out-of-policy libraries.
|
|
74
|
+
- **The "100% Coverage" Fallacy**: The LLM might fixate on achieving an artificial metric like "100% Code Coverage" as the primary goal of the strategy. This leads to useless assertion-free tests that just execute code lines to satisfy the coverage crawler, providing a dangerous false sense of security. The strategy prompt must explicitly prioritize "Confidence in Critical Paths" over arbitrary percentage metrics.
|