oh-my-codex 0.16.3 → 0.16.4

package/skills/frontend-ui-ux/SKILL.md

@@ -1,34 +1,12 @@
 ---
 name: frontend-ui-ux
-description: Designer-developer for UI/UX work
+description: Deprecated compatibility shim for designer-led frontend UI/UX work
 ---
 
-# Frontend UI/UX Command
+# Frontend UI/UX compatibility shim
 
-Routes to the designer agent or Gemini MCP for frontend work.
+Hard-deprecated. Do not invoke or route this skill for new work.
 
-## Usage
-
-```
-/frontend-ui-ux <design task>
-```
-
-## Routing
-
-### Preferred: MCP Direct
-Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools.
-Use `mcp__g__ask_gemini` with `agent_role: "designer"` for design tasks.
-If ToolSearch finds no MCP tools, use the Codex agent fallback below.
-
-### Fallback: Codex Agent
-```
-delegate(role="designer", tier="STANDARD", task="{{ARGUMENTS}}")
-```
-
-## Capabilities
-- Component design and implementation
-- Responsive layouts
-- Design system consistency
-- Accessibility compliance
+Use the `designer` agent/lane directly, or use `$visual-ralph` when the task needs visual iteration and screenshot-based verification. This file exists only to preserve the public/catalog-visible `frontend-ui-ux` alias contract while designer-led frontend guidance is handled by the canonical designer surfaces.
 
 Task: {{ARGUMENTS}}

package/skills/git-master/SKILL.md

@@ -15,8 +15,8 @@ Routes to the git-master agent for git operations.
 
 ## Routing
 
-```
-delegate(role="git-master", tier="STANDARD", task="{{ARGUMENTS}}")
+```text
+Use /prompts:git-master with the user task.
 ```
 
 ## Capabilities
@@ -25,5 +25,3 @@ delegate(role="git-master", tier="STANDARD", task="{{ARGUMENTS}}")
 - Branch management
 - History cleanup
 - Style detection from repo history
-
-Task: {{ARGUMENTS}}

package/skills/omx-setup/SKILL.md

@@ -60,7 +60,7 @@ Supported setup flags (current implementation):
   - `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 archive/remove legacy OMX-managed prompts/skills/native agents; setup still installs native Codex hooks and setup-owned runtime feature flags (`codex_hooks = true`, `goals = true`) because plugins do not carry hooks or enable Codex goal mode by themselves.
+  - `plugin`: rely on Codex plugin discovery for bundled skills and archive/remove legacy OMX-managed prompts/skills/native agents; setup still installs native Codex hooks and setup-owned runtime feature flags (`hooks = true` on current Codex, legacy `codex_hooks = true` when that is the only reported hook feature, plus `goals = true`) because plugins do not carry hooks or enable Codex goal mode by themselves.
 - 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.
@@ -74,7 +74,7 @@ Use this map when reconciling setup behavior or debugging a confusing install:
 | Surface | Owner | Notes |
 | --- | --- | --- |
 | `./.omx/setup-scope.json` | `omx setup` | Persists setup scope and user-scope skill delivery mode. TTY reruns summarize it and offer keep/review/reset. |
-| `~/.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`, `codex_hooks`, and `goals`. |
+| `~/.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 and archives/removes legacy OMX-managed prompt/native-agent copies. |
 | `AGENTS.md` | `omx setup` with overwrite safety | Generated defaults or managed refreshes are guarded by force/session checks. |
@@ -114,7 +114,7 @@ From `omx doctor`, expect:
 - Skills installed (scope-dependent: user or project)
 - AGENTS.md found in project root
 - `.omx/state` exists
-- OMX MCP servers configured in scope target `config.toml` (`~/.codex/config.toml` or `./.codex/config.toml`)
+- 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`
 
 ## Troubleshooting
 

package/skills/pipeline/SKILL.md

@@ -52,9 +52,9 @@ return a `StageResult` with status, artifacts, and duration.
 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**: `state_write({mode: "pipeline", active: true, current_phase: "stage:ralplan"})`
-- **On stage transitions**: `state_write({mode: "pipeline", current_phase: "stage:<name>"})`
-- **On completion**: `state_write({mode: "pipeline", active: false, current_phase: "complete"})`
+- **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
 

package/skills/plan/SKILL.md

@@ -137,15 +137,13 @@ Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 </Steps>
 
 <Tool_Usage>
-- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
-- Use the surface-appropriate structured question path for preference questions (scope, priority, timeline, risk tolerance): attached-tmux OMX runtime uses `omx question`; outside tmux uses native structured input when available. Use plain text only as a last fallback for unsupported surfaces or highly specific free-form values.
-- `omx question` success JSON uses `answers[]` as the primary contract. For single-question planning prompts, read `answers[0].answer`; treat top-level `answer` as legacy compatibility fallback only.
-- Batch `questions[]` may be used for non-interview grouped preference or approval prompts when one submitted form is clearer than multiple interruptions; interview mode still asks one question per round.
+- Use `AskUserQuestion` for preference questions (scope, priority, timeline, risk tolerance) -- provides clickable UI
+- Use plain text for questions needing specific values (port numbers, names, follow-up clarifications)
 - Use the `explore` agent (LOW tier, bounded quick pass) to gather codebase facts before asking the user
 - Use `ask_codex` with `agent_role: "planner"` for planning validation on large-scope plans
 - Use `ask_codex` with `agent_role: "analyst"` for requirements analysis
 - Use `ask_codex` with `agent_role: "critic"` for plan review in consensus and review modes
-- If ToolSearch finds no MCP tools or Codex is unavailable, fall back to equivalent OMX prompt agents -- never block on external tools
+- If optional MCP compatibility tools or Codex consultation are unavailable, fall back to equivalent OMX prompt/native agents -- never block on external tools
 - **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await the Architect result before issuing the Critic call.
 - In consensus mode, default to RALPLAN-DR short mode; enable deliberate mode on `--deliberate` or explicit high-risk signals (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage)
 - In consensus mode with `--interactive`: use `AskUserQuestion` / the structured question UI for the user feedback step (step 2) and the final approval step (step 7) -- never ask for approval in plain text when a structured surface is available. Without `--interactive`, auto-proceed through planning steps without pausing. Output the final plan without execution.
@@ -153,7 +151,6 @@ Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 - In consensus mode, execution follow-up handoff **MUST** include an explicit available-agent-types roster plus concrete staffing / role-allocation guidance grounded in that roster, suggested reasoning levels by lane, product-facing goal-mode follow-up suggestions (`$ultragoal` by default, `$autoresearch-goal` for research projects, `$performance-goal` for optimization/performance projects), explicit `omx team` / `$team` launch hints, and a team verification path
 </Tool_Usage>
 
-
 ## Scenario Examples
 
 **Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.

package/skills/ralph/SKILL.md

@@ -91,14 +91,13 @@ Complex tasks often fail silently: partial implementations get declared "done",
 </Steps>
 
 <Tool_Usage>
-- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
 - Use `ask_codex` with `agent_role: "architect"` for verification cross-checks when changes are security-sensitive, architectural, or involve complex multi-system integration
 - Skip Codex consultation for simple feature additions, well-tested changes, or time-critical verification
-- If ToolSearch finds no MCP tools or Codex is unavailable, proceed with architect agent verification alone -- never block on external tools
-- Use `state_write` / `state_read` for ralph mode state persistence between iterations
+- If MCP compatibility tools are unavailable, proceed with CLI/agent verification alone -- never block on external tools
+- Use `omx state write/read --input '<json>' --json` for ralph mode state persistence between iterations
 - Use Codex goal tools when present: `get_goal` to discover or re-check the active objective, `create_goal` only when the user/system explicitly requested a new goal and no active goal exists, and `update_goal` only after the audited objective is fully achieved.
 - Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context
-- If an `omx_state` MCP tool call reports that its stdio transport is unavailable/closed, do **not** retry the same MCP call. Retry once through the supported CLI parity surface with the same payload, preserving `workingDirectory` and `session_id`: `omx state write --input '<json>' --json`, `omx state read --input '<json>' --json`, or `omx state clear --input '<json>' --json`. If the CLI path also fails, continue with `.omx/context` / `.omx/plans` file-backed artifacts and report the state persistence blocker.
+- Prefer CLI state commands. If an explicit MCP compatibility `omx_state` call reports that its stdio transport is unavailable/closed, do **not** retry the same MCP call. Retry once through the supported CLI parity surface with the same payload, preserving `workingDirectory` and `session_id`: `omx state write --input '<json>' --json`, `omx state read --input '<json>' --json`, or `omx state clear --input '<json>' --json`. If the CLI path also fails, continue with `.omx/context` / `.omx/plans` file-backed artifacts and report the state persistence blocker.
 </Tool_Usage>
 
 ## Goal Mode Integration
@@ -118,18 +117,18 @@ Codex goal mode is the thread-level completion contract for long-running Ralph w
 
 ## State Management
 
-Use the `omx_state` MCP server tools (`state_write`, `state_read`, `state_clear`) for Ralph lifecycle state.
+Use the CLI-first state surface for Ralph lifecycle state (`omx state write/read/clear --input '<json>' --json`). Explicit MCP compatibility tools (`state_write`, `state_read`, `state_clear`) remain acceptable only when already enabled.
 
 - **On start**:
-  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
+  `omx state write --input '{"mode":"ralph","active":true,"iteration":1,"max_iterations":10,"current_phase":"executing","started_at":"<now>","state":{"context_snapshot_path":"<snapshot-path>"}}' --json`
 - **On each iteration**:
-  `state_write({mode: "ralph", iteration: <current>, current_phase: "executing"})`
+  `omx state write --input '{"mode":"ralph","iteration":<current>,"current_phase":"executing"}' --json`
 - **On verification/fix transition**:
-  `state_write({mode: "ralph", current_phase: "verifying"})` or `state_write({mode: "ralph", current_phase: "fixing"})`
+  `omx state write --input '{"mode":"ralph","current_phase":"verifying"}' --json` or `omx state write --input '{"mode":"ralph","current_phase":"fixing"}' --json`
 - **On completion**:
-  `state_write({mode: "ralph", active: false, current_phase: "complete", completed_at: "<now>"})`
+  `omx state write --input '{"mode":"ralph","active":false,"current_phase":"complete","completed_at":"<now>"}' --json`
 - **On cancellation/cleanup**:
-  run `$cancel` (which should call `state_clear(mode="ralph")`)
+  run `$cancel` (which should call `omx state clear --input '{"mode":"ralph"}' --json`)
 
 
 ## Scenario Examples

package/skills/swarm/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: swarm
-description: Swarm deprecated shim
+description: Deprecated compatibility shim for team execution
 ---
 
-# Swarm deprecated
+# Swarm compatibility shim
 
-Hard-deprecated. Do not invoke or route this skill. Use `$team` directly for coordinated multi-agent execution.
+Hard-deprecated. Do not invoke or route this skill for new work.
+
+Use `$team` or `omx team` directly for coordinated multi-agent execution. This file exists only to preserve the public/catalog-visible `swarm` skill contract while Team mode owns coordinated execution.
 
 Task: {{ARGUMENTS}}

package/skills/tdd/SKILL.md

@@ -7,4 +7,98 @@ description: TDD deprecated shim
 
 Hard-deprecated. Do not invoke or route this skill. Keep test-first discipline inside the active implementation workflow and verify with the project test suite.
 
-Task: {{ARGUMENTS}}
+## The Iron Law
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+Write code before test? DELETE IT. Start over. No exceptions.
+
+## Red-Green-Refactor Cycle
+
+### 1. RED: Write Failing Test
+- Write test for the NEXT piece of functionality
+- Run test - MUST FAIL
+- If it passes, your test is wrong
+
+### 2. GREEN: Minimal Implementation
+- Write ONLY enough code to pass the test
+- No extras. No "while I'm here."
+- Run test - MUST PASS
+
+### 3. REFACTOR: Clean Up
+- Improve code quality
+- Run tests after EVERY change
+- Must stay green
+
+### 4. REPEAT
+- Next failing test
+- Continue cycle
+
+## Enforcement Rules
+
+| If You See | Action |
+|------------|--------|
+| Code written before test | STOP. Delete code. Write test first. |
+| Test passes on first run | Test is wrong. Fix it to fail first. |
+| Multiple features in one cycle | STOP. One test, one feature. |
+| Skipping refactor | Go back. Clean up before next feature. |
+
+## Commands
+
+Before each implementation:
+```bash
+# Run the project's test command - should have ONE new failure
+```
+
+After implementation:
+```bash
+# Run the project's test command - new test should pass, all others still pass
+```
+
+## Output Format
+
+When guiding TDD:
+
+```
+## TDD Cycle: [Feature Name]
+
+### RED Phase
+Test: [test code]
+Expected failure: [what error you expect]
+Actual: [run result showing failure]
+
+### GREEN Phase
+Implementation: [minimal code]
+Result: [run result showing pass]
+
+### REFACTOR Phase
+Changes: [what was cleaned up]
+Result: [tests still pass]
+```
+
+## External Model Consultation (Preferred)
+
+The tdd-guide agent SHOULD consult Codex for test strategy validation.
+
+### Protocol
+1. **Form your OWN test strategy FIRST** - Design tests independently
+2. **Consult for validation** - Cross-check test coverage strategy
+3. **Critically evaluate** - Never blindly adopt external suggestions
+4. **Graceful fallback** - Never block if tools unavailable
+
+### When to Consult
+- Complex domain logic requiring comprehensive test coverage
+- Edge case identification for critical paths
+- Test architecture for large features
+- Unfamiliar testing patterns
+
+### When to Skip
+- Simple unit tests
+- Well-understood testing patterns
+- Time-critical TDD cycles
+- Small, isolated functionality
+
+### Tool Usage
+Prefer native `test-engineer` consultation or CLI-backed ask surfaces when available. Optional MCP compatibility ask tools may be used only when already enabled. If consultation tools are unavailable, fall back to the `test-engineer` agent.
+
+**Remember:** The discipline IS the value. Shortcuts destroy the benefit.

package/skills/ultragoal/SKILL.md

@@ -34,15 +34,48 @@ Loop until `omx ultragoal status` reports all goals complete:
 4. If no active Codex goal exists, call `create_goal` with the printed payload. In aggregate mode, if the same aggregate Codex objective is already active, continue the current OMX story without creating a new Codex goal.
 5. Complete the current OMX story only.
 6. Run a completion audit against the story objective and real artifacts/tests.
-7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, call `update_goal({status: "complete"})`, then call `get_goal` again for a fresh `complete` snapshot.
-8. Checkpoint the durable ledger with that snapshot:
-   `omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path>`
+7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, first run the mandatory final cleanup/review gate below; call `update_goal({status: "complete"})` only after that gate is clean, then call `get_goal` again for a fresh `complete` snapshot.
+8. Checkpoint the durable ledger with that snapshot. Intermediate aggregate checkpoints use only `--codex-goal-json`; final clean checkpoints also require `--quality-gate-json`:
+   `omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path> [--quality-gate-json <quality-gate-json-or-path>]`
 9. If blocked or failed, checkpoint failure:
    `omx ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
 10. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
    `omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json <get_goal-json-or-path>`
 11. Resume failed goals with `omx ultragoal complete-goals --retry-failed`.
 
+
+## Mandatory final cleanup and review gate
+
+The final ultragoal story is not complete until the active agent has run the final quality gate:
+
+1. Run targeted verification for the story.
+2. Run `ai-slop-cleaner` on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
+3. Rerun verification after the cleaner pass.
+4. Run `$code-review`. Clean means `codeReview.recommendation: "APPROVE"` and `codeReview.architectStatus: "CLEAR"`; `COMMENT`, `WATCH`, `REQUEST CHANGES`, and `BLOCK` are non-clean.
+5. If review is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+
+   ```sh
+   omx ultragoal record-review-blockers --goal-id <id> --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json <active-get-goal-json-or-path>
+   ```
+
+   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the Codex goal active, and lets `omx ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need a fresh/available Codex goal context because the old per-story Codex goal remains active/incomplete.
+
+6. If review is clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with a structured final gate:
+
+   ```sh
+   omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<tests/files/review evidence>" --codex-goal-json <fresh-complete-get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
+   ```
+
+`--quality-gate-json` must include:
+
+```json
+{
+  "aiSlopCleaner": { "status": "passed", "evidence": "cleaner report" },
+  "verification": { "status": "passed", "commands": ["npm test"], "evidence": "post-cleaner verification" },
+  "codeReview": { "recommendation": "APPROVE", "architectStatus": "CLEAR", "evidence": "final review synthesis" }
+}
+```
+
 ## Constraints
 
 - The shell command cannot directly invoke Codex interactive `/goal`; it emits a model-facing handoff for the active Codex agent.

package/skills/ultraqa/SKILL.md

@@ -5,17 +5,15 @@ description: QA cycling workflow - test, verify, fix, repeat until goal met
 
 # UltraQA Skill
 
-[ULTRAQA ACTIVATED - AUTONOMOUS QA CYCLING]
-
-## Overview
-
-## GPT-5.5 Guidance Alignment
+## Operating Contract
 
-Use the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step QA, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
+- Use outcome-first framing with concise, evidence-dense progress and completion reporting.
+- Treat newer user updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
+- If the user says `continue`, advance the current verified next step instead of restarting discovery.
 
-You are now in **ULTRAQA** mode - an autonomous QA cycling workflow that runs until your quality goal is met.
+[ULTRAQA ACTIVATED - AUTONOMOUS QA CYCLING]
 
-**Cycle**: qa-tester → architect verification → fix → repeat
+## Overview
 
 ## Goal Parsing
 
@@ -43,10 +41,10 @@ If no structured goal provided, interpret the argument as a custom goal.
    - `--custom`: Run appropriate command and check for pattern
    - `--interactive`: Use qa-tester for interactive CLI/service testing:
      ```
-     delegate(role="qa-tester", tier="STANDARD", task="TEST:
+     Use `/prompts:qa-tester` with:
      Goal: [describe what to verify]
      Service: [how to start]
-     Test cases: [specific scenarios to verify]")
+     Test cases: [specific scenarios to verify]
      ```
 
 2. **CHECK RESULT**: Did the goal pass?
@@ -55,18 +53,18 @@ If no structured goal provided, interpret the argument as a custom goal.
 
 3. **ARCHITECT DIAGNOSIS**: Spawn architect to analyze failure
    ```
-   delegate(role="architect", tier="THOROUGH", task="DIAGNOSE FAILURE:
+   Use `/prompts:architect` with:
    Goal: [goal type]
    Output: [test/build output]
-   Provide root cause and specific fix recommendations.")
+   Provide root cause and specific fix recommendations.
    ```
 
 4. **FIX ISSUES**: Apply architect's recommendations
    ```
-   delegate(role="executor", tier="STANDARD", task="FIX:
+   Use `/prompts:executor` with:
    Issue: [architect diagnosis]
    Files: [affected files]
-   Apply the fix precisely as recommended.")
+   Apply the fix precisely as recommended.
    ```
 
 5. **REPEAT**: Go back to step 1
@@ -95,20 +93,19 @@ Output progress each cycle:
 
 ## State Tracking
 
-Use `omx_state` MCP tools for UltraQA lifecycle state.
+Use the CLI-first state surface (`omx state ... --json`) for UltraQA lifecycle state. If explicit MCP compatibility tools are already available, equivalent `omx_state` calls are optional compatibility, not the default.
 
 - **On start**:
-  `state_write({mode: "ultraqa", active: true, current_phase: "qa", iteration: 1, started_at: "<now>"})`
+  `omx state write --input '{"mode":"ultraqa","active":true,"current_phase":"qa","iteration":1,"started_at":"<now>"}' --json`
 - **On each cycle**:
-  `state_write({mode: "ultraqa", current_phase: "qa", iteration: <cycle>})`
+  `omx state write --input '{"mode":"ultraqa","current_phase":"qa","iteration":<cycle>}' --json`
 - **On diagnose/fix transitions**:
-  `state_write({mode: "ultraqa", current_phase: "diagnose"})`
-  `state_write({mode: "ultraqa", current_phase: "fix"})`
+  `omx state write --input '{"mode":"ultraqa","current_phase":"diagnose"}' --json`
+  `omx state write --input '{"mode":"ultraqa","current_phase":"fix"}' --json`
 - **On completion**:
-  `state_write({mode: "ultraqa", active: false, current_phase: "complete", completed_at: "<now>"})`
+  `omx state write --input '{"mode":"ultraqa","active":false,"current_phase":"complete","completed_at":"<now>"}' --json`
 - **For resume detection**:
-  `state_read({mode: "ultraqa"})`
-
+  `omx state read --input '{"mode":"ultraqa"}' --json`
 
 ## Scenario Examples
 
@@ -134,9 +131,9 @@ User can cancel with `/cancel` which clears the state file.
 
 When goal is met OR max cycles reached OR exiting early, run `$cancel` or call:
 
-`state_clear({mode: "ultraqa"})`
+`omx state clear --input '{"mode":"ultraqa"}' --json`
 
-Use MCP state cleanup rather than deleting files directly.
+Use CLI state cleanup rather than deleting files directly.
 
 ---
 

package/skills/ultrawork/SKILL.md

@@ -81,16 +81,16 @@ Sequential task execution wastes time when tasks are independent. Ultrawork keep
 
 ## State Management
 
-Use `omx_state` MCP tools for ultrawork lifecycle state.
+Use the CLI-first state surface (`omx state ... --json`) for ultrawork lifecycle state. If explicit MCP compatibility tools are already available, equivalent `omx_state` calls are optional compatibility, not the default.
 
 - **On start**:
-  `state_write({mode: "ultrawork", active: true, reinforcement_count: 1, started_at: "<now>"})`
+  `omx state write --input '{"mode":"ultrawork","active":true,"reinforcement_count":1,"started_at":"<now>"}' --json`
 - **On each reinforcement/loop step**:
-  `state_write({mode: "ultrawork", reinforcement_count: <current>})`
+  `omx state write --input '{"mode":"ultrawork","reinforcement_count":<current>}' --json`
 - **On completion**:
-  `state_write({mode: "ultrawork", active: false})`
+  `omx state write --input '{"mode":"ultrawork","active":false}' --json`
 - **On cancellation/cleanup**:
-  run `$cancel` (which should call `state_clear(mode="ultrawork")`)
+  run `$cancel` (which should call `omx state clear --input '{"mode":"ultrawork"}' --json`)
 
 <Examples>
 <Good>
@@ -105,7 +105,7 @@ Direct-tool lane:
 - update `skills/ultrawork/SKILL.md`
 
 Background evidence lane:
-- delegate(role="test-engineer", tier="STANDARD", task="Map which hook tests cover ultrawork activation messaging", model="...")
+- use /prompts:test-engineer for this scoped task
 ```
 Why good: Context is grounded first, acceptance criteria are explicit, and the direct-tool lane runs alongside a bounded evidence lane.
 </Good>
@@ -122,8 +122,8 @@ Why good: Shared-file work stays local; independent evidence work fans out.
 <Bad>
 Parallelizing before the task is grounded:
 ```
-delegate(role="executor", tier="STANDARD", task="Implement whatever seems necessary", model="...")
-delegate(role="test-engineer", tier="STANDARD", task="Figure out how to test it later", model="...")
+use /prompts:executor for this scoped task
+use /prompts:test-engineer for this scoped task
 ```
 Why bad: No context snapshot, no pass/fail target, and delegation starts before the work is shaped.
 </Bad>