ralph

[RALPH + ULTRAWORK - ITERATION {{ITERATION}}/{{MAX}}]

Your previous attempt did not output the completion promise. Continue working on the task.

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

<Use_When>

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

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

<Why_This_Exists> Complex tasks often fail silently: partial implementations get declared "done", tests get skipped, edge cases get forgotten. Ralph prevents this by looping until work is genuinely complete, requiring fresh verification evidence before allowing completion, and using tiered architect review to confirm quality. </Why_This_Exists>

<Execution_Policy>

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

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

State Management

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: {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"))

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.

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

---

Content truncated.