oh-my-codex 0.7.5 → 0.8.0

package/skills/help/SKILL.md

@@ -44,7 +44,7 @@ I'll figure out what to stop based on context.
 If you haven't configured OMX yet:
 
 ```
-/omc-setup
+/omx-setup
 ```
 
 This is the **only command** you need to know. It downloads the configuration and you're done.
@@ -134,7 +134,7 @@ Based on patterns found, output recommendations:
 - "Use security-reviewer after auth/API changes"
 
 **If defaultExecutionMode not set:**
-- "Set defaultExecutionMode in /omc-setup for consistent behavior"
+- "Set defaultExecutionMode in /omx-setup for consistent behavior"
 
 ### Step 4: Output Report
 
@@ -179,7 +179,7 @@ No token tracking found. To enable tracking:
 1. Ensure ~/.omx/state/ directory exists
 2. Run any OMX command to start tracking
 
-Tip: Run /omc-setup to configure OMX properly.
+Tip: Run /omx-setup to configure OMX properly.
 ```
 
 ## Need More Help?

package/skills/ralph/SKILL.md

@@ -38,6 +38,18 @@ Complex tasks often fail silently: partial implementations get declared "done",
 </Execution_Policy>
 
 <Steps>
+0. **Pre-context intake (required before planning/execution loop starts)**:
+   - Assemble or load a context snapshot at `.omx/context/{task-slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`).
+   - Minimum snapshot fields:
+     - task statement
+     - desired outcome
+     - known facts/evidence
+     - constraints
+     - unknowns/open questions
+     - likely codebase touchpoints
+   - If an existing relevant snapshot is available, reuse it and record the path in Ralph state.
+   - If request ambiguity is high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` to close critical gaps.
+   - Do not begin Ralph execution work (delegation, implementation, or verification loops) until snapshot grounding exists. If forced to proceed quickly, note explicit risk tradeoffs.
 1. **Review progress**: Check TODO list and any prior iteration state
 2. **Continue from where you left off**: Pick up incomplete tasks
 3. **Delegate in parallel**: Route tasks to specialist agents at appropriate tiers
@@ -45,18 +57,24 @@ Complex tasks often fail silently: partial implementations get declared "done",
    - Standard work: MEDIUM tier (Sonnet) -- "Add error handling to this module"
    - Complex analysis: HIGH tier (Opus) -- "Debug this race condition"
 4. **Run long operations in background**: Builds, installs, test suites use `run_in_background: true`
-5. **Verify completion with fresh evidence**:
+5. **Visual task gate (when screenshot/reference images are present)**:
+   - Run `$visual-verdict` **before every next edit**.
+   - Require structured JSON output: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, `reasoning`.
+   - Persist verdict to `.omx/state/{scope}/ralph-progress.json` including numeric + qualitative feedback.
+   - Default pass threshold: `score >= 90`.
+   - **URL-based cloning tasks**: When the task description contains a target URL (e.g., "clone https://example.com"), invoke `$web-clone` instead of `$visual-verdict`. The web-clone skill handles the full extraction → generation → verification pipeline and uses `$visual-verdict` internally for visual scoring.
+6. **Verify completion with fresh evidence**:
    a. Identify what command proves the task is complete
    b. Run verification (test, build, lint)
    c. Read the output -- confirm it actually passed
    d. Check: zero pending/in_progress TODO items
-6. **Architect verification** (tiered):
+7. **Architect verification** (tiered):
    - <5 files, <100 lines with full tests: STANDARD tier minimum (architect-medium / Sonnet)
    - Standard changes: STANDARD tier (architect-medium / Sonnet)
    - >20 files or security/architectural changes: THOROUGH tier (architect / Opus)
    - Ralph floor: always at least STANDARD, even for small changes
-7. **On approval**: Run `/cancel` to cleanly exit and clean up all state files
-8. **On rejection**: Fix the issues raised, then re-verify at the same tier
+8. **On approval**: Run `/cancel` to cleanly exit and clean up all state files
+9. **On rejection**: Fix the issues raised, then re-verify at the same tier
 </Steps>
 
 <Tool_Usage>
@@ -65,6 +83,7 @@ Complex tasks often fail silently: partial implementations get declared "done",
 - 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
+- Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context
 </Tool_Usage>
 
 ## State Management
@@ -72,7 +91,7 @@ Complex tasks often fail silently: partial implementations get declared "done",
 Use the `omx_state` MCP server tools (`state_write`, `state_read`, `state_clear`) for Ralph lifecycle state.
 
 - **On start**:
-  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>"})`
+  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
 - **On each iteration**:
   `state_write({mode: "ralph", iteration: <current>, current_phase: "executing"})`
 - **On verification/fix transition**:
@@ -148,12 +167,24 @@ When the user provides the `--prd` flag, initialize a Product Requirements Docum
 ### Detecting PRD Mode
 Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
 
+### Visual Reference Flags (Optional)
+Ralph execution supports visual reference flags for screenshot tasks:
+- Repeatable image inputs: `-i <image-path>` (can be used multiple times)
+- Image directory input: `--images-dir <directory>`
+
+Example:
+`ralph -i refs/hn.png -i refs/hn-item.png --images-dir ./screenshots "match HackerNews layout"`
+
 ### PRD Workflow
-1. Create canonical PRD/progress artifacts:
+1. Run deep-interview in quick mode before creating PRD artifacts:
+   - Execute: `$deep-interview --quick <task>`
+   - Complete a compact requirements pass (context, goals, scope, constraints, validation)
+   - Persist interview output to `.omx/interviews/{slug}-{timestamp}.md`
+2. Create canonical PRD/progress artifacts:
    - PRD: `.omx/plans/prd-{slug}.md`
    - Progress ledger: `.omx/state/{scope}/ralph-progress.json` (session scope when available, else root scope)
-2. Parse the task (everything after `--prd` flag)
-3. Break down into user stories:
+3. Parse the task (everything after `--prd` flag)
+4. Break down into user stories:
 
 ```json
 {
@@ -173,9 +204,9 @@ Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
 }
 ```
 
-4. Initialize canonical progress ledger at `.omx/state/{scope}/ralph-progress.json`
-5. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
-6. Proceed to normal ralph loop using user stories as the task list
+5. Initialize canonical progress ledger at `.omx/state/{scope}/ralph-progress.json`
+6. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
+7. Proceed to normal ralph loop using user stories as the task list
 
 ### Example
 User input: `--prd build a todo app with React and TypeScript`

package/skills/ralplan/SKILL.md

@@ -58,6 +58,23 @@ The consensus workflow:
 
 Follow the Plan skill's full documentation for consensus mode details.
 
+## Pre-context Intake
+
+Before consensus planning or execution handoff, ensure a grounded context snapshot exists:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.omx/context/{slug}-*.md` when available.
+3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before continuing.
+
+Do not hand off to execution modes until this intake is complete; if urgency forces progress, explicitly document the risk tradeoffs.
+
 ## Pre-Execution Gate
 
 ### Why the Gate Exists

package/skills/skill/SKILL.md

@@ -15,19 +15,19 @@ Meta-skill for managing oh-my-codex skills via CLI-like commands.
 Show all local skills organized by scope.
 
 **Behavior:**
-1. Scan user skills at `~/.codex/skills/omc-learned/`
-2. Scan project skills at `.omx/skills/`
+1. Scan user skills at `~/.agents/skills/`
+2. Scan project skills at `.agents/skills/`
 3. Parse YAML frontmatter for metadata
 4. Display in organized table format:
 
 ```
-USER SKILLS (~/.codex/skills/omc-learned/):
+USER SKILLS (~/.agents/skills/):
 | Name              | Triggers           | Quality | Usage | Scope |
 |-------------------|--------------------|---------|-------|-------|
 | error-handler     | fix, error         | 95%     | 42    | user  |
 | api-builder       | api, endpoint      | 88%     | 23    | user  |
 
-PROJECT SKILLS (.omx/skills/):
+PROJECT SKILLS (.agents/skills/):
 | Name              | Triggers           | Quality | Usage | Scope   |
 |-------------------|--------------------|---------|-------|---------|
 | test-runner       | test, run          | 92%     | 15    | project |
@@ -51,8 +51,8 @@ Interactive wizard for creating a new skill.
 4. **Ask for argument hint** (optional)
    - Example: "<file> [options]"
 5. **Ask for scope:**
-   - `user` → `~/.codex/skills/omc-learned/<name>/SKILL.md`
-   - `project` → `.omx/skills/<name>/SKILL.md`
+   - `user` → `~/.agents/skills/<name>/SKILL.md`
+   - `project` → `.agents/skills/<name>/SKILL.md`
 6. **Create skill file** with template:
 
 ```yaml
@@ -105,7 +105,7 @@ Triggers (comma-separated): log, logger, logging
 Argument hint (optional): <level> [message]
 Scope (user/project): user
 
-✓ Created skill at ~/.codex/skills/omc-learned/custom-logger/SKILL.md
+✓ Created skill at ~/.agents/skills/custom-logger/SKILL.md
 → Edit with: /skill edit custom-logger
 ```
 
@@ -117,13 +117,13 @@ Remove a skill by name.
 
 **Behavior:**
 1. **Search for skill** in both scopes:
-   - `~/.codex/skills/omc-learned/<name>/SKILL.md`
-   - `.omx/skills/<name>/SKILL.md`
+   - `~/.agents/skills/<name>/SKILL.md`
+   - `.agents/skills/<name>/SKILL.md`
 2. **If found:**
    - Display skill info (name, description, scope)
    - **Ask for confirmation:** "Delete '<name>' skill from <scope>? (yes/no)"
 3. **If confirmed:**
-   - Delete entire skill directory (e.g., `~/.codex/skills/omc-learned/<name>/`)
+   - Delete entire skill directory (e.g., `~/.agents/skills/<name>/`)
    - Report: "✓ Removed skill '<name>' from <scope>"
 4. **If not found:**
    - Report: "✗ Skill '<name>' not found in user or project scope"
@@ -135,7 +135,7 @@ Remove a skill by name.
 User: /skill remove old-logger
 Assistant: Found skill 'old-logger' in user scope:
   Description: Legacy logging utility
-  Scope: user (~/.codex/skills/omc-learned/)
+  Scope: user (~/.agents/skills/)
 
 Delete 'old-logger' skill? (yes/no)
 
@@ -251,13 +251,13 @@ Show detailed information about a skill.
 
 ```
 Skill: custom-logger
-Scope: user (~/.codex/skills/omc-learned/custom-logger/)
+Scope: user (~/.agents/skills/custom-logger/)
 Description: Enhanced logging with structured output
 Triggers: log, logger, logging
 Argument Hint: <level> [message]
 Quality: 95% (if available)
 Usage Count: 42 times (if available)
-File Path: /home/user/.codex/skills/omc-learned/custom-logger/SKILL.md
+File Path: /home/user/.agents/skills/custom-logger/SKILL.md
 
 --- FULL CONTENT ---
 [entire markdown content]
@@ -272,7 +272,7 @@ Assistant: Skill: custom-logger
 Scope: user
 Description: Enhanced logging with structured output
 Triggers: log, logger, logging
-File: ~/.codex/skills/omc-learned/custom-logger/SKILL.md
+File: ~/.agents/skills/custom-logger/SKILL.md
 
 --- CONTENT ---
 # Custom Logger Skill
@@ -290,8 +290,8 @@ Sync skills between user and project scopes.
 
 **Behavior:**
 1. **Scan both scopes:**
-   - User skills: `~/.codex/skills/omc-learned/`
-   - Project skills: `.omx/skills/`
+   - User skills: `~/.agents/skills/`
+   - Project skills: `.agents/skills/`
 2. **Compare and categorize:**
    - User-only skills (not in project)
    - Project-only skills (not in user)
@@ -339,7 +339,7 @@ Assistant: Found 5 user-only skills and 2 project-only skills.
 
 Copy 'error-handler' from user to project? (yes/no/skip)
 User: yes
-Assistant: ✓ Copied 'error-handler' to .omx/skills/
+Assistant: ✓ Copied 'error-handler' to .agents/skills/
 
 Copy 'api-builder' from user to project? (yes/no/skip)
 User: skip
@@ -360,7 +360,7 @@ First, check if skill directories exist and create them if needed:
 
 ```bash
 # Check and create user-level skills directory
-USER_SKILLS_DIR="$HOME/.codex/skills/omc-learned"
+USER_SKILLS_DIR="$HOME/.agents/skills"
 if [ -d "$USER_SKILLS_DIR" ]; then
   echo "User skills directory exists: $USER_SKILLS_DIR"
 else
@@ -369,7 +369,7 @@ else
 fi
 
 # Check and create project-level skills directory
-PROJECT_SKILLS_DIR=".omx/skills"
+PROJECT_SKILLS_DIR=".agents/skills"
 if [ -d "$PROJECT_SKILLS_DIR" ]; then
   echo "Project skills directory exists: $PROJECT_SKILLS_DIR"
 else
@@ -384,15 +384,15 @@ Scan both directories and show a comprehensive inventory:
 
 ```bash
 # Scan user-level skills
-echo "=== USER-LEVEL SKILLS (~/.codex/skills/omc-learned/) ==="
-if [ -d "$HOME/.codex/skills/omc-learned" ]; then
-  USER_COUNT=$(find "$HOME/.codex/skills/omc-learned" -name "*.md" 2>/dev/null | wc -l)
+echo "=== USER-LEVEL SKILLS (~/.agents/skills/) ==="
+if [ -d "$HOME/.agents/skills" ]; then
+  USER_COUNT=$(find "$HOME/.agents/skills" -name "*.md" 2>/dev/null | wc -l)
   echo "Total skills: $USER_COUNT"
 
   if [ $USER_COUNT -gt 0 ]; then
     echo ""
     echo "Skills found:"
-    find "$HOME/.codex/skills/omc-learned" -name "*.md" -type f -exec sh -c '
+    find "$HOME/.agents/skills" -name "*.md" -type f -exec sh -c '
       FILE="$1"
       NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
       DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
@@ -408,15 +408,15 @@ else
 fi
 
 echo ""
-echo "=== PROJECT-LEVEL SKILLS (.omx/skills/) ==="
-if [ -d ".omx/skills" ]; then
-  PROJECT_COUNT=$(find ".omx/skills" -name "*.md" 2>/dev/null | wc -l)
+echo "=== PROJECT-LEVEL SKILLS (.agents/skills/) ==="
+if [ -d ".agents/skills" ]; then
+  PROJECT_COUNT=$(find ".agents/skills" -name "*.md" 2>/dev/null | wc -l)
   echo "Total skills: $PROJECT_COUNT"
 
   if [ $PROJECT_COUNT -gt 0 ]; then
     echo ""
     echo "Skills found:"
-    find ".omx/skills" -name "*.md" -type f -exec sh -c '
+    find ".agents/skills" -name "*.md" -type f -exec sh -c '
       FILE="$1"
       NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
       DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
@@ -467,8 +467,8 @@ Ask user to provide either:
 - **Paste content**: Paste skill markdown content directly
 
 Then ask for scope:
-- **User-level** (~/.codex/skills/omc-learned/) - Available across all projects
-- **Project-level** (.omx/skills/) - Only for this project
+- **User-level** (~/.agents/skills/) - Available across all projects
+- **Project-level** (.agents/skills/) - Only for this project
 
 Validate the skill format and save to the chosen location.
 
@@ -715,7 +715,7 @@ When invoked without arguments, run the full guided wizard.
 
 **Automatic Application**: Codex detects triggers and applies skills automatically - no need to remember or search for solutions.
 
-**Version Control**: Project-level skills (.omx/skills/) are committed with your code, so the whole team benefits.
+**Version Control**: Project-level skills (.agents/skills/) are committed with your code, so the whole team benefits.
 
 **Evolving Knowledge**: Skills improve over time as you discover better approaches and refine triggers.
 
@@ -760,8 +760,8 @@ Good skills are:
 > /skill list
 
 Checking skill directories...
-✓ User skills directory exists: ~/.codex/skills/omc-learned/
-✓ Project skills directory exists: .omx/skills/
+✓ User skills directory exists: ~/.agents/skills/
+✓ Project skills directory exists: .agents/skills/
 
 Scanning for skills...
 

package/skills/team/SKILL.md

@@ -70,6 +70,23 @@ tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || tru
 
 If duplicates exist, remove extras before `omx team` to prevent HUD ending up in worker stack.
 
+## Pre-context Intake Gate
+
+Before launching `omx team`, require a grounded context snapshot:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.omx/context/{slug}-*.md` when available.
+3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before team launch.
+
+Do not start worker panes until this gate is satisfied; if forced to proceed quickly, state explicit scope/risk limitations in the launch report.
+
 ## Current Runtime Behavior (As Implemented)
 
 `omx team` currently performs:
@@ -343,6 +360,49 @@ When operating this skill, provide concrete progress evidence:
 Do not claim success without file/pane evidence.
 Do not claim clean completion if shutdown occurred with `in_progress>0`.
 
+## MCP Job Lifecycle Tools
+
+For programmatic or agent-driven team spawning (as opposed to interactive CLI use), OMX exposes four MCP tools via the `team-server`:
+
+| Tool | Description |
+|------|-------------|
+| `omx_run_team_start` | Spawn tmux CLI workers in the background; returns a `jobId` immediately |
+| `omx_run_team_status` | Non-blocking status check for a running job |
+| `omx_run_team_wait` | Block until the job completes, with automatic idle-pane nudging |
+| `omx_run_team_cleanup` | Kill worker tmux panes for a job (early stop only) |
+
+### CLI vs MCP Tools
+
+- **`omx team ...` CLI** — Primary method for interactive team orchestration. Use this when you are operating inside a live tmux session and want direct pane visibility.
+- **`omx_run_team_*` MCP tools** — For programmatic or agent-driven team spawning (analogous to OMC's `omc_run_team_*` tools). Use these when an agent needs to launch workers, poll status, and collect results without manual intervention.
+
+### Naming Distinction
+
+Two cleanup tools exist and must not be confused:
+
+- `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.omx/state/team/<team>/`). Use after a team run is fully complete.
+- `omx_run_team_cleanup` (**team-server**): Kills tmux worker **panes** for a job. Use only when stopping workers early; otherwise `omx_run_team_wait` handles natural termination.
+
+### Basic Usage Example
+
+```
+1. omx_run_team_start({
+     teamName: "fix-bugs",
+     agentTypes: ["codex"],
+     tasks: [{ subject: "Fix bug", description: "..." }],
+     cwd: "/path/to/project"
+   })
+   → Returns { jobId: "omx-abc123" }
+
+2. omx_run_team_wait({ job_id: "omx-abc123", timeout_ms: 300000 })
+   → Blocks until done, auto-nudges idle panes
+
+3. omx_run_team_cleanup({ job_id: "omx-abc123" })
+   → Only needed if stopping workers early
+```
+
+`omx_run_team_status` can be called between steps 1 and 2 for a non-blocking poll if you need to interleave other work while workers run.
+
 ## Limitations
 
 - Worktree provisioning requires a git repository and can fail on branch/path collisions

package/skills/visual-verdict/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: visual-verdict
+description: Structured visual QA verdict for screenshot-to-reference comparisons
+---
+
+<Purpose>
+Use this skill to compare generated UI screenshots against one or more reference images and return a strict JSON verdict that can drive the next edit iteration.
+</Purpose>
+
+<Use_When>
+- The task includes visual fidelity requirements (layout, spacing, typography, component styling)
+- You have a generated screenshot and at least one reference image
+- You need deterministic pass/fail guidance before continuing edits
+</Use_When>
+
+<Inputs>
+- `reference_images[]` (one or more image paths)
+- `generated_screenshot` (current output image)
+- Optional: `category_hint` (e.g., `hackernews`, `sns-feed`, `dashboard`)
+</Inputs>
+
+<Output_Contract>
+Return **JSON only** with this exact shape:
+
+```json
+{
+  "score": 0,
+  "verdict": "revise",
+  "category_match": false,
+  "differences": ["..."],
+  "suggestions": ["..."],
+  "reasoning": "short explanation"
+}
+```
+
+Rules:
+- `score`: integer 0-100
+- `verdict`: short status (`pass`, `revise`, or `fail`)
+- `category_match`: `true` when the generated screenshot matches the intended UI category/style
+- `differences[]`: concrete visual mismatches (layout, spacing, typography, colors, hierarchy)
+- `suggestions[]`: actionable next edits tied to the differences
+- `reasoning`: 1-2 sentence summary
+
+<Threshold_And_Loop>
+- Target pass threshold is **90+**.
+- If `score < 90`, continue editing and rerun `$visual-verdict` before any further code edits in the next iteration.
+- Persist the verdict in `.omx/state/{scope}/ralph-progress.json` with both:
+  - numeric signal (`score`, threshold pass/fail)
+  - qualitative signal (`reasoning`, `suggestions`, `next_actions`)
+</Threshold_And_Loop>
+
+<Debug_Visualization>
+When mismatch diagnosis is hard:
+1. Keep `$visual-verdict` as the authoritative decision.
+2. Use pixel-level diff tooling (pixel diff / pixelmatch overlay) as a **secondary debug aid** to localize hotspots.
+3. Convert pixel diff hotspots into concrete `differences[]` and `suggestions[]` updates.
+</Debug_Visualization>
+
+<Example>
+```json
+{
+  "score": 87,
+  "verdict": "revise",
+  "category_match": true,
+  "differences": [
+    "Top nav spacing is tighter than reference",
+    "Primary button uses smaller font weight"
+  ],
+  "suggestions": [
+    "Increase nav item horizontal padding by 4px",
+    "Set primary button font-weight to 600"
+  ],
+  "reasoning": "Core layout matches, but style details still diverge."
+}
+```
+</Example>