macos-app-scaffold-new

name	macos-app-scaffold-new
description	Scaffold a new macOS app with XcodeGen, GitHub Actions CI/CD, code signing, notarization, auto-update, and SwiftUI starter code
argument-hint	[AppName] [BundleID]
disable-model-invocation	true
allowed-tools	Bash, Write, Read, Edit, Glob, Grep, Agent

New macOS App Scaffold

Create a production-ready macOS application project. Walk the user through interactive choices, then generate all files.

Arguments

• $ARGUMENTS[0] = App name (e.g., MyApp)
• $ARGUMENTS[1] = Bundle ID (e.g., me.xueshi.myapp)

If arguments are missing, ask the user before proceeding.

---

Interactive Flow

Ask questions in this exact order. Present each step clearly with numbered/lettered options and defaults in bold. Wait for user response before proceeding to the next step. You may combine steps 3 and 4 into a single message if appropriate, presenting them as a checklist.

Step 0: Generation strategy — template repo vs from-scratch (ask first)

Ask the user:

I can scaffold this two ways: A) From the template repo (default, fastest, fewest tokens) — clones XueshiQiao/macos-app-starter and applies a small rename + customization diff. Best when your needs match the template's flavor (Menu Bar + Window hybrid, Sparkle, signed CI, full i18n, MIT, no sandbox). B) From scratch — generates every file from the templates in this skill. Best when your archetype/feature mix is far from the template (e.g., Menu Bar only, no Sparkle, sandboxed, no localization).

Which would you like? (default A)

If the user picks A (template), follow "Generation Path A: Template Clone" below — most steps simplify to "delete the parts you don't need" and "rename".

If the user picks B (from-scratch), follow the existing Step 1 → Step 5 flow and the Generation Rules section.

The template's exact flavor (so you can judge fit on the user's behalf):

• Archetype: Menu Bar + Window (hybrid)
• Sandbox: No
• SPM deps: Sparkle, KeyboardShortcuts, Aptabase
• Auto-update: Sparkle
• Background helper: None
• Languages: English + Simplified Chinese
• License: MIT
• Cask: Draft (template_only topology)
• CI/CD: Two-track signed/unsigned (workflow file is in the template repo)

If 5+ of these don't match what the user wants, recommend B.

Step 1: Identity (from args or ask)

• App Name (required) — used for directory name, target name, display name
• Bundle ID (required, suggest default: me.xueshi.<appname-lowercase>)

Step 2: App Archetype

Ask user to pick one:

• A) Menu Bar only — LSUIElement: true, NSStatusItem, no dock icon
• B) Windowed only — standard WindowGroup, dock icon visible
• C) Menu Bar + Window — hybrid: menu bar extra + main window

Default: A

Step 2.5: Background Helper (advanced — default None)

Ask once. Most apps don't need a separate helper process; the default is None and you should not push users toward the other options. Show this table when asking:

Option	What you get	Runs as	Approval	When to pick it	Limits / cost
A) None (default)	Single-process app.	user	n/a	90% of apps. Anything you can do inside the main app process.	none
B) Login Item (SMAppService.mainApp)	Main app auto-launches at login.	user	none	Menu bar tools, chat clients, quick-capture apps that the user wants opened automatically.	Adds zero capability — only convenience.
C) User Agent (SMAppService.agent)	Separate LaunchAgent helper binary; launchd starts it on demand once the user has logged in. App ↔ helper via XPC.	user	none	Persistent background work that doesn't need root: clipboard watcher, sync engine, global hotkey daemon, on-device AI worker.	Two-process complexity, must design XPC protocol, helper signed with same Team ID.
D) Privileged Daemon (SMAppService.daemon)	Separate LaunchDaemon helper binary; launchd starts it on demand at the system level (no login required). App ↔ helper via privileged XPC.	root	user must approve in System Settings	VPN / packet filter, system-wide network proxy, kext-adjacent ops, services that must run before any user logs in (set RunAtLoad for that case).	High MAS review bar, helper effectively unsandboxable, runtime XPC caller authorization is your responsibility (see HelperMain.swift), user-visible approval flow.

Default: A (None). Confirm explicitly before generating C or D. If the user picks D, ask one verification question: "Which specific operation needs root?" — if they cannot name one, steer them to C.

If C is selected, copy templates/agent/ files into the project (see "Background Helper Templates" section below). If D is selected, copy templates/daemon/ files (and tell the user about the System Settings approval step).

If A or B is selected, skip the helper templates entirely.

Step 3: Features

Present as a checklist. User can accept defaults or customize:

Feature	Default	Notes
Runnable starter app	Yes	Generates compilable Swift source files
XcodeGen (project.yml)	Yes	Single source of truth for build config
App Sandbox	No	Required for App Store. Incompatible with Accessibility API, CGEvent tap, etc. Tell the user this trade-off.
SPM dependencies	Yes	Ask which: GRDB, KeyboardShortcuts, Sparkle, etc.
SwiftLint config	No	Generates .swiftlint.yml with sensible defaults
Unit test target	Yes	XCTest skeleton with one example test
Launch at Login	Yes if menu bar archetype, No otherwise	Uses SMAppService
Accessibility permission gate	No	Startup permission check + prompt (for apps using CGEvent tap, AXUIElement, etc.)
Screen Recording permission flow	No	For apps using ScreenCaptureKit (SCShareableContent, SCStream). Generates ScreenRecordingPermission.swift + a 3-state modal (ScreenRecordingPromptView.swift) that handles the mandatory relaunch on first grant. NOT a substitute for the Accessibility gate — first-grant semantics differ.
Localization	No	If yes, ask which languages (always includes English). Generates Localizable.xcstrings or .strings.
File-based logging	Yes	~/Library/Logs/<AppName>.log with lightweight FileLog class
Settings/Preferences window	Yes	Sidebar window the app owns — copy templates/settings/. Never a SwiftUI Settings scene: for a menu-bar app it opens behind other apps and cannot be fixed from outside. Read .

Step 4: CI/CD & Distribution

Feature	Default	Condition	Notes
Apple Developer Account	Yes	—	If NO: skip code signing, notarization, and stapling in CI. Build unsigned only.
GitHub Actions CI/CD	Yes	—	Build pipeline. If no Apple account, builds unsigned universal binary only.
Auto release on v* tags	Yes	Requires CI/CD	softprops/action-gh-release@v2
Release notes languages	English	Requires auto release	User can add more: Chinese, Japanese, German, etc.
Auto-update mechanism	None	Requires CI/CD + Apple account	A) GitHub API polling (lightweight) B) Sparkle (full-featured, requires SPM dep) C) None
Homebrew Cask formula	No	Requires CI/CD	Template .rb file for brew install --cask. If yes, ALSO ask the tap-topology question below.
License	MIT	—	MIT / GPL-3.0 / Apache-2.0 / None

Step 4a: Cask publishing target (only if Homebrew Cask = Yes)

Modern Homebrew (5.x) refuses to install casks from arbitrary paths — they must live in a tap. Asking up front avoids generating a cask file in a location nobody can install from. Present these four options:

Option	Where the .rb lives	Install command users will run	When to pick
A) Existing shared tap (default if user has one)	<owner>/homebrew-tap/Casks/<name>.rb (separate repo)	brew install --cask <owner>/tap/<name>	User already publishes other casks from one shared tap. Ask for <owner> and confirm the repo name.
B) New per-app tap	<owner>/homebrew-<name>/Casks/<name>.rb (new separate repo)	brew install --cask <owner>/<name>/<name>	First cask, no shared tap yet, prefer per-app isolation. The skill scaffolds the tap repo skeleton (README + Casks/), but the user must gh repo create it.
C) Submit to homebrew/cask	upstream Homebrew/homebrew-cask PR	brew install --cask <name>	App is signed, notarized, has public releases, and has a working livecheck. Skill writes the cask + a checklist; user opens the PR manually. Note: brew audit --new rules apply only here.
D) Template only	Casks/<name>.rb in the app repo (NOT installable as-is)	n/a	User wants to decide later. README will document this is a draft and not a working install.

Default: A if the user names an existing tap, otherwise B.

Capture: cask_topology ∈ {shared_tap, per_app_tap, homebrew_cask, template_only}, tap_owner (for A/B), tap_repo_name (for A: usually homebrew-tap; for B: homebrew-<name>).

These values drive: where the .rb is written, the README install command, the CI cask-bump step's target repo, and which validation commands appear in the post-generation summary. | README.md | Yes | — | With badges (build status, macOS version, license), install instructions, screenshots section |

Step 5: Always Generated (no choice, do not ask)

These are always created regardless of choices:

• git init + .gitignore
• AGENTS.md (project conventions) + CLAUDE.md symlink → AGENTS.md
• Entitlements file (content varies based on sandbox choice)

---

Generation Path A: Template Clone (default)

Use this when the user picked A in Step 0. This is dramatically cheaper in tokens because the template repo holds all the boilerplate.

Path A: Steps

1. Clone via GitHub template:

   gh repo create <OwnerOrUser>/<NewRepoName> --template XueshiQiao/macos-app-starter --public --clone
   cd <NewRepoName>
   

   If the user wants the project locally without creating a GitHub repo yet, use gh repo clone + delete-remote pattern, or git clone --depth=1 + rm -rf .git && git init.

2. Rename. Find-and-replace across the repo:

   • MacOSAppStarter → <AppName>
   • dev.xueshi.macos-app-starter → <BundleID>
   • macosappstarter (lowercase, in cask file) → <appname-lowercase>
   • XueshiQiao → user's GitHub owner (in README badges, AGENTS.md, cask file URL, and project.yml's SUFeedURL)
   • macos-app-starter → user's repo name (in SUFeedURL and any GitHub-Releases-asset URLs in workflow)
   • Update LICENSE copyright holder

   About SUFeedURL: the template ships with the raw GitHub URL pattern (https://raw.githubusercontent.com/<owner>/<repo>/main/appcast.xml). CI generates appcast.xml on every tagged release and commits it back to main with [skip ci]. This matches the production pattern in AnyDrag, PastePawX, HyperCapsLock. Do NOT swap to a github.io URL unless Pages is actually set up — that's the failure mode that broke the first version of this template.

   Sparkle keypair MUST be regenerated. The template ships with SUPublicEDKey matching a throwaway private key stored as the template repo's SPARKLE_EDDSA_KEY secret. Forks that don't regenerate are accepting updates signed by anyone who can read the template repo's secret history — bad. The README's "Setup before you ship" step covers the regeneration commands.

   Aptabase key MUST be replaced. The template ships with the maintainer's real Aptabase key (A-US-3800930688) so events flow to a known dashboard during template development. Forks that don't replace it will leak their users' app-launch events into the maintainer's project.

   Files to touch (all done with Edit):

   • project.yml

3b. Replace the starter's Settings window (REQUIRED whenever the user kept a settings window). The macos-app-starter repo predates this template and may still ship a SwiftUI Settings { … } scene. Leaving it in place ships the activation bug: for a menu-bar app the settings window opens behind other apps. Do this even though the clone "already has settings" — especially then.

- Delete the starter's `SettingsView.swift` (and any `SettingsLink` call
  sites in the menu-bar menu).
- Remove the `Settings { … }` scene from the app entry point.
- Copy `templates/settings/` in and wire it up as described under
  **Settings window** in `## File Templates` below.

Grep to confirm nothing survived:
```bash
grep -rn "Settings *{\|SettingsLink" <AppName>/Sources/   # must return nothing
```

4. Regenerate the Xcode project — xcodegen generate. Then build to verify nothing was broken by the rename: xcodebuild -scheme <AppName> -destination 'platform=macOS' build.

5. Sparkle keys, Aptabase key, Apple Developer secrets — same as the from-scratch path. The template ships placeholders; tell the user which to replace.

6. Re-init git if the user wants a clean history: rm -rf .git && git init && git add . && git commit -m "Initial commit (from macos-app-starter template)".

When NOT to use Path A

If the user's choice mix differs significantly from the template (Step 0 lists the exact flavor), recommend Path B instead — the template-deletion overhead may exceed the cost of generating the matching set from scratch. Rough rule: if 5+ of the template's choices are wrong for the user, prefer Path B.

---

Generation Path B: From Scratch

Use this when the user picked B in Step 0. The rest of this document — the existing Generation Rules, File Templates, and Background Helper Templates sections — describes Path B.

Generation Rules

After collecting all answers, generate files in the project directory (current working directory + /<AppName>/).

Generation Order

1. Create directory structure
2. git init
3. .gitignore
4. project.yml (if XcodeGen)
5. Entitlements file
6. Info.plist (if needed)
7. Swift source files (if runnable starter)
8. .swiftlint.yml (if selected)
9. Assets.xcassets structure
10. .github/workflows/build.yml (if CI/CD)
11. Homebrew Cask formula (if selected)
12. LICENSE
13. README.md (if selected)
14. AGENTS.md + CLAUDE.md symlink
15. Initial git commit

After Generation

Print a summary:

1. List all generated files
2. Show next steps:
   • cd <AppName>
   • brew install xcodegen && xcodegen generate (if XcodeGen)
   • open <AppName>.xcodeproj then Cmd+R
   • List GitHub secrets to configure (if CI/CD + Apple account)
   • Remind to push with git push -u origin main && git push --tags
3. Cask validation (only if Homebrew Cask was generated):
   • brew style ./Casks/<name>.rb — style check
   • brew audit --cask --online <tap-ref> — full audit (online checks fetch URLs, run livecheck, validate sha256). The <tap-ref> is whatever the install command uses (e.g., <owner>/tap/<name> for shared tap).
   • For topology C only, also run brew audit --cask --new --online <tap-ref>. The --new flag enforces the homebrew/cask main rules (popularity, verified: placement, etc.) and should be ignored for personal taps — they don't apply there.
   • For topology A/B, after pushing the cask repo: brew tap <owner>/<short> then brew install --cask <full-ref> to verify end-to-end.

---

File Templates

.gitignore

# Xcode
build/
DerivedData/
*.xcuserdata
xcuserdata/

# XcodeGen generated project
*.xcodeproj/

# Generated Info.plist (managed by XcodeGen)
# Uncomment if using GENERATE_INFOPLIST_FILE: YES
# **/Info.plist

# Swift Package Manager
.build/
Packages/
Package.resolved

# macOS
.DS_Store
.AppleDouble
.LSOverride

# Misc
*.swp
*~

If NOT using XcodeGen, remove the *.xcodeproj/ line.

project.yml (XcodeGen)

name: {{AppName}}
options:
  bundleIdPrefix: {{BundleIDPrefix}}
  deploymentTarget:
    macOS: "14.0"
  xcodeVersion: "16.0"
  minimumXcodeGenVersion: "2.35"

settings:
  base:
    SWIFT_VERSION: "6.0"
    MACOSX_DEPLOYMENT_TARGET: "14.0"
    ARCHS: "$(ARCHS_STANDARD)"
    ONLY_ACTIVE_ARCH_Release: "NO"
    ENABLE_HARDENED_RUNTIME: YES
    CODE_SIGN_STYLE: Automatic
    DEVELOPMENT_TEAM: ""
    SWIFT_STRICT_CONCURRENCY: targeted

# If SPM dependencies selected, add:
# packages:
#   PackageName:
#     url: https://github.com/...
#     majorVersion: X.Y.Z

targets:
  {{AppName}}:
    type: application
    platform: macOS
    sources:
      - path: {{AppName}}/Sources
      - path: {{AppName}}/Assets.xcassets
      # If localization: add Resources path
    info:
      path: {{AppName}}/Info.plist
      properties:
        LSUIElement: {{true if menu bar, false if windowed}}
        CFBundleDisplayName: $(PRODUCT_NAME)
        CFBundleShortVersionString: $(MARKETING_VERSION)
        CFBundleVersion: $(CURRENT_PROJECT_VERSION)
        # If accessibility gate:
        # NSAppleEventsUsageDescription: "..."
    settings:
      base:
        PRODUCT_BUNDLE_IDENTIFIER: {{BundleID}}
        CODE_SIGN_ENTITLEMENTS: {{AppName}}/Resources/{{AppName}}.entitlements
        PRODUCT_NAME: {{AppName}}
        MARKETING_VERSION: "1.0.0"
        CURRENT_PROJECT_VERSION: "1"
        COMBINE_HIDPI_IMAGES: true
        ASSETCATALOG_COMPILER_APPICON_NAME: AppIcon
    entitlements:
      path: {{AppName}}/Resources/{{AppName}}.entitlements
    # If SPM deps:
    # dependencies:
    #   - package: PackageName

  # If unit test target:
  # {{AppName}}Tests:
  #   type: bundle.unit-test
  #   platform: macOS
  #   sources:
  #     - path: {{AppName}}Tests
  #   dependencies:
  #     - target: {{AppName}}
  #   settings:
  #     base:
  #       BUNDLE_LOADER: $(TEST_HOST)
  #       TEST_HOST: $(BUILT_PRODUCTS_DIR)/{{AppName}}.app/Contents/MacOS/{{AppName}}

Adapt the template based on user choices. Remove comments, fill in actual values.

Entitlements

Without sandbox:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict/>
</plist>

With sandbox:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
    <key>com.apple.security.files.user-selected.read-write</key>
    <true/>
</dict>
</plist>

Swift Source Files (if runnable starter)

Generate these based on archetype. All files go in {{AppName}}/Sources/.

App Entry Point: {{AppName}}App.swift

No Settings scene in any archetype below — that is deliberate, not an omission. For an LSUIElement app the Settings scene opens the settings window behind whatever the user is looking at, and nothing outside it can fix that (full explanation in templates/settings/README.md). All three archetypes therefore use the same owned window, so there is one code path to maintain. Because dropping the scene also silently drops the application menu's "Settings…" item and its ⌘, shortcut, every archetype restores it with CommandGroup(replacing: .appSettings).

Menu Bar only:

import SwiftUI

@main
struct {{AppName}}App: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        MenuBarExtra("{{AppName}}", systemImage: "app.fill") {
            MenuBarView()
        }
        .menuBarExtraStyle(.window)
        .commands {
            CommandGroup(replacing: .appSettings) {
                Button("Settings…") { SettingsWindowController.shared.show() }
                    .keyboardShortcut(",", modifiers: .command)
            }
        }
    }
}

Windowed only:

import SwiftUI

@main
struct {{AppName}}App: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .commands {
            CommandGroup(replacing: .appSettings) {
                Button("Settings…") { SettingsWindowController.shared.show() }
                    .keyboardShortcut(",", modifiers: .command)
            }
        }
    }
}

Menu Bar + Window (hybrid):

import SwiftUI

@main
struct {{AppName}}App: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

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

        MenuBarExtra("{{AppName}}", systemImage: "app.fill") {
            MenuBarView()
        }
        .menuBarExtraStyle(.window)
        .commands {
            CommandGroup(replacing: .appSettings) {
                Button("Settings…") { SettingsWindowController.shared.show() }
                    .keyboardShortcut(",", modifiers: .command)
            }
        }
    }
}

AppDelegate.swift

import AppKit

class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationDidFinishLaunching(_ notification: Notification) {
        // App startup logic here
    }

    func applicationWillTerminate(_ notification: Notification) {
        // Cleanup logic here
    }
}

If Launch at Login is enabled, add import ServiceManagement and SMAppService setup. If Analytics is enabled, add Aptabase initialization. If Accessibility gate is enabled, add permission check call.

ContentView.swift (if windowed or hybrid)

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack {
            Image(systemName: "app.fill")
                .imageScale(.large)
                .foregroundStyle(.tint)
            Text("Welcome to {{AppName}}")
        }
        .padding()
        .frame(minWidth: 400, minHeight: 300)
    }
}

MenuBarView.swift (if menu bar archetype)

import SwiftUI

struct MenuBarView: View {
    var body: some View {
        VStack(spacing: 12) {
            Text("{{AppName}}")
                .font(.headline)

            Divider()

            Button("Quit") {
                NSApplication.shared.terminate(nil)
            }
            .keyboardShortcut("q")
        }
        .padding()
        .frame(width: 240)
    }
}

Settings window (if settings window)

Copy the files, do not write your own. The Settings window is a template, not a snippet to improvise — it encodes an activation bug that is easy to reintroduce and hard to notice.

Templates location. skills/macos-app-scaffold-new/templates/settings/. Read templates/settings/README.md before copying.

Copy	To	When
SettingsWindowController.swift	{{AppName}}/Sources/	Always
SettingsStore.swift	{{AppName}}/Sources/	Always
SettingsChrome.swift	{{AppName}}/Sources/	Always
GeneralPage.swift	{{AppName}}/Sources/	Always
AboutPage.swift	{{AppName}}/Sources/	Always
LocalizationOverride.swift	{{AppName}}/Sources/	Only if the in-app interface-language picker was selected

Then, in order — these are generation steps, not suggestions. Each copied file carries marked blocks to uncomment or delete; leaving them as-is ships a feature the user declined, or advertises one that isn't there.

1. Replace {{AppName}} in every copied file.
2. Confirm the app entry point has the CommandGroup(replacing: .appSettings) block shown above, and no Settings { … } scene.
3. Open it from the menu-bar menu with a plain button — never SettingsLink:

   Button("Settings…") { SettingsWindowController.shared.show() }
   

4. If "Launch at Login" was NOT selected: delete the marked Section in GeneralPage.swift and the launchAtLogin property in SettingsStore.swift. Both ship it unconditionally — leaving them registers a login item the user declined.
5. If the in-app interface-language picker WAS selected: uncomment the four marked blocks — the picker Section in GeneralPage.swift, the interfaceLanguage / interfaceLanguageCodes pass-throughs in SettingsStore.swift, and both the @ObservedObject line and the .id(languageRevision.value) line in SettingsChrome.swift. Then do the rest of "Wiring it" in templates/settings/README.md — applyStored() in applicationWillFinishLaunching, observing the revision on every other surface, and converting strings to L("…"). Uncommenting only some of these yields a picker that changes nothing.
6. Point SettingsStore.isOperational / statusText at whatever can actually block this app (a permission, a helper). If nothing can, delete the status footer from SettingsChrome.swift rather than shipping a light that is always green.
7. Delete the AboutPage link rows the app does not have, and set its real URLs.
8. Build. The templates compile as shipped, so an error here means a marked block was half-uncommented.

Do not flatten this into a TabView, and do not re-add a Settings scene "for the ⌘, shortcut" — step 2 already provides it.

LaunchAtLoginManager.swift (if Launch at Login)

Skip this file if you copied the Settings template — SettingsStore already implements launch-at-login against SMAppService, and GeneralPage binds to it. Generating both leaves two owners of one setting, which is the exact drift the template's README warns about. Generate this manager only when there is no Settings window, or when something outside Settings also needs to toggle it — in which case make SettingsStore.launchAtLogin forward to the manager rather than calling SMAppService itself.

import ServiceManagement

final class LaunchAtLoginManager {
    static let shared = LaunchAtLoginManager()

    var isEnabled: Bool {
        SMAppService.mainApp.status == .enabled
    }

    func setEnabled(_ enabled: Bool) {
        do {
            if enabled {
                try SMAppService.mainApp.register()
            } else {
                try SMAppService.mainApp.unregister()
            }
        } catch {
            print("Failed to \(enabled ? "enable" : "disable") launch at login: \(error)")
        }
    }
}

PermissionManager.swift (if Accessibility gate)

import AppKit
import ApplicationServices

final class PermissionManager {
    static let shared = PermissionManager()

    var isAccessibilityGranted: Bool {
        AXIsProcessTrusted()
    }

    func requestAccessibilityIfNeeded() {
        let options = [kAXTrustedCheckOptionPrompt.takeUnretainedValue(): true] as CFDictionary
        AXIsProcessTrustedWithOptions(options)
    }

    func ensureAccessibility(completion: @escaping () -> Void) {
        if isAccessibilityGranted {
            completion()
            return
        }

        requestAccessibilityIfNeeded()

        // Poll until granted
        Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { timer in
            if AXIsProcessTrusted() {
                timer.invalidate()
                DispatchQueue.main.async {
                    completion()
                }
            }
        }
    }
}

ScreenRecordingPermission.swift + ScreenRecordingPromptView.swift (if Screen Recording flow)

Use the templates in skills/macos-app-scaffold-new/templates/screen-recording/ — ScreenRecordingPermission.swift, ScreenRecordingPromptView.swift, and a README.md documenting the gotchas. Read the README before generating.

The single non-negotiable invariant the manager encodes: on first grant, ScreenCaptureKit (SCShareableContent, SCStream, SCScreenshotManager) will NOT start working in the same process. The user MUST quit and relaunch. Do not write a flow that polls SCShareableContent after grant — it does not work, and "polling longer" does not fix it.

The manager exposes three states — notGranted, grantedPendingRelaunch, granted — which the prompt view maps to three branches: explain → "Open Settings" → poll → "Relaunch Now". Wire ScreenRecordingPromptView as a .sheet(isPresented:) from any feature entry point that needs screen capture. Gate all ScreenCaptureKit calls on ScreenRecordingPermission.shared.isReadyForCapture (the canonical helper) — never on status != .notGranted, which lets .grantedPendingRelaunch through and produces silent failures.

When generating, also add this to the project's debug config:

# project.yml
configs:
  Debug: debug
settings:
  configs:
    Debug:
      CODE_SIGN_IDENTITY: "Apple Development"   # NOT "-" (ad-hoc)
      DEVELOPMENT_TEAM: <user's Team ID>

Reason: ad-hoc / changing-identity rebuilds wipe the TCC entry silently, which is the dev-loop bug that costs everyone a day the first time.

Do NOT add NSScreenRecordingUsageDescription to Info.plist. It is not consulted by this API.

FileLog.swift (if file-based logging)

import Foundation

final class FileLog: Sendable {
    private let label: String
    private let fileURL: URL

    init(_ label: String) {
        self.label = label
        let logsDir = FileManager.default.homeDirectoryForCurrentUser
            .appendingPathComponent("Library/Logs")
        // Replace {{AppName}} with actual app name at generation time
        self.fileURL = logsDir.appendingPathComponent("{{AppName}}.log")
    }

    func info(_ message: String) {
        log("INFO", message)
    }

    func error(_ message: String) {
        log("ERROR", message)
    }

    private func log(_ level: String, _ message: String) {
        let timestamp = ISO8601DateFormatter().string(from: Date())
        let line = "\(timestamp) [\(level)] [\(label)] \(message)\n"
        if let data = line.data(using: .utf8) {
            if FileManager.default.fileExists(atPath: fileURL.path) {
                if let handle = try? FileHandle(forWritingTo: fileURL) {
                    handle.seekToEndOfFile()
                    handle.write(data)
                    handle.closeFile()
                }
            } else {
                try? data.write(to: fileURL)
            }
        }
        #if DEBUG
        print("[\(label)] \(message)")
        #endif
    }
}

UpdateChecker.swift (if auto-update via GitHub API polling)

import Foundation

final class UpdateChecker: ObservableObject {
    @Published var updateAvailable = false
    @Published var latestVersion: String?
    @Published var downloadURL: URL?

    // Replace with actual GitHub owner/repo at generation time
    private let owner = "{{GitHubOwner}}"
    private let repo = "{{GitHubRepo}}"
    private let currentVersion: String

    init() {
        self.currentVersion = Bundle.main.object(
            forInfoDictionaryKey: "CFBundleShortVersionString"
        ) as? String ?? "0.0.0"
    }

    func checkForUpdates() async {
        guard let url = URL(string: "https://api.github.com/repos/\(owner)/\(repo)/releases/latest") else { return }

        do {
            let (data, _) = try await URLSession.shared.data(from: url)
            let release = try JSONDecoder().decode(GitHubRelease.self, from: data)
            let latest = release.tagName.trimmingCharacters(in: CharacterSet(charactersIn: "v"))

            await MainActor.run {
                self.latestVersion = latest
                self.updateAvailable = latest.compare(currentVersion, options: .numeric) == .orderedDescending
                self.downloadURL = release.assets.first(where: { $0.name.hasSuffix(".dmg") })?.browserDownloadURL
            }
        } catch {
            print("Update check failed: \(error)")
        }
    }
}

private struct GitHubRelease: Decodable {
    let tagName: String
    let assets: [Asset]

    struct Asset: Decodable {
        let name: String
        let browserDownloadURL: URL

        enum CodingKeys: String, CodingKey {
            case name
            case browserDownloadURL = "browser_download_url"
        }
    }

    enum CodingKeys: String, CodingKey {
        case tagName = "tag_name"
        case assets
    }
}

If auto-update is Sparkle instead, add Sparkle to SPM deps and generate SPUStandardUpdaterController setup instead of the above.

Unit Test (if selected)

File: {{AppName}}Tests/{{AppName}}Tests.swift

import XCTest
@testable import {{AppName}}

final class {{AppName}}Tests: XCTestCase {
    func testExample() throws {
        XCTAssertTrue(true, "Project builds and tests run")
    }
}

.swiftlint.yml (if selected)

disabled_rules:
  - trailing_whitespace
  - line_length
  - type_body_length
  - file_length
  - function_body_length

opt_in_rules:
  - empty_count
  - closure_spacing
  - force_unwrapping
  - implicitly_unwrapped_optional

excluded:
  - DerivedData
  - build
  - .build
  - Packages

GitHub Actions: .github/workflows/build.yml

Generate based on CI/CD choices. The workflow has conditional blocks.

Copy templates/ci/build.yml to .github/workflows/build.yml and substitute the placeholders. Do not retype it, and do not write your own from memory — this file encodes several failures that only surface on a real tagged release, listed in templates/ci/README.md.

mkdir -p .github/workflows
cp <skill-dir>/templates/ci/build.yml .github/workflows/build.yml
# then replace {{AppName}} / {{SchemeName}} / {{BundleID}} / {{EntitlementsPath}}

If the user does NOT have an Apple Developer Account, remove all steps that have if: env.HAS_APPLE_SECRETS == 'true' and the HAS_APPLE_SECRETS env var. Keep only: checkout, setup, build, create DMG (unsigned), upload artifact, and release.

If Homebrew Cask is selected, append the cask-bump step below. It runs only on tag pushes, after the GitHub Release is created (so the DMG URL resolves and sha256 matches). Skip this entirely for cask_topology = template_only.

The step pushes directly to the tap repo. For cask_topology:

• A (shared_tap): target repo is {{tap_owner}}/{{tap_repo_name}}, file path Casks/{{appname-lowercase}}.rb.
• B (per_app_tap): target repo is {{tap_owner}}/homebrew-{{appname-lowercase}}, file path Casks/{{appname-lowercase}}.rb.
• C (homebrew_cask): do NOT auto-push to Homebrew/homebrew-cask (PR-only flow). Instead, comment in the workflow: # After release, run: brew bump-cask-pr {{appname-lowercase}} --version <new> so the user opens a PR by hand.

Required GitHub secret: HOMEBREW_TAP_TOKEN — a fine-grained PAT with Contents: Read and write scope on the tap repo only. Do NOT reuse GITHUB_TOKEN; it's scoped to the current repo and cannot push to the tap.

      - name: Update Homebrew cask in tap repo
        if: startsWith(github.ref, 'refs/tags/v') && env.HAS_APPLE_SECRETS == 'true'
        env:
          TAP_REPO: {{tap_owner}}/{{tap_repo_name}}        # e.g. XueshiQiao/homebrew-tap
          CASK_PATH: Casks/{{appname-lowercase}}.rb
          TAP_TOKEN: ${{"{{"}} secrets.HOMEBREW_TAP_TOKEN {{"}}"}}
        run: |
          set -euo pipefail
          if [[ -z "$TAP_TOKEN" ]]; then
            echo "::warning::HOMEBREW_TAP_TOKEN not set — skipping cask update."
            exit 0
          fi

          VERSION="${GITHUB_REF_NAME#v}"
          DMG_PATH="$APP_NAME.dmg"
          SHA256=$(shasum -a 256 "$DMG_PATH" | awk '{print $1}')

          WORK="$RUNNER_TEMP/tap"
          git clone --depth=1 "https://x-access-token:${TAP_TOKEN}@github.com/${TAP_REPO}.git" "$WORK"
          cd "$WORK"

          # Bump version + sha256. Use perl (not sed -i) for portable in-place edit.
          perl -i -pe 's/^(\s*version\s+)"[^"]*"/$1"'"$VERSION"'"/' "$CASK_PATH"
          perl -i -pe 's/^(\s*sha256\s+)"[^"]*"/$1"'"$SHA256"'"/' "$CASK_PATH"

          if git diff --quiet; then
            echo "Cask already up-to-date at $VERSION."
            exit 0
          fi

          git -c user.name="github-actions[bot]" \
              -c user.email="41898282+github-actions[bot]@users.noreply.github.com" \
              commit -am "Update {{appname-lowercase}} to $VERSION"
          git push origin HEAD:main

Notes for whoever maintains this:

• perl -i is used over sed -i because sed -i syntax differs between GNU and BSD/macOS. The runner is macOS, so this matters.
• The commit message format matches what brew bump-cask-pr produces, so anyone later switching to PR-flow gets consistent history.
• For topology B, the user must gh repo create the tap repo before the first tag push; otherwise the clone step fails. Document this in the post-generation summary's "Next steps".

Release Notes Languages

If multiple languages are selected, create a RELEASE_TEMPLATE.md at project root:

## What's New / Release Notes

### English
- 

### {{Language2}} (e.g., Chinese / 中文)
- 

And add to AGENTS.md a convention:

Release notes must include sections for each configured language: {{list of languages}}.

Homebrew Cask (if selected)

Where the file goes depends on cask_topology from Step 4a:

cask_topology	Path the skill writes
shared_tap (A)	The skill canNOT write to a sibling repo on disk. Print the cask body and instruct: "Save this as Casks/{{appname-lowercase}}.rb in your {{tap_owner}}/{{tap_repo_name}} repo and push."
per_app_tap (B)	Scaffold a sibling repo skeleton at ../homebrew-{{appname-lowercase}}/ containing Casks/{{appname-lowercase}}.rb, a minimal README.md, and .gitignore. Tell the user to cd ../homebrew-{{appname-lowercase}} && gh repo create {{tap_owner}}/homebrew-{{appname-lowercase}} --public --source=. --push.
homebrew_cask (C)	Write to Casks/{{appname-lowercase}}.rb in the app repo as a working draft, plus a HOMEBREW_CASK_PR_CHECKLIST.md (see below). The user copies the cask into a homebrew-cask fork to open the PR.
template_only (D)	Write to Casks/{{appname-lowercase}}.rb in the app repo with a comment header marking it as a draft. README must reflect that this is not yet installable.

Template (used in all four cases — the only difference is where it lands):

cask "{{appname-lowercase}}" do
  version "1.0.0"
  sha256 ""

  url "https://github.com/{{GitHubOwner}}/{{GitHubRepo}}/releases/download/v#{version}/{{AppName}}.dmg"
  # Add `verified:` ONLY when url's host differs from homepage's host (current
  # audit rule). Both this template's url and homepage point at github.com, so
  # `verified:` here is unnecessary and will be flagged by `brew audit`. If you
  # later host the DMG on a different domain, add e.g.:
  #   verified: "github.com/{{GitHubOwner}}/{{GitHubRepo}}/"
  name "{{AppName}}"
  desc "{{one-line description, ≤80 chars, no trailing period, no app name}}"
  homepage "https://github.com/{{GitHubOwner}}/{{GitHubRepo}}"

  # --- livecheck block: emit ONE of the two variants below ---
  # If auto_update_mechanism == "sparkle": use the :sparkle variant. The url
  # MUST match SUFeedURL in Info.plist. The recommended pattern is to host
  # the appcast as a GitHub Release asset:
  #   https://github.com/<owner>/<repo>/releases/latest/download/appcast.xml
  # so this livecheck url and the SUFeedURL are identical. Do NOT swap to
  # a guessed github.io URL — Pages is not on by default, and users without
  # Pages set up will get 404s. If the user has set up Pages explicitly, then
  # use their actual hosted URL.
  # If auto_update_mechanism == "github" or "none": use the :github_latest variant.

  # Variant A — Sparkle:
  livecheck do
    url "{{appcast-feed-url-from-SUFeedURL-or-TODO}}"
    strategy :sparkle
  end

  # Variant B — GitHub releases:
  livecheck do
    url :url
    strategy :github_latest
  end

  # --- auto_updates: include ONLY when auto_update_mechanism != "none" ---
  # Tells brew not to fight with the app's self-update. Required for Sparkle
  # apps and for any app that polls GitHub Releases internally.
  auto_updates true

  # depends_on macos: comes from the deployment target (e.g. macOS 14 → :sonoma).
  # Map: 12→:monterey, 13→:ventura, 14→:sonoma, 15→:sequoia, 26→:tahoe.
  depends_on macos: ">= :{{deployment_target_codename}}"

  app "{{AppName}}.app"

  zap trash: [
    "~/Library/Preferences/{{BundleID}}.plist",
    "~/Library/Application Support/{{AppName}}",
    "~/Library/Caches/{{BundleID}}",
    "~/Library/HTTPStorages/{{BundleID}}",
    "~/Library/Saved Application State/{{BundleID}}.savedState",
    "~/Library/Logs/{{AppName}}.log",
  ]
end

For topology B (per_app_tap), also create the sibling repo skeleton:

../homebrew-{{appname-lowercase}}/README.md:

# {{tap_owner}}/homebrew-{{appname-lowercase}}

Homebrew tap for [{{AppName}}](https://github.com/{{GitHubOwner}}/{{GitHubRepo}}).

## Install

```bash
brew install --cask {{tap_owner}}/{{appname-lowercase}}/{{appname-lowercase}}

`../homebrew-{{appname-lowercase}}/.gitignore`:

.DS_Store

**For topology C (`homebrew_cask`)**, also create `HOMEBREW_CASK_PR_CHECKLIST.md` at project root listing: signed + notarized release present, livecheck verified with `brew livecheck --cask Casks/{{appname-lowercase}}.rb`, `brew audit --cask --online --new Casks/{{appname-lowercase}}.rb` clean, fork `Homebrew/homebrew-cask`, copy the file to `Casks/{{first-letter}}/{{appname-lowercase}}.rb` (note the alphabetized subdirectory), open PR titled `Add {{appname-lowercase}} <version>`.

### LICENSE

Generate the selected license file with the current year and "{{AppName}}" as the project name.

### README.md (if selected)

```markdown
# {{AppName}}

> Brief description here

[![Build](https://github.com/{{GitHubOwner}}/{{GitHubRepo}}/actions/workflows/build.yml/badge.svg)](https://github.com/{{GitHubOwner}}/{{GitHubRepo}}/actions/workflows/build.yml)
![macOS 14+](https://img.shields.io/badge/macOS-14%2B-blue)
![Swift 6.0](https://img.shields.io/badge/Swift-6.0-orange)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Features

- Feature 1
- Feature 2

## Screenshots

<!-- Add screenshots here -->

## Installation

### Download

Download the latest `.dmg` from [Releases](https://github.com/{{GitHubOwner}}/{{GitHubRepo}}/releases).

### Homebrew (if cask is generated)

Render the install command according to `cask_topology`:

- **A) shared_tap**: `brew install --cask {{tap_owner}}/tap/{{appname-lowercase}}`
  (assumes `tap_repo_name` = `homebrew-tap`; brew auto-prepends the
  `homebrew-` prefix from the second segment, so users type `tap`, not the full repo name)
- **B) per_app_tap**: `brew install --cask {{tap_owner}}/{{appname-lowercase}}/{{appname-lowercase}}`
- **C) homebrew_cask** (after PR is merged): `brew install --cask {{appname-lowercase}}`
- **D) template_only**: omit this section entirely, OR include it with a
  prominent note: `<!-- Cask template generated but not yet published. The bare
  command below requires homebrew/cask submission; see Casks/{{appname-lowercase}}.rb. -->`

```bash
brew install --cask {{rendered-from-topology}}

Build from Source

brew install xcodegen
xcodegen generate
open {{AppName}}.xcodeproj
# Cmd+R to build and run

License

MIT

Adapt badges based on license choice and macOS version.

### AGENTS.md

Generate project-specific conventions. Always include:

```markdown
# Agent Guidelines for {{AppName}}

## Single Source of Truth
`project.yml` is the ONLY source of truth for project configuration. Do NOT edit
`.pbxproj` or `Info.plist` directly. Modify `project.yml` and run `xcodegen generate`.

## Build & Run
```bash
brew install xcodegen
cd {{project-root-if-nested}}
xcodegen generate
open {{AppName}}.xcodeproj  # Cmd+R to run

Tech Stack

• Swift 6.0, SwiftUI, macOS 14.0+
• XcodeGen (project.yml)
• {{List selected SPM dependencies}}
• {{Archetype description}}

Architecture

• Entry point: {{AppName}}/Sources/{{AppName}}App.swift
• {{List key files based on what was generated}}

Versioning

• MARKETING_VERSION and CURRENT_PROJECT_VERSION in project.yml
• Git tags (v*) trigger release builds

CI/CD

{{If CI/CD: describe the pipeline}} {{If Apple account: list required GitHub secrets}}

GitHub Secrets Required

{{If Apple account:}}

• MAC_CERTS_P12_BASE64 — Base64-encoded Developer ID Application certificate (.p12)
• MAC_CERTS_P12_PASSWORD — Password for the .p12 file
• APPLE_ID — Apple ID email for notarization
• APPLE_TEAM_ID — Apple Developer Team ID
• APP_SPECIFIC_PASSWORD — App-specific password for notarization

Release Notes

{{If multiple languages: list language convention}}

Then create the `CLAUDE.md` symlink:
```bash
ln -s AGENTS.md CLAUDE.md

Assets.xcassets

Create the minimal structure:

{{AppName}}/Assets.xcassets/
├── Contents.json
└── AppIcon.appiconset/
    └── Contents.json

Assets.xcassets/Contents.json:

{
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

AppIcon.appiconset/Contents.json:

{
  "images" : [
    {
      "idiom" : "mac",
      "scale" : "1x",
      "size" : "16x16"
    },
    {
      "idiom" : "mac",
      "scale" : "2x",
      "size" : "16x16"
    },
    {
      "idiom" : "mac",
      "scale" : "1x",
      "size" : "32x32"
    },
    {
      "idiom" : "mac",
      "scale" : "2x",
      "size" : "32x32"
    },
    {
      "idiom" : "mac",
      "scale" : "1x",
      "size" : "128x128"
    },
    {
      "idiom" : "mac",
      "scale" : "2x",
      "size" : "128x128"
    },
    {
      "idiom" : "mac",
      "scale" : "1x",
      "size" : "256x256"
    },
    {
      "idiom" : "mac",
      "scale" : "2x",
      "size" : "256x256"
    },
    {
      "idiom" : "mac",
      "scale" : "1x",
      "size" : "512x512"
    },
    {
      "idiom" : "mac",
      "scale" : "2x",
      "size" : "512x512"
    }
  ],
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

Analytics (if Aptabase selected)

Add to project.yml packages:

Aptabase:
  url: https://github.com/nicklama/aptabase-swift
  majorVersion: 0.3.0

Add initialization in AppDelegate.applicationDidFinishLaunching:

import Aptabase

Aptabase.shared.initialize(appKey: "YOUR_APTABASE_KEY")

Onboarding Window (if selected)

File: {{AppName}}/Sources/WelcomeView.swift

import SwiftUI

struct WelcomeView: View {
    /// Handed in by whoever created the window. `@Environment(\.dismiss)` does
    /// NOTHING inside a plain `NSHostingView` in an AppKit `NSWindow`, so a
    /// "Get Started" button wired to it sets the flag and leaves the window
    /// sitting there. Take the close action as a parameter instead.
    let onFinish: () -> Void

    var body: some View {
        VStack(spacing: 24) {
            // If the Settings window template is also present, use its
            // `HeroTile(symbol:color:)` and `.auroraBackground()` here so the
            // first thing a user sees matches the place they come back to.
            Image(systemName: "app.fill")
                .font(.system(size: 64))
                .foregroundStyle(.tint)

            Text("Welcome to {{AppName}}")
                .font(.largeTitle)
                .fontWeight(.bold)

            Text("Brief description of what the app does.")
                .font(.title3)
                .foregroundStyle(.secondary)
                .multilineTextAlignment(.center)

            Button("Get Started") {
                OnboardingState.markSeen()
                onFinish()
            }
            .buttonStyle(.borderedProminent)
            .controlSize(.large)
        }
        .padding(40)
        .frame(width: 480, height: 360)
    }
}

/// Stored as the app VERSION that completed onboarding, not a bare bool, so a
/// later release can re-introduce itself when it changes something the user
/// needs to know about — without re-showing this one to everybody.
enum OnboardingState {
    private static let key = "onboardingCompletedVersion"
    private static var current: String {
        Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "0"
    }
    static var shouldShow: Bool { UserDefaults.standard.string(forKey: key) == nil }
    static func markSeen() { UserDefaults.standard.set(current, forKey: key) }
    /// To test the flow again: `defaults delete <BundleID> onboardingCompletedVersion`
    static func reset() { UserDefaults.standard.removeObject(forKey: key) }
}

Present it from AppDelegate when OnboardingState.shouldShow. Two things this window must do, both of which are silently wrong if you skip them:

private var welcomeWindow: NSWindow?

private func showWelcome() {
    let window = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 480, height: 360),
                          styleMask: [.titled, .closable, .fullSizeContentView],
                          backing: .buffered, defer: false)
    window.center()
    window.isReleasedWhenClosed = false
    window.contentView = NSHostingView(rootView: WelcomeView { [weak self] in
        self?.welcomeWindow?.close()
        self?.welcomeWindow = nil     // isReleasedWhenClosed is false — this frees it
    })
    welcomeWindow = window

    // A menu-bar app is NOT frontmost at launch. Without activating first the
    // window opens behind everything and the user never sees it.
    NSApp.activate(ignoringOtherApps: true)
    window.makeKeyAndOrderFront(nil)
}

Localization (if selected)

The modern stack (Xcode 15+) uses String Catalogs (.xcstrings). They auto-extract strings from String(localized:) calls at build time and provide a UI for translation. Prefer them over legacy .strings/.stringsdict.

1. project.yml additions:

settings:
  base:
    LOCALIZATION_PREFERS_STRING_CATALOGS: YES
    DEVELOPMENT_LANGUAGE: en           # or whatever the base language is
    SWIFT_EMIT_LOC_STRINGS: YES        # auto-extract String(localized:) at build time

# All selected languages must appear in `knownRegions` so Xcode picks them up.
# These are BCP-47 codes: en, zh-Hans, zh-Hant, ja, ko, de, fr, es, pt-BR, ...
options:
  knownRegions:
    - en
    - {{Language2}}                    # e.g. zh-Hans
    - Base                             # required by Xcode for resource loading

sources:
  - path: {{AppName}}/Sources
  - path: {{AppName}}/Assets.xcassets
  - path: {{AppName}}/Resources

2. {{AppName}}/Resources/Localizable.xcstrings — one file with all UI strings. Skeleton:

{
  "sourceLanguage" : "en",
  "strings" : {
    "Settings" : {
      "extractionState" : "manual",
      "localizations" : {
        "en"      : { "stringUnit" : { "state" : "translated", "value" : "Settings" } },
        "zh-Hans" : { "stringUnit" : { "state" : "translated", "value" : "设置" } }
      }
    }
  },
  "version" : "1.0"
}

After the first build with SWIFT_EMIT_LOC_STRINGS: YES, Xcode auto-fills new strings from String(localized:) calls. The skill should seed the file with strings for every UI string in generated Swift files (Settings, Onboarding, menu items, etc.).

3. {{AppName}}/Resources/InfoPlist.xcstrings — separate catalog for plist values like CFBundleDisplayName, CFBundleName, menu bar status item title. Required when you want the app's display name to be localized:

{
  "sourceLanguage" : "en",
  "strings" : {
    "CFBundleDisplayName" : {
      "localizations" : {
        "en"      : { "stringUnit" : { "state" : "translated", "value" : "{{AppName}}" } },
        "zh-Hans" : { "stringUnit" : { "state" : "translated", "value" : "{{ChineseAppName}}" } }
      }
    }
  },
  "version" : "1.0"
}

In Info.plist (or via XcodeGen infoPlist:), set CFBundleDisplayName to $(CFBundleDisplayName) so it's resolved from the catalog.

4. Swift usage:

// Preferred — String Catalogs auto-extract these.
Text("Settings")                                    // SwiftUI: implicit localization
let title = String(localized: "Welcome")            // explicit
let n = String(localized: "\(count) items")         // interpolation works

// Avoid: NSLocalizedString (older API; still works but not auto-extracted as cleanly)
// Avoid: bare String literals shown in UI without going through String(localized:)

5. Runtime language switch (optional). Only if the user selected the in-app interface-language picker in Step 3. Pick exactly ONE of these two modes for the whole app — they are mutually exclusive, and running both leaves two independent preferences plus a picker that appears to work and does not:

Mode	Mechanism	Write UI strings as	Switches
Follow the system (default)	nothing — macOS resolves it	String(localized:) or bare Text("…")	with the system, at launch
Instant in-app switch	templates/settings/LocalizationOverride.swift only	L("…")	immediately, no relaunch

Do not write an AppleLanguages switcher. Setting UserDefaults.standard.set([code], forKey: "AppleLanguages") cannot switch a running app: Bundle.main has already resolved its localization, and rebuilding the SwiftUI tree does not change that — it only takes effect on the next launch. An earlier version of this skill shipped exactly that helper and claimed .id(...) made it instant. It does not.

For the instant mode, follow the five wiring steps in templates/settings/README.md ("Wiring it"). Copying the file is only step 1; skipping any of the others produces a feature that is advertised and absent, or a picker that changes nothing.

6. AGENTS.md convention — add this so future code stays localizable:

All UI strings must go through String(localized:) (or SwiftUI implicit Text("...")). Never use bare String literals for text shown to users. New strings appear automatically in Localizable.xcstrings after build; translate non-English entries before merging.

If the app uses the instant in-app switch mode instead, write that convention as:

All UI strings must go through L("..."). Never use a bare SwiftUI literal, Text("...") or String(localized:) for user-facing text — neither routes through the language override, so those strings silently keep rendering in the system language. Because L's argument is a variable, Xcode cannot auto-extract them: add every new string to Localizable.xcstrings by hand, in all shipped languages.

7. Release notes — when multiple languages are configured, the release notes template (see "Release Notes Languages" above) should have a section per language so changelog text matches what Sparkle (or the user) shows.

---

Background Helper Templates

Only use this section if the user picked C (User Agent) or D (Privileged Daemon) in Step 2.5. For A and B, skip entirely.

Templates live alongside this skill:

templates/
├── agent/    # SMAppService.agent — user-context helper (no approval required)
└── daemon/   # SMAppService.daemon — root helper (user approval required)

Each template directory contains:

File	Purpose
README.md	Per-template explanation; read this first
HelperProtocol.swift	Shared XPC protocol — compiled into BOTH targets
HelperMain.swift	Helper executable entry point
HelperManager.swift	App-side controller (register/unregister + XPC client)
LaunchAgent.plist / LaunchDaemon.plist	launchd plist embedded in app bundle
project.yml.snippet	XcodeGen target + dependency wiring
entitlements.snippet.xml	Helper target entitlements

Generation steps (when helper is selected)

1. Read the appropriate template README.md first to understand the structure.
2. Copy the template files into the project, substituting placeholders:
   • {{AppName}} → user's app name
   • {{AppBundleID}} → user's bundle ID (e.g. me.xueshi.myapp)
   • {{HelperBundleID}} → <AppBundleID>.helper (e.g. me.xueshi.myapp.helper)
   • {{HelperExecutableName}} → <AppName>Helper (e.g. MyAppHelper)
   • {{TeamID}} → only for daemon; ask the user (security find-identity -p codesigning)
3. Suggested layout in the project:

   {{AppName}}/
   ├── Sources/                       (existing app code, includes HelperManager.swift)
   ├── Shared/
   │   └── HelperProtocol.swift       (compiled into BOTH targets)
   └── Helper/
       ├── HelperMain.swift
       ├── {{HelperExecutableName}}.entitlements
       └── Launch{Agents,Daemons}/
           └── {{HelperBundleID}}.plist
   

4. Append the project.yml.snippet blocks into the user's project.yml.
5. Place HelperManager.swift in Sources/ so the app can call it.
6. After scaffolding, tell the user:
   • Run xcodegen generate and build once.
   • For agent: call try HelperManager.shared.register() from a Settings toggle. Done.
   • For daemon: call try HelperManager.shared.register(), then watch for status == .requiresApproval and surface a button that calls HelperManager.shared.openSystemSettings().

Codesign loop

The CI codesign step in build.yml already includes a sweep of Contents/MacOS/<helper> that picks up <helper>.entitlements if present at {{AppName}}/Helper/<helper>.entitlements. Verify the path matches.

What NOT to do

• Don't generate the daemon template unless the user explicitly confirmed they need root for a specific named operation. Default to agent or to no helper.
• Don't merge HelperProtocol.swift into the app target only — the helper target must compile against the exact same source file, or the connection invalidates silently at runtime.
• Don't enable KeepAlive / RunAtLoad in the launchd plist unless the user asked for "always running". On-demand activation is the recommended pattern.

---

Reminders

• All {{placeholders}} must be replaced with actual values from user input
• Do NOT generate an Xcode project file — XcodeGen handles that
• Ensure all generated Swift files compile together (no missing imports, no type errors)
• Use @MainActor and Sendable where appropriate for Swift 6.0 concurrency
• The .xcodeproj directory must be in .gitignore when using XcodeGen
• Always create CLAUDE.md as a symlink to AGENTS.md, never as a standalone file