flutter-dev-protocol

name	flutter-dev-protocol
description	Development protocol for mobile-dev agent working with Flutter (primary) and React Native (secondary). Covers project detection, architecture patterns, state management conventions, testing, and platform-specific guidelines. Automatically loaded by the mobile-dev agent.
user-invokable	false

Flutter Development Protocol

Project Detection

On task start, auto-detect the project type:

1. Check for pubspec.yaml → Flutter project
2. Check for package.json with react-native dependency → React Native project
3. If neither found → report to team-lead, this may be a new project setup

Flutter Mode (Primary)

Project Setup Checklist

Before starting work on a new Flutter project:

1. Verify pubspec.yaml dependencies:
   • flutter_riverpod or riverpod for state management
   • go_router for routing
   • flutter_test in dev_dependencies
   • integration_test in dev_dependencies
2. Check analysis_options.yaml for strict linting rules
3. Scan lib/ for existing architecture patterns (feature-first, layer-first)
4. Read existing screens and widgets to understand naming conventions

State Management: Riverpod

Use Riverpod as the default state management solution:

// lib/features/products/presentation/providers/product_provider.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';

final productListProvider = FutureProvider.autoDispose<List<Product>>((ref) async {
  final repository = ref.read(productRepositoryProvider);
  return repository.getProducts();
});

Rules:

• Use ConsumerWidget or ConsumerStatefulWidget (not StatelessWidget + Consumer)
• Use autoDispose for providers that should clean up when no longer listened to
• Keep providers focused — one concern per provider
• Use ref.watch in build methods, ref.read in callbacks

Routing: GoRouter

// lib/core/router/app_router.dart
final routerProvider = Provider<GoRouter>((ref) {
  return GoRouter(
    routes: [
      GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
      GoRoute(path: '/products/:id', builder: (_, state) =>
        ProductDetailScreen(id: state.pathParameters['id']!)),
    ],
  );
});

Widget Conventions

1. Always use const constructors when possible
2. Extract widgets — if a build method exceeds ~50 lines, extract sub-widgets
3. Use Key for list items — ValueKey(item.id) for lists
4. Platform-aware — use Platform.isIOS / Platform.isAndroid for platform-specific behavior
5. Responsive — use LayoutBuilder or MediaQuery for adaptive layouts

Testing Protocol

# Unit tests
flutter test test/unit/ --reporter=expanded

# Widget tests
flutter test test/widget/ --reporter=expanded

# Integration tests (requires device/emulator)
flutter test integration_test/ --reporter=expanded

# All tests
flutter test --reporter=expanded

Test structure:

test/
├── unit/
│   └── features/
│       └── products/
│           └── product_repository_test.dart
├── widget/
│   └── features/
│       └── products/
│           └── product_card_test.dart
└── helpers/
    ├── test_helper.dart
    └── mocks.dart

Build & Verify

# Quick analysis
dart analyze

# Format check
dart format --set-exit-if-changed lib/ test/

# Build Android (debug, fast)
flutter build apk --debug

# Build iOS (debug, fast — macOS only)
flutter build ios --debug --no-codesign

React Native Mode (Secondary)

When working on a React Native project, adapt these patterns:

State Management

• Zustand (simple) or Redux Toolkit (complex)
• React Query for server state

Testing

npx jest --passWithNoTests

Build

npx react-native run-android
npx react-native run-ios

Branch Naming for Mobile

mobile/<task-id>-<short-description>

Examples:

• mobile/task-010-product-listing-screen
• mobile/task-011-cart-provider
• mobile/task-012-checkout-flow

Domain Boundary Reminder

You may ONLY modify:

• Flutter: lib/, android/, ios/, test/, integration_test/, pubspec.yaml, analysis_options.yaml
• React Native: src/, android/, ios/, __tests__/, package.json (dependencies only, with team-lead approval)

NEVER modify shared types, backend code, or web frontend code.