oh-my-codex 0.16.3 → 0.17.0

package/skills/design/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: design
+description: Canonical repo-local DESIGN.md workflow for product, UI/UX, and frontend decision source of truth
+---
+
+# Design Skill
+
+Use `$design` when product, UI/UX, frontend, or design-system decisions need a durable source of truth in the repository. This skill discovers existing design context, interviews for missing product/design information, and creates or refreshes repo-local `DESIGN.md` so future UI/UX/frontend work is grounded instead of improvised.
+
+## Purpose
+
+Make repo-local `DESIGN.md` source of truth and canonical design contract for the current repository:
+
+`existing repo evidence -> missing-context interview -> create/refresh DESIGN.md -> use DESIGN.md for UI/UX/frontend decisions`.
+
+The output is not a pixel-matching loop and not a one-off visual critique. It is the maintained design brief/checklist that implementation, review, and future visual work should cite.
+
+## Use when
+
+- The user asks for design direction, UX guidance, frontend planning, or design-system alignment.
+- A repo needs a design brief before UI/frontend implementation begins.
+- Existing UI/components/assets/screenshots need to be summarized into a reusable design source of truth.
+- UI/UX/frontend decisions are ambiguous and should be resolved through product context, constraints, and documented principles.
+- A feature needs `DESIGN.md` created or refreshed before `$ralph`, a designer lane, or implementation work proceeds.
+
+## Do not use when
+
+- The user provides or requests a visual reference/image/live URL and wants measured implementation until screenshots match. Use `$visual-ralph` for that visual-reference implementation loop.
+- The task is pure backend/API/infrastructure work with no user-facing design consequence.
+- The user only asks to compare screenshots or score visual fidelity. Use `$visual-ralph` and its built-in visual verdict flow.
+
+## Relationship to `$visual-ralph`
+
+`$design` owns the durable repo design source of truth: product goals, users, IA, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`.
+
+`$visual-ralph` owns implementation against an approved generated/static/live-URL visual reference, with screenshot capture, Visual Ralph verdict scoring, and pixel-diff evidence. `$visual-ralph` may read `DESIGN.md`, and it may leave design-system artifacts behind, but it does not replace the `DESIGN.md` discovery/interview/refresh workflow.
+
+If both are needed, run `$design` first to establish the design contract, then run `$visual-ralph` only after the visual reference/baseline is approved.
+
+## Workflow
+
+### 1. Discover local design evidence
+
+Inspect the repository before writing guidance. Look for:
+
+- `DESIGN.md`, `docs/design*`, `docs/ux*`, `docs/frontend*`, `README.md`, product specs, PRDs, and issue notes.
+- Existing UI source: routes, pages, layouts, components, stories, examples, demos, theme files, CSS variables, Tailwind/theme config, tokens, icons, and assets.
+- Screenshots, mockups, brand files, logos, Figma/export notes, Storybook snapshots, Playwright screenshots, visual-regression baselines, or `.omx/artifacts/visual-ralph/*` references.
+- Accessibility, responsive, i18n, content, and platform constraints already encoded in code or docs.
+
+Record evidence with file paths. Distinguish observed facts from design inferences.
+
+### 2. Interview only for missing context
+
+Ask concise questions only when repo evidence cannot answer design-critical context. Prefer one focused round that closes the biggest gaps, such as:
+
+- target users/personas and jobs to be done,
+- product/business goals and non-goals,
+- brand personality or forbidden aesthetics,
+- primary flows and information architecture,
+- accessibility level, device/browser support, and implementation constraints,
+- existing design assets or references the repo does not contain.
+
+If the user wants autonomous progress or cannot answer, create `DESIGN.md` with explicit assumptions and open questions instead of blocking.
+
+### 3. Create or refresh `DESIGN.md`
+
+Use the structure below. Preserve useful existing content, remove contradictions, and mark unknowns as open questions. Keep it actionable for implementers and reviewers.
+
+#### Required `DESIGN.md` structure/checklist
+
+```markdown
+# Design
+
+## Source of truth
+- Status: Draft | Active | Needs refresh
+- Last refreshed: YYYY-MM-DD
+- Primary product surfaces:
+- Evidence reviewed:
+
+## Brand
+- Personality:
+- Trust signals:
+- Avoid:
+
+## Product goals
+- Goals:
+- Non-goals:
+- Success signals:
+
+## Personas and jobs
+- Primary personas:
+- User jobs:
+- Key contexts of use:
+
+## Information architecture
+- Primary navigation:
+- Core routes/screens:
+- Content hierarchy:
+
+## Design principles
+- Principle 1:
+- Principle 2:
+- Tradeoffs:
+
+## Visual language
+- Color:
+- Typography:
+- Spacing/layout rhythm:
+- Shape/radius/elevation:
+- Motion:
+- Imagery/iconography:
+
+## Components
+- Existing components to reuse:
+- New/changed components:
+- Variants and states:
+- Token/component ownership:
+
+## Accessibility
+- Target standard:
+- Keyboard/focus behavior:
+- Contrast/readability:
+- Screen-reader semantics:
+- Reduced motion and sensory considerations:
+
+## Responsive behavior
+- Supported breakpoints/devices:
+- Layout adaptations:
+- Touch/hover differences:
+
+## Interaction states
+- Loading:
+- Empty:
+- Error:
+- Success:
+- Disabled:
+- Offline/slow network, if applicable:
+
+## Content voice
+- Tone:
+- Terminology:
+- Microcopy rules:
+
+## Implementation constraints
+- Framework/styling system:
+- Design-token constraints:
+- Performance constraints:
+- Compatibility constraints:
+- Test/screenshot expectations:
+
+## Open questions
+- [ ] Question / owner / impact
+```
+
+### 4. Use `DESIGN.md` as the decision contract
+
+For UI/UX/frontend work after the refresh:
+
+- Cite the relevant `DESIGN.md` sections before making design choices.
+- Prefer existing components, tokens, and documented constraints.
+- If implementation reveals a design contradiction, update `DESIGN.md` or add an open question before proceeding.
+- Do not introduce a new design-system layer when existing repo-native patterns can be extended.
+
+### 5. Handoff to implementation or Visual Ralph when appropriate
+
+- For normal frontend implementation, hand off with the relevant `DESIGN.md` sections, repo evidence, and acceptance criteria.
+- For visual-reference/image/live-URL matching, hand off to `$visual-ralph` with the approved reference/baseline and note that `DESIGN.md` is supporting context, not the visual verdict target.
+
+## Completion checklist
+
+Do not declare the design workflow complete until:
+
+- Existing design docs/assets/components/screenshots have been inspected or explicitly noted as absent.
+- Missing product/design context has been answered, assumed, or listed in `DESIGN.md` open questions.
+- `DESIGN.md` exists at the repo root and contains all required checklist sections.
+- UI/UX/frontend recommendations cite `DESIGN.md` rather than relying on unstated preferences.
+- Any `$visual-ralph` handoff is clearly separated as visual implementation matching, not DESIGN.md governance.
+
+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,16 @@
 ---
 name: frontend-ui-ux
-description: Designer-developer for UI/UX work
+description: Deprecated compatibility shim for frontend UI/UX work; use $design or $visual-ralph
 ---
 
-# 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
+Use `$design` when the task needs product/design context, UX guidance, frontend planning, design-system alignment, or a repo-local `DESIGN.md` source of truth.
 
-```
-/frontend-ui-ux <design task>
-```
+Use `$visual-ralph` when the task needs implementation against an approved generated/static/live-URL visual reference with screenshot capture, Visual Ralph verdict scoring, and pixel-diff evidence.
 
-## 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
+This file exists only to preserve the public/catalog-visible `frontend-ui-ux` compatibility contract while canonical design guidance is handled by `$design` and measured visual implementation is handled by `$visual-ralph`.
 
 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/skill/SKILL.md

@@ -313,7 +313,8 @@ Project-only skills (2):
   - backend-scaffold
 
 Common skills (3):
-  - frontend-ui-ux
+  - design
+  - frontend-ui-ux (deprecated; use design or visual-ralph)
   - git-master
   - planner
 

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.