@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-architecture/SKILL.md

@@ -1,500 +1,484 @@
 ---
 name: swift-architecture
-description: "Select, implement, or migrate between app architecture patterns for Apple platform apps. Use when choosing between MV (Model-View with @Observable), MVVM, MVI, TCA (The Composable Architecture), Clean Architecture, VIPER, or Coordinator patterns; when evaluating architecture fit for a feature's complexity; when migrating from one pattern to another; or when reviewing whether an app's current architecture is appropriate. Scoped to Apple-platform patterns using Swift 6.3, SwiftUI, and UIKit."
+description: "App architecture on Apple platforms (Swift 6.3, SwiftUI, UIKit): MV with @Observable, MVVM, MVI, TCA, Clean Architecture, VIPER, Coordinator, module boundaries, dependency direction. Use when selecting, implementing or migrating between patterns, judging whether a feature's complexity justifies a heavier one, or reviewing whether an app's architecture fits. Not for SwiftUI state wrappers, navigation, concurrency diagnostics or test syntax."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
+
 # Swift Architecture
 
-Select and implement the right architecture pattern for Apple platform apps built with Swift 6.3 and SwiftUI or UIKit.
-
-## Contents
-
-- [Scope Boundary](#scope-boundary)
-- [Architecture Selection](#architecture-selection)
-- [MV Pattern (Model-View with `@Observable`)](#mv-pattern)
-- [MVVM](#mvvm)
-- [MVI (Model-View-Intent)](#mvi)
-- [TCA (The Composable Architecture)](#tca)
-- [Clean Architecture](#clean-architecture)
-- [Coordinator Pattern](#coordinator-pattern)
-- [VIPER](#viper)
-- [Migration Between Patterns](#migration-between-patterns)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-
-## Scope Boundary
-
-This skill owns architecture-level decisions: pattern selection, module
-boundaries, dependency direction, migration/escalation strategy, and structural
-test strategy. It does not own SwiftUI state mechanics; route `@State`,
-`@Bindable`, `@Environment`, edit-sheet/local state, bindings, view composition,
-and `@Observable` MV implementation mechanics to `swiftui-patterns`. Use
-`swiftui-navigation` for `NavigationStack`, `NavigationSplitView`,
-`NavigationPath`, route models, sheets, tabs, and deep-link URL handling;
-`swift-concurrency` for `@MainActor`, default MainActor isolation, `Sendable`,
-strict-concurrency diagnostics, and data-race diagnostics; and `swift-testing`
-for `@Test`, `#expect`, `#require`, fixtures, parameterized tests, mocks, stubs,
-and suite organization.
-
-## Architecture Selection
-
-| Pattern | Best For | Complexity | Testability |
-|---------|----------|-----------|-------------|
-| **MV** | Small-to-medium SwiftUI apps, rapid iteration | Low | Moderate |
-| **MVVM** | Medium apps, teams familiar with reactive patterns | Medium | High |
-| **MVI** | Complex state machines, predictable state flow | Medium-High | High |
-| **TCA** | Large apps needing composable features, strong testing | High | Very High |
-| **Clean Architecture** | Enterprise apps, strict separation of concerns | High | Very High |
-| **Coordinator** | Apps with complex navigation flows (UIKit or hybrid) | Medium | High |
-| **VIPER** | Legacy UIKit modules already using VIPER boundaries | Very High | High |
-
-**Default recommendation for new SwiftUI apps:** Start with MV (Model-View
-with `@Observable`). Escalate to MVVM or TCA only when the feature's complexity
-demands it.
-
-Boundary-split answers should use one `swift-architecture` bucket for
-pattern/module/dependency/migration/test-strategy decisions. Do not add a
-separate architecture-owned "SwiftUI state ownership" bucket; property-wrapper,
-local binding, navigation, concurrency-diagnostic, fixture, and parameterized
-test mechanics are sibling-skill handoffs.
-
-### Decision Framework
-
-1. **Is the feature a simple CRUD screen?** → MV pattern
-2. **Does the screen have complex business logic separate from the view?** → MVVM
-3. **Do you need deterministic state transitions and side-effect management?** → MVI or TCA
-4. **Is the app large with many independent feature modules?** → TCA or Clean Architecture
-5. **Is navigation complex with deep linking and conditional flows?** → Add Coordinator pattern
-
-## MV Pattern
-
-The simplest SwiftUI architecture. The view observes `@Observable` models
-directly. No intermediate view model layer.
+Which structure a Swift app or feature should have, and how to move from one
+structure to another without a rewrite. Examples are written for Swift 6.3; they use
+SwiftUI with Observation (iOS 17 or later) unless a UIKit type appears.
 
-```swift
-import Observation
-import SwiftUI
+## Scope boundary
+
+This skill decides:
+
+- which pattern a feature uses,
+- where module boundaries fall and which way dependencies point,
+- how to migrate or escalate between patterns,
+- the test strategy at the structural level (what is unit-testable, and where).
+
+It hands off the mechanics:
+
+| Topic | Skill |
+| --- | --- |
+| `@State`, `@Bindable`, `@Environment`, bindings, local and edit-sheet state, view composition, the mechanics of MV with `@Observable` | `swiftui-patterns` |
+| `NavigationStack`, `NavigationSplitView`, paths, route models, sheets, tabs, deep links | `swiftui-navigation` |
+| `@MainActor`, default main-actor isolation, `Sendable`, strict-concurrency and data-race diagnostics | `swift-concurrency` |
+| Swift Testing syntax (`@Test`, `#expect`, `#require`), fixtures, parameterized cases, test doubles, suite layout | `swift-testing` |
+
+When one question touches several of these, answer the architecture part in a
+single block (pattern, modules, dependency direction, migration, test
+strategy). There is no extra block here for how SwiftUI views hold state;
+property wrappers, bindings, navigation wiring, concurrency errors, fixtures and
+parameterized tests are answered by the skills in the table.
+
+## Architecture selection
+
+| Pattern | Good match | Cost to adopt | How testable |
+| --- | --- | --- | --- |
+| MV (`@Observable` models) | Small or mid-sized SwiftUI apps where speed of change matters | Low | Moderate |
+| MVVM | Mid-sized apps; teams at home with reactive view models | Medium | High |
+| MVI | Features that are really state machines and need a predictable flow | Medium to high | High |
+| TCA | Big apps built from composable features, with heavy testing | High | Very high |
+| Clean Architecture | Enterprise codebases that require strict layer separation | High | Very high |
+| Coordinator | Involved navigation in UIKit or mixed UIKit and SwiftUI apps | Medium | High |
+| VIPER | UIKit modules that were already built as VIPER | Very high | High |
 
+Default for a new SwiftUI app: MV with `@Observable`. Escalate to MVVM, and
+later TCA, when the feature has grown enough to need it, not before.
+
+### Decision framework
+
+- A simple CRUD screen: **MV**.
+- Business logic that should live apart from the view: **MVVM**.
+- State transitions that must be deterministic, with side effects managed
+  explicitly: **MVI** or **TCA**.
+- Dozens of separately owned feature modules in one app: **TCA** or **Clean
+  Architecture**.
+- Navigation with deep links and conditional flows: add a **Coordinator** on
+  top of whichever pattern the features use (in pure SwiftUI, prefer path-based
+  routing first; see Coordinator below).
+
+## MV pattern
+
+Views read `@Observable` model objects themselves; nothing sits between them.
+
+```swift
 @MainActor
 @Observable
-final class TripStore {
-    var trips: [Trip] = []
-    var isLoading = false
-    var error: Error?
+final class WorkoutLog {
+    private(set) var sessions: [Workout] = []
+    private(set) var loading = false
+    var lastError: (any Error)?
 
-    private let service: TripService
+    private let store: any WorkoutStore
 
-    init(service: TripService) {
-        self.service = service
-    }
+    init(store: any WorkoutStore) { self.store = store }
 
-    func loadTrips() async {
-        isLoading = true
-        defer { isLoading = false }
-        do {
-            trips = try await service.fetchTrips()
-        } catch {
-            self.error = error
-        }
+    func refresh() async {
+        loading = true
+        defer { loading = false }
+        do { sessions = try await store.allWorkouts() }
+        catch { lastError = error }
     }
 
-    func deleteTrip(_ trip: Trip) async throws {
-        try await service.delete(trip)
-        trips.removeAll { $0.id == trip.id }
+    func remove(_ workout: Workout) async throws {
+        try await store.delete(workout.id)
+        sessions.removeAll { $0.id == workout.id }
     }
 }
 
-struct TripsView: View {
-    @State private var store = TripStore(service: .live)
+struct WorkoutLogScreen: View {
+    @State private var log: WorkoutLog
+
+    init(store: any WorkoutStore) {
+        _log = State(initialValue: WorkoutLog(store: store))
+    }
 
     var body: some View {
-        List(store.trips) { trip in
-            TripRow(trip: trip)
-        }
-        .task { await store.loadTrips() }
+        let entries = log.sessions
+        return List(entries) { Text($0.title) }
+            .overlay { if log.loading { ProgressView() } }
+            .task { await log.refresh() }
     }
 }
 ```
 
-**When MV is enough:** Single-screen features, prototype/MVP, small teams,
-straightforward data flow.
+The view owns the model with `@State` and loads it in `.task`. The dependency
+comes in through the initializer, never created inside the model.
 
-**When to upgrade:** Business logic grows complex, unit testing the view's
-behavior becomes difficult, multiple views need to share and transform the
-same state differently.
+MV is enough for single-screen features, prototypes and MVPs, small teams and
+straightforward data flow. Move on when business logic keeps growing, when view
+behaviour becomes hard to unit test, or when several views need different
+transformations of the same shared state.
 
 ## MVVM
 
-Separates view logic into a `ViewModel` that the view observes. The view model
-transforms model data for display and handles user actions.
+A view model sits between the view and the model: it prepares display values
+and receives user actions, and the view watches it.
 
 ```swift
+struct WorkoutRow: Identifiable {
+    let id: Workout.ID
+    let title: String
+    let when: String
+
+    init(_ workout: Workout) {
+        id = workout.id
+        title = workout.title
+        when = workout.start.formatted(.dateTime.month().day())
+    }
+}
+
 @MainActor
 @Observable
-final class TripListViewModel {
-    private(set) var trips: [TripRowItem] = []
-    private(set) var isLoading = false
-    var searchText = ""
-
-    var filteredTrips: [TripRowItem] {
-        guard !searchText.isEmpty else { return trips }
-        return trips.filter { $0.name.localizedStandardContains(searchText) }
-    }
+final class WorkoutListModel {
+    private(set) var rows: [WorkoutRow] = []
+    private(set) var loading = false
+    var filter = ""
 
-    private let repository: TripRepository
+    private var all: [Workout] = []
+    private let store: any WorkoutStore
 
-    init(repository: TripRepository) {
-        self.repository = repository
-    }
+    init(store: any WorkoutStore) { self.store = store }
 
-    func loadTrips() async {
-        isLoading = true
-        defer { isLoading = false }
-        let models = (try? await repository.fetchAll()) ?? []
-        trips = models.map { TripRowItem(from: $0) }
+    var visibleRows: [WorkoutRow] {
+        filter.isEmpty ? rows : rows.filter { $0.title.localizedStandardContains(filter) }
     }
 
-    func delete(at offsets: IndexSet) async {
-        let toDelete = offsets.map { filteredTrips[$0] }
-        for item in toDelete {
-            try? await repository.delete(id: item.id)
-        }
-        await loadTrips()
+    func load() async {
+        loading = true
+        defer { loading = false }
+        all = (try? await store.allWorkouts()) ?? []
+        rows = all.map(WorkoutRow.init)
     }
-}
-
-struct TripRowItem: Identifiable {
-    let id: UUID
-    let name: String
-    let dateRange: String
 
-    init(from trip: Trip) {
-        self.id = trip.id
-        self.name = trip.name
-        self.dateRange = trip.startDate.formatted(.dateTime.month().day())
-            + " - " + trip.endDate.formatted(.dateTime.month().day())
+    func delete(rowsAt positions: IndexSet) async {
+        let doomed = positions.map { visibleRows[$0].id }
+        for id in doomed { try? await store.delete(id) }
+        await load()
     }
 }
 
-struct TripListView: View {
-    @State private var viewModel: TripListViewModel
+struct WorkoutListScreen: View {
+    @State private var model: WorkoutListModel
 
-    init(repository: TripRepository) {
-        _viewModel = State(initialValue: TripListViewModel(repository: repository))
+    init(store: any WorkoutStore) {
+        _model = State(initialValue: WorkoutListModel(store: store))
     }
 
     var body: some View {
         List {
-            ForEach(viewModel.filteredTrips) { item in
-                Text(item.name)
-            }
-            .onDelete { offsets in
-                Task { await viewModel.delete(at: offsets) }
+            ForEach(model.visibleRows, id: \.id) { row in
+                LabeledContent(row.title, value: row.when)
             }
+            .onDelete { positions in Task { await model.delete(rowsAt: positions) } }
         }
-        .searchable(text: $viewModel.searchText)
-        .task { await viewModel.loadTrips() }
+        .searchable(text: $model.filter)
+        .task { await model.load() }
     }
 }
 ```
 
-**Testing a ViewModel:**
+The payoff is a view model you can test without any view:
 
 ```swift
-@Test func filteredTripsMatchesSearch() async {
-    let repo = MockTripRepository(trips: [
-        Trip(name: "Paris"), Trip(name: "Tokyo"), Trip(name: "Paris TX")
-    ])
-    let vm = TripListViewModel(repository: repo)
-    await vm.loadTrips()
-    vm.searchText = "Paris"
-    #expect(vm.filteredTrips.count == 2)
+@Test @MainActor
+func filterMatchesTitle() async {
+    let model = WorkoutListModel(store: FakeWorkoutStore(titles: ["Row", "Run", "Swim"]))
+    await model.load()
+    model.filter = "ru"
+    #expect(model.visibleRows.count == 1)
 }
 ```
 
 ## MVI
 
-Unidirectional data flow: views dispatch **intents**, a **reducer** produces
-new **state**, and **side effects** are handled explicitly.
+Data moves one way. The view emits intents, a single function applies each
+intent to the state, and any work with side effects is spelled out there.
 
 ```swift
 @MainActor
 @Observable
-final class TripListStore {
-    private(set) var state = State()
-
+final class WorkoutFeed {
     struct State {
-        var trips: [Trip] = []
-        var isLoading = false
-        var error: String?
+        var sessions: [Workout] = []
+        var loading = false
+        var message: String?
     }
 
     enum Intent {
-        case loadTrips
-        case deleteTrip(Trip)
-        case clearError
+        case appeared
+        case remove(Workout.ID)
+        case dismissMessage
     }
 
-    private let service: TripService
+    private(set) var state = State()
+    private let store: any WorkoutStore
 
-    init(service: TripService) {
-        self.service = service
-    }
+    init(store: any WorkoutStore) { self.store = store }
 
     func send(_ intent: Intent) {
-        Task { await handle(intent) }
+        Task { await apply(intent) }
     }
 
-    private func handle(_ intent: Intent) async {
-        switch intent {
-        case .loadTrips:
-            state.isLoading = true
+    private func apply(_ next: Intent) async {
+        switch next {
+        case .appeared:
+            state.loading = true
+            do { state.sessions = try await store.allWorkouts() }
+            catch { state.message = error.localizedDescription }
+            state.loading = false
+        case .remove(let id):
             do {
-                state.trips = try await service.fetchTrips()
+                try await store.delete(id)
+                state.sessions.removeAll { $0.id == id }
             } catch {
-                state.error = error.localizedDescription
+                state.message = error.localizedDescription
             }
-            state.isLoading = false
-
-        case .deleteTrip(let trip):
-            try? await service.delete(trip)
-            state.trips.removeAll { $0.id == trip.id }
-
-        case .clearError:
-            state.error = nil
+        case .dismissMessage:
+            state.message = nil
         }
     }
 }
 ```
 
-**Advantages:** Predictable state transitions, easy to log/replay intents,
-clear separation of "what happened" from "what changed."
+What it buys: every transition is predictable, intents can be logged and
+replayed, and "what happened" (the intent) is kept apart from "what changed"
+(the state).
 
 ## TCA
 
-The Composable Architecture (Point-Free) provides composable reducers,
-dependency injection, exhaustive testing, and structured side effects.
-
-Docs: [TCA](https://sosumi.ai/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/main/documentation/composablearchitecture)
+The Composable Architecture is an open-source library. Features are reducers
+that compose; dependencies are injected through a registry; effects are values
+the store runs; tests can assert every state change exhaustively.
 
 ```swift
 import ComposableArchitecture
 
 @Reducer
-struct TripList {
+struct WorkoutsFeature {
     @ObservableState
     struct State: Equatable {
-        var trips: IdentifiedArrayOf<Trip> = []
-        var isLoading = false
-        var errorMessage: String?
+        var sessions: IdentifiedArrayOf<Workout> = []
+        var loading = false
     }
 
     enum Action {
         case onAppear
-        case tripsLoaded([Trip])
-        case tripsFailed(String)
-        case deleteTrip(Trip.ID)
+        case loaded([Workout])
+        case removeTapped(Workout.ID)
     }
 
-    @Dependency(\.tripClient) var tripClient
+    @Dependency(\.workoutClient) var workoutClient
 
     var body: some ReducerOf<Self> {
         Reduce { state, action in
             switch action {
-            case .onAppear:
-                state.isLoading = true
-                state.errorMessage = nil
+            case .onAppear where !state.loading:
+                state.loading = true
                 return .run { send in
-                    do {
-                        let trips = try await tripClient.fetchAll()
-                        await send(.tripsLoaded(trips))
-                    } catch {
-                        await send(.tripsFailed(error.localizedDescription))
-                    }
+                    let sessions = try await workoutClient.fetchAll()
+                    await send(.loaded(sessions))
                 }
-            case .tripsLoaded(let trips):
-                state.trips = IdentifiedArray(uniqueElements: trips)
-                state.isLoading = false
+            case .loaded(let sessions):
+                state.loading = false
+                state.sessions = IdentifiedArray(uniqueElements: sessions)
                 return .none
-            case .tripsFailed(let message):
-                state.errorMessage = message
-                state.isLoading = false
+            case .onAppear:
                 return .none
-            case .deleteTrip(let id):
-                state.trips.remove(id: id)
-                return .run { _ in try await tripClient.delete(id) }
+            case .removeTapped(let id):
+                state.sessions.remove(id: id)
+                return .run { [id] _ in
+                    try await workoutClient.delete(id)
+                }
             }
         }
     }
 }
 ```
 
-**Use TCA when:** You need deterministic state transitions for complex state
-flows, structured side-effect sequencing, feature composition, strong reducer
-testing, or app-wide dependency injection.
+Choose it for complex flows that must be deterministic, effects that need
+sequencing, features composed from smaller features, reducer-level testing, and
+dependency injection across the whole app.
 
 ## Clean Architecture
 
-Layers: **Domain** (entities, use cases, repository protocols) → **Data**
-(repository implementations, network, persistence) → **Presentation** (views,
-view models). Dependencies point inward.
+Three layers with dependencies pointing inward:
+
+- **Domain**: the entities, the use cases, and the protocols repositories must
+  satisfy. It imports no UI or persistence framework.
+- **Data**: repository implementations, networking, persistence.
+- **Presentation**: views and view models.
 
 ```swift
-// Domain layer
-protocol TripRepository: Sendable {
-    func fetchAll() async throws -> [Trip]
-    func save(_ trip: Trip) async throws
-    func delete(id: UUID) async throws
+// Domain
+protocol WorkoutRepository: Sendable {
+    func fetchAll() async throws -> [Workout]
+    func save(_ workout: Workout) async throws
+    func delete(_ id: Workout.ID) async throws
 }
 
-struct FetchUpcomingTripsUseCase: Sendable {
-    private let repository: TripRepository
-
-    init(repository: TripRepository) {
-        self.repository = repository
-    }
+struct UpcomingWorkouts: Sendable {
+    let repository: any WorkoutRepository
 
-    func execute() async throws -> [Trip] {
-        try await repository.fetchAll()
-            .filter { $0.startDate > .now }
-            .sorted { $0.startDate < $1.startDate }
+    func callAsFunction(after now: Date = .now) async throws -> [Workout] {
+        let everything = try await repository.fetchAll()
+        return everything
+            .filter { $0.start > now }
+            .sorted { $0.start < $1.start }
     }
 }
 
-// Data layer
-struct RemoteTripRepository: TripRepository {
-    private let client: APIClient
+// Data
+struct RemoteWorkoutRepository: WorkoutRepository {
+    let api: FitnessAPI
 
-    func fetchAll() async throws -> [Trip] {
-        try await client.request(.get, "/trips")
-    }
-    // ...
+    func fetchAll() async throws -> [Workout] { try await api.get("/workouts") }
+    func save(_ workout: Workout) async throws { try await api.post("/workouts", body: workout) }
+    func delete(_ id: Workout.ID) async throws { try await api.delete("/workouts/\(id)") }
 }
 
-// Presentation layer
+// Presentation
 @MainActor
 @Observable
-final class UpcomingTripsViewModel {
-    private(set) var trips: [Trip] = []
-    private let useCase: FetchUpcomingTripsUseCase
+final class PlannerModel {
+    private(set) var upcoming: [Workout] = []
+    private let upcomingWorkouts: UpcomingWorkouts
 
-    init(useCase: FetchUpcomingTripsUseCase) {
-        self.useCase = useCase
-    }
+    init(upcomingWorkouts: UpcomingWorkouts) { self.upcomingWorkouts = upcomingWorkouts }
 
-    func load() async {
-        trips = (try? await useCase.execute()) ?? []
-    }
+    func load() async { upcoming = (try? await upcomingWorkouts()) ?? [] }
 }
 ```
 
-**Use Clean Architecture when:** Strict separation is required (enterprise,
-regulated domains), the domain layer must be testable without any framework
-dependencies, or multiple presentation targets share the same business logic.
-
-## Coordinator Pattern
-
-Separates navigation logic from views. Especially useful in UIKit or hybrid
-apps with complex navigation flows.
-
-Keep Coordinators `@MainActor`, inject dependencies at coordinator creation,
-and pass user-selection callbacks from view models or controllers back to the
-coordinator. The coordinator owns push/modal decisions; feature models own
-business logic.
-
-In pure SwiftUI apps, `NavigationStack` with path-based routing often
-replaces the Coordinator pattern. Use Coordinators when you need UIKit
-integration or shared navigation logic across platforms.
-
-## VIPER
+Reach for it when rules or regulation demand hard separation, when domain code
+has to be tested with no framework present, or when an app, a widget and a
+watch app all run one set of business rules.
 
-VIPER splits a feature into **View**, **Interactor**, **Presenter**,
-**Entity**, and **Router** roles. Treat it as a maintenance pattern for apps
-that already have strict UIKit module boundaries rather than a default for new
-SwiftUI work.
+## Coordinator pattern
 
-**Use VIPER when:** An existing UIKit codebase already organizes screens as
-VIPER modules, teams need explicit handoff contracts between presentation,
-business logic, and routing, or a migration must preserve module boundaries
-while modernizing internals.
+Coordinators take navigation out of views and controllers. They pay off mostly
+in UIKit and hybrid apps.
 
-**Avoid VIPER when:** A new SwiftUI feature can use MV, MVVM, TCA, or Clean
-Architecture with fewer files and clearer data flow.
-
-## Migration Between Patterns
-
-### ObservableObject → `@Observable`
+- A coordinator is `@MainActor` and receives its dependencies when it is
+  created.
+- View models and view controllers report user choices through callbacks; the
+  coordinator decides whether to push or present.
+- Feature models keep the business logic. The coordinator only routes.
 
 ```swift
-// Before (iOS 16)
-class TripStore: ObservableObject {
-    @Published var trips: [Trip] = []
-}
-// View uses @ObservedObject or @StateObject
-
-// After (iOS 17+)
 @MainActor
-@Observable
-final class TripStore {
-    var trips: [Trip] = []
-}
-// View uses @State for owned; plain injection or @Bindable only when needed
-```
-
-Migration routing: keep Coordinators for UIKit or hybrid boundaries; pure
-SwiftUI flows usually own `NavigationStack`/path state. Route detailed route
-enums, `NavigationSplitView`, sheets, tabs, and deep links to
-`swiftui-navigation`, strict-concurrency diagnostics to `swift-concurrency`,
-and fixtures or parameterized tests to `swift-testing`. Migrate per feature module, not app-wide by default; keep each module internally consistent while allowing different modules to use different patterns during incremental adoption.
-
-### MVVM → MV (simplifying)
+final class OnboardingCoordinator {
+    private let navigation: UINavigationController
+    private let account: AccountService
 
-If a view model only passes through model data without transforming it,
-remove the view model and let the view observe the model directly.
-
-### MV → MVVM (scaling up)
-
-Extract business logic and data transformation into a view model when:
-- The view's `body` contains conditional logic for data formatting
-- Multiple views need different projections of the same model
-- You need to test logic without instantiating views
+    init(navigation: UINavigationController, account: AccountService) {
+        self.navigation = navigation
+        self.account = account
+    }
 
-### Any → TCA
+    func start() {
+        let welcome = WelcomeViewController(onContinue: { [weak self] in self?.showSignUp() })
+        navigation.setViewControllers([welcome], animated: false)
+    }
 
-TCA adoption is typically incremental: wrap one feature's state and actions
-in a `Reducer`, migrate its dependencies to `@Dependency`, and test.
+    private func showSignUp() {
+        let form = SignUpViewController(account: account, onDone: { [weak self] in self?.finish() })
+        navigation.pushViewController(form, animated: true)
+    }
 
-## Common Mistakes
+    private func finish() { navigation.dismiss(animated: true) }
+}
+```
 
-| Mistake | Fix |
-|---------|-----|
-| Using `ObservableObject` in new iOS 17+ code | Use `@Observable`; isolate UI-observed app state to `@MainActor` for Swift 6 data-race safety |
-| View model that only forwards model properties | Remove the view model; use MV pattern |
-| Massive view model with navigation, networking, and formatting | Split into focused collaborators (coordinator, service, formatter) |
-| Choosing TCA for a two-screen app | Start with MV; adopt TCA when composition and testing demands justify it |
-| Protocol-heavy Clean Architecture for a simple feature | Match architecture complexity to feature complexity |
-| Coordinator pattern in pure SwiftUI without UIKit needs | Use `NavigationStack` path-based routing instead |
-| Starting new SwiftUI modules with VIPER | Reserve VIPER for legacy UIKit maintenance or strict module-boundary migrations |
-| Mixing architecture patterns inside one feature module | Keep one pattern inside each feature module; migrate different modules independently when needed |
+In a pure SwiftUI app, a `NavigationStack` driven by a path usually does this
+job without a coordinator. Keep coordinators for UIKit integration or for
+navigation logic shared across platforms.
 
-## Review Checklist
+## VIPER
 
-- [ ] Architecture choice is justified by feature complexity and team needs
-- [ ] Architecture identifies the model/store owner; `@State`, plain injection, and `@Bindable` wiring hand off to `swiftui-patterns`
-- [ ] Dependencies are injected, not created internally (testability)
-- [ ] SwiftUI MV mechanics, `NavigationSplitView`, strict-concurrency diagnostics, fixtures, and parameterized tests hand off to sibling skills explicitly
-- [ ] State mutations happen in a clear, auditable location
-- [ ] View models (if present) are testable without views
-- [ ] No god objects  -  responsibilities are distributed appropriately
-- [ ] Pattern is consistent within each feature module, including during migrations
+View, Interactor, Presenter, Entity, Router. Its value today is keeping
+existing UIKit modules with hard boundaries maintainable; it is not where new
+SwiftUI work should begin.
+
+Use it when an existing UIKit codebase is already organized into VIPER modules,
+when teams depend on its explicit handoff contracts, or when a migration has to
+keep those module boundaries intact. For new SwiftUI features, pick one of the
+lighter patterns above; they need far fewer files for the same result.
+
+## Migration between patterns
+
+### ObservableObject to @Observable
+
+| Before (iOS 16) | After (iOS 17+) |
+| --- | --- |
+| `class Model: ObservableObject` with `@Published` properties | `@MainActor @Observable final class Model` with plain stored properties |
+| `@StateObject var model` | `@State private var model` for a model the view owns |
+| `@ObservedObject var model` | A plain `let` or `var` property for an injected model the view only reads |
+| `$model.property` bindings through `@ObservedObject` | `@Bindable var model` only where a binding is needed |
+
+The wiring details belong to `swiftui-patterns`.
+
+### Routing during a migration
+
+- Keep coordinators at UIKit and hybrid boundaries; let pure SwiftUI areas own
+  a path-driven `NavigationStack`.
+- Anything about route enums, split views, sheet or tab presentation, or deep
+  link handling goes to `swiftui-navigation`.
+- Isolation and `Sendable` errors that appear during the move go to
+  `swift-concurrency`.
+- Test fixtures and parameterized tests go to `swift-testing`.
+
+### Strategy
+
+Migrate one feature module at a time, not the whole app at once. Each module
+stays internally consistent; different modules may use different patterns
+while adoption is in progress.
+
+- **MVVM to MV**: delete view models that only forward model properties.
+- **MV to MVVM**: when `body` fills up with formatting conditionals, when two
+  screens want the same data shaped differently, or when logic must be tested
+  without a view.
+- **Any pattern to TCA**: go incrementally. Pick one feature, express its state
+  and actions as a `Reducer`, move what it depends on behind `@Dependency`,
+  cover it with tests, then take the next feature.
+
+## Common mistakes
+
+| Symptom | Fix |
+| --- | --- |
+| New iOS 17+ code still built on `ObservableObject` | Switch to `@Observable` and keep state the UI reads on `@MainActor`, which Swift 6 needs to rule out data races |
+| A view model whose properties just mirror the model | Delete the layer; MV is enough |
+| One oversized view model that routes, fetches and formats | Give routing, fetching and formatting to separate collaborators |
+| TCA adopted for an app with two screens | Begin with MV and escalate later |
+| Protocols and layers everywhere for a small feature | Size the structure to the problem |
+| Coordinators in an all-SwiftUI app with no UIKit | Let a path-driven `NavigationStack` route |
+| VIPER chosen for a brand-new SwiftUI module | Leave VIPER to the legacy code |
+| Two or three patterns mixed in one feature module | Settle on one per module |
+
+## Review checklist
+
+- [ ] The pattern is justified by the feature's complexity and the team's needs
+- [ ] Each model or store has a named owner; the `@State`, injection and `@Bindable` details are left to `swiftui-patterns`
+- [ ] Models receive their dependencies; they never construct them
+- [ ] Handoffs are explicit: MV wiring, split view layout, concurrency errors, fixtures and parameterized tests each point at their skill
+- [ ] State changes happen in one clear, auditable place
+- [ ] View models and stores can be exercised in tests with no view involved
+- [ ] No single object has taken over the feature
+- [ ] Each feature module uses one pattern consistently, including mid-migration
 
 ## References
 
-- Apple docs: [Observation](https://sosumi.ai/documentation/observation) | [Observable](https://sosumi.ai/documentation/observation/observable())
-- Apple docs: [Migrating from ObservableObject to Observable](https://sosumi.ai/documentation/swiftui/migrating-from-the-observable-object-protocol-to-the-observable-macro)
-- Apple docs: [`State`](https://sosumi.ai/documentation/swiftui/state) | [`Bindable`](https://sosumi.ai/documentation/swiftui/bindable) | [`Environment`](https://sosumi.ai/documentation/swiftui/environment)
-- Apple docs: [`NavigationStack`](https://sosumi.ai/documentation/swiftui/navigationstack)
-- Apple docs: [Swift Testing](https://sosumi.ai/documentation/testing)
-- TCA docs: [ComposableArchitecture](https://sosumi.ai/external/https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/main/documentation/composablearchitecture)
+- [Observation](https://developer.apple.com/documentation/observation)
+- [Observable()](https://developer.apple.com/documentation/observation/observable())
+- [Migrating from the Observable Object protocol to the Observable macro](https://developer.apple.com/documentation/swiftui/migrating-from-the-observable-object-protocol-to-the-observable-macro)
+- [State](https://developer.apple.com/documentation/swiftui/state)
+- [Bindable](https://developer.apple.com/documentation/swiftui/bindable)
+- [Environment](https://developer.apple.com/documentation/swiftui/environment)
+- [NavigationStack](https://developer.apple.com/documentation/swiftui/navigationstack)
+- [Swift Testing](https://developer.apple.com/documentation/testing)
+- [The Composable Architecture documentation](https://swiftpackageindex.com/pointfreeco/swift-composable-architecture/main/documentation/composablearchitecture)