Ralph

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

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

<Escalation_And_Stop_Conditions>

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

<Final_Checklist>

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

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

Original task: {{PROMPT}}