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.
- package/LICENSE +21 -0
- package/NOTICE.md +26 -0
- package/README.ar.md +122 -0
- package/README.md +268 -2
- package/install.sh +86 -0
- package/package.json +39 -4
- package/skills/dart-flutter-best-practices/SKILL.md +242 -0
- package/skills/dart-flutter-best-practices/assets/AGENTS-snippet.md +24 -0
- package/skills/dart-flutter-best-practices/assets/analysis_options.yaml +86 -0
- package/skills/dart-flutter-best-practices/references/effective-dart.md +338 -0
- package/skills/dart-flutter-best-practices/scripts/format-dart-hook.sh +48 -0
- package/skills/dart-flutter-review/SKILL.md +342 -0
- package/skills/dart-flutter-review/references/ci.md +212 -0
- package/skills/dart-flutter-review/references/finding-format.md +238 -0
- package/skills/dart-flutter-review/references/review-guide.md +217 -0
- package/skills/dart-flutter-review/references/reviewer-prompts.md +1456 -0
- package/skills/dart-flutter-review/scripts/ci_action.sh +81 -0
- package/skills/dart-flutter-review/scripts/heuristics.py +1135 -0
- package/skills/dart-flutter-review/scripts/review.sh +440 -0
- package/skills/dart-naming/SKILL.md +208 -0
- package/skills/dart-naming/references/naming.md +522 -0
- package/skills/flutter-accessibility/SKILL.md +211 -0
- package/skills/flutter-accessibility/references/placement-by-architecture.md +185 -0
- package/skills/flutter-accessibility/references/review.md +92 -0
- package/skills/flutter-accessibility/references/rules.md +306 -0
- package/skills/flutter-accessibility/references/semantics-and-labels.md +187 -0
- package/skills/flutter-accessibility/references/testing-accessibility.md +152 -0
- package/skills/flutter-accessibility/references/visual-and-input.md +148 -0
- package/skills/flutter-accessibility/scripts/check_accessibility.py +1411 -0
- package/skills/flutter-adaptive-layout/SKILL.md +239 -0
- package/skills/flutter-adaptive-layout/references/input-and-platform.md +221 -0
- package/skills/flutter-adaptive-layout/references/placement-by-architecture.md +86 -0
- package/skills/flutter-adaptive-layout/references/review.md +98 -0
- package/skills/flutter-adaptive-layout/references/rules.md +502 -0
- package/skills/flutter-adaptive-layout/references/size-classes-and-layout.md +326 -0
- package/skills/flutter-adaptive-layout/references/testing-adaptive-layouts.md +158 -0
- package/skills/flutter-adaptive-layout/scripts/check_adaptive.py +1743 -0
- package/skills/flutter-architecture/SKILL.md +276 -0
- package/skills/flutter-architecture/references/anti-patterns/data-and-repositories.md +264 -0
- package/skills/flutter-architecture/references/anti-patterns/dependency-rule.md +314 -0
- package/skills/flutter-architecture/references/anti-patterns/di-and-globals.md +105 -0
- package/skills/flutter-architecture/references/anti-patterns/over-engineering.md +140 -0
- package/skills/flutter-architecture/references/anti-patterns/pattern-specific.md +473 -0
- package/skills/flutter-architecture/references/anti-patterns/presentation.md +411 -0
- package/skills/flutter-architecture/references/anti-patterns/state.md +348 -0
- package/skills/flutter-architecture/references/anti-patterns.md +195 -0
- package/skills/flutter-architecture/references/bloc.md +339 -0
- package/skills/flutter-architecture/references/clean-architecture.md +270 -0
- package/skills/flutter-architecture/references/detect.md +310 -0
- package/skills/flutter-architecture/references/mvc.md +249 -0
- package/skills/flutter-architecture/references/mvn.md +377 -0
- package/skills/flutter-architecture/references/mvvm.md +319 -0
- package/skills/flutter-architecture/references/repository-pattern.md +215 -0
- package/skills/flutter-architecture/references/state-management.md +190 -0
- package/skills/flutter-architecture/scripts/arch_check.py +2546 -0
- package/skills/flutter-design-system/SKILL.md +208 -0
- package/skills/flutter-design-system/references/components-and-placement.md +240 -0
- package/skills/flutter-design-system/references/review.md +92 -0
- package/skills/flutter-design-system/references/rules.md +438 -0
- package/skills/flutter-design-system/references/tokens-and-theming.md +338 -0
- package/skills/flutter-design-system/scripts/check_design_system.py +1517 -0
- package/skills/flutter-error-handling/SKILL.md +190 -0
- package/skills/flutter-error-handling/references/error-flow-by-architecture.md +646 -0
- package/skills/flutter-error-handling/references/global-handlers.md +246 -0
- package/skills/flutter-error-handling/references/result-vs-exceptions.md +302 -0
- package/skills/flutter-error-handling/references/review.md +85 -0
- package/skills/flutter-error-handling/references/rules.md +823 -0
- package/skills/flutter-error-handling/scripts/check_errors.py +2005 -0
- package/skills/flutter-feature-scaffold/SKILL.md +219 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc.dart.tmpl +44 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/bloc_test.dart.tmpl +41 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/event.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/state.dart.tmpl +37 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/view.dart.tmpl +55 -0
- package/skills/flutter-feature-scaffold/assets/templates/bloc/view_test.dart.tmpl +29 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/data_source.dart.tmpl +28 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/dto.dart.tmpl +24 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/entity.dart.tmpl +18 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/repository.dart.tmpl +6 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl.dart.tmpl +26 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/repository_impl_test.dart.tmpl +60 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/usecase.dart.tmpl +13 -0
- package/skills/flutter-feature-scaffold/assets/templates/clean/usecase_test.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/core/failure.dart.tmpl +24 -0
- package/skills/flutter-feature-scaffold/assets/templates/core/http_client.dart.tmpl +35 -0
- package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit.dart.tmpl +29 -0
- package/skills/flutter-feature-scaffold/assets/templates/cubit/cubit_test.dart.tmpl +41 -0
- package/skills/flutter-feature-scaffold/assets/templates/cubit/view.dart.tmpl +52 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/api_client.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/binding.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/controller.dart.tmpl +34 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/controller_test.dart.tmpl +42 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/state.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/getx/view.dart.tmpl +38 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/entity.dart.tmpl +9 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier.dart.tmpl +25 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/notifier_test.dart.tmpl +56 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/repository.dart.tmpl +5 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl.dart.tmpl +32 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/repository_impl_test.dart.tmpl +58 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/request.dart.tmpl +10 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/response.dart.tmpl +20 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/source.dart.tmpl +32 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/state.dart.tmpl +28 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/usecase_test.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/view.dart.tmpl +52 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/view_test.dart.tmpl +34 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvn/widget.dart.tmpl +19 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_client.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/api_model.dart.tmpl +20 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/command.dart.tmpl +66 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository.dart.tmpl +7 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl.dart.tmpl +23 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/repository_impl_test.dart.tmpl +54 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/result.dart.tmpl +33 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase.dart.tmpl +15 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/usecase_test.dart.tmpl +22 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/view.dart.tmpl +47 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/view_test.dart.tmpl +27 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel.dart.tmpl +32 -0
- package/skills/flutter-feature-scaffold/assets/templates/mvvm/viewmodel_test.dart.tmpl +64 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/notifier.dart.tmpl +41 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/notifier_test.dart.tmpl +44 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/state.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/view.dart.tmpl +39 -0
- package/skills/flutter-feature-scaffold/assets/templates/provider/view_test.dart.tmpl +30 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier.dart.tmpl +23 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/notifier_test.dart.tmpl +55 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/providers.dart.tmpl +24 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/view.dart.tmpl +45 -0
- package/skills/flutter-feature-scaffold/assets/templates/riverpod/view_test.dart.tmpl +31 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/list.dart.tmpl +21 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/model.dart.tmpl +27 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/repository.dart.tmpl +6 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl.dart.tmpl +25 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/repository_impl_test.dart.tmpl +59 -0
- package/skills/flutter-feature-scaffold/assets/templates/shared/source.dart.tmpl +28 -0
- package/skills/flutter-feature-scaffold/references/profiles.md +145 -0
- package/skills/flutter-feature-scaffold/scripts/scaffold.py +1069 -0
- package/skills/flutter-firebase/SKILL.md +256 -0
- package/skills/flutter-firebase/references/firestore-data.md +178 -0
- package/skills/flutter-firebase/references/placement-by-architecture.md +309 -0
- package/skills/flutter-firebase/references/review.md +109 -0
- package/skills/flutter-firebase/references/rules.md +636 -0
- package/skills/flutter-firebase/references/security-rules-and-app-check.md +226 -0
- package/skills/flutter-firebase/references/setup-messaging-config.md +169 -0
- package/skills/flutter-firebase/references/testing-firebase.md +157 -0
- package/skills/flutter-firebase/scripts/check_firebase.py +2155 -0
- package/skills/flutter-forms/SKILL.md +191 -0
- package/skills/flutter-forms/references/multi-step-and-dirty-state.md +190 -0
- package/skills/flutter-forms/references/placement-by-architecture.md +326 -0
- package/skills/flutter-forms/references/review.md +88 -0
- package/skills/flutter-forms/references/rules.md +238 -0
- package/skills/flutter-forms/references/secure-inputs.md +256 -0
- package/skills/flutter-forms/references/validation-patterns.md +285 -0
- package/skills/flutter-forms/scripts/check_forms.py +1278 -0
- package/skills/flutter-i18n/SKILL.md +241 -0
- package/skills/flutter-i18n/references/formatting.md +174 -0
- package/skills/flutter-i18n/references/gen-l10n-and-arb.md +315 -0
- package/skills/flutter-i18n/references/placement-by-architecture.md +460 -0
- package/skills/flutter-i18n/references/review.md +93 -0
- package/skills/flutter-i18n/references/rtl-and-arabic.md +367 -0
- package/skills/flutter-i18n/scripts/check_i18n.py +1805 -0
- package/skills/flutter-navigation/SKILL.md +199 -0
- package/skills/flutter-navigation/references/deep-links-and-security.md +242 -0
- package/skills/flutter-navigation/references/go-router-patterns.md +361 -0
- package/skills/flutter-navigation/references/placement-by-architecture.md +414 -0
- package/skills/flutter-navigation/references/review.md +102 -0
- package/skills/flutter-navigation/references/rules.md +256 -0
- package/skills/flutter-navigation/scripts/check_navigation.py +1424 -0
- package/skills/flutter-networking/SKILL.md +202 -0
- package/skills/flutter-networking/references/client-setup.md +180 -0
- package/skills/flutter-networking/references/dtos-and-json.md +114 -0
- package/skills/flutter-networking/references/placement-by-architecture.md +147 -0
- package/skills/flutter-networking/references/requests.md +160 -0
- package/skills/flutter-networking/references/review.md +94 -0
- package/skills/flutter-networking/references/rules.md +487 -0
- package/skills/flutter-networking/references/testing-with-fakes.md +137 -0
- package/skills/flutter-networking/scripts/check_networking.py +1607 -0
- package/skills/flutter-performance/SKILL.md +219 -0
- package/skills/flutter-performance/references/diagnosing-jank.md +134 -0
- package/skills/flutter-performance/references/isolates.md +105 -0
- package/skills/flutter-performance/references/lists-images-painting.md +116 -0
- package/skills/flutter-performance/references/rebuild-scope.md +154 -0
- package/skills/flutter-performance/references/review.md +93 -0
- package/skills/flutter-performance/references/rules.md +400 -0
- package/skills/flutter-performance/scripts/check_performance.py +1360 -0
- package/skills/flutter-persistence/SKILL.md +198 -0
- package/skills/flutter-persistence/references/caching-and-offline.md +169 -0
- package/skills/flutter-persistence/references/choosing-storage.md +188 -0
- package/skills/flutter-persistence/references/migrations.md +201 -0
- package/skills/flutter-persistence/references/placement-by-architecture.md +232 -0
- package/skills/flutter-persistence/references/review.md +93 -0
- package/skills/flutter-persistence/references/rules.md +405 -0
- package/skills/flutter-persistence/scripts/check_persistence.py +1690 -0
- package/skills/flutter-platform-integration/SKILL.md +219 -0
- package/skills/flutter-platform-integration/references/channels-and-pigeon.md +194 -0
- package/skills/flutter-platform-integration/references/ffi.md +147 -0
- package/skills/flutter-platform-integration/references/permissions-and-isolates.md +124 -0
- package/skills/flutter-platform-integration/references/placement-by-architecture.md +102 -0
- package/skills/flutter-platform-integration/references/plugins-and-platform-views.md +129 -0
- package/skills/flutter-platform-integration/references/review.md +94 -0
- package/skills/flutter-platform-integration/references/rules.md +557 -0
- package/skills/flutter-platform-integration/references/testing-platform-code.md +125 -0
- package/skills/flutter-platform-integration/scripts/check_platform.py +1824 -0
- package/skills/flutter-release/SKILL.md +219 -0
- package/skills/flutter-release/references/ci-cd.md +156 -0
- package/skills/flutter-release/references/flavors-and-environments.md +127 -0
- package/skills/flutter-release/references/release-checklist.md +79 -0
- package/skills/flutter-release/references/review.md +91 -0
- package/skills/flutter-release/references/rules.md +417 -0
- package/skills/flutter-release/references/signing-and-versioning.md +113 -0
- package/skills/flutter-release/references/store-requirements.md +61 -0
- package/skills/flutter-release/scripts/check_release.py +1930 -0
- package/skills/flutter-secure-defaults/SKILL.md +270 -0
- package/skills/flutter-secure-defaults/references/network-and-auth.md +203 -0
- package/skills/flutter-secure-defaults/references/review.md +103 -0
- package/skills/flutter-secure-defaults/references/rules.md +452 -0
- package/skills/flutter-secure-defaults/references/secrets-and-config.md +136 -0
- package/skills/flutter-secure-defaults/references/secure-defaults-by-layer.md +474 -0
- package/skills/flutter-secure-defaults/references/secure-scaffold-checklist.md +147 -0
- package/skills/flutter-secure-defaults/references/storage-and-privacy.md +161 -0
- package/skills/flutter-secure-defaults/references/webview-and-links.md +153 -0
- package/skills/flutter-secure-defaults/scripts/check_secure_defaults.py +1571 -0
- package/skills/flutter-testing/SKILL.md +197 -0
- package/skills/flutter-testing/references/review.md +71 -0
- package/skills/flutter-testing/references/strategy-by-architecture.md +491 -0
- package/skills/flutter-testing/references/test-smells.md +475 -0
- package/skills/flutter-testing/references/widget-and-golden.md +337 -0
- package/skills/flutter-testing/scripts/test_gaps.py +1268 -0
- package/skills/flutter-ui-practices/SKILL.md +158 -0
- package/skills/flutter-ui-practices/references/flutter-ui.md +282 -0
- 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`.
|