feat: rules routing over official sync + flutter env setup skill (#21)

Wreos · web-flow · commit 83dc264111f5 · 2026-02-21T21:19:37.000-08:00
* feat: route official flutter rules via priority policy and add env setup skill

* chore: simplify command prompts by removing repeated guardrails

* chore: bump plugin version to 1.10.5 for api surface changes
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "flutter-cursor-plugin",
   "displayName": "Flutter Cursor Plugin",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "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",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,13 @@
   - `.github/workflows/semantic-quality.yml`
   - `docs/semantic-quality-gates.md`
 - Updated scaffold architecture guidance to prefer existing project state-management convention before selecting a pattern.
+- Reworked official Flutter AI rules integration to use policy routing instead of post-sync text patching:
+  - added high-priority policy layer `rules/flutter-plugin-policy-priority.mdc`
+  - kept synced upstream profiles as base source of truth
+- Added deterministic environment setup workflow:
+  - command: `commands/setup-flutter-environment.md`
+  - skill: `skills/setup-flutter-environment/SKILL.md`
+- Simplified command prompts by removing repeated guardrails boilerplate from canonical command files.
 
 ## 1.10.0
 
diff --git a/README.md b/README.md
@@ -97,6 +97,7 @@ Reference project layout:
   - `update-flutter-dependencies`
   - `prepare-mobile-release`
   - `setup-mobile-github-pipeline`
+  - `setup-flutter-environment`
   - `integrate-firebase`
   - `security-review`
   - `sync-official-flutter-ai-rules`
@@ -107,6 +108,7 @@ Reference project layout:
   - `rules/flutter-development-best-practices.mdc`
   - `rules/dart-effective-dart.mdc`
   - `rules/flutter-test-best-practices.mdc`
+  - `rules/flutter-plugin-policy-priority.mdc`
 - **Skills**
   - `skills/build-flutter-features/`
   - `skills/scaffold-flutter-architecture/`
@@ -119,6 +121,7 @@ Reference project layout:
   - `skills/update-flutter-dependencies/`
   - `skills/security-audit/`
   - `skills/sync-official-flutter-ai-rules/`
+  - `skills/setup-flutter-environment/`
 
 ## MCP integrations
 
@@ -127,6 +130,7 @@ Reference project layout:
 - **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.
+- **Rule priority routing**: `rules/flutter-plugin-policy-priority.mdc` is the high-priority policy layer over synced official rules.
 
 ## Official documentation
 
@@ -185,6 +189,8 @@ Reference project layout:
    - `docs/release-automation.md`
 14. For command namespacing/aliases (`flutter:*`), see:
    - `docs/command-namespacing.md`
+15. For deterministic local setup and SDK/MCP readiness, use:
+   - `setup-flutter-environment`
 
 Note: every code review flow includes mandatory security checks (OWASP MASVS-oriented).
 
@@ -200,3 +206,4 @@ Note: every code review flow includes mandatory security checks (OWASP MASVS-ori
 8. GitHub Actions mobile CI pipeline setup for APK/AAB build automation.
 9. Security audit and secrets scanner workflow via `/security-review`.
 10. Safe Flutter/Dart dependency upgrades with deterministic validation and rollback.
+11. Deterministic environment bootstrapping for Flutter SDK, MCP, and baseline checks.
diff --git a/commands/flutter-setup-flutter-environment.md b/commands/flutter-setup-flutter-environment.md
@@ -0,0 +1,10 @@
+---
+name: flutter:setup-flutter-environment
+description: Alias for `setup-flutter-environment`. Prepare and verify Flutter development environment (SDK, doctor, MCP, and baseline repo checks).
+---
+
+Namespaced alias for `setup-flutter-environment`.
+
+1. Run the canonical command with the same intent.
+2. Follow `./setup-flutter-environment.md`.
+3. Keep output and checks identical to the canonical command.
diff --git a/commands/generate-flutter-tests.md b/commands/generate-flutter-tests.md
@@ -10,6 +10,3 @@ Generate tests for the target feature or class.
 3. Keep tests behavior-driven and deterministic.
 4. Prefer focused tests for changed code paths.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/implement-figma-screen.md b/commands/implement-figma-screen.md
@@ -13,6 +13,3 @@ Implement a Flutter UI from Figma source.
 6. Add widget tests for critical interactions and visible states.
 7. If no Figma URL/node is provided, stop and request it before implementation.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/implement-flutter-feature.md b/commands/implement-flutter-feature.md
@@ -12,6 +12,3 @@ Implement or refactor a Flutter feature.
 5. Keep dependencies injected and testable.
 6. Add/update tests for modified behavior.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/integrate-firebase.md b/commands/integrate-firebase.md
@@ -11,6 +11,3 @@ Integrate Firebase into the target Flutter app.
 4. Complete `../docs/firebase-integration-checklist.md`.
 5. Verify Android and iOS initialization in release-capable configuration.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/migrate-flutter-code.md b/commands/migrate-flutter-code.md
@@ -11,6 +11,3 @@ Run a migration/refactor task.
 4. Use Dart MCP diagnostics to validate each step.
 5. Add or update tests for behavioral changes.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/prepare-mobile-release.md b/commands/prepare-mobile-release.md
@@ -11,6 +11,3 @@ Prepare app for store publication.
 4. Produce iOS release artifact (`.ipa`/archive) and validate signing/versioning.
 5. Confirm store metadata/compliance inputs are complete before submission.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/resolve-flutter-build-error.md b/commands/resolve-flutter-build-error.md
@@ -12,6 +12,3 @@ Resolve a build or runtime failure.
 5. Document root cause and prevention notes.
 6. Always report: reproduction command, root cause, and post-fix verification command output.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/review-flutter-code.md b/commands/review-flutter-code.md
@@ -14,6 +14,3 @@ Run structured Flutter code review.
 7. Include testing and accessibility checks.
 8. If no review target is provided (PR/diff/files), stop and request explicit scope.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/scaffold-flutter-feature.md b/commands/scaffold-flutter-feature.md
@@ -11,6 +11,3 @@ Create a new feature module scaffold.
 4. Build minimal complete skeleton first (UI + state + data boundaries).
 5. Add starter tests with `write-widget-test` / `write-bloc-test`.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/security-review.md b/commands/security-review.md
@@ -15,6 +15,3 @@ Run a security audit and secrets scan (Claude-style `/security-review` workflow)
 8. If target scope (diff/branch/files) is missing, stop and ask for explicit scope.
 9. If scanners are unavailable, report that explicitly and continue with manual checks.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/setup-flutter-environment.md b/commands/setup-flutter-environment.md
@@ -0,0 +1,12 @@
+---
+name: setup-flutter-environment
+description: Prepare and verify Flutter development environment (SDK, doctor, MCP, and baseline repo checks).
+---
+
+Set up and validate Flutter environment before development work.
+
+1. Follow `../skills/setup-flutter-environment/SKILL.md`.
+2. Capture `flutter --version`, `dart --version`, and `flutter doctor -v`.
+3. Verify Dart MCP availability with `dart mcp-server --help`.
+4. Run repository baseline validations after setup changes.
+
diff --git a/commands/setup-mobile-github-pipeline.md b/commands/setup-mobile-github-pipeline.md
@@ -11,6 +11,3 @@ Set up a mobile CI pipeline in GitHub Actions.
 4. Ensure pipeline runs analyze/tests before building artifacts.
 5. Validate generated APK/AAB artifacts and branch trigger strategy.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/sync-official-flutter-ai-rules.md b/commands/sync-official-flutter-ai-rules.md
@@ -12,7 +12,5 @@ Sync official Flutter AI rules into the plugin repository.
    - `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`.
+5. Keep plugin policy in `rules/flutter-plugin-policy-priority.mdc` (do not patch synced official content).
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/update-flutter-dependencies.md b/commands/update-flutter-dependencies.md
@@ -11,6 +11,3 @@ Run a controlled dependency upgrade.
 4. Document version deltas, breaking changes, and rollback plan.
 5. Always include this baseline in validation: `flutter --version` (before/after), `flutter pub outdated`, `flutter analyze`, and impacted `flutter test`.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/write-bloc-test.md b/commands/write-bloc-test.md
@@ -11,6 +11,3 @@ Create or update a Bloc/Cubit test file.
 4. Start from `../templates/bloc_test_template.dart`.
 5. Run affected tests and fix failures.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/write-e2e-test.md b/commands/write-e2e-test.md
@@ -14,6 +14,3 @@ Create or update a Patrol E2E test.
 7. Keep credentials in `--dart-define` / `.patrol.env` (no hardcoded secrets).
 8. Run affected Patrol tests and fix failures.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/commands/write-widget-test.md b/commands/write-widget-test.md
@@ -12,6 +12,3 @@ Create or update a widget test file.
 5. Prefer behavioral assertions (user action -> observable outcome, branch shown/hidden, verify side effects), not only style attributes.
 6. Run affected tests and fix failures.
 
-Preconditions and guardrails:
-- Enforce `../docs/prompt-execution-guardrails.md` before execution.
-- Validate outcomes using `../docs/validation-matrix.md`.
diff --git a/docs/flutter-ai-rules-sync.md b/docs/flutter-ai-rules-sync.md
@@ -1,10 +1,10 @@
 # Official Flutter AI Rules Sync
 
-This document explains how to sync and use official Flutter AI rules in this plugin.
+This document explains how to sync and route 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.
+Flutter publishes official AI rules in multiple sizes. This repository keeps a synced copy and exposes an active profile, then applies plugin policy via a separate higher-priority routing layer.
 
 ## Profiles
 
@@ -32,6 +32,14 @@ scripts/sync_official_flutter_ai_rules.sh 4k
 - `rules/official/flutter-ai-rules-4k.mdc`
 - `rules/official/flutter-ai-rules-1k.mdc`
 - `rules/flutter-official-ai-rules.mdc` (active profile copy)
+- `rules/flutter-plugin-policy-priority.mdc` (high-priority policy routing layer)
+
+## Routing and precedence
+
+- Official Flutter rules are synced as-is and used as the base.
+- Plugin policy is defined separately in `rules/flutter-plugin-policy-priority.mdc`.
+- If official guidance conflicts with plugin policy, plugin policy wins.
+- Do not patch official text in sync scripts to enforce plugin policy.
 
 ## Upstream sources
 
diff --git a/plugin.json b/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "flutter-cursor-plugin",
   "displayName": "Flutter Cursor Plugin",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "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",
diff --git a/rules/flutter-official-ai-rules.mdc b/rules/flutter-official-ai-rules.mdc
@@ -26,9 +26,9 @@ Do not edit manually; run scripts/sync_official_flutter_ai_rules.sh.
 * **SOLID:** strictly enforced.
 * **State Management:**
   * **Pattern:** Separate UI state (ephemeral) from App state.
-  * **Project First:** Follow the existing project architecture and state-management choice.
-  * **Selection:** Use Riverpod/Bloc/Cubit/GetX/ValueNotifier based on project conventions, complexity, and team standards.
-  * **DI:** Keep dependencies explicit via constructor injection or project-standard DI.
+  * **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).
diff --git a/rules/flutter-plugin-policy-priority.mdc b/rules/flutter-plugin-policy-priority.mdc
@@ -0,0 +1,24 @@
+---
+description: High-priority plugin policy routing layer that overrides conflicting lower-priority guidance.
+alwaysApply: true
+globs: ["lib/**/*.dart", "test/**/*.dart", "**/*.dart"]
+---
+
+# Flutter Plugin Policy Priority
+
+This file is the high-priority policy layer for this plugin.
+
+## Rule routing
+
+- Base guidance: `rules/flutter-official-ai-rules.mdc` (synced from upstream Flutter profiles).
+- Project policy: this file and other plugin-level rule files.
+- Conflict rule: if official guidance conflicts with project policy, project policy wins.
+- Do not patch synced official files to enforce project policy.
+
+## Architecture and state-management policy
+
+- Project First: follow the existing project architecture and state-management choice.
+- Keep state management consistent with established conventions in the target codebase.
+- Riverpod, Bloc, Cubit, GetX, and ValueNotifier are all allowed when justified by project context.
+- If no convention exists, pick the simplest viable architecture and document the rationale.
+- Keep dependencies explicit via constructor injection or project-standard DI.
diff --git a/scripts/sync_official_flutter_ai_rules.sh b/scripts/sync_official_flutter_ai_rules.sh
@@ -66,9 +66,7 @@ awk '
   { print }
 ' "${out_dir}/flutter-ai-rules-${profile}.mdc" > "${active_rule}"
 
-# Align active profile with plugin policy: pick state management by project context.
-perl -0pi -e 's/\* \*\*State Management:\*\*\n  \* \*\*Pattern:\*\* Separate UI state \(ephemeral\) from App state\.\n  \* \*\*Native First:\*\* Use `ValueNotifier`, `ChangeNotifier`\.\n  \* \*\*Prohibited:\*\* NO Riverpod, Bloc, GetX unless explicitly requested\.\n  \* \*\*DI:\*\* Manual constructor injection or `provider` package if requested\./* **State Management:**\n  * **Pattern:** Separate UI state (ephemeral) from App state.\n  * **Project First:** Follow the existing project architecture and state-management choice.\n  * **Selection:** Use Riverpod\/Bloc\/Cubit\/GetX\/ValueNotifier based on project conventions, complexity, and team standards.\n  * **DI:** Keep dependencies explicit via constructor injection or project-standard DI./s' "${active_rule}"
-
 echo "Synced official Flutter AI rules."
 echo "Selected active profile: ${profile}"
 echo "Active rule: rules/flutter-official-ai-rules.mdc"
+echo "Policy override routing: rules/flutter-plugin-policy-priority.mdc"
diff --git a/scripts/validate_prompt_semantics.sh b/scripts/validate_prompt_semantics.sh
@@ -33,6 +33,7 @@ canonical_commands=(
   "commands/migrate-flutter-code.md"
   "commands/scaffold-flutter-feature.md"
   "commands/setup-mobile-github-pipeline.md"
+  "commands/setup-flutter-environment.md"
   "commands/sync-official-flutter-ai-rules.md"
   "commands/write-widget-test.md"
   "commands/write-bloc-test.md"
@@ -41,9 +42,8 @@ canonical_commands=(
 
 for cmd_file in "${canonical_commands[@]}"; do
   base="$(basename "${cmd_file}")"
-  check "C-${base} has guardrails section" "rg -q '^Preconditions and guardrails:' '${cmd_file}'"
-  check "C-${base} references prompt guardrails doc" "rg -q 'prompt-execution-guardrails\\.md' '${cmd_file}'"
-  check "C-${base} references validation matrix" "rg -q 'validation-matrix\\.md' '${cmd_file}'"
+  check "C-${base} has command name frontmatter" "rg -q '^name:\\s*' '${cmd_file}'"
+  check "C-${base} has command description frontmatter" "rg -q '^description:\\s*' '${cmd_file}'"
 done
 
 for skill in skills/*/SKILL.md; do
@@ -59,8 +59,10 @@ for agent in agents/*.md; do
   check "A-${base} expects validation evidence" "rg -qi '(validation|commands and results|evidence)' '${agent}'"
 done
 
-check "Active Flutter rules are project-first for state management" "rg -q '\\* \\*\\*Project First:\\*\\* Follow the existing project architecture and state-management choice\\.' rules/flutter-official-ai-rules.mdc"
-check "Active Flutter rules do not prohibit Riverpod/Bloc/GetX outright" "! rg -q 'Prohibited:\\*\\* NO Riverpod, Bloc, GetX unless explicitly requested\\.' rules/flutter-official-ai-rules.mdc"
+check "Priority policy rule exists and is alwaysApply" "rg -q '^alwaysApply: true$' rules/flutter-plugin-policy-priority.mdc"
+check "Priority policy enforces project-first state management" "rg -q 'Project First: follow the existing project architecture and state-management choice\\.' rules/flutter-plugin-policy-priority.mdc"
+check "Priority policy allows Bloc/Riverpod style choices by project context" "rg -q 'Riverpod, Bloc, Cubit, GetX, and ValueNotifier are all allowed when justified by project context\\.' rules/flutter-plugin-policy-priority.mdc"
+check "Sync script does not patch official state-management text" "! rg -q 'Prohibited:\\*\\* NO Riverpod, Bloc, GetX unless explicitly requested\\.' scripts/sync_official_flutter_ai_rules.sh"
 check "Scaffold architecture skill enforces project-first state-management selection" "rg -q 'existing project state-management convention' skills/scaffold-flutter-architecture/SKILL.md"
 
 total=$((pass_count + fail_count))
diff --git a/skills/setup-flutter-environment/SKILL.md b/skills/setup-flutter-environment/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: setup-flutter-environment
+description: Prepare a deterministic Flutter development environment with SDK/tooling verification, MCP readiness, and baseline validation commands.
+---
+
+# Setup Flutter Environment
+
+Use this skill when a project needs a clean, reproducible Flutter setup before implementation, testing, or release work.
+
+## Workflow
+
+1. Check installed toolchain versions:
+   - `flutter --version`
+   - `dart --version`
+2. Run environment diagnostics:
+   - `flutter doctor -v`
+3. Resolve blocking setup gaps:
+   - Android licenses (`flutter doctor --android-licenses`) when Android is required.
+   - Xcode CLI tools/simulator notes when iOS/macOS is required.
+4. Verify MCP availability:
+   - `dart mcp-server --help`
+5. Ensure plugin-level setup files are present and valid:
+   - `mcp.json`
+   - `.cursor/settings.json` plugin enablement (if required by local workflow).
+6. Run repository validation commands when available (for this plugin repo):
+   - `./scripts/validate_agents_skills.sh`
+   - `./scripts/validate_prompt_semantics.sh`
+
+## Guardrails
+
+- Do not claim setup is complete while `flutter doctor` still has unresolved blockers for requested target platforms.
+- Keep setup changes minimal and reversible; avoid unrelated dependency upgrades.
+- If a required platform is out of scope (for example iOS on a non-iOS task), report it explicitly instead of forcing changes.
+
+## Required output
+
+1. Detected Flutter/Dart versions.
+2. `flutter doctor` summary with unresolved blockers.
+3. MCP availability result.
+4. Commands executed and pass/fail status.
+5. Next actions required from the user (if any manual steps remain).
diff --git a/skills/sync-official-flutter-ai-rules/SKILL.md b/skills/sync-official-flutter-ai-rules/SKILL.md

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "flutter-cursor-plugin",`
`3`	`3`	`"displayName": "Flutter Cursor Plugin",`
`4`		`- "version": "1.10.4",`
	`4`	`+ "version": "1.10.5",`
`5`	`5`	`"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.",`
`6`	`6`	`"author": {`
`7`	`7`	`"name": "Aleksandr Lozhkovoi",`