@wazir-dev/cli 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 (629) hide show
  1. package/AGENTS.md +111 -0
  2. package/CHANGELOG.md +14 -0
  3. package/CONTRIBUTING.md +101 -0
  4. package/LICENSE +21 -0
  5. package/README.md +314 -0
  6. package/assets/composition-engine.mmd +34 -0
  7. package/assets/demo-script.sh +17 -0
  8. package/assets/logo-dark.svg +14 -0
  9. package/assets/logo.svg +14 -0
  10. package/assets/pipeline.mmd +39 -0
  11. package/assets/record-demo.sh +51 -0
  12. package/docs/README.md +51 -0
  13. package/docs/adapters/context-mode.md +60 -0
  14. package/docs/concepts/architecture.md +87 -0
  15. package/docs/concepts/artifact-model.md +60 -0
  16. package/docs/concepts/composition-engine.md +36 -0
  17. package/docs/concepts/indexing-and-recall.md +160 -0
  18. package/docs/concepts/observability.md +41 -0
  19. package/docs/concepts/roles-and-workflows.md +59 -0
  20. package/docs/concepts/terminology-policy.md +27 -0
  21. package/docs/getting-started/01-installation.md +78 -0
  22. package/docs/getting-started/02-first-run.md +102 -0
  23. package/docs/getting-started/03-adding-to-project.md +15 -0
  24. package/docs/getting-started/04-host-setup.md +15 -0
  25. package/docs/guides/ci-integration.md +15 -0
  26. package/docs/guides/creating-skills.md +15 -0
  27. package/docs/guides/expertise-module-authoring.md +15 -0
  28. package/docs/guides/hook-development.md +15 -0
  29. package/docs/guides/memory-and-learnings.md +34 -0
  30. package/docs/guides/multi-host-export.md +15 -0
  31. package/docs/guides/troubleshooting.md +101 -0
  32. package/docs/guides/writing-custom-roles.md +15 -0
  33. package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
  34. package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
  35. package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
  36. package/docs/readmes/INDEX.md +99 -0
  37. package/docs/readmes/features/expertise/README.md +171 -0
  38. package/docs/readmes/features/exports/README.md +222 -0
  39. package/docs/readmes/features/hooks/README.md +103 -0
  40. package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
  41. package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
  42. package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
  43. package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
  44. package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
  45. package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
  46. package/docs/readmes/features/hooks/session-start.md +119 -0
  47. package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
  48. package/docs/readmes/features/roles/README.md +157 -0
  49. package/docs/readmes/features/roles/clarifier.md +152 -0
  50. package/docs/readmes/features/roles/content-author.md +190 -0
  51. package/docs/readmes/features/roles/designer.md +193 -0
  52. package/docs/readmes/features/roles/executor.md +184 -0
  53. package/docs/readmes/features/roles/learner.md +210 -0
  54. package/docs/readmes/features/roles/planner.md +182 -0
  55. package/docs/readmes/features/roles/researcher.md +164 -0
  56. package/docs/readmes/features/roles/reviewer.md +184 -0
  57. package/docs/readmes/features/roles/specifier.md +162 -0
  58. package/docs/readmes/features/roles/verifier.md +215 -0
  59. package/docs/readmes/features/schemas/README.md +178 -0
  60. package/docs/readmes/features/skills/README.md +63 -0
  61. package/docs/readmes/features/skills/brainstorming.md +96 -0
  62. package/docs/readmes/features/skills/debugging.md +148 -0
  63. package/docs/readmes/features/skills/design.md +120 -0
  64. package/docs/readmes/features/skills/prepare-next.md +109 -0
  65. package/docs/readmes/features/skills/run-audit.md +159 -0
  66. package/docs/readmes/features/skills/scan-project.md +109 -0
  67. package/docs/readmes/features/skills/self-audit.md +176 -0
  68. package/docs/readmes/features/skills/tdd.md +137 -0
  69. package/docs/readmes/features/skills/using-skills.md +92 -0
  70. package/docs/readmes/features/skills/verification.md +120 -0
  71. package/docs/readmes/features/skills/writing-plans.md +104 -0
  72. package/docs/readmes/features/tooling/README.md +320 -0
  73. package/docs/readmes/features/workflows/README.md +186 -0
  74. package/docs/readmes/features/workflows/author.md +181 -0
  75. package/docs/readmes/features/workflows/clarify.md +154 -0
  76. package/docs/readmes/features/workflows/design-review.md +171 -0
  77. package/docs/readmes/features/workflows/design.md +169 -0
  78. package/docs/readmes/features/workflows/discover.md +162 -0
  79. package/docs/readmes/features/workflows/execute.md +173 -0
  80. package/docs/readmes/features/workflows/learn.md +167 -0
  81. package/docs/readmes/features/workflows/plan-review.md +165 -0
  82. package/docs/readmes/features/workflows/plan.md +170 -0
  83. package/docs/readmes/features/workflows/prepare-next.md +167 -0
  84. package/docs/readmes/features/workflows/review.md +169 -0
  85. package/docs/readmes/features/workflows/run-audit.md +191 -0
  86. package/docs/readmes/features/workflows/spec-challenge.md +159 -0
  87. package/docs/readmes/features/workflows/specify.md +160 -0
  88. package/docs/readmes/features/workflows/verify.md +177 -0
  89. package/docs/readmes/packages/README.md +50 -0
  90. package/docs/readmes/packages/ajv.md +117 -0
  91. package/docs/readmes/packages/context-mode.md +118 -0
  92. package/docs/readmes/packages/gray-matter.md +116 -0
  93. package/docs/readmes/packages/node-test.md +137 -0
  94. package/docs/readmes/packages/yaml.md +112 -0
  95. package/docs/reference/configuration-reference.md +159 -0
  96. package/docs/reference/expertise-index.md +52 -0
  97. package/docs/reference/git-flow.md +43 -0
  98. package/docs/reference/hooks.md +87 -0
  99. package/docs/reference/host-exports.md +50 -0
  100. package/docs/reference/launch-checklist.md +172 -0
  101. package/docs/reference/marketplace-listings.md +76 -0
  102. package/docs/reference/release-process.md +34 -0
  103. package/docs/reference/roles-reference.md +77 -0
  104. package/docs/reference/skills.md +33 -0
  105. package/docs/reference/templates.md +29 -0
  106. package/docs/reference/tooling-cli.md +94 -0
  107. package/docs/truth-claims.yaml +222 -0
  108. package/expertise/PROGRESS.md +63 -0
  109. package/expertise/README.md +18 -0
  110. package/expertise/antipatterns/PROGRESS.md +56 -0
  111. package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
  112. package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
  113. package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
  114. package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
  115. package/expertise/antipatterns/backend/index.md +24 -0
  116. package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
  117. package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
  118. package/expertise/antipatterns/code/async-antipatterns.md +622 -0
  119. package/expertise/antipatterns/code/code-smells.md +1186 -0
  120. package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
  121. package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
  122. package/expertise/antipatterns/code/index.md +27 -0
  123. package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
  124. package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
  125. package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
  126. package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
  127. package/expertise/antipatterns/design/dark-patterns.md +1121 -0
  128. package/expertise/antipatterns/design/index.md +22 -0
  129. package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
  130. package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
  131. package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
  132. package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
  133. package/expertise/antipatterns/frontend/index.md +23 -0
  134. package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
  135. package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
  136. package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
  137. package/expertise/antipatterns/index.md +31 -0
  138. package/expertise/antipatterns/performance/index.md +20 -0
  139. package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
  140. package/expertise/antipatterns/performance/premature-optimization.md +623 -0
  141. package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
  142. package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
  143. package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
  144. package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
  145. package/expertise/antipatterns/process/index.md +23 -0
  146. package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
  147. package/expertise/antipatterns/security/index.md +20 -0
  148. package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
  149. package/expertise/antipatterns/security/security-theater.md +843 -0
  150. package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
  151. package/expertise/architecture/PROGRESS.md +70 -0
  152. package/expertise/architecture/data/caching-architecture.md +671 -0
  153. package/expertise/architecture/data/data-consistency.md +574 -0
  154. package/expertise/architecture/data/data-modeling.md +536 -0
  155. package/expertise/architecture/data/event-streams-and-queues.md +634 -0
  156. package/expertise/architecture/data/index.md +25 -0
  157. package/expertise/architecture/data/search-architecture.md +663 -0
  158. package/expertise/architecture/data/sql-vs-nosql.md +708 -0
  159. package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
  160. package/expertise/architecture/decisions/build-vs-buy.md +616 -0
  161. package/expertise/architecture/decisions/index.md +23 -0
  162. package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
  163. package/expertise/architecture/decisions/technology-selection.md +616 -0
  164. package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
  165. package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
  166. package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
  167. package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
  168. package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
  169. package/expertise/architecture/distributed/index.md +25 -0
  170. package/expertise/architecture/distributed/saga-pattern.md +797 -0
  171. package/expertise/architecture/foundations/architectural-thinking.md +460 -0
  172. package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
  173. package/expertise/architecture/foundations/design-principles-solid.md +649 -0
  174. package/expertise/architecture/foundations/domain-driven-design.md +719 -0
  175. package/expertise/architecture/foundations/index.md +25 -0
  176. package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
  177. package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
  178. package/expertise/architecture/index.md +34 -0
  179. package/expertise/architecture/integration/api-design-graphql.md +638 -0
  180. package/expertise/architecture/integration/api-design-grpc.md +804 -0
  181. package/expertise/architecture/integration/api-design-rest.md +892 -0
  182. package/expertise/architecture/integration/index.md +25 -0
  183. package/expertise/architecture/integration/third-party-integration.md +795 -0
  184. package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
  185. package/expertise/architecture/integration/websockets-realtime.md +791 -0
  186. package/expertise/architecture/mobile-architecture/index.md +22 -0
  187. package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
  188. package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
  189. package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
  190. package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
  191. package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
  192. package/expertise/architecture/patterns/event-driven.md +797 -0
  193. package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
  194. package/expertise/architecture/patterns/index.md +27 -0
  195. package/expertise/architecture/patterns/layered-architecture.md +736 -0
  196. package/expertise/architecture/patterns/microservices.md +753 -0
  197. package/expertise/architecture/patterns/modular-monolith.md +692 -0
  198. package/expertise/architecture/patterns/monolith.md +626 -0
  199. package/expertise/architecture/patterns/plugin-architecture.md +735 -0
  200. package/expertise/architecture/patterns/serverless.md +780 -0
  201. package/expertise/architecture/scaling/database-scaling.md +615 -0
  202. package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
  203. package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
  204. package/expertise/architecture/scaling/index.md +24 -0
  205. package/expertise/architecture/scaling/multi-tenancy.md +800 -0
  206. package/expertise/architecture/scaling/stateless-design.md +787 -0
  207. package/expertise/backend/embedded-firmware.md +625 -0
  208. package/expertise/backend/go.md +853 -0
  209. package/expertise/backend/index.md +24 -0
  210. package/expertise/backend/java-spring.md +448 -0
  211. package/expertise/backend/node-typescript.md +625 -0
  212. package/expertise/backend/python-fastapi.md +724 -0
  213. package/expertise/backend/rust.md +458 -0
  214. package/expertise/backend/solidity.md +711 -0
  215. package/expertise/composition-map.yaml +443 -0
  216. package/expertise/content/foundations/content-modeling.md +395 -0
  217. package/expertise/content/foundations/editorial-standards.md +449 -0
  218. package/expertise/content/foundations/index.md +24 -0
  219. package/expertise/content/foundations/microcopy.md +455 -0
  220. package/expertise/content/foundations/terminology-governance.md +509 -0
  221. package/expertise/content/index.md +34 -0
  222. package/expertise/content/patterns/accessibility-copy.md +518 -0
  223. package/expertise/content/patterns/index.md +24 -0
  224. package/expertise/content/patterns/notification-content.md +433 -0
  225. package/expertise/content/patterns/sample-content.md +486 -0
  226. package/expertise/content/patterns/state-copy.md +439 -0
  227. package/expertise/design/PROGRESS.md +58 -0
  228. package/expertise/design/disciplines/dark-mode-theming.md +577 -0
  229. package/expertise/design/disciplines/design-systems.md +595 -0
  230. package/expertise/design/disciplines/index.md +25 -0
  231. package/expertise/design/disciplines/information-architecture.md +800 -0
  232. package/expertise/design/disciplines/interaction-design.md +788 -0
  233. package/expertise/design/disciplines/responsive-design.md +552 -0
  234. package/expertise/design/disciplines/usability-testing.md +516 -0
  235. package/expertise/design/disciplines/user-research.md +792 -0
  236. package/expertise/design/foundations/accessibility-design.md +796 -0
  237. package/expertise/design/foundations/color-theory.md +797 -0
  238. package/expertise/design/foundations/iconography.md +795 -0
  239. package/expertise/design/foundations/index.md +26 -0
  240. package/expertise/design/foundations/motion-and-animation.md +653 -0
  241. package/expertise/design/foundations/rtl-design.md +585 -0
  242. package/expertise/design/foundations/spacing-and-layout.md +607 -0
  243. package/expertise/design/foundations/typography.md +800 -0
  244. package/expertise/design/foundations/visual-hierarchy.md +761 -0
  245. package/expertise/design/index.md +32 -0
  246. package/expertise/design/patterns/authentication-flows.md +474 -0
  247. package/expertise/design/patterns/content-consumption.md +789 -0
  248. package/expertise/design/patterns/data-display.md +618 -0
  249. package/expertise/design/patterns/e-commerce.md +1494 -0
  250. package/expertise/design/patterns/feedback-and-states.md +642 -0
  251. package/expertise/design/patterns/forms-and-input.md +819 -0
  252. package/expertise/design/patterns/gamification.md +801 -0
  253. package/expertise/design/patterns/index.md +31 -0
  254. package/expertise/design/patterns/microinteractions.md +449 -0
  255. package/expertise/design/patterns/navigation.md +800 -0
  256. package/expertise/design/patterns/notifications.md +705 -0
  257. package/expertise/design/patterns/onboarding.md +700 -0
  258. package/expertise/design/patterns/search-and-filter.md +601 -0
  259. package/expertise/design/patterns/settings-and-preferences.md +768 -0
  260. package/expertise/design/patterns/social-and-community.md +748 -0
  261. package/expertise/design/platforms/desktop-native.md +612 -0
  262. package/expertise/design/platforms/index.md +25 -0
  263. package/expertise/design/platforms/mobile-android.md +825 -0
  264. package/expertise/design/platforms/mobile-cross-platform.md +983 -0
  265. package/expertise/design/platforms/mobile-ios.md +699 -0
  266. package/expertise/design/platforms/tablet.md +794 -0
  267. package/expertise/design/platforms/web-dashboard.md +790 -0
  268. package/expertise/design/platforms/web-responsive.md +550 -0
  269. package/expertise/design/psychology/behavioral-nudges.md +449 -0
  270. package/expertise/design/psychology/cognitive-load.md +1191 -0
  271. package/expertise/design/psychology/error-psychology.md +778 -0
  272. package/expertise/design/psychology/index.md +22 -0
  273. package/expertise/design/psychology/persuasive-design.md +736 -0
  274. package/expertise/design/psychology/user-mental-models.md +623 -0
  275. package/expertise/design/tooling/open-pencil.md +266 -0
  276. package/expertise/frontend/angular.md +1073 -0
  277. package/expertise/frontend/desktop-electron.md +546 -0
  278. package/expertise/frontend/flutter.md +782 -0
  279. package/expertise/frontend/index.md +27 -0
  280. package/expertise/frontend/native-android.md +409 -0
  281. package/expertise/frontend/native-ios.md +490 -0
  282. package/expertise/frontend/react-native.md +1160 -0
  283. package/expertise/frontend/react.md +808 -0
  284. package/expertise/frontend/vue.md +1089 -0
  285. package/expertise/humanize/domain-rules-code.md +79 -0
  286. package/expertise/humanize/domain-rules-content.md +67 -0
  287. package/expertise/humanize/domain-rules-technical-docs.md +56 -0
  288. package/expertise/humanize/index.md +35 -0
  289. package/expertise/humanize/self-audit-checklist.md +87 -0
  290. package/expertise/humanize/sentence-patterns.md +218 -0
  291. package/expertise/humanize/vocabulary-blacklist.md +105 -0
  292. package/expertise/i18n/PROGRESS.md +65 -0
  293. package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
  294. package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
  295. package/expertise/i18n/advanced/complex-scripts.md +30 -0
  296. package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
  297. package/expertise/i18n/advanced/testing-i18n.md +28 -0
  298. package/expertise/i18n/content/content-adaptation.md +23 -0
  299. package/expertise/i18n/content/locale-specific-formatting.md +23 -0
  300. package/expertise/i18n/content/machine-translation-integration.md +28 -0
  301. package/expertise/i18n/content/translation-management.md +29 -0
  302. package/expertise/i18n/foundations/date-time-calendars.md +67 -0
  303. package/expertise/i18n/foundations/i18n-architecture.md +272 -0
  304. package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
  305. package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
  306. package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
  307. package/expertise/i18n/foundations/string-externalization.md +236 -0
  308. package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
  309. package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
  310. package/expertise/i18n/index.md +38 -0
  311. package/expertise/i18n/platform/backend-i18n.md +31 -0
  312. package/expertise/i18n/platform/flutter-i18n.md +148 -0
  313. package/expertise/i18n/platform/native-android-i18n.md +36 -0
  314. package/expertise/i18n/platform/native-ios-i18n.md +36 -0
  315. package/expertise/i18n/platform/react-i18n.md +103 -0
  316. package/expertise/i18n/platform/web-css-i18n.md +81 -0
  317. package/expertise/i18n/rtl/arabic-specific.md +175 -0
  318. package/expertise/i18n/rtl/hebrew-specific.md +149 -0
  319. package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
  320. package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
  321. package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
  322. package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
  323. package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
  324. package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
  325. package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
  326. package/expertise/i18n/rtl/rtl-typography.md +160 -0
  327. package/expertise/index.md +113 -0
  328. package/expertise/index.yaml +216 -0
  329. package/expertise/infrastructure/cloud-aws.md +597 -0
  330. package/expertise/infrastructure/cloud-gcp.md +599 -0
  331. package/expertise/infrastructure/cybersecurity.md +816 -0
  332. package/expertise/infrastructure/database-mongodb.md +447 -0
  333. package/expertise/infrastructure/database-postgres.md +400 -0
  334. package/expertise/infrastructure/devops-cicd.md +787 -0
  335. package/expertise/infrastructure/index.md +27 -0
  336. package/expertise/performance/PROGRESS.md +50 -0
  337. package/expertise/performance/backend/api-latency.md +1204 -0
  338. package/expertise/performance/backend/background-jobs.md +506 -0
  339. package/expertise/performance/backend/connection-pooling.md +1209 -0
  340. package/expertise/performance/backend/database-query-optimization.md +515 -0
  341. package/expertise/performance/backend/index.md +23 -0
  342. package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
  343. package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
  344. package/expertise/performance/foundations/caching-strategies.md +489 -0
  345. package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
  346. package/expertise/performance/foundations/index.md +24 -0
  347. package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
  348. package/expertise/performance/foundations/memory-management.md +964 -0
  349. package/expertise/performance/foundations/performance-budgets.md +1314 -0
  350. package/expertise/performance/index.md +31 -0
  351. package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
  352. package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
  353. package/expertise/performance/infrastructure/index.md +22 -0
  354. package/expertise/performance/infrastructure/load-balancing.md +1081 -0
  355. package/expertise/performance/infrastructure/observability.md +1079 -0
  356. package/expertise/performance/mobile/index.md +23 -0
  357. package/expertise/performance/mobile/mobile-animations.md +544 -0
  358. package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
  359. package/expertise/performance/mobile/mobile-network.md +452 -0
  360. package/expertise/performance/mobile/mobile-rendering.md +599 -0
  361. package/expertise/performance/mobile/mobile-startup-time.md +505 -0
  362. package/expertise/performance/platform-specific/flutter-performance.md +647 -0
  363. package/expertise/performance/platform-specific/index.md +22 -0
  364. package/expertise/performance/platform-specific/node-performance.md +1307 -0
  365. package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
  366. package/expertise/performance/platform-specific/react-performance.md +1403 -0
  367. package/expertise/performance/web/bundle-optimization.md +1239 -0
  368. package/expertise/performance/web/image-and-media.md +636 -0
  369. package/expertise/performance/web/index.md +24 -0
  370. package/expertise/performance/web/network-optimization.md +1133 -0
  371. package/expertise/performance/web/rendering-performance.md +1098 -0
  372. package/expertise/performance/web/ssr-and-hydration.md +918 -0
  373. package/expertise/performance/web/web-vitals.md +1374 -0
  374. package/expertise/quality/accessibility.md +985 -0
  375. package/expertise/quality/evidence-based-verification.md +499 -0
  376. package/expertise/quality/index.md +24 -0
  377. package/expertise/quality/ml-model-audit.md +614 -0
  378. package/expertise/quality/performance.md +600 -0
  379. package/expertise/quality/testing-api.md +891 -0
  380. package/expertise/quality/testing-mobile.md +496 -0
  381. package/expertise/quality/testing-web.md +849 -0
  382. package/expertise/security/PROGRESS.md +54 -0
  383. package/expertise/security/agentic-identity.md +540 -0
  384. package/expertise/security/compliance-frameworks.md +601 -0
  385. package/expertise/security/data/data-encryption.md +364 -0
  386. package/expertise/security/data/data-privacy-gdpr.md +692 -0
  387. package/expertise/security/data/database-security.md +1171 -0
  388. package/expertise/security/data/index.md +22 -0
  389. package/expertise/security/data/pii-handling.md +531 -0
  390. package/expertise/security/foundations/authentication.md +1041 -0
  391. package/expertise/security/foundations/authorization.md +603 -0
  392. package/expertise/security/foundations/cryptography.md +1001 -0
  393. package/expertise/security/foundations/index.md +25 -0
  394. package/expertise/security/foundations/owasp-top-10.md +1354 -0
  395. package/expertise/security/foundations/secrets-management.md +1217 -0
  396. package/expertise/security/foundations/secure-sdlc.md +700 -0
  397. package/expertise/security/foundations/supply-chain-security.md +698 -0
  398. package/expertise/security/index.md +31 -0
  399. package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
  400. package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
  401. package/expertise/security/infrastructure/container-security.md +721 -0
  402. package/expertise/security/infrastructure/incident-response.md +1295 -0
  403. package/expertise/security/infrastructure/index.md +24 -0
  404. package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
  405. package/expertise/security/infrastructure/network-security.md +1337 -0
  406. package/expertise/security/mobile/index.md +23 -0
  407. package/expertise/security/mobile/mobile-android-security.md +1218 -0
  408. package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
  409. package/expertise/security/mobile/mobile-data-storage.md +1265 -0
  410. package/expertise/security/mobile/mobile-ios-security.md +1401 -0
  411. package/expertise/security/mobile/mobile-network-security.md +1520 -0
  412. package/expertise/security/smart-contract-security.md +594 -0
  413. package/expertise/security/testing/index.md +22 -0
  414. package/expertise/security/testing/penetration-testing.md +1258 -0
  415. package/expertise/security/testing/security-code-review.md +1765 -0
  416. package/expertise/security/testing/threat-modeling.md +1074 -0
  417. package/expertise/security/testing/vulnerability-scanning.md +1062 -0
  418. package/expertise/security/web/api-security.md +586 -0
  419. package/expertise/security/web/cors-and-headers.md +433 -0
  420. package/expertise/security/web/csrf.md +562 -0
  421. package/expertise/security/web/file-upload.md +1477 -0
  422. package/expertise/security/web/index.md +25 -0
  423. package/expertise/security/web/injection.md +1375 -0
  424. package/expertise/security/web/session-management.md +1101 -0
  425. package/expertise/security/web/xss.md +1158 -0
  426. package/exports/README.md +17 -0
  427. package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
  428. package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
  429. package/exports/hosts/claude/.claude/agents/designer.md +55 -0
  430. package/exports/hosts/claude/.claude/agents/executor.md +55 -0
  431. package/exports/hosts/claude/.claude/agents/learner.md +51 -0
  432. package/exports/hosts/claude/.claude/agents/planner.md +53 -0
  433. package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
  434. package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
  435. package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
  436. package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
  437. package/exports/hosts/claude/.claude/commands/author.md +42 -0
  438. package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
  439. package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
  440. package/exports/hosts/claude/.claude/commands/design.md +44 -0
  441. package/exports/hosts/claude/.claude/commands/discover.md +37 -0
  442. package/exports/hosts/claude/.claude/commands/execute.md +48 -0
  443. package/exports/hosts/claude/.claude/commands/learn.md +38 -0
  444. package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
  445. package/exports/hosts/claude/.claude/commands/plan.md +39 -0
  446. package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
  447. package/exports/hosts/claude/.claude/commands/review.md +40 -0
  448. package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
  449. package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
  450. package/exports/hosts/claude/.claude/commands/specify.md +38 -0
  451. package/exports/hosts/claude/.claude/commands/verify.md +37 -0
  452. package/exports/hosts/claude/.claude/settings.json +34 -0
  453. package/exports/hosts/claude/CLAUDE.md +19 -0
  454. package/exports/hosts/claude/export.manifest.json +38 -0
  455. package/exports/hosts/claude/host-package.json +67 -0
  456. package/exports/hosts/codex/AGENTS.md +19 -0
  457. package/exports/hosts/codex/export.manifest.json +38 -0
  458. package/exports/hosts/codex/host-package.json +41 -0
  459. package/exports/hosts/cursor/.cursor/hooks.json +16 -0
  460. package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
  461. package/exports/hosts/cursor/export.manifest.json +38 -0
  462. package/exports/hosts/cursor/host-package.json +42 -0
  463. package/exports/hosts/gemini/GEMINI.md +19 -0
  464. package/exports/hosts/gemini/export.manifest.json +38 -0
  465. package/exports/hosts/gemini/host-package.json +41 -0
  466. package/hooks/README.md +18 -0
  467. package/hooks/definitions/loop_cap_guard.yaml +21 -0
  468. package/hooks/definitions/post_tool_capture.yaml +24 -0
  469. package/hooks/definitions/pre_compact_summary.yaml +19 -0
  470. package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
  471. package/hooks/definitions/protected_path_write_guard.yaml +19 -0
  472. package/hooks/definitions/session_start.yaml +19 -0
  473. package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
  474. package/hooks/loop-cap-guard +17 -0
  475. package/hooks/post-tool-lint +36 -0
  476. package/hooks/protected-path-write-guard +17 -0
  477. package/hooks/session-start +41 -0
  478. package/llms-full.txt +2355 -0
  479. package/llms.txt +43 -0
  480. package/package.json +79 -0
  481. package/roles/README.md +20 -0
  482. package/roles/clarifier.md +42 -0
  483. package/roles/content-author.md +63 -0
  484. package/roles/designer.md +55 -0
  485. package/roles/executor.md +55 -0
  486. package/roles/learner.md +51 -0
  487. package/roles/planner.md +53 -0
  488. package/roles/researcher.md +43 -0
  489. package/roles/reviewer.md +54 -0
  490. package/roles/specifier.md +47 -0
  491. package/roles/verifier.md +71 -0
  492. package/schemas/README.md +24 -0
  493. package/schemas/accepted-learning.schema.json +20 -0
  494. package/schemas/author-artifact.schema.json +156 -0
  495. package/schemas/clarification.schema.json +19 -0
  496. package/schemas/design-artifact.schema.json +80 -0
  497. package/schemas/docs-claim.schema.json +18 -0
  498. package/schemas/export-manifest.schema.json +20 -0
  499. package/schemas/hook.schema.json +67 -0
  500. package/schemas/host-export-package.schema.json +18 -0
  501. package/schemas/implementation-plan.schema.json +19 -0
  502. package/schemas/proposed-learning.schema.json +19 -0
  503. package/schemas/research.schema.json +18 -0
  504. package/schemas/review.schema.json +29 -0
  505. package/schemas/run-manifest.schema.json +18 -0
  506. package/schemas/spec-challenge.schema.json +18 -0
  507. package/schemas/spec.schema.json +20 -0
  508. package/schemas/usage.schema.json +102 -0
  509. package/schemas/verification-proof.schema.json +29 -0
  510. package/schemas/wazir-manifest.schema.json +173 -0
  511. package/skills/README.md +40 -0
  512. package/skills/brainstorming/SKILL.md +77 -0
  513. package/skills/debugging/SKILL.md +50 -0
  514. package/skills/design/SKILL.md +61 -0
  515. package/skills/dispatching-parallel-agents/SKILL.md +128 -0
  516. package/skills/executing-plans/SKILL.md +70 -0
  517. package/skills/finishing-a-development-branch/SKILL.md +169 -0
  518. package/skills/humanize/SKILL.md +123 -0
  519. package/skills/init-pipeline/SKILL.md +124 -0
  520. package/skills/prepare-next/SKILL.md +20 -0
  521. package/skills/receiving-code-review/SKILL.md +123 -0
  522. package/skills/requesting-code-review/SKILL.md +105 -0
  523. package/skills/requesting-code-review/code-reviewer.md +108 -0
  524. package/skills/run-audit/SKILL.md +197 -0
  525. package/skills/scan-project/SKILL.md +41 -0
  526. package/skills/self-audit/SKILL.md +153 -0
  527. package/skills/subagent-driven-development/SKILL.md +154 -0
  528. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  529. package/skills/subagent-driven-development/implementer-prompt.md +102 -0
  530. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  531. package/skills/tdd/SKILL.md +23 -0
  532. package/skills/using-git-worktrees/SKILL.md +163 -0
  533. package/skills/using-skills/SKILL.md +95 -0
  534. package/skills/verification/SKILL.md +22 -0
  535. package/skills/wazir/SKILL.md +463 -0
  536. package/skills/writing-plans/SKILL.md +30 -0
  537. package/skills/writing-skills/SKILL.md +157 -0
  538. package/skills/writing-skills/anthropic-best-practices.md +122 -0
  539. package/skills/writing-skills/persuasion-principles.md +50 -0
  540. package/templates/README.md +20 -0
  541. package/templates/artifacts/README.md +10 -0
  542. package/templates/artifacts/accepted-learning.md +19 -0
  543. package/templates/artifacts/accepted-learning.template.json +12 -0
  544. package/templates/artifacts/author.md +74 -0
  545. package/templates/artifacts/author.template.json +19 -0
  546. package/templates/artifacts/clarification.md +21 -0
  547. package/templates/artifacts/clarification.template.json +12 -0
  548. package/templates/artifacts/execute-notes.md +19 -0
  549. package/templates/artifacts/implementation-plan.md +21 -0
  550. package/templates/artifacts/implementation-plan.template.json +11 -0
  551. package/templates/artifacts/learning-proposal.md +19 -0
  552. package/templates/artifacts/next-run-handoff.md +21 -0
  553. package/templates/artifacts/plan-review.md +19 -0
  554. package/templates/artifacts/proposed-learning.template.json +12 -0
  555. package/templates/artifacts/research.md +21 -0
  556. package/templates/artifacts/research.template.json +12 -0
  557. package/templates/artifacts/review-findings.md +19 -0
  558. package/templates/artifacts/review.template.json +11 -0
  559. package/templates/artifacts/run-manifest.template.json +8 -0
  560. package/templates/artifacts/spec-challenge.md +19 -0
  561. package/templates/artifacts/spec-challenge.template.json +11 -0
  562. package/templates/artifacts/spec.md +21 -0
  563. package/templates/artifacts/spec.template.json +12 -0
  564. package/templates/artifacts/verification-proof.md +19 -0
  565. package/templates/artifacts/verification-proof.template.json +11 -0
  566. package/templates/examples/accepted-learning.example.json +14 -0
  567. package/templates/examples/author.example.json +152 -0
  568. package/templates/examples/clarification.example.json +15 -0
  569. package/templates/examples/docs-claim.example.json +8 -0
  570. package/templates/examples/export-manifest.example.json +7 -0
  571. package/templates/examples/host-export-package.example.json +11 -0
  572. package/templates/examples/implementation-plan.example.json +17 -0
  573. package/templates/examples/proposed-learning.example.json +13 -0
  574. package/templates/examples/research.example.json +15 -0
  575. package/templates/examples/research.example.md +6 -0
  576. package/templates/examples/review.example.json +17 -0
  577. package/templates/examples/run-manifest.example.json +9 -0
  578. package/templates/examples/spec-challenge.example.json +14 -0
  579. package/templates/examples/spec.example.json +21 -0
  580. package/templates/examples/verification-proof.example.json +21 -0
  581. package/templates/examples/wazir-manifest.example.yaml +65 -0
  582. package/templates/task-definition-schema.md +99 -0
  583. package/tooling/README.md +20 -0
  584. package/tooling/src/adapters/context-mode.js +50 -0
  585. package/tooling/src/capture/command.js +376 -0
  586. package/tooling/src/capture/store.js +99 -0
  587. package/tooling/src/capture/usage.js +270 -0
  588. package/tooling/src/checks/branches.js +50 -0
  589. package/tooling/src/checks/brand-truth.js +110 -0
  590. package/tooling/src/checks/changelog.js +231 -0
  591. package/tooling/src/checks/command-registry.js +36 -0
  592. package/tooling/src/checks/commits.js +102 -0
  593. package/tooling/src/checks/docs-drift.js +103 -0
  594. package/tooling/src/checks/docs-truth.js +201 -0
  595. package/tooling/src/checks/runtime-surface.js +156 -0
  596. package/tooling/src/cli.js +116 -0
  597. package/tooling/src/command-options.js +56 -0
  598. package/tooling/src/commands/validate.js +320 -0
  599. package/tooling/src/doctor/command.js +91 -0
  600. package/tooling/src/export/command.js +77 -0
  601. package/tooling/src/export/compiler.js +498 -0
  602. package/tooling/src/guards/loop-cap-guard.js +52 -0
  603. package/tooling/src/guards/protected-path-write-guard.js +67 -0
  604. package/tooling/src/index/command.js +152 -0
  605. package/tooling/src/index/storage.js +1061 -0
  606. package/tooling/src/index/summarizers.js +261 -0
  607. package/tooling/src/loaders.js +18 -0
  608. package/tooling/src/project-root.js +22 -0
  609. package/tooling/src/recall/command.js +225 -0
  610. package/tooling/src/schema-validator.js +30 -0
  611. package/tooling/src/state-root.js +40 -0
  612. package/tooling/src/status/command.js +71 -0
  613. package/wazir.manifest.yaml +135 -0
  614. package/workflows/README.md +19 -0
  615. package/workflows/author.md +42 -0
  616. package/workflows/clarify.md +38 -0
  617. package/workflows/design-review.md +46 -0
  618. package/workflows/design.md +44 -0
  619. package/workflows/discover.md +37 -0
  620. package/workflows/execute.md +48 -0
  621. package/workflows/learn.md +38 -0
  622. package/workflows/plan-review.md +42 -0
  623. package/workflows/plan.md +39 -0
  624. package/workflows/prepare-next.md +37 -0
  625. package/workflows/review.md +40 -0
  626. package/workflows/run-audit.md +41 -0
  627. package/workflows/spec-challenge.md +41 -0
  628. package/workflows/specify.md +38 -0
  629. package/workflows/verify.md +37 -0
@@ -0,0 +1,506 @@
1
+ # Background Jobs: Performance Expertise Module
2
+
3
+ ## Why Background Jobs Matter for API Latency
4
+
5
+ Every millisecond spent doing work inside an HTTP request-response cycle is a millisecond
6
+ the user waits. Background jobs move non-critical work off the request path, turning
7
+ synchronous bottlenecks into asynchronous operations that complete independently.
8
+
9
+ A typical user registration endpoint might do all of this synchronously:
10
+
11
+ 1. Validate input (1-2 ms)
12
+ 2. Hash password (50-100 ms with bcrypt, 12 rounds)
13
+ 3. Insert into database (5-20 ms)
14
+ 4. Send welcome email via SMTP (300-2,000 ms)
15
+ 5. Resize and upload avatar to S3 (200-1,500 ms)
16
+ 6. Sync to CRM via third-party API (100-800 ms)
17
+
18
+ **Total synchronous: 656-4,422 ms.** Only steps 1-3 must complete before responding.
19
+ Moving steps 4-6 to background jobs: **response drops to 56-122 ms** (steps 1-3 + ~1 ms
20
+ enqueue). That is a 10-35x improvement. Companies that implement background jobs report
21
+ up to 40% improvement in application responsiveness (Source:
22
+ [Microsoft Azure Architecture Center](https://learn.microsoft.com/en-us/azure/architecture/best-practices/background-jobs)).
23
+
24
+ ### Before/After: Email Sending Off the Request Path
25
+
26
+ ```
27
+ BEFORE (synchronous):
28
+ POST /api/checkout
29
+ ├── Validate cart 5 ms
30
+ ├── Process payment 40 ms
31
+ ├── Create order record 10 ms
32
+ ├── Send confirmation email 1,800 ms (SMTP handshake + delivery)
33
+ └── Return response
34
+ TOTAL: ~1,855 ms (p50), ~3,200 ms (p99)
35
+
36
+ AFTER (background job):
37
+ POST /api/checkout
38
+ ├── Validate cart 5 ms
39
+ ├── Process payment 40 ms
40
+ ├── Create order record 10 ms
41
+ ├── Enqueue email job 1 ms (Redis LPUSH)
42
+ └── Return response
43
+ TOTAL: ~56 ms (p50), ~85 ms (p99)
44
+ ```
45
+
46
+ SMTP is chatty: connection latency alone is 40-52 ms, full send cycle averages
47
+ 300-2,000 ms (Source: [SendGrid](https://docs.sendgrid.com/ui/account-and-settings/troubleshooting-delays-and-latency)).
48
+ **Result: API latency drops from ~1,855 ms to ~56 ms -- a 97% reduction.** The email
49
+ still arrives within seconds.
50
+
51
+ ---
52
+
53
+ ## Job Queue Systems Comparison
54
+
55
+ ### BullMQ (Node.js / TypeScript)
56
+
57
+ Redis-backed, Lua scripts for atomic operations. Throughput benchmarks (Source:
58
+ [BullMQ Benchmarks](https://bullmq.io/articles/benchmarks/bullmq-elixir-vs-oban/),
59
+ [Dragonfly + BullMQ](https://www.dragonflydb.io/blog/running-bullmq-with-dragonfly-part-2-optimization)):
60
+
61
+ | Scenario | Concurrency | Throughput |
62
+ |---|---|---|
63
+ | Minimal work (raw overhead) | Single worker | 27,200 jobs/sec |
64
+ | 10 ms simulated I/O | 10 | 911 jobs/sec |
65
+ | 10 ms simulated I/O | 100 | 8,300 jobs/sec |
66
+ | ~1 ms CPU work | 100 | 24,300 jobs/sec |
67
+ | With DragonflyDB backend | Multi-queue | 250,000+ jobs/sec |
68
+
69
+ Features: priority queues, rate limiting, cron scheduling, flow dependencies,
70
+ batch processing, built-in metrics.
71
+
72
+ ### Sidekiq (Ruby)
73
+
74
+ Redis-backed, multi-threaded. Benchmarks (Source:
75
+ [Sidekiq Scaling](https://sidekiq.org/wiki/Scaling)):
76
+
77
+ | Scenario | Configuration | Throughput |
78
+ |---|---|---|
79
+ | No-op jobs (sidekiqload) | Single process, 25 threads | ~4,500 jobs/sec |
80
+ | 5M job drain benchmark | Optimized | ~13,000 ops/sec |
81
+ | Enterprise Swarm | Multi-process containers | Billions/day |
82
+
83
+ Using Sidekiq natively is at least **2x faster** than wrapping in ActiveJob due to
84
+ serialization and callback overhead (Source:
85
+ [benchmark-sidekiq-and-activejob](https://github.com/chrismaximin/benchmark-sidekiq-and-activejob)).
86
+
87
+ ### Celery (Python)
88
+
89
+ Supports Redis and RabbitMQ brokers. Benchmarks (Source:
90
+ [Judoscale](https://judoscale.com/blog/choose-python-task-queue),
91
+ [UnfoldAI](https://unfoldai.com/redis-vs-rabbitmq-for-message-broker/)):
92
+
93
+ | Scenario | Broker | Throughput |
94
+ |---|---|---|
95
+ | Synchronous baseline | None | 200 tasks/sec |
96
+ | Celery + RabbitMQ | RabbitMQ | 1,200 tasks/sec (6x speedup) |
97
+ | 100K tasks, 400 workers | Redis | 1,370 tasks/sec (73 sec total) |
98
+ | 100K tasks, 400 workers | RabbitMQ | 1,075 tasks/sec (93 sec total) |
99
+
100
+ Redis is ~21% faster than RabbitMQ in write-heavy scenarios. For >10,000 msgs/min, Redis
101
+ delivers up to 15% reduced latency. RabbitMQ offers stronger durability guarantees.
102
+
103
+ ### AWS SQS (Managed Service)
104
+
105
+ Fully managed, no broker to operate. Benchmarks (Source:
106
+ [AWS Docs](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-throughput-horizontal-scaling-and-batching.html),
107
+ [SoftwareMill](https://softwaremill.com/amazon-sqs-performance-latency/)):
108
+
109
+ | Queue Type | Configuration | Throughput |
110
+ |---|---|---|
111
+ | Standard | Single thread, 20 ms latency | ~50 TPS |
112
+ | Standard | Multi-thread/client | Near-unlimited TPS |
113
+ | FIFO | Without batching | 300 msgs/sec |
114
+ | FIFO | With batching | 3,000 msgs/sec |
115
+ | FIFO High Throughput | Without batching | 70,000 msgs/sec |
116
+
117
+ Latency: 20-200 ms for API operations. Scaling is linear with client count.
118
+
119
+ ### Comparison Summary
120
+
121
+ | Feature | BullMQ | Sidekiq | Celery | AWS SQS |
122
+ |---|---|---|---|---|
123
+ | Language | Node.js/TS | Ruby | Python | Any (SDK) |
124
+ | Peak throughput | 27K/sec* | 13K/sec | 1.2K/sec** | Near-unlimited*** |
125
+ | Priority queues | Built-in | Weighted | Via routing | Multiple queues |
126
+ | Rate limiting | Built-in | Enterprise | Token bucket | Build yourself |
127
+ | DLQ support | Manual | Manual | Manual | Native |
128
+ | Ops burden | Manage Redis | Manage Redis | Manage broker | Zero |
129
+
130
+ \* Minimal work. \*\* Default; optimized reaches 10K+. \*\*\* Standard queues.
131
+
132
+ ---
133
+
134
+ ## Job Processing Patterns
135
+
136
+ ### 1. Fire-and-Forget
137
+
138
+ Enqueue and do not wait for the result. Highest throughput (<1 ms enqueue via Redis
139
+ LPUSH). Use for: email, analytics, audit logging, cache warming. Always pair with
140
+ DLQ monitoring to catch silent failures.
141
+
142
+ ### 2. Request-Reply (RPC over Queue)
143
+
144
+ Producer enqueues and waits for completion (polling or callback). Adds 50-200 ms
145
+ overhead vs. direct call. Use for: image processing where caller needs the URL,
146
+ PDF generation, synchronous-feeling workflows that benefit from worker isolation.
147
+
148
+ ### 3. Fan-Out (Scatter-Gather)
149
+
150
+ One event triggers multiple independent jobs in parallel. With N fan-out targets and
151
+ N dedicated worker pools, work completes in the time of the single slowest job.
152
+ Use for: order processing (inventory + email + analytics + fulfillment), notification
153
+ dispatch (email + SMS + push), ETL pipelines.
154
+
155
+ ### 4. Priority Queues
156
+
157
+ Jobs assigned priority levels; higher-priority dequeued first (Source:
158
+ [DZone](https://dzone.com/articles/modern-queue-patterns-guide)):
159
+
160
+ | Priority | Examples | Worker Allocation |
161
+ |---|---|---|
162
+ | P0 Critical | Payment processing, system alerts | 60% |
163
+ | P1 High | User-facing operations | 25% |
164
+ | P2 Normal | Batch processing, reports | 10% |
165
+ | P3 Low | Analytics, cleanup | 5% |
166
+
167
+ **Starvation risk:** Without safeguards, low-priority jobs never execute. Mitigate with
168
+ weighted fair queuing (Asynq uses `critical:6, default:3, low:1` ratios), age-based
169
+ promotion, or dedicated worker pools per tier.
170
+
171
+ ### 5. Pipeline (Chained Jobs)
172
+
173
+ Sequential execution where each job feeds results to the next. BullMQ Flows provide
174
+ parent-child dependencies; Celery uses chains and chords. Use for: ETL, multi-step
175
+ workflows (upload -> validate -> process -> notify).
176
+
177
+ ---
178
+
179
+ ## Batch Processing Optimization
180
+
181
+ Processing one-at-a-time incurs per-job overhead. Batching amortizes it. The difference
182
+ between naive and optimized batch approaches can be **10-100x** in execution time
183
+ (Source: [OneUptime](https://oneuptime.com/blog/post/2026-01-24-batch-processing-optimization/view)).
184
+
185
+ | Chunk Size | Throughput vs. Baseline | Failure Blast Radius |
186
+ |---|---|---|
187
+ | 1 (no batching) | 1x | 1 job |
188
+ | 100 | 3-5x | 100 jobs |
189
+ | 1,000 | 8-15x | 1,000 jobs |
190
+ | 10,000 | 10-20x | 10,000 jobs |
191
+
192
+ **Rule of thumb:** Start with chunks of 100-1,000 records.
193
+
194
+ **Worker sizing:** For CPU-bound work, set workers = CPU cores. For I/O-bound work,
195
+ set workers = 2-5x CPU cores (network wait overlaps).
196
+
197
+ **Checkpointing:** For jobs >5 minutes, save progress every N records to enable
198
+ resumable processing. Shopify's `job-iteration` gem makes jobs interruptible and
199
+ resumable by design, running in production since 2017 (Source:
200
+ [Shopify Engineering](https://shopify.engineering/high-availability-background-jobs)).
201
+
202
+ ---
203
+
204
+ ## Retry Strategies with Exponential Backoff
205
+
206
+ Fixed-interval retries create thundering herds: 10,000 jobs all retrying at exactly
207
+ 60 seconds overwhelm a recovering service. Exponential backoff with jitter spreads load.
208
+
209
+ **Formula:** `delay = min(base_delay * 2^(attempt - 1) + jitter, max_delay)`
210
+
211
+ Example with base delay 3,000 ms (Source:
212
+ [BullMQ Docs](https://docs.bullmq.io/guide/retrying-failing-jobs)):
213
+
214
+ | Attempt | Delay | Cumulative Wait |
215
+ |---|---|---|
216
+ | 1 | 3 sec | 3 sec |
217
+ | 2 | 6 sec | 9 sec |
218
+ | 3 | 12 sec | 21 sec |
219
+ | 5 | 48 sec | 1.5 min |
220
+ | 7 | 192 sec (3.2 min) | 6.3 min |
221
+
222
+ **Jitter strategies:** Full jitter (`random(0, base * 2^attempt)`) provides best
223
+ spread and is recommended by AWS. Equal jitter guarantees minimum delay. Decorrelated
224
+ jitter minimizes correlation between clients.
225
+
226
+ **Configuration by job type:**
227
+
228
+ | Job Type | Max Retries | Base Delay | Max Delay |
229
+ |---|---|---|---|
230
+ | Email sending | 5 | 30 sec | 30 min |
231
+ | Payment webhook | 8 | 60 sec | 4 hours |
232
+ | API sync | 5 | 10 sec | 10 min |
233
+ | Image processing | 3 | 5 sec | 2 min |
234
+
235
+ ---
236
+
237
+ ## Dead Letter Queues and Failure Handling
238
+
239
+ A DLQ receives messages that could not be processed after exhausting retries. It isolates
240
+ problematic messages for inspection without blocking valid message processing (Source:
241
+ [Medium - Yapi Kredi Teknoloji](https://medium.com/yapi-kredi-teknoloji/dead-letter-queue-dlq-and-retry-management-in-asynchronous-microservices-054bb318b1bb)).
242
+
243
+ ```
244
+ Producer -> Main Queue -> Worker --Success--> Done
245
+ --Failure--> Retry (N times)
246
+ --Exhausted--> DLQ -> Alert + Manual Review
247
+ ```
248
+
249
+ **AWS SQS DLQ config** (Source:
250
+ [AWS Docs](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html)):
251
+ maxReceiveCount range 1-1,000, default 10. Recommended: 3-5 for most workloads.
252
+ Setting to 1 moves messages on a single transient failure. DLQ retention must exceed
253
+ source queue retention.
254
+
255
+ ### Failure Classification
256
+
257
+ | Failure Type | Example | Retry? | Action |
258
+ |---|---|---|---|
259
+ | Transient | Network timeout, 503 | Yes | Exponential backoff |
260
+ | Rate limit | 429 Too Many Requests | Yes | Backoff + rate awareness |
261
+ | Bad input | Invalid email format | No | DLQ immediately |
262
+ | Auth failure | Expired API key | No | Alert, DLQ |
263
+ | Bug in handler | TypeError, NPE | No | DLQ, fix code, replay |
264
+
265
+ Always implement DLQ replay: after fixing the root cause, move DLQ messages back to the
266
+ main queue for reprocessing.
267
+
268
+ ---
269
+
270
+ ## Job Scheduling and Rate Limiting
271
+
272
+ ### Scheduled Jobs
273
+
274
+ Use cron-style scheduling for recurring work. In multi-worker deployments, ensure only
275
+ one instance creates the schedule (BullMQ uses Redis locks, Sidekiq Enterprise uses
276
+ `unique_for`, Celery uses single `celery-beat` process).
277
+
278
+ ### Rate Limiting
279
+
280
+ Control processing speed to protect downstream services:
281
+
282
+ | Strategy | Description | Use Case |
283
+ |---|---|---|
284
+ | Fixed window | N jobs per time window | API rate limits |
285
+ | Sliding window | N jobs in rolling window | Traffic shaping |
286
+ | Token bucket | Tokens replenish at fixed rate | Variable workloads |
287
+ | Concurrency limit | Max N simultaneous jobs | Resource protection |
288
+
289
+ **Practical rate limits** (set to 70-80% of downstream service limit):
290
+
291
+ | Service | API Limit | Recommended Job Rate |
292
+ |---|---|---|
293
+ | SendGrid | 600/sec | 500 jobs/sec |
294
+ | Stripe | 100 reads/sec | 80 jobs/sec |
295
+ | Twilio | 100 msgs/sec | 80 jobs/sec |
296
+ | GitHub API | 5,000/hour | 1 job/sec |
297
+
298
+ ---
299
+
300
+ ## Common Bottlenecks
301
+
302
+ ### 1. Queue Backup (Growing Depth)
303
+
304
+ Queue depth grows continuously; consumers cannot keep up. Causes: producer rate exceeds
305
+ consumer rate, traffic spikes, slow downstream dependencies. Redis stores all pending
306
+ jobs in memory -- unbounded growth leads to OOM.
307
+
308
+ **Fixes:** Add workers (linear throughput scaling), increase concurrency, enable batching,
309
+ implement backpressure. **Alert:** Queue depth >2x steady state for >5 minutes.
310
+
311
+ ### 2. Slow Consumers
312
+
313
+ Jobs take 10-100x longer than expected. Causes: downstream API degradation, N+1 queries
314
+ in job handler, unbounded data processing (1M records in one job).
315
+
316
+ **Fixes:** Per-job timeouts (30s for email, 5min for reports), profile handlers, circuit
317
+ breakers for external deps, chunk large datasets (1,000 per job, not 1,000,000).
318
+
319
+ ### 3. No Backpressure
320
+
321
+ Producers enqueue faster than consumers process with no mechanism to slow down. Result:
322
+ unbounded queue growth, Redis OOM, total system failure (Source:
323
+ [AWS Builders Library](https://aws.amazon.com/builders-library/avoiding-insurmountable-queue-backlogs/)).
324
+
325
+ **Fixes:** Queue depth limits (reject when >N items), dynamic rate limiting based on
326
+ consumer lag, spillover queues (Amazon's pattern), circuit breaker on enqueue (return
327
+ HTTP 503).
328
+
329
+ ### 4. Job Starvation
330
+
331
+ Low-priority jobs never execute because high-priority jobs consume all workers.
332
+
333
+ **Fixes:** Weighted fair queuing (`critical:6, default:3, low:1`), dedicated worker pools
334
+ per priority, age-based promotion (auto-promote after 30min wait).
335
+
336
+ ### 5. Redis Memory Exhaustion
337
+
338
+ Causes: completed jobs not cleaned up, large payloads (>10 KB/job), millions of pending
339
+ jobs. 10,000 jobs at 50 MB each = 500 GB Redis memory.
340
+
341
+ **Fixes:** Configure `removeOnComplete` with TTLs, store large data in S3/DB and pass
342
+ references only (<1 KB payloads), set `maxmemory-policy` to `noeviction`, monitor usage.
343
+
344
+ ---
345
+
346
+ ## Anti-Patterns
347
+
348
+ ### 1. Processing in the Request Path
349
+
350
+ Synchronously sending email, notifying warehouses, syncing analytics in an HTTP handler.
351
+ User waits 1.3-2.8 seconds instead of <100 ms. **Fix:** Enqueue as background jobs.
352
+
353
+ ### 2. No Retry Limits
354
+
355
+ `max_retries=None` means a permanently invalid record retries forever. At 1 retry/min,
356
+ that is 1,440 wasted executions/day. **Fix:** Always set max_retries (3-8).
357
+
358
+ ### 3. No Monitoring
359
+
360
+ Silent queue failures are invisible until user-facing impact (Source:
361
+ [Last9](https://last9.io/blog/background-job-observability/)). A DLQ growing at
362
+ 100 jobs/hour goes unnoticed for 3 days = 7,200 lost jobs. **Fix:** Alert on queue
363
+ depth, failure rate, DLQ growth.
364
+
365
+ ### 4. Huge Job Payloads
366
+
367
+ Embedding 50 MB CSV data in job payload. 10K such jobs = 500 GB Redis memory.
368
+ **Fix:** Store externally, pass references: `{ fileKey: 's3://bucket/file.csv' }`.
369
+
370
+ ### 5. Mixing Job Types in One Queue
371
+
372
+ A bulk export creating 10K tasks blocks password reset emails in a FIFO queue (Source:
373
+ [ShermanOnSoftware](https://shermanonsoftware.com/2024/07/10/multiple-queues-vs-prioritized-queues-for-saas-background-workers/)).
374
+ **Fix:** Separate queues by category (emails-critical, emails-marketing, reports).
375
+
376
+ ### 6. Non-Idempotent Jobs
377
+
378
+ Retrying a payment job without idempotency keys charges the customer twice.
379
+ **Fix:** Use idempotency keys (`idempotency_key: charge-${orderId}`).
380
+
381
+ ---
382
+
383
+ ## Monitoring and Observability
384
+
385
+ ### Key Metrics
386
+
387
+ | Metric | Alert Threshold | Why It Matters |
388
+ |---|---|---|
389
+ | Queue depth | >2x steady state for 5 min | Backlog growing |
390
+ | Processing time (p50/p95/p99) | p99 > 3x p50 | Performance degradation |
391
+ | Failure rate | >5% over 15 min | Systemic issue |
392
+ | Throughput (jobs/sec) | <50% expected | Worker failures |
393
+ | DLQ depth growth | >0 sustained | Unrecoverable failures |
394
+ | Job age (time in queue) | p95 > 60 sec | Capacity issues |
395
+ | Worker utilization | >90% sustained | Need more workers |
396
+ | Avg retry count | >1.5 per job | Flaky dependency |
397
+
398
+ (Source: [Last9](https://last9.io/blog/background-job-observability/),
399
+ [BullMQ Metrics](https://docs.bullmq.io/guide/metrics))
400
+
401
+ ### Rate-of-Change Analysis
402
+
403
+ Raw queue depth is misleading. Depth of 5,000 is fine if draining at 1,000/sec (5s to
404
+ clear) but critical if growing at 100/sec (Source:
405
+ [OneUptime](https://oneuptime.com/blog/post/2026-01-27-sqs-queue-depth-monitoring/view)):
406
+
407
+ ```
408
+ drain_rate = (depth_t0 - depth_t1) / interval
409
+ time_to_drain = current_depth / drain_rate (if draining)
410
+ time_to_oom = available_memory / (growth_rate * avg_job_size) (if growing)
411
+ ```
412
+
413
+ ### Dashboard Essentials
414
+
415
+ 1. **Real-time:** Queue depth per queue, active workers, jobs/sec
416
+ 2. **Trends:** Processing time percentiles over 24h
417
+ 3. **Failures:** Failure rate, DLQ depth, top error messages
418
+ 4. **Capacity:** Worker utilization, estimated drain time
419
+
420
+ ---
421
+
422
+ ## Decision Tree: Should This Be a Background Job?
423
+
424
+ ```
425
+ Does the user need the result before you can respond?
426
+ |
427
+ +-- YES: Can it complete in <200 ms?
428
+ | +-- YES -> Keep in request path (DB reads, auth, validation)
429
+ | +-- NO -> Request-reply pattern. Return 202 + polling if >5s.
430
+ |
431
+ +-- NO: Is the work idempotent (or can you make it so)?
432
+ +-- NO -> Refactor for idempotency first, then background it.
433
+ +-- YES: How critical is delivery?
434
+ +-- MUST deliver (payments, compliance)
435
+ | -> Transactional outbox + background job. DLQ + alerts. Max retries 8-10.
436
+ +-- SHOULD deliver (emails, notifications)
437
+ | -> Standard background job + retry + DLQ. Max retries 3-5.
438
+ +-- NICE to deliver (analytics, cache)
439
+ -> Fire-and-forget. Max retries 1-2. Accept some loss.
440
+ ```
441
+
442
+ ### Quick Reference
443
+
444
+ | Operation | Background? | Pattern | Rationale |
445
+ |---|---|---|---|
446
+ | Password hashing | No | Request path | User needs auth result now |
447
+ | Welcome email | Yes | Fire-and-forget | User proceeds without seeing it |
448
+ | PDF invoice | Yes | Request-reply | Takes 2-30 seconds |
449
+ | Image thumbnails | Yes | Fire-and-forget | Show placeholder until ready |
450
+ | Search index update | Yes | Fire-and-forget | Eventual consistency OK |
451
+ | Data export (CSV) | Yes | Async + 202 | Can take minutes |
452
+ | Webhook delivery | Yes | Fire-and-forget + retry | External endpoint, needs backoff |
453
+ | Report aggregation | Yes | Scheduled (cron) | Runs on fixed schedule |
454
+
455
+ ---
456
+
457
+ ## Production Checklist
458
+
459
+ - [ ] Idempotency: every handler safe to retry without side effects
460
+ - [ ] Retry policy: max_retries 3-8, exponential backoff configured
461
+ - [ ] Dead letter queue: configured, monitored, alerting on growth
462
+ - [ ] Timeouts: per-job timeout set (prevent zombie jobs)
463
+ - [ ] Payload size: <10 KB; large data stored externally with references
464
+ - [ ] Monitoring: queue depth, failure rate, processing time, DLQ dashboards
465
+ - [ ] Alerting: queue backup, high failure rate, DLQ growth
466
+ - [ ] Graceful shutdown: workers finish in-flight jobs on SIGTERM
467
+ - [ ] Connection pooling: DB/Redis connections pooled, not per-job
468
+ - [ ] Separate queues: different job types by priority/SLA
469
+ - [ ] Cleanup: completed/failed jobs auto-removed after TTL (24-72h)
470
+ - [ ] Backpressure: queue depth limits or producer throttling
471
+ - [ ] Health checks: worker liveness probes (K8s, ECS)
472
+
473
+ ---
474
+
475
+ ## Sources
476
+
477
+ - [BullMQ Official Site & Benchmarks](https://bullmq.io/)
478
+ - [BullMQ Elixir vs Oban Benchmark](https://bullmq.io/articles/benchmarks/bullmq-elixir-vs-oban/)
479
+ - [BullMQ Metrics Docs](https://docs.bullmq.io/guide/metrics)
480
+ - [BullMQ Retry Docs](https://docs.bullmq.io/guide/retrying-failing-jobs)
481
+ - [Dragonfly + BullMQ Optimization](https://www.dragonflydb.io/blog/running-bullmq-with-dragonfly-part-2-optimization)
482
+ - [Sidekiq Official](https://sidekiq.org/) | [Scaling Wiki](https://sidekiq.org/wiki/Scaling)
483
+ - [Sidekiq 7.0 Metrics](https://www.mikeperham.com/2022/10/27/sidekiq-7.0-metrics/)
484
+ - [Benchmark Sidekiq vs ActiveJob](https://github.com/chrismaximin/benchmark-sidekiq-and-activejob)
485
+ - [Sensor Tower: Scaling Sidekiq Workers](https://sensortower.com/blog/how-we-scaled-to-thousands-of-sidekiq-workers)
486
+ - [Celery Best Practices](https://moldstud.com/articles/p-celery-configuration-best-practices-enhance-your-task-queue-efficiency)
487
+ - [Redis vs RabbitMQ for Celery](https://unfoldai.com/redis-vs-rabbitmq-for-message-broker/)
488
+ - [Judoscale: Python Task Queues](https://judoscale.com/blog/choose-python-task-queue)
489
+ - [AWS SQS Performance](https://softwaremill.com/amazon-sqs-performance-latency/)
490
+ - [AWS SQS Throughput Scaling](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-throughput-horizontal-scaling-and-batching.html)
491
+ - [AWS SQS Dead Letter Queues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html)
492
+ - [AWS SQS FIFO High Throughput](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/high-throughput-fifo.html)
493
+ - [AWS Builders Library: Queue Backlogs](https://aws.amazon.com/builders-library/avoiding-insurmountable-queue-backlogs/)
494
+ - [SQS Queue Depth Monitoring](https://oneuptime.com/blog/post/2026-01-27-sqs-queue-depth-monitoring/view)
495
+ - [Shopify: High Availability Background Jobs](https://shopify.engineering/high-availability-background-jobs)
496
+ - [Shopify job-iteration](https://github.com/Shopify/job-iteration)
497
+ - [Microsoft Azure: Background Jobs Guidance](https://learn.microsoft.com/en-us/azure/architecture/best-practices/background-jobs)
498
+ - [DZone: Modern Queue Patterns](https://dzone.com/articles/modern-queue-patterns-guide)
499
+ - [Backpressure in Distributed Systems](https://dzone.com/articles/backpressure-in-distributed-systems)
500
+ - [DLQ and Retry Management](https://medium.com/yapi-kredi-teknoloji/dead-letter-queue-dlq-and-retry-management-in-asynchronous-microservices-054bb318b1bb)
501
+ - [Queue-Based Exponential Backoff](https://dev.to/andreparis/queue-based-exponential-backoff-a-resilient-retry-pattern-for-distributed-systems-37f3)
502
+ - [Background Job Observability - Last9](https://last9.io/blog/background-job-observability/)
503
+ - [Batch Processing Optimization](https://oneuptime.com/blog/post/2026-01-24-batch-processing-optimization/view)
504
+ - [Multiple vs Prioritized Queues](https://shermanonsoftware.com/2024/07/10/multiple-queues-vs-prioritized-queues-for-saas-background-workers/)
505
+ - [SendGrid: Delays and Latency](https://docs.sendgrid.com/ui/account-and-settings/troubleshooting-delays-and-latency)
506
+ - [Bull vs Celery vs Sidekiq](https://www.index.dev/skill-vs-skill/backend-sidekiq-vs-celery-vs-bull)