@code-migration/wow-migrator 0.2.3 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Install KMP migration skills into Claude Code, Codex, Cursor, Gemini, OpenCode, OpenClaw, and JiuwenSwarm via npm install.",
   "keywords": [
     "android",

package/skills/android-to-kmp-migrator/SKILL.md

@@ -63,7 +63,7 @@ Module-first migrator for Legacy Android → KMP target assembly. **Upstream ana
 
 ## Protocol Summary
 
-0. Pre-flight — [dependencies.yaml](dependencies.yaml): `rg` / `git` / `curl`, optional `jetbrains` MCP (`optional_mcp`), upstream analyst **P6** (`upstream_inputs`); record `dependency_preflight` in `run_manifest.json`.
+0. Pre-flight — [dependencies.yaml](dependencies.yaml): `rg` / `git` / `curl`, optional `jetbrains` MCP (`optional_mcp`), upstream analyst **P6** (`upstream_inputs`); **identify `design_mode` from user input (default `mvi`)**; record `dependency_preflight` and `design_mode` in `run_manifest.json`.
 1. Verify analyst **P6**; `run_manifest.json`, `upstream_analyst_index.json`.
 2. Migration inventory + `modules_migration_index.json`.
 3. Workspace state init.
@@ -73,6 +73,23 @@ Module-first migrator for Legacy Android → KMP target assembly. **Upstream ana
 7. Global representation + completion-report `report` mode.
 8. **kmp-test-validator** — **mandatory** when **V0** ready (MG17).
 
+## Design Mode (architecture pattern)
+
+The migrator targets one presentation architecture per run, selected at **pre-flight (Step 0)** by the Leader from the **user input**, then frozen for the whole run and recorded in `run_manifest.json` → `design_mode`.
+
+| `design_mode` | Architecture reference | When chosen |
+|---|---|---|
+| `mvi` **(default)** | [references/kmp-mvi-flowredux.md](references/kmp-mvi-flowredux.md) | Default when user input gives no clear signal; or user mentions MVI, FlowRedux, state machine, reducer, intent, unidirectional, sealed `State`/`Action`, `dispatch`, `inState`, `onEnter` |
+| `mvvm` | [references/kmp-mvvm.md](references/kmp-mvvm.md) | User mentions MVVM, shared `ViewModel`, `StateFlow`/`uiState`, `viewModelScope`, `collectAsStateWithLifecycle`, KMP-ObservableViewModel, SKIE |
+
+Both modes also follow [references/kmp-expert.md](references/kmp-expert.md) for base KMP/CMP conventions.
+
+**Rules**:
+- **Default is `mvi`** — when the user input contains no explicit or implied architecture signal, the Leader MUST select `mvi`.
+- Record the decision as `design_mode: { value, source: "user_input | default", signals: [] }` in `run_manifest.json` at **MG0**.
+- The Leader passes `design_mode` and the resolved `architecture_reference_path` to every architecture-producing role (planning-gate, prep, module-implementation, module-node-review-fix, global-migration-phase) and to TPA for target-pattern detection.
+- `design_mode` is **fixed for the run**; a mid-run change requires a fresh run, not in-place mutation.
+
 ## Skill Chain (mandatory)
 
 ```text
@@ -108,6 +125,7 @@ android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-
 | [bind.md](bind.md) | Limits, constraints, failures |
 | [dependencies.yaml](dependencies.yaml) | CLI + optional MCP per role |
 | [roles/](roles/) | Role specs |
+| [references/](references/) | Architecture references: `kmp-mvi-flowredux.md` (MVI, default), `kmp-mvvm.md` (MVVM), `kmp-expert.md` (base KMP/CMP) |
 
 ## Handoff Gates
 
@@ -123,6 +141,7 @@ android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-
 ## Shared Rules
 
 - **Skill chain**: `android-project-analyst` **P6** before migrator; `kmp-test-validator` **after** migrator **V0** — both mandatory.
+- **Design mode**: identified from user input at pre-flight, **default `mvi`**; frozen for the run; architecture-producing roles MUST follow the resolved `architecture_reference_path` (`kmp-mvi-flowredux.md` for `mvi`, `kmp-mvvm.md` for `mvvm`).
 - **Target KMP edit mandate**: after analyst P6 understanding, migrator roles MUST create or update production files under `kmp_target_project_path`. Planning-only or artifact-only completion is invalid.
 - **Roles that edit target** (record `changed_files[]` or `integration_changed_files[]`):
   - `migration-prep` — optional scaffold edits (theme, resources, routes, models) when planning allows

package/skills/android-to-kmp-migrator/bind.md

@@ -29,6 +29,7 @@
 - **Skill chain (mandatory)**:
   - **Before migrator**: `android-project-analyst` MUST finish and produce package **P6** (`handoff_gates.P6.ready = true`). If P6 is missing or stale, return `blocked` and dispatch analyst — do not start migrator nodes.
   - **After migrator**: when package **V0** is ready, Leader MUST invoke `kmp-test-validator` (MG17). Migrator completion without validator dispatch is invalid.
+- **Design mode**: at pre-flight the Leader identifies `design_mode` from user input — **default `mvi`** when no architecture signal is present. It is recorded in `run_manifest.json`, **frozen for the run**, and every architecture-producing role MUST follow the resolved `architecture_reference_path` (`references/kmp-mvi-flowredux.md` for `mvi`, `references/kmp-mvvm.md` for `mvvm`). Both modes also follow `references/kmp-expert.md`.
 - **Role schedule**: dispatch only role IDs listed in [SKILL.md](SKILL.md).
 - **Mode discipline**:
   - `module-implementation`: `ui` then `logic` — separate invocations
@@ -44,6 +45,9 @@
 | Failure | Response |
 |---|---|
 | Unknown or invalid role ID | Reject; use role from `SKILL.md` registry |
+| `design_mode` not identified at pre-flight | Default to `mvi`; record `source: default` in `run_manifest.json` |
+| Architecture-producing dispatch missing `design_mode` | Reject; re-dispatch with `design_mode` + `architecture_reference_path` |
+| Code produced against wrong architecture vs `design_mode` | `needs_rerun` owning role with correct reference |
 | `ui` and `logic` combined | Reject invocation |
 | `integrate` and `align` combined | Reject invocation |
 | Verification restoration failed | Rerun `module-implementation` or `migration-prep`; no completion record |

package/skills/android-to-kmp-migrator/output-contract.md

@@ -147,7 +147,7 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 
 | Step | Gate | Required artifacts before next step |
 |---|---|---|
-| `MG0` | Run lock | `run_manifest.json`, `upstream-index/upstream_analyst_index.json` |
+| `MG0` | Run lock | `run_manifest.json` (incl. `design_mode`), `upstream-index/upstream_analyst_index.json` |
 | `MG1` | Workspace init | global `migration_workspace_state.*` |
 | `MG2` | Migration index | `migration_module_inventory.*`, `modules_migration_index.json`, per-module `module_brief.json` |
 | `MG3` | Target baseline | global `target-project-assistant/*` (`mode: global_baseline`) + `target_alignment_revision.*` |
@@ -241,6 +241,30 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 
 ## Key Artifact Content Requirements
 
+### `run_manifest.json` → `design_mode`
+
+Records the presentation architecture pattern, identified from **user input** at pre-flight (Step 0a) and **frozen for the run**. Default is `mvi` when user input gives no clear signal.
+
+```json
+{
+  "design_mode": {
+    "value": "mvi",
+    "source": "default",
+    "signals": [],
+    "architecture_reference_path": "references/kmp-mvi-flowredux.md"
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `value` | `mvi` (default) \| `mvvm` |
+| `source` | `user_input` when a signal was matched; `default` when none |
+| `signals` | matched keywords/phrases from user input (empty when defaulted) |
+| `architecture_reference_path` | `references/kmp-mvi-flowredux.md` for `mvi`, `references/kmp-mvvm.md` for `mvvm` |
+
+The Leader MUST pass `design_mode.value` and `design_mode.architecture_reference_path` into every architecture-producing dispatch (`migration-planning-gate`, `migration-prep`, `module-implementation`, `module-node-review-fix`, `global-migration-phase`) and to `target-project-assistant` for target-pattern detection.
+
 ### `upstream_analyst_index.json`
 
 ```json
@@ -328,7 +352,7 @@ Human/agent-readable synthesis of align mode; includes `entry_point_alignment_re
 
 ## Leader Obligations
 
-1. Verify analyst package `P6` before `MG0` completes.
+1. Verify analyst package `P6` before `MG0` completes; identify `design_mode` from user input (default `mvi`) and write it to `run_manifest.json` at `MG0`, then pass `design_mode` + `architecture_reference_path` into every architecture-producing dispatch.
 2. Dispatch `target-project-assistant` for all target-project questions; other roles MUST reference TPA artifacts instead of re-analyzing target ad hoc.
 3. Ensure each module produces **target KMP edits** via `module-implementation` (and optional `migration-prep` / `module-node-review-fix` `fix`) before writing `module_completion_record.json`.
 4. Write `module_completion_record.json` after each module passes `migration-verification`; include aggregated `target_changed_files[]` for the module.
@@ -353,3 +377,6 @@ Human/agent-readable synthesis of align mode; includes `entry_point_alignment_re
 | Planning complete but `changed_files[]` empty when tasks require edits | `needs_rerun` → `module-implementation` or `migration-prep` |
 | `changed_files` paths outside `kmp_target_project_path` | `blocked` — reject artifact; rerun owning role |
 | `target_files_exist` failed | `needs_rerun` → owning edit role |
+| `design_mode` missing from `run_manifest.json` at MG0 | `blocked`, `reason: missing` — Leader must identify (default `mvi`) before module dispatch |
+| Architecture-producing dispatch missing `design_mode` / `architecture_reference_path` | Reject dispatch; re-dispatch with `design_mode` injected |
+| Implementation/review uses the wrong architecture vs `design_mode` | `needs_rerun` → owning role with correct `architecture_reference_path` |

package/skills/android-to-kmp-migrator/references/kmp-expert.md

@@ -0,0 +1,260 @@
+---
+name: kmp-expert
+description: >
+  Foundational Kotlin Multiplatform / Compose Multiplatform knowledge for KMP/CMP
+  development. Use when working on any KMP/CMP task: project setup, source set
+  hierarchy, expect/actual, Gradle/version-catalog config, choosing the library
+  stack (Ktor, SQLDelight, Room, Koin, serialization), iOS interop (SKIE,
+  KMP-NativeCoroutines), Wasm/web targets, or debugging build/source-set issues.
+  Triggers on Kotlin Multiplatform, KMP, CMP, Compose Multiplatform, commonMain,
+  expect/actual, shared module, iosMain, klib, Kotlin/Native.
+---
+
+# Kotlin Multiplatform / Compose Multiplatform — expert skill
+
+This is the foundational knowledge layer for KMP/CMP work. For presentation
+architecture, see the companion `kmp-mvvm` and `kmp-mvi-flowredux` skills — this
+skill covers everything beneath them: structure, source sets, interop, and the stack.
+
+References:
+- https://kotlinlang.org/docs/multiplatform/multiplatform-discover-project.html
+- https://kotlinlang.org/docs/multiplatform/multiplatform-hierarchy.html
+- https://blog.jetbrains.com/kotlin/2026/05/new-kmp-default-structure/
+
+## KMP vs CMP — know which one you mean
+
+- **KMP (Kotlin Multiplatform)** — shares non-UI logic (networking, persistence,
+  business rules). You build the UI natively per platform (Compose on Android,
+  SwiftUI on iOS). Officially supported by Google for Android/iOS logic sharing.
+- **CMP (Compose Multiplatform)** — a declarative UI framework layered on top of KMP
+  that lets you share the UI too. On iOS it renders via Skia (Skiko), not native widgets.
+
+Decision rule: push as much as possible into `commonMain`. Use KMP-only when you need
+the deepest native iOS fidelity; use CMP when one UI codebase outweighs that.
+
+---
+
+## Compilation targets
+
+| Target | Compiler | Output |
+|---|---|---|
+| Android / JVM backend | Kotlin/JVM | JVM bytecode |
+| iOS / macOS / watchOS / tvOS / Linux / Windows | Kotlin/Native (LLVM) | Native binary / `.framework` |
+| Web | Kotlin/Wasm (or legacy Kotlin/JS) | WebAssembly / JS |
+
+Kotlin/Native produces standalone binaries with no VM, which is how KMP gets native
+performance on iOS.
+
+---
+
+## Project structure (JetBrains 2026 default)
+
+The default structure changed in 2026 to give each module a single responsibility,
+aligning with Android Gradle Plugin 9.0.
+
+```
+project-root/
+├── shared/          ← KMP library: ALL shared code (the only multiplatform module)
+│   └── src/
+│       ├── commonMain/      ← 80–90% of code lives here
+│       ├── androidMain/     ← Android actuals + JVM-only deps
+│       ├── iosMain/         ← iOS actuals (intermediate; see hierarchy below)
+│       ├── desktopMain/     ← JVM desktop actuals
+│       ├── wasmJsMain/      ← web actuals
+│       └── commonTest/
+├── androidApp/      ← thin Android entry point, depends on :shared
+├── iosApp/          ← Xcode project consuming the shared framework
+├── desktopApp/      ← JVM desktop entry point
+└── webApp/          ← Wasm/JS entry point
+```
+
+The old single `composeApp` module that mixed library + app concerns is replaced by a
+clean `shared` library plus separate `*App` modules. Generate new projects at
+`kmp.jetbrains.com`. Reference samples: `KMP-App-Template`, `kotlinconf-app`, RSS Reader.
+
+For large apps, modularize further: feature modules (`:feature-x`) each split into
+`domain`/`data`/`presentation`, plus shared `:core-network`, `:core-db`, `:core-ui`.
+
+---
+
+## Source set hierarchy — the mental model
+
+Source sets form a tree. During compilation for a target, Kotlin combines **all** source
+sets on the path from `commonMain` down to the platform leaf.
+
+```
+                 commonMain
+                /          \
+          appleMain       jvmAndroidShared (you create if needed)
+          /      \         /        \
+     iosMain   macosMain  androidMain  desktopMain
+     /    \
+iosArm64  iosSimulatorArm64
+```
+
+Key facts:
+- `commonMain` compiles to every target; code here may use only multiplatform APIs.
+- **Intermediate source sets** (`iosMain`, `appleMain`, `nativeMain`) share code among a
+  subset of targets. Put `actual` declarations in the intermediate set (e.g. `iosMain`),
+  not in each leaf (`iosArm64Main`, `iosSimulatorArm64Main`).
+- The **default hierarchy template** (modern Kotlin) auto-wires `nativeMain`, `appleMain`,
+  `iosMain`, etc. You rarely need manual `dependsOn` anymore.
+- Kotlin does **not** auto-share a JVM+Android source set. If their deps overlap, create a
+  custom intermediate set and wire it with `dependsOn` (IDE intellisense may complain but
+  it compiles).
+
+---
+
+## expect / actual — the platform contract
+
+The cornerstone mechanism. Declare an `expect` in `commonMain`; provide an `actual` per
+target (or per intermediate source set).
+
+```kotlin
+// commonMain
+expect fun getPlatform(): Platform
+interface Platform { val name: String }
+
+// androidMain
+actual fun getPlatform(): Platform = object : Platform {
+    override val name = "Android ${Build.VERSION.SDK_INT}"
+}
+
+// iosMain
+actual fun getPlatform(): Platform = object : Platform {
+    override val name = UIDevice.currentDevice.systemName()
+}
+```
+
+Three forms:
+1. `expect fun` / `actual fun` — functions (most common)
+2. `expect class` / `actual class` — full classes
+3. **Interface + expect factory** (recommended) — declare an `interface` in common, an
+   `expect fun buildX(): Interface` factory, and platform `actual` factories returning
+   platform impls. This keeps common code free of platform types and is easier to test.
+
+Prefer the interface+factory form over `expect class`; it avoids the strictness of
+matching every member signature across platforms.
+
+When NOT to use expect/actual: if a library already provides a multiplatform API (Ktor,
+SQLDelight, kotlinx-datetime), use it directly in `commonMain` — no expect/actual needed.
+
+---
+
+## The standard 2026 library stack
+
+Verify multiplatform support at `klibs.io` before adding any dependency.
+
+| Concern | Library | Notes |
+|---|---|---|
+| Networking | **Ktor client** | `commonMain` core + per-platform engine (OkHttp/Android, Darwin/iOS, CIO/desktop) |
+| Serialization | **kotlinx.serialization** | apply the plugin to the module that defines `@Serializable` types |
+| Persistence | **SQLDelight** (typed SQL) or **Room KMP** (Google, DAO-style) | SQLDelight for control; Room for Android-team familiarity |
+| Key-value | **multiplatform-settings** or **DataStore** | small prefs |
+| DI | **Koin** | no codegen → fast multiplatform compile; `koin-compose-viewmodel` for CMP |
+| Dates/time | **kotlinx-datetime** | multiplatform `Instant`, `LocalDate`, time zones |
+| Coroutines | **kotlinx-coroutines-core** | the concurrency backbone |
+| Image loading | **Coil 3** | multiplatform |
+| Navigation | Navigation-Compose (KMP), **Voyager**, or **Decompose** | Decompose pairs well with KMP lifecycle |
+| Testing | **kotlinx-coroutines-test** + **Turbine** | flow testing |
+
+---
+
+## Gradle configuration (modern, terse)
+
+```kotlin
+// shared/build.gradle.kts
+plugins {
+    kotlin("multiplatform")
+    kotlin("plugin.serialization")
+    id("com.android.library")
+}
+
+kotlin {
+    androidTarget()
+    iosX64(); iosArm64(); iosSimulatorArm64()
+    jvm("desktop")
+    wasmJs { browser() }
+
+    // Default hierarchy template auto-creates iosMain/appleMain/nativeMain.
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.ktor.client.core)
+            implementation(libs.kotlinx.serialization.json)
+            implementation(libs.koin.core)
+            implementation(libs.kotlinx.coroutines.core)
+        }
+        androidMain.dependencies { implementation(libs.ktor.client.okhttp) }
+        iosMain.dependencies     { implementation(libs.ktor.client.darwin) }
+        getByName("desktopMain").dependencies { implementation(libs.ktor.client.cio) }
+        commonTest.dependencies  {
+            implementation(libs.turbine)
+            implementation(libs.kotlinx.coroutines.test)
+        }
+    }
+}
+```
+
+Use a `gradle/libs.versions.toml` version catalog for all dependency coordinates —
+it is the standard for keeping versions consistent across modules.
+
+---
+
+## iOS interop — the hard part
+
+Kotlin/Native exports through an Objective-C bridge, which is lossy: sealed classes lose
+exhaustiveness, `Int?` becomes a boxed `KotlinInt`, and `suspend` functions become
+completion-handler callbacks. Mitigations:
+
+| Tool | What it fixes |
+|---|---|
+| **SKIE** | Maps Kotlin `Flow` → Swift `AsyncSequence`, sealed classes → Swift enums with associated values, default args. Easy setup, less verbose. |
+| **KMP-NativeCoroutines** | Maps `suspend`/`Flow` to Swift `async/await`, Combine, or RxSwift with proper cancellation. The more battle-tested option. |
+| **KMP-ObservableViewModel** | Lets SwiftUI observe Kotlin ViewModels and handles the iOS lifecycle/store-owner boilerplate. |
+| **Swift Export (emerging)** | Direct Kotlin→Swift modules (suspend→async/await, sealed→enums) without the ObjC layer. Still experimental — don't build production architecture on it yet. |
+
+Practical rules:
+- Reduce the exported surface: mark internal code `internal`/`private` and enable
+  `explicitApi()` so you don't export everything by default.
+- Annotate the flows/suspend functions you expose with the chosen tool's annotation
+  (`@NativeCoroutines`, `@NativeCoroutinesState`).
+- iOS engineers should never see `KotlinInt` or completion handlers — that's a sign your
+  interop layer is missing.
+
+---
+
+## Common gotchas
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `@Serializable` compiles but crashes at runtime | serialization plugin not on the module defining the type | Apply `kotlin("plugin.serialization")` to that module |
+| IDE shows red but it compiles | IntelliSense lagging on intermediate source sets | Sync Gradle; the build is the source of truth |
+| Can't share code across JVM + Android | Kotlin doesn't auto-create that intermediate set | Create a custom source set with `dependsOn` |
+| iOS sees opaque classes, no exhaustive switch | Raw ObjC bridge without SKIE | Add SKIE or KMP-NativeCoroutines |
+| Slow Kotlin/Native builds | Native compilation is inherently slower than JVM | Use `embedAndSign`/`SKIE` caching; iterate on Android/desktop, verify on iOS less often |
+| `expect class` won't compile — member mismatch | strict signature matching across platforms | Switch to interface + `expect` factory function |
+| Coroutine on iOS never cancels | exposed raw `suspend` without interop annotation | Annotate with `@NativeCoroutines` for proper cancellation |
+| Android-only API leaked into commonMain | wrote `android.*` import in common code | Move it behind expect/actual or an interface |
+
+---
+
+## Build/run quick reference
+
+```bash
+./gradlew :shared:build                 # compile the shared library, all targets
+./gradlew :androidApp:installDebug      # build + install Android app
+./gradlew :desktopApp:run               # run desktop (JVM) app
+./gradlew :shared:iosSimulatorArm64Test # run iOS tests on simulator
+# iOS app itself is built/run from Xcode (iosApp project) consuming the framework
+```
+
+---
+
+## When advising on KMP/CMP work
+
+1. Default to putting code in `commonMain`; only drop to platform source sets when an API
+   genuinely differs. Reach for expect/actual last, libraries first.
+2. Check `klibs.io` for multiplatform support before suggesting any dependency.
+3. For UI: ask whether they want shared UI (CMP) or native UI (KMP-only) before scaffolding.
+4. For presentation logic, defer to the `kmp-mvvm` or `kmp-mvi-flowredux` skill.
+5. Always consider the iOS interop cost of anything exposed across the Swift boundary.

package/skills/android-to-kmp-migrator/references/kmp-mvi-flowredux.md

@@ -0,0 +1,344 @@
+---
+name: kmp-mvi-flowredux
+description: >
+  KMP/CMP MVI architecture using FlowRedux state machines. Use when building or
+  reviewing Kotlin Multiplatform features that need MVI pattern: state machines,
+  sealed State/Action classes, unidirectional data flow, Compose Multiplatform UI
+  wiring, or when the user mentions FlowRedux, MVI, state machine, inState, onEnter,
+  dispatch, or sealed interface State.
+---
+
+# KMP MVI with FlowRedux — architecture skill
+
+Reference: https://freeletics.github.io/FlowRedux/
+
+## Core concepts
+
+MVI (Model-View-Intent) enforces **unidirectional data flow**:
+
+```
+Action (Intent) ──► StateMachine ──► State ──► UI
+       ▲                                        │
+       └────────────────────────────────────────┘
+                      dispatch()
+```
+
+FlowRedux models this as an explicit **state machine** with a Coroutines DSL:
+- `State` — sealed interface; each subtype is a discrete screen state
+- `Action` — sealed interface; every user gesture or external event
+- `FlowReduxStateMachineFactory` — holds the `spec { }` DSL and produces instances
+- `FlowReduxStateMachine` — public API: `state: Flow<State>` + `suspend dispatch(action)`
+
+---
+
+## Architecture layers
+
+```
+:shared/commonMain
+  ├── feature/
+  │   ├── model/
+  │   │   ├── FeatureState.kt        ← sealed interface State + subtypes
+  │   │   └── FeatureAction.kt       ← sealed interface Action + subtypes
+  │   ├── statemachine/
+  │   │   └── FeatureStateMachineFactory.kt  ← FlowReduxStateMachineFactory
+  │   └── domain/
+  │       └── FeatureRepository.kt   ← interface; expect/actual for platform impl
+  └── di/
+      └── FeatureModule.kt           ← Koin module wiring factory + repo
+
+:composeApp/commonMain
+  └── feature/
+      ├── FeatureScreen.kt           ← @Composable, uses produceStateMachine()
+      └── FeatureViewModel.kt        ← optional: ViewModel wrapper for lifecycle
+```
+
+**Rule:** All state machine logic lives in `:shared/commonMain`. The UI layer
+(`:composeApp`) only renders state and dispatches actions — zero business logic.
+
+---
+
+## Coding guidance
+
+### 1. Define State and Action as sealed interfaces
+
+```kotlin
+// shared/commonMain/.../model/ItemListState.kt
+sealed interface ItemListState {
+    data object Loading : ItemListState
+    data class ShowContent(val items: List<Item>) : ItemListState
+    data class Error(val message: String, val countdown: Int) : ItemListState
+}
+
+// shared/commonMain/.../model/ItemListAction.kt
+sealed interface ItemListAction {
+    data object RetryLoading : ItemListAction
+    data class ToggleFavorite(val itemId: Int) : ItemListAction
+}
+```
+
+Rules:
+- `State` subtypes are `data object` (no fields) or `data class` (immutable fields)
+- Never put UI logic inside a `State` — it is plain data
+- `Action` subtypes carry only the payload the handler needs — nothing else
+
+### 2. Write the StateMachineFactory in commonMain
+
+```kotlin
+// shared/commonMain/.../statemachine/ItemListStateMachineFactory.kt
+class ItemListStateMachineFactory(
+    private val repository: ItemRepository
+) : FlowReduxStateMachineFactory<ItemListState, ItemListAction>() {
+
+    init {
+        initializeWith { Loading }
+
+        spec {
+            inState<Loading> {
+                onEnter { state ->
+                    try {
+                        val items = repository.loadItems()
+                        state.override { ShowContent(items) }
+                    } catch (t: Throwable) {
+                        state.override { Error(t.message ?: "Unknown error", countdown = 3) }
+                    }
+                }
+            }
+
+            inState<Error> {
+                on<RetryLoading> { _, state ->
+                    state.override { Loading }
+                }
+
+                collectWhileInState(timerEverySecond()) { _, state ->
+                    val next = state.snapshot.countdown - 1
+                    if (next <= 0) state.override { Loading }
+                    else state.mutate { copy(countdown = next) }
+                }
+            }
+
+            inState<ShowContent> {
+                on<ToggleFavorite>(executionPolicy = ExecutionPolicy.Unordered) { action, state ->
+                    // delegate to child state machine — see composing section
+                    state.mutate { copy(items = items.map { item ->
+                        if (item.id == action.itemId) item.copy(toggling = true) else item
+                    }) }
+                }
+            }
+        }
+    }
+}
+```
+
+Rules:
+- One factory per feature/screen — not one global machine
+- `initializeWith { }` always first in `init`
+- Extract large handlers into `private suspend fun` for readability and unit-testability
+- Never call `state.override` or `state.mutate` after the function returns — these are the only mutation points
+
+### 3. DSL blocks reference
+
+| Block | Triggers when | Typical use |
+|---|---|---|
+| `onEnter { }` | State is entered | Load data, start timers |
+| `on<Action> { }` | Action arrives while in this state | User interactions |
+| `collectWhileInState(flow) { }` | Flow emits while in this state | Countdown, realtime updates |
+| `onActionEffect<Action> { }` | Like `on<>` but does NOT transition state | Logging, analytics side-effects |
+| `condition { }` | Wraps sub-blocks with a predicate | Feature flags, conditional handlers |
+| `untilIdentityChanged { }` | Re-enters block when identity field changes | Pagination, refresh on id change |
+
+### 4. ExecutionPolicy — choose deliberately
+
+```kotlin
+// Default: CancelPrevious — cancel in-flight handler when same action fires again
+on<SearchQueryChanged> { action, state -> ... }
+
+// Unordered — run in parallel, no order guarantee; use for independent async ops
+on<ToggleFavorite>(executionPolicy = ExecutionPolicy.Unordered) { ... }
+
+// Ordered — sequential; use when order matters and you must not cancel
+on<PageLoad>(executionPolicy = ExecutionPolicy.Ordered) { ... }
+
+// Throttled — ignore re-triggers within duration; use for debounce-like behaviour
+on<ButtonClick>(executionPolicy = ExecutionPolicy.Throttled(500.milliseconds)) { ... }
+```
+
+### 5. Compose Multiplatform UI wiring
+
+```kotlin
+// composeApp/commonMain/.../FeatureScreen.kt
+@Composable
+fun ItemListScreen(factory: ItemListStateMachineFactory) {
+    val stateMachine = factory.produceStateMachine()   // FlowRedux compose extension
+    val state by stateMachine.state.collectAsState()   // or use stateMachine.state.value
+
+    when (val s = state) {
+        is Loading     -> LoadingIndicator()
+        is ShowContent -> ContentList(s.items, onToggle = {
+            stateMachine.dispatch(ToggleFavorite(it))  // dispatch is non-suspending in compose ext
+        })
+        is Error       -> ErrorView(s.message, s.countdown, onRetry = {
+            stateMachine.dispatch(RetryLoading)
+        })
+    }
+}
+```
+
+For Android ViewModel lifecycle:
+
+```kotlin
+class ItemListViewModel @Inject constructor(
+    private val factory: ItemListStateMachineFactory
+) : ViewModel() {
+    private val stateMachine = factory.shareIn(viewModelScope)
+    val state: StateFlow<ItemListState> = stateMachine.state
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5000), Loading)
+
+    fun dispatch(action: ItemListAction) {
+        viewModelScope.launch { stateMachine.dispatch(action) }
+    }
+}
+```
+
+### 6. Composing state machines (hierarchical)
+
+Delegate a sub-problem to a child state machine rather than bloating the parent spec:
+
+```kotlin
+inState<ShowContent> {
+    onActionStartStateMachine(
+        stateMachineFactoryBuilder = { action: ToggleFavorite ->
+            FavoriteStatusStateMachineFactory(
+                itemId = action.itemId,
+                httpClient = httpClient
+            )
+        }
+    ) { favoriteStatus: FavoriteStatus ->
+        // merge child state into parent state
+        mutate { copy(items = items.updateFavoriteStatus(favoriteStatus)) }
+    }
+}
+```
+
+Use `onEnterStartStateMachine()` when you want a child machine to start on state entry
+rather than on an explicit action.
+
+### 7. Effects (side-effects without state transition)
+
+```kotlin
+inState<ShowContent> {
+    onActionEffect<ToggleFavorite> { action, stateSnapshot ->
+        analytics.track("toggle_favorite", mapOf("id" to action.itemId))
+        // cannot mutate state from an effect block
+    }
+}
+```
+
+Use `*Effect` variants whenever you need to react to an action or event but must not
+change state (navigation events, analytics, logging).
+
+---
+
+## Project structure checklist
+
+```
+:shared
+  commonMain
+    └── feature/itemlist/
+        ├── model/
+        │   ├── ItemListState.kt          ✓ sealed interface, data classes, immutable
+        │   └── ItemListAction.kt         ✓ sealed interface
+        ├── statemachine/
+        │   ├── ItemListStateMachineFactory.kt  ✓ extends FlowReduxStateMachineFactory
+        │   └── FavoriteStatusStateMachineFactory.kt  ✓ child machine
+        ├── domain/
+        │   └── ItemRepository.kt         ✓ interface only
+        └── data/
+            └── ItemRepositoryImpl.kt     ✓ actual implementation (or expect/actual)
+
+:composeApp
+  commonMain
+    └── feature/itemlist/
+        ├── ItemListScreen.kt             ✓ @Composable, pure render + dispatch
+        └── ItemListViewModel.kt          ✓ only if AndroidX lifecycle needed
+```
+
+---
+
+## Testing guidance
+
+Prefer **functional integration tests** with Turbine over unit tests per handler.
+
+```kotlin
+// Use runTest + Turbine for the full state machine
+@Test
+fun `loading transitions to ShowContent on success`() = runTest {
+    val factory = ItemListStateMachineFactory(FakeItemRepository(items = sampleItems))
+    val sm = factory.shareIn(backgroundScope)
+
+    sm.state.test {
+        assertEquals(Loading, awaitItem())
+        assertEquals(ShowContent(sampleItems), awaitItem())
+    }
+}
+
+// Override initial state to test mid-flow without replaying all transitions
+@Test
+fun `retry from Error transitions to Loading`() = runTest {
+    val factory = ItemListStateMachineFactory(FakeItemRepository())
+    factory.initializeWith { Error("oops", countdown = 3) }
+    val sm = factory.shareIn(backgroundScope)
+
+    sm.state.test {
+        assertEquals(Error("oops", 3), awaitItem())
+        sm.dispatch(RetryLoading)
+        assertEquals(Loading, awaitItem())
+    }
+}
+```
+
+For **unit testing handlers**, extract them to `private suspend fun` and test with
+`ChangeableState` + `changedState.reduce(snapshot)` directly.
+
+---
+
+## Gradle dependencies
+
+```kotlin
+// shared/build.gradle.kts
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            // FlowRedux core (KMP)
+            implementation("com.freeletics.flowredux:flowredux:2.0.1")
+            // Coroutines
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+        }
+    }
+}
+
+// composeApp/build.gradle.kts
+commonMain.dependencies {
+    // FlowRedux Compose extensions (produceStateMachine, dispatch)
+    implementation("com.freeletics.flowredux:compose:2.0.1")
+}
+
+// Testing
+commonTest.dependencies {
+    implementation("app.cash.turbine:turbine:1.1.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
+}
+```
+
+---
+
+## Anti-patterns to avoid
+
+| Anti-pattern | Fix |
+|---|---|
+| Business logic inside `@Composable` | Move to `inState { }` handlers |
+| Mutable state inside `State` data class | All fields must be `val`; use `state.mutate { copy(...) }` |
+| One giant state machine for the whole app | One factory per screen/feature |
+| `state.override` called after a `return` | Override is the last expression in the lambda |
+| Catching all `Throwable` silently | Log or encode the error into an `Error` state subtype |
+| Skipping `ExecutionPolicy` on concurrent actions | Explicitly choose `Unordered` or `Ordered` where needed |
+| Navigation logic inside state | Use `onActionEffect` + a navigation callback; state stays pure data |

package/skills/android-to-kmp-migrator/references/kmp-mvvm.md

@@ -0,0 +1,328 @@
+---
+name: kmp-mvvm
+description: >
+  KMP/CMP MVVM architecture with shared ViewModels. Use when building or reviewing
+  Kotlin Multiplatform features that follow the MVVM pattern: ViewModel + StateFlow,
+  UI state classes, state hoisting, collectAsStateWithLifecycle, Koin viewModel
+  injection, or bridging shared ViewModels to SwiftUI on iOS. Triggers on MVVM,
+  ViewModel, StateFlow, uiState, viewModelScope, KMP-ObservableViewModel, SKIE.
+---
+
+# KMP MVVM with shared ViewModels — architecture skill
+
+References:
+- https://kotlinlang.org/docs/multiplatform/compose-viewmodel.html
+- https://touchlab.co/kmp-view-models
+
+## Core concepts
+
+MVVM separates concerns into three groups:
+
+```
+        observe (StateFlow)              user events (fun calls)
+View ◄───────────────────────── ViewModel ◄──────────────────── View
+ │                                  │
+ │                                  ▼
+ │                          Model (UseCase / Repository)
+ └─ renders UiState                 │
+                                    ▼
+                            data / network / cache
+```
+
+- **Model** — domain + data layer (UseCases, Repositories) in `commonMain`
+- **ViewModel** — holds and exposes immutable `UiState` as `StateFlow`, handles events
+- **View** — Compose Multiplatform (shared) or native (SwiftUI/Compose), renders state only
+
+MVVM vs MVI: MVVM exposes a single immutable `UiState` and *public methods* for events,
+rather than dispatching `Action` objects through a reducer. Use MVVM when the team is
+Android/Compose-native and the per-screen state is simple; reach for MVI/FlowRedux when
+state transitions are complex enough to warrant an explicit state machine.
+
+---
+
+## Architecture layers
+
+```
+:shared/commonMain
+  ├── feature/order/
+  │   ├── presentation/
+  │   │   ├── OrderUiState.kt        ← single immutable data class (the "Model" the View sees)
+  │   │   └── OrderViewModel.kt      ← extends ViewModel, exposes StateFlow<OrderUiState>
+  │   ├── domain/
+  │   │   ├── OrderRepository.kt     ← interface
+  │   │   └── PlaceOrderUseCase.kt   ← business logic, no Android deps
+  │   └── data/
+  │       └── OrderRepositoryImpl.kt ← actual impl (Ktor/SQLDelight)
+  └── di/
+      └── OrderModule.kt             ← Koin module: viewModelOf(::OrderViewModel)
+
+:composeApp/commonMain
+  └── feature/order/
+      └── OrderScreen.kt             ← @Composable, koinViewModel() + collectAsStateWithLifecycle()
+
+iosApp (Swift)                        ← observes ViewModel via KMP-ObservableViewModel
+```
+
+**Rule:** ViewModel, UiState, and all logic live in `:shared/commonMain`. The View only
+collects state and calls ViewModel methods.
+
+---
+
+## Choosing the ViewModel base class
+
+There are three viable approaches. Pick one per project and stay consistent.
+
+| Approach | commonMain dependency | iOS story | When to use |
+|---|---|---|---|
+| **AndroidX `lifecycle-viewmodel` (multiplatform)** | `androidx.lifecycle:lifecycle-viewmodel:2.8+` | Manual lifecycle on iOS; brings `viewModelScope` baggage | CMP-first apps where iOS UI is also Compose |
+| **KMP-ObservableViewModel** (rickclephas) | `com.rickclephas.kmp:kmp-observableviewmodel-core` | First-class: SwiftUI observes directly, handles store-owner boilerplate | **Recommended** when iOS uses SwiftUI; this is the official Kotlin-docs recommendation |
+| **Pure Kotlin ViewModel** (your own `interface`/base) | none | Explicit Swift observer wrapper you write | Maximum control, zero androidx in commonMain |
+
+The official Kotlin documentation recommends **KMP-ObservableViewModel** for SwiftUI
+because there is no built-in `ViewModelStoreOwner` on iOS — the library ties the
+ViewModel lifecycle to the SwiftUI view automatically.
+
+---
+
+## Coding guidance
+
+### 1. Model UiState as a single immutable data class
+
+```kotlin
+// shared/commonMain/.../presentation/OrderUiState.kt
+data class OrderUiState(
+    val quantity: Int = 1,
+    val items: List<OrderItem> = emptyList(),
+    val isLoading: Boolean = false,
+    val errorMessage: String? = null,
+)
+```
+
+Rules:
+- One `UiState` per screen — never expose multiple loose `StateFlow`s for one screen
+- All fields `val`, with sensible defaults
+- Represent loading/error as fields (`isLoading`, `errorMessage`), or use a sealed
+  `UiState` if states are mutually exclusive enough to warrant it
+- Keep it free of framework types (no `Composable`, no `Color`, no `Painter`)
+
+### 2. ViewModel exposes StateFlow, never MutableStateFlow
+
+```kotlin
+// shared/commonMain/.../presentation/OrderViewModel.kt
+import com.rickclephas.kmp.observableviewmodel.ViewModel
+import com.rickclephas.kmp.observableviewmodel.MutableStateFlow
+import com.rickclephas.kmp.observableviewmodel.stateIn
+import com.rickclephas.kmp.nativecoroutines.NativeCoroutinesState
+
+class OrderViewModel(
+    private val placeOrder: PlaceOrderUseCase,
+    private val repository: OrderRepository,
+) : ViewModel() {
+
+    private val _uiState = MutableStateFlow(viewModelScope, OrderUiState())
+
+    @NativeCoroutinesState                       // exposes the flow cleanly to Swift
+    val uiState: StateFlow<OrderUiState> = _uiState.asStateFlow()
+
+    init { loadItems() }
+
+    fun setQuantity(n: Int) {
+        _uiState.update { it.copy(quantity = n) }
+    }
+
+    fun submit() {
+        viewModelScope.coroutineScope.launch {
+            _uiState.update { it.copy(isLoading = true, errorMessage = null) }
+            runCatching { placeOrder(_uiState.value.quantity) }
+                .onSuccess { _uiState.update { s -> s.copy(isLoading = false) } }
+                .onFailure { t -> _uiState.update { s -> s.copy(isLoading = false, errorMessage = t.message) } }
+        }
+    }
+
+    private fun loadItems() { /* launch in viewModelScope, update _uiState */ }
+}
+```
+
+Rules:
+- `_uiState` is private `MutableStateFlow`; expose read-only `StateFlow` via `asStateFlow()`
+- Always update via `update { copy(...) }` — atomic, avoids race conditions
+- Launch coroutines in `viewModelScope` so they cancel when the ViewModel clears
+- Annotate the public flow with `@NativeCoroutinesState` for clean Swift interop
+- Never expose `suspend` functions to the View; the View calls plain `fun`, the VM launches
+
+### 3. Compose Multiplatform View — state hoisting + lifecycle-aware collection
+
+```kotlin
+// composeApp/commonMain/.../OrderScreen.kt
+@Composable
+fun OrderScreen(viewModel: OrderViewModel = koinViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+
+    OrderContent(
+        state = uiState,
+        onQuantityChange = viewModel::setQuantity,
+        onSubmit = viewModel::submit,
+    )
+}
+
+// Stateless, hoisted — fully previewable and testable
+@Composable
+private fun OrderContent(
+    state: OrderUiState,
+    onQuantityChange: (Int) -> Unit,
+    onSubmit: () -> Unit,
+) {
+    Column {
+        if (state.isLoading) LinearProgressIndicator()
+        QuantityStepper(state.quantity, onQuantityChange)
+        state.errorMessage?.let { Text(it, color = MaterialTheme.colorScheme.error) }
+        Button(onClick = onSubmit, enabled = !state.isLoading) { Text("Place order") }
+    }
+}
+```
+
+Rules:
+- Split into a stateful screen (`koinViewModel()` + collect) and a stateless content
+  composable that takes `state` + lambdas — this is **state hoisting**
+- Use `collectAsStateWithLifecycle()` (not bare `collectAsState()`) so collection pauses
+  when the UI is not visible
+- Pass method references (`viewModel::setQuantity`), not the whole ViewModel, into content
+- The stateless content composable has zero ViewModel dependency → trivially previewable
+
+### 4. Dependency injection with Koin
+
+```kotlin
+// shared/commonMain/.../di/OrderModule.kt
+val orderModule = module {
+    singleOf(::OrderRepositoryImpl) bind OrderRepository::class
+    factoryOf(::PlaceOrderUseCase)
+    viewModelOf(::OrderViewModel)        // koin-compose-viewmodel
+}
+```
+
+Compose retrieves it with `koinViewModel()` (from `koin-compose-viewmodel`), which
+scopes the ViewModel to the navigation entry / composition correctly on all platforms.
+
+### 5. iOS bridge (SwiftUI)
+
+With KMP-ObservableViewModel + `@NativeCoroutinesState`, SwiftUI observes directly:
+
+```swift
+struct OrderView: View {
+    @StateViewModel var viewModel = OrderViewModel(placeOrder: ..., repository: ...)
+
+    var body: some View {
+        VStack {
+            if viewModel.uiState.isLoading { ProgressView() }
+            Stepper("Qty: \(viewModel.uiState.quantity)",
+                    value: Binding(get: { Int(viewModel.uiState.quantity) },
+                                   set: { viewModel.setQuantity(n: Int32($0)) }))
+            Button("Place order") { viewModel.submit() }
+        }
+    }
+}
+```
+
+If you instead use AndroidX ViewModel + SKIE, SKIE maps `StateFlow` to a Swift
+`AsyncSequence`/`@Observable` and you bridge it with an observer wrapper.
+
+---
+
+## Project structure checklist
+
+```
+:shared
+  commonMain
+    └── feature/order/
+        ├── presentation/
+        │   ├── OrderUiState.kt          ✓ single immutable data class
+        │   └── OrderViewModel.kt        ✓ private Mutable, public StateFlow
+        ├── domain/
+        │   ├── OrderRepository.kt       ✓ interface
+        │   └── PlaceOrderUseCase.kt     ✓ pure logic, no androidx
+        ├── data/
+        │   └── OrderRepositoryImpl.kt   ✓ Ktor / SQLDelight
+        └── di/OrderModule.kt            ✓ viewModelOf(::OrderViewModel)
+
+:composeApp
+  commonMain
+    └── feature/order/OrderScreen.kt     ✓ stateful screen + stateless content
+
+iosApp                                   ✓ @StateViewModel, observes uiState
+```
+
+---
+
+## Testing guidance
+
+The ViewModel is a plain class — test it with `runTest` + Turbine, injecting fakes.
+
+```kotlin
+@Test
+fun `submit sets loading then clears on success`() = runTest {
+    val vm = OrderViewModel(
+        placeOrder = FakePlaceOrderUseCase(succeeds = true),
+        repository = FakeOrderRepository(),
+    )
+    vm.uiState.test {
+        assertEquals(OrderUiState(), awaitItem())           // initial
+        vm.setQuantity(3)
+        assertEquals(3, awaitItem().quantity)
+        vm.submit()
+        assertTrue(awaitItem().isLoading)                   // loading on
+        assertFalse(awaitItem().isLoading)                  // cleared after success
+    }
+}
+```
+
+The stateless content composable is tested separately with Compose UI tests / screenshot
+tests — it takes a `UiState` directly, so no ViewModel is needed.
+
+---
+
+## Gradle dependencies
+
+```kotlin
+// shared/build.gradle.kts
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            // Recommended iOS-friendly ViewModel (official Kotlin docs)
+            implementation("com.rickclephas.kmp:kmp-observableviewmodel-core:1.0.0-BETA-13")
+            // OR the AndroidX multiplatform ViewModel
+            // implementation("org.jetbrains.androidx.lifecycle:lifecycle-viewmodel:2.8.4")
+
+            implementation("io.insert-koin:koin-core:4.0.0")
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
+        }
+        commonTest.dependencies {
+            implementation("app.cash.turbine:turbine:1.1.0")
+            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
+        }
+    }
+}
+
+// composeApp/build.gradle.kts
+commonMain.dependencies {
+    implementation("io.insert-koin:koin-compose-viewmodel:4.0.0")  // koinViewModel()
+    implementation("org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose:2.8.4")
+}
+```
+
+For SwiftUI interop, add the KMP-ObservableViewModel Swift package, or KMP-NativeCoroutines / SKIE.
+
+---
+
+## Anti-patterns to avoid
+
+| Anti-pattern | Fix |
+|---|---|
+| Exposing `MutableStateFlow` publicly | Expose read-only `StateFlow` via `asStateFlow()` |
+| Multiple loose `StateFlow`s for one screen | Combine into one `UiState` data class |
+| Business logic inside the `@Composable` | Move to the ViewModel; the View only renders + calls methods |
+| Passing the whole ViewModel into child composables | Hoist state: pass `UiState` + lambdas |
+| `collectAsState()` instead of `collectAsStateWithLifecycle()` | Use the lifecycle-aware variant to pause off-screen collection |
+| `suspend` functions exposed to the View | Keep them internal; the VM launches in `viewModelScope` |
+| Framework types (`Color`, `Painter`) inside `UiState` | Keep `UiState` platform-agnostic data only |
+| AndroidX ViewModel in commonMain when targeting SwiftUI | Prefer KMP-ObservableViewModel or a pure-Kotlin base |
+| Mutating state with `.value = .value.copy()` under concurrency | Use `update { copy(...) }` for atomic updates |

package/skills/android-to-kmp-migrator/roles/global-migration-phase.md

@@ -49,7 +49,7 @@ You are the `global-migration-phase` node subagent. Your job is **target KMP pro
 - Integrate mode: no edits outside `kmp_target_project_path` or outside approved integration glue paths from TPA `integration_constraints`.
 
 **Mandatory**:
-- Integrate: validate `kmp_target_project_path`, package `M4`, all module representations, analyst cross-module globals, and `target_alignment_revision.json` before editing.
+- Integrate: validate `kmp_target_project_path`, `design_mode` + `architecture_reference_path`, package `M4`, all module representations, analyst cross-module globals, and `target_alignment_revision.json` before editing. Cross-module glue, DI, and entry wiring MUST follow the run's `design_mode` (default `mvi`: state-machine wiring per `references/kmp-mvi-flowredux.md`; `mvvm`: `ViewModel`/Koin wiring per `references/kmp-mvvm.md`) and `references/kmp-expert.md` base KMP conventions — shared glue/nav/DI in `commonMain`, platform entry wrappers in `androidMain`/`iosMain`, `expect`/`actual` for platform launch hooks.
 - Integrate: `output_dir = <global_dir>/node-results/global-migration-phase/integrate`
 - Align: primary output under `<global_dir>/node-results/global-migration-phase/align`; alignment report under `report_dir`
 - Include `mode` and `kmp_target_project_path` in JSON return payload.
@@ -190,6 +190,11 @@ Read-only verification after integrate. For each Legacy Android entry in analyst
 ```text
 ROLE: global-migration-phase node in android-to-kmp-migrator. Modes: integrate | align. NEVER combine.
 
+DESIGN MODE: glue/DI/entry wiring follows design_mode (default mvi → references/kmp-mvi-flowredux.md
+state-machine wiring; mvvm → references/kmp-mvvm.md ViewModel/Koin wiring) and references/kmp-expert.md
+base KMP conventions (shared glue/nav/DI in commonMain, platform entry wrappers + expect/actual launch
+hooks in androidMain/iosMain). Do NOT mix patterns.
+
 INTEGRATE — EDIT THE TARGET KMP PROJECT:
 - Wire cross-module UI transitions, control logic handoffs, and data calls inside kmp_target_project_path.
 - Wire entry points: Android launcher/Application/root nav/deep links → KMP app shell (entry_point_wiring[]).
@@ -208,7 +213,7 @@ CONTROL:
   analyst cross-module globals, target_alignment_revision before editing.
 - Align: consume global_system_integration output; inspect target files without modifying them.
 
-INPUTS: mode, kmp_target_project_path, analyst cross_module_architecture_path,
+INPUTS: mode, design_mode, architecture_reference_path, kmp_target_project_path, analyst cross_module_architecture_path,
 cross_module_data_logic_path, module_migration_representation paths,
 presentation_resource entry_points paths (per module + launcher module),
 target_alignment_revision_path (entry_point_anchors[]), global_system_integration path (align mode),

package/skills/android-to-kmp-migrator/roles/migration-planning-gate.md

@@ -9,7 +9,7 @@ You are the `migration-planning-gate` node subagent. You merge **migration analy
 ## Success Criteria
 
 - `migration_planning_gate.json` and `migration_planning_gate.md` written under `output_dir`.
-- **Planning section**: SPEC/raw-source deltas, source-to-target map (from TPA anchors), reuse inventory, ordered `implementation_tasks`.
+- **Planning section**: SPEC/raw-source deltas, source-to-target map (from TPA anchors), reuse inventory, ordered `implementation_tasks`. The source-to-target map and tasks MUST follow the run's `design_mode` (default `mvi`) layout from `architecture_reference_path` — `mvi` (`references/kmp-mvi-flowredux.md`): `model/` (sealed `State`/`Action`), `statemachine/` (`FlowReduxStateMachineFactory`), `domain/`; `mvvm` (`references/kmp-mvvm.md`): `presentation/` (`ViewModel` + `UiState`), `domain/`, `data/`. Both modes target a KMP project per `references/kmp-expert.md` base conventions — map source to KMP source sets (`commonMain` first, `androidMain`/`iosMain` only for platform actuals) and the 2026 `shared` + `*App` module layout.
 - **Dependency/platform section**: capability map, minimal-change dependency decisions, platform boundaries, `ready_for_implementation` or `blocked`.
 - No feature UI/logic implementation; build-config changes only when gate justifies them.
 
@@ -64,9 +64,13 @@ See [output-contract.md](../output-contract.md). Artifact basename: `migration_p
 ROLE: migration-planning-gate node. Merge planning + dependency/platform gate in ONE invocation.
 
 PLANNING: SPEC deltas, source-to-target map from TPA anchors, ordered tasks. No target re-survey.
+Layout follows design_mode (default mvi): mvi → model/statemachine/domain (references/kmp-mvi-flowredux.md);
+mvvm → presentation(ViewModel+UiState)/domain/data (references/kmp-mvvm.md).
+Both target a KMP project per references/kmp-expert.md base conventions: prefer commonMain, drop to
+androidMain/iosMain only for platform actuals, follow the shared + *App module layout.
 GATE: capability map, minimal-change deps, platform boundaries. ready_for_implementation or blocked.
 
-INPUTS: migration_module_id, module_scope, module_brief_path, target_module_anchors_path,
+INPUTS: design_mode, architecture_reference_path, migration_module_id, module_scope, module_brief_path, target_module_anchors_path,
 target_alignment_revision_path, upstream module_representation, SPEC paths, target path,
 allowed_files, allowed_source_sets, output_dir.
 

package/skills/android-to-kmp-migrator/roles/migration-prep.md

@@ -10,7 +10,7 @@ You are the `migration-prep` node subagent. You merge **presentation integration
 
 - `migration_prep.json` and `migration_prep.md` written under `output_dir`.
 - **Presentation section**: token mappings, resource mapping, route mapping, UI handoff, presentation gaps.
-- **State/data section**: state mappings, model mappings, API contract expectations, logic handoff.
+- **State/data section**: state mappings, model mappings, API contract expectations, logic handoff. State holder expectations MUST follow the run's `design_mode` (default `mvi`): `mvi` → sealed `State`/`Action` + state-machine handoff (`references/kmp-mvi-flowredux.md`); `mvvm` → immutable `UiState` + `ViewModel` event-method handoff (`references/kmp-mvvm.md`). All scaffold and contracts target a KMP project per `references/kmp-expert.md` base conventions — place shared tokens/resources/models/routes in `commonMain`, reserve `androidMain`/`iosMain` for platform actuals, and prefer the multiplatform stack (Ktor, kotlinx-serialization, kotlinx-datetime) over Android-only types.
 - Changed files recorded; cross-module impacts noted.
 - No full UI layouts or repository/API behavior.
 
@@ -71,8 +71,12 @@ ROLE: migration-prep node. Merge presentation + state/data prep in ONE invocatio
 
 PRESENTATION: tokens, resources, media, routes, UI handoff.
 STATE/DATA: state holders, models, mappers, API expectations, logic handoff.
+State holder shape follows design_mode (default mvi): mvi → sealed State/Action + state machine
+(references/kmp-mvi-flowredux.md); mvvm → UiState + ViewModel methods (references/kmp-mvvm.md).
+Target is a KMP project per references/kmp-expert.md: scaffold in commonMain, platform actuals only in
+androidMain/iosMain, prefer the multiplatform library stack over Android-only types.
 
-INPUTS: migration_module_id, migration_planning_gate_path, analyst dimension paths,
+INPUTS: design_mode, architecture_reference_path, migration_module_id, migration_planning_gate_path, analyst dimension paths,
 target path, allowed_files, output_dir.
 
 OUTPUTS: migration_prep.json, migration_prep.md

package/skills/android-to-kmp-migrator/roles/module-implementation.md

@@ -25,6 +25,17 @@ You merge **UI implementation** and **logic implementation** with strict modes.
 
 **Gate**: `logic` mode MUST NOT run until latest UI review is `approved`.
 
+## Design Mode (architecture pattern)
+
+The run's `design_mode` (default `mvi`) is supplied by the Leader together with `architecture_reference_path`. You MUST implement to that pattern; do not mix patterns.
+
+| `design_mode` | Reference | Shape you produce |
+|---|---|---|
+| `mvi` **(default)** | `references/kmp-mvi-flowredux.md` | Sealed `State`/`Action`, `FlowReduxStateMachineFactory`, `dispatch()` from UI, unidirectional flow |
+| `mvvm` | `references/kmp-mvvm.md` | `ViewModel` exposing immutable `UiState` as `StateFlow`, public event methods, `collectAsStateWithLifecycle()` |
+
+Both modes follow `references/kmp-expert.md` for base KMP/CMP conventions. If `design_mode` or `architecture_reference_path` is missing from the dispatch, return `blocked` — do not guess the pattern.
+
 ## Success Criteria
 
 **UI mode**:
@@ -54,7 +65,7 @@ You merge **UI implementation** and **logic implementation** with strict modes.
 - Do not run full project compile/build — static edits only; build is `kmp-test-validator`.
 
 **Mandatory**:
-- Validate `kmp_target_project_path`, planning-gate `ready_for_implementation`, prep outputs, `target_module_anchors.json`, `allowed_files`, source sets, and workspace state before editing.
+- Validate `kmp_target_project_path`, `design_mode` + `architecture_reference_path`, planning-gate `ready_for_implementation`, prep outputs, `target_module_anchors.json`, `allowed_files`, source sets, and workspace state before editing.
 - Map each implementation task to a target path from planning/TPA before writing code.
 - Include `mode`, `kmp_target_project_path`, and `changed_files` in JSON return payload.
 - Write migration evidence artifacts under `output_dir`; write **implementation code** under `kmp_target_project_path`.
@@ -70,6 +81,8 @@ You merge **UI implementation** and **logic implementation** with strict modes.
   "legacy_module_id": "",
   "module_scope": {},
   "kmp_target_project_path": "",
+  "design_mode": "mvi | mvvm",
+  "architecture_reference_path": "",
   "output_root": "",
   "output_dir": "",
   "target_edit_summary": {
@@ -127,6 +140,11 @@ ROLE: module-implementation node in android-to-kmp-migrator. Modes: ui | logic.
 YOU IMPLEMENT IN THE TARGET KMP PROJECT. Edit/create KMP files under kmp_target_project_path.
 Legacy Android and analyst artifacts are read-only evidence. Do NOT edit Legacy Android.
 
+DESIGN MODE: follow design_mode (default mvi). mvi → references/kmp-mvi-flowredux.md
+(sealed State/Action + FlowReduxStateMachineFactory + dispatch); mvvm → references/kmp-mvvm.md
+(ViewModel + immutable UiState StateFlow + public event methods). Both follow references/kmp-expert.md.
+Do NOT mix patterns. If design_mode/architecture_reference_path missing, return blocked.
+
 UI MODE:
 - Port visible UI from upstream presentation evidence into target Compose/resources/navigation.
 - changed_files = every target file you created or modified.
@@ -143,7 +161,7 @@ CONTROL:
 - Map each task to a target path from planning source_to_target_map / TPA anchors first.
 - If anchor or allowed_files is missing, return blocked — do not guess target paths.
 
-INPUTS: mode, migration_module_id, legacy_module_id, kmp_target_project_path,
+INPUTS: mode, design_mode, architecture_reference_path, migration_module_id, legacy_module_id, kmp_target_project_path,
 migration_planning_gate_path, migration_prep_path, target_module_anchors_path,
 upstream module_representation + presentation_resource/behavior_logic paths (read-only),
 prior module_implementation_ui output (logic mode), allowed_files, output_dir.

package/skills/android-to-kmp-migrator/roles/module-node-review-fix.md

@@ -11,6 +11,17 @@ You are the `module-node-review-fix` node subagent. You consolidate review and f
 - `mode: review`: read-only review of one module/node slice.
 - `mode: fix`: scoped edit of explicit `must_fix` findings from one review report.
 
+## Design Mode (architecture pattern)
+
+The run's `design_mode` (default `mvi`) and `architecture_reference_path` are supplied by the Leader. Both modes MUST judge/repair code against that pattern:
+
+- `mvi` → `references/kmp-mvi-flowredux.md` (sealed `State`/`Action`, `FlowReduxStateMachineFactory`, `dispatch`).
+- `mvvm` → `references/kmp-mvvm.md` (`ViewModel` + immutable `UiState` `StateFlow` + public event methods).
+
+Both modes also judge code against `references/kmp-expert.md` base KMP/CMP conventions — correct source-set placement (`commonMain` vs `androidMain`/`iosMain`), `expect`/`actual` usage, no Android-only APIs leaked into `commonMain`, and multiplatform-stack choices.
+
+Flag architecture drift (wrong pattern vs `design_mode`) or base-KMP violations as `must_fix` findings in review; in fix mode, conform to the references. Do not introduce the other pattern.
+
 ## Success Criteria
 
 - Review mode writes `module_node_review.json` and `module_node_review.md`.
@@ -68,10 +79,15 @@ Shared return shape applies.
 ROLE: module-node-review-fix node.
 
 Respect mode strictly.
-Review mode: read-only; verify one owning node slice for contract, scope, parity, source-set, target convention, dependency discipline, and handoff readiness.
+Review mode: read-only; verify one owning node slice for contract, scope, parity, source-set, target convention, design_mode architecture conformance, dependency discipline, and handoff readiness.
 Fix mode: consume one review report; fix only assigned must_fix findings inside allowed_files; set requires_re_review=true.
 
-INPUTS: mode, migration_module_id, module_scope, owning_node, owning_node_output_path, changed_files, review_report_path for fix mode, allowed_files, workspace state, output_dir.
+DESIGN MODE: judge/repair against design_mode (default mvi). mvi → references/kmp-mvi-flowredux.md;
+mvvm → references/kmp-mvvm.md. Also enforce references/kmp-expert.md base KMP conventions (source-set
+placement, expect/actual, no android.* in commonMain). Wrong-pattern or base-KMP violations are must_fix.
+Never introduce the other pattern.
+
+INPUTS: mode, design_mode, architecture_reference_path, migration_module_id, module_scope, owning_node, owning_node_output_path, changed_files, review_report_path for fix mode, allowed_files, workspace state, output_dir.
 
 OUTPUTS:
 - review mode: module_node_review.json/md (read-only reviewed files, findings, approval/needs-fix decision, blockers)

package/skills/android-to-kmp-migrator/roles/target-project-assistant.md

@@ -20,6 +20,8 @@ You are the `target-project-assistant` node subagent. You understand the existin
 - `target_alignment_revision.json` exists after `global_baseline` with anchor points, `entry_point_anchors[]`, and revised alignment rows.
 - Per-module `target_module_anchors.json` maps legacy evidence to resolvable target paths.
 - `consult` responses reference prior alignment revision version and list affected anchor ids.
+- `target_project_layout` notes the target's existing presentation pattern and whether it matches the run's `design_mode` (default `mvi`); a mismatch is surfaced in `integration_constraints[]` for the Leader, not silently resolved.
+- `target_project_layout` is read against `references/kmp-expert.md` base KMP conventions — record the target's source-set hierarchy (`commonMain` / `androidMain` / `iosMain`), `shared` + `*App` module shape, and multiplatform stack so anchors resolve to the correct KMP source set; flag deviations from the base layout in `integration_constraints[]`.
 - No target code edits (read-only analysis).
 
 ## Boundary
@@ -106,7 +108,14 @@ You own target KMP understanding and alignment revision. Modes:
 
 You do NOT edit target code or run full builds. Other roles MUST use your artifacts.
 
-INPUTS: kmp_target_project_path, analyst_output_root, upstream_analyst_index_path, modules_index_path,
+DESIGN MODE: detect the target's existing presentation pattern and compare to design_mode (default mvi:
+references/kmp-mvi-flowredux.md; mvvm: references/kmp-mvvm.md). Record the match/mismatch in
+integration_constraints[] — do not resolve it yourself.
+KMP BASE: read the target against references/kmp-expert.md — capture source-set hierarchy
+(commonMain/androidMain/iosMain), shared + *App module shape, and stack so anchors resolve to the right
+source set; flag base-layout deviations in integration_constraints[].
+
+INPUTS: design_mode, architecture_reference_path, kmp_target_project_path, analyst_output_root, upstream_analyst_index_path, modules_index_path,
 migration_assembly_basis_path, cross_module_architecture_path, cross_module_data_logic_path,
 legacy module_representation paths, migration_module_id, mode, output_dir.
 

package/skills/android-to-kmp-migrator/workflow.md

@@ -59,10 +59,19 @@ graph TD
 ## Step 0 — Pre-flight
 
 - **Executor**: Leader
-- **Input**: [dependencies.yaml](dependencies.yaml) — `tools[]` (`rg`, `git`, `curl`), `optional_mcp.jetbrains`, `upstream_inputs` analyst **P6**
-- **Output**: `run_manifest.json` → `dependency_preflight` (CLI status, MCP availability, P6 readiness pointer)
+- **Input**: [dependencies.yaml](dependencies.yaml) — `tools[]` (`rg`, `git`, `curl`), `optional_mcp.jetbrains`, `upstream_inputs` analyst **P6**; the **user input / migration request**
+- **Output**: `run_manifest.json` → `dependency_preflight` (CLI status, MCP availability, P6 readiness pointer) and `design_mode` (architecture pattern decision)
 - **Gate**: missing CLI tools → degraded modes per dependencies.yaml; `android-project-analyst` **P6** not ready → **blocked** — invoke analyst first, do not dispatch migrator nodes
 
+### Step 0a — Identify design mode (default MVI)
+
+- Scan the **user input** for an explicit or implied presentation architecture:
+  - **`mvvm`** signals: "MVVM", shared `ViewModel`, `StateFlow` / `uiState`, `viewModelScope`, `collectAsStateWithLifecycle`, KMP-ObservableViewModel, SKIE → `references/kmp-mvvm.md`
+  - **`mvi`** signals: "MVI", FlowRedux, state machine, reducer, intent, unidirectional, sealed `State`/`Action`, `dispatch`, `inState`, `onEnter` → `references/kmp-mvi-flowredux.md`
+- **No clear signal → default `mvi`.**
+- Record `design_mode: { value: "mvi | mvvm", source: "user_input | default", signals: [], architecture_reference_path: "" }` in `run_manifest.json`.
+- Freeze `design_mode` for the run; pass `design_mode` + `architecture_reference_path` into every architecture-producing dispatch (planning-gate, prep, module-implementation, module-node-review-fix, global-migration-phase) and to TPA for target-pattern detection.
+
 ## Step 1 — Upstream + output root
 
 - Verify analyst package **P6**; write `upstream_analyst_index.json`.
@@ -125,6 +134,7 @@ Any target question → TPA `mode: consult` (append `consultation_log`).
 ## Acceptance Criteria
 
 - `android-project-analyst` **P6** verified before any migrator module dispatch.
+- `design_mode` identified from user input at Step 0 (default `mvi`) and recorded in `run_manifest.json`; architecture-producing dispatches carry `design_mode` + `architecture_reference_path`.
 - Target KMP files created or updated under `kmp_target_project_path` for every module requiring implementation; `target_changed_files[]` aggregated in `migration_report.json`.
 - `kmp-test-validator` invoked after **V0** — mandatory MG17 step.
 - Dispatch only role IDs from `SKILL.md`.