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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Abdulrahman Obaid
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE.md ADDED
@@ -0,0 +1,26 @@
1
+ # Notices and attribution
2
+
3
+ The skills in this repository are original work by Abdulrahman Obaid, released
4
+ under the MIT License (see `LICENSE`). Parts of them summarise, quote or adapt
5
+ third-party documentation, which remains under its own license. Changes were
6
+ made in every case: guidelines were condensed, reorganised into checklists,
7
+ mapped to analyzer rules, and annotated.
8
+
9
+ | Source | Used in | License |
10
+ |---|---|---|
11
+ | **Effective Dart**, https://dart.dev/effective-dart (dart-lang/site-www), © the Dart project authors | `skills/dart-flutter-best-practices/references/effective-dart.md` (guideline headings quoted verbatim), `skills/dart-naming/` | Content: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Code samples: BSD-3-Clause |
12
+ | **Dart linter rule registry**, dart-lang/site-www `src/data/linter_rules.json` | lint ↔ guideline mapping, `assets/analysis_options.yaml` | CC BY 4.0 / BSD-3-Clause |
13
+ | **Flutter documentation**: app architecture guide, case study, recommendations, design patterns, performance best practices, accessibility, theming and persistence cookbook. https://docs.flutter.dev (flutter/website), © the Flutter project authors | `skills/flutter-architecture/`, `skills/flutter-ui-practices/`, `skills/flutter-performance/`, `skills/flutter-persistence/`, `skills/flutter-design-system/`, `skills/flutter-accessibility/` | Content: [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/) (as stated in the flutter/website LICENSE). Code samples: BSD |
14
+ | **Flutter style guide** (flutter/flutter `docs/contributing/Style-guide-for-Flutter-repo.md`) | `skills/dart-naming/`, `skills/flutter-ui-practices/` | BSD-3-Clause |
15
+ | **flutter_lints / lints** rule sets (flutter/packages, dart-lang/core) | `assets/analysis_options.yaml` | BSD-3-Clause |
16
+ | **Bloc documentation**: architecture, naming conventions, modeling state. https://bloclibrary.dev (felangel/bloc) | `skills/flutter-architecture/references/bloc.md`, `skills/dart-naming/` | MIT |
17
+ | **Riverpod documentation**: DO/DON'T. https://riverpod.dev (rrousselGit/riverpod) | `skills/flutter-architecture/references/state-management.md` | MIT |
18
+ | **MVN (Model-View-Notifier)** pattern, by Abdulrahman Abied: https://abdelrahman-abied.github.io/mvn-architecture-pattern | `skills/flutter-architecture/references/mvn.md`, `skills/dart-naming/` | Author's own work |
19
+ | **Agent Skills specification**: https://agentskills.io | skill format, `tests/validate_skills.py` (implements the published constraints; no text copied) | see agentskills.io |
20
+
21
+ Clean Architecture (Robert C. Martin), the Repository pattern (Martin Fowler,
22
+ *Patterns of Enterprise Application Architecture*) and MVC/MVVM are described
23
+ in our own words from widely published sources. No text is copied.
24
+
25
+ Trademarks (Dart, Flutter, and the names of coding agents) belong to their
26
+ owners. Mentioning an agent doesn't imply endorsement.
package/README.ar.md ADDED
@@ -0,0 +1,122 @@
1
+ <div dir="rtl">
2
+
3
+ # flutter-pro-skills
4
+
5
+ **مجموعة Agent Skills بتخلّي أي AI agent يكتب ويراجع كود Flutter نضيف وآمن من الأول (clean and secure by default)، وبيحكم على الكود حسب معمارية مشروعك إنت.**
6
+
7
+ [English](README.md) · [الترخيص MIT](LICENSE)
8
+
9
+ ## ليه الريبو ده؟
10
+
11
+ - **أمان وقت الكتابة، مش بعد ما المشكلة تحصل.** طلبنا من agent: "ضيف login واحفظ الـ token".
12
+ - **من غير الـ skills:** حفظ الـ token في `SharedPreferences` في المرتين.
13
+ - **بالـ skills:** استخدم `flutter_secure_storage` في المرتين، ومن غير ولا مشكلة أمان.
14
+
15
+ ([تفاصيل الـ benchmark](bench/README.md))
16
+ - **بيحكم بمعماريتك إنت.** الـ skills بتكتشف لوحدها مشروعك ماشي بأنهي معمارية: MVVM، و MVN، و Bloc/Cubit، و MVC، و GetX، و Provider، و Riverpod، و Clean Architecture. وبعدها بتطبّق قواعد المعمارية دي بس. ده مهم لأن المعماريات بتختلف فعلًا:
17
+ - في MVVM مسموح للـ ViewModel يكلّم الـ Repository على طول.
18
+ - في MVN لازم الـ Notifier يعدّي على Use Case.
19
+ - في Bloc ممنوع bloc يكلّم bloc تاني.
20
+
21
+ أي أداة بتفرض stack واحد هتطلّع لك أخطاء مش حقيقية.
22
+ - **أدوات فحص حقيقية، مش بس كلام.**
23
+ - 17 checker بيقروا الكود من غير ما يعدّلوا فيه حاجة: المعمارية، والأخطاء، والتستات، والأمان، والتنقّل، والـ forms، والترجمة والـ RTL، والأداء، والتخزين المحلي، والـ networking، و Firebase (ومعاه الـ security rules)، والكود الـ native، والـ design system، والـ adaptive layout، والـ accessibility، والـ release، والـ review.
24
+ - مكتوبين بـ Python من غير أي مكتبات خارجية، وعليهم حوالي 2250 تست.
25
+ - اتجرّبوا على تطبيقات مفتوحة المصدر حقيقية، زي Compass الرسمي من فريق Flutter، وأمثلة Bloc و Riverpod الرسمية، و lichess، و immich، و Wonderous، وأمثلة drift.
26
+ - **GitHub Action بيقفل الـ PR على المشاكل الجديدة بس،** فالمشاكل القديمة في المشروع متعطّلش الفريق.
27
+ - **شغالة مع أي agent بيقرأ `SKILL.md`:** Claude Code، و Codex، و Cursor، و GitHub Copilot، و Gemini CLI، و OpenCode. اتجربت فعلًا على Claude Code و OpenCode.
28
+
29
+ ## التثبيت
30
+
31
+ </div>
32
+
33
+ ```bash
34
+ npx skills add abdelrahman-abied/flutter-pro-skills
35
+ ```
36
+
37
+ <div dir="rtl">
38
+
39
+ أو:
40
+
41
+ </div>
42
+
43
+ ```bash
44
+ npx flutter-pro-skills
45
+ ```
46
+
47
+ <div dir="rtl">
48
+
49
+ أو من نسخة محلية من الريبو:
50
+
51
+ </div>
52
+
53
+ ```bash
54
+ git clone https://github.com/abdelrahman-abied/flutter-pro-skills
55
+ cd flutter-pro-skills && ./install.sh
56
+ ```
57
+
58
+ <div dir="rtl">
59
+
60
+ وبعد كده كلّم الـ agent عادي بالعربي أو بالإنجليزي:
61
+ - *"اعمل feature للطلبات"*
62
+ - *"راجع الـ PR بتاعي"*
63
+ - *"هل الـ structure بتاعنا صح؟ إحنا شغالين Clean + MVN"*
64
+ - *"احفظ الـ token بشكل آمن"*
65
+ - *"إيه اللي ملوش تستات؟"*
66
+ - *"راجع الترجمة العربية والـ RTL"*
67
+ - *"الليستة دي بتقطّع ليه؟"*
68
+ - *"ضيف dark mode بالـ design tokens بتاعتنا"*
69
+ - *"الشاشة دي شغالة مع TalkBack؟"*
70
+
71
+ الـ agent بيختار الـ skill المناسبة لوحده.
72
+
73
+ ## الـ 21 skill
74
+
75
+ | الـ skill | بتعمل إيه |
76
+ |---|---|
77
+ | `dart-flutter-best-practices` | المدخل الرئيسي: كتابة كود Dart سليم على أسلوب مشروعك، و 149 قاعدة من Effective Dart |
78
+ | `flutter-architecture` | بتكتشف معماريتك وبتحكم بقواعدها (28 قاعدة أوتوماتيك و 28 anti-pattern) |
79
+ | `flutter-feature-scaffold` | بتعمل feature جديدة كاملة بمعماريتك، **آمنة من الأول**، ومش بتكتب فوق أي ملف موجود |
80
+ | `flutter-secure-defaults` | الأمان في كل طبقة: الـ tokens في secure storage، والـ auth في interceptor، و HTTPS بس، ومفيش secrets في الكود ولا بيانات شخصية في الـ logs |
81
+ | `flutter-error-handling` | الأخطاء ماشية صح بين الطبقات، و `Result` ولا exceptions، ومفيش spinner بيلف على طول |
82
+ | `flutter-testing` | تختبر إيه الأول حسب معماريتك، و test smells، والأجزاء اللي ملهاش تستات |
83
+ | `flutter-navigation` | go_router، والـ guards، و validation للـ deep links |
84
+ | `flutter-forms` | الـ validation، وحقول الباسورد والـ OTP، والحماية من الضغط مرتين |
85
+ | `flutter-i18n` | ملفات الترجمة، **صيغ الجمع العربي**، والـ RTL، والأيقونات اللي لازم تنعكس |
86
+ | `flutter-performance` | الـ rebuilds حسب معماريتك، و `const`، و `RepaintBoundary`، والليستات الـ lazy والـ slivers، والـ isolates، وحجم الصور، وتشخيص التقطيع بـ DevTools |
87
+ | `flutter-persistence` | Drift و sqflite و Hive و shared_preferences، والـ caching، والـ offline-first والـ sync، والـ migrations، وكلها ورا الـ repository. والـ SQL بـ parameters بس |
88
+ | `flutter-networking` | طبقة الـ API حسب معماريتك: client واحد متظبّط (Dio أو http) بـ timeouts، و DTOs و JSON متأكد منه، وحماية الـ pagination من الطلب المكرر، والـ cancellation، والـ retry للطلبات الآمنة بس، والـ WebSockets، و fake clients في التستات |
89
+ | `flutter-firebase` | Firebase كـ data source ورا الـ repository: ترتيب الـ init، و queries ليها limit، و listeners بتتقفل، و security rules عمرها ما تفضل في test mode، و App Check، و FCM background handler صح، ومفيش secrets في Remote Config، والـ emulators في الـ debug بس |
90
+ | `flutter-platform-integration` | الكود الـ native كـ data source: الـ platform channels والـ Pigeon، والـ FFI من غير memory leaks، والـ platform views، وكتابة plugin، والـ permissions وقت ما تحتاجها، والـ background isolates |
91
+ | `flutter-design-system` | الـ tokens، و `ThemeData` و `ColorScheme`، و `ThemeExtension`، وطبقة components، والـ dark mode، ومفيش ألوان أو مقاسات مكتوبة على طول في الـ features |
92
+ | `flutter-adaptive-layout` | كود واحد شغال على الموبايل والتابلت والـ foldables والـ desktop والويب: breakpoints موحّدة، و list-detail، و bar أو rail حسب العرض، ومفيش قفل للـ orientation، و hover و keyboard، ومفيش crash من `dart:io Platform` على الويب |
93
+ | `flutter-accessibility` | `Semantics` والـ labels، وحجم الـ tap targets، والـ contrast، وتكبير الخط، وترتيب الـ focus، وتستات الـ screen reader. ومفيش أسرار بتتقري بصوت عالي |
94
+ | `flutter-release` | النشر: الـ flavors والـ environments بتتحدد في مكان واحد، والـ signing بره الـ git، والـ versioning، ومتطلبات المتاجر، و CI/CD آمن (مفيش secrets في الـ logs ولا ثغرات `pull_request_target`) |
95
+ | `flutter-ui-practices` | الـ dispose، و `context` بعد `await`، وتكلفة الـ build، والـ keys |
96
+ | `dart-naming` | قواعد التسمية، وأسماء كل دور في كل معمارية |
97
+ | `dart-flutter-review` | **review كامل** بـ agents شغالين بالتوازي، وتقرير واحد مرتّب حسب الخطورة |
98
+
99
+ ولو عايز فحص أمان عميق قبل النشر على المتجر (obfuscation، و pinning، و RASP)، ثبّت معاها [flutter-security-audit](https://github.com/abdelrahman-abied/flutter-security-audit).
100
+
101
+ ## نتايج الـ benchmark (بصراحة)
102
+
103
+ **أهم نتيجة (Claude Code، v1.7.0):** لما طلبنا "ضيف login واحفظ الـ token"، **Opus من غير الـ skills حفظه في `SharedPreferences` العادي في المرتين** (ثغرة SEC-001). أما **Sonnet بالـ skills فحفظه في `flutter_secure_storage` في المرتين، ومن غير ولا مشكلة أمان**. وفي مهمة شاشة المنتجات، Sonnet بالـ skills كان قد Opus بالظبط (0 مشاكل) وبنفس التكلفة تقريبًا.
104
+
105
+ | المهمة | من غير skills | بالـ skills |
106
+ |---|---|---|
107
+ | كتابة login وحفظ الـ token | `SharedPreferences` ❌ | `flutter_secure_storage` ✅ |
108
+ | review لـ 12 مشكلة مزروعة | 92%. واتعادت على v1.6.1: ‏10/12 و 12/12 في 10–15 دقيقة | 96%، ومن غير أي إنذار غلط على MVN. واتعادت على v1.6.1: **12/12 في المرتين**، بس ادعاءات زيادة ضعف ووقت 30–45 دقيقة |
109
+ | الحكم على معمارية Bloc | 2/2، وواحد أو اتنين ادعاءات بتخالف bloclibrary | 2/2، و**0** ادعاءات بتخالف bloclibrary على v1.6.1 |
110
+ | كتابة شاشة ليستة (T4، اتعادت 18 أكتوبر) | مرة من مرتين ضاف مخالفة معمارية و catch بيبلع الخطأ | 0 مشاكل جديدة في المرتين؛ ومرة صلّح مشاكل قديمة كمان. الفرق صغير على الموديل ده |
111
+
112
+ على Claude Code (Opus) الكود طلع نضيف في الحالتين، و 0 مشاكل من الـ checkers. الـ skills زوّدت التستات (37–43 مقابل 0–12 لكل run) بتكلفة 3–4 أضعاف تقريبًا، والـ review جاب 12/12 في الحالتين وبقى في نفس الوقت تقريبًا. واتعادت T3 في 18 أكتوبر وطلعت نفس النتيجة (من غير skills: الـ token في `SharedPreferences` في المرتين). العينة صغيرة (مرتين لكل مهمة، وموديل واحد مجاني)، والتفاصيل كلها في [bench/README.md](bench/README.md).
113
+
114
+ ## المساهمة
115
+
116
+ **أهم مساهمة ممكن تعملها هي إنك تبلّغ عن false positive،** يعني الأداة قالت إن فيه مشكلة وهي مش مشكلة. فيه نموذج جاهز لده في الـ issues. اقرأ [CONTRIBUTING.md](CONTRIBUTING.md).
117
+
118
+ ## الترخيص
119
+
120
+ MIT، © 2026 Abdulrahman Obaid. نمط MVN (Model-View-Notifier) من تأليف Abdulrahman Abied.
121
+
122
+ </div>
package/README.md CHANGED
@@ -1,3 +1,269 @@
1
- # Temporary Holding Version
1
+ # flutter-pro-skills
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Agent Skills that make any AI coding agent write and review Flutter code
4
+ that is clean and secure by default, judged by your app's own architecture.**
5
+
6
+ > مهارات تخلّي أي AI agent يكتب ويراجع كود Flutter نضيف وآمن من الأول، وعلى نفس معمارية مشروعك. · [اقرأ بالعربي](README.ar.md)
7
+
8
+ [![tests](https://github.com/abdelrahman-abied/flutter-pro-skills/actions/workflows/test.yml/badge.svg)](https://github.com/abdelrahman-abied/flutter-pro-skills/actions/workflows/test.yml)
9
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
10
+ [![Agent Skills](https://img.shields.io/badge/format-agentskills.io-8A2BE2)](https://agentskills.io)
11
+
12
+ <p align="center">
13
+ <img src="docs/assets/arch-compare.svg" alt="The same code judged differently per architecture: a view model calling a repository is OK in MVVM and Bloc but ARCH-012 in MVN; bloc-to-bloc is ARCH-010 in Bloc while notifier-to-notifier via ref.watch is OK in MVN" width="860">
14
+ </p>
15
+
16
+ ## Why this suite
17
+
18
+ - **Secure by default while writing, not after an audit.** In our benchmark,
19
+ agents asked to "add login and store the token":
20
+ - with the skills: both runs used `flutter_secure_storage`, with 0 security
21
+ findings
22
+ - without the skills: both runs stored the token in `SharedPreferences`
23
+ - see [the benchmark](bench/README.md)
24
+ - **Judged by *your* architecture.** The suite detects MVVM, MVN, Bloc/Cubit,
25
+ MVC, GetX, Provider, Riverpod and Clean Architecture, then applies only that
26
+ pattern's rules. The patterns really do disagree: MVVM view models may call
27
+ repositories, MVN notifiers go through use cases, and Bloc forbids
28
+ bloc→bloc. Other packs pick one stack and flag everything else.
29
+ - **Real checkers, not just prose.**
30
+ - Seventeen read-only checkers: architecture (import graph), error
31
+ handling, test gaps, security defaults, navigation, forms, i18n/RTL,
32
+ performance, persistence, networking, Firebase (incl. security rules),
33
+ platform integration, design system, adaptive layout, accessibility,
34
+ release (flavors, signing, store, CI), and review heuristics.
35
+ - All of them use stdlib Python and have about 2,250 regression tests.
36
+ - They are calibrated on real open-source apps: Flutter's Compass sample,
37
+ the bloc and riverpod examples, lichess, immich, Wonderous, the drift
38
+ examples and others.
39
+ - **A CI gate that fails PRs only on *new* violations,** so legacy code never
40
+ blocks adoption.
41
+ - **Works with any agent that reads `SKILL.md`:** Claude Code, Codex, Cursor,
42
+ GitHub Copilot, Gemini CLI, OpenCode and Antigravity. Verified on Claude
43
+ Code and OpenCode.
44
+
45
+ ## Quick start
46
+
47
+ ```bash
48
+ npx skills add abdelrahman-abied/flutter-pro-skills # open skills CLI, 70+ agents
49
+ ```
50
+
51
+ Or use the installer, which needs bash and writes to `~/.agents/skills` (Codex,
52
+ Gemini CLI, Copilot, Cursor, OpenCode, Antigravity) and `~/.claude/skills`
53
+ (Claude Code):
54
+
55
+ ```bash
56
+ npx flutter-pro-skills # --project path/to/app · --agent claude · --uninstall
57
+ ```
58
+
59
+ Contributors can run it from a clone, where `--link` makes edits go live:
60
+
61
+ ```bash
62
+ git clone https://github.com/abdelrahman-abied/flutter-pro-skills
63
+ cd flutter-pro-skills && ./install.sh --link
64
+ ```
65
+
66
+ Then just ask:
67
+ - *"Add a checkout feature."*
68
+ - *"Review my PR against main."*
69
+ - *"Is our structure right? We use Clean + MVN."*
70
+ - *"Store the auth token securely."*
71
+ - *"Find untested code."*
72
+ - *"Why does this list jank?"*
73
+ - *"Add dark mode with our design tokens."*
74
+ - *"Is this screen usable with TalkBack?"*
75
+ - *"Why does the spinner never stop?"*
76
+ - *"راجع الترجمة العربية والـ RTL."* ("Review the Arabic translation and the RTL.")
77
+
78
+ ## The skills
79
+
80
+ | Skill | What it does | Checker |
81
+ |---|---|---|
82
+ | [`dart-flutter-best-practices`](skills/dart-flutter-best-practices/SKILL.md) | **Entry point.** Writing code: read the project, follow its conventions, verify with `dart format`/`dart analyze`. Effective Dart (149 guidelines mapped to lints), recommended lint set | — |
83
+ | [`flutter-architecture`](skills/flutter-architecture/SKILL.md) | Detects the pattern and judges by its rules. 28 automated rules and 28 documented anti-patterns | `arch_check.py` |
84
+ | [`flutter-feature-scaffold`](skills/flutter-feature-scaffold/SKILL.md) | New feature in **your** pattern (MVN, MVVM, Bloc, Cubit, GetX, Provider, Riverpod; ± Clean). **Secure by default**, compile-tested, never overwrites | `scaffold.py` |
85
+ | [`flutter-secure-defaults`](skills/flutter-secure-defaults/SKILL.md) | Security per layer: tokens in secure storage, auth in interceptors, HTTPS, no secrets in source, no PII in logs, safe WebViews | `check_secure_defaults.py` |
86
+ | [`flutter-error-handling`](skills/flutter-error-handling/SKILL.md) | Error flow through your architecture, `Result` vs exceptions, global handlers, no stuck spinners | `check_errors.py` |
87
+ | [`flutter-testing`](skills/flutter-testing/SKILL.md) | What to test first per architecture, test smells, untested units ranked | `test_gaps.py` |
88
+ | [`flutter-navigation`](skills/flutter-navigation/SKILL.md) | go_router, guards, deep-link validation, navigation placement per pattern | `check_navigation.py` |
89
+ | [`flutter-forms`](skills/flutter-forms/SKILL.md) | Validation, form state per pattern, password/OTP inputs, double-submit | `check_forms.py` |
90
+ | [`flutter-i18n`](skills/flutter-i18n/SKILL.md) | gen-l10n/ARB parity, Arabic plural forms, RTL layout and mirrored icons, formatting | `check_i18n.py` |
91
+ | [`flutter-performance`](skills/flutter-performance/SKILL.md) | Rebuild scope per pattern, `const`, `RepaintBoundary`, lazy lists and slivers, isolates, image decode size, jank diagnosis in DevTools | `check_performance.py` |
92
+ | [`flutter-persistence`](skills/flutter-persistence/SKILL.md) | Drift, sqflite, Hive, shared_preferences, caching, offline-first and sync, migrations, placed behind your repositories. Parameterised SQL only | `check_persistence.py` |
93
+ | [`flutter-networking`](skills/flutter-networking/SKILL.md) | The API client layer per architecture: one configured Dio/http client with timeouts, DTOs and validated JSON, pagination guards, cancellation, idempotent-only retry, WebSockets, fake clients in tests | `check_networking.py` |
94
+ | [`flutter-firebase`](skills/flutter-firebase/SKILL.md) | Firebase as a data source behind your repositories: init order, bounded Firestore queries and cancelled listeners, security rules never left in test mode, App Check, FCM background handlers, no secrets in Remote Config, emulators only in debug | `check_firebase.py` |
95
+ | [`flutter-platform-integration`](skills/flutter-platform-integration/SKILL.md) | Native code as a data source: platform channels and Pigeon, FFI with freed memory, platform views, writing plugins, permissions at the moment of use, background isolates | `check_platform.py` |
96
+ | [`flutter-design-system`](skills/flutter-design-system/SKILL.md) | Tokens, `ThemeData`/`ColorScheme`, `ThemeExtension`, a component layer, dark mode, no raw colours or sizes in features | `check_design_system.py` |
97
+ | [`flutter-adaptive-layout`](skills/flutter-adaptive-layout/SKILL.md) | One codebase on phones, tablets, foldables, desktop and web: shared size classes, list-detail, bar vs rail, no orientation locks, hover and keyboard input, no `dart:io Platform` crashes on web | `check_adaptive.py` |
98
+ | [`flutter-accessibility`](skills/flutter-accessibility/SKILL.md) | `Semantics` and labels, tap targets, WCAG contrast, text scale, focus order, screen-reader tests. No secrets read aloud | `check_accessibility.py` |
99
+ | [`flutter-release`](skills/flutter-release/SKILL.md) | Shipping the app: flavors and environments injected at the root, signing kept out of git, versioning, store requirements, safe CI/CD (no secrets in logs, no `pull_request_target` holes) | `check_release.py` |
100
+ | [`flutter-ui-practices`](skills/flutter-ui-practices/SKILL.md) | Lifecycle and `dispose`, `context` after `await`, build cost, lists, keys | (review heuristics) |
101
+ | [`dart-naming`](skills/dart-naming/SKILL.md) | Effective Dart naming plus role names per architecture | — |
102
+ | [`dart-flutter-review`](skills/dart-flutter-review/SKILL.md) | **Review orchestrator.** Every checker, then parallel reviewer sub-agents, verified Highs, one deduplicated report, CI mode | `review.sh` |
103
+
104
+ For deep release audits (obfuscation, pinning, RASP, attestation), install the
105
+ companion skill [flutter-security-audit](https://github.com/abdelrahman-abied/flutter-security-audit).
106
+ The review runs its `scan.sh` automatically when it is installed.
107
+
108
+ ### Which skill answers my question?
109
+
110
+ | You ask | Skill |
111
+ |---|---|
112
+ | "Create a new feature / screen / module" | `flutter-feature-scaffold` |
113
+ | "Is our architecture OK?", "where should this code go?" | `flutter-architecture` |
114
+ | "Store the token", "add login", "is this secure?" | `flutter-secure-defaults` |
115
+ | "Errors aren't shown", "app crashes", "Result or exceptions?" | `flutter-error-handling` |
116
+ | "What should I test?", "flaky tests" | `flutter-testing` |
117
+ | "go_router guards", "deep links" | `flutter-navigation` |
118
+ | "Validation", "login form", "double submit" | `flutter-forms` |
119
+ | "Translate", "Arabic", "RTL", "hardcoded strings" | `flutter-i18n` |
120
+ | "Memory leak", "setState after dispose" | `flutter-ui-practices` |
121
+ | "Jank", "slow list", "too many rebuilds", "compute / isolate" | `flutter-performance` |
122
+ | "Cache this offline", "Drift migration", "Hive or SQLite?" | `flutter-persistence` |
123
+ | "Set up Dio", "infinite scroll", "retry", "parse this JSON" | `flutter-networking` |
124
+ | "Add flavors", "sign the release", "publish to the Play Store", "release workflow" | `flutter-release` |
125
+ | "Add Firebase", "Firestore rules", "FCM", "Crashlytics", "Remote Config" | `flutter-firebase` |
126
+ | "Call native code", "MethodChannel", "Pigeon", "FFI", "write a plugin", "ask for permission" | `flutter-platform-integration` |
127
+ | "Dark mode", "design tokens", "ThemeExtension", "hard-coded colours" | `flutter-design-system` |
128
+ | "Tablet layout", "make it responsive", "desktop/web support", "breakpoints" | `flutter-adaptive-layout` |
129
+ | "Screen reader", "TalkBack/VoiceOver", "contrast", "tap target" | `flutter-accessibility` |
130
+ | "What should I call this?" | `dart-naming` |
131
+ | "Review my PR / codebase" | `dart-flutter-review` |
132
+ | "Write / refactor this", "set up lints" | `dart-flutter-best-practices` |
133
+
134
+ Agents pick the right skill from its description. To force one:
135
+
136
+ | Agent | How to force a skill |
137
+ |---|---|
138
+ | Claude Code, Cursor | `/dart-flutter-review` |
139
+ | Codex | `$dart-flutter-review` |
140
+ | Gemini CLI, Copilot, OpenCode | name it: *"use the dart-flutter-review skill"* |
141
+
142
+ ---
143
+
144
+ ## See it work
145
+
146
+ <p align="center">
147
+ <img src="docs/assets/review-preview.svg" alt="Excerpt of real review.sh output: detected MVN profile, ARCH-005 and ARCH-101 violations, and heuristic candidates" width="820">
148
+ </p>
149
+
150
+ ```bash
151
+ bash ~/.agents/skills/dart-flutter-review/scripts/review.sh path/to/app [--diff main] # everything, read-only
152
+ python3 ~/.agents/skills/flutter-architecture/scripts/arch_check.py path/to/app [--json]
153
+ python3 ~/.agents/skills/flutter-secure-defaults/scripts/check_secure_defaults.py path/to/app
154
+ python3 ~/.agents/skills/flutter-accessibility/scripts/check_accessibility.py path/to/app
155
+ python3 ~/.agents/skills/flutter-feature-scaffold/scripts/scaffold.py path/to/app orders # dry run
156
+ ```
157
+
158
+ See a full report at [docs/examples/sample-review.md](docs/examples/sample-review.md),
159
+ and raw outputs in [docs/examples/](docs/examples/).
160
+
161
+ ## CI: fail pull requests on new violations only
162
+
163
+ ```yaml
164
+ # .github/workflows/flutter-review.yml
165
+ on: pull_request
166
+ jobs:
167
+ review:
168
+ runs-on: ubuntu-latest
169
+ steps:
170
+ - uses: actions/checkout@v4
171
+ with: { fetch-depth: 0 }
172
+ - uses: abdelrahman-abied/flutter-pro-skills@v1
173
+ with:
174
+ base-ref: origin/${{ github.base_ref }}
175
+ fail-on: high
176
+ baseline: .github/arch-baseline.json # optional: record today's issues once, fail only on new ones
177
+ flutter: true # also run the analyzer and every checker
178
+ ```
179
+
180
+ Create the baseline once with
181
+ `python3 …/arch_check.py . --write-baseline .github/arch-baseline.json`.
182
+ See [`ci.md`](skills/dart-flutter-review/references/ci.md) for the details.
183
+
184
+ ## Benchmark
185
+
186
+ **Headline (Claude Code, v1.7.0):** asked to "add login and store the token",
187
+ **Opus without the skills stored it in plain `SharedPreferences` in both runs**
188
+ (SEC-001 high). **Sonnet with the skills used `flutter_secure_storage` in both
189
+ runs, with 0 security findings.** On the gallery task, Sonnet + skills matched
190
+ Opus (0 findings) at about the same cost. See
191
+ [bench/README.md](bench/README.md).
192
+
193
+ We ran the same 3 tasks with and without the skills on a free, non-Claude
194
+ model (OpenCode + big-pickle, 2 runs each):
195
+
196
+ | Task | Without skills | With skills |
197
+ |---|---|---|
198
+ | **Write**: add login and store the token | Token in `SharedPreferences` (1 high security finding, both runs) | `flutter_secure_storage`, **0 security findings** (both runs) |
199
+ | **Review**: 12 planted issues | 92% recall, 0.5 MVN decoys flagged. Re-run on v1.6.1: 10/12 and 12/12, 10–15 min | 96% recall, **0** decoys flagged, more extra findings, about 6× slower. Re-run on v1.6.1: **12/12 both**, about 2× the extra claims, 30–45 min |
200
+ | **Bloc architecture**: 2 planted violations | 2/2. Re-run on v1.6.1: 1.5 claims contradicting bloclibrary | 2/2. The first run had 1.5 contradicting claims, a calibration bug since fixed. Re-run on v1.6.1: **0** |
201
+ | **Write a list screen** (T4, re-run 2026-10-18) | 1 of 2 runs added a layering violation and a swallowed catch | 0 new findings in both runs; one also fixed existing issues. A small difference on this model |
202
+
203
+ T3 was re-run on 2026-10-18 with the same result (baseline: SEC-001 high in
204
+ both runs; skills: 0). On Claude Code (Opus), both configurations write
205
+ clean code with 0 checker findings. The skills add tests (37–43 vs 0–12
206
+ per run) at about 3–4× the cost, and reviews hit 12/12 either way, now in
207
+ about the same time. Small N, author-written fixtures, one model. See the full method, the
208
+ limitations and how to re-run it in [bench/README.md](bench/README.md).
209
+
210
+ ## Works alongside the official skills
211
+
212
+ The Flutter and Dart teams publish
213
+ [flutter/agent-plugins](https://github.com/flutter/agent-plugins) and
214
+ [dart-lang/skills](https://github.com/dart-lang/skills). **Install them too.**
215
+ They are step-by-step recipes. This suite adds architecture-aware judgment,
216
+ secure-by-default writing, checkers and a review/CI pipeline. Where an official
217
+ recipe exists, these skills point to it.
218
+
219
+ ## Make every agent on a team follow it
220
+
221
+ 1. **Declare your architecture** in `AGENTS.md`, using
222
+ [`AGENTS-snippet.md`](skills/dart-flutter-best-practices/assets/AGENTS-snippet.md).
223
+ 2. **Adopt the lint set**
224
+ [`analysis_options.yaml`](skills/dart-flutter-best-practices/assets/analysis_options.yaml).
225
+ 3. **Enforce formatting** with
226
+ [`format-dart-hook.sh`](skills/dart-flutter-best-practices/scripts/format-dart-hook.sh),
227
+ as an agent hook or a git pre-commit hook.
228
+ 4. **Gate PRs** with the GitHub Action above.
229
+
230
+ To accept a specific finding, add `// arch-ignore: ARCH-005 <reason>` on that
231
+ line or the line above it. There are matching `err-`, `sec-`, `nav-`, `form-`,
232
+ `i18n-`, `perf-`, `persist-`, `net-`, `ds-`, `a11y-`, `rel-`, `plat-`, `adapt-` and `fire-ignore` comments.
233
+
234
+ **Precedence:**
235
+ 1. Your project's own decisions: lints, the declared architecture, and
236
+ conventions used consistently.
237
+ 2. The pattern's canonical source.
238
+ 3. Effective Dart.
239
+ 4. Flutter team guidance.
240
+
241
+ **Agents without skills support:** point your `AGENTS.md`, `CLAUDE.md`,
242
+ `GEMINI.md` or `.cursor/rules` at
243
+ `…/skills/dart-flutter-best-practices/SKILL.md` and
244
+ `…/skills/dart-flutter-review/SKILL.md`.
245
+
246
+ **Requirements:**
247
+ - `bash` and `python3` 3.8 or later (stdlib only).
248
+ - The Dart/Flutter SDK, for the analyzer passes. Without it they're skipped,
249
+ not failed.
250
+ - On Windows, use Git Bash or WSL.
251
+
252
+ ---
253
+
254
+ ## Contributing
255
+
256
+ False-positive reports are the most valuable contribution. Use the
257
+ [false-positive issue form](.github/ISSUE_TEMPLATE/false_positive.yml), and
258
+ see [CONTRIBUTING.md](CONTRIBUTING.md) and [`docs/CONTRACTS.md`](docs/CONTRACTS.md).
259
+
260
+ ```bash
261
+ bash tests/run_all.sh # spec + YAML validation and every skill's tests; no Flutter SDK needed
262
+ ```
263
+
264
+ ## License
265
+
266
+ MIT, © 2026 Abdulrahman Obaid. Parts summarise or adapt the Dart/Flutter docs
267
+ (CC BY) and the Bloc/Riverpod docs (MIT); see [`NOTICE.md`](NOTICE.md). MVN
268
+ (Model-View-Notifier) is by Abdulrahman Abied. Changes are listed in
269
+ [`CHANGELOG.md`](CHANGELOG.md).
package/install.sh ADDED
@@ -0,0 +1,86 @@
1
+ #!/usr/bin/env bash
2
+ # Install the flutter-pro-skills suite into one or more coding agents' skill folders.
3
+ #
4
+ # Usage:
5
+ # ./install.sh [--agent <name>]... [--project <dir>] [--link] [--skills a,b] [--uninstall] [--list]
6
+ #
7
+ # --agent where to install (repeatable). Default: agents + claude
8
+ # agents ~/.agents/skills Codex, Gemini CLI, GitHub Copilot, Cursor,
9
+ # OpenCode, Antigravity (the interoperable path)
10
+ # claude ~/.claude/skills Claude Code (also read by Cursor, Copilot, OpenCode)
11
+ # cursor ~/.cursor/skills
12
+ # gemini ~/.gemini/skills
13
+ # copilot ~/.copilot/skills
14
+ # opencode ~/.config/opencode/skills
15
+ # --project install into <dir>/.agents/skills, <dir>/.claude/skills, ... instead of $HOME
16
+ # --link symlink instead of copy (for contributors with a clone: edits go live; not with npx, its cache is temporary)
17
+ # --skills comma-separated subset (default: all twenty-one; they reference each other, so keep them together)
18
+ # --uninstall remove the suite's skills from the chosen locations
19
+ # --list print target folders and exit
20
+ #
21
+ # Agents that read several of these folders may show a skill twice if you install to both;
22
+ # pick one location per agent when that happens.
23
+ set -euo pipefail
24
+
25
+ # npm runs this script through a symlink in node_modules/.bin, so follow links to find the suite.
26
+ SOURCE="${BASH_SOURCE[0]}"
27
+ while [ -L "$SOURCE" ]; do
28
+ LINK_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
29
+ SOURCE="$(readlink "$SOURCE")"
30
+ case "$SOURCE" in /*) ;; *) SOURCE="$LINK_DIR/$SOURCE" ;; esac
31
+ done
32
+ REPO="$(cd "$(dirname "$SOURCE")" && pwd)"
33
+ ALL_SKILLS="dart-flutter-best-practices dart-naming flutter-ui-practices flutter-architecture flutter-feature-scaffold flutter-testing flutter-error-handling flutter-secure-defaults flutter-navigation flutter-forms flutter-i18n flutter-performance flutter-persistence flutter-networking flutter-firebase flutter-platform-integration flutter-design-system flutter-adaptive-layout flutter-accessibility flutter-release dart-flutter-review"
34
+ AGENTS=""; BASE="$HOME"; PROJECT=0; LINK=0; SKILLS="$ALL_SKILLS"; UNINSTALL=0; LIST=0
35
+
36
+ while [ $# -gt 0 ]; do
37
+ case "$1" in
38
+ --agent) AGENTS="$AGENTS ${2:?--agent needs a name}"; shift 2 ;;
39
+ --project) BASE="$(cd "${2:?--project needs a dir}" && pwd)"; PROJECT=1; shift 2 ;;
40
+ --link) LINK=1; shift ;;
41
+ --skills) SKILLS="$(echo "${2:?--skills needs a list}" | tr ',' ' ')"; shift 2 ;;
42
+ --uninstall) UNINSTALL=1; shift ;;
43
+ --list) LIST=1; shift ;;
44
+ -h|--help) sed -n 2,24p "$0"; exit 0 ;;
45
+ *) echo "unknown option: $1 (see --help)" >&2; exit 2 ;;
46
+ esac
47
+ done
48
+ [ -n "$AGENTS" ] || AGENTS="agents claude"
49
+
50
+ target_for() {
51
+ case "$1" in
52
+ agents) echo "$BASE/.agents/skills" ;;
53
+ claude) echo "$BASE/.claude/skills" ;;
54
+ cursor) echo "$BASE/.cursor/skills" ;;
55
+ gemini) echo "$BASE/.gemini/skills" ;;
56
+ copilot) if [ $PROJECT = 1 ]; then echo "$BASE/.github/skills"; else echo "$BASE/.copilot/skills"; fi ;;
57
+ opencode) if [ $PROJECT = 1 ]; then echo "$BASE/.opencode/skills"; else echo "$BASE/.config/opencode/skills"; fi ;;
58
+ *) echo "unknown agent: $1" >&2; return 2 ;;
59
+ esac
60
+ }
61
+
62
+ for s in $SKILLS; do
63
+ [ -f "$REPO/skills/$s/SKILL.md" ] || { echo "unknown skill: $s" >&2; exit 2; }
64
+ done
65
+
66
+ for a in $AGENTS; do
67
+ dest="$(target_for "$a")" || exit 2
68
+ if [ $LIST = 1 ]; then echo "$a -> $dest"; continue; fi
69
+ mkdir -p "$dest"
70
+ for s in $SKILLS; do
71
+ tgt="$dest/$s"
72
+ if [ -e "$tgt" ] || [ -L "$tgt" ]; then
73
+ # only replace things this installer put there (a symlink into this repo, or a copy carrying the suite tag)
74
+ # (dart-flutter-skills is the suite's pre-release name; accept it so upgrades replace old copies)
75
+ if [ -L "$tgt" ] || grep -Eq 'suite: (flutter-pro-skills|dart-flutter-skills)' "$tgt/SKILL.md" 2>/dev/null; then
76
+ rm -rf "${tgt:?}"
77
+ else
78
+ echo "skip $tgt (exists and is not from this suite)" >&2; continue
79
+ fi
80
+ fi
81
+ [ $UNINSTALL = 1 ] && { echo "removed $tgt"; continue; }
82
+ if [ $LINK = 1 ]; then ln -s "$REPO/skills/$s" "$tgt"; else cp -R "$REPO/skills/$s" "$tgt"; fi
83
+ chmod +x "$tgt"/scripts/*.sh "$tgt"/scripts/*.py 2>/dev/null || true
84
+ echo "$([ $LINK = 1 ] && echo linked || echo installed) $s -> $tgt"
85
+ done
86
+ done
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "flutter-pro-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.7.2",
4
+ "description": "Agent Skills that write and review Dart & Flutter code by your app's own architecture: MVVM, MVN, Bloc, Clean, Riverpod, GetX.",
5
+ "keywords": [
6
+ "flutter",
7
+ "dart",
8
+ "agent-skills",
9
+ "ai-agents",
10
+ "claude-code",
11
+ "codex",
12
+ "cursor",
13
+ "github-copilot",
14
+ "gemini-cli",
15
+ "opencode",
16
+ "clean-architecture",
17
+ "mvvm",
18
+ "bloc",
19
+ "riverpod",
20
+ "code-review"
21
+ ],
22
+ "homepage": "https://github.com/abdelrahman-abied/flutter-pro-skills#readme",
23
+ "bugs": "https://github.com/abdelrahman-abied/flutter-pro-skills/issues",
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git+https://github.com/abdelrahman-abied/flutter-pro-skills.git"
27
+ },
28
+ "license": "MIT",
29
+ "author": "Abdulrahman Obaid (https://github.com/abdelrahman-abied)",
30
+ "bin": {
31
+ "flutter-pro-skills": "install.sh"
32
+ },
33
+ "files": [
34
+ "install.sh",
35
+ "skills/",
36
+ "!skills/*/tests/",
37
+ "!**/__pycache__/",
38
+ "!**/*.pyc",
39
+ "NOTICE.md"
40
+ ]
41
+ }