@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/side-effects-and-mutating-pairs.md

@@ -0,0 +1,158 @@
+# Side Effects and Mutating Pairs
+
+Extended examples for side-effect naming, the -ed/-ing decision tree, form- prefix patterns, Boolean naming, and factory methods.
+
+## Contents
+
+- [Side-Effect Naming Extended Examples](#side-effect-naming-extended-examples)
+- [The -ed/-ing Decision Tree](#the--ed-ing-decision-tree)
+- [Form- Prefix Patterns](#form--prefix-patterns)
+- [Boolean Naming Patterns](#boolean-naming-patterns)
+- [Factory Method Naming](#factory-method-naming)
+
+## Side-Effect Naming Extended Examples
+
+### Mutating  -  imperative verbs
+
+Methods that change the receiver's state use imperative verb form.
+
+```swift
+array.sort()
+array.append(newElement)
+array.removeAll()
+set.insert(member)
+dictionary.updateValue(newValue, forKey: key)
+buffer.replaceSubrange(range, with: newElements)
+```
+
+### Nonmutating  -  nouns, past participles, descriptions
+
+Methods that return a value without changing the receiver use a form that describes the result.
+
+```swift
+let sorted = array.sorted()
+let distance = point.distance(to: origin)
+let trimmed = string.trimmingCharacters(in: .whitespaces)
+let union = setA.union(setB)
+let successor = index.advanced(by: 1)
+let prefix = array.prefix(3)
+```
+
+### Mixed  -  same type, both variants
+
+When both exist, the naming makes the difference obvious at every call site.
+
+```swift
+// Mutating
+array.sort()
+// Nonmutating  -  returns new value
+let newArray = array.sorted()
+
+// Mutating
+set.formUnion(other)
+// Nonmutating  -  returns new value
+let combined = set.union(other)
+```
+
+## The -ed/-ing Decision Tree
+
+Use this decision tree to choose between `-ed` and `-ing` for the nonmutating variant of a verb-described operation.
+
+**Step 1: Try the past participle (`-ed`).** Read the phrase: "a [verb]-ed [noun]". If it sounds grammatical, use `-ed`.
+
+```
+sort → sorted          ✓  "a sorted array" sounds correct
+sortLines → sortedLines ✓ "sorted lines" describes the result
+reverse → reversed      ✓ "a reversed collection" sounds correct
+shuffle → shuffled      ✓ "a shuffled deck" sounds correct
+```
+
+**Step 2: Does -ed fail the result-description test?**
+
+Use the present participle (`-ing`) only when the `-ed` form is ungrammatical or describes the direct object rather than the returned receiver or result. A direct object is a clue to check the grammar, not the rule by itself.
+
+```
+append → appending                  "appended" does not describe the returned receiver clearly
+stripNewlines → strippingNewlines   direct-object pattern from the guidelines
+```
+
+### Extended -ed/-ing examples and naming patterns
+
+| Mutating | Nonmutating | Suffix | Reasoning |
+|----------|-------------|--------|-----------|
+| `sort()` | `sorted()` | -ed | "a sorted array" |
+| `sortLines()` | `sortedLines()` | -ed | "sorted lines" describes the result |
+| `reverse()` | `reversed()` | -ed | "a reversed collection" |
+| `shuffle()` | `shuffled()` | -ed | "a shuffled deck" |
+| `append(_:)` | `appending(_:)` | -ing | `appended` does not describe the returned receiver clearly |
+| `filter(_:)` | `filter(_:)` | n/a | nonmutating only in stdlib |
+| `drop(while:)` | `drop(while:)` | n/a | nonmutating only in stdlib |
+
+## Form- Prefix Patterns
+
+The `form` prefix applies only to noun-described operations where the nonmutating version is the noun itself.
+
+### Standard library examples
+
+| Nonmutating (noun) | Mutating (form- prefix) |
+|---------------------|------------------------|
+| `union(other)` | `formUnion(other)` |
+| `intersection(other)` | `formIntersection(other)` |
+| `symmetricDifference(other)` | `formSymmetricDifference(other)` |
+
+### When NOT to use form-
+
+Do not apply `form` to verb-described operations. The imperative verb form is already the mutating version.
+
+```swift
+// WRONG  -  sort is a verb, not a noun
+mutating func formSort()       // ✗
+mutating func sort()           // ✓
+
+// WRONG  -  append is a verb
+mutating func formAppend(_:)   // ✗
+mutating func append(_:)       // ✓
+```
+
+The `form` prefix exists because the noun form (`union`) is naturally the nonmutating name, and the mutating version needs a distinct name. Verbs do not have this problem  -  the imperative (`sort`) and participle (`sorted`) are already distinct.
+
+## Boolean Naming Patterns
+
+Boolean properties and methods read as assertions about the receiver. They answer a yes/no question.
+
+```swift
+// Properties  -  "is" prefix for adjectives
+line.isEmpty
+url.isFileURL
+connection.isSecure
+view.isHidden
+option.isEnabled
+
+// Properties  -  no prefix for verb phrases
+set.contains(element)        // "set contains element"
+string.hasPrefix("https")    // "string has prefix"
+array.canAppend(element)     // "array can append element"
+
+// BAD patterns
+line.empty          // is this a verb ("empty the line") or adjective?
+list.include        // verb or boolean?
+node.leaf           // noun, not an assertion
+```
+
+## Factory Method Naming
+
+Factory methods that create and return a new value use the `make` prefix. This distinguishes them from initializers and from methods that return existing values.
+
+```swift
+// GOOD  -  factory creates a new value
+let iterator = collection.makeIterator()
+let buffer = parser.makeBuffer()
+let snapshot = store.makeSnapshot()
+
+// BAD  -  wrong prefix
+let iterator = collection.createIterator()    // use "make"
+let buffer = parser.buildBuffer()             // use "make"
+let snapshot = store.getSnapshot()            // "get" implies retrieval, not creation
+```
+
+The `make` prefix signals to callers that the returned value is freshly created, distinct from any cached or shared state.

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

@@ -0,0 +1,499 @@
+---
+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."
+---
+
+# 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.
+
+```swift
+import Observation
+import SwiftUI
+
+@MainActor
+@Observable
+final class TripStore {
+    var trips: [Trip] = []
+    var isLoading = false
+    var error: Error?
+
+    private let service: TripService
+
+    init(service: TripService) {
+        self.service = service
+    }
+
+    func loadTrips() async {
+        isLoading = true
+        defer { isLoading = false }
+        do {
+            trips = try await service.fetchTrips()
+        } catch {
+            self.error = error
+        }
+    }
+
+    func deleteTrip(_ trip: Trip) async throws {
+        try await service.delete(trip)
+        trips.removeAll { $0.id == trip.id }
+    }
+}
+
+struct TripsView: View {
+    @State private var store = TripStore(service: .live)
+
+    var body: some View {
+        List(store.trips) { trip in
+            TripRow(trip: trip)
+        }
+        .task { await store.loadTrips() }
+    }
+}
+```
+
+**When MV is enough:** Single-screen features, prototype/MVP, small teams,
+straightforward data flow.
+
+**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.
+
+## MVVM
+
+Separates view logic into a `ViewModel` that the view observes. The view model
+transforms model data for display and handles user actions.
+
+```swift
+@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) }
+    }
+
+    private let repository: TripRepository
+
+    init(repository: TripRepository) {
+        self.repository = repository
+    }
+
+    func loadTrips() async {
+        isLoading = true
+        defer { isLoading = false }
+        let models = (try? await repository.fetchAll()) ?? []
+        trips = models.map { TripRowItem(from: $0) }
+    }
+
+    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()
+    }
+}
+
+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())
+    }
+}
+
+struct TripListView: View {
+    @State private var viewModel: TripListViewModel
+
+    init(repository: TripRepository) {
+        _viewModel = State(initialValue: TripListViewModel(repository: repository))
+    }
+
+    var body: some View {
+        List {
+            ForEach(viewModel.filteredTrips) { item in
+                Text(item.name)
+            }
+            .onDelete { offsets in
+                Task { await viewModel.delete(at: offsets) }
+            }
+        }
+        .searchable(text: $viewModel.searchText)
+        .task { await viewModel.loadTrips() }
+    }
+}
+```
+
+**Testing a ViewModel:**
+
+```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)
+}
+```
+
+## MVI
+
+Unidirectional data flow: views dispatch **intents**, a **reducer** produces
+new **state**, and **side effects** are handled explicitly.
+
+```swift
+@MainActor
+@Observable
+final class TripListStore {
+    private(set) var state = State()
+
+    struct State {
+        var trips: [Trip] = []
+        var isLoading = false
+        var error: String?
+    }
+
+    enum Intent {
+        case loadTrips
+        case deleteTrip(Trip)
+        case clearError
+    }
+
+    private let service: TripService
+
+    init(service: TripService) {
+        self.service = service
+    }
+
+    func send(_ intent: Intent) {
+        Task { await handle(intent) }
+    }
+
+    private func handle(_ intent: Intent) async {
+        switch intent {
+        case .loadTrips:
+            state.isLoading = true
+            do {
+                state.trips = try await service.fetchTrips()
+            } catch {
+                state.error = 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
+        }
+    }
+}
+```
+
+**Advantages:** Predictable state transitions, easy to log/replay intents,
+clear separation of "what happened" from "what changed."
+
+## 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)
+
+```swift
+import ComposableArchitecture
+
+@Reducer
+struct TripList {
+    @ObservableState
+    struct State: Equatable {
+        var trips: IdentifiedArrayOf<Trip> = []
+        var isLoading = false
+        var errorMessage: String?
+    }
+
+    enum Action {
+        case onAppear
+        case tripsLoaded([Trip])
+        case tripsFailed(String)
+        case deleteTrip(Trip.ID)
+    }
+
+    @Dependency(\.tripClient) var tripClient
+
+    var body: some ReducerOf<Self> {
+        Reduce { state, action in
+            switch action {
+            case .onAppear:
+                state.isLoading = true
+                state.errorMessage = nil
+                return .run { send in
+                    do {
+                        let trips = try await tripClient.fetchAll()
+                        await send(.tripsLoaded(trips))
+                    } catch {
+                        await send(.tripsFailed(error.localizedDescription))
+                    }
+                }
+            case .tripsLoaded(let trips):
+                state.trips = IdentifiedArray(uniqueElements: trips)
+                state.isLoading = false
+                return .none
+            case .tripsFailed(let message):
+                state.errorMessage = message
+                state.isLoading = false
+                return .none
+            case .deleteTrip(let id):
+                state.trips.remove(id: id)
+                return .run { _ in try await tripClient.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.
+
+## Clean Architecture
+
+Layers: **Domain** (entities, use cases, repository protocols) → **Data**
+(repository implementations, network, persistence) → **Presentation** (views,
+view models). Dependencies point inward.
+
+```swift
+// Domain layer
+protocol TripRepository: Sendable {
+    func fetchAll() async throws -> [Trip]
+    func save(_ trip: Trip) async throws
+    func delete(id: UUID) async throws
+}
+
+struct FetchUpcomingTripsUseCase: Sendable {
+    private let repository: TripRepository
+
+    init(repository: TripRepository) {
+        self.repository = repository
+    }
+
+    func execute() async throws -> [Trip] {
+        try await repository.fetchAll()
+            .filter { $0.startDate > .now }
+            .sorted { $0.startDate < $1.startDate }
+    }
+}
+
+// Data layer
+struct RemoteTripRepository: TripRepository {
+    private let client: APIClient
+
+    func fetchAll() async throws -> [Trip] {
+        try await client.request(.get, "/trips")
+    }
+    // ...
+}
+
+// Presentation layer
+@MainActor
+@Observable
+final class UpcomingTripsViewModel {
+    private(set) var trips: [Trip] = []
+    private let useCase: FetchUpcomingTripsUseCase
+
+    init(useCase: FetchUpcomingTripsUseCase) {
+        self.useCase = useCase
+    }
+
+    func load() async {
+        trips = (try? await useCase.execute()) ?? []
+    }
+}
+```
+
+**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
+
+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.
+
+**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.
+
+**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`
+
+```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)
+
+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
+
+### Any → TCA
+
+TCA adoption is typically incremental: wrap one feature's state and actions
+in a `Reducer`, migrate its dependencies to `@Dependency`, and test.
+
+## Common Mistakes
+
+| 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 |
+
+## Review Checklist
+
+- [ ] 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
+
+## 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)