Proposal: Android (Kotlin / Jetpack Compose) guidance surface + twin native development

[rterakedis]

Proposal: Android (Kotlin / Jetpack Compose) guidance surface + twin native development

Status: idea for discussion — nothing implemented yet.

Motivation

Leanwheel currently ships two platform guidance surfaces: Swift/SwiftUI (stubs/swift/, refresh-swift, swift-audit, appstore-preflight, sim.sh) and Web (stubs/web/, refresh-web, web-audit). This proposal adds a third — native Android (Kotlin + Jetpack Compose) — and, on top of it, a twin-development mode: building the Apple and Android versions of the same app side-by-side as two fully native codebases driven by one shared spec.

Why two native codebases instead of a cross-platform layer (KMP, React Native, Flutter)? Those layers reintroduce exactly the problems a native-first developer wants to avoid: interop quirks, debugging across a bridge, a third toolchain. The historical objection to "write it twice natively" was human cost — but with agents, the cost structure flips. The expensive artifact is the spec (Behavior Contract, ACs, edge cases, design tokens), and leanwheel already treats the spec as the first-class deliverable. Two dev agents implementing the same contract natively is cheaper and safer than one agent translating idioms between platforms.

Leanwheel is already shaped for this: the flywheel is an orchestrator holding a small context that spawns isolated dev subagents returning terse reports. Twin dev is the same shape with two spawns per story instead of one. The real risks are spec drift (platforms quietly diverging in behavior) and doubled verification burden — both of which have leanwheel-native mitigations (shared Behavior Contracts, the stack-agnostic evals command cases, a parity pass at review).

Scope decisions (proposed)

• Kotlin + Jetpack Compose only. No XML views, no Java, single-activity architecture, Material 3. Greenfield apps have no reason to touch the legacy surface, and a narrow lane is what keeps the guidance token-lean — the same opinionated stance as the SwiftUI-only Swift stubs.
• Follow the platform on architecture style. The Swift stubs enforce a services-not-ViewModels house style; Google's canonical guidance is ViewModel-centric (ViewModel + StateFlow + unidirectional data flow), and Compose's lifecycle/config-change model genuinely wants ViewModels. The Android stubs should follow the platform and record the asymmetry explicitly so a future sync doesn't "fix" it.
• Monorepo as the recommended twin layout. /setup already supports multi-surface projects (web + Apple in one repo, both guardrail blocks in one CLAUDE.md, both stub trees under docs/setup/). Android becomes a third surface in that same pattern. The shared spec then lives in the monorepo's docs/ for free: single git history (atomic cross-platform commits per story), one GitHub issue/milestone set, and worktree isolation already handles two dev agents working different subtrees of the same repo.

Phase 0 — Facts pass before authoring anything

The refresh-swift history shows why this comes first: a past run invented a phantom OS version, and the simulator-automation work proved toolchain facts must be verified live, not recalled. Before writing stubs:

• A /research-style cited pass on current-stable facts: Android API level and target-SDK policy, Kotlin 2.x / Compose BOM versions, Play Console policies.
• All embedded Play/policy facts get the appstore-preflight treatment: dated, ⚠️-flagged where volatile, refreshed by the new refresh skill.

Phase 1 — Guidance stubs (setup/stubs/android/ + modern-android.md)

Mirror the Swift stub set file-for-file where an analogue exists, authored via the research pass, in the same lean ✅/❌ style:

Swift stub	Android analogue
architecture.md	single-activity, UI/domain/data layers, DI stance (Hilt vs manual — simplicity ladder applies)
state-management.md	StateFlow / remember / state hoisting / SavedStateHandle
concurrency.md	coroutines, structured concurrency, dispatchers, viewModelScope
ui-composition.md	recomposition discipline, stability, slot APIs, file-decomposition targets
swiftdata.md	persistence.md: Room + DataStore (self-gating, like swiftdata.md)
testing.md	JUnit / Compose testing APIs / Robolectric posture
testability.md	seed scenarios via launch extras / instrumentation args, Modifier.testTag convention (the accessibilityIdentifier analogue), one deep-link route table
accessibility.md	TalkBack, semantics, touch targets, contrast
anti-patterns.md	numbered, same format
simulator.md	emulator.md — see Phase 3
modern-swiftui.md	modern-android.md guardrails block (~50 lines, ## Android Guardrails heading in project CLAUDE.md)

Encouragingly, the deep-link route-table principle ports cleanly and Android's tooling is friendlier than simctl: adb shell am start -d delivers custom-scheme links without the iOS 26 "Open in app?" alert, uiautomator dump gives a real view hierarchy without a test runner, and dark mode / font scale are one-line adb shell settings.

Phase 2 — Skill kit (mirroring the four-skill Swift pattern)

• refresh-android — mirrors refresh-swift: gold-standard sources (developer.android.com, the Now in Android sample, Compose docs, Kotlin docs, pinned community authors), version-axis rules, updates docs/setup/android/ + stubs, and refreshes the Play-facts tables in the preflight skill (cheap-gated on Google's policy changelog).
• android-audit — mirrors swift-audit: greps source/docs/stories against the guidance, testTag convention check, staged testability retrofit (Stage 0 foundation + per-screen stages), Pass-F deletion tags, one remediation story out.
• playstore-preflight — mirrors appstore-preflight, and for a first-time Android publisher it's the highest-value skill in the set: audits manifest permissions vs declared usage, target SDK floor, Data Safety consistency, signing config, AAB readiness — plus the non-code checklist (Play Console account, identity verification, closed-testing gates, content rating questionnaire, store listing assets, pre-launch report).
• Wiring into existing skills (each a small, established touch point): setup gains an Android scaffold question + stub-copy step + guardrails append; upgrade-project detects the new assets; dev-story step 4 routes docs/setup/android/ files by story topic; code-review reads them as rejection criteria; epics / check-readiness Check 8's testability-foundation-story requirement generalizes from Apple-only to Apple-or-Android; discover / next detect Android projects (settings.gradle.kts); guard-a11y-id.sh learns the Compose interactive-element / testTag pattern, gated on the Android testability stub existing.

Per-story platform routing (forced by the monorepo layout)

Today's model routing is per-project: swift_project = "an .xcodeproj exists anywhere" → Opus for every dev story. In a monorepo holding both apps, an Android story would falsely route as Swift. The twin-era rule: classify each story by the platform/subtree it touches (frontmatter platform: field, or derived from the Design Contract), and route model + guidance stubs + Build & Test Gate command from that — xcodebuild for Apple stories, ./gradlew for Android stories, both for twin stories. Guidance routing stays scoped the same way: a story loads docs/setup/swift/ or docs/setup/android/, never both.

Model routing for Kotlin: start on the Sonnet default (Kotlin has far more training data and better compiler diagnostics than Swift) and let docs/metrics/flywheel-ledger.jsonl build-iteration counts show whether it needs the Swift-style Opus exception. That's exactly what the ledger exists for.

Phase 3 — Emulator automation (emu.sh + live verification)

The sim.sh analogue, scaffolded by /setup on Android projects:

• doctor (JDK, ANDROID_HOME, sdkmanager, licenses accepted, an AVD exists) / boot / install / launch / shots (dark/light × font-scale matrix via adb shell settings, one boot per device) / dump (uiautomator) / flow (Compose UI tests or Gradle managed devices) / open (deep links via am start).
• Config in .leanwheel/emu.json — machine-independent by construction, artifacts self-ignoring: the same conventions sim.json settled on.
• design-verify and the dev-story Build & Test Gate get Android branches (./gradlew assembleDebug testDebugUnitTest).

This phase must end with a live verification session on a real machine: install the command-line SDK, create an arm64 AVD, and actually run every subcommand. The sim.sh regression notes exist because two silent failures only surfaced under real use — the same discipline applies here.

Phase 4 — Twin native development (the genuinely new part)

Ships after Phases 1–3 are proven on a standalone Android project, because it composes them.

• Shared spec, per-platform subtrees. Platform-neutral artifacts — PRD, epics, Behavior Contracts, EXPERIENCE.md, the AC list, eval scenarios — live once in docs/. Each platform subtree keeps its own architecture doc, platform Design Contract sections, story task lists, and platform-specific eval command lines. The Behavior Contract is the keystone: it's already defined as flows/states/invariants/edge cases with no platform vocabulary, so one contract legitimately drives two implementations.
• A twin mode on the flywheel (or a thin twin-story orchestrator): create-story runs once, producing the shared contract + two platform Design Contracts; then two lw-story-developer spawns, one per subtree; each runs its own Build & Test Gate and evals; review adds a parity pass — same ACs checked off on both platforms, same edge-case handling, invariants verified on both sides. A story isn't done until both platforms are green, so drift can't accumulate silently.
• Sequencing heuristic: build the platform the maintainer knows best one story ahead for the first few epics — product decisions surface where there's judgment to resolve them, and the second platform follows a settled contract.

Data sync: within-ecosystem vs cross-ecosystem

This is the one place twin development forks on a product decision rather than a framework one, and the guidance should force the question early (at /prd or check-readiness time, before twin epics are planned):

Does a single user's data need to roam across ecosystems (e.g. an iPhone and an Android tablet)?

• No — per-ecosystem sync (recommended default). The Apple app keeps its platform-native sync (CloudKit / NSPersistentCloudKitContainer); the Android app uses Room locally (+ optionally Android's own backup / Drive auto-backup). Parity then lives at the schema and behavior level: the Behavior Contract gains a data-shape section so the Room schema mirrors the Core Data / SwiftData model entity-for-entity, and migration discipline is enforced on both sides. Cheap, and it doesn't touch a working Apple app.
• Yes — cross-ecosystem sync. Platform-native sync is a dead end: CloudKit has no Android client — an Android app cannot read or write iCloud private databases, full stop. Roaming requires a shared cross-platform backend (Firebase, Supabase, custom server) on both platforms, which for an existing CloudKit app means a significant migration before Android work even starts. The guidance should state this price plainly so it's chosen deliberately, never discovered mid-epic.

Supporting stub work either way: persistence.md gets a "Room mirrors the source schema" section for twin projects, and the Android testability stub gets the seeding-guard analogue of the Swift CloudKit guard (never seed fixtures into a production-synced store).

Play Store onboarding facts (dated Aug 2026 — ⚠️ volatile, re-verify)

Captured here because they carry real lead time for a first-time publisher; they'd live in playstore-preflight's non-code checklist, refreshed by refresh-android:

• Personal accounts created after Nov 13, 2023 must run a closed test with 12 opted-in testers for 14 consecutive days before production access. The clock starts when the 12th tester opts in. No exemptions for personal accounts.
• Organization accounts are exempt from the closed-testing requirement — but require a D-U-N-S number plus organization identity verification, which can take weeks if the entity doesn't already have one. (An existing D-U-N-S from Apple business developer enrollment transfers conceptually — both key verification off the same system.)
• Either way: account setup is the longest external lead time in the plan — start it in parallel with everything above.
• One-time $25 registration fee; AAB-only uploads; annual target-API-level ratchet; Data Safety form required.

Sources: Google Play developer community — org account clarification, The Google Play 12-Tester Rule, Explained (2026), Google Play Closed Testing Explained

Proposed rollout

1. Epic A (this repo): Phase 0 facts pass → stubs/android/ + modern-android.md → refresh-android / android-audit / playstore-preflight → skill wiring with per-story platform routing → emu.sh + emulator.md, ending with the live toolchain verification session. Symlink sync at the end (new skills/agents).
2. Proof run: a throwaway Android hello-world through the full loop (setup → story → dev → emu.sh → preflight) — doubles as an Android on-ramp for a maintainer who's never shipped one.
3. Epic B (this repo): twin-mode orchestration — shared Behavior Contract + per-platform Design Contracts, two dev spawns per story, parity pass at review — informed by whatever the proof run teaches.
4. In parallel (maintainer-side): start the Play org account + D-U-N-S process; answer the sync question above.

Open questions

1. Is the Compose-only / Material 3 / no-XML lane the right enforced scope, or does anyone need View-interop guidance?
2. Per-story platform: frontmatter vs deriving platform from the Design Contract — which is the cleaner routing key?
3. Should twin mode be a flag on the existing flywheels (--platforms apple,android) or a separate thin orchestrator skill?
4. Kotlin model routing: is Sonnet-default-with-ledger-watch the right starting posture, or should Compose stories inherit the Swift Opus exception from day one?