Ralph

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

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

Goal Mode Integration

Codex goal mode is the thread-level completion contract for long-running Ralph work. Ralph state tracks workflow mechanics; goal mode tracks whether the user objective is truly done. When the goal tools are available:

1. Call get_goal during intake or before the first execution loop when the prompt/hook says an active thread goal exists.
2. If no goal exists, call create_goal only when the user or system explicitly asked for goal tracking; otherwise continue with Ralph state alone.
3. Treat goal.objective as binding acceptance scope. Newer user updates can refine the current branch, but do not silently narrow the goal.
4. Before completion, perform a prompt-to-artifact checklist and completion audit against real evidence:
   • restate the objective as deliverables/success criteria
   • map every prompt requirement, named workflow ($ralplan, $ralph), file, command, test, gate, and deliverable to evidence
   • inspect the actual files, command output, state, and tests behind each checklist item
   • identify missing, weakly verified, or uncovered requirements and continue if any remain
5. Call update_goal({status: "complete"}) only when the audit shows no required work remains. Do not use passing tests, Ralph state, or architect approval as proxy proof unless they cover the whole goal.
6. If goal tools are unavailable, keep working through Ralph state and mention the missing goal-mode evidence in the final report.

State Management

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: 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: omx state write --input '{"mode":"ralph","iteration":<current>,"current_phase":"executing"}' --json
• On verification/fix transition: omx state write --input '{"mode":"ralph","current_phase":"verifying"}' --json or omx state write --input '{"mode":"ralph","current_phase":"fixing"}' --json
• On completion (only after the completion audit passes with real evidence): omx state write --input '{"mode":"ralph","active":false,"current_phase":"complete","completed_at":"<now>","completion_audit":{"passed":true,"prompt_to_artifact_checklist":["<requirement mapped to artifact/evidence>"],"verification_evidence":["<fresh test/build/lint command and result>"]}}' --json
• Before the final answer:
  1. Run fresh verification and read the output.
  2. Build prompt_to_artifact_checklist entries that map every user requirement, workflow gate, named file, command, PR/delivery requirement, and stop condition to a concrete artifact or evidence item.
  3. Build verification_evidence entries with concrete commands, exit status, files inspected, PR URLs, or other machine-checkable evidence.
  4. Write the Ralph completion state with a top-level completion_audit field on the Ralph state object. Do not write bare top-level prompt_to_artifact_checklist or verification_evidence fields by themselves; the Stop gate will reject them.
  5. Read the state back with omx state read --input '{"mode":"ralph"}' --json and verify completion_audit.passed === true, a non-empty checklist, and non-empty verification evidence before producing the final answer.
  6. If Codex goal mode is active, call update_goal({status:"complete"}) only after this Ralph audit read-back succeeds.
• On cancellation/cleanup: run $cancel (which should call omx state clear --input '{"mode":"ralph"}' --json)

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.

When the user provides the --prd flag, initialize a Product Requirements Document before starting the ralph loop.

Detecting PRD Mode

Check if {{PROMPT}} contains --prd or --PRD.

Prompt-side $ralph workflow activation is lighter-weight than omx ralph --prd .... It seeds Ralph workflow state and guidance, but it does not implicitly launch the CLI entrypoint or apply the PRD startup gate. Treat omx ralph --prd ... as the explicit PRD-gated path.

Detecting --no-deslop

Check if {{PROMPT}} contains --no-deslop. If --no-deslop is present, skip the deslop pass entirely after Step 7 and continue using the latest successful pre-deslop verification evidence.

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

{
  "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
    }
  ]
}

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 Workflow: Detect flag, extract task, create .omx/plans/prd-{slug}.md, create .omx/state/{scope}/ralph-progress.json, begin ralph loop.

Legacy compatibility

• During the compatibility window, Ralph --prd startup still validates machine-readable story state from .omx/prd.json.
• .omx/plans/prd-{slug}.md remains the canonical storage/documentation artifact, but it is not yet the startup validation source.
• If .omx/prd.json exists and canonical PRD is absent, migrate one-way into .omx/plans/prd-{slug}.md.
• If .omx/progress.txt exists and canonical progress ledger is absent, import one-way into .omx/state/{scope}/ralph-progress.json.
• Keep legacy files unchanged for one release cycle.

Background Execution Rules

Run in background (run_in_background: true):

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

Run blocking (foreground):

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

Original task: {{PROMPT}}