@tenantegroup/ai-rules-mcp 1.0.0

package/rules/dotnet/logging.md

@@ -0,0 +1,25 @@
+Rule: Enforce Logging and Diagnostics
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files for every logging implementation.
+- AI MUST use Serilog as the logging framework.
+- AI MUST use structured logs with named properties.
+- AI MUST configure Serilog at startup in `MauiProgram.cs` or `Program.cs`.
+- AI MUST integrate logging with dependency injection.
+- AI MUST apply log levels consistently: Debug/Information/Warning/Error/Fatal.
+- AI MUST write logs to console and rolling file sink.
+- AI MUST enforce file retention policy: daily rolling, retain 14 days, cap 100MB per file.
+- AI MUST log operational events and exception context.
+Prohibited:
+- AI MUST NOT log secrets, tokens, passwords, API keys, or PII.
+- AI MUST NOT use unstructured concatenated log strings when structured properties are applicable.
+- AI MUST NOT leave verbose debug logging enabled in production defaults.
+- AI MUST NOT swallow exceptions without logging context.
+- AI MUST NOT bypass configured retention limits.
+Patterns:
+- `Log.Information("Processed order {OrderId}", orderId);`
+- `Log.Error(ex, "Sync failed for {EntityId}", entityId);`
+- Configure sinks in startup composition root.
+- Use contextual enrichment (request id, correlation id) where available.
+Examples:
+- `builder.Logging.AddSerilog();`
+- `.WriteTo.File("logs/app-.log", rollingInterval: RollingInterval.Day, retainedFileCountLimit: 14, fileSizeLimitBytes: 104857600)`

package/rules/dotnet/maui.md

@@ -0,0 +1,26 @@
+Rule: Enforce .NET MAUI UI Rules
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files before producing MAUI code.
+- AI MUST implement UI in XAML first.
+- AI MUST use MAUI Shell with URI-based navigation.
+- AI MUST use data binding for UI state and actions.
+- AI MUST keep UI thread non-blocking by using async/await for long operations.
+- AI MUST execute UI updates on the main thread when marshalling from background tasks.
+- AI MUST keep code-behind minimal and UI-only.
+- AI MUST expose user-facing state from ViewModels (`IsLoading`, `ErrorMessage`, etc.).
+- AI MUST implement offline-first behavior where UI reads from local SQLite-backed state.
+Prohibited:
+- AI MUST NOT place business logic in XAML code-behind.
+- AI MUST NOT perform direct database calls from Views.
+- AI MUST NOT perform direct API calls from Views.
+- AI MUST NOT use synchronous blocking operations in UI workflows.
+- AI MUST NOT use `async void` except framework-required event handlers.
+- AI MUST NOT use event-handler-centric architecture when commands are applicable.
+Patterns:
+- Bind properties with `{Binding ...}`.
+- Bind actions to `ICommand` generated by `[RelayCommand]`.
+- Navigate with `await Shell.Current.GoToAsync("route");`.
+- Trigger startup/loading in `InitializeAsync()`.
+Examples:
+- `<Button Text="Save" Command="{Binding SaveCommand}" />`
+- `await Shell.Current.GoToAsync("//home");`

package/rules/dotnet/mvvm.md

@@ -0,0 +1,26 @@
+Rule: Enforce MVVM with CommunityToolkit
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files and enforce strict MVVM separation.
+- AI MUST implement ViewModels with `ObservableObject` from CommunityToolkit.Mvvm.
+- AI MUST define bindable state using `[ObservableProperty]`.
+- AI MUST define user actions using `[RelayCommand]`.
+- AI MUST inject dependencies through constructors only.
+- AI MUST keep constructors lightweight and move runtime work to `InitializeAsync()`.
+- AI MUST call business logic through services only.
+- AI MUST handle operation failures and expose safe user-facing error state.
+Prohibited:
+- AI MUST NOT implement manual `INotifyPropertyChanged` patterns.
+- AI MUST NOT instantiate services directly inside ViewModels.
+- AI MUST NOT call APIs directly from ViewModels.
+- AI MUST NOT call SQLite directly from ViewModels.
+- AI MUST NOT place navigation-independent business rules in ViewModels.
+- AI MUST NOT use `async void` except framework-required handlers.
+Patterns:
+- `public partial class XViewModel : ObservableObject`
+- `[ObservableProperty] private bool isLoading;`
+- `[RelayCommand] private async Task LoadAsync()`
+- Constructor injection: `XViewModel(IXService service)`
+- ViewModel lifecycle default: transient registration; singleton only with explicit justification.
+Examples:
+- `builder.Services.AddTransient<LoginViewModel>();`
+- `[RelayCommand] private async Task RefreshAsync() { ... }`

package/rules/dotnet/packaging.md

@@ -0,0 +1,24 @@
+Rule: Enforce Packaging and Distribution
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files when defining release and distribution workflows.
+- AI MUST use semantic versioning (`MAJOR.MINOR.PATCH`) for all releases.
+- AI MUST publish release artifacts through GitHub Releases for every version.
+- AI MUST include release notes for every published version.
+- AI MUST produce platform-specific distributables for MAUI applications.
+- AI MUST package Windows MAUI releases as MSIX artifacts.
+- AI MUST package CLI releases as self-contained binaries per target platform.
+- AI MUST maintain deterministic artifact naming that includes application name, version, and target platform.
+Prohibited:
+- AI MUST NOT publish unversioned release artifacts.
+- AI MUST NOT ship debug builds as production release artifacts.
+- AI MUST NOT skip release notes on published versions.
+- AI MUST NOT mix preview and stable artifact channels without explicit labeling.
+- AI MUST NOT bypass signing requirements where platform policy requires signing.
+Patterns:
+- GitHub Releases as canonical artifact distribution channel.
+- Version tag format: `v<MAJOR>.<MINOR>.<PATCH>`.
+- Artifact naming: `<app>-<version>-<platform>.<ext>`.
+- Release workflow: build -> package -> sign (if required) -> publish artifacts -> publish release notes.
+Examples:
+- `MyApp-1.4.0-windows-x64.msix`
+- `mycli-1.4.0-linux-x64`

package/rules/dotnet/project-structure.md

@@ -0,0 +1,26 @@
+Rule: Enforce Project Structure
+Requirements:
+- AI MUST follow this file and all `.ai/rules/*.md` files at all times.
+- AI MUST use feature-based organization only.
+- AI MUST keep single-level features only: `Features/<FeatureName>/`.
+- AI MUST use this root structure: `Features/`, `Infrastructure/`, `Services/`, `Models/`, `Data/`, `Configuration/`.
+- AI MUST place shared cross-feature business services in `Services/`.
+- AI MUST place low-level technical services in `Infrastructure/` only.
+- AI MUST keep feature-specific files inside their feature folder.
+- AI MUST use standard naming: `<Name>Page.xaml`, `<Name>Page.xaml.cs`, `<Name>ViewModel.cs`, `<Name>Service.cs`.
+Prohibited:
+- AI MUST NOT create layer-based or mixed structure alternatives.
+- AI MUST NOT create nested feature folders beyond one level.
+- AI MUST NOT place business logic in `Infrastructure/`.
+- AI MUST NOT scatter feature files across unrelated folders.
+- AI MUST NOT invent non-standard naming conventions.
+Patterns:
+- `Features/Orders/OrdersPage.xaml`
+- `Features/Orders/OrdersPage.xaml.cs`
+- `Features/Orders/OrdersViewModel.cs`
+- `Features/Orders/OrdersService.cs`
+- `Data/DatabaseService.cs`
+- `Data/Repositories/`
+Examples:
+- `Features/Auth/LoginPage.xaml`
+- `Features/Auth/LoginViewModel.cs`

package/rules/dotnet/sqlite.md

@@ -0,0 +1,29 @@
+Rule: Enforce SQLite Data Layer
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files before generating data access code.
+- AI MUST use `sqlite-net-pcl` for SQLite access.
+- AI MUST use `SQLiteAsyncConnection` for all database operations.
+- AI MUST initialize database at `Path.Combine(FileSystem.AppDataDirectory, "app.db")`.
+- AI MUST define entities with sqlite-net attributes (`[Table]`, `[PrimaryKey]`, `[Indexed]` as needed).
+- AI MUST centralize connection lifecycle in `DatabaseService`.
+- AI MUST use repository classes for table access.
+- AI MUST use transactions for multi-record write operations.
+- AI MUST treat SQLite as primary local source for UI-facing reads.
+- AI MUST persist API responses to SQLite before exposing updated state to ViewModels.
+- AI MUST define explicit conflict handling policy during synchronization (merge or local-priority).
+Prohibited:
+- AI MUST NOT use direct SQL strings when repository methods can express the query.
+- AI MUST NOT use synchronous DB operations.
+- AI MUST NOT call SQLite from Views.
+- AI MUST NOT call SQLite from ViewModels.
+- AI MUST NOT store secrets in plaintext database fields.
+- AI MUST NOT replace sqlite-net with other ORMs in this architecture.
+- AI MUST NOT update UI state from API payloads before SQLite persistence in offline-first flows.
+Patterns:
+- `Data/DatabaseService.cs` manages connection and table creation.
+- `Data/Repositories/<Entity>Repository.cs` encapsulates queries.
+- API synchronization writes to repositories, then ViewModels load from repositories.
+- Use `RunInTransactionAsync` or equivalent transactional pattern for grouped writes.
+Examples:
+- `_db = new SQLiteAsyncConnection(dbPath);`
+- `await _db.CreateTableAsync<UserEntity>();`

package/rules/dotnet/testing.md

@@ -0,0 +1,24 @@
+Rule: Enforce Testing Standards
+Requirements:
+- AI MUST follow all `.ai/rules/*.md` files when generating tests or testable code.
+- AI MUST define service dependencies behind interfaces to enable mocking.
+- AI MUST inject dependencies into ViewModels and services through constructors.
+- AI MUST keep ViewModels free of direct database and API calls to preserve unit testability.
+- AI MUST write tests against behavior and public contracts, not private implementation details.
+- AI MUST keep I/O-dependent logic behind abstractions to allow deterministic tests.
+- AI MUST use async test methods for async production methods.
+- AI MUST keep test data deterministic and isolated per test.
+Prohibited:
+- AI MUST NOT couple tests to external services, real network calls, or production databases.
+- AI MUST NOT use static mutable shared state across tests.
+- AI MUST NOT rely on execution order between tests.
+- AI MUST NOT introduce synchronous wrappers around async code for tests.
+- AI MUST NOT bypass dependency injection in tests by direct concrete instantiation when mocks/fakes are required.
+Patterns:
+- Mock service interfaces in ViewModel tests.
+- Test command methods through ViewModel public API.
+- Use in-memory or isolated SQLite test stores when persistence behavior must be validated.
+- Organize tests by feature and target class behavior.
+Examples:
+- `var vm = new LoginViewModel(mockAuthService.Object);`
+- `await vm.LoginCommand.ExecuteAsync(null);`

package/rules/flutter/api.md

@@ -0,0 +1,29 @@
+Rule: Enforce Retrofit API Integration
+Requirements:
+- AI MUST use Retrofit for all HTTP communication — annotated `@RestApi()` abstract classes.
+- AI MUST provide one shared, configured Dio instance via a `@Riverpod(keepAlive: true)` provider in `core/network/dio_client.dart`.
+- AI MUST include the `AuthInterceptor` on all Dio instances except the auth API client.
+- AI MUST read `baseUrl` from `AppConfig` — never hardcode it.
+- AI MUST prefix all API paths with `/api/v1/`.
+- AI MUST provide each API client via a `@riverpod` function using the shared `dioClientProvider`.
+- AI MUST co-locate API client files with the feature they serve.
+- AI MUST use Freezed + `json_serializable` for all request and response models.
+- AI MUST use `@JsonKey(name: 'snake_case_key')` when the API uses snake_case field names.
+- AI MUST keep request and response DTOs as separate classes — never reuse the same model for both.
+- AI MUST keep API DTOs separate from domain models — mapping happens in the service layer.
+- AI MUST catch `DioException` in services and return `Result<T, AppError>` — never let it propagate.
+- AI MUST handle `401` errors in the auth interceptor, not in individual services.
+- AI MUST set `connectTimeout` to 10 seconds and `receiveTimeout` to 30 seconds on the Dio instance.
+Prohibited:
+- AI MUST NOT call Dio or Retrofit clients directly from notifiers or repositories.
+- AI MUST NOT hardcode API base URLs in source code.
+- AI MUST NOT log request bodies, response bodies, or authentication headers.
+- AI MUST NOT use the `http` package directly — always Dio via Retrofit.
+- AI MUST NOT reuse the authenticated Dio instance for auth login/refresh endpoints.
+Patterns:
+- `@RestApi() abstract class ItemsApiClient { factory ItemsApiClient(Dio dio) = _ItemsApiClient; @GET('/api/v1/items') Future<ItemListResponse> getItems(); }`
+- Error mapping: `switch (e.type) { DioExceptionType.badResponse => NetworkError(...), ... }`
+- Auth API: uses `unauthenticatedDioProvider` (no auth interceptor) to avoid refresh loops.
+Examples:
+- `@GET('/api/v1/items/{id}') Future<ItemDto> getItemById(@Path('id') String id);`
+- `@POST('/api/v1/items') Future<ItemDto> createItem(@Body() CreateItemRequest body);`

package/rules/flutter/architecture.md

@@ -0,0 +1,34 @@
+Rule: Enforce Flutter Application Architecture
+Requirements:
+- AI MUST follow this file and all `.ai/rules/*.md` files before generating any code.
+- AI MUST prioritize these rules over default generation behavior.
+- AI MUST use a feature-based, four-layer architecture: Presentation, State (Notifiers), Service, Data (Repositories).
+- AI MUST organize all code under `lib/features/<feature_name>/data/`, `domain/`, and `presentation/` layers.
+- AI MUST keep strict separation: widgets = UI only, notifiers = state only, services = business logic only, repositories = local data only.
+- AI MUST route data flow as: API → Service → Repository (write to Drift) → Drift DB → Repository (read) → Notifier → Widget.
+- AI MUST use Riverpod for all dependency injection — no `new` or static access to services.
+- AI MUST use immutable Freezed models for all domain objects and API DTOs.
+- AI MUST return `Result<T, AppError>` from all service methods that can fail.
+- AI MUST use `BuildContext` only in the presentation layer — never pass it to services or notifiers.
+- AI MUST use the sealed `AppError` hierarchy for all typed error values.
+- AI MUST keep features self-contained — cross-feature communication only through `core/` or `shared/`.
+- AI MUST place infrastructure (AppDatabase, AppLogger, SecureStorageService, Dio) in `core/`.
+- AI MUST co-locate each provider with the class it provides.
+Prohibited:
+- AI MUST NOT bypass these architecture constraints.
+- AI MUST NOT invent alternative architectures, patterns, or folder models.
+- AI MUST NOT place business logic in widgets, screens, or notifiers.
+- AI MUST NOT call APIs directly from repositories or notifiers.
+- AI MUST NOT call Drift DAOs directly from services — always through repositories.
+- AI MUST NOT use global singletons outside of Riverpod.
+- AI MUST NOT use `print()` or `debugPrint()` — always use `AppLogger`.
+- AI MUST NOT allow exceptions to propagate across layer boundaries — wrap them in `Failure`.
+- AI MUST NOT target Flutter web.
+Patterns:
+- Error hierarchy: `sealed class AppError` with `NetworkError`, `AuthError`, `DatabaseError`, `UnknownError`.
+- Result type: `sealed class Result<T>` with `Success<T>(value)` and `Failure<T>(error)`.
+- All models use `@freezed` with `json_serializable`.
+- API DTOs, database rows, and domain models are separate types; mapping happens at service/repository boundary.
+Examples:
+- `return switch (result) { Success(:final value) => value, Failure(:final error) => throw error };`
+- `@Riverpod(keepAlive: true) AppDatabase appDatabase(AppDatabaseRef ref) { ... }`

package/rules/flutter/auth.md

@@ -0,0 +1,27 @@
+Rule: Enforce Authentication & Token Management
+Requirements:
+- AI MUST store all tokens exclusively in `flutter_secure_storage` via `SecureStorageService`.
+- AI MUST use `encryptedSharedPreferences: true` on Android and `KeychainAccessibility.first_unlock` on iOS.
+- AI MUST provide `SecureStorageService` with `@Riverpod(keepAlive: true)`.
+- AI MUST implement `AuthService` with `login()`, `logout()`, `isAuthenticated()`, and `refreshAccessToken()` methods, each returning `Result<T, AppError>`.
+- AI MUST provide `AuthNotifier` with `@Riverpod(keepAlive: true)` — it must be keepAlive because the GoRouter provider reads it.
+- AI MUST implement the auth interceptor to silently attach the JWT access token to all outgoing requests.
+- AI MUST implement automatic token refresh on `401` in the auth interceptor with a `_isRefreshing` guard.
+- AI MUST use a separate unauthenticated Dio instance for the auth API client (login, refresh, logout endpoints) to avoid infinite refresh loops.
+- AI MUST clear all tokens from secure storage on logout and on failed token refresh.
+- AI MUST check session persistence in `AuthNotifier.build()` by reading from secure storage.
+- AI MUST handle the initial auth check lazily — token validity is confirmed on the first API call, not on startup.
+Prohibited:
+- AI MUST NOT store tokens in SharedPreferences, Drift, plain files, or in-memory objects.
+- AI MUST NOT log tokens, passwords, or credentials under any circumstances.
+- AI MUST NOT include tokens in URL parameters.
+- AI MUST NOT handle `401` errors in services — always in the auth interceptor.
+- AI MUST NOT allow concurrent token refresh attempts — use the `_isRefreshing` flag.
+Patterns:
+- `SecureStorageService` constants: `_accessTokenKey`, `_refreshTokenKey`, `_userIdKey`.
+- On logout: call `storage.clearAll()` even if server logout fails (best-effort).
+- Auth interceptor retry: on successful refresh, retry the original request with the new token; on failed refresh, call `handler.next(err)` and let GoRouter redirect to login.
+- `AuthState` sealed: `authenticated({required User user})` and `unauthenticated()`.
+Examples:
+- `await storage.saveTokens(accessToken: response.accessToken, refreshToken: response.refreshToken);`
+- `options.headers['Authorization'] = 'Bearer $token';`

package/rules/flutter/configuration.md

@@ -0,0 +1,24 @@
+Rule: Enforce Configuration & Secrets Management
+Requirements:
+- AI MUST centralize all configuration in a typed `AppConfig` class in `core/config/app_config.dart`.
+- AI MUST provide `AppConfig` with `@Riverpod(keepAlive: true)`.
+- AI MUST use `String.fromEnvironment(...)` with sensible defaults in `AppConfig.fromEnvironment()`.
+- AI MUST inject all build-time configuration via `--dart-define` variables: `APP_ENV`, `API_BASE_URL`, `APP_VERSION`, `BUILD_NUMBER`.
+- AI MUST support `.dart_define/<env>.json` files via `--dart-define-from-file` for local development.
+- AI MUST exclude `.dart_define/` from version control — commit only a `.dart_define/development.json.example` template.
+- AI MUST store runtime credentials (JWT tokens, user ID) in `flutter_secure_storage` via `SecureStorageService`.
+- AI MUST inject production secrets via CI/CD GitHub Secrets — never commit them.
+- AI MUST expose `isProduction` and `isDebug` convenience getters on `AppConfig`.
+- AI MUST default `API_BASE_URL` to `http://localhost:8787` (local Wrangler worker) in development.
+Prohibited:
+- AI MUST NOT hardcode API URLs, environment flags, or secrets in Dart source code.
+- AI MUST NOT call `String.fromEnvironment(...)` outside of `AppConfig`.
+- AI MUST NOT commit `.dart_define/*.json`, `.env`, or any file containing real secrets.
+- AI MUST NOT store feature flags in compile-time config — they come from the API and are cached in Drift.
+Patterns:
+- Environments: `development`, `staging`, `production` via `AppEnvironment` enum.
+- What goes where: API URL → Dart-define, auth tokens → flutter_secure_storage, feature flags → KV via API cached in Drift.
+- `AppConfig.fromEnvironment()` factory reads all `String.fromEnvironment` calls once at startup.
+Examples:
+- `flutter run --dart-define-from-file=.dart_define/development.json`
+- `flutter build apk --dart-define=APP_ENV=production --dart-define=API_BASE_URL=https://api.myapp.workers.dev`

package/rules/flutter/database.md

@@ -0,0 +1,30 @@
+Rule: Enforce Drift SQLite Data Layer
+Requirements:
+- AI MUST use Drift as the only local data storage solution.
+- AI MUST define a single `AppDatabase` class in `core/database/app_database.dart` provided with `@Riverpod(keepAlive: true)`.
+- AI MUST call `ref.onDispose(db.close)` on the AppDatabase provider.
+- AI MUST define all tables as Dart classes extending `Table`, declared in the feature's `data/` folder.
+- AI MUST register all tables and DAOs in the `@DriftDatabase` annotation on `AppDatabase`.
+- AI MUST use `text()` for string primary keys (UUIDs are strings, not integers).
+- AI MUST define explicit `primaryKey` on every table.
+- AI MUST include `isSynced` (BoolColumn), `createdAt` (DateTimeColumn), and `updatedAt` (DateTimeColumn) on all tables that participate in backend sync.
+- AI MUST encapsulate all queries in DAOs — never query tables directly from repositories.
+- AI MUST use `watch()` for reactive queries (UI data sources) and `get()` for one-shot queries (background/sync operations).
+- AI MUST expose `getUnsynced()` and `markSynced()` on any DAO whose table has `isSynced`.
+- AI MUST wrap repositories' mapping so they return typed domain models, not raw Drift rows.
+- AI MUST save new or modified records with `isSynced: false` in the repository.
+- AI MUST increment `schemaVersion` and add an explicit `onUpgrade` migration step for every schema change.
+- AI MUST store all DateTimes in UTC and configure `store_date_time_values_as_text: true` in `build.yaml`.
+- AI MUST use transactions for multi-table write operations.
+- AI MUST add `AppDatabase.inMemory() : super(NativeDatabase.memory());` constructor for testing.
+Prohibited:
+- AI MUST NOT use Hive, shared_preferences, or any other storage library for persistent data.
+- AI MUST NOT query Drift tables directly from services — always through repositories.
+- AI MUST NOT call APIs from repositories.
+- AI MUST NOT modify applied migrations.
+Patterns:
+- Table: `class Items extends Table { TextColumn get id => text()(); BoolColumn get isSynced => boolean().withDefault(const Constant(false))(); @override Set<Column> get primaryKey => {id}; }`
+- DAO reactive: `Stream<List<Item>> watchAll() => (select(items)..orderBy([...])).watch();`
+- DAO upsert: `Future<void> upsert(ItemsCompanion c) => into(items).insertOnConflictUpdate(c);`
+Examples:
+- `@Riverpod(keepAlive: true) AppDatabase appDatabase(AppDatabaseRef ref) { final db = AppDatabase(); ref.onDispose(db.close); return db; }`

package/rules/flutter/logging.md

@@ -0,0 +1,27 @@
+Rule: Enforce Logging & Diagnostics Standards
+Requirements:
+- AI MUST use the `logger` package wrapped by `AppLogger` for all logging.
+- AI MUST provide `AppLogger` with `@Riverpod(keepAlive: true)` in `core/logging/app_logger.dart`.
+- AI MUST inject `AppLogger` into all services via constructor injection.
+- AI MUST use `logger.debug()` for development diagnostics (disabled in production).
+- AI MUST use `logger.info()` for significant events: login, logout, sync completed, data loaded.
+- AI MUST use `logger.warn()` for recoverable failures: API retry, sync item skipped.
+- AI MUST use `logger.error()` for failures requiring attention: unhandled exceptions, sync aborted.
+- AI MUST set production log level to `Level.warning` — debug and info are suppressed.
+- AI MUST capture uncaught Flutter errors in `FlutterError.onError` in `main.dart`.
+- AI MUST capture async errors in `PlatformDispatcher.instance.onError` in `main.dart`.
+- AI MUST always log: auth events, sync operations, feature-level operations, error conditions.
+- AI MUST include contextual key-value pairs in log messages using the `extra` parameter.
+Prohibited:
+- AI MUST NOT use `print()` or `debugPrint()` in any production code.
+- AI MUST NOT use the `logger` package directly in features — always through `AppLogger`.
+- AI MUST NOT log passwords, tokens, credentials, PII (email, name, phone), raw API bodies, or payment information.
+Patterns:
+- Log format: `logger.info('Items fetched', extra: {'count': response.items.length});`
+- Error log: `logger.error('Sync failed', error: e, stackTrace: st);`
+- Warn log: `logger.warn('Failed to push item', error: e.message, extra: {'itemId': item.id});`
+- Production output: route `Level.warning` and above to Sentry or platform crash reporting.
+- Message tense: present for actions (`'Fetching items'`), past for completed events (`'Items loaded'`).
+Examples:
+- `logger.info('User login successful', extra: {'userId': userId});`
+- `logger.warn('Sync failed for item', extra: {'itemId': itemId});`

package/rules/flutter/navigation.md

@@ -0,0 +1,28 @@
+Rule: Enforce GoRouter Navigation
+Requirements:
+- AI MUST use GoRouter for all navigation.
+- AI MUST configure the router in `core/router/app_router.dart` as a `@Riverpod(keepAlive: true)` provider.
+- AI MUST define all route name constants in `abstract final class AppRoutes` using kebab-case strings.
+- AI MUST navigate using `context.goNamed(AppRoutes.routeName)` — never hardcoded path strings.
+- AI MUST use `context.goNamed` for top-level navigation (replaces current route).
+- AI MUST use `context.pushNamed` for stacked/modal navigation.
+- AI MUST use `context.pop()` to navigate back.
+- AI MUST implement all auth guards in the router's `redirect` callback — never in individual screens.
+- AI MUST use `ShellRoute` for persistent navigation UI (bottom nav, side drawer).
+- AI MUST pass only primitive IDs through path parameters, not full objects.
+- AI MUST load data inside the destination screen using the ID via Riverpod providers.
+- AI MUST define a custom `errorBuilder` for unmatched routes.
+- AI MUST configure deep links per platform (intent filters on Android, URL schemes on iOS/macOS).
+Prohibited:
+- AI MUST NOT use hardcoded path strings in navigation calls.
+- AI MUST NOT check auth state inside individual screens to redirect.
+- AI MUST NOT pass complex objects through GoRouter's `extra` parameter.
+- AI MUST NOT use the imperative `Navigator` API — always GoRouter.
+Patterns:
+- Router provider: `@Riverpod(keepAlive: true) GoRouter router(RouterRef ref) { final authState = ref.watch(authNotifierProvider); return GoRouter(redirect: ..., routes: _routes); }`
+- Route constant: `static const itemDetail = 'item-detail';`
+- Navigation: `context.goNamed(AppRoutes.itemDetail, pathParameters: {'id': item.id});`
+- Redirect: `if (!isLoggedIn && !isAuthRoute) return '/auth/login'; if (isLoggedIn && isAuthRoute) return '/dashboard'; return null;`
+Examples:
+- `context.goNamed(AppRoutes.dashboard);`
+- `context.goNamed(AppRoutes.itemDetail, pathParameters: {'id': item.id});`

package/rules/flutter/offline-sync.md

@@ -0,0 +1,26 @@
+Rule: Enforce Offline-First & Background Sync
+Requirements:
+- AI MUST treat the local Drift database as the primary data source at all times — the UI never reads from the API directly.
+- AI MUST use `connectivity_plus` via a `ConnectivityService` provided with `@Riverpod(keepAlive: true)`.
+- AI MUST implement a `SyncService` provided with `@Riverpod(keepAlive: true)` that listens to `ConnectivityService.isOnlineStream` and triggers `syncAll()` when the device comes back online.
+- AI MUST guard `syncAll()` with a `_isSyncing` boolean to prevent concurrent sync runs.
+- AI MUST implement a dedicated sync task class per resource (e.g., `ItemSyncTask`) that pushes local unsynced changes then pulls remote data.
+- AI MUST push local unsynced items before pulling remote data in every sync task.
+- AI MUST handle individual record push failures gracefully — log the failure and continue syncing other records.
+- AI MUST use upsert semantics when writing pulled data to Drift (server wins on conflict).
+- AI MUST save offline writes locally with `isSynced: false` immediately, then attempt an immediate push if online.
+- AI MUST support pull-to-refresh by calling `syncService.syncAll()` from the UI.
+- AI MUST implement `SyncStatusNotifier` (keepAlive) with sealed states: `idle`, `syncing`, `lastSyncedAt`, `error`.
+- AI MUST perform an initial sync on first launch before navigating to the main content.
+- AI MUST log sync start, completion, and any failures using `AppLogger`.
+Prohibited:
+- AI MUST NOT read from the API in the UI layer — always from Drift streams via notifiers.
+- AI MUST NOT allow a single sync failure to abort the entire sync run.
+- AI MUST NOT implement complex merge conflict strategies — server wins is the default.
+Patterns:
+- Sync task: `async execute() { await _pushLocalChanges(); await _pullRemoteData(); }`
+- Push: iterate `getUnsynced()`, call API per item, call `markSynced([id])` on success.
+- Pull: call API list endpoint, call `repository.saveAll(items)` with upsert.
+- Offline write: `await _repository.save(item); if (await _connectivity.isOnline) { ... markSynced; }`
+Examples:
+- `_connectivitySubscription = connectivity.isOnlineStream.listen((isOnline) { if (isOnline && !_isSyncing) syncAll(); });`

package/rules/flutter/platform.md

@@ -0,0 +1,30 @@
+Rule: Enforce Platform Targets & Build Configuration
+Requirements:
+- AI MUST target iOS (min 16.0), Android (min API 26), macOS (min 13.0), and Windows (min 10) only.
+- AI MUST manage environments (development, staging, production) via Dart-define variables, not Flutter flavors.
+- AI MUST pin all dependencies to major versions in `pubspec.yaml` (e.g., `^2.x.x`).
+- AI MUST commit `pubspec.lock` to ensure reproducible builds.
+- AI MUST use GitHub Actions for all CI/CD pipelines.
+- AI MUST run `dart run build_runner build --delete-conflicting-outputs` in every CI run before analyze and test.
+- AI MUST enforce the branch model: `main` = production, `staging` = staging, `feature/*` = development.
+- AI MUST require all PRs to pass `flutter analyze` and `flutter test --coverage` before merge.
+- AI MUST manage signing credentials exclusively via GitHub Secrets — never commit keystores, `.p12` files, or `key.properties`.
+- AI MUST enable Keychain sharing on iOS and the appropriate entitlements on macOS for `flutter_secure_storage`.
+- AI MUST configure Associated Domains on iOS and intent filters on Android for deep link support.
+- AI MUST encapsulate all platform-conditional code in dedicated platform service classes.
+- AI MUST pin the Flutter version in `.flutter-version` or the CI workflow YAML.
+Prohibited:
+- AI MUST NOT target Flutter web — use Nuxt + Cloudflare for web interfaces.
+- AI MUST NOT use Flutter flavors for environment management — Dart-define is the standard.
+- AI MUST NOT commit signing credentials, keystores, provisioning profiles, or `key.properties`.
+- AI MUST NOT scatter `Platform.isIOS` / `Platform.isAndroid` checks in widget trees.
+- AI MUST NOT run `flutter pub upgrade` as part of routine development — only deliberately.
+- AI MUST NOT allow direct commits to `main` — all changes enter via pull request.
+Patterns:
+- CI validate: checkout → Flutter setup → `pub get` → `build_runner` → `flutter analyze` → `flutter test`.
+- Platform CI secrets (Android): `ANDROID_KEYSTORE_BASE64`, `ANDROID_KEY_PROPERTIES`, `GOOGLE_PLAY_SERVICE_ACCOUNT`.
+- Platform CI secrets (iOS): `IOS_CERTIFICATE_BASE64`, `IOS_CERTIFICATE_PASSWORD`, `IOS_PROVISIONING_PROFILE_BASE64`, `APP_STORE_CONNECT_API_KEY`.
+- Shared CI secrets: `PROD_API_BASE_URL`, `STAGING_API_BASE_URL`, `APP_VERSION`.
+Examples:
+- `flutter build appbundle --release --dart-define=APP_ENV=production --dart-define=API_BASE_URL=$API_BASE_URL`
+- `flutter build ipa --release --dart-define=APP_ENV=production --export-options-plist=ios/ExportOptions.plist`

package/rules/flutter/project-structure.md

@@ -0,0 +1,32 @@
+Rule: Enforce Standard Project Structure
+Requirements:
+- AI MUST place all application source code under `lib/`.
+- AI MUST use the standard top-level layout: `lib/main.dart`, `lib/app.dart`, `lib/core/`, `lib/features/`, `lib/shared/`.
+- AI MUST place infrastructure in `core/`: `bootstrap/`, `database/`, `network/`, `router/`, `storage/`, `logging/`, `errors/`, `config/`, `theme/`.
+- AI MUST place each feature under `lib/features/<feature_name>/` with `data/`, `domain/`, and `presentation/` subdirectories.
+- AI MUST place reusable cross-feature widgets and utilities under `lib/shared/widgets/` and `lib/shared/extensions/`.
+- AI MUST mirror the `lib/features/` structure in `test/features/`.
+- AI MUST place test fixtures in `test/helpers/fixtures/`.
+- AI MUST place AI rule files in `.ai/rules/`.
+- AI MUST follow naming conventions: snake_case files, PascalCase classes, camelCase variables and constants.
+- AI MUST suffix: screens with `Screen`, notifiers with `Notifier`, repositories with `Repository`, services with `Service`.
+- AI MUST suffix Riverpod providers as camelCase + `Provider` (e.g., `authServiceProvider`).
+- AI MUST keep `main.dart` minimal — only Flutter binding init, bootstrap, and `runApp`.
+- AI MUST declare all assets in `pubspec.yaml`.
+- AI MUST commit `pubspec.lock`.
+Prohibited:
+- AI MUST NOT create feature-specific logic inside `core/` or `shared/`.
+- AI MUST NOT create centralized provider files — providers live with the class they provide.
+- AI MUST NOT scatter `Platform.isIOS` checks throughout widget trees.
+- AI MUST NOT use callbacks for `async` operations — always use `async/await`.
+- AI MUST NOT commit `.dart_define/` files, `.g.dart`, or `.freezed.dart` files.
+Patterns:
+- `lib/features/auth/data/auth_repository.dart`
+- `lib/features/auth/domain/auth_service.dart`
+- `lib/features/auth/presentation/screens/login_screen.dart`
+- `lib/features/auth/presentation/notifiers/auth_notifier.dart`
+- `lib/core/database/app_database.dart`
+- `lib/core/network/dio_client.dart`
+Examples:
+- File: `auth_service.dart` → Class: `AuthService` → Provider: `authServiceProvider`
+- File: `item_list_screen.dart` → Class: `ItemListScreen`

package/rules/flutter/riverpod.md

@@ -0,0 +1,32 @@
+Rule: Enforce Riverpod State Management
+Requirements:
+- AI MUST use Riverpod with `riverpod_generator` for all state management and dependency injection.
+- AI MUST wrap the root widget in `ProviderScope` exactly once in `main.dart`.
+- AI MUST use `@riverpod` annotation on functions for services, repositories, and API clients.
+- AI MUST use `@riverpod` class notation (extending `_$ClassName`) for mutable notifiers.
+- AI MUST use `@Riverpod(keepAlive: true)` for: AppDatabase, SecureStorageService, AppLogger, Dio client, AuthNotifier, router, ConnectivityService, SyncService.
+- AI MUST use auto-dispose (default `@riverpod`) for feature services, feature notifiers, and screen-specific state.
+- AI MUST use `ref.watch(provider)` only inside `build()` methods.
+- AI MUST use `ref.read(provider)` only inside callbacks, event handlers, and notifier methods.
+- AI MUST use `ref.listen(provider, ...)` for one-off side effects like navigation and snackbars.
+- AI MUST use `AsyncValue` with `.when()` for all async state in the UI.
+- AI MUST define complex notifier state as `@freezed sealed class` for exhaustive pattern matching.
+- AI MUST use `family` modifier for providers that require parameters.
+- AI MUST use `StreamNotifier` when the data source is a Drift reactive stream.
+- AI MUST add `part 'filename.g.dart';` and import `riverpod_annotation` in annotated files.
+Prohibited:
+- AI MUST NOT write providers manually using `Provider(...)`, `StateNotifierProvider(...)`, or `ChangeNotifierProvider(...)`.
+- AI MUST NOT create global mutable singletons outside of Riverpod.
+- AI MUST NOT pass `WidgetRef` to services, repositories, or notifier constructors.
+- AI MUST NOT use `ref.read` inside `build()`.
+- AI MUST NOT use `ref.watch` inside callbacks or notifier methods.
+- AI MUST NOT check `.isLoading` or `.hasError` directly — always use `.when()` or `.maybeWhen()`.
+- AI MUST NOT create centralized provider files.
+Patterns:
+- Function provider: `@riverpod AuthService authService(AuthServiceRef ref) => AuthService(...);`
+- Notifier: `@riverpod class AuthNotifier extends _$AuthNotifier { @override FutureOr<AuthState> build() async { ... } }`
+- StreamNotifier: `@riverpod class ItemListNotifier extends _$ItemListNotifier { @override Stream<List<Item>> build() => ref.read(itemRepositoryProvider).watchAll(); }`
+- Family: `@riverpod Future<ItemDetail> itemDetail(ItemDetailRef ref, String itemId) async { ... }`
+Examples:
+- `final state = ref.watch(itemListNotifierProvider);`
+- `state.when(loading: () => LoadingIndicator(), error: (e, _) => ErrorView(error: e.toString()), data: (items) => ItemList(items: items))`

package/rules/flutter/testing.md

@@ -0,0 +1,31 @@
+Rule: Enforce Testing Standards
+Requirements:
+- AI MUST write tests before implementation (TDD).
+- AI MUST write unit tests for every service method, notifier state transition, and repository operation.
+- AI MUST use `mocktail` for mocking — never `mockito` with code generation.
+- AI MUST use `ProviderContainer` with provider overrides to test notifiers without a widget tree.
+- AI MUST use `AppDatabase.inMemory()` for repository tests — never a real database file.
+- AI MUST call `addTearDown(container.dispose)` in every notifier test `setUp`.
+- AI MUST call `tearDown(() => db.close())` in every repository test.
+- AI MUST structure each test using Arrange / Act / Assert.
+- AI MUST use `group()` to organize related tests within a test file.
+- AI MUST name tests descriptively: `'returns items when cache is populated'`.
+- AI MUST place reusable test data in `test/helpers/fixtures/<feature>_fixtures.dart` as `abstract final class`.
+- AI MUST place mock class declarations in `test/helpers/mock_providers.dart`.
+- AI MUST configure mock logger stubs in `setUp` to silence logging during tests.
+- AI MUST test widget screens by overriding providers in a wrapping `ProviderScope`.
+- AI MUST ensure `flutter test --coverage` passes in CI before any PR merges.
+Prohibited:
+- AI MUST NOT use real service implementations in unit tests — always mocks.
+- AI MUST NOT use `mockito` or its code generation in this project.
+- AI MUST NOT write tests that depend on execution order.
+- AI MUST NOT skip tests or mark them as `skip` without an explicit reason.
+Patterns:
+- Mock declaration: `class MockItemService extends Mock implements ItemService {}`
+- ProviderContainer: `container = ProviderContainer(overrides: [itemServiceProvider.overrideWithValue(mockService)]);`
+- Notifier test: `final state = await container.read(itemListNotifierProvider.future);`
+- Widget test: `await tester.pumpWidget(ProviderScope(overrides: [...], child: const MaterialApp(home: ItemListScreen())));`
+- Fixture: `abstract final class ItemFixtures { static final item1 = Item(id: 'item-001', title: 'First Item', ...); }`
+Examples:
+- `when(() => mockService.getItems()).thenAnswer((_) async => Success(items));`
+- `verify(() => mockApi.getItems()).called(1);`

package/rules/nuxt/architecture-principles.md

@@ -0,0 +1,31 @@
+# Architecture Principles
+
+## Core Standards
+- Use one technology stack across all projects: Nuxt 4 + Cloudflare + D1 + Drizzle
+- Maintain one repository per project
+- Configure one database per environment
+- Implement a mandatory services layer for all business logic
+- Generate migrations for every schema change
+- Write tests from day one
+- Deploy using Cloudflare-first architecture
+- Optimize only when measurements justify the need
+
+## Philosophy
+- Prioritize mastery over novelty
+- Choose consistency over experimentation
+- Focus on shipping over theorizing
+- Maintain discipline over chaos
+
+## Application Architecture
+- Use Nuxt as a fullstack framework with `/app` for UI and `/server` for backend
+- Keep API routes thin; business logic belongs in services
+- Access databases only from within service layer
+- Never place business logic in API handlers
+- Never make direct database calls from API files
+
+## When NOT to Use This Stack
+Avoid this architecture when:
+- Complex relational requirements exceed SQLite capabilities
+- Extreme realtime multiplayer scale is required
+- Long-running CPU-intensive workloads are needed
+- On-premise deployment is required

package/rules/nuxt/authentication.md

@@ -0,0 +1,35 @@
+# Authentication Standards
+
+## Choose Authentication Model Based on Project Type
+
+### Internal Applications
+- Use OAuth with Entra / Azure AD
+- Validate JWT in server middleware
+- Map role claims server-side
+- Extract roles from JWT token claims
+
+### Public SaaS Applications
+- Implement OAuth (Google, GitHub) as primary method
+- Optionally support email/password authentication
+- Use HTTP-only cookies for session management
+- Store sessions in D1 database
+- Optionally cache sessions in KV for performance
+
+### Mobile Backends
+- Issue short-lived JWT access tokens (15 minutes recommended)
+- Store refresh tokens in D1 database
+- Implement stateless token validation
+- Never store tokens in frontend local storage
+
+## Global Authentication Rules
+- Implement no role logic in frontend code
+- Enforce all authorization checks server-side
+- Centralize authentication in middleware
+- Never trust client-side authentication state
+- Always validate tokens on every protected request
+
+## Middleware Implementation
+- Create centralized auth middleware at `/server/middleware/auth.ts`
+- Return 401 for missing or invalid tokens
+- Attach user context to request event for downstream use
+- Log authentication failures for security monitoring