winforms-to-avalonia

name

winforms-to-avalonia

description

Orchestrate a phased WinForms-to-Avalonia migration: behavior contracts, UI-independent application logic, platform adapters, MVVM shell, parity/cutover, evolution, and hardening. Use when the request explicitly involves moving a WinForms or .NET Framework desktop UI to Avalonia, or continuing that migration. Do not trigger for unrelated migrations, rewrites, ViewModel refactors, settings work, or command-line work without WinForms-to-Avalonia context. Load this orchestrator before one matching phase skill.

WinForms -> Avalonia (generic orchestrator)

Rewrite for behavior contracts and layered architecture, not control-for-control ports. WinForms handlers and Designer state are evidence of what users can do; Avalonia Views only present ViewModel state.

Suite (A–G)

Phase	Skill	Generic outcome
A	wfa-capture-contracts	Inventory, modules, command contracts, coverage matrix, capability split
B	wfa-extract-domain	UI-independent application core, boundary ports, TDD
C	wfa-platform-services	Platform and infrastructure adapters
D	wfa-avalonia-ui	Composition root, MVVM, bindings, secondary tools
E	wfa-parity-verify	Diff matrix, acceptance, packaging, trunk/cutover
F	wfa-post-port-evolve	Product evolution without reintroducing legacy coupling
G	wfa-harden-decompose	State decomposition, resilience, security review, test isolation

Shared references (all product-agnostic):

• references/lifecycle-full.md — A–G journey and gates
• references/phase-roadmap.md — critical path and parallelism
• references/architecture-blueprint.md — layering and composition
• references/anti-patterns.md — port and long-term smells
• references/reusable-learnings.md — distilled rules of thumb
• references/execution-corrections.md — how humans correct agents mid-migration (read this)

Route work

1. Locate the legacy tree, target runtime, repository guidance, and existing migration artifacts.
2. Inventory actual product capabilities before proposing abstractions or project boundaries.
3. Choose a phase from the evidence below.
4. Load one phase skill and only the references needed for that work.
5. Use the repository's specification workflow per capability slice when applicable.

Situation	Phase
No contracts / file coverage map	A
Business rules or use-case orchestration still inside Forms/helpers	B
Filesystem, process, dialogs, settings, or OS APIs leak into the application core	C
UI event-driven / manual control refresh	D
Comparing old vs new / delete legacy?	E
Avalonia is the trunk; evolving discovered product capabilities	F
Oversized ViewModels, stale async results, security debt, mixed Headless host	G

Rules that always apply

1. Contracts before controls - command catalog, state transitions, external effects, and acceptance evidence.
2. Discover before abstracting - never assume a feature, integration, or storage mechanism exists.
3. Layering - the application core has no Avalonia/WinForms types; adapters own environment-specific effects.
4. Diagnostics over UI prompts below the presentation layer.
5. State over controls - bindings and application state are authoritative; do not scrape controls before commands.
6. Consistent behavior - one rule or option must produce the same semantics at every entry point and consumer.
7. Security before release - bound untrusted input, external resource access, and dynamic execution in the phase that introduces them.
8. Durable writes - version, validate, and atomically replace persisted state; preserve recoverable data on failure.
9. No source-text tests that grep implementation files; no file-existence-only unit tests.
10. Headless UI tests run in a separate project/process from non-UI unit tests.
11. Sequential tests when multiple projects share build outputs.
12. Legacy delete only after parity evidence and explicit decisions for every remaining gap.
13. Half-extractions are bugs - extracted types must own behavior or be removed.
14. Analyze then patch - establish the cause before changing architecture or adding fallbacks.
15. Clean cuts over dual paths when the target design has been chosen.
16. Firm specification decisions - do not leave incompatible designs simultaneously optional.
17. Tasks need evidence - code, behavior tests, and command output before marking done.

Handoff after each phase

• Artifacts and paths
• Specification/change status if used
• Gaps and decisions
• Next phase skill
• Tests run

For “do the whole migration,” still checkpoint after A and after B+C before large UI work.