npm - claudecode-omc - Versions diffs - 4.9.4 → 5.0.0 - Mend

claudecode-omc 4.9.4 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3894) hide show

package/docs/MIGRATION.md DELETED Viewed

@@ -1,987 +0,0 @@
-# Migration Guide
-This guide covers all migration paths for oh-my-claudecode. Find your current version below.
----
-## Table of Contents
-- [Unreleased: Team MCP Runtime Deprecation (CLI-Only)](#unreleased-team-mcp-runtime-deprecation-cli-only)
-- [v3.5.3 → v3.5.5: Test Fixes & Cleanup](#v353--v355-test-fixes--cleanup)
-- [v3.5.2 → v3.5.3: Skill Consolidation](#v352--v353-skill-consolidation)
-- [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)
----
-## Unreleased: Team MCP Runtime Deprecation (CLI-Only)
-### TL;DR
-`omc_run_team_start/status/wait/cleanup` are now hard-deprecated at runtime. Calls return:
-```json
-{
-  "code": "deprecated_cli_only",
-  "message": "Legacy team MCP runtime tools are deprecated. Use the omc team CLI instead."
-}
-```
-Use CLI commands instead:
-- `omc team [N:agent-type] "<task>"`
-- `omc team status <team-name>`
-- `omc team shutdown <team-name> [--force]`
-- `omc team api <operation> --input '<json>' --json`
-### `omc ask` env alias sunset (Phase-1 compatibility)
-`OMC_ASK_*` is now canonical for advisor execution. Phase-1 accepts `OMX_ASK_ADVISOR_SCRIPT` and `OMX_ASK_ORIGINAL_TASK` with deprecation warnings. Planned hard sunset for alias removal: **2026-06-30**.
-### How to Migrate
-1. Replace MCP runtime tool calls with CLI equivalents.
-2. Update skills/prompts from `/omc-teams ...` to `omc team ...` syntax.
-3. Legacy Team MCP runtime is now opt-in only (not enabled by default). If you enable it manually, treat responses as deprecation-only compatibility output.
-### Example mapping
-```bash
-# Old (deprecated runtime path)
-mcp__team__omc_run_team_start(...)
-mcp__team__omc_run_team_status({ job_id: ... })
-mcp__team__omc_run_team_wait({ job_id: ... })
-mcp__team__omc_run_team_cleanup({ job_id: ... })
-# New (CLI-first)
-omc team 2:codex "review auth flow"
-omc team status review-auth-flow
-omc team shutdown review-auth-flow --force
-omc team api list-tasks --input '{"team_name":"review-auth-flow"}' --json
-```
----
-## v3.5.3 → v3.5.5: Test Fixes & Cleanup
-### TL;DR
-Maintenance release fixing test suite issues and continuing skill consolidation from v3.5.3.
-### What Changed
-**Test Fixes:**
-- Delegation-enforcer tests marked as skipped (implementation pending)
-- Analytics expectations corrected for agent attribution
-- All remaining tests now pass cleanly
-**Skill Consolidation:**
-- Continued cleanup from v3.5.3
-- Removed deprecated `cancel-*` skills (use `/cancel` instead)
-- Final skill count: 37 core skills
-### Migration Steps
-1. **No breaking changes** - All functionality preserved
-2. **Test suite** now runs cleanly with `npm run test:run`
-3. **Deprecated skills** removed (already replaced in v3.5.3)
-### For Developers
-If you were depending on deprecated `cancel-*` skills, update to use the unified `/cancel` command which auto-detects the active mode.
----
-## v3.5.2 → v3.5.3: Skill Consolidation
-### TL;DR
-8 deprecated skills have been removed. The unified `/cancel` and `/omc-setup` commands replace them.
-### Removed Skills
-The following skills have been **completely removed** in v3.5.3:
-| Removed Skill        | Replacement                            |
-| -------------------- | -------------------------------------- |
-| `cancel-autopilot`   | `/oh-my-claudecode:cancel`             |
-| `cancel-ralph`       | `/oh-my-claudecode:cancel`             |
-| `cancel-ultrawork`   | `/oh-my-claudecode:cancel`             |
-| `cancel-ultraqa`     | `/oh-my-claudecode:cancel`             |
-| `omc-default`        | `/oh-my-claudecode:omc-setup --local`  |
-| `omc-default-global` | `/oh-my-claudecode:omc-setup --global` |
-| `planner`            | `/oh-my-claudecode:plan`               |
-### What Changed
-**Before v3.5.3:**
-```bash
-/oh-my-claudecode:cancel-ralph      # Cancel ralph specifically
-/oh-my-claudecode:omc-default       # Configure local project
-/oh-my-claudecode:planner "task"    # Start planning
-```
-**After v3.5.3:**
-```bash
-/oh-my-claudecode:cancel            # Auto-detects and cancels any active mode
-/oh-my-claudecode:omc-setup --local # Configure local project
-/oh-my-claudecode:plan "task"       # Start planning (includes interview mode)
-```
-### New Features
-**New skill: `/learn-about-omc`**
-- Analyzes your OMC usage patterns
-- Provides personalized recommendations
-- Identifies underutilized features
-**Plan skill now supports consensus mode:**
-```bash
-/oh-my-claudecode:plan --consensus "task"  # Iterative planning with Critic review
-/oh-my-claudecode:ralplan "task"           # Alias for plan --consensus
-```
-### Migration Steps
-1. **No action required** - The unified `/cancel` command already worked in v3.5
-2. **Update any scripts** that reference removed commands
-3. **Re-run `/omc-setup`** if you want to update your CLAUDE.md configuration
-### Skill Count
-- v3.5: 42 skills
-- v3.5.3: 37 skills (8 removed, 3 added)
----
-## v2.x → v3.0: Package Rename & Auto-Activation
-### TL;DR
-Your old commands still work! But now you don't need them.
-**Before 3.0:** Explicitly invoke 25+ commands like `/oh-my-claudecode:ralph "task"`, `/oh-my-claudecode:ultrawork "task"`
-**After 3.0:** Just work naturally - Claude auto-activates the right behaviors. One-time setup: just say "setup omc"
-### Project Rebrand
-The project was rebranded to better reflect its purpose and improve discoverability.
-- **Project/brand name**: `oh-my-claudecode` (GitHub repo, plugin name, commands)
-- **npm package name**: `claudecode-omc`
-> **Why the difference?** The npm package name `claudecode-omc` is used for distribution, while the project, GitHub repository, plugin, and all commands use `oh-my-claudecode`.
-#### NPM Install Command
-```bash
-npm i -g claudecode-omc@latest
-```
-### What Changed
-#### Before (2.x): Explicit Commands
-You had to remember and explicitly invoke specific commands for each mode:
-```bash
-# 2.x workflow: Multiple commands, lots to remember
-/oh-my-claudecode:ralph "implement user authentication"       # Persistence mode
-/oh-my-claudecode:ultrawork "refactor the API layer"          # Maximum parallelism
-/oh-my-claudecode:planner "plan the new dashboard"            # Planning interview
-/oh-my-claudecode:deepsearch "find database schema files"     # Deep search
-/oh-my-claudecode:git-master "commit these changes"           # Git expertise
-/oh-my-claudecode:deepinit ./src                              # Index codebase
-/oh-my-claudecode:analyze "why is this test failing?"         # Deep analysis
-```
-#### After (3.0): Auto-Activation + Keywords
-Work naturally. Claude detects intent and activates behaviors automatically:
-```bash
-# 3.0 workflow: Just talk naturally OR use optional keywords
-"don't stop until user auth is done"                # Auto-activates ralph-loop
-"fast: refactor the entire API layer"               # Auto-activates ultrawork
-"plan: design the new dashboard"                    # Auto-activates planning
-"ralph ulw: migrate the database"                   # Combined: persistence + parallelism
-"find all database schema files"                    # Auto-activates search mode
-"commit these changes properly"                     # Auto-activates git expertise
-```
-### Agent Naming Standard
-Agent naming is now strictly descriptive and role-based (for example: `architect`, `planner`, `analyst`, `critic`, `document-specialist`, `designer`, `writer`, `vision`, `executor`).
-Use canonical role names across prompts, commands, docs, and scripts. Avoid introducing alternate myth-style or legacy aliases in new content.
-### Directory Migration
-Directory structures have been renamed for consistency with the new package name:
-#### Local Project Directories
-- **Old**: `.omc/`
-- **New**: `.omc/`
-#### Global Directories
-- **Old**: `~/.omc/`
-- **New**: `~/.omc/`
-#### Skills Directory
-- **Old**: `~/.claude/skills/omc-learned/`
-- **New**: `~/.claude/skills/omc-learned/`
-#### Config Files
-- **Old**: `~/.claude/omc/mnemosyne.json`
-- **New**: `~/.claude/omc/learner.json`
-### Environment Variables
-All environment variables have been renamed from `OMC_*` to `OMC_*`:
-| Old                      | New                      |
-| ------------------------ | ------------------------ |
-| OMC_USE_NODE_HOOKS       | OMC_USE_NODE_HOOKS       |
-| OMC_USE_BASH_HOOKS       | OMC_USE_BASH_HOOKS       |
-| OMC_PARALLEL_EXECUTION   | OMC_PARALLEL_EXECUTION   |
-| OMC_LSP_TOOLS            | OMC_LSP_TOOLS            |
-| OMC_MAX_BACKGROUND_TASKS | OMC_MAX_BACKGROUND_TASKS |
-| OMC_ROUTING_ENABLED      | OMC_ROUTING_ENABLED      |
-| OMC_ROUTING_DEFAULT_TIER | OMC_ROUTING_DEFAULT_TIER |
-| OMC_ESCALATION_ENABLED   | OMC_ESCALATION_ENABLED   |
-| OMC_DEBUG                | OMC_DEBUG                |
-### Command Mapping
-All 2.x commands continue to work. Here's what changed:
-| 2.x Command                            | 3.0 Equivalent                                     | Works?                 |
-| -------------------------------------- | -------------------------------------------------- | ---------------------- |
-| `/oh-my-claudecode:ralph "task"`       | Say "don't stop until done" OR use `ralph` keyword | ✅ YES (both ways)     |
-| `/oh-my-claudecode:ultrawork "task"`   | Say "fast" or "parallel" OR use `ulw` keyword      | ✅ YES (both ways)     |
-| `/oh-my-claudecode:ultrawork-ralph`    | Say "ralph ulw:" prefix                            | ✅ YES (keyword combo) |
-| `/oh-my-claudecode:planner "task"`     | Say "plan this" OR use `plan` keyword              | ✅ YES (both ways)     |
-| `/oh-my-claudecode:plan "description"` | Start planning naturally                           | ✅ YES                 |
-| `/oh-my-claudecode:review [path]`      | Invoke normally                                    | ✅ YES (unchanged)     |
-| `/oh-my-claudecode:deepsearch "query"` | Say "find" or "search"                             | ✅ YES (auto-detect)   |
-| `/oh-my-claudecode:analyze "target"`   | Say "analyze" — routes to debugger/architect agent | ✅ YES (keyword route) |
-| `/oh-my-claudecode:deepinit [path]`    | Invoke normally                                    | ✅ YES (unchanged)     |
-| `/oh-my-claudecode:git-master`         | Say "git", "commit", "atomic commit"               | ✅ YES (auto-detect)   |
-| `/oh-my-claudecode:frontend-ui-ux`     | Say "UI", "styling", "component", "design"         | ✅ YES (auto-detect)   |
-| `/oh-my-claudecode:note "content"`     | Say "remember this" or "save this"                 | ✅ YES (auto-detect)   |
-| `/oh-my-claudecode:cancel-ralph`       | Say "stop", "cancel", or "abort"                   | ✅ YES (auto-detect)   |
-| `/oh-my-claudecode:omc-doctor`         | Invoke normally                                    | ✅ YES (unchanged)     |
-| All other commands                     | Work exactly as before                             | ✅ YES                 |
-### Magic Keywords
-Include these anywhere in your message to explicitly activate behaviors. Use keywords when you want explicit control (optional):
-| Keyword             | Effect                                   | Example                           |
-| ------------------- | ---------------------------------------- | --------------------------------- |
-| `ralph`             | Persistence mode - won't stop until done | "ralph: refactor the auth system" |
-| `ralplan`           | Iterative planning with consensus        | "ralplan: add OAuth support"      |
-| `ulw` / `ultrawork` | Maximum parallel execution               | "ulw: fix all type errors"        |
-| `plan`              | Planning interview                       | "plan: new API design"            |
-**ralph includes ultrawork:**
-```
-ralph: migrate the entire database
-    ↓
-Persistence (won't stop) + Ultrawork (maximum parallelism) built-in
-```
-**No keywords?** Claude still auto-detects:
-```
-"don't stop until this works"      # Triggers ralph
-"fast, I'm in a hurry"             # Triggers ultrawork
-"help me design the dashboard"     # Triggers planning
-```
-### Natural Cancellation
-Say any of these to stop:
-- "stop"
-- "cancel"
-- "abort"
-- "nevermind"
-- "enough"
-- "halt"
-Claude intelligently determines what to stop:
-```
-If in ralph-loop     → Exit persistence loop
-If in ultrawork      → Return to normal mode
-If in planning       → End planning interview
-If multiple active   → Stop the most recent
-```
-No more `/oh-my-claudecode:cancel-ralph` - just say "cancel"!
-### Migration Steps
-Follow these steps to migrate your existing setup:
-#### 1. Uninstall Old Package (if installed via npm)
-```bash
-npm uninstall -g oh-my-claudecode
-```
-#### 2. Install via Plugin System (Required)
-```bash
-# In Claude Code:
-/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
-/plugin install oh-my-claudecode
-```
-> **Note**: npm/bun global installs are no longer supported. Use the plugin system.
-#### 3. Rename Local Project Directories
-If you have existing projects using the old directory structure:
-```bash
-# In each project directory
-mv .omc .omc
-```
-#### 4. Rename Global Directories
-```bash
-# Global configuration directory
-mv ~/.omc ~/.omc
-# Skills directory
-mv ~/.claude/skills/omc-learned ~/.claude/skills/omc-learned
-# Config directory
-mv ~/.claude/omc ~/.claude/omc
-```
-#### 5. Update Environment Variables
-Update your shell configuration files (`.bashrc`, `.zshrc`, etc.):
-```bash
-# Replace all OMC_* variables with OMC_*
-# Example:
-# OLD: export OMC_ROUTING_ENABLED=true
-# NEW: export OMC_ROUTING_ENABLED=true
-```
-#### 6. Update Scripts and Configurations
-Search for and update any references to:
-- Package name: `oh-my-claudecode` → `oh-my-claudecode`
-- Agent names: Use the mapping table above
-- Commands: Use the new slash commands
-- Directory paths: Update `.omc` → `.omc`
-#### 7. Run One-Time Setup
-In Claude Code, just say "setup omc", "omc setup", or any natural language equivalent.
-This:
-- Downloads latest CLAUDE.md
-- Configures 32 agents
-- Enables auto-behavior detection
-- Activates continuation enforcement
-- Sets up skill composition
-### Verification
-After migration, verify your setup:
-1. **Check installation**:
-   ```bash
-   npm list -g oh-my-claudecode
-   ```
-2. **Verify directories exist**:
-   ```bash
-   ls -la .omc/  # In project directory
-   ls -la ~/.omc/  # Global directory
-   ```
-3. **Test a simple command**:
-   Run `/oh-my-claudecode:omc-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:
-```
-Before: "OK, I need to use /oh-my-claudecode:ultrawork for speed..."
-After:  "I'm in a hurry, go fast!"
-        ↓
-        Claude: "I'm activating ultrawork mode..."
-```
-#### 2. Delegate Always (Automatic)
-Complex work auto-routes to specialist agents:
-```
-Your request              Claude's action
-────────────────────     ────────────────────
-"Refactor the database"   → Delegates to architect
-"Fix the UI colors"       → Delegates to designer
-"Document this API"       → Delegates to writer
-"Search for all errors"   → Delegates to explore
-"Debug this crash"        → Delegates to architect
-```
-You don't ask for delegation - it happens automatically.
-#### 3. Learned Skills (`/oh-my-claudecode:learner`)
-Extract reusable insights from problem-solving:
-```bash
-# After solving a tricky bug:
-"Extract this as a skill"
-    ↓
-Claude learns the pattern and stores it
-    ↓
-Next time keywords match → Solution auto-injects
-```
-Storage:
-- **Project-level**: `.omc/skills/` (version-controlled)
-- **User-level**: `~/.claude/skills/omc-learned/` (portable)
-#### 4. HUD Statusline (Real-Time Orchestration)
-See what Claude is doing in the status bar:
-```
-[OMC] ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | todos:2/5
-```
-Run `/oh-my-claudecode:hud setup` to install. Presets: minimal, focused, full.
-#### 5. Three-Tier Memory System
-Critical knowledge survives context compaction:
-```
-<remember priority>API client at src/api/client.ts</remember>
-    ↓
-Permanently loaded on session start
-    ↓
-Never lost through compaction
-```
-Or use `/oh-my-claudecode:note` to save discoveries manually:
-```bash
-/oh-my-claudecode:note Project uses PostgreSQL with Prisma ORM
-```
-#### 6. Structured Task Tracking (PRD Support)
-**Ralph Loop now uses Product Requirements Documents:**
-```bash
-/oh-my-claudecode:ralph-init "implement OAuth with multiple providers"
-    ↓
-Auto-creates PRD with user stories
-    ↓
-Each story: description + acceptance criteria + pass/fail
-    ↓
-Ralph loops until ALL stories pass
-```
-#### 7. Intelligent Continuation
-**Tasks complete before Claude stops:**
-```
-You: "Implement user dashboard"
-    ↓
-Claude: "I'm activating ralph-loop to ensure completion"
-    ↓
-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.
----
-## v3.0 → v3.1: Notepad Wisdom & Enhanced Features
-### Overview
-Version 3.1 is a minor release adding powerful new features while maintaining full backward compatibility with v3.0.
-### What's New
-#### 1. Notepad Wisdom System
-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.
-#### 4. Session Resume
-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
-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)
----
-## v3.3.x → v3.4.0: Parallel Execution & Advanced Workflows
-### Overview
-Version 3.4.0 introduces powerful parallel execution modes and advanced workflow orchestration while maintaining full backward compatibility with v3.3.x.
-### What's New
-#### 1. Pipeline: Sequential Agent Chaining
-Chain agents with data passing between stages:
-```bash
-/oh-my-claudecode:pipeline explore:haiku -> architect:opus -> executor:sonnet
-```
-**Built-in Presets:**
-- `review` - explore → architect → critic → executor
-- `implement` - planner → executor → tdd-guide
-- `debug` - explore → architect → debugger
-- `research` - parallel(document-specialist, explore) → architect → writer
-- `refactor` - explore → architect-medium → executor-high → qa-tester
-- `security` - explore → security-reviewer → executor → security-reviewer-low
-#### 4. Unified Cancel Command
-Smart cancellation that auto-detects active mode:
-```bash
-/oh-my-claudecode:cancel
-# Or just say: "stop", "cancel", "abort"
-```
-**Auto-detects and cancels:** autopilot, ralph, ultrawork, ultraqa, pipeline
-**Deprecation Notice:**
-Individual cancel commands are deprecated but still work:
-- `/oh-my-claudecode:cancel-ralph` (deprecated)
-- `/oh-my-claudecode:cancel-ultraqa` (deprecated)
-- `/oh-my-claudecode:cancel-ultrawork` (deprecated)
-- `/oh-my-claudecode:cancel-autopilot` (deprecated)
-Use `/oh-my-claudecode:cancel` instead.
-#### 6. Explore-High Agent
-Opus-powered architectural search for complex codebase exploration:
-```typescript
-Task(
-  (subagent_type = "oh-my-claudecode:explore-high"),
-  (model = "opus"),
-  (prompt = "Find all authentication-related code patterns..."),
-);
-```
-**Best for:** Architectural analysis, cross-cutting concerns, complex refactoring planning
-#### 7. State Management Standardization
-State files now use standardized paths:
-**Standard paths:**
-- Local: `.omc/state/{name}.json`
-- Global: `~/.omc/state/{name}.json`
-Legacy locations are auto-migrated on read.
-#### 8. Keyword Conflict Resolution
-When multiple execution mode keywords are present:
-**Conflict Resolution Priority:**
-| Priority | Condition | Result |
-|----------|-----------|--------|
-| 1 (highest) | Single explicit keyword | That mode wins |
-| 2 | Generic "fast"/"parallel" only | Read from config (`defaultExecutionMode`) |
-| 3 (lowest) | No config file | Default to `ultrawork` |
-**Explicit mode keywords:** `ulw`, `ultrawork`
-**Generic keywords:** `fast`, `parallel`
-Users set their default mode preference via `/oh-my-claudecode:omc-setup`.
-### Migration Steps
-Version 3.4.0 is a drop-in upgrade. No migration required!
-```bash
-npm update -g oh-my-claudecode
-```
-All existing configurations, plans, and workflows continue working unchanged.
-### New Configuration Options
-#### Default Execution Mode
-Set your preferred execution mode in `~/.claude/.omc-config.json`:
-```json
-{
-  "defaultExecutionMode": "ultrawork"
-}
-```
-When you use generic keywords like "fast" or "parallel" without explicit mode keywords, this setting determines which mode activates.
-### Breaking Changes
-None. All v3.3.x features and commands continue to work in v3.4.0.
-### New Tools Available
-Once upgraded, you automatically gain access to:
-- Ultrapilot (parallel autopilot)
-- Swarm coordination
-- Pipeline workflows
-- Unified cancel command
-- Explore-high agent
-### Best Practices for v3.4.0
-#### When to Use Each Mode
-| Scenario                | Recommended Mode | Why                                            |
-| ----------------------- | ---------------- | ---------------------------------------------- |
-| Multi-component systems | `team N:executor` | Parallel workers handle independent components |
-| Many small fixes        | `team N:executor` | Atomic task claiming prevents duplicate work   |
-| Sequential dependencies | `pipeline`        | Data passes between stages                     |
-| Single complex task     | `autopilot`      | Full autonomous execution                      |
-| Must complete           | `ralph`          | Persistence guarantee                          |
-#### Keyword Usage
-**Explicit mode control (v3.4.0):**
-```bash
-"ulw: fix all errors"           # ultrawork (explicit)
-"fast: implement feature"       # reads defaultExecutionMode config
-```
-**Natural language (still works):**
-```bash
-"don't stop until done"         # ralph
-"parallel execution"            # reads defaultExecutionMode
-"build me a todo app"           # autopilot
-```
-### Verification
-After upgrading, verify new features:
-1. **Check installation**:
-   ```bash
-   npm list -g oh-my-claudecode
-   ```
-2. **Test unified cancel**:
-   ```bash
-   /oh-my-claudecode:cancel
-   ```
-3. **Check state directory**:
-   ```bash
-   ls -la .omc/state/
-   ```
----
-## v3.x → v4.0: Major Architecture Overhaul
-### Overview
-Version 4.0 is a complete architectural redesign focusing on scalability, maintainability, and developer experience.
-### What's Coming
-⚠️ **This section is under active development as v4.0 is being built.**
-#### Planned Changes
-1. **Modular Architecture**
-   - Plugin system for extensibility
-   - Core/extension separation
-   - Better dependency management
-2. **Enhanced Agent System**
-   - Improved agent lifecycle management
-   - Better error recovery
-   - Performance optimizations
-3. **Improved Configuration**
-   - Unified config schema
-   - Better validation
-   - Migration tooling
-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-claudecode) for announcements
-- Check [CHANGELOG.md](../CHANGELOG.md) for detailed release notes
-- Join discussions in GitHub Issues
----
-## Common Scenarios Across Versions
-### Scenario 1: Quick Implementation Task
-**2.x Workflow:**
-```
-/oh-my-claudecode:ultrawork "implement the todo list feature"
-```
-**3.0+ Workflow:**
-```
-"implement the todo list feature quickly"
-    ↓
-Claude: "I'm activating ultrawork for maximum parallelism"
-```
-**Result:** Same outcome, more natural interaction.
-### Scenario 2: Complex Debugging
-**2.x Workflow:**
-```
-/oh-my-claudecode:ralph "debug the memory leak"
-```
-**3.0+ Workflow:**
-```
-"there's a memory leak in the worker process - don't stop until we fix it"
-    ↓
-Claude: "I'm activating ralph-loop to ensure completion"
-```
-**Result:** Ralph-loop with more context from your natural language.
-### Scenario 3: Strategic Planning
-**2.x Workflow:**
-```
-/oh-my-claudecode:planner "design the new authentication system"
-```
-**3.0+ Workflow:**
-```
-"plan the new authentication system"
-    ↓
-Claude: "I'm starting a planning session"
-    ↓
-Interview begins automatically
-```
-**Result:** Planning interview triggered by natural language.
-### Scenario 4: Stopping Work
-**2.x Workflow:**
-```
-/oh-my-claudecode:cancel-ralph
-```
-**3.0+ Workflow:**
-```
-"stop"
-```
-**Result:** Claude intelligently cancels the active operation.
----
-## Configuration Options
-### Project-Scoped Configuration (Recommended)
-Apply oh-my-claudecode to current project only:
-```
-/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.
----
-## FAQ
-**Q: Do I have to use keywords?**
-A: No. Keywords are optional shortcuts. Claude auto-detects intent without them.
-**Q: Will my old commands break?**
-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`, and `/oh-my-claudecode:plan` work. Note: `/oh-my-claudecode:planner` now redirects to `/oh-my-claudecode:plan`.
-**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 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?**
-A: Keywords are explicit shortcuts. Natural language triggers auto-detection. Both work.
----
-## Need Help?
-- **Diagnose issues**: Run `/oh-my-claudecode:omc-doctor`
-- **See all commands**: Run `/oh-my-claudecode:omc-help`
-- **View real-time status**: Run `/oh-my-claudecode:hud setup`
-- **Review detailed changelog**: See [CHANGELOG.md](../CHANGELOG.md)
-- **Report bugs**: [GitHub Issues](https://github.com/Yeachan-Heo/oh-my-claudecode/issues)
----
-## What's Next?
-Now that you understand the migration:
-1. **For immediate impact**: Start using keywords (`ralph`, `ulw`, `plan`) in your work
-2. **For full power**: Read [docs/CLAUDE.md](CLAUDE.md) to understand orchestration
-3. **For advanced usage**: Check [docs/ARCHITECTURE.md](ARCHITECTURE.md) for deep dives
-4. **For team onboarding**: Share this guide with teammates
-Welcome to oh-my-claudecode!