@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/rest-api-design/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: rest-api-design
 description: "REST API design: HTTP methods, status codes, pagination, versioning, rate limiting, caching headers, OpenAPI documentation"
 tags: [rest, api, http, openapi, pagination, backend]
 version: "2025.1"
@@ -55,26 +56,26 @@ GET    /api/v1/posts?fields=id,title,slug      # Sparse fieldsets
 
 ```
 # Success
-200 OK              — Successful GET, PUT, PATCH, DELETE
-201 Created         — Successful POST (include Location header)
-204 No Content      — Successful DELETE with no response body
-206 Partial Content — Paginated list or range request
+200 OK               -  Successful GET, PUT, PATCH, DELETE
+201 Created          -  Successful POST (include Location header)
+204 No Content       -  Successful DELETE with no response body
+206 Partial Content  -  Paginated list or range request
 
 # Client Errors
-400 Bad Request     — Invalid syntax, validation error
-401 Unauthorized    — Missing or invalid authentication
-403 Forbidden       — Authenticated but not authorized
-404 Not Found       — Resource does not exist
-405 Method Not Allowed — HTTP method not supported on this endpoint
-409 Conflict        — Duplicate resource, state conflict
-422 Unprocessable Entity — Valid syntax but semantic errors
-429 Too Many Requests — Rate limit exceeded
+400 Bad Request      -  Invalid syntax, validation error
+401 Unauthorized     -  Missing or invalid authentication
+403 Forbidden        -  Authenticated but not authorized
+404 Not Found        -  Resource does not exist
+405 Method Not Allowed  -  HTTP method not supported on this endpoint
+409 Conflict         -  Duplicate resource, state conflict
+422 Unprocessable Entity  -  Valid syntax but semantic errors
+429 Too Many Requests  -  Rate limit exceeded
 
 # Server Errors
-500 Internal Server Error — Unexpected server failure
-502 Bad Gateway     — Upstream service failure
-503 Service Unavailable — Temporary overload or maintenance
-504 Gateway Timeout — Upstream timeout
+500 Internal Server Error  -  Unexpected server failure
+502 Bad Gateway      -  Upstream service failure
+503 Service Unavailable  -  Temporary overload or maintenance
+504 Gateway Timeout  -  Upstream timeout
 ```
 
 ## Response Envelope
@@ -218,10 +219,10 @@ GET /api/users?version=2
 
 ```typescript
 // Response headers
-// X-RateLimit-Limit: 100          — Max requests per window
-// X-RateLimit-Remaining: 67       — Remaining requests
-// X-RateLimit-Reset: 1705312800   — Unix timestamp when window resets
-// Retry-After: 30                 — Seconds to wait (on 429)
+// X-RateLimit-Limit: 100           -  Max requests per window
+// X-RateLimit-Remaining: 67        -  Remaining requests
+// X-RateLimit-Reset: 1705312800    -  Unix timestamp when window resets
+// Retry-After: 30                  -  Seconds to wait (on 429)
 
 // Express middleware example
 import rateLimit from 'express-rate-limit';

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

@@ -1,13 +1,13 @@
 ---
 name: shareplay-activities
-description: "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime/iMessage-integrated group activity on iOS, macOS, tvOS, or visionOS."
+description: "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime, Messages, AirDrop, or nearby visionOS group activity on iOS, macOS, tvOS, or visionOS."
 ---
 
 # GroupActivities / SharePlay
 
 Build shared real-time experiences using the GroupActivities framework. SharePlay
-connects people over FaceTime or iMessage, synchronizing media playback, app state,
-or custom data. Targets Swift 6.2 / iOS 26+.
+connects people over FaceTime, Messages, AirDrop, and nearby visionOS sharing,
+synchronizing media playback, app state, or custom data. Targets Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -24,23 +24,18 @@ or custom data. Targets Swift 6.2 / iOS 26+.
 
 ## Setup
 
-### Entitlements
+### Capability
 
-Add the Group Activities entitlement to your app:
+Add the **Group Activities** capability to the app target in Xcode. Xcode adds
+the required entitlement and updates the provisioning profile:
 
 ```xml
 <key>com.apple.developer.group-session</key>
 <true/>
 ```
 
-### Info.plist
-
-For apps that start SharePlay without a FaceTime call (iOS 17+), add:
-
-```xml
-<key>NSSupportsGroupActivities</key>
-<true/>
-```
+Configure this only for app targets. Group Activities are not available in
+widgets, extensions, or App Clips.
 
 ### Checking Eligibility
 
@@ -49,7 +44,7 @@ import GroupActivities
 
 let observer = GroupStateObserver()
 
-// Check if a FaceTime call or iMessage group is active
+// Check if a FaceTime call or Messages conversation is active
 if observer.isEligibleForGroupSession {
     showSharePlayButton()
 }
@@ -69,7 +64,6 @@ Conform to `GroupActivity` and provide metadata:
 
 ```swift
 import GroupActivities
-import CoreTransferable
 
 struct WatchTogetherActivity: GroupActivity {
     let movieID: String
@@ -93,10 +87,16 @@ struct WatchTogetherActivity: GroupActivity {
 | `.watchTogether` | Video playback |
 | `.listenTogether` | Audio playback |
 | `.createTogether` | Collaborative creation (drawing, editing) |
+| `.exploreTogether` | Shared browsing, planning, or exploration |
+| `.learnTogether` | Shared learning or studying |
+| `.readTogether` | Shared reading |
+| `.shopTogether` | Shared shopping |
 | `.workoutTogether` | Shared fitness sessions |
 
-The activity struct must conform to `Codable` so the system can transfer it
-between devices.
+`GroupActivity` is `Codable`; stored activity data must be codable. Add
+`Transferable` only for SwiftUI `ShareLink`, SharePlay over AirDrop, or
+AppKit/UIKit share sheets. Keep payloads minimal: use identifiers or URLs
+instead of large data.
 
 ## Session Lifecycle
 
@@ -111,7 +111,7 @@ the activity:
 final class SharePlayManager {
     private var session: GroupSession<WatchTogetherActivity>?
     private var messenger: GroupSessionMessenger?
-    private var tasks = TaskGroup()
+    private var sessionTasks: [Task<Void, Never>] = []
 
     func observeSessions() {
         Task {
@@ -128,22 +128,31 @@ final class SharePlayManager {
         self.messenger = GroupSessionMessenger(session: session)
 
         // Observe session state changes
-        Task {
+        let stateTask = Task {
             for await state in session.$state.values {
                 handleState(state)
             }
         }
+        sessionTasks.append(stateTask)
 
         // Observe participant changes
-        Task {
+        let participantTask = Task {
             for await participants in session.$activeParticipants.values {
                 handleParticipants(participants)
             }
         }
+        sessionTasks.append(participantTask)
 
         // Join the session
         session.join()
     }
+
+    private func cleanUp() {
+        sessionTasks.forEach { $0.cancel() }
+        sessionTasks.removeAll()
+        session = nil
+        messenger = nil
+    }
 }
 ```
 
@@ -190,11 +199,12 @@ session?.end()
 
 ## Sending and Receiving Messages
 
-Use `GroupSessionMessenger` to sync app state between participants.
+Use `GroupSessionMessenger` to sync small, time-sensitive app state between
+participants.
 
 ### Defining Messages
 
-Messages must be `Codable`:
+Messages must be `Codable`; keep each message under 256 KB.
 
 ```swift
 struct SyncMessage: Codable {
@@ -235,21 +245,22 @@ func observeMessages() {
 ### Delivery Modes
 
 ```swift
-// Reliable (default) -- guaranteed delivery, ordered
+// Reliable (default) -- checked and retried for crucial state
 let reliableMessenger = GroupSessionMessenger(
     session: session,
     deliveryMode: .reliable
 )
 
-// Unreliable -- faster, no guarantees (good for frequent position updates)
+// Unreliable -- lower latency, no delivery guarantee
 let unreliableMessenger = GroupSessionMessenger(
     session: session,
     deliveryMode: .unreliable
 )
 ```
 
-Use `.reliable` for state-changing actions (play/pause, selections). Use
-`.unreliable` for high-frequency ephemeral data (cursor positions, drawing strokes).
+Use `.reliable` for state-changing actions such as selections or turns. Use
+`.unreliable` for high-frequency ephemeral data such as cursor positions,
+drawing strokes, and reactions.
 
 ## Coordinated Media Playback
 
@@ -269,21 +280,9 @@ func configurePlayback(
 }
 ```
 
-Once connected, play/pause/seek actions on any participant's player are
-automatically synchronized to all other participants. No manual message
-passing is needed for playback controls.
-
-### Handling Playback Events
-
-```swift
-// Notify participants about playback events
-let event = GroupSessionEvent(
-    originator: session.localParticipant,
-    action: .play,
-    url: nil
-)
-session.showNotice(event)
-```
+Once connected, AVFoundation synchronizes play/pause, seeking, rate, playback speed,
+and time. Do not put AVPlayer transport fields in messenger messages or snapshots,
+including late-joiner snapshots; use custom messages only for state outside playback.
 
 ## Starting SharePlay from Your App
 
@@ -301,13 +300,12 @@ func startSharePlay() async throws {
 
     switch await activity.prepareForActivation() {
     case .activationPreferred:
-        // Present the sharing controller
-        let controller = try GroupActivitySharingController(activity)
-        present(controller, animated: true)
+        // A conversation is active and the user chose to share.
+        _ = try await activity.activate()
 
     case .activationDisabled:
-        // SharePlay is disabled or unavailable
-        print("SharePlay not available")
+        // The user chose local playback, or sharing is unavailable.
+        startLocalExperience()
 
     case .cancelled:
         break
@@ -318,21 +316,36 @@ func startSharePlay() async throws {
 }
 ```
 
-For `ShareLink` (SwiftUI) and direct `activity.activate()` patterns, see
-`references/shareplay-patterns.md`.
+When no conversation is active (i.e., `isEligibleForGroupSession` is false),
+use `GroupActivitySharingController` to let the user pick contacts first:
+
+```swift
+let controller = try GroupActivitySharingController(activity)
+present(controller, animated: true)
+```
+
+Use the `shareplay` SF Symbol for custom controls. Treat `GroupActivityMetadata`
+as discovery copy: concise title, subtitle, image, and type aligned with the
+entry point. Keep sibling domains out: GameKit owns auth, matchmaking,
+leaderboards, achievements, and voice/chat; TabletopKit owns seats, board
+equipment, spatial placement, turns, rules, and authoritative tabletop state;
+AVKit owns playback UI. SharePlay owns invitations, lifecycle, participants, and
+coordination handoffs. See [references/shareplay-patterns.md](references/shareplay-patterns.md) for SwiftUI `ShareLink`, AirDrop, and direct activation patterns.
 
 ## GroupSessionJournal: File Transfer
 
-For large data (images, files), use `GroupSessionJournal` instead of
-`GroupSessionMessenger` (which has a size limit):
+For larger, non-time-sensitive attachments, use `GroupSessionJournal` instead
+of `GroupSessionMessenger`. Journal items must conform to `Transferable`, are
+available to late joiners, and are limited to 100 MB. It requires iOS/iPadOS/tvOS
+17+, macOS 14+, or visionOS 1+. For larger/protected assets, share a pointer or manifest and use server storage or app-managed file transfer.
 
 ```swift
 import GroupActivities
 
 let journal = GroupSessionJournal(session: session)
 
-// Upload a file
-let attachment = try await journal.add(imageData)
+// Upload a Transferable file or data item
+let attachment = try await journal.add(sharedImageItem)
 
 // Observe incoming attachments
 Task {
@@ -400,16 +413,16 @@ func handleParticipants(_ participants: Set<Participant>) {
 }
 ```
 
-### DON'T: Use GroupSessionMessenger for large data
+### DON'T: Use SharePlay transports for large/protected assets
 
 ```swift
-// WRONG -- messenger has a per-message size limit
-let largeImage = try Data(contentsOf: imageURL)  // 5 MB
-try await messenger.send(largeImage, to: .all)    // May fail
-
-// CORRECT -- use GroupSessionJournal for files
+// WRONG -- messenger is small/time-sensitive; journal is Transferable and <=100 MB
+let imageData = try Data(contentsOf: imageURL)     // 300 KB
+try await messenger.send(imageData, to: .all)      // Too large
+// CORRECT -- journal attachments up to 100 MB; otherwise share a pointer/manifest
 let journal = GroupSessionJournal(session: session)
-try await journal.add(largeImage)
+try await journal.add(sharedImageItem)
+// Larger/protected assets: server storage or app-managed file transfer
 ```
 
 ### DON'T: Send redundant messages for media playback
@@ -454,23 +467,25 @@ final class ActivityManager {
 
 ## Review Checklist
 
-- [ ] Group Activities entitlement (`com.apple.developer.group-session`) added
+- [ ] Group Activities capability added to the app target only
 - [ ] `GroupActivity` struct is `Codable` with meaningful metadata
+- [ ] `Transferable` conformance added when using `ShareLink`, AirDrop, or share sheets
 - [ ] `sessions()` observed in a long-lived object (not a SwiftUI view body)
 - [ ] `session.join()` called after receiving and configuring the session
 - [ ] `session.leave()` called when the user navigates away or dismisses
-- [ ] `GroupSessionMessenger` created with appropriate `deliveryMode`
+- [ ] `GroupSessionMessenger` messages stay under 256 KB with appropriate `deliveryMode`
 - [ ] Late-joining participants receive current state on connection
 - [ ] `$state` and `$activeParticipants` publishers observed for lifecycle changes
-- [ ] `GroupSessionJournal` used for large file transfers instead of messenger
+- [ ] `GroupSessionJournal` used for non-time-sensitive `Transferable` attachments
 - [ ] `AVPlaybackCoordinator` used for media sync (not manual messages)
 - [ ] `GroupStateObserver.isEligibleForGroupSession` checked before showing SharePlay UI
-- [ ] `prepareForActivation()` called before presenting sharing controller
+- [ ] `GroupActivitySharingController` used when no conversation is active
 - [ ] Session invalidation handled with cleanup of messenger, journal, and tasks
 
 ## References
 
-- Extended patterns (collaborative canvas, spatial Personas, custom templates): `references/shareplay-patterns.md`
+- Extended patterns (SwiftUI sharing, collaborative canvas, spatial Personas): [references/shareplay-patterns.md](references/shareplay-patterns.md)
+- [Configuring Group Activities](https://sosumi.ai/documentation/xcode/configuring-group-activities)
 - [GroupActivities framework](https://sosumi.ai/documentation/groupactivities)
 - [GroupActivity protocol](https://sosumi.ai/documentation/groupactivities/groupactivity)
 - [GroupSession](https://sosumi.ai/documentation/groupactivities/groupsession)
@@ -481,3 +496,5 @@ final class ActivityManager {
 - [Defining your app's SharePlay activities](https://sosumi.ai/documentation/groupactivities/defining-your-apps-shareplay-activities)
 - [Presenting SharePlay activities from your app's UI](https://sosumi.ai/documentation/groupactivities/promoting-shareplay-activities-from-your-apps-ui)
 - [Synchronizing data during a SharePlay activity](https://sosumi.ai/documentation/groupactivities/synchronizing-data-during-a-shareplay-activity)
+- [Supporting coordinated media playback](https://sosumi.ai/documentation/avfoundation/supporting-coordinated-media-playback)
+- [SharePlay HIG](https://sosumi.ai/design/human-interface-guidelines/shareplay)

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

@@ -0,0 +1,47 @@
+{
+  "skill_name": "shareplay-activities",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm adding SharePlay to a SwiftUI movie app. Show the Group Activities setup, the activity type and metadata, how to start the activity from the app, how to listen for sessions, and how to sync AVPlayer playback. Keep custom messages only where they are actually needed.",
+      "expected_output": "A source-grounded SharePlay media implementation plan that uses the Group Activities capability, a codable GroupActivity, prepareForActivation/activate or GroupActivitySharingController, long-lived session observation with join/leave cleanup, and AVPlaybackCoordinator for player rate/time sync.",
+      "files": [],
+      "assertions": [
+        "Adds the Group Activities capability to the app target and references the `com.apple.developer.group-session` entitlement without inventing unsupported Info.plist keys.",
+        "Defines a `GroupActivity` with codable stored data, concise `GroupActivityMetadata`, `.watchTogether`, and a fallback URL or equivalent content identifier.",
+        "Uses `GroupStateObserver.isEligibleForGroupSession` to choose between direct activation and presenting `GroupActivitySharingController` when no conversation is active.",
+        "Observes `Activity.sessions()` in a long-lived manager, stores cancellable `Task<Void, Never>` handles, calls `session.join()`, and cleans up on invalidation or leave.",
+        "Uses `player.playbackCoordinator.coordinateWithSession(session)` for AVPlayer rate/time synchronization and avoids redundant play/pause/seek messenger messages.",
+        "Keeps app-specific `GroupSessionMessenger` messages separate from AVPlayer transport sync."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this collaborative whiteboard SharePlay design: every stroke is sent reliably, image drops are sent through GroupSessionMessenger as Data, late joiners rebuild from whatever messages they happen to receive, and the sessions() listener is in a SwiftUI view task. Fix the architecture.",
+      "expected_output": "A correction-focused SharePlay architecture that separates reliable and unreliable message streams, uses GroupSessionJournal for large Transferable attachments, sends state snapshots to late joiners, and moves session observation into a retained manager.",
+      "files": [],
+      "assertions": [
+        "Moves `sessions()` observation out of a recreated SwiftUI view and into a retained manager or model object.",
+        "Uses unreliable messaging for high-frequency ephemeral stroke or cursor updates and reliable messaging for durable state-changing commands such as clear canvas or selections.",
+        "Mentions that messenger payloads should stay under 256 KB and should not carry large image/file data.",
+        "Uses `GroupSessionJournal` for larger non-time-sensitive attachments, notes `Transferable` item requirements, and includes the 100 MB attachment limit.",
+        "Handles late joiners by detecting new participants and sending a full state snapshot or equivalent canonical state.",
+        "Includes leave/end and task cleanup so abandoned sessions and message listeners do not leak."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I want a SharePlay launch path that works from a normal SwiftUI share button, over AirDrop when people are nearby, and from a custom UIKit button when no FaceTime call is active. Also call out what belongs in GameKit, TabletopKit, or AVKit instead of this SharePlay layer.",
+      "expected_output": "A boundary-aware SharePlay UI plan that uses Transferable for ShareLink/AirDrop/share sheets, GroupActivitySharingController for no active conversation, and keeps Game Center services, TabletopKit board mechanics, and AVKit playback UI or media player details in sibling framework domains.",
+      "files": [],
+      "assertions": [
+        "States that SwiftUI `ShareLink`, SharePlay over AirDrop, and system share sheets require the activity or shared item to conform to `Transferable`.",
+        "Keeps the transferable payload minimal by sharing IDs, URLs, or activity descriptors instead of large media or documents.",
+        "Uses `GroupActivitySharingController` when no FaceTime call or Messages conversation is active and direct `prepareForActivation()`/`activate()` when one is active.",
+        "Mentions the `shareplay` SF Symbol or equivalent UI affordance and concise activity metadata as discoverability guidance.",
+        "Keeps GameKit authentication, leaderboards, matchmaking, and voice/chat out of the SharePlay implementation except for handoff boundaries.",
+        "Keeps TabletopKit board equipment/seat/action mechanics and AVKit playback UI details outside the SharePlay layer while allowing GroupActivities session coordination handoffs."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/shareplay-activities/references/shareplay-patterns.md

@@ -8,6 +8,7 @@ patterns that exceed the main skill file's scope.
 - [Collaborative Drawing Canvas](#collaborative-drawing-canvas)
 - [Full SharePlay Manager](#full-shareplay-manager)
 - [SwiftUI SharePlay Integration](#swiftui-shareplay-integration)
+  - [ShareLink and AirDrop](#sharelink-and-airdrop)
 - [Custom Activity with State Sync](#custom-activity-with-state-sync)
 - [Participant Tracking](#participant-tracking)
 
@@ -76,12 +77,11 @@ final class DrawingManager {
     var isConnected = false
 
     func startObserving() {
-        let task = Task {
+        Task {
             for await session in DrawTogetherActivity.sessions() {
-                await configureSession(session)
+                configureSession(session)
             }
         }
-        tasks.append(task)
     }
 
     private func configureSession(
@@ -186,13 +186,15 @@ final class SharePlayManager<Activity: GroupActivity> {
 
     private var tasks: [Task<Void, Never>] = []
 
+    // GroupSessionJournal requires iOS/iPadOS/tvOS 17+, macOS 14+,
+    // or visionOS 1+. Gate this property if your deployment target is older.
+
     func startObserving() {
-        let task = Task {
+        Task {
             for await session in Activity.sessions() {
-                await configure(session)
+                configure(session)
             }
         }
-        tasks.append(task)
     }
 
     private func configure(_ session: GroupSession<Activity>) {
@@ -292,6 +294,36 @@ enum SharePlayError: Error {
 
 ## SwiftUI SharePlay Integration
 
+Use this section when surfacing activities through SwiftUI controls. A custom
+button works best when a FaceTime call or Messages conversation is already
+active. Use `ShareLink`, UIKit/AppKit share sheets, or
+`GroupActivitySharingController` when the user needs to choose participants.
+
+### ShareLink and AirDrop
+
+SwiftUI `ShareLink`, SharePlay over AirDrop, and system share sheets require
+the shared item or activity to conform to `Transferable`. Keep the transferable
+payload small; share IDs and URLs, then load heavy content after joining.
+
+```swift
+import CoreTransferable
+import GroupActivities
+import SwiftUI
+
+extension WatchTogetherActivity: Transferable {
+    static var transferRepresentation: some TransferRepresentation {
+        GroupActivityTransferRepresentation { activity in
+            activity
+        }
+    }
+}
+
+ShareLink(
+    item: WatchTogetherActivity(movieID: movieID, movieTitle: movieTitle),
+    preview: SharePreview(movieTitle)
+)
+```
+
 ### SharePlay Button
 
 ```swift
@@ -339,7 +371,7 @@ struct SharePlayStatusView: View {
 
     var body: some View {
         if isConnected {
-            HStack(spacing: 4) {
+            HStack {
                 Image(systemName: "shareplay")
                     .foregroundStyle(.green)
                 Text("\(participantCount) connected")
@@ -353,9 +385,13 @@ struct SharePlayStatusView: View {
 
 ### Full Activity View
 
+Create the session manager at an app, scene, or feature coordinator boundary and
+inject it into SwiftUI. The content view should use the manager, not own the
+`sessions()` observation lifecycle.
+
 ```swift
 struct SharedMovieView: View {
-    @State private var manager = SharePlayManager<WatchTogetherActivity>()
+    @Environment(SharePlayManager<WatchTogetherActivity>.self) private var manager
 
     let movieID: String
     let movieTitle: String
@@ -530,7 +566,10 @@ final class ParticipantTracker {
 
 ### Nearby Participant Detection
 
-On iOS 17+ and visionOS, check if participants are physically nearby:
+On visionOS 26+, nearby Apple Vision Pro participants can join the same group
+activity. The core session, messenger, and journal APIs treat nearby and
+FaceTime participants the same; use `isNearbyWithLocalParticipant` only when UI
+or spatial placement needs to distinguish them:
 
 ```swift
 for participant in session.activeParticipants {