@olegkoval/agent-skills 1.12.0 → 1.13.0

package/packages/software-development/macos-menubar-app/adapters/claude/skills/macos-menubar-app/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: macos-menubar-app
+description: Build a production-quality macOS menubar or notch app in SwiftUI — covering MenuBarExtra setup, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and /critique-driven polish cycles. Use when starting or extending a macOS agent app that lives in the status bar or Mac notch area.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires Xcode 15+, macOS 13+ deployment target, and an Apple Developer account for App Store distribution.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - macos
+    - swiftui
+    - menubar
+    - notch
+    - xcode
+    - apple
+    - sandbox
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · SwiftUI macOS menubar app pattern observed in FocusNotch session, Jun 2026 (364 user turns, ~48 MB transcript covering idea → spec → impl → critique cycles → App Store)*
+
+# macOS Menubar / Notch App (SwiftUI)
+
+## Overview
+
+Build a macOS app that lives in the menu bar or notch using SwiftUI's `MenuBarExtra`. Covers the full lifecycle: project setup, window management, entitlements, user interaction (keyboard shortcuts, sound), and App Store preparation.
+
+## When to Use
+
+- User asks to build an app for the macOS menubar, status bar, or notch
+- Adding a menubar presence to an existing macOS app
+- Debugging sandbox rejections or entitlement errors in a SwiftUI app
+
+## Workflow
+
+### 1. Project Setup
+
+Create a new macOS App target in Xcode:
+
+- **Interface**: SwiftUI
+- **App Sandbox**: Enabled (required for App Store)
+- **Bundle ID**: `com.yourname.AppName`
+- **Deployment target**: macOS 13+ (for `MenuBarExtra`)
+
+In `Info.plist`, set:
+
+```xml
+<key>LSUIElement</key>
+<true/>
+```
+
+This hides the app from the Dock — the menu bar becomes the only entry point.
+
+### 2. MenuBarExtra (SwiftUI native)
+
+```swift
+@main
+struct FocusApp: App {
+    var body: some Scene {
+        MenuBarExtra {
+            ContentView()
+                .frame(width: 320, height: 480)
+        } label: {
+            Label("Focus", systemImage: "timer")
+        }
+        .menuBarExtraStyle(.window)
+    }
+}
+```
+
+Use `.menuBarExtraStyle(.window)` for a popover-style panel. Use `.menuBarExtraStyle(.menu)` for a dropdown menu.
+
+### 3. Notch Detection
+
+On MacBooks with a notch, the safe area changes. Detect and adapt:
+
+```swift
+func isNotchPresent() -> Bool {
+    guard let screen = NSScreen.main else { return false }
+    // The notch area is excluded from visibleFrame top
+    let screenHeight = screen.frame.height
+    let visibleTop = screen.visibleFrame.maxY
+    return visibleTop < screenHeight
+}
+```
+
+Position windows below the notch:
+
+```swift
+window.setFrameOrigin(NSPoint(
+    x: window.frame.origin.x,
+    y: NSScreen.main!.frame.height - window.frame.height - notchOffset
+))
+```
+
+### 4. Sandbox Entitlements
+
+Minimum `.entitlements` for a sandboxed menubar app:
+
+```xml
+<?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/>
+    <!-- Add only what the app actually uses: -->
+    <!-- <key>com.apple.security.network.client</key> -->
+    <!-- <true/> -->
+</dict>
+</plist>
+```
+
+For focus/blocking features that need accessibility:
+
+```xml
+<key>com.apple.security.temporary-exception.apple-events</key>
+<array>
+    <string>com.apple.systemevents</string>
+</array>
+```
+
+### 5. Accessibility Permission (Focus Detection)
+
+To detect which app is in focus (required for distraction blocking):
+
+```swift
+import ApplicationServices
+
+func requestAccessibilityPermission() -> Bool {
+    let options: NSDictionary = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true]
+    return AXIsProcessTrustedWithOptions(options)
+}
+```
+
+Call this on first launch and prompt the user to grant access in **System Settings → Privacy → Accessibility**.
+
+### 6. Sound Effects
+
+```swift
+import AVFoundation
+
+class SoundPlayer {
+    private var player: AVAudioPlayer?
+
+    func play(_ filename: String, extension ext: String = "mp3") {
+        guard let url = Bundle.main.url(forResource: filename, withExtension: ext) else { return }
+        player = try? AVAudioPlayer(contentsOf: url)
+        player?.play()
+    }
+}
+```
+
+Add sound files to the Xcode target (check **Target Membership** in file inspector).
+
+For system sounds (no file needed):
+
+```swift
+NSSound.beep()
+// or
+NSSound(named: .init("Hero"))?.play()
+```
+
+### 7. Keyboard Shortcuts
+
+Global shortcuts (work when app is not focused) — requires Accessibility permission:
+
+```swift
+NSEvent.addGlobalMonitorForEvents(matching: .keyDown) { event in
+    if event.modifierFlags.contains([.command, .shift]) && event.keyCode == 36 { // ⌘⇧↩
+        // Handle shortcut
+    }
+}
+```
+
+Local shortcuts (SwiftUI):
+
+```swift
+.keyboardShortcut("s", modifiers: [.command, .shift])
+```
+
+### 8. Persistent State (AppStorage)
+
+```swift
+@AppStorage("timerDuration") private var timerDuration: Double = 25 * 60
+@AppStorage("soundEnabled") private var soundEnabled: Bool = true
+```
+
+For complex state, use `UserDefaults` with a suite name to share across extensions.
+
+### 9. Polish Cycle
+
+After each implementation slice:
+
+> **Optional skills**: Steps 1 and 3 require `/critique` and `/whimsy-injector` from the agent-skills catalog. Install them via `skillshare` if not already available; skip these steps if not installed.
+
+1. Run `/critique` — evaluate against Apple HIG, WCAG contrast, interaction consistency
+2. Fix all P0/P1 findings
+3. Run `/whimsy-injector` on completion screens and idle states
+4. Test on a machine **without** a notch to verify layout
+
+### 10. App Store Preparation
+
+See `olko:apple-store-submit` for the full submission and rejection-handling workflow.
+
+Pre-submission checklist:
+
+```bash
+# Validate archive
+xcodebuild archive -scheme <AppName> -archivePath build/<AppName>.xcarchive
+
+# Check sandbox
+codesign --verify --deep --strict build/<AppName>.xcarchive/Products/Applications/<AppName>.app
+
+# Verify entitlements
+codesign -d --entitlements :- build/<AppName>.xcarchive/Products/Applications/<AppName>.app
+```
+
+## Key Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| App appears in Dock | `LSUIElement` missing | Add to `Info.plist` |
+| Menubar icon missing after build | Asset catalog misconfigured | Use PDF or SVG template image, tick **Template Image** |
+| Crash on click | View not loaded in popover window | Add `.frame()` to `MenuBarExtra` content |
+| Sound not playing | File not in target | Check Target Membership in file inspector |
+| Accessibility prompt not shown | Missing entitlement | Add `temporary-exception.apple-events` or use XPC |
+| Notch overlap | Hardcoded y-position | Detect `visibleFrame` vs `frame` delta |
+
+## Verification
+
+- [ ] App does not appear in Dock (`LSUIElement` = true)
+- [ ] MenuBarExtra icon renders as template image (respects dark/light mode)
+- [ ] Sound plays on timer events
+- [ ] Keyboard shortcuts respond both globally and locally
+- [ ] App passes `codesign --verify --deep --strict`
+- [ ] Layout correct on M1 MacBook (no notch) and M3 MacBook Pro (notch)

package/packages/software-development/macos-menubar-app/adapters/codex/README.md

@@ -0,0 +1,3 @@
+# Codex adapter
+
+Use the canonical skill directly from `packages/software-development/macos-menubar-app/SKILL.md`.

package/packages/software-development/macos-menubar-app/adapters/cursor/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:macos-menubar-app",
+  "version": "0.1.0",
+  "description": "Build a production-quality macOS menubar or notch app in SwiftUI — MenuBarExtra, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and App Store preparation.",
+  "skills": "skills/"
+}

package/packages/software-development/macos-menubar-app/adapters/cursor/skills/macos-menubar-app/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: macos-menubar-app
+description: Build a production-quality macOS menubar or notch app in SwiftUI — covering MenuBarExtra setup, sandbox entitlements, keyboard shortcuts, sound effects, accessibility permissions, and /critique-driven polish cycles. Use when starting or extending a macOS agent app that lives in the status bar or Mac notch area.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires Xcode 15+, macOS 13+ deployment target, and an Apple Developer account for App Store distribution.
+metadata:
+  targets: ["cursor"]
+  author: Oleg Koval
+  tags:
+    - macos
+    - swiftui
+    - menubar
+    - notch
+    - xcode
+    - apple
+    - sandbox
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · SwiftUI macOS menubar app pattern observed in FocusNotch session, Jun 2026 (364 user turns, ~48 MB transcript covering idea → spec → impl → critique cycles → App Store)*
+
+# macOS Menubar / Notch App (SwiftUI)
+
+## Overview
+
+Build a macOS app that lives in the menu bar or notch using SwiftUI's `MenuBarExtra`. Covers the full lifecycle: project setup, window management, entitlements, user interaction (keyboard shortcuts, sound), and App Store preparation.
+
+## When to Use
+
+- User asks to build an app for the macOS menubar, status bar, or notch
+- Adding a menubar presence to an existing macOS app
+- Debugging sandbox rejections or entitlement errors in a SwiftUI app
+
+## Workflow
+
+### 1. Project Setup
+
+Create a new macOS App target in Xcode:
+
+- **Interface**: SwiftUI
+- **App Sandbox**: Enabled (required for App Store)
+- **Bundle ID**: `com.yourname.AppName`
+- **Deployment target**: macOS 13+ (for `MenuBarExtra`)
+
+In `Info.plist`, set:
+
+```xml
+<key>LSUIElement</key>
+<true/>
+```
+
+This hides the app from the Dock — the menu bar becomes the only entry point.
+
+### 2. MenuBarExtra (SwiftUI native)
+
+```swift
+@main
+struct FocusApp: App {
+    var body: some Scene {
+        MenuBarExtra {
+            ContentView()
+                .frame(width: 320, height: 480)
+        } label: {
+            Label("Focus", systemImage: "timer")
+        }
+        .menuBarExtraStyle(.window)
+    }
+}
+```
+
+Use `.menuBarExtraStyle(.window)` for a popover-style panel. Use `.menuBarExtraStyle(.menu)` for a dropdown menu.
+
+### 3. Notch Detection
+
+On MacBooks with a notch, the safe area changes. Detect and adapt:
+
+```swift
+func isNotchPresent() -> Bool {
+    guard let screen = NSScreen.main else { return false }
+    // The notch area is excluded from visibleFrame top
+    let screenHeight = screen.frame.height
+    let visibleTop = screen.visibleFrame.maxY
+    return visibleTop < screenHeight
+}
+```
+
+Position windows below the notch:
+
+```swift
+window.setFrameOrigin(NSPoint(
+    x: window.frame.origin.x,
+    y: NSScreen.main!.frame.height - window.frame.height - notchOffset
+))
+```
+
+### 4. Sandbox Entitlements
+
+Minimum `.entitlements` for a sandboxed menubar app:
+
+```xml
+<?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/>
+    <!-- Add only what the app actually uses: -->
+    <!-- <key>com.apple.security.network.client</key> -->
+    <!-- <true/> -->
+</dict>
+</plist>
+```
+
+For focus/blocking features that need accessibility:
+
+```xml
+<key>com.apple.security.temporary-exception.apple-events</key>
+<array>
+    <string>com.apple.systemevents</string>
+</array>
+```
+
+### 5. Accessibility Permission (Focus Detection)
+
+To detect which app is in focus (required for distraction blocking):
+
+```swift
+import ApplicationServices
+
+func requestAccessibilityPermission() -> Bool {
+    let options: NSDictionary = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true]
+    return AXIsProcessTrustedWithOptions(options)
+}
+```
+
+Call this on first launch and prompt the user to grant access in **System Settings → Privacy → Accessibility**.
+
+### 6. Sound Effects
+
+```swift
+import AVFoundation
+
+class SoundPlayer {
+    private var player: AVAudioPlayer?
+
+    func play(_ filename: String, extension ext: String = "mp3") {
+        guard let url = Bundle.main.url(forResource: filename, withExtension: ext) else { return }
+        player = try? AVAudioPlayer(contentsOf: url)
+        player?.play()
+    }
+}
+```
+
+Add sound files to the Xcode target (check **Target Membership** in file inspector).
+
+For system sounds (no file needed):
+
+```swift
+NSSound.beep()
+// or
+NSSound(named: .init("Hero"))?.play()
+```
+
+### 7. Keyboard Shortcuts
+
+Global shortcuts (work when app is not focused) — requires Accessibility permission:
+
+```swift
+NSEvent.addGlobalMonitorForEvents(matching: .keyDown) { event in
+    if event.modifierFlags.contains([.command, .shift]) && event.keyCode == 36 { // ⌘⇧↩
+        // Handle shortcut
+    }
+}
+```
+
+Local shortcuts (SwiftUI):
+
+```swift
+.keyboardShortcut("s", modifiers: [.command, .shift])
+```
+
+### 8. Persistent State (AppStorage)
+
+```swift
+@AppStorage("timerDuration") private var timerDuration: Double = 25 * 60
+@AppStorage("soundEnabled") private var soundEnabled: Bool = true
+```
+
+For complex state, use `UserDefaults` with a suite name to share across extensions.
+
+### 9. Polish Cycle
+
+After each implementation slice:
+
+> **Optional skills**: Steps 1 and 3 require `/critique` and `/whimsy-injector` from the agent-skills catalog. Install them via `skillshare` if not already available; skip these steps if not installed.
+
+1. Run `/critique` — evaluate against Apple HIG, WCAG contrast, interaction consistency
+2. Fix all P0/P1 findings
+3. Run `/whimsy-injector` on completion screens and idle states
+4. Test on a machine **without** a notch to verify layout
+
+### 10. App Store Preparation
+
+See `olko:apple-store-submit` for the full submission and rejection-handling workflow.
+
+Pre-submission checklist:
+
+```bash
+# Validate archive
+xcodebuild archive -scheme <AppName> -archivePath build/<AppName>.xcarchive
+
+# Check sandbox
+codesign --verify --deep --strict build/<AppName>.xcarchive/Products/Applications/<AppName>.app
+
+# Verify entitlements
+codesign -d --entitlements :- build/<AppName>.xcarchive/Products/Applications/<AppName>.app
+```
+
+## Key Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| App appears in Dock | `LSUIElement` missing | Add to `Info.plist` |
+| Menubar icon missing after build | Asset catalog misconfigured | Use PDF or SVG template image, tick **Template Image** |
+| Crash on click | View not loaded in popover window | Add `.frame()` to `MenuBarExtra` content |
+| Sound not playing | File not in target | Check Target Membership in file inspector |
+| Accessibility prompt not shown | Missing entitlement | Add `temporary-exception.apple-events` or use XPC |
+| Notch overlap | Hardcoded y-position | Detect `visibleFrame` vs `frame` delta |
+
+## Verification
+
+- [ ] App does not appear in Dock (`LSUIElement` = true)
+- [ ] MenuBarExtra icon renders as template image (respects dark/light mode)
+- [ ] Sound plays on timer events
+- [ ] Keyboard shortcuts respond both globally and locally
+- [ ] App passes `codesign --verify --deep --strict`
+- [ ] Layout correct on M1 MacBook (no notch) and M3 MacBook Pro (notch)