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,342 @@
1
+ ---
2
+ name: dart-flutter-review
3
+ description: Review, audit or quality-check Dart/Flutter code, a diff, branch or PR and return one severity-ranked report with file:line evidence and a fix per finding. A read-only mechanical pass (format, analyzer, dart fix --dry-run, the suite's checkers, heuristic greps) is followed by parallel judgment passes (architecture, UI, idioms, naming, security, plus one per specialist such as tests, errors, i18n, performance, accessibility). Highs are verified and findings deduplicated. A CI mode and GitHub Action fail PRs only on new violations. Use it whenever someone asks to review, audit or sanity-check Dart/Flutter code, a branch, PR or codebase before merging, asks "what's wrong with this code" or wants a CI gate, even if they never say "review". Load it before reading the diff. If the request covers only one concern (only tests, only strings/RTL, only names), load that skill instead.
4
+ license: MIT
5
+ metadata:
6
+ author: abdelrahman-abied
7
+ version: "1.7.2"
8
+ suite: flutter-pro-skills
9
+ ---
10
+
11
+ # Dart & Flutter review (orchestrator)
12
+
13
+ A good review tells the author the few things that matter most, why they
14
+ matter, and exactly how to fix them. The toolchain owns the mechanical layer.
15
+ Your attention goes to what tools can't see, judged against the pattern the
16
+ project actually uses. This skill is **read-only** until the user asks for
17
+ fixes.
18
+
19
+ You run five phases: **0** scope and profile, **1** mechanical, **2** judgment
20
+ (in parallel when possible), **3** verify the Highs, **4** merge and report,
21
+ **5** offer fixes.
22
+
23
+ ## What this skill uses
24
+
25
+ | File | Holds | Load |
26
+ |---|---|---|
27
+ | `scripts/review.sh` | The mechanical pass (calls `scripts/heuristics.py` and the architecture checker) | Run it, don't read it |
28
+ | `references/review-guide.md` | Procedure detail, calibration rules, severity rubric, report template | By section |
29
+ | `references/finding-format.md` | The exact shape every pass returns findings in, with examples | Before Phase 2 |
30
+ | `references/reviewer-prompts.md` | Self-contained prompts for each reviewer and the verifier | When you spawn sub-agents |
31
+ | `references/ci.md` | CI mode, the baseline flow and the GitHub Action | When asked for CI, a PR gate or a baseline |
32
+ | `scripts/ci_action.sh` | The GitHub Action's entry point (also runnable locally) | Run it, don't read it |
33
+
34
+ Sibling skills, each with a fallback path relative to this skill's folder:
35
+ - `flutter-architecture` (`../flutter-architecture/SKILL.md`): profile detection, per-pattern rules, the anti-pattern catalog, `arch_check.py`
36
+ - `flutter-ui-practices` (`../flutter-ui-practices/SKILL.md`): widgets, lifecycle, async/context, performance
37
+ - `dart-naming` (`../dart-naming/SKILL.md`): naming
38
+ - `dart-flutter-best-practices` (`../dart-flutter-best-practices/SKILL.md`): Effective Dart checklist (`../dart-flutter-best-practices/references/effective-dart.md`) and the stricter lint set
39
+ - `flutter-testing` (`../flutter-testing/SKILL.md`): test strategy per pattern, `test_gaps.py` (optional testing pass)
40
+ - `flutter-error-handling` (`../flutter-error-handling/SKILL.md`): error flow across layers, `check_errors.py` (optional errors pass)
41
+ - `flutter-secure-defaults` (`../flutter-secure-defaults/SKILL.md`): write-time security per layer, `check_secure_defaults.py` (security pass)
42
+ - `flutter-navigation`, `flutter-forms`, `flutter-i18n` (`../flutter-<x>/SKILL.md`): routing and deep links, forms and input, localisation and RTL, each with a `check_*.py` (optional passes)
43
+ - `flutter-performance`, `flutter-persistence`, `flutter-networking`, `flutter-design-system`, `flutter-accessibility`, `flutter-release`, `flutter-platform-integration`, `flutter-adaptive-layout`, `flutter-firebase` (`../flutter-<x>/SKILL.md`): jank and rebuilds, local storage and migrations, the API client layer, tokens and themes, semantics and contrast, flavors/signing/store/CI, channels/Pigeon/FFI/plugins, size classes/platform idioms, Firebase rules/init/FCM, each with a `check_*.py` (optional passes)
44
+ - `flutter-security-audit`: a separate skill by the same author (RASP, pinning, obfuscation, attestation, MASVS/CWE). When installed next to this one, `review.sh` runs its `scan.sh`, and the security pass loads it for depth
45
+
46
+ If a sibling is missing, run without it and name the gap on the report's
47
+ **Coverage** line. A partial review that says what it skipped beats a
48
+ confident one that silently didn't check.
49
+
50
+ **Load references by section.** Run `grep -n '^##' <file>` and read only the
51
+ sections the code touches. The suite's references total thousands of lines, and
52
+ reading them all wastes the context you need for the code.
53
+
54
+ ## Phase 0: scope and profile
55
+
56
+ 1. **Scope.** Decide whether this is a **diff** or a **project** review.
57
+ - Diff: "review my PR / my changes / this branch". Get the files with
58
+ `git diff --name-only --diff-filter=ACMR <base>...HEAD -- '*.dart'`, plus
59
+ uncommitted and untracked files if the user means the working tree.
60
+ Judge the changed lines and whatever they directly affect: callers of a
61
+ changed signature, the `dispose` for a newly added controller.
62
+ - Project or feature: "review the app / this feature / lib/". Cover every
63
+ layer, and prioritise logic files, big widgets, and anything with async,
64
+ I/O or lifecycles.
65
+ - Ask only if you can't infer it.
66
+ 2. **Profile.** Read `pubspec.yaml` (SDK constraint, state-management and DI
67
+ dependencies) and `analysis_options.yaml` (what is enabled or disabled).
68
+ Then read the project instructions file: `AGENTS.md`, `CLAUDE.md`,
69
+ `GEMINI.md`, `.cursor/rules/…` or `.github/copilot-instructions.md`. Look for
70
+ a **declared architecture** line (e.g. `Architecture: Clean + MVN`). A
71
+ declared pattern beats detection. Map it to a profile value for
72
+ `--profile`: `mvn`, `mvvm`, `bloc`, `mvc`, `getx`, `provider`, `riverpod`
73
+ or `setstate`.
74
+ 3. **Note conventions** from two or three files: k-constants, `var` vs
75
+ `final`, `_onTap` handlers, suffixes. A convention used consistently is a
76
+ project decision, not a finding.
77
+ 4. **Size.** Count the non-generated `.dart` files in scope. That count
78
+ decides parallel vs sequential in Phase 2. Never review generated code
79
+ (`*.g.dart`, `*.freezed.dart`, `*.gen.dart`, `*.mocks.dart`, `lib/generated/`,
80
+ l10n output, "GENERATED CODE" headers). `review.sh` takes the scope from
81
+ `arch_check.py`'s `files[]`, so its file count is the one to use.
82
+
83
+ ## Phase 1: mechanical pass
84
+
85
+ Run the script once and **save its output to a temp file**, because sub-agents
86
+ read it instead of re-running it:
87
+
88
+ ```bash
89
+ out="$(mktemp "${TMPDIR:-/tmp}/dart-review.XXXXXX")"
90
+ bash <skill-dir>/scripts/review.sh <project-root> [--diff <ref>] [--profile <p>] > "$out" 2>&1
91
+ echo "$out"
92
+ ```
93
+
94
+ `<skill-dir>` is this skill's folder. Flags: `--diff <ref>`, `--profile <p>`
95
+ (from Phase 0; it reaches every sibling checker), `--max <n>`, the CI flags
96
+ `--ci`, `--fail-on`, `--baseline` (see "CI mode" below), and skips:
97
+ `--no-extra`, `--no-arch`, `--no-tests`, `--no-errors`, `--no-security` (both
98
+ security sections), `--no-audit`, `--no-nav`, `--no-forms`, `--no-i18n`,
99
+ `--no-perf`, `--no-persist`, `--no-net`, `--no-ds`, `--no-a11y`, `--no-release`,
100
+ `--no-platform`, `--no-adaptive`, `--no-firebase`, or one
101
+ `--skip extra,arch,tests,errors,security,audit,nav,forms,i18n,perf,persist,net,ds,a11y,release,platform,adaptive,firebase`. `--findings-only` prints only the checker findings at low or above, plus
102
+ analyzer errors and warnings. Use it to check your own change once after
103
+ writing; it isn't meant for a review report. The script never
104
+ modifies the project. Exit code 0 means the report was produced, even with
105
+ findings. Exit code 2 means there's no `pubspec.yaml` or `dart` isn't on PATH.
106
+ Only `--ci` exits 1.
107
+
108
+ Sections (run `grep -n '^== ' "$out"` to find them):
109
+ - `CONTEXT`: SDK, lint include, scope. A pub workspace member gets a
110
+ `packages:` line (resolved at the workspace root); that is fine. A
111
+ `WARNING: no .dart_tool` line means packages aren't resolved. Suggest
112
+ `flutter pub get` / `dart pub get` and rerun, because otherwise ANALYZER is
113
+ mostly unresolved-import noise. Don't report that noise. A `WARNING: pubspec
114
+ sdk constraint …` line means the installed SDK can't analyse this project,
115
+ so ANALYZER, AUTO-FIXABLE and EXTRA LINTS are skipped: say so on Coverage.
116
+ - `FORMAT`, `AUTO-FIXABLE`: these become **one** collapsed Mechanical finding.
117
+ - `ANALYZER`: the project's own lint config. Fold each item into a judgment
118
+ finding. `codegen: N generated file(s) missing` plus `collapsed: M error(s)`
119
+ means build_runner hasn't run: report **one** finding ("run build_runner"),
120
+ never the cascade. `analyzer crashed (…)` means no analyzer results; name it
121
+ on Coverage.
122
+ - `EXTRA LINTS`: the stricter set the project has *not* adopted. Mention it once
123
+ under "Worth adopting", and never report it as violations.
124
+ - `ARCHITECTURE PROFILE` / `ARCHITECTURE VIOLATIONS`: the detected profile and
125
+ `ARCH-0xx`/`ARCH-1xx` hits. If the line says `skipped`, the architecture
126
+ skill isn't installed.
127
+ - `TEST GAPS` / `TEST SMELLS`: from `flutter-testing`'s `test_gaps.py`,
128
+ untested units ranked by architecture priority, and smells in `test/`.
129
+ Always whole-project, even in diff mode.
130
+ - `ERROR HANDLING`: `[ERR-0xx]` groups from `flutter-error-handling`'s
131
+ `check_errors.py`, limited to the diff in diff mode.
132
+ - `SECURITY DEFAULTS` (`[SEC-0xx]`), `NAVIGATION` (`[NAV-0xx]`), `FORMS`
133
+ (`[FORM-0xx]`), `I18N` (`[I18N-0xx]`), `PERFORMANCE` (`[PERF-0xx]`),
134
+ `PERSISTENCE` (`[PERSIST-0xx]`), `NETWORKING` (`[NET-0xx]`), `FIREBASE` (`[FIRE-0xx]`), `PLATFORM` (`[PLAT-0xx]`), `DESIGN SYSTEM` (`[DS-0xx]`), `ADAPTIVE LAYOUT` (`[ADAPT-0xx]`),
135
+ `ACCESSIBILITY` (`[A11Y-0xx]`): the sibling checkers, limited to the diff in
136
+ diff mode. `RELEASE` (`[REL-0xx]`) reads Gradle, Xcode, plist and CI files,
137
+ so it always covers the whole project and says so in diff mode. `FIREBASE`
138
+ does the same, because it reads the security rules files.
139
+ - `SECURITY AUDIT`: `flutter-security-audit`'s `scan.sh`, regrouped
140
+ (`[NET-NO-PINNING] (high) … (absence check)`). These are candidates.
141
+ Absence checks are project-wide, and they're omitted in diff mode.
142
+ - Any of these says `skipped` when its skill isn't installed, and `error` if
143
+ its script failed. No failure stops the run.
144
+ - `CANDIDATES`: heuristic `[CANDIDATE]` lines. Each must be confirmed by
145
+ reading before it becomes a finding. When ERROR HANDLING ran, the
146
+ `swallowed-catch` candidate keeps only its count and says "see ERROR
147
+ HANDLING": those catches are ERR-001 hits, so report each one once, there.
148
+ Likewise `eager-children-map` says "see PERFORMANCE" when that checker
149
+ ran, and `hardcoded-color` says "see DESIGN SYSTEM". `opacity-widget` keeps
150
+ its locations: drop it only where `PERF-005` reports the same line.
151
+
152
+ If `dart` isn't available, still run the architecture checker on its own
153
+ (`python3 -I <skill-dir>/../flutter-architecture/scripts/arch_check.py <project-root>
154
+ [--files <list>] [--profile <p>]`, it needs only Python), and say that the
155
+ analyzer and format passes were skipped. The other checkers (`test_gaps.py`,
156
+ `check_errors.py`, `check_secure_defaults.py`, `check_navigation.py`,
157
+ `check_forms.py`, `check_i18n.py`, `check_performance.py`,
158
+ `check_persistence.py`, `check_networking.py`, `check_firebase.py`, `check_platform.py`, `check_adaptive.py`, `check_release.py`, `check_design_system.py`, `check_accessibility.py`)
159
+ need only Python, and `scan.sh` only bash
160
+ (CLIs in `references/ci.md` › Local equivalents).
161
+
162
+ ## Phase 2: judgment passes
163
+
164
+ There are four core dimensions and fourteen optional ones. Each returns findings
165
+ in the shape given in `references/finding-format.md`. Each pass loads its
166
+ skill's SKILL.md **and its `<skill>/references/review.md`** (the review checklist and
167
+ finding examples live there, not in SKILL.md).
168
+
169
+ | Pass | Loads | Starts from | IDs |
170
+ |---|---|---|---|
171
+ | (a) Architecture | `flutter-architecture` | `ARCHITECTURE` sections + profile | `ARCH-0xx`, `ARCH-1xx`, `AP-` |
172
+ | (b) Flutter UI / lifecycle / performance | `flutter-ui-practices` | lifecycle and build candidates; context/async lints | `UI-`, `LINT:` |
173
+ | (c) Dart idioms + naming | `effective-dart.md` from the hub + `dart-naming` | naming and error-handling candidates; analyzer | `ED-`, `NAME-`, `LINT:` |
174
+ | (d) Security | `flutter-secure-defaults`; `flutter-security-audit` for depth | `SECURITY DEFAULTS`, `SECURITY AUDIT` | `SEC-0xx`, `SEC-` |
175
+ | (e) Testing (optional) | `flutter-testing` | `TEST GAPS` / `TEST SMELLS` | `TEST-` |
176
+ | (f) Errors (optional) | `flutter-error-handling` | `ERROR HANDLING`; owns catches when it runs | `ERR-0xx`, `ERR-` |
177
+ | (g) Navigation (optional) | `flutter-navigation` | `NAVIGATION` | `NAV-0xx`, `NAV-` |
178
+ | (h) Forms (optional) | `flutter-forms` | `FORMS` | `FORM-0xx`, `FORM-` |
179
+ | (i) I18n (optional) | `flutter-i18n` | `I18N` | `I18N-0xx`, `I18N-` |
180
+ | (j) Performance (optional) | `flutter-performance` | `PERFORMANCE` | `PERF-0xx`, `PERF-` |
181
+ | (k) Persistence (optional) | `flutter-persistence` | `PERSISTENCE` | `PERSIST-0xx`, `PERSIST-` |
182
+ | (l) Design system (optional) | `flutter-design-system` | `DESIGN SYSTEM` | `DS-0xx`, `DS-` |
183
+ | (m) Accessibility (optional) | `flutter-accessibility` | `ACCESSIBILITY` | `A11Y-0xx`, `A11Y-` |
184
+ | (n) Networking (optional) | `flutter-networking` | `NETWORKING` | `NET-0xx`, `NET-` |
185
+ | (o) Release (optional) | `flutter-release` | `RELEASE` | `REL-0xx`, `REL-` |
186
+ | (p) Platform integration (optional) | `flutter-platform-integration` | `PLATFORM` | `PLAT-0xx`, `PLAT-` |
187
+ | (q) Adaptive layout (optional) | `flutter-adaptive-layout` | `ADAPTIVE LAYOUT` | `ADAPT-0xx`, `ADAPT-` |
188
+ | (r) Firebase (optional) | `flutter-firebase` | `FIREBASE` | `FIRE-0xx`, `FIRE-` |
189
+
190
+ **Follow the `== PASS PLAN`** at the end of the mechanical output: it is the
191
+ cheapest way to a fast review. It lists the core passes, every optional pass
192
+ whose checker found something at low or above (`run:`), and the ones with
193
+ nothing to confirm (`skip:`). Run the `run:` passes. Skip the `skip:` ones
194
+ unless the user asked about that area or reading the code turns up something
195
+ in it: each skipped pass saves a full reading pass, and its checker already
196
+ looked. The plan's `mode:` line says quick or parallel (below).
197
+
198
+ The security pass (d) is core: "secure by default" means every review looks.
199
+ If neither security skill is installed, run it from the template's own
200
+ checklist and say so on Coverage. Run each optional pass when its skill is
201
+ installed (its section isn't `skipped`) or the user asks about that area; for
202
+ (g)–(r), also only when the code has it (a router, forms, localisation or
203
+ user-facing strings, widgets, local storage, theme code, HTTP calls, platform
204
+ folders or CI config, platform channels or FFI, widgets for (q), a Firebase dependency for (r)). If a skill is missing, leave the pass out and name the
205
+ gap on the Coverage line. The idioms pass (c) still covers swallowed catches
206
+ when (f) doesn't run, and the UI pass (b) still covers l10n/RTL when (i)
207
+ doesn't, and lists, images, colours and semantics when (j), (l) or (m) don't.
208
+
209
+ **In parallel, when you can.** Use parallel sub-agents if your agent can spawn
210
+ them (for example Claude Code's Agent/Task tool, Codex sub-agents, or another
211
+ agent's equivalent) **and** the scope is big enough: roughly more than 15
212
+ files, or the user asked for a deep or thorough review.
213
+ 1. Write the file list to a temp file. You already have the mechanical output
214
+ path.
215
+ 2. Fill in the templates from `references/reviewer-prompts.md` verbatim: A, B,
216
+ C and D (security), plus E (testing), F (errors), G (navigation), H (forms),
217
+ I (i18n), J (performance), K (persistence), L (design system), M
218
+ (accessibility), N (networking), O (release), P (platform integration)
219
+ Q (adaptive layout) and R (Firebase) when they apply, as above.
220
+ Use absolute paths.
221
+ 3. Spawn every reviewer **at once**, each **read-only**, and wait for all of
222
+ them. Each prompt says: confirm by reading, return text only, write no
223
+ files, edit no code.
224
+ 4. If a reviewer fails or returns something malformed, run that dimension
225
+ yourself. Don't drop it silently.
226
+
227
+ **Quick mode, otherwise** (`mode: quick` in the plan: 15 files or fewer, or
228
+ no sub-agents). Don't run the templates one by one. Make **one combined
229
+ pass** instead:
230
+ 1. Confirm every `run:` group and every High or Medium `[CANDIDATE]` by
231
+ opening the file at that line. Drop what reading disproves.
232
+ 2. Read the files in scope once, in this order: lifecycle and UI bugs, the
233
+ architecture rules of the detected pattern, security, then error flow.
234
+ Note only what is at least Medium, or a Low with a one-line fix.
235
+ 3. Load a sibling skill only to settle a finding you are unsure of, and read
236
+ only the section the rule points at, not the whole reference.
237
+
238
+ Use the same finding format, so Phase 4 works the same way. For more than ~40
239
+ files without sub-agents, sample each layer and say that you sampled.
240
+
241
+ ## Phase 3: verify every High
242
+
243
+ A false High costs the author more than a missed Low, so give each High finding
244
+ **one adversarial check** that tries to disprove it. The check looks for a
245
+ dispose in a base class or mixin, `ref.onDispose`, ownership handed elsewhere,
246
+ a mounted guard, a project decision, or a pattern that sanctions the code.
247
+ Spawn a verifier per High, or batch small ones, using Template V in
248
+ `references/reviewer-prompts.md`, if sub-agents are available. Otherwise do the
249
+ check yourself and argue against your own finding. Drop **DISPROVED**
250
+ findings. Apply **DOWNGRADE** results with the stated reason. Keep
251
+ **CONFIRMED** findings, and mark them `confidence: confirmed`.
252
+
253
+ ## Phase 4: merge and report
254
+
255
+ 1. **Collect** all pass outputs and build the one Mechanical line from FORMAT and
256
+ AUTO-FIXABLE ("`dart fix --apply` resolves 42 issues across 17 files:
257
+ unnecessary_this ×18, …").
258
+ 2. **Dedupe by (file, line, root cause).** The same root cause in several
259
+ places is one finding with a location list. When passes overlap, keep the
260
+ **most specific ID**. A numbered `ARCH-` rule beats an `AP-` slug. A
261
+ `UI-`/`ED-`/`NAME-` slug that names the root cause beats a `LINT:` code
262
+ that only shows the symptom. An `ERR-` ID beats `ED-swallowed-catch` and
263
+ the `swallowed-catch` candidate for the same catch. A checker ID beats the
264
+ reading-level slug for the same file and line: `SEC-0xx` beats a `scan.sh`
265
+ ID (cite it in `rule:`), `I18N-010` beats `UI-l10n` (hard-coded UI string),
266
+ `I18N-012` beats `UI-rtl` (physical-direction geometry), `PERF-` beats
267
+ `UI-eager-list`/`UI-opacity`/`UI-image-decode-size`/`UI-rebuild-scope`/
268
+ `UI-blocking-ui-isolate`, `DS-` beats `UI-hardcoded-style`, `A11Y-` beats
269
+ `UI-a11y`, storage tokens stay `SEC-001` over any `PERSIST-` slug, transport
270
+ security stays `SEC-` over `NET-` (NET owns timeouts, client reuse,
271
+ retry policy, pagination and cancellation), and `NAV-`/`FORM-`
272
+ beat `UI-` for routing and form fields. Navigation inside logic stays
273
+ `ARCH-102`. Fold the others into `rule:` and `evidence:`.
274
+ 3. **Calibrate** with `references/review-guide.md` › "Calibrate before
275
+ reporting". Respect the project's decisions and keep each rule at its own
276
+ strength. Judge architecture against the declared or detected profile.
277
+ **Analyzer output that `dart fix` can't apply is not Mechanical**: it goes
278
+ into the judgment finding it belongs to. Info items are trade-offs, not
279
+ defects.
280
+ 4. **Rank**: High, then Medium, Low, Info, Mechanical. Within one severity,
281
+ put the widest blast radius first: most locations, public API, hot path.
282
+ 5. **Report** with the template in `references/review-guide.md` › "Report
283
+ template". Include the Scope, Toolchain, Architecture and Coverage lines,
284
+ a one-sentence verdict, and the summary table. Give full write-ups for the
285
+ High and Medium findings, and let a table carry the long tail.
286
+ **Deliver it in chat** unless the user asked for a file.
287
+
288
+ ## Phase 5: offer fixes, don't apply them
289
+
290
+ End by offering the next step without taking it. You can (a) apply the
291
+ mechanical layer with `dart fix --apply && dart format <scope>`, (b) fix the
292
+ High items, or (c) fix specific findings. Renaming a public member of a
293
+ published package is breaking, so say so and offer a `@Deprecated`
294
+ forwarding member.
295
+
296
+ If the user accepts, make the changes. Then rerun `scripts/review.sh` on the
297
+ touched files: `--diff HEAD` covers uncommitted and untracked changes. Report
298
+ the before/after counts per section and any finding the change didn't
299
+ resolve.
300
+
301
+ ## CI mode
302
+
303
+ For a PR gate rather than a conversation, run the mechanical pass in CI mode:
304
+
305
+ ```bash
306
+ bash <skill-dir>/scripts/review.sh <project-root> --ci [--fail-on high|medium|low] [--baseline <file>] [--diff <ref>]
307
+ ```
308
+
309
+ It exits 1 when architecture violations at or above `--fail-on` (default
310
+ `high`) are **new** versus the baseline, or when the analyzer reports errors
311
+ (only counted after `pub get`, and never for codegen cascades, an analyzer
312
+ crash or an SDK the pubspec excludes). Test gaps, error handling, security
313
+ (including `scan.sh`, whatever its own exit code), navigation, forms, i18n,
314
+ performance, persistence, networking, design system, accessibility, release, platform, adaptive layout, firebase and candidates are informational and never fail the run. A `== CI RESULT` section explains the
315
+ verdict, and with `$GITHUB_STEP_SUMMARY` set it appends a Markdown summary
316
+ (section counts and top findings). The baseline comes from
317
+ `arch_check.py --write-baseline <file>`, and its keys ignore line numbers, so
318
+ unrelated edits don't invalidate it.
319
+
320
+ The repository root's `action.yml` wraps this as a GitHub Action
321
+ (`uses: abdelrahman-abied/flutter-pro-skills@v1`). With `flutter: false` it
322
+ runs only the architecture check and needs nothing but Python. Read
323
+ `references/ci.md` for the workflow YAML, the baseline adoption flow and the
324
+ equivalent local commands. CI mode is a gate, not a review: when someone asks
325
+ why CI failed, run the normal phases on the reported files.
326
+
327
+ ## Lessons from real runs
328
+
329
+ - **Sub-agents return text, not files.** Some environments block sub-agents
330
+ from writing files. Ask for the findings in the reply, and do any file
331
+ writing yourself.
332
+ - **One mechanical run.** Sub-agents read the saved output. If four agents
333
+ re-run `dart analyze`, the review takes four times as long and they may
334
+ disagree.
335
+ - **Candidates are not findings.** Heuristic greps have false positives by
336
+ design: tear-off disposal, generic dispose loops, ownership hand-offs.
337
+ Open the file before you report.
338
+ - **Mechanical means `dart fix`/`dart format` can fix it.** Errors, warnings
339
+ and lints with no fix belong in judgment findings.
340
+ - **Deliver in chat** unless the user asked for a file.
341
+ - **Read references by section.** Grep the headings. Don't read every file
342
+ in full.
@@ -0,0 +1,212 @@
1
+ # CI mode and the GitHub Action
2
+
3
+ A review in chat finds problems; CI keeps new ones out. CI mode turns the
4
+ mechanical pass into a gate that fails a pull request only on what the pull
5
+ request **adds**. Existing debt goes into a committed baseline, so you can turn
6
+ the gate on today without fixing the whole codebase first.
7
+
8
+ ## Contents
9
+ 1. What fails the build
10
+ 2. GitHub Action
11
+ 3. Adopting a baseline
12
+ 4. Local equivalents
13
+ 5. Outputs and the step summary
14
+ 6. Troubleshooting
15
+
16
+ ## 1. What fails the build
17
+
18
+ | Check | Fails CI? |
19
+ |---|---|
20
+ | Architecture violations (`ARCH-0xx`, `ARCH-1xx`) at or above `fail-on` that are not in the baseline | Yes |
21
+ | Analyzer **errors** in scope (full mode only, and only after `pub get`; a pub workspace member uses the workspace root's `.dart_tool/package_config.json`) | Yes |
22
+ | Analyzer errors that are likely **codegen cascades** (`uri_has_not_been_generated`, `undefined_*`, `redirect_to_non_class`, `mixin_of_non_class`, … while generated files are missing) | No, collapsed into one line: run `build_runner` first |
23
+ | Analyzer results when the analyzer **crashed** (often an analyzer plugin), or when the pubspec SDK constraint excludes the installed SDK | No, the section says why |
24
+ | Architecture violations below `fail-on`, or recorded in the baseline | No, reported |
25
+ | Analyzer warnings and infos, format, `dart fix` | No, reported |
26
+ | Test gaps, error handling, security defaults, the `flutter-security-audit` `scan.sh` pass (whatever its own exit code), navigation, forms, i18n, performance, persistence, networking, design system, accessibility, release, platform, adaptive layout, firebase, heuristic candidates | No, informational |
27
+ | A usage or environment error (no `pubspec.yaml`, bad input, missing base ref) | Yes (exit 2) |
28
+
29
+ `fail-on` is `high` by default. `medium` also fails on medium violations, and
30
+ `low` on everything. Start at `high` and tighten once the baseline shrinks.
31
+
32
+ Exit codes: `0` pass, `1` CI failure, `2` usage or environment error.
33
+
34
+ ## 2. GitHub Action
35
+
36
+ The repository root holds a composite action. Pin a tag (`@v1`) or a commit SHA.
37
+
38
+ ```yaml
39
+ # .github/workflows/flutter-review.yml
40
+ name: Flutter review
41
+ on:
42
+ pull_request:
43
+ push:
44
+ branches: [main]
45
+
46
+ jobs:
47
+ architecture:
48
+ runs-on: ubuntu-latest
49
+ steps:
50
+ - uses: actions/checkout@v4
51
+ with:
52
+ fetch-depth: 0 # base-ref diffs need history
53
+ - uses: abdelrahman-abied/flutter-pro-skills@v1
54
+ id: review
55
+ with:
56
+ path: . # folder with pubspec.yaml
57
+ base-ref: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || '' }}
58
+ fail-on: high
59
+ baseline: .github/arch-baseline.json # optional; see section 3
60
+ flutter: false # architecture only: python3, no Flutter SDK
61
+ - if: always()
62
+ run: echo "new violations: ${{ steps.review.outputs.new-violations }}"
63
+ ```
64
+
65
+ Full mechanical review (format, analyzer, `dart fix`, architecture, test gaps,
66
+ error handling) on a pull request:
67
+
68
+ ```yaml
69
+ - uses: abdelrahman-abied/flutter-pro-skills@v1
70
+ with:
71
+ base-ref: origin/${{ github.base_ref }}
72
+ baseline: .github/arch-baseline.json
73
+ flutter: true
74
+ flutter-version: stable # or a version such as 3.24.x
75
+ ```
76
+
77
+ | Input | Default | Meaning |
78
+ |---|---|---|
79
+ | `path` | `.` | The project root (the folder with `pubspec.yaml`), relative to the repository root. For a monorepo, run one step per package |
80
+ | `base-ref` | empty | Report only `.dart` files changed versus this ref (diffed from the merge base). Empty means the whole project |
81
+ | `fail-on` | `high` | `high`, `medium` or `low` |
82
+ | `baseline` | empty | An `arch-baseline@1` file, relative to the repository root |
83
+ | `flutter` | `false` | `true` installs Flutter with `subosito/flutter-action@v2`, runs `flutter pub get` and the full `review.sh --ci`. `false` runs only `arch_check.py --ci` |
84
+ | `flutter-version` | `stable` | A channel (`stable`, `beta`, `master`) or a version, used when `flutter` is `true` |
85
+
86
+ | Output | Meaning |
87
+ |---|---|
88
+ | `new-violations` | The number of architecture violations not in the baseline, at any severity |
89
+ | `report-path` | The plain-text report on the runner (upload it with `actions/upload-artifact` if you want to keep it) |
90
+
91
+ `flutter: false` is fast (seconds) and needs only `python3`, which GitHub's
92
+ Linux and macOS runners already have. Use `flutter: true` when you also want
93
+ analyzer errors to fail the build; it costs a Flutter install and `pub get`.
94
+
95
+ ## 3. Adopting a baseline
96
+
97
+ 1. **Write the baseline once**, from the default branch, at the repository root:
98
+
99
+ ```bash
100
+ python3 -I <skills>/flutter-architecture/scripts/arch_check.py . \
101
+ --write-baseline .github/arch-baseline.json
102
+ ```
103
+
104
+ Pass the same `--profile` you use in CI if you declare one.
105
+ 2. **Commit it.** It is plain JSON:
106
+ `{"schema": "flutter-pro-skills/arch-baseline@1", "entries": [{"id", "file", "key"}]}`,
107
+ with one entry per existing violation. `key` is the evidence (the import or
108
+ the offending line) with whitespace normalised and **no line numbers**, so
109
+ adding code above a violation doesn't make it "new". Identical lines in one
110
+ file are counted, so a third copy of a line that is baselined twice is one
111
+ new violation.
112
+ 3. **Point CI at it** (`baseline:` input, or `--baseline`). From then on, CI
113
+ fails only on violations that aren't in it. The text report says
114
+ `summary: N new, M baselined`, plus how many baseline entries no longer
115
+ match (fixed debt).
116
+ 4. **Shrink it.** When you fix old violations, regenerate the file with the
117
+ same command and commit the smaller baseline. Review baseline diffs like
118
+ code: a baseline that grows in a pull request is the PR accepting new debt.
119
+
120
+ Changing the evidence line of a baselined violation (editing the offending
121
+ import or line itself) makes it new again. That is deliberate: the line was
122
+ touched, so it should be looked at.
123
+
124
+ ## 4. Local equivalents
125
+
126
+ `<skills>` is the folder holding the suite's skill folders (for example
127
+ `.claude/skills`, `.agents/skills`, or a clone of this repository's `skills/`).
128
+
129
+ ```bash
130
+ # what the action runs with flutter: false
131
+ python3 -I <skills>/flutter-architecture/scripts/arch_check.py . --ci --fail-on high \
132
+ --baseline .github/arch-baseline.json
133
+
134
+ # ... limited to a branch's changes
135
+ git diff --name-only --relative "$(git merge-base origin/main HEAD)" -- '*.dart' > /tmp/changed.txt
136
+ python3 -I <skills>/flutter-architecture/scripts/arch_check.py . --ci --files /tmp/changed.txt \
137
+ --baseline .github/arch-baseline.json
138
+
139
+ # what the action runs with flutter: true (after flutter pub get)
140
+ bash <skills>/dart-flutter-review/scripts/review.sh . --ci --fail-on high \
141
+ --baseline .github/arch-baseline.json --diff origin/main
142
+
143
+ # the action's own entry point, with the inputs as environment variables
144
+ INPUT_PATH=. INPUT_FLUTTER=false INPUT_FAIL_ON=high INPUT_BASELINE=.github/arch-baseline.json \
145
+ bash <skills>/dart-flutter-review/scripts/ci_action.sh
146
+
147
+ # the sibling passes on their own (read-only, python3 only)
148
+ python3 -I <skills>/flutter-testing/scripts/test_gaps.py . [--profile <p>]
149
+ python3 -I <skills>/flutter-error-handling/scripts/check_errors.py . [--files <list>] [--profile <p>]
150
+ python3 -I <skills>/flutter-secure-defaults/scripts/check_secure_defaults.py . [--files <list>] [--profile <p>]
151
+ python3 -I <skills>/flutter-navigation/scripts/check_navigation.py . [--files <list>] [--profile <p>]
152
+ python3 -I <skills>/flutter-forms/scripts/check_forms.py . [--files <list>] [--profile <p>]
153
+ python3 -I <skills>/flutter-i18n/scripts/check_i18n.py . [--files <list>] [--profile <p>]
154
+ python3 -I <skills>/flutter-performance/scripts/check_performance.py . [--files <list>] [--profile <p>]
155
+ python3 -I <skills>/flutter-persistence/scripts/check_persistence.py . [--files <list>] [--profile <p>]
156
+ python3 -I <skills>/flutter-networking/scripts/check_networking.py . [--files <list>] [--profile <p>]
157
+ python3 -I <skills>/flutter-firebase/scripts/check_firebase.py . [--profile <p>] # reads firestore/storage/database rules too
158
+ python3 -I <skills>/flutter-platform-integration/scripts/check_platform.py . [--files <list>] [--profile <p>]
159
+ python3 -I <skills>/flutter-adaptive-layout/scripts/check_adaptive.py . [--files <list>] [--profile <p>]
160
+ python3 -I <skills>/flutter-release/scripts/check_release.py . [--profile <p>] # reads Gradle/Xcode/plist/CI files too
161
+ python3 -I <skills>/flutter-design-system/scripts/check_design_system.py . [--files <list>] [--profile <p>]
162
+ python3 -I <skills>/flutter-accessibility/scripts/check_accessibility.py . [--files <list>] [--profile <p>]
163
+ bash <skills>/flutter-security-audit/scan.sh . [--json] # separate skill; exits 1 on Critical/High by itself
164
+
165
+ # skip sections in review.sh: --no-security (both security passes), --no-audit, --no-nav,
166
+ # --no-forms, --no-i18n, --no-perf, --no-persist, --no-net, --no-ds, --no-a11y, --no-release, --no-platform, --no-adaptive, --no-firebase,
167
+ # or one list: --skip audit,nav,forms,i18n,perf,persist,net,ds,a11y,release,platform,adaptive,firebase
168
+ ```
169
+
170
+ `echo $?` after any of them: `0` pass, `1` CI failure, `2` usage error.
171
+ `--fail-on` only matters with `--ci`. `--baseline` works without `--ci` too:
172
+ it reports only new violations and still exits 0.
173
+
174
+ ## 5. Outputs and the step summary
175
+
176
+ With `$GITHUB_STEP_SUMMARY` set (GitHub sets it in every job), the run appends
177
+ a Markdown summary: the result, a table of findings per section, and the top
178
+ findings (the most severe architecture, error-handling and test-gap groups,
179
+ with an example location each). Locally you can preview it with
180
+ `GITHUB_STEP_SUMMARY=/tmp/summary.md bash review.sh . --ci`.
181
+
182
+ The text report ends with a `== CI RESULT` section that names each reason for
183
+ the verdict. `review.sh --ci` and `arch_check.py --ci` print an
184
+ ` ci: pass|fail (N at or above <sev>)` line in the architecture section.
185
+
186
+ ## 6. Troubleshooting
187
+
188
+ - **`base-ref '…' not found`**: check out with `fetch-depth: 0`, or pass a ref
189
+ that exists on the runner (`origin/main`, not `main`, after a default checkout).
190
+ - **Analyzer errors "not counted (no pub get)"**: the full mode needs resolved
191
+ packages. The action runs `flutter pub get`; locally, run it yourself.
192
+ - **Thousands of analyzer errors, `uri_has_not_been_generated`**: code
193
+ generation hasn't run. Run `dart run build_runner build --delete-conflicting-outputs`
194
+ (and `flutter gen-l10n` if used) before `review.sh`. Without it the
195
+ cascades are collapsed and not counted, but real errors hide among them.
196
+ - **`WARNING: no .dart_tool` in a monorepo**: a pub workspace member is
197
+ resolved at the workspace root, so run `pub get` there. review.sh walks up
198
+ to that root and only uses a config that lists the package.
199
+ - **`analyzer crashed (…; in analyzer plugin package:x)`**: the Analysis
200
+ Server hit an exception, usually in a plugin. Disable the plugin under
201
+ `analyzer: plugins:` (or `plugins:`) for the CI run, or pin a working version.
202
+ - **`ANALYZER (skipped: pubspec sdk constraint …)`**: the installed SDK is
203
+ outside `environment: sdk:` (or the constraint is pre-null-safety, which
204
+ Dart 3 can't analyse). Pin the matching Flutter version (`flutter-version`
205
+ input). `>=2.12.0 <3.0.0` style constraints count as `<4.0.0` on Dart 3.
206
+ - **Every violation is new**: the baseline was written with a different
207
+ `--profile`, from a different `path`, or before a mass rename. Regenerate it.
208
+ - **A violation you disagree with**: silence it in code with
209
+ `// arch-ignore: ARCH-0xx <reason>` (it then shows as suppressed), rather
210
+ than growing the baseline.
211
+ - **Windows runners** aren't supported (the scripts are bash). Use
212
+ `ubuntu-latest` or `macos-latest`.