chore: run 10-iteration quality audit and stabilize outputs (#17)

Wreos · lozhkovoi · web-flow · commit 5e2a878ea46f · 2026-02-21T13:16:52.000-08:00
Co-authored-by: Aleksandr Lozhkovoi &lt;aleksandr.lozhkovoi@enpal.de&gt;
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.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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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}"

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.0",`
	`4`	`+ "version": "1.10.1",`
`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",`