oh-my-codex 0.20.3 → 0.21.0

package/skills/doctor/SKILL.md

@@ -3,237 +3,116 @@ name: doctor
 description: Diagnose and fix oh-my-codex installation issues
 ---
 
-# Doctor Skill
+# OMX Doctor
 
-Note: All `~/.codex/...` paths in this guide respect `CODEX_HOME` when that environment variable is set.
+Use this task card to diagnose installation/discovery problems. Shared safety, lifecycle, hook, team, autonomy, and cancellation rules live in `templates/AGENTS.md`. `~/.codex` means `${CODEX_HOME:-~/.codex}` when `CODEX_HOME` is set.
 
-## Canonical skill root
+## Run diagnostics
 
-OMX installs skills to `${CODEX_HOME:-~/.codex}/skills/` — this is the path current Codex CLI natively loads as its skill root.
-
-`~/.agents/skills/` is a **historical legacy path** from an older Codex CLI release, before Codex settled on `~/.codex` as its home directory. Current Codex CLI and OMX no longer write there.
-
-**In a mixed OMX + plain Codex environment:**
-- **Use**: `${CODEX_HOME:-~/.codex}/skills/` (user scope) or `.codex/skills/` (project scope)
-- **Clean up if present**: `~/.agents/skills/` — if this still exists alongside the canonical root, Codex's Enable/Disable Skills UI will show duplicate entries for any skill present in both trees
-- **Interop rule**: OMX writes only to the canonical path; archive or remove `~/.agents/skills/` once you have confirmed `${CODEX_HOME:-~/.codex}/skills/` is your active root
-
-## Task: Run Installation Diagnostics
-
-You are the OMX Doctor - diagnose and fix installation issues.
+```bash
+omx doctor
+omx doctor --team             # include Team runtime checks
+omx doctor --verbose          # include detailed check evidence
+omx doctor --force            # repair eligible repo artifact ownership issues
+omx doctor --dry-run --force  # preview eligible ownership repairs
+```
 
-### Step 1: Check Plugin Version
+For a local source checkout, build first and invoke `node bin/omx.js doctor`. Keep command output and exact paths for the report.
 
-Official Codex plugin caches are marketplace- and version-scoped, for example `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/`. Local installs may use `local` as the version identifier.
+### Plugin cache and version
 
 ```bash
-# Get installed plugin cache versions across marketplaces.
-# Cache shape: $PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex/$PLUGIN_VERSION/
 PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
 CACHE_ENTRIES=$(find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex/*" -mindepth 3 -maxdepth 3 -type d 2>/dev/null)
-
 if [[ -z "$CACHE_ENTRIES" ]]; then
   echo "Installed plugin cache: none"
 else
-  while IFS= read -r VERSION_DIR; do
-    MARKETPLACE_NAME=$(basename "$(dirname "$(dirname "$VERSION_DIR")")")
-    PLUGIN_VERSION=$(basename "$VERSION_DIR")
-    printf 'Installed plugin cache: marketplace=%s version=%s path=%s\n' "$MARKETPLACE_NAME" "$PLUGIN_VERSION" "$VERSION_DIR"
-  done <<< "$CACHE_ENTRIES"
+  while IFS= read -r d; do
+    m=$(basename "$(dirname "$(dirname "$d")")"); v=$(basename "$d")
+    printf 'Installed plugin cache: marketplace=%s version=%s path=%s\n' "$m" "$v" "$d"
+  done <<<"$CACHE_ENTRIES"
 fi
-
-# Get latest from npm
 LATEST=$(npm view oh-my-codex version 2>/dev/null)
 echo "Latest npm: $LATEST"
 ```
 
-**Diagnosis**:
-- If no cache entry exists: INFO - plugin marketplace artifact not cached; this may be normal when OMX was installed only through npm/setup
-- Compare each printed `PLUGIN_VERSION` with `LATEST`; if it differs and is not `local`: WARN - outdated plugin cache
-- If one marketplace has multiple version directories: WARN - stale cache for that marketplace/plugin pair
-- Remember: plugin install/discovery is not a replacement for `npm install -g oh-my-codex` plus `omx setup`; the packaged plugin carries plugin-scoped companion metadata for optional MCP compatibility servers and apps, with first-party MCP disabled by default, while native/runtime hooks and the rest of OMX runtime wiring stay setup-owned
-
-### Step 2: Check Hook Configuration (config.toml + legacy settings.json)
-
-Check `~/.codex/config.toml` first (current Codex config), then check legacy `~/.codex/settings.json` only if it exists.
-
-Look for hook entries pointing to removed scripts like:
-- `bash $HOME/.codex/hooks/keyword-detector.sh`
-- `bash $HOME/.codex/hooks/persistent-mode.sh`
-- `bash $HOME/.codex/hooks/session-start.sh`
-
-**Diagnosis**:
-- If found: CRITICAL - legacy hooks causing duplicates
-
-### Step 3: Check for Legacy Bash Hook Scripts
-
-```bash
-ls -la ~/.codex/hooks/*.sh 2>/dev/null
-```
-
-**Diagnosis**:
-- If `keyword-detector.sh`, `persistent-mode.sh`, `session-start.sh`, or `stop-continuation.sh` exist: WARN - legacy scripts (can cause confusion)
+No cache is INFO (normal for npm/setup-only installs). A non-`local` cache version differing from `LATEST`, or multiple versions for one marketplace, is WARN. Plugin discovery does not replace npm installation plus `omx setup`; native/runtime wiring remains setup-owned.
 
-### Step 4: Check AGENTS.md
+### Hooks, AGENTS, and skill roots
 
 ```bash
-# Check if AGENTS.md exists
-ls -la ~/.codex/AGENTS.md 2>/dev/null
-
-# Check for OMX marker
-grep -q "oh-my-codex Multi-Agent System" ~/.codex/AGENTS.md 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"
+CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
+ls -la "$CODEX_DIR/config.toml" "$CODEX_DIR/settings.json" 2>/dev/null
+rg 'keyword-detector|persistent-mode|session-start|stop-continuation' "$CODEX_DIR/config.toml" "$CODEX_DIR/settings.json" 2>/dev/null || true
+ls -la "$CODEX_DIR/hooks"/*.sh 2>/dev/null
+ls -la "$CODEX_DIR/AGENTS.md" 2>/dev/null
+grep -q "oh-my-codex Multi-Agent System" "$CODEX_DIR/AGENTS.md" 2>/dev/null && echo "Has OMX config" || echo "Missing OMX config"
+ls -la "$CODEX_DIR/agents" "$CODEX_DIR/commands" "$CODEX_DIR/skills" "$HOME/.agents/skills" 2>/dev/null
 ```
 
-**Diagnosis**:
-- If missing: CRITICAL - AGENTS.md not configured
-- If missing OMX marker: WARN - outdated AGENTS.md
-
-### Step 5: Check for Stale Plugin Cache
-
-```bash
-# List marketplace/version cache entries for this plugin
-PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
-find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex/*" -mindepth 3 -maxdepth 3 -type d 2>/dev/null \
-  | while IFS= read -r VERSION_DIR; do
-      MARKETPLACE_NAME=$(basename "$(dirname "$(dirname "$VERSION_DIR")")")
-      PLUGIN_VERSION=$(basename "$VERSION_DIR")
-      printf '%s\t%s\n' "$MARKETPLACE_NAME" "$PLUGIN_VERSION"
-    done
-```
+Classify legacy hook references as **CRITICAL** (duplicate hooks). The scripts `keyword-detector.sh`, `persistent-mode.sh`, `session-start.sh`, and `stop-continuation.sh` are **WARN**. Missing AGENTS.md is **CRITICAL**; missing the OMX marker is **WARN**. `${CODEX_HOME:-~/.codex}/skills` is the canonical user root. `~/.agents/skills` is historical and overlapping trees can duplicate skill entries. OMX files under legacy `agents/` or `commands/` are **WARN**.
 
-**Diagnosis**:
-- If a single marketplace lists multiple versions: WARN - multiple cached versions for that marketplace/plugin pair (cleanup recommended)
+With `--team`, retain any `resume_blocker`, `slow_shutdown`, `delayed_status_lag`, `stale_leader`, or `orphan_tmux_session` diagnostics; failed checks set a non-zero exit status.
 
-### Step 6: Check for Legacy Curl-Installed Content
-
-Check for legacy agents, commands, and historical legacy skill roots from older installs/migrations:
-
-```bash
-# Check for legacy agents directory
-ls -la ~/.codex/agents/ 2>/dev/null
-
-# Check for legacy commands directory
-ls -la ~/.codex/commands/ 2>/dev/null
-
-# Check canonical current skills directory
-ls -la ${CODEX_HOME:-~/.codex}/skills/ 2>/dev/null
-
-# Check historical legacy skill directory
-ls -la ~/.agents/skills/ 2>/dev/null
-```
+## Report contract
 
-**Diagnosis**:
-- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy generated agents or hand-installed role files. The Codex plugin can package reusable workflows plus plugin-scoped companion metadata for optional MCP/apps; legacy setup installs native agents, while plugin setup archives stale legacy native-agent files and keeps config/hooks current.
-- If `~/.codex/commands/` exists with oh-my-codex-related files: WARN - legacy command files from older installs. Current OMX uses skills/workflows plus setup-managed native surfaces.
-- If `${CODEX_HOME:-~/.codex}/skills/` exists with OMX skills: OK - canonical current user skill root
-- If `~/.agents/skills/` exists: WARN - historical legacy skill root that can overlap with `${CODEX_HOME:-~/.codex}/skills/` and cause duplicate Enable/Disable Skills entries
-
-Look for files like:
-- `architect.md`, `researcher.md`, `explore.md`, `executor.md`, etc. in agents/
-- `ultrawork.md`, `deepsearch.md`, etc. in commands/
-- Any oh-my-codex-related `.md` files in skills/
-
----
-
-## Report Format
-
-After running all checks, output a report:
-
-```
+```text
 ## OMX Doctor Report
-
 ### Summary
 [HEALTHY / ISSUES FOUND]
-
 ### Checks
-
 | Check | Status | Details |
-|-------|--------|---------|
-| Plugin Version | OK/WARN/CRITICAL | ... |
+| Plugin Version | OK/WARN/INFO | ... |
 | Hook Config (config.toml / legacy settings.json) | OK/CRITICAL | ... |
 | Legacy Scripts (~/.codex/hooks/) | OK/WARN | ... |
 | AGENTS.md | OK/WARN/CRITICAL | ... |
 | Plugin Cache | OK/WARN | ... |
-| Legacy Agents (~/.codex/agents/) | OK/WARN | ... |
-| Legacy Commands (~/.codex/commands/) | OK/WARN | ... |
-| Skills (${CODEX_HOME:-~/.codex}/skills) | OK/WARN | ... |
-| Legacy Skill Root (~/.agents/skills) | OK/WARN | ... |
-
+| Legacy Agents / Commands | OK/WARN | ... |
+| Skills (canonical / historical root) | OK/WARN | ... |
 ### Issues Found
-1. [Issue description]
-2. [Issue description]
-
+1. ...
 ### Recommended Fixes
-[List fixes based on issues]
+...
 ```
 
----
-
-## Auto-Fix (if user confirms)
-
-If issues found, ask user: "Would you like me to fix these issues automatically?"
+## Remediation (after user confirmation and confirming each target is OMX-owned)
 
-If yes, apply fixes:
+Remove only confirmed OMX legacy content; preserve unrelated user files:
 
-### Fix: Legacy Hooks in legacy settings.json
-If `~/.codex/settings.json` exists, remove the legacy `"hooks"` section (keep other settings intact).
-
-### Fix: Legacy Bash Scripts
-```bash
-rm -f ~/.codex/hooks/keyword-detector.sh
-rm -f ~/.codex/hooks/persistent-mode.sh
-rm -f ~/.codex/hooks/session-start.sh
-rm -f ~/.codex/hooks/stop-continuation.sh
-```
-
-### Fix: Outdated Plugin
 ```bash
-# Global cache reset across all marketplaces for this plugin.
-# If you only want one marketplace, set MARKETPLACE_NAME and remove just that subtree instead.
+# If settings.json exists, remove only its legacy "hooks" section.
+rm -f "$CODEX_DIR/hooks/keyword-detector.sh" "$CODEX_DIR/hooks/persistent-mode.sh" "$CODEX_DIR/hooks/session-start.sh" "$CODEX_DIR/hooks/stop-continuation.sh"
 PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
 find "$PLUGIN_CACHE_ROOT" -path "*/oh-my-codex" -type d -prune -exec rm -rf {} +
-echo "Plugin cache cleared across all marketplaces. Restart Codex CLI to fetch the latest marketplace entry."
 ```
 
-### Fix: Stale Cache (multiple versions)
+For older curl installs, inspect first and remove only directories containing OMX-managed files:
+
 ```bash
-# Keep only the newest version inside the selected marketplace/plugin cache.
-# Set MARKETPLACE_NAME to the exact marketplace printed in Step 1.
-PLUGIN_CACHE_ROOT="${CODEX_HOME:-$HOME/.codex}/plugins/cache"
-PLUGIN_CACHE_DIR="$PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex"
-KEEP_VERSION=$(for dir in "$PLUGIN_CACHE_DIR"/*; do [[ -d "$dir" ]] && basename "$dir"; done | sort -V | tail -1)
-if [[ -n "$KEEP_VERSION" ]]; then
-  find "$PLUGIN_CACHE_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "$KEEP_VERSION" -exec rm -rf {} +
-fi
+ls -la "$CODEX_DIR/agents" "$CODEX_DIR/commands" "$CODEX_DIR/skills" "$HOME/.agents/skills" 2>/dev/null
+# Optional backups:
+# mv "$CODEX_DIR/agents" "$CODEX_DIR/agents.bak"
+# mv "$CODEX_DIR/commands" "$CODEX_DIR/commands.bak"
+# mv "$HOME/.agents/skills" "$HOME/.agents/skills.bak"
+rm -rf "$CODEX_DIR/agents" "$CODEX_DIR/commands" "$HOME/.agents/skills"
 ```
 
-### Fix: Missing/Outdated AGENTS.md
-Fetch latest from GitHub and write to `~/.codex/AGENTS.md`:
-```
+If AGENTS.md is missing/outdated, fetch the current raw file and write it to `$CODEX_DIR/AGENTS.md`:
+
+```text
 WebFetch(url: "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-codex/main/docs/AGENTS.md", prompt: "Return the complete raw markdown content exactly as-is")
 ```
 
-### Fix: Legacy Curl-Installed Content
-
-Remove legacy agents/commands plus the historical `~/.agents/skills` tree if it overlaps with the canonical `${CODEX_HOME:-~/.codex}/skills` install:
+To keep only the newest cache version for a selected marketplace:
 
 ```bash
-# Backup first (optional - ask user)
-# mv ~/.codex/agents ~/.codex/agents.bak
-# mv ~/.codex/commands ~/.codex/commands.bak
-# mv ~/.agents/skills ~/.agents/skills.bak
-
-# Or remove directly
-rm -rf ~/.codex/agents
-rm -rf ~/.codex/commands
-rm -rf ~/.agents/skills
+PLUGIN_CACHE_DIR="$PLUGIN_CACHE_ROOT/$MARKETPLACE_NAME/oh-my-codex"
+KEEP_VERSION=$(for d in "$PLUGIN_CACHE_DIR"/*; do [[ -d "$d" ]] && basename "$d"; done | sort -V | tail -1)
+[[ -n "$KEEP_VERSION" ]] && find "$PLUGIN_CACHE_DIR" -mindepth 1 -maxdepth 1 -type d ! -name "$KEEP_VERSION" -exec rm -rf {} +
 ```
 
-**Note**: Only remove if these contain oh-my-codex-related files. If user has custom agents/commands/skills, warn them and ask before removing.
-
----
+If AGENTS.md is missing or stale, refresh it from the current release source, then rerun `omx doctor`. If legacy `~/.agents/skills` overlaps the canonical root, archive/remove that tree only after checking for custom skills. Restart Codex after fixes and report before/after evidence.
 
-## Post-Fix
+## Exit conditions
 
-After applying fixes, inform user:
-> Fixes applied. **Restart Codex CLI** for changes to take effect.
+Stop with **HEALTHY** only when required paths, hook/config checks, AGENTS marker, plugin cache status, and (when requested) Team checks pass. Otherwise report **ISSUES FOUND**, exact failed evidence, and the smallest confirmed remediation; do not claim a fix from a recommendation alone.

package/skills/omx-setup/SKILL.md

@@ -5,136 +5,55 @@ description: Setup and configure oh-my-codex using current CLI behavior
 
 # OMX Setup
 
-Use this skill when users want to install or refresh oh-my-codex for the **current project plus user-level OMX directories**.
+Use this task card to install or refresh OMX for the current project and/or user scope. Shared safety, lifecycle, hook, team, autonomy, and cancellation rules live in `templates/AGENTS.md`. Do not infer new CLI behavior from this card; the implementation is authoritative.
 
-## Command
+## Command and alternatives
 
 ```bash
-omx setup [--force] [--merge-agents|--no-merge-agents|--clear-merge-agents-policy] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>]
+omx setup [--force] [--merge-agents|--no-merge-agents|--clear-merge-agents-policy] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>] [--mcp <none|compat>] [--no-mcp|--with-mcp] [--disable-team|--enable-team|--team-mode <enabled|disabled>]
+omx agents-init [path] [--dry-run] [--force] [--verbose]
 ```
 
-If you only want lightweight `AGENTS.md` scaffolding for an existing repo or subtree, use `omx agents-init [path]` instead of full setup.
-
-Supported setup flags (current implementation):
-- `--force`: overwrite/reinstall managed artifacts where applicable; it is transient and is neither persisted nor replayed
-- `--merge-agents`, `--no-merge-agents`, `--clear-merge-agents-policy`: exact bare policy selectors (equals/value spellings are rejected). Repeated identical selectors are idempotent; conflicting set/clear selectors fail before setup mutations. An explicit set overrides saved policy. `--merge-agents` selects the existing managed-section merge branch; `--no-merge-agents` only suppresses that branch; clear always removes the saved explicit policy and cannot combine with a set selector
-- `--dry-run`: print actions without mutating files
-- `--verbose`: print per-file/per-step details
-- `--scope`: choose install scope (`user`, `project`)
-- `--plugin`: use Codex plugin delivery for bundled skills while archiving/removing legacy OMX-managed prompts/skills, refreshing setup-owned native agent TOMLs for `agent_type` routing, and keeping setup-owned runtime hooks
-- `--legacy`: use legacy setup delivery, overriding any persisted plugin install mode
-- `--install-mode`: explicitly choose setup delivery mode (`legacy` or `plugin`); canonical form for scripted setup
-
-## What this setup actually does
-
-`omx setup` performs these steps:
-
-1. Resolve setup scope:
-   - `--scope` explicit value
-   - else persisted `./.omx/setup-scope.json` (with automatic migration of legacy values)
-   - if a TTY user has persisted setup preferences, `omx setup` first summarizes the recorded choices and asks whether to **keep**, **review/change**, or **reset** them
-   - else interactive prompt on TTY (default `user`)
-   - else default `user` (safe for CI/tests)
-2. Resolve setup install mode:
-   - explicit `--plugin`, `--legacy`, or `--install-mode legacy|plugin`, if present
-   - persisted install mode in `./.omx/setup-scope.json`, if present and the TTY review decision is `keep`
-   - else discovered installed plugin cache under `${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json` with `name: oh-my-codex` makes `plugin` the default for both `user` and `project` scope, so project setup does not duplicate plugin-provided skills/hooks with legacy `.codex/skills` and `.codex/hooks.json`
-   - else in `user` scope, interactive prompt on TTY (`legacy` by default, or `plugin` when a plugin cache is discovered)
-   - else default `legacy` unless a plugin cache is discovered
-3. Create required directories. Preferences are atomically persisted only after all setup work succeeds.
-4. In legacy mode, install prompts/native agents/skills and merge full config.toml. In plugin mode, archive/remove legacy OMX-managed prompts/skills, refresh installable native agent TOMLs for `agent_type` routing, clean up stale generated non-installable native agents, and keep native Codex hooks installed.
-5. Verify Team CLI API interop markers exist in built `dist/cli/team.js`
-6. Generate AGENTS.md defaults only when selected/allowed (or legacy behavior outside plugin mode)
-7. Configure notify hook references outside plugin mode and write `./.omx/hud-config.json`
-
-## Important behavior notes
-
-- `omx setup` prompts for scope when no scope is provided and stdin/stdout are TTY. If `./.omx/setup-scope.json` already exists, setup now summarizes the saved choices first and asks whether to keep them, review/change them, or reset and behave like a fresh setup run.
-- Non-interactive setup never blocks for this review prompt: it keeps deterministic CLI/persisted/default behavior for CI and scripted installs.
-- In `user` scope, `omx setup` also prompts for skill delivery mode when no prior install mode is kept; installed plugin cache discovery makes plugin mode the default prompt/non-interactive choice. In `project` scope, installed plugin cache discovery selects plugin mode non-interactively to avoid overlapping project legacy skills/hooks with plugin-provided surfaces.
-- Local project orchestration file is `./AGENTS.md` (project root).
-- If `AGENTS.md` exists and neither `--force` nor `--merge-agents` is used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
-- Use `--merge-agents` to keep existing project guidance while allowing setup to refresh OMX-managed AGENTS sections and the generated model capability table idempotently.
-- A successful explicit set persists `mergeAgents: true` or `false` in the invoking working root's `./.omx/setup-scope.json`, even for `--scope user`; it is never a global user preference and cannot leak to another root. A valid matching policy is replayed by both immediate and deferred `omx update` refreshes.
-- `--no-merge-agents` is contextual, not a preserve, replace, or safety mode: the current prompt, skip, managed-refresh, plugin-default, and force behavior still controls the non-merge path. Absence keeps existing behavior exactly.
-- TTY review preserves a matching policy while unrelated settings change. Reset or a scope change removes the inherited policy unless the same setup run explicitly sets true or false. `--clear-merge-agents-policy` always removes the policy and cannot combine with a set selector. Malformed, unknown, nonboolean, scopeless, or wrong-scope policy data is treated as absent.
-- Explicit policy intent is atomically committed only after all setup work succeeds. If active-session or plugin-symlink safeguards skip the current AGENTS write but setup otherwise succeeds, explicit true, false, or clear still persists as future update intent; the safeguards themselves are unchanged.
-- Merge is not the default, and this policy does not adopt the rejected #2892 merge-by-default behavior. Older OMX binaries ignore this additive field safely but can erase it when rewriting their known setup preferences.
-- Scope targets:
-  - `user`: user directories (`~/.codex`, `~/.codex/skills`, `~/.omx/agents`)
-  - `project`: local directories (`./.codex`, `./.codex/skills`, `./.omx/agents`)
-- User-scope skill delivery targets:
-  - `legacy`: keep installing/updating OMX skills in the resolved user skill root
-  - `plugin`: rely on Codex plugin discovery for bundled skills and plugin-scoped lifecycle hooks when Codex reports `plugin_hooks`; archive/remove legacy OMX-managed prompts/skills, refresh installable setup-owned native agent TOMLs for `agent_type` routing, and remove only stale generated/non-installable native agents. Setup still enables setup-owned runtime feature flags (`plugin_hooks = true` and `goals = true` when supported, or legacy setup-managed `hooks`/`codex_hooks` fallback when plugin hooks are not reported).
-- Migration hint: in `user` scope, if historical `~/.agents/skills` still exists alongside `${CODEX_HOME:-~/.codex}/skills`, current setup prints a cleanup hint. **Why the paths differ**: `${CODEX_HOME:-~/.codex}/skills/` is the path current Codex CLI natively loads as its skill root; `~/.agents/skills/` was the skill root in an older Codex CLI release before `~/.codex` became the standard home directory. OMX writes only to the canonical `${CODEX_HOME:-~/.codex}/skills/` path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove `~/.agents/skills/` to resolve this.
-- If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
-- Plugin mode prompts separately for optional AGENTS.md defaults and optional `developer_instructions` defaults. If `developer_instructions` already exists, setup asks before overwriting it; non-interactive runs preserve it.
-- With `--force` or `--merge-agents`, AGENTS updates may still be skipped if an active OMX session is detected (safety guard).
-- Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.
-
-## Setup-owned configuration surfaces
-
-Use this map when reconciling setup behavior or debugging a confusing install:
-
-| Surface | Owner | Notes |
-| --- | --- | --- |
-| `./.omx/setup-scope.json` | `omx setup` | Persists setup scope, install mode, and an optional explicit AGENTS merge policy per working root. TTY reruns summarize choices and offer keep/review/reset; only valid matching-scope boolean policy replays on update. |
-| `~/.codex/config.toml` / `./.codex/config.toml` | `omx setup` generated blocks + user edits | Setup refreshes OMX-managed blocks while preserving supported manual content; setup-owned runtime feature flags include `multi_agent`, `child_agents_md`, the Codex hook feature flag (`hooks` or legacy `codex_hooks`), and `goals`. |
-| `~/.codex/hooks.json` / `./.codex/hooks.json` | `omx setup` shared ownership | Setup owns OMX native hook wrappers and preserves user-owned hooks. |
-| prompts, skills, native agents | `omx setup` or Codex plugin delivery | Legacy mode installs local files; plugin mode relies on plugin discovery for bundled skills, archives/removes legacy OMX-managed prompt/skill copies, and refreshes setup-owned native agent TOMLs for `agent_type` routing while cleaning up stale generated/non-installable native agents. |
-| `AGENTS.md` | `omx setup` with overwrite safety | Generated defaults or managed refreshes are guarded by force/session checks. |
-| `./.omx/hud-config.json` | `omx setup` / `$hud` | Setup creates the focused default; `$hud` can adjust it later. |
-| notification hooks | `omx setup` / `$configure-notifications` | Setup wires defaults outside plugin skill delivery; notification skill owns deeper provider configuration. |
-
-## If `$omx-setup` is missing or stale
-
-The source repo ships `skills/omx-setup/SKILL.md` and the catalog marks it active. If Codex does not show `$omx-setup`, treat it as an installation/discovery issue rather than a missing source skill:
-
-1. Run `omx setup --verbose` in the intended scope.
-2. Run `omx doctor` and check the reported setup scope, Codex home, skill root, and hook/config status.
-3. If using project scope, confirm `./.codex/skills/omx-setup/SKILL.md` exists.
-4. If using user scope, confirm `${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md` exists in legacy mode, or that the oh-my-codex plugin is installed/discovered in plugin mode.
-5. If duplicate/stale skills appear, check for legacy `~/.agents/skills` overlap and follow the cleanup hint printed by setup/doctor.
-
-## Recommended workflow
-
-1. Run setup:
+Use `agents-init` for lightweight AGENTS.md scaffolding only, not a full install.
 
-```bash
-omx setup --force --verbose
-```
-
-2. Verify installation:
-
-```bash
-omx doctor
-```
+Supported setup options:
+- `--force`: overwrite/reinstall managed artifacts; transient, not persisted or replayed.
+- `--merge-agents`, `--no-merge-agents`, `--clear-merge-agents-policy`: exact bare selectors (no values/equals). Repeated identical selectors are idempotent; conflicting selectors fail before mutations. Set persists an explicit policy per invoking project root; clear removes it and cannot combine with a set. Merge refreshes managed sections; no-merge only suppresses that branch and is not a preserve mode.
+- `--dry-run`, `--verbose`: preview actions or show per-file/per-step detail.
+- `--scope user|project`: choose user (`~/.codex`, `~/.omx/agents`) or project (`./.codex`, `./.omx/agents`) targets.
+- `--plugin` / `--legacy`: select delivery mode; `--install-mode legacy|plugin` is the canonical scripted spelling. Conflicting mode flags fail.
+- `--mcp none|compat` (plus `--no-mcp` / `--with-mcp`): omit or enable first-party MCP compatibility and shared registry sync.
+- `--disable-team`, `--enable-team`, `--team-mode enabled|disabled`: select Team skill/context generation; conflicting selectors fail.
 
-3. Start Codex with OMX in the target project directory.
+## Resolve setup
 
-## Expected verification indicators
+1. Scope: explicit flag, valid persisted `./.omx/setup-scope.json`, TTY choice (default `user`), or non-interactive `user`. Legacy `project-local` migrates to `project`.
+2. Mode: explicit flag, persisted mode when retained, discovered `${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json` with `name: oh-my-codex` (plugin default), otherwise legacy. TTY reruns summarize saved choices and offer keep/review/reset; non-interactive runs do not block.
+3. Create required directories and atomically persist preferences only after successful setup.
 
-From `omx doctor`, expect:
-- Prompts installed (scope-dependent: user or project)
-- Skills installed (scope-dependent: user or project)
-- AGENTS.md found in project root
-- `.omx/state` exists
-- CLI-first config present in the scope target `config.toml`; first-party OMX MCP servers and shared MCP registry sync are omitted by default unless setup was run with `--mcp compat`
+## What setup changes
 
-## Troubleshooting
+- Legacy mode installs prompts/native agents/skills and merges full config.toml.
+- Plugin mode archives/removes legacy OMX-managed prompts/skills, refreshes installable native agent TOMLs and stale generated non-installable agents, and keeps setup-owned runtime hooks.
+- Both modes verify Team CLI interop markers in built `dist/cli/team.js`, generate AGENTS defaults only when selected/allowed, and write `./.omx/hud-config.json`; notification hook references are setup-owned outside plugin skill delivery.
+- `AGENTS.md` is `./AGENTS.md`. Without `--force` or `--merge-agents`, interactive runs ask before overwrite and non-interactive runs preserve it. Active-session safeguards may skip writes. Plugin mode may separately prompt for AGENTS and `developer_instructions` defaults; non-interactive runs preserve existing files.
+- Plugin mode enables setup-owned runtime flags (`plugin_hooks`, `goals`, or legacy `hooks`/`codex_hooks` fallback). Project scope uses `CODEX_HOME=./.codex` unless explicitly overridden.
 
-- If using local source changes, run build first:
+## Verify
 
 ```bash
-npm run build
+omx setup --force --verbose
+omx doctor
 ```
 
-- If your global `omx` points to another install, run local entrypoint:
+Expect doctor evidence for prompts and skills in the selected scope, project-root AGENTS.md, `.omx/state`, and CLI-first config in the scope target `config.toml`. First-party MCP and shared registry sync are omitted unless setup used `--mcp compat` (if supported by the installed CLI).
 
-```bash
-node bin/omx.js setup --force --verbose
-node bin/omx.js doctor
-```
+If using local source, run `npm run build` before `node bin/omx.js setup --force --verbose` and `node bin/omx.js doctor`. If AGENTS was not overwritten or merged, stop the active OMX session and rerun with `--force` or `--merge-agents`; do not edit lifecycle state manually.
+
+## Discovery troubleshooting
+
+If `$omx-setup` is absent/stale: run `omx setup --verbose`, then `omx doctor`; verify `./.codex/skills/omx-setup/SKILL.md` for project scope or `${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md` for legacy user scope. In plugin mode verify the oh-my-codex plugin is installed/discovered. For duplicates, inspect historical `~/.agents/skills` overlap and follow doctor/setup cleanup guidance.
+
+## Exit contract
 
-- If AGENTS.md was not overwritten during `--force`, stop active OMX session and rerun setup.
-- If AGENTS.md was not merged during `--merge-agents`, stop active OMX session and rerun setup.
+Report selected scope/mode, dry-run versus mutation, AGENTS policy, affected roots, and doctor indicators. Stop only after setup completes successfully and verification identifies the expected files/config; on failure preserve the exact command output and rerun the smallest corrective command. Do not claim installation from a dry-run alone.

package/skills/pipeline/SKILL.md

@@ -1,97 +1,14 @@
 ---
 name: pipeline
-description: Configurable pipeline orchestrator for sequencing stages
+description: Sunset stub — use $plan and $team directly instead
 ---
 
-# Pipeline Skill
+# Pipeline — removed
 
-`$pipeline` is the configurable pipeline orchestrator for OMX. It sequences stages
-through a uniform `PipelineStage` interface, with state persistence and resume support.
+`$pipeline` was removed in OMX 0.21.
 
-## Default Autopilot Pipeline
+Pipeline's configurable stage sequencing overlapped `$plan` (planning) and `$team` (execution) without a unique runtime. Use the canonical skills directly: `$plan` for optional planning, `$team` for coordinated parallel execution, `$ultragoal` for durable goal-mode runs.
 
-The default Autopilot pipeline sequences:
+Migration: replace `$pipeline` with explicit `$plan` and `$team` invocations as the task warrants.
 
-```
-deep-interview -> ralplan -> ultragoal (+ team if needed) -> code-review -> ultraqa
-```
-
-`$team` is conditional: use it only inside an active Ultragoal story when independent lanes or broad verification make coordinated parallel execution useful. Explicit legacy Ralph pipelines remain available through custom stages, but Ralph is not the advertised default Autopilot loop.
-
-## Configuration
-
-Pipeline parameters are configurable per run:
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `maxRalphIterations` | 10 | Quality-gate retry ceiling; legacy option name retained for compatibility |
-| `workerCount` | 2 | Number of Codex CLI team workers |
-| `agentType` | `executor` | Agent type for team workers |
-
-## Stage Interface
-
-Every stage implements the `PipelineStage` interface:
-
-```typescript
-interface PipelineStage {
-  readonly name: string;
-  run(ctx: StageContext): Promise<StageResult>;
-  canSkip?(ctx: StageContext): boolean;
-}
-```
-
-Stages receive a `StageContext` with accumulated artifacts from prior stages and
-return a `StageResult` with status, artifacts, and duration.
-
-## Built-in Stages
-
-- **deep-interview**: Requirements clarification and ambiguity gate.
-- **ralplan**: Consensus planning (planner + architect + critic). Skips only when both `prd-*.md` and `test-spec-*.md` planning artifacts already exist **and** durable consensus evidence records Architect approval followed by Critic approval. Plan/test-spec files alone are not consensus evidence. If either review is missing, blocked, out of order, or non-approving, the stage remains in ralplan or fails with an explicit blocker/max-iteration outcome instead of progressing to execution. Carries any `deep-interview-*.md` spec paths forward for traceability.
-- **ultragoal**: Durable goal-mode execution with `.omx/ultragoal` ledgers. Launch `$team` only from inside an Ultragoal story when parallel lanes are warranted.
-- **code-review**: Merge-readiness review gate.
-- **ultraqa**: Adversarial QA gate after a clean review; docs-only/trivially non-runtime changes may record an explicit skip reason.
-- **team-exec** and **ralph-verify**: Legacy/custom pipeline adapters retained for explicit non-default pipelines.
-
-## State Management
-
-Pipeline state persists via the ModeState system at `.omx/state/pipeline-state.json`.
-The HUD renders pipeline phase automatically. Resume is supported from the last incomplete stage.
-
-- **On start**: `omx state write --input '{"mode":"pipeline","active":true,"current_phase":"stage:ralplan"}' --json`
-- **On stage transitions**: `omx state write --input '{"mode":"pipeline","current_phase":"stage:<name>"}' --json`
-- **On completion**: `omx state write --input '{"mode":"pipeline","active":false,"current_phase":"complete"}' --json`
-
-## API
-
-```typescript
-import {
-  runPipeline,
-  createAutopilotPipelineConfig,
-  createDeepInterviewStage,
-  createRalplanStage,
-  createUltragoalStage,
-  createCodeReviewStage,
-  createUltraqaStage,
-} from './pipeline/index.js';
-
-const config = createAutopilotPipelineConfig('build feature X', {
-  stages: [
-    createDeepInterviewStage(),
-    createRalplanStage(),
-    createUltragoalStage(),
-    createCodeReviewStage(),
-    createUltraqaStage(),
-  ],
-});
-
-const result = await runPipeline(config);
-```
-
-## Relationship to Other Modes
-
-- **autopilot**: Autopilot can use pipeline as its execution engine (v0.8+)
-- **team**: Pipeline delegates execution to team mode (Codex CLI workers)
-- **ultragoal**: Autopilot delegates durable execution to Ultragoal by default
-- **team**: Optional execution engine inside an Ultragoal story when parallel lanes are needed
-- **ralph**: Available only for explicit legacy/custom pipelines
-- **ralplan**: Pipeline planning runs RALPLAN consensus planning
+Task: {{ARGUMENTS}}