# Native iOS + Android (SwiftUI + Jetpack Compose, Shared Schema) — AI Agent Guidelines & Architecture Rules

> 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.
> Technologies: Swift, SwiftUI, Kotlin, Jetpack Compose

---

## AGENTS.md
```markdown
# 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.
```

---

## CLAUDE.md
```markdown
# CLAUDE.md — SwiftUI + Compose Commands & Conventions

> Claude Code also reads `AGENTS.md` when no `CLAUDE.md` is present — keep this file for Claude-specific directives.

## Common Commands
- `./schema/generate.sh` - Regenerate Swift and Kotlin models from the shared schema
- `xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 17'` - iOS tests
- `./gradlew :app:testDebugUnitTest :app:connectedDebugAndroidTest` - Android tests
- `swiftlint` / `./gradlew ktlintCheck` - Lint

## Code Style Guidelines
- Work in one platform at a time unless the change starts in `schema/`.
- Never edit files under `Generated/` or `generated/`.
- Match the platform's idiom; do not port patterns from the other platform.
```

---

## .cursor/rules/stack.mdc
```markdown
---
description: Native SwiftUI and Jetpack Compose apps with a shared schema
globs: ["ios/**/*.swift", "android/**/*.kt", "schema/**/*"]
alwaysApply: true
---

# SwiftUI + Jetpack Compose, Shared Schema

- iOS: Swift 6 strict concurrency, SwiftUI, Observation, SwiftData, Swift Testing.
- Android: Kotlin 2, Compose, ViewModel + StateFlow, Room, Hilt.
- Only the schema is shared; models and clients are generated for both platforms.
- On-device store is the source of truth; UI observes the store.
- Generated code is never hand-edited. Lint with zero warnings.
```

---

## Architecture Overview & Best Practices
## Architecture Overview

Guidelines for **native apps on both platforms**: **SwiftUI** and **SwiftData** on iOS, **Jetpack Compose** and **Room** on Android, and a single **shared schema** that generates the models and clients for both.

### Key Advantages

- **Each platform at its best**: platform idioms, platform tooling and platform extensions without a cross-platform layer in the way.
- **One contract**: a model change starts in the schema and becomes a compile error on both platforms, which is the feedback loop an agent needs.
- **Self-contained projects**: an agent can read and change one platform without loading the other.