@code-migration/wow-migrator 0.2.3 → 0.2.5

package/package.json

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

package/skills/android-project-analyst/SKILL.md

@@ -11,27 +11,27 @@ roles:
   - id: analysis-workspace-state
     kind: ai_agent
     purpose: Analysis ledger — module status, node output inventory, stale inputs, rerun/blocker history, artifact readiness, and next actions. No source analysis or SPEC writing.
-    skills: []
+    skills: [operating-instructions]
     tools: [git]
   - id: presentation-resource
     kind: ai_agent
     purpose: Presentation and resource owner — screens, UI technologies, navigation, UI modules, local/remote image and media resources, safe downloads, and UI/resource migration implications.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg, curl]
   - id: project-architecture
     kind: ai_agent
     purpose: Project architecture owner — Gradle/module topology, architecture style, layer roles, dependency ecosystem, Jetpack/DI/platform services, generated tooling, and Android-only constraints.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
   - id: data-contract-flow
     kind: ai_agent
     purpose: Data contract and flow owner — network/local data contracts, models, consumers, repositories, streams, transformations, cache/error/pagination, write-back, and UI state propagation.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
   - id: behavior-logic
     kind: ai_agent
     purpose: Behavior and control-flow owner — user actions, lifecycle, state holders, business rules, side effects, state machines, navigation effects, gates, and cross-module interactions.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
 ---
 
@@ -41,6 +41,8 @@ This is the agent-facing registry and team definition for the `android-project-a
 
 **Canonical file recording system**: [output-contract.md](output-contract.md) defines every output path, required content, write order, and downstream **handoff package gates** (`P0`–`P6`). Downstream handlers (`migration-task-adapter`, `android-to-kmp-migrator`, `kmp-test-validator`) trigger only when the declared package artifacts exist, are non-empty, in-path, and not stale. The Leader MUST read `output-contract.md` before the first dispatch and MUST NOT claim completion without updating `handoff_gates` in the workspace ledger and `SPEC/verification.md`.
 
+**Baseline operating instructions**: [../operating-instructions/SKILL.md](../operating-instructions/SKILL.md) is the shared conduct layer for this skill and every dispatched analyst role. The Leader MUST read it before pre-flight/module partitioning and include it in each role dispatch as baseline instructions; role files, workflow gates, and output contracts add to it, not replace it.
+
 The team is **module-first Mixed B+C with a workspace-state ledger**: the Leader partitions the project into `analysis_modules`, writes index artifacts and one `modules/<module_id>/` folder per module, maintains `analysis-workspace-state` before downstream consumption, runs three foundation nodes in **parallel** (B) inside each module, then a final **gated specialization** node (C) synthesizes module behavior from verified upstream outputs. The Leader writes a module representation per module, records cross-module architecture and data/logic separately under `global/`, then combines everything into `global_representation.*` and SPEC. The controller owns routing, strict output-path enforcement, reconciliation, workspace-state refreshes, and SPEC integration; nodes own bounded module analysis only.
 
 ## Module Partitioning Model

package/skills/android-project-analyst/dependencies.yaml

@@ -5,7 +5,17 @@
 # Android Studio MCP is optional auxiliary evidence for the Legacy Android source project —
 # it never replaces durable node artifacts or handoff package gates (P0–P6).
 
-skills: []   # No local domain-specific skill packages required for active roles.
+skills:
+  - name: operating-instructions
+    required: true
+    used_by:
+      - Leader
+      - analysis-workspace-state
+      - presentation-resource
+      - project-architecture
+      - data-contract-flow
+      - behavior-logic
+    purpose: Shared baseline conduct layer loaded before analyst pre-flight, module partitioning, node dispatch, evidence synthesis, and final handoff work.
 
 optional_mcp:
   - server: jetbrains

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

@@ -11,47 +11,47 @@ roles:
   - id: migration-workspace-state
     kind: ai_agent
     purpose: Migration ledger — handoff gates M0–V0, plan-vs-code gaps, stale outputs, rerun hooks. No code edits.
-    skills: []
+    skills: [operating-instructions]
     tools: [git]
   - id: target-project-assistant
     kind: ai_agent
     purpose: Target KMP owner — global baseline, per-module anchors, alignment revision, consult log.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
   - id: migration-planning-gate
     kind: ai_agent
     purpose: Planning and dependency/platform gate — SPEC deltas, source-to-target map, capability map, ready_for_implementation.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
   - id: migration-prep
     kind: ai_agent
     purpose: Presentation and state/data prep — tokens, resources, routes, state/models/API expectations.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg, curl]
   - id: module-implementation
     kind: ai_agent
     purpose: Target KMP module implementation by mode — edit/create KMP UI files first, then logic after UI approval.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
   - id: module-node-review-fix
     kind: ai_agent
     purpose: Review or scoped fix by mode; fresh re-review after every fix.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg, git]
   - id: migration-verification
     kind: ai_agent
     purpose: Module static checks + UI/logic restoration vs analyst — no full project build.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg, git]
   - id: global-migration-phase
     kind: ai_agent
     purpose: Target KMP global integrate (edit cross-module glue + entry point wiring) then align (read-only analyst vs target comparison incl. entry points) by mode.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg]
   - id: completion-report
     kind: ai_agent
     purpose: Readiness and migration_report modes; validation handoff to kmp-test-validator.
-    skills: []
+    skills: [operating-instructions]
     tools: [rg, git]
 ---
 
@@ -61,9 +61,11 @@ Module-first migrator for Legacy Android → KMP target assembly. **Upstream ana
 
 **Canonical contract**: [output-contract.md](output-contract.md)
 
+**Baseline operating instructions**: [../operating-instructions/SKILL.md](../operating-instructions/SKILL.md) is the shared conduct layer for this skill and every dispatched migrator role. The Leader MUST read it before pre-flight and include it in each role dispatch as baseline instructions; role files, architecture references, workflow gates, and output contracts add to it, not replace it.
+
 ## 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 +75,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 +127,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 +143,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/dependencies.yaml

@@ -8,6 +8,20 @@
 
 # Skill chain (mandatory — Leader enforces at Step 0 and MG17)
 skills:
+  - name: operating-instructions
+    required: true
+    used_by:
+      - Leader
+      - migration-workspace-state
+      - target-project-assistant
+      - migration-planning-gate
+      - migration-prep
+      - module-implementation
+      - module-node-review-fix
+      - migration-verification
+      - global-migration-phase
+      - completion-report
+    purpose: Shared baseline conduct layer loaded before migrator pre-flight, planning, implementation, review/fix, verification, integration, and reporting work.
   - name: android-project-analyst
     required: true
     phase: prerequisite

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.