macos-app-scaffold-enhance

name	macos-app-scaffold-enhance
description	Add features to an existing macOS app — CI/CD, auto-update, logging, SwiftLint, localization, Launch at Login, and more
argument-hint	[feature-name]
disable-model-invocation	true
allowed-tools	Bash, Write, Read, Edit, Glob, Grep, Agent

Enhance Existing macOS App

Add production-ready features to an existing macOS project. This skill analyzes the current project, shows what's already in place, and surgically adds only the new pieces.

Companion to /new-macos-app (which scaffolds from scratch).

Arguments

• $ARGUMENTS = Optional feature name to add directly (e.g., ci-cd, auto-update, logging)

If no argument given, run the full analysis and let the user pick.

---

Step 1: Analyze Existing Project

Before asking anything, scan the current directory for:

Check for:
├── project.yml              → XcodeGen?
├── *.xcodeproj/             → Xcode project exists?
├── Package.swift            → SPM package?
├── .github/workflows/*.yml  → CI/CD?
├── .swiftlint.yml           → SwiftLint?
├── .gitignore               → Git initialized?
├── AGENTS.md / CLAUDE.md    → Agent config?
├── LICENSE                  → License file?
├── README.md                → README?
├── Casks/*.rb               → Homebrew Cask?
├── **/Sources/**App.swift   → App entry point?
├── **/*.entitlements        → Entitlements?
├── **/Info.plist            → App metadata?
└── **/*.xcstrings or *.strings → Localization?

Also read project.yml (or .pbxproj info) to determine:

• App name, bundle ID, deployment target
• Current SPM dependencies
• Sandbox status
• Whether it's a menu bar app (LSUIElement)
• Current version numbers

Step 2: Show Status Dashboard

Present a clear dashboard of what exists vs what can be added:

## Project: {{AppName}} ({{BundleID}})

### Already in place
 ✓ XcodeGen (project.yml)
 ✓ Git initialized
 ✓ GitHub Actions CI/CD
 ✓ Entitlements (no sandbox)

### Available to add
 1. Auto-update mechanism (GitHub API polling / Sparkle)
 2. File-based logging
 3. SwiftLint config
 4. Unit test target
 5. Launch at Login
 6. Accessibility permission gate
 7. Screen Recording permission flow
 8. Localization
 9. Settings/Preferences window
 10. Analytics (Aptabase)
 11. Onboarding/Welcome window
 12. Homebrew Cask formula
 13. README.md with badges
 14. License file
 15. AGENTS.md + CLAUDE.md symlink

Which features would you like to add? (comma-separated numbers, or "all")

Only show features that are NOT already detected. If a feature partially exists, note it (e.g., "CI/CD exists but missing notarization steps").

If the user provided an argument (e.g., /enhance-macos-app auto-update), skip the dashboard and go directly to that feature.

Step 3: Add Selected Features

For each selected feature, follow these rules:

General Rules

1. Read before writing. Always read existing files before modifying them. Never overwrite existing code.
2. Surgical additions. Add new files, append to existing configs. Don't restructure what's already there.
3. Respect existing patterns. If the project uses tabs, use tabs. If it has a specific import style, match it.
4. XcodeGen awareness. If project.yml exists, modify it instead of the Xcode project. Remind the user to run xcodegen generate after.
5. No breaking changes. New features must not break existing builds.
6. Explain what changed. After each feature, list exactly what files were created/modified.

Feature: CI/CD (GitHub Actions)

Adds: .github/workflows/build.yml

Before generating, ask:

• Do you have an Apple Developer Account? (affects signing/notarization steps)
• What Xcode version? (default: 16.1)

Copy the template. Do not write this workflow yourself, and do not adapt it from memory.

mkdir -p .github/workflows
cp <macos-app-scaffold-new>/templates/ci/build.yml .github/workflows/build.yml

Then substitute {{AppName}} and adjust the env: block and the entitlements path to match the existing project (read them from project.yml).

Read templates/ci/README.md before changing anything in it. It documents why each non-obvious line exists — every one of them is a failure that only appears on a real tagged release, after the build has already gone green, with an error message that points somewhere else.

This instruction is emphatic because it was ignored once, at real cost: a hand-written workflow that looked entirely reasonable and passed on main got three of those wrong and burned several release attempts before the cause was visible.

If the project has no Apple Developer account, the same template still works — it detects the absent secrets and produces an unsigned DMG.

Verify the result, don't assume it. A green run on main proves only that the project compiles; signing, notarization and release only execute on a tag. Cut a real tag, download the published artifact, and check it with spctl -a -vv, xcrun stapler validate and lipo -archs — see the template's README for the expected output.

Also check if .gitignore needs updating for build artifacts.

Feature: Auto-Update

Prerequisite: CI/CD must exist (check .github/workflows/). If not, offer to add CI/CD first.

Ask: Which approach?

• A) GitHub API polling (lightweight) — adds UpdateChecker.swift
• B) Sparkle (full-featured) — adds Sparkle SPM dependency + SPUStandardUpdaterController setup

For GitHub API polling:

• Ask for GitHub owner/repo (or detect from git remote)
• Generate UpdateChecker.swift (see new-macos-app templates)
• Show how to integrate in the Settings window's About page (or AppDelegate)

For Sparkle:

• Add Sparkle (v2.9.0+) to project.yml packages section
• Add SUFeedURL to Info.plist properties in project.yml
• Generate SPUStandardUpdaterController setup in AppDelegate
• Add "Check for Updates" menu item or Settings toggle

EdDSA key generation — instruct the user to run locally:

# Download Sparkle, extract, then:
./bin/generate_keys
# This prints the public key (add to Info.plist as SUPublicEDKey)
# and saves the private key to Keychain.
# Export the private key and add as GitHub secret: SPARKLE_EDDSA_KEY

CI/CD appcast generation — add these steps to the existing build.yml:

- name: Download Sparkle tools
  if: env.HAS_APPLE_SECRETS == 'true'
  run: |
    SPARKLE_VERSION="2.9.0"
    curl -sL -o "$RUNNER_TEMP/sparkle.tar.xz" \
      "https://github.com/sparkle-project/Sparkle/releases/download/${SPARKLE_VERSION}/Sparkle-${SPARKLE_VERSION}.tar.xz"
    mkdir -p "$RUNNER_TEMP/sparkle"
    tar -xf "$RUNNER_TEMP/sparkle.tar.xz" -C "$RUNNER_TEMP/sparkle"

- name: Sign DMG and generate appcast
  if: env.HAS_APPLE_SECRETS == 'true'
  env:
    SPARKLE_EDDSA_KEY: ${{ secrets.SPARKLE_EDDSA_KEY }}
  run: |
    echo -n "$SPARKLE_EDDSA_KEY" > "$RUNNER_TEMP/sparkle_eddsa.key"
    SIGN_OUTPUT=$("$RUNNER_TEMP/sparkle/bin/sign_update" "$APP_NAME.dmg" -f "$RUNNER_TEMP/sparkle_eddsa.key")
    rm -f "$RUNNER_TEMP/sparkle_eddsa.key"

    ED_SIGNATURE=$(echo "$SIGN_OUTPUT" | sed -n 's/.*sparkle:edSignature="\([^"]*\)".*/\1/p')
    # Anchor the grep so it matches the SETTING line (MARKETING_VERSION: "1.2.3")
    # and skips reference lines like CFBundleShortVersionString: $(MARKETING_VERSION).
    # Without the anchor, `head -1` may pick a reference line that has no quotes
    # and `awk -F'"' '{print $2}'` returns empty — silently producing an appcast
    # with empty <sparkle:version>/<sparkle:shortVersionString>.
              
              
     [   ]  [   ] 
       
       
    
      
    
    

    {
       
       
       
       
       
       
       
       
       
       
       
       
    }  

Additional GitHub secrets for Sparkle:

• SPARKLE_EDDSA_KEY — EdDSA private key exported from generate_keys

Appcast hosting: Upload appcast.xml alongside the DMG in the GitHub Release, or host it separately (e.g., GitHub Pages, S3). Set SUFeedURL in Info.plist to point to the hosted appcast.

Feature: File-Based Logging

Adds: FileLog.swift in the Sources directory.

• Detect the Sources directory path from project structure
• Generate FileLog.swift with the app name in the log path
• Show usage example: private let log = FileLog("ClassName")

Feature: SwiftLint

Adds: .swiftlint.yml at project root.

Generate sensible defaults (see new-macos-app template). Ask if they want strict or relaxed rules.

Feature: Unit Test Target

Modifies: project.yml (if XcodeGen) to add test target. Adds: {{AppName}}Tests/{{AppName}}Tests.swift

• Read existing target name from project.yml
• Add test target with dependency on main target
• Generate skeleton test file

Feature: Launch at Login

Adds: LaunchAtLoginManager.swift Modifies: the Settings window's General page (if present) to add the toggle.

• Uses SMAppService (macOS 13+)
• If a Settings window exists, offer to add the toggle to its General page. If the project still has an old flat SettingsView.swift, offer to migrate it to the sidebar template first — see Feature: Settings/Preferences Window

Feature: Background Helper (User Agent or Privileged Daemon)

Advanced. Almost no app needs this. The Launch at Login feature above is the right answer for "I want my app to start at login". This feature is for apps that need a separate helper process running in the background.

Decision table (show this verbatim when the user asks for this feature):

Option	What you get	Runs as	Approval	Pick when…
User Agent (SMAppService.agent)	Separate helper binary; launchd starts it on demand once the user has logged in. App ↔ helper via XPC.	user	none	Background work that does not need root: clipboard watcher, sync engine, hotkey daemon, on-device AI worker.
Privileged Daemon (SMAppService.daemon)	Separate 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, kext-adjacent, system-wide proxy, services that must run before any user logs in (set RunAtLoad for that).

Default: User Agent. Confirm explicitly before adding the daemon variant. If the user picks daemon, ask one verification question: "Which specific operation needs root?" — if they cannot name one, steer them to agent.

Adds (User Agent):

• Shared/HelperProtocol.swift (compiled into both targets)
• Helper/HelperMain.swift
• Helper/LaunchAgents/<HelperBundleID>.plist
• Helper/<HelperExecutableName>.entitlements
• Sources/HelperManager.swift

Adds (Privileged Daemon):

• Same five files but under Helper/LaunchDaemons/
• Plist contains SMAuthorizedClients with the app's designated requirement
• HelperManager.swift includes status polling and openSystemSettings()

Modifies:

• project.yml — adds a tool-type helper target, copies the plist into Contents/Library/Launch{Agents,Daemons}/, and lists the helper as a dependency of the main app with copy.destination: executables
• .github/workflows/build.yml — extends the codesign loop to sign Contents/MacOS/<helper> with <helper>.entitlements if present
• Optionally, the Settings window's General page — adds a toggle bound to HelperManager.shared

Templates location. The agent and daemon templates ship with the companion macos-app-scaffold-new skill. From this skill's directory the relative path is ../macos-app-scaffold-new/templates/{agent,daemon}/; from the repo root it is skills/macos-app-scaffold-new/templates/{agent,daemon}/. If you cannot find them locally (e.g., user installed only one skill), fetch from the upstream repo at https://github.com/XueshiQiao/macos-app-scaffold/tree/main/skills/macos-app-scaffold-new/templates. Read each template's README.md before copying.

Placeholders to substitute:

• {{AppName}}, {{AppBundleID}} — read from project.yml
• {{HelperBundleID}} — default <AppBundleID>.helper, ask to confirm
• {{HelperExecutableName}} — default <AppName>Helper, ask to confirm
• {{TeamID}} — daemon only; ask the user, or run security find-identity -p codesigning -v and offer the matches

After generating, tell the user:

1. Run xcodegen generate and build.
2. For agent: call try HelperManager.shared.register() from a Settings toggle. Helper launches on first XPC call.
3. For daemon: call try HelperManager.shared.register(). If status becomes .requiresApproval, surface a button that calls HelperManager.shared.openSystemSettings(). After the user flips the switch, status transitions to .enabled.
4. Test without rebooting:
   • Agent: launchctl kickstart -k gui/$(id -u)/<HelperBundleID>
   • Daemon: sudo launchctl kickstart -k system/<HelperBundleID>
   • Logs: log stream --predicate 'subsystem == "<HelperBundleID>"'

Feature: Accessibility Permission Gate

Adds: PermissionManager.swift Modifies: AppDelegate.swift to call permission check on launch.

• Read existing AppDelegate to find the right insertion point
• Add AXIsProcessTrustedWithOptions check

Feature: Screen Recording Permission

Do not bundle this with the Accessibility gate. They look similar but the first-grant semantics are fundamentally different. ScreenCaptureKit requires a full app relaunch after first grant — Accessibility does not. An inline-style flow that polls SCShareableContent after grant is the single most common bug in this corner of the API.

Adds:

• Sources/ScreenRecordingPermission.swift — manager with the relaunch invariant encoded in its Status enum (notGranted / grantedPendingRelaunch / granted)
• Sources/ScreenRecordingPromptView.swift — three-state SwiftUI modal: explain → "Open Settings" → poll → "Relaunch Now"

Templates location. ../macos-app-scaffold-new/templates/screen-recording/ (repo path: skills/macos-app-scaffold-new/templates/screen-recording/). Read its README.md before generating — it documents the dev-loop gotchas the templates exist to prevent.

Modifies:

• A Settings tab or feature entry point — present ScreenRecordingPromptView as a sheet when the user first reaches a feature that captures the screen
• Any code that calls SCShareableContent / SCStream / SCScreenshotManager — must gate on ScreenRecordingPermission.shared.isReadyForCapture (NEVER on status != .notGranted, which lets .grantedPendingRelaunch through and produces silent failures)

Detect-and-replace: if the project already contains a ScreenRecordingChecker.swift (an earlier version of macos-app-starter shipped one), replace it. That earlier file calls CGRequestScreenCaptureAccess and immediately uses SCShareableContent without any relaunch handling — the textbook bug this template exists to fix. Migrate call sites from ScreenRecordingChecker.shared.isGranted to ScreenRecordingPermission.shared.isReadyForCapture.

Placeholders to substitute:

• {{AppName}} — replace in ScreenRecordingPromptView.swift (UI string)

Tell the user about the dev-loop gotcha (mandatory):

1. Debug builds must use a stable signing identity. Set CODE_SIGN_IDENTITY: "Apple Development" (NOT -) in project.yml for the Debug config, and pin DEVELOPMENT_TEAM. Re-signing with a different identity silently wipes the TCC entry, the System Settings toggle disappears, and ScreenCaptureKit returns nothing — without any error.
2. To reproduce the first-grant flow during testing: tccutil reset ScreenCapture <BundleID>.
3. Do NOT add NSScreenRecordingUsageDescription to Info.plist. It is not consulted by this API; the system dialog uses CFBundleDisplayName.
4. ScreenCaptureKit works under App Sandbox once TCC is granted — no entitlement change is needed.

App Sandbox note: Unlike Accessibility (which is incompatible with sandbox), Screen Recording works in sandboxed apps. Mention this if the user is on the App Store path.

Feature: Localization

Adds: Localizable.xcstrings (and InfoPlist.xcstrings for display name). Optionally, for an instant in-app language switch, LocalizationOverride.swift from ../macos-app-scaffold-new/templates/settings/. Modifies: project.yml to add Resources/ path, LOCALIZATION_PREFERS_STRING_CATALOGS: YES, SWIFT_EMIT_LOC_STRINGS: YES, DEVELOPMENT_LANGUAGE, and knownRegions (must include all selected languages plus Base). AGENTS.md to add the "no bare UI string literals" convention.

See macos-app-scaffold-new/SKILL.md "Localization (if selected)" section for the full template — same xcstrings JSON shape, same project.yml settings, same AGENTS.md text. Follow the same approach when enhancing.

Pick one language mode, never both. Either the app follows the system (strings written as String(localized:) or bare Text("…")), or it offers an instant in-app switch (LocalizationOverride.swift only, strings written as L("…")). Do not write an AppleLanguages switcher: Bundle.main has already resolved its localization in a running process, so that only takes effect at the next launch no matter how the view tree is rebuilt. For the instant mode, follow all five steps under "Wiring it" in ../macos-app-scaffold-new/templates/settings/README.md — copying the file is only the first.

Ask: Which languages? (always includes English)

• Scan existing Swift files for hardcoded strings that should be localized
• Generate the strings file with discovered keys
• Show how to use String(localized:) or NSLocalizedString

Feature: Settings/Preferences Window

Adds: the files in templates/settings/. Modifies: app entry point — adds CommandGroup(replacing: .appSettings), and removes any existing Settings { … } scene.

Templates location. ../macos-app-scaffold-new/templates/settings/ (repo path: skills/macos-app-scaffold-new/templates/settings/). Read its README.md before copying. Copy the files; do not improvise a settings window.

Never add a SwiftUI Settings scene, and remove one if you find it. For a menu-bar app (LSUIElement: true) it opens the settings window behind whatever the user is looking at — the app is never frontmost when its menu-bar icon is clicked, and SettingsLink orders the window in without activating the app. There is no hook on the Settings scene to fix it.

Steps:

1. Copy SettingsWindowController.swift, SettingsStore.swift, SettingsChrome.swift, GeneralPage.swift, AboutPage.swift into the app's Sources/. Replace {{AppName}}.
2. In the app entry point, delete any Settings { … } scene and add:

   .commands {
       CommandGroup(replacing: .appSettings) {
           Button("Settings…") { SettingsWindowController.shared.show() }
               .keyboardShortcut(",", modifiers: .command)
       }
   }
   

   This is not optional: dropping the Settings scene silently removes the application menu's "Settings…" item and its ⌘, shortcut.
3. Open it from the menu-bar menu with Button("Settings…") { SettingsWindowController.shared.show() } — replace any SettingsLink.
4. Migrate, don't discard. If the project already has a settings view, move each existing control into GeneralPage (or a new page) rather than dropping it. Bindings that read through an existing manager or engine should keep doing so — see "own it, or forward it" in the template README; do not mirror their values into SettingsStore.
5. Point SettingsStore.isOperational / statusText at whatever can actually block this app, or delete the status footer.

Confirm nothing survived:

grep -rn "Settings *{\|SettingsLink" Sources/    # must return nothing

Feature: Analytics (Aptabase)

Modifies: project.yml to add Aptabase SPM dependency. Adds: Analytics initialization in AppDelegate.

• Add package to project.yml
• Add Aptabase.shared.initialize(appKey: "YOUR_KEY") in AppDelegate
• Remind user to get their Aptabase app key

Feature: Onboarding/Welcome Window

Adds: WelcomeView.swift + window management code.

• Generate SwiftUI welcome view
• Add UserDefaults check for first launch (store the app VERSION that completed it, not a bare bool — a later release can then re-introduce itself without re-showing this one to everybody)
• Show how to present it from AppDelegate

Two traps, both of which produce a window that looks fine and does nothing:

• Activate before ordering front. A menu-bar app is not frontmost at launch, so an unactivated window opens behind everything:

  NSApp.activate(ignoringOtherApps: true)
  window.makeKeyAndOrderFront(nil)
  

• @Environment(\.dismiss) does not work here. Inside a plain NSHostingView in an AppKit NSWindow it is a no-op, so a "Done" button wired to it silently fails. Pass an explicit close callback into the view:

  window.contentView = NSHostingView(rootView: WelcomeView { [weak self] in
      self?.welcomeWindow?.close()
      self?.welcomeWindow = nil     // isReleasedWhenClosed is false — this frees it
  })
  

If the Settings window template is also present, reuse its HeroTile and auroraBackground() so the first thing a user sees and the place they come back to look like the same app.

Feature: Homebrew Cask

Adds: A working cask .rb file at the chosen tap location, plus (for topology B) a sibling tap repo skeleton, plus (for topology C) a PR checklist.

Detect first, then ask:

• Detect GitHub remote (git remote get-url origin) → owner/repo for the URL.
• Read version from project.yml (MARKETING_VERSION or top-level version).
• Read deployment target from project.yml (DEPLOYMENT_TARGET / MACOSX_DEPLOYMENT_TARGET) → maps to depends_on macos: codename.
• Detect auto-update mechanism: presence of Sparkle SPM dep, or an appcast.xml file → Sparkle; else look for any GitHub-release polling code → :github_latest; else default to :github_latest for livecheck and omit auto_updates true.

Then ask the tap-topology question — same four options as the new-app skill (see macos-app-scaffold-new/SKILL.md Step 4a). Default to A if the user mentions an existing tap, otherwise B. Capture cask_topology, tap_owner, tap_repo_name.

Generate using the template in macos-app-scaffold-new/SKILL.md "Homebrew Cask (if selected)" — same fields (desc, livecheck, auto_updates, depends_on, expanded zap), same per-topology destination logic.

If the project has a CI workflow (.github/workflows/*.yml) AND topology is A or B, also append the cask-bump step described in the new-app skill (search for Update Homebrew cask in tap repo). Tell the user to add the HOMEBREW_TAP_TOKEN secret. Do not append the step for C or D.

After writing files, run validation: brew style ./Casks/<name>.rb. Report the result. Defer brew audit --cask --online to the user since it requires the cask to be reachable via a tap.

Feature: README.md

Adds: README.md with badges.

• Read project info (name, macOS version, Swift version, license)
• Generate README with build badge, version badge, license badge
• Include build-from-source instructions based on detected build system

Feature: License

Adds: LICENSE file.

Ask: MIT / GPL-3.0 / Apache-2.0 / None

Feature: AGENTS.md + CLAUDE.md

Adds: AGENTS.md and CLAUDE.md symlink.

• Analyze the project and generate conventions based on what's actually there
• Document build commands, tech stack, architecture, CI/CD, secrets
• Create CLAUDE.md as symlink: ln -s AGENTS.md CLAUDE.md
• If CLAUDE.md already exists as a regular file, ask before replacing

---

Step 4: Summary

After all features are added, print:

1. Files created — list of new files
2. Files modified — list of changed files with what changed
3. Next steps:
   • xcodegen generate (if project.yml was modified)
   • Any secrets to configure
   • Any manual steps needed (e.g., get Aptabase key, set up Sparkle EdDSA keys)

---

Feature Name Aliases

For argument-based invocation, accept these aliases:

Argument	Feature
ci-cd, ci, github-actions	CI/CD
auto-update, update, sparkle	Auto-Update
logging, log, filelog	File-Based Logging
swiftlint, lint	SwiftLint
test, tests, unit-test	Unit Test Target
launch-at-login, login, autostart	Launch at Login
helper, agent, xpc-helper, background-helper	Background Helper — User Agent
daemon, privileged-helper, root-helper	Background Helper — Privileged Daemon
accessibility, a11y, permission	Accessibility Gate
screen-recording, screencapture, sckit, screencapturekit	Screen Recording Permission
localization, l10n, i18n	Localization
settings, preferences, prefs	Settings Window
analytics, aptabase	Analytics
onboarding, welcome	Onboarding Window
homebrew, cask, brew	Homebrew Cask
readme	README.md

---

Reminders

• Always read existing files before modifying. Never assume structure.
• If project.yml exists, it is the single source of truth. Modify it, not .pbxproj.
• After modifying project.yml, remind the user to run xcodegen generate.
• Respect the AGENTS.md / CLAUDE.md symlink convention. Never replace a symlink with a standalone file.
• Use Swift 6.0 conventions (@MainActor, Sendable) in all generated code.
• Generated code must compile with the existing project. Check imports and types.
• Universal binary support: ensure CI builds use ARCHS="arm64 x86_64" ONLY_ACTIVE_ARCH=NO.