@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,24 @@
1
+ # Directory Purpose
2
+
3
+ The `backend` directory provides language and framework-specific guidelines for building robust, secure, and scalable server-side applications and APIs.
4
+
5
+ # Key Concepts
6
+
7
+ - Backend framework idioms and conventions
8
+ - Dependency injection and routing
9
+ - Managing asynchronous operations and concurrency
10
+
11
+ # File Map
12
+
13
+ - `index.md` — semantic map of the backend directory
14
+ - `go.md` — Goroutines, channels, and standard library idioms
15
+ - `java-spring.md` — Spring Boot, dependency injection, and JPA
16
+ - `node-typescript.md` — Express/NestJS, event loop, and TS typing
17
+ - `python-fastapi.md` — Pydantic, async/await, and dependency injection
18
+ - `rust.md` — Cargo, ownership model, and safe concurrency
19
+
20
+ # Reading Guide
21
+
22
+ If writing a Node service → read `node-typescript.md`
23
+ If writing a high-performance systems service → read `go.md` or `rust.md`
24
+ If writing a Python API → read `python-fastapi.md`
@@ -0,0 +1,448 @@
1
+ # Java + Spring Boot — Expertise Module
2
+
3
+ > A Java/Spring Boot specialist designs, builds, and maintains backend services using the Spring ecosystem on
4
+ > Java 21+. Scope covers REST/GraphQL APIs, data access, security, messaging, observability, and cloud-native
5
+ > deployment — from monolith to microservices — with emphasis on production-grade reliability and performance.
6
+
7
+ ---
8
+
9
+ ## 1. Core Patterns & Conventions
10
+
11
+ ### 1.1 Project Structure
12
+
13
+ **Feature-based packaging** over layer-based for anything beyond trivial services. Group all layers
14
+ (controller, service, repository, model) per domain concept for cohesion and future extractability.
15
+
16
+ ```
17
+ com.example.app
18
+ ├── order/ # Feature package
19
+ │ ├── OrderController.java
20
+ │ ├── OrderService.java
21
+ │ ├── OrderRepository.java
22
+ │ ├── Order.java
23
+ │ └── OrderDto.java
24
+ ├── product/
25
+ ├── shared/ # Cross-cutting: exceptions, config, security
26
+ └── Application.java
27
+ ```
28
+
29
+ **Multi-module** rule: one module per deployable artifact. Common split: `app-api` (controllers),
30
+ `app-domain` (entities, services, ports — no Spring), `app-infrastructure` (JPA, messaging adapters),
31
+ `app-common` (shared DTOs, exceptions).
32
+
33
+ ### 1.2 Naming Conventions
34
+
35
+ | Element | Convention | Example |
36
+ |------------------|------------------------|----------------------------------|
37
+ | Classes | PascalCase, noun | `OrderService`, `PaymentGateway` |
38
+ | Interfaces | No `I` prefix | `OrderRepository` |
39
+ | Methods | camelCase, verb-first | `findByStatus()`, `cancelOrder()`|
40
+ | Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
41
+ | REST endpoints | kebab-case, plural | `/api/v1/purchase-orders` |
42
+ | Config properties| kebab-case | `app.order-service.max-retries` |
43
+ | DB tables/cols | snake_case | `purchase_order`, `created_at` |
44
+
45
+ ### 1.3 Architecture Patterns
46
+
47
+ - **Layered** (simple CRUD): Controller -> Service -> Repository -> DB. Quick, sufficient for small contexts.
48
+ - **Hexagonal / Ports & Adapters** (complex domains): Domain at center with zero framework deps. Inbound ports define use cases; outbound ports define infra contracts. Preferred for DDD, well-supported by Spring Modulith.
49
+ - **DDD tactical patterns**: Entities (identity + lifecycle), Value Objects (immutable, use records), Aggregates (consistency boundaries), Domain Events (via `ApplicationEventPublisher`), Repositories (one per aggregate root).
50
+
51
+ ### 1.4 Spring Boot 3.x Patterns
52
+
53
+ - **Auto-configuration**: Override selectively via `@ConditionalOnProperty` / `@ConditionalOnMissingBean`. Exclude specific classes, not wholesale: `@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})`
54
+ - **Profiles**: `application-{profile}.yml` for env config (`dev`, `test`, `prod`). Prefer externalized config (env vars, config maps) over profile-specific `@Configuration` classes.
55
+ - **Custom starters**: For shared cross-cutting concerns in multi-service orgs: `company-spring-boot-starter-observability`.
56
+
57
+ ### 1.5 Dependency Injection
58
+
59
+ **Constructor injection is mandatory** (Spring team recommendation). Immutable fields, testable without reflection, fails fast. Single constructor needs no `@Autowired`. Use `@Qualifier` for disambiguation. Never use `@Autowired` on fields.
60
+
61
+ ### 1.6 Data Access
62
+
63
+ - **Spring Data JPA** (default): `JpaRepository<T, ID>`, derived queries, `@Query` JPQL, `@Transactional(readOnly = true)` on reads, projections (interfaces/records) for read-only queries.
64
+ - **JdbcClient** (Spring Boot 3.2+): Lightweight alternative for simple/bulk queries.
65
+ - **R2DBC**: Only with WebFlux end-to-end; mixing with blocking JPA defeats the purpose.
66
+
67
+ ### 1.7 Error Handling — RFC 7807 ProblemDetail
68
+
69
+ Enable globally with `spring.mvc.problemdetails.enabled: true`. Combine with `@RestControllerAdvice extends ResponseEntityExceptionHandler` for custom exception mapping. Return `ProblemDetail` with `type`, `title`, `status`, `detail`, and custom properties.
70
+
71
+ ### 1.8 Logging & Observability
72
+
73
+ - **Structured logging**: SLF4J + Logback with `logstash-logback-encoder` (JSON in prod). Include trace/span IDs via Micrometer.
74
+ - **Micrometer + OpenTelemetry**: Micrometer as metrics facade; OTLP export for metrics, traces, logs (Spring Boot 3.2+). Use `@Observed` for custom observations. Spring Boot 4 adds `spring-boot-starter-opentelemetry`.
75
+
76
+ ### 1.9 Virtual Threads (Project Loom)
77
+
78
+ Enable: `spring.threads.virtual.enabled: true` (Spring Boot 3.2+). Configures Tomcat/Jetty + `@Async` + executors.
79
+
80
+ **Rules**: Replace `synchronized` with `ReentrantLock` (avoid carrier-thread pinning). Never pool virtual threads. Use `ScopedValue` over `ThreadLocal`. Monitor pinning: `-Djdk.tracePinnedThreads=short`. Increase HikariCP pool size for higher concurrency.
81
+
82
+ ---
83
+
84
+ ## 2. Anti-Patterns & Pitfalls
85
+
86
+ ### 2.1 Field Injection Everywhere
87
+ `@Autowired` on fields hides dependencies, prevents immutability, requires reflection for testing. Use constructor injection.
88
+
89
+ ### 2.2 God Service Classes
90
+ Services with 20+ methods spanning multiple domains violate SRP. Split by bounded context or use case.
91
+
92
+ ### 2.3 Catching Exception/Throwable Generically
93
+ Swallows programming errors (`NullPointerException`, `IllegalStateException`). Catch specific exceptions; let unexpected ones reach the global handler.
94
+
95
+ ### 2.4 N+1 Query Problem
96
+ Lazy-loaded collections trigger one query per entity (100 orders = 101 queries). Fix: `@EntityGraph`, `JOIN FETCH`, or DTO projections.
97
+
98
+ ### 2.5 Missing @Transactional(readOnly = true)
99
+ Read-write transactions on read paths hold write locks, prevent replica routing, waste connection time.
100
+
101
+ ### 2.6 Unbounded Caches
102
+ `@Cacheable` without TTL or max-size causes OOM. Always configure eviction; monitor hit rates.
103
+
104
+ ### 2.7 Full Spring Context in Unit Tests
105
+ `@SpringBootTest` for a single class loads everything — tests take seconds instead of ms. Use JUnit + Mockito for units; slice tests for layers.
106
+
107
+ ### 2.8 Business Logic in Controllers
108
+ Controllers should handle HTTP concerns only. Business rules in controllers can't be reused (messaging, scheduled tasks) and are harder to test.
109
+
110
+ ### 2.9 Ignoring Connection Pool Configuration
111
+ HikariCP defaults (`maximumPoolSize=10`) are rarely optimal. With virtual threads, connection starvation is common. Size based on load: `connections = (core_count * 2) + spindle_count`.
112
+
113
+ ### 2.10 Returning JPA Entities from Controllers
114
+ Exposes internal schema, creates DB-API coupling, risks infinite recursion with bidirectional relationships, leaks sensitive fields. Map to DTOs (records).
115
+
116
+ ### 2.11 Hardcoded Configuration Values
117
+ Connection strings, timeouts in code require recompilation. Use `@ConfigurationProperties` with `@Validated`.
118
+
119
+ ### 2.12 No Database Migrations
120
+ `ddl-auto=update` in production causes unpredictable changes and data loss. Use Flyway or Liquibase.
121
+
122
+ ### 2.13 Synchronous Microservice Chains
123
+ HTTP calls across 5+ services multiply latency and cascade failures. Use async messaging for non-critical flows; circuit breakers (Resilience4j) for sync calls.
124
+
125
+ ### 2.14 Missing Input Validation
126
+ Trusting client input leads to injection, corrupt data, cryptic errors. Bean Validation (`@Valid`) at controller boundary; domain validation in constructors.
127
+
128
+ ---
129
+
130
+ ## 3. Testing Strategy
131
+
132
+ ### 3.1 Unit Testing (JUnit 5 + Mockito + AssertJ)
133
+ Test classes in isolation, no Spring context. `@ExtendWith(MockitoExtension.class)`, `@Mock`, `@InjectMocks`. Use AssertJ fluent assertions (`assertThat`, `assertThatThrownBy`).
134
+
135
+ ### 3.2 Slice Testing
136
+ - **@WebMvcTest**: Controller layer with MockMvc; mock services via `@MockBean`.
137
+ - **@DataJpaTest**: JPA repos with embedded DB or Testcontainers. Auto-configures `EntityManager` only.
138
+
139
+ ### 3.3 Integration Testing (Testcontainers)
140
+ Spring Boot 3.1+ first-class support. Use `@ServiceConnection` (replaces `@DynamicPropertySource`) for automatic datasource/broker config from containers. Prefer Testcontainers over H2 for realistic tests.
141
+
142
+ ```java
143
+ @SpringBootTest
144
+ @Testcontainers
145
+ class OrderIntegrationTest {
146
+ @Container @ServiceConnection
147
+ static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
148
+
149
+ @Autowired OrderService orderService;
150
+
151
+ @Test
152
+ void shouldPersistAndRetrieveOrder() {
153
+ var id = orderService.placeOrder(new CreateOrderCommand(...));
154
+ assertThat(orderService.findById(id).status()).isEqualTo(OrderStatus.PLACED);
155
+ }
156
+ }
157
+ ```
158
+
159
+ ### 3.4 Contract Testing (Spring Cloud Contract)
160
+ Define contracts in Groovy/YAML. Producer generates tests; consumer gets stub server. Ensures API compatibility without deploying both services.
161
+
162
+ ### 3.5 Architecture Testing (ArchUnit)
163
+ Enforce layer dependencies, no-field-injection rules, naming conventions, and cycle-free packages as unit tests. Integrates with JUnit 5. Current version: 1.4.x (2025).
164
+
165
+ ### 3.6 Testing Pyramid
166
+
167
+ | Level | Framework | Speed | Ratio |
168
+ |--------------|----------------------------|---------|-------|
169
+ | Unit | JUnit 5 + Mockito | ms | 70% |
170
+ | Slice | @WebMvcTest / @DataJpaTest | ~1-3s | 15% |
171
+ | Integration | @SpringBootTest + TC | ~5-15s | 10% |
172
+ | Contract | Spring Cloud Contract | ~2-5s | 5% |
173
+ | Architecture | ArchUnit | ms | + |
174
+
175
+ ---
176
+
177
+ ## 4. Performance Considerations
178
+
179
+ ### 4.1 JVM Tuning
180
+ - **GC**: G1GC (default, balanced); ZGC for low-latency (<1ms pauses).
181
+ - **Heap**: `-Xms` = `-Xmx` in containers (avoid resize overhead). JVM auto-detects cgroup limits (Java 10+).
182
+ - **Always on in prod**: `-Xlog:gc*:file=gc.log:time`. Set `-XX:MaxMetaspaceSize`.
183
+
184
+ ### 4.2 Startup Optimization
185
+
186
+ | Technique | Impact | Trade-off |
187
+ |------------------------|-----------------|-------------------------------------|
188
+ | GraalVM Native Image | ~50-75ms start | Long build, no runtime reflection |
189
+ | CDS (Class Data Sharing)| 30-50% faster | Requires training run |
190
+ | Lazy init | 30-40% faster | First request slower |
191
+ | Spring AOT | 20-30% faster | Build-time bean resolution |
192
+
193
+ ### 4.3 HikariCP Connection Pooling
194
+ Tune `maximum-pool-size` (default 10 is rarely enough), `idle-timeout`, `max-lifetime`, `leak-detection-threshold`. Increase pool size with virtual threads — more concurrent requests means more simultaneous connection demand.
195
+
196
+ ### 4.4 Caching
197
+ Caffeine for local (TTL, max-size, async refresh). Redis for distributed. Always set TTL + max-size; monitor hit/miss with Micrometer. Use `@Cacheable(unless = "#result == null")`.
198
+
199
+ ### 4.5 Virtual Threads vs WebFlux
200
+
201
+ | Criterion | MVC + Virtual Threads | WebFlux (Reactive) |
202
+ |-----------------|---------------------------|---------------------------|
203
+ | Code style | Imperative (familiar) | Functional/reactive |
204
+ | Debugging | Standard stack traces | Complex async traces |
205
+ | DB support | JDBC, JPA (full ecosystem)| R2DBC (limited) |
206
+ | Backpressure | Manual (semaphore) | Built-in (Reactor) |
207
+ | Best for | 90% of enterprise apps | Streaming, gateways, SSE |
208
+
209
+ **Default (2025+)**: MVC + virtual threads for new projects.
210
+
211
+ ---
212
+
213
+ ## 5. Security Considerations
214
+
215
+ ### 5.1 Spring Security 6.x
216
+ Component-based config — no `WebSecurityConfigurerAdapter`. Declare `SecurityFilterChain` bean. Use `requestMatchers()` (not deprecated `antMatchers()`).
217
+
218
+ ### 5.2 OAuth2 Resource Server
219
+ Add `spring-boot-starter-oauth2-resource-server`. Configure `spring.security.oauth2.resourceserver.jwt.issuer-uri`. Validate `aud` claim. Use `oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))`.
220
+
221
+ ### 5.3 Method-Level Security
222
+ `@EnableMethodSecurity` (replaces `@EnableGlobalMethodSecurity`). Use `@PreAuthorize` / `@PostAuthorize` with SpEL expressions for fine-grained access control.
223
+
224
+ ### 5.4 CSRF & CORS
225
+ Disable CSRF only for stateless APIs (JWT/OAuth2). Configure CORS explicitly per origin — never `allowedOrigins("*")` in production. Set allowed methods and headers explicitly.
226
+
227
+ ### 5.5 Input Validation
228
+ Bean Validation on DTOs (`@NotNull`, `@Size`, `@Positive`) + `@Valid` at controller boundary. Custom validators for cross-field logic. Domain validation in constructors as second defense.
229
+
230
+ ---
231
+
232
+ ## 6. Integration Patterns
233
+
234
+ ### 6.1 REST API (Spring MVC + OpenAPI)
235
+ Use `springdoc-openapi-starter-webmvc-ui` (2.8.x) for OpenAPI 3.x + Swagger UI. Generate client SDKs with OpenAPI Generator.
236
+
237
+ ### 6.2 Messaging
238
+ - **Spring Kafka**: `@KafkaListener(topics, groupId)` for consumers.
239
+ - **Spring Cloud Stream**: Broker-agnostic — define `Function`/`Consumer`/`Supplier` beans, bind via config. Switch Kafka <-> RabbitMQ without code changes.
240
+
241
+ ### 6.3 GraphQL
242
+ Built-in support in Spring Boot 3.x. `@QueryMapping`, `@SchemaMapping` for resolvers. Supports batching via `@BatchMapping`.
243
+
244
+ ### 6.4 Scheduling
245
+ `@Scheduled(cron = ...)` + ShedLock (`@SchedulerLock`) for distributed locking in multi-instance deployments. Spring Batch or Quartz for complex orchestration.
246
+
247
+ ### 6.5 Event-Driven (Spring Modulith)
248
+ Inter-module communication via `ApplicationEventPublisher` + `@ApplicationModuleListener` (transactional, at-least-once). Events externalize to Kafka/RabbitMQ via `@EnableSpringCloudStreamEventExternalization` — no code changes in publisher.
249
+
250
+ ---
251
+
252
+ ## 7. DevOps & Deployment
253
+
254
+ ### 7.1 Build Tools
255
+ - **Gradle Kotlin DSL**: 2-3x faster (incremental + caching). Recommended for multi-module / complex builds.
256
+ - **Maven**: ~52% market share (2025). Simpler, more predictable. Better for conventional single-module projects.
257
+
258
+ ### 7.2 Docker
259
+ - **Buildpacks** (preferred): `./gradlew bootBuildImage` — no Dockerfile, OCI-compliant, auto-patched base images.
260
+ - **Layered Jars**: Optimize Docker layer caching when using custom Dockerfiles.
261
+
262
+ ### 7.3 CI/CD (GitHub Actions)
263
+ Setup: `actions/setup-java@v4` with `distribution: temurin`, `java-version: 21`, `cache: gradle`. Build + test + `bootBuildImage` + push to GHCR.
264
+
265
+ ### 7.4 GraalVM Native Images
266
+ Spring Boot 3+ first-class support via Spring AOT: `./gradlew nativeCompile`. Startup ~50-75ms, memory ~50-80MB. Trade-off: long builds, reflection limitations. Best for serverless / scale-to-zero.
267
+
268
+ ### 7.5 Monitoring
269
+ Actuator endpoints: `health`, `metrics`, `prometheus`. Key alerts: `jvm.memory.used`, `http.server.requests` duration, `hikaricp.connections.active`, `jvm.gc.pause`.
270
+
271
+ ---
272
+
273
+ ## 8. Decision Trees
274
+
275
+ ### 8.1 Spring MVC vs WebFlux vs Virtual Threads
276
+
277
+ ```
278
+ I/O-bound app?
279
+ ├── YES
280
+ │ ├── Need streaming / SSE / WebSocket with backpressure? → WebFlux
281
+ │ ├── Need >500K concurrent connections (gateway)? → WebFlux
282
+ │ └── Otherwise → Spring MVC + Virtual Threads (Java 21+)
283
+ └── NO (CPU-bound) → Spring MVC (traditional thread pool)
284
+ ```
285
+
286
+ Default (2025+): **MVC + virtual threads** for new projects.
287
+
288
+ ### 8.2 Gradle vs Maven
289
+
290
+ ```
291
+ Greenfield project?
292
+ ├── YES
293
+ │ ├── Multi-module / complex build logic → Gradle Kotlin DSL
294
+ │ ├── Simple single-module → Maven (simpler) or Gradle (faster)
295
+ │ └── Team has Gradle experience → Gradle
296
+ └── NO → Keep current unless build time is a measurable bottleneck
297
+ ```
298
+
299
+ ### 8.3 Monolith vs Microservices
300
+
301
+ ```
302
+ Team size?
303
+ ├── 1-3 devs / single team → Modular Monolith (Spring Modulith)
304
+ ├── 4-10 devs, 2-3 teams
305
+ │ ├── Boundaries clear and stable? → Microservices (Spring Cloud)
306
+ │ └── Boundaries unclear → Spring Modulith; extract when stable
307
+ └── 10+ devs, many teams → Microservices + service discovery + config server
308
+ + circuit breakers + distributed tracing
309
+ ```
310
+
311
+ **Key insight**: Start with modular monolith. Premature microservices are the #1 architectural mistake. Spring Modulith makes later extraction safe.
312
+
313
+ ---
314
+
315
+ ## 9. Code Examples
316
+
317
+ ### 9.1 REST Controller with Validation (Java 21+)
318
+
319
+ ```java
320
+ @RestController
321
+ @RequestMapping("/api/v1/orders")
322
+ public class OrderController {
323
+ private final OrderService orderService;
324
+ public OrderController(OrderService orderService) { this.orderService = orderService; }
325
+
326
+ @PostMapping
327
+ ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest req) {
328
+ var order = orderService.placeOrder(req.toCommand());
329
+ return ResponseEntity.created(URI.create("/api/v1/orders/" + order.id()))
330
+ .body(OrderResponse.from(order));
331
+ }
332
+
333
+ @GetMapping
334
+ Page<OrderResponse> list(@RequestParam(defaultValue = "0") int page,
335
+ @RequestParam(defaultValue = "20") int size) {
336
+ return orderService.findAll(PageRequest.of(page, size)).map(OrderResponse::from);
337
+ }
338
+ }
339
+
340
+ // DTOs as records
341
+ public record CreateOrderRequest(@NotNull @Positive Long productId, @Min(1) int quantity) {
342
+ public CreateOrderCommand toCommand() { return new CreateOrderCommand(productId, quantity); }
343
+ }
344
+ public record OrderResponse(Long id, String status, BigDecimal total, Instant createdAt) {
345
+ public static OrderResponse from(Order o) {
346
+ return new OrderResponse(o.id(), o.status().name(), o.total(), o.createdAt());
347
+ }
348
+ }
349
+ ```
350
+
351
+ ### 9.2 Domain Entity with DDD Patterns
352
+
353
+ ```java
354
+ @Entity @Table(name = "orders")
355
+ public class Order {
356
+ @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;
357
+ @Enumerated(EnumType.STRING) @Column(nullable = false) private OrderStatus status;
358
+ @Embedded private Money total;
359
+ @Column(nullable = false, updatable = false) private Instant createdAt;
360
+ @OneToMany(cascade = CascadeType.ALL, orphanRemoval = true) private List<OrderItem> items = new ArrayList<>();
361
+
362
+ protected Order() {} // JPA
363
+ public static Order create(CreateOrderCommand cmd) {
364
+ var order = new Order();
365
+ order.status = OrderStatus.PLACED;
366
+ order.createdAt = Instant.now();
367
+ order.items.addAll(cmd.items().stream().map(OrderItem::from).toList());
368
+ order.total = order.items.stream().map(OrderItem::subtotal).reduce(Money.ZERO, Money::add);
369
+ return order;
370
+ }
371
+ public void cancel() {
372
+ if (status != OrderStatus.PLACED)
373
+ throw new IllegalStateException("Cannot cancel order in status: " + status);
374
+ this.status = OrderStatus.CANCELLED;
375
+ }
376
+ // Getters only — no setters
377
+ public Long id() { return id; }
378
+ public OrderStatus status() { return status; }
379
+ public Money total() { return total; }
380
+ }
381
+ ```
382
+
383
+ ### 9.3 Type-Safe Configuration Properties
384
+
385
+ ```java
386
+ @ConfigurationProperties(prefix = "app.order-service")
387
+ @Validated
388
+ public record OrderServiceProperties(
389
+ @NotNull @DurationMin(seconds = 1) Duration paymentTimeout,
390
+ @Min(1) @Max(10) int maxRetries,
391
+ @NotBlank String notificationQueue
392
+ ) {}
393
+ ```
394
+
395
+ ### 9.4 Global Error Handler (RFC 7807)
396
+
397
+ ```java
398
+ @RestControllerAdvice
399
+ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
400
+ @ExceptionHandler(OrderNotFoundException.class)
401
+ ProblemDetail handleNotFound(OrderNotFoundException ex) {
402
+ var pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
403
+ pd.setTitle("Order Not Found");
404
+ pd.setType(URI.create("https://api.example.com/errors/order-not-found"));
405
+ pd.setProperty("orderId", ex.getOrderId());
406
+ return pd;
407
+ }
408
+ }
409
+ ```
410
+
411
+ ### 9.5 Structured Concurrency with Virtual Threads (Java 21+)
412
+
413
+ ```java
414
+ @Service
415
+ public class OrderEnrichmentService {
416
+ private final ProductClient productClient;
417
+ private final CustomerClient customerClient;
418
+
419
+ public EnrichedOrder enrich(Long orderId) throws Exception {
420
+ try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
421
+ var product = scope.fork(() -> productClient.findById(orderId));
422
+ var customer = scope.fork(() -> customerClient.findByOrderId(orderId));
423
+ scope.join().throwIfFailed();
424
+ return new EnrichedOrder(product.get(), customer.get());
425
+ }
426
+ }
427
+ }
428
+ ```
429
+
430
+ ---
431
+
432
+ *Researched: 2026-03-07 | Sources:*
433
+ - [Spring Boot Official Docs — Structuring Your Code](https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html)
434
+ - [Spring Boot Anti-Patterns (DEV.to)](https://dev.to/haraf/spring-boot-anti-patterns-killing-your-app-performance-in-2025-with-real-fixes-explanations-2p05)
435
+ - [10 Anti-Patterns That Infect Your Architecture](https://medium.com/@praveengaddam319/the-toxic-side-of-spring-boot-10-anti-patterns-that-infect-your-architecture-a771697795ef)
436
+ - [Spring Boot Testcontainers Docs](https://docs.spring.io/spring-boot/reference/testing/testcontainers.html)
437
+ - [Virtual Threads Performance Guide](https://java.elitedev.in/java/spring-boot-virtual-thread-pool-complete-performance-optimization-guide-for-java-21-263d0f04/)
438
+ - [WebFlux vs Virtual Threads Decision Matrix (2026)](https://simplifiedlearningblog.com/webflux-vs-virtual-threads-java/)
439
+ - [OAuth2 Resource Server — Spring Security Docs](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html)
440
+ - [GraalVM + Spring Boot Best Practices](https://www.javacodegeeks.com/2025/08/graalvm-and-spring-boot-best-practices-for-native-image-spring-apps.html)
441
+ - [ProblemDetail / RFC 7807 (Baeldung)](https://www.baeldung.com/spring-boot-return-errors-problemdetail)
442
+ - [OpenTelemetry with Spring Boot (Spring Blog)](https://spring.io/blog/2025/11/18/opentelemetry-with-spring-boot/)
443
+ - [Spring Modulith Event-Driven (Spring I/O 2025)](https://2025.springio.net/sessions/event-driven-architectures-with-spring-modulith-and-asyncapi/)
444
+ - [ArchUnit](https://www.archunit.org/)
445
+ - [Hexagonal Architecture, DDD, and Spring (Baeldung)](https://www.baeldung.com/hexagonal-architecture-ddd-spring)
446
+ - [Paketo Buildpacks for Spring Boot](https://github.com/paketo-buildpacks/spring-boot)
447
+ - [Maven vs Gradle 2025](https://quashbugs.com/blog/maven-vs-gradle-choosing-the-right-build-tool-for-api-heavy-backends-2025)
448
+ - [Spring Boot Observability (Voxxed Days 2026)](https://m.devoxx.com/events/vdcern26/talks/4059/spring-boot-observability-in-practice-actuator-micrometer-and-opentelemetry)