---
name: swiftui-compose-native
description: "Use when building, refactoring, or reviewing a Native iOS + Android (SwiftUI + Jetpack Compose, Shared Schema) project (Swift, SwiftUI, Kotlin, Jetpack Compose). Rules for native apps per platform: SwiftUI with SwiftData on iOS, Jetpack Compose with Room on Android, one shared OpenAPI or protobuf schema with codegen, and real-device CI per platform."
license: MIT
metadata:
  source: https://stackitfast.com/rules/swiftui-compose-native
  version: "2026-10-04"
---

# Native iOS + Android (SwiftUI + Jetpack Compose, Shared Schema) — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Native iOS + Android (SwiftUI + Jetpack Compose, Shared Schema) codebase.
- Whenever the project depends on Swift, SwiftUI, Kotlin, Jetpack Compose.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (SwiftUI + Jetpack Compose, Shared Schema)

## 1. System Architecture
- **iOS**: Swift 6 language mode with strict concurrency, SwiftUI for UI, SwiftData (or Core Data for existing stores) on device, Swift Testing for tests.
- **Android**: Kotlin 2 with the K2 compiler, Jetpack Compose for UI, Room on device, Hilt for dependency injection, coroutines and Flow for async.
- **Shared contract**: One OpenAPI or `.proto` schema in `schema/`; Swift and Kotlin models and clients are generated from it on every build. Nothing else is shared between platforms.
- **Auth**: Sign in with Apple and Android Credential Manager (passkeys first), only where accounts exist.
- **Releases**: Each platform has its own CI, signing and staged rollout.

## 2. File Layout
- `ios/`: Xcode project; `Features/<workflow>/` (views, view models, tests), `Persistence/`, `Generated/` (do not edit).
- `android/`: Gradle project with version catalogs; `feature/<workflow>/`, `data/`, `generated/` (do not edit).
- `schema/`: The contract plus the codegen scripts both platforms call.
- Platform extensions (widgets, watch apps, Wear OS tiles) live beside the app in each platform project.

## 3. Platform Rules
- Follow each platform's conventions instead of a shared abstraction: Observation (`@Observable`) on iOS, `ViewModel` + `StateFlow` on Android.
- Views are functions of state. Side effects live in view models or repositories, never in view bodies or composables.
- On-device stores are the source of truth for offline features; network results are written to the store and the UI observes the store.
- A model change starts in `schema/`. Regenerate, then fix the compile errors on both platforms in the same PR.

## 4. Concurrency & Performance
- iOS: no `@unchecked Sendable` or `nonisolated(unsafe)` without a comment explaining why; UI state is `@MainActor`.
- Android: never block the main thread; database and network calls run on `Dispatchers.IO` through repositories.
- Profile with Instruments and the Android Studio profiler before optimising; record the numbers in the PR.

## 5. Coding Standards
- SwiftLint and ktlint (or detekt) run in CI with zero warnings.
- Generated code is never hand-edited; change the schema or the generator.
- No cross-platform UI layer on top of native code; you chose native for the platform.

## 6. Testing Conventions
- iOS: Swift Testing for logic, `#Preview` for every screen state, XCUITest on core flows.
- Android: JUnit and Turbine for view models and flows, Compose UI tests on core flows, Roborazzi or Paparazzi for screenshots.
- Real-device runs per release (a device farm or physical devices) for flows that touch sensors, background work or extensions.

## 7. Git Workflow & PR Conventions
- Conventional Commits with the platform in scope: `feat(ios): home screen widget`, `fix(android): sync retry backoff`.
- Schema changes touch both platforms in one PR; platform owners review their side.
- Release branches per platform; staged rollouts with a halt threshold on crash rate.

## Source
Maintained at https://stackitfast.com/rules/swiftui-compose-native — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.