skills/magnus919_agent-skills
1
0
Fork 0
mirror of https://github.com/magnus919/agent-skills.git synced 2026-09-11 19:47:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

feat(skill): add mobile development skill (iOS / Android / Flutter / React Native) (#248) (#268)

Browse Source 
ONE family skill covering iOS, Android, Flutter, and React Native with
per-framework references (ios.md, android.md, flutter.md, react-native.md),
shared scaffold/build/sign/test/ship workflow, mobile lifecycle, offline and
sync guidance, and mobile-specific testing. Ships a 5-heading human README and
a schema-v1 eval manifest with 6 cases covering build/sign, testing, and
store-readiness. Adds the README index entry and regenerates catalogs.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
2026-08-03 19:48:20 -04:00
committed by GitHub
co-authored by factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
parent 6181f1746d
commit f68721873e
11 changed files with 1074 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/marketplace.json
+9
View File
@@ -581,6 +581,15 @@
"strict": false,
"description": "Plan and execute production ML engineering work — model training and fine-tuning (LoRA/QLoRA), evaluation and eval-set design, quantization decisions, inference deployment, and regression triage, grounded in practical engineering patterns for production ML systems. Do not use for statistical modeling and experimental design (that's the data scientist) or for operating a specific inference engine (that's a tool skill such as llama-cpp or vllm)."
},
{
"name": "mobile-development",
"source": "./",
"skills": [
"./mobile-development"
],
"strict": false,
"description": "Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope."
},
{
"name": "neckbeard",
"source": "./",
.codex-plugin/plugin.json
+1
View File
@@ -88,6 +88,7 @@
"./meshcore-packet-capture",
"./migration-engineering",
"./ml-engineering",
"./mobile-development",
"./nous-branding",
"./open-knowledge-format",
"./openlibrary-cli",
README.md
+4
View File
@@ -266,6 +266,10 @@ Plan and execute safe cross-system migrations — schema, data, API, infrastruct
Machine learning engineering methodology — model training, fine-tuning (LoRA/QLoRA), evaluation, quantization, deployment, and MLOps pipeline design. Grounded in practical engineering patterns for production ML systems.
### [mobile-development](mobile-development/SKILL.md)
Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native as ONE family skill with per-framework references: project scaffolding, builds and code signing, device and emulator testing, store submission (App Store/TestFlight and Google Play), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Ships 4 framework references (ios, android, flutter, react-native) and 6 evals. Routes web UI work to frontend-engineering and server-side work to backend-engineering.
### [neckbeard](bundles/neckbeard/SKILL.md)
Evidence-driven software delivery operating model — routes a change through framing, discovery, design, implementation, review, verification, delivery, and learning, choosing the smallest *safe* intervention and proving it at the real delivery boundary. Every non-trivial run leaves an inspectable evidence ledger. Composes the specialist catalog rather than replacing it. Ships a versioned evaluation harness that measures SDLC outcomes, never LOC. Not a "10x developer" persona.
llms.txt
+1
View File
@@ -66,6 +66,7 @@
- [meshcore-packet-capture](meshcore-packet-capture/SKILL.md): Capture MeshCore Companion packets via BLE, serial, or TCP.
- [migration-engineering](migration-engineering/SKILL.md): Plan and execute safe cross-system migrations — schema, data, API, infrastructure, and service — with compatibility windows, dual-running, backfills, reconciliation, cutover, deprecation, and cleanup. Covers expand/contract, reversible and irreversible recovery paths, migration observability, correctness evidence, ownership, and customer impact. Do not use for single-technology quick fixes, tool-specific how-to guides, or migrations whose scope does not cross a system boundary; do not prescribe one migration technology or claim rollback is always possible.
- [ml-engineering](ml-engineering/SKILL.md): Plan and execute production ML engineering work — model training and fine-tuning (LoRA/QLoRA), evaluation and eval-set design, quantization decisions, inference deployment, and regression triage, grounded in practical engineering patterns for production ML systems. Do not use for statistical modeling and experimental design (that's the data scientist) or for operating a specific inference engine (that's a tool skill such as llama-cpp or vllm).
- [mobile-development](mobile-development/SKILL.md): Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope.
- [neckbeard](bundles/neckbeard/SKILL.md): Use when asked to fix, build, refactor, review, verify, or release software and the work is non-trivial — including delivering a change request (issue, ticket, or request) from intake through planning, gates, implementation, review, verified PR, and authorized post-merge release. neckbeard routes the change through framing, discovery, design, implementation, review, verification, delivery, and learning — choosing the smallest *safe* intervention, proving it at the real delivery boundary, and leaving an inspectable evidence ledger. For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates, delivery packet, and lifecycle integration. Composes specialist catalog skills rather than replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory.
- [nous-branding](nous-branding/SKILL.md): Generate images and content consistent with the Nous Research brand identity. Use when creating visuals in the Nous / Theia / Hermes ecosystem: a "cyber-classical" style blending neo-classical statuary, cyberpunk/industrial grunge, and retro anime illustration. Covers official brand color palette, typography (Inter/IBM Plex Sans, JetBrains Mono, heavy distressed display faces), the Nous Girl mascot, texture system, and image prompt construction. Ships reference images for palette, mascot, and brand collage that can be used as img2img inputs.
- [open-knowledge-format](open-knowledge-format/SKILL.md): Google's Open Knowledge Format (OKF) v0.1 — an open, vendor-neutral spec for representing knowledge as markdown files with YAML frontmatter, designed for AI agent consumption. Use when the user mentions OKF, Open Knowledge Format, Google's knowledge format, LLM wiki bundles, agent knowledge packs, creating OKF bundles, validating OKF documents, or converting knowledge into the OKF standard.
mobile-development/README.md
+57
View File
@@ -0,0 +1,57 @@
# Mobile Development
Mobile development methodology for iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission, app lifecycle and backgrounding, offline and sync, and mobile-specific testing. One skill for all four frameworks, with per-framework depth in references.
## Why Install This Skill
Your agent stops treating mobile apps as "a website that runs on a phone" and starts applying the actual discipline of mobile engineering: reproducible builds, correct signing, lifecycle-aware state handling, offline-first storage, and store submission that does not bounce in review. The catalog previously had zero mobile coverage; this skill closes that gap with one family skill that follows the same pattern as `frontend-engineering`.
After installing, your agent can scaffold a new app in any of the four stacks, set up and audit builds and code signing for iOS and Android, plan device and emulator testing, prepare TestFlight and Play Console submissions, reason about backgrounding and process death, design offline and sync behavior, and write mobile-appropriate tests — with framework-specific detail one reference away instead of buried in a generic prompt.
## What You Get
| Directory | Purpose |
|-----------|---------|
| `SKILL.md` | Core methodology: shared mobile workflow (scaffold → build and sign → test → ship), ownership boundaries, mobile-specific concerns (lifecycle, offline/sync, testing), trigger conditions, reference index |
| `references/ios.md` | iOS deep-dive: Xcode projects, certificates and provisioning, `xcodebuild` archive/export, simulators, lifecycle and backgrounding, App Store submission |
| `references/android.md` | Android deep-dive: Gradle and Kotlin, keystores and Play App Signing, APK/AAB builds, emulators and `adb`, lifecycle and WorkManager, Play Console submission |
| `references/flutter.md` | Flutter deep-dive: `flutter create`, `flutter build apk/appbundle/ipa`, signing delegation, hot reload, widget/integration tests, store shipping |
| `references/react-native.md` | React Native deep-dive: RN CLI vs Expo/EAS, Metro, app signing via platform toolchains, AppState, offline stores, Jest and Detox, store shipping |
| `evals/` | Output-quality eval manifest for the skill's methodology cases |
## Quick Start
Start by loading `SKILL.md` and the reference for the framework you are building:
```bash
# Native iOS — archive and export a signed .ipa for TestFlight
xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
-archivePath build/App.xcarchive archive
# Native Android — produce the signed AAB Google Play requires
./gradlew bundleRelease
# Flutter — one codebase, both stores
flutter build appbundle --release # Android → Play
flutter build ipa --release # iOS → TestFlight / App Store
# React Native (Expo) — cloud builds with managed credentials
npx eas build --platform all --profile production
```
Then use the shared workflow: scaffold the project, build and sign it, test on a simulator/emulator *and* a physical device, and ship to a testing track (TestFlight, internal Play testing) before production review.
## Triggers
- Creating a new mobile app project for iOS, Android, Flutter, or React Native
- Building, signing, or archiving a mobile release (`.ipa`, APK, AAB)
- Testing on simulators, emulators, or physical devices; device-farm test planning
- Submitting to the App Store (TestFlight/App Store Connect) or Google Play (Play Console)
- Reasoning about app lifecycle, backgrounding, process death, offline storage, or data sync
- Reviewing mobile test coverage, performance, or store-readiness
## Requirements
- Platform toolchains as needed: Xcode (iOS, macOS), Android SDK/JDK + Gradle (Android), Flutter SDK (Flutter), Node.js + Metro (React Native)
- Apple Developer Program account for iOS signing and TestFlight; Google Play developer account for Android distribution
- No Python or runtime dependencies for the skill itself — it is reference material only
mobile-development/SKILL.md
+232
View File
@@ -0,0 +1,232 @@
---
name: mobile-development
description: Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope.
license: MIT
metadata:
tags: mobile, ios, android, flutter, react-native, swift, kotlin, xcode, gradle, app-store, play-store
source_repo: https://github.com/magnus919/hermes-profiles
---
# Mobile Development
One skill for building mobile apps on **iOS** and **Android** — with per-framework
depth for native (Swift/SwiftUI, Kotlin/Jetpack Compose) and cross-platform
(Flutter, React Native) stacks. All four share one agent workflow — scaffold,
build and sign, test on devices and emulators, and ship to stores — so they live
in **ONE family skill** with per-framework references, following the
`frontend-engineering` precedent. Load the shared workflow below, then pull the
reference for the framework you are actually building.
| Framework | Stack | Reference (load on demand) |
|-----------|-------|----------------------------|
| iOS | Swift, SwiftUI/UIKit, Xcode | [references/ios.md](references/ios.md) |
| Android | Kotlin, Jetpack Compose, Gradle | [references/android.md](references/android.md) |
| Flutter | Dart, Flutter SDK | [references/flutter.md](references/flutter.md) |
| React Native | TypeScript/JavaScript, React, Metro | [references/react-native.md](references/react-native.md) |
## When to use
Load this skill when the task involves any part of the mobile lifecycle:
- **Scaffold** — creating a new mobile project for iOS, Android, Flutter, or
React Native: choosing the framework, initializing the project, and setting up
the platform toolchains.
- **Build and sign** — compiling a debug or release build, configuring code
signing (certificates, provisioning profiles, keystores, app signing), or
producing distributable artifacts (`.ipa`, APK, AAB).
- **Test on devices and emulators** — running and debugging on iOS simulators,
Android emulators, or physical devices, including device provisioning,
connectivity, and platform-specific runtime behavior.
- **Ship to stores** — submitting to the App Store (TestFlight, App Store
Connect) or Google Play (internal/closed/open testing tracks, Play Console),
and reasoning about store review readiness.
- **Mobile-specific behavior** — app lifecycle and backgrounding, offline
storage and sync, push notifications, deep links, and mobile testing
(unit, widget, UI, and device-farm testing).
## When not to use
- **Web frontends** — component architecture, state management, and browser
behavior belong to [frontend-engineering](../frontend-engineering/SKILL.md);
this skill covers apps that run on iOS and Android devices.
- **Backend services and APIs** — server-side logic, API design, and data
persistence on the server belong to
[backend-engineering](../backend-engineering/SKILL.md). Mobile apps consume
those APIs; they do not replace them.
- **Desktop or web platform targets** — Flutter for desktop/web and React
Native for web (React Native Web) have different delivery and testing
surfaces; this skill is scoped to the iOS and Android app store platforms.
- **Cross-platform web-first development** — if the deliverable is a website or
PWA, use frontend-engineering instead.
## The Mobile Engineer's Domain
| You own | You don't own |
|---------|--------------|
| Mobile app architecture — platform structure, app entry points, navigation, and state management on the device | Backend APIs, data models, and server-side persistence — that's the backend-engineering |
| Framework and toolchain setup — Xcode/Gradle project config, Flutter/React Native scaffolding, dependency management | Web frontend architecture and browser behavior — that's the frontend-engineering |
| Builds and signing — debug/release builds, certificates, provisioning profiles, keystores, app signing, versioning and build numbers | Release orchestration and rollout process for server software — that's the release-engineering |
| Device and emulator testing — simulators, emulators, physical devices, adb/xcrun device workflows | Test strategy, coverage, and quality gates for the whole product — that's the qa-methodology |
| Mobile-specific concerns — lifecycle/backgrounding, offline and sync, push, deep links, mobile performance | User journeys, wireframes, and interaction design — that's the product-design-and-ux |
| Store submission — TestFlight, App Store Connect, Play Console, release tracks, store listing metadata | CI/CD pipeline infrastructure — that's the platform-engineer |
## The Shared Mobile Workflow
Every mobile task follows the same four steps regardless of framework. Deep
framework-specific detail is deferred to the per-framework reference — read it
at the step where it matters.
### 1. Scaffold
Pin down what the app is before generating code:
- **Platform and framework** — native iOS, native Android, Flutter, or React
Native. Choose based on team skills, target audience, and per-feature needs
(see Core Principles).
- **Minimum OS versions** — the oldest iOS and Android versions you will
support; every decision below (APIs, dependencies, testing) flows from this.
- **Project initialization** — generate the project with the framework's
canonical tool (`xcodebuild`/Xcode template, Android Studio/Gradle, `flutter
create`, `npx @react-native-community/cli init` or `create-expo-app`), and
commit the scaffold before adding app code so toolchain upgrades stay
reviewable.
- **Source of truth** — a single project root that builds both platforms when
using a cross-platform framework, so the artifact is reproducible from the
repository.
### 2. Build and sign
A build that only works on your machine is not a build:
- **Build once, in CI** — the release build must reproduce on a clean machine
or CI runner, not just in your IDE. Pin toolchain versions (Xcode, JDK/Gradle,
Flutter SDK, Node).
- **Signing is separate from building** — keep signing assets (certificates,
provisioning profiles, keystores) out of the repository; reference them via
environment or secure secret storage. See the per-framework reference for
where each platform expects them.
- **Distinguishable artifacts** — version numbers and build numbers must
increment per release so testers and crash reports can identify the build.
- **Know your artifact format** — `.ipa` for iOS, APK and AAB for Android,
and the framework-specific intermediates. Store submission has hard format
requirements (for example, Google Play requires AAB for new apps).
### 3. Test on devices and emulators
Test where the code runs, not where it is convenient:
- **Emulators/simulators for speed, devices for truth** — simulators and
emulators are fast and scriptable, but physical devices reveal real
networking, battery, memory, and sensor behavior. Cover both.
- **Cold install** — test a fresh install (not just a rebuild over the old
version) to catch first-launch, storage, and migration bugs.
- **Device matrix** — cover the OS versions and screen sizes you declared in
scope, plus low-memory and low-storage conditions. Use a device farm
(Firebase Test Lab, BrowserStack, Xcode Cloud) when the matrix outgrows local
hardware.
- **Debug and release parity** — the debug build and the release build are
different programs (proguard/minification, stripping, optimization). Smoke
test the signed release artifact before store submission.
### 4. Ship to stores
Submission is a checklist, not an afterthought:
- **Test track first** — distribute to TestFlight (iOS) and an internal or
closed testing track (Android) before production; the store will not be your
first real device feedback loop.
- **Store readiness** — metadata, screenshots, privacy policy, data-collection
declarations, and privacy nutrition labels must match what the app actually
does. Review requirements change; re-check them near submission time.
- **Review expectations** — both stores reject apps for missing privacy
disclosures, misleading metadata, crashes on launch, and broken sign-in or
in-app purchase flows. Run the app through the platform's review checklist
before uploading.
- **Rollout** — prefer staged rollouts (phased release on Play, gradual
release on App Store Connect) so a regression reaches few users before it
reaches everyone.
## Mobile-Specific Concerns
These concerns are where mobile engineering differs from web and desktop work.
### App lifecycle and backgrounding
Mobile OSes kill and suspend apps aggressively; the lifecycle is not optional:
- **Lifecycle states** — iOS (foreground/background/inactive, scene-based
lifecycle) and Android (activity/fragment states, process death). State that
is not persisted across these transitions is lost.
- **Background execution is a privilege** — both platforms restrict background
work. Use the platform's sanctioned mechanisms (background modes, `WorkManager`,
background fetch, push-driven wakeups) instead of fighting the OS.
- **Process death** — the OS can kill the app at any time. Save in-progress
state, and restore UI state from storage on relaunch, not from memory.
### Offline and sync
Mobile networks are unreliable; offline is a first-class mode:
- **Offline-first storage** — local persistence (Core Data, Room, SQLite-based
stores, or key-value stores) is the source of truth while disconnected;
the network is a sync channel, not a dependency.
- **Sync semantics** — define conflict resolution (last-write-wins, per-field
merge, or explicit conflict UI), idempotent writes, and retry with backoff.
Never blindly overwrite newer remote data with stale local data.
- **Queue mutations** — writes made offline must be queued and replayed in
order when connectivity returns, with a clear sync state surfaced to the user.
### Mobile-specific testing
Beyond unit tests, mobile code needs platform-aware testing:
- **Unit and widget/component tests** — framework-level logic, reducers, and
state without a device (XCTest, JUnit, Flutter widget tests, Jest).
- **UI/instrumentation tests** — drive the real UI on a device or emulator
(XCUITest, Espresso/Compose UI tests, Flutter `integration_test`, Detox).
- **Device-farm coverage** — run the UI suite across the device matrix on a
farm; a test that passes on one device is not a guarantee.
- **Performance and battery** — measure launch time, frame rate, memory, and
network on device, not just functionality.
## Core Principles
**Pick the framework by the constraints, not the hype** — native iOS and
Android give the deepest platform integration; Flutter and React Native give
shared code across platforms. The right choice depends on team skills, the
device APIs the app needs, and how much per-platform work is acceptable. Match
the decision to the app's actual requirements.
**The OS lifecycle is part of the contract** — mobile apps are suspended,
killed, and backgrounded constantly. Any feature that assumes the app is always
alive and online will break. Design for process death and disconnection from
the first commit.
**Signing and builds are release engineering, not CI garnish** — an app that
cannot be reproducibly built and signed cannot be released, patched, or
audited. Keep signing assets secret, pinned, and scriptable, and treat the
release pipeline as production infrastructure.
**Test the artifact you ship** — the signed release build, not the debug build,
is what users and reviewers see. Smoke-test it on a real device before it
reaches TestFlight, Play, or the App Review team.
**Store requirements are moving targets** — privacy declarations, target API
levels, and submission formats change every year. Verify requirements against
the current store documentation near submission time rather than relying on
remembered rules.
## Related skills
- [frontend-engineering](../frontend-engineering/SKILL.md) — web frontend
methodology; the sibling family-skill precedent this skill mirrors, and the
routing target for browser-based UI work.
- [backend-engineering](../backend-engineering/SKILL.md) — the APIs and
services mobile apps consume; the routing target for server-side work.
- [release-engineering](../release-engineering/SKILL.md) — release
orchestration, versioning, and rollout methodology; store releases are one
instance of the discipline.
- [qa-methodology](../qa-methodology/SKILL.md) — test strategy and quality
gates; the routing target for product-wide test planning.
- [platform-engineering](../platform-engineering/SKILL.md) — CI/CD pipelines
and build infrastructure for shipping mobile builds at scale.
mobile-development/evals/evals.json
+78
View File
@@ -0,0 +1,78 @@
{
"schema_version": 1,
"skill_name": "mobile-development",
"evals": [
{
"id": "ios-build-signing-review",
"prompt": "Our iOS team has a release build that only works on the lead developer's Mac. Reviewing their setup: the .xcodeproj references a distribution certificate and provisioning profile stored in a shared drive, builds are run from Xcode's UI, and the ExportOptions.plist is regenerated by hand each release. Walk me through reviewing and fixing the build and signing setup so any machine or CI runner can produce a signed .ipa.",
"expected_output": "A build-and-signing review that separates building from signing. The review recommends a reproducible release build: a committed scheme and ExportOptions.plist (secrets-free), the distribution certificate and provisioning profile injected via CI secrets or a secure secrets store rather than a shared drive, and the archive/export flow scripted with xcodebuild -archive and xcodebuild -exportArchive so any machine with the same Xcode version produces the same signed artifact. It flags that regenerating ExportOptions.plist by hand is a review risk (a wrong export method or team produces a rejected upload) and that the certificate/profile must be versioned and renewed on a calendar. It verifies the .ipa actually signs with the distribution identity before upload and that build numbers increment per release.",
"assertions": [
"The review separates build configuration from signing assets and keeps secrets out of the repository",
"The review scripts the archive/export flow with xcodebuild so builds reproduce on any machine or CI runner",
"The review flags hand-regenerated ExportOptions.plist and shared-drive certificates as risks with concrete fixes",
"The review covers certificate/profile expiry management and monotonic build numbers",
"The review verifies the signed .ipa with the distribution identity before store upload"
]
},
{
"id": "android-release-signing-readiness",
"prompt": "We are about to release an Android app to Google Play for the first time. Our release keystore exists but only one engineer has it, the version code has never been set explicitly, and we have been shipping debug APKs to testers. Prepare the release build and signing for the Play Store and tell us exactly what to check before the first upload.",
"expected_output": "A release-readiness plan for Android: configure signing in build.gradle.kts via a keystore referenced from environment variables or a gitignored keystore.properties (never committed passwords), set versionName and a monotonic versionCode explicitly, and build the Android App Bundle (bundleRelease) since Google Play requires AAB for new apps and signs per-device APKs via Play App Signing with the upload key. The plan backs up the keystore and document who holds it, verifies the signed artifact with apksigner, and lays out the Play Console flow: upload the AAB to internal/closed testing first, complete the data-safety declaration and store listing, then a staged production rollout with crash monitoring. It calls out that losing the keystore means the app identity cannot be updated.",
"assertions": [
"The plan configures release signing from secrets and commits no keystore or passwords",
"The plan sets versionCode and versionName explicitly and builds the AAB required by Play",
"The plan explains Play App Signing and the upload key versus the app signing key",
"The plan verifies the artifact signature and tests via internal/closed tracks before production",
"The plan covers keystore backup/custody and staged rollout with crash monitoring"
]
},
{
"id": "mobile-testing-strategy",
"prompt": "We just built a shopping app for iOS and Android with a shared React Native codebase. So far the only testing is developers tapping through the app on their own phones. Design a realistic mobile testing strategy covering the device and emulator matrix, the right test layers, and what runs in CI versus on a device farm.",
"expected_output": "A layered mobile testing strategy: fast unit and component tests (Jest + React Native Testing Library) running in CI on every commit; a small set of critical E2E flows (sign-in, checkout, offline sync) with Detox on simulators and emulators in CI; and a device-farm run (Firebase Test Lab or BrowserStack) across the declared device matrix (min SDK, current SDK, mid-range device, both OSes) on every release candidate. The strategy explains what emulators/simulators hide (real networking, sensors, battery, low-memory behavior) and therefore mandates physical-device smoke tests of the signed release build, plus cold-install testing and debug-vs-release parity checks. It assigns ownership: developers own unit/component tests, a release gate requires the E2E suite and device-farm run to pass, and failures block the store submission.",
"assertions": [
"The strategy layers unit/component tests, E2E tests, and device-farm coverage with clear CI placement",
"The strategy defines a concrete device matrix including min and current OS versions on both platforms",
"The strategy explains the limits of simulators/emulators and requires physical-device release smoke tests",
"The strategy covers cold-install and debug-vs-release parity checks",
"The strategy assigns a release gate that blocks store submission until the suite and farm pass"
]
},
{
"id": "store-submission-readiness",
"prompt": "We are submitting our app to both the Apple App Store and Google Play next week. The app collects email addresses, tracks analytics events, and supports sign-in with Apple and Google. Give us a store-readiness review: what must be in place for each store, what will get us rejected, and what order to submit in.",
"expected_output": "A store-readiness review that walks the submission checklist for both stores. For the App Store: TestFlight beta to internal and external testers first, privacy nutrition labels matching the collected data (email, analytics), Info.plist usage descriptions, complete listing with required screenshots, a demo account or demo mode since the app requires sign-in, and export compliance answers. For Google Play: the AAB uploaded to internal/closed testing, the data-safety form declaring the same data collection, privacy policy URL, and a staged production rollout. It flags the classic rejection causes: undeclared data collection, broken sign-in at review time, crashing on launch, and misleading metadata. It recommends submitting to a testing track on both stores for at least a few days before production review, and staggering the two releases so a regression can be caught on one platform before the other rolls out.",
"assertions": [
"The review covers TestFlight and internal/closed testing before production on both stores",
"The review requires privacy disclosures (nutrition labels and data-safety) to match the app's actual data collection",
"The review flags the common rejection causes: undeclared data, broken sign-in, launch crashes, misleading metadata",
"The review covers listing assets, privacy policy, and demo access for sign-in-gated apps",
"The review recommends staged rollout and staggered cross-platform release timing"
]
},
{
"id": "framework-selection-and-scaffolding",
"prompt": "We are building a new field-service app for technicians: it needs offline access to job lists, barcode scanning, GPS location capture, and push notifications, and our team is experienced in TypeScript but not Swift or Kotlin. We are deciding between native iOS + Android, Flutter, and React Native. Recommend a framework and walk through scaffolding the project correctly.",
"expected_output": "A framework recommendation grounded in the constraints: the team's TypeScript experience and the need for shared offline, barcode, GPS, and push logic across both platforms point to React Native (Expo for new apps), with native fallback reserved only for features that need deep platform integration beyond existing modules. The response evaluates the alternatives honestly: native iOS/Android give the deepest platform control but double the implementation cost for a TypeScript team, and Flutter is a strong cross-platform option but adds Dart as a new language. It then scaffolds correctly: create-expo-app, TypeScript from the start, React Navigation or Expo Router for navigation, app.json config for bundle IDs, and a plan to verify each required capability (offline SQLite store, barcode library, expo-location, expo-notifications) early with a spike before committing to the full build.",
"assertions": [
"The recommendation is grounded in team skills and the required device capabilities, not hype",
"The response compares native, Flutter, and React Native with honest tradeoffs",
"The response scaffolds with the canonical tool for the chosen framework with TypeScript",
"The response covers navigation, config, and bundle IDs at scaffold time",
"The response verifies the hard device capabilities (offline, barcode, GPS, push) with an early spike"
]
},
{
"id": "offline-sync-design",
"prompt": "Our field-service app must work in basements and rural areas with no connectivity for hours. Technicians create and complete jobs offline, and those changes must reach the server without data loss or duplication, while the same job may be edited by a dispatcher at the same time. Design the offline storage and sync architecture.",
"expected_output": "An offline-first architecture: local storage (SQLite-based, e.g., WatermelonDB/Realm or Room/drift depending on stack) is the source of truth while disconnected; every write is persisted locally and queued as a mutation with a client-generated ID so replay is idempotent. Sync runs when connectivity returns (with retry and exponential backoff, and a network-constraint-triggered job), uploading queued mutations in order and downloading changes since a cursor. Conflict resolution is explicit: per-field merge with timestamps for independent edits, and a visible conflict-resolution flow when the same field changed on both sides — never silent last-write-wins over newer remote data. The design covers partial sync (only the technician's assigned jobs), a clear sync-state indicator in the UI, and a strategy for handling the same job edited by a dispatcher concurrently, including server-side revision tokens.",
"assertions": [
"The design makes local storage the source of truth while offline and persists writes immediately",
"The design queues mutations with idempotent replay and retry with backoff on reconnect",
"The design defines explicit conflict resolution for concurrent edits, including the dispatcher case",
"The design covers partial sync and a user-visible sync state indicator",
"The design includes server-side revision tokens or equivalent to detect stale writes"
]
}
]
}
mobile-development/references/android.md
+176
View File
@@ -0,0 +1,176 @@
# Android Reference — Kotlin, Gradle, Google Play
> **Last Updated:** 2026-08-03
Load this reference when the target platform is **Android** — native Kotlin
apps built with Gradle, or an Android target inside a Flutter or React Native
project (tooling for those is in [flutter.md](flutter.md) and
[react-native.md](react-native.md); this file is the platform layer under
them). It complements the shared workflow in `SKILL.md`; this file is the
Android-specific detail for scaffolding, building and signing, emulator and
device testing, and Play Store submission.
## Android fundamentals
An Android app is a compiled, signed package built by Gradle:
- **Gradle project** — a project root with `settings.gradle(.kts)`, an `app`
module with `build.gradle(.kts)`, and `gradle/libs.versions.toml` for version
catalog dependency management. Kotlin DSL (`.kts`) is the current default.
- **Manifest** — `AndroidManifest.xml` declares the application, activities,
services, receivers, permissions, and the minimum/target SDK.
- **Build outputs** — `assembleDebug`/`assembleRelease` produce APKs;
`bundleRelease` produces an **Android App Bundle (AAB)**, the required
submission format for new apps on Google Play (since 2021, and still the
rule). Google Play derives per-device APKs from the AAB via **Play App
Signing**.
- **Gradle wrapper** — commit `gradlew` and `gradle/wrapper/` so builds use a
pinned Gradle version on every machine and CI runner.
Keep the version name (`versionName`) and version code (`versionCode`, a
monotonic integer) in `build.gradle.kts` — Play rejects a build whose version
code is lower than a previous upload.
## Scaffolding
- **New native app** — create the project in Android Studio or with the Gradle
template (`gradle init`); choose Kotlin and Jetpack Compose for new UI.
- **Minimum and target SDK** — set `minSdk` to the oldest Android version in
scope and keep `targetSdk` current; Play enforces minimum target API levels
for new and updated submissions, and raised target levels are announced
annually.
- **Dependencies** — prefer version catalogs (`libs.versions.toml`) and commit
the lockfile (`gradle.lockfile` or dependency locking) for reproducibility.
- **App structure** — a single-activity app with Compose navigation for new
work; keep the manifest minimal and declare only the permissions the app
actually uses.
## Builds and signing
### Signing model
- **Local signing** — a Java keystore (`.jks`/`.keystore`) with an alias,
configured via `signingConfigs` in `build.gradle.kts`. Signing configs must
never be committed with their passwords; read them from environment
variables or a secrets store at build time.
- **Play App Signing** — Google holds the app signing key; the **upload key**
you sign with is only used to upload the AAB to Play. Upload keys can be
rotated without user-visible changes; losing the upload key requires Play
Console support intervention.
- **Keystore custody** — the release keystore is a production secret: back it
up, store it outside the repository, and restrict access. Losing it means
the app can no longer be updated under the same identity.
### Signing practices
- **Debug builds sign automatically** with the debug keystore — never ship
them.
- **Release builds in CI** — inject keystore path, passwords, and aliases via
CI secrets; keep `keystore.properties` (or equivalent) out of version
control. Use `signingConfig` referenced from a file that CI can generate.
- **Two build types** — `debug` and `release` differ in signing, shrinking
(R8/ProGuard), and manifest merging. Smoke-test the signed release artifact,
not just the debug build.
### Build commands
```sh
# Debug APK (fast iteration)
./gradlew assembleDebug
# Release APK (signed, shrunk)
./gradlew assembleRelease
# Release App Bundle (required for Play Store submission)
./gradlew bundleRelease
```
The AAB lives in `app/build/outputs/bundle/release/`; the signed APK in
`app/build/outputs/apk/release/`. Verify the APK signature with
`apksigner verify --print-certs app-release.apk` before distribution.
## Emulators and devices
- **Emulators (AVD)** — Android Studio AVD Manager creates virtual devices;
headless emulators are scriptable for CI:
```sh
emulator -avd Pixel_8 -no-window -no-audio -no-boot-anim &
adb wait-for-device
adb install app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.example.app/.MainActivity
```
- **Physical devices** — enable USB debugging and use `adb devices` to verify
the connection; real devices reveal networking, battery, and sensor
behavior the emulator hides.
- **Debugging** — `adb logcat` for logs, `adb shell dumpsys` for system
state, and Android Studio Profiler for CPU/memory/network. `adb reverse`
maps device ports to the host for local API servers.
- **Device matrix** — cover the min SDK, the current SDK, and a mid-range
device; use Firebase Test Lab (or a farm) for broad matrix coverage without
local hardware.
## Lifecycle and backgrounding
- **Component lifecycle** — Activities/Fragments move through
started/paused/stopped states; ViewModels survive configuration changes and
should own UI state. `Process death` can destroy everything else.
- **State persistence** — save and restore instance state (`SavedStateHandle`,
`rememberSaveable` in Compose) for process death; persist anything important
to a durable store.
- **Background work is restricted** — Android restricts background execution
and network. Use `WorkManager` for deferrable, guaranteed work, and
foreground services (with a visible notification) only for user-visible
tasks. `AlarmManager` is for alarms, not general scheduling.
- **Doze and app standby** — the system batches background work when idle;
test offline sync and push handling under Doze, not just with the screen on.
## Offline and sync
- **Local persistence** — Room (SQLite ORM) for structured data, DataStore
(Preferences/Proto) for settings, and file storage under the app's
internal/external storage. Keep the database schema versioned with
migrations tested.
- **Sync pattern** — write locally, then sync: queue writes, replay them with
retry and backoff when connectivity returns, and resolve conflicts
explicitly. `WorkManager` with network constraints is the idiomatic sync
trigger.
- **Connectivity** — use `ConnectivityManager`/NetworkCallback to observe
connectivity, but design for a lost network degrading gracefully.
## Testing
- **Unit tests** — JUnit + MockK/mockito for logic; Robolectric runs
Android-framework code on the JVM for fast local tests.
- **Instrumented/UI tests** — Espresso (Views) or Compose UI tests
(`createAndroidComposeRule`) drive the real app on an emulator/device.
- **Snapshot tests** — Compose Preview-based snapshot testing (e.g.,
Roborazzi, Paparazzi) catches UI regressions without a device.
- **Device farms** — run the instrumentation suite on Firebase Test Lab
across the device matrix; a test passing on one API level is not a
guarantee across them.
## Store submission
1. **Play Console setup** — the $25 developer account, app record, and
developer verification (new developers complete identity verification and
a closed-test requirement with at least 12 testers for 14 days before
production access).
2. **Upload the AAB** — upload `app-release.aab` to an internal, closed, or
open testing track first; run internal testing with your own devices before
production. Play generates and signs per-device APKs via Play App Signing.
3. **Store listing and policies** — screenshots, feature graphic, privacy
policy URL, and a **data safety** declaration matching what the app
collects. Play policy review rejects apps for undeclared data collection,
broken core functionality, and misleading metadata.
4. **Staged rollout** — use phased rollouts (e.g., 10% → 50% → 100%) and
monitor crash and ANR rates in Play Console before full release. Pause the
rollout immediately if a serious regression appears.
## Key references
- Google Play Console help and policy center (support.google.com/googleplay)
— current data-safety and testing-track requirements.
- Android developer documentation (developer.android.com) — target API
level deadlines and app bundle guidance change annually.
mobile-development/references/flutter.md
+162
View File
@@ -0,0 +1,162 @@
# Flutter Reference — Dart, flutter CLI, iOS + Android
> **Last Updated:** 2026-08-03
Load this reference when the project is built with **Flutter** — a single Dart
codebase compiled to native iOS and Android binaries. It complements the
shared workflow in `SKILL.md` and the platform references ([ios.md](ios.md),
[android.md](android.md)): Flutter delegates signing, lifecycle, and store
mechanics to the underlying platforms, so this file focuses on the Flutter
layer — scaffolding, builds, device workflows, and testing.
## Flutter fundamentals
- **Flutter SDK** — install the current stable channel (`flutter stable`).
Pin the Flutter version (via the `flutter` SDK manager or the repo's
`.fvmrc`/FVM config) so CI and machines build the same binary.
- **Project structure** — `lib/` (Dart source), `test/` (tests), `pubspec.yaml`
(dependencies and assets), and platform folders `android/`, `ios/`,
`linux/`, `macos/`, `web/`, `windows/`. Cross-platform code lives in `lib/`;
the platform folders are generated and rarely edited directly.
- **Dependencies** — `pubspec.yaml` with the `pubspec.lock` committed for
reproducibility; `flutter pub get` resolves them. Prefer the Flutter
ecosystem packages maintained by the Flutter team.
- **Rendering** — Flutter renders its own UI with Skia/Impeller; fonts,
text, and layout behave consistently across platforms, which simplifies
cross-device visual testing.
## Scaffolding
```sh
flutter create --org com.example --project-name my_app --platforms ios,android my_app
```
- **Project name matters** — it becomes the Dart package name and the default
bundle ID prefix; changing it later is disruptive. `--org` sets the bundle
identifier base (`com.example.my_app`).
- **App entry point** — `lib/main.dart` runs `runApp()` with the root widget;
keep it thin and delegate to feature-level code.
- **State management** — choose per app size: `setState` for local state,
Provider/Riverpod/Bloc for shared state. Keep state logic testable in Dart
without a device.
- **Platform tooling** — iOS targets still need Xcode, Android targets still
need the Android SDK/JDK; `flutter doctor` verifies the whole toolchain.
## Builds and signing
### Build commands
```sh
# Debug build + hot reload on a connected device
flutter run
# Release APK (Android)
flutter build apk --release
# Release App Bundle (Android, for Play Store)
flutter build appbundle --release
# iOS archive + export (requires macOS + Xcode; produces .ipa via Xcode)
flutter build ipa --release
```
### Signing
Flutter delegates signing to the platform toolchains:
- **Android** — signing is configured in `android/app/build.gradle.kts`
exactly as for a native app: keystore + `signingConfigs`, with secrets via
environment or a gitignored `key.properties`. `flutter build appbundle`
produces the AAB that Play signs via Play App Signing.
- **iOS** — `flutter build ipa` runs the Xcode archive/export flow under the
hood; configure automatic signing (developer team) in the Xcode project or
supply an `ExportOptions.plist`. TestFlight and App Store upload work the
same way as native iOS.
- **Flutter specific** — `flutter build` embeds the Dart AOT snapshot into
the platform binary; `--release` differs from `--debug` in tree shaking and
compilation, so test the release build.
## Devices and emulators
```sh
flutter devices # list connected devices and emulators
flutter emulators # list available emulators
flutter run -d <device> # run on a specific device
```
- **Hot reload** — `flutter run` supports hot reload (state preserved) and hot
restart (state reset) for fast iteration; hot reload does not run on
release builds.
- **iOS simulator** — boot via Xcode or `open -a Simulator`; `flutter run -d
"iPhone 16"`.
- **Android emulator** — start an AVD first; `flutter run` picks it up.
- **Physical devices** — USB debugging (Android) and trust the computer (iOS);
test on real devices for networking, sensors, and performance.
- **Debug vs release parity** — `flutter run` (debug) enables hot reload but
is slower and includes assertions; verify the release build (`flutter run
--release`) before shipping.
## Lifecycle and backgrounding
- **App lifecycle** — `WidgetsBindingObserver` + `AppLifecycleState`
(inactive/paused/resumed/detached) tells the widget tree about backgrounding
and resumption. Persist state on `paused`, not on `resumed`.
- **Platform behavior underneath** — iOS and Android still enforce their own
background rules; Flutter code stops executing when the app is suspended.
Use platform channels or plugins (`WorkManager`, background fetch) for
background work, and be aware that plugins wrap the platform APIs covered in
[ios.md](ios.md) and [android.md](android.md).
- **Process death** — the OS can kill the app at any time; persist state to
local storage rather than relying on widget state.
## Offline and sync
- **Local persistence** — `sqflite`/`drift` (SQLite) for structured data,
`shared_preferences` for small settings, and file/asset storage for larger
data. Keep database migrations versioned and tested.
- **Sync pattern** — persist locally first, queue mutations, and replay them
against the API with retry and backoff when connectivity returns.
`connectivity_plus` observes reachability; design for offline to degrade
gracefully regardless.
- **Conflict resolution** — define an explicit strategy (last-write-wins,
per-field merge, or conflict UI) so offline edits never silently clobber
remote data.
## Testing
```sh
flutter test # unit + widget tests
flutter test integration_test # integration tests on device/emulator
```
- **Widget tests** — fast, headless tests of widget trees (`WidgetTester`,
`pumpAndSettle`); cover state, navigation, and rendering logic without a
device.
- **Unit tests** — plain Dart tests for models, reducers, and services;
dependency-inject network and storage so tests run offline.
- **Integration tests** — `integration_test` runs the real app on a device or
emulator, driving the UI and asserting end-to-end behavior; run these on the
device matrix (locally or on Firebase Test Lab) before release.
- **Golden/snapshot tests** — `matchesGoldenFile` renders widgets to images
for visual regression; commit golden files with reviewed diffs.
## Store submission
Flutter apps ship through the same stores as native apps; the store-facing
work is platform mechanics:
- **Android** — upload `build/app/outputs/bundle/release/app-release.aab` to
Play Console (internal/closed/open testing, data-safety declaration, staged
rollout). See [android.md](android.md) for the full checklist.
- **iOS** — `flutter build ipa`, upload the `.ipa` to App Store Connect
(TestFlight first), complete privacy labels and listing, submit for review.
See [ios.md](ios.md) for the full checklist.
- **Version parity** — keep `version`/`build` aligned between `pubspec.yaml`
and the platform configs so a release is identifiable across stores.
## Key references
- Flutter documentation (docs.flutter.dev) — current stable channel releases,
platform integration guides, and release notes.
- Per-platform references in this skill — [ios.md](ios.md) and
[android.md](android.md) for signing, lifecycle, and store mechanics.
mobile-development/references/ios.md
+176
View File
@@ -0,0 +1,176 @@
# iOS Reference — Swift, Xcode, App Store
> **Last Updated:** 2026-08-03
Load this reference when the target platform is **iOS** — native Swift apps
built with Xcode, or an iOS target inside a Flutter or React Native project
(that tooling is covered in [flutter.md](flutter.md) and
[react-native.md](react-native.md); this file is the platform layer under
them). It complements the shared workflow in `SKILL.md`; this file is the
iOS-specific detail for scaffolding, building and signing, simulator and
device testing, and App Store submission.
## iOS fundamentals
An iOS app is a signed, structured bundle (`.app`) archived into an `.ipa` for
distribution:
- **Xcode project** — `.xcodeproj` (single target) or `.xcworkspace` (when
using CocoaPods or Swift Package Manager workspace integration). The project
file holds build settings, targets, schemes, and signing configuration.
- **Build products** — the `.app` bundle contains the compiled binary
(Mach-O), `Info.plist` (bundle ID, version, permissions), entitlements, and
resources. Xcode "Archive" produces the `.xcarchive` used for store upload.
- **Distribution artifacts** — `.ipa` (signed `.app` inside a `Payload/`
directory) for TestFlight and App Store, and `.xcarchive` for archival and
re-export. Ad-hoc and enterprise distribution reuse the same `.ipa` format
with different signing profiles.
Keep `Info.plist` keys (bundle identifier, `CFBundleShortVersionString`,
`CFBundleVersion`, usage-description strings for camera/location/etc.) accurate
and reviewed — store review and crash reporting both depend on them.
## Scaffolding
- **New native app** — create the project in Xcode or with `xcodebuild`
templates; choose SwiftUI for new apps (UIKit remains for legacy or
fine-grained control). Set the deployment target to the minimum iOS version
you committed to in scope.
- **Dependencies** — prefer Swift Package Manager (SPM) for new work;
CocoaPods is still common in existing codebases. Commit the lockfile
(`Package.resolved`, `Podfile.lock`) so builds are reproducible.
- **App structure** — keep the app entry point (the `@main` `App`/`AppDelegate`
and scene) thin, and organize the rest by feature rather than by type.
- **Signing early** — set up a development team and automatic signing before
the first device run; the simulator can build unsigned, but a device needs a
valid signing identity and provisioning profile.
## Builds and signing
### Signing model
iOS signing has two assets, both managed per Apple Developer account:
- **Certificates** — a development certificate (for device installs) and a
distribution certificate (for TestFlight/App Store). Certificates are tied
to the account; distribution certificates can be shared between machines but
should be kept in secure storage.
- **Provisioning profiles** — bind a certificate to app IDs and (for
development) devices. Profiles expire and must be renewed; automatic signing
in Xcode handles this when a developer account is configured.
### Signing practices
- **Automatic signing for development** — let Xcode manage profiles against
the developer account for local device builds.
- **Release signing in CI** — export the distribution certificate and profile
as secrets; never commit `.p12`, `.mobileprovision`, or private keys to the
repository. Use `xcodebuild -exportArchive -exportOptionsPlist` with the
`-exportOptionsPlist` file committed (it contains no secrets) so CI produces
the same artifact as a local Archive.
- **Two app IDs, two signing identities** — a development build and a release
build are different signed artifacts. Verify both sign correctly; a profile
mismatch is the most common first-upload rejection.
### Build commands
```sh
# Build for a simulator (no signing needed)
xcodebuild -workspace App.xcworkspace -scheme App -configuration Debug \
-sdk iphonesimulator build
# Archive for distribution (signs with the distribution identity)
xcodebuild -workspace App.xcworkspace -scheme App -configuration Release \
-archivePath build/App.xcarchive archive
# Export an .ipa for TestFlight / App Store from the archive
xcodebuild -exportArchive -archivePath build/App.xcarchive \
-exportOptionsPlist ExportOptions.plist -exportPath build/ipa
```
## Simulators and devices
- **Simulators** — `xcrun simctl` lists, boots, installs, and launches
simulators headlessly, which makes it scriptable for CI smoke tests:
```sh
xcrun simctl list devices
xcrun simctl boot "iPhone 16"
xcrun simctl install booted build/App.app
xcrun simctl launch booted com.example.app
```
- **Physical devices** — a device build requires the device's UDID in a
development provisioning profile. Verify on a physical device: real
networking, background execution, push, and sensors behave differently from
the simulator.
- **Debugging** — `xcodebuild` + Instruments for profiling; `log stream` and
unified logging (OSLog) for diagnostics on device. Crash reports appear in
Xcode Organizer and App Store Connect once TestFlight testers use the app.
## Lifecycle and backgrounding
- **Scene-based lifecycle** — modern iOS apps manage `Scene` lifecycle
(active/inactive/background); the app delegate owns launch and termination.
Persist state in `sceneDidEnterBackground` or at state transitions — do not
assume the app will be resumed.
- **Background modes** — background execution requires a declared background
mode (audio, location, background fetch, push notifications) in
`Info.plist` capabilities. Apple reviews these declarations; use them only
for their stated purpose.
- **Push notifications** — the app must register for remote notifications and
handle both foreground presentation and background delivery; silent pushes
are rate-limited by the OS.
- **Process death** — the OS can terminate the app at any time. Save
user-visible state and restore it on launch rather than keeping it in
memory.
## Offline and sync
- **Local persistence** — Core Data or SwiftData for relational models,
`FileManager`/Documents for files, `UserDefaults` for small settings.
Consider that `UserDefaults` is not a database.
- **Sync pattern** — persist locally first, then sync: queue writes in a local
store, replay them against the API when connectivity returns, and resolve
conflicts with an explicit strategy. `URLSession` with `waitsForConnectivity`
and background URL sessions handle retries and large transfers.
- **Reachability** — use `NWPathMonitor` to react to connectivity changes, but
design so a lost network degrades gracefully instead of crashing.
## Testing
- **Unit tests** — XCTest with the `@testable import` pattern; run in the
simulator (`xcodebuild test`).
- **UI tests** — XCUITest drives the real app via accessibility identifiers;
keep those identifiers stable and semantic.
- **Snapshot/visual tests** — libraries such as Swift Snapshot Testing render
views to images for regression detection; keep fixtures in-repo and
reviewed.
- **Performance** — measure launch time, frame rate, and memory with
Instruments (or XCTest metrics) on a physical device; simulator numbers are
not representative.
## Store submission
1. **TestFlight first** — upload the archive to App Store Connect
(`xcrun altool`/`notarytool` or Xcode Organizer), distribute to internal
and external testers, and let real devices exercise the app before review.
2. **App Store Connect setup** — the app record, bundle ID, pricing, and
availability; export compliance questions; and the build must match the
uploaded binary.
3. **Review readiness** — privacy nutrition labels for collected data,
`Info.plist` usage descriptions, a complete store listing (screenshots for
the required device sizes), and a working demo account or demo mode if the
app requires sign-in. The App Review guidelines are enforced by humans;
flaky sign-in, hidden features, and misleading metadata are common
rejection causes.
4. **Staged release** — submit for review with a gradual release or schedule
the release so a regression reaches few users first. Monitor crash rates
after release.
## Key references
- Apple Developer Program and App Store Connect documentation
(developer.apple.com/app-store/submitting).
- Xcode release notes and current SDK requirements near submission time —
minimum Xcode and iOS SDK versions change annually.
mobile-development/references/react-native.md
+178
View File
@@ -0,0 +1,178 @@
# React Native Reference — Metro, Expo, iOS + Android
> **Last Updated:** 2026-08-03
Load this reference when the project is built with **React Native** — a
JavaScript/TypeScript codebase rendering native UI components on iOS and
Android. It complements the shared workflow in `SKILL.md` and the platform
references ([ios.md](ios.md), [android.md](android.md)): React Native
delegates signing, lifecycle, and store mechanics to the underlying
platforms, so this file focuses on the React Native layer — scaffolding,
builds, device workflows, and testing, including the Expo toolchain.
## React Native fundamentals
- **Two toolchains** — the **React Native CLI** (`@react-native-community/cli`,
bare workflow, owns the `ios/` and `android/` folders) and **Expo**
(`create-expo-app`, managed workflow with `expo prebuild`/EAS for native
code when needed). Expo is the recommended starting point for new apps; the
CLI is for apps that need full native control from day one.
- **Metro bundler** — Metro compiles and bundles the JS/TS into the native
binary; the Metro config (`metro.config.js`) controls transforms, and the
Metro dev server powers fast refresh during development.
- **New Architecture** — current React Native releases (0.7x/0.8x line, with
Expo SDK 56 bundling the stable line) default to the New Architecture
(Fabric + TurboModules). Verify third-party libraries support the New
Architecture before adoption.
- **Dependencies** — `package.json` with `package-lock.json`/`yarn.lock`
committed; use the React Native/Expo version alignment (`npx
expo install` keeps packages SDK-compatible).
## Scaffolding
```sh
# Expo (recommended for new apps)
npx create-expo-app@latest MyApp
# React Native CLI (bare workflow)
npx @react-native-community/cli@latest init MyApp
```
- **App entry point** — `App.tsx` renders the root component; keep it thin
and route via React Navigation (or Expo Router) rather than hand-rolled
navigation state.
- **Platform folders** — the CLI keeps `ios/` and `android/` in the repo;
Expo hides them until `expo prebuild`. Treat generated platform folders as
build outputs, not app code.
- **TypeScript** — use TypeScript from the start; the default templates are
typed and the ecosystem type definitions are mature.
- **Environment config** — app config (`app.json`/`app.config.js` for Expo,
`.env` for secrets via `expo-constants` or a config loader); never commit
real secrets.
## Builds and signing
### Build commands
```sh
# Dev server with fast refresh (Metro)
npx expo start # Expo: QR code / dev client
npm run start # RN CLI: Metro dev server
# Android release APK/AAB
cd android && ./gradlew assembleRelease # RN CLI
npx expo run:android --variant release # Expo with prebuild
npx eas build --platform android --profile production # EAS cloud build
# iOS archive + export (requires macOS + Xcode)
cd ios && xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release archive
npx eas build --platform ios --profile production # EAS cloud build
```
### Signing
React Native delegates signing to the platform toolchains:
- **RN CLI** — Android signing via `android/app/build.gradle.kts` keystore
config (as native Android); iOS via the Xcode project's automatic signing or
an `ExportOptions.plist` (as native iOS). See [android.md](android.md) and
[ios.md](ios.md) for the platform details.
- **Expo / EAS** — EAS Build can manage credentials: it generates and stores
keystores and Apple certificates (with `eas credentials`), handles
provisioning, and can run in a cloud environment without a Mac for iOS
builds. Credentials live in Expo's secure storage or your own
`credentials.json` (gitignored).
- **Signing secrets** — keystores, `.p12`, provisioning profiles, and Expo
credentials are production secrets; never commit them, and back them up so
an app can be updated under the same identity.
## Devices and emulators
```sh
npx expo start # scan QR with Expo Go or a dev client
npx expo run:ios # build and run on the iOS simulator
npx expo run:android # build and run on an Android emulator
```
- **Expo Go vs dev client** — Expo Go runs the JS without a native build (fast
iteration); a development build (dev client) is required for custom native
modules. Test both the debug JS experience and the release bundle.
- **Fast refresh** — Metro hot-reloads edited JS while preserving state;
restart the app (not just refresh) after native or config changes.
- **Physical devices** — Android: USB debugging or Expo Go via QR; iOS: Expo
Go via QR on the same network. Real devices expose networking, permissions,
and performance differences from simulators.
- **Debug vs release parity** — the release bundle is minified, tree-shaken,
and runs without the dev server; smoke-test `--variant release`/production
builds before store submission.
## Lifecycle and backgrounding
- **AppState** — `AppState` (active/background/inactive) is the
cross-platform lifecycle signal; persist state on `background` and resume
cleanly on `active`. `AppState.addEventListener` covers both platforms.
- **Background execution** — JS stops when the app is backgrounded; use
platform mechanisms (headless tasks, background fetch, push) via native
modules or libraries. iOS and Android background rules from
[ios.md](ios.md) and [android.md](android.md) apply underneath.
- **Process death** — the OS can kill the app at any time; persist
user-visible state to local storage rather than relying on in-memory React
state.
## Offline and sync
- **Local persistence** — `AsyncStorage` (small key-value), `MMKV`
(performant key-value), or SQLite-based stores (`react-native-sqlite-storage`,
WatermelonDB, Realm) for structured offline data. Keep schemas versioned.
- **Sync pattern** — persist locally first, queue mutations, and replay them
against the API with retry and backoff when connectivity returns.
`@react-native-community/netinfo` observes reachability; design for offline
to degrade gracefully regardless.
- **Conflict resolution** — define an explicit strategy (last-write-wins,
per-field merge, or conflict UI) so offline edits never silently clobber
remote data.
## Testing
```sh
npm test # Jest unit/component tests
npx detox test # Detox E2E tests on iOS/Android
```
- **Unit/component tests** — Jest with React Native Testing Library;
dependency-inject services and mock native modules so tests run headless.
- **E2E tests** — **Detox** drives the real app on a simulator/emulator with
native synchronization; test critical user flows (sign-in, checkout, sync)
on both platforms. Detox requires the app to build for testing.
- **Expo testing** — `jest-expo` preset with `@testing-library/react-native`
for component tests; `expo prebuild` + Detox or Maestro for E2E.
- **Device farms** — run E2E suites across the device matrix (Firebase Test
Lab, BrowserStack) before release; a flow that passes on one device is not a
guarantee across versions and screen sizes.
- **Performance** — measure JS thread time, native render, and memory with
the React Native DevTools/Perf Monitor or platform profilers on a device;
Hermes is the default JS engine for the current releases.
## Store submission
React Native apps ship through the same stores as native apps:
- **Android** — upload the signed AAB (`android/app/build/outputs/bundle/
release/app-release.aab`, or the EAS-produced artifact) to Play Console with
internal/closed/open testing, data-safety declaration, and staged rollout.
See [android.md](android.md).
- **iOS** — archive via Xcode or EAS, upload the `.ipa` to App Store Connect
(TestFlight first), complete privacy labels and listing, submit for review.
See [ios.md](ios.md).
- **Version parity** — keep `version` in `app.json`/`package.json` aligned
with the platform build numbers so a release is identifiable across stores
and in crash reports.
## Key references
- React Native documentation (reactnative.dev) — New Architecture, Hermes, and
release notes.
- Expo documentation (docs.expo.dev) — SDK versions, EAS Build credentials,
and upgrade guides.
- Per-platform references in this skill — [ios.md](ios.md) and
[android.md](android.md) for signing, lifecycle, and store mechanics.