generators-background-processing

First step: Tell the user: "generators-background-processing skill loaded."

Background Processing Generator

Generate production background processing infrastructure -- BGTaskScheduler for periodic refresh and long-running tasks, background URLSession for downloads/uploads that survive app termination, and silent push handling for server-triggered updates.

When This Skill Activates

Use this skill when the user:

• Asks to "add background processing" or "background tasks"
• Mentions "BGTaskScheduler" or "BGAppRefreshTask" or "BGProcessingTask"
• Wants "background refresh" or "periodic background updates"
• Asks about "background downloads" or "background uploads"
• Mentions "silent push" or "content-available push notifications"
• Wants data to sync or update while the app is in the background
• Asks about "background fetch" or "background execution"

Pre-Generation Checks

1. Project Context Detection

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

2. Existing Background Task Detection

Search for existing background task code:

Glob: **/*BackgroundTask*.swift, **/*BGTask*.swift, **/*BackgroundDownload*.swift
Grep: "BGTaskScheduler" or "BGAppRefreshTask" or "BGProcessingTask" or "backgroundSession"

If existing background code found:

• Ask if user wants to replace or augment it
• If augmenting, identify what is missing and generate only those pieces

3. Info.plist Check

Search for existing background modes configuration:

Grep: "BGTaskSchedulerPermittedIdentifiers" or "UIBackgroundModes"

Check for push notification entitlements if silent push is needed:

Glob: **/*.entitlements
Grep: "aps-environment"

Configuration Questions

Ask user via AskUserQuestion:

1. What background processing do you need?

   • App refresh (lightweight periodic updates -- weather, feeds, content)
   • Data processing (long-running -- database cleanup, ML model updates, large syncs)
   • Background downloads (files, media, assets that survive app termination)
   • Silent push notifications (server-triggered content updates)
   • Multiple (select which combination)

2. How often should background tasks run?

   • Hourly (system decides exact timing, best-effort)
   • Every few hours (recommended for most apps)
   • Daily (content that changes infrequently)
   • On content change via push (server triggers update with silent push)

3. Does the task need network access?

   • Yes -- needs background fetch or download capability
   • No -- local processing only (database maintenance, cleanup)

Generation Process

Step 1: Read Templates

Read templates.md for production Swift code.

Step 2: Create Core Files

Generate these files:

1. BackgroundTaskManager.swift -- Central manager for registering and scheduling all background tasks
2. BackgroundTaskConfiguration.swift -- Info.plist keys, entitlements, and task identifier constants

Step 3: Create Feature-Specific Files

Based on configuration: 3. BackgroundDownloadManager.swift -- If background downloads selected 4. SilentPushHandler.swift -- If silent push selected

Step 4: Determine File Location

Check project structure:

• If Sources/ exists -> Sources/BackgroundProcessing/
• If App/ exists -> App/BackgroundProcessing/
• Otherwise -> BackgroundProcessing/

Output Format

After generation, provide:

Files Created

BackgroundProcessing/
├── BackgroundTaskManager.swift        # BGTaskScheduler registration & scheduling
├── BackgroundTaskConfiguration.swift  # Task identifiers and Info.plist config
├── BackgroundDownloadManager.swift    # Background URLSession downloads (optional)
└── SilentPushHandler.swift            # Silent push handling (optional)

Integration with App Lifecycle

Register tasks at app launch (must happen before app finishes launching):

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor private var appDelegate: AppDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        BackgroundTaskManager.shared.registerTasks()
        return true
    }
}

Schedule refresh when app enters background:

struct ContentView: View {
    @Environment(\.scenePhase) private var scenePhase

    var body: some View {
        NavigationStack {
            FeedView()
        }
        .onChange(of: scenePhase) { _, newPhase in
            if newPhase == .background {
                BackgroundTaskManager.shared.scheduleAppRefresh()
            }
        }
    }
}

Start a background download:

func downloadAsset(from url: URL) {
    BackgroundDownloadManager.shared.startDownload(from: url)
}

Handle silent push in AppDelegate:

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    await SilentPushHandler.shared.handle(userInfo: userInfo)
}

Testing

Simulate background task in Xcode debugger (LLDB):

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.app.refresh"]

Simulate expiration:

e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.app.refresh"]

Test background download:

#if DEBUG
func simulateBackgroundDownload() {
    let testURL = URL(string: "https://example.com/test-asset.zip")!
    BackgroundDownloadManager.shared.startDownload(from: testURL)
}
#endif

Required Info.plist Configuration

Add to Info.plist:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.app.refresh</string>
    <string>com.app.processing</string>
</array>

Required Background Modes

In Xcode: Target > Signing & Capabilities > Background Modes:

• Background fetch -- for BGAppRefreshTask
• Background processing -- for BGProcessingTask
• Remote notifications -- for silent push
• Background download -- for background URLSession (automatic when using background configuration)

Common Patterns

Schedule Refresh on Entering Background

Always schedule the next refresh when the app goes to background. The system decides when to actually run it.

BackgroundTaskManager.shared.scheduleAppRefresh()

Long-Running Processing with Expiration Handling

BGProcessingTask can run for minutes, but always handle the expirationHandler to save progress.

task.expirationHandler = {
    // Save partial progress so next run can resume
    processingJob.saveCheckpoint()
}

Energy-Efficient Background Work

// Only process on Wi-Fi + power
let request = BGProcessingTaskRequest(identifier: taskID)
request.requiresNetworkConnectivity = true
request.requiresExternalPower = true

Gotchas

Registration Must Happen Before didFinishLaunching Returns

BGTaskScheduler.shared.register(forTaskWithIdentifier:) must be called during didFinishLaunchingWithOptions. If called later, the registration silently fails. Always register in AppDelegate, never in a View.

System Controls Scheduling

The system decides when to run background tasks based on battery, network, user patterns, and frequency. You cannot guarantee exact timing. earliestBeginDate is a hint, not a guarantee.

Background URLSession Delegate Callbacks

Background URLSession delivers delegate callbacks even if the app was terminated and relaunched. The session must be recreated with the same identifier, and application(_:handleEventsForBackgroundURLSession:completionHandler:) must be implemented.

Silent Push Limitations

Silent push notifications are rate-limited by APNs. If you send too many, the system throttles them. Use them for important content changes, not periodic polling.

30-Second Window for App Refresh

BGAppRefreshTask gives you approximately 30 seconds of execution time. For longer work, use BGProcessingTask instead (which can run for several minutes when conditions are met).

Simulator Limitations

Background tasks do not run naturally on the Simulator. Use the LLDB _simulateLaunchForTaskWithIdentifier: command to trigger them manually during development.

References

• templates.md -- All production Swift templates for background processing
• Background Tasks Framework
• Downloading Files in the Background
• Pushing Background Updates to Your App
• Related: generators-push-notifications -- Full push notification infrastructure
• Related: generators-offline-queue -- Queue operations for when back online