@olegkoval/agent-skills 1.12.0 → 1.13.0

package/packages/software-development/macos-menubar-app/adapters/kiro/steering/macos-menubar-app.md

@@ -0,0 +1,225 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+inclusion: manual
+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/packages/software-development/macos-menubar-app/adapters/windsurf/rules/macos-menubar-app.md

@@ -0,0 +1,224 @@
+<!-- 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/packages/software-development/skill-budget-audit/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: skill-budget-audit
+description: Diagnose and fix Claude Code's skill context budget overflow — identify heavy plugin bundles that exceed the 2% budget, remove domain-specific ones, deactivate rarely-used skill sets, and validate the warning clears. Use when Claude Code shows "Exceeded skills context budget" or skill descriptions are stripped.
+license: MIT
+allowed-tools: Bash, Read, Write, Edit
+compatibility: Claude Code only. Requires access to ~/.claude/ and ~/.claude/plugins/
+metadata:
+  targets: [_source-only]
+  author: Oleg Koval
+  tags:
+    - claude-code
+    - skills
+    - plugins
+    - context-budget
+    - token-economy
+    - performance
+---
+
+> 🤖 *Auto-generated by **weekly-pattern-learner** · Skill context budget overflow appeared in 2 sessions this week (Jun 2026): initial investigation (7 turns, 742 skills hidden) and cleanup followup (14 turns)*
+
+# Skill Context Budget Audit
+
+## Overview
+
+Claude Code allocates 2% of its context window for skill descriptions. With too many plugins installed, descriptions get stripped and skills become invisible. This skill audits plugin bundles, removes unused domain-specific ones, and restores skill discoverability.
+
+## When to Use
+
+- Claude Code shows: `⚠ Exceeded skills context budget of 2%. All skill descriptions were removed and N additional skills hidden.`
+- Skill invocations fail silently or Claude cannot find a skill by name
+- After installing multiple plugin bundles, noticing slowdown or skill lookup failures
+- Periodically as a maintenance step when adding new skill collections
+
+## Workflow
+
+### 1. Confirm the Symptom
+
+```bash
+# Check Claude Code logs for context budget warning
+cat ~/.claude/logs/claude-code.log 2>/dev/null | grep -i "skill" | tail -20
+
+# Or count installed plugins
+ls ~/.claude/plugins/cache/ | wc -l
+```
+
+If you see `Exceeded skills context budget` or more than ~20 plugin bundles, proceed.
+
+### 2. Inventory Installed Plugins
+
+```bash
+# List all installed plugins with size
+du -sh ~/.claude/plugins/cache/*/ 2>/dev/null | sort -rh | head -30
+
+# Count skills per bundle
+for dir in ~/.claude/plugins/cache/*/; do
+  count=$(find "$dir" -name "*.md" -path "*/skills/*" 2>/dev/null | wc -l | tr -d ' ')
+  echo "$count  $dir"
+done | sort -rn | head -20
+```
+
+### 3. Identify Removal Candidates
+
+Remove bundles that match any of these criteria:
+
+| Criterion | Example bundles |
+|-----------|----------------|
+| Domain not active in current projects | `claude-for-financial-services`, `bitwize-music` |
+| Duplicate superpowers installations | Multiple `superpowers-*` versions |
+| Language-specific bundles for inactive languages | `cc-skills-golang` when not working in Go |
+| Bundles with 30+ skills you never invoke | Large catch-all collections |
+
+Keep: core workflow skills (superpowers, agent-skills), project-specific skills, personal skill collections.
+
+### 4. Remove Heavy Bundles
+
+```bash
+# List Claude Code plugins (check settings.json for registered ones)
+cat ~/.claude/settings.json | grep -A 50 '"plugins"'
+# or
+cat ~/.claude/settings.local.json 2>/dev/null | grep -A 50 '"plugins"'
+```
+
+Remove via Claude Code settings or by editing the plugins list directly:
+
+```bash
+# Backup first
+cp ~/.claude/settings.json ~/.claude/settings.json.bak
+
+# Then edit ~/.claude/settings.json to remove plugin entries
+# Remove entries like:
+#   "claude-for-financial-services"
+#   "bitwize-music"
+#   duplicate superpowers entries
+```
+
+Remove cached plugin directories:
+
+```bash
+cache_dir="$HOME/.claude/plugins/cache/<bundle-name>"
+if [ -d "$cache_dir" ]; then
+  rm -rf "$cache_dir"
+fi
+```
+
+### 5. Conditionally Load Heavy Skill Sets
+
+For language-specific bundles (e.g., `cc-skills-golang`):
+- Only install when actively working in that language
+- Uninstall when switching projects
+
+For security-focused skills (`secskills`):
+- Configure as manually invocable only (not auto-loaded)
+- In plugin settings: set `autoLoad: false` if supported
+
+### 6. Validate the Fix
+
+```bash
+# Restart Claude Code and check:
+# 1. No "Exceeded skills context budget" warning on startup
+# 2. /find-skills or skill listing shows descriptions (not empty)
+# 3. rtk gain shows reasonable context usage
+rtk gain 2>/dev/null || echo "rtk not available"
+```
+
+Open a new Claude Code session and run a skill that was previously failing — verify it activates correctly.
+
+### 7. Prevent Recurrence
+
+**Budget targets:**
+- Keep installed skills under ~200 total (rough safe limit)
+- Prefer curated skill sets over catch-all bundles
+- Review and prune quarterly
+
+**Useful heuristics:**
+- If you haven't invoked a skill in 30 days, the bundle is a candidate for removal
+- Language packs → install per-project, not globally
+- Duplicate superpowers/agent-skills versions → keep exactly one
+
+## Verification
+
+- [ ] No "Exceeded skills context budget" warning in new session
+- [ ] Skill descriptions visible in `/find-skills` output
+- [ ] Previously failing skill invocations succeed
+- [ ] Plugin count reduced to below ~20 bundles
+- [ ] `~/.claude/settings.json` backed up before changes

package/packages/software-development/skill-budget-audit/adapters/claude/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "olko-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.",
+  "skills": "./skills"
+}