oh-my-codex 0.16.3 → 0.17.0

package/plugins/oh-my-codex/skills/ultraqa/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: ultraqa
-description: QA cycling workflow - test, verify, fix, repeat until goal met
+description: Adversarial dynamic e2e QA workflow - generate hostile scenarios, test, verify, fix, report, and clean up
 ---
 
 # UltraQA Skill
 
-[ULTRAQA ACTIVATED - AUTONOMOUS QA CYCLING]
+## Operating Contract
 
-## Overview
-
-## GPT-5.5 Guidance Alignment
+- 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.
+- UltraQA is not satisfied by a shallow build/lint/typecheck/test checklist. It must exercise the requested behavior through adversarial dynamic e2e scenarios whenever the target can be run, simulated, or harnessed safely.
 
-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.
+[ULTRAQA ACTIVATED - ADVERSARIAL DYNAMIC E2E QA CYCLING]
 
-You are now in **ULTRAQA** mode - an autonomous QA cycling workflow that runs until your quality goal is met.
+## Overview
 
-**Cycle**: qa-tester → architect verification → fix → repeat
+UltraQA finds real behavior failures by combining normal verification commands with generated end-to-end scenarios, hostile user modeling, temporary harnesses when useful, and a structured evidence report. The workflow repeats test → diagnose → fix → retest until the goal is met, a bounded stop condition is reached, or a safety boundary blocks further execution.
 
 ## Goal Parsing
 
@@ -23,121 +24,231 @@ Parse the goal from arguments. Supported formats:
 
 | Invocation | Goal Type | What to Check |
 |------------|-----------|---------------|
-| `/ultraqa --tests` | tests | All test suites pass |
-| `/ultraqa --build` | build | Build succeeds with exit 0 |
-| `/ultraqa --lint` | lint | No lint errors |
-| `/ultraqa --typecheck` | typecheck | No TypeScript errors |
-| `/ultraqa --custom "pattern"` | custom | Custom success pattern in output |
+| `/ultraqa --tests` | tests | Existing tests plus adversarial dynamic e2e scenarios for the changed behavior |
+| `/ultraqa --build` | build | Build succeeds and generated smoke/e2e probes still run against the built artifact when applicable |
+| `/ultraqa --lint` | lint | Lint passes and no generated harness/test artifact violates project hygiene |
+| `/ultraqa --typecheck` | typecheck | Typecheck passes and generated typed harnesses compile when applicable |
+| `/ultraqa --custom "pattern"` | custom | Custom success pattern is verified against behavior, not trusted as misleading success output |
+| `/ultraqa --interactive` | interactive | CLI/service behavior is tested with generated hostile and edge-case interactions |
+
+If no structured goal is provided, interpret the argument as a custom behavior goal and derive a runnable e2e strategy from repository context.
+
+## Required Scenario Matrix
+
+Before declaring success, create and maintain a scenario matrix. Each row must include: scenario id, intent, user/attacker model, setup, command or harness, expected signal, actual result, fixes applied, evidence, and cleanup status.
+
+The matrix must include normal-path coverage plus adversarial dynamic e2e scenarios selected from the current goal and codebase. Unless clearly irrelevant or impossible, include these hostile and edge-case classes:
+
+1. **Malformed input**: invalid JSON, missing fields, invalid flags, oversized strings, unusual Unicode, path traversal-like values, and corrupted state files.
+2. **Repeated interruptions**: repeated `continue`, stop/cancel/abort wording, interrupted command output, and retries after partial progress.
+3. **Prompt injection attempts**: user text that tries to override instructions, exfiltrate secrets, skip verification, delete state, or claim false success.
+4. **Cancel/resume behavior**: active state cleanup, resume detection, stale in-progress state, and cancellation followed by a fresh run.
+5. **Stale state**: old `.omx/state` files, mismatched sessions, missing timestamps, and contradictory phase metadata.
+6. **Dirty worktree**: pre-existing modifications, untracked generated files, and verification that UltraQA does not hide or overwrite unrelated work.
+7. **Hung or long-running commands**: bounded timeout handling, killed child processes, and recovery notes.
+8. **Flaky tests**: rerun strategy, failure clustering, quarantine evidence, and avoiding false green from a single lucky pass.
+9. **Misleading success output**: output containing success phrases with non-zero exits, hidden failures, skipped tests, or partial command logs.
 
-If no structured goal provided, interpret the argument as a custom goal.
+## Dynamic E2E and Temporary Harness Rules
+
+- Generate temporary tests, scripts, fixtures, or harnesses when they materially improve behavioral confidence and no existing e2e surface covers the scenario.
+- Prefer project-native test tools and small throwaway harnesses under a temporary directory or clearly named test fixture.
+- Record every generated artifact in the scenario matrix, including whether it was committed intentionally or removed during cleanup.
+- Use bounded runtimes and explicit timeouts for commands that can hang.
+- Validate exit codes and output semantics; do not trust success-looking text alone.
+- Do not delete, rewrite, or mask unrelated user work. Capture dirty-worktree evidence before and after generated harness work.
 
 ## Cycle Workflow
 
 ### Cycle N (Max 5)
 
-1. **RUN QA**: Execute verification based on goal type
-   - `--tests`: Run the project's test command
-   - `--build`: Run the project's build command
-   - `--lint`: Run the project's lint command
-   - `--typecheck`: Run the project's type check command
-   - `--custom`: Run appropriate command and check for pattern
-   - `--interactive`: Use qa-tester for interactive CLI/service testing:
+1. **PLAN ADVERSARIAL QA**
+   - Restate the goal, success criteria, safety bounds, and stop condition.
+   - Inspect repository context enough to identify runnable surfaces, test commands, state files, and cleanup paths.
+   - Build or update the required scenario matrix before running commands.
+
+2. **RUN BASELINE VERIFICATION**
+   - `--tests`: Run the project's test command.
+   - `--build`: Run the project's build command.
+   - `--lint`: Run the project's lint command.
+   - `--typecheck`: Run the project's type check command.
+   - `--custom`: Run the appropriate command and check the pattern plus exit status and failure markers.
+   - `--interactive`: Use qa-tester or an equivalent CLI/service harness:
      ```
-     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: [normal, hostile, malformed, interruption, resume, stale-state, dirty-worktree, hung-command, flaky, and misleading-output scenarios]
      ```
 
-2. **CHECK RESULT**: Did the goal pass?
-   - **YES** → Exit with success message
-   - **NO** → Continue to step 3
+3. **RUN ADVERSARIAL DYNAMIC E2E SCENARIOS**
+   - Execute the scenario matrix using existing e2e tests, generated temporary tests, or generated harnesses.
+   - Model malicious/hostile user behavior explicitly, including prompt injection and attempts to bypass safety or verification.
+   - Exercise malformed input, repeated interruptions, cancel/resume, stale state, dirty worktree handling, hung commands, flaky tests, and misleading success output when relevant.
+   - Capture commands, exit codes, important output excerpts, artifacts, and cleanup status.
+
+4. **CHECK RESULT**
+   - **YES** only if baseline verification and adversarial e2e scenarios passed, generated artifacts are cleaned up or intentionally tracked, and the report has complete evidence.
+   - **NO** if any scenario failed, was skipped without justification, left debris, relied on misleading output, or lacked evidence. Continue to step 5.
 
-3. **ARCHITECT DIAGNOSIS**: Spawn architect to analyze failure
+5. **ARCHITECT DIAGNOSIS**
    ```
-   delegate(role="architect", tier="THOROUGH", task="DIAGNOSE FAILURE:
-   Goal: [goal type]
-   Output: [test/build output]
-   Provide root cause and specific fix recommendations.")
+   Use `/prompts:architect` with:
+   Goal: [goal type and behavior]
+   Scenario matrix: [rows, commands, failures, evidence]
+   Output: [test/build/e2e/harness output]
+   Provide root cause, safety implications, and specific fix recommendations.
    ```
 
-4. **FIX ISSUES**: Apply architect's recommendations
+6. **FIX ISSUES**
    ```
-   delegate(role="executor", tier="STANDARD", task="FIX:
+   Use `/prompts:executor` with:
    Issue: [architect diagnosis]
    Files: [affected files]
-   Apply the fix precisely as recommended.")
+   Constraints: preserve unrelated dirty work, clean temporary harnesses, keep safety bounds
+   Apply the fix precisely as recommended.
    ```
 
-5. **REPEAT**: Go back to step 1
+7. **CLEAN UP AND ROLLBACK**
+   - Remove temporary harnesses, fixtures, logs, spawned processes, and state files unless they are intentional deliverables.
+   - Roll back failed experimental edits that are not part of the final fix.
+   - Re-check the worktree and record remaining intentional changes or residual debris.
+
+8. **REPEAT**
+   - Go back to step 1 with the updated scenario matrix and failure history.
+
+## Safety Bounds
+
+UltraQA must stay inside these safety bounds:
+
+- No destructive commands such as force resets, broad deletes, secret exfiltration, credential dumping, production writes, or unbounded process spawning.
+- No reading or printing secrets beyond the minimum metadata needed to verify absence of leakage.
+- No network or external-production side effects unless the user explicitly authorized them.
+- No unbounded waits: use timeouts, retries with caps, and clear hung-command diagnostics.
+- No hiding unrelated dirty work or generated debris.
+- If a required scenario would violate these bounds, mark it blocked in the report with the safe substitute used.
 
 ## Exit Conditions
 
 | Condition | Action |
 |-----------|--------|
-| **Goal Met** | Exit with success: "ULTRAQA COMPLETE: Goal met after N cycles" |
-| **Cycle 5 Reached** | Exit with diagnosis: "ULTRAQA STOPPED: Max cycles. Diagnosis: ..." |
-| **Same Failure 3x** | Exit early: "ULTRAQA STOPPED: Same failure detected 3 times. Root cause: ..." |
-| **Environment Error** | Exit: "ULTRAQA ERROR: [tmux/port/dependency issue]" |
+| **Goal Met** | Exit with success: `ULTRAQA COMPLETE: Goal met after N cycles` plus the structured report |
+| **Cycle 5 Reached** | Exit with diagnosis: `ULTRAQA STOPPED: Max cycles` plus failures, fixes attempted, residual risks, and evidence |
+| **Same Failure 3x** | Exit early: `ULTRAQA STOPPED: Same failure detected 3 times` plus root cause, safety notes, and next owner |
+| **Safety Boundary** | Exit: `ULTRAQA BLOCKED: [destructive/credentialed/external-production/unbounded action]` plus safe substitute evidence |
+| **Environment Error** | Exit: `ULTRAQA ERROR: [tmux/port/dependency/hung command issue]` plus cleanup status |
+
+## Structured Report
+
+Every terminal UltraQA result must include this report shape:
+
+```markdown
+# UltraQA Report
+
+## Goal and success criteria
+- Goal:
+- Stop condition:
+- Safety bounds applied:
+
+## Scenario matrix
+| ID | User/attacker model | Scenario | Command/harness | Expected signal | Actual result | Status | Evidence | Cleanup |
+|----|---------------------|----------|-----------------|-----------------|---------------|--------|----------|---------|
+
+## Commands run
+- `[exit code] command` — purpose, duration/timeout, key output evidence
+
+## Failures found
+- Scenario ID, failure signal, root cause, user impact, safety impact
+
+## Fixes applied
+- Files changed, rationale, linked failing scenario(s), regression evidence
+
+## Cleanup and rollback
+- Generated artifacts removed or intentionally kept
+- State/process cleanup performed
+- Worktree status before/after
+
+## Residual risks
+- Untested or blocked scenarios with reasons and safe substitutes
+
+## Evidence
+- Test output, e2e logs, harness output, screenshots/transcripts when relevant, and rerun/flake evidence
+```
 
 ## Observability
 
 Output progress each cycle:
-```
-[ULTRAQA Cycle 1/5] Running tests...
-[ULTRAQA Cycle 1/5] FAILED - 3 tests failing
-[ULTRAQA Cycle 1/5] Architect diagnosing...
-[ULTRAQA Cycle 1/5] Fixing: auth.test.ts - missing mock
-[ULTRAQA Cycle 2/5] Running tests...
-[ULTRAQA Cycle 2/5] PASSED - All 47 tests pass
+
+```text
+[ULTRAQA Cycle 1/5] Planning adversarial scenario matrix...
+[ULTRAQA Cycle 1/5] Running baseline tests...
+[ULTRAQA Cycle 1/5] Running ADV-E2E-003 prompt-injection harness...
+[ULTRAQA Cycle 1/5] FAILED - stale state resume accepted misleading success output
+[ULTRAQA Cycle 1/5] Architect diagnosing scenario ADV-E2E-003...
+[ULTRAQA Cycle 1/5] Fixing: src/hooks/... - validate exit code before success phrase
+[ULTRAQA Cycle 1/5] Cleaning temporary harnesses and state...
+[ULTRAQA Cycle 2/5] PASSED - baseline + 9 adversarial scenarios pass
 [ULTRAQA COMPLETE] Goal met after 2 cycles
 ```
 
 ## 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":"planning","iteration":1,"started_at":"<now>","scenario_matrix":[]}' --json`
 - **On each cycle**:
-  `state_write({mode: "ultraqa", current_phase: "qa", iteration: <cycle>})`
+  `omx state write --input '{"mode":"ultraqa","current_phase":"qa","iteration":<cycle>,"scenario_matrix":"<updated matrix path or summary>"}' --json`
+- **On adversarial e2e transition**:
+  `omx state write --input '{"mode":"ultraqa","current_phase":"adversarial-e2e"}' --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 cleanup transition**:
+  `omx state write --input '{"mode":"ultraqa","current_phase":"cleanup"}' --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
 
-**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.
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work, rerun the relevant adversarial scenario, and update the report instead of restarting discovery.
 
 **Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
 
+**Good:** A CLI prints `SUCCESS` while exiting 1. Mark the misleading success output scenario failed, fix the parser or reporting path, and rerun the generated harness.
+
+**Bad:** The workflow runs only `npm test`, `npm run build`, `npm run lint`, or `npm run typecheck`, sees green output, and declares UltraQA complete without adversarial dynamic e2e coverage.
+
+**Bad:** A generated harness leaves untracked files, state, or a child process behind and the final report omits cleanup status.
+
 **Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
 
 ## Cancellation
 
-User can cancel with `/cancel` which clears the state file.
+User can cancel with `/cancel`, which clears UltraQA state. Cancellation itself should be tested in cancel/resume scenarios when relevant, but UltraQA must not block an explicit user cancellation.
 
 ## Important Rules
 
-1. **PARALLEL when possible** - Run diagnosis while preparing potential fixes
-2. **TRACK failures** - Record each failure to detect patterns
-3. **EARLY EXIT on pattern** - 3x same failure = stop and surface
-4. **CLEAR OUTPUT** - User should always know current cycle and status
-5. **CLEAN UP** - Clear state file on completion or cancellation
+1. **ADVERSARIAL E2E REQUIRED** - Baseline build/lint/typecheck/test commands are necessary evidence, not sufficient completion proof.
+2. **SCENARIO MATRIX REQUIRED** - Track normal, hostile, malformed, interruption, injection, cancel/resume, stale-state, dirty-worktree, hung-command, flaky, and misleading-output coverage.
+3. **GENERATE HARNESSES WHEN USEFUL** - Create temporary tests or harnesses when they materially improve behavioral confidence, then clean them up or commit them intentionally.
+4. **PARALLEL WHEN SAFE** - Run independent diagnostics while preparing potential fixes; do not parallelize commands that mutate the same state or worktree.
+5. **TRACK FAILURES** - Record each failure to detect patterns and avoid false greens.
+6. **EARLY EXIT ON PATTERN** - 3x same failure = stop and surface with root cause and residual risk.
+7. **CLEAR OUTPUT** - User should always know current cycle, scenario, command, status, and evidence.
+8. **CLEAN UP** - Clear UltraQA state and temporary artifacts on completion, cancellation, or early stop.
+9. **SAFETY FIRST** - Never exfiltrate secrets, run destructive cleanup, write to production, or wait indefinitely to satisfy a scenario.
 
 ## STATE CLEANUP ON COMPLETION
 
 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. Also remove temporary e2e harnesses, fixtures, and logs unless they are intentional artifacts listed in the report.
 
 ---
 
-Begin ULTRAQA cycling now. Parse the goal and start cycle 1.
+Begin ULTRAQA cycling now. Parse the goal, build the adversarial dynamic e2e scenario matrix, and start cycle 1.

package/plugins/oh-my-codex/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>

package/plugins/oh-my-codex/skills/visual-ralph/SKILL.md

@@ -27,7 +27,7 @@ This is an orchestration skill. It composes existing skills and must not add run
 
 ## Do not use when
 
-- The user only wants design critique or general frontend advice; use `$frontend-ui-ux` or a designer lane.
+- The user only wants repo-wide design guidance, product/design context, or a DESIGN.md source of truth; use `$design` or a designer lane.
 - The task is a non-visual backend/API implementation with no UI reference target.
 - The user already supplied a final static reference image and only needs comparison/fixes; hand directly to `$ralph` with Visual Ralph verdict guidance.
 - The requested output is a deterministic SVG/vector/code-native asset rather than a raster reference.
@@ -117,7 +117,7 @@ Record final diff evidence with the reference/screenshot artifacts so the result
 
 ### 7. Build a reproducible design system
 
-The implementation is incomplete unless the visual match is encoded in repo-native reusable artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config, component variants, Storybook stories, design docs, or existing equivalents.
+The implementation is incomplete unless the visual match is encoded in repo-native reusable artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config, component variants, Storybook stories, updates that align with DESIGN.md, or existing equivalents.
 
 Capture at least the applicable:
 - colors,

package/plugins/oh-my-codex/skills/wiki/SKILL.md

@@ -11,31 +11,31 @@ Persistent, self-maintained markdown knowledge base for project and session know
 ## Operations
 
 ### Ingest
-```text
-wiki_ingest({ title: "Auth Architecture", content: "...", tags: ["auth", "architecture"], category: "architecture" })
+```bash
+omx wiki wiki_ingest --input '{"title":"Auth Architecture","content":"...","tags":["auth","architecture"],"category":"architecture"}' --json
 ```
 
 ### Query
-```text
-wiki_query({ query: "authentication", tags: ["auth"], category: "architecture" })
+```bash
+omx wiki wiki_query --input '{"query":"authentication","tags":["auth"],"category":"architecture"}' --json
 ```
 
 ### Lint
-```text
-wiki_lint()
+```bash
+omx wiki wiki_lint --json
 ```
 
 ### Quick Add
-```text
-wiki_add({ title: "Page Title", content: "...", tags: ["tag1"], category: "decision" })
+```bash
+omx wiki wiki_add --input '{"title":"Page Title","content":"...","tags":["tag1"],"category":"decision"}' --json
 ```
 
 ### List / Read / Delete
-```text
-wiki_list()
-wiki_read({ page: "auth-architecture" })
-wiki_delete({ page: "outdated-page" })
-wiki_refresh()
+```bash
+omx wiki wiki_list --json
+omx wiki wiki_read --input '{"page":"auth-architecture"}' --json
+omx wiki wiki_delete --input '{"page":"outdated-page"}' --json
+omx wiki wiki_refresh --json
 ```
 
 ## Categories

package/skills/analyze/SKILL.md

@@ -144,5 +144,3 @@ A good analyze response is:
 - free of normative drift or judgmental filler
 - explicit about the evidence-vs-inference distinction
 - concise for simple cases, broader only when the question truly needs it
-
-Task: {{ARGUMENTS}}

package/skills/ask-claude/SKILL.md

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

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}}