oh-my-claude-sisyphus 3.3.10 → 3.4.0

package/docs/MIGRATION.md

@@ -1,6 +1,20 @@
-# Migration Guide: 2.x to 3.0
+# Migration Guide
 
-## TL;DR
+This guide covers all migration paths for oh-my-claudecode. Find your current version below.
+
+---
+
+## Table of Contents
+
+- [v2.x → v3.0: Package Rename & Auto-Activation](#v2x--v30-package-rename--auto-activation)
+- [v3.0 → v3.1: Notepad Wisdom & Enhanced Features](#v30--v31-notepad-wisdom--enhanced-features)
+- [v3.x → v4.0: Major Architecture Overhaul](#v3x--v40-major-architecture-overhaul)
+
+---
+
+## v2.x → v3.0: Package Rename & Auto-Activation
+
+### TL;DR
 
 Your old commands still work! But now you don't need them.
 
@@ -8,11 +22,26 @@ Your old commands still work! But now you don't need them.
 
 **After 3.0:** Just work naturally - Claude auto-activates the right behaviors. One-time setup: just say "setup omc"
 
----
+### Package Rename
 
-## What Changed
+The package has been renamed to better reflect its purpose and improve discoverability.
 
-### Before (2.x): Explicit Commands
+- **Old**: `oh-my-claude-sisyphus`
+- **New**: `oh-my-claudecode`
+
+#### NPM Commands
+
+```bash
+# Old
+npm install -g oh-my-claude-sisyphus
+
+# New
+npm install -g oh-my-claudecode
+```
+
+### What Changed
+
+#### Before (2.x): Explicit Commands
 
 You had to remember and explicitly invoke specific commands for each mode:
 
@@ -27,7 +56,7 @@ You had to remember and explicitly invoke specific commands for each mode:
 /oh-my-claudecode:analyze "why is this test failing?"         # Deep analysis
 ```
 
-### After (3.0): Auto-Activation + Keywords
+#### After (3.0): Auto-Activation + Keywords
 
 Work naturally. Claude detects intent and activates behaviors automatically:
 
@@ -41,9 +70,63 @@ Work naturally. Claude detects intent and activates behaviors automatically:
 "commit these changes properly"                     # Auto-activates git expertise
 ```
 
----
+### Agent Name Mapping
 
-## Command Mapping
+All agent names have been updated from Greek mythology references to intuitive, descriptive names:
+
+| Old Name (Greek) | New Name (Intuitive) |
+|------------------|----------------------|
+| prometheus | planner |
+| momus | critic |
+| oracle | architect |
+| metis | analyst |
+| mnemosyne | learner |
+| sisyphus-junior | executor |
+| orchestrator-sisyphus | coordinator |
+| librarian | researcher |
+| frontend-engineer | designer |
+| document-writer | writer |
+| multimodal-looker | vision |
+| explore | explore (unchanged) |
+| qa-tester | qa-tester (unchanged) |
+
+### Directory Migration
+
+Directory structures have been renamed for consistency with the new package name:
+
+#### Local Project Directories
+- **Old**: `.sisyphus/`
+- **New**: `.omc/`
+
+#### Global Directories
+- **Old**: `~/.sisyphus/`
+- **New**: `~/.omc/`
+
+#### Skills Directory
+- **Old**: `~/.claude/skills/sisyphus-learned/`
+- **New**: `~/.claude/skills/omc-learned/`
+
+#### Config Files
+- **Old**: `~/.claude/sisyphus/mnemosyne.json`
+- **New**: `~/.claude/omc/learner.json`
+
+### Environment Variables
+
+All environment variables have been renamed from `SISYPHUS_*` to `OMC_*`:
+
+| Old | New |
+|-----|-----|
+| SISYPHUS_USE_NODE_HOOKS | OMC_USE_NODE_HOOKS |
+| SISYPHUS_USE_BASH_HOOKS | OMC_USE_BASH_HOOKS |
+| SISYPHUS_PARALLEL_EXECUTION | OMC_PARALLEL_EXECUTION |
+| SISYPHUS_LSP_TOOLS | OMC_LSP_TOOLS |
+| SISYPHUS_MAX_BACKGROUND_TASKS | OMC_MAX_BACKGROUND_TASKS |
+| SISYPHUS_ROUTING_ENABLED | OMC_ROUTING_ENABLED |
+| SISYPHUS_ROUTING_DEFAULT_TIER | OMC_ROUTING_DEFAULT_TIER |
+| SISYPHUS_ESCALATION_ENABLED | OMC_ESCALATION_ENABLED |
+| SISYPHUS_DEBUG | OMC_DEBUG |
+
+### Command Mapping
 
 All 2.x commands continue to work. Here's what changed:
 
@@ -65,9 +148,7 @@ All 2.x commands continue to work. Here's what changed:
 | `/oh-my-claudecode:doctor` | Invoke normally | ✅ YES (unchanged) |
 | All other commands | Work exactly as before | ✅ YES |
 
----
-
-## Magic Keywords
+### Magic Keywords
 
 Include these anywhere in your message to explicitly activate behaviors. Use keywords when you want explicit control (optional):
 
@@ -92,9 +173,7 @@ Persistence (won't stop) + Ultrawork (maximum parallelism)
 "help me design the dashboard"     # Triggers planning
 ```
 
----
-
-## Natural Cancellation
+### Natural Cancellation
 
 Say any of these to stop:
 - "stop"
@@ -115,59 +194,95 @@ If multiple active   → Stop the most recent
 
 No more `/oh-my-claudecode:cancel-ralph` - just say "cancel"!
 
----
+### Migration Steps
 
-## Backward Compatibility: All 2.x Commands Still Work
+Follow these steps to migrate your existing setup:
 
-**Zero breaking changes.** Your existing workflows don't break.
+#### 1. Uninstall Old Package
 
-### Explicit Command Invocation Still Works
+```bash
+npm uninstall -g oh-my-claude-sisyphus
+```
 
-You can still use explicit commands if you prefer:
+#### 2. Install New Package
 
 ```bash
-/oh-my-claudecode:ralph "implement OAuth"           # Still works ✅
-/oh-my-claudecode:ultrawork "refactor everything"   # Still works ✅
-/oh-my-claudecode:planner "plan the feature"        # Still works ✅
-/oh-my-claudecode:cancel-ralph                      # Still works ✅
+npm install -g oh-my-claudecode
 ```
 
-These are now **optional** - use them if you like, but you don't have to.
+#### 3. Rename Local Project Directories
+
+If you have existing projects using the old directory structure:
 
-### Skill Composition
+```bash
+# In each project directory
+mv .sisyphus .omc
+```
 
-Skills now compose automatically based on context:
+#### 4. Rename Global Directories
 
+```bash
+# Global configuration directory
+mv ~/.sisyphus ~/.omc
+
+# Skills directory
+mv ~/.claude/skills/sisyphus-learned ~/.claude/skills/omc-learned
+
+# Config directory
+mv ~/.claude/sisyphus ~/.claude/omc
 ```
-Natural request: "Help me refactor the API quickly"
-    ↓
-Auto-detects: Need orchestration + speed
-    ↓
-Activates: orchestrate + ultrawork + git-master skills
-    ↓
-Result: Parallel agents, atomic commits, fast implementation
+
+#### 5. Update Environment Variables
+
+Update your shell configuration files (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+# Replace all SISYPHUS_* variables with OMC_*
+# Example:
+# OLD: export SISYPHUS_ROUTING_ENABLED=true
+# NEW: export OMC_ROUTING_ENABLED=true
 ```
 
-You don't need to invoke multiple commands manually - Claude figures it out.
+#### 6. Update Scripts and Configurations
 
----
+Search for and update any references to:
+- Package name: `oh-my-claude-sisyphus` → `oh-my-claudecode`
+- Agent names: Use the mapping table above
+- Commands: Use the new slash commands
+- Directory paths: Update `.sisyphus` → `.omc`
 
-## Breaking Changes
+#### 7. Run One-Time Setup
 
-**None!** Version 3.0 is purely additive:
+In Claude Code, just say "setup omc", "omc setup", or any natural language equivalent.
 
-- All 2.x commands continue to work
-- All agents renamed but function identically (oracle → architect, etc.)
-- Directory structure changed (.sisyphus → .omc) but handled automatically
-- Environment variables renamed (SISYPHUS_* → OMC_*) but old ones still recognized
+This:
+- Downloads latest CLAUDE.md
+- Configures 19 agents
+- Enables auto-behavior detection
+- Activates continuation enforcement
+- Sets up skill composition
 
-See [MIGRATION-v3.md](MIGRATION-v3.md) for detailed 2.x → 3.0 naming changes.
+### Verification
 
----
+After migration, verify your setup:
+
+1. **Check installation**:
+   ```bash
+   npm list -g oh-my-claudecode
+   ```
 
-## New Features in 3.0
+2. **Verify directories exist**:
+   ```bash
+   ls -la .omc/  # In project directory
+   ls -la ~/.omc/  # Global directory
+   ```
 
-### 1. Zero-Learning-Curve Operation
+3. **Test a simple command**:
+   Run `/oh-my-claudecode:help` in Claude Code to ensure the plugin is loaded correctly.
+
+### New Features in 3.0
+
+#### 1. Zero-Learning-Curve Operation
 
 **No commands to memorize.** Work naturally:
 
@@ -178,7 +293,7 @@ After:  "I'm in a hurry, go fast!"
         Claude: "I'm activating ultrawork mode..."
 ```
 
-### 2. Delegate Always (Automatic)
+#### 2. Delegate Always (Automatic)
 
 Complex work auto-routes to specialist agents:
 
@@ -194,7 +309,7 @@ Your request              Claude's action
 
 You don't ask for delegation - it happens automatically.
 
-### 3. Learned Skills (`/oh-my-claudecode:learner`)
+#### 3. Learned Skills (`/oh-my-claudecode:learner`)
 
 Extract reusable insights from problem-solving:
 
@@ -211,7 +326,7 @@ Storage:
 - **Project-level**: `.omc/skills/` (version-controlled)
 - **User-level**: `~/.claude/skills/omc-learned/` (portable)
 
-### 4. HUD Statusline (Real-Time Orchestration)
+#### 4. HUD Statusline (Real-Time Orchestration)
 
 See what Claude is doing in the status bar:
 
@@ -221,7 +336,7 @@ See what Claude is doing in the status bar:
 
 Run `/oh-my-claudecode:hud setup` to install. Presets: minimal, focused, full.
 
-### 5. Three-Tier Memory System
+#### 5. Three-Tier Memory System
 
 Critical knowledge survives context compaction:
 
@@ -239,7 +354,7 @@ Or use `/oh-my-claudecode:note` to save discoveries manually:
 /oh-my-claudecode:note Project uses PostgreSQL with Prisma ORM
 ```
 
-### 6. Structured Task Tracking (PRD Support)
+#### 6. Structured Task Tracking (PRD Support)
 
 **Ralph Loop now uses Product Requirements Documents:**
 
@@ -253,7 +368,7 @@ Each story: description + acceptance criteria + pass/fail
 Ralph loops until ALL stories pass
 ```
 
-### 7. Intelligent Continuation
+#### 7. Intelligent Continuation
 
 **Tasks complete before Claude stops:**
 
@@ -267,71 +382,137 @@ Creates todo list, works through each item
 Only stops when EVERYTHING is verified complete
 ```
 
+### Backward Compatibility Note
+
+**Note**: v3.0 does not maintain backward compatibility with v2.x naming. You must complete the migration steps above for the new version to work correctly.
+
 ---
 
-## Getting Started with 3.0
+## v3.0 → v3.1: Notepad Wisdom & Enhanced Features
 
-### Step 1: Update Your Plugin
+### Overview
 
-```bash
-# Plugin auto-updates, but you can manually update:
-npm update -g oh-my-claudecode
-```
+Version 3.1 is a minor release adding powerful new features while maintaining full backward compatibility with v3.0.
 
-### Step 2: Run One-Time Setup
+### What's New
 
-In Claude Code, just say "setup omc", "omc setup", or any natural language equivalent.
+#### 1. Notepad Wisdom System
 
-This:
-- Downloads latest CLAUDE.md
-- Configures 19 agents
-- Enables auto-behavior detection
-- Activates continuation enforcement
-- Sets up skill composition
+Plan-scoped wisdom capture for learnings, decisions, issues, and problems.
+
+**Location:** `.omc/notepads/{plan-name}/`
+
+| File | Purpose |
+|------|---------|
+| `learnings.md` | Technical discoveries and patterns |
+| `decisions.md` | Architectural and design decisions |
+| `issues.md` | Known issues and workarounds |
+| `problems.md` | Blockers and challenges |
+
+**API:**
+- `initPlanNotepad()` - Initialize notepad for a plan
+- `addLearning()` - Record technical discoveries
+- `addDecision()` - Record architectural choices
+- `addIssue()` - Record known issues
+- `addProblem()` - Record blockers
+- `getWisdomSummary()` - Get summary of all wisdom
+- `readPlanWisdom()` - Read full wisdom for context
+
+#### 2. Delegation Categories
+
+Semantic task categorization that auto-maps to model tier, temperature, and thinking budget.
+
+| Category | Tier | Temperature | Thinking | Use For |
+|----------|------|-------------|----------|---------|
+| `visual-engineering` | HIGH | 0.7 | high | UI/UX, frontend, design systems |
+| `ultrabrain` | HIGH | 0.3 | max | Complex reasoning, architecture, deep debugging |
+| `artistry` | MEDIUM | 0.9 | medium | Creative solutions, brainstorming |
+| `quick` | LOW | 0.1 | low | Simple lookups, basic operations |
+| `writing` | MEDIUM | 0.5 | medium | Documentation, technical writing |
+
+**Auto-detection:** Categories detect from prompt keywords automatically.
+
+#### 3. Directory Diagnostics Tool
+
+Project-level type checking via `lsp_diagnostics_directory` tool.
+
+**Strategies:**
+- `auto` (default) - Auto-selects best strategy, prefers tsc when tsconfig.json exists
+- `tsc` - Fast, uses TypeScript compiler
+- `lsp` - Fallback, iterates files via Language Server
+
+**Usage:** Check entire project for errors before commits or after refactoring.
 
-### Step 3: Use Naturally
+#### 4. Session Resume
 
-**Just work.** Everything is automatic.
+Background agents can be resumed with full context via `resume-session` tool.
+
+### Migration Steps
+
+Version 3.1 is a drop-in upgrade. No migration required!
 
 ```bash
-"refactor the authentication system"
-    ↓
-Claude auto-detects: complex task, multi-file changes
-    ↓
-Activates: orchestrate + git-master skills
-    ↓
-You're done - Claude handles the rest
+npm update -g oh-my-claudecode
 ```
 
+All existing configurations, plans, and workflows continue working unchanged.
+
+### New Tools Available
+
+Once upgraded, agents automatically gain access to:
+- Notepad wisdom APIs (read/write wisdom during execution)
+- Delegation categories (automatic categorization)
+- Directory diagnostics (project-level type checking)
+- Session resume (recover background agent state)
+
 ---
 
-## Configuration Options
+## v3.x → v4.0: Major Architecture Overhaul
 
-### Project-Scoped Configuration (Recommended)
+### Overview
 
-Apply oh-my-claudecode to current project only:
+Version 4.0 is a complete architectural redesign focusing on scalability, maintainability, and developer experience.
 
-```
-/oh-my-claudecode:omc-default
-```
+### What's Coming
 
-Creates: `./.claude/CLAUDE.md`
+⚠️ **This section is under active development as v4.0 is being built.**
 
-### Global Configuration
+#### Planned Changes
 
-Apply to all Claude Code sessions:
+1. **Modular Architecture**
+   - Plugin system for extensibility
+   - Core/extension separation
+   - Better dependency management
 
-```
-/oh-my-claudecode:omc-default-global
-```
+2. **Enhanced Agent System**
+   - Improved agent lifecycle management
+   - Better error recovery
+   - Performance optimizations
 
-Creates: `~/.claude/CLAUDE.md`
+3. **Improved Configuration**
+   - Unified config schema
+   - Better validation
+   - Migration tooling
 
-**Precedence:** Project config overrides global if both exist.
+4. **Breaking Changes**
+   - TBD based on development progress
+   - Full migration guide will be provided
+
+### Migration Path (Coming Soon)
+
+Detailed migration instructions will be provided when v4.0 reaches release candidate status.
+
+Expected timeline: Q1 2026
+
+### Stay Updated
+
+- Watch the [GitHub repository](https://github.com/Yeachan-Heo/oh-my-claude-sisyphus) for announcements
+- Check [CHANGELOG.md](../CHANGELOG.md) for detailed release notes
+- Join discussions in GitHub Issues
 
 ---
 
-## Common Scenarios: 2.x vs 3.0
+## Common Scenarios Across Versions
 
 ### Scenario 1: Quick Implementation Task
 
@@ -340,7 +521,7 @@ Creates: `~/.claude/CLAUDE.md`
 /oh-my-claudecode:ultrawork "implement the todo list feature"
 ```
 
-**3.0 Workflow:**
+**3.0+ Workflow:**
 ```
 "implement the todo list feature quickly"
     ↓
@@ -356,7 +537,7 @@ Claude: "I'm activating ultrawork for maximum parallelism"
 /oh-my-claudecode:ralph "debug the memory leak"
 ```
 
-**3.0 Workflow:**
+**3.0+ Workflow:**
 ```
 "there's a memory leak in the worker process - don't stop until we fix it"
     ↓
@@ -372,7 +553,7 @@ Claude: "I'm activating ralph-loop to ensure completion"
 /oh-my-claudecode:planner "design the new authentication system"
 ```
 
-**3.0 Workflow:**
+**3.0+ Workflow:**
 ```
 "plan the new authentication system"
     ↓
@@ -390,7 +571,7 @@ Interview begins automatically
 /oh-my-claudecode:cancel-ralph
 ```
 
-**3.0 Workflow:**
+**3.0+ Workflow:**
 ```
 "stop"
 ```
@@ -399,16 +580,29 @@ Interview begins automatically
 
 ---
 
-## Migration Checklist
+## Configuration Options
+
+### Project-Scoped Configuration (Recommended)
 
-If you're upgrading from 2.x:
+Apply oh-my-claudecode to current project only:
 
-- [ ] Install/Update plugin: `claude plugin install oh-my-claude-sisyphus`
-- [ ] Run setup: say "setup omc"
-- [ ] Test natural language: Say "don't stop until done" (should activate ralph)
-- [ ] Test keyword: Use `ralph` keyword in a request (should activate ralph-loop)
-- [ ] Test cancellation: Say "stop" (should cancel active operation)
-- [ ] Review existing scripts: Update references to old command names (optional - old commands still work)
+```
+/oh-my-claudecode:omc-default
+```
+
+Creates: `./.claude/CLAUDE.md`
+
+### Global Configuration
+
+Apply to all Claude Code sessions:
+
+```
+/oh-my-claudecode:omc-default-global
+```
+
+Creates: `~/.claude/CLAUDE.md`
+
+**Precedence:** Project config overrides global if both exist.
 
 ---
 
@@ -418,7 +612,7 @@ If you're upgrading from 2.x:
 A: No. Keywords are optional shortcuts. Claude auto-detects intent without them.
 
 **Q: Will my old commands break?**
-A: No. All 2.x commands continue to work exactly as before.
+A: No. All commands continue to work across minor versions (3.0 → 3.1). Major version changes (3.x → 4.0) will provide migration paths.
 
 **Q: What if I like explicit commands?**
 A: Keep using them! `/oh-my-claudecode:ralph`, `/oh-my-claudecode:ultrawork`, `/oh-my-claudecode:planner` all still work.
@@ -426,7 +620,7 @@ A: Keep using them! `/oh-my-claudecode:ralph`, `/oh-my-claudecode:ultrawork`, `/
 **Q: How do I know what Claude is doing?**
 A: Claude announces major behaviors: "I'm activating ralph-loop..." or set up `/oh-my-claudecode:hud` for real-time status.
 
-**Q: Where's the old command list?**
+**Q: Where's the full command list?**
 A: See [README.md](../README.md) for full command reference. All commands still work.
 
 **Q: What's the difference between keywords and natural language?**
@@ -453,4 +647,4 @@ Now that you understand the migration:
 3. **For advanced usage**: Check [docs/ARCHITECTURE.md](ARCHITECTURE.md) for deep dives
 4. **For team onboarding**: Share this guide with teammates
 
-Welcome to 3.0!
+Welcome to oh-my-claudecode!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-claude-sisyphus",
-  "version": "3.3.10",
+  "version": "3.4.0",
   "description": "Multi-agent orchestration system for Claude Code - Inspired by oh-my-opencode",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@types/node": "^22.10.2",
+    "@types/node": "^22.19.7",
     "@typescript-eslint/eslint-plugin": "^8.18.2",
     "@typescript-eslint/parser": "^8.18.2",
     "@vitest/ui": "^4.0.17",

package/scripts/test-mutual-exclusion.ts

@@ -6,7 +6,7 @@ import { tmpdir } from 'os';
 import { mkdirSync } from 'fs';
 
 // Import the hooks
-import { startUltraQA, clearUltraQAState, isRalphLoopActive } from '../src/hooks/ultraqa-loop/index.js';
+import { startUltraQA, clearUltraQAState, isRalphLoopActive } from '../src/hooks/ultraqa/index.js';
 import { createRalphLoopHook, clearRalphState, isUltraQAActive } from '../src/hooks/ralph-loop/index.js';
 
 // Test utilities

package/skills/analyze/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: analyze
 description: Deep analysis and investigation
-user-invocable: true
 ---
 
 # Deep Analysis Mode

package/skills/autopilot/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: autopilot
 description: Full autonomous execution from idea to working code
-user-invocable: true
 ---
 
 # Autopilot Skill