reis-mobile 0.3.5

package/skills/architecture-feature-first/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: architecture-feature-first
+description: Structures Flutter apps using layered architecture (UI / Logic / Data) with feature-first file organization. Use when creating new features, designing the project structure, adding repositories/services/view models (or cubits/providers/notifiers), or wiring dependency injection. State management agnostic.
+intents: [architecture]
+stacks: [flutter]
+source: https://github.com/evanca/flutter-ai-rules
+license: MIT
+---
+
+# Flutter Architecture — Feature-First Skill
+
+This skill defines how to design, structure, and implement Flutter applications using the recommended **layered architecture** with **feature-first** file organization.
+
+It is **state management agnostic**: the business logic holder in the UI layer may be named ViewModel, Controller, Cubit, Bloc, Provider, or Notifier — depending on the chosen state management approach. The architectural rules apply equally to all of them.
+
+## When to Use
+
+Use this skill when:
+
+* Designing the folder/file structure of a new Flutter app or feature.
+* Creating a new View, ViewModel, Repository, or Service.
+* Deciding which layer owns a piece of logic.
+* Wiring dependency injection between components.
+* Adding a domain (logic) layer for complex business logic.
+
+---
+
+## 1. Layers
+
+Separate every app into a **UI Layer** and a **Data Layer**. Add a **Logic (Domain) Layer** between them only for complex apps.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│   UI Layer    │  Views + business logic holders              │
+│               │  (ViewModel / Cubit / Controller / Provider) │
+├──────────────────────────────────────────────────────────────┤
+│  Logic Layer  │  Use Cases / Interactors  (optional)         │
+├──────────────────────────────────────────────────────────────┤
+│   Data Layer  │  Repositories + Services                     │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Rules:**
+- Only adjacent layers may communicate. The UI layer must never access a Service directly.
+- The Logic layer is added **only** when business logic is too complex for the business logic holder or is reused across multiple screens.
+- Data changes always happen in the Data layer (SSOT = Repository). No mutation in UI or Logic layers.
+- Follow unidirectional data flow: state flows **down** (Data → UI), events flow **up** (UI → Data).
+
+---
+
+## 2. Feature-First File Structure
+
+Organize code by **feature**, not by type. Group all layers belonging to one feature together in a single directory.
+
+Each feature directory contains the files needed for that feature, named according to the chosen state management approach:
+
+| Approach | Business logic holder file |
+|---|---|
+| MVVM / ChangeNotifier | `*_viewmodel.dart` / `*_controller.dart` |
+| BLoC | `*_cubit.dart` / `*_bloc.dart` |
+| Provider / Riverpod | `*_provider.dart` / `*_notifier.dart` |
+
+Example: an `auth` feature would have files like `auth_viewmodel.dart` (or `auth_cubit.dart`, `auth_provider.dart` depending on approach), `login_screen.dart`, and optionally `login_usecase.dart`.
+
+---
+
+## 3. Component Responsibilities
+
+### View
+- Describes how to present data to the user; keep logic minimal and only UI-related.
+- Passes events to the business logic holder in response to user interactions.
+- Keep views focused on presentation; extract reusable widgets into separate components.
+- Use `StatelessWidget` when possible; keep build methods simple.
+
+### Business Logic Holder (ViewModel / Cubit / Controller / Provider)
+- Contains logic to convert app data into UI state and maintains current state needed by the view.
+- Exposes callbacks (commands) to the View and retrieves/transforms data from repositories.
+- Business logic must not live in UI widgets; only interact with repositories via the business logic holder.
+
+### Repository
+- Single Source of Truth (SSOT) for a given type of model data.
+- The only class allowed to mutate its data; all other classes read from it.
+- Handles business logic such as caching, error handling, and refreshing data.
+- Transforms raw data from services into domain models consumed by business logic holders.
+
+### Service
+- Wraps API endpoints and exposes asynchronous response objects.
+- Isolates data-loading and holds no state.
+
+---
+
+## 4. Domain Layer (Use Cases)
+
+Introduce use cases/interactors **only** when:
+- Logic is complex or does not fit cleanly in the UI or Data layers.
+- Logic is reused across multiple business logic holders or merges data from multiple repositories.
+
+Do not add a domain layer for simple CRUD apps.
+
+---
+
+## 5. Dependency Injection
+
+Use dependency injection to provide components with their dependencies, enabling testability and flexibility.
+
+- Supply repositories to business logic holders via constructors.
+- Supply services to repositories via constructors.
+- Design all components with well-defined interfaces so implementations can be swapped without changing consumers.
+
+---
+
+## References
+
+- [Flutter app architecture guide](https://docs.flutter.dev/app-architecture/guide)
+- [Architecture case study (Compass app)](https://docs.flutter.dev/app-architecture/case-study)
+- [Architecture recommendations](https://docs.flutter.dev/app-architecture/recommendations)

package/skills/bloc/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: bloc
+description: Implements Flutter state management using the bloc library (Bloc and Cubit). Use when creating new features, screens, or state management logic with bloc/cubit, modeling state, wiring Flutter widgets to blocs, or writing bloc/cubit unit tests.
+routing: manual
+stacks: [flutter]
+source: https://github.com/evanca/flutter-ai-rules
+license: MIT
+---
+
+# Bloc Skill
+
+This skill defines how to design, implement, and test state management using the [bloc](https://pub.dev/packages/bloc) and [flutter_bloc](https://pub.dev/packages/flutter_bloc) libraries.
+
+## When to Use
+
+Use this skill when:
+
+* Creating a new Cubit or Bloc for a feature.
+* Modeling state (choosing between sealed classes vs a single state class).
+* Wiring `BlocBuilder`, `BlocListener`, `BlocConsumer`, or `BlocProvider` in the widget tree.
+* Writing unit tests for a Cubit or Bloc.
+* Deciding between Cubit and Bloc.
+
+---
+
+## 1. Cubit vs Bloc
+
+| Situation | Use |
+|---|---|
+| Simple state, no events needed | `Cubit` |
+| Complex flows, event traceability needed | `Bloc` |
+| Advanced event processing (debounce, throttle) | `Bloc` with event transformers |
+
+**Default to `Cubit`. Refactor to `Bloc` only when requirements grow.**
+
+---
+
+## 2. Naming Conventions
+
+### Events (Bloc only)
+- Named in **past tense**: `LoginButtonPressed`, `UserProfileLoaded`.
+- Format: `BlocSubject` + optional noun + verb.
+- Initial load event: `BlocSubjectStarted` (e.g., `AuthenticationStarted`).
+- Base event class: `BlocSubjectEvent`.
+
+### States
+- Named as **nouns** (states are snapshots in time).
+- Base state class: `BlocSubjectState`.
+- Sealed subclasses: `BlocSubject` + `Initial` | `InProgress` | `Success` | `Failure`.
+  - Example: `LoginInitial`, `LoginInProgress`, `LoginSuccess`, `LoginFailure`.
+- Single-class approach: `BlocSubjectState` + `BlocSubjectStatus` enum (`initial`, `loading`, `success`, `failure`).
+
+---
+
+## 3. Modeling State
+
+### When to use a sealed class with subclasses
+- States are **well-defined and mutually exclusive**.
+- Type-safe exhaustive `switch` is desired.
+- Subclass-specific properties exist.
+
+```dart
+@immutable
+sealed class LoginState extends Equatable {
+  const LoginState();
+}
+
+final class LoginInitial extends LoginState {
+  @override
+  List<Object?> get props => [];
+}
+
+final class LoginInProgress extends LoginState {
+  @override
+  List<Object?> get props => [];
+}
+
+final class LoginSuccess extends LoginState {
+  const LoginSuccess(this.user);
+  final User user;
+  @override
+  List<Object?> get props => [user];
+}
+
+final class LoginFailure extends LoginState {
+  const LoginFailure(this.message);
+  final String message;
+  @override
+  List<Object?> get props => [message];
+}
+```
+
+Handle all states exhaustively in the UI:
+```dart
+switch (state) {
+  case LoginInitial():  ...
+  case LoginInProgress(): ...
+  case LoginSuccess(:final user): ...
+  case LoginFailure(:final message): ...
+}
+```
+
+### When to use a single class with a status enum
+- Many shared properties across states.
+- Simpler, more flexible; previous data must be retained after failure.
+
+```dart
+enum LoginStatus { initial, loading, success, failure }
+
+@immutable
+class LoginState extends Equatable {
+  const LoginState({
+    this.status = LoginStatus.initial,
+    this.user,
+    this.errorMessage,
+  });
+
+  final LoginStatus status;
+  final User? user;
+  final String? errorMessage;
+
+  LoginState copyWith({
+    LoginStatus? status,
+    User? user,
+    String? errorMessage,
+  }) {
+    return LoginState(
+      status: status ?? this.status,
+      user: user ?? this.user,
+      errorMessage: errorMessage ?? this.errorMessage,
+    );
+  }
+
+  @override
+  List<Object?> get props => [status, user, errorMessage];
+}
+```
+
+### State rules (both approaches)
+- Extend `Equatable` and pass all relevant fields to `props`.
+- Copy `List`/`Map` properties with `List.of`/`Map.of` inside `props`.
+- Annotate with `@immutable`.
+- Always emit a **new instance**; never reuse the same state object.
+- Duplicate states are ignored by bloc — ensure meaningful state changes.
+
+---
+
+## 4. Cubit Implementation
+
+```dart
+class LoginCubit extends Cubit<LoginState> {
+  LoginCubit(this._authRepository) : super(const LoginState());
+
+  final AuthRepository _authRepository;
+
+  Future<void> login(String email, String password) async {
+    emit(state.copyWith(status: LoginStatus.loading));
+    try {
+      final user = await _authRepository.login(email, password);
+      emit(state.copyWith(status: LoginStatus.success, user: user));
+    } catch (e) {
+      emit(state.copyWith(status: LoginStatus.failure, errorMessage: e.toString()));
+    }
+  }
+}
+```
+
+Rules:
+- Only call `emit` inside the Cubit/Bloc.
+- Public methods return `void` or `Future<void>` only.
+- Keep business logic out of UI.
+
+---
+
+## 5. Bloc Implementation
+
+```dart
+sealed class LoginEvent {}
+final class LoginSubmitted extends LoginEvent {
+  LoginSubmitted({required this.email, required this.password});
+  final String email;
+  final String password;
+}
+
+class LoginBloc extends Bloc<LoginEvent, LoginState> {
+  LoginBloc(this._authRepository) : super(LoginInitial()) {
+    on<LoginSubmitted>(_onLoginSubmitted);
+  }
+
+  final AuthRepository _authRepository;
+
+  Future<void> _onLoginSubmitted(
+    LoginSubmitted event,
+    Emitter<LoginState> emit,
+  ) async {
+    emit(LoginInProgress());
+    try {
+      final user = await _authRepository.login(event.email, event.password);
+      emit(LoginSuccess(user));
+    } catch (e) {
+      emit(LoginFailure(e.toString()));
+    }
+  }
+}
+```
+
+Rules:
+- Trigger state changes via `bloc.add(Event())`, not custom public methods.
+- Keep event handler methods private (`_onEventName`).
+- Internal/repository events must be private and may use custom transformers.
+
+---
+
+## 6. Architecture
+
+Three layers — each must stay in its own boundary:
+
+```
+Presentation  →  Business Logic (Cubit/Bloc)  →  Data (Repository → DataProvider)
+```
+
+- **Data Layer**: Repositories wrap data providers. Providers perform raw CRUD (HTTP, DB). Repositories expose clean domain objects.
+- **Business Logic Layer**: Cubits/Blocs receive repository data and emit states. Inject repositories via constructor.
+- **Presentation Layer**: Renders UI based on state. Handles user input by calling cubit methods or adding bloc events.
+
+Rules:
+- Blocs must not access data providers directly — only via repositories.
+- No direct bloc-to-bloc communication. Use `BlocListener` in the UI to bridge blocs.
+- For shared data, inject the same repository into multiple blocs.
+- Initialize `BlocObserver` in `main.dart`.
+
+---
+
+## 7. Flutter Bloc Widgets
+
+| Widget | Use |
+|---|---|
+| `BlocProvider` | Provide a bloc to a subtree |
+| `MultiBlocProvider` | Provide multiple blocs without nesting |
+| `BlocBuilder` | Rebuild UI on state change |
+| `BlocListener` | Side effects only (navigation, dialogs, snackbars) |
+| `MultiBlocListener` | Listen to multiple blocs without nesting |
+| `BlocConsumer` | Rebuild UI + side effects together |
+| `BlocSelector` | Rebuild only when a selected slice of state changes |
+| `RepositoryProvider` | Provide a repository to the widget tree |
+| `MultiRepositoryProvider` | Provide multiple repositories without nesting |
+
+```dart
+BlocProvider(
+  create: (context) => LoginCubit(context.read<AuthRepository>()),
+  child: LoginView(),
+);
+
+BlocBuilder<LoginCubit, LoginState>(
+  builder: (context, state) {
+    return switch (state.status) {
+      LoginStatus.loading => const CircularProgressIndicator(),
+      LoginStatus.success => const HomeView(),
+      LoginStatus.failure => Text(state.errorMessage ?? 'Error'),
+      LoginStatus.initial => const LoginForm(),
+    };
+  },
+);
+
+BlocListener<LoginCubit, LoginState>(
+  listener: (context, state) {
+    if (state.status == LoginStatus.failure) {
+      ScaffoldMessenger.of(context).showSnackBar(
+        SnackBar(content: Text(state.errorMessage ?? 'Login failed')),
+      );
+    }
+  },
+  child: LoginForm(),
+);
+```
+
+Rules:
+- Use `context.read<T>()` in callbacks (not in `build`).
+- Use `context.watch<T>()` in `build` only when necessary; prefer `BlocBuilder`.
+- Never call `context.watch` or `context.select` at the root of `build` — scope with `Builder`.
+- Handle **all** possible states in the UI (initial, loading, success, failure).
+
+---
+
+## 8. Testing
+
+Use `bloc_test` package. Mock repositories with `mocktail`.
+
+```dart
+import 'package:bloc_test/bloc_test.dart';
+import 'package:mocktail/mocktail.dart';
+import 'package:test/test.dart';
+
+class MockAuthRepository extends Mock implements AuthRepository {}
+
+void main() {
+  group('LoginCubit', () {
+    late AuthRepository authRepository;
+    late LoginCubit loginCubit;
+
+    setUp(() {
+      authRepository = MockAuthRepository();
+      loginCubit = LoginCubit(authRepository);
+    });
+
+    tearDown(() => loginCubit.close());
+
+    test('initial state should be LoginState with status initial', () {
+      expect(loginCubit.state, const LoginState());
+    });
+
+    blocTest<LoginCubit, LoginState>(
+      'should emit [loading, success] when login succeeds',
+      build: () {
+        when(() => authRepository.login(any(), any()))
+            .thenAnswer((_) async => fakeUser);
+        return loginCubit;
+      },
+      act: (cubit) => cubit.login('email@test.com', 'password'),
+      expect: () => [
+        const LoginState(status: LoginStatus.loading),
+        LoginState(status: LoginStatus.success, user: fakeUser),
+      ],
+    );
+
+    blocTest<LoginCubit, LoginState>(
+      'should emit [loading, failure] when login throws',
+      build: () {
+        when(() => authRepository.login(any(), any()))
+            .thenThrow(Exception('error'));
+        return loginCubit;
+      },
+      act: (cubit) => cubit.login('email@test.com', 'wrong'),
+      expect: () => [
+        const LoginState(status: LoginStatus.loading),
+        isA<LoginState>().having((s) => s.status, 'status', LoginStatus.failure),
+      ],
+    );
+  });
+}
+```
+
+Rules:
+- Always call `tearDown(() => cubit.close())`.
+- Use `blocTest` for state emission assertions.
+- Use `group()` named after the class under test.
+- Name test cases with "should" to describe expected behavior.
+- Register fallback values for custom types: `registerFallbackValue(MyEvent())`.
+
+---
+
+## References
+
+- [Bloc GitHub Repository](https://github.com/felangel/bloc)

package/skills/code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: code-review
+description: Performs thorough code reviews for Flutter/Dart pull requests and merge requests. Use when asked to review a PR, MR, branch, or a set of changed files. Follows a structured checklist covering correctness, security, style, testing, and documentation.
+intents: [review]
+stacks: [flutter]
+source: https://github.com/evanca/flutter-ai-rules
+license: MIT
+---
+
+# Code Review Skill
+
+This skill defines how to perform structured, objective code reviews.
+
+## When to Use
+
+Use this skill when:
+
+* Asked to review a pull request, merge request, or branch.
+* Evaluating changed, added, or deleted files for correctness and quality.
+
+---
+
+## Review Process
+
+### 1. Branch and Merge Target
+
+- Confirm the current branch is a **feature, bugfix, or PR/MR branch** — not the project's primary branch (e.g. `main`, `master`, `develop`, or equivalent).
+- Verify the branch is **up-to-date** with the target branch.
+- Identify the **target branch** for the merge.
+
+### 2. Change Discovery
+
+- List all **changed, added, and deleted files**.
+- For each change, look up the **commit title** and review how connected components are implemented.
+- **Never assume** a change or fix is correct without investigating the implementation details.
+- If a change remains difficult to understand after several attempts, **note this explicitly** in your report.
+
+### 3. Per-File Review
+
+For every changed file, check:
+
+| Area | What to verify |
+|---|---|
+| **Location** | File is in the correct directory |
+| **Naming** | File name follows naming conventions |
+| **Responsibility** | The file's responsibility is clear; reason for its change is understandable |
+| **Readability** | Variable, function, and class names are descriptive and consistent |
+| **Logic & correctness** | No logic errors or missing edge cases |
+| **Maintainability** | Code is modular; no unnecessary duplication |
+| **Error handling** | Errors and exceptions are handled appropriately |
+| **Security** | No input validation issues; no secrets committed to code |
+| **Performance** | No obvious performance issues or inefficiencies |
+| **Documentation** | Public APIs, complex logic, and new modules are documented |
+| **Test coverage** | New or changed logic has sufficient tests |
+| **Style** | Code matches the project's style guide and coding patterns |
+
+For **generated files**: confirm they are up-to-date and not manually modified.
+
+### 4. Overall Change Set
+
+- Verify the change set is **focused and scoped** to its stated purpose — no unrelated or unnecessary changes.
+- Check that the **PR/MR description** accurately reflects the changes made.
+- Confirm **new or updated tests** cover new or changed logic.
+- Evaluate whether tests could **actually fail**, or only verify a mock implementation.
+
+### 5. CI and Tests
+
+- Ensure **all tests pass** in the continuous integration system.
+- Fetch **online documentation** when unsure about best practices for a particular package or library.
+
+---
+
+## Feedback Standards
+
+- Be **objective and reasonable** — avoid automatic praise or flattery.
+- Take a **devil's advocate approach**: give honest, thoughtful feedback.
+- Provide **clear, constructive feedback** for any issues found, with suggestions for improvement.
+- Include **requests for clarification** for anything that is unclear.
+
+---
+
+## Output Format
+
+Provide your review as a **chat response**, covering conclusions and recommendations **per file**, including:
+
+1. Summary of what changed and why
+2. Issues found (with severity: suggestion / minor / major)
+3. Specific recommendations or questions per file
+4. Overall verdict: approved, approved with suggestions, or changes requested