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,51 @@
1
+ # System Qualities: The "Ilities" Guide
2
+
3
+ Building software is easy. Building software that *lasts*, *scales*, and *adapts* is hard.
4
+
5
+ > **Standard:** align quality attributes to **ISO/IEC 25010:2023** (Ed. 2) — the
6
+ > nine product-quality characteristics: Functional Suitability, Performance
7
+ > Efficiency, Compatibility, **Interaction Capability** (was Usability),
8
+ > Reliability, **Safety** (new in 2023), Security, Maintainability, and
9
+ > **Flexibility** (was Portability). Use these as the canonical NFR checklist.
10
+ > Source: <https://www.iso.org/standard/78176.html> (verified 2026-06-10).
11
+
12
+ ## 1. Reliability & SRE
13
+ *Reliability is the most important feature. If it's down, it doesn't matter how fast it is.*
14
+
15
+ - **SLOs (Service Level Objectives)**: Set a target (e.g., 99.9%). Don't aim for 100%.
16
+ - **Error Budgets**: Use the remaining 0.1% to take risks. If you burn the budget, stop shipping features.
17
+ - **Chaos Engineering**: Break things on purpose. If you don't test failover, it won't work when you need it.
18
+
19
+ ## 2. Scalability & Performance
20
+ *Performance is not about being "fast". It's about being "consistent" under load.*
21
+
22
+ - **Caching**: The fastest query is the one you don't make. Use **Cache-Aside** for most cases.
23
+ - **Async Processing**: Don't make the user wait for email sending. Use a Queue (RabbitMQ / SQS).
24
+ - **Database First**: Optimize your SQL queries and Indices before rewriting the app in Rust.
25
+
26
+ ## 3. Compatibility & Evolution
27
+ *Change is constant. Breaking things is optional.*
28
+
29
+ - **Expand & Contract**: The Golden Rule of Zero Downtime Migrations.
30
+ 1. **Add** the new thing.
31
+ 2. **Support** both old and new.
32
+ 3. **Delete** the old thing.
33
+ - **Tolerant Readers**: Follow Postel's Law. Be strict in what you send, but liberal in what you accept.
34
+ - **Forward Compatibility**: Design today's system to ignore tomorrow's unknown fields.
35
+
36
+ ## 4. Observability
37
+ *You can't fix what you can't see.*
38
+
39
+ - **Logs**: "What happened?" (Events)
40
+ - **Metrics**: "Is it healthy?" (Aggregates)
41
+ - **Traces**: "Where did it happen?" (Context)
42
+
43
+ ---
44
+
45
+ ## Core Performance Skills
46
+ - [Performant Node.js](../../skills/coding/performant-nodejs.skill.md)
47
+ - [Performant Laravel](../../skills/coding/performant-laravel.skill.md)
48
+ - [Performant Python](../../skills/coding/performant-python.skill.md)
49
+ - [Performant Go](../../skills/coding/performant-go.skill.md)
50
+ - [Performant AI](../../skills/coding/performant-ai.skill.md)
51
+ - [Performance Optimization](../../skills/ops/performance-optimization.skill.md)
@@ -0,0 +1,47 @@
1
+ # System Scalability Guide
2
+
3
+ ## 1. Introduction
4
+ Scalability is the property of a system to handle a growing amount of work by adding resources to the system. This guide defines standard approaches to both vertical and horizontal scaling.
5
+
6
+ ## 2. The Scaling Axes (The Scale Cube)
7
+
8
+ ### X-Axis: Horizontal Duplication (Cloning)
9
+ - **Concept:** Running multiple identical copies of the application behind a load balancer.
10
+ - **Prerequisites:** The application must be stateless. Any session data or cached data must be externalized to a shared store (like Redis or Memcached).
11
+ - **Pros:** Conceptually simple, highly available.
12
+ - **Cons:** Can be expensive if resources are underutilized; database becomes the bottleneck quickly.
13
+
14
+ ### Y-Axis: Functional Decomposition (Microservices)
15
+ - **Concept:** Splitting a monolithic application into multiple, distinct, independent services based on business boundaries.
16
+ - **Pros:** Allows independent scaling of high-load features (e.g., scaling the Checkout service independently of the Catalog service).
17
+ - **Cons:** High operational complexity, data consistency challenges (requires Sagas or Event Sourcing).
18
+
19
+ ### Z-Axis: Data Partitioning (Sharding)
20
+ - **Concept:** Partitioning a database where each instance handles only a subset of the data (e.g., routing users A-M to Database 1, and N-Z to Database 2).
21
+ - **Pros:** Solves infinite data growth.
22
+ - **Cons:** Extremely complex application logic; cross-shard joins are nearly impossible.
23
+
24
+ ## 3. Vertical Scaling (Scale Up)
25
+ - **Concept:** Adding more CPU, RAM, or faster Disks (IOPS) to a single machine.
26
+ - **When to use:** Early in a project's lifecycle, or for systems like relational databases (up to a certain physical limit) where horizontal scaling is too expensive to re-architect.
27
+ - **Limits:** Hard physical caps on hardware; requires downtime to upgrade.
28
+
29
+ ## 4. Cache Everything
30
+ Before complex scaling, utilize aggressive caching:
31
+ 1. **CDN / Edge Caching:** Static assets and full HTML pages.
32
+ 2. **API Caching:** HTTP Cache-Control headers.
33
+ 3. **App Level Caching:** Redis/Memcached for frequent DB queries.
34
+
35
+ ## 5. Agentic Implementation
36
+ When working with agents on scalability problems:
37
+ - Invoke the `system-scalability` skill.
38
+ - The agent will evaluate the system and generate a `SCALABILITY_ANALYSIS_TEMPLATE.md` to map out exactly which axis is best suited to the current bottleneck.
39
+
40
+ ---
41
+
42
+ ## Technical Performance Skills
43
+ - [Performant Node.js](../../skills/coding/performant-nodejs.skill.md)
44
+ - [Performant Laravel](../../skills/coding/performant-laravel.skill.md)
45
+ - [Performant Python](../../skills/coding/performant-python.skill.md)
46
+ - [Performant Go](../../skills/coding/performant-go.skill.md)
47
+ - [Performant AI](../../skills/coding/performant-ai.skill.md)
@@ -0,0 +1,506 @@
1
+ # Guide: Systems Architecture
2
+ <!-- Architecture frameworks, quality attributes, styles, documentation standards -->
3
+ <!-- Technology-agnostic. Principles apply across all platforms and languages. -->
4
+ <!-- Standards: ISO/IEC/IEEE 42010, arc42, 4+1 views, C4 model, SEI ATAM -->
5
+
6
+ ---
7
+
8
+ ## What is Architecture?
9
+
10
+ Architecture is the set of **structures** needed to reason about the system — the
11
+ components, their relationships, and the properties of both components and relationships.
12
+
13
+ ```
14
+ Good architecture:
15
+ - Makes the important decisions explicit and visible
16
+ - Makes the wrong thing HARD to do (bad pattern → visible violation)
17
+ - Enables independent evolution of parts without breaking the whole
18
+ - Satisfies the system's quality attribute requirements
19
+
20
+ Architecture is NOT:
21
+ - Technology selection (that's a design decision following architecture)
22
+ - The "big upfront design" — architecture should evolve with the system
23
+ - A single diagram — multiple views are needed to represent a system
24
+ - Just the "happy path" — architecture must address failure modes
25
+ ```
26
+
27
+ ---
28
+
29
+ ## Architecture Fundamentals
30
+
31
+ ### Quality Attributes Drive Architecture
32
+
33
+ ```
34
+ Every architecture decision is a tradeoff between quality attributes.
35
+ The quality attribute requirements (QAS) DETERMINE the architecture style and tactics.
36
+
37
+ Process:
38
+ 1. Identify quality attribute priorities (what matters most for this system)
39
+ 2. Define measurable QAS for top 3-5 attributes
40
+ 3. Select architecture style that supports those QAS
41
+ 4. Apply architectural tactics for specific QAS
42
+ 5. Validate architecture against QAS (ATAM review)
43
+
44
+ If you don't know the quality priorities → you cannot make good architecture decisions.
45
+ ```
46
+
47
+ ### ISO 25010 Quality Attributes
48
+
49
+ ```
50
+ Performance Efficiency
51
+ Time behavior: How fast (response time, throughput)
52
+ Resource utilization: How efficiently resources are used
53
+ Capacity: How much load can be sustained
54
+
55
+ Reliability
56
+ Availability: % of time system is operable
57
+ Fault tolerance: Operation despite component failures
58
+ Recoverability: Speed and completeness of recovery from failure
59
+
60
+ Security
61
+ Confidentiality: Data protected from unauthorized disclosure
62
+ Integrity: Data protected from unauthorized modification
63
+ Non-repudiation: Actions attributable to actors
64
+ Authenticity: Actors and data are genuine
65
+
66
+ Usability
67
+ Appropriateness: Supports task completion
68
+ Learnability: Users learn to use efficiently
69
+ Accessibility: Usable by people with disabilities
70
+
71
+ Maintainability
72
+ Modularity: Changes confined to minimal components
73
+ Reusability: Components usable in other contexts
74
+ Analyzability: Diagnosable efficiently
75
+ Modifiability: Modified without introducing defects
76
+ Testability: Test criteria established and executable
77
+
78
+ Portability
79
+ Adaptability: Works in different environments
80
+ Installability: Can be installed/uninstalled
81
+ Replaceability: Can replace other equivalent software
82
+ ```
83
+
84
+ ---
85
+
86
+ ## Architecture Styles
87
+
88
+ ### Layered Architecture
89
+
90
+ ```
91
+ Structure:
92
+ Layer N (Presentation / Interface)
93
+ ↓ depends on
94
+ Layer N-1 (Application / Use Cases)
95
+ ↓ depends on
96
+ Layer N-2 (Domain / Business Logic)
97
+ ↓ depends on
98
+ Layer N-3 (Infrastructure / Data)
99
+
100
+ Rules:
101
+ - Each layer depends only on the layer directly below it
102
+ - Inner layers have no knowledge of outer layers
103
+ - Cross-layer skipping is an architectural violation
104
+
105
+ Quality strengths: Maintainability, Testability, Modifiability
106
+ Quality weaknesses: Performance (pass-through layers), Scalability
107
+
108
+ Use when:
109
+ - General-purpose business application
110
+ - Small to medium team
111
+ - Maintainability is a dominant quality attribute
112
+ - Not extreme scalability or fault tolerance required
113
+ ```
114
+
115
+ ### Event-Driven Architecture
116
+
117
+ ```
118
+ Structure:
119
+ Components communicate by publishing and subscribing to events.
120
+ No direct coupling between producers and consumers.
121
+
122
+ Producer → [Event Bus] → Consumer(s)
123
+
124
+ Event Bus implementations (technology-agnostic terms):
125
+ Synchronous event: In-process observer pattern
126
+ Async message queue: Persistent queue (at-least-once delivery)
127
+ Event stream: Ordered, replayable log of events
128
+
129
+ Patterns within event-driven:
130
+ Event Notification: Notify that something happened (no payload needed — consumer queries)
131
+ Event-Carried State: Carry all relevant data in the event (consumer needs nothing else)
132
+ Event Sourcing: Events ARE the system of record (state derived from event replay)
133
+
134
+ Quality strengths: Decoupling, Scalability, Auditability, Extensibility
135
+ Quality weaknesses: Complexity, Eventual consistency, Debugging difficulty
136
+
137
+ Use when:
138
+ - High decoupling between components is required
139
+ - Multiple consumers react to the same business event
140
+ - Audit trail of all changes needed
141
+ - System must scale producers and consumers independently
142
+ ```
143
+
144
+ ### Microkernel (Plugin) Architecture
145
+
146
+ ```
147
+ Structure:
148
+ Core system (kernel): minimal, stable feature set
149
+ Plug-in modules: extend core without modifying it
150
+
151
+ [Plug-in A] ──→
152
+ [Plug-in B] ──→ [Core System] ←── [Plug-in Registry]
153
+ [Plug-in C] ──→
154
+
155
+ Quality strengths: Extensibility, Customizability, Isolation
156
+ Quality weaknesses: Plug-in API design complexity, Registry management
157
+
158
+ Use when:
159
+ - Product with many optional features or configurations
160
+ - Third-party extension is a business requirement
161
+ - Multi-tenant SaaS with per-tenant customization
162
+ ```
163
+
164
+ ### Service-Based Architecture
165
+
166
+ ```
167
+ Structure:
168
+ Coarse-grained services aligned to domain capabilities.
169
+ Shared infrastructure (database, auth, logging) but independent service logic.
170
+ Typically 4-12 services (between monolith and microservices complexity).
171
+
172
+ [User Service] [Order Service] [Payment Service]
173
+ ↓ ↓ ↓
174
+ [Shared Database / Shared Cache / Shared Message Bus]
175
+
176
+ Quality strengths: Domain alignment, Team independence, Deployability
177
+ Quality weaknesses: Shared infrastructure coupling, Distributed transaction complexity
178
+
179
+ Use when:
180
+ - Multiple distinct business domains need independence
181
+ - Teams own specific domains (team per service)
182
+ - Microservices overhead not yet justified
183
+ ```
184
+
185
+ ### Space-Based Architecture
186
+
187
+ ```
188
+ Structure:
189
+ Processing units: stateful components with in-memory data grids
190
+ No central database in the request path
191
+ Data virtualization layer synchronizes to persistence asynchronously
192
+
193
+ [Client] → [Processing Unit 1 + local grid]
194
+ [Processing Unit 2 + local grid] ← replicated grid
195
+ [Processing Unit N + local grid]
196
+ ↓ async
197
+ [Persistence Layer]
198
+
199
+ Quality strengths: Extreme scalability, Fault tolerance
200
+ Quality weaknesses: Data consistency complexity, High implementation cost
201
+
202
+ Use when:
203
+ - Extremely high and unpredictable load spikes
204
+ - Elastic scaling is a primary requirement
205
+ - Financial trading systems, ticketing systems
206
+ ```
207
+
208
+ ---
209
+
210
+ ## Architectural Tactics
211
+
212
+ Tactics are design moves to improve a specific quality attribute.
213
+
214
+ ### Performance Tactics
215
+
216
+ ```
217
+ Manage demand:
218
+ Manage event arrival: Limit incoming requests (rate limiting, throttling)
219
+ Manage sampling rate: Sample/skip non-critical work under load
220
+ Prioritize events: Process high-priority events first
221
+
222
+ Manage resources:
223
+ Increase resources: Scale vertically or horizontally
224
+ Introduce concurrency: Process requests in parallel (threads, async)
225
+ Reduce overhead: Minimize unnecessary operations in critical path
226
+ Bound execution: Time-bound all operations (timeouts everywhere)
227
+ Increase efficiency: Cache results; reduce recomputation; lazy loading
228
+
229
+ Arbitrate:
230
+ Scheduling policy: FIFO, round-robin, priority queue
231
+ ```
232
+
233
+ ### Reliability Tactics
234
+
235
+ ```
236
+ Detect faults:
237
+ Monitor: Heartbeat, ping/echo, health check endpoints
238
+ Exceptions: Exception-based detection with classification
239
+
240
+ Recover from faults:
241
+ Preparation: Active redundancy (hot standby), passive redundancy (warm standby)
242
+ Retry: Automatic retry with exponential backoff
243
+ Ignore: Ignore non-critical fault if processing can continue
244
+ Degraded mode: Reduce functionality but keep core running
245
+ Reconfigure: Remove failed component, redistribute load
246
+
247
+ Prevent faults:
248
+ Removal from service: Take component offline for maintenance without system failure
249
+ Transactions: Atomic operations to prevent partial failure
250
+ Circuit breaker: Open circuit on repeated failures; prevent cascade
251
+
252
+ Recovery objectives:
253
+ RTO (Recovery Time Objective): Maximum acceptable downtime after failure
254
+ RPO (Recovery Point Objective): Maximum acceptable data loss (in time)
255
+ ```
256
+
257
+ ### Security Tactics
258
+
259
+ ```
260
+ Detect attacks:
261
+ Detect intrusion: Monitor for known attack patterns
262
+ Detect service denial: Identify DoS/DDoS traffic patterns
263
+
264
+ Resist attacks:
265
+ Identify actors: Authentication (verify identity before granting access)
266
+ Authorize actors: Authorization (enforce permissions after identity established)
267
+ Limit exposure: Minimize attack surface (principle of least privilege)
268
+ Encrypt data: Confidentiality in transit and at rest
269
+ Separate entities: Isolate sensitive components (blast radius reduction)
270
+ Validate input: Reject malformed input at system boundaries
271
+
272
+ React to attacks:
273
+ Revoke access: Terminate sessions, invalidate tokens on detection
274
+ Limit access: Rate limiting, account lockout
275
+ Inform actors: Log and alert on detected attacks
276
+
277
+ Recovery:
278
+ Restore: Recover from known-good state
279
+ Audit: Forensic trail to understand what happened
280
+ ```
281
+
282
+ ### Maintainability Tactics
283
+
284
+ ```
285
+ Reduce coupling:
286
+ Encapsulate: Hide implementation behind stable interfaces
287
+ Use intermediary: Mediator, broker, or adapter between components
288
+ Restrict dependencies: Enforce import/dependency rules (layering)
289
+ Defer binding: Configuration, feature flags, plugin loading
290
+
291
+ Increase cohesion:
292
+ Separate concerns: Single responsibility per module/component
293
+ Abstract common services: Move shared behavior to a clearly defined service
294
+
295
+ Improve testability:
296
+ Control and observe: Inject dependencies (no hardcoded collaborators)
297
+ Sandbox: Isolate components for testing (test doubles, stubs)
298
+ ```
299
+
300
+ ---
301
+
302
+ ## Architecture Documentation Standards
303
+
304
+ ### The 4+1 Architectural Views
305
+
306
+ ```
307
+ Logical View (structural — what the system IS):
308
+ Audience: developers, architects
309
+ Shows: Major abstractions, components, their responsibilities and relationships
310
+ Diagrams: Component diagram, class/entity diagram
311
+
312
+ Process View (behavioral — what the system DOES):
313
+ Audience: developers, performance engineers
314
+ Shows: How components interact at runtime for key use cases
315
+ Concurrency model, processes, threads
316
+ Diagrams: Sequence diagram, activity diagram, state machine diagram
317
+
318
+ Development View (code organization — how the system is BUILT):
319
+ Audience: developers, build engineers
320
+ Shows: Module/package organization, build dependencies, code ownership
321
+ Diagrams: Package diagram, module dependency diagram
322
+
323
+ Deployment View (infrastructure — where the system RUNS):
324
+ Audience: operators, DevOps, architects
325
+ Shows: Mapping of components to physical/virtual infrastructure
326
+ Network topology, hardware, cloud resources
327
+ Diagrams: Deployment diagram, infrastructure diagram
328
+
329
+ Scenarios (+1 view — use cases as validation):
330
+ Audience: all
331
+ Shows: How the 4 views combine for 3-5 key scenarios
332
+ Purpose: Validates that the architecture satisfies the requirements
333
+ Format: Walk-through of a use case across all 4 views
334
+ ```
335
+
336
+ ### arc42 Architecture Documentation Template
337
+
338
+ ```
339
+ arc42 is a standard template for architecture documentation:
340
+
341
+ Section 1: Introduction and Goals (quality goals, stakeholders)
342
+ Section 2: Constraints (technical, organizational, regulatory)
343
+ Section 3: System Scope and Context (Context + Container level)
344
+ Section 4: Solution Strategy (key decisions and approach)
345
+ Section 5: Building Block View (component decomposition)
346
+ Section 6: Runtime View (sequence/activity diagrams per scenario)
347
+ Section 7: Deployment View (infrastructure and deployment)
348
+ Section 8: Cross-Cutting Concepts (patterns applied system-wide)
349
+ Section 9: Architecture Decisions (ADR list)
350
+ Section 10: Quality Requirements (QAS)
351
+ Section 11: Risks and Technical Debt
352
+ Section 12: Glossary
353
+
354
+ Use: templates/architecture/ARCHITECTURE_VIEWS_TEMPLATE.md (follows this structure)
355
+ ```
356
+
357
+ ### Architecture Decision Records (ADR)
358
+
359
+ ```
360
+ Every significant architectural decision must be recorded in an ADR.
361
+ ADRs are permanent — even when superseded, they document WHY the change was made.
362
+
363
+ When to write an ADR:
364
+ - Choosing between 2+ viable architectural approaches
365
+ - Technology choice with significant implications
366
+ - Trade-off decision affecting multiple quality attributes
367
+ - Decision that will be hard to reverse
368
+ - Decision that future engineers will question
369
+
370
+ ADR content:
371
+ Title: Short phrase naming the decision
372
+ Context: Problem and forces at play
373
+ Decision: What was decided
374
+ Status: Proposed / Accepted / Deprecated / Superseded
375
+ Rationale: Why this option was chosen (cite quality attributes, constraints)
376
+ Options: Alternatives considered (with pros/cons)
377
+ Consequences: Positive and negative results of the decision
378
+
379
+ Use: adr-writer.skill and templates/architecture/ADR_TEMPLATE.md
380
+ ```
381
+
382
+ ---
383
+
384
+ ## Architecture Review (ATAM-Lite)
385
+
386
+ ```
387
+ Architecture Tradeoff Analysis Method (ATAM) — adapted for single-team use:
388
+
389
+ 1. Understand the architecture:
390
+ - What style was chosen and why?
391
+ - What are the major components?
392
+ - How do they interact?
393
+
394
+ 2. Enumerate quality attribute scenarios (QAS):
395
+ - Collect QAS from requirements and stakeholders
396
+ - Prioritize top 5-10
397
+
398
+ 3. Analyze architectural approaches:
399
+ - For each QAS: does the architecture satisfy it?
400
+ - Identify sensitivity points (decisions with high leverage)
401
+ - Identify tradeoff points (decisions affecting competing QAS)
402
+
403
+ 4. Identify risks and non-risks:
404
+ - Risk: a decision that may lead to a QAS violation
405
+ - Non-risk: a well-reasoned decision
406
+
407
+ 5. Create fitness functions:
408
+ - Automated checks that verify architecture health over time
409
+ - Add to CI pipeline
410
+
411
+ Use: arch-review.skill and templates/architecture/ARCHITECTURE_REVIEW_TEMPLATE.md
412
+ ```
413
+
414
+ ---
415
+
416
+ ## Common Architecture Anti-Patterns
417
+
418
+ ```
419
+ Big Ball of Mud:
420
+ No discernible structure. Everything depends on everything.
421
+ Fix: Define module boundaries; enforce with dependency analysis tools.
422
+
423
+ God Object / God Module:
424
+ One component with too many responsibilities.
425
+ Signal: > 30% of all code in one file/module, or imported by nearly everything.
426
+ Fix: Split by Single Responsibility Principle — one reason to change.
427
+
428
+ Lava Flow:
429
+ Dead code, unused variables, obsolete designs that cannot be removed because
430
+ no one understands what they do or is afraid to touch them.
431
+ Fix: Characterization tests → understand behavior → refactor safely.
432
+
433
+ Inner Platform Effect:
434
+ Building a framework within the system that reimplements existing platform capabilities.
435
+ Fix: Use the platform. Only abstract what you genuinely need to abstract.
436
+
437
+ Accidental Complexity:
438
+ Complexity introduced by the implementation (incidental) rather than inherent
439
+ in the problem (essential).
440
+ Fix: Continuously ask "is this complexity necessary to solve the problem?"
441
+
442
+ Distributed Monolith:
443
+ Multiple services that are so tightly coupled they must be deployed together.
444
+ Worst of both worlds: complexity of distributed systems + coupling of monolith.
445
+ Fix: Establish true independence (separate data stores, independent deployments).
446
+
447
+ Chatty Services:
448
+ Services making many fine-grained synchronous calls to each other.
449
+ Fix: Coarser-grained interfaces; combine related calls; async for non-critical paths.
450
+
451
+ Shared Database Anti-Pattern:
452
+ Multiple services sharing tables in the same database.
453
+ Fix: Each service owns its data; cross-service access via API.
454
+ ```
455
+
456
+ ---
457
+
458
+ ## Fitness Functions — Continuous Architecture Verification
459
+
460
+ ```
461
+ A fitness function is a test that verifies an architectural property is maintained.
462
+ Run in CI. Fail the build if the architectural property is violated.
463
+
464
+ Structural fitness functions:
465
+ "No module in [layer A] shall import from [layer B]"
466
+ Tool: dependency-cruiser, deptrac, ArchUnit
467
+ "No circular dependencies"
468
+ Tool: madge --circular
469
+ "No class/module with cyclomatic complexity > 10"
470
+ Tool: SonarQube, complexity-report
471
+
472
+ Behavioral fitness functions:
473
+ "All public API endpoints respond within [N]ms at [load]"
474
+ Tool: load test in CI (k6, Gatling)
475
+ "Test coverage never falls below [N]%"
476
+ Tool: coverage reporter in CI
477
+
478
+ Security fitness functions:
479
+ "No high/critical dependency CVEs"
480
+ Tool: npm audit, Snyk in CI
481
+ "No secrets in codebase"
482
+ Tool: gitleaks pre-commit hook
483
+
484
+ Define fitness functions for every identified architecture RISK.
485
+ ```
486
+
487
+ ---
488
+
489
+ ## Checklist: Is the Architecture Ready for Implementation?
490
+
491
+ ```
492
+ □ Quality attributes prioritized (top 5 with measurable QAS)
493
+ □ Architecture style selected with documented rationale (ADR)
494
+ □ System context established (C4 Level 1 — actors and external systems)
495
+ □ Container decomposition complete (C4 Level 2)
496
+ □ Component view for complex containers (C4 Level 3)
497
+ □ All component interfaces documented
498
+ □ Key scenarios as sequence diagrams (at least 3)
499
+ □ Deployment view documented
500
+ □ Security architecture documented
501
+ □ At least one ADR per major decision
502
+ □ Architecture reviewed against QAS (arch-review.skill)
503
+ □ Risks identified and mitigation strategies defined
504
+ □ Fitness functions defined for architecture risks
505
+ □ Human approval obtained (S02 gate)
506
+ ```
@@ -0,0 +1,23 @@
1
+ # Semantic Web & Meta-Knowledge Guide
2
+
3
+ ## 1. Introduction
4
+ The Semantic Web (Web 3.0 W3C standards, not to be confused with crypto-Web3) provides a common framework that allows data to be shared and reused across application, enterprise, and community boundaries. It enables the creation of Enterprise Knowledge Graphs (EKGs) that machines and AI agents can query and reason over.
5
+
6
+ ## 2. Core Technologies
7
+ Rather than storing data in isolated tables (Relational DBs) or documents (NoSQL), Semantic Web technologies store data as a graph of facts.
8
+
9
+ - **RDF (Resource Description Framework)**: The base data model. Data is stored in "Triples" defining a Subject, Predicate, and Object (e.g., `Employee_123` -> `worksFor` -> `Engineering`).
10
+ - **OWL (Web Ontology Language)**: The schema layer. It defines classes, properties, and relationships. It allows for logical deduction (e.g., if X is a Manager of Y, and Y works in Z, then X represents Z).
11
+ - **SPARQL**: The query language for RDF graphs (similar to SQL for relational data).
12
+
13
+ ## 3. Why Use It?
14
+ 1. **Data Silo Elimination**: Merging two relational databases requires complex ETL schemas. Merging two RDF graphs simply requires joining the identical URIs.
15
+ 2. **AI Interoperability**: AI Agents (via MCP or A2A) require context. A semantic knowledge graph provides perfectly clean, relationship-mapped context for LLMs, eliminating hallucination in RAG deployments (GraphRAG).
16
+ 3. **Inference**: Reasoners can infer new facts without them being explicitly stated in the database.
17
+
18
+ ## 4. Ontological Design Principles
19
+ - **Reusability**: Never invent a new property if an existing standard exists. Use `schema.org` for common entities (Person, Organization), `FOAF` for social structures, and `Dublin Core` for document metadata.
20
+ - **URIs as Identifiers**: Every entity and property is a Unique Resource Identifier (URI), ensuring global uniqueness.
21
+
22
+ ## 5. Agentic Implementation
23
+ Invoke the `semantic-web` skill when designing complex AI knowledge retrieval mechanisms or when unifying large enterprise datasets. Unstructured data (text/PDFs) is first parsed by an agent, transformed into RDF triples based on the `ONTOLOGY_TEMPLATE.md`, and stored in a Triplestore/Graph Database (like Neo4j or Amazon Neptune).