---

name: building-flutter-apps description: Build production-ready Flutter apps for Android/iOS using feature-first architecture. Covers project setup, UI patterns, state management (Riverpod/BLoC), navigation (go_router), testing (TDD with mocktail), and deployment. Use when creating Flutter projects, implementing features, debugging Flutter issues, or making architectural decisions.

Building Flutter Apps

Quick Start

Copyflutter create --org com.yourcompany --project-name my_app ./my_app
cd my_app && flutter run

Skill Guides

Feature-First Project Structure

Copylib/
├── main.dart
├── app.dart                    # MaterialApp configuration
├── core/                       # Shared across all features
│   ├── providers/              # Core Riverpod providers
│   │   ├── api_client_provider.dart
│   │   └── shared_preferences_provider.dart
│   ├── network/api_client.dart
│   ├── error/failures.dart
│   ├── theme/app_theme.dart
│   └── widgets/                # Truly reusable widgets only
├── features/
│   ├── auth/
│   │   ├── data/
│   │   │   ├── datasources/
│   │   │   ├── models/
│   │   │   ├── repositories/auth_repository_impl.dart
│   │   │   └── providers/auth_repository_provider.dart
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   └── repositories/auth_repository.dart  # Interface
│   │   └── presentation/
│   │       ├── providers/auth_provider.dart
│   │       ├── screens/
│   │       └── widgets/
│   ├── home/
│   │   ├── data/
│   │   ├── domain/
│   │   └── presentation/
│   └── [other_features]/
└── config/
    ├── routes.dart
    └── environment.dart

Decision Guides

What to Build?

State Management Choice

Essential Commands

Copyflutter pub get                 # Install dependencies
flutter run                     # Debug mode
flutter test                    # Run tests
flutter build apk --release     # Android release
flutter build ipa --release     # iOS release
flutter clean && flutter pub get  # Reset project

# Riverpod code generation
dart run build_runner build --delete-conflicting-outputs
dart run build_runner watch --delete-conflicting-outputs

TDD Workflow (from AGENTS.md)

Copy1. Interface First   → Define contract in domain/repositories/
2. RED Phase         → Write failing test, implementation throws UnimplementedError
3. GREEN Phase       → Write minimum code to pass
4. REFACTOR          → Clean up, add edge cases