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.
Files changed (502) hide show
  1. package/LICENSE +25 -0
  2. package/LICENSE-CODE +202 -0
  3. package/README.md +817 -0
  4. package/agents/AGENTS.md +542 -0
  5. package/agents/CONSTITUTION.md +188 -0
  6. package/agents/guides/00-index.md +142 -0
  7. package/agents/guides/ai/a2ui-protocols.md +71 -0
  8. package/agents/guides/ai/actor-agent-frameworks.md +82 -0
  9. package/agents/guides/ai/agent-communication.md +146 -0
  10. package/agents/guides/ai/agent-identity-trust.md +69 -0
  11. package/agents/guides/ai/agent-only-cognition.md +73 -0
  12. package/agents/guides/ai/agent-only-swarms.md +70 -0
  13. package/agents/guides/ai/agent-operating-ergonomics.md +52 -0
  14. package/agents/guides/ai/agent-ui.md +106 -0
  15. package/agents/guides/ai/ai-agentic.md +309 -0
  16. package/agents/guides/ai/beyond-llms.md +60 -0
  17. package/agents/guides/ai/dynamic-capability-loading.md +121 -0
  18. package/agents/guides/ai/gabbe-innovations.md +111 -0
  19. package/agents/guides/ai/model-customization-decisions.md +78 -0
  20. package/agents/guides/ai/multi-agent-systems.md +85 -0
  21. package/agents/guides/ai/self-evolving-skills.md +137 -0
  22. package/agents/guides/ai/self-healing-summary.md +21 -0
  23. package/agents/guides/ai/visual-mcp-integration.md +106 -0
  24. package/agents/guides/architecture/api-standards.md +61 -0
  25. package/agents/guides/architecture/blockchain-dlt.md +36 -0
  26. package/agents/guides/architecture/critical-systems-arch.md +66 -0
  27. package/agents/guides/architecture/event-driven-architecture.md +39 -0
  28. package/agents/guides/architecture/microservices.md +292 -0
  29. package/agents/guides/architecture/monolith.md +303 -0
  30. package/agents/guides/architecture/orchestration.md +75 -0
  31. package/agents/guides/architecture/system-qualities.md +51 -0
  32. package/agents/guides/architecture/system-scalability.md +47 -0
  33. package/agents/guides/architecture/systems-architecture.md +506 -0
  34. package/agents/guides/data/semantic-web.md +23 -0
  35. package/agents/guides/data/sql-nosql.md +305 -0
  36. package/agents/guides/industry/engineering-standards.md +36 -0
  37. package/agents/guides/industry/global-standards.md +24 -0
  38. package/agents/guides/industry/healthcare-fhir.md +33 -0
  39. package/agents/guides/industry/industrial-iot.md +33 -0
  40. package/agents/guides/industry/telecom-networks.md +34 -0
  41. package/agents/guides/languages/c-sharp.md +66 -0
  42. package/agents/guides/languages/go-lang.md +251 -0
  43. package/agents/guides/languages/java.md +73 -0
  44. package/agents/guides/languages/js-ts-nodejs.md +361 -0
  45. package/agents/guides/languages/nodejs-advanced.md +56 -0
  46. package/agents/guides/languages/php-laravel.md +376 -0
  47. package/agents/guides/languages/python-fastapi-ai.md +257 -0
  48. package/agents/guides/languages/rust.md +73 -0
  49. package/agents/guides/ops/compliance-audit.md +177 -0
  50. package/agents/guides/ops/cost-optimization.md +57 -0
  51. package/agents/guides/ops/dev-environments.md +67 -0
  52. package/agents/guides/ops/dev-workflow.md +44 -0
  53. package/agents/guides/ops/gabbe-cli-workflows.md +252 -0
  54. package/agents/guides/ops/production-health.md +62 -0
  55. package/agents/guides/ops/troubleshooting-guide.md +69 -0
  56. package/agents/guides/patterns/agentic-design-patterns.md +308 -0
  57. package/agents/guides/patterns/agentic-patterns.md +43 -0
  58. package/agents/guides/patterns/ai-native-scenarios.md +71 -0
  59. package/agents/guides/patterns/autonomous-swarm-patterns.md +42 -0
  60. package/agents/guides/patterns/design-patterns.md +68 -0
  61. package/agents/guides/patterns/enterprise-migration-scenario.md +58 -0
  62. package/agents/guides/patterns/enterprise-patterns.md +56 -0
  63. package/agents/guides/patterns/software-design-patterns.md +106 -0
  64. package/agents/guides/patterns/time-complexity-analysis.md +116 -0
  65. package/agents/guides/planning/product-requirements.md +407 -0
  66. package/agents/guides/planning/strategic-analysis.md +98 -0
  67. package/agents/guides/planning/visual-product-specs.md +162 -0
  68. package/agents/guides/principles/clean-code-standards.md +51 -0
  69. package/agents/guides/principles/computing-foundations.md +87 -0
  70. package/agents/guides/principles/diagramming-standards.md +568 -0
  71. package/agents/guides/principles/evaluation-strategy.md +103 -0
  72. package/agents/guides/principles/future-tech.md +35 -0
  73. package/agents/guides/principles/human-agent-collaboration.md +54 -0
  74. package/agents/guides/principles/legacy-tech.md +61 -0
  75. package/agents/guides/principles/mathematical-foundations.md +103 -0
  76. package/agents/guides/principles/modeling-methods.md +97 -0
  77. package/agents/guides/principles/no-code-integration.md +84 -0
  78. package/agents/guides/principles/testing-strategy.md +97 -0
  79. package/agents/guides/principles/visual-design-system.md +44 -0
  80. package/agents/guides/processes/RARV_CYCLE.md +262 -0
  81. package/agents/guides/processes/extension-protocol.md +183 -0
  82. package/agents/guides/processes/full-system-lifecycle.md +47 -0
  83. package/agents/guides/processes/knowledge-integration.md +82 -0
  84. package/agents/guides/processes/loki-sdlc-phases.md +446 -0
  85. package/agents/guides/product/green-software.md +38 -0
  86. package/agents/guides/product/sustainability-checks.md +29 -0
  87. package/agents/guides/security/ai-risk-standards-map.md +98 -0
  88. package/agents/guides/security/api-security.md +51 -0
  89. package/agents/guides/security/cryptography-standards.md +38 -0
  90. package/agents/guides/security/privacy-data-protection.md +41 -0
  91. package/agents/guides/security/secure-architecture.md +43 -0
  92. package/agents/guides/security/threat-modeling.md +46 -0
  93. package/agents/memory/AUDIT_LOG.md +48 -0
  94. package/agents/memory/CONTINUITY.md +49 -0
  95. package/agents/memory/PROJECT_STATE.md +134 -0
  96. package/agents/memory/RESUME_POINTER.md +15 -0
  97. package/agents/memory/episodic/DECISION_LOG_TEMPLATE.md +104 -0
  98. package/agents/memory/semantic/PROJECT_KNOWLEDGE_TEMPLATE.md +194 -0
  99. package/agents/memory/semantic/VECTOR_DB_CONFIG_TEMPLATE.json +46 -0
  100. package/agents/personas/00-index.md +148 -0
  101. package/agents/personas/biz-compliance.md +112 -0
  102. package/agents/personas/biz-legal.md +131 -0
  103. package/agents/personas/eng-api.md +110 -0
  104. package/agents/personas/eng-backend.md +113 -0
  105. package/agents/personas/eng-data.md +50 -0
  106. package/agents/personas/eng-database.md +95 -0
  107. package/agents/personas/eng-frontend.md +75 -0
  108. package/agents/personas/eng-infra.md +105 -0
  109. package/agents/personas/eng-messaging.md +50 -0
  110. package/agents/personas/eng-ml.md +50 -0
  111. package/agents/personas/eng-mobile.md +75 -0
  112. package/agents/personas/eng-perf.md +90 -0
  113. package/agents/personas/eng-qa.md +125 -0
  114. package/agents/personas/eng-tooling.md +49 -0
  115. package/agents/personas/ops-compliance.md +109 -0
  116. package/agents/personas/ops-cost.md +92 -0
  117. package/agents/personas/ops-devops.md +85 -0
  118. package/agents/personas/ops-incident.md +123 -0
  119. package/agents/personas/ops-monitor.md +89 -0
  120. package/agents/personas/ops-release.md +91 -0
  121. package/agents/personas/ops-security.md +104 -0
  122. package/agents/personas/ops-sre.md +85 -0
  123. package/agents/personas/orch-coordinator.md +140 -0
  124. package/agents/personas/orch-judge.md +135 -0
  125. package/agents/personas/orch-planner.md +114 -0
  126. package/agents/personas/orch-researcher.md +165 -0
  127. package/agents/personas/prod-architect.md +110 -0
  128. package/agents/personas/prod-design.md +112 -0
  129. package/agents/personas/prod-ethicist.md +50 -0
  130. package/agents/personas/prod-integration.md +120 -0
  131. package/agents/personas/prod-pm.md +115 -0
  132. package/agents/personas/prod-product-ops.md +128 -0
  133. package/agents/personas/prod-research.md +49 -0
  134. package/agents/personas/prod-safety-engineer.md +28 -0
  135. package/agents/personas/prod-tech-lead.md +119 -0
  136. package/agents/personas/ui-design.md +81 -0
  137. package/agents/scripts/check_skills_docs.py +120 -0
  138. package/agents/scripts/compile_skills.py +284 -0
  139. package/agents/scripts/comprehensive_checker.py +187 -0
  140. package/agents/scripts/dump-context.sh +37 -0
  141. package/agents/scripts/eval_skills.py +268 -0
  142. package/agents/scripts/preflight_summary.sh +80 -0
  143. package/agents/scripts/report_duplicates.py +125 -0
  144. package/agents/scripts/setup-context.ps1 +250 -0
  145. package/agents/scripts/setup-context.sh +398 -0
  146. package/agents/scripts/state_export.sh +84 -0
  147. package/agents/scripts/state_import.sh +99 -0
  148. package/agents/scripts/validate_integrity.py +98 -0
  149. package/agents/scripts/validate_links.py +96 -0
  150. package/agents/scripts/validate_methodology_graph.py +194 -0
  151. package/agents/scripts/validate_skills.py +81 -0
  152. package/agents/scripts/verify_e2e_init_flows.py +246 -0
  153. package/agents/scripts/verify_setup_simulation.py +104 -0
  154. package/agents/scripts/verify_triggers_and_mcps.py +159 -0
  155. package/agents/scripts/verify_use_cases.py +498 -0
  156. package/agents/skills/00-index.md +322 -0
  157. package/agents/skills/ai/a2ui-protocols.skill.md +31 -0
  158. package/agents/skills/ai/actor-agent-frameworks.skill.md +31 -0
  159. package/agents/skills/ai/agent-communication.skill.md +36 -0
  160. package/agents/skills/ai/agent-ui.skill.md +31 -0
  161. package/agents/skills/ai/autonomous-swarm-patterns.skill.md +31 -0
  162. package/agents/skills/ai/beyond-llms.skill.md +31 -0
  163. package/agents/skills/ai/context-engineering.skill.md +79 -0
  164. package/agents/skills/ai/llm-as-judge.skill.md +97 -0
  165. package/agents/skills/ai/multi-agent-systems.skill.md +31 -0
  166. package/agents/skills/ai/rag-evaluation.skill.md +93 -0
  167. package/agents/skills/ai/reasoning-patterns.skill.md +125 -0
  168. package/agents/skills/architecture/adaptive-architecture.skill.md +51 -0
  169. package/agents/skills/architecture/api-design.skill.md +92 -0
  170. package/agents/skills/architecture/api-standards.skill.md +31 -0
  171. package/agents/skills/architecture/arch-debt.skill.md +180 -0
  172. package/agents/skills/architecture/arch-design.skill.md +304 -0
  173. package/agents/skills/architecture/arch-patterns.skill.md +52 -0
  174. package/agents/skills/architecture/arch-review.skill.md +326 -0
  175. package/agents/skills/architecture/architecture-governance.skill.md +62 -0
  176. package/agents/skills/architecture/attribute-driven-design.skill.md +108 -0
  177. package/agents/skills/architecture/blockchain-dlt.skill.md +28 -0
  178. package/agents/skills/architecture/compatibility-design.skill.md +51 -0
  179. package/agents/skills/architecture/critical-systems-arch.skill.md +31 -0
  180. package/agents/skills/architecture/design-patterns.skill.md +59 -0
  181. package/agents/skills/architecture/diagramming.skill.md +380 -0
  182. package/agents/skills/architecture/domain-model.skill.md +294 -0
  183. package/agents/skills/architecture/enterprise-migration-scenario.skill.md +31 -0
  184. package/agents/skills/architecture/enterprise-patterns.skill.md +31 -0
  185. package/agents/skills/architecture/error-handling-strategy.skill.md +58 -0
  186. package/agents/skills/architecture/event-driven-architecture.skill.md +31 -0
  187. package/agents/skills/architecture/event-governance.skill.md +55 -0
  188. package/agents/skills/architecture/fitness-functions.skill.md +111 -0
  189. package/agents/skills/architecture/graphql-schema.skill.md +64 -0
  190. package/agents/skills/architecture/legacy-modernization.skill.md +51 -0
  191. package/agents/skills/architecture/microservices.skill.md +31 -0
  192. package/agents/skills/architecture/middleware-design.skill.md +59 -0
  193. package/agents/skills/architecture/monolith.skill.md +31 -0
  194. package/agents/skills/architecture/realtime-comm.skill.md +52 -0
  195. package/agents/skills/architecture/state-management.skill.md +72 -0
  196. package/agents/skills/architecture/system-qualities.skill.md +31 -0
  197. package/agents/skills/architecture/system-scalability.skill.md +31 -0
  198. package/agents/skills/architecture/systems-architecture.skill.md +31 -0
  199. package/agents/skills/architecture/visual-whiteboarding.skill.md +33 -0
  200. package/agents/skills/brain/README.md +70 -0
  201. package/agents/skills/brain/active-inference.skill.md +74 -0
  202. package/agents/skills/brain/brain-mode.skill.md +125 -0
  203. package/agents/skills/brain/cognitive-architectures.skill.md +53 -0
  204. package/agents/skills/brain/cognitive-testing.skill.md +62 -0
  205. package/agents/skills/brain/consciousness-loop.skill.md +68 -0
  206. package/agents/skills/brain/cost-benefit-router.skill.md +89 -0
  207. package/agents/skills/brain/episodic-consolidation.skill.md +43 -0
  208. package/agents/skills/brain/epistemology-knowledge.skill.md +54 -0
  209. package/agents/skills/brain/global-workspace.skill.md +77 -0
  210. package/agents/skills/brain/learning-adaptation.skill.md +68 -0
  211. package/agents/skills/brain/loki-mode.skill.md +267 -0
  212. package/agents/skills/brain/neuroscience-foundations.skill.md +52 -0
  213. package/agents/skills/brain/scripts/active_inference_loop.py +92 -0
  214. package/agents/skills/brain/scripts/cognition_test.py +80 -0
  215. package/agents/skills/brain/scripts/global_workspace.py +104 -0
  216. package/agents/skills/brain/self-improvement.skill.md +80 -0
  217. package/agents/skills/brain/sensory-motor.skill.md +61 -0
  218. package/agents/skills/brain/sequential-thinking.skill.md +48 -0
  219. package/agents/skills/brain/working-memory.skill.md +47 -0
  220. package/agents/skills/coding/agent-trajectory-eval.skill.md +92 -0
  221. package/agents/skills/coding/artisan-commands.skill.md +52 -0
  222. package/agents/skills/coding/browser-tdd.skill.md +131 -0
  223. package/agents/skills/coding/chaos-fault-injection.skill.md +116 -0
  224. package/agents/skills/coding/ci-autofix.skill.md +53 -0
  225. package/agents/skills/coding/clean-coder.skill.md +58 -0
  226. package/agents/skills/coding/code-review.skill.md +100 -0
  227. package/agents/skills/coding/debug.skill.md +100 -0
  228. package/agents/skills/coding/documentation.skill.md +149 -0
  229. package/agents/skills/coding/eval-driven-development.skill.md +107 -0
  230. package/agents/skills/coding/evals/code-review.eval.yaml +29 -0
  231. package/agents/skills/coding/excalidraw.skill.md +90 -0
  232. package/agents/skills/coding/file-processing.skill.md +55 -0
  233. package/agents/skills/coding/git-workflow.skill.md +153 -0
  234. package/agents/skills/coding/metamorphic-testing.skill.md +113 -0
  235. package/agents/skills/coding/mobile-dev.skill.md +41 -0
  236. package/agents/skills/coding/nodejs-expert.skill.md +23 -0
  237. package/agents/skills/coding/output-validation.skill.md +57 -0
  238. package/agents/skills/coding/pbt-strategy.skill.md +117 -0
  239. package/agents/skills/coding/performant-ai.skill.md +62 -0
  240. package/agents/skills/coding/performant-go.skill.md +61 -0
  241. package/agents/skills/coding/performant-laravel.skill.md +70 -0
  242. package/agents/skills/coding/performant-nodejs.skill.md +67 -0
  243. package/agents/skills/coding/performant-php.skill.md +53 -0
  244. package/agents/skills/coding/performant-python.skill.md +62 -0
  245. package/agents/skills/coding/refactor.skill.md +124 -0
  246. package/agents/skills/coding/secure-coding.skill.md +57 -0
  247. package/agents/skills/coding/sketch-to-diagram.skill.md +106 -0
  248. package/agents/skills/coding/spec-driven-development.skill.md +110 -0
  249. package/agents/skills/coding/tdd-cycle.skill.md +92 -0
  250. package/agents/skills/coding/testing-strategy.skill.md +74 -0
  251. package/agents/skills/coding/time-complexity.skill.md +112 -0
  252. package/agents/skills/coding/tldraw-canvas.skill.md +109 -0
  253. package/agents/skills/coding/tool-construction.skill.md +47 -0
  254. package/agents/skills/coding/ui-gen.skill.md +64 -0
  255. package/agents/skills/coding/vibe-coding.skill.md +63 -0
  256. package/agents/skills/coding/visual-design.skill.md +65 -0
  257. package/agents/skills/coordination/agent-interop.skill.md +72 -0
  258. package/agents/skills/coordination/agent-protocol.skill.md +62 -0
  259. package/agents/skills/coordination/agent-workflow-patterns.skill.md +123 -0
  260. package/agents/skills/coordination/agentic-linter.skill.md +134 -0
  261. package/agents/skills/coordination/agentic-patterns.skill.md +79 -0
  262. package/agents/skills/coordination/meta-optimize.skill.md +62 -0
  263. package/agents/skills/coordination/meta-prompting.skill.md +46 -0
  264. package/agents/skills/coordination/multi-agent-orch.skill.md +78 -0
  265. package/agents/skills/coordination/persona-selector.skill.md +78 -0
  266. package/agents/skills/coordination/self-optimize.skill.md +81 -0
  267. package/agents/skills/coordination/swarm-consensus.skill.md +52 -0
  268. package/agents/skills/core/agent-analytics.skill.md +74 -0
  269. package/agents/skills/core/audit-trail.skill.md +122 -0
  270. package/agents/skills/core/clarify.skill.md +89 -0
  271. package/agents/skills/core/emerging-tech.skill.md +52 -0
  272. package/agents/skills/core/empirical-methods.skill.md +101 -0
  273. package/agents/skills/core/evals/clarify.eval.yaml +29 -0
  274. package/agents/skills/core/evals/integrity-check.eval.yaml +23 -0
  275. package/agents/skills/core/evals/research.eval.yaml +23 -0
  276. package/agents/skills/core/final-review.skill.md +66 -0
  277. package/agents/skills/core/integrity-check.skill.md +149 -0
  278. package/agents/skills/core/knowledge-connect.skill.md +77 -0
  279. package/agents/skills/core/knowledge-gap.skill.md +123 -0
  280. package/agents/skills/core/preflight.skill.md +106 -0
  281. package/agents/skills/core/research.skill.md +107 -0
  282. package/agents/skills/core/retrospective.skill.md +59 -0
  283. package/agents/skills/core/sdlc-checkpoint.skill.md +151 -0
  284. package/agents/skills/core/self-heal.skill.md +163 -0
  285. package/agents/skills/core/session-resume.skill.md +125 -0
  286. package/agents/skills/core/skills-registry.skill.md +65 -0
  287. package/agents/skills/core/state-portability.skill.md +89 -0
  288. package/agents/skills/core/state-preserve.skill.md +76 -0
  289. package/agents/skills/core/system-lifecycle.skill.md +51 -0
  290. package/agents/skills/core/update-scan.skill.md +92 -0
  291. package/agents/skills/data/data-engineering.skill.md +56 -0
  292. package/agents/skills/data/data-governance.skill.md +49 -0
  293. package/agents/skills/data/db-migration.skill.md +136 -0
  294. package/agents/skills/data/semantic-web.skill.md +28 -0
  295. package/agents/skills/data/sql-optimization.skill.md +78 -0
  296. package/agents/skills/industry/engineering-standards.skill.md +31 -0
  297. package/agents/skills/industry/global-standards.skill.md +30 -0
  298. package/agents/skills/industry/healthcare-fhir.skill.md +28 -0
  299. package/agents/skills/industry/industrial-iot.skill.md +30 -0
  300. package/agents/skills/industry/telecom-networks.skill.md +30 -0
  301. package/agents/skills/ops/caching-strategy.skill.md +77 -0
  302. package/agents/skills/ops/capacity-planning.skill.md +67 -0
  303. package/agents/skills/ops/cloud-deploy.skill.md +55 -0
  304. package/agents/skills/ops/configuration-management.skill.md +107 -0
  305. package/agents/skills/ops/cost-optimization.skill.md +39 -0
  306. package/agents/skills/ops/decommission-sunset.skill.md +64 -0
  307. package/agents/skills/ops/dependency-lifecycle.skill.md +63 -0
  308. package/agents/skills/ops/deployment.skill.md +217 -0
  309. package/agents/skills/ops/dev-environments.skill.md +31 -0
  310. package/agents/skills/ops/dev-workflow.skill.md +28 -0
  311. package/agents/skills/ops/docker-dev.skill.md +52 -0
  312. package/agents/skills/ops/enterprise-integration.skill.md +53 -0
  313. package/agents/skills/ops/feature-flag-management.skill.md +59 -0
  314. package/agents/skills/ops/incident-response.skill.md +40 -0
  315. package/agents/skills/ops/infra-devops.skill.md +53 -0
  316. package/agents/skills/ops/k8s-dev.skill.md +51 -0
  317. package/agents/skills/ops/memory-optimization.skill.md +45 -0
  318. package/agents/skills/ops/observability-stack-setup.skill.md +62 -0
  319. package/agents/skills/ops/performance-audit.skill.md +178 -0
  320. package/agents/skills/ops/performance-optimization.skill.md +51 -0
  321. package/agents/skills/ops/production-health.skill.md +85 -0
  322. package/agents/skills/ops/production-verifier.skill.md +50 -0
  323. package/agents/skills/ops/queue-management.skill.md +52 -0
  324. package/agents/skills/ops/release-management.skill.md +39 -0
  325. package/agents/skills/ops/release-validation.skill.md +51 -0
  326. package/agents/skills/ops/reliability-sre.skill.md +51 -0
  327. package/agents/skills/ops/runbook-authoring.skill.md +64 -0
  328. package/agents/skills/ops/system-benchmark.skill.md +69 -0
  329. package/agents/skills/ops/tech-debt.skill.md +143 -0
  330. package/agents/skills/ops/troubleshooting-guide.skill.md +31 -0
  331. package/agents/skills/product/accessibility.skill.md +143 -0
  332. package/agents/skills/product/adr-writer.skill.md +110 -0
  333. package/agents/skills/product/business-case.skill.md +70 -0
  334. package/agents/skills/product/change-management.skill.md +90 -0
  335. package/agents/skills/product/decompose.skill.md +75 -0
  336. package/agents/skills/product/design-thinking.skill.md +62 -0
  337. package/agents/skills/product/estimation-sizing.skill.md +87 -0
  338. package/agents/skills/product/evals/spec-writer.eval.yaml +22 -0
  339. package/agents/skills/product/financial-governance.skill.md +88 -0
  340. package/agents/skills/product/green-software.skill.md +46 -0
  341. package/agents/skills/product/ideation-facilitation.skill.md +87 -0
  342. package/agents/skills/product/market-analysis.skill.md +56 -0
  343. package/agents/skills/product/opportunity-assessment.skill.md +89 -0
  344. package/agents/skills/product/product-analytics.skill.md +92 -0
  345. package/agents/skills/product/professional-practice.skill.md +105 -0
  346. package/agents/skills/product/req-elicitation.skill.md +292 -0
  347. package/agents/skills/product/req-review.skill.md +280 -0
  348. package/agents/skills/product/spec-analyze.skill.md +98 -0
  349. package/agents/skills/product/spec-writer.skill.md +114 -0
  350. package/agents/skills/product/stakeholder-management.skill.md +54 -0
  351. package/agents/skills/product/sustainability-checks.skill.md +29 -0
  352. package/agents/skills/product/systems-thinking.skill.md +56 -0
  353. package/agents/skills/product/user-research-synthesis.skill.md +85 -0
  354. package/agents/skills/product/user-story-mapping.skill.md +54 -0
  355. package/agents/skills/product/visual-specs.skill.md +112 -0
  356. package/agents/skills/security/access-control.skill.md +45 -0
  357. package/agents/skills/security/agent-sandboxing.skill.md +69 -0
  358. package/agents/skills/security/ai-ethics-compliance.skill.md +46 -0
  359. package/agents/skills/security/ai-red-teaming.skill.md +74 -0
  360. package/agents/skills/security/ai-safety-guardrails.skill.md +60 -0
  361. package/agents/skills/security/api-security.skill.md +31 -0
  362. package/agents/skills/security/backup-recovery.skill.md +49 -0
  363. package/agents/skills/security/compliance-review.skill.md +152 -0
  364. package/agents/skills/security/cryptography-standards.skill.md +31 -0
  365. package/agents/skills/security/dependency-security.skill.md +47 -0
  366. package/agents/skills/security/hazard-analysis.skill.md +53 -0
  367. package/agents/skills/security/legal-review.skill.md +41 -0
  368. package/agents/skills/security/log-analysis.skill.md +68 -0
  369. package/agents/skills/security/network-security.skill.md +64 -0
  370. package/agents/skills/security/privacy-audit.skill.md +137 -0
  371. package/agents/skills/security/privacy-data-protection.skill.md +31 -0
  372. package/agents/skills/security/prompt-injection-defense.skill.md +67 -0
  373. package/agents/skills/security/reliability-engineering.skill.md +47 -0
  374. package/agents/skills/security/safety-scan.skill.md +49 -0
  375. package/agents/skills/security/secrets-management.skill.md +65 -0
  376. package/agents/skills/security/secure-architecture.skill.md +31 -0
  377. package/agents/skills/security/security-audit.skill.md +164 -0
  378. package/agents/skills/security/threat-model.skill.md +120 -0
  379. package/agents/skills/security/traceability-audit.skill.md +48 -0
  380. package/agents/templates/00-index.md +162 -0
  381. package/agents/templates/architecture/ADAPTIVE_SYSTEM_TEMPLATE.md +35 -0
  382. package/agents/templates/architecture/ADD_WORKBOOK_TEMPLATE.md +81 -0
  383. package/agents/templates/architecture/ADR_TEMPLATE.md +136 -0
  384. package/agents/templates/architecture/ARCHITECTURE_DECISION_MATRIX.md +169 -0
  385. package/agents/templates/architecture/ARCHITECTURE_REVIEW_TEMPLATE.md +241 -0
  386. package/agents/templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md +353 -0
  387. package/agents/templates/architecture/ARCH_DECISION_FRAMEWORK.md +32 -0
  388. package/agents/templates/architecture/C4_ARCHITECTURE_TEMPLATE.md +185 -0
  389. package/agents/templates/architecture/CAPABILITY_MAP_TEMPLATE.md +153 -0
  390. package/agents/templates/architecture/CONTEXT_MAP_TEMPLATE.md +196 -0
  391. package/agents/templates/architecture/DESIGN_PATTERN_USAGE.md +24 -0
  392. package/agents/templates/architecture/DOMAIN_MODEL_TEMPLATE.md +254 -0
  393. package/agents/templates/architecture/FITNESS_FUNCTION_TEMPLATE.md +59 -0
  394. package/agents/templates/architecture/INTEGRATION_SPEC_TEMPLATE.md +38 -0
  395. package/agents/templates/architecture/LEGACY_AUDIT_TEMPLATE.md +34 -0
  396. package/agents/templates/architecture/QUALITY_ATTRIBUTES_TEMPLATE.md +210 -0
  397. package/agents/templates/architecture/SCALABILITY_ANALYSIS_TEMPLATE.md +46 -0
  398. package/agents/templates/architecture/SMART_CONTRACT_TEMPLATE.md +44 -0
  399. package/agents/templates/architecture/SYSTEM_CONTEXT_TEMPLATE.md +197 -0
  400. package/agents/templates/brain/ACTIVE_INFERENCE_LOOP_TEMPLATE.md +42 -0
  401. package/agents/templates/brain/EPISODIC_MEMORY_LOG_TEMPLATE.md +28 -0
  402. package/agents/templates/brain/GLOBAL_WORKSPACE_CONFIG_TEMPLATE.md +44 -0
  403. package/agents/templates/brain/KNOWLEDGE_MAP_TEMPLATE.md +53 -0
  404. package/agents/templates/brain/OODA_LOOP_TRACE_TEMPLATE.md +44 -0
  405. package/agents/templates/brain/PREDICTION_ERROR_LOG_TEMPLATE.md +33 -0
  406. package/agents/templates/brain/PROJECT_CONTEXT_TEMPLATE.md +36 -0
  407. package/agents/templates/brain/SELF_IMPROVEMENT_LOG_TEMPLATE.md +39 -0
  408. package/agents/templates/brain/WORKING_MEMORY_TEMPLATE.md +34 -0
  409. package/agents/templates/coding/CLEAN_CODE_CHECKLIST.md +30 -0
  410. package/agents/templates/coding/DESIGN_TOKENS_TEMPLATE.json +54 -0
  411. package/agents/templates/coding/DEVCONTAINER_TEMPLATE.json +42 -0
  412. package/agents/templates/coding/DEV_SPACE_TEMPLATE.yaml +48 -0
  413. package/agents/templates/coding/E2E_TEST_SUITE_TEMPLATE.md +36 -0
  414. package/agents/templates/coding/EVAL_PLAN_TEMPLATE.md +85 -0
  415. package/agents/templates/coding/EVAL_RUBRIC_TEMPLATE.md +57 -0
  416. package/agents/templates/coding/GOLDEN_DATASET_TEMPLATE.md +73 -0
  417. package/agents/templates/coding/PROPERTY_TEST_CHECKLIST.md +77 -0
  418. package/agents/templates/coding/SKETCH_TO_DIAGRAM_TEMPLATE.md +56 -0
  419. package/agents/templates/coding/TEST_CASE_TEMPLATE.md +28 -0
  420. package/agents/templates/coding/TEST_PLAN_TEMPLATE.md +36 -0
  421. package/agents/templates/coding/TIME_COMPLEXITY_REPORT_TEMPLATE.md +61 -0
  422. package/agents/templates/coordination/AGENTS_TEMPLATE.md +540 -0
  423. package/agents/templates/coordination/AGENT_HANDSHAKE_TEMPLATE.json +37 -0
  424. package/agents/templates/coordination/AGENT_PROFILE_TEMPLATE.md +28 -0
  425. package/agents/templates/coordination/SWARM_ARCHITECTURE_TEMPLATE.md +53 -0
  426. package/agents/templates/coordination/SWARM_CONFIG_TEMPLATE.json +45 -0
  427. package/agents/templates/core/AUDIT_LOG_TEMPLATE.md +75 -0
  428. package/agents/templates/core/BUG_REPORT_TEMPLATE.md +136 -0
  429. package/agents/templates/core/DEPENDENCY_GRAPH_TEMPLATE.md +63 -0
  430. package/agents/templates/core/ESTIMATION_TEMPLATE.md +70 -0
  431. package/agents/templates/core/MCP_CONFIG_TEMPLATE.json +807 -0
  432. package/agents/templates/core/PLAN_TEMPLATE.md +162 -0
  433. package/agents/templates/core/PROJECT_RETROSPECTIVE_TEMPLATE.md +67 -0
  434. package/agents/templates/core/SDLC_TRACKER.md +217 -0
  435. package/agents/templates/core/SESSION_SNAPSHOT_TEMPLATE.md +168 -0
  436. package/agents/templates/core/SYSTEM_ANALYSIS_TEMPLATE.md +52 -0
  437. package/agents/templates/core/TASKS_TEMPLATE.md +104 -0
  438. package/agents/templates/core/TRACEABILITY_MATRIX_TEMPLATE.md +18 -0
  439. package/agents/templates/core/WHITEBOARD_DESIGN_TEMPLATE.md +46 -0
  440. package/agents/templates/data/DATABASE_SCHEMA_TEMPLATE.md +38 -0
  441. package/agents/templates/data/DATA_PIPELINE_TEMPLATE.md +44 -0
  442. package/agents/templates/data/ONTOLOGY_TEMPLATE.md +52 -0
  443. package/agents/templates/industry/ENGINEERING_STANDARDS_REVIEW_TEMPLATE.md +43 -0
  444. package/agents/templates/industry/FHIR_INTEGRATION_TEMPLATE.md +53 -0
  445. package/agents/templates/industry/GLOBAL_STANDARDS_AUDIT_TEMPLATE.md +45 -0
  446. package/agents/templates/industry/IOT_TELEMETRY_TEMPLATE.md +59 -0
  447. package/agents/templates/industry/TELECOM_API_TEMPLATE.md +50 -0
  448. package/agents/templates/ops/BENCHMARK_REPORT_TEMPLATE.md +48 -0
  449. package/agents/templates/ops/CAPACITY_PLAN_TEMPLATE.md +41 -0
  450. package/agents/templates/ops/COST_OPTIMIZATION_REPORT_TEMPLATE.md +40 -0
  451. package/agents/templates/ops/DECOMMISSION_PLAN_TEMPLATE.md +102 -0
  452. package/agents/templates/ops/DEPLOY_CONFIG_TEMPLATE.md +88 -0
  453. package/agents/templates/ops/INCIDENT_POSTMORTEM_TEMPLATE.md +39 -0
  454. package/agents/templates/ops/INFRA_PLAN_TEMPLATE.md +37 -0
  455. package/agents/templates/ops/RELEASE_READINESS_REPORT.md +35 -0
  456. package/agents/templates/ops/RUNBOOK_TEMPLATE.md +103 -0
  457. package/agents/templates/ops/TECH_DEBT_TEMPLATE.md +102 -0
  458. package/agents/templates/product/BUSINESS_CASE_TEMPLATE.md +42 -0
  459. package/agents/templates/product/CHANGE_MANAGEMENT_PLAN_TEMPLATE.md +68 -0
  460. package/agents/templates/product/EMPATHY_MAP_TEMPLATE.md +47 -0
  461. package/agents/templates/product/EXPERIMENT_PLAN_TEMPLATE.md +84 -0
  462. package/agents/templates/product/GREEN_SOFTWARE_REPORT_TEMPLATE.md +42 -0
  463. package/agents/templates/product/IDEATION_LOG_TEMPLATE.md +42 -0
  464. package/agents/templates/product/NFR_TEMPLATE.md +31 -0
  465. package/agents/templates/product/PRD_TEMPLATE.md +222 -0
  466. package/agents/templates/product/PROBLEM_STATEMENT_TEMPLATE.md +32 -0
  467. package/agents/templates/product/REQUIREMENTS_REVIEW_TEMPLATE.md +173 -0
  468. package/agents/templates/product/SPEC_TEMPLATE.md +259 -0
  469. package/agents/templates/product/STAKEHOLDER_REGISTER_TEMPLATE.md +127 -0
  470. package/agents/templates/product/USER_STORY_MAP_TEMPLATE.md +35 -0
  471. package/agents/templates/product/VISUAL_SPEC_PACKAGE_TEMPLATE.md +207 -0
  472. package/agents/templates/security/DATASHEET_TEMPLATE.md +95 -0
  473. package/agents/templates/security/ETHICAL_IMPACT_ASSESSMENT.md +32 -0
  474. package/agents/templates/security/HAZARD_LOG.md +17 -0
  475. package/agents/templates/security/MODEL_CARD_TEMPLATE.md +120 -0
  476. package/agents/templates/security/SAFETY_CASE.md +39 -0
  477. package/agents/templates/security/SAFETY_POLICY.md +25 -0
  478. package/agents/templates/security/SECURITY_CHECKLIST.md +157 -0
  479. package/agents/templates/security/SYSTEM_CARD_TEMPLATE.md +139 -0
  480. package/agents/templates/security/THREAT_MODEL_TEMPLATE.md +171 -0
  481. package/bin/install.js +572 -0
  482. package/docs/CLI_REFERENCE.md +527 -0
  483. package/docs/INSTALL.md +68 -0
  484. package/docs/MCP_CONFIGURATIONS.md +1765 -0
  485. package/docs/PLATFORM_CONTROLS.md +324 -0
  486. package/docs/POST_INSTALL.md +75 -0
  487. package/docs/QUICK_COMMANDS.md +131 -0
  488. package/docs/QUICK_GUIDE.md +914 -0
  489. package/docs/README_FULL.md +1451 -0
  490. package/docs/SCHEMA.md +164 -0
  491. package/docs/V1_RELEASE_CHECKLIST.md +144 -0
  492. package/docs/VERIFICATION_GUIDE.md +283 -0
  493. package/docs/adr/0001-record-architecture-decisions.md +26 -0
  494. package/docs/adr/0002-brain-active-inference-runtime.md +27 -0
  495. package/docs/adr/0003-additive-only-emitter-schema-evolution.md +33 -0
  496. package/docs/assets/GABBE.png +0 -0
  497. package/docs/gabbe.config.example.json +9 -0
  498. package/docs/reports/duplication-report.md +30 -0
  499. package/install.ps1 +90 -0
  500. package/install.sh +89 -0
  501. package/package.json +49 -0
  502. 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.