@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.1

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

@@ -1,244 +1,153 @@
 ---
 name: kotlin-coroutines-expert
-description: "Expert patterns for Kotlin Coroutines and Flow, covering structured concurrency, error handling, and testing. Use when writing or reviewing coroutines and Flow, or a concurrency bug needs diagnosing."
-risk: safe
-source: community
-date_added: "2026-02-27"
+description: "Kotlin coroutines and Flow: scopes, structured concurrency, cancellation, exception handling, dispatcher injection, StateFlow versus SharedFlow, runTest and Turbine. Use when a coroutine leaks, hangs, swallows errors or tests flake."
+metadata:
+  risk: safe
+  source: multi-agent-pipeline
+  date_added: "2026-09-25"
 ---
 
-# Kotlin Coroutines Expert
+# Kotlin Coroutines and Flow
 
-## Overview
+Targets Kotlin 2.x and kotlinx.coroutines 1.9 or later. Android specifics
+(viewModelScope, lifecycle-aware collection) appear where they change the answer;
+the rest applies to any JVM or multiplatform code.
 
-A guide to mastering asynchronous programming with Kotlin Coroutines. Covers advanced topics like structured concurrency, `Flow` transformations, exception handling, and testing strategies.
+## Mental model in five sentences
 
-## When to Use This Skill
+1. Every coroutine runs inside a `CoroutineScope`, and its `Job` is a child of
+   that scope's job.
+2. A parent does not complete until all its children complete.
+3. Cancelling a parent cancels every child; a failing child cancels its parent
+   and siblings, unless a `SupervisorJob` sits in between.
+4. Cancellation is cooperative: it is only observed at suspension points or
+   explicit checks.
+5. A `suspend` function should be main-safe: callers may invoke it from any
+   thread, and it moves blocking work off the caller's dispatcher itself.
 
-- Use when implementing asynchronous operations in Kotlin.
-- Use when designing reactive data streams with `Flow`.
-- Use when debugging coroutine cancellations or exceptions.
-- Use when writing unit tests for suspending functions or Flows.
+## Scopes: pick the one whose lifetime matches the work
 
-## Step-by-Step Guide
+| Work | Scope |
+|---|---|
+| Loading data for a screen | `viewModelScope` (cancelled in `onCleared`) |
+| UI-bound collection | `lifecycleScope` + `repeatOnLifecycle(STARTED)`, or `collectAsStateWithLifecycle` in Compose |
+| Several calls that must all finish before returning | `coroutineScope { }` inside a suspend function |
+| Work that must outlive the screen (sync, upload) | an application-level scope injected as a dependency, or WorkManager if it must survive process death |
+| Tests | `runTest`'s `TestScope`, or `backgroundScope` for never-ending collectors |
 
-### 1. Structured Concurrency
-
-Always launch coroutines within a defined `CoroutineScope`. Use `coroutineScope` or `supervisorScope` to group concurrent tasks.
+`GlobalScope` has no owner, no cancellation and no error routing. Replace it
+with an injected application scope:
 
 ```kotlin
-suspend fun loadDashboardData(): DashboardData = coroutineScope {
-    val userDeferred = async { userRepo.getUser() }
-    val settingsDeferred = async { settingsRepo.getSettings() }
-    
-    DashboardData(
-        user = userDeferred.await(),
-        settings = settingsDeferred.await()
-    )
-}
+@Singleton
+class AppScope @Inject constructor() : CoroutineScope by CoroutineScope(SupervisorJob() + Dispatchers.Default)
 ```
 
-### 2. Exception Handling
-
-Use `CoroutineExceptionHandler` for top-level scopes, but rely on `try-catch` within suspending functions for granular control.
+## Parallel decomposition
 
 ```kotlin
-val handler = CoroutineExceptionHandler { _, exception ->
-    println("Caught $exception")
+suspend fun loadOrderSummary(orderId: String): OrderSummary = coroutineScope {
+    val order = async { orderApi.fetch(orderId) }
+    val items = async { itemApi.fetchForOrder(orderId) }
+    val invoice = async { invoiceApi.latest(orderId) }
+    OrderSummary(order.await(), items.await(), invoice.await())
 }
-
-viewModelScope.launch(handler) {
-    try {
-        riskyOperation()
-    } catch (e: IOException) {
-        // Handle network error specifically
-    }
-}
-```
-
-### 3. Reactive Streams with Flow
-
-Use `StateFlow` for state that needs to be retained, and `SharedFlow` for events.
-
-```kotlin
-// Cold Flow (Lazy)
-val searchResults: Flow<List<Item>> = searchQuery
-    .debounce(300)
-    .flatMapLatest { query -> searchRepo.search(query) }
-    .flowOn(Dispatchers.IO)
-
-// Hot Flow (State)
-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.
+If any call throws, `coroutineScope` cancels the other two and rethrows. That
+is usually what you want. When partial results are acceptable, use
+`supervisorScope` and handle each failure at its `await`:
 
 ```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()
-    }
+suspend fun loadDashboard(): Dashboard = supervisorScope {
+    val recent = async { orderRepository.recent() }
+    val promos = async { promoRepository.active() }
+    Dashboard(
+        recentOrders = recent.await(),
+        promotions = runCatchingCancellable { promos.await() }.getOrDefault(emptyList()),
+    )
 }
 ```
 
-In tests, provide a single `TestDispatcher` (typically `StandardTestDispatcher`) for both qualifiers so `runTest`'s scheduler drives everything.
+## Cancellation
 
-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.
+- Suspending library calls (`delay`, `withContext`, `Flow.collect`, Retrofit and
+  Room suspend functions) check cancellation for you.
+- A CPU loop must check: call `ensureActive()` or `yield()` every iteration.
+- Blocking Java I/O does not observe cancellation; wrap it in
+  `runInterruptible(Dispatchers.IO) { }` if it can block for long.
+- Cleanup that itself suspends needs `withContext(NonCancellable) { }` inside
+  `finally`, otherwise the first suspension throws immediately.
+- Timeouts: `withTimeout` throws `TimeoutCancellationException`;
+  `withTimeoutOrNull` returns null. Prefer the latter at boundaries.
 
-### 5. Cancellation-Safe Error Handling
+### Never swallow CancellationException
 
-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)`.
+`catch (e: Exception)` and `runCatching` both catch `CancellationException`,
+which keeps a cancelled coroutine running. Rethrow it:
 
 ```kotlin
-suspend fun loadOrFallback(): Data =
+inline fun <T> runCatchingCancellable(block: () -> T): Result<T> =
     try {
-        repo.fetch()
+        Result.success(block())
     } catch (e: CancellationException) {
         throw e
-    } catch (e: Throwable) {
-        Data.empty()
+    } catch (e: Exception) {
+        Result.failure(e)
     }
 ```
 
-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.
+## Exceptions
 
-```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
+| Builder | Where the exception goes |
+|---|---|
+| `launch` | propagates to the parent job; if it reaches a root scope, to its `CoroutineExceptionHandler`, else the thread's uncaught handler (crash on Android) |
+| `async` | stored in the `Deferred`, thrown at `await()`, and also propagates to the parent unless under a supervisor |
+| `coroutineScope` | rethrown to the caller after cancelling siblings |
+| `supervisorScope` / `SupervisorJob` | a child's failure does not cancel siblings; each `launch` child needs its own handling |
 
-### Example 1: Parallel Execution with Error Handling
+A `CoroutineExceptionHandler` is a last-resort logger. It only works on a root
+coroutine or a direct child of a supervisor, and it cannot resume the work.
+Handle expected failures with `try`/`catch` or `Result` close to the call.
 
-```kotlin
-suspend fun fetchDataWithErrorHandling() = supervisorScope {
-    val task1 = async { 
-        try { api.fetchA() } catch (e: Exception) { null } 
-    }
-    val task2 = async { api.fetchB() }
-    
-    // If task2 fails, task1 is NOT cancelled because of supervisorScope
-    val result1 = task1.await()
-    val result2 = task2.await() // May throw
-}
-```
+## Dispatchers
 
-### Example 2: Fire-and-Forget Background Persistence
+- `Dispatchers.Main.immediate` for UI state updates (the default in
+  `viewModelScope`).
+- `Dispatchers.IO` for blocking I/O; it is elastic, 64 threads by default.
+- `Dispatchers.Default` for CPU work, sized to the core count.
+- `Dispatchers.IO.limitedParallelism(n)` for a bounded pool, for example a
+  database that tolerates only one writer.
 
-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.
+Inject dispatchers instead of hard-coding them so tests can substitute a
+`TestDispatcher`:
 
 ```kotlin
-class CacheWriter @Inject constructor(
-    @IoDispatcher ioDispatcher: CoroutineDispatcher
+class NoteRepository(
+    private val dao: NoteDao,
+    private val io: CoroutineDispatcher = Dispatchers.IO,
 ) {
-    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)
-            }
-        }
+    suspend fun export(file: File) = withContext(io) {
+        file.writeText(dao.all().joinToString("\n") { it.body })
     }
 }
 ```
 
-### 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!!
-    }
-}
-```
+Room and Retrofit suspend functions already switch threads; wrapping them in
+`withContext(io)` is harmless but unnecessary.
 
-## Best Practices
+## Review checklist
 
-- ✅ **Do:** Use `Dispatchers.IO` for blocking I/O operations.
-- ✅ **Do:** Cancel scopes when they are no longer needed (e.g., `ViewModel.onCleared`).
-- ✅ **Do:** Use `TestScope` and `runTest` for unit testing coroutines.
-- ❌ **Don't:** Use `GlobalScope`. It breaks structured concurrency and can lead to leaks.
-- ❌ **Don't:** Catch `CancellationException` unless you rethrow it.
+- No `GlobalScope`, no `runBlocking` outside `main` and tests.
+- Each coroutine's scope matches the lifetime of its work.
+- `CancellationException` is rethrown everywhere exceptions are caught.
+- Long loops call `ensureActive()`; blocking calls are on `IO` or interruptible.
+- Dispatchers are injected; suspend functions are main-safe.
+- Flows exposed to UI are `StateFlow` built with `stateIn` and `WhileSubscribed`.
+- One-shot events have exactly one consumer and are not lost on rotation.
+- `callbackFlow` ends with `awaitClose`.
+- Tests use `runTest`, a shared scheduler and Turbine; no `Thread.sleep`.
 
-## Troubleshooting
+## References
 
-**Problem:** Coroutine test hangs or fails unpredictably.
-**Solution:** Ensure you are using `runTest` and injecting `TestDispatcher` into your classes so you can control virtual time.
+- `references/patterns.md`: Flow operators, callbackFlow, StateFlow/SharedFlow/Channel and stateIn; runTest, schedulers, MainDispatcherRule and Turbine. Load it when the task reaches those topics.

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

@@ -0,0 +1,103 @@
+# Coroutines: Flow and testing
+
+Loaded on demand from `../SKILL.md`.
+
+## Flow
+
+A `Flow` is cold: the block runs once per collector, from scratch.
+
+### Operators worth knowing by reflex
+
+| Goal | Operator |
+|---|---|
+| React to the latest input only, cancel stale work | `mapLatest`, `flatMapLatest`, `collectLatest` |
+| Search-as-you-type | `debounce(300)` then `distinctUntilChanged()` then `flatMapLatest` |
+| Merge several state sources into one | `combine(a, b, c) { ... }` |
+| Pair up emissions one to one | `zip` |
+| Run upstream on another dispatcher | `flowOn(Dispatchers.IO)` (affects operators above it only) |
+| Handle upstream errors | `catch { emit(fallback) }` (does not catch downstream errors) |
+| Retry transient failures | `retryWhen { cause, attempt -> cause is IOException && attempt < 3 }` |
+| Side effect at boundaries | `onStart`, `onEach`, `onCompletion` |
+| Absorb a fast producer | `buffer()`, `conflate()` |
+
+Never call `withContext` inside `flow { }` to change the emitting context; it
+throws an `IllegalStateException`. Use `flowOn`, or `channelFlow` when emitting
+from several coroutines.
+
+### Bridging callbacks
+
+```kotlin
+fun ConnectivityManager.onlineUpdates(): Flow<Boolean> = callbackFlow {
+    val callback = object : ConnectivityManager.NetworkCallback() {
+        override fun onAvailable(network: Network) { trySend(true) }
+        override fun onLost(network: Network) { trySend(false) }
+    }
+    registerDefaultNetworkCallback(callback)
+    awaitClose { unregisterNetworkCallback(callback) }
+}.distinctUntilChanged()
+```
+
+`awaitClose` is mandatory; without it the flow completes immediately and the
+listener leaks.
+
+### Hot streams
+
+| Type | Holds a value | Replays | Drops when nobody listens | Use for |
+|---|---|---|---|---|
+| `StateFlow` | yes, always | latest value | no, keeps the latest | UI state, equality-conflated |
+| `SharedFlow` | optional | configurable `replay` | depends on buffer config | broadcasting to many collectors |
+| `Channel` | no | no | no, suspends or buffers until received | one-shot events for exactly one consumer |
+
+Convert a cold flow to state in a ViewModel with `stateIn`:
+
+```kotlin
+val state: StateFlow<ProductListState> =
+    combine(repository.products(), filter) { products, f -> ProductListState(products.filter(f::matches)) }
+        .stateIn(
+            scope = viewModelScope,
+            started = SharingStarted.WhileSubscribed(5_000),
+            initialValue = ProductListState.Loading,
+        )
+```
+
+`WhileSubscribed(5_000)` keeps the upstream alive across a configuration change
+and stops it when the screen is really gone. Update `MutableStateFlow` with
+`update { it.copy(...) }` for an atomic read-modify-write.
+
+## Testing
+
+```kotlin
+class ProductListViewModelTest {
+    @get:Rule val mainRule = MainDispatcherRule()
+
+    @Test
+    fun filterNarrowsProducts() = runTest {
+        val repo = FakeProductRepository(listOf(product("mug"), product("lamp")))
+        val vm = ProductListViewModel(repo)
+
+        vm.state.test {
+            assertEquals(ProductListState.Loading, awaitItem())
+            assertEquals(2, (awaitItem() as ProductListState.Ready).items.size)
+            vm.setQuery("mug")
+            assertEquals(1, (awaitItem() as ProductListState.Ready).items.size)
+            cancelAndIgnoreRemainingEvents()
+        }
+    }
+}
+
+class MainDispatcherRule(
+    private val dispatcher: TestDispatcher = UnconfinedTestDispatcher(),
+) : TestWatcher() {
+    override fun starting(description: Description) = Dispatchers.setMain(dispatcher)
+    override fun finished(description: Description) = Dispatchers.resetMain()
+}
+```
+
+- `runTest` skips `delay` using virtual time; `advanceTimeBy`,
+  `advanceUntilIdle` and `testScheduler.currentTime` control it.
+- Share one `TestCoroutineScheduler` between every injected `TestDispatcher`
+  in a test, or virtual time diverges.
+- `StandardTestDispatcher` queues work until advanced (good for ordering
+  assertions); `UnconfinedTestDispatcher` runs eagerly (good for collectors).
+- Start never-ending collectors in `backgroundScope` so the test can finish.
+- Turbine's `test { }` fails on unconsumed events; that is the point.

package/pipeline/skills/shared/external/live-activities/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: live-activities
 description: "Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit. Use when building real-time updating widgets for the Lock Screen and Dynamic Island  -  delivery tracking, sports scores, ride-sharing status, workout timers, media playback, or any time-sensitive information that updates in real time. Also use when working with ActivityKit, ActivityAttributes, Activity lifecycle (request/update/end), Dynamic Island layouts (compact/minimal/expanded), push-to-update Live Activities, or Lock Screen live widgets."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # ActivityKit
@@ -365,7 +367,7 @@ the system-managed push update budget. When cadence matters, check
 
 Schedule a Live Activity to start at a future time. The system starts the
 activity automatically without the app being in the foreground. Use for events
-with known start times (sports games, flights, scheduled deliveries).
+with known start times (sports games, product launches, scheduled deliveries).
 
 ```swift
 let scheduledDate = Calendar.current.date(
@@ -390,7 +392,7 @@ let activity = try Activity.request(
 
 Use the iOS 18+ `style:` request parameter to choose persistence behavior. Use
 `.standard` for persistent Live Activities such as deliveries, rides, sports
-scores, timers, and flight/status boards. Use `.transient` only for a
+scores, timers, and order-status boards. Use `.transient` only for a
 short-lived expanded Dynamic Island presentation; it can auto-end when the user
 locks the device, collapses or shrinks the expanded presentation, leaves the
 app, or does other work outside Dynamic Island.

package/pipeline/skills/shared/external/live-activities/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "activitykit",
+  "skill_name": "live-activities",
   "evals": [
     {
       "id": 1,
@@ -16,7 +16,7 @@
     },
     {
       "id": 2,
-      "prompt": "Review this Live Activity plan for mistakes: use Activity.request(attributes:content:pushType:start:) on iOS 26 to schedule a flight board; use style: .transient but guard it as iOS 26 only; send a push-to-start payload without alert because the user already opted into notifications; set NSSupportsLiveActivitiesFrequentUpdates and push updates every 30 seconds; say ended activities always disappear after 8 hours.",
+      "prompt": "Review this Live Activity plan for mistakes: use Activity.request(attributes:content:pushType:start:) on iOS 26 to schedule an order-status board; use style: .transient but guard it as iOS 26 only; send a push-to-start payload without alert because the user already opted into notifications; set NSSupportsLiveActivitiesFrequentUpdates and push updates every 30 seconds; say ended activities always disappear after 8 hours.",
       "expected_output": "A correction-focused review that identifies stale or inaccurate ActivityKit claims and replaces them with current Apple-source behavior.",
       "files": [],
       "expectations": [

package/pipeline/skills/shared/external/localization-reuse-map/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: localization-reuse-map
 description: >-
-  Produce a per-screen localization-reuse map for one redesigned screen (iOS / Android / web): for each UI
-  element it pairs the NEW localization key + values with the LEGACY key + values per platform and the
-  content team's ACTUAL CMS copy read live from Figma Dev Mode annotations, recommends a reuse verdict
-  (reuse / review / new) the content team confirms, renders a key-to-UI overlay plus a per-key red-box
-  screenpiece, and publishes a Confluence page live (idempotent). Also scans the implemented screen for
-  error and dynamic keys the registry misses. Use when mapping a redesigned screen's strings to the
-  legacy ones for reuse, one screen at a time. Trigger phrases  -  "localization reuse map", "map old keys
-  to new keys for this screen", "which legacy translations can we reuse", "reuse existing translations",
-  "CMS copy from Figma annotations", "localization excel", "CMS import sheet", "/localization-reuse-map".
+  Builds a per-screen localization-reuse map for one redesigned screen (iOS, Android, web): pairs each
+  UI element's new key and values with the legacy key per platform and the live CMS copy from Figma Dev
+  Mode annotations, recommends reuse, review or new for the content team to confirm, renders a key-to-UI
+  overlay, publishes a Confluence page, and flags error and dynamic keys the registry misses. Use when
+  mapping one redesigned screen's strings to legacy ones. Triggers - localization reuse map, map old
+  keys to new keys, reuse legacy translations, CMS copy from Figma annotations, localization excel, CMS
+  import sheet, /localization-reuse-map.
 ---
 
 # Localization Reuse Map  -  old↔new localization map for one screen

package/pipeline/skills/shared/external/localization-reuse-map/reference/sources-and-recipes.md

@@ -33,7 +33,7 @@ what it **wires**; neither alone is complete. Do all three:
    gh api "repos/<org>/<specs-repo>/contents/design-export/<project>/screens/<screen-slug>/components-used.md" -H "Accept: application/vnd.github.raw"
    ```
    Read **every state frame** of the screen (empty / 1-item / filled)  -  components only present in the
-   filled state (e.g. a passenger list) still belong to the screen. The folder also has `screenshot.png`,
+   filled state (e.g. an item list) still belong to the screen. The folder also has `screenshot.png`,
    `tree.json` (node ids), `tokens.json`. *(Live alternative if a frame isn't exported: Figma REST via a
    host Figma tool  -  REST works with a token; MCP/live needs Figma Desktop in Dev Mode. The export is
    preferred  -  single-repo.)*
@@ -42,7 +42,7 @@ what it **wires**; neither alone is complete. Do all three:
    python3 -c "import json;d=json.load(open('Resources/Figma/Components/<NODE-DASH>.json'));print([k['key'] for k in d.get('localizationKeys',[])])"
    ```
    These include keys the component renders that **never appear in the screen code** (e.g.
-   `PassengerListGroup.Title`, `PassengerListRow.Delete`). Beware the inverse: a shared
+   `ItemListGroup.Title`, `ItemListRow.Delete`). Beware the inverse: a shared
    component (e.g. `HeaderMain`, `BottomActions`) owns many keys the screen does **not** use because the
    screen passes its own title in  -  confirm against the code.
 3. **What the screen wires**  -  read the scene/screen file: each `LocalizationStringKey.<Ns>.<leaf>` call
@@ -66,7 +66,7 @@ keys: map once where that component is mapped  -  flag, don't duplicate per scre
    # then fetch each cell class and grep its keys:
    gh api ".../Forms/TextInputCell/PresentationModels/<Field>TextInputCellPresentationModel.swift" -H "Accept: application/vnd.github.raw" | grep -oE '"[^"]+"\.localized'
    ```
-   This is how `NewSurnameReq` / `PnrNumber` / `ReservationEticketPlaceHolder` surface  -  a VM-only grep
+   This is how `NewSurnameReq` / `OrderNumber` / `ShippingAddressPlaceHolder` surface  -  a VM-only grep
    misses them. Keys are the string literal before `.localized`.
 3. **Android.** Layout XML carries labels as `@string/Key`; fragment carries runtime strings as `R.string.`:
    ```bash

package/pipeline/skills/shared/external/localization-reuse-map/scripts/resolve-new-values.py

@@ -9,9 +9,9 @@ Why a script: the model otherwise hand-copies 8 languages x N keys out of JSON
 files  -  slow, token-heavy, and error-prone. This is pure file IO, so it is a
 script. Read-only; touches nothing.
 
-Key-form handling: code often references a key as `AddPassenger.continueButton`
+Key-form handling: code often references a key as `AddAddress.continueButton`
 (camelCase leaf) while the Suggested filename PascalCases every dotted segment
-(`AddPassenger.ContinueButton.json`). We normalise the first character of
+(`AddAddress.ContinueButton.json`). We normalise the first character of
 each segment to upper-case before resolving, so either form works as input.
 Accessibility keys live under `AccessibilityStrings/Sources/Suggested/`  -  pass
 `--domain accessibility` for those.

package/pipeline/skills/shared/external/macos-menubar-tuist-app/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: macos-menubar-tuist-app
 description: "Build, refactor, or review SwiftUI macOS menubar apps that use Tuist. Use when building, refactoring or reviewing a SwiftUI macOS menubar app that uses Tuist."
-risk: safe
-source: "Dimillian/Skills (MIT)"
-date_added: "2026-03-25"
+metadata:
+  risk: safe
+  source: "Dimillian/Skills (MIT)"
+  date_added: "2026-03-25"
 ---
 
 # macos-menubar-tuist-app

package/pipeline/skills/shared/external/macos-spm-app-packaging/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: macos-spm-app-packaging
 description: "Scaffold, build, sign, and package SwiftPM macOS apps without Xcode projects. Use when a SwiftPM macOS app has to be built, signed or packaged without an Xcode project."
-risk: safe
-source: "Dimillian/Skills (MIT)"
-date_added: "2026-03-25"
+metadata:
+  risk: safe
+  source: "Dimillian/Skills (MIT)"
+  date_added: "2026-03-25"
 ---
 
 # macOS SwiftPM App Packaging (No Xcode)
 
 ## Overview
 Bootstrap a complete SwiftPM macOS app folder, then build, package, and run it without Xcode. Use `assets/templates/bootstrap/` for the starter layout and `references/packaging.md` + `references/release.md` for packaging and release details.
+Read `references/scaffold.md` when building the package from `swift package init` by hand instead of copying the bootstrap template.
 
 ## When to Use
 

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

@@ -1,6 +1,8 @@
 ---
 name: mapkit-location
 description: "Implement, review, or improve maps and location features in iOS/macOS apps using MapKit and CoreLocation. Use when working with Map views, annotations, markers, polylines, user location tracking, geocoding, reverse geocoding, search/autocomplete, directions and routes, geofencing, region monitoring, CLLocationUpdate async streams, or location authorization flows. Also use when working with maps, coordinates, addresses, places, directions, distance calculations, or location-based features in Swift apps."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # MapKit

package/pipeline/skills/shared/external/mapkit-location/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "mapkit",
+  "skill_name": "mapkit-location",
   "evals": [
     {
       "id": 0,

package/pipeline/skills/shared/external/metrickit-diagnostics/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: metrickit-diagnostics
 description: "Collect and analyze on-device performance metrics and crash diagnostics using MetricKit. Use when setting up MXMetricManager, handling MXMetricPayload or MXDiagnosticPayload, processing crash/hang/disk-write diagnostics via MXCallStackTree, adding custom signpost metrics, correcting mxSignpost or extended launch measurement code, or uploading telemetry to an analytics backend."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # MetricKit

package/pipeline/skills/shared/external/metrickit-diagnostics/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill_name": "metrickit",
+  "skill_name": "metrickit-diagnostics",
   "evals": [
     {
       "id": 0,