feat(flutter-cursor-templates): introduce MCP integration and conventions in project brief

- Added optional MCP integration settings in project-brief.yaml, allowing for environment-based server configurations. - Introduced conventions for strict package imports to enhance code organization and maintainability. - Updated brief schema to validate new MCP properties and ensure correct usage. - Implemented MCP JSON builder to generate .cursor/mcp.json based on project brief settings. - Enhanced resolver to include MCP configuration in generated files when enabled. This update improves integration capabilities and enforces coding standards across the project.
2026-05-14 13:33:13 +05:30
parent 2ee257c630
commit da64f769da
109 changed files with 2076 additions and 85 deletions
@@ -0,0 +1,20 @@
+# Cursor — TestApp
+
+## Quick start
+
+1. Open this repo in **Cursor** so `.cursor/rules/` and `.cursor/skills/` load automatically.
+2. Read **`rules/universal/rule-authoring.mdc`** — how we maintain AI rules.
+3. Stack and product context live in **`project-brief.yaml`** at the repo root; regenerate `.cursor/` with `cursor_gen` after changing it.
+4. **Slash skills** (primary workflows): open the Command Palette and use the project commands, or reference:
+   - `.cursor/skills/build/SKILL.md` — end-to-end feature implementation
+   - `.cursor/skills/debug-issue/SKILL.md` — structured debugging
+   - `.cursor/skills/verify-change/SKILL.md` — pre-PR verification
+   - `.cursor/skills/explain-code/SKILL.md` — explain-only walkthroughs
+5. **Agents** (`.cursor/agents/*.mdc`) are reusable reviewer personas — attach when asking for code review or focused passes.
+6. **Custom overrides**: files under `.cursor/custom/` and `CURSOR:CUSTOM` blocks in generated files are preserved on `cursor_gen --refresh` (see generator docs).
+
+## Optional
+
+- **`integrations.mcp.enabled`** in `project-brief.yaml` — generates `.cursor/mcp.json` with env-based server entries (no secrets in git).
+- **`telemetry_opt_in: true`** — emits local telemetry helpers under `.cursor/telemetry/` (never commit usage logs if you enable logging).
+- Run **`bash tool/cursor_audit.sh`** from the project root periodically to catch stale feature rules and overly broad `alwaysApply` usage.
@@ -0,0 +1,27 @@
+# Build artefacts
+build/
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+*.g.dart
+*.freezed.dart
+*.gr.dart
+*.config.dart
+
+# Secrets
+.env
+.env.*
+firebase_options.dart
+google-services.json
+GoogleService-Info.plist
+
+# Large binary assets
+assets/fonts/
+assets/videos/
+*.aab
+*.apk
+*.ipa
+
+# IDE
+.idea/
+*.iml
@@ -3,4 +3,5 @@
 Repo-level notes for AI assistants. Authoritative stack and conventions are in `project-brief.yaml` and `.cursor/` (regenerate with `cursor_gen` from the project root).

 - **Package:** `com.test.testapp`
- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain`
+- **Onboarding:** `.cursor/ONBOARDING.md` — layout, slash commands → skills, MCP opt-in, audits
+- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain` (see `.cursor/commands/*.md`)
@@ -1,4 +1,5 @@
 # TestApp — generated by cursor_gen; adjust commands to your repo
+# Optional: run `bash tool/cursor_audit.sh` after changing features.modules or rule files.
 pre-commit:
  commands:
    flutter-analyze:
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# TestApp — Cursor rule hygiene (generated by cursor_gen)
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CURSOR="${ROOT}/.cursor"
+RULES="${CURSOR}/rules"
+
+echo "== cursor_audit (${ROOT}) =="
+
+if [[ ! -d "$CURSOR" ]]; then
+  echo "ERROR: missing ${CURSOR}"
+  exit 1
+fi
+
+if [[ -d "$RULES" ]]; then
+  ac="$(grep -R "alwaysApply: true" "$RULES" --include='*.mdc' 2>/dev/null | wc -l | tr -d ' ')"
+  echo "alwaysApply: true occurrences in .cursor/rules: ${ac}"
+  echo "  (expect a small number — meta/safety; prefer scoped globs for domain rules)"
+else
+  echo "WARN: no ${RULES}"
+fi
+
+if [[ -d "$RULES/features" ]]; then
+  shopt -s nullglob
+  for f in "$RULES/features"/*.mdc; do
+    base="$(basename "$f" .mdc)"
+    if [[ ! -d "${ROOT}/lib/features/${base}" ]] && [[ ! -d "${ROOT}/lib/feature_${base}" ]]; then
+      echo "WARN: rules/features/${base}.mdc has no obvious lib/features/${base} folder — update features.modules or lib layout"
+    fi
+  done
+  shopt -u nullglob
+fi
+
+echo "OK — review warnings above after brief or folder renames"
@@ -0,0 +1 @@
+End-to-end feature implementation (research, TDD, integration tests, verification). Follow the workflow and constraints in `@file:.cursor/skills/build/SKILL.md`. Use `project-brief.yaml` as the source of truth for stack and platforms.
@@ -0,0 +1 @@
+Structured bug triage and evidence-first debugging. Follow `@file:.cursor/skills/debug-issue/SKILL.md`. Gather reproduction steps, logs, and failing commands before proposing fixes.
@@ -0,0 +1 @@
+Explain-only walkthrough of code paths and stack behavior (no edits). Follow `@file:.cursor/skills/explain-code/SKILL.md`. Do not modify source files unless the user explicitly asks.
@@ -0,0 +1 @@
+Pre-PR verification checklist (analyze, tests, hooks) without full /build lifecycle. Follow `@file:.cursor/skills/verify-change/SKILL.md` for the change in scope.
@@ -0,0 +1,29 @@
+---
+description: CI/CD, flavours, and quality gates for TestApp
+globs: [".github/**", "codemagic.yaml", "Makefile", "pubspec.yaml", "fastlane/**"]
+alwaysApply: false
+---
+
+# CI/CD & flavours — TestApp
+
+## Context
+Pipeline and flavour setup must stay aligned with how the app is built and released.
+
+## Flavours
+- Documented in `project-brief.yaml`: **dev, prod**
+- Use `--flavor` / `-t lib/main_<flavour>.dart` (or your project’s entrypoints) consistently across local, CI, and store builds
+- Configuration via `--dart-define` / `--dart-define-from-file` — **never** hardcode secrets in source
+
+## Quality gates (recommended stages)
+- **Lint:** `dart format --set-exit-if-changed .` and `flutter analyze`
+- **Unit + widget:** `flutter test` (with coverage if the team tracks it)
+- **Goldens:** fixed device/locale; CI fails on drift unless intentionally updated
+- **Smoke build:** e.g. `flutter build apk` or `flutter build ios --no-codesign` for the primary flavour
+- **E2E:** when `testing.depth` includes e2e — patrol on CI devices or Firebase Test Lab
+
+## Cursor integration
+- After substantive edits: run analyze and relevant tests before PR
+- For release-oriented tasks, use the **deploy** skill at `.cursor/skills/deploy/SKILL.md` when present
+
+## CI/CD tool
+- Selected in brief: **GitHub Actions** (`github_actions`)
@@ -0,0 +1,21 @@
+---
+description: "Feature module auth — contracts, boundaries, and ownership (fill after design)"
+globs: ["lib/**/auth/**", "test/**/auth/**"]
+alwaysApply: false
+---
+
+# Feature — Auth
+
+## Context
+This stub was generated from `features.modules` in `project-brief.yaml`. Use it to capture **public contracts** (routes, DTOs, events) and **dependencies** for `auth` so agents do not invent cross-feature wiring.
+
+## Constraints
+- List external dependencies (other features, packages, backend endpoints) explicitly
+- Document invariants (auth required, idempotency, offline behavior) when known
+- Update or delete this file when the module is removed or renamed — run `bash tool/cursor_audit.sh` to catch drift
+
+## Patterns
+- Link to key entry points: primary screen(s), state holder(s), repository interface(s)
+
+## Anti-patterns
+- Empty file left forever — either fill it or delete the module entry from the brief
@@ -0,0 +1,21 @@
+---
+description: "Feature module home — contracts, boundaries, and ownership (fill after design)"
+globs: ["lib/**/home/**", "test/**/home/**"]
+alwaysApply: false
+---
+
+# Feature — Home
+
+## Context
+This stub was generated from `features.modules` in `project-brief.yaml`. Use it to capture **public contracts** (routes, DTOs, events) and **dependencies** for `home` so agents do not invent cross-feature wiring.
+
+## Constraints
+- List external dependencies (other features, packages, backend endpoints) explicitly
+- Document invariants (auth required, idempotency, offline behavior) when known
+- Update or delete this file when the module is removed or renamed — run `bash tool/cursor_audit.sh` to catch drift
+
+## Patterns
+- Link to key entry points: primary screen(s), state holder(s), repository interface(s)
+
+## Anti-patterns
+- Empty file left forever — either fill it or delete the module entry from the brief
@@ -0,0 +1,21 @@
+---
+description: "Feature module products — contracts, boundaries, and ownership (fill after design)"
+globs: ["lib/**/products/**", "test/**/products/**"]
+alwaysApply: false
+---
+
+# Feature — Products
+
+## Context
+This stub was generated from `features.modules` in `project-brief.yaml`. Use it to capture **public contracts** (routes, DTOs, events) and **dependencies** for `products` so agents do not invent cross-feature wiring.
+
+## Constraints
+- List external dependencies (other features, packages, backend endpoints) explicitly
+- Document invariants (auth required, idempotency, offline behavior) when known
+- Update or delete this file when the module is removed or renamed — run `bash tool/cursor_audit.sh` to catch drift
+
+## Patterns
+- Link to key entry points: primary screen(s), state holder(s), repository interface(s)
+
+## Anti-patterns
+- Empty file left forever — either fill it or delete the module entry from the brief
@@ -1,6 +1,7 @@
 ---
-description: "Core Flutter conventions for TestApp — always applied"
-alwaysApply: true
+description: "Core Flutter conventions for TestApp"
+globs: ["lib/**/*.dart", "test/**/*.dart", "integration_test/**/*.dart"]
+alwaysApply: false
 ---

 # Flutter Core Standards — TestApp
@@ -29,9 +30,9 @@ alwaysApply: true
 - Private members: `_camelCase`

 ## Imports
- Order: dart: → package: → relative
- Use relative imports within a feature; absolute for cross-feature
- Never import a feature's internal files from outside that feature
+### Imports (strict — `conventions.strict_package_imports: true`)
+- Use `package:<your_pubspec_name>/...` imports everywhere in `lib/` and `test/` — **no** relative `../` across feature boundaries (the brief `project.package` id is often the app bundle id; prefer the **pubspec.yaml `name`** for Dart imports)
+- Barrel files (`index.dart`) at feature roots; do not wildcard re-export third-party packages

 ## Code quality
 - Max function length: 40 lines. Extract widgets and helpers aggressively
@@ -1,6 +1,7 @@
 ---
-description: "Project context for TestApp — always applied"
-alwaysApply: true
+description: "Stack summary and product context for TestApp"
+globs: ["project-brief.yaml", ".cursor/**/*.md", ".cursor/**/*.mdc", "pubspec.yaml"]
+alwaysApply: false
 ---

 # Project Context — TestApp
@@ -0,0 +1,24 @@
+---
+description: How Cursor rules in this repository must be written and maintained.
+globs: [".cursor/rules/**/*.mdc"]
+alwaysApply: true
+---
+
+# Rule authoring — TestApp
+
+## Context
+Rules are version-controlled contracts for AI assistants. Poor rules waste context and silently steer every edit.
+
+## Constraints
+- One focused concern per file; split broad topics instead of one mega-rule
+- Every rule MUST have a clear `description` in frontmatter (one sentence)
+- Prefer `alwaysApply: false` with **narrow** `globs` for domain rules — reserve `alwaysApply: true` for meta and safety
+- `globs` must be as specific as possible — never `["**/*"]` unless tooling requires it
+- Code samples in rules MUST be valid for this project (Dart/Flutter/YAML as appropriate)
+- Deprecated guidance is removed, not left commented out
+- Each substantive rule includes **Context** (why), **Constraints** (must/must not), and where helpful **Patterns** / **Anti-patterns**
+
+## Anti-patterns
+- Domain rules (testing, l10n, a feature) with `alwaysApply: true` — burns context
+- Rules with no concrete examples when the topic is code-facing
+- Stale feature rules after modules are removed — run `tool/cursor_audit.sh` periodically
@@ -1,6 +1,7 @@
 ---
-description: "UI/UX standards for TestApp — always applied"
-alwaysApply: true
+description: "UI/UX standards for TestApp"
+globs: ["lib/**/*.dart", "test/**/*.dart", "integration_test/**/*.dart"]
+alwaysApply: false
 ---

 # UI / UX Standards — TestApp
				`@@ -0,0 +1 @@`
				End-to-end feature implementation (research, TDD, integration tests, verification). Follow the workflow and constraints in `@file:.cursor/skills/build/SKILL.md`. Use `project-brief.yaml` as the source of truth for stack and platforms.
				`@@ -0,0 +1 @@`
				Structured bug triage and evidence-first debugging. Follow `@file:.cursor/skills/debug-issue/SKILL.md`. Gather reproduction steps, logs, and failing commands before proposing fixes.
				`@@ -0,0 +1 @@`
				Explain-only walkthrough of code paths and stack behavior (no edits). Follow `@file:.cursor/skills/explain-code/SKILL.md`. Do not modify source files unless the user explicitly asks.
				`@@ -0,0 +1 @@`
				Pre-PR verification checklist (analyze, tests, hooks) without full /build lifecycle. Follow `@file:.cursor/skills/verify-change/SKILL.md` for the change in scope.