oh-my-codex 0.15.2 → 0.16.0

package/skills/build-fix/SKILL.md

@@ -1,145 +1,10 @@
 ---
 name: build-fix
-description: Fix build and TypeScript errors with minimal changes
+description: Build Fix deprecated shim
 ---
 
-# Build Fix Skill
+# Build Fix deprecated
 
-Fix build and compilation errors quickly with minimal code changes. Get the build green without refactoring.
+Hard-deprecated. Do not invoke or route this skill. Build failures should be handled by the active execution, debugging, or verification workflow.
 
-## When to Use
-
-This skill activates when:
-- User says "fix the build", "build is broken"
-- TypeScript compilation fails
-- the build command or type checker reports errors
-- User requests "minimal fixes" for errors
-
-## What It Does
-
-## GPT-5.5 Guidance Alignment
-
-- Default to outcome-first progress and completion reporting: state the target result, evidence, validation status, and stop condition before adding process detail.
-- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
-- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the build-fix workflow is grounded; stop once enough evidence exists.
-- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, credentialed, external-production, or preference-dependent.
-
-Delegates to the `build-fixer` agent (STANDARD tier) to:
-
-1. **Collect Errors**
-   - Run the project's type check command (e.g., `tsc --noEmit`, `mypy`, `cargo check`, `go vet`)
-   - Or run the project's build command to get build failures
-   - Categorize errors by type and severity
-
-2. **Fix Strategically**
-   - Add type annotations where missing
-   - Add null checks where needed
-   - Fix import/export statements
-   - Resolve module resolution issues
-   - Fix linter errors blocking build
-
-3. **Minimal Diff Strategy**
-   - NO refactoring of unrelated code
-   - NO architectural changes
-   - NO performance optimizations
-   - ONLY what's needed to make build pass
-
-4. **Verify**
-   - Run the project's type check command after each fix
-   - Ensure no new errors introduced
-   - Stop when build passes
-
-## Command Guidance
-
-- Prefer `omx sparkshell` for noisy build/typecheck runs, repository search/listing, and bounded read-only inspection when summary output is enough.
-- Use raw shell when exact stdout/stderr, shell composition, dependency installation, or low-level debugging fidelity is required.
-- If `omx sparkshell` returns incomplete, ambiguous, or `summary unavailable` output, retry with a more precise command or the raw shell immediately.
-
-## Agent Delegation
-
-```
-delegate(
-  role="build-fixer",
-  tier="STANDARD",
-  prompt="BUILD FIX TASK
-
-Fix all build and TypeScript errors with minimal changes.
-
-Requirements:
-- Run tsc/build to collect errors
-- Fix errors one at a time
-- Verify each fix doesn't introduce new errors
-- NO refactoring, NO architectural changes
-- Stop when build passes
-
-Output: Build error resolution report with:
-- List of errors fixed
-- Lines changed per fix
-- Final build status"
-)
-```
-
-## Stop Conditions
-
-The build-fixer agent stops when:
-- Type check command exits with code 0
-- Build command completes successfully
-- No new errors introduced
-
-## Output Format
-
-```
-BUILD FIX REPORT
-================
-
-Errors Fixed: 12
-Files Modified: 8
-Lines Changed: 47
-
-Fixes Applied:
-1. src/utils/validation.ts:15 - Added return type annotation
-2. src/components/Header.tsx:42 - Added null check for props.user
-3. src/api/client.ts:89 - Fixed import path for axios
-...
-
-Final Build Status: ✓ PASSING
-Verification: [type check command] (exit code 0)
-```
-
-## Best Practices
-
-- **One fix at a time** - Easier to verify and debug
-- **Minimal changes** - Don't refactor while fixing
-- **Document why** - Comment non-obvious fixes
-- **Test after** - Ensure tests still pass
-
-
-## 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 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.
-
-**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
-
-## Use with Other Skills
-
-Combine with other skills for comprehensive fixing:
-
-**With Ultrawork:**
-```
-/ultrawork fix all build errors
-```
-Spawns multiple build-fixer agents in parallel for different files.
-
-**With Ralph:**
-```
-/ralph fix the build
-```
-Keeps trying until build passes, even if it takes multiple iterations.
-
-**With Team:**
-```
-/team "debug build failures and fix type errors"
-```
-Uses: explore → build-fixer → verifier workflow.
+Task: {{ARGUMENTS}}

package/skills/deepsearch/SKILL.md

@@ -1,38 +1,10 @@
 ---
 name: deepsearch
-description: Thorough codebase search
+description: Deepsearch deprecated shim
 ---
 
-# Deep Search Mode
+# Deepsearch deprecated
 
-[DEEPSEARCH MODE ACTIVATED]
+Hard-deprecated. Do not invoke or route this skill. Use `$analyze` for deep repository analysis or `omx explore` for fast repo-local lookup.
 
-## Objective
-
-Perform thorough search of the codebase for the specified query, pattern, or concept.
-
-## Search Strategy
-
-1. **Broad Search**
-   - Search for exact matches
-   - Search for related terms and variations
-   - Check common locations (components, utils, services, hooks)
-
-2. **Deep Dive**
-   - Read files with matches
-   - Check imports/exports to find connections
-   - Follow the trail (what imports this? what does this import?)
-
-3. **Synthesize**
-   - Map out where the concept is used
-   - Identify the main implementation
-   - Note related functionality
-
-## Output Format
-
-- **Primary Locations** (main implementations)
-- **Related Files** (dependencies, consumers)
-- **Usage Patterns** (how it's used across the codebase)
-- **Key Insights** (patterns, conventions, gotchas)
-
-Focus on being comprehensive but concise. Cite file paths and line numbers.
+Task: {{ARGUMENTS}}

package/skills/ecomode/SKILL.md

@@ -1,114 +1,10 @@
 ---
 name: ecomode
-description: Token-efficient model routing modifier
+description: Ecomode deprecated shim
 ---
 
-# Ecomode Skill
+# Ecomode deprecated
 
-Token-efficient model routing. This is a **MODIFIER**, not a standalone execution mode.
+Hard-deprecated. Do not invoke or route this skill. Use `$ultrawork` directly for maintained high-throughput execution workflows.
 
-## 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
-delegate(role="executor", tier="LOW", task="...")
-delegate(role="explore", tier="LOW", task="...")
-delegate(role="architect", tier="LOW", task="...")
-
-// FALLBACK - Only if LOW fails
-delegate(role="executor", tier="STANDARD", task="...")
-delegate(role="architect", tier="STANDARD", task="...")
-
-// AVOID - Only for planning/critique if essential
-delegate(role="planner", tier="THOROUGH", 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 `omx_state` MCP tools for ecomode lifecycle state.
-
-- **On activation**:
-  `state_write({mode: "ecomode", active: true})`
-- **On deactivation/completion**:
-  `state_write({mode: "ecomode", active: false})`
-- **On cancellation/cleanup**:
-  run `$cancel` (which should call `state_clear(mode="ecomode")`)
+Task: {{ARGUMENTS}}

package/skills/help/SKILL.md

@@ -1,202 +1,10 @@
 ---
 name: help
-description: Guide on using oh-my-codex plugin
+description: Help deprecated skill
 ---
 
-# How OMX Works
+# Help deprecated
 
-Plain English works as best-effort guidance — OMX inspects each prompt and may add advisory routing context to steer the model toward a suitable lane. This is **advisory prompt-routing context**: it does not activate a skill or workflow by itself. Explicit keywords remain the deterministic control surface when you want exact, guaranteed routing.
+Hard-deprecated. Do not invoke or route this skill. Use `$omx-setup`, `omx setup`, or `omx doctor` directly for setup, install, and troubleshooting guidance.
 
-**Triage lanes** (when no keyword matches): complex/multi-step prompts may receive HEAVY guidance (autopilot-shaped); repo-local read-only lookups receive LIGHT/explore guidance; implementation work receives LIGHT/executor guidance; UI work receives LIGHT/designer guidance; external official-doc/reference/source-backed lookup receives LIGHT/researcher guidance; simple conversational prompts receive no injection (PASS). To opt out per prompt, include a phrase such as `no workflow`, `just chat`, or `plain answer`.
-
-## What Happens Automatically
-
-| When You... | I Automatically... |
-|-------------|-------------------|
-| Give me a complex task | Parallelize and delegate to specialist agents |
-| Ask me to plan something | Start a planning interview |
-| Need something done completely | Persist until verified complete |
-| Work on UI/frontend | Activate design sensibility |
-| Say "stop" or "cancel" | Intelligently stop current operation |
-
-## Magic Keywords (Optional Shortcuts)
-
-You can include these words naturally in your request for explicit control:
-
-| Keyword | Effect | Example |
-|---------|--------|---------|
-| **ralph** | Persistence mode | "ralph: fix all the bugs" |
-| **ralplan** | Iterative planning | "ralplan this feature" |
-| **ulw** | Max parallelism | "ulw refactor the API" |
-| **plan** | Planning interview | "plan the new endpoints" |
-
-**ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords.
-
-## Stopping Things
-
-Just say:
-- "stop"
-- "cancel"
-- "abort"
-
-I'll figure out what to stop based on context.
-
-## First Time Setup
-
-If you haven't configured OMX yet:
-
-```
-/omx-setup
-```
-
-This is the primary setup command for full OMX runtime wiring. Codex plugin install/discovery can expose packaged skills/workflows plus plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks remain setup-owned; it is not a replacement for `npm install -g oh-my-codex` plus `omx setup`. Legacy setup mode installs native agents/prompts; plugin setup mode archives stale legacy prompt/native-agent files and keeps config/hooks/optional AGENTS.md/HUD/runtime wiring current, including native `.codex/hooks.json` coverage. Plugin caches may appear under `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/oh-my-codex/$VERSION/` (or `local` for local installs).
-
-If you only need lightweight directory guidance scaffolding for `AGENTS.md` files, use:
-
-```bash
-omx agents-init .
-```
-
-That command is intentionally narrower than full setup: it only bootstraps `AGENTS.md` files for the target directory and its immediate child directories.
-
-## For 2.x Users
-
-Your old commands still work! `/ralph`, `/ultrawork`, `/plan`, etc. all function exactly as before.
-
-But now you don't NEED them - everything is automatic.
-
----
-
-## Usage Analysis
-
-Analyze your oh-my-codex usage and get tailored recommendations to improve your workflow.
-
-> Note: This replaces the former `/learn-about-omc` skill.
-
-### What It Does
-
-1. Reads token tracking from `~/.omx/state/token-tracking.jsonl`
-2. Reads session history from `.omx/state/session-history.json`
-3. Analyzes agent usage patterns
-4. Identifies underutilized features
-5. Recommends configuration changes
-
-### Step 1: Gather Data
-
-```bash
-# Check for token tracking data
-TOKEN_FILE="$HOME/.omx/state/token-tracking.jsonl"
-SESSION_FILE=".omx/state/session-history.json"
-CONFIG_FILE="$HOME/.codex/.omx-config.json"
-
-echo "Analyzing OMX Usage..."
-echo ""
-
-# Check what data is available
-HAS_TOKENS=false
-HAS_SESSIONS=false
-HAS_CONFIG=false
-
-if [[ -f "$TOKEN_FILE" ]]; then
-  HAS_TOKENS=true
-  TOKEN_COUNT=$(wc -l < "$TOKEN_FILE")
-  echo "Token records found: $TOKEN_COUNT"
-fi
-
-if [[ -f "$SESSION_FILE" ]]; then
-  HAS_SESSIONS=true
-  SESSION_COUNT=$(cat "$SESSION_FILE" | jq '.sessions | length' 2>/dev/null || echo "0")
-  echo "Sessions found: $SESSION_COUNT"
-fi
-
-if [[ -f "$CONFIG_FILE" ]]; then
-  HAS_CONFIG=true
-  DEFAULT_MODE=$(cat "$CONFIG_FILE" | jq -r '.defaultExecutionMode // "not set"')
-  echo "Default execution mode: $DEFAULT_MODE"
-fi
-```
-
-### Step 2: Analyze Agent Usage (if token data exists)
-
-```bash
-if [[ "$HAS_TOKENS" == "true" ]]; then
-  echo ""
-  echo "TOP AGENTS BY USAGE:"
-  cat "$TOKEN_FILE" | jq -r '.agentName // "main"' | sort | uniq -c | sort -rn | head -10
-
-  echo ""
-  echo "MODEL DISTRIBUTION:"
-  cat "$TOKEN_FILE" | jq -r '.modelName' | sort | uniq -c | sort -rn
-fi
-```
-
-### Step 3: Generate Recommendations
-
-Based on patterns found, output recommendations:
-
-**If high Opus usage (>40%) and no ecomode:**
-- "Consider using ecomode for routine tasks to save tokens"
-
-**If no team usage:**
-- "Try /team for coordinated review workflows"
-
-**If no security-reviewer usage:**
-- "Use security-reviewer after auth/API changes"
-
-**If defaultExecutionMode not set:**
-- "Set defaultExecutionMode in /omx-setup for consistent behavior"
-
-### Step 4: Output Report
-
-Format a summary with:
-- Token summary (total, by model)
-- Top agents used
-- Underutilized features
-- Personalized recommendations
-
-### Example Output
-
-```
-📊 Your OMX Usage Analysis
-
-TOKEN SUMMARY:
-- Total records: 1,234
-- By Reasoning Effort: high 45%, medium 40%, low 15%
-
-TOP AGENTS:
-1. executor (234 uses)
-2. architect (89 uses)
-3. explore (67 uses)
-
-UNDERUTILIZED FEATURES:
-- ecomode: 0 uses (could save ~30% on routine tasks)
-- team: 0 uses (great for coordinated workflows)
-
-RECOMMENDATIONS:
-1. Set defaultExecutionMode: "ecomode" to save tokens
-2. Try /team for PR review workflows
-3. Use explore agent before architect to save context
-```
-
-### Graceful Degradation
-
-If no data found:
-
-```
-📊 Limited Usage Data Available
-
-No token tracking found. To enable tracking:
-1. Ensure ~/.omx/state/ directory exists
-2. Run any OMX command to start tracking
-
-Tip: Run /omx-setup to configure OMX properly.
-```
-
-## Need More Help?
-
-- **README**: https://github.com/Yeachan-Heo/oh-my-codex
-- **Issues**: https://github.com/Yeachan-Heo/oh-my-codex/issues
-
----
-
-*Version: 4.2.3*
+Task: {{ARGUMENTS}}

package/skills/note/SKILL.md

@@ -1,62 +1,10 @@
 ---
 name: note
-description: Save notes to notepad.md for compaction resilience
+description: Note deprecated shim
 ---
 
-# Note Skill
+# Note deprecated
 
-Save important context to `.omx/notepad.md` that survives conversation compaction.
+Hard-deprecated. Do not invoke or route this skill. Use OMX persistent memory/notepad surfaces directly when notes are required.
 
-## Usage
-
-| Command | Action |
-|---------|--------|
-| `/note <content>` | Add to Working Memory with timestamp |
-| `/note --priority <content>` | Add to Priority Context (always loaded) |
-| `/note --manual <content>` | Add to MANUAL section (never pruned) |
-| `/note --show` | Display current notepad contents |
-| `/note --prune` | Remove entries older than 7 days |
-| `/note --clear` | Clear Working Memory (keep Priority + MANUAL) |
-
-## Sections
-
-### Priority Context (500 char limit)
-- **Always** injected on session start
-- Use for critical facts: "Project uses pnpm", "API in src/api/client.ts"
-- Keep it SHORT - this eats into your context budget
-
-### Working Memory
-- Timestamped session notes
-- Auto-pruned after 7 days
-- Good for: debugging breadcrumbs, temporary findings
-
-### MANUAL
-- Never auto-pruned
-- User-controlled permanent notes
-- Good for: team contacts, deployment info
-
-## Examples
-
-```
-/note Found auth bug in UserContext - missing useEffect dependency
-/note --priority Project uses TypeScript strict mode, all files in src/
-/note --manual Contact: api-team@company.com for backend questions
-/note --show
-/note --prune
-```
-
-## Behavior
-
-1. Creates `.omx/notepad.md` if it doesn't exist
-2. Parses the argument to determine section
-3. Appends content with timestamp (for Working Memory)
-4. Warns if Priority Context exceeds 500 chars
-5. Confirms what was saved
-
-## Integration
-
-Notepad content is automatically loaded on session start:
-- Priority Context: ALWAYS loaded
-- Working Memory: Loaded if recent entries exist
-
-This helps survive conversation compaction without losing critical context.
+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 `codex_hooks = true` because plugins do not carry hooks.
+  - `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.
 - 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. |
+| `~/.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/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. |

package/skills/performance-goal/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: performance-goal
+description: "Run an evaluator-gated performance optimization workflow over Codex goal mode with durable OMX artifacts and safe goal handoffs."
+---
+
+# Performance Goal Workflow
+
+Use this skill when a user asks OMX to optimize performance and wants a goal-oriented loop rather than a one-off review.
+
+## Contract
+
+- OMX owns durable workflow state under `.omx/goals/performance/<slug>/`.
+- Codex goal mode owns only the active-thread focus/accounting primitive.
+- Shell commands do **not** mutate hidden Codex goal state. They write artifacts and emit model-facing handoff text.
+- No optimization work may start until an evaluator command and pass/fail contract exist.
+- Do not call `update_goal({status: "complete"})` until the evaluator has a passing checkpoint and a completion audit proves the objective is done; then call `get_goal` again and pass that fresh snapshot to `omx performance-goal complete --codex-goal-json`.
+
+## CLI
+
+Create the workflow and evaluator contract:
+
+```sh
+omx performance-goal create \
+  --objective "Reduce CLI startup latency by 20%" \
+  --evaluator-command "npm run perf:startup" \
+  --evaluator-contract "PASS when p95 latency improves by 20% and regression tests pass" \
+  --slug startup-latency
+```
+
+Emit the Codex goal handoff:
+
+```sh
+omx performance-goal start --slug startup-latency
+```
+
+Record evaluator evidence:
+
+```sh
+omx performance-goal checkpoint --slug startup-latency --status pass --evidence "benchmark + tests passed"
+omx performance-goal checkpoint --slug startup-latency --status fail --evidence "benchmark regressed"
+omx performance-goal checkpoint --slug startup-latency --status blocked --evidence "missing fixture"
+```
+
+Complete only after a passing checkpoint:
+
+```sh
+omx performance-goal complete --slug startup-latency --evidence "final evaluator evidence" --codex-goal-json <get_goal-json-or-path>
+```
+
+## Agent Loop
+
+1. Run `omx performance-goal create` if no workflow exists.
+2. Run `omx performance-goal start` and follow the handoff:
+   - call `get_goal`;
+   - call `create_goal` only when no active goal exists and the objective is explicit;
+   - work only against the evaluator contract;
+   - after evaluator pass and completion audit, call `update_goal({status: "complete"})`, call `get_goal` again, and pass that snapshot to `omx performance-goal complete --codex-goal-json`;
+3. Optimize in small reversible patches.
+4. Run the evaluator and related regression tests.
+5. Record each pass/fail/blocker with `checkpoint`.
+6. Complete only when the pass artifact exists and no required work remains.
+
+## Completion Gate
+
+A performance goal is incomplete unless `.omx/goals/performance/<slug>/state.json` contains a `lastValidation.status` of `pass` and `omx performance-goal complete` receives a matching complete Codex `get_goal` snapshot via `--codex-goal-json`. Passing ordinary tests alone is not sufficient unless they are the declared evaluator contract.

package/skills/plan/SKILL.md

@@ -114,7 +114,7 @@ Jumping into code without understanding requirements leads to rework, scope cree
 2. Evaluate via Critic using `ask_codex` with `agent_role: "critic"`
 3. For cleanup/refactor/anti-slop work, verify that the artifact includes a cleanup plan, regression tests or an explicit test gap, smell-by-smell passes, and quality gates.
 4. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
-5. If the current context authored the artifact, hand the review to `/review`, `critic`, `quality-reviewer`, `security-reviewer`, or `verifier` as appropriate.
+5. If the current context authored the artifact, hand the review to `$code-review`, `critic`, `quality-reviewer`, or `verifier` as appropriate.
 
 ### Plan Output Format