@olegkoval/agent-skills 1.12.0 → 1.13.0

package/.windsurf/rules/macos-menubar-app.md

@@ -0,0 +1,225 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+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."
+---
+
+
+> 🤖 *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/catalog/skills.json

@@ -359,6 +359,72 @@
         "windsurf",
         "kiro"
       ]
+    },
+    {
+      "name": "apple-store-submit",
+      "lookupName": "olko:apple-store-submit",
+      "category": "software-development",
+      "path": "packages/software-development/apple-store-submit",
+      "description": "Handle Apple App Store rejection emails end-to-end: parse rejection reasons, plan fixes, implement code changes, navigate App Store Connect, and resubmit.",
+      "tags": [
+        "apple",
+        "app-store",
+        "ios",
+        "macos",
+        "xcode",
+        "submission",
+        "rejection"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot",
+        "windsurf",
+        "kiro"
+      ]
+    },
+    {
+      "name": "macos-menubar-app",
+      "lookupName": "olko:macos-menubar-app",
+      "category": "software-development",
+      "path": "packages/software-development/macos-menubar-app",
+      "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.",
+      "tags": [
+        "macos",
+        "swiftui",
+        "menubar",
+        "notch",
+        "xcode",
+        "apple",
+        "sandbox"
+      ],
+      "adapters": [
+        "codex",
+        "claude",
+        "cursor",
+        "copilot",
+        "windsurf",
+        "kiro"
+      ]
+    },
+    {
+      "name": "skill-budget-audit",
+      "lookupName": "olko:skill-budget-audit",
+      "category": "software-development",
+      "path": "packages/software-development/skill-budget-audit",
+      "description": "Diagnose and fix Claude Code skill context budget overflow — identify heavy plugin bundles, remove domain-specific ones, and restore skill discoverability.",
+      "tags": [
+        "claude-code",
+        "skills",
+        "plugins",
+        "context-budget",
+        "token-economy",
+        "performance"
+      ],
+      "adapters": [
+        "claude"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olegkoval/agent-skills",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/packages/software-development/apple-store-submit/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: apple-store-submit
+description: Handle Apple App Store rejection emails end-to-end — parse rejection reasons, create a fix plan, implement code changes (privacy strings, entitlements, sandbox), navigate App Store Connect to update metadata, and resubmit. Use when an app receives a rejection or when preparing a first-time submission.
+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, an Apple Developer account, and App Store Connect access.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - apple
+    - app-store
+    - ios
+    - macos
+    - xcode
+    - submission
+    - rejection
+---
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · App Store rejection handling workflow observed in FocusNotch App Store session, Jun 2026 (92 user turns covering rejection → plan → code fixes → metadata → resubmit)*
+
+# Apple App Store Submission & Rejection Handling
+
+## Overview
+
+Parse Apple rejection feedback, implement targeted fixes, update App Store Connect metadata, and resubmit — covering the complete cycle from rejection email to approved build.
+
+## When to Use
+
+- Apple review team sends a rejection email
+- App fails automated pre-review checks (binary rejected at upload)
+- Preparing metadata for first-time submission (screenshots, keywords, privacy labels)
+- Resolving App Store Connect errors before submitting for review
+
+## Workflow
+
+### 1. Parse the Rejection
+
+Read the full rejection email. Extract and list:
+
+- **Guideline numbers** violated (e.g., 2.1, 4.2.0, 5.1.1)
+- **Code-level issues** — missing entitlements, incorrect privacy strings, sandbox violations
+- **Metadata issues** — wrong screenshot sizes, subtitle policy, keyword stuffing
+- **UX issues** — crashes described by reviewer, broken flows, missing functionality
+
+Create a numbered fix plan: one item per rejection point, with the type of fix needed.
+
+### 2. Classify Fixes by Type
+
+| Type | Location |
+|------|----------|
+| Privacy usage strings missing | `Info.plist` |
+| Entitlement missing/wrong | `<AppName>.entitlements` |
+| Crash or broken feature | Source code |
+| Screenshots wrong size/content | App Store Connect |
+| Keywords/subtitle/description | App Store Connect |
+| Build number conflict | Xcode + App Store Connect |
+
+### 3. Implement Code Fixes
+
+**Privacy permission strings** (`Info.plist`):
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>Used for voice input during focus sessions.</string>
+
+<key>NSCalendarsUsageDescription</key>
+<string>Used to sync tasks with your calendar.</string>
+```
+
+**Entitlements** (`<AppName>.entitlements`):
+
+```xml
+<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/>
+```
+
+**Sandbox violations** — remove `NoEscapeBlock` patterns, replace deprecated APIs, use only sandboxed file access via Security-Scoped Bookmarks when needed.
+
+### 4. Build and Archive
+
+```bash
+# Clean build
+xcodebuild clean \
+  -scheme <AppName> \
+  -destination 'generic/platform=macOS'
+
+# Archive
+xcodebuild archive \
+  -scheme <AppName> \
+  -archivePath build/<AppName>.xcarchive \
+  -destination 'generic/platform=macOS'
+
+# Export for App Store
+xcodebuild -exportArchive \
+  -archivePath build/<AppName>.xcarchive \
+  -exportPath build/export \
+  -exportOptionsPlist ExportOptions.plist
+```
+
+Validate codesigning before upload:
+
+```bash
+codesign --verify --deep --strict --verbose=4 build/export/<AppName>.app
+spctl --assess --verbose=4 build/export/<AppName>.app
+```
+
+### 5. Update App Store Connect Metadata
+
+Navigate: **My Apps → [App] → App Store tab**
+
+Common metadata fixes:
+
+- **App name**: max 30 chars
+- **Subtitle**: max 30 chars, no duplicate keywords from the title field
+- **Keywords**: 100-char total limit, comma-separated, no spaces after commas
+- **Screenshots**: exact pixel dimensions per device type (check Apple's current spec)
+- **Privacy Nutrition Labels**: must accurately reflect data collected/linked to user
+- **Build selection**: select the newly uploaded build before submitting
+
+### 6. Write Reviewer Notes
+
+In the submission form, fill **Notes for Reviewer**:
+
+- Explain each rejection point and what was changed
+- Reference specific guideline numbers: "Addressing 2.1 — added NSMicrophoneUsageDescription to Info.plist"
+- If a feature requires special credentials to test, provide test account details
+
+### 7. Submit and Track
+
+1. Upload via **Xcode Organizer → Distribute App → App Store Connect**
+2. In App Store Connect: select the new build, fill notes, **Submit for Review**
+3. Typical re-review: 24–48h
+4. If rejected again: respond in the **Resolution Center** thread (same case number)
+5. Escalate via Resolution Center for policy disagreements — do not open a new submission
+
+## Build Number Protocol
+
+Apple rejects builds with a duplicate build number. Increment `CFBundleVersion` in `Info.plist` or Xcode target settings before every upload:
+
+```bash
+# Bump build number (e.g., 9 → 10)
+xcrun agvtool new-version -all 10
+```
+
+## Verification
+
+- [ ] Every rejection guideline number has a corresponding fix in the plan
+- [ ] `xcodebuild archive` exits 0 with no warnings about entitlements
+- [ ] `codesign --verify` passes
+- [ ] App Store Connect shows build status as "Ready to Submit"
+- [ ] Reviewer Notes reference each changed item
+- [ ] Build number is higher than any previously uploaded build

package/packages/software-development/apple-store-submit/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-apple-store-submit",
+  "description": "Handle Apple App Store rejection emails end-to-end: parse rejection reasons, plan fixes, implement code changes, navigate App Store Connect, and resubmit.",
+  "skills": "./skills"
+}

package/packages/software-development/apple-store-submit/adapters/claude/skills/apple-store-submit/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: apple-store-submit
+description: Handle Apple App Store rejection emails end-to-end — parse rejection reasons, create a fix plan, implement code changes (privacy strings, entitlements, sandbox), navigate App Store Connect to update metadata, and resubmit. Use when an app receives a rejection or when preparing a first-time submission.
+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, an Apple Developer account, and App Store Connect access.
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - apple
+    - app-store
+    - ios
+    - macos
+    - xcode
+    - submission
+    - rejection
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · App Store rejection handling workflow observed in FocusNotch App Store session, Jun 2026 (92 user turns covering rejection → plan → code fixes → metadata → resubmit)*
+
+# Apple App Store Submission & Rejection Handling
+
+## Overview
+
+Parse Apple rejection feedback, implement targeted fixes, update App Store Connect metadata, and resubmit — covering the complete cycle from rejection email to approved build.
+
+## When to Use
+
+- Apple review team sends a rejection email
+- App fails automated pre-review checks (binary rejected at upload)
+- Preparing metadata for first-time submission (screenshots, keywords, privacy labels)
+- Resolving App Store Connect errors before submitting for review
+
+## Workflow
+
+### 1. Parse the Rejection
+
+Read the full rejection email. Extract and list:
+
+- **Guideline numbers** violated (e.g., 2.1, 4.2.0, 5.1.1)
+- **Code-level issues** — missing entitlements, incorrect privacy strings, sandbox violations
+- **Metadata issues** — wrong screenshot sizes, subtitle policy, keyword stuffing
+- **UX issues** — crashes described by reviewer, broken flows, missing functionality
+
+Create a numbered fix plan: one item per rejection point, with the type of fix needed.
+
+### 2. Classify Fixes by Type
+
+| Type | Location |
+|------|----------|
+| Privacy usage strings missing | `Info.plist` |
+| Entitlement missing/wrong | `<AppName>.entitlements` |
+| Crash or broken feature | Source code |
+| Screenshots wrong size/content | App Store Connect |
+| Keywords/subtitle/description | App Store Connect |
+| Build number conflict | Xcode + App Store Connect |
+
+### 3. Implement Code Fixes
+
+**Privacy permission strings** (`Info.plist`):
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>Used for voice input during focus sessions.</string>
+
+<key>NSCalendarsUsageDescription</key>
+<string>Used to sync tasks with your calendar.</string>
+```
+
+**Entitlements** (`<AppName>.entitlements`):
+
+```xml
+<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/>
+```
+
+**Sandbox violations** — remove `NoEscapeBlock` patterns, replace deprecated APIs, use only sandboxed file access via Security-Scoped Bookmarks when needed.
+
+### 4. Build and Archive
+
+```bash
+# Clean build
+xcodebuild clean \
+  -scheme <AppName> \
+  -destination 'generic/platform=macOS'
+
+# Archive
+xcodebuild archive \
+  -scheme <AppName> \
+  -archivePath build/<AppName>.xcarchive \
+  -destination 'generic/platform=macOS'
+
+# Export for App Store
+xcodebuild -exportArchive \
+  -archivePath build/<AppName>.xcarchive \
+  -exportPath build/export \
+  -exportOptionsPlist ExportOptions.plist
+```
+
+Validate codesigning before upload:
+
+```bash
+codesign --verify --deep --strict --verbose=4 build/export/<AppName>.app
+spctl --assess --verbose=4 build/export/<AppName>.app
+```
+
+### 5. Update App Store Connect Metadata
+
+Navigate: **My Apps → [App] → App Store tab**
+
+Common metadata fixes:
+
+- **App name**: max 30 chars
+- **Subtitle**: max 30 chars, no duplicate keywords from the title field
+- **Keywords**: 100-char total limit, comma-separated, no spaces after commas
+- **Screenshots**: exact pixel dimensions per device type (check Apple's current spec)
+- **Privacy Nutrition Labels**: must accurately reflect data collected/linked to user
+- **Build selection**: select the newly uploaded build before submitting
+
+### 6. Write Reviewer Notes
+
+In the submission form, fill **Notes for Reviewer**:
+
+- Explain each rejection point and what was changed
+- Reference specific guideline numbers: "Addressing 2.1 — added NSMicrophoneUsageDescription to Info.plist"
+- If a feature requires special credentials to test, provide test account details
+
+### 7. Submit and Track
+
+1. Upload via **Xcode Organizer → Distribute App → App Store Connect**
+2. In App Store Connect: select the new build, fill notes, **Submit for Review**
+3. Typical re-review: 24–48h
+4. If rejected again: respond in the **Resolution Center** thread (same case number)
+5. Escalate via Resolution Center for policy disagreements — do not open a new submission
+
+## Build Number Protocol
+
+Apple rejects builds with a duplicate build number. Increment `CFBundleVersion` in `Info.plist` or Xcode target settings before every upload:
+
+```bash
+# Bump build number (e.g., 9 → 10)
+xcrun agvtool new-version -all 10
+```
+
+## Verification
+
+- [ ] Every rejection guideline number has a corresponding fix in the plan
+- [ ] `xcodebuild archive` exits 0 with no warnings about entitlements
+- [ ] `codesign --verify` passes
+- [ ] App Store Connect shows build status as "Ready to Submit"
+- [ ] Reviewer Notes reference each changed item
+- [ ] Build number is higher than any previously uploaded build

package/packages/software-development/apple-store-submit/adapters/codex/README.md

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

package/packages/software-development/apple-store-submit/adapters/cursor/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "olko:apple-store-submit",
+  "version": "0.1.0",
+  "description": "Handle Apple App Store rejection emails end-to-end: parse rejection reasons, plan fixes, implement code changes, navigate App Store Connect, and resubmit.",
+  "skills": "skills/"
+}