/offline-queue

name: offline-queue
description: Generates an offline operation queue with persistence, automatic retry on connectivity, and conflict resolution. Use when user needs offline-first behavior, queued mutations, or pending operations that sync when back online.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Offline Queue Generator

Generate a production offline operation queue that persists API requests/mutations when offline, stores them to disk, and retries with exponential backoff when connectivity returns. Essential for apps that need offline-first behavior.

When This Skill Activates

Use this skill when the user:

• Asks to "add offline queue" or "offline support"
• Wants to "queue requests" when there is no network
• Mentions "offline first" architecture or design
• Asks about "retry when online" or "retry on reconnect"
• Wants "pending operations" that sync later
• Mentions "offline mutations" or "queue API calls"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check Swift version (requires Swift 5.9+)
• [ ] Check deployment target (iOS 16+ / macOS 13+)
• [ ] Check for @Observable support (iOS 17+ / macOS 14+)
• [ ] Identify source file locations

2. Conflict Detection

Search for existing networking/offline code:

Glob: **/*OfflineQueue*.swift, **/*OfflineOperation*.swift, **/*NetworkMonitor*.swift, **/*RetryPolicy*.swift
Grep: "NWPathMonitor" or "OfflineQueue" or "pendingOperations" or "offlineQueue"

If existing offline handling found:

• Ask if user wants to replace or extend it
• If extending, adapt generated code to existing patterns

3. Framework Availability

Check for Network framework availability (required for NWPathMonitor). Available on iOS 12+ / macOS 10.14+, so effectively always available for our iOS 16+ / macOS 13+ targets.

Configuration Questions

Ask user via AskUserQuestion:

1. **Operation types?**

• API calls only (JSON requests/responses)
• File uploads only (multipart data)
• Both API calls and file uploads

2. **Persistence strategy?**

• SwiftData (iOS 17+ / macOS 14+) — structured queries, migration support
• File-based (JSON files in app support) — simpler, wider compatibility — recommended

3. **Retry strategy?**

• Exponential backoff with jitter — recommended (prevents thundering herd)
• Linear backoff (fixed interval between retries)
• Immediate (retry as soon as connectivity returns, no delay)

4. **Conflict resolution?**

• Server wins (discard client changes on conflict)
• Client wins (overwrite server data on conflict)
• Manual merge (surface conflicts to the user for resolution)

Generation Process

Step 1: Read Templates

Read `patterns.md` for architecture guidance and conflict resolution strategies. Read `templates.md` for production Swift code.

Step 2: Create Core Files

Generate these files: 1. `OfflineOperation.swift` — Codable model for queued operations 2. `OfflineQueueManager.swift` — Actor managing enqueue, dequeue, process, retry 3. `QueuePersistence.swift` — Protocol + file-based implementation for saving operations 4. `NetworkMonitor.swift` — @Observable wrapper around NWPathMonitor

Step 3: Create Policy Files

5. `RetryPolicy.swift` — Configurable backoff strategy with jitter

Step 4: Create UI Files

6. `OfflineQueueDashboardView.swift` — Debug view showing queue state and manual controls 7. `OfflineQueueModifier.swift` — ViewModifier showing "Offline" banner when disconnected

Step 5: Determine File Location

Check project structure:

• If `Sources/` exists → `Sources/OfflineQueue/`
• If `App/` exists → `App/OfflineQueue/`
• Otherwise → `OfflineQueue/`

Output Format

After generation, provide:

Files Created

OfflineQueue/
├── OfflineOperation.swift          # Codable operation model
├── OfflineQueueManager.swift       # Actor-based queue manager
├── QueuePersistence.swift          # Protocol + file-based persistence
├── NetworkMonitor.swift            # NWPathMonitor wrapper
├── RetryPolicy.swift               # Exponential backoff with jitter
├── OfflineQueueDashboardView.swift # Debug dashboard view
└── OfflineQueueModifier.swift      # Offline banner modifier

Integration with Networking Layer

**Enqueue an operation when offline:**

// In your networking layer or repository
func createPost(_ post: Post) async throws {
    guard networkMonitor.isConnected else {
        let operation = OfflineOperation(
            endpoint: "/api/posts",
            httpMethod: .post,
            body: try JSONEncoder().encode(post),
            headers: ["Content-Type": "application/json"]
        )
        await queueManager.enqueue(operation)
        return
    }
    // Normal online request
    try await apiClient.post("/api/posts", body: post)
}

**Transparent offline support with a wrapper:**

func performOrQueue<T: Codable>(
    endpoint: String,
    method: HTTPMethod,
    body: T
) async throws {
    let data = try JSONEncoder().encode(body)

    if networkMonitor.isConnected {
        try await apiClient.request(endpoint: endpoint, method: method, body: data)
    } else {
        let operation = OfflineOperation(
            endpoint: endpoint,
            httpMethod: method,
            body: data
        )
        await queueManager.enqueue(operation)
    }
}

**Show offline banner in your app:**

struct ContentView: View {
    var body: some View {
        NavigationStack {
            FeedView()
        }
        .offlineQueueBanner()  // Shows "Offline — changes will sync" when disconnected
    }
}

**Add dashboard for debugging:**

#if DEBUG
NavigationLink("Offline Queue") {
    OfflineQueueDashboardView()
}
#endif

Testing

@Test
func operationEnqueuedWhenOffline() async throws {
    let persistence = MockQueuePersistence()
    let monitor = MockNetworkMo