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,407 @@
|
|
|
1
|
+
# Guide: Product Requirements Engineering
|
|
2
|
+
<!-- Standards, methods, and quality criteria for writing verifiable requirements -->
|
|
3
|
+
<!-- Standards: IEEE 29148:2018, ISO/IEC 25010, IREB, BABOK, EARS -->
|
|
4
|
+
<!-- Technology-agnostic — applies to any product, system, or feature -->
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## What Good Requirements Look Like
|
|
9
|
+
|
|
10
|
+
Bad requirements cause more project failures than bad code. The goal is requirements that are:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
CORRECT: States a real stakeholder need (not an assumed solution)
|
|
14
|
+
COMPLETE: No gaps — all behaviors, errors, and edge cases specified
|
|
15
|
+
CONSISTENT: No contradictions between requirements
|
|
16
|
+
UNAMBIGUOUS: One interpretation only — no wiggle room
|
|
17
|
+
TESTABLE: An independent tester can write a pass/fail test
|
|
18
|
+
FEASIBLE: Achievable within known constraints
|
|
19
|
+
NECESSARY: Actually needed — not gold-plating
|
|
20
|
+
TRACEABLE: Links to a stakeholder goal or use case
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Requirement Types
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
Functional Requirements (FR):
|
|
29
|
+
What the system DOES — behaviors, operations, responses
|
|
30
|
+
"WHEN [trigger], the system SHALL [action]"
|
|
31
|
+
Verified by: test execution
|
|
32
|
+
|
|
33
|
+
Quality Requirements (QR / NFR):
|
|
34
|
+
How well the system performs — quality attributes
|
|
35
|
+
"The system SHALL [behavior] achieving [measurable standard]"
|
|
36
|
+
Verified by: measurement, benchmark, audit
|
|
37
|
+
|
|
38
|
+
Constraints (CON):
|
|
39
|
+
Non-negotiable restrictions on solution space
|
|
40
|
+
"The system SHALL [comply with / use / not exceed] [constraint]"
|
|
41
|
+
Verified by: inspection, compliance review
|
|
42
|
+
|
|
43
|
+
Interface Requirements (IR):
|
|
44
|
+
How the system interacts with external actors and systems
|
|
45
|
+
"The system SHALL communicate with [external] using [protocol/format]"
|
|
46
|
+
Verified by: integration test, protocol validation
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## EARS Syntax (Easy Approach to Requirements Syntax)
|
|
52
|
+
|
|
53
|
+
EARS provides five templates that cover all requirement types. Use these templates
|
|
54
|
+
for every formal requirement statement.
|
|
55
|
+
|
|
56
|
+
### Pattern 1 — Ubiquitous (Always True)
|
|
57
|
+
```
|
|
58
|
+
Template: "The [system name] shall [capability or constraint]."
|
|
59
|
+
Use for: Business rules always in effect; security invariants; data invariants
|
|
60
|
+
|
|
61
|
+
Example:
|
|
62
|
+
"The system shall store all user passwords using a one-way cryptographic hash
|
|
63
|
+
with a minimum work factor of 12."
|
|
64
|
+
|
|
65
|
+
Anti-pattern: "The system should use strong passwords."
|
|
66
|
+
→ No trigger, vague ("strong"), uses "should" not "shall"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Pattern 2 — Event-Driven (When Trigger Fires)
|
|
70
|
+
```
|
|
71
|
+
Template: "WHEN [trigger event] the [system name] shall [response]."
|
|
72
|
+
Use for: User actions; external events; time-based triggers; system events
|
|
73
|
+
|
|
74
|
+
Examples:
|
|
75
|
+
"WHEN an unauthenticated user submits valid credentials,
|
|
76
|
+
the system shall issue a session token with a 15-minute expiry."
|
|
77
|
+
|
|
78
|
+
"WHEN a payment authorization fails after 3 retry attempts,
|
|
79
|
+
the system shall notify the customer and release the reserved inventory."
|
|
80
|
+
|
|
81
|
+
"WHEN a background job has not completed within 30 minutes,
|
|
82
|
+
the system shall mark it as failed and alert the operations team."
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Pattern 3 — State-Driven (While in a State)
|
|
86
|
+
```
|
|
87
|
+
Template: "WHILE [system or user is in state] the [system name] shall [behavior]."
|
|
88
|
+
Use for: Operating modes; session states; system health states; time windows
|
|
89
|
+
|
|
90
|
+
Examples:
|
|
91
|
+
"WHILE a user session is active, the system shall refresh the session token
|
|
92
|
+
automatically every 14 minutes without requiring user interaction."
|
|
93
|
+
|
|
94
|
+
"WHILE the system is in maintenance mode, the system shall return a
|
|
95
|
+
503 Service Unavailable response to all API requests."
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Pattern 4 — Optional Feature (Configuration-Dependent)
|
|
99
|
+
```
|
|
100
|
+
Template: "WHERE [feature or configuration is enabled] the [system name] shall [behavior]."
|
|
101
|
+
Use for: Optional features; licensed capabilities; tenant-level configuration
|
|
102
|
+
|
|
103
|
+
Examples:
|
|
104
|
+
"WHERE multi-factor authentication is enabled for a tenant,
|
|
105
|
+
the system shall require a TOTP code after successful password verification."
|
|
106
|
+
|
|
107
|
+
"WHERE the system is deployed in the EU region, the system shall store all
|
|
108
|
+
personal data exclusively on servers located within the European Economic Area."
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Pattern 5 — Unwanted Behavior (Defensive)
|
|
112
|
+
```
|
|
113
|
+
Template: "IF [unwanted condition] THEN the [system name] shall [protective response]."
|
|
114
|
+
Use for: Error handling; security violations; resource limits; abuse prevention
|
|
115
|
+
|
|
116
|
+
Examples:
|
|
117
|
+
"IF a login attempt fails 5 consecutive times within 15 minutes,
|
|
118
|
+
THEN the system shall lock the account and send a notification to the
|
|
119
|
+
registered email address with an unlock link."
|
|
120
|
+
|
|
121
|
+
"IF the database connection pool is exhausted,
|
|
122
|
+
THEN the system shall return a 503 response with a Retry-After header
|
|
123
|
+
set to 30 seconds."
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Compound EARS (combining patterns)
|
|
127
|
+
```
|
|
128
|
+
Templates may be combined for complex requirements:
|
|
129
|
+
"WHERE [feature enabled] WHEN [trigger] the system shall [response]."
|
|
130
|
+
"WHILE [state] IF [condition] THEN the system shall [response]."
|
|
131
|
+
|
|
132
|
+
Example:
|
|
133
|
+
"WHERE audit logging is enabled WHEN an administrator modifies user permissions,
|
|
134
|
+
the system shall record the change with the administrator's identity, timestamp,
|
|
135
|
+
previous value, and new value in the immutable audit log."
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Requirements Quality Checklist (per requirement)
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
The "shall" test:
|
|
144
|
+
□ Contains exactly one "shall"
|
|
145
|
+
□ Subject is "the system" (not a person)
|
|
146
|
+
|
|
147
|
+
Atomicity:
|
|
148
|
+
□ States ONE behavior (no "and" connecting two behaviors)
|
|
149
|
+
□ If "and" appears — split into two requirements
|
|
150
|
+
|
|
151
|
+
Measurability:
|
|
152
|
+
□ Quality terms are quantified:
|
|
153
|
+
"fast" → "within [N]ms"
|
|
154
|
+
"many" → "[N] or more"
|
|
155
|
+
"high availability" → "[N]% monthly uptime"
|
|
156
|
+
"large" → "[N] MB / GB / TB"
|
|
157
|
+
|
|
158
|
+
Implementation-agnostic:
|
|
159
|
+
□ No technology named (no "using React", "via REST API", "with PostgreSQL")
|
|
160
|
+
□ States WHAT the system does, not HOW
|
|
161
|
+
|
|
162
|
+
Positive statement:
|
|
163
|
+
□ States what SHALL happen, not what should be avoided
|
|
164
|
+
□ Exception: Pattern 5 (unwanted behavior) intentionally defensive
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Requirement Levels and Hierarchy
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
Business Requirement:
|
|
173
|
+
"Increase customer retention by reducing support ticket volume by 30%"
|
|
174
|
+
Level: Strategic goal — NOT a system requirement
|
|
175
|
+
|
|
176
|
+
User Requirement:
|
|
177
|
+
"As a customer, I want to track my order in real-time so I don't need to
|
|
178
|
+
contact support for status updates."
|
|
179
|
+
Level: User story — derived from business requirement
|
|
180
|
+
|
|
181
|
+
System Requirement:
|
|
182
|
+
"WHEN an order status changes, the system shall update the customer-facing
|
|
183
|
+
status page within 30 seconds of the change occurring."
|
|
184
|
+
Level: EARS requirement — testable system behavior derived from user requirement
|
|
185
|
+
|
|
186
|
+
Design Constraint (if applicable):
|
|
187
|
+
"The system shall expose order status via a WebSocket connection to minimize
|
|
188
|
+
polling overhead."
|
|
189
|
+
Level: Architecture constraint — acceptable only if mandated, not invented
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## User Stories (Agile Format)
|
|
195
|
+
|
|
196
|
+
When using user stories alongside EARS:
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
User Story template:
|
|
200
|
+
As a [specific actor role],
|
|
201
|
+
I want to [action or goal],
|
|
202
|
+
So that [business benefit or outcome].
|
|
203
|
+
|
|
204
|
+
Acceptance Criteria (GIVEN/WHEN/THEN — BDD format):
|
|
205
|
+
GIVEN [precondition — system state or actor state]
|
|
206
|
+
WHEN [action the actor takes]
|
|
207
|
+
THEN [expected outcome]
|
|
208
|
+
AND [additional assertions]
|
|
209
|
+
|
|
210
|
+
Example:
|
|
211
|
+
As an authenticated customer,
|
|
212
|
+
I want to view a list of my past orders,
|
|
213
|
+
So that I can track the status of recent purchases and reorder items.
|
|
214
|
+
|
|
215
|
+
Acceptance Criteria:
|
|
216
|
+
GIVEN I am authenticated as a customer with at least one order
|
|
217
|
+
WHEN I navigate to my Order History page
|
|
218
|
+
THEN I see a list of all my orders, newest first
|
|
219
|
+
AND each order shows: order number, date, status, and total amount
|
|
220
|
+
AND if I have no orders, I see an empty state with a link to browse products
|
|
221
|
+
|
|
222
|
+
GIVEN I have more than 20 orders
|
|
223
|
+
WHEN I scroll to the bottom of the list
|
|
224
|
+
THEN the next 20 orders load automatically (infinite scroll)
|
|
225
|
+
|
|
226
|
+
GIVEN the service is unavailable
|
|
227
|
+
WHEN I navigate to my Order History page
|
|
228
|
+
THEN I see an error message explaining the issue and a retry option
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## Use Cases (Detailed Process Documentation)
|
|
234
|
+
|
|
235
|
+
Use cases complement EARS by showing full interaction flows:
|
|
236
|
+
|
|
237
|
+
```
|
|
238
|
+
Use Case Template:
|
|
239
|
+
|
|
240
|
+
Name: [Verb + Noun — e.g., "Place Order"]
|
|
241
|
+
ID: UC-NNN
|
|
242
|
+
Actor(s): [Primary actor: e.g., Authenticated Customer]
|
|
243
|
+
[Secondary actors: e.g., Payment Gateway]
|
|
244
|
+
Goal: [What the primary actor wants to achieve]
|
|
245
|
+
Preconditions: [What must be true before this use case can start]
|
|
246
|
+
Trigger: [What starts this use case]
|
|
247
|
+
|
|
248
|
+
Main Flow:
|
|
249
|
+
1. [Actor] [initiates action]
|
|
250
|
+
2. [System] [validates or processes]
|
|
251
|
+
3. [Actor] [provides additional input]
|
|
252
|
+
4. [System] [responds with result]
|
|
253
|
+
5. [Use case ends with: success state]
|
|
254
|
+
|
|
255
|
+
Extensions (Alternative and Exception Flows):
|
|
256
|
+
2a. Validation fails:
|
|
257
|
+
2a.1. [System] displays error message with field-level details
|
|
258
|
+
2a.2. [Actor] corrects input
|
|
259
|
+
2a.3. Return to step 2
|
|
260
|
+
|
|
261
|
+
4a. External service unavailable:
|
|
262
|
+
4a.1. [System] queues action for retry
|
|
263
|
+
4a.2. [System] informs actor of delay
|
|
264
|
+
4a.3. Use case ends with: pending state
|
|
265
|
+
|
|
266
|
+
Postconditions (Success):
|
|
267
|
+
- [System state after successful completion]
|
|
268
|
+
- [What the actor has now]
|
|
269
|
+
- [Any events emitted]
|
|
270
|
+
|
|
271
|
+
Postconditions (Failure):
|
|
272
|
+
- [System state if use case fails]
|
|
273
|
+
- [No partial state changes committed]
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Non-Functional Requirements Framework (ISO 25010)
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
Write at least one QAS for each applicable quality attribute:
|
|
282
|
+
|
|
283
|
+
Performance Efficiency:
|
|
284
|
+
Time behavior: Response time, throughput
|
|
285
|
+
Resource utilization: CPU, memory, bandwidth at stated load
|
|
286
|
+
Capacity: Maximum scale (users, data volume, transactions)
|
|
287
|
+
|
|
288
|
+
Reliability:
|
|
289
|
+
Availability: Percentage uptime over time period
|
|
290
|
+
Fault tolerance: Behavior under component failure
|
|
291
|
+
Recoverability: Recovery time and data loss on failure (RTO, RPO)
|
|
292
|
+
|
|
293
|
+
Usability:
|
|
294
|
+
Appropriateness: Task completion rate
|
|
295
|
+
Learnability: Time to proficiency for new user
|
|
296
|
+
Accessibility: WCAG 2.2 compliance level (A / AA / AAA)
|
|
297
|
+
Error prevention: Number of unrecoverable errors per N sessions
|
|
298
|
+
|
|
299
|
+
Security:
|
|
300
|
+
Confidentiality: Data accessible only to authorized parties
|
|
301
|
+
Integrity: Data not modified without authorization
|
|
302
|
+
Non-repudiation: Actions can be attributed to actor
|
|
303
|
+
Authenticity: Actor identity verifiable
|
|
304
|
+
|
|
305
|
+
Maintainability:
|
|
306
|
+
Modularity: Change confined to N modules for typical feature
|
|
307
|
+
Testability: Coverage achievable within N hours
|
|
308
|
+
Modifiability: New feature implementable in N days
|
|
309
|
+
|
|
310
|
+
Portability:
|
|
311
|
+
Adaptability: Works in [specified environments]
|
|
312
|
+
Installability: Deployment procedure completable in N minutes
|
|
313
|
+
|
|
314
|
+
Compatibility:
|
|
315
|
+
Interoperability: Exchange data with [specified systems] correctly
|
|
316
|
+
Coexistence: Operates alongside [specified systems] without interference
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## Traceability Matrix
|
|
322
|
+
|
|
323
|
+
Maintain bidirectional traceability:
|
|
324
|
+
|
|
325
|
+
```
|
|
326
|
+
Stakeholder → Business Goal → User Story / Use Case → EARS Requirement → Test
|
|
327
|
+
|
|
328
|
+
Template:
|
|
329
|
+
| Business Goal | Use Case | FR-NNN (EARS) | Test ID | Verified |
|
|
330
|
+
|---|---|---|---|---|
|
|
331
|
+
| Reduce support tickets | UC-007 Place Order | FR-024 | T-089 | [YES/NO] |
|
|
332
|
+
|
|
333
|
+
Forward trace: "Which requirements implement this goal?"
|
|
334
|
+
Backward trace: "Why does this requirement exist? Which goal does it serve?"
|
|
335
|
+
|
|
336
|
+
Orphan requirements (no business goal trace) → probably gold-plating → remove or justify
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## Priority Classification (MoSCoW)
|
|
342
|
+
|
|
343
|
+
```
|
|
344
|
+
MUST: System cannot launch without this. Failure = launch blocked.
|
|
345
|
+
Represents minimum viable product. All MUST requirements MUST be met.
|
|
346
|
+
|
|
347
|
+
SHOULD: Expected by stakeholders but not blocking launch.
|
|
348
|
+
High value, do next after MUST.
|
|
349
|
+
|
|
350
|
+
COULD: Desirable if time/budget allows. "Nice to have."
|
|
351
|
+
Include if effort is low and value is clear.
|
|
352
|
+
|
|
353
|
+
WON'T: Explicitly out of scope for this version.
|
|
354
|
+
Agreed not to do now (may revisit later).
|
|
355
|
+
Documenting WON'T prevents scope creep.
|
|
356
|
+
|
|
357
|
+
Rule: MUST requirements should represent ≤ 60% of total effort.
|
|
358
|
+
If MUST > 60%: scope is too large — something must move to SHOULD.
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## Requirements Review Gates
|
|
364
|
+
|
|
365
|
+
```
|
|
366
|
+
Before architecture design begins:
|
|
367
|
+
□ All stakeholders identified
|
|
368
|
+
□ All MUST requirements present and EARS-compliant
|
|
369
|
+
□ No ambiguous terms in any MUST requirement
|
|
370
|
+
□ No consistency conflicts between requirements
|
|
371
|
+
□ All MUST requirements are testable
|
|
372
|
+
□ Traceability from every FR to a use case
|
|
373
|
+
□ Quality requirements exist for top 3 quality attributes
|
|
374
|
+
□ Constraints documented
|
|
375
|
+
□ Out-of-scope defined explicitly
|
|
376
|
+
□ Human (product owner) has approved requirements
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
---
|
|
380
|
+
|
|
381
|
+
## Common Requirements Anti-Patterns
|
|
382
|
+
|
|
383
|
+
```
|
|
384
|
+
"The system shall be fast."
|
|
385
|
+
→ Fix: "WHEN [actor] performs [action], the system SHALL respond within [N]ms
|
|
386
|
+
under [load condition]."
|
|
387
|
+
|
|
388
|
+
"The system shall handle errors gracefully."
|
|
389
|
+
→ Fix: Write one Pattern 5 (unwanted behavior) requirement per significant error condition.
|
|
390
|
+
|
|
391
|
+
"The system shall be secure."
|
|
392
|
+
→ Fix: Write specific security requirements covering authentication, authorization,
|
|
393
|
+
encryption, and input validation separately.
|
|
394
|
+
|
|
395
|
+
"The user shall be able to..."
|
|
396
|
+
→ Fix: "the system" is always the subject of a requirement, not "the user."
|
|
397
|
+
User goals belong in use cases; system requirements describe system behavior.
|
|
398
|
+
|
|
399
|
+
"The system shall provide a REST API."
|
|
400
|
+
→ Fix: This is an architecture/interface requirement, not a functional requirement.
|
|
401
|
+
The underlying need is: "The system shall expose [capability] to [actor]
|
|
402
|
+
via a machine-readable interface." REST is a design choice.
|
|
403
|
+
|
|
404
|
+
"The system shall allow admins to manage users."
|
|
405
|
+
→ Fix: Too vague. Decompose: what does "manage" mean?
|
|
406
|
+
Create, Read, Update, Deactivate, Delete, Unlock — each is a separate FR.
|
|
407
|
+
```
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Strategic Analysis Guide
|
|
2
|
+
<!-- Connects Business Value, User Needs, and System Architecture -->
|
|
3
|
+
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Overview
|
|
7
|
+
|
|
8
|
+
Strategic Analysis is the **"Phase 0"** of the Agentic SDLC. Before writing requirements (Spec-Driven Development), we must answer three fundamental questions:
|
|
9
|
+
|
|
10
|
+
1. **Business:** Is this worth investigating? (Business Case)
|
|
11
|
+
2. **User:** Who is this for and what do they need? (Design Thinking)
|
|
12
|
+
3. **System:** How does this impact the whole? (Systems Thinking)
|
|
13
|
+
|
|
14
|
+
These workflows produce the *raw material* meant to be consumed by the `spec-writer.skill`.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. Business Link (ROI)
|
|
19
|
+
|
|
20
|
+
**Tool:** `business-case.skill`
|
|
21
|
+
**Output:** `product/BUSINESS_CASE_TEMPLATE.md`
|
|
22
|
+
|
|
23
|
+
Use this when you have a feature idea but aren't sure if it pays off.
|
|
24
|
+
|
|
25
|
+
```mermaid
|
|
26
|
+
graph LR
|
|
27
|
+
A[Idea] --> B(Business Case Skill)
|
|
28
|
+
B --> C{Good ROI?}
|
|
29
|
+
C -- Yes --> D[Project Approved]
|
|
30
|
+
C -- No --> E[Kill / Pivot]
|
|
31
|
+
D --> F[Spec Writer Skill]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
[Idea] ---> (Business Case Skill) ---> <Good ROI?>
|
|
36
|
+
|
|
|
37
|
+
+-(No)---+---(Yes)-+
|
|
38
|
+
| |
|
|
39
|
+
v v
|
|
40
|
+
[Kill / Pivot] [Project Approved]
|
|
41
|
+
|
|
|
42
|
+
v
|
|
43
|
+
[Spec Writer Skill]
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Key Questions
|
|
47
|
+
- What is the cost of doing nothing?
|
|
48
|
+
- What is the Payback Period?
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 2. Design Thinking (User Empathy)
|
|
53
|
+
|
|
54
|
+
**Tool:** `design-thinking.skill`
|
|
55
|
+
**Output:** `product/EMPATHY_MAP_TEMPLATE.md`, `docs/strategic/USER_JOURNEY.md`
|
|
56
|
+
|
|
57
|
+
Use this when requirements are vague or you don't fully understand the user's pain.
|
|
58
|
+
|
|
59
|
+
### Workflow
|
|
60
|
+
1. **Empathize:** "Create an Empathy Map for [Persona]."
|
|
61
|
+
2. **Define:** "Draft a Problem Statement based on the map."
|
|
62
|
+
3. **Ideate:** "Brainstorm solutions for [Problem]."
|
|
63
|
+
4. **Prototype:** "Describe a text-based wireframe for the solution."
|
|
64
|
+
|
|
65
|
+
The **Prototype** text becomes the primary input for the PRD.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 3. Systems Thinking (Holistic View)
|
|
70
|
+
|
|
71
|
+
**Tool:** `systems-thinking.skill`
|
|
72
|
+
**Output:** `docs/strategic/SYSTEM_ANALYSIS.md`
|
|
73
|
+
|
|
74
|
+
Use this for complex bugs, re-architecture, or recurring incidents.
|
|
75
|
+
|
|
76
|
+
### The Iceberg Model
|
|
77
|
+
Instead of just fixing the **Event** (the bug), we dig deeper:
|
|
78
|
+
- **Event:** The server crashed.
|
|
79
|
+
- **Pattern:** It crashes every Friday at 4 PM.
|
|
80
|
+
- **Structure:** Batch jobs run then, and we have no rate limiting.
|
|
81
|
+
- **Mental Model:** "Internal jobs don't need limits."
|
|
82
|
+
|
|
83
|
+
### Causal Loop Diagrams
|
|
84
|
+
We map variables to find **Leverage Points**.
|
|
85
|
+
- *Example:* "Adding more developers (A) increases communication overhead (B), which slows down velocity (C), which leads to pressure to add more developers (A)." -> **Reinforcing Loop (Vicious)**.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Integration with SDD
|
|
90
|
+
|
|
91
|
+
These outputs are not shelf-ware. They are **context inputs**:
|
|
92
|
+
|
|
93
|
+
> "Agent, read `product/BUSINESS_CASE_TEMPLATE.md` and `product/EMPATHY_MAP_TEMPLATE.md`. Now, use the **spec-writer skill** to draft a PRD for the solution defined in the Business Case."
|
|
94
|
+
|
|
95
|
+
This ensures your Spec/PRD is:
|
|
96
|
+
1. Financially viable.
|
|
97
|
+
2. User-centric.
|
|
98
|
+
3. Systemically sound.
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
# Guide: Visual Product Design Phase
|
|
2
|
+
|
|
3
|
+
<!-- Bridge between product discovery/PRD and architecture/implementation -->
|
|
4
|
+
<!-- Integrates: image-recognition MCP, Excalidraw MCP, tldraw MCP, Draw.io MCP, Mermaid -->
|
|
5
|
+
|
|
6
|
+
## Purpose
|
|
7
|
+
|
|
8
|
+
Before implementation begins, the system must have **complete visual specifications** alongside text-based requirements. This guide defines how to process visual inputs — whiteboard photos, napkin sketches, architecture diagrams, UI wireframes, state machines, and ER models — into structured, version-controlled design artifacts.
|
|
9
|
+
|
|
10
|
+
**This phase sits between PRD approval (S01) and Architecture Design (S02).**
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
S01 Requirements (PRD) → ★ VISUAL SPEC PHASE ★ → S02 Architecture → … → S05 Implementation
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. Visual Input Catalogue
|
|
19
|
+
|
|
20
|
+
The agent accepts the following visual input types and maps each to appropriate recognition and output tools:
|
|
21
|
+
|
|
22
|
+
| Input Type | Examples | Recognition | Output Tool | Output Format |
|
|
23
|
+
|---|---|---|---|---|
|
|
24
|
+
| **Architecture sketches** | Whiteboard C4, service topology | `image-recognition` | Excalidraw or Mermaid | `.excalidraw` / `flowchart` |
|
|
25
|
+
| **UI wireframes** | Paper wireframes, napkin UIs | `image-recognition` | tldraw | `.tldr` |
|
|
26
|
+
| **Flowcharts** | Process flows, decision trees | `image-recognition` | Mermaid or Excalidraw | `flowchart TD` |
|
|
27
|
+
| **State diagrams** | State machines, lifecycle flows | `image-recognition` | Mermaid | `stateDiagram-v2` |
|
|
28
|
+
| **ER diagrams** | Database schemas, entity relationships | `image-recognition` | Mermaid or Draw.io | `erDiagram` |
|
|
29
|
+
| **Sequence diagrams** | API flows, actor interactions | `image-recognition` | Mermaid | `sequenceDiagram` |
|
|
30
|
+
| **Use case diagrams** | Actor-system interactions | `image-recognition` | Mermaid or Excalidraw | `flowchart` / `.excalidraw` |
|
|
31
|
+
| **Component diagrams** | Module hierarchy, package structure | `image-recognition` | Mermaid | `graph TD` |
|
|
32
|
+
| **Network/deployment diagrams** | Infrastructure topology | `image-recognition` | Draw.io or Excalidraw | `.drawio` / `.excalidraw` |
|
|
33
|
+
| **Mind maps / brainstorm boards** | Feature maps, idea clusters | `image-recognition` | tldraw | `.tldr` |
|
|
34
|
+
| **Figma/design tool exports** | High-fidelity mockups | Direct import | Reference only | `.png` / `.svg` |
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 2. Recognition Pipeline
|
|
39
|
+
|
|
40
|
+
### Step 1: Ingest Visual Input
|
|
41
|
+
```
|
|
42
|
+
User provides: photo, scan, screenshot, or exported image
|
|
43
|
+
Agent receives: file path or base64 image
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Step 2: Recognize Elements
|
|
47
|
+
Using `image-recognition` MCP:
|
|
48
|
+
- Identify all shapes (rectangles, circles, diamonds, arrows, lines)
|
|
49
|
+
- Extract text labels from each shape (OCR)
|
|
50
|
+
- Map connections (which arrows connect which elements)
|
|
51
|
+
- Note spatial groupings, colors, and layers
|
|
52
|
+
- Classify diagram type (architecture / flowchart / wireframe / ER / state / sequence)
|
|
53
|
+
|
|
54
|
+
### Step 3: Structure Results
|
|
55
|
+
Organize recognized elements into typed nodes and edges:
|
|
56
|
+
```
|
|
57
|
+
Nodes: {id, label, type, shape, group, position}
|
|
58
|
+
Edges: {source, target, label, direction, style}
|
|
59
|
+
Groups: {name, children[], color}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Step 4: Human Verification
|
|
63
|
+
**MANDATORY**: Present structured element list to user before generating formal diagrams.
|
|
64
|
+
Recognition is imperfect — missing elements, misread labels, and ambiguous arrows are common.
|
|
65
|
+
|
|
66
|
+
### Step 5: Generate Formal Diagram
|
|
67
|
+
Route to appropriate output tool based on diagram type (see Section 1 table).
|
|
68
|
+
|
|
69
|
+
### Step 6: Document
|
|
70
|
+
Fill `VISUAL_SPEC_PACKAGE_TEMPLATE.md` with all results.
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 3. Output Mapping — Tool Selection Guide
|
|
75
|
+
|
|
76
|
+
### When to use each tool
|
|
77
|
+
|
|
78
|
+
| Diagram Type | **Mermaid** (text) | **Excalidraw** (visual) | **tldraw** (canvas) | **Draw.io** (enterprise) |
|
|
79
|
+
|---|---|---|---|---|
|
|
80
|
+
| Architecture (C4) | ✅ Simple (<15 nodes) | ✅ Complex, hand-drawn style | ❌ | ✅ Enterprise docs |
|
|
81
|
+
| Flowcharts | ✅ Default choice | ✅ Large flows | ❌ | ✅ Confluence export |
|
|
82
|
+
| State machines | ✅ Default choice | ❌ | ❌ | ⚠️ Only if complex |
|
|
83
|
+
| ER diagrams | ✅ Default choice | ❌ | ❌ | ✅ Detailed schemas |
|
|
84
|
+
| Sequence diagrams | ✅ Default choice | ❌ | ❌ | ❌ |
|
|
85
|
+
| UI wireframes | ❌ | ⚠️ Simple layouts | ✅ Default choice | ❌ |
|
|
86
|
+
| Mind maps | ❌ | ✅ | ✅ | ❌ |
|
|
87
|
+
| Deployment/infra | ⚠️ Simple only | ✅ | ❌ | ✅ Default choice |
|
|
88
|
+
|
|
89
|
+
**Priority rule**: Text-based (Mermaid) first, visual tools only when complexity demands.
|
|
90
|
+
See `visual-mcp-integration.md` for full tool selection criteria.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## 4. Integration with Product Templates
|
|
95
|
+
|
|
96
|
+
### PRD_TEMPLATE.md
|
|
97
|
+
- **Section 6 (Data Model)**: Supplement text schema with Mermaid `erDiagram`
|
|
98
|
+
- **Section 8 (UI/UX Notes)**: Link to tldraw wireframes or Figma exports
|
|
99
|
+
- **Section 7 (API Surface)**: Supplement with Mermaid `sequenceDiagram` for key flows
|
|
100
|
+
|
|
101
|
+
### SPEC_TEMPLATE.md
|
|
102
|
+
- Reference generated architecture diagrams (Excalidraw/Mermaid C4)
|
|
103
|
+
- Include state diagrams for complex lifecycle entities
|
|
104
|
+
- Embed or link ER diagrams from the Visual Spec Package
|
|
105
|
+
|
|
106
|
+
### USER_STORY_MAP_TEMPLATE.md
|
|
107
|
+
- Link use case diagrams to user stories
|
|
108
|
+
- Reference flowcharts for acceptance criteria visualization
|
|
109
|
+
|
|
110
|
+
### VISUAL_SPEC_PACKAGE_TEMPLATE.md (NEW)
|
|
111
|
+
- Central document collecting all visual design artifacts
|
|
112
|
+
- Design Readiness Checklist acts as quality gate before S02
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 5. Visual Spec Package Contents
|
|
117
|
+
|
|
118
|
+
A complete Visual Spec Package includes (not all required — depends on project):
|
|
119
|
+
|
|
120
|
+
### Required (for any project)
|
|
121
|
+
- [ ] System architecture diagram (C4 Context at minimum)
|
|
122
|
+
- [ ] At least one workflow/flowchart for the primary user flow
|
|
123
|
+
- [ ] Data model / ER diagram if persistent storage is involved
|
|
124
|
+
|
|
125
|
+
### Recommended (for UI-facing projects)
|
|
126
|
+
- [ ] UI wireframes for key screens (tldraw or Figma)
|
|
127
|
+
- [ ] Screen flow / navigation diagram
|
|
128
|
+
- [ ] Component hierarchy
|
|
129
|
+
|
|
130
|
+
### Optional (for complex systems)
|
|
131
|
+
- [ ] State diagrams for lifecycle entities (orders, payments, sessions)
|
|
132
|
+
- [ ] Sequence diagrams for multi-service interactions
|
|
133
|
+
- [ ] Deployment / infrastructure diagram
|
|
134
|
+
- [ ] Use case diagram for actor-system boundaries
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 6. Design Readiness Gate
|
|
139
|
+
|
|
140
|
+
**The agent MUST NOT proceed to implementation (S03) until the following checklist passes:**
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
Design Readiness Checklist:
|
|
144
|
+
□ PRD approved (S01 complete)
|
|
145
|
+
□ Architecture diagram generated and human-verified
|
|
146
|
+
□ Primary user workflows diagrammed (flowchart/sequence)
|
|
147
|
+
□ Data model documented (text + ER diagram if DB involved)
|
|
148
|
+
□ UI wireframes created (if user-facing)
|
|
149
|
+
□ State diagrams present for entities with >3 states
|
|
150
|
+
□ All scanned/sketched inputs processed and documented
|
|
151
|
+
□ Visual Spec Package template filled
|
|
152
|
+
□ All diagrams committed to git (Mermaid in .md, .excalidraw, .tldr)
|
|
153
|
+
□ Human approval received on Visual Spec Package
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 7. Security Considerations
|
|
159
|
+
|
|
160
|
+
- **External API usage**: `image-recognition` MCP sends images to vision APIs. For sensitive architecture diagrams, use verbal description or local OCR instead.
|
|
161
|
+
- **Diagram storage**: All generated diagrams are local files (`.excalidraw`, `.tldr`, `.drawio`, `.md`). No cloud storage unless explicitly configured.
|
|
162
|
+
- **PII in diagrams**: Check for credentials, internal IPs, or customer data visible in whiteboard photos before processing.
|