ralph

<Purpose> Ralph is a persistence loop that keeps working on a task until it is fully complete and architect-verified. It wraps ultrawork's parallel execution with session persistence, automatic retry on failure, and mandatory verification before completion. </Purpose>

• Task requires guaranteed completion with verification (not just "do your best")
• User says "ralph", "don't stop", "must complete", "finish this", or "keep going until done"
• Work may span multiple iterations and needs persistence across retries
• Task benefits from parallel execution with architect sign-off at the end </Use_When>

• User wants a full autonomous pipeline from idea to code -- use

  autopilot

  instead
• User wants to explore or plan before committing -- use

  plan

  skill instead
• User wants a quick one-shot fix -- delegate directly to an executor agent
• User wants manual control over completion -- use

  ultrawork

  directly </Do_Not_Use_When>

• Fire independent agent calls simultaneously -- never wait sequentially for independent work
• Use

  run_in_background: true

  for long operations (installs, builds, test suites)
• Always pass the

  model

  parameter explicitly when delegating to agents
• Read

  docs/shared/agent-tiers.md

  before first delegation to select correct agent tiers
• Deliver the full implementation: no scope reduction, no partial completion, no deleting tests to make them pass
• Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more 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 execution loop is grounded
• Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent </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, gather brownfield facts first. When session guidance enables `USE_OMX_EXPLORE_CMD`, prefer `omx explore` for simple read-only repository lookups with narrow, concrete prompts; otherwise use the richer normal explore path. 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 - Simple lookups: LOW tier -- "What does this function return?" - Standard work: STANDARD tier -- "Add error handling to this module" - Complex analysis: THOROUGH tier -- "Debug this race condition" - When Ralph is entered as a ralplan follow-up, start from the approved **available-agent-types roster** and make the delegation plan explicit: implementation lane, evidence/regression lane, and final sign-off lane using only known agent types 4. **Run long operations in background**: Builds, installs, test suites use `run_in_background: true` 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 7. **Architect verification** (tiered): - <5 files, <100 lines with full tests: STANDARD tier minimum (architect role) - Standard changes: STANDARD tier (architect role) - >20 files or security/architectural changes: THOROUGH tier (architect role) - Ralph floor: always at least STANDARD, even for small changes 7.5 **Mandatory Deslop Pass**: - After Step 7 passes, run `oh-my-codex:ai-slop-cleaner` on **all files changed during the Ralph session**. - Scope the cleaner to **changed files only**; do not widen the pass beyond Ralph-owned edits. - Run the cleaner in **standard mode** (not `--review`). - If the prompt contains `--no-deslop`, skip Step 7.5 entirely and proceed with the most recent successful verification evidence. 7.6 **Regression Re-verification**: - After the deslop pass, re-run all tests/build/lint and read the output to confirm they still pass. - If post-deslop regression fails, roll back cleaner changes or fix and retry. Then rerun Step 7.5 and Step 7.6 until the regression is green. - Do not proceed to completion until post-deslop regression is green (unless `--no-deslop` explicitly skipped the deslop pass). 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>

• 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
• Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context </Tool_Usage>

• 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>"}})

• On each iteration:

  state_write({mode: "ralph", iteration: <current>, current_phase: "executing"})

• On verification/fix transition:

  state_write({mode: "ralph", current_phase: "verifying"})

  or

  state_write({mode: "ralph", current_phase: "fixing"})

• On completion:

  state_write({mode: "ralph", active: false, current_phase: "complete", completed_at: "<now>"})

• On cancellation/cleanup: run

  $cancel

  (which should call

  state_clear(mode="ralph")

  )

omx_state

state_write

state_read

state_clear

<Examples> <Good> Correct parallel delegation: ``` delegate(role="executor", tier="LOW", task="Add type export for UserConfig") delegate(role="executor", tier="STANDARD", task="Implement the caching layer for API responses") delegate(role="executor", tier="THOROUGH", task="Refactor auth module to support OAuth2 flow") ``` Why good: Three independent tasks fired simultaneously at appropriate tiers. </Good> <Good> Correct verification before completion: ``` 1. Run: npm test → Output: "42 passed, 0 failed" 2. Run: npm run build → Output: "Build succeeded" 3. Run: lsp_diagnostics → Output: 0 errors 4. Delegate to architect at STANDARD tier → Verdict: "APPROVED" 5. Run /cancel ``` Why good: Fresh evidence at each step, architect verification, then clean exit. </Good> <Bad> Claiming completion without verification: "All the changes look good, the implementation should work correctly. Task complete." Why bad: Uses "should" and "look good" -- no fresh test/build output, no architect verification. </Bad> <Bad> Sequential execution of independent tasks: ``` delegate(executor, LOW, "Add type export") → wait → delegate(executor, STANDARD, "Implement caching") → wait → delegate(executor, THOROUGH, "Refactor auth") ``` Why bad: These are independent tasks that should run in parallel, not sequentially. </Bad> </Examples>

• Stop and report when a fundamental blocker requires user input (missing credentials, unclear requirements, external service down)
• Stop when the user says "stop", "cancel", or "abort" -- run

  /cancel

• Continue working when the hook system sends "The boulder never stops" -- this means the iteration continues
• If architect rejects verification, fix the issues and re-verify (do not stop)
• If the same issue recurs across 3+ iterations, report it as a potential fundamental problem </Escalation_And_Stop_Conditions>

• All requirements from the original task are met (no scope reduction)
• Zero pending or in_progress TODO items
• Fresh test run output shows all tests pass
• Fresh build output shows success
• lsp_diagnostics shows 0 errors on affected files
• Architect verification passed (STANDARD tier minimum)
• ai-slop-cleaner pass completed on changed files (or --no-deslop specified)
• Post-deslop regression tests pass

• /cancel

  run for clean state cleanup </Final_Checklist>

<Advanced>

continue

提交PR

continue

• Repeatable image inputs:

  -i <image-path>

  (can be used multiple times)
• Image directory input:

  --images-dir <directory>

ralph -i refs/hn.png -i refs/hn-item.png --images-dir ./screenshots "match HackerNews layout"

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)
3. Parse the task (everything after

   --prd

   flag)
4. Break down into user stories:

1. Initialize canonical progress ledger at

   .omx/state/{scope}/ralph-progress.json

2. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
3. Proceed to normal ralph loop using user stories as the task list

{
  "project": "[Project Name]",
  "branchName": "ralph/[feature-name]",
  "description": "[Feature description]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Short title]",
      "description": "As a [user], I want to [action] so that [benefit].",
      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
      "priority": 1,
      "passes": false
    }
  ]
}

• Package installation (npm install, pip install, cargo build)
• Build processes (make, project build commands)
• Test suites
• Docker operations (docker build, docker pull)

• Quick status checks (git status, ls, pwd)
• File reads and edits
• Simple commands </Advanced>

run_in_background: true