cross-platform-app— agent skill

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

1. 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.

1. 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

Generated 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.