claudecode-omc 4.9.4 → 5.0.0

package/docs/REFERENCE.md

@@ -1,843 +0,0 @@
-# Reference Documentation
-
-Complete reference for oh-my-claudecode. For quick start, see the main [README.md](../README.md).
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [CLI Commands: ask/team/session](#cli-commands-askteamsession)
-- [Legacy MCP Team Runtime Tools (Deprecated)](#legacy-mcp-team-runtime-tools-deprecated)
-- [Agents (29 Total)](#agents-29-total)
-- [Skills (32 Total)](#skills-32-total)
-- [Slash Commands](#slash-commands)
-- [Hooks System](#hooks-system)
-- [Magic Keywords](#magic-keywords)
-- [Platform Support](#platform-support)
-- [Performance Monitoring](#performance-monitoring)
-- [Troubleshooting](#troubleshooting)
-- [Changelog](#changelog)
-
----
-
-## Installation
-
-**Only the Claude Code Plugin method is supported.** Other installation methods (npm, bun, curl) are deprecated and may not work correctly.
-
-### Claude Code Plugin (Required)
-
-```bash
-# Step 1: Add the marketplace
-/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
-
-# Step 2: Install the plugin
-/plugin install oh-my-claudecode
-```
-
-This integrates directly with Claude Code's plugin system and uses Node.js hooks.
-
-> **Note**: Direct npm/bun global installs are **not supported**. The plugin system handles all installation and hook setup automatically.
-
-### Requirements
-
-- [Claude Code](https://docs.anthropic.com/claude-code) installed
-- One of:
-  - **Claude Max/Pro subscription** (recommended for individuals)
-  - **Anthropic API key** (`ANTHROPIC_API_KEY` environment variable)
-
----
-
-## Configuration
-
-### Project-Scoped Configuration (Recommended)
-
-Configure omc for the current project only:
-
-```
-/oh-my-claudecode:omc-setup --local
-```
-
-- Creates `./.claude/CLAUDE.md` in your current project
-- Configuration applies only to this project
-- Won't affect other projects or global settings
-- **Safe**: Preserves your global CLAUDE.md
-
-### Global Configuration
-
-Configure omc for all Claude Code sessions:
-
-```
-/oh-my-claudecode:omc-setup
-```
-
-- Creates `~/.claude/CLAUDE.md` globally
-- Configuration applies to all projects
-- **Warning**: Completely overwrites existing `~/.claude/CLAUDE.md`
-
-### What Configuration Enables
-
-| Feature           | Without     | With omc Config            |
-| ----------------- | ----------- | -------------------------- |
-| Agent delegation  | Manual only | Automatic based on task    |
-| Keyword detection | Disabled    | ultrawork, search |
-| Todo continuation | Basic       | Enforced completion        |
-| Model routing     | Default     | Smart tier selection       |
-| Skill composition | None        | Auto-combines skills       |
-
-### Configuration Precedence
-
-If both configurations exist, **project-scoped takes precedence** over global:
-
-```
-./.claude/CLAUDE.md  (project)   →  Overrides  →  ~/.claude/CLAUDE.md  (global)
-```
-
-### Environment Variables
-
-| Variable                   | Default              | Description                                                                                                                                                                                                                                                                 |
-| -------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OMC_STATE_DIR`            | _(unset)_            | Centralized state directory. When set, OMC stores state at `$OMC_STATE_DIR/{project-id}/` instead of `{worktree}/.omc/`. This preserves state across worktree deletions. The project identifier is derived from the git remote URL (or worktree path for local-only repos). |
-| `OMC_BRIDGE_SCRIPT`        | _(auto-detected)_    | Path to the Python bridge script                                                                                                                                                                                                                                            |
-| `OMC_PARALLEL_EXECUTION`   | `true`               | Enable/disable parallel agent execution                                                                                                                                                                                                                                     |
-| `OMC_CODEX_DEFAULT_MODEL`  | _(provider default)_ | Default model for Codex CLI workers                                                                                                                                                                                                                                         |
-| `OMC_GEMINI_DEFAULT_MODEL` | _(provider default)_ | Default model for Gemini CLI workers                                                                                                                                                                                                                                        |
-| `OMC_LSP_TIMEOUT_MS`       | `15000`              | Timeout (ms) for LSP requests. Increase for large repos or slow language servers                                                                                                                                                                                            |
-| `DISABLE_OMC`              | _(unset)_            | Set to any value to disable all OMC hooks                                                                                                                                                                                                                                   |
-| `OMC_SKIP_HOOKS`           | _(unset)_            | Comma-separated list of hook names to skip                                                                                                                                                                                                                                  |
-
-#### Centralized State with `OMC_STATE_DIR`
-
-By default, OMC stores state in `{worktree}/.omc/`. This is lost when worktrees are deleted. To preserve state across worktree lifecycles, set `OMC_STATE_DIR`:
-
-```bash
-# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
-export OMC_STATE_DIR="$HOME/.claude/omc"
-```
-
-This resolves to `~/.claude/omc/{project-identifier}/` where the project identifier uses a hash of the git remote URL (stable across worktrees/clones) with a fallback to the directory path hash for local-only repos.
-
-If both a legacy `{worktree}/.omc/` directory and a centralized directory exist, OMC logs a notice and uses the centralized directory. You can then migrate data from the legacy directory and remove it.
-
-### When to Re-run Setup
-
-- **First time**: Run after installation (choose project or global)
-- **After updates**: Re-run to get the latest configuration
-- **Different machines**: Run on each machine where you use Claude Code
-- **New projects**: Run `/oh-my-claudecode:omc-setup --local` in each project that needs omc
-
-> **NOTE**: After updating the plugin (via `npm update`, `git pull`, or Claude Code's plugin update), you MUST re-run `/oh-my-claudecode:omc-setup` to apply the latest CLAUDE.md changes.
-
-### Remote OMC / Remote MCP Access
-
-Issue #1653 asked whether OMC can "connect to a remote OMC" so one development machine can browse files on lab/test machines without opening an interactive SSH session.
-
-The narrow, coherent answer today is:
-
-- **Supported**: connect to a **remote MCP server** through the unified MCP registry
-- **Not implemented**: a general "OMC cluster", shared remote filesystem view, or automatic remote-OMC federation
-- **Still appropriate for full remote shell workflows**: SSH, worktrees, or a mounted/network filesystem
-
-If a remote host already exposes an MCP endpoint, add it to your MCP registry (or Claude settings and then re-run setup so OMC syncs the registry to Codex too):
-
-```json
-{
-  "mcpServers": {
-    "remoteOmc": {
-      "url": "https://lab.example.com/mcp",
-      "timeout": 30
-    }
-  }
-}
-```
-
-This gives OMC a coherent remote connection surface for MCP-backed tools. It does **not** make all remote files magically appear as a local workspace, and it does **not** replace SSH for arbitrary shell access.
-
-If you need richer cross-machine behavior in the future, that would require a separate authenticated remote execution/filesystem design rather than stretching the current local-workspace architecture.
-
-### Agent Customization
-
-Edit agent files in `~/.claude/agents/` to customize behavior:
-
-```yaml
----
-name: architect
-description: Your custom description
-tools: Read, Grep, Glob, Bash, Edit
-model: opus # or sonnet, haiku
----
-Your custom system prompt here...
-```
-
-### Project-Level Config
-
-Create `.claude/CLAUDE.md` in your project for project-specific instructions:
-
-```markdown
-# Project Context
-
-This is a TypeScript monorepo using:
-
-- Bun runtime
-- React for frontend
-- PostgreSQL database
-
-## Conventions
-
-- Use functional components
-- All API routes in /src/api
-- Tests alongside source files
-```
-
-### Stop Callback Notification Tags
-
-Configure tags for Telegram/Discord stop callbacks with `omc config-stop-callback`.
-
-```bash
-# Set/replace tags
-omc config-stop-callback telegram --enable --token <bot_token> --chat <chat_id> --tag-list "@alice,bob"
-omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678,role:987654321098765432"
-
-# Incremental updates
-omc config-stop-callback telegram --add-tag charlie
-omc config-stop-callback discord --remove-tag @here
-omc config-stop-callback discord --clear-tags
-
-# Inspect current callback config
-omc config-stop-callback telegram --show
-omc config-stop-callback discord --show
-```
-
-Tag behavior:
-
-- Telegram: `alice` is normalized to `@alice`
-- Discord: supports `@here`, `@everyone`, numeric user IDs (`<@id>`), and role tags (`role:<id>` -> `<@&id>`)
-- `file` callbacks ignore tag options
-
----
-
-## CLI Commands: ask/team/session
-
-### `omc ask`
-
-```bash
-omc ask claude "review this patch"
-omc ask codex "review this patch from a security perspective"
-omc ask gemini --prompt "suggest UX improvements"
-omc ask claude --agent-prompt executor --prompt "create an implementation plan"
-```
-
-- Provider matrix: `claude | codex | gemini`
-- Artifacts: `.omc/artifacts/ask/{provider}-{slug}-{timestamp}.md`
-- Canonical env vars: `OMC_ASK_ADVISOR_SCRIPT`, `OMC_ASK_ORIGINAL_TASK`
-- Phase-1 aliases (deprecated warning): `OMX_ASK_ADVISOR_SCRIPT`, `OMX_ASK_ORIGINAL_TASK`
-- Skill entrypoint: `/oh-my-claudecode:ask <claude|codex|gemini> <prompt>` routes to this command
-
-### `omc team` (CLI runtime surface)
-
-```bash
-omc team 2:codex "review auth flow"
-omc team status review-auth-flow
-omc team shutdown review-auth-flow --force
-omc team api claim-task --input '{"team_name":"auth-review","task_id":"1","worker":"worker-1"}' --json
-```
-
-Supported entrypoints: direct start (`omc team [N:agent] "<task>"`), `status`, `shutdown`, and `api`.
-
-Topology behavior:
-- inside classic tmux (`$TMUX` set): reuse the current tmux surface for split-pane or `--new-window` layouts
-- inside cmux (`CMUX_SURFACE_ID` without `$TMUX`): launch a detached tmux session for team workers
-- plain terminal: launch a detached tmux session for team workers
-
-### `omc session search`
-
-```bash
-omc session search "team leader stale"
-omc session search notify-hook --since 7d
-omc session search provider-routing --project all --json
-```
-
-- Defaults to the current project/worktree scope
-- Use `--project all` to search across all local Claude project transcripts
-- Supports `--limit`, `--session`, `--since`, `--context`, `--case-sensitive`, and `--json`
-- MCP/tool surface: `session_search` returns structured JSON for agents and automations
-
----
-
-## Legacy MCP Team Runtime Tools (Deprecated, Opt-In Only)
-
-The Team MCP runtime server is **not enabled by default**. If manually enabled, runtime tools are still **CLI-only deprecated** and return a deterministic error envelope:
-
-```json
-{
-  "code": "deprecated_cli_only",
-  "message": "Legacy team MCP runtime tools are deprecated. Use the omc team CLI instead."
-}
-```
-
-Use `omc team ...` replacements instead:
-
-| Tool                   | Purpose                                                    |
-| ---------------------- | ---------------------------------------------------------- |
-| `omc_run_team_start`   | **Deprecated** → `omc team [N:agent-type] "<task>"`        |
-| `omc_run_team_status`  | **Deprecated** → `omc team status <team-name>`             |
-| `omc_run_team_wait`    | **Deprecated** → monitor via `omc team status <team-name>` |
-| `omc_run_team_cleanup` | **Deprecated** → `omc team shutdown <team-name> [--force]` |
-
-Optional compatibility enablement (manual only):
-
-```json
-{
-  "mcpServers": {
-    "team": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/bridge/team-mcp.cjs"]
-    }
-  }
-}
-```
-
-### Runtime status semantics
-
-- **Artifact-first terminal convergence**: team monitors prefer finalized state artifacts when present.
-- **Deterministic parse-failure handling**: malformed result artifacts are treated as terminal `failed`.
-- **Cleanup scope**: shutdown/cleanup only clears `.omc/state/team/{teamName}` for the target team (never sibling teams).
-
-## Agents (29 Total)
-
-Always use `oh-my-claudecode:` prefix when calling via Task tool.
-
-### By Domain and Tier
-
-| Domain           | LOW (Haiku)             | MEDIUM (Sonnet)       | HIGH (Opus)         |
-| ---------------- | ----------------------- | --------------------- | ------------------- |
-| **Analysis**     | `architect-low`         | `architect-medium`    | `architect`         |
-| **Execution**    | `executor-low`          | `executor`            | `executor-high`     |
-| **Search**       | `explore`               | -                     | `explore-high`      |
-| **Research**     | -                       | `document-specialist` | -                   |
-| **Frontend**     | `designer-low`          | `designer`            | `designer-high`     |
-| **Docs**         | `writer`                | -                     | -                   |
-| **Visual**       | -                       | `vision`              | -                   |
-| **Planning**     | -                       | -                     | `planner`           |
-| **Critique**     | -                       | -                     | `critic`            |
-| **Pre-Planning** | -                       | -                     | `analyst`           |
-| **Testing**      | -                       | `qa-tester`           | -                   |
-| **Tracing**      | -                       | `tracer`              | -                   |
-| **Security**     | `security-reviewer-low` | -                     | `security-reviewer` |
-| **Build**        | -                       | `debugger`            | -                   |
-| **TDD**          | -                       | `test-engineer`       | -                   |
-| **Code Review**  | -                       | -                     | `code-reviewer`     |
-| **Data Science** | -                       | `scientist`           | `scientist-high`    |
-
-### Agent Selection Guide
-
-| Task Type                    | Best Agent                    | Model  |
-| ---------------------------- | ----------------------------- | ------ |
-| Quick code lookup            | `explore`                     | haiku  |
-| Find files/patterns          | `explore`                     | haiku  |
-| Complex architectural search | `explore-high`                | opus   |
-| Simple code change           | `executor-low`                | haiku  |
-| Feature implementation       | `executor`                    | sonnet |
-| Complex refactoring          | `executor-high`               | opus   |
-| Debug simple issue           | `architect-low`               | haiku  |
-| Debug complex issue          | `architect`                   | opus   |
-| UI component                 | `designer`                    | sonnet |
-| Complex UI system            | `designer-high`               | opus   |
-| Write docs/comments          | `writer`                      | haiku  |
-| Research docs/APIs           | `document-specialist` (repo docs first; optional Context Hub / `chub`) | sonnet |
-| Analyze images/diagrams      | `vision`                      | sonnet |
-| Strategic planning           | `planner`                     | opus   |
-| Review/critique plan         | `critic`                      | opus   |
-| Pre-planning analysis        | `analyst`                     | opus   |
-| Test CLI interactively       | `qa-tester`                   | sonnet |
-| Evidence-driven causal tracing | `tracer`                    | sonnet |
-| Security review              | `security-reviewer`           | opus   |
-| Quick security scan          | `security-reviewer-low`       | haiku  |
-| Fix build errors             | `debugger`                    | sonnet |
-| Simple build fix             | `debugger` (model=haiku)      | haiku  |
-| TDD workflow                 | `test-engineer`               | sonnet |
-| Quick test suggestions       | `test-engineer` (model=haiku) | haiku  |
-| Code review                  | `code-reviewer`               | opus   |
-| Quick code check             | `code-reviewer` (model=haiku) | haiku  |
-| Data analysis/stats          | `scientist`                   | sonnet |
-| Quick data inspection        | `scientist` (model=haiku)     | haiku  |
-| Complex ML/hypothesis        | `scientist-high`              | opus   |
-
----
-
-## Skills (32 Total)
-
-Includes **31 canonical skills + 1 deprecated alias** (`psm`). Runtime truth comes from the builtin skill loader scanning `skills/*/SKILL.md` and expanding aliases declared in frontmatter.
-
-| Skill                     | Description                                                      | Manual Command                              |
-| ------------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
-| `ai-slop-cleaner`         | Anti-slop cleanup workflow with optional reviewer-only `--review` pass | `/oh-my-claudecode:ai-slop-cleaner`         |
-| `ask`                     | Ask Claude, Codex, or Gemini via local CLI and capture a reusable artifact | `/oh-my-claudecode:ask`               |
-| `autopilot`               | Full autonomous execution from idea to working code              | `/oh-my-claudecode:autopilot`               |
-| `cancel`                  | Unified cancellation for active modes                            | `/oh-my-claudecode:cancel`                  |
-| `ccg`                     | Tri-model workflow via `ask codex` + `ask gemini`, then Claude synthesis | `/oh-my-claudecode:ccg`                     |
-| `configure-notifications` | Configure notification integrations (Telegram, Discord, Slack) via natural language | `/oh-my-claudecode:configure-notifications` |
-| `deep-dive`               | Two-stage trace → deep-interview pipeline with context handoff   | `/oh-my-claudecode:deep-dive`               |
-| `deep-interview`          | Socratic deep interview with ambiguity gating                    | `/oh-my-claudecode:deep-interview`          |
-| `deepinit`                | Generate hierarchical AGENTS.md docs                             | `/oh-my-claudecode:deepinit`                |
-| `external-context`        | Parallel document-specialist research                            | `/oh-my-claudecode:external-context`        |
-| `hud`                     | Configure HUD/statusline                                         | `/oh-my-claudecode:hud`                     |
-| `learner`                 | Extract reusable skill from session                              | `/oh-my-claudecode:learner`                 |
-| `mcp-setup`               | Configure MCP servers                                            | `/oh-my-claudecode:mcp-setup`               |
-| `omc-doctor`              | Diagnose and fix installation issues                             | `/oh-my-claudecode:omc-doctor`              |
-| `omc-plan`                | Planning workflow (`/plan` safe alias)                           | `/oh-my-claudecode:omc-plan`                |
-| `omc-reference`           | Detailed OMC agent/tools/team/commit reference skill             | Auto-loaded reference only                  |
-| `omc-setup`               | One-time setup wizard                                            | `/oh-my-claudecode:omc-setup`               |
-| `omc-teams`               | Spawn `claude`/`codex`/`gemini` tmux workers for parallel execution | `/oh-my-claudecode:omc-teams`             |
-| `project-session-manager` | Manage isolated dev environments (git worktrees + tmux)          | `/oh-my-claudecode:project-session-manager` |
-| `psm` | **Deprecated** compatibility alias for `project-session-manager` | `/oh-my-claudecode:psm` |
-| `ralph`                   | Persistence loop until verified completion                       | `/oh-my-claudecode:ralph`                   |
-| `ralplan`                 | Consensus planning alias for `/omc-plan --consensus`             | `/oh-my-claudecode:ralplan`                 |
-| `release`                 | Automated release workflow                                       | `/oh-my-claudecode:release`                 |
-| `setup`                   | Unified setup entrypoint for install, diagnostics, and MCP configuration | `/oh-my-claudecode:setup`              |
-| `sciomc`                  | Parallel scientist orchestration                                 | `/oh-my-claudecode:sciomc`                  |
-| `skill`                   | Manage local skills (list/add/remove/search/edit)                | `/oh-my-claudecode:skill`                   |
-| `team`                    | Coordinated multi-agent workflow                                 | `/oh-my-claudecode:team`                    |
-| `trace`                   | Evidence-driven tracing lane with parallel tracer hypotheses     | `/oh-my-claudecode:trace`                   |
-| `ultraqa`                 | QA cycle until goal is met                                       | `/oh-my-claudecode:ultraqa`                 |
-| `ultrawork`               | Maximum parallel throughput mode                                 | `/oh-my-claudecode:ultrawork`               |
-| `visual-verdict`          | Structured visual QA verdict for screenshot/reference comparisons | `/oh-my-claudecode:visual-verdict`          |
-| `writer-memory`           | Agentic memory system for writing projects                       | `/oh-my-claudecode:writer-memory`           |
-
-
----
-
-## Slash Commands
-
-Each installed skill is exposed as `/oh-my-claudecode:<skill-name>`. The skills table above is the full runtime-backed list; the commands below highlight common entrypoints and aliases. Compatibility keyword modes like `deep-analyze` and `tdd` are prompt-triggered behaviors, not standalone slash commands.
-
-| Command                                     | Description                                                                                   |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `/oh-my-claudecode:ai-slop-cleaner <target>`    | Run the anti-slop cleanup workflow (`--review` for reviewer-only pass)                    |
-| `/oh-my-claudecode:ask <claude|codex|gemini> <prompt>` | Route a prompt through the selected advisor CLI and capture an ask artifact         |
-| `/oh-my-claudecode:autopilot <task>`            | Full autonomous execution                                                                  |
-| `/oh-my-claudecode:configure-notifications`     | Configure notification integrations                                                       |
-| `/oh-my-claudecode:deep-dive <problem>`         | Run the trace → deep-interview pipeline                                                   |
-| `/oh-my-claudecode:deep-interview <idea>`       | Socratic interview with ambiguity scoring before execution                                 |
-| `/oh-my-claudecode:deepinit [path]`             | Index codebase with hierarchical AGENTS.md files                                           |
-| `/oh-my-claudecode:mcp-setup`                   | Configure MCP servers                                                                      |
-| `/oh-my-claudecode:omc-doctor`                  | Diagnose and fix installation issues                                                       |
-| `/oh-my-claudecode:omc-plan <description>`      | Start planning session (supports consensus structured deliberation)                        |
-| `/oh-my-claudecode:omc-setup`                   | One-time setup wizard                                                                      |
-| `/oh-my-claudecode:omc-teams <N>:<agent> <task>`       | Spawn `claude`/`codex`/`gemini` tmux workers for legacy parallel execution                |
-| `/oh-my-claudecode:project-session-manager <arguments>` | Manage isolated dev environments with git worktrees + tmux                         |
-| `/oh-my-claudecode:psm <arguments>`             | Deprecated alias for project session manager                                               |
-| `/oh-my-claudecode:ralph <task>`                | Self-referential loop until task completion (`--critic=architect|critic|codex`)           |
-| `/oh-my-claudecode:ralplan <description>`       | Iterative planning with consensus structured deliberation (`--deliberate` for high-risk mode) |
-| `/oh-my-claudecode:release`                     | Automated release workflow                                                                 |
-| `/oh-my-claudecode:setup`                       | Unified setup entrypoint (`setup`, `setup doctor`, `setup mcp`)                           |
-| `/oh-my-claudecode:sciomc <topic>`              | Parallel research orchestration                                                            |
-| `/oh-my-claudecode:team <N>:<agent> <task>`     | Coordinated native team workflow                                                           |
-| `/oh-my-claudecode:trace`                       | Evidence-driven tracing lane that orchestrates parallel tracer hypotheses in team mode     |
-| `/oh-my-claudecode:ultraqa <goal>`              | Autonomous QA cycling workflow                                                             |
-| `/oh-my-claudecode:ultrawork <task>`            | Maximum performance mode with parallel agents                                              |
-| `/oh-my-claudecode:visual-verdict <task>`       | Structured visual QA verdict for screenshot/reference comparisons                          |
-
-### Skill Pipeline Metadata (Preview)
-
-Built-in skills and slash-loaded skills can now declare a lightweight pipeline/handoff contract in frontmatter:
-
-```yaml
-pipeline: [deep-interview, omc-plan, autopilot]
-next-skill: omc-plan
-next-skill-args: --consensus --direct
-handoff: .omc/specs/deep-interview-{slug}.md
-```
-
-When present, OMC appends a standardized **Skill Pipeline** section to the rendered skill prompt so the current stage, handoff artifact, and explicit next `Skill("oh-my-claudecode:...")` invocation are carried forward consistently.
-
-### Skills 2.0 Compatibility (MVP)
-
-OMC's canonical project-local skill directory remains `.omc/skills/`, but the runtime now also reads compatibility skills from `.agents/skills/`.
-
-For builtin and slash-loaded skills, OMC also appends a standardized **Skill Resources** section when the skill directory contains bundled assets such as helper scripts, templates, or support libraries. This helps agents reuse packaged skill resources instead of recreating them ad hoc.
-
----
-
-## Hooks System
-
-Oh-my-claudecode includes 31 lifecycle hooks that enhance Claude Code's behavior.
-
-### Execution Mode Hooks
-
-| Hook              | Description                                                                 |
-| ----------------- | --------------------------------------------------------------------------- |
-| `autopilot`       | Full autonomous execution from idea to working code                         |
-| `ultrawork`       | Maximum parallel agent execution                                            |
-| `ralph`           | Persistence until verified complete                                         |
-| `team-pipeline`   | Native team staged pipeline orchestration                                   |
-| `ultraqa`         | QA cycling until goal met                                                   |
-| `mode-registry`   | Tracks active execution mode state (including team/ralph/ultrawork/ralplan) |
-| `persistent-mode` | Maintains mode state across sessions                                        |
-
-### Core Hooks
-
-| Hook                 | Description                                           |
-| -------------------- | ----------------------------------------------------- |
-| `rules-injector`     | Dynamic rules injection with YAML frontmatter parsing |
-| `omc-orchestrator`   | Enforces orchestrator behavior and delegation         |
-| `auto-slash-command` | Automatic slash command detection and execution       |
-| `keyword-detector`   | Magic keyword detection (ultrawork, ralph, etc.)      |
-| `todo-continuation`  | Ensures todo list completion                          |
-| `notepad`            | Compaction-resilient memory system                    |
-| `learner`            | Skill extraction from conversations                   |
-
-### Context & Recovery
-
-| Hook                        | Description                                      |
-| --------------------------- | ------------------------------------------------ |
-| `recovery`                  | Edit error, session, and context window recovery |
-| `preemptive-compaction`     | Context usage monitoring to prevent limits       |
-| `pre-compact`               | Pre-compaction processing                        |
-| `directory-readme-injector` | README context injection                         |
-
-### Quality & Validation
-
-| Hook                       | Description                                            |
-| -------------------------- | ------------------------------------------------------ |
-| `comment-checker`          | BDD detection and directive filtering                  |
-| `thinking-block-validator` | Extended thinking validation                           |
-| `empty-message-sanitizer`  | Empty message handling                                 |
-| `permission-handler`       | Permission requests and validation                     |
-| `think-mode`               | Extended thinking detection                            |
-| `code-simplifier`          | Auto-simplify recently modified files on Stop (opt-in) |
-
-### Code Simplifier Hook
-
-The `code-simplifier` Stop hook automatically delegates recently modified source files to the
-`code-simplifier` agent after each Claude turn. It is **disabled by default** and must be
-explicitly enabled via the global OMC config file:
-
-- Linux/Unix default: `${XDG_CONFIG_HOME:-~/.config}/omc/config.json`
-- macOS/Windows legacy/default path: `~/.omc/config.json`
-- Existing legacy `~/.omc/config.json` continues to be read as a fallback where applicable.
-
-**Enable:**
-
-```json
-{
-  "codeSimplifier": {
-    "enabled": true
-  }
-}
-```
-
-**Full config options:**
-
-```json
-{
-  "codeSimplifier": {
-    "enabled": true,
-    "extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
-    "maxFiles": 10
-  }
-}
-```
-
-| Option       | Type       | Default                                         | Description                        |
-| ------------ | ---------- | ----------------------------------------------- | ---------------------------------- |
-| `enabled`    | `boolean`  | `false`                                         | Opt-in to automatic simplification |
-| `extensions` | `string[]` | `[".ts",".tsx",".js",".jsx",".py",".go",".rs"]` | File extensions to consider        |
-| `maxFiles`   | `number`   | `10`                                            | Maximum files simplified per turn  |
-
-**How it works:**
-
-1. When Claude stops, the hook runs `git diff HEAD --name-only` to find modified files
-2. If modified source files are found, the hook injects a message asking Claude to delegate to the `code-simplifier` agent
-3. The agent simplifies the files for clarity and consistency without changing behavior
-4. A turn-scoped marker prevents the hook from triggering more than once per turn cycle
-
-### Coordination & Environment
-
-| Hook                      | Description                              |
-| ------------------------- | ---------------------------------------- |
-| `subagent-tracker`        | Tracks spawned sub-agents                |
-| `session-end`             | Session termination handling             |
-| `non-interactive-env`     | CI/non-interactive environment handling  |
-| `agent-usage-reminder`    | Reminder to use specialized agents       |
-| `background-notification` | Background task completion notifications |
-| `plugin-patterns`         | Plugin pattern detection                 |
-| `setup`                   | Initial setup and configuration          |
-
----
-
-## Magic Keywords
-
-Use these trigger phrases in natural language prompts to activate enhanced modes:
-
-| Keyword                                                 | Effect                                                                                        |
-| ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `ultrawork`, `ulw`                                      | Activates parallel agent orchestration                                                        |
-| `autopilot`, `build me`, `I want a`                     | Full autonomous execution                                                                     |
-| `deslop`, `anti-slop`, cleanup/refactor + slop smells         | Anti-slop cleanup workflow (`ai-slop-cleaner`)                                               |
-| `ralph`, `don't stop`, `must complete`                  | Persistence until verified complete                                                           |
-| `ccg`, `claude-codex-gemini`                            | Claude-Codex-Gemini orchestration                                                             |
-| `ralplan`                                               | Iterative planning consensus with structured deliberation (`--deliberate` for high-risk mode) |
-| `deep interview`, `ouroboros`                           | Deep Socratic interview with mathematical clarity gating                                      |
-| `deepsearch`, `search the codebase`, `find in codebase` | Codebase-focused search mode                                                                  |
-| `deepanalyze`, `deep-analyze`                           | Deep analysis mode                                                                            |
-| `ultrathink`                                            | Deep reasoning mode                                                                           |
-| `tdd`, `test first`, `red green`                        | TDD workflow enforcement                                                                      |
-| `cancelomc`, `stopomc`                                  | Unified cancellation                                                                          |
-
-### Examples
-
-```bash
-# In Claude Code:
-
-# Maximum parallelism
-ultrawork implement user authentication with OAuth
-
-# Enhanced search
-deepsearch for files that import the utils module
-
-# Deep analysis
-deep-analyze why the tests are failing
-
-# Autonomous execution
-autopilot: build a todo app with React
-
-# Parallel autonomous execution
-team 3:executor "build a fullstack todo app"
-
-# Persistence mode
-ralph: refactor the authentication module
-
-# Planning session
-ralplan this feature
-
-# TDD workflow
-tdd: implement password validation
-
-# Stop active orchestration
-stopomc
-```
-
----
-
-## Platform Support
-
-### Operating Systems
-
-| Platform    | Install Method              | Hook Type      |
-| ----------- | --------------------------- | -------------- |
-| **Windows** | WSL2 recommended (see note) | Node.js (.mjs) |
-| **macOS**   | Claude Code Plugin          | Bash (.sh)     |
-| **Linux**   | Claude Code Plugin          | Bash (.sh)     |
-
-> **Note**: Bash hooks are fully portable across macOS and Linux (no GNU-specific dependencies).
-
-> **Windows**: Native Windows (win32) support is experimental. OMC requires tmux, which is not available on native Windows. **WSL2 is strongly recommended** for Windows users. See the [WSL2 installation guide](https://learn.microsoft.com/en-us/windows/wsl/install). Native Windows issues may have limited support.
-
-> **Advanced**: Set `OMC_USE_NODE_HOOKS=1` to use Node.js hooks on macOS/Linux.
-
-### Available Tools
-
-| Tool          | Status       | Description           |
-| ------------- | ------------ | --------------------- |
-| **Read**      | ✅ Available | Read files            |
-| **Write**     | ✅ Available | Create files          |
-| **Edit**      | ✅ Available | Modify files          |
-| **Bash**      | ✅ Available | Run shell commands    |
-| **Glob**      | ✅ Available | Find files by pattern |
-| **Grep**      | ✅ Available | Search file contents  |
-| **WebSearch** | ✅ Available | Search the web        |
-| **WebFetch**  | ✅ Available | Fetch web pages       |
-| **Task**      | ✅ Available | Spawn subagents       |
-| **TodoWrite** | ✅ Available | Track tasks           |
-
-### LSP Tools (Real Implementation)
-
-| Tool                        | Status         | Description                                 |
-| --------------------------- | -------------- | ------------------------------------------- |
-| `lsp_hover`                 | ✅ Implemented | Get type info and documentation at position |
-| `lsp_goto_definition`       | ✅ Implemented | Jump to symbol definition                   |
-| `lsp_find_references`       | ✅ Implemented | Find all usages of a symbol                 |
-| `lsp_document_symbols`      | ✅ Implemented | Get file outline (functions, classes, etc.) |
-| `lsp_workspace_symbols`     | ✅ Implemented | Search symbols across workspace             |
-| `lsp_diagnostics`           | ✅ Implemented | Get errors, warnings, hints                 |
-| `lsp_prepare_rename`        | ✅ Implemented | Check if rename is valid                    |
-| `lsp_rename`                | ✅ Implemented | Rename symbol across project                |
-| `lsp_code_actions`          | ✅ Implemented | Get available refactorings                  |
-| `lsp_code_action_resolve`   | ✅ Implemented | Get details of a code action                |
-| `lsp_servers`               | ✅ Implemented | List available language servers             |
-| `lsp_diagnostics_directory` | ✅ Implemented | Project-level type checking                 |
-
-> **Note**: LSP tools require language servers to be installed (typescript-language-server, pylsp, rust-analyzer, gopls, etc.). Use `lsp_servers` to check installation status.
-
-### AST Tools (ast-grep Integration)
-
-| Tool               | Status         | Description                                  |
-| ------------------ | -------------- | -------------------------------------------- |
-| `ast_grep_search`  | ✅ Implemented | Pattern-based code search using AST matching |
-| `ast_grep_replace` | ✅ Implemented | Pattern-based code transformation            |
-
-> **Note**: AST tools use [@ast-grep/napi](https://ast-grep.github.io/) for structural code matching. Supports meta-variables like `$VAR` (single node) and `$$$` (multiple nodes).
-
----
-
-## Performance Monitoring
-
-oh-my-claudecode includes comprehensive monitoring for agent performance, token usage, and debugging parallel workflows.
-
-For complete documentation, see **[Performance Monitoring Guide](./PERFORMANCE-MONITORING.md)**.
-
-### Quick Overview
-
-| Feature                 | Description                                     | Access                               |
-| ----------------------- | ----------------------------------------------- | ------------------------------------ |
-| **Agent Observatory**   | Real-time agent status, efficiency, bottlenecks | HUD / API                            |
-| **Session-End Summaries** | Persisted per-session summaries and callback payloads | `.omc/sessions/*.json`, `session-end` |
-| **Session Replay**      | Event timeline for post-session analysis        | `.omc/state/agent-replay-*.jsonl`    |
-| **Session Search**      | Search prior local transcript/session artifacts  | `omc session search`, `session_search` |
-| **Intervention System** | Auto-detection of stale agents, cost overruns   | Automatic                            |
-
-### CLI Commands
-
-```bash
-omc hud                              # Render the current HUD statusline
-omc team status <team-name>          # Inspect a running team job
-tail -20 .omc/state/agent-replay-*.jsonl
-ls .omc/sessions/*.json
-```
-
-### HUD Presets
-
-Enable a supported preset for agent and context visibility in your status line:
-
-```json
-{
-  "omcHud": {
-    "preset": "focused"
-  }
-}
-```
-
-### External Resources
-
-- **[MarginLab.ai](https://marginlab.ai)** - SWE-Bench-Pro performance tracking with statistical significance testing for detecting Claude model degradation
-
----
-
-## Troubleshooting
-
-### Diagnose Installation Issues
-
-```bash
-/oh-my-claudecode:omc-doctor
-```
-
-Checks for:
-
-- Missing dependencies
-- Configuration errors
-- Hook installation status
-- Agent availability
-- Skill registration
-
-### Configure HUD Statusline
-
-```bash
-/oh-my-claudecode:hud setup
-```
-
-Installs or repairs the HUD statusline for real-time status updates.
-
-### HUD Configuration (settings.json)
-
-Configure HUD elements in `~/.claude/settings.json`:
-
-```json
-{
-  "omcHud": {
-    "preset": "focused",
-    "elements": {
-      "cwd": true,
-      "gitRepo": true,
-      "gitBranch": true,
-      "showTokens": true
-    }
-  }
-}
-```
-
-| Element      | Description                                                                                       | Default |
-| ------------ | ------------------------------------------------------------------------------------------------- | ------- |
-| `cwd`        | Show current working directory                                                                    | `false` |
-| `gitRepo`    | Show git repository name                                                                          | `false` |
-| `gitBranch`  | Show current git branch                                                                           | `false` |
-| `omcLabel`   | Show [OMC] label                                                                                  | `true`  |
-| `contextBar` | Show context window usage                                                                         | `true`  |
-| `agents`     | Show active agents count                                                                          | `true`  |
-| `todos`      | Show todo progress                                                                                | `true`  |
-| `ralph`      | Show ralph loop status                                                                            | `true`  |
-| `autopilot`  | Show autopilot status                                                                             | `true`  |
-| `showTokens` | Show transcript-derived token usage (`tok:i1.2k/o340`, plus `r...` reasoning and `s...` session total when reliable) | `false` |
-
-Additional `omcHud` layout options (top-level):
-
-| Option     | Description                                                                       | Default    |
-| ---------- | --------------------------------------------------------------------------------- | ---------- |
-| `maxWidth` | Maximum HUD line width (terminal columns)                                         | unset      |
-| `wrapMode` | `truncate` (ellipsis) or `wrap` (break at `\|` boundaries) when `maxWidth` is set | `truncate` |
-
-Available presets: `minimal`, `focused`, `full`, `dense`, `analytics`, `opencode`
-
-### Common Issues
-
-| Issue                 | Solution                                                                         |
-| --------------------- | -------------------------------------------------------------------------------- |
-| Commands not found    | Re-run `/oh-my-claudecode:omc-setup`                                             |
-| Hooks not executing   | Check hook permissions: `chmod +x ~/.claude/hooks/**/*.sh`                       |
-| Agents not delegating | Verify CLAUDE.md is loaded: check `./.claude/CLAUDE.md` or `~/.claude/CLAUDE.md` |
-| LSP tools not working | Install language servers: `npm install -g typescript-language-server`            |
-| Token limit errors    | Use `/oh-my-claudecode:` for token-efficient execution                           |
-
-### Auto-Update
-
-Oh-my-claudecode includes a silent auto-update system that checks for updates in the background.
-
-Features:
-
-- **Rate-limited**: Checks at most once every 24 hours
-- **Concurrent-safe**: Lock file prevents simultaneous update attempts
-- **Cross-platform**: Works on both macOS and Linux
-
-To manually update, re-run the plugin install command or use Claude Code's built-in update mechanism.
-
-### Uninstall
-
-Use Claude Code's plugin management:
-
-```
-/plugin uninstall oh-my-claudecode@oh-my-claudecode
-```
-
-Or manually remove the installed files:
-
-```bash
-rm ~/.claude/agents/{architect,document-specialist,explore,designer,writer,vision,critic,analyst,executor,qa-tester}.md
-rm ~/.claude/commands/{analyze,autopilot,deepsearch,plan,review,ultrawork}.md
-```
-
----
-
-## Changelog
-
-See [CHANGELOG.md](../CHANGELOG.md) for version history and release notes.
-
----
-
-## License
-
-MIT - see [LICENSE](../LICENSE)
-
-## Credits
-
-Inspired by [oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) by code-yeongyu.