feat: sync official Flutter AI rules profiles (#10)

* feat: sync official Flutter AI rules profiles

* fix: make API guard runner-compatible and fix AI docs link

---------

Co-authored-by: Aleksandr Lozhkovoi <aleksandr.lozhkovoi@enpal.de>

Author: Wreos

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "flutter-cursor-plugin",
   "displayName": "Flutter Cursor Plugin",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Open-source Cursor plugin for end-to-end Flutter development and testing with Dart MCP, Figma MCP, practical architecture patterns, and reliable test workflows.",
   "author": {
     "name": "Aleksandr Lozhkovoi",

.github/scripts/api_stability_guard.sh

@@ -41,13 +41,13 @@ if [[ "${head_root_version}" == "${base_root_version}" && "${head_canonical_vers
   exit 1
 fi
 
-if ! git diff --name-only "${diff_range}" | rg -q '^CHANGELOG\.md$'; then
+if ! git diff --name-only "${diff_range}" | grep -Eq '^CHANGELOG\.md$'; then
   echo "API surface changed but CHANGELOG.md was not updated."
   exit 1
 fi
 
 breaking_change=false
-if echo "${api_name_status}" | rg -q '^(D|R[0-9]*)\s'; then
+if echo "${api_name_status}" | grep -Eq '^(D|R[0-9]+)[[:space:]]'; then
   breaking_change=true
 fi
 
@@ -81,7 +81,7 @@ if [[ "${breaking_change}" == true ]]; then
     exit 1
   fi
 
-  if ! git diff -U0 "${diff_range}" -- CHANGELOG.md | rg -qi '^\+.*breaking'; then
+  if ! git diff -U0 "${diff_range}" -- CHANGELOG.md | grep -Eiq '^\+.*breaking'; then
     echo "Breaking API change detected; add a CHANGELOG line that includes the word 'breaking'."
     exit 1
   fi

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- Added official Flutter AI rules sync workflow:
+  - command: `commands/sync-official-flutter-ai-rules.md`
+  - skill: `skills/sync-official-flutter-ai-rules/SKILL.md`
+  - docs: `docs/flutter-ai-rules-sync.md`
+  - sync script: `scripts/sync_official_flutter_ai_rules.sh`
+- Added synced official Flutter AI rules profiles:
+  - `rules/official/flutter-ai-rules-10k.mdc`
+  - `rules/official/flutter-ai-rules-4k.mdc`
+  - `rules/official/flutter-ai-rules-1k.mdc`
+  - active: `rules/flutter-official-ai-rules.mdc`
 - Added dedicated security posture documentation (`docs/security-posture.md`) with `/security-review` scope, false-positive handling, and CI integration guidance.
 - Added a "Value in 5 minutes" demo section to `README.md` with one-prompt flow and three copy-ready scenarios.
 - Added visual demo artifact `assets/demo-5min-flow.svg` for quick onboarding value proof.

README.md

@@ -87,6 +87,7 @@ Three ready-to-run scenarios:
   - `setup-mobile-github-pipeline`
   - `integrate-firebase`
   - `security-review`
+  - `sync-official-flutter-ai-rules`
   - `write-widget-test`
   - `write-bloc-test`
   - `write-e2e-test`
@@ -105,13 +106,15 @@ Three ready-to-run scenarios:
   - `skills/migrate-flutter-code/`
   - `skills/update-flutter-dependencies/`
   - `skills/security-audit/`
+  - `skills/sync-official-flutter-ai-rules/`
 
 ## MCP integrations
 
 - **Dart MCP**: use for analysis, fix suggestions, formatting guidance, and project-aware Dart/Flutter workflows.
 - **Figma MCP**: use when translating Figma nodes/screens to Flutter UI with higher visual fidelity.
 - **Effective Dart**: align implementation with the official guidance at https://dart.dev/effective-dart.
 - **Claude `/security-review` parity**: security workflow mirrors `anthropics/claude-code-security-review` patterns (diff-aware + false-positive filtering).
+- **Official Flutter AI rules sync**: use `sync-official-flutter-ai-rules` to refresh upstream Flutter rules profiles.
 
 ## Official documentation
 
@@ -123,6 +126,7 @@ Three ready-to-run scenarios:
 - Claude Code Security Review: https://github.com/anthropics/claude-code-security-review
 - Cursor plugin schema: https://raw.githubusercontent.com/cursor/plugins/main/schemas/plugin.schema.json
 - Flutter MCP server docs: https://docs.flutter.dev/ai/mcp-server
+- Flutter AI docs: https://docs.flutter.dev/ai
 
 ## Requirements
 
@@ -161,6 +165,9 @@ Three ready-to-run scenarios:
    - `docs/dependency-upgrade-checklist.md`
 11. For monorepo/workspace setups, follow:
    - `docs/monorepo-workspace-guide.md`
+12. To sync official Flutter AI rules profiles (`10k`/`4k`/`1k`), use:
+   - `sync-official-flutter-ai-rules`
+   - `docs/flutter-ai-rules-sync.md`
 
 Note: every code review flow includes mandatory security checks (OWASP MASVS-oriented).
 

commands/sync-official-flutter-ai-rules.md

@@ -0,0 +1,14 @@
+---
+name: sync-official-flutter-ai-rules
+description: Sync official Flutter AI rules from Flutter upstream and select active profile (10k, 4k, 1k).
+---
+
+Sync official Flutter AI rules into the plugin repository.
+
+1. Follow `../skills/sync-official-flutter-ai-rules/SKILL.md`.
+2. Pick profile by context size:
+   - `10k` for maximum guidance depth.
+   - `4k` for balanced detail and token usage.
+   - `1k` for minimal and fast context.
+3. Run `scripts/sync_official_flutter_ai_rules.sh <10k|4k|1k>`.
+4. Commit synced files under `rules/official/` and active file `rules/flutter-official-ai-rules.mdc`.

docs/flutter-ai-rules-sync.md

@@ -0,0 +1,41 @@
+# Official Flutter AI Rules Sync
+
+This document explains how to sync and use official Flutter AI rules in this plugin.
+
+## Why this exists
+
+Flutter publishes official AI rules in multiple sizes. This repository keeps a synced copy and exposes an active profile.
+
+## Profiles
+
+- `10k`: full and most detailed profile.
+- `4k`: balanced profile (recommended default).
+- `1k`: compact profile for constrained contexts.
+
+## Sync command
+
+Run from repository root:
+
+```bash
+scripts/sync_official_flutter_ai_rules.sh <10k|4k|1k>
+```
+
+Example:
+
+```bash
+scripts/sync_official_flutter_ai_rules.sh 4k
+```
+
+## Generated files
+
+- `rules/official/flutter-ai-rules-10k.mdc`
+- `rules/official/flutter-ai-rules-4k.mdc`
+- `rules/official/flutter-ai-rules-1k.mdc`
+- `rules/flutter-official-ai-rules.mdc` (active profile copy)
+
+## Upstream sources
+
+- https://raw.githubusercontent.com/flutter/flutter/main/docs/rules/rules_10k.md
+- https://raw.githubusercontent.com/flutter/flutter/main/docs/rules/rules_4k.md
+- https://raw.githubusercontent.com/flutter/flutter/main/docs/rules/rules_1k.md
+- https://docs.flutter.dev/ai

docs/official-release-checklist.md

@@ -19,6 +19,7 @@ Use this checklist before tagging a public release.
 
 - Dart MCP workflow is documented and referenced by relevant agents/commands.
 - Figma MCP workflow is documented for UI implementation paths.
+- Official Flutter AI rules sync workflow is documented (`docs/flutter-ai-rules-sync.md`).
 
 ## Open source readiness
 

plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "flutter-cursor-plugin",
   "displayName": "Flutter Cursor Plugin",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Open-source Cursor plugin for end-to-end Flutter development and testing with Dart MCP, Figma MCP, practical architecture patterns, and reliable test workflows.",
   "author": "Aleksandr Lozhkovoi",
   "license": "MIT",

rules/flutter-official-ai-rules.mdc

@@ -0,0 +1,87 @@
+<!--
+Synced from official Flutter AI rules.
+Source: https://raw.githubusercontent.com/flutter/flutter/main/docs/rules/rules_4k.md
+Profile: 4k
+Do not edit manually; run scripts/sync_official_flutter_ai_rules.sh.
+-->
+
+# AI Rules for Flutter
+
+## Persona & Tools
+* **Role:** Expert Flutter Developer. Focus: Beautiful, performant, maintainable code.
+* **Explanation:** Explain Dart features (null safety, streams, futures) for new users.
+* **Tools:** ALWAYS run `dart_format`. Use `dart_fix` for cleanups. Use `analyze_files` with `flutter_lints` to catch errors early.
+* **Dependencies:** Add with `flutter pub add`. Use `pub_dev_search` for discovery. Explain why a package is needed.
+
+## Architecture & Structure
+* **Entry:** Standard `lib/main.dart`.
+* **Layers:** Presentation (Widgets), Domain (Logic), Data (Repo/API).
+* **Features:** Group by feature (e.g., `lib/features/login/`) for scalable apps.
+* **SOLID:** strictly enforced.
+* **State Management:**
+  * **Pattern:** Separate UI state (ephemeral) from App state.
+  * **Native First:** Use `ValueNotifier`, `ChangeNotifier`.
+  * **Prohibited:** NO Riverpod, Bloc, GetX unless explicitly requested.
+  * **DI:** Manual constructor injection or `provider` package if requested.
+
+## Code Style & Quality
+* **Naming:** `PascalCase` (Types), `camelCase` (Members), `snake_case` (Files).
+* **Conciseness:** Functions <20 lines. Avoid verbosity.
+* **Null Safety:** NO `!` operator. Use `?` and flow analysis (e.g. `if (x != null)`).
+* **Async:** Use `async/await` for Futures. Catch all errors with `try-catch`.
+* **Logging:** Use `dart:developer` `log()` locally. NEVER use `print`.
+
+## Flutter Best Practices
+* **Build Methods:** Keep pure and fast. No side effects. No network calls.
+* **Isolates:** Use `compute()` for heavy tasks like JSON parsing.
+* **Lists:** `ListView.builder` or `SliverList` for performance.
+* **Immutability:** `const` constructors everywhere validation. `StatelessWidget` preference.
+* **Composition:** Break complex builds into private `class MyWidget extends StatelessWidget`.
+
+## Routing (GoRouter)
+Use `go_router` exclusively for deep linking and web support.
+
+```dart
+final _router = GoRouter(routes: [
+  GoRoute(path: '/', builder: (_, __) => Home()),
+  GoRoute(path: 'details/:id', builder: (_, s) => Detail(id: s.pathParameters['id']!)),
+]);
+MaterialApp.router(routerConfig: _router);
+```
+
+## Data (JSON)
+Use `json_serializable` with `fieldRename: FieldRename.snake`.
+
+```dart
+@JsonSerializable(fieldRename: FieldRename.snake)
+class User {
+  final String name;
+  User({required this.name});
+  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);
+}
+```
+
+## Visual Design (Material 3)
+* **Aesthetics:** Premium, custom look. "Wow" the user. Avoid default blue.
+* **Theme:** Use `ThemeData` with `ColorScheme.fromSeed`.
+* **Modes:** Support Light & Dark modes (`ThemeMode.system`).
+* **Typography:** `google_fonts`. Define a consistent Type Scale.
+* **Layout:** `LayoutBuilder` for responsiveness. `OverlayPortal` for popups.
+* **Components:** Use `ThemeExtension` for custom tokens (colors/sizes).
+
+## Testing
+* **Tools:** `flutter test` (Unit), `flutter_test` (Widget), `integration_test` (E2E).
+* **Mocks:** Prefer Fakes. Use `mockito` sparingly.
+* **Pattern:** Arrange-Act-Assert.
+* **Assertions:** Use `package:checks`.
+
+## Accessibility (A11Y)
+* **Contrast:** 4.5:1 minimum for text.
+* **Semantics:** Label all interactive elements specifically.
+* **Scale:** Test dynamic font sizes (up to 200%).
+* **Screen Readers:** Verify with TalkBack/VoiceOver.
+
+## Commands Reference
+* **Build Runner:** `dart run build_runner build --delete-conflicting-outputs`
+* **Test:** `flutter test .`
+* **Analyze:** `flutter analyze .`