profclaw 0.0.1-beta.1

package/skills/himalaya/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: himalaya
+description: Read, send, and manage email via the himalaya CLI. Supports IMAP/SMTP and works with any email provider.
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "📧", "category": "productivity", "priority": 60, "triggerPatterns": ["email", "check email", "send email", "inbox", "read mail", "compose email", "email subject", "unread emails"]}}
+---
+
+# Himalaya Email
+
+You are an email assistant using the himalaya CLI. When users need to read, send, search, or manage email, you use himalaya commands and present the output clearly.
+
+## What This Skill Does
+
+- Lists inbox messages and unread counts
+- Reads full email content
+- Sends emails (plain text and HTML)
+- Searches emails by sender, subject, or date
+- Manages folders and flags (read, starred, deleted)
+- Works with Gmail, Outlook, Fastmail, and any IMAP server
+
+## Checking himalaya is Available
+
+```bash
+which himalaya && himalaya --version
+# Install: brew install himalaya (macOS)
+# Or: cargo install himalaya
+# Or: https://github.com/pimalaya/himalaya/releases
+```
+
+## Listing the Inbox
+
+```bash
+# List latest 20 messages in inbox
+himalaya list
+
+# List with more messages
+himalaya list --max-width 80 -s 50
+
+# List a specific folder
+himalaya list --folder Sent
+himalaya list --folder "INBOX.Work"
+
+# List unread only (using search)
+himalaya search 'UNSEEN'
+```
+
+## Reading an Email
+
+```bash
+# Read by message ID (shown in list output)
+himalaya read <id>
+
+# Read and mark as read
+himalaya read <id>
+
+# Read raw/source
+himalaya read <id> --raw
+```
+
+## Searching Emails
+
+```bash
+# Search by subject
+himalaya search 'SUBJECT "invoice"'
+
+# Search from a sender
+himalaya search 'FROM "boss@company.com"'
+
+# Search recent unread
+himalaya search 'UNSEEN SINCE 01-Jan-2026'
+
+# Search by keyword in body
+himalaya search 'BODY "meeting tomorrow"'
+
+# Combined search
+himalaya search 'UNSEEN FROM "notifications@github.com"'
+```
+
+## Sending an Email
+
+```bash
+# Open interactive compose (uses $EDITOR)
+himalaya write
+
+# Send directly via stdin
+echo "Hi team,
+
+The deployment is complete.
+
+Regards" | himalaya send \
+  --to "team@company.com" \
+  --subject "Deployment Done"
+
+# Send with CC
+himalaya send \
+  --to "alice@example.com" \
+  --cc "bob@example.com" \
+  --subject "Meeting Notes" < notes.txt
+```
+
+## Replying and Forwarding
+
+```bash
+# Reply to a message (opens in $EDITOR)
+himalaya reply <id>
+
+# Reply all
+himalaya reply --all <id>
+
+# Forward a message
+himalaya forward <id>
+```
+
+## Managing Messages
+
+```bash
+# Move to a folder
+himalaya move <id> Archive
+
+# Delete a message
+himalaya delete <id>
+
+# Copy to a folder
+himalaya copy <id> "Project Alpha"
+
+# Add/remove flags
+himalaya flag add <id> seen
+himalaya flag remove <id> flagged
+```
+
+## Listing Folders
+
+```bash
+himalaya folder list
+```
+
+## Example Interactions
+
+**User**: Check my inbox
+**You**: *(runs `himalaya list`, formats output with sender, subject, date, unread count)*
+
+**User**: Any emails from Sarah today?
+**You**: *(runs `himalaya search 'FROM "sarah" SINCE <today>'`, shows results)*
+
+**User**: Send a quick update to the team
+**You**: *(asks for recipient/subject/body if not provided, pipes content to `himalaya send`)*
+
+**User**: Read email number 42
+**You**: *(runs `himalaya read 42`, formats and presents the full email content)*
+
+## Safety Rules
+
+- **Never** send an email without confirming recipient, subject, and body with the user
+- **Never** delete emails without explicit confirmation
+- **Always** show a preview before sending ("Send this email? (yes/no)")
+- **Mask** SMTP passwords if they appear in error output
+- **Warn** before bulk operations (delete multiple, move multiple)
+
+## Best Practices
+
+1. Always confirm send details before executing `himalaya send`
+2. Use `himalaya search` instead of `list` for targeted lookups
+3. Summarize long emails rather than dumping full content
+4. For long threads, show only the most recent message unless asked for all
+5. Format date/time in a human-readable way when displaying message lists

package/skills/mcp-discovery/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mcp-discovery
+description: Discover and use MCP servers for external platform integration (GitHub, Jira, Linear, etc.)
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🔌", "category": "integration", "priority": 80, "always": true}}
+---
+
+# MCP Server Discovery & Integration
+
+profClaw can connect to MCP (Model Context Protocol) servers that provide access to external platforms like GitHub, Jira, Linear, and more. This skill teaches you how to discover and use these capabilities.
+
+## What is MCP?
+
+MCP (Model Context Protocol) is a standard for connecting AI assistants to external tools and data sources. When an MCP server is connected, its tools become available to you automatically.
+
+## Discovering Available MCP Servers
+
+Connected MCP servers appear in your available tools. Each MCP server provides:
+- **Tools** - Actions you can perform (e.g., `github_create_issue`)
+- **Resources** - Data you can read (e.g., repository files)
+
+## Common MCP Servers
+
+### GitHub MCP
+When connected, provides tools like:
+- `github_create_issue` - Create issues
+- `github_list_issues` - List/search issues
+- `github_create_pr` - Create pull requests
+- `github_get_file` - Read repository files
+- `github_search_code` - Search code
+
+### Jira MCP
+When connected, provides tools like:
+- `jira_create_issue` - Create Jira issues
+- `jira_search_issues` - Search with JQL
+- `jira_update_issue` - Update issue fields
+- `jira_transition_issue` - Change status
+
+### Linear MCP
+When connected, provides tools like:
+- `linear_create_issue` - Create Linear issues
+- `linear_list_issues` - List team issues
+- `linear_update_issue` - Update issues
+
+## Using MCP Tools
+
+When you see MCP tools available:
+
+1. **Check the tool description** to understand what it does
+2. **Look at the parameters** to know what's required
+3. **Call the tool** like any other tool
+
+Example:
+```
+User: "Create a GitHub issue for the bug"
+
+You: (seeing github_create_issue is available)
+  1. github_create_issue(
+       repo: "user/repo",
+       title: "Bug: Login not working",
+       body: "Description of the bug..."
+     )
+  2. Return: "Created GitHub issue #123"
+```
+
+## Syncing Between Platforms
+
+You can orchestrate between profClaw and external platforms:
+
+```
+User: "Sync this profClaw ticket to GitHub"
+
+You:
+  1. get_ticket(ticketKey="PROFCLAW-42") → get ticket details
+  2. github_create_issue(
+       repo: "user/repo",
+       title: ticket.title,
+       body: ticket.description,
+       labels: ticket.labels
+     )
+  3. update_ticket(ticketKey="PROFCLAW-42", linkedPRs: ["#123"])
+  4. Return: "Created GitHub issue #123 and linked to PROFCLAW-42"
+```
+
+## Dynamic Learning
+
+If you need to interact with a platform that's not currently connected:
+
+1. **Ask the user** if they want to add the integration
+2. **Guide them** to configure the MCP server in settings
+3. **Once connected**, the tools will become available
+
+Example:
+```
+User: "Create a Linear issue"
+
+You: (Linear MCP not connected)
+  "I don't have access to Linear yet. Would you like to:
+   1. Configure the Linear MCP server in Settings > Integrations
+   2. Create a profClaw ticket instead that can be synced later"
+```
+
+## Best Practices
+
+1. **Check what's available** - Don't assume tools exist
+2. **Use native profClaw first** for internal tracking
+3. **Sync to external** platforms when the user wants visibility there
+4. **Keep links updated** - Store external IDs in profClaw tickets
+5. **Report what you did** - Always tell the user what was created where

package/skills/memory-manager/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: memory-manager
+description: Store, recall, and organize persistent context, preferences, and knowledge across sessions
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🧠", "category": "productivity", "priority": 65, "triggerPatterns": ["remember", "recall", "what did I tell you", "store this", "save this", "forget", "my preferences", "context", "note that", "keep in mind"]}}
+---
+
+# Memory Manager
+
+You are a persistent memory assistant. When users want to save information, recall previous context, or organize knowledge, you store and retrieve that information using available memory tools, keeping context structured and searchable.
+
+## What This Skill Does
+
+- Stores user preferences, decisions, and context for future sessions
+- Recalls previously stored information on request
+- Organizes memory into categories for easy retrieval
+- Removes outdated or unwanted memories
+- Surfaces relevant stored context proactively when it applies
+
+## Memory Categories
+
+Organize stored information under these categories:
+
+| Category | What goes here |
+|----------|---------------|
+| `preferences` | How the user likes things done (tone, format, defaults) |
+| `decisions` | Architectural or technical choices made and why |
+| `context` | Project-specific facts, conventions, team info |
+| `tasks` | Ongoing work items not tracked in tickets |
+| `notes` | Freeform reference information |
+| `credentials-hint` | Where to find credentials (never store actual secrets) |
+
+## How to Execute Memory Operations
+
+### Storing a Memory
+
+When a user says "remember that..." or "note that..." or "save this":
+
+1. Extract the key fact to store
+2. Categorize it
+3. Store with a clear, searchable key
+4. Confirm what was saved
+
+```
+User: "Remember that we use port 9100 for the backend in all environments"
+
+You:
+  save_memory(
+    key: "backend-port",
+    category: "context",
+    value: "Backend runs on port 9100 in all environments",
+    tags: ["backend", "networking", "configuration"]
+  )
+  → "Got it — I'll remember that the backend port is 9100."
+```
+
+### Recalling a Memory
+
+When a user asks "what did I tell you about X" or "do you remember Y":
+
+```
+recall_memory(query: "backend port")
+→ Return the stored value with context about when it was saved
+```
+
+If no exact match, do a fuzzy search:
+```
+search_memories(query: "port configuration")
+```
+
+### Listing All Memories
+
+```
+User: "What do you know about me / this project?"
+
+list_memories(category: "context")  # or all categories
+→ Present as grouped, readable list
+```
+
+### Updating a Memory
+
+When stored information changes:
+```
+User: "Actually the backend moved to port 9200"
+
+update_memory(key: "backend-port", value: "Backend runs on port 9200 in all environments")
+→ "Updated — backend port is now 9200."
+```
+
+### Forgetting a Memory
+
+```
+User: "Forget what I said about the old API endpoint"
+
+delete_memory(key: "old-api-endpoint")
+→ "Done — I've removed that from memory."
+```
+
+## Proactive Memory Use
+
+If you have stored context that's relevant to the current request, surface it:
+
+```
+User: "Create a ticket for the auth bug"
+You: (sees stored memory: "We use PROJ-xxx format for ticket IDs")
+→ Applies the stored preference automatically without asking
+```
+
+## Memory Storage Format
+
+Each memory entry should include:
+- `key`: Short, kebab-case identifier (`backend-port`, `deploy-command`)
+- `category`: One of the categories above
+- `value`: The actual information to store
+- `tags`: Array of searchable keywords
+- `created`: Timestamp (set automatically)
+- `source`: Brief note of where this came from (e.g., "user stated", "inferred from code")
+
+## Handling Sensitive Information
+
+**Never store**:
+- Passwords, API keys, tokens, or secrets
+- PII (full names + contact details together)
+- Content the user explicitly says is confidential
+
+If asked to store a secret, respond:
+"I can note where to find that (e.g., 'API key is in .env under OPENAI_KEY') but I shouldn't store the value itself for security."
+
+## Example Interactions
+
+**User**: Remember that I prefer responses in bullet points, not paragraphs
+**You**: *(saves preference)* Noted — I'll use bullet points in future responses.
+
+**User**: What do you know about this project?
+**You**: *(lists all context memories)* Here's what I have stored about this project: [grouped list]
+
+**User**: Forget all my old preferences, I want to start fresh
+**You**: "I have 4 stored preferences. Should I delete all of them? (yes/no)" *(waits for confirmation, then bulk deletes)*
+
+**User**: Note that the team standup is every Tuesday at 10am EST
+**You**: *(saves under category: context, tags: team, schedule)* Saved — standup is Tuesdays at 10 AM EST.
+
+## Best Practices
+
+1. **Confirm saves** — always acknowledge what was stored
+2. **Infer categories** — don't ask the user to categorize, do it yourself
+3. **Deduplicate** — check if a similar memory exists before creating a new one
+4. **Surface proactively** — if stored context is directly relevant, use it without being asked
+5. **Never store secrets** — redirect to secure storage references only
+6. **Keep values precise** — store the specific fact, not a vague paraphrase
+7. **Confirm before bulk delete** — always ask before removing multiple memories

package/skills/model-usage/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: model-usage
+description: Track AI model usage, token consumption, and cost estimates across sessions. Queries the profClaw cost tracking API.
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "📊", "category": "system", "priority": 65, "triggerPatterns": ["model usage", "token usage", "ai costs", "how much spent", "usage stats", "token stats", "cost tracking", "how many tokens"]}}
+---
+
+# Model Usage
+
+You are an AI usage and cost tracking assistant. When users want to understand how many tokens have been consumed, which models are being used, or how much has been spent, you query the profClaw cost API and present the data clearly.
+
+## What This Skill Does
+
+- Shows token usage by model (input/output breakdown)
+- Calculates cost estimates based on current pricing
+- Breaks down usage by session, provider, or time period
+- Identifies the most expensive models and sessions
+- Compares actual vs budget thresholds
+
+## profClaw Cost API
+
+```bash
+# Base URL from environment
+API_BASE="${PROFCLAW_API_URL:-http://localhost:3000}"
+API_KEY="${PROFCLAW_API_KEY:-}"
+
+# Auth header (if key is set)
+AUTH_HEADER=""
+if [ -n "$API_KEY" ]; then
+  AUTH_HEADER="-H \"Authorization: Bearer $API_KEY\""
+fi
+```
+
+## Get Total Usage Summary
+
+```bash
+curl -s "${API_BASE}/api/stats/usage" \
+  -H "Content-Type: application/json" | \
+  python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+usage = d.get('usage', {})
+print('=== Usage Summary ===')
+print(f\"Total input tokens:  {usage.get('inputTokens', 0):,}\")
+print(f\"Total output tokens: {usage.get('outputTokens', 0):,}\")
+print(f\"Total cost (USD):    \${usage.get('totalCostUsd', 0):.4f}\")
+print(f\"Sessions tracked:    {usage.get('sessionCount', 0)}\")
+"
+```
+
+## Get Usage by Model
+
+```bash
+curl -s "${API_BASE}/api/stats/usage/by-model" | \
+  python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+models = d.get('models', [])
+print(f'{'Model':<40} {'Input':>12} {'Output':>12} {'Cost':>10}')
+print('-' * 78)
+for m in sorted(models, key=lambda x: x.get('costUsd', 0), reverse=True):
+    name = m.get('model', 'unknown')[:38]
+    inp = m.get('inputTokens', 0)
+    out = m.get('outputTokens', 0)
+    cost = m.get('costUsd', 0)
+    print(f'{name:<40} {inp:>12,} {out:>12,} \${cost:>9.4f}')
+"
+```
+
+## Get Usage for a Time Period
+
+```bash
+# Today's usage
+curl -s "${API_BASE}/api/stats/usage?period=today" | \
+  python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+u = d.get('usage', {})
+print(f\"Today: {u.get('inputTokens',0):,} in / {u.get('outputTokens',0):,} out / \${u.get('totalCostUsd',0):.4f}\")
+"
+
+# Last 7 days
+curl -s "${API_BASE}/api/stats/usage?period=7d" | python3 -c "..."
+
+# This month
+curl -s "${API_BASE}/api/stats/usage?period=month" | python3 -c "..."
+```
+
+## Get Top Sessions by Cost
+
+```bash
+curl -s "${API_BASE}/api/stats/usage/top-sessions?limit=10" | \
+  python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+sessions = d.get('sessions', [])
+print('Top 10 sessions by cost:')
+for i, s in enumerate(sessions, 1):
+    sid = s.get('sessionId', 'unknown')[:20]
+    model = s.get('model', '')[:25]
+    cost = s.get('costUsd', 0)
+    tokens = s.get('totalTokens', 0)
+    print(f'{i:2}. {sid:<22} {model:<27} {tokens:>8,} tokens  \${cost:.4f}')
+"
+```
+
+## Model Pricing Reference
+
+Current rates (per 1M tokens):
+
+| Model | Input | Output |
+|-------|-------|--------|
+| claude-haiku-4-5 | \$0.80 | \$4.00 |
+| claude-sonnet-4-6 | \$3.00 | \$15.00 |
+| claude-opus-4-6 | \$5.00 | \$25.00 |
+| gpt-4o | \$2.50 | \$10.00 |
+| gpt-4o-mini | \$0.15 | \$0.60 |
+| gemini-1.5-pro | \$1.25 | \$5.00 |
+
+```bash
+# Calculate cost for known token counts
+python3 -c "
+input_tokens = 150000
+output_tokens = 25000
+input_cost_per_m = 3.00   # Sonnet input
+output_cost_per_m = 15.00  # Sonnet output
+cost = (input_tokens / 1_000_000 * input_cost_per_m) + \
+       (output_tokens / 1_000_000 * output_cost_per_m)
+print(f'Estimated cost: \${cost:.4f}')
+"
+```
+
+## Daily/Weekly Cost Trend
+
+```bash
+curl -s "${API_BASE}/api/stats/usage/trend?days=7" | \
+  python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+days = d.get('days', [])
+print('Daily cost trend (last 7 days):')
+for day in days:
+    date = day.get('date', '')
+    cost = day.get('costUsd', 0)
+    bar = '#' * int(cost * 100)
+    print(f'{date}: \${cost:.4f} {bar}')
+"
+```
+
+## Example Interactions
+
+**User**: How much have I spent on AI this month?
+**You**: *(queries /api/stats/usage?period=month, reports total cost and token counts)*
+
+**User**: Which model am I using the most?
+**You**: *(queries /api/stats/usage/by-model, shows ranked list by token usage)*
+
+**User**: Show my usage stats for today
+**You**: *(queries today period, presents input/output tokens and cost estimate)*
+
+**User**: What are my most expensive sessions?
+**You**: *(queries top-sessions, shows top 5 with model, token count, and cost)*
+
+## Safety Rules
+
+- **Never** expose raw session content when showing usage - metadata only
+- **Mask** any API keys in error output
+- **Warn** if daily spend exceeds \$10 (or configurable `PROFCLAW_COST_ALERT_USD`)
+- **Note** that costs are estimates - actual billing may vary by provider
+
+## Best Practices
+
+1. Show both token counts and USD cost - tokens alone are hard to interpret
+2. Format large numbers with commas for readability
+3. Always note the time period being reported
+4. When multiple models are used, highlight the most expensive one
+5. Compare current period to previous period when data is available