From 8ac33ff372dbbe64a7eebd53e1fb60c6f8102b27 Mon Sep 17 00:00:00 2001 From: Aleksandr Lozhkovoi Date: Sat, 21 Feb 2026 22:16:20 +0100 Subject: [PATCH] chore: run 10-iteration quality audit and stabilize outputs --- .cursor-plugin/plugin.json | 2 +- CHANGELOG.md | 6 ++ README.md | 2 + commands/generate-flutter-tests.md | 2 + commands/implement-figma-screen.md | 2 + commands/implement-flutter-feature.md | 2 + commands/integrate-firebase.md | 2 + commands/migrate-flutter-code.md | 2 + commands/prepare-mobile-release.md | 2 + commands/resolve-flutter-build-error.md | 2 + commands/review-flutter-code.md | 2 + commands/scaffold-flutter-feature.md | 2 + commands/security-review.md | 2 + commands/setup-mobile-github-pipeline.md | 2 + commands/sync-official-flutter-ai-rules.md | 2 + commands/update-flutter-dependencies.md | 2 + commands/write-bloc-test.md | 2 + commands/write-e2e-test.md | 2 + commands/write-widget-test.md | 2 + docs/command-output-contract.md | 34 +++++++++ docs/official-release-checklist.md | 2 + docs/quality-iterations-2026-02-21.md | 22 ++++++ plugin.json | 2 +- scripts/quality_audit_commands.sh | 87 ++++++++++++++++++++++ 24 files changed, 187 insertions(+), 2 deletions(-) create mode 100644 docs/command-output-contract.md create mode 100644 docs/quality-iterations-2026-02-21.md create mode 100755 scripts/quality_audit_commands.sh diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index 5e23c20..ce6ea6a 100644 --- 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.0", + "version": "1.10.1", "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 index c7535d0..038d688 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## Unreleased +- Ran 10 command quality iterations and added reproducible audit: + - script: `scripts/quality_audit_commands.sh` + - report: `docs/quality-iterations-2026-02-21.md` +- Added shared output contract for deterministic command responses: + - `docs/command-output-contract.md` +- Updated all canonical commands to reference the output contract. - Added reference example repository for project structure and tests: - https://github.com/Wreos/flutter-cursor-plugin-example - Added pre-release enable guide (`docs/pre-release-enable-plugin.md`) with repository install and manual workspace settings options. diff --git a/README.md b/README.md index 105ea12..19fe90b 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,8 @@ Reference project layout: - **Release automation**: `docs/release-automation.md` for semver bump, changelog cut, tag, and GitHub Release publishing. - **Security posture**: `docs/security-posture.md` for `/security-review` scope, false-positive handling, and CI integration. - **Reference Flutter app layout**: https://github.com/Wreos/flutter-cursor-plugin-example +- **Output contract**: `docs/command-output-contract.md` for deterministic command response shape. +- **Quality iterations report**: `docs/quality-iterations-2026-02-21.md`. - **Agents** - `flutter-app-builder` (general Flutter implementation) - `flutter-code-reviewer` diff --git a/commands/generate-flutter-tests.md b/commands/generate-flutter-tests.md index 01261cb..3c79d55 100644 --- a/commands/generate-flutter-tests.md +++ b/commands/generate-flutter-tests.md @@ -9,3 +9,5 @@ Generate tests for the target feature or class. 2. Enforce `../rules/flutter-test-best-practices.mdc`. 3. Keep tests behavior-driven and deterministic. 4. Prefer focused tests for changed code paths. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/implement-figma-screen.md b/commands/implement-figma-screen.md index dddff7a..94202ac 100644 --- a/commands/implement-figma-screen.md +++ b/commands/implement-figma-screen.md @@ -11,3 +11,5 @@ Implement a Flutter UI from Figma source. 4. Use Figma MCP for node context, layout, spacing, typography, and assets. 5. Use Dart MCP for post-implementation analysis and fixes. 6. Add widget tests for critical interactions and visible states. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/implement-flutter-feature.md b/commands/implement-flutter-feature.md index 791c08a..7345590 100644 --- a/commands/implement-flutter-feature.md +++ b/commands/implement-flutter-feature.md @@ -11,3 +11,5 @@ Implement or refactor a Flutter feature. 4. Use Dart MCP for analysis and project-aware updates. 5. Keep dependencies injected and testable. 6. Add/update tests for modified behavior. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/integrate-firebase.md b/commands/integrate-firebase.md index 7bfb0f4..6c2988b 100644 --- a/commands/integrate-firebase.md +++ b/commands/integrate-firebase.md @@ -10,3 +10,5 @@ Integrate Firebase into the target Flutter app. 3. Enforce `../rules/dart-effective-dart.mdc`. 4. Complete `../docs/firebase-integration-checklist.md`. 5. Verify Android and iOS initialization in release-capable configuration. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/migrate-flutter-code.md b/commands/migrate-flutter-code.md index bbf6fe8..a6aeb04 100644 --- a/commands/migrate-flutter-code.md +++ b/commands/migrate-flutter-code.md @@ -10,3 +10,5 @@ Run a migration/refactor task. 3. Enforce `../rules/dart-effective-dart.mdc`. 4. Use Dart MCP diagnostics to validate each step. 5. Add or update tests for behavioral changes. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/prepare-mobile-release.md b/commands/prepare-mobile-release.md index cccb1a1..371a5ed 100644 --- a/commands/prepare-mobile-release.md +++ b/commands/prepare-mobile-release.md @@ -10,3 +10,5 @@ Prepare app for store publication. 3. Produce Android release artifact (`.aab`) and validate signing/versioning. 4. Produce iOS release artifact (`.ipa`/archive) and validate signing/versioning. 5. Confirm store metadata/compliance inputs are complete before submission. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/resolve-flutter-build-error.md b/commands/resolve-flutter-build-error.md index 67a3919..b226327 100644 --- a/commands/resolve-flutter-build-error.md +++ b/commands/resolve-flutter-build-error.md @@ -10,3 +10,5 @@ Resolve a build or runtime failure. 3. Apply smallest safe fix. 4. Re-run failing command and impacted tests. 5. Document root cause and prevention notes. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/review-flutter-code.md b/commands/review-flutter-code.md index 382c82d..27847a8 100644 --- a/commands/review-flutter-code.md +++ b/commands/review-flutter-code.md @@ -12,3 +12,5 @@ Run structured Flutter code review. 5. Include OWASP MASVS-focused mobile security checks. 6. Prioritize findings by severity and regression risk. 7. Include testing and accessibility checks. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/scaffold-flutter-feature.md b/commands/scaffold-flutter-feature.md index 9205d52..55495a3 100644 --- a/commands/scaffold-flutter-feature.md +++ b/commands/scaffold-flutter-feature.md @@ -10,3 +10,5 @@ Create a new feature module scaffold. 3. Enforce `../rules/dart-effective-dart.mdc`. 4. Build minimal complete skeleton first (UI + state + data boundaries). 5. Add starter tests with `write-widget-test` / `write-bloc-test`. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/security-review.md b/commands/security-review.md index 9f8a339..77533bb 100644 --- a/commands/security-review.md +++ b/commands/security-review.md @@ -12,3 +12,5 @@ Run a security audit and secrets scan (Claude-style `/security-review` workflow) 5. Apply false-positive filtering so output stays actionable. 6. Return findings first, prioritized by severity and exploitability. 7. Include concrete remediation steps and verification commands. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/setup-mobile-github-pipeline.md b/commands/setup-mobile-github-pipeline.md index 9d88849..4b4b293 100644 --- a/commands/setup-mobile-github-pipeline.md +++ b/commands/setup-mobile-github-pipeline.md @@ -10,3 +10,5 @@ Set up a mobile CI pipeline in GitHub Actions. 3. Add project-specific Flutter version, channels, and build flavor arguments. 4. Ensure pipeline runs analyze/tests before building artifacts. 5. Validate generated APK/AAB artifacts and branch trigger strategy. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/sync-official-flutter-ai-rules.md b/commands/sync-official-flutter-ai-rules.md index 560d4f0..aa6359b 100644 --- a/commands/sync-official-flutter-ai-rules.md +++ b/commands/sync-official-flutter-ai-rules.md @@ -12,3 +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`. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/update-flutter-dependencies.md b/commands/update-flutter-dependencies.md index 7838555..e09a03b 100644 --- a/commands/update-flutter-dependencies.md +++ b/commands/update-flutter-dependencies.md @@ -9,3 +9,5 @@ Run a controlled dependency upgrade. 2. Keep changes incremental and reviewable. 3. Run `flutter analyze` and impacted tests before finalizing. 4. Document version deltas, breaking changes, and rollback plan. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/write-bloc-test.md b/commands/write-bloc-test.md index 54f77e2..a598e3f 100644 --- a/commands/write-bloc-test.md +++ b/commands/write-bloc-test.md @@ -10,3 +10,5 @@ Create or update a Bloc/Cubit test file. 3. Enforce `../rules/flutter-test-best-practices.mdc`. 4. Start from `../templates/bloc_test_template.dart`. 5. Run affected tests and fix failures. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/write-e2e-test.md b/commands/write-e2e-test.md index 831eeac..f40c9de 100644 --- a/commands/write-e2e-test.md +++ b/commands/write-e2e-test.md @@ -13,3 +13,5 @@ Create or update a Patrol E2E test. 6. Keep one main path per test; avoid branching in test body. 7. Keep credentials in `--dart-define` / `.patrol.env` (no hardcoded secrets). 8. Run affected Patrol tests and fix failures. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/commands/write-widget-test.md b/commands/write-widget-test.md index 568c073..84426fd 100644 --- a/commands/write-widget-test.md +++ b/commands/write-widget-test.md @@ -11,3 +11,5 @@ Create or update a widget test file. 4. Start from `../templates/widget_test_template.dart`. 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. + +99. Return final response using `../docs/command-output-contract.md`. diff --git a/docs/command-output-contract.md b/docs/command-output-contract.md new file mode 100644 index 0000000..646ae90 --- /dev/null +++ b/docs/command-output-contract.md @@ -0,0 +1,34 @@ +# Command Output Contract + +All command workflows should return results using this structure. + +## Required sections + +1. Result + - One short statement of outcome (done/blocked/partial). +2. Changes + - Files touched and what changed. +3. Validation + - Commands/checks executed and pass/fail status. +4. Risks + - Remaining risks, assumptions, or edge cases. +5. Next steps + - Optional, only when actionable follow-up exists. + +## Command-specific requirements + +- Review/security commands: + - Findings first, ordered by severity. + - Include exact file references. +- Migration/upgrade commands: + - Before/after versions. + - Rollback notes. +- Build/debug commands: + - Reproduction command. + - Root cause and fix verification. + +## Quality bar + +- Avoid vague summaries without evidence. +- Prefer concrete file paths and command outputs. +- Keep conclusions tied to actual checks, not assumptions. diff --git a/docs/official-release-checklist.md b/docs/official-release-checklist.md index 9a7d135..812e4cc 100644 --- a/docs/official-release-checklist.md +++ b/docs/official-release-checklist.md @@ -16,6 +16,8 @@ Use this checklist before tagging a public release. - Templates are generic and repository-agnostic. - No private/company-specific references remain. - Effective Dart alignment is explicitly enforced (`rules/dart-effective-dart.mdc`). +- Command output contract is documented and referenced (`docs/command-output-contract.md`). +- Latest quality-iterations report exists (`docs/quality-iterations-2026-02-21.md`). ## Tooling diff --git a/docs/quality-iterations-2026-02-21.md b/docs/quality-iterations-2026-02-21.md new file mode 100644 index 0000000..abd7e83 --- /dev/null +++ b/docs/quality-iterations-2026-02-21.md @@ -0,0 +1,22 @@ +# Plugin Quality Iterations (2026-02-21) + +Automated quality audit over 10 command iterations. + +| Iteration | Command | Frontmatter | Skill/Workflow Ref | Output Contract | Steps >= 4 | Status | +|---:|---|---|---|---|---|---| +| 1 | `implement-flutter-feature` | pass | pass | pass | pass | **PASS** | +| 2 | `implement-figma-screen` | pass | pass | pass | pass | **PASS** | +| 3 | `generate-flutter-tests` | pass | pass | pass | pass | **PASS** | +| 4 | `review-flutter-code` | pass | pass | pass | pass | **PASS** | +| 5 | `security-review` | pass | pass | pass | pass | **PASS** | +| 6 | `update-flutter-dependencies` | pass | pass | pass | pass | **PASS** | +| 7 | `resolve-flutter-build-error` | pass | pass | pass | pass | **PASS** | +| 8 | `prepare-mobile-release` | pass | pass | pass | pass | **PASS** | +| 9 | `sync-official-flutter-ai-rules` | pass | pass | pass | pass | **PASS** | +| 10 | `integrate-firebase` | pass | pass | pass | pass | **PASS** | + +## Findings + +- Stabilized command output with a shared contract: `docs/command-output-contract.md`. +- Canonical command set now references the output contract for deterministic response shape. +- This report is generated by `scripts/quality_audit_commands.sh`. diff --git a/plugin.json b/plugin.json index cf8dc53..6fbbab0 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "name": "flutter-cursor-plugin", "displayName": "Flutter Cursor Plugin", - "version": "1.10.0", + "version": "1.10.1", "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/scripts/quality_audit_commands.sh b/scripts/quality_audit_commands.sh new file mode 100755 index 0000000..b54e72d --- /dev/null +++ b/scripts/quality_audit_commands.sh @@ -0,0 +1,87 @@ +#!/usr/bin/env bash + +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +commands=( + "implement-flutter-feature.md" + "implement-figma-screen.md" + "generate-flutter-tests.md" + "review-flutter-code.md" + "security-review.md" + "update-flutter-dependencies.md" + "resolve-flutter-build-error.md" + "prepare-mobile-release.md" + "sync-official-flutter-ai-rules.md" + "integrate-firebase.md" +) + +report_file="${repo_root}/docs/quality-iterations-2026-02-21.md" + +{ + echo "# Plugin Quality Iterations (2026-02-21)" + echo + echo "Automated quality audit over 10 command iterations." + echo + echo "| Iteration | Command | Frontmatter | Skill/Workflow Ref | Output Contract | Steps >= 4 | Status |" + echo "|---:|---|---|---|---|---|---|" +} > "${report_file}" + +idx=1 +all_pass=true + +for cmd in "${commands[@]}"; do + path="${repo_root}/commands/${cmd}" + content="$(cat "${path}")" + + has_frontmatter="fail" + has_skill_or_workflow="fail" + has_output_contract="fail" + has_min_steps="fail" + status="FAIL" + + if grep -Eq '^---' "${path}" && grep -Eq '^name:' "${path}" && grep -Eq '^description:' "${path}"; then + has_frontmatter="pass" + fi + + if grep -Eq '(\.\./skills/|templates/|docs/)' "${path}"; then + has_skill_or_workflow="pass" + fi + + if grep -Eq 'command-output-contract' "${path}"; then + has_output_contract="pass" + fi + + step_count="$(grep -Ec '^[0-9]+\.' "${path}" || true)" + if [ "${step_count}" -ge 4 ]; then + has_min_steps="pass" + fi + + if [ "${has_frontmatter}" = "pass" ] && \ + [ "${has_skill_or_workflow}" = "pass" ] && \ + [ "${has_output_contract}" = "pass" ] && \ + [ "${has_min_steps}" = "pass" ]; then + status="PASS" + else + all_pass=false + fi + + echo "| ${idx} | \`${cmd%.md}\` | ${has_frontmatter} | ${has_skill_or_workflow} | ${has_output_contract} | ${has_min_steps} | **${status}** |" >> "${report_file}" + idx=$((idx + 1)) +done + +{ + echo + echo "## Findings" + echo + echo "- Stabilized command output with a shared contract: \`docs/command-output-contract.md\`." + echo "- Canonical command set now references the output contract for deterministic response shape." + echo "- This report is generated by \`scripts/quality_audit_commands.sh\`." +} >> "${report_file}" + +if [ "${all_pass}" = false ]; then + echo "Quality audit failed. See ${report_file}" >&2 + exit 1 +fi + +echo "Quality audit passed. Report: ${report_file}"