flutter-pro-skills 0.0.0-stage → 1.7.2

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 (234) hide show
  1. package/LICENSE +21 -0
  2. package/NOTICE.md +26 -0
  3. package/README.ar.md +122 -0
  4. package/README.md +268 -2
  5. package/install.sh +86 -0
  6. package/package.json +39 -4
  7. package/skills/dart-flutter-best-practices/SKILL.md +242 -0
  8. package/skills/dart-flutter-best-practices/assets/AGENTS-snippet.md +24 -0
  9. package/skills/dart-flutter-best-practices/assets/analysis_options.yaml +86 -0
  10. package/skills/dart-flutter-best-practices/references/effective-dart.md +338 -0
  11. package/skills/dart-flutter-best-practices/scripts/format-dart-hook.sh +48 -0
  12. package/skills/dart-flutter-review/SKILL.md +342 -0
  13. package/skills/dart-flutter-review/references/ci.md +212 -0
  14. package/skills/dart-flutter-review/references/finding-format.md +238 -0
  15. package/skills/dart-flutter-review/references/review-guide.md +217 -0
  16. package/skills/dart-flutter-review/references/reviewer-prompts.md +1456 -0
  17. package/skills/dart-flutter-review/scripts/ci_action.sh +81 -0
  18. package/skills/dart-flutter-review/scripts/heuristics.py +1135 -0
  19. package/skills/dart-flutter-review/scripts/review.sh +440 -0
  20. package/skills/dart-naming/SKILL.md +208 -0
  21. package/skills/dart-naming/references/naming.md +522 -0
  22. package/skills/flutter-accessibility/SKILL.md +211 -0
  23. package/skills/flutter-accessibility/references/placement-by-architecture.md +185 -0
  24. package/skills/flutter-accessibility/references/review.md +92 -0
  25. package/skills/flutter-accessibility/references/rules.md +306 -0
  26. package/skills/flutter-accessibility/references/semantics-and-labels.md +187 -0
  27. package/skills/flutter-accessibility/references/testing-accessibility.md +152 -0
  28. package/skills/flutter-accessibility/references/visual-and-input.md +148 -0
  29. package/skills/flutter-accessibility/scripts/check_accessibility.py +1411 -0
  30. package/skills/flutter-adaptive-layout/SKILL.md +239 -0
  31. package/skills/flutter-adaptive-layout/references/input-and-platform.md +221 -0
  32. package/skills/flutter-adaptive-layout/references/placement-by-architecture.md +86 -0
  33. package/skills/flutter-adaptive-layout/references/review.md +98 -0
  34. package/skills/flutter-adaptive-layout/references/rules.md +502 -0
  35. package/skills/flutter-adaptive-layout/references/size-classes-and-layout.md +326 -0
  36. package/skills/flutter-adaptive-layout/references/testing-adaptive-layouts.md +158 -0
  37. package/skills/flutter-adaptive-layout/scripts/check_adaptive.py +1743 -0
  38. package/skills/flutter-architecture/SKILL.md +276 -0
  39. package/skills/flutter-architecture/references/anti-patterns/data-and-repositories.md +264 -0
  40. package/skills/flutter-architecture/references/anti-patterns/dependency-rule.md +314 -0
  41. package/skills/flutter-architecture/references/anti-patterns/di-and-globals.md +105 -0
  42. package/skills/flutter-architecture/references/anti-patterns/over-engineering.md +140 -0
  43. package/skills/flutter-architecture/references/anti-patterns/pattern-specific.md +473 -0
  44. package/skills/flutter-architecture/references/anti-patterns/presentation.md +411 -0
  45. package/skills/flutter-architecture/references/anti-patterns/state.md +348 -0
  46. package/skills/flutter-architecture/references/anti-patterns.md +195 -0
  47. package/skills/flutter-architecture/references/bloc.md +339 -0
  48. package/skills/flutter-architecture/references/clean-architecture.md +270 -0
  49. package/skills/flutter-architecture/references/detect.md +310 -0
  50. package/skills/flutter-architecture/references/mvc.md +249 -0
  51. package/skills/flutter-architecture/references/mvn.md +377 -0
  52. package/skills/flutter-architecture/references/mvvm.md +319 -0
  53. package/skills/flutter-architecture/references/repository-pattern.md +215 -0
  54. package/skills/flutter-architecture/references/state-management.md +190 -0
  55. package/skills/flutter-architecture/scripts/arch_check.py +2546 -0
  56. package/skills/flutter-design-system/SKILL.md +208 -0
  57. package/skills/flutter-design-system/references/components-and-placement.md +240 -0
  58. package/skills/flutter-design-system/references/review.md +92 -0
  59. package/skills/flutter-design-system/references/rules.md +438 -0
  60. package/skills/flutter-design-system/references/tokens-and-theming.md +338 -0
  61. package/skills/flutter-design-system/scripts/check_design_system.py +1517 -0
  62. package/skills/flutter-error-handling/SKILL.md +190 -0
  63. package/skills/flutter-error-handling/references/error-flow-by-architecture.md +646 -0
  64. package/skills/flutter-error-handling/references/global-handlers.md +246 -0
  65. package/skills/flutter-error-handling/references/result-vs-exceptions.md +302 -0
  66. package/skills/flutter-error-handling/references/review.md +85 -0
  67. package/skills/flutter-error-handling/references/rules.md +823 -0
  68. package/skills/flutter-error-handling/scripts/check_errors.py +2005 -0
  69. package/skills/flutter-feature-scaffold/SKILL.md +219 -0
  70. package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc.dart.tmpl +44 -0
  71. package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc_test.dart.tmpl +41 -0
  72. package/skills/flutter-feature-scaffold/assets/templates/bloc/event.dart.tmpl +19 -0
  73. package/skills/flutter-feature-scaffold/assets/templates/bloc/state.dart.tmpl +37 -0
  74. package/skills/flutter-feature-scaffold/assets/templates/bloc/view.dart.tmpl +55 -0
  75. package/skills/flutter-feature-scaffold/assets/templates/bloc/view_test.dart.tmpl +29 -0
  76. package/skills/flutter-feature-scaffold/assets/templates/clean/data_source.dart.tmpl +28 -0
  77. package/skills/flutter-feature-scaffold/assets/templates/clean/dto.dart.tmpl +24 -0
  78. package/skills/flutter-feature-scaffold/assets/templates/clean/entity.dart.tmpl +18 -0
  79. package/skills/flutter-feature-scaffold/assets/templates/clean/repository.dart.tmpl +6 -0
  80. package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl.dart.tmpl +26 -0
  81. package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl_test.dart.tmpl +60 -0
  82. package/skills/flutter-feature-scaffold/assets/templates/clean/usecase.dart.tmpl +13 -0
  83. package/skills/flutter-feature-scaffold/assets/templates/clean/usecase_test.dart.tmpl +21 -0
  84. package/skills/flutter-feature-scaffold/assets/templates/core/failure.dart.tmpl +24 -0
  85. package/skills/flutter-feature-scaffold/assets/templates/core/http_client.dart.tmpl +35 -0
  86. package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit.dart.tmpl +29 -0
  87. package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit_test.dart.tmpl +41 -0
  88. package/skills/flutter-feature-scaffold/assets/templates/cubit/view.dart.tmpl +52 -0
  89. package/skills/flutter-feature-scaffold/assets/templates/getx/api_client.dart.tmpl +21 -0
  90. package/skills/flutter-feature-scaffold/assets/templates/getx/binding.dart.tmpl +19 -0
  91. package/skills/flutter-feature-scaffold/assets/templates/getx/controller.dart.tmpl +34 -0
  92. package/skills/flutter-feature-scaffold/assets/templates/getx/controller_test.dart.tmpl +42 -0
  93. package/skills/flutter-feature-scaffold/assets/templates/getx/state.dart.tmpl +31 -0
  94. package/skills/flutter-feature-scaffold/assets/templates/getx/view.dart.tmpl +38 -0
  95. package/skills/flutter-feature-scaffold/assets/templates/mvn/entity.dart.tmpl +9 -0
  96. package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier.dart.tmpl +25 -0
  97. package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier_test.dart.tmpl +56 -0
  98. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository.dart.tmpl +5 -0
  99. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl.dart.tmpl +32 -0
  100. package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl_test.dart.tmpl +58 -0
  101. package/skills/flutter-feature-scaffold/assets/templates/mvn/request.dart.tmpl +10 -0
  102. package/skills/flutter-feature-scaffold/assets/templates/mvn/response.dart.tmpl +20 -0
  103. package/skills/flutter-feature-scaffold/assets/templates/mvn/source.dart.tmpl +32 -0
  104. package/skills/flutter-feature-scaffold/assets/templates/mvn/state.dart.tmpl +28 -0
  105. package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase.dart.tmpl +19 -0
  106. package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase_test.dart.tmpl +21 -0
  107. package/skills/flutter-feature-scaffold/assets/templates/mvn/view.dart.tmpl +52 -0
  108. package/skills/flutter-feature-scaffold/assets/templates/mvn/view_test.dart.tmpl +34 -0
  109. package/skills/flutter-feature-scaffold/assets/templates/mvn/widget.dart.tmpl +19 -0
  110. package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_client.dart.tmpl +31 -0
  111. package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_model.dart.tmpl +20 -0
  112. package/skills/flutter-feature-scaffold/assets/templates/mvvm/command.dart.tmpl +66 -0
  113. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository.dart.tmpl +7 -0
  114. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl.dart.tmpl +23 -0
  115. package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl_test.dart.tmpl +54 -0
  116. package/skills/flutter-feature-scaffold/assets/templates/mvvm/result.dart.tmpl +33 -0
  117. package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase.dart.tmpl +15 -0
  118. package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase_test.dart.tmpl +22 -0
  119. package/skills/flutter-feature-scaffold/assets/templates/mvvm/view.dart.tmpl +47 -0
  120. package/skills/flutter-feature-scaffold/assets/templates/mvvm/view_test.dart.tmpl +27 -0
  121. package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel.dart.tmpl +32 -0
  122. package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel_test.dart.tmpl +64 -0
  123. package/skills/flutter-feature-scaffold/assets/templates/provider/notifier.dart.tmpl +41 -0
  124. package/skills/flutter-feature-scaffold/assets/templates/provider/notifier_test.dart.tmpl +44 -0
  125. package/skills/flutter-feature-scaffold/assets/templates/provider/state.dart.tmpl +31 -0
  126. package/skills/flutter-feature-scaffold/assets/templates/provider/view.dart.tmpl +39 -0
  127. package/skills/flutter-feature-scaffold/assets/templates/provider/view_test.dart.tmpl +30 -0
  128. package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier.dart.tmpl +23 -0
  129. package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier_test.dart.tmpl +55 -0
  130. package/skills/flutter-feature-scaffold/assets/templates/riverpod/providers.dart.tmpl +24 -0
  131. package/skills/flutter-feature-scaffold/assets/templates/riverpod/view.dart.tmpl +45 -0
  132. package/skills/flutter-feature-scaffold/assets/templates/riverpod/view_test.dart.tmpl +31 -0
  133. package/skills/flutter-feature-scaffold/assets/templates/shared/list.dart.tmpl +21 -0
  134. package/skills/flutter-feature-scaffold/assets/templates/shared/model.dart.tmpl +27 -0
  135. package/skills/flutter-feature-scaffold/assets/templates/shared/repository.dart.tmpl +6 -0
  136. package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl.dart.tmpl +25 -0
  137. package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl_test.dart.tmpl +59 -0
  138. package/skills/flutter-feature-scaffold/assets/templates/shared/source.dart.tmpl +28 -0
  139. package/skills/flutter-feature-scaffold/references/profiles.md +145 -0
  140. package/skills/flutter-feature-scaffold/scripts/scaffold.py +1069 -0
  141. package/skills/flutter-firebase/SKILL.md +256 -0
  142. package/skills/flutter-firebase/references/firestore-data.md +178 -0
  143. package/skills/flutter-firebase/references/placement-by-architecture.md +309 -0
  144. package/skills/flutter-firebase/references/review.md +109 -0
  145. package/skills/flutter-firebase/references/rules.md +636 -0
  146. package/skills/flutter-firebase/references/security-rules-and-app-check.md +226 -0
  147. package/skills/flutter-firebase/references/setup-messaging-config.md +169 -0
  148. package/skills/flutter-firebase/references/testing-firebase.md +157 -0
  149. package/skills/flutter-firebase/scripts/check_firebase.py +2155 -0
  150. package/skills/flutter-forms/SKILL.md +191 -0
  151. package/skills/flutter-forms/references/multi-step-and-dirty-state.md +190 -0
  152. package/skills/flutter-forms/references/placement-by-architecture.md +326 -0
  153. package/skills/flutter-forms/references/review.md +88 -0
  154. package/skills/flutter-forms/references/rules.md +238 -0
  155. package/skills/flutter-forms/references/secure-inputs.md +256 -0
  156. package/skills/flutter-forms/references/validation-patterns.md +285 -0
  157. package/skills/flutter-forms/scripts/check_forms.py +1278 -0
  158. package/skills/flutter-i18n/SKILL.md +241 -0
  159. package/skills/flutter-i18n/references/formatting.md +174 -0
  160. package/skills/flutter-i18n/references/gen-l10n-and-arb.md +315 -0
  161. package/skills/flutter-i18n/references/placement-by-architecture.md +460 -0
  162. package/skills/flutter-i18n/references/review.md +93 -0
  163. package/skills/flutter-i18n/references/rtl-and-arabic.md +367 -0
  164. package/skills/flutter-i18n/scripts/check_i18n.py +1805 -0
  165. package/skills/flutter-navigation/SKILL.md +199 -0
  166. package/skills/flutter-navigation/references/deep-links-and-security.md +242 -0
  167. package/skills/flutter-navigation/references/go-router-patterns.md +361 -0
  168. package/skills/flutter-navigation/references/placement-by-architecture.md +414 -0
  169. package/skills/flutter-navigation/references/review.md +102 -0
  170. package/skills/flutter-navigation/references/rules.md +256 -0
  171. package/skills/flutter-navigation/scripts/check_navigation.py +1424 -0
  172. package/skills/flutter-networking/SKILL.md +202 -0
  173. package/skills/flutter-networking/references/client-setup.md +180 -0
  174. package/skills/flutter-networking/references/dtos-and-json.md +114 -0
  175. package/skills/flutter-networking/references/placement-by-architecture.md +147 -0
  176. package/skills/flutter-networking/references/requests.md +160 -0
  177. package/skills/flutter-networking/references/review.md +94 -0
  178. package/skills/flutter-networking/references/rules.md +487 -0
  179. package/skills/flutter-networking/references/testing-with-fakes.md +137 -0
  180. package/skills/flutter-networking/scripts/check_networking.py +1607 -0
  181. package/skills/flutter-performance/SKILL.md +219 -0
  182. package/skills/flutter-performance/references/diagnosing-jank.md +134 -0
  183. package/skills/flutter-performance/references/isolates.md +105 -0
  184. package/skills/flutter-performance/references/lists-images-painting.md +116 -0
  185. package/skills/flutter-performance/references/rebuild-scope.md +154 -0
  186. package/skills/flutter-performance/references/review.md +93 -0
  187. package/skills/flutter-performance/references/rules.md +400 -0
  188. package/skills/flutter-performance/scripts/check_performance.py +1360 -0
  189. package/skills/flutter-persistence/SKILL.md +198 -0
  190. package/skills/flutter-persistence/references/caching-and-offline.md +169 -0
  191. package/skills/flutter-persistence/references/choosing-storage.md +188 -0
  192. package/skills/flutter-persistence/references/migrations.md +201 -0
  193. package/skills/flutter-persistence/references/placement-by-architecture.md +232 -0
  194. package/skills/flutter-persistence/references/review.md +93 -0
  195. package/skills/flutter-persistence/references/rules.md +405 -0
  196. package/skills/flutter-persistence/scripts/check_persistence.py +1690 -0
  197. package/skills/flutter-platform-integration/SKILL.md +219 -0
  198. package/skills/flutter-platform-integration/references/channels-and-pigeon.md +194 -0
  199. package/skills/flutter-platform-integration/references/ffi.md +147 -0
  200. package/skills/flutter-platform-integration/references/permissions-and-isolates.md +124 -0
  201. package/skills/flutter-platform-integration/references/placement-by-architecture.md +102 -0
  202. package/skills/flutter-platform-integration/references/plugins-and-platform-views.md +129 -0
  203. package/skills/flutter-platform-integration/references/review.md +94 -0
  204. package/skills/flutter-platform-integration/references/rules.md +557 -0
  205. package/skills/flutter-platform-integration/references/testing-platform-code.md +125 -0
  206. package/skills/flutter-platform-integration/scripts/check_platform.py +1824 -0
  207. package/skills/flutter-release/SKILL.md +219 -0
  208. package/skills/flutter-release/references/ci-cd.md +156 -0
  209. package/skills/flutter-release/references/flavors-and-environments.md +127 -0
  210. package/skills/flutter-release/references/release-checklist.md +79 -0
  211. package/skills/flutter-release/references/review.md +91 -0
  212. package/skills/flutter-release/references/rules.md +417 -0
  213. package/skills/flutter-release/references/signing-and-versioning.md +113 -0
  214. package/skills/flutter-release/references/store-requirements.md +61 -0
  215. package/skills/flutter-release/scripts/check_release.py +1930 -0
  216. package/skills/flutter-secure-defaults/SKILL.md +270 -0
  217. package/skills/flutter-secure-defaults/references/network-and-auth.md +203 -0
  218. package/skills/flutter-secure-defaults/references/review.md +103 -0
  219. package/skills/flutter-secure-defaults/references/rules.md +452 -0
  220. package/skills/flutter-secure-defaults/references/secrets-and-config.md +136 -0
  221. package/skills/flutter-secure-defaults/references/secure-defaults-by-layer.md +474 -0
  222. package/skills/flutter-secure-defaults/references/secure-scaffold-checklist.md +147 -0
  223. package/skills/flutter-secure-defaults/references/storage-and-privacy.md +161 -0
  224. package/skills/flutter-secure-defaults/references/webview-and-links.md +153 -0
  225. package/skills/flutter-secure-defaults/scripts/check_secure_defaults.py +1571 -0
  226. package/skills/flutter-testing/SKILL.md +197 -0
  227. package/skills/flutter-testing/references/review.md +71 -0
  228. package/skills/flutter-testing/references/strategy-by-architecture.md +491 -0
  229. package/skills/flutter-testing/references/test-smells.md +475 -0
  230. package/skills/flutter-testing/references/widget-and-golden.md +337 -0
  231. package/skills/flutter-testing/scripts/test_gaps.py +1268 -0
  232. package/skills/flutter-ui-practices/SKILL.md +158 -0
  233. package/skills/flutter-ui-practices/references/flutter-ui.md +282 -0
  234. package/skills/flutter-ui-practices/references/review.md +89 -0
@@ -0,0 +1,242 @@
1
+ ---
2
+ name: dart-flutter-best-practices
3
+ description: Hub for writing idiomatic Dart and Flutter code - Effective Dart, the official lints, the language features your SDK allows and the project's own conventions, verified with `dart format` and `dart analyze`. Use it whenever you write or refactor general Dart code, a package or CLI, ask if code is idiomatic, or set up lints, `analysis_options.yaml` or formatting. When one concern dominates, load that specialist instead - `flutter-feature-scaffold`, `dart-naming`, `flutter-ui-practices`, `flutter-performance` (jank), `flutter-architecture`, `flutter-testing`, `flutter-error-handling`, `flutter-secure-defaults`, `flutter-navigation`, `flutter-forms`, `flutter-i18n`, `flutter-persistence`, `flutter-networking`, `flutter-firebase`, `flutter-platform-integration`, `flutter-design-system`, `flutter-adaptive-layout`, `flutter-accessibility`, `flutter-release`, `dart-flutter-review` (reviews).
4
+ license: MIT
5
+ metadata:
6
+ author: abdelrahman-abied
7
+ version: "1.7.2"
8
+ suite: flutter-pro-skills
9
+ ---
10
+
11
+ # Dart & Flutter best practices (hub)
12
+
13
+ This is the entry point of the `flutter-pro-skills` suite. It holds the rules
14
+ that apply to *all* Dart code, the WRITE workflow, and team setup. It sends
15
+ everything more specific to a sibling skill, so you load only what the task
16
+ touches.
17
+
18
+ The aim is code that reads as if one careful author wrote it. That means it
19
+ agrees with the official guidance, it fits the project it lives in, and it
20
+ avoids the bugs idiomatic Dart rules out by construction (unawaited futures,
21
+ swallowed errors, `late` fields read too early).
22
+
23
+ ## Precedence when sources disagree
24
+
25
+ 1. **The project's own decisions**: its lint config, its project instructions
26
+ file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/…`,
27
+ `.github/copilot-instructions.md`), its declared architecture, and any
28
+ convention it uses consistently. Effective Dart's first theme is *be
29
+ consistent*. A "correct" rule applied to half a codebase makes it worse. If
30
+ the project disables a lint on purpose, it has decided, so don't argue
31
+ with it file by file.
32
+ 2. **The chosen pattern's canonical source**: MVN follows the `mvn` spec by its
33
+ author, Bloc follows bloclibrary.dev, Riverpod follows riverpod.dev, and
34
+ MVVM follows the docs.flutter.dev architecture guide.
35
+ 3. **Effective Dart**: the baseline for all Dart code. The full checklist is
36
+ in `references/effective-dart.md`.
37
+ 4. **Flutter team guidance for apps**, from docs.flutter.dev and `flutter_lints`.
38
+ 5. **The Flutter framework's internal style guide.** It was written for
39
+ contributors to the framework, and several of its rules contradict Effective
40
+ Dart (`kConstant` prefixes, 100-column lines). Follow it only where the
41
+ project already does.
42
+
43
+ Keep each rule at the strength of its source keyword. **DO/DON'T** means
44
+ near-always, **PREFER/AVOID** means unless there's a good reason, and
45
+ **CONSIDER** depends on context. A PREFER deviation is not a bug.
46
+
47
+ ## Route to the right skill
48
+
49
+ Load the sibling skill for the part of the task in front of you. If your agent
50
+ doesn't auto-load skills, read the fallback path, which is relative to this
51
+ skill's folder because the suite installs as sibling folders. If a sibling is
52
+ missing, say so and carry on with Effective Dart and this file.
53
+
54
+ | The task involves | Load | Fallback path |
55
+ |---|---|---|
56
+ | Naming or renaming anything: classes, methods, booleans, files, providers, blocs, events | `dart-naming` | `../dart-naming/SKILL.md` |
57
+ | Widgets, `State` lifecycle and `dispose`, `BuildContext` across `await`, `build()` cost, lists, theming, accessibility, widget tests | `flutter-ui-practices` | `../flutter-ui-practices/SKILL.md` |
58
+ | Where code belongs: layers, folders, MVVM / MVN / Bloc / Clean Architecture / repositories, state management, anti-patterns | `flutter-architecture` | `../flutter-architecture/SKILL.md` |
59
+ | Creating a new feature, screen or module in the project's own architecture (generates the files, dry run first) | `flutter-feature-scaffold` | `../flutter-feature-scaffold/SKILL.md` |
60
+ | Writing or reviewing tests, what to test per layer, untested code, flaky tests, mocks vs fakes, goldens | `flutter-testing` | `../flutter-testing/SKILL.md` |
61
+ | try/catch, exceptions vs `Result`, failures, error states, "spinner never stops", crash reporting, global handlers | `flutter-error-handling` | `../flutter-error-handling/SKILL.md` |
62
+ | Reviewing, auditing or critiquing code, a diff or a PR | `dart-flutter-review` | `../dart-flutter-review/SKILL.md` |
63
+ | Tokens, credentials, auth, storage, HTTP clients, logging of sensitive data, WebViews, "is this secure", secure defaults while writing | `flutter-secure-defaults` | `../flutter-secure-defaults/SKILL.md` |
64
+ | go_router, deep links, redirects/guards, passing route arguments, url_launcher | `flutter-navigation` | `../flutter-navigation/SKILL.md` |
65
+ | Forms, validation, TextFormField, focus, submit/double-submit, password/OTP inputs | `flutter-forms` | `../flutter-forms/SKILL.md` |
66
+ | Localization, ARB/gen-l10n, plurals, dates/numbers, RTL and Arabic | `flutter-i18n` | `../flutter-i18n/SKILL.md` |
67
+ | Jank, slow scrolling, excess rebuilds, `const`, `RepaintBoundary`, lazy lists and slivers, isolates and `compute`, image decode size, DevTools profiling | `flutter-performance` | `../flutter-performance/SKILL.md` |
68
+ | Local storage and caching: Drift, sqflite, Hive/Isar, shared_preferences, offline-first and sync, migrations | `flutter-persistence` | `../flutter-persistence/SKILL.md` |
69
+ | API calls and the HTTP client: Dio/http/retrofit setup, timeouts, interceptors, DTOs and JSON, pagination, cancellation, retry, WebSockets | `flutter-networking` | `../flutter-networking/SKILL.md` |
70
+ | Firebase: init, Auth, Firestore queries and listeners, security rules, App Check, FCM, Crashlytics, Remote Config, emulators | `flutter-firebase` | `../flutter-firebase/SKILL.md` |
71
+ | Native code: platform channels, Pigeon, FFI, platform views, writing a plugin, runtime permissions, background isolates | `flutter-platform-integration` | `../flutter-platform-integration/SKILL.md` |
72
+ | Design tokens, `ThemeData`/`ColorScheme`, `ThemeExtension`, shared components, dark mode, raw colours or sizes in feature code | `flutter-design-system` | `../flutter-design-system/SKILL.md` |
73
+ | Phones, tablets, foldables, desktop and web from one codebase: size classes and breakpoints, list-detail, navigation bar vs rail, orientation, hover/keyboard input, `dart:io Platform` on web | `flutter-adaptive-layout` | `../flutter-adaptive-layout/SKILL.md` |
74
+ | Accessibility: `Semantics`, labels, tap targets, contrast, text scale, focus order, screen-reader tests | `flutter-accessibility` | `../flutter-accessibility/SKILL.md` |
75
+ | Shipping the app: flavors and environments, signing, versioning, store requirements, CI/CD (GitHub Actions, Codemagic, Fastlane) | `flutter-release` | `../flutter-release/SKILL.md` |
76
+ | Deep security audit: obfuscation, pinning, RASP, attestation, build hardening | `flutter-security-audit` (separate repo, if installed) | `../flutter-security-audit/SKILL.md`; otherwise say it isn't installed |
77
+
78
+ Writing a Flutter feature usually touches several of these. Scaffold it in
79
+ the project's pattern, then use architecture for where the code goes, UI for
80
+ the widgets, naming for the new types, error handling for its failure paths,
81
+ and testing for its tests.
82
+
83
+ ## First: read the project
84
+
85
+ Spend a minute on these before you write a line.
86
+
87
+ - **`pubspec.yaml` and the SDK constraint.** The *lower bound* of
88
+ `environment: sdk:` sets the package's language version, and that decides
89
+ which features compile. The installed SDK doesn't decide it. Features gated
90
+ by language version:
91
+
92
+ | Feature | Needs |
93
+ |---|---|
94
+ | Records, patterns, `switch` expressions, class modifiers (`sealed`, `final`, `base`, `interface`) | ≥3.0 |
95
+ | Extension types | ≥3.3 |
96
+ | Digit separators (`1_000_000`) | ≥3.6 |
97
+ | Wildcard `_` parameters and locals; the tall formatter style; `formatter:` options in `analysis_options.yaml` | ≥3.7 |
98
+ | `formatter: trailing_commas: preserve`; null-aware elements (`[?maybeItem]`) | ≥3.8 |
99
+ | Dot shorthands (`.start`, `.new()`, `.all(8)` where the type is known) | ≥3.10 |
100
+ | Private named initializing formals (`Foo({required this._client})`, preferred over `: _client = client`) | ≥3.12 |
101
+
102
+ Also note what kind of package it is (Flutter app, Dart package or CLI) and
103
+ which state-management, DI and routing packages it depends on.
104
+ - **`analysis_options.yaml`.** Check which set is included (`flutter_lints`,
105
+ `lints/recommended`, `very_good_analysis` or custom), which rules are added
106
+ or disabled, the `formatter: page_width`, and the `exclude:` globs.
107
+ Generated code (`*.g.dart`, `*.freezed.dart`) is never yours to edit or judge.
108
+ - **The project instructions file** (see Precedence). Look for a declared
109
+ architecture line such as `Architecture: Clean + MVN`, and for
110
+ team conventions.
111
+ - **Two or three neighbouring files.** Check `var` vs `final` locals (either is
112
+ fine, but pick one), relative vs `package:` imports, feature-first vs
113
+ layer-first folders, role suffixes (`Screen`/`Page`/`View`,
114
+ `Notifier`/`ViewModel`/`Bloc`), and how errors and results are modelled.
115
+
116
+ ## WRITE mode: generating or changing code
117
+
118
+ 1. **Match before you invent.** New code should look like it belongs: use the
119
+ project's state management, folder structure and suffixes. Match its
120
+ *conventions*, not its *defects*. If the neighbouring code leaks
121
+ controllers or does I/O in widgets, don't copy that. Write the new code
122
+ correctly and mention the existing problem.
123
+ 2. **Load the sibling for what you touch** (routing table above). The
124
+ architecture skill decides *where* code goes, and the UI skill covers
125
+ lifecycle and `build()`. The naming skill applies whenever you introduce a
126
+ public name, because names are the one thing tools can't fix later without
127
+ breaking callers.
128
+ **Keep the reading budget small.** Read each needed sibling's SKILL.md,
129
+ not its `references/`: open a reference only when the SKILL.md sends you
130
+ there for the decision in front of you, and then read that section, not
131
+ the file. When `flutter-feature-scaffold` generates the feature, its
132
+ templates already pass every checker in the suite, so you don't need to
133
+ pre-load the performance, design-system, accessibility, networking or
134
+ persistence skills to write it. Check once on what you wrote with
135
+ `bash ../dart-flutter-review/scripts/review.sh <project-root> --diff HEAD --findings-only`
136
+ (every checker, only what is left to fix), and load a sibling only for a
137
+ finding you need to fix.
138
+ 3. **Write it idiomatically the first time.** Hold the code to the judgment
139
+ rules below as you write. Default lints don't catch them. Use the newest
140
+ features the SDK constraint allows when they make the code clearer, and
141
+ never use features it doesn't allow.
142
+ 4. **Verify with the toolchain, then fix only what you introduced.**
143
+ ```bash
144
+ dart format <files you touched> # respects formatter: page_width
145
+ dart analyze <files or dir> # `flutter analyze` is equivalent in a Flutter app
146
+ ```
147
+ Fix every error, warning and lint *your change* introduced. Don't reformat
148
+ or "fix" unrelated files: that buries the real change in noise and makes the
149
+ diff hard to review. If a lint must stay, write `// ignore: rule_name`
150
+ followed by the reason. An unexplained ignore is itself a finding. If
151
+ `dart` isn't available, say that you couldn't verify.
152
+ 5. **Add the tests your change needs**, even when you extend existing code
153
+ rather than scaffold a feature. That means:
154
+ - a repository or source test over a fake: the success path and each
155
+ error mapping
156
+ - a logic-holder test of its state transitions (pagination: the next page
157
+ appended, a second request dropped while one is in flight)
158
+ - one widget test per screen state
159
+
160
+ **Size the tests to the change:** for a small change (a login, one
161
+ endpoint, one widget), write one focused test per layer you touched. Write
162
+ the full set only for a new feature. Use fakes, not mocks, and no real
163
+ network or delays. The checklist is in
164
+ `flutter-feature-scaffold` (its cross-cutting rules). Load
165
+ `flutter-testing` only for something it doesn't cover.
166
+ 6. **Don't over-document.** Add `///` docs to public APIs whose names don't
167
+ say everything. Never write a comment that restates the name
168
+ (`/// The user id.` on `userId`). See *Documentation* in
169
+ `references/effective-dart.md`.
170
+ 7. **Never hand-edit generated files.** Change the source and run
171
+ `dart run build_runner build -d` (or tell the user to).
172
+
173
+ ## Dart judgment rules (no default lint catches these)
174
+
175
+ Check these by reading. Each maps to a row in `references/effective-dart.md`,
176
+ so grep it for the keyword (`late`, `FutureOr`, `getter`, `catch`) when you
177
+ want the exact guideline and its strength.
178
+
179
+ - Don't use `late` when you need to check whether the field was initialised.
180
+ Use a nullable field instead.
181
+ - Don't store what you can calculate. Use a getter, not a field that must be
182
+ kept in sync.
183
+ - Return `Future<void>`, never plain `void`, from async members that produce no
184
+ value. Avoid `FutureOr<T>` as a return type.
185
+ - Don't return a nullable `Future`, `Stream` or collection. Return an empty
186
+ one instead.
187
+ - Throw `Error` subclasses only for programmer mistakes, and `Exception`s for
188
+ runtime failures. Never catch `Error`. Don't write a bare `catch` without
189
+ `on` unless you rethrow or report the error.
190
+ - Don't create a class with only static members. Use top-level functions and
191
+ constants, or an `abstract final class` as a namespace.
192
+ - Use class modifiers (`final`, `base`, `interface`, `sealed`) to say how a
193
+ public class may be extended or implemented. Model closed sets of variants
194
+ as `sealed` with an exhaustive `switch`.
195
+ - Avoid positional `bool` parameters (`render(true)`); make them named.
196
+ - Override `hashCode` whenever you override `==`. Don't give mutable classes
197
+ value equality.
198
+ - Annotate types on public APIs and on variables without initialisers. Don't
199
+ annotate obvious locals.
200
+ - Every `Future` is awaited, returned, or wrapped in `unawaited(...)` on
201
+ purpose. A dropped future loses its error.
202
+
203
+ ## Naming and Flutter UI live in sibling skills
204
+
205
+ - Naming rules (casing, `get`/`k`/`I` prefixes, booleans, callbacks, files, role suffixes) are in `dart-naming`.
206
+ - Widget rules (dispose, `context.mounted`, pure `build()`, widget classes over helper methods, lazy lists, `MediaQuery.sizeOf`) are in `flutter-ui-practices`.
207
+ - Deep dives that widget code often needs: `flutter-performance` (jank and rebuilds), `flutter-design-system` (tokens and themes), `flutter-accessibility` (semantics, targets, contrast), `flutter-persistence` (local storage and caching).
208
+ - Architecture rules (layering, which layer may call which, per-pattern conventions) are in `flutter-architecture`.
209
+ - Review procedure, severity and report format are in `dart-flutter-review`.
210
+ - If one of these isn't installed, apply Effective Dart and say which guidance was unavailable.
211
+
212
+ ## Setup for teams
213
+
214
+ Offer these when the user wants a project to follow the conventions every
215
+ time. Don't add them silently.
216
+
217
+ - **Lint set: `assets/analysis_options.yaml`.** This is `flutter_lints` plus the
218
+ Effective Dart rules that aren't on by default, with each rule annotated by
219
+ the guideline it enforces. For a pure Dart package, change the include to
220
+ `package:lints/recommended.yaml` and drop the rules marked `[flutter]`.
221
+ Suggest it when the project has no `analysis_options.yaml` or an empty one.
222
+ `dart-flutter-review` also runs it as an informational EXTRA LINTS pass.
223
+ - **Project instructions: `assets/AGENTS-snippet.md`.** This is a short block
224
+ for `AGENTS.md`. The other agents' files (`CLAUDE.md`, `GEMINI.md`,
225
+ `.cursor/rules/`, `.github/copilot-instructions.md`) can include it or
226
+ copy it. Fill in its `Architecture:` line: reviewers judge the code against
227
+ the declared pattern rather than guessing it.
228
+ - **Format on write: `scripts/format-dart-hook.sh`** (optional). It runs
229
+ `dart format` on one edited `.dart` file and skips generated code. It never
230
+ blocks and always exits 0. It accepts a file path as `$1`, which works for
231
+ any hook system that can pass a path and for git pre-commit, or hook JSON
232
+ `{"tool_input":{"file_path":…}}` on stdin, for example a Claude Code
233
+ post-edit hook. Setup examples are in the script header.
234
+
235
+ ## Files in this skill
236
+
237
+ | File | Use it when |
238
+ |---|---|
239
+ | `references/effective-dart.md` | You're writing non-trivial Dart, or you're unsure about a guideline. It has ~150 rows, one per guideline, each tagged with the lint that enforces it or *judgment*. Grep it for a keyword, or `grep -n '^##'` to find a section, rather than reading it whole |
240
+ | `assets/analysis_options.yaml` | Setting up or tightening lints |
241
+ | `assets/AGENTS-snippet.md` | Making every agent in a repo follow these conventions |
242
+ | `scripts/format-dart-hook.sh` | Enforcing formatting automatically |
@@ -0,0 +1,24 @@
1
+ ## Dart / Flutter conventions
2
+
3
+ <!-- Paste this block into the repo's AGENTS.md. Agents that read another file
4
+ can include or copy it: CLAUDE.md (a line `@AGENTS.md` imports it),
5
+ GEMINI.md, .cursor/rules/*.mdc, .github/copilot-instructions.md.
6
+ It's loaded on every task, so keep it short; the flutter-pro-skills
7
+ skills carry the detail. Edit the [bracketed] parts and delete the rest. -->
8
+
9
+ - Follow Effective Dart and this repo's `analysis_options.yaml`. When writing or
10
+ reviewing Dart, use the `dart-flutter-best-practices` skill (it routes to
11
+ `dart-naming`, `flutter-ui-practices`, `flutter-architecture` and
12
+ `dart-flutter-review`).
13
+ - Architecture: [Clean + MVN | MVVM (Flutter guide) | Bloc + Clean | Provider | MVC | GetX]
14
+ (see the `flutter-architecture` skill). Reviewers judge the code against this
15
+ declared pattern, not a guessed one.
16
+ - Layout: [feature-first `lib/features/<name>/{domain,data,presentation}` | layer-first].
17
+ Role suffixes: [`XView`, `XNotifier`, `XState`, `XUseCase`, `XRepository`/`XRepositoryImpl`].
18
+ - Locals: [`final` unless reassigned | `var` everywhere]. Imports: [relative inside lib/ | `package:` only].
19
+ - Constants: lowerCamelCase (`defaultPadding`), no `k` prefix. [Delete this line if the repo uses `kFoo`.]
20
+ - Before saying a change is done, run `dart format <changed files>` and
21
+ `flutter analyze` (or `dart analyze`) with zero new issues. Never add
22
+ `// ignore:` without a reason comment.
23
+ - Never edit generated files (`*.g.dart`, `*.freezed.dart`). Change the
24
+ source and run `dart run build_runner build -d`.
@@ -0,0 +1,86 @@
1
+ # Recommended analysis_options.yaml: Effective Dart + Flutter team lints.
2
+ #
3
+ # Base: package:flutter_lints (includes package:lints/recommended + core).
4
+ # For a pure Dart package or CLI, replace the include with
5
+ # include: package:lints/recommended.yaml
6
+ # and drop the Flutter-only rules marked [flutter].
7
+ #
8
+ # Every rule below is stable in the Dart linter registry and maps to an Effective
9
+ # Dart guideline or a Flutter team recommendation. Comments name the guideline.
10
+ # Delete anything your team disagrees with. Consistency matters more than any
11
+ # single rule.
12
+
13
+ include: package:flutter_lints/flutter.yaml
14
+
15
+ formatter:
16
+ page_width: 80 # Effective Dart: PREFER lines 80 characters or fewer (Dart >= 3.7)
17
+ # trailing_commas: preserve # opt-in manual control over splitting (Dart >= 3.8)
18
+
19
+ analyzer:
20
+ exclude:
21
+ - "**/*.g.dart"
22
+ - "**/*.freezed.dart"
23
+ - "**/*.gr.dart"
24
+ - "**/*.mocks.dart"
25
+ - "lib/generated/**"
26
+ language:
27
+ strict-casts: true # no implicit downcasts from dynamic
28
+ strict-inference: true # Effective Dart: DO annotate with dynamic instead of letting inference fail
29
+ strict-raw-types: true # Effective Dart: AVOID writing incomplete generic types
30
+ errors:
31
+ # Promote the bug-catching ones so they can't be ignored.
32
+ use_build_context_synchronously: error
33
+ cancel_subscriptions: warning
34
+ close_sinks: warning
35
+ unawaited_futures: warning
36
+
37
+ linter:
38
+ rules:
39
+ # --- Style: ordering & formatting ---
40
+ - directives_ordering # dart: → package: → relative; exports last; alphabetical
41
+ - prefer_relative_imports # Usage: PREFER relative import paths (within lib/)
42
+ # (incompatible with always_use_package_imports; pick one)
43
+
44
+ # --- Documentation ---
45
+ - comment_references # DO use [square brackets] for in-scope identifiers
46
+ # - public_member_api_docs # PREFER doc comments for public APIs (enable for published packages)
47
+
48
+ # --- Usage ---
49
+ - unnecessary_lambdas # DON'T create a lambda when a tear-off will do
50
+ - prefer_final_locals # DO follow a consistent var/final rule (this picks "final if not reassigned")
51
+ - prefer_final_in_for_each
52
+ - avoid_catching_errors # DON'T explicitly catch Error
53
+ - only_throw_errors # throw Error/Exception subtypes, never strings
54
+ - unawaited_futures # every Future is awaited or explicitly unawaited()
55
+ - avoid_void_async # DO use Future<void> for async members with no value
56
+ - cancel_subscriptions # lifecycle: StreamSubscription must be cancelled
57
+ - close_sinks # lifecycle: sinks/StreamControllers must be closed
58
+ - use_string_buffers # perf: StringBuffer in loops
59
+ - avoid_slow_async_io
60
+ # - avoid_catches_without_on_clauses # AVOID catches without `on` (strict; noisy in app code)
61
+ # - prefer_expression_function_bodies # CONSIDER => for simple members (noisy)
62
+
63
+ # --- Design ---
64
+ - always_declare_return_types # DO annotate return types on function declarations
65
+ - type_annotate_public_apis # DO type annotate fields/top-levels if not obvious
66
+ - omit_local_variable_types # DON'T redundantly type annotate initialized locals
67
+ - avoid_types_on_closure_parameters # DON'T annotate inferred params on function expressions
68
+ - avoid_positional_boolean_parameters # AVOID positional boolean parameters
69
+ - use_to_and_as_if_applicable # PREFER to___() / as___() naming
70
+ - avoid_returning_this # AVOID returning this for fluent interfaces (use cascades)
71
+ - avoid_setters_without_getters # DON'T define a setter without a getter
72
+ - use_setters_to_change_properties
73
+ - avoid_classes_with_only_static_members
74
+ - avoid_equals_and_hash_code_on_mutable_classes
75
+ - avoid_dynamic_calls # AVOID dynamic unless you want to disable static checking
76
+ - prefer_mixin # PREFER pure mixin / pure class over mixin class
77
+ - use_enums
78
+ - avoid_unused_constructor_parameters
79
+
80
+ # --- Flutter [flutter] ---
81
+ - use_colored_box
82
+ - use_decorated_box
83
+ - sized_box_shrink_expand
84
+ - avoid_redundant_argument_values
85
+ # - prefer_const_constructors # removed from flutter_lints 5 as noisy; enable if your team wants it
86
+ # - prefer_const_literals_to_create_immutables