oh-my-codex 0.8.0 → 0.8.2

package/skills/configure-notifications/SKILL.md

@@ -24,255 +24,263 @@ triggers:
 
 # Configure OMX Notifications
 
-Unified entry point for setting up notifications across all supported platforms.
-OMX can notify you on Discord, Telegram, Slack, or your own OpenClaw gateway.
+Unified and only entry point for notification setup.
 
-## How This Skill Works
+- **Native integrations (first-class):** Discord, Telegram, Slack
+- **Generic extensibility integrations:** `custom_webhook_command`, `custom_cli_command`
 
-This skill detects what's already configured, presents a menu, and delegates to the
-appropriate platform skill. It also handles cross-cutting settings like verbosity,
-notification profiles, reply listener, and idle cooldown.
+> Standalone configure skills (`configure-discord`, `configure-telegram`, `configure-slack`, `configure-openclaw`) are removed.
 
-## Step 1: Detect Currently Configured Platforms
+## Step 1: Inspect Current State
 
 ```bash
 CONFIG_FILE="$HOME/.codex/.omx-config.json"
 
 if [ -f "$CONFIG_FILE" ]; then
-  DISCORD_ENABLED=$(jq -r '.notifications.discord.enabled // false' "$CONFIG_FILE" 2>/dev/null)
-  DISCORD_BOT_ENABLED=$(jq -r '.notifications["discord-bot"].enabled // false' "$CONFIG_FILE" 2>/dev/null)
-  TELEGRAM_ENABLED=$(jq -r '.notifications.telegram.enabled // false' "$CONFIG_FILE" 2>/dev/null)
-  SLACK_ENABLED=$(jq -r '.notifications.slack.enabled // false' "$CONFIG_FILE" 2>/dev/null)
-  OPENCLAW_ENABLED=$(jq -r '.notifications.openclaw.enabled // false' "$CONFIG_FILE" 2>/dev/null)
-  NOTIF_ENABLED=$(jq -r '.notifications.enabled // false' "$CONFIG_FILE" 2>/dev/null)
-  VERBOSITY=$(jq -r '.notifications.verbosity // "session"' "$CONFIG_FILE" 2>/dev/null)
-  COOLDOWN=$(jq -r '.notifications.idleCooldownSeconds // 60' "$CONFIG_FILE" 2>/dev/null)
-  REPLY_ENABLED=$(jq -r '.notifications.reply.enabled // false' "$CONFIG_FILE" 2>/dev/null)
-
-  echo "NOTIF_ENABLED=$NOTIF_ENABLED"
-  echo "DISCORD_ENABLED=$DISCORD_ENABLED"
-  echo "DISCORD_BOT_ENABLED=$DISCORD_BOT_ENABLED"
-  echo "TELEGRAM_ENABLED=$TELEGRAM_ENABLED"
-  echo "SLACK_ENABLED=$SLACK_ENABLED"
-  echo "OPENCLAW_ENABLED=$OPENCLAW_ENABLED"
-  echo "VERBOSITY=$VERBOSITY"
-  echo "COOLDOWN=$COOLDOWN"
-  echo "REPLY_ENABLED=$REPLY_ENABLED"
+  jq -r '
+    {
+      notifications_enabled: (.notifications.enabled // false),
+      discord: (.notifications.discord.enabled // false),
+      discord_bot: (.notifications["discord-bot"].enabled // false),
+      telegram: (.notifications.telegram.enabled // false),
+      slack: (.notifications.slack.enabled // false),
+      openclaw: (.notifications.openclaw.enabled // false),
+      custom_webhook_command: (.notifications.custom_webhook_command.enabled // false),
+      custom_cli_command: (.notifications.custom_cli_command.enabled // false),
+      verbosity: (.notifications.verbosity // "session"),
+      idleCooldownSeconds: (.notifications.idleCooldownSeconds // 60),
+      reply_enabled: (.notifications.reply.enabled // false)
+    }
+  ' "$CONFIG_FILE"
 else
   echo "NO_CONFIG_FILE"
 fi
 ```
 
-## Step 2: Show Current Status and Main Menu
+## Step 2: Main Menu
 
-Display a summary of what's configured:
-
-```
-OMX Notification Status
-───────────────────────
-  Discord webhook: enabled / not configured
-  Discord bot:     enabled / not configured
-  Telegram:        enabled / not configured
-  Slack:           enabled / not configured
-  OpenClaw:        enabled / not configured
-
-  Verbosity:       session (default)
-  Idle cooldown:   60s
-  Reply listener:  disabled
-```
-
-Then use AskUserQuestion:
+Use AskUserQuestion:
 
 **Question:** "What would you like to configure?"
 
 **Options:**
-1. **Discord** - Webhook or bot notifications to Discord channels
-2. **Telegram** - Bot notifications to personal or group chats
-3. **Slack** - Incoming webhook notifications to Slack channels
-4. **OpenClaw** - Self-hosted gateway (`notifications.openclaw.gateways + hooks`) with /hooks/agent delivery verification
-5. **Cross-cutting settings** - Verbosity, idle cooldown, profiles, reply listener
-6. **Disable all notifications** - Turn off all notification dispatching
+1. **Discord (native)** - webhook or bot
+2. **Telegram (native)** - bot token + chat id
+3. **Slack (native)** - incoming webhook
+4. **Generic webhook command** - `custom_webhook_command`
+5. **Generic CLI command** - `custom_cli_command`
+6. **Cross-cutting settings** - verbosity, idle cooldown, profiles, reply listener
+7. **Disable all notifications** - set `notifications.enabled = false`
 
-## Step 3: Delegate to Platform Skill
+## Step 3: Configure Native Platforms (Discord / Telegram / Slack)
 
-Based on the user's choice, invoke the appropriate platform skill:
+Collect and validate platform-specific values, then write directly under native keys:
 
-- **Discord** → invoke `/configure-discord`
-- **Telegram** → invoke `/configure-telegram`
-- **Slack** → invoke `/configure-slack`
-- **OpenClaw** → invoke `/configure-openclaw`
-- **Cross-cutting settings** → continue with Step 4 below
-- **Disable all** → continue with Step 5 below
+- Discord webhook: `notifications.discord`
+- Discord bot: `notifications["discord-bot"]`
+- Telegram: `notifications.telegram`
+- Slack: `notifications.slack`
 
-When delegating, say: "Starting the [Platform] configuration wizard..." and invoke the skill.
+Do not write these as generic command/webhook aliases.
 
-## Step 4: Cross-Cutting Settings
+## Step 4: Configure Generic Extensibility
 
-If the user chose "Cross-cutting settings":
+### 4a) `custom_webhook_command`
 
-### 4a. Verbosity
+Use AskUserQuestion to collect:
+- URL
+- Optional headers
+- Optional method (`POST` default, or `PUT`)
+- Optional event list (`session-end`, `ask-user-question`, `session-start`, `session-idle`, `stop`)
+- Optional instruction template
 
-Use AskUserQuestion:
+Write:
 
-**Question:** "How verbose should notifications be?"
+```bash
+jq \
+  --arg url "$URL" \
+  --arg method "${METHOD:-POST}" \
+  --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.custom_webhook_command = {
+     enabled: true,
+     url: $url,
+     method: $method,
+     instruction: $instruction,
+     events: ["session-end", "ask-user-question"]
+   }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
+```
 
-**Options:**
-1. **session (Recommended)** - Start, idle, stop, end events + tmux snippet
-2. **minimal** - Start, stop, end only (no idle events, no tmux tail)
-3. **agent** - All session events plus ask-user-question prompts
-4. **verbose** - Everything including tool call output
+### 4b) `custom_cli_command`
 
-Write verbosity to config:
+Use AskUserQuestion to collect:
+- Command template (supports `{{event}}`, `{{instruction}}`, `{{sessionId}}`, `{{projectPath}}`)
+- Optional event list
+- Optional instruction template
+
+Write:
 
 ```bash
-echo "$(cat "$CONFIG_FILE")" | jq \
-  --arg verbosity "$VERBOSITY" \
-  '.notifications.verbosity = $verbosity' > "$CONFIG_FILE"
+jq \
+  --arg command "$COMMAND_TEMPLATE" \
+  --arg instruction "${INSTRUCTION:-OMX event {{event}} for {{projectPath}}}" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.custom_cli_command = {
+     enabled: true,
+     command: $command,
+     instruction: $instruction,
+     events: ["session-end", "ask-user-question"]
+   }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-Env var alternative: `OMX_NOTIFY_VERBOSITY=session`
+> Activation gate: OpenClaw-backed dispatch is active only when `OMX_OPENCLAW=1`.
+> For command gateways, also require `OMX_OPENCLAW_COMMAND=1`.
+> Optional timeout env override: `OMX_OPENCLAW_COMMAND_TIMEOUT_MS` (ms).
 
-### 4b. Idle Notification Cooldown
+### 4b-1) OpenClaw + Clawdbot Agent Workflow (recommended for dev)
 
-Use AskUserQuestion:
+If the user explicitly asks to route hook notifications through **clawdbot agent turns**
+(not direct message/webhook forwarding), use a command gateway that invokes
+`clawdbot agent` and delivers back to Discord.
 
-**Question:** "How often should idle notifications fire at most? (in seconds)"
+Notes:
+- Hook name mapping is intentional: notifications `session-stop` -> OpenClaw hook `stop`.
+- OMX shell-escapes template substitutions for command gateways (including `{{instruction}}`).
+- Keep `instruction` templates concise and avoid untrusted shell metacharacters.
+- During troubleshooting, avoid swallowing command output; route it to a log file.
+- Timeout precedence: `gateways.<name>.timeout` > `OMX_OPENCLAW_COMMAND_TIMEOUT_MS` > `5000`.
+- For clawdbot agent workflows, set `gateways.<name>.timeout` to `120000` (recommended).
+- For dev operations, enforce Korean output in all hook instructions.
+- Include both `session={{sessionId}}` and `tmux={{tmuxSession}}` in hook text for traceability.
+- If follow-up is needed, explicitly instruct clawdbot to consult `SOUL.md` and continue in `#omc-dev`.
+- **Error handling**: Append `|| true` to prevent OMX hook failures from blocking the session.
+- **JSONL logging**: Use `.jsonl` extension and append (`>>`) for structured log aggregation.
+- **Reply target format**: Use `--reply-to 'channel:CHANNEL_ID'` for reliability (preferred over channel aliases).
 
-**Options:**
-1. **60 seconds (default)** - At most once per minute
-2. **300 seconds** - At most once per 5 minutes
-3. **0 (disabled)** - Send every turn with no throttling
-4. **Custom** - Enter a number of seconds
-
-Write the cooldown to config:
+Example (targeting `#omc-dev` with production-tested settings):
 
 ```bash
-echo "$(cat "$CONFIG_FILE")" | jq \
-  --argjson cooldown "$COOLDOWN_SECONDS" \
-  '.notifications.idleCooldownSeconds = $cooldown' > "$CONFIG_FILE"
+jq \
+  --arg command "(clawdbot agent --session-id omx-hooks --message {{instruction}} --thinking minimal --deliver --reply-channel discord --reply-to 'channel:1468539002985644084' --timeout 120 --json >>/tmp/omx-openclaw-agent.jsonl 2>&1 || true)" \
+  '.notifications = (.notifications // {enabled: true}) |
+   .notifications.enabled = true |
+   .notifications.verbosity = "verbose" |
+   .notifications.events = (.notifications.events // {}) |
+   .notifications.events["session-start"] = {enabled: true} |
+   .notifications.events["session-idle"] = {enabled: true} |
+   .notifications.events["ask-user-question"] = {enabled: true} |
+   .notifications.events["session-stop"] = {enabled: true} |
+   .notifications.events["session-end"] = {enabled: true} |
+   .notifications.openclaw = (.notifications.openclaw // {}) |
+   .notifications.openclaw.enabled = true |
+   .notifications.openclaw.gateways = (.notifications.openclaw.gateways // {}) |
+   .notifications.openclaw.gateways["local"] = {
+     type: "command",
+     command: $command,
+     timeout: 120000
+   } |
+   .notifications.openclaw.hooks = (.notifications.openclaw.hooks // {}) |
+   .notifications.openclaw.hooks["session-start"] = {
+     enabled: true,
+     gateway: "local",
+     instruction: "OMX hook=session-start project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 상태를 공유하고 SOUL.md를 참고해 필요한 후속 조치를 #omc-dev에 안내하세요."
+   } |
+   .notifications.openclaw.hooks["session-idle"] = {
+     enabled: true,
+     gateway: "local",
+     instruction: "OMX hook=session-idle project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 idle 상황을 간단히 공유하고 진행중인 작업 팔로업을 안내하세요."
+   } |
+   .notifications.openclaw.hooks["ask-user-question"] = {
+     enabled: true,
+     gateway: "local",
+     instruction: "OMX hook=ask-user-question session={{sessionId}} tmux={{tmuxSession}} question={{question}}. 한국어로 사용자 응답 필요를 #omc-dev에 알리고 즉시 액션 아이템을 제시하세요."
+   } |
+   .notifications.openclaw.hooks["stop"] = {
+     enabled: true,
+     gateway: "local",
+     instruction: "OMX hook=session-stop project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}. 한국어로 중단 상태와 정리 액션을 SOUL.md 기준으로 전달하세요."
+   } |
+   .notifications.openclaw.hooks["session-end"] = {
+     enabled: true,
+     gateway: "local",
+     instruction: "OMX hook=session-end project={{projectName}} session={{sessionId}} tmux={{tmuxSession}} reason={{reason}}. 한국어로 완료 요약을 1줄로 남기고 필요한 후속 조치를 안내하세요."
+   }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-Env var alternative: `OMX_IDLE_COOLDOWN_SECONDS=60`
-
-### 4c. Notification Profiles
+Verification for this mode:
 
-Explain that profiles let the user have different notification configs per context:
-
-```
-Notification Profiles
-─────────────────────
-Profiles let you switch notification targets based on context.
-For example: a "work" profile for your work Slack, a "personal"
-profile for your personal Telegram.
-
-Activate a profile with: OMX_NOTIFY_PROFILE=work
-or set a default: .omx-config.json > notifications.defaultProfile
+```bash
+clawdbot agent --session-id omx-hooks --message "OMX hook test via clawdbot agent path" \
+  --thinking minimal --deliver --reply-channel discord --reply-to 'channel:1468539002985644084' --timeout 120 --json
 ```
 
-Use AskUserQuestion:
-
-**Question:** "Would you like to configure notification profiles?"
-
-**Options:**
-1. **Yes** - Set up named profiles
-2. **No, use flat config** - Keep the current single-config setup
+Dev runbook (Korean + tmux follow-up):
 
-If yes, guide the user to manually add profiles under `notifications.profiles` in `.omx-config.json`, and set `defaultProfile`.
+```bash
+# 1) identify active OMX tmux sessions
+tmux list-sessions -F '#{session_name}' | rg '^omx-' || true
 
-### 4d. Reply Listener
+# 2) confirm hook templates include session/tmux context
+jq '.notifications.openclaw.hooks' "$CONFIG_FILE"
 
-Explain the reply listener:
+# 3) inspect agent JSONL logs when delivery looks broken
+tail -n 120 /tmp/omx-openclaw-agent.jsonl | jq -s '.[] | {timestamp: (.timestamp // .time), status: (.status // .error // "ok")}'
 
+# 4) check for recent errors in logs
+rg '"error"|"failed"|"timeout"' /tmp/omx-openclaw-agent.jsonl | tail -20
 ```
-Reply Listener
-──────────────
-The reply listener lets you send messages back to Codex from
-Discord (bot) or Telegram. When OMX asks for input, you can
-reply directly from your phone or messaging app.
-
-Requires:
-  - Discord Bot or Telegram platform configured
-  - OMX_REPLY_ENABLED=true in your shell profile
-  - For Discord: OMX_REPLY_DISCORD_USER_IDS=<your user ID>
-    (only messages from these IDs are accepted for security)
-```
-
-Use AskUserQuestion:
-
-**Question:** "Would you like to enable the reply listener?"
 
-**Options:**
-1. **Yes** - Enable two-way communication from Discord/Telegram
-2. **No** - Keep notifications one-way only
+### 4c) Compatibility + precedence contract
 
-If yes, write to config:
+OMX accepts both:
+- explicit `notifications.openclaw` schema (legacy/runtime shape)
+- generic aliases (`custom_webhook_command`, `custom_cli_command`)
 
-```bash
-echo "$(cat "$CONFIG_FILE")" | jq \
-  '.notifications.reply = (.notifications.reply // {}) |
-   .notifications.reply.enabled = true' > "$CONFIG_FILE"
-```
+Deterministic precedence:
+1. `notifications.openclaw` **wins** when present and valid.
+2. Generic aliases are ignored in that case (with warning).
 
-And remind them to set `OMX_REPLY_ENABLED=true` and (for Discord) `OMX_REPLY_DISCORD_USER_IDS`.
+## Step 5: Cross-Cutting Settings
 
-## Step 5: Disable All Notifications
+### Verbosity
+- minimal / session (recommended) / agent / verbose
 
-If the user chose "Disable all notifications":
-
-Use AskUserQuestion:
+### Idle cooldown
+- `notifications.idleCooldownSeconds`
 
-**Question:** "Are you sure you want to disable all notifications?"
+### Profiles
+- `notifications.profiles`
+- `notifications.defaultProfile`
 
-**Options:**
-1. **Yes, disable all** - Set notifications.enabled = false
-2. **No, go back** - Return to the main menu
+### Reply listener
+- `notifications.reply.enabled`
+- env gates: `OMX_REPLY_ENABLED=true`, and for Discord `OMX_REPLY_DISCORD_USER_IDS=...`
 
-If confirmed:
+## Step 6: Disable All Notifications
 
 ```bash
-echo "$(cat "$CONFIG_FILE")" | jq \
-  '.notifications.enabled = false' > "$CONFIG_FILE"
+jq '.notifications.enabled = false' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
 ```
 
-Confirm: "Notifications disabled. Re-enable anytime by running /configure-notifications."
-
-## Step 6: After Configuration
-
-After completing any platform or setting configuration, offer to configure another:
-
-Use AskUserQuestion:
+## Step 7: Verification Guidance
 
-**Question:** "Would you like to configure another platform or setting?"
+After writing config, run a smoke check:
 
-**Options:**
-1. **Yes** - Return to the main menu (Step 2)
-2. **No, I'm done** - Show final summary and exit
+```bash
+npm run build
+```
 
-## Final Summary
+For OpenClaw-like HTTP integrations, verify both:
+- `/hooks/wake` smoke test
+- `/hooks/agent` delivery verification
 
-Display a summary of all active notification platforms:
+## Final Summary Template
 
-```
-OMX Notification Configuration Complete!
-─────────────────────────────────────────
-  Active platforms:
-    Discord webhook: enabled
-    Telegram:        enabled
-
-  Verbosity:       session
-  Idle cooldown:   60s
-  Reply listener:  disabled
-
-Config saved to: ~/.codex/.omx-config.json
-
-Quick reference — env vars:
-  OMX_DISCORD_WEBHOOK_URL=...
-  OMX_TELEGRAM_BOT_TOKEN=...
-  OMX_TELEGRAM_CHAT_ID=...
-  OMX_SLACK_WEBHOOK_URL=...
-  OMX_NOTIFY_VERBOSITY=session
-  OMX_IDLE_COOLDOWN_SECONDS=60
-  OMX_OPENCLAW=1
-
-Run /configure-notifications again to update any settings.
-```
+Show:
+- Native platforms enabled
+- Generic aliases enabled (`custom_webhook_command`, `custom_cli_command`)
+- Whether explicit `notifications.openclaw` exists (and therefore overrides aliases)
+- Verbosity + idle cooldown + reply listener state
+- Config path (`~/.codex/.omx-config.json`)

package/skills/omx-setup/SKILL.md

@@ -30,7 +30,7 @@ Supported setup flags (current implementation):
    - else default `user` (safe for CI/tests)
 2. Create directories and persist effective scope
 3. Install prompts, native agent configs, skills, and merge config.toml (scope determines target directories)
-4. Verify required team MCP comm tool exports exist in built `dist/mcp/state-server.js`
+4. Verify Team CLI API interop markers exist in built `dist/cli/team.js`
 5. Generate project-root `./AGENTS.md` from `templates/AGENTS.md` (or skip when existing and no force)
 6. Configure notify hook references and write `./.omx/hud-config.json`
 

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ description: N coordinated agents on shared task list using tmux-based orchestra
 
 # Team Skill
 
-`$team` is the tmux-based parallel execution mode for OMX. It starts real worker Codex and/or Claude CLI sessions in split panes and coordinates them through `.omx/state/team/...` files plus MCP team tools.
+`$team` is the tmux-based parallel execution mode for OMX. It starts real worker Codex and/or Claude CLI sessions in split panes and coordinates them through `.omx/state/team/...` files plus CLI team interop (`omx team api ...`) and state files.
 
 This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.
 
@@ -166,6 +166,23 @@ Follow this exact lifecycle when running `$team`:
 Do not run `shutdown` while workers are actively writing updates unless user explicitly requested abort/cancel.
 Do not treat ad-hoc pane typing as primary control flow when runtime/state evidence is available.
 
+## Message Dispatch Policy (CLI-first, state-first)
+
+To avoid brittle behavior, **message/task delivery must not be driven by ad-hoc tmux typing**.
+
+Required default path:
+
+1. Use `omx team ...` runtime lifecycle commands for orchestration.
+2. Use `omx team api ... --json` for mailbox/task mutations.
+3. Verify delivery via mailbox/state evidence (`mailbox/*.json`, task status, `omx team status`).
+
+Strict rules:
+
+- **MUST NOT** use direct `tmux send-keys` as the primary mechanism to deliver instructions/messages.
+- **MUST NOT** spam Enter/trigger keys without first checking runtime/state evidence.
+- **MUST** prefer durable state writes + runtime dispatch (`dispatch/requests.json`, mailbox, inbox).
+- Direct tmux interaction is **fallback-only** and only after failure checks (for example `worker_notify_failed:<worker>`) or explicit user request (for example “press enter”).
+
 ## Operational Commands
 
 ```bash
@@ -206,6 +223,31 @@ Semantics:
 - `.omx/state/team/<team>/workers/worker-<n>/status.json`
 - `.omx/state/team-leader-nudge.json`
 
+
+## Team Mutation Interop (CLI-first)
+
+Use `omx team api` for machine-readable mutation/reads instead of legacy `team_*` MCP tools.
+
+```bash
+omx team api <operation> --input '{"team_name":"my-team",...}' --json
+```
+
+Examples:
+
+```bash
+omx team api send-message --input '{"team_name":"my-team","from_worker":"worker-1","to_worker":"leader-fixed","body":"ACK"}' --json
+omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json
+omx team api transition-task-status --input '{"team_name":"my-team","task_id":"1","from":"in_progress","to":"completed","claim_token":"<token>"}' --json
+```
+
+`--json` responses include stable metadata for automation:
+- `schema_version`
+- `timestamp`
+- `command`
+- `ok`
+- `operation`
+- `data` or `error`
+
 ## Team + Worker Protocol Notes
 
 Leader-to-worker:
@@ -215,8 +257,8 @@ Leader-to-worker:
 
 Worker-to-leader:
 
-- Send ACK to `leader-fixed` mailbox via `team_send_message`
-- Claim task via state API, execute, update task + status
+- Send ACK to `leader-fixed` mailbox via `omx team api send-message --json`
+- Claim/transition/release task lifecycle via `omx team api <operation> --json`
 
 Task ID rule (critical):
 
@@ -294,10 +336,10 @@ Checks:
 
 1. Worker pane capture shows inbox processing
 2. `.omx/state/team/<team>/mailbox/leader-fixed.json` exists
-3. Worker skill loaded and `team_send_message` called
+3. Worker skill loaded and `omx team api send-message --json` called
 4. Task-id mismatch not blocking worker flow
 
-### Worker logs `team_send_message ENOENT` / `team_update_task ENOENT`
+### Worker logs `omx team api ... ENOENT` (or legacy `team_send_message ENOENT` / `team_update_task ENOENT`)
 
 Meaning:
 - Team state path no longer exists while worker is still running.

package/skills/worker/SKILL.md

@@ -15,22 +15,37 @@ You MUST be running with `OMX_TEAM_WORKER` set. It looks like:
 
 Example: `alpha/worker-2`
 
+## Load Worker Skill Path (Claude/Codex)
+
+When a worker inbox tells you to load this skill, resolve the first existing path:
+
+1. `${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md`
+2. `~/.agents/skills/worker/SKILL.md`
+3. `<leader_cwd>/.agents/skills/worker/SKILL.md`
+4. `<leader_cwd>/skills/worker/SKILL.md` (repo fallback)
+
 ## Startup Protocol (ACK)
 
 1. Parse `OMX_TEAM_WORKER` into:
    - `teamName` (before the `/`)
    - `workerName` (after the `/`, usually `worker-<n>`)
-2. Send an ACK to the lead mailbox:
+2. Send a startup ACK to the lead mailbox **before task work**:
    - Recipient worker id: `leader-fixed`
-   - Body: one short line including your workerName and what you’re ready to do.
+   - Body: one short deterministic line (recommended: `ACK: <workerName> initialized`).
 3. After ACK, proceed to your inbox instructions.
 
 The lead will see your message in:
 
 `<team_state_root>/team/<teamName>/mailbox/leader-fixed.json`
 
-Use the MCP tool:
-- `team_send_message` with `{team_name, from_worker, to_worker:"leader-fixed", body}`
+Use CLI interop:
+- `omx team api send-message --input <json> --json` with `{team_name, from_worker, to_worker:"leader-fixed", body}`
+
+Copy/paste template:
+
+```bash
+omx team api send-message --input "{\"team_name\":\"<teamName>\",\"from_worker\":\"<workerName>\",\"to_worker\":\"leader-fixed\",\"body\":\"ACK: <workerName> initialized\"}" --json
+```
 
 ## Inbox + Tasks
 
@@ -47,11 +62,11 @@ Use the MCP tool:
 5. Task id format:
    - The MCP/state API uses the numeric id (`"1"`), not `"task-1"`.
    - Never use legacy `tasks/{id}.json` wording.
-6. Claim the task (do NOT start work without a claim) using claim-safe lifecycle APIs (`team_claim_task` / `claimTask`).
+6. Claim the task (do NOT start work without a claim) using claim-safe lifecycle CLI interop (`omx team api claim-task --json`).
 7. Do the work.
-8. Complete/fail the task via lifecycle transition APIs (`team_transition_task_status` / `transitionTaskStatus`) from `in_progress` to `completed` or `failed`.
+8. Complete/fail the task via lifecycle transition CLI interop (`omx team api transition-task-status --json`) from `in_progress` to `completed` or `failed`.
    - Do NOT directly write lifecycle fields (`status`, `owner`, `result`, `error`) in task files.
-9. Use `team_release_task_claim` / `releaseTaskClaim` only for rollback/requeue to `pending` (not for completion).
+9. Use `omx team api release-task-claim --json` only for rollback/requeue to `pending` (not for completion).
 10. Update your worker status:
    `<team_state_root>/team/<teamName>/workers/<workerName>/status.json` with `{"state":"idle", ...}`
 
@@ -67,9 +82,24 @@ Note: leader dispatch is state-first. The durable queue lives at:
 `<team_state_root>/team/<teamName>/dispatch/requests.json`
 Hooks/watchers may nudge you after mailbox/inbox state is already written.
 
-Use MCP tools:
-- `team_mailbox_list` to read
-- `team_mailbox_mark_delivered` to acknowledge delivery
+Use CLI interop:
+- `omx team api mailbox-list --json` to read
+- `omx team api mailbox-mark-delivered --json` to acknowledge delivery
+
+Copy/paste templates:
+
+```bash
+omx team api mailbox-list --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\"}" --json
+omx team api mailbox-mark-delivered --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\",\"message_id\":\"<MESSAGE_ID>\"}" --json
+```
+
+## Dispatch Discipline (state-first)
+
+Worker sessions should treat team state + CLI interop as the source of truth.
+
+- Prefer inbox/mailbox/task state and `omx team api ... --json` operations.
+- Do **not** rely on ad-hoc tmux keystrokes as a primary delivery channel.
+- If a manual trigger arrives (for example `tmux send-keys` nudge), treat it only as a prompt to re-check state and continue through the normal claim-safe lifecycle.
 
 ## Shutdown