oh-my-claudecode-opencode 0.2.1 → 0.3.0

package/assets/skills/help.md

@@ -0,0 +1,66 @@
+---
+name: help
+description: Guide on using oh-my-claudecode plugin
+user-invocable: true
+---
+
+# How OMC Works
+
+**You don't need to learn any commands!** OMC enhances Claude Code with intelligent behaviors that activate automatically.
+
+## What Happens Automatically
+
+| When You... | I Automatically... |
+|-------------|-------------------|
+| Give me a complex task | Parallelize and delegate to specialist agents |
+| Ask me to plan something | Start a planning interview |
+| Need something done completely | Persist until verified complete |
+| Work on UI/frontend | Activate design sensibility |
+| Say "stop" or "cancel" | Intelligently stop current operation |
+
+## Magic Keywords (Optional Shortcuts)
+
+You can include these words naturally in your request for explicit control:
+
+| Keyword | Effect | Example |
+|---------|--------|---------|
+| **ralph** | Persistence mode | "ralph: fix all the bugs" |
+| **ralplan** | Iterative planning | "ralplan this feature" |
+| **ulw** | Max parallelism | "ulw refactor the API" |
+| **plan** | Planning interview | "plan the new endpoints" |
+
+**Combine them:** "ralph ulw: migrate the database"
+
+## Stopping Things
+
+Just say:
+- "stop"
+- "cancel"
+- "abort"
+
+I'll figure out what to stop based on context.
+
+## First Time Setup
+
+If you haven't configured OMC yet:
+
+```
+/oh-my-claudecode:omc-setup
+```
+
+This is the **only command** you need to know. It downloads the configuration and you're done.
+
+## For 2.x Users
+
+Your old commands still work! `/ralph`, `/ultrawork`, `/planner`, etc. all function exactly as before.
+
+But now you don't NEED them - everything is automatic.
+
+## Need More Help?
+
+- **README**: https://github.com/Yeachan-Heo/oh-my-claudecode
+- **Issues**: https://github.com/Yeachan-Heo/oh-my-claudecode/issues
+
+---
+
+*Version: 3.0.11*

package/assets/skills/hud.md

@@ -0,0 +1,239 @@
+---
+name: hud
+description: Configure HUD display options (layout, presets, display elements)
+user-invocable: true
+role: config-writer  # DOCUMENTATION ONLY - This skill writes to ~/.claude/ paths
+scope: ~/.claude/**  # DOCUMENTATION ONLY - Allowed write scope
+---
+
+# HUD Skill
+
+Configure the OMC HUD (Heads-Up Display) for the statusline.
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `/oh-my-claudecode:hud` | Show current HUD status (auto-setup if needed) |
+| `/oh-my-claudecode:hud setup` | Install/repair HUD statusline |
+| `/oh-my-claudecode:hud minimal` | Switch to minimal display |
+| `/oh-my-claudecode:hud focused` | Switch to focused display (default) |
+| `/oh-my-claudecode:hud full` | Switch to full display |
+| `/oh-my-claudecode:hud status` | Show detailed HUD status |
+
+## Auto-Setup
+
+When you run `/oh-my-claudecode:hud` or `/oh-my-claudecode:hud setup`, the system will automatically:
+1. Check if `~/.claude/hud/omc-hud.mjs` exists
+2. Check if `statusLine` is configured in `~/.claude/settings.json`
+3. If missing, create the HUD wrapper script and configure settings
+4. Report status and prompt to restart Claude Code if changes were made
+
+**IMPORTANT**: If the argument is `setup` OR if the HUD script doesn't exist at `~/.claude/hud/omc-hud.mjs`, you MUST create the HUD files directly using the instructions below.
+
+### Setup Instructions (Run These Commands)
+
+**Step 1:** Check if setup is needed:
+```bash
+ls ~/.claude/hud/omc-hud.mjs 2>/dev/null && echo "EXISTS" || echo "MISSING"
+```
+
+**Step 2:** Check if the plugin is built (CRITICAL - common issue!):
+```bash
+# Find the latest version and check if dist/hud/index.js exists
+PLUGIN_VERSION=$(ls ~/.claude/plugins/cache/omc/oh-my-claudecode/ 2>/dev/null | sort -V | tail -1)
+if [ -n "$PLUGIN_VERSION" ]; then
+  ls ~/.claude/plugins/cache/omc/oh-my-claudecode/$PLUGIN_VERSION/dist/hud/index.js 2>/dev/null && echo "BUILT" || echo "NOT_BUILT"
+fi
+```
+
+**If NOT_BUILT**, the plugin needs to be compiled. Run:
+```bash
+cd ~/.claude/plugins/cache/omc/oh-my-claudecode/$PLUGIN_VERSION && npm install
+```
+This will install dependencies and build the TypeScript code automatically (via the `prepare` script).
+
+**Step 3:** If omc-hud.mjs is MISSING or argument is `setup`, create the HUD directory and script:
+
+First, create the directory:
+```bash
+mkdir -p ~/.claude/hud
+```
+
+Then, use the Write tool to create `~/.claude/hud/omc-hud.mjs` with this exact content:
+
+```javascript
+#!/usr/bin/env node
+/**
+ * OMC HUD - Statusline Script
+ * Wrapper that imports from plugin cache or development paths
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+async function main() {
+  const home = homedir();
+
+  // 1. Try plugin cache first (marketplace: omc, plugin: oh-my-claudecode)
+  const pluginCacheBase = join(home, ".claude/plugins/cache/omc/oh-my-claudecode");
+  if (existsSync(pluginCacheBase)) {
+    try {
+      const versions = readdirSync(pluginCacheBase);
+      if (versions.length > 0) {
+        const latestVersion = versions.sort().reverse()[0];
+        const pluginPath = join(pluginCacheBase, latestVersion, "dist/hud/index.js");
+        if (existsSync(pluginPath)) {
+          await import(pluginPath);
+          return;
+        }
+      }
+    } catch { /* continue */ }
+  }
+
+  // 2. Development paths
+  const devPaths = [
+    join(home, "Workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
+    join(home, "workspace/oh-my-claude-sisyphus/dist/hud/index.js"),
+    join(home, "Workspace/oh-my-claudecode/dist/hud/index.js"),
+    join(home, "workspace/oh-my-claudecode/dist/hud/index.js"),
+  ];
+
+  for (const devPath of devPaths) {
+    if (existsSync(devPath)) {
+      try {
+        await import(devPath);
+        return;
+      } catch { /* continue */ }
+    }
+  }
+
+  // 3. Fallback
+  console.log("[OMC] run /omc-setup to install properly");
+}
+
+main();
+```
+
+**Step 3:** Make it executable:
+```bash
+chmod +x ~/.claude/hud/omc-hud.mjs
+```
+
+**Step 4:** Update settings.json to use the HUD:
+
+Read `~/.claude/settings.json`, then update/add the `statusLine` field:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/hud/omc-hud.mjs"
+  }
+}
+```
+
+Use the Edit tool to add/update this field while preserving other settings.
+
+**Step 5:** Clean up old HUD scripts (if any):
+```bash
+rm -f ~/.claude/hud/sisyphus-hud.mjs 2>/dev/null
+```
+
+**Step 6:** Tell the user to restart Claude Code for changes to take effect.
+
+## Display Presets
+
+### Minimal
+Shows only the essentials:
+```
+[OMC] ralph | ultrawork | todos:2/5
+```
+
+### Focused (Default)
+Shows all relevant elements:
+```
+[OMC] ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | bg:3/5 | todos:2/5
+```
+
+### Full
+Shows everything including multi-line agent details:
+```
+[OMC] ralph:3/10 | US-002 (2/5) | ultrawork | ctx:[████░░]67% | agents:3 | bg:3/5 | todos:2/5
+├─ O architect    2m   analyzing architecture patterns...
+├─ e explore     45s   searching for test files
+└─ s executor     1m   implementing validation logic
+```
+
+## Multi-Line Agent Display
+
+When agents are running, the HUD shows detailed information on separate lines:
+- **Tree characters** (`├─`, `└─`) show visual hierarchy
+- **Agent code** (O, e, s) indicates agent type with model tier color
+- **Duration** shows how long each agent has been running
+- **Description** shows what each agent is doing (up to 45 chars)
+
+## Display Elements
+
+| Element | Description |
+|---------|-------------|
+| `[OMC]` | Mode identifier |
+| `ralph:3/10` | Ralph loop iteration/max |
+| `US-002` | Current PRD story ID |
+| `ultrawork` | Active mode badge |
+| `skill:name` | Last activated skill (cyan) |
+| `ctx:67%` | Context window usage |
+| `agents:2` | Running subagent count |
+| `bg:3/5` | Background task slots |
+| `todos:2/5` | Todo completion |
+
+## Color Coding
+
+- **Green**: Normal/healthy
+- **Yellow**: Warning (context >70%, ralph >7)
+- **Red**: Critical (context >85%, ralph at max)
+
+## Configuration Location
+
+HUD config is stored at: `~/.claude/.omc/hud-config.json`
+
+## Manual Configuration
+
+You can manually edit the config file:
+
+```json
+{
+  "preset": "focused",
+  "elements": {
+    "omcLabel": true,
+    "ralph": true,
+    "prdStory": true,
+    "activeSkills": true,
+    "lastSkill": true,
+    "contextBar": true,
+    "agents": true,
+    "backgroundTasks": true,
+    "todos": true
+  },
+  "thresholds": {
+    "contextWarning": 70,
+    "contextCritical": 85,
+    "ralphWarning": 7
+  }
+}
+```
+
+## Troubleshooting
+
+If the HUD is not showing:
+1. Run `/oh-my-claudecode:hud setup` to auto-install and configure
+2. Restart Claude Code after setup completes
+3. If still not working, run `/oh-my-claudecode:doctor` for full diagnostics
+
+Manual verification:
+- HUD script: `~/.claude/hud/omc-hud.mjs`
+- Settings: `~/.claude/settings.json` should have `statusLine` configured
+
+---
+
+*The HUD updates automatically every ~300ms during active sessions.*

package/assets/skills/learner.md

@@ -0,0 +1,136 @@
+---
+name: learner
+description: Extract a learned skill from the current conversation
+user-invocable: true
+---
+
+# Learner Skill
+
+## The Insight
+
+Reusable skills are not code snippets to copy-paste, but **principles and decision-making heuristics** that teach Claude HOW TO THINK about a class of problems.
+
+**The difference:**
+- BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
+- GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."
+
+A good skill changes how Claude APPROACHES problems, not just what code it produces.
+
+## Why This Matters
+
+Before extracting a skill, ask yourself:
+- "Could someone Google this in 5 minutes?" → If yes, STOP. Don't extract.
+- "Is this specific to THIS codebase?" → If no, STOP. Don't extract.
+- "Did this take real debugging effort to discover?" → If no, STOP. Don't extract.
+
+If a potential skill fails any of these questions, it's not worth saving.
+
+## Recognition Pattern
+
+Use /oh-my-claudecode:learner ONLY after:
+- Solving a tricky bug that required deep investigation
+- Discovering a non-obvious workaround specific to this codebase
+- Finding a hidden gotcha that wastes time when forgotten
+- Uncovering undocumented behavior that affects this project
+
+## The Approach
+
+### Extraction Process
+
+**Step 1: Gather Required Information**
+
+- **Problem Statement**: The SPECIFIC error, symptom, or confusion that occurred
+  - Include actual error messages, file paths, line numbers
+  - Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
+
+- **Solution**: The EXACT fix, not general advice
+  - Include code snippets, file paths, configuration changes
+  - Example: "Add null check before accessing session.user, regenerate session on 401"
+
+- **Triggers**: Keywords that would appear when hitting this problem again
+  - Use error message fragments, file names, symptom descriptions
+  - Example: ["sessionId undefined", "session.ts TypeError", "401 session"]
+
+- **Scope**: Almost always Project-level unless it's a truly universal insight
+
+**Step 2: Quality Validation**
+
+The system REJECTS skills that are:
+- Too generic (no file paths, line numbers, or specific error messages)
+- Easily Googleable (standard patterns, library usage)
+- Vague solutions (no code snippets or precise instructions)
+- Poor triggers (generic words that match everything)
+
+**Step 3: Save Location**
+
+- **User-level**: ~/.claude/skills/omc-learned/ - Rare. Only for truly portable insights.
+- **Project-level**: .omc/skills/ - Default. Version-controlled with repo.
+
+### What Makes a USEFUL Skill
+
+**CRITICAL**: Not every solution is worth saving. A good skill is:
+
+1. **Non-Googleable**: Something you couldn't easily find via search
+   - BAD: "How to read files in TypeScript" ❌
+   - GOOD: "This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓
+
+2. **Context-Specific**: References actual files, error messages, or patterns from THIS codebase
+   - BAD: "Use try/catch for error handling" ❌
+   - GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError - wrap StreamResponse in try/except" ✓
+
+3. **Actionable with Precision**: Tells you exactly WHAT to do and WHERE
+   - BAD: "Handle edge cases" ❌
+   - GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field" ✓
+
+4. **Hard-Won**: Took significant debugging effort to discover
+   - BAD: Generic programming patterns ❌
+   - GOOD: "Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns" ✓
+
+### Anti-Patterns (DO NOT EXTRACT)
+
+- Generic programming patterns (use documentation instead)
+- Refactoring techniques (these are universal)
+- Library usage examples (use library docs)
+- Type definitions or boilerplate
+- Anything a junior dev could Google in 5 minutes
+
+## Skill Format
+
+Skills are saved as markdown with this structure:
+
+### YAML Frontmatter
+
+Standard metadata fields:
+- id, name, description, source, triggers, quality
+
+### Body Structure (Required)
+
+```markdown
+# [Skill Name]
+
+## The Insight
+What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.
+Example: "Async I/O operations are independently failable. Client lifecycle != server lifecycle."
+
+## Why This Matters
+What goes wrong if you don't know this? What symptom led you here?
+Example: "Proxy server crashes on client disconnect, taking down other requests."
+
+## Recognition Pattern
+How do you know when this skill applies? What are the signs?
+Example: "Building any long-lived connection handler (proxy, websocket, SSE)"
+
+## The Approach
+The decision-making heuristic, not just code. How should Claude THINK about this?
+Example: "For each I/O operation, ask: what if this fails right now? Handle it locally."
+
+## Example (Optional)
+If code helps, show it - but as illustration of the principle, not copy-paste material.
+```
+
+**Key**: A skill is REUSABLE if Claude can apply it to NEW situations, not just identical ones.
+
+## Related Commands
+
+- /oh-my-claudecode:note - Save quick notes that survive compaction (less formal than skills)
+- /oh-my-claudecode:ralph - Start a development loop with learning capture

package/assets/skills/mcp-setup.md

@@ -0,0 +1,196 @@
+---
+name: mcp-setup
+description: Configure popular MCP servers for enhanced agent capabilities
+user-invocable: true
+---
+
+# MCP Setup
+
+Configure Model Context Protocol (MCP) servers to extend Claude Code's capabilities with external tools like web search, file system access, and GitHub integration.
+
+## Overview
+
+MCP servers provide additional tools that Claude Code agents can use. This skill helps you configure popular MCP servers in your `~/.claude/settings.json`.
+
+## Step 1: Show Available MCP Servers
+
+Present the user with available MCP server options using AskUserQuestion:
+
+**Question:** "Which MCP server would you like to configure?"
+
+**Options:**
+1. **Context7** - Documentation and code context from popular libraries
+2. **Exa Web Search** - Enhanced web search (replaces built-in websearch)
+3. **Filesystem** - Extended file system access with additional capabilities
+4. **GitHub** - GitHub API integration for issues, PRs, and repository management
+5. **All of the above** - Configure all recommended MCP servers
+6. **Custom** - Add a custom MCP server
+
+## Step 2: Gather Required Information
+
+### For Context7:
+No API key required. Ready to use immediately.
+
+### For Exa Web Search:
+Ask for API key:
+```
+Do you have an Exa API key?
+- Get one at: https://exa.ai
+- Enter your API key, or type 'skip' to configure later
+```
+
+### For Filesystem:
+Ask for allowed directories:
+```
+Which directories should the filesystem MCP have access to?
+Default: Current working directory
+Enter comma-separated paths, or press Enter for default
+```
+
+### For GitHub:
+Ask for token:
+```
+Do you have a GitHub Personal Access Token?
+- Create one at: https://github.com/settings/tokens
+- Recommended scopes: repo, read:org
+- Enter your token, or type 'skip' to configure later
+```
+
+## Step 3: Update settings.json
+
+Read the current `~/.claude/settings.json` and add/update the `mcpServers` section.
+
+### Context7 Configuration:
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@context7/mcp"]
+    }
+  }
+}
+```
+
+### Exa Web Search Configuration:
+```json
+{
+  "mcpServers": {
+    "exa": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/exa-mcp-server"],
+      "env": {
+        "EXA_API_KEY": "<user-provided-key>"
+      }
+    }
+  }
+}
+```
+
+### Filesystem Configuration:
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-filesystem", "<allowed-directories>"]
+    }
+  }
+}
+```
+
+### GitHub Configuration:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/github-mcp-server"],
+      "env": {
+        "GITHUB_TOKEN": "<user-provided-token>"
+      }
+    }
+  }
+}
+```
+
+## Step 4: Merge Configuration
+
+When updating settings.json:
+
+1. Read existing file: `~/.claude/settings.json`
+2. Parse as JSON (handle comments with jsonc-parser if needed)
+3. Merge new `mcpServers` entries with existing ones (don't overwrite user's other MCP servers)
+4. Write back to file with proper formatting
+
+```bash
+# Backup existing settings first
+cp ~/.claude/settings.json ~/.claude/settings.json.bak 2>/dev/null || true
+```
+
+Use the Edit tool or Write tool to update the settings file, preserving existing configuration.
+
+## Step 5: Verify Installation
+
+After configuration, verify the MCP servers are properly set up:
+
+```bash
+# Check if settings.json has mcpServers
+grep -q "mcpServers" ~/.claude/settings.json && echo "MCP servers configured" || echo "Configuration may have failed"
+
+# List configured servers
+node -e "const s = require('$HOME/.claude/settings.json'); console.log('Configured MCP servers:', Object.keys(s.mcpServers || {}).join(', ') || 'none')"
+```
+
+## Step 6: Show Completion Message
+
+```
+MCP Server Configuration Complete!
+
+CONFIGURED SERVERS:
+[List the servers that were configured]
+
+NEXT STEPS:
+1. Restart Claude Code for changes to take effect
+2. The configured MCP tools will be available to all agents
+
+USAGE TIPS:
+- Context7: Ask about library documentation (e.g., "How do I use React hooks?")
+- Exa: Use for web searches (e.g., "Search the web for latest TypeScript features")
+- Filesystem: Extended file operations beyond the working directory
+- GitHub: Interact with GitHub repos, issues, and PRs
+
+TROUBLESHOOTING:
+- If MCP servers don't appear, check ~/.claude/settings.json for syntax errors
+- Ensure you have Node.js 18+ installed for npx commands
+- Run /oh-my-claudecode:doctor to diagnose issues
+
+To add more MCP servers later, run: /oh-my-claudecode:mcp-setup
+```
+
+## Custom MCP Server
+
+If user selects "Custom":
+
+Ask for:
+1. Server name (identifier)
+2. Command to run (e.g., `npx`, `node`, path to executable)
+3. Arguments (comma-separated)
+4. Environment variables (optional, key=value pairs)
+
+Then add to mcpServers section accordingly.
+
+## Common Issues
+
+### MCP Server Not Loading
+- Ensure Node.js 18+ is installed
+- Check that npx is available in PATH
+- Verify no JSON syntax errors in settings.json
+
+### API Key Issues
+- Exa: Verify key at https://dashboard.exa.ai
+- GitHub: Ensure token has required scopes
+
+### Agents Still Using Built-in Tools
+- Restart Claude Code after configuration
+- The built-in websearch will be deprioritized when exa is configured

package/assets/skills/note.md

@@ -0,0 +1,63 @@
+---
+name: note
+description: Save notes to notepad.md for compaction resilience
+user-invocable: true
+---
+
+# Note Skill
+
+Save important context to `.omc/notepad.md` that survives conversation compaction.
+
+## Usage
+
+| Command | Action |
+|---------|--------|
+| `/oh-my-claudecode:note <content>` | Add to Working Memory with timestamp |
+| `/oh-my-claudecode:note --priority <content>` | Add to Priority Context (always loaded) |
+| `/oh-my-claudecode:note --manual <content>` | Add to MANUAL section (never pruned) |
+| `/oh-my-claudecode:note --show` | Display current notepad contents |
+| `/oh-my-claudecode:note --prune` | Remove entries older than 7 days |
+| `/oh-my-claudecode:note --clear` | Clear Working Memory (keep Priority + MANUAL) |
+
+## Sections
+
+### Priority Context (500 char limit)
+- **Always** injected on session start
+- Use for critical facts: "Project uses pnpm", "API in src/api/client.ts"
+- Keep it SHORT - this eats into your context budget
+
+### Working Memory
+- Timestamped session notes
+- Auto-pruned after 7 days
+- Good for: debugging breadcrumbs, temporary findings
+
+### MANUAL
+- Never auto-pruned
+- User-controlled permanent notes
+- Good for: team contacts, deployment info
+
+## Examples
+
+```
+/oh-my-claudecode:note Found auth bug in UserContext - missing useEffect dependency
+/oh-my-claudecode:note --priority Project uses TypeScript strict mode, all files in src/
+/oh-my-claudecode:note --manual Contact: api-team@company.com for backend questions
+/oh-my-claudecode:note --show
+/oh-my-claudecode:note --prune
+```
+
+## Behavior
+
+1. Creates `.omc/notepad.md` if it doesn't exist
+2. Parses the argument to determine section
+3. Appends content with timestamp (for Working Memory)
+4. Warns if Priority Context exceeds 500 chars
+5. Confirms what was saved
+
+## Integration
+
+Notepad content is automatically loaded on session start:
+- Priority Context: ALWAYS loaded
+- Working Memory: Loaded if recent entries exist
+
+This helps survive conversation compaction without losing critical context.