cursor_gen/README.md

Flutter Cursor Generator — Complete Implementation

AI-powered, project-specific Cursor configuration generator for Flutter teams. Implements all 6 pillars from the architecture review.

Repository Structure

flutter-cursor-gen/
├── flutter-cursor-templates/     ← Shared template repo (hosted internally)
│   ├── generator/                ← Dart CLI tool
│   │   ├── bin/cursor_gen.dart   ← Entry point
│   │   ├── src/                  ← Core modules
│   │   │   ├── brief_loader.dart      ← Parses project-brief.yaml
│   │   │   ├── resolver.dart          ← Maps brief → template files
│   │   │   ├── renderer.dart          ← Substitutes {{PLACEHOLDERS}}
│   │   │   ├── validator.dart         ← Schema validation
│   │   │   ├── version_manager.dart   ← Pillar 1: version locking
│   │   │   ├── override_manager.dart  ← Pillar 2: custom/ preservation
│   │   │   ├── wizard.dart            ← Interactive brief creator
│   │   │   └── telemetry.dart         ← Pillar 6: opt-in analytics
│   │   ├── test/
│   │   │   ├── generator_test.dart    ← Pillar 3: full test suite
│   │   │   └── golden/                ← Golden output files per stack combo
│   │   ├── brief-schema.json          ← IDE autocomplete for project-brief.yaml
│   │   └── pubspec.yaml
│   ├── templates/
│   │   ├── rules/
│   │   │   ├── universal/             ← Always included (flutter-core, ui-ux, project-context)
│   │   │   ├── security/              ← Pillar 5: always-on security rules
│   │   │   ├── error-handling/        ← Always-on error handling
│   │   │   ├── state-management/      ← bloc | riverpod | getx | hooks_riverpod
│   │   │   ├── architecture/          ← clean | feature_first | mvvm | mvc | layered
│   │   │   ├── backend/               ← firebase | supabase | rest | realtime
│   │   │   ├── routing/               ← gorouter | getx_nav | auto_route
│   │   │   ├── testing/               ← testing-{sm} + testing-e2e-{tool}
│   │   │   ├── platform/              ← Pillar 4: ios | android | web | desktop
│   │   │   ├── codegen/               ← Pillar 4: freezed | json_serializable | injectable | retrofit
│   │   │   └── i18n/                  ← localization rules
│   │   ├── skills/                    ← scaffold-feature | scaffold-screen | generate-tests | ...
│   │   ├── agents/                    ← code-reviewer | test-writer | ui-validator | migration | security
│   │   └── hooks/                     ← arch-guard.ts | flutter-analyze.ts | hooks.json
│   ├── .github/workflows/
│   │   └── template-ci.yml            ← Pillar 3: CI for templates
│   ├── VERSION
│   └── CHANGELOG.md
│
└── example-project/              ← One reference app: commented project-brief.yaml + custom/ demo
    ├── project-brief.yaml        ← All stack options documented in-file
    └── .cursor/custom/           ← Pillar 2: never overwritten by the generator

---

Quick Start

1. Install the CLI globally

From pub.dev:

dart pub global activate cursor_gen

From this repository:

cd flutter-cursor-templates/generator
dart pub global activate --source path .

From Git:

dart pub global activate --source git https://github.com/company/flutter-cursor-templates --git-path generator

If cursor_gen is not found after activation, add Dart's global bin directory to your shell:

export PATH="$PATH":"$HOME/.pub-cache/bin"

2. Create your brief (interactive wizard)

cursor_gen --wizard

Or copy the single reference brief (every option is explained in comments):

cp path/to/flutter-cursor-gen/example-project/project-brief.yaml .

3. Generate your .cursor/ directory

cursor_gen --validate
cursor_gen

4. Commit and share with your team

git add .cursor/ project-brief.yaml
git commit -m "chore: add cursor AI config for this project"

---

All CLI commands

cursor_gen                   # First-time setup
cursor_gen --wizard          # Interactive brief creator
cursor_gen --validate        # Validate brief without generating
cursor_gen --refresh         # Re-generate (preserves custom/ + CURSOR:CUSTOM blocks)
cursor_gen --diff            # Preview changes before refresh
cursor_gen --check-updates   # Check for template version updates
cursor_gen --telemetry       # Show usage analytics report

---

Six Pillars — What Was Built

🔴 Pillar 1 — Template Versioning & Update Propagation

• cursor_templates_version field in project-brief.yaml locks the version
• version_manager.dart writes .cursor-gen-lock.json after every generation
• --check-updates shows diff between locked and latest version
• --diff previews what would change before --refresh
• CHANGELOG.md documents all template changes

🔴 Pillar 2 — Override / Customization Layer

• .cursor/custom/ folder is never touched by the generator
• CURSOR:CUSTOM / CURSOR:CUSTOM:END markers preserve inline customizations on --refresh
• override_manager.dart snapshots and restores custom content around every generation
• custom/README.md explains the system to new team members

🔴 Pillar 3 — Generator Testing & Output Quality Gates

• generator_test.dart: full test suite covering resolver, renderer, validator
• Golden file tests for all 3 stack combinations (BLoC+Clean, Riverpod+FF, GetX+MVC)
• --check-updates validates no unreplaced {{PLACEHOLDER}} patterns survive
• CI pipeline in .github/workflows/template-ci.yml runs all combinations on every PR
• Lint step detects duplicate alwaysApply: true conflicts

🟠 Pillar 4 — Multi-Platform & Code Generation Awareness

• platforms field in brief: [ios, android, web, desktop] → generates platform-specific rules
• Web: warns about dart:io, PWA requirements, renderer differences
• Desktop: window management, keyboard shortcuts, context menus
• codegen field: [freezed, json_serializable, injectable, retrofit] → generates tool-specific rules
• Each codegen template explains "never edit .g.dart" and build_runner usage

🟠 Pillar 5 — Security as Rules, Not Just an Agent

• security-standards.mdc has alwaysApply: true — enforced on EVERY file write
• Covers: secure storage, certificate pinning, no hardcoded secrets, PII logging rules, obfuscation
• error-handling.mdc also always-on: global error boundaries, crash reporters, typed errors
• Security agent still exists for deep consultation — but is a second layer, not the only layer

🟡 Pillar 6 — Observability & Feedback Loop

• telemetry_opt_in: true in brief enables local telemetry (never sent anywhere)
• telemetry.dart logs generation history to .cursor/telemetry.json
• --telemetry command prints report + quarterly review checklist
• Feedback loop questions built into the report: which rules most violated, which agents ignored

Additional fixes (lower priority gaps)

• Brief discovery UX: --wizard interactive CLI, brief-schema.json for IDE autocomplete
• arch-guard documented: arch-guard.ts.tmpl fully implemented with per-architecture rules
• i18n rules: localization.mdc.tmpl — ARB format, ICU plurals, never-hardcode-strings rule
• Error handling: error-handling.mdc.tmpl — FlutterError.onError, AppError sealed class, crash reporters

---

Running Tests (Pillar 3)

cd flutter-cursor-templates/generator
dart pub get
dart test test/generator_test.dart

Update golden files after intentional template changes:

# Delete the golden you want to update, then run:
dart test test/generator_test.dart --name "Golden"
# The test will create new goldens on first run