@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

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

@@ -124,191 +124,33 @@ transformations of the same shared state.
 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 WorkoutListModel {
-    private(set) var rows: [WorkoutRow] = []
-    private(set) var loading = false
-    var filter = ""
-
-    private var all: [Workout] = []
-    private let store: any WorkoutStore
-
-    init(store: any WorkoutStore) { self.store = store }
-
-    var visibleRows: [WorkoutRow] {
-        filter.isEmpty ? rows : rows.filter { $0.title.localizedStandardContains(filter) }
-    }
-
-    func load() async {
-        loading = true
-        defer { loading = false }
-        all = (try? await store.allWorkouts()) ?? []
-        rows = all.map(WorkoutRow.init)
-    }
-
-    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 WorkoutListScreen: View {
-    @State private var model: WorkoutListModel
-
-    init(store: any WorkoutStore) {
-        _model = State(initialValue: WorkoutListModel(store: store))
-    }
-
-    var body: some View {
-        List {
-            ForEach(model.visibleRows, id: \.id) { row in
-                LabeledContent(row.title, value: row.when)
-            }
-            .onDelete { positions in Task { await model.delete(rowsAt: positions) } }
-        }
-        .searchable(text: $model.filter)
-        .task { await model.load() }
-    }
-}
-```
+The payoff is a view model you can test without any view.
 
-The payoff is a view model you can test without any view:
-
-```swift
-@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)
-}
-```
+Code for this section: [Architecture pattern examples](references/pattern-examples.md).
 
 ## MVI
 
 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 WorkoutFeed {
-    struct State {
-        var sessions: [Workout] = []
-        var loading = false
-        var message: String?
-    }
-
-    enum Intent {
-        case appeared
-        case remove(Workout.ID)
-        case dismissMessage
-    }
-
-    private(set) var state = State()
-    private let store: any WorkoutStore
-
-    init(store: any WorkoutStore) { self.store = store }
-
-    func send(_ intent: Intent) {
-        Task { await apply(intent) }
-    }
-
-    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 {
-                try await store.delete(id)
-                state.sessions.removeAll { $0.id == id }
-            } catch {
-                state.message = error.localizedDescription
-            }
-        case .dismissMessage:
-            state.message = nil
-        }
-    }
-}
-```
-
 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).
 
+Code for this section: [Architecture pattern examples](references/pattern-examples.md).
+
 ## TCA
 
 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 WorkoutsFeature {
-    @ObservableState
-    struct State: Equatable {
-        var sessions: IdentifiedArrayOf<Workout> = []
-        var loading = false
-    }
-
-    enum Action {
-        case onAppear
-        case loaded([Workout])
-        case removeTapped(Workout.ID)
-    }
-
-    @Dependency(\.workoutClient) var workoutClient
-
-    var body: some ReducerOf<Self> {
-        Reduce { state, action in
-            switch action {
-            case .onAppear where !state.loading:
-                state.loading = true
-                return .run { send in
-                    let sessions = try await workoutClient.fetchAll()
-                    await send(.loaded(sessions))
-                }
-            case .loaded(let sessions):
-                state.loading = false
-                state.sessions = IdentifiedArray(uniqueElements: sessions)
-                return .none
-            case .onAppear:
-                return .none
-            case .removeTapped(let id):
-                state.sessions.remove(id: id)
-                return .run { [id] _ in
-                    try await workoutClient.delete(id)
-                }
-            }
-        }
-    }
-}
-```
-
 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.
 
+Code for this section: [Architecture pattern examples](references/pattern-examples.md).
+
 ## Clean Architecture
 
 Three layers with dependencies pointing inward:
@@ -318,51 +160,12 @@ Three layers with dependencies pointing inward:
 - **Data**: repository implementations, networking, persistence.
 - **Presentation**: views and view models.
 
-```swift
-// Domain
-protocol WorkoutRepository: Sendable {
-    func fetchAll() async throws -> [Workout]
-    func save(_ workout: Workout) async throws
-    func delete(_ id: Workout.ID) async throws
-}
-
-struct UpcomingWorkouts: Sendable {
-    let repository: any WorkoutRepository
-
-    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
-struct RemoteWorkoutRepository: WorkoutRepository {
-    let api: FitnessAPI
-
-    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
-@MainActor
-@Observable
-final class PlannerModel {
-    private(set) var upcoming: [Workout] = []
-    private let upcomingWorkouts: UpcomingWorkouts
-
-    init(upcomingWorkouts: UpcomingWorkouts) { self.upcomingWorkouts = upcomingWorkouts }
-
-    func load() async { upcoming = (try? await upcomingWorkouts()) ?? [] }
-}
-```
-
 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.
 
+Code for this section: [Architecture pattern examples](references/pattern-examples.md).
+
 ## Coordinator pattern
 
 Coordinators take navigation out of views and controllers. They pay off mostly
@@ -374,35 +177,12 @@ in UIKit and hybrid apps.
   coordinator decides whether to push or present.
 - Feature models keep the business logic. The coordinator only routes.
 
-```swift
-@MainActor
-final class OnboardingCoordinator {
-    private let navigation: UINavigationController
-    private let account: AccountService
-
-    init(navigation: UINavigationController, account: AccountService) {
-        self.navigation = navigation
-        self.account = account
-    }
-
-    func start() {
-        let welcome = WelcomeViewController(onContinue: { [weak self] in self?.showSignUp() })
-        navigation.setViewControllers([welcome], animated: false)
-    }
-
-    private func showSignUp() {
-        let form = SignUpViewController(account: account, onDone: { [weak self] in self?.finish() })
-        navigation.pushViewController(form, animated: true)
-    }
-
-    private func finish() { navigation.dismiss(animated: true) }
-}
-```
-
 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.
 
+Code for this section: [Architecture pattern examples](references/pattern-examples.md).
+
 ## VIPER
 
 View, Interactor, Presenter, Entity, Router. Its value today is keeping
@@ -477,6 +257,7 @@ while adoption is in progress.
 
 ## References
 
+- [Architecture pattern examples](references/pattern-examples.md): open when implementing or reviewing a feature in MVVM, MVI, TCA, Clean Architecture or with coordinators.
 - [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)

package/pipeline/skills/shared/external/swift-architecture/references/pattern-examples.md

@@ -0,0 +1,295 @@
+# Architecture pattern examples
+
+<!-- toc -->
+- [MVVM](#mvvm)
+- [MVI](#mvi)
+- [TCA](#tca)
+- [Clean Architecture](#clean-architecture)
+- [Coordinator pattern](#coordinator-pattern)
+<!-- /toc -->
+
+Worked code for MVVM, MVI, TCA, Clean Architecture and the Coordinator pattern. SKILL.md keeps the selection guidance and the rules for each pattern.
+
+## MVVM
+
+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 WorkoutListModel {
+    private(set) var rows: [WorkoutRow] = []
+    private(set) var loading = false
+    var filter = ""
+
+    private var all: [Workout] = []
+    private let store: any WorkoutStore
+
+    init(store: any WorkoutStore) { self.store = store }
+
+    var visibleRows: [WorkoutRow] {
+        filter.isEmpty ? rows : rows.filter { $0.title.localizedStandardContains(filter) }
+    }
+
+    func load() async {
+        loading = true
+        defer { loading = false }
+        all = (try? await store.allWorkouts()) ?? []
+        rows = all.map(WorkoutRow.init)
+    }
+
+    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 WorkoutListScreen: View {
+    @State private var model: WorkoutListModel
+
+    init(store: any WorkoutStore) {
+        _model = State(initialValue: WorkoutListModel(store: store))
+    }
+
+    var body: some View {
+        List {
+            ForEach(model.visibleRows, id: \.id) { row in
+                LabeledContent(row.title, value: row.when)
+            }
+            .onDelete { positions in Task { await model.delete(rowsAt: positions) } }
+        }
+        .searchable(text: $model.filter)
+        .task { await model.load() }
+    }
+}
+```
+
+The payoff is a view model you can test without any view:
+
+```swift
+@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
+
+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 WorkoutFeed {
+    struct State {
+        var sessions: [Workout] = []
+        var loading = false
+        var message: String?
+    }
+
+    enum Intent {
+        case appeared
+        case remove(Workout.ID)
+        case dismissMessage
+    }
+
+    private(set) var state = State()
+    private let store: any WorkoutStore
+
+    init(store: any WorkoutStore) { self.store = store }
+
+    func send(_ intent: Intent) {
+        Task { await apply(intent) }
+    }
+
+    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 {
+                try await store.delete(id)
+                state.sessions.removeAll { $0.id == id }
+            } catch {
+                state.message = error.localizedDescription
+            }
+        case .dismissMessage:
+            state.message = nil
+        }
+    }
+}
+```
+
+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 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 WorkoutsFeature {
+    @ObservableState
+    struct State: Equatable {
+        var sessions: IdentifiedArrayOf<Workout> = []
+        var loading = false
+    }
+
+    enum Action {
+        case onAppear
+        case loaded([Workout])
+        case removeTapped(Workout.ID)
+    }
+
+    @Dependency(\.workoutClient) var workoutClient
+
+    var body: some ReducerOf<Self> {
+        Reduce { state, action in
+            switch action {
+            case .onAppear where !state.loading:
+                state.loading = true
+                return .run { send in
+                    let sessions = try await workoutClient.fetchAll()
+                    await send(.loaded(sessions))
+                }
+            case .loaded(let sessions):
+                state.loading = false
+                state.sessions = IdentifiedArray(uniqueElements: sessions)
+                return .none
+            case .onAppear:
+                return .none
+            case .removeTapped(let id):
+                state.sessions.remove(id: id)
+                return .run { [id] _ in
+                    try await workoutClient.delete(id)
+                }
+            }
+        }
+    }
+}
+```
+
+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
+
+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
+protocol WorkoutRepository: Sendable {
+    func fetchAll() async throws -> [Workout]
+    func save(_ workout: Workout) async throws
+    func delete(_ id: Workout.ID) async throws
+}
+
+struct UpcomingWorkouts: Sendable {
+    let repository: any WorkoutRepository
+
+    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
+struct RemoteWorkoutRepository: WorkoutRepository {
+    let api: FitnessAPI
+
+    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
+@MainActor
+@Observable
+final class PlannerModel {
+    private(set) var upcoming: [Workout] = []
+    private let upcomingWorkouts: UpcomingWorkouts
+
+    init(upcomingWorkouts: UpcomingWorkouts) { self.upcomingWorkouts = upcomingWorkouts }
+
+    func load() async { upcoming = (try? await upcomingWorkouts()) ?? [] }
+}
+```
+
+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.
+
+## Coordinator pattern
+
+Coordinators take navigation out of views and controllers. They pay off mostly
+in UIKit and hybrid apps.
+
+- 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
+@MainActor
+final class OnboardingCoordinator {
+    private let navigation: UINavigationController
+    private let account: AccountService
+
+    init(navigation: UINavigationController, account: AccountService) {
+        self.navigation = navigation
+        self.account = account
+    }
+
+    func start() {
+        let welcome = WelcomeViewController(onContinue: { [weak self] in self?.showSignUp() })
+        navigation.setViewControllers([welcome], animated: false)
+    }
+
+    private func showSignUp() {
+        let form = SignUpViewController(account: account, onDone: { [weak self] in self?.finish() })
+        navigation.pushViewController(form, animated: true)
+    }
+
+    private func finish() { navigation.dismiss(animated: true) }
+}
+```
+
+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.