/appkit-app-architecture-workflow

name: appkit-app-architecture-workflow
description: Guide AppKit app-structure decisions for macOS apps across app delegates, status-item menu bar apps, responder-chain menus, windows, controllers, restoration, archiving, Observation, and mixed AppKit/SwiftUI composition. Use when the user wants help deciding where AppKit responsibilities belong or how to avoid steering a macOS app into SwiftUI-only structure when AppKit owns the behavior.

AppKit App Architecture Workflow

Purpose

Provide a docs-first workflow for AppKit app-structure decisions in macOS apps. This skill owns ownership-boundary guidance for AppKit lifetimes, menu bar apps, menus, responder-chain action routing, windows, controllers, restoration, archiving, AppKit MVC, Observation interop, and mixed AppKit/SwiftUI composition.

It is not the Apple-docs router, not the SwiftUI architecture workflow, not the accessibility workflow, and not the Xcode execution workflow.

For Xcode app source layout, keep UIKit/AppKit controller support view-adjacent: `Sources/Views/Shared`, `Sources/Views/macOS`, and `Sources/Views/iOS` own view surfaces, and controller support files use concatenated prefixed names such as `GEAWhateverViewController.swift` beside their matching view. Do not collect ordinary app controller support in a root `Controllers/` directory.

When To Use

• Use this skill when the user wants help structuring an AppKit or mixed

AppKit/SwiftUI macOS app.

• Use this skill when the question involves `NSApplication`,

`NSApplicationDelegate`, app activation policy, app reopen behavior, menu bar apps, `NSStatusItem`, status menus, popovers, panels, or quit behavior.

• Use this skill when the question involves the main menu, contextual menus,

toolbar actions, target/action, responder-chain action routing, or menu validation.

• Use this skill when deciding whether app-level, window-level, controller-level,

document-level, model-level, or hosted SwiftUI state should own a responsibility.

• Use this skill for old-school AppKit restoration, including restoration

identifiers, `NSWindowRestoration`, window-controller restoration, document reopening, and workspace reopening.

• Use this skill when deciding between `NSSecureCoding`, `NSKeyedArchiver`,

`Codable`, user defaults, files, Core Data, SwiftData, or another persistence surface for AppKit-owned state.

• Use this skill when a mixed AppKit/SwiftUI app uses SwiftData and the agent

must keep SwiftData directly driving SwiftUI-owned screens while AppKit keeps only the AppKit-owned lifetime, controller, restoration, or bridge boundary.

• Use this skill when using Swift Observation with AppKit controls,

controllers, delegates, or hosted SwiftUI views.

• Use this skill when embedding SwiftUI in AppKit through `NSHostingView` or

`NSHostingController`, or when exposing AppKit views to SwiftUI through representable bridges.

• Recommend `swiftui-app-architecture-workflow` when the actual owner is

SwiftUI `App`, scenes, commands, focus, environment, preferences, or reusable view composition.

• Recommend `explore-apple-swift-docs` when the user primarily needs Apple or

Swift documentation lookup rather than architecture guidance.

• Recommend `xcode-build-run-workflow` when the work becomes build, run,

preview, diagnostics, file-membership, or guarded mutation work in an existing Xcode-managed project.

• Recommend `xcode-testing-workflow` when the work becomes Swift Testing,

XCTest, XCUITest, `.xctestplan`, or test diagnosis.

• Recommend `apple-ui-accessibility-workflow` when the work is primarily about

accessibility-specific implementation or review.

When Not To Use

• Do not use this skill as the primary path for raw Apple-docs search or source

selection.

• Do not use this skill as the primary path for SwiftUI-first scene,

environment, focus, preference, or reusable view-composition decisions.

• Do not use this skill as a generic macOS UI style, animation, or component

library workflow when the real issue is not AppKit app structure.

• Do not use this skill as the primary path for Xcode execution, signing,

target-membership, sandbox, entitlement, or test mechanics.

Single-Path Workflow

1. Classify the request:

• app lifecycle and app delegate
• menu bar or status-item app
• menus, toolbar actions, responder chain, and validation
• windows, controllers, panels, and inspectors
• restoration, documents, and workspaces
• AppKit MVC, target/action, bindings, and delegates
• archiving, persistence, and migration
• Observation and AppKit
• mixed AppKit/SwiftUI composition

2. Apply the Apple docs gate before recommending structure:

• read the relevant AppKit, SwiftUI, Observation, or Foundation

documentation first

• state the documented behavior being relied on before giving architecture

guidance

• if Apple docs and the current code disagree, stop and surface that conflict
• if no relevant Apple docs can be found, say that explicitly before

proceeding 3. Choose the AppKit ownership boundary:

• app delegate or app-level model
• status-item or menu-bar controller
• main-menu or responder-chain action target
• document controller or document model
• window controller
• view controller
• model object
• hosted SwiftUI boundary
• local view-only state

4. Choose the state and action transport:

• direct initializer injection
• target/action
• delegate method
• responder-chain action
• menu validation
• AppKit binding
• notification or publisher only for real broadcast state
• Observation-driven model update
• explicit SwiftUI hosting input/output
• persistence or restoration payload

5. Check the anti-patterns before finalizing guidance:

• SwiftUI scene structure forced onto AppKit-owned behavior
• repositories, stores, service layers, mirrored DTOs, view-model cache

layers, or wrapper objects inserted betwe