oh-my-codex 0.16.2 → 0.16.4

package/skills/ask-gemini/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: ask-gemini
-description: Ask Gemini deprecated skill
+description: Deprecated compatibility shim for Gemini advisor requests
 ---
 
-# Ask Gemini deprecated
+# Ask Gemini compatibility shim
 
-Hard-deprecated. Do not invoke or route this skill. Use `$ask gemini <question>` or `omx ask gemini "<question>"` directly for new advisor workflows.
+Hard-deprecated. Do not invoke or route this skill for new work.
+
+Use `$ask gemini <question>` or `omx ask gemini "<question>"` directly for Gemini advisor workflows. This file exists only to preserve the public/catalog-visible `ask-gemini` skill contract while the canonical `$ask` workflow owns provider selection.
 
 Task: {{ARGUMENTS}}

package/skills/autopilot/SKILL.md

@@ -75,7 +75,7 @@ Before Phase `ralplan` starts or resumes:
 </Execution_Policy>
 
 <State_Management>
-Use `omx_state` MCP tools (or `omx state ... --json` fallback if MCP transport is unavailable) for Autopilot lifecycle state. State must be session-aware when a session id exists.
+Use the CLI-first state surface (`omx state ... --json`) for Autopilot lifecycle state. State must be session-aware when a session id exists. If the explicit MCP compatibility surface is already available, equivalent `omx_state` tool calls remain acceptable but are not required.
 
 Required fields:
 
@@ -99,7 +99,7 @@ Required fields:
 }
 ```
 
-- **On start**: `state_write({mode:"autopilot", active:true, current_phase:"ralplan", iteration:1, review_cycle:0, state:{phase_cycle:["ralplan","ralph","code-review"], handoff_artifacts:{context_snapshot_path, ralplan:null, ralph:null, code_review:null}, review_verdict:null, return_to_ralplan_reason:null}})`
+- **On start**: `omx state write --input '{"mode":"autopilot","active":true,"current_phase":"ralplan","iteration":1,"review_cycle":0,"state":{"phase_cycle":["ralplan","ralph","code-review"],"handoff_artifacts":{"context_snapshot_path":"<snapshot-path>","ralplan":null,"ralph":null,"code_review":null},"review_verdict":null,"return_to_ralplan_reason":null}}' --json`
 - **On ralplan -> ralph**: set `current_phase:"ralph"`, persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
 - **On ralph -> code-review**: set `current_phase:"code-review"`, persist implementation/test evidence under `handoff_artifacts.ralph`.
 - **On clean review**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}` and `completed_at`.

package/skills/code-review/SKILL.md

@@ -141,9 +141,7 @@ The code-reviewer agent SHOULD consult Codex for cross-validation.
 - Small, isolated changes
 
 ### Tool Usage
-Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools.
-Use `mcp__x__ask_codex` with `agent_role: "code-reviewer"`.
-If ToolSearch finds no MCP tools, fall back to the `code-reviewer` agent.
+Prefer native `code-reviewer` agent consultation or CLI-backed `ask_codex` surfaces when available. Optional MCP compatibility ask tools may be used only when already enabled. If consultation tools are unavailable, fall back to the `code-reviewer` agent.
 
 **Note:** Codex calls can take up to 1 hour. Consider the review timeline before consulting.
 

package/skills/deep-interview/SKILL.md

@@ -72,7 +72,7 @@ If no flag is provided, use **Standard**.
 - Do not hand off to execution while ambiguity remains above threshold unless user explicitly opts to proceed with warning
 - Do not crystallize or hand off while `Non-goals` or `Decision Boundaries` remain unresolved, even if the weighted ambiguity threshold is met
 - Treat early exit as a safety valve, not the default success path
-- Persist mode state for resume safety (`state_write` / `state_read`)
+- Persist mode state for resume safety with CLI-first state commands (`omx state write/read --input '<json>' --json`); use `state_write` / `state_read` only when explicit MCP compatibility is enabled
 </Execution_Policy>
 
 <Steps>
@@ -101,7 +101,7 @@ If no flag is provided, use **Standard**.
 2. Detect project context:
    - Run `explore` to classify **brownfield** (existing codebase target) vs **greenfield**.
    - For brownfield, collect relevant codebase context before questioning.
-3. Initialize state via `state_write(mode="deep-interview")`:
+3. Initialize state via `omx state write --input '{"mode":"deep-interview","active":true}' --json`:
 
 ```json
 {
@@ -286,7 +286,7 @@ Readiness gate:
 Show weighted breakdown table, readiness-gate status (`Non-goals`, `Decision Boundaries`), and the next focus dimension.
 
 ### 2e) Persist state
-Append round result and updated scores via `state_write`.
+Append round result and updated scores via `omx state write --input '<json>' --json`; use `state_write` only when explicit MCP compatibility is enabled.
 
 ### 2f) Round controls
 - Do not offer early exit before the first explicit assumption probe and one persistent follow-up have happened
@@ -428,7 +428,7 @@ Preserve `$ralph` for persistent single-owner execution/verification and `$team`
 - From attached-tmux Bash/tool paths, call it as `OMX_QUESTION_RETURN_PANE=$TMUX_PANE omx question ...` unless an explicit `%pane` return target is already known
 - If the current runtime is outside tmux and cannot render `omx question`, use native structured input when available; otherwise ask exactly one concise plain-text question and wait for the answer
 - After `omx question` returns JSON, prefer `answers[0].answer` / `answers[]`; use legacy `answer` only as a fallback for older records
-- Use `state_write` / `state_read` for resumable mode state
+- Use `omx state write/read --input '<json>' --json` for resumable mode state; `state_write` / `state_read` are explicit MCP compatibility fallbacks only
 - If the interview cannot ask a required `omx question` round, persist the blocker as terminal state with `active: false` and `current_phase: "blocked"`; do not write a terminal blocked phase with `active: true`
 - Read/write context snapshots under `.omx/context/`
 - Record whether the oversized-context summary gate is not needed, pending, or satisfied before any scoring or handoff step
@@ -475,7 +475,7 @@ enableChallengeModes = true
 
 ## Resume
 
-If interrupted, rerun `$deep-interview`. Resume from persisted mode state via `state_read(mode="deep-interview")`.
+If interrupted, rerun `$deep-interview`. Resume from persisted mode state via `omx state read --input '{"mode":"deep-interview"}' --json`.
 
 ## Recommended 3-Stage Pipeline
 
@@ -487,5 +487,3 @@ deep-interview -> ralplan -> autopilot
 - Stage 2 (ralplan): feasibility + architecture gate
 - Stage 3 (autopilot): execution + QA + validation gate
 </Advanced>
-
-Task: {{ARGUMENTS}}

package/skills/doctor/SKILL.md

@@ -51,7 +51,7 @@ echo "Latest npm: $LATEST"
 - 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 now carries plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks and the rest of OMX runtime wiring stay setup-owned
+- 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)
 
@@ -123,7 +123,7 @@ ls -la ~/.agents/skills/ 2>/dev/null
 ```
 
 **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 MCP/apps; legacy setup installs native agents, while plugin setup archives stale legacy native-agent files and keeps config/hooks current.
+- 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

package/skills/ecomode/SKILL.md

@@ -7,4 +7,108 @@ description: Ecomode deprecated shim
 
 Hard-deprecated. Do not invoke or route this skill. Use `$ultrawork` directly for maintained high-throughput execution workflows.
 
-Task: {{ARGUMENTS}}
+## What Ecomode Does
+
+Overrides default model selection to prefer cheaper tiers:
+
+| Default Tier | Ecomode Override |
+|--------------|------------------|
+| THOROUGH | STANDARD, THOROUGH only if essential |
+| STANDARD | LOW first, STANDARD if needed |
+| LOW | LOW - no change |
+
+## What Ecomode Does NOT Do
+
+- **Persistence**: Use `ralph` for "don't stop until done"
+- **Parallel Execution**: Use `ultrawork` for parallel agents
+- **Delegation Enforcement**: Always active via core orchestration
+
+## Combining Ecomode with Other Modes
+
+Ecomode is a modifier that combines with execution modes:
+
+| Combination | Effect |
+|-------------|--------|
+| `eco ralph` | Ralph loop with cheaper agents |
+| `eco ultrawork` | Parallel execution with cheaper agents |
+| `eco autopilot` | Full autonomous with cost optimization |
+
+## Ecomode Routing Rules
+
+**ALWAYS prefer lower tiers. Only escalate when task genuinely requires it.**
+
+| Decision | Rule |
+|----------|------|
+| DEFAULT | Start with LOW tier for most tasks |
+| UPGRADE | Escalate to STANDARD when LOW tier fails or task requires multi-file reasoning |
+| AVOID | THOROUGH tier - only for planning/critique if essential |
+
+## Agent Selection in Ecomode
+
+**FIRST ACTION:** Before delegating any work, read the agent reference file:
+```
+Read file: docs/shared/agent-tiers.md
+```
+This provides the complete agent tier matrix, MCP tool assignments, and selection guidance.
+
+**Ecomode preference order:**
+
+```
+// PREFERRED - Use for most tasks
+use /prompts:executor for this scoped task
+use /prompts:explore for this scoped task
+use /prompts:architect for this scoped task
+
+// FALLBACK - Only if LOW fails
+use /prompts:executor for this scoped task
+use /prompts:architect for this scoped task
+
+// AVOID - Only for planning/critique if essential
+use /prompts:planner for this scoped task
+```
+
+## Delegation Enforcement
+
+Ecomode maintains all delegation rules from core protocol with cost-optimized routing:
+
+| Action | Delegate To | Model |
+|--------|-------------|-------|
+| Code changes | executor | LOW / STANDARD |
+| Analysis | architect | LOW |
+| Search | explore | LOW |
+| Documentation | writer | LOW |
+
+### Background Execution
+Long-running commands (install, build, test) run in background. Maximum 20 concurrent.
+
+## Token Savings Tips
+
+1. **Batch similar tasks** to one agent instead of spawning many
+2. **Use explore (LOW tier)** for file discovery, not architect
+3. **Prefer LOW-tier executor routing** for simple changes - only upgrade if it fails
+4. **Use writer (LOW tier)** for all documentation tasks
+5. **Avoid THOROUGH-tier agents** unless the task genuinely requires deep reasoning
+
+## Disabling Ecomode
+
+Ecomode can be completely disabled via config. When disabled, all ecomode keywords are ignored.
+
+Set in `~/.codex/.omx-config.json`:
+```json
+{
+  "ecomode": {
+    "enabled": false
+  }
+}
+```
+
+## State Management
+
+Use the CLI-first state surface (`omx state ... --json`) for ecomode lifecycle state. If explicit MCP compatibility tools are already available, equivalent `omx_state` calls are optional compatibility, not the default.
+
+- **On activation**:
+  `omx state write --input '{"mode":"ecomode","active":true}' --json`
+- **On deactivation/completion**:
+  `omx state write --input '{"mode":"ecomode","active":false}' --json`
+- **On cancellation/cleanup**:
+  run `$cancel` (which should call `omx state clear --input '{"mode":"ecomode"}' --json`)

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`, `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.