feat: standardize agent/skill outputs and add validation runner (#19)

Wreos · lozhkovoi · web-flow · commit 526a813696e4 · 2026-02-21T13:31:06.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.2",
+  "version": "1.10.3",
   "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,10 @@
 
 ## Unreleased
 
+- Added output expectations to all agents and standardized required output sections across all skills.
+- Added validation script for agent/skill prompt quality:
+  - `scripts/validate_agents_skills.sh`
+- Verified prompt test matrix for all agents/skills (26 checks, all passing).
 - Hardened command prompts with shared execution guardrails:
   - `docs/prompt-execution-guardrails.md`
 - Added deterministic validation guidance:
diff --git a/agents/flutter-app-builder.md b/agents/flutter-app-builder.md
@@ -30,3 +30,10 @@ Primary agent for Flutter feature development.
 - Keep architecture layered (presentation/domain/data boundaries).
 - Add/update tests proportionally to behavior changes.
 - Prefer incremental, reviewable changes over large rewrites.
+
+## Output expectations
+
+1. Selected route/skill and reason.
+2. Scope and files touched.
+3. Validation commands and results.
+4. Risks or follow-up steps.
diff --git a/agents/flutter-code-reviewer.md b/agents/flutter-code-reviewer.md
@@ -22,3 +22,10 @@ Dedicated agent for code review and conventions.
 - Missing error handling.
 - Test gaps and brittle assertions.
 - Accessibility and localization risks.
+
+## Output expectations
+
+1. Findings first, ordered by severity.
+2. File references for each finding.
+3. Security findings included explicitly.
+4. Residual risks/testing gaps summary.
diff --git a/agents/flutter-mobile-release-manager.md b/agents/flutter-mobile-release-manager.md
@@ -18,3 +18,10 @@ Dedicated agent for mobile app publishing readiness.
 - Android Play-ready build and signing checks.
 - iOS App Store-ready archive and signing checks.
 - Versioning, release notes, privacy declarations, and submission gating.
+
+## Output expectations
+
+1. Android readiness status.
+2. iOS readiness status.
+3. Validation evidence (commands/artifacts/checklists).
+4. Blocking issues before submission.
diff --git a/agents/flutter-test-writer.md b/agents/flutter-test-writer.md
@@ -25,3 +25,10 @@ Main router for Flutter test tasks.
 - For widget tests, enforce behavior-first assertions (actions, branching, side effects), not synthetic-only attribute checks.
 - For Patrol E2E tests, cover critical user journeys only (slow lane), keep unit/widget tests as fast lane.
 - Run only impacted tests before finishing.
+
+## Output expectations
+
+1. Test type selected (widget/bloc/integration) and reason.
+2. Files changed and template used.
+3. Test commands run and pass/fail result.
+4. Remaining coverage gaps.
diff --git a/plugin.json b/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "flutter-cursor-plugin",
   "displayName": "Flutter Cursor Plugin",
-  "version": "1.10.2",
+  "version": "1.10.3",
   "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/validate_agents_skills.sh b/scripts/validate_agents_skills.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${repo_root}"
+
+pass_count=0
+fail_count=0
+
+check() {
+  local name="$1"
+  local cmd="$2"
+  if eval "${cmd}" >/dev/null 2>&1; then
+    echo "PASS | ${name}"
+    pass_count=$((pass_count + 1))
+  else
+    echo "FAIL | ${name}"
+    fail_count=$((fail_count + 1))
+  fi
+}
+
+# Agents (4)
+check "A1 flutter-app-builder output expectations" "rg -q '^## Output expectations' agents/flutter-app-builder.md"
+check "A2 flutter-test-writer output expectations" "rg -q '^## Output expectations' agents/flutter-test-writer.md"
+check "A3 flutter-code-reviewer output expectations" "rg -q '^## Output expectations' agents/flutter-code-reviewer.md"
+check "A4 flutter-mobile-release-manager output expectations" "rg -q '^## Output expectations' agents/flutter-mobile-release-manager.md"
+
+# Skills (11)
+for skill in skills/*/SKILL.md; do
+  base="$(basename "$(dirname "${skill}")")"
+  check "S-${base} has workflow" "rg -q '^## Workflow' '${skill}'"
+  check "S-${base} has output section" "rg -q '^## (Required output|Output format)' '${skill}'"
+done
+
+total=$((pass_count + fail_count))
+echo
+echo "SUMMARY | total=${total} passed=${pass_count} failed=${fail_count}"
+
+if [ "${fail_count}" -gt 0 ]; then
+  exit 1
+fi
diff --git a/skills/build-flutter-features/SKILL.md b/skills/build-flutter-features/SKILL.md
@@ -32,6 +32,13 @@ Use this skill for non-test Flutter development tasks.
 - Restrict changes to the requested feature/module unless explicitly expanded.
 - Do not mix unrelated refactors with feature delivery.
 
+## Required output
+
+1. Goal + scope summary.
+2. Files changed by layer (presentation/domain/data).
+3. Validation commands run and results.
+4. Residual risks or follow-up TODOs.
+
 ## Required references
 
 - `../../rules/flutter-development-best-practices.mdc`
diff --git a/skills/integrate-firebase/SKILL.md b/skills/integrate-firebase/SKILL.md
@@ -29,6 +29,13 @@ Use this skill for end-to-end Firebase integration in Flutter apps.
 - Add error handling and fallback behavior for remote dependencies.
 - Validate behavior in both debug and release-capable builds.
 
+## Required output
+
+1. Enabled Firebase services and where they are wired.
+2. Android/iOS configuration files changed.
+3. Validation commands run and runtime checks performed.
+4. Known gaps or follow-up production steps.
+
 ## Required references
 
 - `../../docs/firebase-integration-checklist.md`
diff --git a/skills/migrate-flutter-code/SKILL.md b/skills/migrate-flutter-code/SKILL.md
@@ -21,3 +21,10 @@ Use for framework/API/state-management migrations.
 - Do not mix unrelated refactors with migration work.
 - Keep intermediate states buildable when possible.
 - Prefer codemod-like repetitive edits over ad hoc changes.
+
+## Required output
+
+1. Migration target and acceptance criteria.
+2. Batch-by-batch changes summary.
+3. Validation commands/results per batch.
+4. Breaking changes and rollback notes.
diff --git a/skills/release-mobile-apps/SKILL.md b/skills/release-mobile-apps/SKILL.md
@@ -27,6 +27,19 @@ Use this skill for Android/iOS store publishing preparation.
 7. Submit and monitor post-release health metrics.
 8. If CI pipeline is missing, create it with `commands/setup-mobile-github-pipeline.md` and `templates/github_actions_flutter_mobile_ci.yml`.
 
+## Guardrails
+
+- Do not mark release ready without artifact build evidence.
+- Keep Android/iOS signing and versioning checks explicit.
+- Flag missing compliance metadata as blockers, not warnings.
+
+## Required output
+
+1. Android readiness status (+ artifact path if built).
+2. iOS readiness status (+ artifact/archive status).
+3. Validation commands run and outcomes.
+4. Blocking gaps before submission.
+
 ## Required references
 
 - `../../docs/mobile-app-publishing-checklist.md`
diff --git a/skills/scaffold-flutter-architecture/SKILL.md b/skills/scaffold-flutter-architecture/SKILL.md
@@ -22,3 +22,16 @@ Use for new feature/module boilerplate generation.
 - Inject dependencies through constructors.
 - Avoid hidden globals.
 - Keep files cohesive and naming consistent.
+
+## Guardrails
+
+- Keep scaffold minimal and compilable.
+- Avoid adding business logic before contracts/interfaces exist.
+- Do not generate unused files/classes.
+
+## Required output
+
+1. Generated folder tree.
+2. Core files created and purpose.
+3. Starter tests added.
+4. Remaining TODOs to complete feature behavior.
diff --git a/skills/sync-official-flutter-ai-rules/SKILL.md b/skills/sync-official-flutter-ai-rules/SKILL.md
@@ -29,6 +29,13 @@ Use this workflow to keep plugin guidance aligned with upstream Flutter AI rules
 - Keep active file `rules/flutter-official-ai-rules.mdc` aligned with chosen profile.
 - Prefer `4k` unless there is a clear reason to switch to `10k` or `1k`.
 
+## Required output
+
+1. Selected profile and rationale.
+2. Files synced/updated.
+3. Diff summary for active rule.
+4. Follow-up actions (if manual review is needed).
+
 ## Official upstream sources
 
 - `https://raw.githubusercontent.com/flutter/flutter/main/docs/rules/rules_10k.md`
diff --git a/skills/write-flutter-tests/SKILL.md b/skills/write-flutter-tests/SKILL.md
@@ -40,3 +40,16 @@ Use this skill as the single entry point for Flutter test work.
   - `bloc-tests.md`
   - `integration-tests.md`
   - `../../docs/test-environment-setup.md`
+
+## Guardrails
+
+- Prefer deterministic tests over time-dependent assertions.
+- Keep test setup local unless shared helpers already exist.
+- Avoid broad snapshot/golden assertions unless explicitly requested.
+
+## Required output
+
+1. Test type selected and why.
+2. Files created/updated.
+3. Test commands run and results.
+4. Flakiness risks or missing coverage notes.

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