android-domain-delivery

Android Domain Delivery

Overview

Android Domain Delivery is the production playbook for Kotlin Android changes where UI state, lifecycle, async work, persistence, permissions, navigation, offline behavior, and tests all meet. It keeps Compose screens declarative, ViewModels lifecycle-aware, Flow pipelines cancellable, Room migrations reversible, WorkManager jobs constrained, and user-facing behavior accessible before any "done" claim.

The skill assumes modern Android: Kotlin, Jetpack Compose, ViewModel with SavedStateHandle, StateFlow, coroutines, Hilt or the local DI pattern, Room, DataStore where present, WorkManager, Navigation Compose, Material 3, and JUnit/MockK/Turbine/Compose UI or Espresso tests.

When to Use

Use for Android feature screens, ViewModel changes, repository/data-source work, Flow/coroutine behavior, Room schema changes, WorkManager jobs, navigation routes, runtime permissions, accessibility fixes, offline-first sync, test expansion, or release rollback planning.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: read local source first, preserve evidence, keep scope narrow, use current framework docs for drift-prone APIs, verify before completion claims, and cap confidence when instrumented, accessibility, offline, or migration proof is missing.

Step 0 - Read source of truth

1. Read the user request, AGENTS.md, active task item, owned write set, and any Android project notes in .supervibe/memory/.
2. Inspect settings.gradle*, module Gradle files, AndroidManifest.xml, package layout, DI modules, navigation graph, theme, database, workers, permissions, and nearest unit/instrumented tests.
3. Search existing Kotlin patterns for ViewModel, SavedStateHandle, StateFlow, collectAsStateWithLifecycle, repository boundaries, Room migrations, WorkManager constraints, permission flows, and test utilities.
4. Use CodeGraph for unfamiliar features and CodeGraph or symbol search before changing public routes, DAO methods, repository interfaces, ViewModel APIs, worker names, or shared UI components.

When not to use

• Do not use when the task is generic planning, product shaping, design, or release governance and no Android implementation or review boundary exists.
• Do not use when another stack, database, security, deployment, or API owner has the primary decision; hand off to that specialist and keep the Android part scoped.
• Do not use to justify dependency swaps, broad rewrites, heavy test runs during graph execution, or mixed old-plan scope without explicit approval.

Practical Delivery Hardening

• Keep the stack-specific lifecycle, data, security, accessibility, rollback, and test requirements in this skill as the authority; these rules only decide how small the first implementation should be.
• Check framework-native, platform-native, standard-library, and existing project capabilities before custom code, new dependencies, or a new helper; reuse the local adapter, validation, migration, component, cache, queue, or test primitive when it already covers the behavior.
• Avoid speculative abstractions: delete or skip wrappers, duplicate dispatchers, unused knobs, generic factories, and indirection until source evidence shows a second real caller or a concrete behavior gap.
• Use one focused runnable check for the changed surface: a scoped command, artifact validator, or runtime proof that exercises the stack-specific behavior. Keep broad suites and release validators for final gates unless the active workflow explicitly asks for them.
• Safety, regulatory, security, and accessibility exceptions override the minimal path. When data loss, policy-sensitive behavior, auth/permission changes, cryptography, migration risk, concurrency risk, or assistive-technology behavior is affected, upgrade to the named owner, stronger review, rollback plan, and runtime proof before claiming readiness.
• Set a simplification ceiling before coding: stay with the thin reversible slice while complexity is local, risk is low, and coupling is contained. The upgrade trigger is observable scale, repeated branching, cross-boundary coupling, durability risk, or proof that the native capability cannot satisfy the behavior; downshift again when the trigger disappears.

Decision tree

Pixel-producing UI? -> stateless Composable + Route wrapper; no repository calls.
Screen state or events? -> ViewModel owns StateFlow, SavedStateHandle, viewModelScope.
Continuous data? -> Flow from repository/DAO; lifecycle-aware collection in UI.
One-shot side effect? -> event channel/state effect consumed once, not mutable global.
Local persistence? -> Room DAO/migration or DataStore; migration and rollback proof.
Deferred/reliable work? -> WorkManager with constraints, idempotency, retry policy.
Needs camera/location/notifications/etc.? -> runtime permission UX + denied/permanent-denied path.
Navigation changes? -> typed route/deep link contract + back-stack/process-death test.
Offline requirement? -> source-of-truth cache, sync conflict policy, stale/error UI.
Accessibility affected? -> semantics, content descriptions, focus order, 48dp targets, font scale.

Procedure

1. Define the slice: feature, entry route, user outcome, data source, offline expectation, permission surface, verification command, and rollback path.

2. Map layers. UI Composables render immutable state and emit events; Route wrappers obtain ViewModels; ViewModels orchestrate use cases; repositories own data composition; DAOs and network clients do I/O only.

3. Shape state. Model loading, content, empty, validation, transient error, permission-denied, offline-stale, and retry states explicitly. Persist user-visible inputs and route args through SavedStateHandle.

4. Control coroutines. Launch UI work in viewModelScope, avoid GlobalScope, use structured concurrency, surface cancellation, and test Flow emissions with Turbine or the local test helper. Use collectAsStateWithLifecycle() in Compose, not raw collection in a Composable body.

5. Keep Compose stable. Split large screens into stateless pieces, pass stable data, provide keys for Lazy lists, avoid expensive work in @Composable functions, and localize every user-visible string and content description.

6. Handle persistence deliberately. Room queries returning changing data expose Flow; migrations are explicit, tested, and schema-exported. Never use fallbackToDestructiveMigration() in production paths.

7. Design background work. WorkManager jobs are idempotent, named, constrained for network/battery/charging as appropriate, cancellation-aware, and tested with WorkManager test helpers. Foreground work shows a user-visible notification and rollback path.

8. Implement permissions as a user journey. Include rationale, denial, permanent denial/settings, background permission constraints, and graceful feature degradation. Never request a permission before the user intent.

9. Protect navigation. Use existing route style, keep arguments typed and minimal, define deep link compatibility, test back-stack behavior, and prove process-death restoration for routes with form or scroll state.

10. Add tests first when behavior changes. Cover ViewModel state transitions, Flow success/error/loading, repository cache/network failure, DAO migration, worker retry/failure, permission denial, navigation, and Compose semantics.

11. Verify with scoped Gradle commands when policy allows. When this worker is told not to run tests, record the exact deferred commands and rely only on source review evidence.

12. Repair loop: localize failures to UI state, ViewModel, repository, Room, worker, permission, or navigation boundary; fix the smallest cause; rerun the same scoped command when allowed.

13. Read the source artifact, owned file paths, graph/task scope, and current project convention; record the evidence path, command, receipt, or runtime state that proves the starting point.

14. If required source, owner, dependency, runtime boundary, or approval is missing, stop and return BLOCKED with the missing field, impacted artifact, and next action instead of guessing.

15. After edits or reviewer findings, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, artifact path, confidence, and remaining blocker before completion.

Worked example

Add an offline-capable order history screen:

1. Navigation adds OrderHistoryRoute(accountId) and passes the ID through SavedStateHandle.
2. DAO exposes observeOrders(accountId): Flow<List<OrderEntity>>; repository exposes domain Flow<OrderHistory> and refreshes from the API on demand.
3. ViewModel combines cached orders, refresh status, and connectivity into OrderHistoryUiState.
4. Compose renders loading, stale-cache banner, empty state, retry action, TalkBack labels, and keyed LazyColumn rows.
5. WorkManager schedules constrained periodic sync with unique work and retry.
6. Tests cover cached success, network failure with stale data, empty cache, refresh retry, route process death, worker retry, and Compose semantics.

Good and bad delivery paths

Good delivery path: deliver through Navigation, Room DAO, repository Flow, ViewModel state, Compose semantics, and WorkManager unique work. Runtime-specific tests include Room migration tests, coroutine/ViewModel state tests, WorkManager retry and failure tests, Compose semantics, TalkBack labels, and process-death route restore. Rollback removes the navigation entry and unique work, keeps the Room schema compatible, and disables refresh while cached reads still render. Failure boundaries are network outage, stale or empty cache, permission or auth denial, worker exhaustion, migration incompatibility, and duplicate sync.

Bad unsafe path: write Retrofit and Room calls directly in composables, launch unscoped coroutines from buttons, add a one-way migration, and verify only with a screenshot. That path has no runtime-specific tests for the changed stack surface, no concrete rollback beyond hope or manual cleanup, and weak failure boundaries for network outage, stale or empty cache, permission or auth denial, worker exhaustion, migration incompatibility, and duplicate sync.

Anti-example or Common rationalizations

• "The Composable can call the repository because it is quick" hides lifecycle and cancellation, breaks previews/tests, and duplicates orchestration.
• "The worker only syncs a small payload" still needs constraints, idempotency, retry classification, and cancellation because it runs outside the screen.
• "We can request location on screen open" fails privacy review; permission requests must follow user intent with a denial path.
• "Room migration can be destructive in beta" fails when beta users have real data; destructive migration needs an explicit non-production guard.

Common rationalizations

• "It is just Android, so the generic implementation pattern is enough" fails because lifecycle, runtime, data, and deployment constraints differ by stack.
• "A broad suite will prove it faster" fails in graph execution; use the declared scoped command and reserve broad validators for the final release gate.
• "We can clean up the architecture while here" fails unless that cleanup is in the accepted graph scope, has rollback, and has its own verification path.

Red flags

• GlobalScope, raw CoroutineScope(), or runBlocking in production Android code.
• Mutable collections or unstable data objects passed deep into Compose.
• Flow collected in a Composable without lifecycle awareness.
• Hard-coded strings, missing content descriptions, or touch targets below 48dp.
• WorkManager request without constraints, unique work policy, or retry plan.
• Permission grant assumed in ViewModel/repository without denied/error state.
• Room schema version changed without migration and migration test.

Checklist

• Layer ownership is explicit: Composable, Route, ViewModel, use case, repository, data source, worker.
• UI state models loading, content, empty, error, offline, permission, and retry paths.
• Coroutine scopes and Flow collection are lifecycle-safe.
• Room, DataStore, WorkManager, navigation, and permission changes include tests or deferred final-gate commands.
• Accessibility covers semantics, labels, focus, font scale, contrast, and target size.
• Rollback is named for schema, route, worker, permission, or release changes.

Failure modes

• The Android specialist applies a generic pattern and misses framework-owned lifecycle, typing, permission, migration, cache, or deployment behavior.
• The worker mixes a new graph task with stale plan scope and creates a larger review surface than the MVP flow needs.
• The task closes with prose only: no source evidence, no scoped command or final-gate deferral, no rollback, and no next action for blockers.

Output contract

• status: PASS, BLOCKED, PARTIAL, or DEFERRED.
• slice: screen, ViewModel, repository, Room, WorkManager, permission, navigation, offline, or accessibility behavior changed.
• boundaries: files touched by layer and why each belongs there.
• stateAndLifecycle: StateFlow, SavedStateHandle, coroutine scope, and Flow collection decisions.
• dataAndOffline: Room/DataStore/cache/sync behavior, migration, stale data, conflict, and rollback notes.
• permissionsNavigationAccessibility: permission UX, route/back-stack, and TalkBack/font-scale evidence.
• tests: focused commands run with exit code or explicit deferral reason.
• rollback: migration down path, feature flag, work cancellation, route compatibility, or revert plan.
• confidence: score with caps from missing instrumented, migration, offline, accessibility, or runtime proof.

Guard rails

• DO NOT: mix LiveData and Flow in new code unless adapting at one legacy seam.
• DO NOT: add broad permissions, background work, destructive migrations, or route-breaking changes without product reason and rollback.
• DO NOT: put business logic, network calls, database calls, or coroutine launches inside pure Composables.
• ALWAYS: keep user-visible strings localized and accessibility semantics testable.
• ALWAYS: preserve existing app architecture and DI choices unless the task explicitly authorizes an architecture migration.

Verification

• Unit: ViewModel/use-case/repository tests with JUnit, MockK or local test doubles, Turbine for Flow, and coroutine test dispatcher control.

• Instrumented/UI: Compose UI or Espresso tests for route, interaction, permission, accessibility, and process-death behavior where affected.

• Persistence: Room migration tests and exported schema diff when DB version changes.

• Background: WorkManager test driver for constraints, retry, failure, and cancellation.

• Static/build: scoped ./gradlew test, connectedAndroidTest, lint, ktlintCheck, detekt, and assemble commands when policy allows.

• If any scoped check fails or new evidence appears, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, blockers, and final-gate deferrals before claiming completion.

Supporting references

• examples/delivery.md - worked Android implementation example, anti-example, and verification fixture.
• domain-packs/android.md - Android practice pack with review matrix, rollback prompts, and MVP guard rails.
• evals/regression.json - Use when calibrating android-domain-delivery trigger boundaries, happy-path/failure-path coverage, boundary rollback behavior, or resource-tree regressions.

Related

• supervibe:source-driven-development
• supervibe:tdd
• supervibe:test-strategy
• supervibe:verification
• supervibe:code-review
• supervibe:stacks/android:android-developer
• supervibe:stacks/flutter:flutter-developer
• supervibe:stacks/ios:ios-developer

Supporting references

Resource tree hardening

• references/practice-pack.md - Read when android-domain-delivery needs deeper load rules, local evidence anchors, gotchas, or a final checklist.
• scripts/self-check.mjs - Run with --check before claiming the android-domain-delivery resource tree is complete; add --json when machine-readable evidence is needed.
• evals/regression.json - Use when tuning android-domain-delivery trigger boundaries or checking should-trigger and should-not-trigger prompts.
• examples/workflow.md - Load when a concrete android-domain-delivery workflow example or anti-example would clarify the next action.
• templates/output-contract.md - Use when emitting agent-output so status, evidence, blockers, confidence, and nextAction stay consistent.