software-mobile

Mobile Development

Use this skill for platform choice, cross-platform tradeoffs, Android implementation guidance, and shared mobile concerns such as authentication, notifications, deep linking, release readiness, and policy checks. For deep native iOS implementation or rewrite work, route to software-ios-native. For native iOS build, install, packaging, or stale-app debugging, route to software-ios-runtime-debugging.

Quick Reference

When to Use This Skill

Use this skill when you need:

• Platform selection between native iOS, native Android, React Native, Flutter, Kotlin Multiplatform, and wrapper shells
• Android app development with Kotlin, Jetpack Compose, ViewModel, StateFlow, and WorkManager
• Cross-platform decisions across React Native, Expo, Flutter, Kotlin Multiplatform, and WebView shells
• Mobile auth, passkeys, push notifications, offline-first sync, deep links, and app-store release preparation
• Backend translation pipeline design for localized prose delivery to mobile clients

When NOT to Use This Skill

Platform Selection

Need to ship mobile product?
    │
    ├─ Single platform only?
    │   ├─ iOS → SwiftUI for new code, UIKit interop where needed
    │   └─ Android → Jetpack Compose for new code, Views interop where needed
    │
    ├─ Both iOS and Android?
    │   ├─ Native integrations / performance / platform fidelity dominate? → Separate native apps
    │   ├─ JS/TS team and fastest shared delivery? → React Native + Expo-managed for greenfield
    │   ├─ Fully shared rendering and custom UI control? → Flutter
    │   └─ Kotlin team, shared logic, native UI? → Kotlin Multiplatform
    │
    └─ Existing web app wrapper?
        ├─ Low-complexity shell → WebView / Capacitor
        └─ Meaningful native features → React Native or native modules

Cross-Platform Defaults (July 2026)

Workflow

1. Confirm product scope, platform targets, native requirements, and release constraints.
2. Route web-only, backend, or iOS-native deep dives to adjacent skills.
3. Choose the stack from the selection guidance above.
4. Apply guidance for auth, push, offline behavior, release gates, and testing.
   • For iOS push: prove the local sandbox path and the production path separately.
   • Treat push signoff as two gates: transport proof (notification accepted and shown) and open-path proof (tapping from cold start and warm start does not freeze or crash).
5. Re-check current platform-policy and framework facts before final recommendations.

Mobile task
  -> Identify platform mix, app type, and user-facing surface
  -> Route deep native work to iOS or Android specialist skills
  -> Define architecture, state, navigation, storage, and release gates
  -> Implement bounded slice with accessibility and localization checks
  -> Build, install, launch, test, and capture proof
  -> Report platform-specific blockers and handoffs

Platform Defaults

iOS

• SwiftUI for new screens; UIKit interop for mature or heavily customized flows.
• @Observable on iOS 17+; keep ObservableObject only when supporting older baselines.
• Swift Concurrency throughout; keep UI-facing state on @MainActor.
• Swift Testing for unit tests; XCTest for UI/legacy coverage.
• Privacy manifests, required-reason APIs, and App Review requirements are hard release gates.
• Backend routing authoritative per device row (push_environment); verify the newest row after every install type change.
• iOS push QA: validate the notification-open path explicitly after transport succeeds — tap from cold start, tap from warm resume, force-close and relaunch normally.
• Before TestFlight upload, inspect archived app entitlements: confirm aps-environment = production.

iOS Release Operations

Android

• Jetpack Compose for new UI; Views only for interop or legacy.
• ViewModel + StateFlow; LiveData is maintenance-mode for older View-based code only.
• WorkManager for guaranteed background work; Credential Manager for passkeys/password/federated sign-in.
• Baseline Profiles and Macrobenchmark for startup and scroll performance.
• Play target SDK policy, Data safety, and Play Integrity are hard release gates.
• New apps and updates must target API 36 / Android 16 by August 31, 2026 (extension requests can push individual apps to November 1, 2026); existing published apps must target at least API 35 / Android 15 to remain visible on Android 16+/17 devices. This deadline moves every year — re-check developer.android.com/google/play/requirements/target-sdk before every release, don't reuse a cached deadline.

Known Platform Traps

iOS

• _performBlockAfterCATransactionCommitSynchronizes: / "Call must be made on main thread" is a private SwiftUI symbol, not user-code. Web-search the signature before any code review.
• Once APNs accepts a push payload and the banner appears, any freeze or crash after tapping belongs to the app-side open path (delegate isolation, pending-route races, off-main UI mutations) — not to transport.
• dataCorrupted + <!DOCTYPE html> is an API routing / auth bug, not a concurrency bug.
• Xcode 26 default TLS Client Hello changed: apps talking to servers with strict TLS-fingerprint allowlists may see login or API failures on fresh builds — verify against staging.

Android / Kotlin

• android.view.ViewRootImpl$CalledFromWrongThreadException and ConcurrentModificationException inside SnapshotStateObserver are the Android parallels to iOS main-thread crashes. They surface when a MutableStateFlow backing UI state is mutated from Dispatchers.IO while Compose is reading it on the main thread.
• Safe pattern: do blocking work inside withContext(Dispatchers.IO) { ... }, return a plain value, then assign to _uiState.value on the main thread. Collect in composables via collectAsStateWithLifecycle().
• Kotlin 2.x + Strong Skipping Mode: emitting a fresh data class instance per field on every ViewModel event defeats Compose's identity-based skip check. Split UI state into @Immutable sub-objects; hoist derived lists with stateIn; wrap per-row callbacks in remember(id) { { ... } }.
• When adb logcat shows the crash includes SnapshotStateObserver, MonotonicFrameClock, or Recomposer, route to software-android-native and software-android-runtime-debugging.

Expert Judgment Calls

Non-experts see a working build and call it done. An expert checks the cases where "it built and ran once" is not the same as "it will pass review, survive an audit, or work for the next user."

• Cross-platform regret is asymmetric. Moving from native to shared code is a full rewrite; moving from shared code to native is usually a partial, surgical one (pull out the hot path, keep the rest). When timeline pressure forces a shared-framework choice, explicitly list which native integrations (camera pipelines, ARKit/ARCore, background audio, CarPlay/Android Auto, widgets, App Intents/App Actions) are foreseeable within 12 months — those are the ones that force a native escape hatch later, and the earlier you know, the cheaper the hedge (e.g., isolate the module behind a platform-abstraction boundary from day one).
• One native escape hatch usually means you need native hiring anyway. Teams under-price this: a single deep native module (e.g., a custom camera pipeline or a hardware SDK) requires the same iOS/Android specialist skill as a fully native app, just applied to a smaller surface. Budget the hire, not just the sprint.
• App Review rejection risk hides in account and auth flows, not UI polish. The most common late-stage iOS rejections a non-expert misses: (1) Guideline 5.1.1(v) — in-app account deletion that actually deletes the record and revokes tokens, not just deactivates; (2) Sign in with Apple parity — if the app offers any third-party or social login, Sign in with Apple must be offered too, at equal prominence; (3) subscription flows that don't expose "Cancel Subscription" reachably inside the app or account settings. Verify all three before submission, every release — Apple periodically increases enforcement on these without a version bump to announce it.
• Push permission priming is a judgment call, not a technical one. Requesting notification permission on first launch reliably produces "Don't Allow" from most users, who then never see the system prompt again. An expert defers the OS prompt until the user has taken an action that makes the value of push obvious (e.g., after placing an order), and separately audits whether the soft-ask copy itself needs its own re-prompt path if declined.
• Offline-first correctness is a conflict-resolution decision, not a caching decision. Before implementing local-first storage, force an explicit answer to "what happens when two devices edit the same record while offline" — last-write-wins, field-level merge, or user-facing conflict UI. Silence on this question means the team will discover the answer in production, from a support ticket.
• A shared entitlement registry is cheaper before launch than after. Apps that sell both in-store (StoreKit/Play Billing) and web/Stripe entitlements without one canonical source of truth accumulate silent state drift (a user paid on web, app still shows locked) that is expensive to retrofit once both paths have real users.
• Framework benchmark claims decay faster than they're written. A blog post claiming "Flutter is now as fast as native" or "RN startup time improved 40%" is a snapshot of one app, one release, one device. Treat every unsourced performance claim as a hypothesis to verify with Instruments/Macrobenchmark on the actual product, not a fact to design around.

Release Readiness Checklist

iOS App Store

• Icons, launch assets, and permission copy are complete
• Privacy manifest and required-reason APIs are correct for app targets and listed SDKs
• Third-party SDK compliance matches Apple's current requirements
• Accessibility, deep links, and push flows tested on current devices
• App Store metadata, privacy policy, and TestFlight coverage ready
• Full App Store Connect preparation — see references/app-store-connect-checklist.md

Google Play

• Target SDK matches the latest Play policy (API 36 / Android 16 required for new apps and updates by August 31, 2026 — re-verify the current deadline, it moves annually)
• Privacy policy, content rating, and Data safety complete
• Integrity, auth, and background behavior tested under modern Android constraints
• Internal/closed/open tracks configured appropriately

Common Anti-Patterns

Known Traps

• Assuming one mobile framework decision solves release, entitlement, deep-link, and push behavior without platform-specific proof
• Validating auth, push, or deep links only in local debug builds and treating that as production readiness
• Mixing sandbox, staging, and production mobile backends until install-specific behavior becomes impossible to reproduce
• Using emulator or simulator success as proof for background execution, notification delivery, or device-specific lifecycle
• Choosing a cross-platform stack before listing native integrations, extension points, and store-policy constraints that can force native escape hatches

Navigation

References

• references/ios-best-practices.md — iOS architecture, concurrency, testing, accessibility, release
• references/android-best-practices.md — Android architecture, Compose, coroutines, testing, performance
• references/cross-platform-comparison.md — React Native / Flutter / KMP / native tradeoffs
• references/deep-linking-guide.md — Universal Links, App Links, Expo Router, post-Dynamic-Links
• references/mobile-testing-patterns.md — test pyramid, device strategy, snapshot/UI/E2E
• references/offline-first-architecture.md — local-first storage, sync, conflict resolution
• references/push-notifications-guide.md — APNs, FCM, permissions, channels, analytics
• references/operational-playbook.md — release operations, decision tables, centralized patterns
• references/app-store-connect-checklist.md — App Store Connect field-by-field checklist
• references/backend-translation-pipeline.md — i18n patterns for backend-generated prose delivered to mobile clients
• data/sources.json — current official and curated external sources

Shared Checklists And Utilities

• ../software-clean-code-standard/assets/checklists/mobile-release-checklist.md
• ../software-clean-code-standard/references/auth-utilities.md
• ../software-clean-code-standard/references/error-handling.md
• ../software-clean-code-standard/references/resilience-utilities.md
• ../software-clean-code-standard/references/testing-utilities.md
• ../software-clean-code-standard/references/clean-code-standard.md

Templates

• Swift: assets/swift/template-swift.md, assets/swift/template-swift-concurrency.md, assets/swift/template-swift-combine.md, assets/swift/template-swift-performance.md, assets/swift/template-swift-testing.md
• SwiftUI: assets/swiftui/template-swiftui-advanced.md
• Kotlin / Android: assets/kotlin/template-kotlin.md, assets/kotlin/template-kotlin-coroutines.md, assets/kotlin/template-kotlin-compose-advanced.md, assets/kotlin/template-kotlin-testing.md
• Cross-platform: assets/cross-platform/template-platform-patterns.md, assets/cross-platform/template-webview.md

Related Skills

• software-ios-native — Native iOS 17+ implementation, rewrites, and agent workflows
• software-ios-ai-engine — Apple Foundation Models, local AI engines, on-device retrieval
• software-ios-runtime-debugging — Build/install/launch proof, simulator drift, packaging triage
• software-ios-design — Native iOS visual hierarchy, HIG, screenshot review
• software-android-native — Native Android, Kotlin, Jetpack Compose, agent workflows
• software-android-design — Material Design 3, screenshot review
• software-android-runtime-debugging — Android build/install/launch proof, emulator drift
• software-frontend — Web UI and shared product surfaces
• software-backend — API design, auth, backend contracts
• software-baas-platforms — Supabase, Firebase, Appwrite, PocketBase
• qa-testing-strategy — CI gates, reliability, release confidence
• qa-resilience — Network resilience and failure-mode design
• qa-testing-ios — iOS-specific testing
• software-ui-ux-design — Mobile UX and accessibility

Fact-Checking

Store policy deadlines, minimum SDK/Xcode requirements, and framework architecture defaults (React Native, Expo, Kotlin/Compose Multiplatform) change on their own release cadence and are wrong within months if hardcoded. Before quoting any date, version, or percentage in this skill or its references, verify it against a current primary source — Apple Developer News/Release Notes, Google Play Console Help, the framework's official changelog — rather than this file's memory of it. If a source can't be reached and the fact is load-bearing (a submission gate, a deadline, a required minimum version), say so explicitly and flag the guidance as unverified rather than stating it as current fact.

Always re-verify before release or final recommendation:

• Apple release notes, minimum Xcode/SDK version for App Store Connect uploads, third-party SDK requirements, App Review Guidelines
• Google Play target API policy and deadline, Android release behavior, Credential Manager, Play Integrity
• React Native and Expo changelogs (architecture status, routing, OTA)
• Kotlin Multiplatform and Compose Multiplatform release notes

Freshness Protocol

When users ask recommendation or "what's current" questions, use web search first. If unavailable, answer from data/sources.json and mark guidance as potentially stale.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.