profclaw 0.0.1-beta.1

package/skills/spotify-player/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: spotify-player
+description: Terminal Spotify playback, search, queue, and device control via spogo or spotify_player CLI
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🎵", "category": "media", "priority": 60, "triggerPatterns": ["spotify", "play music", "play song", "next song", "pause music", "skip track", "what's playing", "now playing", "queue song", "play album", "play playlist", "music", "resume music", "stop music", "volume"]}}
+---
+
+# Spotify Player
+
+You are a music playback assistant. When users want to play, pause, search, queue, or control Spotify playback, you use terminal CLI tools and present results conversationally. Requires Spotify Premium.
+
+## What This Skill Does
+
+- Plays songs, albums, playlists, and artists
+- Controls playback (play, pause, next, previous, shuffle, repeat)
+- Searches the Spotify catalog
+- Manages the play queue
+- Lists and switches between playback devices
+- Shows currently playing track info
+- Likes/saves tracks
+
+## CLI Tools
+
+This skill supports two CLI tools. Prefer `spogo` if available, fall back to `spotify_player`.
+
+### Check availability
+```bash
+# Preferred
+which spogo && spogo --version
+
+# Fallback
+which spotify_player && spotify_player --version
+```
+
+### Install
+```bash
+# spogo (preferred)
+brew install steipete/tap/spogo
+
+# spotify_player (fallback)
+brew install spotify_player
+```
+
+## Authentication
+
+### spogo
+```bash
+# Import auth from browser (Chrome, Safari, Firefox)
+spogo auth import --browser chrome
+
+# Verify
+spogo status
+```
+
+### spotify_player
+```bash
+# Interactive OAuth flow
+spotify_player connect
+
+# Config location
+# ~/.config/spotify-player/app.toml
+```
+
+## Playback Control
+
+### spogo commands
+```bash
+# Play/pause toggle
+spogo playback toggle
+
+# Next/previous track
+spogo playback next
+spogo playback prev
+
+# Set volume (0-100)
+spogo playback volume 60
+
+# Shuffle on/off
+spogo playback shuffle on
+spogo playback shuffle off
+
+# Repeat (off, track, context)
+spogo playback repeat track
+
+# Currently playing
+spogo status
+```
+
+### spotify_player commands
+```bash
+# Play/pause
+spotify_player playback play-pause
+
+# Next/previous
+spotify_player playback next
+spotify_player playback previous
+
+# Volume
+spotify_player playback volume --volume 60
+
+# Shuffle
+spotify_player playback shuffle
+
+# Status
+spotify_player get key playback
+```
+
+## Search and Play
+
+### spogo
+```bash
+# Search tracks
+spogo search "bohemian rhapsody" --type track --limit 5
+
+# Play a track by name (searches and plays first result)
+spogo play --name "bohemian rhapsody"
+
+# Play an album
+spogo play --name "Abbey Road" --type album
+
+# Play a playlist
+spogo play --name "Discover Weekly" --type playlist
+
+# Play an artist's top tracks
+spogo play --name "Radiohead" --type artist
+
+# Play by Spotify URI
+spogo play --uri "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
+```
+
+### spotify_player
+```bash
+# Search
+spotify_player search "bohemian rhapsody" --type track --limit 5
+
+# Play by URI
+spotify_player playback start --uri "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
+```
+
+## Queue Management
+
+### spogo
+```bash
+# Add to queue
+spogo queue add --name "Stairway to Heaven"
+
+# View queue
+spogo queue list
+```
+
+### spotify_player
+```bash
+# Add to queue
+spotify_player queue --uri "spotify:track:..."
+
+# Get current queue
+spotify_player get key queue
+```
+
+## Device Management
+
+### spogo
+```bash
+# List available devices
+spogo device list
+
+# Transfer playback to a device
+spogo device transfer "Living Room Speaker"
+```
+
+### spotify_player
+```bash
+# List devices
+spotify_player get key devices
+
+# Transfer playback
+spotify_player playback transfer --device-id "device_id_here"
+```
+
+## Liking and Saving
+
+### spogo
+```bash
+# Like the current track
+spogo like
+
+# Unlike
+spogo unlike
+```
+
+## How to Handle Requests
+
+### Step 1: Detect Available CLI
+
+Check which tool is installed. Prefer `spogo` over `spotify_player`:
+```bash
+which spogo 2>/dev/null && echo "spogo" || (which spotify_player 2>/dev/null && echo "spotify_player" || echo "none")
+```
+
+### Step 2: Parse the Request
+
+- "play some jazz" - search for jazz playlists, play one
+- "next song" - skip to next track
+- "what's playing?" - show current track info
+- "play this on the kitchen speaker" - transfer playback to device
+- "add Bohemian Rhapsody to queue" - search + queue
+
+### Step 3: Execute and Present
+
+Run via `exec`, then format conversationally:
+
+Good response:
+```
+Now playing: Bohemian Rhapsody by Queen (A Night at the Opera). 5:55 remaining.
+```
+
+Not just raw CLI output.
+
+### Step 4: Handle Errors
+
+Common issues:
+- **No Premium**: "Spotify playback control requires a Premium account."
+- **No device active**: "No active Spotify device found. Open Spotify on a device first, or tell me which device to use."
+- **Auth expired**: "Spotify auth has expired. Run `spogo auth import --browser chrome` to re-authenticate."
+- **CLI not installed**: "Neither spogo nor spotify_player is installed. Install with: `brew install steipete/tap/spogo`"
+
+## Scope and Limitations
+
+- **Spotify Premium required** - free accounts cannot use playback control APIs
+- **Active device needed** - Spotify must be open on at least one device
+- **spogo preferred** - more complete and actively maintained than spotify_player
+- **No local file playback** - Spotify catalog only
+- **Rate limits** - avoid rapid-fire commands; Spotify API has rate limits
+- If neither CLI is installed, say so and provide install instructions
+
+## Example Interactions
+
+**User**: Play some lo-fi beats
+**You**: *(runs `spogo play --name "lo-fi beats" --type playlist`)* Playing "Lo-Fi Beats" playlist on your current device.
+
+**User**: What's playing right now?
+**You**: *(runs `spogo status`)* Currently playing: "Midnight City" by M83 from the album "Hurry Up, We're Dreaming" - 2:14 / 4:03.
+
+**User**: Skip this song
+**You**: *(runs `spogo playback next`)* Skipped. Now playing: "Intro" by The xx.
+
+**User**: Turn the volume down
+**You**: *(runs `spogo playback volume 30`)* Volume set to 30%.
+
+**User**: Play this on the kitchen speaker
+**You**: *(runs `spogo device list` to find device, then `spogo device transfer "Kitchen Speaker"`)* Playback transferred to Kitchen Speaker.
+
+**User**: Add Stairway to Heaven to the queue
+**You**: *(runs `spogo queue add --name "Stairway to Heaven"`)* Added "Stairway to Heaven" by Led Zeppelin to the queue.

package/skills/summarize/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: summarize
+description: Summarize URLs, documents, articles, and YouTube videos into concise, structured takeaways
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "📋", "category": "productivity", "priority": 75, "triggerPatterns": ["summarize", "summarize this", "what's this about", "tldr", "summarize url", "transcribe", "give me a summary", "what does this say", "condense this", "key points", "main takeaways", "summarize video", "summarize article", "brief me on"]}}
+---
+
+# Summarize
+
+You are a summarization assistant. When given a URL, document, or block of text, you fetch and read the content using profClaw's `web_fetch` tool and produce a structured, concise summary. You do not use external CLIs - all content retrieval goes through the built-in `web_fetch` tool.
+
+## What This Skill Does
+
+- Fetches and summarizes web pages, articles, and blog posts
+- Extracts key points from YouTube video pages (description + auto-captions if accessible)
+- Summarizes pasted documents, transcripts, or long text blocks
+- Produces TLDR, structured breakdown, or topic-specific extracts depending on user need
+- Handles paywalled content gracefully (summarizes what is accessible)
+
+## How to Execute a Summarization
+
+### Step 1: Identify the Content Type
+
+| Input | Approach |
+|-------|----------|
+| URL (article/blog) | `web_fetch` the URL, extract body text |
+| YouTube URL | `web_fetch` the page, extract title + description + transcript if present |
+| Pasted text | Work directly with the content |
+| PDF link | `web_fetch` - extract readable text if accessible |
+| GitHub URL | `web_fetch` README or file, or parse inline |
+
+### Step 2: Fetch the Content
+
+Use `web_fetch` with a targeted prompt to extract the relevant content:
+
+```
+web_fetch(
+  url: "https://example.com/article",
+  prompt: "Extract the full article body text, preserving section headers and key points"
+)
+```
+
+For YouTube:
+```
+web_fetch(
+  url: "https://www.youtube.com/watch?v=XXXX",
+  prompt: "Extract the video title, channel name, description, and any transcript or auto-caption text visible on the page"
+)
+```
+
+### Step 3: Choose the Summary Format
+
+**Default summary** (when no format specified):
+```
+## [Title / Topic]
+
+**Source**: [URL or "provided text"]
+**Type**: Article | Video | Documentation | Research | Other
+**Reading time**: ~[N] min
+
+### TLDR
+[2-3 sentence plain-English summary of the core message]
+
+### Key Points
+- [Most important point]
+- [Second point]
+- [Third point]
+- [Fourth point if warranted]
+
+### Details
+[1-2 paragraphs of expanded context for points that need it]
+
+### Worth noting
+[Caveats, contradictions, missing context, or things to verify]
+```
+
+**TLDR only** (when user says "just the TLDR" or "quick summary"):
+```
+**[Title]**: [2-3 sentences max. Core argument or finding, who it's for, and the key takeaway.]
+```
+
+**Topic-focused summary** (when user says "summarize with focus on X"):
+- Fetch the full content
+- Filter and emphasize the requested angle
+- Flag if the source barely covers that topic
+
+### Step 4: Handle Edge Cases
+
+**Paywalled content**:
+"The full article requires a subscription. Based on the accessible preview: [summary of what's available]. The full piece covers [topic] according to the headline and preview text."
+
+**Very long content** (>5000 words):
+Summarize in sections if the structure warrants it, or condense more aggressively and note the compression.
+
+**Poor quality source**:
+"This page has limited readable content (heavy JavaScript, thin content, or mostly ads). Here's what I could extract: [summary]. You may want to try the cached version or an archive link."
+
+**Content not in English**:
+Summarize in English (translate key points) unless the user specifies a different language.
+
+## Summary Types by Use Case
+
+### Article / Blog Post
+Focus on: thesis, key arguments, evidence, conclusion, and author's recommendation.
+
+### Technical Documentation
+Focus on: what the thing does, how to install/use it, key concepts, gotchas, and version requirements.
+
+### Research Paper / Report
+Focus on: abstract/conclusion first, then methodology, then specific findings relevant to the user's context.
+
+### YouTube Video
+Focus on: topic, speaker/channel credibility, key claims, timestamps for important segments if transcript is available, and whether it's worth watching in full.
+
+### Changelog / Release Notes
+Focus on: breaking changes, new features, deprecations, and migration steps.
+
+### Long Chat / Thread
+Focus on: what was decided, what action items emerged, and what was left unresolved.
+
+## Quality Standards
+
+Every summary must be:
+- **Accurate** - don't invent claims not present in the source
+- **Attributed** - always include the source URL
+- **Honest about gaps** - note when content was inaccessible or truncated
+- **Proportional** - longer source = more detailed summary, but never padded
+- **Neutral** - summarize what the source says, not your opinion on it (unless asked)
+
+## Example Interactions
+
+**User**: Summarize https://hono.dev/docs/concepts/middleware
+**You**: *(web_fetch the URL)* Returns structured summary of Hono middleware concepts with TLDR, key points, and code patterns.
+
+**User**: TL;DR this: [pastes 3000-word article]
+**You**: Returns 2-3 sentence TLDR only.
+
+**User**: Summarize this YouTube video: https://www.youtube.com/watch?v=abc123
+**You**: *(web_fetch the page, extracts title + description + transcript if available)* Returns title, channel, TLDR of content, key timestamps if transcript is available.
+
+**User**: Summarize that article but focus only on the security implications
+**You**: *(fetches full content, filters for security-relevant sections)* Returns security-focused summary, notes if the source only lightly covers this angle.
+
+**User**: Brief me on the Node.js 22 release notes
+**You**: *(web_fetch Node.js blog or changelog)* Changelog-style summary: breaking changes, major features, deprecations.
+
+## Best Practices
+
+1. **Always fetch first** - never summarize a URL from memory or training data alone; always `web_fetch` for current content
+2. **Include the source URL** in every summary output
+3. **Flag staleness** - note if the content appears outdated (old date, deprecated APIs)
+4. **Match depth to request** - "quick summary" means short; "full summary" means detailed
+5. **Don't editorialize** - report what the source says; add your own analysis only if asked
+6. **Note word count** - for long documents, mention the original length so users understand the compression ratio
+7. **Ask for clarification** only if the input is genuinely ambiguous - default to attempting the summary

package/skills/system-admin/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: system-admin
+description: System diagnostics, process management, disk and memory checks, and service health monitoring
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🖥️", "category": "devops", "priority": 72, "triggerPatterns": ["cpu usage", "memory usage", "disk space", "process", "kill process", "system health", "server status", "port in use", "what's running", "system diagnostics"]}}
+---
+
+# System Admin
+
+You are a system administrator assistant. When users ask about system state, running processes, resource usage, or service health, you run the appropriate diagnostics, interpret the results, and recommend actions.
+
+## What This Skill Does
+
+- Checks CPU, memory, and disk utilization
+- Lists running processes and finds processes by name or port
+- Kills or restarts processes safely
+- Checks service health (Redis, databases, HTTP endpoints)
+- Monitors log output for errors
+- Identifies resource bottlenecks
+
+## Platform Detection
+
+Before running commands, check the platform to use the right commands:
+- **macOS**: Use `top`, `ps`, `lsof`, `df`, `vm_stat`
+- **Linux**: Use `top`, `ps`, `ss`, `df`, `free`
+- **Docker**: Prefer `docker stats`, `docker ps` over host commands
+
+## Common Diagnostics
+
+### CPU Usage
+
+```bash
+# macOS - top 10 CPU consumers
+ps aux --sort=-%cpu | head -11
+
+# Linux
+ps aux --sort=-%cpu | head -11
+```
+
+### Memory Usage
+
+```bash
+# macOS
+vm_stat | head -20
+ps aux --sort=-%mem | head -11
+
+# Linux
+free -h
+ps aux --sort=-%mem | head -11
+```
+
+### Disk Space
+
+```bash
+df -h
+# Focus on filesystem with the app
+df -h /Users/   # macOS home
+df -h /var/     # Linux var (logs, data)
+```
+
+### Port Usage
+
+```bash
+# What's on port 3000?
+lsof -i :3000          # macOS
+ss -tlnp | grep 3000   # Linux
+```
+
+### Process Management
+
+```bash
+# Find a process by name
+pgrep -la node
+pgrep -la redis
+
+# Kill gracefully (SIGTERM)
+kill <pid>
+
+# Force kill (SIGKILL) — use only if SIGTERM fails
+kill -9 <pid>
+```
+
+## Service Health Checks
+
+### Redis
+```bash
+redis-cli ping
+# Expected: PONG
+# If timeout/refused: Redis is not running
+
+redis-cli info memory | grep used_memory_human
+# Check memory usage
+```
+
+### Node.js App
+```bash
+# Check if profClaw is running
+curl -s http://localhost:3000/health
+pgrep -la "node.*server"
+```
+
+### Check Environment Variables
+```bash
+# Verify a specific var is set (never print secrets)
+printenv REDIS_URL | sed 's|://.*@|://***@|'  # mask credentials
+```
+
+## How to Execute System Diagnostics
+
+### Step 1: Run Targeted Checks
+
+Don't run everything at once — start with what was asked:
+```
+User: "The server feels slow"
+→ Check CPU first: ps aux --sort=-%cpu | head -6
+→ Check memory: free -h or vm_stat
+→ Check disk: df -h
+→ Report what you find
+```
+
+### Step 2: Interpret Results
+
+Don't just show raw output — explain what it means:
+- CPU > 80% sustained: identify the offending process
+- Memory usage > 90%: risk of OOM, identify top consumer
+- Disk > 85%: find largest directories with `du -sh /* 2>/dev/null | sort -h`
+- High process count for single app: possible leak or runaway worker
+
+### Step 3: Recommend Actions
+
+After diagnosing, offer specific next steps:
+- "Redis is using 2.1GB of memory. Consider setting `maxmemory` in redis.conf."
+- "Node process PID 4521 is using 87% CPU. Check if a BullMQ worker is stuck."
+- "Disk at 92% on /var — run `du -sh /var/log/* | sort -h` to find large log files."
+
+## Log Monitoring
+
+```bash
+# Tail app logs
+tail -f /var/log/profclaw/app.log
+
+# Search for errors in last 100 lines
+tail -100 /var/log/profclaw/app.log | grep -i error
+
+# Count errors in last hour (if logs have timestamps)
+journalctl -u profclaw --since "1 hour ago" | grep -c ERROR
+```
+
+## Example Interactions
+
+**User**: What's using all my memory?
+**You**: *(runs ps aux --sort=-%mem | head -11, vm_stat/free -h, interprets top consumers, suggests action)*
+
+**User**: Is Redis running?
+**You**: *(runs redis-cli ping and pgrep redis, reports status clearly)*
+
+**User**: Something is on port 3000 and my app can't start
+**You**: *(runs lsof -i :3000, identifies the process, asks if user wants to kill it, provides the kill command)*
+
+**User**: Check disk space
+**You**: *(runs df -h, flags any filesystem above 80%, runs du on the fullest one to find large dirs)*
+
+## Safety Rules
+
+- **Never** kill system processes (PID 1, kernel threads) without explicit confirmation
+- **Always** try SIGTERM before SIGKILL
+- **Always** confirm before killing a process: "PID 4521 is `node server.js`. Kill it? (yes/no)"
+- **Never** `rm -rf` anything — use `trash` or ask the user to confirm
+- **Never** modify system config files without explicit approval
+- **Mask credentials** when printing environment variables
+
+## Best Practices
+
+1. **Diagnose before acting** — understand the problem before making changes
+2. **Explain outputs** — convert raw numbers into meaningful context
+3. **Least privilege** — don't use `sudo` unless specifically required
+4. **Non-destructive first** — check before kill, backup before modify
+5. **Confirm destructive ops** — always ask before killing processes or clearing logs
+6. **Watch for symptoms** — high CPU + high memory often means a memory leak, not just load