oh-my-claude-sisyphus 3.0.9 → 3.0.10

package/commands/omc-setup.md

@@ -0,0 +1,132 @@
+---
+description: One-time setup for oh-my-claudecode (the ONLY command you need to learn)
+---
+
+# OMC Setup
+
+This is the **only command you need to learn**. After running this, everything else is automatic.
+
+## Step 1: Ask User Preference
+
+Use the AskUserQuestion tool to prompt the user:
+
+**Question:** "Where should I configure oh-my-claudecode?"
+
+**Options:**
+1. **Local (this project)** - Creates `.claude/CLAUDE.md` in current project directory. Best for project-specific configurations.
+2. **Global (all projects)** - Creates `~/.claude/CLAUDE.md` for all Claude Code sessions. Best for consistent behavior everywhere.
+
+## Step 2: Execute Based on Choice
+
+### If User Chooses LOCAL:
+
+```bash
+# Create .claude directory in current project
+mkdir -p .claude
+
+# Download fresh CLAUDE.md from GitHub
+curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o .claude/CLAUDE.md && \
+echo "Downloaded CLAUDE.md to .claude/CLAUDE.md"
+```
+
+### If User Chooses GLOBAL:
+
+```bash
+# Download fresh CLAUDE.md to global config
+curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o ~/.claude/CLAUDE.md && \
+echo "Downloaded CLAUDE.md to ~/.claude/CLAUDE.md"
+```
+
+## Step 3: Setup HUD Statusline
+
+The HUD shows real-time status in Claude Code's status bar. **Invoke the hud skill** to set up and configure:
+
+Use the Skill tool to invoke: `hud` with args: `setup`
+
+This will:
+1. Install the HUD wrapper script to `~/.claude/hud/omc-hud.mjs`
+2. Configure `statusLine` in `~/.claude/settings.json`
+3. Report status and prompt to restart if needed
+
+## Step 4: Verify Plugin Installation
+
+```bash
+grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"
+```
+
+## Step 5: Detect Upgrade from 2.x
+
+Check if user has existing configuration:
+```bash
+# Check for existing 2.x artifacts
+ls ~/.claude/commands/ralph-loop.md 2>/dev/null || ls ~/.claude/commands/ultrawork.md 2>/dev/null
+```
+
+If found, this is an upgrade from 2.x.
+
+## Step 6: Show Welcome Message
+
+### For New Users:
+
+```
+OMC Setup Complete!
+
+You don't need to learn any commands. I now have intelligent behaviors that activate automatically.
+
+WHAT HAPPENS AUTOMATICALLY:
+- Complex tasks -> I parallelize and delegate to specialists
+- "plan this" -> I start a planning interview
+- "don't stop until done" -> I persist until verified complete
+- "stop" or "cancel" -> I intelligently stop current operation
+
+MAGIC KEYWORDS (optional power-user shortcuts):
+Just include these words naturally in your request:
+
+| Keyword | Effect | Example |
+|---------|--------|---------|
+| ralph | Persistence mode | "ralph: fix the auth bug" |
+| 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"
+
+HUD STATUSLINE:
+The status bar now shows OMC state. Restart Claude Code to see it.
+
+That's it! Just use Claude Code normally.
+```
+
+### For Users Upgrading from 2.x:
+
+```
+OMC Setup Complete! (Upgraded from 2.x)
+
+GOOD NEWS: Your existing commands still work!
+- /ralph, /ultrawork, /planner, etc. all still function
+
+WHAT'S NEW in 3.0:
+You no longer NEED those commands. Everything is automatic now:
+- Just say "don't stop until done" instead of /ralph
+- Just say "fast" or "parallel" instead of /ultrawork
+- Just say "plan this" instead of /planner
+- Just say "stop" instead of /cancel-ralph
+
+MAGIC KEYWORDS (power-user shortcuts):
+| Keyword | Same as old... | Example |
+|---------|----------------|---------|
+| ralph | /ralph | "ralph: fix the bug" |
+| ralplan | /ralplan | "ralplan this feature" |
+| ulw | /ultrawork | "ulw refactor API" |
+| plan | /planner | "plan the endpoints" |
+
+HUD STATUSLINE:
+The status bar now shows OMC state. Restart Claude Code to see it.
+
+Your workflow won't break - it just got easier!
+```
+
+## Fallback
+
+If curl fails, tell user to manually download from:
+https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md

package/commands/plan.md

@@ -1,3 +1,35 @@
 ---
 description: Start a planning session with Planner
 ---
+
+# Plan Skill
+
+[PLANNING MODE ACTIVATED]
+
+## Planning Session with Planner
+
+You are now in planning mode with Planner, the strategic planning consultant.
+
+### Current Phase: Interview Mode
+
+I will ask clarifying questions to fully understand your requirements before creating a plan.
+
+### What Happens Next
+1. **Interview** - I'll ask questions about your goals, constraints, and preferences
+2. **Analysis** - Analyst will analyze for hidden requirements and risks
+3. **Planning** - I'll create a comprehensive work plan
+4. **Review** (optional) - Critic can review the plan for quality
+
+### Transition Commands
+Say one of these when you're ready to generate the plan:
+- "Make it into a work plan!"
+- "Create the plan"
+- "I'm ready to plan"
+
+### Plan Storage
+- Drafts are saved to `.omc/drafts/`
+- Final plans are saved to `.omc/plans/`
+
+---
+
+Let's begin. Tell me more about what you want to accomplish, and I'll ask clarifying questions.

package/commands/ralph-init.md

@@ -0,0 +1,59 @@
+---
+description: Initialize a PRD (Product Requirements Document) for structured ralph-loop execution
+---
+
+# Ralph Init Skill
+
+[RALPH-INIT - PRD CREATION MODE]
+
+## What is PRD?
+
+A PRD (Product Requirements Document) structures your task into discrete user stories for ralph-loop.
+
+## Your Task
+
+Create `.omc/prd.json` and `.omc/progress.txt` based on the task description.
+
+### prd.json Structure
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Short title]",
+      "description": "As a [user], I want to [action] so that [benefit].",
+      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
+      "priority": 1,
+      "passes": false
+    }
+  ]
+}
+```
+
+### progress.txt Structure
+
+```
+# Ralph Progress Log
+Started: [ISO timestamp]
+
+## Codebase Patterns
+(No patterns discovered yet)
+
+---
+```
+
+### Guidelines
+
+1. **Right-sized stories**: Each completable in one focused session
+2. **Verifiable criteria**: Include "Typecheck passes", "Tests pass"
+3. **Independent stories**: Minimize dependencies between stories
+4. **Priority order**: Foundational work (DB, types) before UI
+
+After creating files, report summary and suggest running `/ralph-loop` to start.
+
+Task to break down:
+{{ARGUMENTS}}

package/commands/ralph.md

@@ -1,3 +1,99 @@
 ---
 description: Self-referential loop until task completion with architect verification
 ---
+
+# Ralph Skill
+
+[RALPH + ULTRAWORK - ITERATION {{ITERATION}}/{{MAX}}]
+
+Your previous attempt did not output the completion promise. Continue working on the task.
+
+## ULTRAWORK MODE (AUTO-ACTIVATED)
+
+Ralph automatically activates Ultrawork for maximum parallel execution. You MUST follow these rules:
+
+### Parallel Execution Rules
+- **PARALLEL**: Fire independent calls simultaneously - NEVER wait sequentially
+- **BACKGROUND FIRST**: Use Task(run_in_background=true) for long operations (10+ concurrent)
+- **DELEGATE**: Route tasks to specialist agents immediately
+
+### Smart Model Routing (SAVE TOKENS)
+
+| Task Complexity | Tier | Examples |
+|-----------------|------|----------|
+| Simple lookups | LOW (haiku) | "What does this function return?", "Find where X is defined" |
+| Standard work | MEDIUM (sonnet) | "Add error handling", "Implement this feature" |
+| Complex analysis | HIGH (opus) | "Debug this race condition", "Refactor auth module" |
+
+### Available Agents by Tier
+
+| Domain | LOW (Haiku) | MEDIUM (Sonnet) | HIGH (Opus) |
+|--------|-------------|-----------------|-------------|
+| **Analysis** | `architect-low` | `architect-medium` | `architect` |
+| **Execution** | `executor-low` | `executor` | `executor-high` |
+| **Search** | `explore` | `explore-medium` | - |
+| **Research** | `researcher-low` | `researcher` | - |
+| **Frontend** | `designer-low` | `designer` | `designer-high` |
+| **Docs** | `writer` | - | - |
+
+**CRITICAL: Always pass `model` parameter explicitly!**
+```
+Task(subagent_type="oh-my-claudecode:architect-low", model="haiku", prompt="...")
+Task(subagent_type="oh-my-claudecode:executor", model="sonnet", prompt="...")
+Task(subagent_type="oh-my-claudecode:architect", model="opus", prompt="...")
+```
+
+### Background Execution Rules
+
+**Run in Background** (set `run_in_background: true`):
+- Package installation: npm install, pip install, cargo build
+- Build processes: npm run build, make, tsc
+- Test suites: npm test, pytest, cargo test
+- Docker operations: docker build, docker pull
+
+**Run Blocking** (foreground):
+- Quick status checks: git status, ls, pwd
+- File reads, edits
+- Simple commands
+
+## COMPLETION REQUIREMENTS
+
+Before claiming completion, you MUST:
+1. Verify ALL requirements from the original task are met
+2. Ensure no partial implementations
+3. Check that code compiles/runs without errors
+4. Verify tests pass (if applicable)
+5. TODO LIST: Zero pending/in_progress tasks
+
+## ARCHITECT VERIFICATION (MANDATORY)
+
+When you believe the task is complete:
+1. **First**, spawn Architect to verify your work (ALWAYS pass model explicitly!):
+   ```
+   Task(subagent_type="oh-my-claudecode:architect", model="opus", prompt="Verify this implementation is complete: [describe what you did]")
+   ```
+
+2. **Wait for Architect's assessment**
+
+3. **If Architect approves**: Output `<promise>{{PROMISE}}</promise>`
+4. **If Architect finds issues**: Fix them, then repeat verification
+
+DO NOT output the completion promise without Architect verification.
+
+## ZERO TOLERANCE
+
+- NO Scope Reduction - deliver FULL implementation
+- NO Partial Completion - finish 100%
+- NO Premature Stopping - ALL TODOs must be complete
+- NO TEST DELETION - fix code, not tests
+
+## INSTRUCTIONS
+
+- Review your progress so far
+- Continue from where you left off
+- Use parallel execution and background tasks
+- When FULLY complete AND Architect verified, output: <promise>{{PROMISE}}</promise>
+- Do not stop until the task is truly done
+
+Original task:
+{{PROMPT}}

package/commands/ralplan.md

@@ -1,3 +1,217 @@
 ---
 description: Iterative planning with Planner, Architect, and Critic until consensus
 ---
+
+# Ralplan Skill
+
+## Overview
+
+Ralplan orchestrates three specialized agents—Planner, Architect, and Critic—in an iterative loop until consensus is reached on a comprehensive work plan. This skill ensures plans are strategically sound, architecturally valid, and thoroughly reviewed before execution.
+
+## The Planning Triad
+
+Three agents collaborate in structured phases to validate and refine work plans:
+
+| Agent | Role | Output |
+|-------|------|--------|
+| **Planner** | Strategic Planner | Creates/refines the work plan |
+| **Architect** | Strategic Advisor | Answers questions, validates architecture |
+| **Critic** | Ruthless Reviewer | Critiques and identifies gaps |
+
+## The Iteration Loop
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       RALPLAN LOOP                              │
+│                                                                 │
+│    ┌──────────────┐                                             │
+│    │   PLANNER    │◄────────────────────────────────┐           │
+│    │   (Plans)    │                                 │           │
+│    └──────┬───────┘                                 │           │
+│           │                                         │           │
+│           ▼                                         │           │
+│    ┌──────────────┐     Questions?    ┌───────────┐ │           │
+│    │   Has open   │─────────────────► │ ARCHITECT │ │           │
+│    │  questions?  │                   │ (Advises) │ │           │
+│    └──────┬───────┘                   └─────┬─────┘ │           │
+│           │                                 │       │           │
+│           │ No questions                    │       │           │
+│           ▼                                 ▼       │           │
+│    ┌──────────────┐                  ┌──────────┐   │           │
+│    │    CRITIC    │◄─────────────────│ Answers  │   │           │
+│    │  (Reviews)   │                  └──────────┘   │           │
+│    └──────┬───────┘                                 │           │
+│           │                                         │           │
+│           ▼                                         │           │
+│    ┌──────────────┐     REJECT      ┌──────────────┐│           │
+│    │   Verdict?   │─────────────────►│  Feedback   ││           │
+│    └──────┬───────┘                  │ to Planner  │┘           │
+│           │                          └─────────────┘            │
+│           │ OKAY                                                │
+│           ▼                                                     │
+│    ┌──────────────────────────────────────────────────────────┐ │
+│    │                  PLAN APPROVED                           │ │
+│    │           Ready for /ralph execution                     │ │
+│    └──────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## State Management
+
+Ralplan maintains persistent state in `.omc/ralplan-state.json` to track progress and enable recovery across interruptions:
+
+```json
+{
+  "active": true,
+  "mode": "ralplan",
+  "iteration": 1,
+  "max_iterations": 5,
+  "plan_path": ".omc/plans/[feature].md",
+  "current_phase": "planner_planning",
+  "started_at": "ISO-timestamp",
+  "task_description": "[original task]"
+}
+```
+
+**Phases**: `planner_planning` → `architect_consultation` → `critic_review` → `handling_verdict` → `complete`
+
+## Execution Protocol
+
+### Initialization
+
+The skill begins by establishing the planning environment:
+
+1. Create `.omc/plans/` directory if it doesn't exist
+2. Read task description from user input
+3. Create `ralplan-state.json` with initial values:
+   - `active: true`
+   - `iteration: 0`
+   - `max_iterations: 5`
+   - `current_phase: "planner_planning"`
+   - `started_at`: Current ISO timestamp
+   - `task_description`: User's task description
+
+### Planner Planning Phase
+
+The Planner creates an initial plan based on task context:
+
+- Invoke Planner in **direct planning mode** (bypassing interview since task context is pre-gathered)
+- Planner receives task context directly without preliminary questioning
+- Planner mandatorily consults with Metis for gap detection
+- Planner generates plan directly to `.omc/plans/[feature-name].md`
+- Plan includes: requirements summary, concrete acceptance criteria, specific implementation steps with file references, risk identification with mitigations, and verification steps
+- Signal completion with `PLAN_READY: .omc/plans/[filename].md`
+- Extract plan path from completion signal and update state
+
+### Architect Consultation (Conditional)
+
+The Architect provides strategic guidance in two scenarios:
+
+1. **After Planner**: If Planner raises architectural questions needing strategic input
+2. **After Critic rejection**: If Critic identifies questions requiring expert guidance
+
+When invoked, the Architect receives file paths to read for analysis, not summaries. This enables thorough examination of the existing codebase context before providing recommendations.
+
+### Critic Review
+
+The Critic examines the plan against quality standards:
+
+- Critic receives the plan file path (per its design)
+- Critic conducts thorough review of plan completeness and feasibility
+- Critic emits verdict: either `OKAY` (approval) or `REJECT` with specific issues
+
+### Verdict Handling and Iteration
+
+Based on Critic's verdict, the skill either approves the plan or continues iteration:
+
+**If verdict is OKAY:**
+- Mark plan as approved
+- Log approval with iteration count
+- Prepare plan for execution with `/ralph` or manual orchestration
+- Set state `active: false, current_phase: "complete"`
+
+**If verdict is REJECT:**
+- Extract Critic feedback with specific issues
+- Increment iteration counter
+- If `iteration >= max_iterations` (5):
+  - Force approval with warning about unresolved concerns
+  - Recommend manual review before execution
+- Otherwise:
+  - Feed Critic feedback back to Planner
+  - Return to Planner Planning phase for refinement
+
+## Iteration Rules
+
+| Rule | Description |
+|------|-------------|
+| **Max 5 iterations** | Safety limit prevents infinite loops |
+| **Planner owns plan** | Only Planner writes to plan file |
+| **Architect provides wisdom** | Architect reads and advises, never modifies |
+| **Critic has final say** | Plan approved only when Critic signals OKAY |
+| **Feedback is specific** | Each rejection includes actionable improvements |
+| **State persists** | Progress survives session interruptions |
+
+## Quality Gates
+
+The orchestrator must verify these gates before invoking Critic for each review:
+
+1. **Plan file exists** at the path specified in state
+2. **File references are valid** - Verify all mentioned files exist in codebase
+3. **Acceptance criteria are concrete** - No vague "improve" or "optimize" without measurable metrics
+4. **No ambiguous language** - Each task clearly specifies what to do
+
+If any gate fails, return to Planner with specific failure feedback for remediation.
+
+## Agent Communication Protocol
+
+### Planner to Architect Questions
+
+```
+ARCHITECT_QUESTION:
+- Topic: [Architecture/Performance/Security/Pattern]
+- Context: [What we're planning]
+- Files to examine: [specific paths]
+- Specific Question: [What we need answered]
+```
+
+### Architect to Planner Answers
+
+```
+ARCHITECT_ANSWER:
+- Topic: [Matching topic]
+- Analysis: [What Architect found after reading files]
+- Recommendation: [Specific guidance]
+- Trade-offs: [What to consider]
+- References: [file:line citations from codebase]
+```
+
+### Critic to Planner Feedback
+
+```
+CRITIC_FEEDBACK:
+- Verdict: REJECT
+- Critical Issues:
+  1. [Issue with specific fix required]
+  2. [Issue with specific fix required]
+- Minor Issues:
+  1. [Nice to fix]
+- Questions for Architect (if any):
+  1. [Architectural question needing expert input]
+```
+
+## Cancellation
+
+To stop an active ralplan session:
+
+- Use `/cancel-ralph` (automatically detects ralplan via state file)
+- Or manually delete `.omc/ralplan-state.json`
+
+## Skill Workflow
+
+1. **Initialize state** and log: `[RALPLAN Iteration 0/5] Initializing...`
+2. **Parse task** from user input
+3. **Spawn Planner** in direct planning mode
+4. **Iterate** through planning loop with observability logging at each phase
+5. **Complete** when Critic approves or max iterations reached with warnings
+
+The iterative loop refines the plan until it meets the rigorous standards of all three agents, ensuring comprehensive, architecturally sound work plans ready for execution.

package/commands/release.md

@@ -0,0 +1,82 @@
+---
+description: Automated release workflow for oh-my-claudecode
+---
+
+# Release Skill
+
+Automate the release process for oh-my-claudecode.
+
+## Usage
+
+```
+/release <version>
+```
+
+Example: `/release 2.4.0` or `/release patch` or `/release minor`
+
+## Release Checklist
+
+Execute these steps in order:
+
+### 1. Version Bump
+Update version in all locations:
+- `package.json`
+- `src/installer/index.ts` (VERSION constant)
+- `src/__tests__/installer.test.ts` (expected version)
+- `.claude-plugin/plugin.json`
+- `README.md` (version badge and title)
+
+### 2. Run Tests
+```bash
+npm run test:run
+```
+All 231+ tests must pass before proceeding.
+
+### 3. Commit Version Bump
+```bash
+git add -A
+git commit -m "chore: Bump version to <version>"
+```
+
+### 4. Create & Push Tag
+```bash
+git tag v<version>
+git push origin main
+git push origin v<version>
+```
+
+### 5. Publish to npm
+```bash
+npm publish --access public
+```
+
+### 6. Create GitHub Release
+```bash
+gh release create v<version> --title "v<version> - <title>" --notes "<release notes>"
+```
+
+### 7. Verify
+- [ ] npm: https://www.npmjs.com/package/oh-my-claudecode
+- [ ] GitHub: https://github.com/Yeachan-Heo/oh-my-claudecode/releases
+
+## Version Files Reference
+
+| File | Field/Line |
+|------|------------|
+| `package.json` | `"version": "X.Y.Z"` |
+| `src/installer/index.ts` | `export const VERSION = 'X.Y.Z'` |
+| `src/__tests__/installer.test.ts` | `expect(VERSION).toBe('X.Y.Z')` |
+| `.claude-plugin/plugin.json` | `"version": "X.Y.Z"` |
+| `README.md` | Title + version badge |
+
+## Semantic Versioning
+
+- **patch** (X.Y.Z+1): Bug fixes, minor improvements
+- **minor** (X.Y+1.0): New features, backward compatible
+- **major** (X+1.0.0): Breaking changes
+
+## Notes
+
+- Always run tests before publishing
+- Create release notes summarizing changes
+- Plugin marketplace syncs automatically from GitHub releases

package/commands/review.md

@@ -1,3 +1,35 @@
 ---
 description: Review a plan with Critic
 ---
+
+# Review Skill
+
+[PLAN REVIEW MODE ACTIVATED]
+
+## Role
+
+Critically evaluate plans using Critic. No plan passes without meeting rigorous standards.
+
+## Review Criteria
+
+| Criterion | Standard |
+|-----------|----------|
+| Clarity | 80%+ claims cite file/line |
+| Testability | 90%+ criteria are concrete |
+| Verification | All file refs exist |
+| Specificity | No vague terms |
+
+## Verdicts
+
+**APPROVED** - Plan meets all criteria, ready for execution
+**REVISE** - Plan has issues needing fixes (with specific feedback)
+**REJECT** - Fundamental problems require replanning
+
+## What Gets Checked
+
+1. Are requirements clear and unambiguous?
+2. Are acceptance criteria concrete and testable?
+3. Do file references actually exist?
+4. Are implementation steps specific?
+5. Are risks identified with mitigations?
+6. Are verification steps defined?