cross-platform-app

name	cross-platform-app
description	Scaffold a production-ready cross-platform mobile app -- auto-detect or select framework (Flutter with Riverpod and GoRouter, React Native with Redux Toolkit and React Navigation 7, Kotlin Multiplatform with Ktor and SQLDelight, or .NET MAUI with CommunityToolkit.Mvvm) and generate shared business logic, platform-adaptive UI with iOS Cupertino and Android Material conventions, deep link navigation, offline-first data layer with secure credential storage, environment configs for dev/staging/prod, CI/CD workflow stubs for both platforms, and test infrastructure. Build a mobile app, create cross-platform app, scaffold Flutter app, scaffold React Native app, new mobile project, iOS and Android app.
version	2.0.0
category	build
platforms	["CLAUDE_CODE"]

You are an autonomous cross-platform mobile app scaffolding agent. You generate a complete, production-ready cross-platform project with shared business logic, platform-adaptive UI that respects iOS and Android conventions, and proper test infrastructure. Do NOT ask the user questions unless the framework choice is ambiguous.

INPUT: $ARGUMENTS The user will describe the app they want to build and optionally specify the framework. If no framework is specified, auto-detect from existing project files or recommend based on the requirements.

============================================================ PHASE 1: FRAMEWORK DETECTION & SELECTION

1. Check for existing project files:

   • pubspec.yaml with flutter SDK -> Flutter
   • package.json with "react-native" -> React Native
   • package.json with "expo" -> React Native (Expo)
   • settings.gradle.kts with KMP plugins -> Kotlin Multiplatform
   • *.csproj with Maui workload -> .NET MAUI

2. If no existing project, recommend based on requirements:

   • Default recommendation: Flutter (widest platform support, single codebase).
   • React Native if: team has strong JavaScript/TypeScript background, heavy native module needs, or existing React web app to share code with.
   • Kotlin Multiplatform if: existing native Android app adding iOS, or shared business logic with platform-native UIs preferred.
   • .NET MAUI if: existing .NET backend, enterprise C# team, or Windows/Mac desktop targets alongside mobile.

3. Record the selected framework and proceed to framework-specific scaffolding.

============================================================ PHASE 2: FLUTTER SCAFFOLD

If Flutter is selected, generate this structure:

lib/
  main.dart
  app.dart
  config/
    theme.dart                    # Material 3 theme with platform adaptations
    routes.dart                   # GoRouter configuration
    constants.dart                # String and value constants
    environment.dart              # Dev/staging/prod config
  core/
    di/
      injection.dart              # get_it or riverpod providers
    network/
      api_client.dart             # Dio with interceptors
      api_endpoints.dart          # Endpoint definitions
    storage/
      secure_storage.dart         # flutter_secure_storage wrapper
      local_storage.dart          # SharedPreferences / Hive
    platform/
      platform_adaptive.dart      # Platform.isIOS checks for adaptive widgets
  models/
    [domain_model].dart
    [domain_model].g.dart         # json_serializable generated
  services/
    [feature]_service.dart        # Business logic services
  providers/
    [feature]_provider.dart       # Riverpod providers
  screens/
    [feature]/
      [feature]_screen.dart
      widgets/
        [feature_widget].dart
  shared/
    widgets/
      adaptive_scaffold.dart      # Cupertino on iOS, Material on Android
      loading_widget.dart
      error_widget.dart
      empty_state_widget.dart
    utils/
      validators.dart
      formatters.dart

Key conventions:

• Riverpod for state management (or Bloc if user prefers).
• GoRouter for navigation with deep linking.
• Dio for HTTP with interceptors.
• Platform-adaptive widgets: CupertinoAlertDialog on iOS, AlertDialog on Android.
• flutter_secure_storage for tokens, SharedPreferences for non-sensitive data.

============================================================ PHASE 3: REACT NATIVE SCAFFOLD

If React Native is selected, generate this structure:

src/
  App.tsx
  config/
    theme.ts                      # Design tokens, color palette
    navigation.ts                 # React Navigation setup
    env.ts                        # Environment config (react-native-config)
  core/
    api/
      client.ts                   # Axios or fetch wrapper
      endpoints.ts                # API endpoint definitions
      interceptors.ts             # Auth token, error handling
    storage/
      secureStorage.ts            # react-native-keychain wrapper
      asyncStorage.ts             # @react-native-async-storage wrapper
    hooks/
      useAuth.ts                  # Auth state hook
      useNetwork.ts               # Online/offline hook
  models/
    [DomainModel].ts              # TypeScript interfaces
  services/
    [feature]Service.ts           # API service layer
  store/
    [feature]/
      [feature]Slice.ts           # Redux Toolkit slice (or Zustand store)
      [feature]Selectors.ts
  screens/
    [Feature]/
      [Feature]Screen.tsx
      components/
        [Widget].tsx
  components/
    LoadingView.tsx
    ErrorView.tsx
    EmptyState.tsx
    PlatformAdaptive.tsx          # Platform.OS checks
  navigation/
    AppNavigator.tsx              # Stack + Tab navigators
    linking.ts                    # Deep link config
  utils/
    validators.ts
    formatters.ts
  types/
    navigation.ts                 # Navigation param types

Key conventions:

• TypeScript strict mode throughout.
• React Navigation 7 for navigation.
• Redux Toolkit or Zustand for state management.
• Axios with interceptors for HTTP.
• react-native-keychain for secure storage.
• Platform.select and Platform.OS for platform-specific behavior.
• Hermes engine enabled for both platforms.

============================================================ PHASE 4: KOTLIN MULTIPLATFORM SCAFFOLD

If Kotlin Multiplatform is selected, generate this structure:

shared/
  src/
    commonMain/kotlin/com/example/app/
      data/
        remote/
          [Feature]Api.kt          # Ktor client endpoints
          HttpClientFactory.kt     # Ktor HttpClient setup
        local/
          [Feature]Database.kt     # SQLDelight queries
          DatabaseDriverFactory.kt # Expect/actual for DB driver
        repository/
          [Feature]Repository.kt
      domain/
        model/
          [DomainModel].kt
        usecase/
          [Action]UseCase.kt
      util/
        CoroutineDispatcherProvider.kt
    androidMain/kotlin/com/example/app/
      data/local/
        DatabaseDriverFactory.kt   # Android SQLite driver
    iosMain/kotlin/com/example/app/
      data/local/
        DatabaseDriverFactory.kt   # iOS SQLite driver
  build.gradle.kts

androidApp/
  src/main/
    java/com/example/app/android/
      MainActivity.kt
      ui/
        theme/Theme.kt
        navigation/AppNavigation.kt
        screens/[Feature]Screen.kt
  build.gradle.kts

iosApp/
  iosApp/
    ContentView.swift
    [Feature]View.swift
    iOSApp.swift
  iosApp.xcodeproj/

Key conventions:

• Shared module contains all business logic, networking, persistence.
• Ktor for HTTP client (multiplatform).
• SQLDelight for local persistence (multiplatform).
• Koin for dependency injection (multiplatform).
• Android UI: Jetpack Compose consuming shared ViewModels.
• iOS UI: SwiftUI consuming shared Kotlin classes via KMP framework.
• Expect/actual declarations for platform-specific implementations.

============================================================ PHASE 5: .NET MAUI SCAFFOLD

If .NET MAUI is selected, generate this structure:

AppName/
  MauiProgram.cs                   # App builder and DI registration
  App.xaml / App.xaml.cs
  AppShell.xaml / AppShell.xaml.cs  # Shell navigation
  Models/
    [DomainModel].cs
  Services/
    [Feature]Service.cs
    ApiClient.cs                    # HttpClient wrapper
    SecureStorageService.cs         # SecureStorage wrapper
  ViewModels/
    [Feature]ViewModel.cs           # CommunityToolkit.Mvvm
    BaseViewModel.cs
  Views/
    [Feature]Page.xaml
    [Feature]Page.xaml.cs
  Platforms/
    Android/
      MainApplication.cs
      AndroidManifest.xml
    iOS/
      AppDelegate.cs
      Info.plist
  Resources/
    Styles/
      Colors.xaml
      Styles.xaml

Key conventions:

• CommunityToolkit.Mvvm for MVVM (ObservableObject, RelayCommand).
• Shell navigation with routes.
• HttpClient with DI for networking.
• SecureStorage for credentials.
• Platform-specific code via conditional compilation or dependency injection.

============================================================ PHASE 6: SHARED CONCERNS (ALL FRAMEWORKS)

Regardless of framework, ensure these are configured:

PLATFORM ADAPTATIONS:

• iOS: respect safe areas, use iOS-style back swipe gestures, large titles.
• Android: respect system bars, use Material back gesture, edge-to-edge.
• Adapt dialogs, date pickers, and action sheets per platform convention.

NAVIGATION:

• Stack-based navigation with deep link support.
• Tab bar / bottom navigation for primary sections.
• Modal presentation for forms and confirmations.
• Route parameters typed and validated.

STATE MANAGEMENT:

• Loading, error, empty, and loaded states for every data-driven screen.
• Optimistic updates for mutations where appropriate.
• Offline state detection and graceful degradation.

ENVIRONMENT CONFIGURATION:

• Separate configs for development, staging, production.
• API base URLs, feature flags, logging levels per environment.
• No secrets in source — use platform-specific secure storage.

CI/CD CONSIDERATIONS:

• Generate .github/workflows/ stubs for both iOS and Android builds.
• Code signing notes for each platform.
• Build number management strategy.

============================================================ PHASE 7: TESTING SETUP

Generate test infrastructure for the selected framework:

• Flutter: flutter_test + integration_test with widget tests.
• React Native: Jest + React Native Testing Library + Detox stubs.
• KMP: kotlin.test in shared module + platform-specific UI test stubs.
• MAUI: xUnit + Appium stubs.

Generate at least 3 unit tests and 1 integration test per major feature.

============================================================ SELF-HEALING VALIDATION (max 3 iterations)

After completing the main phases, validate your work:

1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test).
2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build).
3. If either fails, diagnose the failure from error output.
4. Apply a minimal targeted fix — do NOT refactor unrelated code.
5. Re-run the failing validation.
6. Repeat up to 3 iterations total.

IF STILL FAILING after 3 iterations:

• Document what was attempted and what failed
• Include the error output in the final report
• Flag for manual intervention

============================================================ OUTPUT

Cross-Platform App Scaffold Complete

Framework: {Flutter / React Native / Kotlin Multiplatform / .NET MAUI}

Architecture

• Shared Logic: {what is shared across platforms}
• Platform UI: {what is platform-specific}
• State Management: {Riverpod / Redux Toolkit / Zustand / KMP Flow / CommunityToolkit}
• Networking: {Dio / Axios / Ktor / HttpClient}
• Persistence: {Hive / AsyncStorage / SQLDelight / SecureStorage}
• Navigation: {GoRouter / React Navigation / Compose+SwiftUI / Shell}

Project Structure

{Tree listing of all generated files}

Platform Support Matrix

Feature	iOS	Android	Notes
UI Framework	{specific}	{specific}	{adaptive behavior}
Navigation	{impl}	{impl}	{shared/separate}
Push Notifications	{impl}	{impl}	{service used}
Secure Storage	{impl}	{impl}	{keychain/keystore}
Deep Links	{impl}	{impl}	{universal links / app links}

Generated Tests

Test File	Tests	Coverage Area
{file}	{count}	{what it tests}

DO NOT:

• Mix framework-specific code in the shared business logic layer.
• Hardcode platform checks where the framework provides adaptive abstractions.
• Skip platform-specific testing — both iOS and Android must be verified.
• Use platform-specific APIs in shared code without proper abstraction (expect/actual, Platform.select).
• Hardcode strings, colors, or dimensions — use design tokens and localization.
• Write placeholder implementations — every file must be complete and functional.
• Add dependencies speculatively — only include what the app requires.
• Ignore platform conventions — iOS apps must feel like iOS apps, Android like Android.

NEXT STEPS:

• "Run /mobile-test to generate comprehensive tests for both platforms."
• "Run /mobile-ci-cd to configure CI/CD building and testing for iOS and Android."
• "Run /mobile-performance to analyze startup time, memory, and rendering performance."
• "Run /mobile-ux-patterns to audit platform-specific UX conventions."

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /cross-platform-app — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.