reis-mobile 0.4.0 → 0.6.0

package/skills/{android-navigation-event/SKILL.md → mobile-android/references/ui/navigation-event/GUIDE.md}

@@ -1,28 +1,4 @@
----
-name: android-navigation-event
-description: Intercept back gestures and run Predictive Back animations using the
-  NavigationEvent (androidx.navigationevent) library in Compose Android. Handles Activity
-  setup, parent-child dispatcher scoping in `ViewPagers` or tabs, Compose `NavigationBackHandler`,
-  and migration from legacy `BackHandler` on SDK 36+.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-09-01'
-  keywords:
-  - Android
-  - Navigation Event
-  - Jetpack Compose
-  - Back Navigation
-  - Dispatcher
-  - Guidelines
-  - Troubleshooting
-  - ComponentActivity
-  - Dialog
-  - ViewPager
----
+> Adapted from the `navigation-event` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Common guidelines
 

package/skills/{android-styles/SKILL.md → mobile-android/references/ui/styles/GUIDE.md}

@@ -1,24 +1,4 @@
----
-name: android-styles
-description: Use this skill to integrate the Jetpack Compose Styles API into an Android
-  project. This skill guides you through upgrading dependencies, setting up component
-  themes, making custom components styleable, and migrating existing layout properties
-  to use unified styles. Migrate custom design system components, replace hard coded
-  parameters with Style attributes, and use Modifier.styleable for interaction states.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-09-08'
-  keywords:
-  - Jetpack Compose
-  - Styles
-  - Theming with Styles
-  - Migrate to Styles
-  - Modifier.styleable
----
+> Adapted from the `styles` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Limitations
 

package/skills/mobile-android/references/ui.md

@@ -0,0 +1,14 @@
+# Android: UI and navigation
+
+Jetpack Compose, adaptive layouts, edge-to-edge, styles, XML-to-Compose migration and Navigation 3.
+
+| Guide | What it covers |
+|---|---|
+| [adaptive](ui/adaptive/GUIDE.md) | Instructions to make or update an app's UI so that it adapts to different Android devices including phones, tablets, foldables, laptops, desktop, TV, Auto and XR. |
+| [edge-to-edge](ui/edge-to-edge/GUIDE.md) | Use this skill to migrate your Jetpack Compose app to add adaptive edge-to-edge support and troubleshoot common issues. |
+| [styles](ui/styles/GUIDE.md) | Use this skill to integrate the Jetpack Compose Styles API into an Android project. |
+| [migrate-xml-views-to-jetpack-compose](ui/migrate-xml-views-to-jetpack-compose/GUIDE.md) | Provides a structured workflow for migrating an Android XML View to Jetpack Compose. |
+| [navigation-3](ui/navigation-3/GUIDE.md) | Learn how to install and migrate to Jetpack Navigation 3, and how to implement features and patterns such as deep links, multiple backstacks, scenes (dialogs, bottom sheets, list-detail, two-pane, supporting pane), conditional navigation (such as logged-in navigation versus anonymous), returning results from flows, integration with Hilt, ViewModel, Kotlin, and view interoperability. |
+| [navigation-event](ui/navigation-event/GUIDE.md) | Intercept back gestures and run Predictive Back animations using the NavigationEvent (androidx.navigationevent) library in Compose Android. |
+
+Each guide lives in its own folder with its references and scripts. Relative paths in a guide — and `<repo_root>` where a guide uses it — refer to that guide's folder.

package/skills/mobile-architecture/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mobile-architecture
+description: Designs and reviews the architecture of mobile apps on every stack — layers (UI, domain, data), unidirectional data flow, state ownership and state management, feature-first modularization, dependency injection, navigation, offline data and use cases — for Flutter (BLoC, Riverpod, Provider, ChangeNotifier), native Android (ViewModel, Hilt, Gradle modules), native iOS (SwiftUI and UIKit, Observation, Swift packages, actors) and React Native (server vs client state, React Navigation, Expo Router, native modules). Use when structuring a new app or feature, choosing or implementing state management, refactoring to layers or modules, or when the user asks where code should live, even if they only mention one class or screen.
+intents: [architecture]
+stacks: ["*"]
+---
+
+# Mobile Architecture
+
+What makes a mobile codebase keep up with its team, and how each stack expresses it. This file holds the principles; each platform's patterns, libraries and structure live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) — structure guides and one guide per state management library |
+| Native Android (Kotlin), or the Android side of Kotlin Multiplatform | [references/android.md](references/android.md) |
+| Native iOS (Swift) | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+
+## 2. Map before judging
+
+Read the entry point, navigation setup, dependency wiring, module or package graph and two or three representative features before proposing changes. A coherent structure that differs from the references is not a finding; inconsistency and coupling are.
+
+## 3. Principles on every stack
+
+- **Layers with one direction of dependency.** UI renders state and sends events; logic (view models, blocs, stores, use cases) decides; data (repositories and data sources) fetches and stores. UI never calls HTTP clients, databases or platform SDKs directly.
+- **Unidirectional data flow.** State flows down to the UI; events flow up. The UI does not mutate shared state in place.
+- **Single source of truth.** Each piece of data has one owner — usually a repository — that the rest of the app observes. Duplicated copies drift.
+- **State ownership.** Screen state lives with the screen's logic and survives configuration changes where the platform requires it; app-wide state (session, settings) has one explicit owner; server data lives in a cache or repository, not copied into global stores.
+- **Impossible states unrepresentable.** Model loading, content and error as one sealed or discriminated state instead of independent flags.
+- **Feature boundaries.** Organize by feature once there are several; features depend on shared core code, not on each other's internals.
+- **Dependencies injected.** Construct dependencies at a composition root (DI container or initializers) and pass them in; no service locators reached from deep inside features.
+- **Offline and errors by design.** Decide what works offline, how writes sync and how failures reach the user before building screens.
+- **Testability as a check.** If business logic cannot be tested without a device, it is in the wrong layer.
+
+## 4. Proportion
+
+Match the structure to the app and team. A domain layer, a DI framework or a multi-module build pays off with size and team count; adding them to a small app is also a finding. Propose incremental steps with the files involved, highest impact and lowest risk first.
+
+## Output
+
+```markdown
+## Architecture Overview
+## Architecture Issues
+## Coupling Problems
+## Refactoring Suggestions
+## Recommended Architecture
+## Action Plan
+```
+
+Cite `path:line` for every finding.

package/skills/mobile-architecture/references/android.md

@@ -0,0 +1,54 @@
+# Android architecture
+
+Follows Google's guide to app architecture. Adapt to the project instead of forcing a rewrite.
+
+## Layers
+
+- **UI layer:** Composables (or Views) render a `UiState` exposed by a `ViewModel` as `StateFlow`; user events call `ViewModel` functions. Composables stay stateless where possible and receive state and callbacks as parameters (state hoisting).
+- **Domain layer (optional):** use cases for business logic that is reused by several `ViewModel`s or complex enough to test alone. Name them by action (`GetUserOrdersUseCase`) with one public `operator fun invoke`.
+- **Data layer:** repositories are the single source of truth, expose `Flow` or suspend functions, and hide data sources (Retrofit/Ktor services, Room DAOs, DataStore). Offline-first apps read from the database and sync from the network into it.
+
+```kotlin
+@HiltViewModel
+class OrdersViewModel @Inject constructor(repository: OrdersRepository) : ViewModel() {
+    val uiState: StateFlow<OrdersUiState> = repository.observeOrders()
+        .map<List<Order>, OrdersUiState> { OrdersUiState.Content(it) }
+        .catch { emit(OrdersUiState.Error) }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), OrdersUiState.Loading)
+}
+```
+
+The names are illustrative; use the project's conventions.
+
+## State
+
+- `ViewModel` survives configuration changes; `SavedStateHandle` keeps what must survive process death (ids, form input).
+- Collect state in the UI with lifecycle awareness (`collectAsStateWithLifecycle` in Compose, `repeatOnLifecycle` in Views).
+- One-off events (navigation, messages) are modeled as state the UI consumes, or handled by the UI directly, not replayed on rotation.
+
+## Modularization
+
+```text
+:app                         application, navigation graph, DI wiring
+:feature:<name>              screens and ViewModels of one feature
+:core:data, :core:domain     repositories, use cases
+:core:ui, :core:designsystem shared UI and theme
+:core:testing                fakes and test utilities
+```
+
+- Feature modules do not depend on each other; they communicate through navigation and `:core` contracts.
+- Prefer `implementation` over `api` dependencies to keep modules decoupled and builds incremental.
+- Share build logic with convention plugins and versions with the version catalog.
+- Split into modules when build time, ownership or boundaries need it, not by default in a small app.
+
+## Dependency injection and navigation
+
+- Hilt (or Koin) at the composition root; constructor injection everywhere else. Dispatchers are injected so tests can control them.
+- Navigation: Navigation Compose, or Navigation 3 for new Compose apps (see `mobile-android` → UI). Pass ids between destinations, not objects.
+
+## Problems to look for
+
+- Activities, Fragments or Composables calling DAOs, Retrofit services or `SharedPreferences`.
+- `ViewModel`s holding `Context`, Views or Activity references.
+- Several classes owning the same data, or UI state split into contradictory fields.
+- A single `:app` module in a large codebase, or circular and `api`-leaking module dependencies.

package/skills/{flutter-app-architecture/SKILL.md → mobile-architecture/references/flutter/app-architecture.md}

@@ -1,11 +1,4 @@
----
-name: flutter-app-architecture
-description: Provides best practices for Flutter app architecture, including layered architecture, data flow, state management patterns, and extensibility guidelines.
-intents: [architecture]
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `flutter-app-architecture` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter App Architecture Skill
 

package/skills/{flutter-bloc/SKILL.md → mobile-architecture/references/flutter/bloc.md}

@@ -1,11 +1,4 @@
----
-name: flutter-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
----
+> Adapted from the `bloc` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Bloc Skill
 

package/skills/{flutter-change-notifier/SKILL.md → mobile-architecture/references/flutter/change-notifier.md}

@@ -1,11 +1,4 @@
----
-name: flutter-change-notifier
-description: Implements state management with ChangeNotifier and Provider in Flutter. Use when setting up ChangeNotifier models, providing them to the widget tree, consuming state with Consumer or Provider.of, or optimizing rebuilds.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `flutter-change-notifier` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter ChangeNotifier Skill
 

package/skills/{flutter-architecture-feature-first/SKILL.md → mobile-architecture/references/flutter/feature-first.md}

@@ -1,11 +1,4 @@
----
-name: flutter-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
----
+> Adapted from the `architecture-feature-first` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter Architecture — Feature-First Skill
 

package/skills/{flutter-login-usecase/SKILL.md → mobile-architecture/references/flutter/login-use-case.md}

@@ -1,10 +1,3 @@
----
-name: flutter-login-usecase
-description: "Implements a Flutter login use case that authenticates through an injected repository and persists the access token through an injected storage abstraction. Use when building or reviewing the login flow of a Flutter app with layered architecture."
-routing: manual
-stacks: [flutter]
----
-
 # flutter-login-usecase
 
 ## Description

package/skills/{flutter-managing-state/SKILL.md → mobile-architecture/references/flutter/managing-state.md}

@@ -1,14 +1,5 @@
----
-name: flutter-managing-state
-description: Manages application and ephemeral state in a Flutter app. Use when sharing data between widgets or handling complex UI state transitions.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Thu, 12 Mar 2026 22:18:06 GMT
-intents: [architecture]
-stacks: [flutter]
-source: https://github.com/flutter/skills
-license: BSD-3-Clause
----
+> Adapted from the `flutter-managing-state` skill in [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Managing State in Flutter
 
 ## Contents

package/skills/{flutter-provider/SKILL.md → mobile-architecture/references/flutter/provider.md}

@@ -1,11 +1,4 @@
----
-name: flutter-provider
-description: Uses the Provider package for dependency injection and state management in Flutter. Use when setting up providers, consuming state, optimizing rebuilds, using ProxyProvider, or migrating from deprecated providers.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `provider` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Provider Skill
 

package/skills/{flutter-apply-architecture-best-practices/SKILL.md → mobile-architecture/references/flutter/recommended-architecture.md}

@@ -1,14 +1,5 @@
----
-name: flutter-apply-architecture-best-practices
-description: Architects a Flutter application using the recommended layered approach (UI, Logic, Data). Use when structuring a new project or refactoring for scalability.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 20:11:20 GMT
-intents: [architecture]
-stacks: [flutter]
-source: https://github.com/flutter/skills
-license: BSD-3-Clause
----
+> Adapted from the `flutter-apply-architecture-best-practices` skill in [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Architecting Flutter Applications
 
 ## Contents

package/skills/{flutter-riverpod/SKILL.md → mobile-architecture/references/flutter/riverpod.md}

@@ -1,11 +1,4 @@
----
-name: flutter-riverpod
-description: Uses Riverpod for state management in Flutter/Dart. Use when setting up providers, combining requests, managing state disposal, passing arguments, performing side effects, testing providers, or applying Riverpod best practices.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `riverpod` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Riverpod Skill
 

package/skills/mobile-architecture/references/flutter.md

@@ -0,0 +1,21 @@
+# Flutter architecture
+
+Start with the structure guides, then the guide for the state management the project uses. Do not introduce a second state management approach without a reason the user agrees with.
+
+| Guide | What it covers |
+|---|---|
+| [app-architecture](flutter/app-architecture.md) | Provides best practices for Flutter app architecture, including layered architecture, data flow, state management patterns, and extensibility guidelines. |
+| [feature-first](flutter/feature-first.md) | Structures Flutter apps using layered architecture (UI / Logic / Data) with feature-first file organization. |
+| [recommended-architecture](flutter/recommended-architecture.md) | Architects a Flutter application using the recommended layered approach (UI, Logic, Data). |
+| [managing-state](flutter/managing-state.md) | Manages application and ephemeral state in a Flutter app. |
+| [bloc](flutter/bloc.md) | Implements Flutter state management using the bloc library (Bloc and Cubit). |
+| [riverpod](flutter/riverpod.md) | Uses Riverpod for state management in Flutter/Dart. |
+| [provider](flutter/provider.md) | Uses the Provider package for dependency injection and state management in Flutter. |
+| [change-notifier](flutter/change-notifier.md) | Implements state management with ChangeNotifier and Provider in Flutter. |
+| [login-use-case](flutter/login-use-case.md) | Implements a Flutter login use case that authenticates through an injected repository and persists the access token through an injected storage abstraction. |
+
+## Deciding
+
+- Detect the state management in `pubspec.yaml` (`flutter_bloc`, `flutter_riverpod`/`riverpod`, `provider`) and in `lib/` before recommending one.
+- Layers: UI (widgets) → logic (blocs, notifiers, view models) → data (repositories, data sources). Widgets do not call HTTP clients, databases or plugins directly.
+- Feature-first folders scale better than folders by technical type once the app has several features.

package/skills/mobile-architecture/references/ios.md

@@ -0,0 +1,58 @@
+# iOS architecture
+
+Adapt to what the project uses — SwiftUI or UIKit, MVVM or another pattern — instead of forcing a rewrite. Check the deployment target before recommending APIs such as `@Observable` (iOS 17) or SwiftData (iOS 17).
+
+## Layers
+
+- **Presentation:** SwiftUI views stay declarative and render state from an observable model; UIKit view controllers stay thin and delegate to a view model or presenter.
+- **Domain / services:** business rules in plain Swift types behind protocols, testable without UI.
+- **Data:** API clients, persistence (SwiftData, Core Data, files, Keychain) and caching behind repository-like types. Views never call `URLSession` or `UserDefaults` directly.
+
+```swift
+@MainActor
+@Observable
+final class OrdersModel {
+    private(set) var state: LoadState<[Order]> = .loading
+    private let repository: OrdersRepository
+
+    init(repository: OrdersRepository) { self.repository = repository }
+
+    func load() async {
+        do { state = .loaded(try await repository.orders()) }
+        catch { state = .failed(error) }
+    }
+}
+```
+
+The names are illustrative. Before iOS 17, the same model is an `ObservableObject` with `@Published` properties.
+
+## State ownership
+
+- The view that creates a model owns it: `@State` with `@Observable`, or `@StateObject` with `ObservableObject`. Views that receive it do not recreate it (`@ObservedObject`, `@Bindable` or a plain property).
+- App-wide dependencies are injected at the root (initializers or the SwiftUI environment), not reached through singletons.
+- Navigation state lives in one place per flow: a `NavigationStack` path in a model, or a coordinator in UIKit.
+
+## Concurrency boundaries
+
+- UI-facing types are `@MainActor`.
+- Shared mutable state lives in an `actor` or is confined to one isolation domain.
+- Types crossing isolation boundaries are `Sendable`; compiler warnings about isolation are architecture findings, not noise.
+
+## Modularization
+
+```text
+App/                         app target: composition root, navigation, app lifecycle
+Packages/
+  Core/                      networking, persistence, design system, shared models
+  Features/<Name>/           views and models of one feature
+```
+
+- Local Swift packages make boundaries explicit and build incrementally; features depend on `Core`, not on each other.
+- Split when build time, ownership or boundaries need it; a small app does not need a package per screen.
+
+## Problems to look for
+
+- Massive view controllers or views mixing networking, persistence and layout.
+- Singletons used as shared mutable state across features.
+- Models recreated by views that do not own them; navigation state scattered across views.
+- `DispatchQueue.main.async` sprinkled to silence threading warnings instead of actor isolation.

package/skills/mobile-architecture/references/react-native.md

@@ -0,0 +1,61 @@
+# React Native architecture
+
+Adapt to what the project uses — Expo or bare React Native, React Navigation or Expo Router, its state libraries — instead of forcing a rewrite. Check the versions in `package.json` before recommending APIs.
+
+## Structure
+
+```text
+src/
+  app/ or navigation/        routes (Expo Router) or navigators, providers
+  features/<name>/
+    screens/                 screen components
+    components/              feature components
+    hooks/                   feature logic exposed as hooks
+    api/                     requests and response mapping
+  shared/                    design system, API client, utilities, types
+```
+
+Features depend on `shared`; they do not import each other's internals.
+
+## State: decide by kind
+
+| Kind | Where it lives |
+|---|---|
+| Server state (data from APIs) | A server-state cache: TanStack Query or RTK Query — caching, refetching, retries and invalidation included |
+| Screen state (inputs, toggles) | `useState`/`useReducer` in the screen or a feature hook |
+| App-wide client state (session, preferences) | A small store (Zustand, Redux Toolkit) or context with a narrow value |
+| Navigation state | The router; pass ids in params, not objects |
+| Persisted state | MMKV or AsyncStorage for preferences, SQLite for relational data, the Keychain/Keystore for secrets |
+
+Copying server data into a global store and synchronizing it by hand is the most common source of stale data.
+
+## Logic in hooks, UI in components
+
+```tsx
+export function useOrders() {
+  return useQuery({ queryKey: ['orders'], queryFn: api.orders.list });
+}
+
+export function OrdersScreen() {
+  const { data, isPending, isError, refetch } = useOrders();
+  if (isPending) return <Loading />;
+  if (isError) return <ErrorState onRetry={refetch} />;
+  return <OrderList orders={data} />;
+}
+```
+
+The names are illustrative. Components render and delegate; data access and rules live in hooks and plain TypeScript modules that can be tested without rendering.
+
+## Boundaries
+
+- **API layer:** one typed client; responses validated or mapped at the boundary (for example with zod) instead of `as` casts in screens.
+- **Platform differences:** `.ios.tsx`/`.android.tsx` files or a small platform module, not `Platform.OS` checks spread across screens.
+- **Native code:** behind a typed module interface (Turbo Modules or Expo Modules), wrapped once. Check whether the app runs on the New Architecture before choosing a native module approach.
+- **Configuration:** environment values through the build (app config, EAS environment variables); secrets stay on the backend.
+
+## Problems to look for
+
+- `fetch`/`axios` calls and business rules inside components and effects.
+- One large context re-rendering the whole app on any change, or deep prop drilling.
+- Large objects or callbacks passed through navigation params.
+- `strict` TypeScript disabled in a codebase that relies on types.

package/skills/mobile-code-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mobile-code-review
+description: Reviews mobile code for the bugs that reach production on every stack — Flutter and Dart (pull request checklist, widget lifecycle and rebuilds, project health, static analysis), native Android (Kotlin, coroutines, Jetpack Compose, lifecycle), native iOS (Swift concurrency, SwiftUI, retain cycles) and React Native (hooks, re-renders, platform code, Expo) — with file:line evidence and a structured report. Use whenever the user asks for a code review, PR or merge request review, project audit or quality check of a mobile app, or runs /reis-mobile:review, even if they only point at a diff or a folder.
+intents: [review, performance]
+stacks: ["*"]
+---
+
+# Mobile Code Review
+
+One review process for every mobile stack. This file holds how to review and what always matters; each platform's checklist lives in its reference.
+
+## 1. Pick the checklists
+
+Detect the stack first, then apply the platform checklist to the files in scope:
+
+| Project | Read |
+|---|---|
+| Flutter / Dart | [references/flutter.md](references/flutter.md), which orders the Flutter checklists in `references/flutter/` |
+| Native Android (Kotlin/Java), or the Android side of Kotlin Multiplatform | [references/android.md](references/android.md) |
+| Native iOS (Swift/Objective-C) | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+
+In a cross-platform app, native code in `android/`, `ios/` or native modules gets the native checklist too. Security findings follow `mobile-security` when it is loaded.
+
+## 2. Scope
+
+- **Changes (diff or pull request):** review what changed, reading the whole file when the hunk is not enough to understand it. New untracked files are not in the diff; read them.
+- **Whole project:** start at the entry points (app startup, navigation, dependency setup), then the data layer, authentication and the most complex screens.
+
+## 3. Evidence before findings
+
+- Open the code and confirm every suspicion. A finding without evidence at `file:line` does not go in the report.
+- Do not invent APIs, versions or lint rules. Check the lock files and build files (`pubspec.lock`, version catalog, `Package.resolved`, `package.json`) before claiming something is missing, deprecated or unavailable.
+- Do not report style that a configured linter already enforces.
+- When the project deliberately does something differently and it is coherent, say so instead of flagging it.
+
+## 4. What always matters, on any stack
+
+- **Lifecycle:** async work that outlives its screen; listeners, subscriptions, timers and controllers never released.
+- **Threading:** I/O or heavy parsing on the main/UI thread; UI updated off it.
+- **State:** impossible states that can be represented; loading and error handled; state lost on rotation, backgrounding or process death.
+- **Network:** timeouts, retries without backoff, offline handling, unvalidated responses.
+- **Credentials:** tokens in insecure storage, secrets in code or the bundle, sensitive data in logs.
+- **Platform:** permissions requested without handling denial; manifest, `Info.plist`, entitlements or config changes that affect store publishing.
+- **Tests:** new logic without tests when the project already has a suite.
+
+## 5. Severity
+
+Rank by real impact on users: crash or data loss, credential leak, store rejection, then noticeable degradation, then maintainability. Say why each finding matters, not only what rule it breaks.
+
+## Report
+
+Unless an agent defines its own format, answer with:
+
+```markdown
+## Summary
+Stack, scope (diff or project), verdict: approve | approve-with-changes | request-changes.
+
+## Critical
+## Bugs
+## Architecture
+## Security
+## Performance
+## Maintainability
+
+## Suggested changes
+Prioritized list. For each item: file:line, problem, why it matters, fix.
+```
+
+Write "No findings." in a section with nothing to report.

package/skills/{android-code-review/SKILL.md → mobile-code-review/references/android.md}

@@ -1,10 +1,3 @@
----
-name: android-code-review
-description: Reviews native Android code in Kotlin and Java for the bugs that reach production — lifecycle and Context leaks, coroutine scope, dispatcher and cancellation mistakes, Flow collection outside the lifecycle, Jetpack Compose state, recomposition and side effects, state lost on configuration change or process death, main-thread I/O, WorkManager and permission handling, and exported components. Use when reviewing Kotlin or Java files in an Android app or module, Activities, Fragments, ViewModels, Composables, repositories or Gradle modules, or when the user asks for an Android code review or PR review.
-intents: [review, performance]
-stacks: [android, kotlin-multiplatform]
----
-
 # Android Code Review
 
 Apply to Kotlin and Java sources under `src/main` (and `androidMain` in KMP). Items are ordered by impact: the first sections cause crashes, leaks or lost user data. Before flagging an API as missing or deprecated, check the library versions in the version catalog or build files.
@@ -41,7 +34,7 @@ Apply to Kotlin and Java sources under `src/main` (and `androidMain` in KMP). It
 
 ## 5. Platform
 
-- [ ] **Exported components.** `android:exported="true"` on activities, services, receivers or providers without a permission, that act on the incoming `Intent` without validating it. Details in `mobile-security-audit`.
+- [ ] **Exported components.** `android:exported="true"` on activities, services, receivers or providers without a permission, that act on the incoming `Intent` without validating it. Details in `mobile-security`.
 - [ ] **Runtime permissions.** Features used without checking the permission, or denial ("don't ask again") not handled.
 - [ ] **Background work.** Long work started from an Activity or a plain `Service` that the system will stop; persistent or deferrable work belongs in `WorkManager`. Starting foreground services and exact alarms have restrictions that depend on `targetSdk`; check it before reviewing.
 - [ ] **`PendingIntent` mutability.** Flags must include `FLAG_IMMUTABLE` or `FLAG_MUTABLE` explicitly on apps targeting Android 12 or higher.

package/skills/{flutter-code-review/SKILL.md → mobile-code-review/references/flutter/pr-review.md}

@@ -1,11 +1,4 @@
----
-name: flutter-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
----
+> Adapted from the `code-review` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Code Review Skill
 

package/skills/{flutter-project-audit/SKILL.md → mobile-code-review/references/flutter/project-audit.md}

@@ -1,10 +1,3 @@
----
-name: flutter-project-audit
-description: Audits the health of a Flutter project as a whole — pubspec constraints and lock file, analysis_options and lints, SDK and platform configuration (minSdk, iOS deployment target), flavors and environments, generated code, folder structure and test setup. Use when reviewing or auditing a Flutter app or plugin, before a release, or when the user asks whether a Flutter project is well configured.
-intents: [review, architecture, dependency]
-stacks: [flutter]
----
-
 # Flutter Project Audit
 
 Project health checklist. Every item must be confirmed by reading the cited file; do not report what you could not verify.

package/skills/{flutter-dart-run-static-analysis/SKILL.md → mobile-code-review/references/flutter/static-analysis.md}

@@ -1,14 +1,5 @@
----
-name: flutter-dart-run-static-analysis
-description: Execute `dart analyze` to identify warnings and errors, and use `dart fix --apply` to automatically resolve mechanical lint issues. Use during development to ensure code quality and before committing changes.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Fri, 24 Apr 2026 15:09:34 GMT
-intents: [review]
-stacks: [flutter]
-source: https://github.com/dart-lang/skills
-license: BSD-3-Clause
----
+> Adapted from the `dart-run-static-analysis` skill in [dart-lang/skills](https://github.com/dart-lang/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Analyzing and Fixing Dart Code
 
 ## Contents

package/skills/{flutter-widget-review/SKILL.md → mobile-code-review/references/flutter/widget-review.md}

@@ -1,10 +1,3 @@
----
-name: flutter-widget-review
-description: Reviews Flutter widget code for lifecycle bugs, BuildContext misuse across async gaps, missing dispose, side effects in build, unnecessary rebuilds, list and image performance, layout overflow risks and accessibility. Use when reviewing Dart files under lib/ that contain widgets, screens or pages, or when the user asks to review Flutter UI code.
-intents: [review, performance]
-stacks: [flutter]
----
-
 # Flutter Widget Review
 
 Apply to Dart files with widgets (`StatelessWidget`, `StatefulWidget`, `ConsumerWidget`, `HookWidget`...). Items are ordered by impact: the first ones cause crashes or visible bugs.

package/skills/mobile-code-review/references/flutter.md

@@ -0,0 +1,18 @@
+# Reviewing Flutter and Dart code
+
+Apply the checklists in this order; stop early for a small diff that only touches widgets.
+
+| Step | Checklist | When |
+|---|---|---|
+| 1 | [flutter/static-analysis.md](flutter/static-analysis.md) — `dart analyze`, `dart fix` | Always, when the Dart SDK is available; report the analyzer output before manual findings |
+| 2 | [flutter/pr-review.md](flutter/pr-review.md) — pull request checklist: correctness, security, style, tests, docs | Reviewing a diff, branch or pull request |
+| 3 | [flutter/widget-review.md](flutter/widget-review.md) — lifecycle, `BuildContext` across async gaps, dispose, rebuilds, lists, layout, accessibility | Files with widgets, screens or pages; performance reviews |
+| 4 | [flutter/project-audit.md](flutter/project-audit.md) — `pubspec.yaml`, lints, native configuration, flavors, structure, CI | Auditing a whole project, or a diff that touches `pubspec.yaml`, `android/`, `ios/` or CI |
+
+## Flutter-specific notes
+
+- Dart style and idioms: the Effective Dart and Dart 3 guides in the `mobile-flutter` skill (`references/dart.md`).
+- Follow the project's state management (BLoC/Cubit, Riverpod, Provider) instead of suggesting another one.
+- Check the Flutter and Dart versions in `pubspec.lock` before recommending newer APIs (`MediaQuery.sizeOf`, Dart 3 patterns).
+- Generated files (`*.g.dart`, `*.freezed.dart`, `*.mocks.dart`) are reviewed through their source annotations, not line by line.
+- Native code under `android/` and `ios/` follows [android.md](android.md) and [ios.md](ios.md).