Flutter

--- name: flutter description: Build production Flutter apps with Clean Architecture, Riverpod (preferred over Bloc/Provider), GoRouter navigation, Impeller rendering engine, Dart 3.7+ patterns, platform channels via Pigeon, and App Store/Play Store deployment. triggers: ["create a Flutter app", "set up state management", "design widgets", "implement navigation", "deploy to stores", "flutter clean architecture", "riverpod", "go_router", "build flutter", "mobile app flutter", "pubspec.yaml", "flutter test", "flutter build", "platform channel", "pigeon", "impeller"] negatives: ["React Native", "web-only React", "general mobile design", "SwiftUI", "Jetpack Compose", "Xamarin", "Ionic", "Cordova"] license: MIT compatibility: opencode metadata: workflow: mobile audience: developers version: "4.0.0" author: shokunin

Flutter Architect

Widgets are functions of state. Keep them pure. Compose, don't inherit.

Production Flutter apps with Clean Architecture, Riverpod, GoRouter, Impeller, and platform channels. Based on Flutter docs, Riverpod patterns, and production experience.

Decision Framework

Before writing Flutter code, answer:

• Is native performance critical? (animations, camera, maps) → Flutter is a strong fit
• Is the team already experienced with Dart? → Proceed. If React/TypeScript, consider react-native skill
• Is the app content-heavy with standard platform UI? → Consider native or react-native
• Does the app need platform-specific features not available in packages? → Verify pub.dev coverage first

Workflow

1. Scaffold: dart run flutter_skeleton or create lib/core, lib/features/*/domain|data|presentation by hand. Add Riverpod + GoRouter + Freezed deps in pubspec.yaml.
2. Domain first: Define entities, repository contracts, and use cases. Zero Flutter imports. Pure Dart with freezed for sealed unions.
3. Data layer: Implement repositories with Dio/retrofit, DTOs with json_serializable, and data sources. Wire up in Riverpod with Provider<AuthRepository>.
4. Presentation: Build screens and widgets with ConsumerWidget/ConsumerStatefulWidget. Wire NotifierProvider for each feature. Keep ref.watch at leaf level.
5. Routing: Configure GoRouter with auth redirect (redirect guard), nested routes per feature, and deep link patterns.
6. Ship: Run tests → flutter build appbundle / flutter build ipa → deploy via Codemagic or GitHub Actions. Enable Impeller on Android in build.gradle.

Sub-Commands

Architecture

lib/
├ core/
│   ├ theme/      # Material 3 theming
│   ├ constants/  # App-wide constants
│   └ network/    # Dio + interceptors
├ features/
│  ├ auth/
│  │   ├ domain/        # Pure Dart — entities, use cases, contracts
│  │   ├ data/          # Repo impl, API, DTOs, data sources
│  │   └ presentation/  # Riverpod providers + screens + widgets
│  ├ home/
│  └ profile/
└ main.dart

Domain Layer (zero Flutter imports)

class User {
  final String id;
  final String email;
  const User({required this.id, required this.email});
}

abstract class AuthRepository {
  Future<User> login(String email, String password);
  Stream<User?> authStateChanges();
}

class Login {
  final AuthRepository repository;
  const Login(this.repository);
  Future<User> call(String email, String password) => repository.login(email, password);
}

Riverpod State Management

final authStateProvider = StreamProvider<User?>((ref) {
  return ref.watch(authRepositoryProvider).authStateChanges();
});

final loginProvider = NotifierProvider<LoginNotifier, AsyncValue<void>>((ref) {
  return LoginNotifier(ref.watch(loginUseCaseProvider));
});

class LoginScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final status = ref.watch(loginProvider);
    return status.when(
      loading: () => const CircularProgressIndicator(),
      error: (e, _) => ErrorWidget(message: e.toString()),
      data: (_) => const LoginForm(),
    );
  }
}

GoRouter with Auth Guard

final router = GoRouter(
  redirect: (context, state) {
    final isAuth = ref.read(authStateProvider).value != null;
    final isLogin = state.matchedLocation.startsWith('/login');
    if (!isAuth && !isLogin) return '/login';
    if (isAuth && isLogin) return '/';
    return null;
  },
  routes: [
    GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
    GoRoute(path: '/login', builder: (_, __) => const LoginScreen()),
  ],
);

Impeller

Since Flutter 3.24+, Impeller is default on iOS. On Android, opt in:

// android/app/build.gradle
renderingEngine = "impeller"

Eliminates first-frame jank. Faster frame rendering. Better memory on low-end devices.

Platform Channels via Pigeon

// battery.dart (Pigeon input)
@HostApi()
abstract class BatteryApi {
  int getBatteryLevel();
}

Run: dart run pigeon --input battery.dart --dart_out lib/battery.dart

Performance Rules

• const constructors everywhere
• Consumer at leaf level (not entire screen)
• ListView.builder / GridView.builder (lazy)
• cached_network_image
• Profile: flutter run --profile, DevTools
• Avoid RepaintBoundary overuse

Perceived Performance

Flutter renders at 60fps on most devices and 120fps on ProMotion displays. Performance perception differs:

Error Handling

Production Checklist

• Riverpod providers: domain → data → presentation layers
• Domain layer: zero Flutter imports
• GoRouter: auth redirect + deep linking
• Impeller enabled on Android
• const constructors everywhere
• Platform channels via Pigeon (not manual MethodChannel)
• Unit tests for domain layer
• Widget tests for critical screens
• CI/CD: Codemagic / GitHub Actions
• ErrorWidget.builder + PlatformDispatcher.onError
• Retry logic on network failures
• Freezed / sealed classes for state unions

Anti-Patterns

Review Format (Required)

When reviewing Flutter code, use Before | After | Why format:

Perceived Performance (Extended)

Flutter renders at 60fps on most devices, 120fps on ProMotion displays.

Rule: The user feels the slowest frame. Optimize for worst case, not average.

Sources

• Flutter Documentation (flutter.dev)
• Dart 3.7 Language Tour (dart.dev)
• Riverpod Documentation (riverpod.dev)
• GoRouter Documentation
• Impeller Rendering Engine
• Pigeon Plugin

Pre-Flight Checklist

Before submitting Flutter code:

• All widgets use const constructors where possible (check with dart analyze)
• Long lists use ListView.builder or SliverList.builder, never ListView(children: [...])
• ref.watch only in build methods; ref.read only in callbacks
• Routes use GoRouter typed parameters, not manual string parsing
• AsyncValue has .when(data:, loading:, error:) — all three branches covered
• Platform channels use Pigeon-generated code, never manual MethodChannel
• android/app/build.gradle has renderingEngine = "impeller" (Android 14+)
• No console.log or print() statements in production code
• flutter analyze passes with zero errors or warnings
• Tested on real Android device (not just iOS simulator or vice versa)
• App works correctly when process is killed and restarted (state restoration)
• Safe areas respected: MediaQuery.of(context).padding or SafeArea widget

Checklist

• Skill loads without errors in the AI agent
• YAML frontmatter is valid (description, compatibility, audience)
• Workflow section provides clear step-by-step instructions
• Error handling section covers common failure modes
• All referenced files (references/, scripts/, assets/) exist
• Skill triggers correctly for intended use cases
• No broken links or missing resources