macos-app-lifecycle-bridge
Use when a macOS AppKit or SwiftUI app needs lifecycle, activation, window, panel, menu/status-item, event-monitor, reopen, ownership, or teardown work.
SKILL.mdskills/macos-app-lifecycle-bridge/SKILL.md
GitHubmacOS App Lifecycle Bridge
Define one owner for every AppKit resource and one decision point for every user-visible transition.
Route the Work
- Inspect the app entry point, delegate/adaptor, SwiftUI scenes, activation-policy changes, windows, panels, hosting, status items, menus, event monitors, reopen, and shutdown paths.
- Choose a primary lifecycle: SwiftUI scenes with delegate-only integration, or an AppKit coordinator that retains controllers and hosts SwiftUI. Never let both own the same surface or command.
- Read ownership-and-transitions.md to assign owners and model launch, headless, active/inactive, reopen, close, hide, and termination transitions.
- Read windows-menus-and-monitors.md when implementing a window, panel, hosting shell, menu/status item, or event monitor.
- If Xcode MCP is available, run
DocumentationSearch; use apple-documentation.md as the dated API index.
Preserve These Invariants
- Keep lifecycle coordinators, AppKit resources, and their cleanup on the main actor.
- Give each persistent window identity, panel, status item, menu target, and monitor token one retained owner. Views request actions; SwiftUI recomputation must not recreate shells.
- Model activation policy, app activity, visibility, key/main status, and background readiness separately.
- Treat show, activate, make-key, order-front, close, and release as different operations.
- Make reopen, repeated show, start, stop, and teardown idempotent.
- Pair every observer, timer, task, delegate, callback, status item, and monitor with explicit cleanup; avoid owner/callback retain cycles.
- Local event monitors may alter this app's events; global monitors only observe other apps and may require Accessibility trust. Remove each token exactly once.
- Keep menu tracking bounded and perform expensive work before the menu opens.
Complete the Task
Separate transition decisions from AppKit effects where tests benefit. Verify actual activation, focus, panel/menu behavior, repeated presentation, and teardown—not only compilation. Report the ownership graph, transition behavior, cleanup guarantees, and runtime evidence.
Review
- Last updated: 2026-08-30
- Last reviewed: 2026-08-30
- Apple documentation reviewed: 2026-08-30
Scope/evidence: AppKit and SwiftUI lifecycle ownership, activation, windows, panels, menus, event monitors, reopen, and teardown guidance was checked with Xcode MCP DocumentationSearch.