claudecode-omc 4.8.4 → 4.9.3

package/docs/MIGRATION.md

@@ -627,39 +627,7 @@ Version 3.4.0 introduces powerful parallel execution modes and advanced workflow
 
 ### What's New
 
-#### 1. Ultrapilot: Parallel Autopilot
-
-Execute complex tasks with up to 5 concurrent workers for 3-5x speedup:
-
-```bash
-/oh-my-claudecode:ultrapilot "build a fullstack todo app"
-```
-
-**Key Features:**
-
-- Automatic task decomposition into parallelizable subtasks
-- File ownership coordination to prevent conflicts
-- Parallel execution with intelligent coordination
-- State files: `.omc/state/ultrapilot-state.json`, `.omc/state/ultrapilot-ownership.json`
-
-**Best for:** Multi-component systems, fullstack apps, large refactoring
-
-#### 2. Swarm: Coordinated Agent Teams
-
-N coordinated agents with atomic task claiming:
-
-```bash
-/oh-my-claudecode:swarm 5:executor "fix all TypeScript errors"
-```
-
-**Key Features:**
-
-- Shared task pool with atomic claiming (prevents duplicate work)
-- 5-minute timeout per task with auto-release
-- Scales from 2 to 10 workers
-- Clean completion when all tasks done
-
-#### 3. Pipeline: Sequential Agent Chaining
+#### 1. Pipeline: Sequential Agent Chaining
 
 Chain agents with data passing between stages:
 
@@ -685,7 +653,7 @@ Smart cancellation that auto-detects active mode:
 # Or just say: "stop", "cancel", "abort"
 ```
 
-**Auto-detects and cancels:** autopilot, ultrapilot, ralph, ultrawork, ultraqa, swarm, pipeline
+**Auto-detects and cancels:** autopilot, ralph, ultrawork, ultraqa, pipeline
 
 **Deprecation Notice:**
 Individual cancel commands are deprecated but still work:
@@ -782,9 +750,9 @@ Once upgraded, you automatically gain access to:
 
 | Scenario                | Recommended Mode | Why                                            |
 | ----------------------- | ---------------- | ---------------------------------------------- |
-| Multi-component systems | `ultrapilot`     | Parallel workers handle independent components |
-| Many small fixes        | `swarm`          | Atomic task claiming prevents duplicate work   |
-| Sequential dependencies | `pipeline`       | Data passes between stages                     |
+| Multi-component systems | `team N:executor` | Parallel workers handle independent components |
+| Many small fixes        | `team N:executor` | Atomic task claiming prevents duplicate work   |
+| Sequential dependencies | `pipeline`        | Data passes between stages                     |
 | Single complex task     | `autopilot`      | Full autonomous execution                      |
 | Must complete           | `ralph`          | Persistence guarantee                          |
 
@@ -815,21 +783,15 @@ After upgrading, verify new features:
    npm list -g oh-my-claudecode
    ```
 
-2. **Test ultrapilot**:
-
-   ```bash
-   /oh-my-claudecode:ultrapilot "create a simple React component"
-   ```
-
-3. **Test unified cancel**:
+2. **Test unified cancel**:
 
    ```bash
    /oh-my-claudecode:cancel
    ```
 
-4. **Check state directory**:
+3. **Check state directory**:
    ```bash
-   ls -la .omc/state/  # Should see ultrapilot-state.json after running ultrapilot
+   ls -la .omc/state/
    ```
 
 ---

package/docs/PERFORMANCE-MONITORING.md

@@ -412,10 +412,10 @@ cleanupReplayFiles(process.cwd()); // Keeps last 10 sessions
 **Symptoms**: Merge conflicts, unexpected file changes
 
 **Solutions**:
-1. Use `ultrapilot` mode for automatic file ownership
+1. Use `team N:executor` mode for automatic file ownership
 2. Check `detectFileConflicts()` before parallel execution
 3. Review file_ownership in agent state
-4. Use `swarm` mode with explicit task isolation
+4. Use `team N:executor` mode with explicit task isolation
 
 ### Missing Session-End Summaries
 

package/docs/REFERENCE.md

@@ -10,8 +10,8 @@ Complete reference for oh-my-claudecode. For quick start, see the main [README.m
 - [Configuration](#configuration)
 - [CLI Commands: ask/team/session](#cli-commands-askteamsession)
 - [Legacy MCP Team Runtime Tools (Deprecated)](#legacy-mcp-team-runtime-tools-deprecated)
-- [Agents (28 Total)](#agents-28-total)
-- [Skills (34 Total)](#skills-34-total)
+- [Agents (29 Total)](#agents-29-total)
+- [Skills (32 Total)](#skills-32-total)
 - [Slash Commands](#slash-commands)
 - [Hooks System](#hooks-system)
 - [Magic Keywords](#magic-keywords)
@@ -129,6 +129,33 @@ If both a legacy `{worktree}/.omc/` directory and a centralized directory exist,
 
 > **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:
@@ -205,7 +232,7 @@ omc ask claude --agent-prompt executor --prompt "create an implementation plan"
 - 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
+- Skill entrypoint: `/oh-my-claudecode:ask <claude|codex|gemini> <prompt>` routes to this command
 
 ### `omc team` (CLI runtime surface)
 
@@ -218,6 +245,11 @@ omc team api claim-task --input '{"team_name":"auth-review","task_id":"1","worke
 
 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
@@ -272,7 +304,7 @@ Optional compatibility enablement (manual only):
 - **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)
+## Agents (29 Total)
 
 Always use `oh-my-claudecode:` prefix when calling via Task tool.
 
@@ -291,6 +323,7 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool.
 | **Critique**     | -                       | -                     | `critic`            |
 | **Pre-Planning** | -                       | -                     | `analyst`           |
 | **Testing**      | -                       | `qa-tester`           | -                   |
+| **Tracing**      | -                       | `tracer`              | -                   |
 | **Security**     | `security-reviewer-low` | -                     | `security-reviewer` |
 | **Build**        | -                       | `debugger`            | -                   |
 | **TDD**          | -                       | `test-engineer`       | -                   |
@@ -318,6 +351,7 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool.
 | 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 |
@@ -332,83 +366,78 @@ Always use `oh-my-claudecode:` prefix when calling via Task tool.
 
 ---
 
-## Skills (34 Total)
+## Skills (32 Total)
 
-Includes **33 canonical skills + 1 deprecated alias** (`psm`).
+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                              |
 | ------------------------- | ---------------------------------------------------------------- | ------------------------------------------- |
-| `ask-codex`               | Ask Codex via `omc ask codex` and store an ask artifact          | `/oh-my-claudecode:ask-codex`               |
 | `ai-slop-cleaner`         | Anti-slop cleanup workflow with optional reviewer-only `--review` pass | `/oh-my-claudecode:ai-slop-cleaner`         |
-| `ask-gemini`              | Ask Gemini via `omc ask gemini` and store an ask artifact        | `/oh-my-claudecode:ask-gemini`              |
+| `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 notifications (Discord/Telegram/Slack/OpenClaw)        | `/oh-my-claudecode:configure-notifications` |
-| `configure-openclaw`      | Configure OpenClaw gateway (deprecated, use configure-notifications) | `/oh-my-claudecode:configure-openclaw`      |
-| _OpenClaw routing_        | Normalized native/HTTP routing contract for clawhip consumers    | [`docs/OPENCLAW-ROUTING.md`](./OPENCLAW-ROUTING.md) |
+| `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`                     |
-| `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-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`               | Legacy compatibility wrapper for `omc team` CLI                  | `/oh-my-claudecode:omc-teams`               |
+| `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`                     |
+| `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`                 |
 | `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`                   | Show orchestration trace timeline                                | `/oh-my-claudecode:trace`                   |
+| `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`           |
 
-`psm` | **Deprecated** compatibility alias for `project-session-manager`
 
 ---
 
 ## Slash Commands
 
-All installed skills are available as slash commands with the prefix `/oh-my-claudecode:`. Compatibility keyword modes like `deep-analyze` and `tdd` are prompt-triggered behaviors, not standalone 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: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 (`--critic=architect|critic|codex`)               |
-| `/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:sciomc <topic>`          | Parallel research orchestration                                                               |
-| `/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:setup`                   | Unified setup entrypoint (`setup`, `setup doctor`, `setup mcp`)                              |
-| `/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                                                  |
+| `/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)
 
@@ -423,6 +452,12 @@ 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
@@ -477,7 +512,11 @@ Oh-my-claudecode includes 31 lifecycle hooks that enhance Claude Code's behavior
 
 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 `~/.omc/config.json`.
+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:**
 
@@ -721,23 +760,25 @@ Configure HUD elements in `~/.claude/settings.json`:
     "elements": {
       "cwd": true,
       "gitRepo": true,
-      "gitBranch": 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`  |
+| 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):
 

package/docs/design/SKILLS_2_0_ADAPTATION.md

@@ -0,0 +1,115 @@
+# Skills 2.0 Adaptation for OMC (MVP)
+
+## Context
+
+The broader AI coding-agent ecosystem is converging on a more package-oriented skill model:
+
+- reusable workflows live in directory-based skill packages
+- skills ship bundled resources, not just prose
+- orchestration surfaces increasingly expose explicit handoffs, tools, and workflow contracts
+
+OMC already has strong foundations here:
+
+- `SKILL.md` frontmatter
+- slash-loaded skills
+- builtin skill loading
+- pipeline / handoff metadata
+
+This MVP focuses on the smallest concrete adaptation that improves interoperability without forcing a large schema migration.
+
+## Research summary
+
+### Anthropic Claude Code
+
+Claude Code's custom subagent model emphasizes:
+
+- specialized workflow packaging
+- scoped capabilities and tools
+- explicit subagent composition
+- preloaded skills/resources
+
+### OpenAI Agents SDK
+
+The Agents SDK treats the following as first-class:
+
+- tools
+- handoffs
+- workflows/pipelines
+- guardrails
+
+### Agent Skills ecosystem
+
+The Agent Skills ecosystem centers on project-local skill packaging conventions such as `.agents/skills/`, with bundled artifacts that should be reused by the agent at execution time.
+
+## OMC gaps
+
+1. **Project-local compatibility gap**
+   - OMC's canonical project-local skill directory is `.omc/skills/`
+   - emerging conventions also use `.agents/skills/`
+   - OMC should interoperate without abandoning its own canonical layout
+
+2. **Bundled-resource visibility gap**
+   - OMC renders skill markdown well
+   - but it does not consistently call attention to `lib/`, `templates/`, scripts, or helper files shipped beside the skill
+   - this increases needless reinvention and reduces package leverage
+
+## MVP scope implemented in Phase 1
+
+### 1. Compatibility read support for `.agents/skills/`
+
+- Keep `.omc/skills/` as the canonical OMC project-local skill directory
+- Add `.agents/skills/` as a compatibility read source for:
+  - learned/project skill discovery
+  - slash-loaded skill discovery
+- Preserve deterministic priority order:
+  - project commands
+  - user commands
+  - project `.omc/skills`
+  - project `.agents/skills`
+  - user skill directories
+
+### 2. Standardized `Skill Resources` rendering
+
+When a skill directory contains extra bundled assets beyond `SKILL.md`, OMC now appends a standardized block:
+
+- skill directory path
+- bundled resource entries (for example `lib/`, `templates/`, scripts)
+- a reuse-first reminder
+
+This is rendered for:
+
+- builtin skills
+- slash-loaded skills
+
+## Why this slice
+
+This MVP is intentionally narrow:
+
+- high practical value
+- low migration risk
+- no new dependency
+- backward compatible with current skill metadata
+
+It gives OMC a real step toward a "skills 2.0" model without prematurely freezing a large frontmatter schema.
+
+## Deferred follow-ups
+
+### Phase 2
+
+Add optional richer skill contract metadata, potentially including:
+
+- deliverables
+- artifact paths
+- allowed tools
+- model/runtime preferences
+- explicit execution constraints
+
+### Phase 3
+
+Add validation / diagnostics around richer contracts and potentially artifact-first execution helpers.
+
+## Risks
+
+- `.agents/skills/` compatibility may surface overlapping names if users intentionally mirror the same skill in both locations; precedence is now explicit, but duplication may still confuse humans.
+- `Skill Resources` currently summarizes top-level bundled assets only; deeper artifact indexing is out of scope for the MVP.
+- This does not yet introduce a richer validated schema; it improves packaging and discoverability first.

package/docs/ko/ARCHITECTURE.md

@@ -108,7 +108,7 @@ Task(
 상태 파일은 표준화된 위치를 따릅니다:
 
 **로컬 프로젝트 상태:**
-- `.omc/state/{name}.json` - 세션 상태 (ultrapilot, swarm, pipeline)
+- `.omc/state/{name}.json` - 세션 상태 (pipeline, team)
 - `.omc/notepads/{plan-name}/` - 계획 범위의 지식 캡처
 
 **글로벌 상태:**

package/docs/ko/MIGRATION.md

@@ -593,39 +593,7 @@ npm update -g claudecode-omc
 
 ### 새로운 기능
 
-#### 1. ultrapilot: 병렬 autopilot
-
-최대 5개의 동시 워커로 복잡한 작업을 3-5배 빠르게 실행합니다:
-
-```bash
-/oh-my-claudecode:ultrapilot "build a fullstack todo app"
-```
-
-**주요 기능:**
-
-- 병렬화 가능한 하위 작업으로의 자동 작업 분해
-- 충돌을 방지하는 파일 소유권 조정
-- 지능적 조정을 통한 병렬 실행
-- 상태 파일: `.omc/state/ultrapilot-state.json`, `.omc/state/ultrapilot-ownership.json`
-
-**적합한 경우:** 멀티 컴포넌트 시스템, 풀스택 앱, 대규모 리팩토링
-
-#### 2. swarm: 조정된 에이전트 팀
-
-원자적 작업 클레이밍을 가진 N개의 조정된 에이전트:
-
-```bash
-/oh-my-claudecode:swarm 5:executor "fix all TypeScript errors"
-```
-
-**주요 기능:**
-
-- 원자적 클레이밍이 있는 공유 작업 풀 (중복 작업 방지)
-- 작업당 5분 타임아웃 및 자동 해제
-- 2개에서 10개 워커까지 확장 가능
-- 모든 작업 완료 시 깔끔한 종료
-
-#### 3. pipeline: 순차적 에이전트 체이닝
+#### 1. pipeline: 순차적 에이전트 체이닝
 
 스테이지 간 데이터 전달을 가진 에이전트 체이닝:
 
@@ -665,7 +633,7 @@ npm update -g claudecode-omc
 # 또는 그냥: "stop", "cancel", "abort"
 ```
 
-**자동 감지 및 취소:** autopilot, ultrapilot, ralph, ultrawork, ultraqa, swarm, pipeline
+**자동 감지 및 취소:** autopilot, ralph, ultrawork, ultraqa, pipeline
 
 **폐기 안내:**
 개별 취소 명령어는 폐기되었지만 여전히 작동합니다:
@@ -768,8 +736,6 @@ omc config-agent-tiers --disable-low
 
 업그레이드 후 자동으로 다음에 접근할 수 있습니다:
 
-- ultrapilot (병렬 autopilot)
-- swarm 조정
 - pipeline 워크플로우
 - ecomode 실행
 - 통합 cancel 명령어
@@ -781,8 +747,8 @@ omc config-agent-tiers --disable-low
 
 | 시나리오             | 추천 모드    | 이유                                    |
 | -------------------- | ------------ | --------------------------------------- |
-| 멀티 컴포넌트 시스템 | `ultrapilot` | 병렬 워커가 독립적인 컴포넌트를 처리    |
-| 많은 소규모 수정     | `swarm`      | 원자적 작업 클레이밍으로 중복 작업 방지 |
+| 멀티 컴포넌트 시스템 | `team N:executor` | 병렬 워커가 독립적인 컴포넌트를 처리    |
+| 많은 소규모 수정     | `team N:executor` | 원자적 작업 클레이밍으로 중복 작업 방지 |
 | 순차적 의존성        | `pipeline`   | 스테이지 간 데이터 전달                 |
 | 예산 고려            | ``           | 스마트 라우팅으로 30-50% 토큰 절약      |
 | 단일 복잡한 작업     | `autopilot`  | 완전 자율 실행                          |
@@ -817,21 +783,15 @@ omc config-agent-tiers --disable-low
    npm list -g claudecode-omc
    ```
 
-2. **ultrapilot 테스트**:
-
-   ```bash
-   /oh-my-claudecode:ultrapilot "create a simple React component"
-   ```
-
-3. **통합 cancel 테스트**:
+2. **통합 cancel 테스트**:
 
    ```bash
    /oh-my-claudecode:cancel
    ```
 
-4. **상태 디렉토리 확인**:
+3. **상태 디렉토리 확인**:
    ```bash
-   ls -la .omc/state/  # ultrapilot 실행 후 ultrapilot-state.json이 보여야 합니다
+   ls -la .omc/state/
    ```
 
 ---