@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/external/kotlin-coroutines-expert/SKILL.md

@@ -70,6 +70,78 @@ val searchResults: Flow<List<Item>> = searchQuery
 val uiState: StateFlow<UiState> = _uiState.asStateFlow()
 ```
 
+### 4. Injectable Dispatchers
+
+Never hardcode `Dispatchers.IO` / `Dispatchers.Default` inside repositories and data sources. Inject them through Hilt qualifiers so a test can swap in a `TestDispatcher` and control virtual time without touching production code.
+
+```kotlin
+@Retention(AnnotationRetention.BINARY)
+@Qualifier
+annotation class IoDispatcher
+
+@Retention(AnnotationRetention.BINARY)
+@Qualifier
+annotation class DefaultDispatcher
+
+@Module
+@InstallIn(SingletonComponent::class)
+object DispatchersModule {
+    @IoDispatcher
+    @Provides
+    fun provideIoDispatcher(): CoroutineDispatcher = Dispatchers.IO
+
+    @DefaultDispatcher
+    @Provides
+    fun provideDefaultDispatcher(): CoroutineDispatcher = Dispatchers.Default
+}
+
+class ItemRepository @Inject constructor(
+    private val api: ItemApi,
+    @IoDispatcher private val ioDispatcher: CoroutineDispatcher
+) {
+    suspend fun load(id: String): Item = withContext(ioDispatcher) {
+        api.fetch(id).toDomain()
+    }
+}
+```
+
+In tests, provide a single `TestDispatcher` (typically `StandardTestDispatcher`) for both qualifiers so `runTest`'s scheduler drives everything.
+
+The `DispatcherProvider` interface idiom (one injected object exposing `io`, `default`, `main`) is a valid alternative and helps when a class needs several dispatchers, but the per-dispatcher qualifier form is leaner: it names the exact dependency at the constructor and avoids a wrapper type.
+
+### 5. Cancellation-Safe Error Handling
+
+A broad `catch` swallows `CancellationException` and silently breaks structured concurrency: the coroutine keeps running after its scope was cancelled. Rethrow it explicitly before any `catch (Throwable)` or `catch (Exception)`.
+
+```kotlin
+suspend fun loadOrFallback(): Data =
+    try {
+        repo.fetch()
+    } catch (e: CancellationException) {
+        throw e
+    } catch (e: Throwable) {
+        Data.empty()
+    }
+```
+
+Choose the strategy per branch. On the critical branch, let cancellation and real failures propagate so the caller sees them. On an optional parallel branch, degrade to a fallback after the rethrow.
+
+```kotlin
+suspend fun loadScreen(): ScreenData = coroutineScope {
+    val core = async { repo.loadCore() }
+    val banner = async {
+        try {
+            repo.loadPromoBanner()
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Throwable) {
+            null
+        }
+    }
+    ScreenData(core = core.await(), banner = banner.await())
+}
+```
+
 ## Examples
 
 ### Example 1: Parallel Execution with Error Handling
@@ -87,6 +159,77 @@ suspend fun fetchDataWithErrorHandling() = supervisorScope {
 }
 ```
 
+### Example 2: Fire-and-Forget Background Persistence
+
+A long-lived scope built on `SupervisorJob` for writes whose failure must not cancel siblings or crash the caller. The body is always guarded, because an uncaught throw in a supervisor child still reaches the scope's exception handler.
+
+```kotlin
+class CacheWriter @Inject constructor(
+    @IoDispatcher ioDispatcher: CoroutineDispatcher
+) {
+    private val scope = CoroutineScope(SupervisorJob() + ioDispatcher)
+
+    fun persist(entry: CacheEntry) {
+        scope.launch {
+            try {
+                dao.upsert(entry)
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Throwable) {
+                logger.warn("cache write failed", e)
+            }
+        }
+    }
+}
+```
+
+### Example 3: Double-Checked Lazy Async Init in a Suspend Context
+
+Guard a one-time async initialization with `Mutex.withLock`, not `synchronized`. `synchronized` blocks the thread and cannot host suspend calls; `withLock` suspends the coroutine and releases cooperatively.
+
+```kotlin
+class TokenProvider @Inject constructor(private val api: AuthApi) {
+    private val mutex = Mutex()
+    @Volatile private var cached: Token? = null
+
+    suspend fun token(): Token {
+        cached?.let { return it }
+        return mutex.withLock {
+            cached ?: api.fetchToken().also { cached = it }
+        }
+    }
+}
+```
+
+### Example 4: Awaiting a Suspend Result Inside a Synchronous Callback
+
+A framework callback that must return a value synchronously cannot call a suspend function directly, and `runBlocking` on the main or a callback thread risks deadlock. Bridge with a scoped `launch`, a lock/condition, and `withTimeout` so a stalled producer cannot block forever.
+
+```kotlin
+fun interceptSync(request: Request): Response {
+    val lock = ReentrantLock()
+    val done = lock.newCondition()
+    var result: Response? = null
+
+    scope.launch {
+        val value = try {
+            withTimeout(5_000) { resolver.resolve(request) }
+        } catch (e: Throwable) {
+            Response.passthrough(request)
+        }
+        lock.withLock {
+            result = value
+            done.signalAll()
+        }
+    }
+
+    lock.withLock {
+        while (result == null) done.await()
+        return result!!
+    }
+}
+```
+
 ## Best Practices
 
 - ✅ **Do:** Use `Dispatchers.IO` for blocking I/O operations.

package/pipeline/skills/shared/external/mapkit-location/SKILL.md

@@ -130,29 +130,10 @@ Map {
 ### Camera Position
 
 `MapCameraPosition` controls what the map displays. Bind it to let the user
-interact and to programmatically move the camera.
-
-```swift
-// Center on a region
-@State private var position: MapCameraPosition = .region(
-    MKCoordinateRegion(
-        center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
-        span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
-    )
-)
-
-// Follow user location
-@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
-
-// Specific camera angle (3D perspective)
-@State private var position: MapCameraPosition = .camera(
-    MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
-)
-
-// Frame specific items
-position = .item(MKMapItem.forCurrentLocation())
-position = .rect(MKMapRect(...))
-```
+interact and to programmatically move the camera. Initialize it with `.region`,
+`.userLocation(fallback:)`, `.camera`, `.item`, `.rect`, or `.automatic`. See
+[references/mapkit-patterns.md](references/mapkit-patterns.md) ("Camera Control") for the position
+initializers, animated fly-to, framing content, and reading the visible region.
 
 ### Map Style
 
@@ -308,76 +289,39 @@ if let placemark = placemarks.first {
 
 ### MKGeocodingRequest and MKReverseGeocodingRequest (iOS 26+)
 
-New MapKit-native geocoding that returns `MKMapItem` with richer data and
-`MKAddress` / `MKAddressRepresentations` for flexible address formatting.
-
-```swift
-@available(iOS 26, *)
-func reverseGeocode(location: CLLocation) async throws -> MKMapItem? {
-    guard let request = MKReverseGeocodingRequest(location: location) else {
-        return nil
-    }
-    let mapItems = try await request.mapItems
-    return mapItems.first
-}
-
-@available(iOS 26, *)
-func forwardGeocode(address: String) async throws -> [MKMapItem] {
-    guard let request = MKGeocodingRequest(addressString: address) else { return [] }
-    return try await request.mapItems
-}
-```
+New MapKit-native geocoding returns `MKMapItem` with richer data and `MKAddress`
+/ `MKAddressRepresentations` for flexible address formatting. Construct
+`MKGeocodingRequest(addressString:)` or `MKReverseGeocodingRequest(location:)` and
+await `.mapItems`. See [references/mapkit-patterns.md](references/mapkit-patterns.md) ("iOS 26 New
+APIs") for both, plus `MKAddressRepresentations` formatting.
 
 ## Search
 
 ### MKLocalSearchCompleter (Autocomplete)
 
-```swift
-@Observable
-final class SearchCompleter: NSObject, MKLocalSearchCompleterDelegate {
-    var results: [MKLocalSearchCompletion] = []
-    var query: String = "" { didSet { completer.queryFragment = query } }
-
-    private let completer = MKLocalSearchCompleter()
-
-    override init() {
-        super.init()
-        completer.delegate = self
-        completer.resultTypes = [.address, .pointOfInterest]
-    }
-
-    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
-        results = completer.results
-    }
-
-    func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
-        results = []
-    }
-}
-```
+Set `queryFragment` on an `MKLocalSearchCompleter` and read `results` from its
+delegate for suggestions. Debounce input (300ms+) and constrain `completer.region`
+to the visible map region.
 
 ### MKLocalSearch (Full Search)
 
+Convert a selected completion (or a natural-language query) into full `MKMapItem`
+results:
+
 ```swift
 func search(for completion: MKLocalSearchCompletion) async throws -> [MKMapItem] {
     let request = MKLocalSearch.Request(completion: completion)
     request.resultTypes = [.pointOfInterest, .address]
-    let search = MKLocalSearch(request: request)
-    let response = try await search.start()
-    return response.mapItems
-}
-
-// Search by natural language query within a region
-func searchNearby(query: String, region: MKCoordinateRegion) async throws -> [MKMapItem] {
-    let request = MKLocalSearch.Request()
-    request.naturalLanguageQuery = query
-    request.region = region
-    let search = MKLocalSearch(request: request)
-    let response = try await search.start()
+    let response = try await MKLocalSearch(request: request).start()
     return response.mapItems
 }
 ```
 
+For a natural-language query, set `request.naturalLanguageQuery` and
+`request.region` instead. See [references/mapkit-patterns.md](references/mapkit-patterns.md) ("Search
+with Autocomplete") for the full completer delegate class and a `.searchable`
+view integration.
+
 ## Directions
 
 ```swift
@@ -411,32 +355,13 @@ Map {
 }
 ```
 
-### ETA Calculation
+### ETA and Cycling Directions
 
-```swift
-func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> TimeInterval {
-    let request = MKDirections.Request()
-    request.source = source
-    request.destination = destination
-    let directions = MKDirections(request: request)
-    let response = try await directions.calculateETA()
-    return response.expectedTravelTime
-}
-```
-
-### Cycling Directions (iOS 14+)
-
-```swift
-func getCyclingDirections(to destination: MKMapItem) async throws -> MKRoute? {
-    let request = MKDirections.Request()
-    request.source = MKMapItem.forCurrentLocation()
-    request.destination = destination
-    request.transportType = .cycling
-    let directions = MKDirections(request: request)
-    let response = try await directions.calculate()
-    return response.routes.first
-}
-```
+For travel time only, use `MKDirections.calculateETA()` (returns
+`expectedTravelTime` without route geometry). For bike routes, set
+`request.transportType = .cycling` (iOS 14+). See
+[references/mapkit-patterns.md](references/mapkit-patterns.md) ("ETA Calculation" and "Cycling
+Directions") for both.
 
 ## PlaceDescriptor (iOS 26+)
 

package/pipeline/skills/shared/external/mapkit-location/references/mapkit-patterns.md

@@ -137,6 +137,33 @@ Annotation(place.name, coordinate: place.coordinate, anchor: .bottom) {
 
 ## Camera Control (MapCameraPosition)
 
+### Setting an initial position
+
+`MapCameraPosition` controls what the map displays. Bind it to let the user
+interact and to move the camera programmatically.
+
+```swift
+// Center on a region
+@State private var position: MapCameraPosition = .region(
+    MKCoordinateRegion(
+        center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
+        span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
+    )
+)
+
+// Follow user location
+@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)
+
+// Specific camera angle (3D perspective)
+@State private var position: MapCameraPosition = .camera(
+    MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
+)
+
+// Frame specific items
+position = .item(MKMapItem.forCurrentLocation())
+position = .rect(MKMapRect(...))
+```
+
 ### Animate camera changes
 
 Wrap position updates in `withAnimation` for smooth transitions:
@@ -389,6 +416,21 @@ ForEach(Array(response.routes.enumerated()), id: \.offset) { index, route in
 }
 ```
 
+### ETA Calculation
+
+Use `calculateETA()` when you only need travel time, not the full route geometry.
+
+```swift
+func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> TimeInterval {
+    let request = MKDirections.Request()
+    request.source = source
+    request.destination = destination
+    let directions = MKDirections(request: request)
+    let response = try await directions.calculateETA()
+    return response.expectedTravelTime
+}
+```
+
 ---
 
 ## Look Around Preview