claudecode-omc 4.5.7 → 4.7.4

package/docs/REFERENCE.md

@@ -8,8 +8,10 @@ Complete reference for oh-my-claudecode. For quick start, see the main [README.m
 
 - [Installation](#installation)
 - [Configuration](#configuration)
+- [CLI Commands: ask/team](#cli-commands-askteam)
+- [Legacy MCP Team Runtime Tools (Deprecated)](#legacy-mcp-team-runtime-tools-deprecated)
 - [Agents (28 Total)](#agents-28-total)
-- [Skills (37 Total)](#skills-37-total)
+- [Skills (38 Total)](#skills-38-total)
 - [Slash Commands](#slash-commands)
 - [Hooks System](#hooks-system)
 - [Magic Keywords](#magic-keywords)
@@ -76,13 +78,13 @@ Configure omc for all Claude Code sessions:
 
 ### What Configuration Enables
 
-| Feature | Without | With omc Config |
-|---------|---------|-----------------|
-| Agent delegation | Manual only | Automatic based on task |
-| Keyword detection | Disabled | ultrawork, search, analyze |
-| Todo continuation | Basic | Enforced completion |
-| Model routing | Default | Smart tier selection |
-| Skill composition | None | Auto-combines skills |
+| Feature           | Without     | With omc Config            |
+| ----------------- | ----------- | -------------------------- |
+| Agent delegation  | Manual only | Automatic based on task    |
+| Keyword detection | Disabled    | ultrawork, search, analyze |
+| Todo continuation | Basic       | Enforced completion        |
+| Model routing     | Default     | Smart tier selection       |
+| Skill composition | None        | Auto-combines skills       |
 
 ### Configuration Precedence
 
@@ -94,15 +96,16 @@ If both configurations exist, **project-scoped takes precedence** over 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 |
-| `DISABLE_OMC` | _(unset)_ | Set to any value to disable all OMC hooks |
-| `OMC_SKIP_HOOKS` | _(unset)_ | Comma-separated list of hook names to skip |
+| 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`
 
@@ -135,9 +138,8 @@ Edit agent files in `~/.claude/agents/` to customize behavior:
 name: architect
 description: Your custom description
 tools: Read, Grep, Glob, Bash, Edit
-model: opus  # or sonnet, haiku
+model: opus # or sonnet, haiku
 ---
-
 Your custom system prompt here...
 ```
 
@@ -149,11 +151,13 @@ Create `.claude/CLAUDE.md` in your project for project-specific instructions:
 # 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
@@ -179,124 +183,188 @@ 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
+
+### `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 shortcuts: `/oh-my-claudecode:ask-codex` and `/oh-my-claudecode:ask-gemini` route 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`.
+
+---
+
+## 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 (28 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` | - |
-| **Security** | `security-reviewer-low` | - | `security-reviewer` |
-| **Build** | - | `build-fixer` | - |
-| **TDD** | - | `test-engineer` | - |
-| **Code Review** | - | - | `code-reviewer` |
-| **Data Science** | - | `scientist` | `scientist-high` |
+| 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`           | -                   |
+| **Security**     | `security-reviewer-low` | -                     | `security-reviewer` |
+| **Build**        | -                       | `build-fixer`         | -                   |
+| **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` | 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 |
-| Security review | `security-reviewer` | opus |
-| Quick security scan | `security-reviewer-low` | haiku |
-| Fix build errors | `build-fixer` | sonnet |
-| Simple build fix | `build-fixer` (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 |
+| 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`         | 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 |
+| Security review              | `security-reviewer`           | opus   |
+| Quick security scan          | `security-reviewer-low`       | haiku  |
+| Fix build errors             | `build-fixer`                 | sonnet |
+| Simple build fix             | `build-fixer` (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 (37 Total)
-
-### Core Skills
-
-| Skill | Description | Manual Command |
-|-------|-------------|----------------|
-| `orchestrate` | Multi-agent orchestration mode | - |
-| `autopilot` | Full autonomous execution from idea to working code | `/oh-my-claudecode:autopilot` |
-| `ultrawork` | Maximum performance with parallel agents | `/oh-my-claudecode:ultrawork` |
-| `ultrapilot` | Parallel autopilot with 3-5x speedup | `/oh-my-claudecode:ultrapilot` |
-| `team` | N coordinated agents on shared task list using native teams | `/oh-my-claudecode:team` |
-| `swarm` | **Deprecated** compatibility facade over team orchestration (use `team`) | `/oh-my-claudecode:swarm` |
-| `pipeline` | Sequential agent chaining | `/oh-my-claudecode:pipeline` |
-| `ralph` | Self-referential development until completion | `/oh-my-claudecode:ralph` |
-| `ralph-init` | Initialize PRD for structured task tracking | `/oh-my-claudecode:ralph-init` |
-| `ultraqa` | Autonomous QA cycling workflow | `/oh-my-claudecode:ultraqa` |
-| `plan` | Start planning session (consensus mode uses RALPLAN-DR structured deliberation) | `/oh-my-claudecode:plan` |
-| `ralplan` | Iterative planning (Planner+Architect+Critic) with structured deliberation; short mode default, `--deliberate` for high-risk pre-mortem + expanded test plan | `/oh-my-claudecode:ralplan` |
-| `review` | Review work plans with critic | `/oh-my-claudecode:review` |
-
-### Enhancement Skills
-
-| Skill | Description | Manual Command |
-|-------|-------------|----------------|
-| `deepinit` | Hierarchical AGENTS.md codebase documentation | `/oh-my-claudecode:deepinit` |
-| `deepsearch` | Thorough multi-strategy codebase search | `/oh-my-claudecode:deepsearch` |
-| `analyze` | Deep analysis and investigation | `/oh-my-claudecode:analyze` |
-| `sciomc` | Parallel scientist orchestration | `/oh-my-claudecode:sciomc` |
-| `frontend-ui-ux` | Designer-turned-developer UI/UX expertise | (silent activation) |
-| `git-master` | Git expert for atomic commits and history | (silent activation) |
-| `tdd` | TDD enforcement: test-first development | `/oh-my-claudecode:tdd` |
-| `learner` | Extract reusable skill from session | `/oh-my-claudecode:learner` |
-| `build-fix` | Fix build and TypeScript errors | `/oh-my-claudecode:build-fix` |
-| `code-review` | Comprehensive code review | `/oh-my-claudecode:code-review` |
-| `security-review` | Security vulnerability detection | `/oh-my-claudecode:security-review` |
-
-### Utility Skills
-
-| Skill | Description | Manual Command |
-|-------|-------------|----------------|
-| `note` | Save notes to compaction-resilient notepad | `/oh-my-claudecode:note` |
-| `cancel` | Unified cancellation for all modes | `/oh-my-claudecode:cancel` |
-| `omc-setup` | One-time setup wizard | `/oh-my-claudecode:omc-setup` |
-| `omc-doctor` | Diagnose and fix installation issues | `/oh-my-claudecode:omc-doctor` |
-| `omc-help` | Show OMC usage guide | `/oh-my-claudecode:omc-help` |
-| `hud` | Configure HUD statusline | `/oh-my-claudecode:hud` |
-| `release` | Automated release workflow | `/oh-my-claudecode:release` |
-| `mcp-setup` | Configure MCP servers | `/oh-my-claudecode:mcp-setup` |
-| `writer-memory` | Agentic memory system for writers | `/oh-my-claudecode:writer-memory` |
-| `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` |
-| `skill` | Manage local skills (list, add, remove, search, edit) | `/oh-my-claudecode:skill` |
+## Skills (38 Total)
+
+Includes **37 canonical skills + 1 deprecated alias** (`psm`).
+
+| Skill                     | Description                                                      | Manual Command                              |
+| ------------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
+| `analyze`                 | Deep analysis and investigation                                  | `/oh-my-claudecode:analyze`                 |
+| `ask-codex`               | Ask Codex via `omc ask codex` and store an ask artifact          | `/oh-my-claudecode:ask-codex`               |
+| `ask-gemini`              | Ask Gemini via `omc ask gemini` and store an ask artifact        | `/oh-my-claudecode:ask-gemini`              |
+| `autopilot`               | Full autonomous execution from idea to working code              | `/oh-my-claudecode:autopilot`               |
+| `build-fix`               | Fix build and TypeScript errors                                  | `/oh-my-claudecode:build-fix`               |
+| `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`                     |
+| `code-review`             | Comprehensive code review                                        | `/oh-my-claudecode:code-review`             |
+| `configure-notifications` | Configure notifications (Discord/Telegram/Slack/OpenClaw)        | `/oh-my-claudecode:configure-notifications` |
+| `configure-openclaw`      | Configure OpenClaw notification bridge                           | `/oh-my-claudecode:configure-openclaw`      |
+| `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`                     |
+| `learn-about-omc`         | Analyze OMC usage patterns                                       | `/oh-my-claudecode:learn-about-omc`         |
+| `learner`                 | Extract reusable skill from session                              | `/oh-my-claudecode:learner`                 |
+| `mcp-setup`               | Configure MCP servers                                            | `/oh-my-claudecode:mcp-setup`               |
+| `note`                    | Save notes to notepad                                            | `/oh-my-claudecode:note`                    |
+| `omc-doctor`              | Diagnose and fix installation issues                             | `/oh-my-claudecode:omc-doctor`              |
+| `omc-help`                | Show OMC usage guide                                             | `/oh-my-claudecode:omc-help`                |
+| `omc-plan`                | Planning workflow (`/plan` safe alias)                           | `/oh-my-claudecode:omc-plan`                |
+| `omc-security-review`     | Security review workflow (`/security-review` safe alias)         | `/oh-my-claudecode:omc-security-review`     |
+| `omc-setup`               | One-time setup wizard                                            | `/oh-my-claudecode:omc-setup`               |
+| `omc-teams`               | Legacy compatibility wrapper for `omc team` CLI                  | `/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`                   |
+| `ralph-init`              | Initialize PRD for structured ralph execution                    | `/oh-my-claudecode:ralph-init`              |
+| `ralplan`                 | Consensus planning alias for `/omc-plan --consensus`             | `/oh-my-claudecode:ralplan`                 |
+| `release`                 | Automated release workflow                                       | `/oh-my-claudecode:release`                 |
+| `sciomc`                  | Parallel scientist orchestration                                 | `/oh-my-claudecode:sciomc`                  |
+| `skill`                   | Manage local skills (list/add/remove/search/edit)                | `/oh-my-claudecode:skill`                   |
+| `tdd`                     | Test-first workflow enforcement                                  | `/oh-my-claudecode:tdd`                     |
+| `team`                    | Coordinated multi-agent workflow                                 | `/oh-my-claudecode:team`                    |
+| `trace`                   | Show orchestration trace timeline                                | `/oh-my-claudecode:trace`                   |
+| `ultraqa`                 | QA cycle until goal is met                                       | `/oh-my-claudecode:ultraqa`                 |
+| `ultrawork`               | Maximum parallel throughput mode                                 | `/oh-my-claudecode:ultrawork`               |
+| `writer-memory`           | Agentic memory system for writing projects                       | `/oh-my-claudecode:writer-memory`           |
+
+`psm` | **Deprecated** compatibility alias for `project-session-manager`
 
 ---
 
@@ -304,36 +372,32 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool.
 
 All skills are available as slash commands with the prefix `/oh-my-claudecode:`.
 
-| Command | Description |
-|---------|-------------|
-| `/oh-my-claudecode:orchestrate <task>` | Activate multi-agent orchestration mode |
-| `/oh-my-claudecode:autopilot <task>` | Full autonomous execution |
-| `/oh-my-claudecode:ultrawork <task>` | Maximum performance mode with parallel agents |
-| `/oh-my-claudecode:ultrapilot <task>` | Parallel autopilot (3-5x faster) |
-| `/oh-my-claudecode:team <N>:<agent> <task>` | Coordinated native team workflow |
-| `/oh-my-claudecode:swarm <N>:<agent> <task>` | Deprecated alias for Team orchestration |
-| `/oh-my-claudecode:pipeline <stages>` | Sequential agent chaining |
-| `/oh-my-claudecode:ralph-init <task>` | Initialize PRD for structured task tracking |
-| `/oh-my-claudecode:ralph <task>` | Self-referential loop until task completion |
-| `/oh-my-claudecode:ultraqa <goal>` | Autonomous QA cycling workflow |
-| `/oh-my-claudecode:plan <description>` | Start planning session (supports consensus structured deliberation) |
-| `/oh-my-claudecode:ralplan <description>` | Iterative planning with consensus structured deliberation (`--deliberate` for high-risk mode) |
-| `/oh-my-claudecode:review [plan-path]` | Review a plan with critic |
-| `/oh-my-claudecode:deepsearch <query>` | Thorough multi-strategy codebase search |
-| `/oh-my-claudecode:deepinit [path]` | Index codebase with hierarchical AGENTS.md files |
-| `/oh-my-claudecode:analyze <target>` | Deep analysis and investigation |
-| `/oh-my-claudecode:sciomc <topic>` | Parallel research orchestration |
-| `/oh-my-claudecode:tdd <feature>` | TDD workflow enforcement |
-| `/oh-my-claudecode:learner` | Extract reusable skill from session |
-| `/oh-my-claudecode:note <content>` | Save notes to notepad.md |
-| `/oh-my-claudecode:cancel` | Unified cancellation |
-| `/oh-my-claudecode:omc-setup` | One-time setup wizard |
-| `/oh-my-claudecode:omc-doctor` | Diagnose and fix installation issues |
-| `/oh-my-claudecode:omc-help` | Show OMC usage guide |
-| `/oh-my-claudecode:hud` | Configure HUD statusline |
-| `/oh-my-claudecode:release` | Automated release workflow |
-| `/oh-my-claudecode:mcp-setup` | Configure MCP servers |
-| `/oh-my-claudecode:psm <arguments>` | Deprecated alias for project session manager |
+| Command                                     | Description                                                                                   |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `/oh-my-claudecode:autopilot <task>`        | Full autonomous execution                                                                     |
+| `/oh-my-claudecode:ultrawork <task>`        | Maximum performance mode with parallel agents                                                 |
+| `/oh-my-claudecode:team <N>:<agent> <task>` | Coordinated native team workflow                                                              |
+| `/oh-my-claudecode:ralph-init <task>`       | Initialize PRD for structured task tracking                                                   |
+| `/oh-my-claudecode:ralph <task>`            | Self-referential loop until task completion                                                   |
+| `/oh-my-claudecode:ultraqa <goal>`          | Autonomous QA cycling workflow                                                                |
+| `/oh-my-claudecode:omc-plan <description>`  | Start planning session (supports consensus structured deliberation)                           |
+| `/oh-my-claudecode:ralplan <description>`   | Iterative planning with consensus structured deliberation (`--deliberate` for high-risk mode) |
+| `/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:analyze <target>`        | Deep analysis and investigation                                                               |
+| `/oh-my-claudecode:sciomc <topic>`          | Parallel research orchestration                                                               |
+| `/oh-my-claudecode:tdd <feature>`           | TDD workflow enforcement                                                                      |
+| `/oh-my-claudecode:learner`                 | Extract reusable skill from session                                                           |
+| `/oh-my-claudecode:note <content>`          | Save notes to notepad.md                                                                      |
+| `/oh-my-claudecode:cancel`                  | Unified cancellation                                                                          |
+| `/oh-my-claudecode:omc-setup`               | One-time setup wizard                                                                         |
+| `/oh-my-claudecode:omc-doctor`              | Diagnose and fix installation issues                                                          |
+| `/oh-my-claudecode:omc-help`                | Show OMC usage guide                                                                          |
+| `/oh-my-claudecode:hud`                     | Configure HUD statusline                                                                      |
+| `/oh-my-claudecode:release`                 | Automated release workflow                                                                    |
+| `/oh-my-claudecode:mcp-setup`               | Configure MCP servers                                                                         |
+| `/oh-my-claudecode:trace`                   | Show orchestration trace timeline                                                             |
+| `/oh-my-claudecode:psm <arguments>`         | Deprecated alias for project session manager                                                  |
 
 ---
 
@@ -343,49 +407,47 @@ 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 |
-| `ultrapilot` | Parallel autopilot with file ownership |
-| `team-pipeline` | Native team staged pipeline orchestration |
-| `ultraqa` | QA cycling until goal met |
-| `swarm` | Coordinated multi-agent with SQLite task claiming |
-| `mode-registry` | Tracks active execution mode state (including team/ralph/ultrawork/ralplan) |
-| `persistent-mode` | Maintains mode state across sessions |
+| 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 |
+| 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 |
+| 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) |
+| 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
 
@@ -394,6 +456,7 @@ The `code-simplifier` Stop hook automatically delegates recently modified source
 explicitly enabled via `~/.omc/config.json`.
 
 **Enable:**
+
 ```json
 {
   "codeSimplifier": {
@@ -403,6 +466,7 @@ explicitly enabled via `~/.omc/config.json`.
 ```
 
 **Full config options:**
+
 ```json
 {
   "codeSimplifier": {
@@ -413,13 +477,14 @@ explicitly enabled via `~/.omc/config.json`.
 }
 ```
 
-| 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 |
+| 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
@@ -427,38 +492,35 @@ explicitly enabled via `~/.omc/config.json`.
 
 ### 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 |
+| 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 |
+| `plugin-patterns`         | Plugin pattern detection                 |
+| `setup`                   | Initial setup and configuration          |
 
 ---
 
 ## Magic Keywords
 
-Just include these words anywhere in your prompt to activate enhanced modes:
-
-| Keyword | Effect |
-|---------|--------|
-| `ultrawork`, `ulw`, `uw` | Activates parallel agent orchestration |
-| `eco`, `efficient`, `save-tokens`, `budget` | Token-efficient parallel execution |
-| `autopilot`, `build me`, `I want a` | Full autonomous execution |
-| `ultrapilot`, `parallel build`, `swarm build` | Parallel autopilot (3-5x faster) |
-| `ralph`, `don't stop`, `must complete` | Persistence until verified complete |
-| `plan this`, `plan the` | Planning interview workflow |
-| `ralplan` | Iterative planning consensus with structured deliberation (`--deliberate` for high-risk mode) |
-| `search`, `find`, `locate` | Enhanced search mode |
-| `analyze`, `investigate`, `debug` | Deep analysis mode |
-| `sciomc` | Parallel research orchestration |
-| `tdd`, `test first`, `red green` | TDD workflow enforcement |
-| `swarm N agents` | Coordinated agent swarm |
-| `pipeline`, `chain agents` | Sequential agent chaining |
-| `stop`, `cancel`, `abort` | Unified cancellation |
+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                                                                     |
+| `ralph`, `don't stop`, `must complete`                  | Persistence until verified complete                                                           |
+| `team`, `coordinated team`                              | Team pipeline 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
 
@@ -468,35 +530,29 @@ Just include these words anywhere in your prompt to activate enhanced modes:
 # Maximum parallelism
 ultrawork implement user authentication with OAuth
 
-# Token-efficient parallelism
-eco fix all TypeScript errors
-
 # Enhanced search
-find all files that import the utils module
+deepsearch for files that import the utils module
 
 # Deep analysis
-analyze why the tests are failing
+deep-analyze why the tests are failing
 
 # Autonomous execution
 autopilot: build a todo app with React
 
-# Parallel autopilot
-ultrapilot: build a fullstack todo app
+# Parallel autonomous execution
+team 3:executor "build a fullstack todo app"
 
 # Persistence mode
 ralph: refactor the authentication module
 
 # Planning session
-plan this feature
+ralplan this feature
 
 # TDD workflow
 tdd: implement password validation
 
-# Coordinated swarm
-swarm 5 agents: fix all lint errors
-
-# Agent chaining
-pipeline: analyze → fix → test this bug
+# Stop active orchestration
+stopomc
 ```
 
 ---
@@ -505,11 +561,11 @@ pipeline: analyze → fix → test this bug
 
 ### Operating Systems
 
-| Platform | Install Method | Hook Type |
-|----------|---------------|-----------|
+| Platform    | Install Method              | Hook Type      |
+| ----------- | --------------------------- | -------------- |
 | **Windows** | WSL2 recommended (see note) | Node.js (.mjs) |
-| **macOS** | curl or npm | Bash (.sh) |
-| **Linux** | curl or npm | Bash (.sh) |
+| **macOS**   | curl or npm                 | Bash (.sh)     |
+| **Linux**   | curl or npm                 | Bash (.sh)     |
 
 > **Note**: Bash hooks are fully portable across macOS and Linux (no GNU-specific dependencies).
 
@@ -519,44 +575,44 @@ pipeline: analyze → fix → test this bug
 
 ### 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 |
+| 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 |
+| 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 |
+| 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).
 
@@ -570,21 +626,21 @@ For complete documentation, see **[Performance Monitoring Guide](./PERFORMANCE-M
 
 ### Quick Overview
 
-| Feature | Description | Access |
-|---------|-------------|--------|
-| **Agent Observatory** | Real-time agent status, efficiency, bottlenecks | HUD / API |
-| **Token Analytics** | Cost tracking, usage reports, budget warnings | `omc stats`, `omc cost` |
-| **Session Replay** | Event timeline for post-session analysis | `.omc/state/agent-replay-*.jsonl` |
-| **Intervention System** | Auto-detection of stale agents, cost overruns | Automatic |
+| Feature                 | Description                                     | Access                               |
+| ----------------------- | ----------------------------------------------- | ------------------------------------ |
+| **Agent Observatory**   | Real-time agent status, efficiency, bottlenecks | HUD / API                            |
+| **Token Analytics**     | Cost tracking, usage reports, budget warnings   | HUD (`analytics` preset), `omc cost` |
+| **Session Replay**      | Event timeline for post-session analysis        | `.omc/state/agent-replay-*.jsonl`    |
+| **Intervention System** | Auto-detection of stale agents, cost overruns   | Automatic                            |
 
 ### CLI Commands
 
 ```bash
-omc stats          # Current session statistics
+omc                # Default analytics dashboard
 omc cost daily     # Daily cost report
 omc cost weekly    # Weekly cost report
-omc agents         # Agent breakdown
 omc backfill       # Import historical transcript data
+# Agent breakdown: use HUD observatory / replay logs
 ```
 
 ### HUD Analytics Preset
@@ -614,6 +670,7 @@ Enable detailed cost tracking in your status line:
 ```
 
 Checks for:
+
 - Missing dependencies
 - Configuration errors
 - Hook installation status
@@ -645,35 +702,43 @@ Configure HUD elements in `~/.claude/settings.json`:
 }
 ```
 
-| 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` |
+| 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`  |
+
+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` |
+| 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 |
+| 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