claudecode-omc 4.8.4 → 4.9.3

package/docs/ARCHITECTURE.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-oh-my-claudecode enables Claude Code to orchestrate specialized agents through a skill-based routing system.
+oh-my-claudecode enables Claude Code to orchestrate specialized agents through a skill-based routing system. It is built on four interlocking systems: **Hooks** detect lifecycle events, **Skills** inject behaviors, **Agents** execute specialized work, and **State** tracks progress across context resets.
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
@@ -36,33 +36,82 @@ oh-my-claudecode enables Claude Code to orchestrate specialized agents through a
                                                             └─────────────────┘
 ```
 
-## Core Concepts
+The four systems flow in sequence:
 
-### Skills
+```
+User Input --> Hooks (event detection) --> Skills (behavior injection)
+           --> Agents (task execution) --> State (progress tracking)
+```
 
-Skills are **behavior injections** that modify how the orchestrator operates. Instead of swapping agents, we inject capabilities through composable skills:
+---
 
-- **Execution Skills**: Primary task handlers (`default`, `planner`, `orchestrate`)
-- **Enhancement Skills**: Additional capabilities (`ultrawork`, `git-master`, `frontend-ui-ux`)
-- **Guarantee Skills**: Completion enforcement (`ralph`)
+## Agent System
 
-Skills can stack and compose:
-```
-Task: "ultrawork: refactor API with proper commits"
-Skills: ultrawork + default + git-master
-```
+### Overview
+
+OMC provides 19 specialized agents organized into 4 lanes. Each agent is invoked as `oh-my-claudecode:<agent-name>` and runs on the appropriate model tier.
+
+### Build/Analysis Lane
+
+Covers the full development lifecycle from exploration to verification.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `explore` | haiku | Codebase discovery, file/symbol mapping |
+| `analyst` | opus | Requirements analysis, hidden constraint discovery |
+| `planner` | opus | Task sequencing, execution plan creation |
+| `architect` | opus | System design, interface definition, trade-off analysis |
+| `debugger` | sonnet | Root-cause analysis, build error resolution |
+| `executor` | sonnet | Code implementation, refactoring |
+| `verifier` | sonnet | Completion verification, test adequacy confirmation |
+| `tracer` | sonnet | Evidence-driven causal tracing, competing hypothesis analysis |
+
+### Review Lane
+
+Quality gates before handoff. Catches correctness and security issues.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `security-reviewer` | sonnet | Security vulnerabilities, trust boundaries, authn/authz review |
+| `code-reviewer` | opus | Comprehensive code review, API contracts, backward compatibility |
+
+### Domain Lane
+
+Domain experts called in when needed.
+
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `test-engineer` | sonnet | Test strategy, coverage, flaky-test hardening |
+| `designer` | sonnet | UI/UX architecture, interaction design |
+| `writer` | haiku | Documentation, migration notes |
+| `qa-tester` | sonnet | Interactive CLI/service runtime validation via tmux |
+| `scientist` | sonnet | Data analysis, statistical research |
+| `git-master` | sonnet | Git operations, commits, rebase, history management |
+| `document-specialist` | sonnet | External documentation, API/SDK reference lookup |
+| `code-simplifier` | opus | Code clarity, simplification, maintainability improvement |
 
-### Agents
+### Coordination Lane
 
-32 specialized agents organized by complexity tier:
+Challenges plans and designs made by other agents. A plan passes only when no gaps can be found.
 
-| Tier | Model | Use For |
-|------|-------|---------|
-| LOW | Haiku | Quick lookups, simple operations |
-| MEDIUM | Sonnet | Standard implementations |
-| HIGH | Opus | Complex reasoning, architecture |
+| Agent | Default Model | Role |
+|-------|---------------|------|
+| `critic` | opus | Gap analysis of plans and designs, multi-angle review |
 
-See [REFERENCE.md](./REFERENCE.md) for the complete agent roster.
+### Model Routing
+
+OMC uses three model tiers:
+
+| Tier | Model | Characteristics | Cost |
+|------|-------|-----------------|------|
+| LOW | haiku | Fast and inexpensive | Low |
+| MEDIUM | sonnet | Balanced performance and cost | Medium |
+| HIGH | opus | Highest-quality reasoning | High |
+
+Default assignments by role:
+- **haiku**: Fast lookups and simple tasks (`explore`, `writer`)
+- **sonnet**: Code implementation, debugging, testing (`executor`, `debugger`, `test-engineer`)
+- **opus**: Architecture, strategic analysis, review (`architect`, `planner`, `critic`, `code-reviewer`)
 
 ### Delegation
 
@@ -76,11 +125,61 @@ Task(
 )
 ```
 
-Categories like `visual-engineering` and `ultrabrain` auto-select model tier, temperature, and thinking budget.
+**Delegate to agents when:**
+- Multiple files need to change
+- Refactoring is required
+- Debugging or root-cause analysis is needed
+- Code review or security review is needed
+- Planning or research is required
+
+**Handle directly when:**
+- Simple file lookups
+- Straightforward question answering
+- Single-command operations
+
+### Agent Selection Guide
+
+| Task Type | Recommended Agent | Model |
+|-----------|-------------------|-------|
+| Quick code lookup | `explore` | haiku |
+| Feature implementation | `executor` | sonnet |
+| Complex refactoring | `executor` (model=opus) | opus |
+| Simple bug fix | `debugger` | sonnet |
+| Complex debugging | `architect` | opus |
+| UI component | `designer` | sonnet |
+| Documentation | `writer` | haiku |
+| Test strategy | `test-engineer` | sonnet |
+| Security review | `security-reviewer` | sonnet |
+| Code review | `code-reviewer` | opus |
+| Data analysis | `scientist` | sonnet |
+
+### Typical Agent Workflow
+
+```
+explore --> analyst --> planner --> critic --> executor --> verifier
+(discover)  (analyze)   (sequence)  (review)   (implement)  (confirm)
+```
+
+### Agent Role Boundaries
+
+| Agent | Does | Does Not |
+|-------|------|----------|
+| `architect` | Code analysis, debugging, verification | Requirements gathering, planning |
+| `analyst` | Find requirements gaps | Code analysis, planning |
+| `planner` | Create task plans | Requirements analysis, plan review |
+| `critic` | Review plan quality | Requirements analysis, code analysis |
 
-## Skill Composition
+---
 
-Skills compose in layers:
+## Skills System
+
+### Overview
+
+Skills are **behavior injections** that modify how the orchestrator operates. Instead of swapping agents, skills add capabilities on top of existing agents. OMC provides 31 skills total (28 user-invocable + 3 internal/pipeline).
+
+### Skill Layers
+
+Skills compose in three layers:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -103,31 +202,361 @@ Skills compose in layers:
 
 **Formula:** `[Execution Skill] + [0-N Enhancements] + [Optional Guarantee]`
 
+Example:
+```
+Task: "ultrawork: refactor API with proper commits"
+Active skills: ultrawork + default + git-master
+```
+
+### How to Invoke Skills
+
+**Slash commands:**
+```bash
+/oh-my-claudecode:autopilot build me a todo app
+/oh-my-claudecode:ralph refactor the auth module
+/oh-my-claudecode:team 3:executor "implement fullstack app"
+```
+
+**Magic keywords** — include a keyword in natural language and the skill activates automatically:
+```bash
+autopilot build me a todo app      # activates autopilot
+ralph: refactor the auth module    # activates ralph
+ultrawork implement OAuth          # activates ultrawork
+```
+
+### Core Workflow Skills
+
+#### autopilot
+Full autonomous 5-stage pipeline from idea to working code.
+- Trigger: `autopilot`, `build me`, `I want a`
+```bash
+autopilot build me a REST API with authentication
+```
+
+#### ralph
+Repeating loop that does not stop until work is verified complete. The `verifier` agent confirms completion before the loop exits.
+- Trigger: `ralph`, `don't stop`, `must complete`
+```bash
+ralph: refactor the authentication module
+```
+
+#### ultrawork
+Maximum parallelism — launches multiple agents simultaneously.
+- Trigger: `ultrawork`, `ulw`
+```bash
+ultrawork implement user authentication with OAuth
+```
+
+#### team
+Coordinates N Claude agents with a 5-stage pipeline: `plan → prd → exec → verify → fix`
+```bash
+/oh-my-claudecode:team 3:executor "implement fullstack todo app"
+```
+
+#### ccg (Claude-Codex-Gemini)
+Fans out to Codex and Gemini simultaneously; Claude synthesizes the results.
+- Trigger: `ccg`, `claude-codex-gemini`
+```bash
+ccg: review this authentication implementation
+```
+
+#### ralplan
+Iterative planning: Planner, Architect, and Critic loop until they reach consensus.
+- Trigger: `ralplan`
+```bash
+ralplan this feature
+```
+
+### Utility Skills
+
+| Skill | Description | Command |
+|-------|-------------|---------|
+| `cancel` | Cancel active execution mode | `/oh-my-claudecode:cancel` |
+| `hud` | Status bar configuration | `/oh-my-claudecode:hud` |
+| `omc-setup` | Initial setup wizard | `/oh-my-claudecode:omc-setup` |
+| `omc-doctor` | Diagnose installation | `/oh-my-claudecode:omc-doctor` |
+| `learner` | Extract reusable skills from session | `/oh-my-claudecode:learner` |
+| `skill` | Manage local skills (list/add/remove) | `/oh-my-claudecode:skill` |
+| `trace` | Evidence-driven causal tracing | `/oh-my-claudecode:trace` |
+| `release` | Automated release workflow | `/oh-my-claudecode:release` |
+| `deepinit` | Generate hierarchical AGENTS.md | `/oh-my-claudecode:deepinit` |
+| `deep-interview` | Socratic deep interview | `/oh-my-claudecode:deep-interview` |
+| `sciomc` | Parallel scientist agent orchestration | `/oh-my-claudecode:sciomc` |
+| `external-context` | Parallel document-specialist research | `/oh-my-claudecode:external-context` |
+| `ai-slop-cleaner` | Clean AI expression patterns | `/oh-my-claudecode:ai-slop-cleaner` |
+| `writer-memory` | Memory system for writing projects | `/oh-my-claudecode:writer-memory` |
+
+### Magic Keyword Reference
+
+| Keyword | Effect |
+|---------|--------|
+| `ultrawork`, `ulw`, `uw` | Parallel agent orchestration |
+| `autopilot`, `build me`, `I want a`, `handle it all`, `end to end`, `e2e this` | Autonomous execution pipeline |
+| `ralph`, `don't stop`, `must complete`, `until done` | Loop until verified complete |
+| `ccg`, `claude-codex-gemini` | 3-model orchestration |
+| `ralplan` | Consensus-based planning |
+| `deep interview`, `ouroboros` | Socratic deep interview |
+| `code review`, `review code` | Comprehensive code review mode |
+| `security review`, `review security` | Security-focused review mode |
+| `deepsearch`, `search the codebase`, `find in codebase` | Codebase search mode |
+| `deepanalyze`, `deep-analyze` | Deep analysis mode |
+| `ultrathink`, `think hard`, `think deeply` | Deep reasoning mode |
+| `tdd`, `test first`, `red green` | TDD workflow |
+| `deslop`, `anti-slop` | AI expression cleanup |
+| `cancelomc`, `stopomc` | Cancel active execution mode |
+
+### Keyword Detection Sources
+
+Keywords are processed in two places:
+
+| Source | Role | Customizable |
+|--------|------|--------------|
+| `config.jsonc` `magicKeywords` | 4 categories (ultrawork, search, analyze, ultrathink) | Yes |
+| `keyword-detector` hook | 11+ triggers (autopilot, ralph, ccg, etc.) | No |
+
+The `autopilot`, `ralph`, and `ccg` triggers are hardcoded in the hook and cannot be changed through config.
+
+---
+
+## Hooks
+
+### Overview
+
+Hooks are code that reacts to Claude Code lifecycle events. They run automatically when a user submits a prompt, uses a tool, or starts/ends a session. OMC implements agent delegation, keyword detection, and state persistence through this hook system.
+
+### Lifecycle Events
+
+Claude Code provides 11 lifecycle events. OMC registers hooks on these events:
+
+| Event | When It Fires | OMC Usage |
+|-------|---------------|-----------|
+| `UserPromptSubmit` | User submits a prompt | Magic keyword detection, skill injection |
+| `SessionStart` | Session begins | Initial setup, project memory load |
+| `PreToolUse` | Before a tool is used | Permission validation, parallel execution hints |
+| `PermissionRequest` | Permission requested | Bash command permission handling |
+| `PostToolUse` | After a tool is used | Result validation, project memory update |
+| `PostToolUseFailure` | After a tool fails | Error recovery handling |
+| `SubagentStart` | Subagent starts | Agent tracking |
+| `SubagentStop` | Subagent stops | Agent tracking, output verification |
+| `PreCompact` | Before context compaction | Preserve critical information, save project memory |
+| `Stop` | Claude is about to stop | Persistent mode enforcement, code simplification |
+| `SessionEnd` | Session ends | Session data cleanup |
+
+### system-reminder Injection
+
+Hooks inject additional context to Claude via `<system-reminder>` tags:
+
+```xml
+<system-reminder>
+hook success: Success
+</system-reminder>
+```
+
+Injected pattern meanings:
+
+| Pattern | Meaning |
+|---------|---------|
+| `hook success: Success` | Hook ran normally, continue as planned |
+| `hook additional context: ...` | Additional context information, take note |
+| `[MAGIC KEYWORD: ...]` | Magic keyword detected, execute indicated skill |
+| `The boulder never stops` | ralph/ultrawork mode is active |
+
+### Key Hooks
+
+**keyword-detector** — fires on `UserPromptSubmit`. Detects magic keywords in user input and activates the corresponding skill.
+
+**persistent-mode** — fires on `Stop`. When a persistent mode (ralph, ultrawork) is active, prevents Claude from stopping until work is verified complete.
+
+**pre-compact** — fires on `PreCompact`. Saves critical information to the notepad before the context window is compressed.
+
+**subagent-tracker** — fires on `SubagentStart` and `SubagentStop`. Tracks currently running agents; validates output on stop.
+
+**context-guard-stop** — fires on `Stop`. Monitors context usage and warns when approaching the limit.
+
+**code-simplifier** — fires on `Stop`. Disabled by default. When enabled, automatically simplifies modified files when Claude stops.
+
+Enable via config:
+```json
+{
+  "codeSimplifier": {
+    "enabled": true,
+    "extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
+    "maxFiles": 10
+  }
+}
+```
+
+### Hook Registration Structure
+
+OMC hooks are declared in `hooks.json`. Each hook is a Node.js script with a timeout:
+
+```json
+{
+  "UserPromptSubmit": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node scripts/keyword-detector.mjs",
+          "timeout": 5
+        }
+      ]
+    }
+  ]
+}
+```
+
+- `matcher`: Pattern the hook responds to (`*` matches all input)
+- `timeout`: Timeout in seconds
+- `type`: Always `"command"` (runs an external command)
+
+### Disabling Hooks
+
+Disable all hooks:
+```bash
+export DISABLE_OMC=1
+```
+
+Skip specific hooks (comma-separated):
+```bash
+export OMC_SKIP_HOOKS="keyword-detector,persistent-mode"
+```
+
+---
+
 ## State Management
 
-State files follow standardized locations:
+### Overview
 
-**Local Project State:**
-- `.omc/state/{name}.json` - Session state (ultrapilot, swarm, pipeline)
-- `.omc/notepads/{plan-name}/` - Plan-scoped wisdom capture
+OMC stores task progress and project knowledge in the `.omc/` directory. The state system preserves critical information even when context compaction resets the context window.
+
+### Directory Structure
+
+```
+.omc/
+├── state/                    # Per-mode state files
+│   ├── autopilot-state.json  # autopilot progress
+│   ├── ralph-state.json      # ralph loop state
+│   ├── team/                 # team task state
+│   └── sessions/             # per-session state
+│       └── {sessionId}/
+├── notepad.md                # Compaction-resistant memo pad
+├── project-memory.json       # Project knowledge store
+├── plans/                    # Execution plans
+├── notepads/                 # Per-plan knowledge capture
+│   └── {plan-name}/
+│       ├── learnings.md
+│       ├── decisions.md
+│       ├── issues.md
+│       └── problems.md
+├── autopilot/                # autopilot artifacts
+│   └── spec.md
+├── research/                 # Research results
+└── logs/                     # Execution logs
+```
 
 **Global State:**
-- `~/.omc/state/{name}.json` - User preferences and global config
+- `~/.omc/state/{name}.json` — user preferences and global config
 
 Legacy locations are auto-migrated on read.
 
-## Hooks
+### Notepad
+
+**File:** `.omc/notepad.md`
+
+The notepad survives context compaction. Content written to it persists even after the context window is reset.
 
-oh-my-claudecode includes 31 hooks in `src/hooks/` for lifecycle events:
+Notes can be saved using the `notepad_write_manual` MCP tool or the `notepad_write_priority` tool for persistent notes.
 
-| Event | Purpose |
-|-------|---------|
-| `UserPromptSubmit` | Keyword detection, mode activation |
-| `Stop` | Continuation enforcement, session end |
-| `PreToolUse` | Permission validation |
-| `PostToolUse` | Error recovery, rules injection |
+**MCP Tools:**
 
-See [REFERENCE.md](./REFERENCE.md) for the complete hooks list.
+| Tool | Description |
+|------|-------------|
+| `notepad_read` | Read notepad contents |
+| `notepad_write_priority` | Write high-priority memo (permanent retention) |
+| `notepad_write_working` | Write working memo |
+| `notepad_write_manual` | Write manual memo |
+| `notepad_prune` | Clean up old memos |
+| `notepad_stats` | View notepad statistics |
+
+**How it works:**
+1. On `PreCompact` event, important information is saved to the notepad
+2. After compaction, notepad contents are re-injected into context
+3. Agents use the notepad to recover previous context
+
+### Project Memory
+
+**File:** `.omc/project-memory.json`
+
+Project memory is a persistent store for project-level knowledge. It survives across sessions.
+
+**MCP Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `project_memory_read` | Read project memory |
+| `project_memory_write` | Overwrite entire project memory |
+| `project_memory_add_note` | Add a note |
+| `project_memory_add_directive` | Add a directive |
+
+**Lifecycle integration:**
+- `SessionStart`: Load project memory and inject into context
+- `PostToolUse`: Extract project knowledge from tool results and save
+- `PreCompact`: Save project memory before context compaction
+
+### Session Scope
+
+**Path:** `.omc/state/sessions/{sessionId}/`
+
+Stores state isolated per session. Multiple sessions on the same project run simultaneously without state conflicts.
+
+### Plan Notepad (Per-Plan Knowledge Capture)
+
+**Path:** `.omc/notepads/{plan-name}/`
+
+Stores learnings from each execution plan separately.
+
+| File | Contents |
+|------|----------|
+| `learnings.md` | Discovered patterns, successful approaches |
+| `decisions.md` | Architecture decisions and rationale |
+| `issues.md` | Problems and blockers |
+| `problems.md` | Technical debt and cautions |
+
+All entries are timestamped automatically.
+
+### Centralized State (Optional)
+
+By default, state is stored in the project's `.omc/` directory and is deleted when the worktree is removed.
+
+To preserve state across worktree deletions, set the `OMC_STATE_DIR` environment variable:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export OMC_STATE_DIR="$HOME/.claude/omc"
+```
+
+State is then stored at `~/.claude/omc/{project-identifier}/`. The project identifier is a hash of the Git remote URL, so the same repository shares state across different worktrees.
+
+### Persistent Memory Tags
+
+For critical information, use `<remember>` tags:
+
+```xml
+<!-- Retained for 7 days -->
+<remember>API endpoint changed to /v2</remember>
+
+<!-- Retained permanently -->
+<remember priority>Never access production DB directly</remember>
+```
+
+| Tag | Retention |
+|-----|-----------|
+| `<remember>` | 7 days |
+| `<remember priority>` | Permanent |
+
+---
 
 ## Verification Protocol
 
@@ -144,6 +573,8 @@ The verification module ensures work completion with evidence:
 
 Evidence must be fresh (within 5 minutes) and include actual command output.
 
+---
+
 ## For More Details
 
 - **Complete Reference**: See [REFERENCE.md](./REFERENCE.md)

package/docs/CLAUDE.md

@@ -1,5 +1,5 @@
 <!-- OMC:START -->
-<!-- OMC:VERSION:4.7.10 -->
+<!-- OMC:VERSION:4.8.5 -->
 
 # oh-my-claudecode - Intelligent Multi-Agent Orchestration
 

package/docs/COMPATIBILITY.md

@@ -168,7 +168,7 @@ The `plugin.json` defines the plugin's metadata and tools:
 
 ### Skill and Agent Discovery
 
-**Skills** are discovered from `SKILL.md` files in the skills directory. Each skill directory must contain a SKILL.md with frontmatter:
+**Skills** are discovered from `SKILL.md` files in the skills directory. OMC's canonical project-local write target remains `.omc/skills/`, and it now also reads project-local compatibility skills from `.agents/skills/`. Each skill directory must contain a SKILL.md with frontmatter:
 
 ```markdown
 ---
@@ -223,6 +223,23 @@ Located at `~/.claude/settings.json`:
 }
 ```
 
+### Remote MCP / Remote OMC Shape
+
+OMC can sync and preserve **remote MCP** entries in the unified registry. That is the supported narrow answer to "connect to a remote OMC":
+
+```json
+{
+  "mcpServers": {
+    "remoteOmc": {
+      "url": "https://lab.example.com/mcp",
+      "timeout": 30
+    }
+  }
+}
+```
+
+This supports remote MCP endpoints. It does **not** create a general multi-host OMC cluster or a transparent shared remote filesystem view.
+
 ### Plugin-Embedded MCP Servers
 
 Plugins can define MCP servers in their manifest:

package/docs/LOCAL_PLUGIN_INSTALL.md

@@ -2,6 +2,14 @@
 
 How to install oh-my-claudecode from a local development directory as a Claude Code plugin.
 
+## When to use this guide
+
+Use this document for **local development checkouts and git worktrees** where you want Claude Code to load the plugin from your current repo state.
+
+- **Marketplace/plugin users**: prefer the README quick-start flow
+- **npm users**: prefer `npm i -g oh-my-claude-sisyphus@latest`
+- **Local-dev/worktree users**: use this guide so the installed plugin matches the branch/worktree you are editing
+
 ## Quick Install
 
 ```bash
@@ -11,7 +19,10 @@ claude plugin marketplace add /path/to/oh-my-claudecode
 # 2. Install the plugin from the local marketplace
 claude plugin install oh-my-claudecode@oh-my-claudecode
 
-# 3. Restart Claude Code to pick up the plugin
+# 3. Re-run setup inside Claude Code so CLAUDE.md / skills reflect this checkout
+/setup
+
+# 4. Restart Claude Code to pick up the plugin
 ```
 
 ## Commands Reference
@@ -58,7 +69,7 @@ The plugin requires a `plugin.json` manifest:
 
 ## Development Workflow
 
-After making changes to the plugin:
+After making changes to the plugin (including from a linked git worktree):
 
 ```bash
 # 1. Build (if TypeScript changes)
@@ -70,7 +81,10 @@ claude plugin marketplace update oh-my-claudecode
 # 3. Update the installed plugin
 claude plugin update oh-my-claudecode@oh-my-claudecode
 
-# 4. Restart Claude Code session
+# 4. Re-run setup in Claude Code so prompts/skills match the refreshed plugin
+/setup
+
+# 5. Restart Claude Code session
 ```
 
 ## Vs. npm Global Install