Skip to content

Commit da9097e

Browse files
Wreoslozhkovoi
andauthored
feat: semantic prompt quality gates (#20)
* feat: standardize agent/skill outputs and add validation runner * feat: add semantic prompt quality gates * fix: install ripgrep for semantic quality checks --------- Co-authored-by: Aleksandr Lozhkovoi <aleksandr.lozhkovoi@enpal.de>
1 parent 526a813 commit da9097e

13 files changed

Lines changed: 149 additions & 5 deletions

File tree

.cursor-plugin/plugin.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "flutter-cursor-plugin",
33
"displayName": "Flutter Cursor Plugin",
4-
"version": "1.10.3",
4+
"version": "1.10.4",
55
"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.",
66
"author": {
77
"name": "Aleksandr Lozhkovoi",
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Semantic Prompt Quality
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
semantic-quality:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v4
14+
15+
- name: Ensure ripgrep
16+
run: |
17+
if ! command -v rg >/dev/null 2>&1; then
18+
sudo apt-get update
19+
sudo apt-get install -y ripgrep
20+
fi
21+
22+
- name: Validate agent/skill structure
23+
run: bash scripts/validate_agents_skills.sh
24+
25+
- name: Validate prompt semantics
26+
run: bash scripts/validate_prompt_semantics.sh

CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@
1717
- Added reference example repository for project structure and tests:
1818
- https://github.com/Wreos/flutter-cursor-plugin-example
1919
- Added pre-release enable guide (`docs/pre-release-enable-plugin.md`) with repository install and manual workspace settings options.
20+
- Added semantic prompt quality gates:
21+
- `scripts/validate_prompt_semantics.sh`
22+
- `.github/workflows/semantic-quality.yml`
23+
- `docs/semantic-quality-gates.md`
24+
- Updated scaffold architecture guidance to prefer existing project state-management convention before selecting a pattern.
2025

2126
## 1.10.0
2227

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ Reference project layout:
8080
- **Reference Flutter app layout**: https://github.com/Wreos/flutter-cursor-plugin-example
8181
- **Prompt guardrails**: `docs/prompt-execution-guardrails.md`.
8282
- **Validation matrix**: `docs/validation-matrix.md`.
83+
- **Semantic quality gates**: `docs/semantic-quality-gates.md`.
8384
- **Agents**
8485
- `flutter-app-builder` (general Flutter implementation)
8586
- `flutter-code-reviewer`

agents/flutter-code-reviewer.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,5 @@ Dedicated agent for code review and conventions.
2828
1. Findings first, ordered by severity.
2929
2. File references for each finding.
3030
3. Security findings included explicitly.
31-
4. Residual risks/testing gaps summary.
31+
4. Validation evidence (commands/scans/checks performed).
32+
5. Residual risks/testing gaps summary.

agents/flutter-test-writer.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,5 +30,5 @@ Main router for Flutter test tasks.
3030

3131
1. Test type selected (widget/bloc/integration) and reason.
3232
2. Files changed and template used.
33-
3. Test commands run and pass/fail result.
33+
3. Validation commands run and pass/fail result.
3434
4. Remaining coverage gaps.

docs/semantic-quality-gates.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Semantic Prompt Quality Gates
2+
3+
This repository validates prompt quality on two levels:
4+
5+
1. Structural checks (`scripts/validate_agents_skills.sh`):
6+
- required sections exist in agents and skills.
7+
2. Semantic checks (`scripts/validate_prompt_semantics.sh`):
8+
- canonical commands include guardrails and validation references.
9+
- skills include workflow, output contract, and guardrails/scope limits.
10+
- agents require validation evidence in output expectations.
11+
- active Flutter rules remain project-first for state management.
12+
- no blanket prohibition of Riverpod/Bloc/GetX in active rules.
13+
14+
Run locally:
15+
16+
```bash
17+
bash scripts/validate_agents_skills.sh
18+
bash scripts/validate_prompt_semantics.sh
19+
```
20+
21+
CI runs both checks in `.github/workflows/semantic-quality.yml`.

plugin.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "flutter-cursor-plugin",
33
"displayName": "Flutter Cursor Plugin",
4-
"version": "1.10.3",
4+
"version": "1.10.4",
55
"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.",
66
"author": "Aleksandr Lozhkovoi",
77
"license": "MIT",
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
#!/usr/bin/env bash
2+
3+
set -euo pipefail
4+
5+
repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
6+
cd "${repo_root}"
7+
8+
pass_count=0
9+
fail_count=0
10+
11+
check() {
12+
local name="$1"
13+
local cmd="$2"
14+
if eval "${cmd}" >/dev/null 2>&1; then
15+
echo "PASS | ${name}"
16+
pass_count=$((pass_count + 1))
17+
else
18+
echo "FAIL | ${name}"
19+
fail_count=$((fail_count + 1))
20+
fi
21+
}
22+
23+
canonical_commands=(
24+
"commands/implement-flutter-feature.md"
25+
"commands/implement-figma-screen.md"
26+
"commands/generate-flutter-tests.md"
27+
"commands/review-flutter-code.md"
28+
"commands/security-review.md"
29+
"commands/update-flutter-dependencies.md"
30+
"commands/resolve-flutter-build-error.md"
31+
"commands/prepare-mobile-release.md"
32+
"commands/integrate-firebase.md"
33+
"commands/migrate-flutter-code.md"
34+
"commands/scaffold-flutter-feature.md"
35+
"commands/setup-mobile-github-pipeline.md"
36+
"commands/sync-official-flutter-ai-rules.md"
37+
"commands/write-widget-test.md"
38+
"commands/write-bloc-test.md"
39+
"commands/write-e2e-test.md"
40+
)
41+
42+
for cmd_file in "${canonical_commands[@]}"; do
43+
base="$(basename "${cmd_file}")"
44+
check "C-${base} has guardrails section" "rg -q '^Preconditions and guardrails:' '${cmd_file}'"
45+
check "C-${base} references prompt guardrails doc" "rg -q 'prompt-execution-guardrails\\.md' '${cmd_file}'"
46+
check "C-${base} references validation matrix" "rg -q 'validation-matrix\\.md' '${cmd_file}'"
47+
done
48+
49+
for skill in skills/*/SKILL.md; do
50+
base="$(basename "$(dirname "${skill}")")"
51+
check "S-${base} has workflow" "rg -q '^## Workflow' '${skill}'"
52+
check "S-${base} has output contract" "rg -q '^## (Required output|Output format)' '${skill}'"
53+
check "S-${base} has guardrails or scope limits" "rg -q '^## (Guardrails|Scope guardrails|Quality defaults)' '${skill}'"
54+
done
55+
56+
for agent in agents/*.md; do
57+
base="$(basename "${agent}")"
58+
check "A-${base} has output expectations" "rg -q '^## Output expectations' '${agent}'"
59+
check "A-${base} expects validation evidence" "rg -qi '(validation|commands and results|evidence)' '${agent}'"
60+
done
61+
62+
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"
63+
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"
64+
check "Scaffold architecture skill enforces project-first state-management selection" "rg -q 'existing project state-management convention' skills/scaffold-flutter-architecture/SKILL.md"
65+
66+
total=$((pass_count + fail_count))
67+
echo
68+
echo "SUMMARY | total=${total} passed=${pass_count} failed=${fail_count}"
69+
70+
if [ "${fail_count}" -gt 0 ]; then
71+
exit 1
72+
fi

skills/debug-flutter-issues/SKILL.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ Use for compiler/build/runtime failures.
1919
4. Apply smallest deterministic fix.
2020
5. Validate with rerun and impacted tests.
2121

22+
## Guardrails
23+
24+
- Do not propose a fix without a reproducible command or clear log evidence.
25+
- Keep fixes minimal and limited to the failing layer unless a cross-layer root cause is proven.
26+
- Call out unknowns explicitly instead of guessing when logs are incomplete.
27+
2228
## Output format
2329

2430
- Root cause.

0 commit comments

Comments
 (0)