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,241 @@
1
+ # Architecture Review Report — [System Name]
2
+ <!-- Created by: arch-review.skill -->
3
+ <!-- Methodology: ATAM-lite (Architecture Tradeoff Analysis Method, adapted for single-agent use) -->
4
+ <!-- Standard: ISO/IEC/IEEE 42010, SEI ATAM -->
5
+
6
+ ---
7
+
8
+ ## Meta
9
+
10
+ | Field | Value |
11
+ |---|---|
12
+ | **System** | [system name] |
13
+ | **Architecture version / commit** | [reference] |
14
+ | **Review date** | [YYYY-MM-DD] |
15
+ | **Reviewer** | [agent / human] |
16
+ | **Artifacts reviewed** | [list: architecture doc, codebase, ADRs, diagrams] |
17
+ | **Requirements reference** | [PRD.md, SPEC.md] |
18
+
19
+ ---
20
+
21
+ ## Executive Summary
22
+
23
+ **Architecture Fitness**: SOUND / AT RISK / INADEQUATE
24
+
25
+ [3-5 sentences: overall assessment, most important finding, immediate recommendation]
26
+
27
+ **Most critical issues**:
28
+ 1. [Critical issue 1]
29
+ 2. [Critical issue 2]
30
+
31
+ ---
32
+
33
+ ## Architecture as Found
34
+
35
+ > Reconstructed or verified architecture description — this is the ACTUAL architecture,
36
+ > not the intended one. Code is the source of truth if documentation conflicts.
37
+
38
+ ### System Context (reconstructed if needed)
39
+
40
+ ```mermaid
41
+ C4Context
42
+ [Reconstruct or verify from actual system]
43
+ ```
44
+
45
+ ```text
46
+ [Reconstruct or verify Level 1 System Context from actual system]
47
+ ```
48
+
49
+ ### Container View (major components / services)
50
+
51
+ ```mermaid
52
+ C4Container
53
+ [Actual containers/components as they exist]
54
+ ```
55
+
56
+ ```text
57
+ [Actual Level 2 containers/components as they exist]
58
+ ```
59
+
60
+ ### Primary Architecture Style
61
+
62
+ **Identified style**: [Layered / Event-Driven / Service-Based / Monolith / etc.]
63
+ **As intended vs as found**: [Does the actual structure match stated intent?]
64
+ **Style consistency**: [Is the style applied consistently, or are there mixed patterns?]
65
+
66
+ ---
67
+
68
+ ## Quality Attribute Scenario Analysis
69
+
70
+ For each QAS, assess whether the architecture satisfies it:
71
+
72
+ | QAS ID | Quality Attr | Stimulus | Measure | Verdict | Evidence |
73
+ |---|---|---|---|---|---|
74
+ | QAS-P01 | Performance | 1k concurrent users | p99 < 2s | AT RISK | [Synchronous DB calls with no caching] |
75
+ | QAS-R01 | Reliability | DB server failure | Recovery < 30s | VIOLATED | [Single DB instance, no replica] |
76
+ | QAS-S01 | Security | SQL injection attempt | Zero success rate | SATISFIED | [Parameterized queries verified] |
77
+
78
+ **Verdict values**:
79
+ - `SATISFIED`: Architecture demonstrably meets this QAS
80
+ - `AT RISK`: May not meet under stress, failure, or scale
81
+ - `VIOLATED`: Architecturally cannot meet this QAS
82
+ - `UNKNOWN`: Insufficient evidence to assess
83
+
84
+ ---
85
+
86
+ ## QAS Details
87
+
88
+ ### QAS-P01: Performance — [VERDICT]
89
+
90
+ **Finding**: [What specific architectural element causes concern or provides assurance]
91
+
92
+ **Evidence**:
93
+ - [Specific code location, design element, or measurement]
94
+ - [Load profile or usage data if available]
95
+
96
+ **Risk**: [What happens if this QAS is violated]
97
+
98
+ **Recommendation**: [Specific architectural change to improve this]
99
+ **Effort**: [hours / days / weeks]
100
+
101
+ ---
102
+
103
+ ### QAS-R01: Reliability — [VERDICT]
104
+
105
+ **Finding**:
106
+ **Evidence**:
107
+ **Risk**:
108
+ **Recommendation**:
109
+ **Effort**:
110
+
111
+ ---
112
+
113
+ <!-- Add one section per QAS -->
114
+
115
+ ---
116
+
117
+ ## Architecture Smells Catalog
118
+
119
+ ### Structural Smells
120
+
121
+ | Smell | Severity | Location | Evidence | Recommendation |
122
+ |---|---|---|---|---|
123
+ | God Component | HIGH | [ComponentX — 45% of all logic] | [import graph shows 23 dependents] | Split by [responsibility boundary] |
124
+ | Cyclic Dependency | HIGH | [Module A → B → C → A] | [madge output] | Extract shared abstraction |
125
+ | Layer Inversion | MEDIUM | [Domain imports Infrastructure] | [file:line] | Invert dependency via interface |
126
+ | Bottleneck | MEDIUM | [SharedUtils — 89% of modules depend on it] | [dependency graph] | Split into specific utilities |
127
+
128
+ ### Communication Smells
129
+
130
+ | Smell | Severity | Location | Evidence | Recommendation |
131
+ |---|---|---|---|---|
132
+ | Missing Circuit Breaker | HIGH | [External payment API call] | [No timeout, no fallback in code] | Add circuit breaker pattern |
133
+ | Synchronous Overuse | MEDIUM | [Email sending in request path] | [POST /orders calls email inline] | Move to async worker |
134
+ | Implicit Contract | MEDIUM | [Service A calls Service B's internal URL] | [Hardcoded internal endpoint in code] | Define explicit client interface |
135
+
136
+ ### Data Smells
137
+
138
+ | Smell | Severity | Description | Recommendation |
139
+ |---|---|---|---|
140
+ | Shared Mutable State | HIGH | [Global config object mutated across threads] | Immutable config or thread-local |
141
+ | Cross-Module DB Access | HIGH | [Module B queries Module A's tables directly] | Route through Module A's API |
142
+
143
+ ---
144
+
145
+ ## Sensitivity Points
146
+
147
+ > Design decisions that, if changed, would significantly affect one or more quality attributes.
148
+
149
+ | Sensitivity Point | Current Decision | Quality Attributes Affected | Change Impact |
150
+ |---|---|---|---|
151
+ | [Database access pattern] | [Synchronous ORM queries] | Performance, Scalability | HIGH — all latency-sensitive operations affected |
152
+ | [Authentication placement] | [Per-endpoint auth checks] | Security, Performance | MEDIUM — missing one check = security hole |
153
+ | [Message queue reliability] | [Fire-and-forget events] | Reliability, Data Consistency | HIGH — lost events = data inconsistency |
154
+
155
+ ---
156
+
157
+ ## Tradeoff Points
158
+
159
+ > Design decisions where improving one quality attribute degrades another.
160
+
161
+ | Tradeoff Point | Decision | Improves | Degrades | Assessment |
162
+ |---|---|---|---|---|
163
+ | [Encryption at rest] | [All data encrypted] | Security | Performance (5-10% overhead) | ACCEPTABLE — security requirement dominates |
164
+ | [Synchronous auth check] | [Check on every request] | Security | Latency (+10ms) | ACCEPTABLE — latency impact minimal |
165
+ | [Eventual consistency] | [Async event updates] | Performance, Scalability | Data Consistency | AT RISK — may violate QAS-R01 |
166
+
167
+ ---
168
+
169
+ ## Risks
170
+
171
+ | Risk ID | Description | Likelihood | Impact | Mitigation |
172
+ |---|---|---|---|---|
173
+ | RISK-001 | Single DB instance — no failover | H | H | Add read replica + automatic failover |
174
+ | RISK-002 | No circuit breaker on payment API | M | H | Implement circuit breaker with fallback |
175
+ | RISK-003 | God component coupling blocks team velocity | H | M | Planned decomposition per ADR-007 |
176
+
177
+ ---
178
+
179
+ ## Non-Risks (Sound Decisions)
180
+
181
+ > Well-reasoned decisions that may look risky but are actually sound.
182
+
183
+ | Decision | Why it's a non-risk |
184
+ |---|---|
185
+ | [Synchronous auth on all requests] | [Adds < 10ms; eliminates async session complexity; security cannot be eventually consistent] |
186
+ | [Single-process architecture] | [Load profile shows < 500 concurrent users; single process is sufficient and simpler] |
187
+
188
+ ---
189
+
190
+ ## Fitness Functions
191
+
192
+ > Checks that should be continuously measured to verify the architecture is healthy.
193
+
194
+ | Fitness Function | Status | Measurement | Frequency |
195
+ |---|---|---|---|
196
+ | No cyclic dependencies | EXISTING | `madge --circular src/` | Each PR |
197
+ | Test coverage ≥ 99% | EXISTING | CI coverage report | Each commit |
198
+ | No cross-layer imports | MISSING | dependency-cruiser | Should be: each PR |
199
+ | p99 latency < 500ms | MISSING | Load test in CI | Should be: each release |
200
+ | No CRITICAL CVEs | EXISTING | `npm audit` | Each PR |
201
+
202
+ **Recommended additions**: [list fitness functions to add based on risks found]
203
+
204
+ ---
205
+
206
+ ## Recommendations (Prioritized)
207
+
208
+ | Priority | Risk/Smell | Recommendation | Effort | ADR Needed |
209
+ |---|---|---|---|---|
210
+ | CRITICAL | RISK-001 — No DB failover | Add read replica and automatic failover | 2-3 days | YES — ADR-NNN |
211
+ | CRITICAL | RISK-002 — No circuit breaker | Implement circuit breaker for external calls | 1 day | NO |
212
+ | HIGH | God Component [X] | Decompose into [A] and [B] by [boundary] | 1 sprint | YES — ADR-NNN |
213
+ | HIGH | Cyclic dependency A→B→C→A | Extract shared abstraction [D] | 3 days | NO |
214
+ | MEDIUM | Missing fitness functions | Add dependency-cruiser + load test to CI | 2 days | NO |
215
+
216
+ ---
217
+
218
+ ## Architecture Evolution Recommendations
219
+
220
+ For significant improvements that require phased implementation:
221
+
222
+ ### Phase 1 (Immediate — before next release)
223
+ [Critical risk mitigations]
224
+
225
+ ### Phase 2 (Next sprint — maintainability)
226
+ [Architecture smell remediation]
227
+
228
+ ### Phase 3 (Next quarter — strategic improvement)
229
+ [Structural changes that improve long-term health]
230
+
231
+ ---
232
+
233
+ ## Review Sign-off
234
+
235
+ **Gate decision**: APPROVED / APPROVED WITH CONDITIONS / BLOCKED
236
+
237
+ **Conditions for BLOCKED or APPROVED WITH CONDITIONS**:
238
+ - [ ] [Specific condition that must be met]
239
+
240
+ **Sign-off**: [human name / date]
241
+ **Next review trigger**: [When should this architecture be reviewed again? Major feature / N months / scale milestone]
@@ -0,0 +1,353 @@
1
+ # Architecture Views — [System Name]
2
+ <!-- Multi-view architecture documentation following 4+1 Views / arc42 structure -->
3
+ <!-- Created by: arch-design.skill (new) or arch-review.skill (reconstructed) -->
4
+ <!-- Diagrams: Mermaid syntax. Render in VS Code (Mermaid Preview), GitHub, or Notion. -->
5
+ <!-- Standard: ISO/IEC/IEEE 42010, arc42, C4 Model, 4+1 Architectural Views -->
6
+
7
+ ---
8
+
9
+ ## Meta
10
+
11
+ | Field | Value |
12
+ |---|---|
13
+ | **System** | [system name] |
14
+ | **Version** | [1.0] |
15
+ | **Date** | [YYYY-MM-DD] |
16
+ | **Status** | DRAFT / APPROVED |
17
+ | **Approved by** | [human/role] |
18
+ | **QAS reference** | [QUALITY_ATTRIBUTES.md] |
19
+ | **ADRs** | [docs/architecture/decisions/] |
20
+
21
+ ---
22
+
23
+ ## 1. Introduction and Goals
24
+
25
+ ### 1.1 Business Goals
26
+
27
+ [What business problems does this system solve? 3-5 bullet points]
28
+
29
+ ### 1.2 Quality Goals (Top 5)
30
+
31
+ | Priority | Quality Attribute | QAS | Measure |
32
+ |---|---|---|---|
33
+ | 1 | [e.g., Reliability] | QAS-R01 | [e.g., 99.9% availability] |
34
+ | 2 | | | |
35
+
36
+ ### 1.3 Stakeholders
37
+
38
+ | Role | Expectation from this architecture |
39
+ |---|---|
40
+ | [Product Owner] | [Architecture supports rapid feature addition] |
41
+ | [Operations Team] | [System can be monitored and deployed without downtime] |
42
+
43
+ ---
44
+
45
+ ## 2. Constraints
46
+
47
+ ### 2.1 Technical Constraints
48
+
49
+ | ID | Constraint | Rationale |
50
+ |---|---|---|
51
+ | TC-001 | [e.g., Must integrate with [existing system] via REST] | [existing investment] |
52
+ | TC-002 | | |
53
+
54
+ ### 2.2 Organizational Constraints
55
+
56
+ | ID | Constraint | Rationale |
57
+ |---|---|---|
58
+ | OC-001 | [e.g., Must be operated by a team of ≤ 5 engineers] | [team size] |
59
+
60
+ ### 2.3 Regulatory Constraints
61
+
62
+ | ID | Constraint | Standard |
63
+ |---|---|---|
64
+ | RC-001 | [e.g., All personal data encrypted at rest and in transit] | [GDPR Art. 32] |
65
+
66
+ ---
67
+
68
+ ## 3. Context and Scope (C4 Level 1)
69
+
70
+ > Highest level view: who uses the system and what external systems does it interact with?
71
+
72
+ ```mermaid
73
+ C4Context
74
+ title System Context — [System Name]
75
+
76
+ Person(primaryUser, "[Primary User Role]", "[What they do with the system]")
77
+ Person(adminUser, "[Admin Role]", "[What admins do]")
78
+
79
+ System(system, "[System Name]", "[One-sentence system description]")
80
+
81
+ System_Ext(extSystem1, "[External System 1]", "[What it provides]")
82
+ System_Ext(extSystem2, "[External System 2]", "[What it provides]")
83
+
84
+ Rel(primaryUser, system, "Uses", "HTTPS")
85
+ Rel(adminUser, system, "Administers", "HTTPS")
86
+ Rel(system, extSystem1, "[interaction label]", "[protocol]")
87
+ Rel(system, extSystem2, "[interaction label]", "[protocol]")
88
+
89
+ UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
90
+ ```
91
+
92
+ **Scope definition:**
93
+ - In scope: [what the system handles]
94
+ - Out of scope: [what it explicitly does not handle]
95
+
96
+ ---
97
+
98
+ ## 4. Solution Strategy
99
+
100
+ ### 4.1 Architecture Style
101
+
102
+ **Primary style**: [Layered / Event-Driven / Microkernel / Service-Based / ...]
103
+ **Rationale**: [Why this style — which quality attributes drive this choice]
104
+
105
+ See: [ADR-001 — Architecture Style Decision]
106
+
107
+ ### 4.2 Decomposition Strategy
108
+
109
+ **Approach**: [Domain-driven / Capability-based / Layered]
110
+ **Key decisions**: [summary of major structural decisions]
111
+
112
+ ### 4.3 Key Technology Areas (without specific technology selection)
113
+
114
+ | Area | Decision | Rationale |
115
+ |---|---|---|
116
+ | Data persistence | [relational / document / event store] | [QAS driven] |
117
+ | Communication style | [synchronous / async / hybrid] | [QAS driven] |
118
+ | API style | [REST / event-based / hybrid] | [consumer needs] |
119
+ | Security approach | [centralized auth / per-service / gateway] | [QAS-S driven] |
120
+
121
+ ---
122
+
123
+ ## 5. Building Block View (C4 Level 2 — Containers)
124
+
125
+ > What are the major deployable units?
126
+
127
+ ```mermaid
128
+ C4Container
129
+ title Container Diagram — [System Name]
130
+
131
+ Person(user, "[User Role]")
132
+
133
+ System_Boundary(system, "[System Name]") {
134
+ Container(webapp, "[Web App / Client]", "[Technology: e.g., Browser SPA]", "[Responsibility]")
135
+ Container(api, "[API / Backend]", "[Technology: e.g., Server process]", "[Responsibility]")
136
+ Container(worker, "[Background Worker]", "[Technology: e.g., Queue consumer]", "[Responsibility]")
137
+ ContainerDb(db, "[Primary Store]", "[Technology: e.g., Relational DB]", "[What data]")
138
+ ContainerDb(cache, "[Cache]", "[Technology: e.g., In-memory store]", "[What's cached]")
139
+ }
140
+
141
+ System_Ext(ext1, "[External System]")
142
+
143
+ Rel(user, webapp, "Uses", "HTTPS")
144
+ Rel(webapp, api, "Calls", "HTTPS/JSON")
145
+ Rel(api, db, "Reads/writes", "TCP")
146
+ Rel(api, cache, "Reads/writes", "TCP")
147
+ Rel(api, ext1, "[interaction]", "[protocol]")
148
+ Rel(api, worker, "Enqueues jobs", "Message Queue")
149
+ Rel(worker, db, "Reads/writes", "TCP")
150
+ ```
151
+
152
+ ### Container Responsibilities
153
+
154
+ | Container | Responsibility | Owns | Does NOT own |
155
+ |---|---|---|---|
156
+ | [Web App] | [User interface, client-side logic] | [UI state] | [Business rules] |
157
+ | [API] | [Business logic, orchestration] | [Domain logic] | [UI, raw data storage] |
158
+ | [Worker] | [Async processing, background jobs] | [Job execution] | [Synchronous requests] |
159
+ | [Primary Store] | [Persistent data storage] | [Canonical data] | [Derived/cached data] |
160
+
161
+ ---
162
+
163
+ ## 6. Component View (C4 Level 3 — inside one container)
164
+
165
+ > Zoom into the most complex container. Create one diagram per major container if needed.
166
+
167
+ ```mermaid
168
+ C4Component
169
+ title Component Diagram — [API Container]
170
+
171
+ Container_Boundary(api, "[API Container]") {
172
+ Component(entrypoint, "[HTTP Router / Entry Point]", "[Type]", "[Routes requests to handlers]")
173
+ Component(auth, "[Authentication Component]", "[Type]", "[Validates identity]")
174
+ Component(authz, "[Authorization Component]", "[Type]", "[Enforces permissions]")
175
+
176
+ Component(featureA, "[Feature A Handler]", "[Type]", "[Handles use case A]")
177
+ Component(featureB, "[Feature B Handler]", "[Type]", "[Handles use case B]")
178
+
179
+ Component(domainA, "[Domain Service A]", "[Type]", "[Core business logic for A]")
180
+ Component(repoA, "[Repository A]", "[Type]", "[Data access for domain A]")
181
+
182
+ Component(ext1client, "[External System Client]", "[Type]", "[Calls external system]")
183
+ }
184
+
185
+ ContainerDb(db, "[Primary Store]")
186
+ System_Ext(ext1, "[External System]")
187
+
188
+ Rel(entrypoint, auth, "All requests through")
189
+ Rel(auth, authz, "Authenticated requests to")
190
+ Rel(authz, featureA, "Authorized requests")
191
+ Rel(featureA, domainA, "Calls")
192
+ Rel(domainA, repoA, "Reads/writes via")
193
+ Rel(repoA, db, "SQL/query")
194
+ Rel(featureA, ext1client, "Calls when needed")
195
+ Rel(ext1client, ext1, "HTTPS API call")
196
+ ```
197
+
198
+ ### Component Responsibilities
199
+
200
+ | Component | Responsibility | Layer | Interface |
201
+ |---|---|---|---|
202
+ | [HTTP Router] | [Route HTTP requests, parse input] | Adapter | [HTTP] |
203
+ | [Auth Component] | [Verify identity token] | Adapter | [Internal] |
204
+ | [Feature A Handler] | [Orchestrate use case A] | Application | [Internal] |
205
+ | [Domain Service A] | [Core business rules for A] | Domain | [Internal] |
206
+ | [Repository A] | [Persist/retrieve A's data] | Infrastructure | [Internal] |
207
+
208
+ ---
209
+
210
+ ## 7. Runtime View (Process / Behavioral)
211
+
212
+ > How do the components interact for key use cases?
213
+
214
+ ### 7.1 [Key Use Case 1 — e.g., User Registration]
215
+
216
+ ```mermaid
217
+ sequenceDiagram
218
+ autonumber
219
+ actor User
220
+ participant EntryPoint as HTTP Router
221
+ participant Auth as Auth Component
222
+ participant Handler as [Feature Handler]
223
+ participant Domain as [Domain Service]
224
+ participant Repo as [Repository]
225
+ participant DB as [Primary Store]
226
+
227
+ User->>EntryPoint: [HTTP request with payload]
228
+ EntryPoint->>Auth: [validate / parse]
229
+ Auth-->>EntryPoint: [identity / error]
230
+ EntryPoint->>Handler: [parsed command/query]
231
+ Handler->>Domain: [business operation]
232
+ Domain->>Repo: [persist / retrieve]
233
+ Repo->>DB: [query]
234
+ DB-->>Repo: [result]
235
+ Repo-->>Domain: [domain objects]
236
+ Domain-->>Handler: [result]
237
+ Handler-->>EntryPoint: [response DTO]
238
+ EntryPoint-->>User: [HTTP response]
239
+ ```
240
+
241
+ ### 7.2 [Key Use Case 2 — e.g., Background Job Processing]
242
+
243
+ ```mermaid
244
+ sequenceDiagram
245
+ [Add sequence for async/background flows]
246
+ ```
247
+
248
+ ---
249
+
250
+ ## 8. Deployment View
251
+
252
+ > Where does the system run?
253
+
254
+ ```mermaid
255
+ C4Deployment
256
+ title Deployment Diagram — [System Name] — [Environment: Production]
257
+
258
+ Deployment_Node(cloud, "[Cloud Provider / Region]") {
259
+ Deployment_Node(lb, "[Load Balancer]") {
260
+ Container(api1, "[API Instance 1]", "[Container/VM]")
261
+ Container(api2, "[API Instance 2]", "[Container/VM]")
262
+ }
263
+ Deployment_Node(worker_node, "[Worker Node]") {
264
+ Container(worker, "[Worker Process]", "[Container/VM]")
265
+ }
266
+ Deployment_Node(data_node, "[Data Layer]") {
267
+ ContainerDb(db_primary, "[Primary DB]", "[Relational DB]")
268
+ ContainerDb(db_replica, "[Read Replica]", "[Relational DB]")
269
+ ContainerDb(cache, "[Cache]", "[In-memory]")
270
+ }
271
+ }
272
+
273
+ Deployment_Node(cdn, "[CDN]") {
274
+ Container(static, "[Static Assets]")
275
+ }
276
+ ```
277
+
278
+ ### Deployment Topology
279
+
280
+ | Environment | Description | Key differences from production |
281
+ |---|---|---|
282
+ | Local Dev | [Docker Compose, single instance] | [Single DB, no cache] |
283
+ | Staging | [Cloud, single-node] | [Real integrations, reduced scale] |
284
+ | Production | [Cloud, multi-node, HA] | [Fully redundant] |
285
+
286
+ ---
287
+
288
+ ## 9. Cross-Cutting Concepts
289
+
290
+ ### 9.1 Security Architecture
291
+
292
+ ```
293
+ Authentication: [approach — token-based, session-based, federated]
294
+ Authorization: [approach — RBAC, ABAC, ACL]
295
+ Boundary: [where is auth enforced — gateway, per-component]
296
+ Data security: [encryption at rest / in transit approach]
297
+ Secret mgmt: [where secrets are stored and how accessed]
298
+ ```
299
+
300
+ ### 9.2 Observability Architecture
301
+
302
+ ```
303
+ Logging: [structured log format, where collected]
304
+ Metrics: [what is measured, where surfaced]
305
+ Tracing: [distributed trace approach, correlation IDs]
306
+ Alerting: [what triggers alerts, who is notified]
307
+ ```
308
+
309
+ ### 9.3 Error Handling Strategy
310
+
311
+ ```
312
+ System errors: [how internal errors are caught and handled]
313
+ User errors: [how validation and user mistakes are communicated]
314
+ External errors: [how upstream failures are handled — circuit breaker, retry, fallback]
315
+ Error taxonomy: [error classification — transient, permanent, user, system]
316
+ ```
317
+
318
+ ---
319
+
320
+ ## 10. Architecture Decisions
321
+
322
+ | ADR | Decision | Status |
323
+ |---|---|---|
324
+ | [ADR-001] | [Architecture style choice] | ACCEPTED |
325
+ | [ADR-002] | [Decomposition strategy] | ACCEPTED |
326
+ | [ADR-003] | [Communication pattern] | ACCEPTED |
327
+
328
+ Full ADRs in: `docs/architecture/decisions/`
329
+
330
+ ---
331
+
332
+ ## 11. Quality Requirements Addressed
333
+
334
+ | QAS | How the architecture addresses it |
335
+ |---|---|
336
+ | QAS-P01 [Performance] | [e.g., Caching layer + async worker for heavy operations] |
337
+ | QAS-R01 [Reliability] | [e.g., Active-passive failover + health checks] |
338
+ | QAS-S01 [Security] | [e.g., Centralized auth gateway + input validation layer] |
339
+
340
+ ---
341
+
342
+ ## 12. Risks and Technical Debt
343
+
344
+ | Risk | Likelihood | Impact | Mitigation |
345
+ |---|---|---|---|
346
+ | [Risk description] | H/M/L | H/M/L | [What reduces this risk] |
347
+
348
+ See: `docs/architecture/ARCHITECTURE_RISKS.md`
349
+
350
+ ---
351
+
352
+ *Last updated: [date]*
353
+ *Review trigger: new major feature, team composition change, significant scale change*
@@ -0,0 +1,32 @@
1
+ # Architecture Decision Framework
2
+
3
+ **Decision Title**: [e.g., Monolith vs Microservices for Order Service]
4
+ **Date**: [YYYY-MM-DD]
5
+ **Status**: [Proposed / Accepted / Rejected]
6
+
7
+ ## 1. Context & Problem Statement
8
+ [What are we trying to solve? e.g., "The Order service needs independent scaling for Black Friday."]
9
+
10
+ ## 2. Options Considered
11
+
12
+ | Option | Description | Pros | Cons |
13
+ |---|---|---|---|
14
+ | **Option A** | [e.g., Modular Monolith] | - Simple deployment<br>- Zero network latency | - Harder to scale writes independently |
15
+ | **Option B** | [e.g., Microservices] | - Independent scaling<br>- Tech stack freedom | - High operational complexity<br>- Network latency |
16
+ | **Option C** | [e.g., Serverless] | - Pay-per-use<br>- Infinite scaling | - Cold starts<br>- Vendor lock-in |
17
+
18
+ ## 3. Decision Drivers (NFRs)
19
+ - **Scalability**: [High/Med/Low importance]
20
+ - **Cost**: [Budget constraints]
21
+ - **Time to Market**: [Urgency]
22
+ - **Maintainability**: [Team skill level]
23
+
24
+ ## 4. Final Recommendation
25
+ **Selected Option**: [Option B]
26
+
27
+ **Justification**:
28
+ [Why this option won. e.g., "Scalability is the #1 driver. We accept the operational complexity cost."]
29
+
30
+ ## 5. Consequences
31
+ - **Positive**: [e.g., Can scale to 10k TPS]
32
+ - **Negative**: [e.g., Need to implement distributed tracing]