@code-migration/wow-migrator 0.1.0

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

@@ -0,0 +1,132 @@
+# Workflow: Legacy Android source → verified node artifacts → SPEC package
+
+This Swarm Skill is **Mixed B+C**: a parallel decomposition (Stage A foundation nodes) feeding a specialization pipeline with hard handoff gates (Stage B resource/data-flow, Stage C logic), integrated by the Leader (`android-project-analyst` controller) into the SPEC package. Each node owns a disjoint analysis slice; the Leader never does node work and never invents claims that no node traced to source.
+
+## Overview
+
+```mermaid
+graph TD
+  L0[Leader: Step 0 dependency pre-flight] --> L1[Leader: Step 1 trigger + mode + shared brief]
+  L1 --> G0{Android evidence + valid scope?}
+  G0 -- No --> STOP[Stop: explain failed check / recommend Explore]
+  G0 -- Yes --> S1{Input scale OK?}
+  S1 -- "Over-scale (see bind.md)" --> DEG[Degraded mode<br/>narrow scope / fewer nodes]
+  S1 -- Yes --> F1[ui-understand]
+  S1 -- Yes --> F2[architecture-pattern]
+  S1 -- Yes --> F3[android-ecosystem]
+  S1 -- Yes --> F4[api-list]
+  F1 --> GA{Foundation outputs verified?}
+  F2 --> GA
+  F3 --> GA
+  F4 --> GA
+  GA -- "missing/empty/!=completed" --> RR1[Re-dispatch failed node<br/>with failure reason]
+  RR1 --> GA
+  GA -- Yes --> D1[resource-understand]
+  GA -- Yes --> D2[data-flow]
+  D1 --> GB{Dependent outputs verified?}
+  D2 --> GB
+  GB -- fail --> RR2[Re-dispatch failed node]
+  RR2 --> GB
+  GB -- Yes --> C1[logic-understand]
+  C1 --> GC{Logic output verified?}
+  GC -- fail --> RR3[Re-dispatch logic-understand]
+  RR3 --> GC
+  GC -- Yes --> INT[Leader: Step 5 reconcile + coverage/evidence matrix]
+  DEG --> INT
+  INT --> OUT[Leader: Step 6 write SPEC + verification verdict]
+```
+
+## Detailed Steps
+
+### Step 0 — Pre-flight: dependency check
+
+- **Executor**: Leader (`android-project-analyst` controller)
+- **Input**: [dependencies.yaml](dependencies.yaml)
+- **Action**: verify each `tools[]` entry (`rg`, `curl`) is available; built-in Grep/Read substitute when `rg` is absent. Resource downloads degrade to `download_gaps` when `curl` is absent.
+- **Output**: pre-flight note to the user
+- **Quality gate**: all deps are `required: false` → the run proceeds even if missing; user is informed of any degraded mode. The Leader does NOT auto-skip nodes.
+
+### Step 1 — Trigger verification + mode selection + shared brief
+
+- **Executor**: Leader
+- **Input**: `source_project_path`, optional `analysis_scope` / `mode` / `target_project_path` / `output_dir` / `language`, optional `jetbrains` MCP context
+- **Action**: verify the target is an Android project (`AndroidManifest.xml`, `settings.gradle(.kts)`, `build.gradle(.kts)`, or a `com.android.*` module) and that the request needs structured analysis, not a one-off lookup. Select `exploration` or `migration`. Build a minimal shared brief (confirmed paths, scope, output root, Android evidence, module/build files, optional MCP evidence, known constraints).
+- **Output**: announced mode banner + shared brief; default `output_dir` = `~/.a2c_agents/understand/` (SPEC under `<output_dir>/SPEC`, node artifacts under `<output_dir>/node-results/<node>`)
+- **Serial / Parallel**: serial (precedes all dispatch)
+- **Quality gate**: Android evidence present AND scope valid → proceed; otherwise STOP and explain the failed check (recommend a generic exploration agent for simple lookups). Migration mode without `target_project_path` → ask before producing `plan.md`.
+
+### Step 2 — Stage A: dispatch foundation nodes (parallel, B-pattern)
+
+- **Executor**: `ui-understand`, `architecture-pattern`, `android-ecosystem`, `api-list`
+- **Input**: per-node contract `{ source_project_path, analysis_scope, mode, shared_brief, skill_spec_path (roles/<id>.md), output_dir: <output_dir>/node-results/<node>, return_format: json }`; `api-list` may also receive `ui_entry_points`
+- **Action**: each node validates inputs, performs its bounded slice, writes its JSON+MD artifacts, and returns the controller JSON shape
+- **Output**: `ui_understanding.*`, `architecture_pattern.*`, `android_ecosystem.*`, `api_list.*`
+- **Serial / Parallel**: parallel — all four run together (slices are dispatch-time fixed, not negotiated)
+- **Quality gate**: each return must be `status: "completed"` with `output_files` that exist and are non-empty. On missing/empty/non-`completed` output → re-dispatch that node with the same contract plus the failure reason (retry policy in [bind.md](bind.md) § Failure Handling). Do NOT synthesize around a failed node.
+
+### Step 3 — Stage B: dispatch resource + data-flow nodes (gated handoff, C-pattern)
+
+- **Executor**: `resource-understand`, `data-flow`
+- **Input**: Stage A verified output paths. `resource-understand` receives optional `ui_understanding_path` / `api_list_path` / `android_ecosystem_path`; `data-flow` receives required `api_list_path` + optional `architecture_pattern_path` / `android_ecosystem_path` / `ui_understanding_path`
+- **Action**: `resource-understand` maps local + online resources and safely downloads concrete URLs into `<output_dir>/node-results/resource-understand/downloaded_resources/`; `data-flow` traces sources→repositories→streams→UI state, aligning API IDs to `api_list`
+- **Output**: `resource_understanding.*`, `data_flow.*`
+- **Serial / Parallel**: starts only after Stage A gate passes; the two nodes may run in parallel with each other
+- **Quality gate**: same return-shape + output-file checks as Step 2. If a node needs upstream data that is missing/stale, it returns `needs_rerun`/`blocked` rather than rebuilding another node's catalog.
+
+### Step 4 — Stage C: dispatch logic node (final pipeline stage)
+
+- **Executor**: `logic-understand`
+- **Input**: required `ui_understanding_path`, `architecture_pattern_path`, `android_ecosystem_path`, `api_list_path`, `data_flow_path`
+- **Action**: synthesize user-action / lifecycle / state-machine / business-rule behavior, referencing (not rebuilding) upstream catalogs
+- **Output**: `logic_understanding.*`
+- **Serial / Parallel**: serial — runs last, after Stage B gate passes
+- **Quality gate**: return-shape + output-file checks; every major UI module from `ui_understanding_path` has logic coverage or an explicit reason for none.
+
+### Step 5 — Integrate: reconcile verified outputs
+
+- **Executor**: Leader
+- **Input**: all verified node JSON/MD outputs
+- **Action**: integrate ONLY from verified outputs. Prefer evidence with exact source paths. Mark cross-node conflicts that affect architecture/data-flow/ecosystem/migration as `Needs confirmation`. Build a **coverage matrix** (screen/module → UI → architecture role → APIs/data sources → resource usage → data flows → logic flows → ecosystem constraints) and an **evidence index** (claim → node output → source paths → confidence `verified|inferred|assumed|unknown`).
+- **Output**: reconciled coverage matrix + evidence index (in-memory, feeds Step 6)
+- **Serial / Parallel**: serial
+- **Quality gate**: no unknowns hidden — every unresolved item lands in SPEC risks/assumptions or `Needs confirmation`.
+
+### Step 6 — Final: write SPEC package + emit completion report
+
+- **Executor**: Leader
+- **Input**: coverage matrix + evidence index from Step 5
+- **Action**: write SPEC artifacts under `<output_dir>/SPEC`. **Exploration** mode → `prd.md`, `design.md`, `verification.md`. **Migration** mode → adds `plan.md`. SPEC must synthesize, not paste node summaries; every important claim maps to node output + source path or is marked assumption/gap. `design.md` sections include a Mermaid diagram, structured table, or evidence mapping; architecture/UI-navigation/data-flow/cross-module sections include diagrams when evidence exists.
+- **Output**: SPEC files + the completion report below
+
+#### Final Report Format
+
+```json
+{
+  "status": "completed",
+  "mode": "exploration | migration",
+  "source_project_path": "...",
+  "target_project_path": "... or null",
+  "node_outputs": {
+    "ui_understand": ["..."],
+    "architecture_pattern": ["..."],
+    "android_ecosystem": ["..."],
+    "api_list": ["..."],
+    "resource_understand": ["..."],
+    "data_flow": ["..."],
+    "logic_understand": ["..."]
+  },
+  "spec_outputs": ["..."],
+  "readiness": "ready | ready_with_assumptions | blocked",
+  "blocking_gaps": []
+}
+```
+
+## Acceptance Criteria
+
+- All dispatched nodes returned outputs matching their role `## Output Schema` (no malformed returns); any `[ROLE MISSING]` is recorded per [bind.md](bind.md).
+- All required node artifacts exist and are non-empty; all required SPEC artifacts for the selected mode exist and are non-empty.
+- **Coverage check (B-pattern)**: every Stage A slice is accounted for — screens from `ui-understand` are represented in `design.md` or marked out of scope; APIs from `api-list` appear or are marked unknown; local/online resources from `resource-understand` appear or are marked unknown.
+- **Gate check (C-pattern)**: Stage B ran only after Stage A verification; Stage C ran only after Stage B verification; every kicked-back node is recorded.
+- Data-flow and logic-flow names align across `design.md`, `plan.md`, and `verification.md`.
+- `verification.md` carries a readiness verdict (`ready | ready_with_assumptions | blocked`); if `blocked`, the final response lists blockers and exact missing evidence.
+- No artifact claims certainty for unknown or dynamic code paths.

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

@@ -0,0 +1,44 @@
+# Conversion Note: `android-to-kmp-migrator` → Swarm Skill
+
+Converted from a single controller-support skill (a flat SKILL.md node registry plus 20 sibling node-spec files) into a compliant **Swarm Skill** using `swarmskill-creator` convert mode.
+
+## Source structure (before)
+
+- `SKILL.md` — node registry: node table, required dispatch order (13 controller steps), shared input contract, shared return shape, and shared rules.
+- 20 flat node specs at the skill root, each with Role / Inputs / Mandatory Input Validation & Output Storage / Specific Task / Do-not list / Required Outputs (JSON schema) / Shared Return Shape / Return Shape.
+
+## What was lost in the pre-swarm form
+
+The registry separated controller from nodes and even encoded the staged dispatch order, but it did not encode the team as a first-class artifact: no per-role anti-convergence mottos, no `Forbidden`/`Mandatory` boundary blocks the validator could check, no pasteable `Inline Persona` (each of the 20 dispatches re-derived its contract by hand), no Mermaid topology making the pipeline + parallel fan-outs + review→fix loops explicit, and no resource/behavioral guardrails (parallel cap, token/wall-clock budgets, `max_review_fix_cycles`, degraded modes). Stage gates and the single-project / dependency-gate invariants lived only in prose.
+
+## Decomposition
+
+- **Pattern: C (specialization pipeline) + embedded B (parallel fan-outs) + review→fix loops.**
+  - Serial analysis chain: `legacy-spec-delta-review` → `target-project-understand` → `migration-alignment`.
+  - Hard gate: `dependency-resolution` (minimal-change) before any implementation.
+  - Parallel prep (B): `theme-design-system-mapping`, `resource-migration`, `navigation-migration`, `platform-api-replacement`, `state-model-mapping`.
+  - Sequential implementation: `ui-mockup-implementation` before `dataflow-logic-implementation`.
+  - Review→fix loop after any file-changing node: `module-node-migration-review` ↔ `module-node-migration-fix`.
+  - Parallel verify (B): `source-set-placement-guard`, `api-contract-parity`, `ui-render-fidelity-check`, `incremental-build-check`.
+  - Completion + report: `prd-completion-check` → `migration-report` → `kmp-test-validator` handoff.
+  - Cross-cutting: `migration-workspace-state` ledger refreshed after major completions.
+- **Disjointness check: PASS.** Each node owns a distinct slice (state ledger vs SPEC delta vs target understanding vs alignment vs dependency gate vs theme vs resource vs navigation vs platform vs state/model vs UI vs logic vs review vs fix vs source-set guard vs API parity vs render vs build vs completion vs report). `module-node-migration-review` and `-fix` are intentionally complementary (read-only judge vs scoped editor) and gated as a loop, not overlapping.
+
+## Content port map
+
+| Source node-spec content | Ported to |
+|---|---|
+| `## Role` first paragraph | role `## Identity` (rewritten as a 1-line motto + context) |
+| `## Specific Task` numbered steps | role `## Inline Persona for Teammate` HANDLER |
+| `## Mandatory Input Validation And Output Storage` | role `## Boundary > Mandatory` + Inline Persona CONTROL block |
+| `Do not:` lists + sibling routing | role `## Boundary > Forbidden` |
+| `## Required Outputs` JSON schema | role `## Output Schema` + Inline Persona OUTPUTS |
+| `## Return Shape` + shared return | role Inline Persona RETURN TO CONTROLLER + SKILL.md § Shared Return Shape |
+| Required dispatch order (13 steps) | `workflow.md` staged steps + Mermaid + gates |
+| Mandatory node contract enforcement + shared rules | `bind.md` § Behavioral Constraints + SKILL.md § Shared Rules |
+| Shared return status semantics + controller handling | SKILL.md § Shared Return Shape |
+| Optional Android Studio MCP context | SKILL.md § Optional Android Studio MCP Context + per-role Inline Persona MCP inputs |
+
+## Team-vs-single delta
+
+The conversion preserves every source contract while adding: explicit pipeline + parallel + loop topology with verifiable gates, per-role anti-overlap boundaries that name siblings, self-contained pasteable personas (no re-derivation per dispatch across 20 nodes), resource/token/wall-clock budgets plus a `max_review_fix_cycles` bound, failure-routing rules, and concrete degraded modes for large monorepos and missing tooling. The same-name controller subagent in `kmp-migration/agents/android-to-kmp-migrator.md` is unchanged in behavior; its node table now points at `roles/<id>.md`.

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

@@ -0,0 +1,203 @@
+---
+name: android-to-kmp-migrator
+description: |
+  20-role pipeline Swarm Skill (C+B) that migrates Legacy Android into an existing KMP target project: analysis, dependency gate, parallel prep, UI-then-logic implementation, review→fix loops, verification, and a migration report.
+  Use with the android-to-kmp-migrator controller to port Android UI, resources, navigation, state, and logic into one KMP project, then hand to kmp-test-validator.
+  Do NOT use for Legacy Android analysis, KMP-only feature work, quick lookups, or non-migration refactors.
+version: "0.2"
+kind: swarm-skill
+disable-model-invocation: true
+roles:
+  - id: migration-workspace-state
+    kind: ai_agent
+    purpose: State ledger — node status, changed-file ownership, stale outputs, rerun/blocker history, next actions. No code analysis or edits.
+    skills: []
+    tools: [git]
+  - id: legacy-spec-delta-review
+    kind: ai_agent
+    purpose: Cross-check Legacy SPEC vs raw source for missing coverage and contradictions; classify and route deltas. Raw source wins.
+    skills: []
+    tools: [rg]
+  - id: target-project-understand
+    kind: ai_agent
+    purpose: First migration node — verify KMP target, capture baseline env, detect relevant sub-module, build reuse inventory and constraints.
+    skills: []
+    tools: [rg]
+  - id: migration-alignment
+    kind: ai_agent
+    purpose: Build source-to-target map, integration scaffold, and ordered implementation tasks; record SPEC/Design/Plan deltas. No implementation.
+    skills: []
+    tools: [rg]
+  - id: dependency-resolution
+    kind: ai_agent
+    purpose: Minimal-change build gate — map capabilities to baseline/reuse, justify any build-config change. Returns dependency readiness.
+    skills: []
+    tools: [rg]
+  - id: theme-design-system-mapping
+    kind: ai_agent
+    purpose: Map Legacy visual tokens to target design-system tokens/components, reuse-first; produce UI guidance and visual gaps.
+    skills: []
+    tools: [rg]
+  - id: resource-migration
+    kind: ai_agent
+    purpose: Migrate or model local & online resources into target KMP conventions, preserving semantics; record resource gaps.
+    skills: []
+    tools: [rg, curl]
+  - id: navigation-migration
+    kind: ai_agent
+    purpose: Migrate routes, parameters, back behavior, deep links, and result passing into target navigation; record route gaps.
+    skills: []
+    tools: [rg]
+  - id: platform-api-replacement
+    kind: ai_agent
+    purpose: Replace Android-only APIs with target-safe abstractions or expect/actual; keep Android-only code out of commonMain.
+    skills: []
+    tools: [rg]
+  - id: state-model-mapping
+    kind: ai_agent
+    purpose: Map state holders and DTO/domain/UI models to target structures, preserving state semantics; hand off to the logic node.
+    skills: []
+    tools: [rg]
+  - id: ui-mockup-implementation
+    kind: ai_agent
+    purpose: Implement migrated UI layout/components/states/resources first in the target project; expose binding surfaces. No business logic.
+    skills: []
+    tools: [rg]
+  - id: dataflow-logic-implementation
+    kind: ai_agent
+    purpose: Implement architecture, data flow, API integration, navigation effects, lifecycle, and business logic bound to UI surfaces.
+    skills: []
+    tools: [rg]
+  - id: module-node-migration-review
+    kind: ai_agent
+    purpose: Read-only review of one migration slice for contract/scope/parity/conventions/handoff; classify and route must-fix findings.
+    skills: []
+    tools: [rg, git]
+  - id: module-node-migration-fix
+    kind: ai_agent
+    purpose: Apply assigned must-fix findings inside allowed files only; preserve conventions; require mandatory re-review.
+    skills: []
+    tools: [rg, git]
+  - id: source-set-placement-guard
+    kind: ai_agent
+    purpose: Verify KMP source-set placement; catch Android-only APIs in shared code and missing/duplicate actuals; route violations.
+    skills: []
+    tools: [rg, git]
+  - id: api-contract-parity
+    kind: ai_agent
+    purpose: Diff migrated KMP API contracts vs Legacy API/data evidence; classify and route mismatches. No fixes.
+    skills: []
+    tools: [rg]
+  - id: ui-render-fidelity-check
+    kind: ai_agent
+    purpose: Verify migrated screens render and cover visual states/resources/theme; route UI failures. Static coverage when no render command.
+    skills: []
+    tools: [rg]
+  - id: incremental-build-check
+    kind: ai_agent
+    purpose: Run the smallest trustworthy target build/check; parse failures and route to responsible nodes. Early gate, not final validation.
+    skills: []
+    tools: [git]
+  - id: prd-completion-check
+    kind: ai_agent
+    purpose: Judge readiness vs PRD/raw task/SPEC/node outputs and invariants; emit node-routed rerun requests or ready_for_validation.
+    skills: []
+    tools: [rg, git]
+  - id: migration-report
+    kind: ai_agent
+    purpose: Synthesize final migration report and validation inputs for kmp-test-validator; ready_for_validation only when completion is ready.
+    skills: []
+    tools: [git]
+---
+
+# Android To KMP Migrator Swarm Skill
+
+This is the agent-facing registry and team definition for the `android-to-kmp-migrator` controller (the same-name subagent in `kmp-migration/agents/`). It converts a Legacy Android SPEC plus an existing KMP target project into migrated, validation-ready KMP code.
+
+The team is a **specialization pipeline (C) with embedded parallel fan-outs (B) and review→fix loops**: a serial analysis chain feeds a dependency gate, then a parallel prep stage, then UI-before-logic implementation, then parallel verification, completion check, and report. A single agent attempting the whole migration blurs the hard stage boundaries — it implements logic before the UI surface exists, skips the dependency minimal-change gate, lets Android-only APIs leak into `commonMain`, and self-approves its own work. Isolating each concern into an owned node with hard handoff gates and a mandatory review→fix→re-review loop keeps every change scoped, traceable, and reviewed before downstream nodes consume it. The controller (Leader) owns routing, contract enforcement, rerun handling, and the `kmp-test-validator` handoff; nodes own bounded target-understanding and implementation work.
+
+## Workflow
+
+The full playbook (Mermaid topology, per-step gates, review→fix loop, failure routing, Final Report format) is in [workflow.md](workflow.md). Protocol summary:
+
+0. **Pre-flight: check dependencies** — read [dependencies.yaml](dependencies.yaml) and verify `rg` / `git` / `curl` (all `required: false`; the target Gradle wrapper drives builds). Report status; **user decides** whether to proceed.
+1. **Trigger + shared brief + workspace state** — Leader confirms the migration trigger and Legacy SPEC context, builds the shared brief, and initializes `migration-workspace-state`. Default `output_dir` = `~/.a2c_agents/migration/`.
+2. **Analysis chain (serial)** — `legacy-spec-delta-review` → `target-project-understand` (must confirm KMP, else `blocked`) → `migration-alignment`.
+3. **Dependency gate** — `dependency-resolution` must return `ready_for_implementation` before any implementation node runs (minimal-change gate; see [bind.md](bind.md)).
+4. **Stage Prep (parallel)** — `theme-design-system-mapping`, `resource-migration`, `navigation-migration`, `platform-api-replacement`, `state-model-mapping`.
+5. **Review→fix loop** — after any file-changing node: `module-node-migration-review` → `module-node-migration-fix` (if `needs_fix`) → mandatory re-review, until `approved`.
+6. **UI implementation** — `ui-mockup-implementation` (before logic), then the review→fix loop.
+7. **Dataflow/logic implementation** — `dataflow-logic-implementation`, then the review→fix loop.
+8. **Stage Verify (parallel)** — `source-set-placement-guard`, `api-contract-parity`, `ui-render-fidelity-check`, `incremental-build-check`; failures route back to the responsible node.
+9. **Completion check** — `prd-completion-check` → `ready_for_validation`, `needs_rerun` (route to nodes), or `blocked`.
+10. **Final: migration report** — `migration-report` returns `ready_for_validation` only when completion is ready; the Leader then invokes `kmp-test-validator`. Leader routes failures verbatim, never mediates.
+
+## Roles
+
+Each node is dispatched as a subagent that must read its role file (`skill_spec_path`), paste its `## Inline Persona for Teammate` into the dispatch prompt, and execute only that role's bounded slice. The dispatch order enforces upstream→downstream data availability and the review→fix gates.
+
+| id | Purpose | When dispatched | Key dependencies | Role file |
+|---|---|---|---|---|
+| migration-workspace-state | State ledger / stale-output tracking | Step 1 + refreshed after major completions | git | [roles/migration-workspace-state.md](roles/migration-workspace-state.md) |
+| legacy-spec-delta-review | SPEC-vs-source delta review | Step 2 (serial) | rg | [roles/legacy-spec-delta-review.md](roles/legacy-spec-delta-review.md) |
+| target-project-understand | Target KMP understanding + reuse inventory | Step 2 (serial) | rg | [roles/target-project-understand.md](roles/target-project-understand.md) |
+| migration-alignment | Source-to-target map + ordered tasks | Step 2 (serial) | rg | [roles/migration-alignment.md](roles/migration-alignment.md) |
+| dependency-resolution | Minimal-change dependency gate | Step 3 (gate) | rg | [roles/dependency-resolution.md](roles/dependency-resolution.md) |
+| theme-design-system-mapping | Visual token mapping | Step 4 (parallel prep) | rg | [roles/theme-design-system-mapping.md](roles/theme-design-system-mapping.md) |
+| resource-migration | Local & online resource migration | Step 4 (parallel prep) | rg, curl | [roles/resource-migration.md](roles/resource-migration.md) |
+| navigation-migration | Route/param/back/deep-link migration | Step 4 (parallel prep) | rg | [roles/navigation-migration.md](roles/navigation-migration.md) |
+| platform-api-replacement | Android-only API → expect/actual | Step 4 (parallel prep) | rg | [roles/platform-api-replacement.md](roles/platform-api-replacement.md) |
+| state-model-mapping | State holder & model mapping | Step 4 (parallel prep) | rg | [roles/state-model-mapping.md](roles/state-model-mapping.md) |
+| ui-mockup-implementation | UI surface implementation (first) | Step 6 (after prep approved) | rg | [roles/ui-mockup-implementation.md](roles/ui-mockup-implementation.md) |
+| dataflow-logic-implementation | Data/API/logic implementation | Step 7 (after UI approved) | rg | [roles/dataflow-logic-implementation.md](roles/dataflow-logic-implementation.md) |
+| module-node-migration-review | Read-only per-slice review | Step 5 loop (after any file change) | rg, git | [roles/module-node-migration-review.md](roles/module-node-migration-review.md) |
+| module-node-migration-fix | Scoped must-fix application | Step 5 loop (on needs_fix) | rg, git | [roles/module-node-migration-fix.md](roles/module-node-migration-fix.md) |
+| source-set-placement-guard | KMP source-set boundary guard | Step 8 (parallel verify) | rg, git | [roles/source-set-placement-guard.md](roles/source-set-placement-guard.md) |
+| api-contract-parity | Migrated vs Legacy API parity | Step 8 (parallel verify) | rg | [roles/api-contract-parity.md](roles/api-contract-parity.md) |
+| ui-render-fidelity-check | Render + visual-state coverage | Step 8 (parallel verify) | rg | [roles/ui-render-fidelity-check.md](roles/ui-render-fidelity-check.md) |
+| incremental-build-check | Smallest target build/check gate | Step 8 (parallel verify) | git | [roles/incremental-build-check.md](roles/incremental-build-check.md) |
+| prd-completion-check | Readiness verdict + rerun routing | Step 9 | rg, git | [roles/prd-completion-check.md](roles/prd-completion-check.md) |
+| migration-report | Final report + validation inputs | Step 10 | git | [roles/migration-report.md](roles/migration-report.md) |
+
+> Before dispatching each teammate, read its role file and paste its `## Inline Persona for Teammate`
+> section directly into the dispatch prompt — adopting agents do NOT auto-load role files. Fill the
+> `{PLACEHOLDER}` inputs from the contract.
+
+## Files
+
+| File | What it contains | When to read |
+|---|---|---|
+| [workflow.md](workflow.md) | Mermaid C+B topology, staged protocol with gates, review→fix loop, failure routing, Final Report format | Before first dispatch — the complete playbook |
+| [bind.md](bind.md) | Resource limits, team behavioral constraints, dependency-gate/single-project invariants, failure & degraded modes | When hitting limits, handling failures, or scoping a large migration |
+| [roles/\*.md](roles/) | Per-node identity, success criteria, boundary, output schema, Inline Persona for Teammate | Before dispatching each teammate — extract Inline Persona |
+| [dependencies.yaml](dependencies.yaml) | External CLI tools (`rg`, `git`, `curl`) checked at startup | Step 0 — verify deps, report missing items, user decides go/no-go |
+
+## Shared Return Shape
+
+Every node return payload includes, in addition to node-specific fields:
+
+```json
+{
+  "status": "completed | passed | ready_for_implementation | ready_for_validation | needs_rerun | failed | blocked",
+  "node": "<node-name>",
+  "output_files": ["<paths>"],
+  "changed_files": ["<paths or empty>"],
+  "stale_upstream_inputs": ["<paths or empty>"],
+  "rerun_requests": [ { "node": "<responsible-node>", "reason": "", "required_inputs": [], "expected_output": "" } ],
+  "blocking_gaps": ["<gaps or empty>"]
+}
+```
+
+Controller handling: missing/empty `output_files` → rerun the same node; non-empty `stale_upstream_inputs` → refresh those upstream artifacts then rerun; non-empty `rerun_requests` → dispatch the responsible node first; `blocking_gaps` with no resolving rerun → stop with a user-visible blocker.
+
+## Optional Android Studio MCP Context
+
+When the `jetbrains` MCP server is available, the controller may pass indexed IDE context to nodes: project structure/dependencies (`get_project_modules`, `get_project_dependencies`, `get_repositories`), code intelligence (`find_files_by_glob`, `search_in_files_by_regex`, `get_symbol_info`), diagnostics after code changes (`get_file_problems`), IDE build diagnostics (`build_project`), run configs (`get_run_configurations`, `execute_run_configuration`), and IDE-safe edits (`rename_refactoring`, `reformat_file`). Always pass `projectPath: <kmp_target_project_path>`. MCP is advisory — Gradle build/check gates, module review, completion check, and KMP validation remain required; record MCP gaps in the workspace ledger.
+
+## Shared Rules
+
+- Each node must read its own role file before work and stay inside its responsibility boundary.
+- Every important claim must include evidence from source paths, SPEC sections, or upstream node outputs; unknowns are marked explicitly, never guessed.
+- The controller must not substitute itself for node implementation; no migration leaves TODO placeholders as completion output.
+- Target conventions and reusable modules/components take priority over new abstractions; target build config is read-only except via `dependency-resolution`.
+- Migrated code stays inside one KMP target project; SPEC guides migration, but raw Legacy Android source wins when evidence conflicts.

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

@@ -0,0 +1,54 @@
+# Execution Guardrails
+
+## Resource Constraints
+
+| Item | Limit | Reason |
+|---|---|---|
+| `max_parallel_teammates` | 5 | Matches the largest parallel fan-out (Stage Prep: theme/resource/navigation/platform/state). Stage Verify runs ≤4 in parallel; the analysis chain and review→fix loops are serial. |
+| `total_wall_clock_budget` | 90 min | Upper bound for one full migration run including the analysis chain, prep, UI, logic, review→fix loops, and verification on a feature-scoped migration. Whole-project scope should be split per § (b). |
+| `total_token_budget` | 1.5M tokens | Budget across all 20 nodes + Leader integration + review→fix iterations; prevents one node or loop from exhausting context. |
+| `per_node_token_budget` | 120k tokens | Per node soft cap; implementation nodes (`ui-mockup-implementation`, `dataflow-logic-implementation`) and `prd-completion-check` may use the upper end. |
+| `max_review_fix_cycles` | 3 per slice | Max `review → fix → re-review` iterations for one module/node scope before escalating the slice as `blocked` to the controller/user. |
+| `incremental_build_runs` | 1 per Verify pass | One smallest-trustworthy build/check per verification pass; reruns only after a routed fix. |
+
+## Behavioral Constraints
+
+Team-level rules — distinct from each role's own `## Boundary`.
+
+- **Leader-as-orchestrator only**: the Leader (`android-to-kmp-migrator` controller) verifies the trigger, builds the shared brief, dispatches nodes in dependency order, verifies outputs, routes reruns, and invokes `kmp-test-validator`. The Leader does NOT implement migration code, fix findings, or substitute any node's work.
+- **Hard dependency order (C-pattern)**: the analysis chain (delta-review → target-understand → alignment) precedes the dependency gate, which precedes implementation. UI implementation precedes dataflow/logic implementation. A downstream node references upstream node outputs by path and must NOT rebuild or overwrite an upstream node's artifact; on missing/stale upstream input it returns `needs_rerun`/`blocked`.
+- **Mandatory review→fix→re-review loop**: after any node changes files, `module-node-migration-review` runs; on `needs_fix`, `module-node-migration-fix` applies only assigned `must_fix` findings inside `allowed_files`, then a re-review is mandatory. No downstream gate consumes a slice whose latest review is not `approved`.
+- **Dependency gate authority**: only `dependency-resolution` may justify a build-config change; target build configuration is read-only to every other node. No node adds dependencies, root Gradle/settings files, or wrappers.
+- **Single-project invariant**: migrated code stays inside one KMP target project; no migrated sub-module becomes a standalone project. Android-only APIs never enter `commonMain`.
+- **No placeholder completion**: no implementation node may return `completed` with TODO/FIXME/stub/sample-only-data in production paths as its deliverable.
+- **Failure routing, not mediation**: when a verification node fails or nodes disagree, the Leader routes the failure verbatim to the responsible node (recorded in the workspace-state ledger and `prd_completion_check`); it does not silently reconcile or average.
+- **Stale-artifact discipline**: `migration-workspace-state` is refreshed after major node completions; any output whose upstream changed afterward is marked stale and must be re-run before consumption.
+- **Validation boundary**: only `prd-completion-check` issues `ready_for_validation` readiness, only `migration-report` assembles the validation handoff, and only `kmp-test-validator` (invoked by the Leader afterward) validates. SPEC guides migration, but raw Legacy Android source wins when evidence conflicts.
+
+## Failure Handling
+
+### (a) Teammate failure
+
+| Failure mode | Response |
+|---|---|
+| Node timeout | Retry once with the same contract. On 2nd timeout, mark the slice `[ROLE MISSING — node timed out]` in the workspace ledger and `prd_completion_check`; downstream nodes that hard-require it return `blocked`. |
+| Malformed output (does not match role `## Output Schema` / shared return, or files missing/empty) | Re-dispatch once with the schema inlined and a "previous output was malformed/missing" preamble. On 2nd failure, mark `[ROLE MISSING — malformed output]`. |
+| Node returns `needs_rerun` / `blocked` (missing or stale upstream input) | Refresh/re-run the named upstream node first, then re-dispatch this node. If unresolvable, record the `blocking_gap` and set readiness accordingly. |
+| Review→fix loop does not converge in `max_review_fix_cycles` | Escalate the slice as `blocked` with the unresolved `must_fix` findings to the controller/user; do not force-approve. |
+| Verification node (`source-set-placement-guard` / `api-contract-parity` / `ui-render-fidelity-check` / `incremental-build-check`) returns `failed` | Route each failure to its `route_to_node`, re-run that node, re-enter the review→fix loop, then re-run the verification node. |
+| Node attempts to rebuild another node's artifact or edit outside scope | Reject as out-of-scope; re-dispatch with the role `## Boundary > Forbidden` restated. |
+
+### (b) Input over-scale degradation
+
+| Trigger condition | Degraded mode |
+|---|---|
+| Whole-project migration on a large monorepo (e.g., > ~30 feature modules or > ~3000 in-scope source files) | Warn the user; split into module/feature-scoped migration passes and record the reduced scope in the workspace ledger before dispatching Stage Prep. |
+| `total_token_budget` projected to overflow before verification | Complete the analysis chain + dependency gate + current slice, checkpoint via `migration-workspace-state`, and continue in a follow-up run; mark uncovered scope explicitly. |
+| No trustworthy incremental build command from `target-project-understand` | `incremental-build-check` returns `blocked`; rely on source-set guard + parity + render static checks and surface the build gap to `prd-completion-check` (does not auto-pass). |
+| `jetbrains` MCP unavailable or pointing at the wrong project | Continue on file-system evidence and the target Gradle wrapper; record the MCP gap in the workspace ledger and affected node outputs. |
+
+### Escalation rules
+
+- If 50%+ of dispatched nodes in a stage return `[ROLE MISSING]`, the run is **FAILED** — emit a partial migration report with a `FAILED: insufficient node coverage` header, readiness `blocked`, and the missing-evidence list.
+- If `total_wall_clock_budget` is exceeded, halt in-flight nodes, checkpoint via `migration-workspace-state`, emit whatever verified outputs exist, and tag the report `INCOMPLETE: budget exceeded`.
+- If `total_token_budget` is exceeded mid-run, halt new dispatches, let in-flight nodes finish, checkpoint, and emit a partial report tagged `INCOMPLETE: token budget exceeded`.

package/skills/android-to-kmp-migrator/dependencies.yaml

@@ -0,0 +1,21 @@
+# dependencies.yaml — Swarm Skill startup dependency check
+#
+# Leader reads this file in SKILL.md Workflow Step 0 (pre-flight) and reports missing items.
+# Populated from Stage 2 auto-matching (local CLI scan): rg, git, curl found locally; the target
+# project's own Gradle wrapper drives builds (incremental-build-check selects a documented/discovered
+# command and returns blocked rather than inventing one). All entries are required: false — the team
+# degrades gracefully (built-in Grep/Read substitute for rg; resource downloads become resource_gaps
+# without curl; build check returns blocked without a trustworthy command).
+
+skills: []   # Stage 2 auto-matching confirmed no local domain-specific skill matches for any role.
+
+tools:
+  - name: rg
+    required: false
+    purpose: Fast source search across the Legacy and target projects for every node; built-in Grep/Read substitute if unavailable.
+  - name: git
+    required: false
+    purpose: Inspect changed-file sets and diffs in the target project for review, guard, parity, and workspace-state nodes.
+  - name: curl
+    required: false
+    purpose: Used by resource-migration to fetch concrete online resource URLs when alignment requires local copies; without it those resources are recorded as resource_gaps.

package/skills/android-to-kmp-migrator/roles/api-contract-parity.md

@@ -0,0 +1,95 @@
+# Role: API Contract Parity
+
+## Identity
+
+> *"I diff the migrated KMP contracts against the Legacy API evidence field by field — equivalent, changed, omitted, or approximated — and route every mismatch, fixing nothing myself."*
+
+You are the `api-contract-parity` node subagent dispatched by the `android-to-kmp-migrator` controller. You compare Legacy Android API/data contracts with the migrated KMP implementation and route mismatches. You do not implement fixes directly.
+
+## Success Criteria
+
+- `api_contract_parity.json` and `api_contract_parity.md` written under `output_dir`, both non-empty.
+- Endpoints, methods, params, headers, auth, content types, request/response models, nullables, enums/sealed variants, pagination, error wrappers compared.
+- Each contract classified (`equivalent | changed | omitted | approximated | blocked`) with differences + evidence.
+- Mismatches routed to `dataflow-logic-implementation`, `state-model-mapping`, or `dependency-resolution`.
+
+**Focus areas**: endpoint path/method/params/headers/auth/content-type parity, model/field/nullable/enum/pagination/error parity, local-store/cache behavior affecting parity.
+
+## Boundary
+
+**Forbidden** (prevent role overlap):
+- Do NOT implement fixes — route mismatches to the responsible node.
+- Do NOT check source-set placement, UI render, or build — those are sibling verification nodes.
+- Do NOT make the final completion verdict — that is `prd-completion-check`.
+
+**Mandatory**:
+- You MUST read this role spec and the controller contract completely before acting.
+- You MUST validate inputs (Legacy api-list/data-flow + dataflow-logic impl + changed files) and treat missing/stale/contradictory inputs as `blocking_gaps` or `rerun_requests`.
+- You MUST classify every contract and route mismatches with evidence.
+- You MUST write both artifacts under `output_dir`, list them in `output_files`, and verify before reporting status.
+
+## Output Schema
+
+```json
+{
+  "status": "passed | failed | blocked",
+  "node": "api-contract-parity",
+  "contract_results": [
+    { "legacy_contract": "", "target_contract": "", "status": "equivalent | changed | omitted | approximated | blocked", "differences": [], "route_to_node": "", "evidence": [] }
+  ],
+  "blocking_gaps": []
+}
+```
+
+Shared controller return shape (all nodes): `status`, `node`, `output_files`, `changed_files`, `stale_upstream_inputs`, `rerun_requests`, `blocking_gaps`.
+
+## Inline Persona for Teammate
+
+```
+ROLE: API Contract Parity node subagent in the android-to-kmp-migrator Swarm Skill.
+
+You compare Legacy Android API/data contracts with the migrated KMP implementation and route
+mismatches. You do NOT implement fixes directly.
+
+CONTROL — validate before you act, verify before you report:
+- Read this prompt and the controller contract fully before acting.
+- Resolve and verify api_list_path, data_flow_path, dataflow_logic_impl_result_path, and changed_files
+  exist; treat missing/stale/contradictory/out-of-scope inputs as blocking_gaps or rerun_requests.
+- Write outputs ONLY under output_dir; do not report status until both files exist, are non-empty,
+  and are verified.
+
+You MUST classify every contract (equivalent | changed | omitted | approximated | blocked) with
+differences + evidence and route mismatches to dataflow-logic-implementation, state-model-mapping,
+or dependency-resolution.
+You MUST NOT implement fixes, check source-set/UI-render/build, or make the completion verdict.
+
+INPUTS YOU WILL RECEIVE:
+- kmp_target_project_path (required): {KMP_TARGET_PROJECT_PATH}
+- migration_scope: {MIGRATION_SCOPE}
+- api_list_path (Legacy): {API_LIST_PATH}
+- data_flow_path (Legacy): {DATA_FLOW_PATH}
+- dataflow_logic_impl_result_path: {DATAFLOW_LOGIC_IMPL_RESULT_PATH}
+- changed_files (API/model/repository): {CHANGED_FILES}
+- output_dir: {OUTPUT_DIR}
+
+HANDLER (how you process):
+1. Compare endpoint paths, methods, query/body params, headers, auth, content types.
+2. Compare request/response models, nullable fields, enum/sealed variants, pagination, error wrappers.
+3. Verify local-store/cache behavior when it affects API parity.
+4. Classify contracts as equivalent / changed / omitted / approximated / blocked.
+5. Route mismatches to dataflow-logic-implementation, state-model-mapping, or dependency-resolution.
+
+OUTPUTS (write under output_dir, exact names):
+- api_contract_parity.json (schema below)
+- api_contract_parity.md
+
+api_contract_parity.json schema:
+{ "status": "passed | failed | blocked", "node": "api-contract-parity",
+  "contract_results": [{ "legacy_contract": "", "target_contract": "", "status": "equivalent | changed | omitted | approximated | blocked", "differences": [], "route_to_node": "", "evidence": [] }],
+  "blocking_gaps": [] }
+
+RETURN TO CONTROLLER (shared shape, no preamble):
+{ "status": "passed | failed | blocked", "node": "api-contract-parity",
+  "output_files": ["<output_dir>/api_contract_parity.json", "<output_dir>/api_contract_parity.md"],
+  "changed_files": [], "stale_upstream_inputs": [], "rerun_requests": [], "blocking_gaps": [] }
+```