ralph

name	ralph
description	Bounded continuation loop on top of Ultrawork with architect verification.

Ralph

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

Ralph is the persistence loop that keeps working on a task until it is fully complete, freshly verified, cleaned up, and architect-approved. It wraps the Ultrawork execution discipline with session persistence, automatic continuation, quality cleanup, regression re-verification, and a Stop-hook completion audit.

<Invocation_Contract>

• Treat every /omagy:ralph ... invocation as a Ralph runtime invocation, not as a plain natural-language request.
• The first tool action for a new Ralph task must be omagy ralph start or, when resuming, omagy ralph status --json followed by omagy ralph next --json. Do not run Read, ListDir, Search, Bash, command -v, build/test commands, target file reads, implementation work, or verification before Ralph runtime activation.
• Do not satisfy the user request only by running the requested file reads, edits, tests, or verification commands outside Ralph runtime state.
• If the user gives only natural task text, infer a compact task, desired_outcome, known_facts, constraints, unknowns, and touchpoints payload and run omagy ralph start --input '<json>' --json before executing the task.
• Before final response, record current-run evidence with omagy ralph record, complete with omagy ralph complete, and read back omagy state read --input '{"mode":"ralph"}' --json. </Invocation_Contract>

<Final_Response_Wording_Gate>

• For any request containing read-only, do not modify files, no source changes, 不修改, 不要修改, or equivalent, classify workspace cleanliness before the final answer:
  • verified_clean: a current-run cleanliness command succeeded and showed no changes.
  • not_verified: the cleanliness command failed, was unavailable, or the directory is not a Git repository.
• If cleanliness is not_verified, the final answer must include exactly this sentence and no other cleanliness/no-modification sentence: No source-writing tool call was observed; workspace cleanliness is not verified because <cleanliness command> failed or was unavailable.
• In not_verified state, do not translate, paraphrase, soften, or add Chinese equivalents. Forbidden final-answer phrases include: "可以确认没有执行任何写操作", "没有修改任何文件", "未修改源代码", "没有任何源文件被修改", "未改变任何工作区文件", "confirmed no modification", and "no files were changed".
• If a draft final answer contains one of those forbidden claims, rewrite the final answer before sending it. </Final_Response_Wording_Gate>

<Use_When>

• The user wants guaranteed completion instead of a best-effort pass.
• The task may need multiple iterations, retries, or continuation after a Stop hook.
• The work benefits from parallel specialist lanes and final architect sign-off.
• The user asks Ralph to execute the latest /omagy:plan handoff.
• The user asks for review-then-fix, such as /omagy:ralph code-review then fix all issues. </Use_When>

<Do_Not_Use_When>

• The user wants to explore or design before committing; use /omagy:plan or /omagy:deep-interview.
• The user wants a lightweight single-pass execution with evidence only; use /omagy:ultrawork.
• The user wants read-only review; use /omagy:code-review.
• The user wants durable multi-worker tmux coordination; use /omagy:team. </Do_Not_Use_When>

<Why_This_Exists> Complex agent tasks often fail by declaring partial work complete, skipping tests, ignoring review findings, or losing context across retries. Ralph exists to prevent that failure mode: every run starts from grounded context, continues until the task is done or blocked, verifies with current-run evidence, asks an architect lane to challenge the result, performs a cleanup/deslop pass, reruns verification, and only then records a passing completion audit. </Why_This_Exists>

<Execution_Policy>

• Start with outcome-first framing: target result, constraints, validation evidence, and stop condition.
• Do not begin implementation, delegation, or verification loops until pre-context intake has created or reused a .omagy/context/*.md snapshot and Ralph state records context_snapshot_path.
• Use Ultrawork's parallel execution discipline without activating a separate /omagy:ultrawork workflow state. Ralph owns persistence and completion.
• Fire independent agy subagent lanes in parallel when they are truly independent; do not wait sequentially for unrelated specialist work.
• Use agy's available long-task, Schedule, foreground command, or native subagent behavior according to the host surface. Do not claim that the Omagy CLI itself starts subagents.
• Treat .omagy/state/ralph-progress.json as Ralph's canonical progress ledger. Record meaningful iterations, blockers, verification results, architect verdicts, cleanup/deslop results, and visual feedback through omagy ralph record or omagy ralph record-visual.
• Deliver the full implementation. Do not reduce scope, delete tests to make checks pass, or call the task complete on "should work" evidence.
• Antigravity currently does not expose Codex Goal Mode tools such as get_goal or update_goal. Capture the host objective in Ralph state as host_objective / host_objective_source, and treat the completion audit as the authoritative objective closure contract.
• When launched after an approved plan, prefer omagy ralph --json or /omagy:ralph with no extra task text so the runtime resolves the latest visible /omagy:ralph "<task>" plan handoff and seeds approved_plan plus staffing fields. If there is no unique handoff, stop and return to /omagy:plan.
• Ask the user only for material ambiguity, destructive external action, credentials, production side effects, or preference-dependent branches. </Execution_Policy>

0. **Pre-context intake (required)**: - Assemble or reuse `.omagy/context/{task-slug}-{timestamp}.md` with UTC timestamp format `YYYYMMDDTHHMMSSZ`. - Minimum snapshot fields: - task statement - desired outcome - known facts/evidence - constraints - unknowns/open questions - likely codebase touchpoints - Start or resume Ralph through the Ralph runtime:

 ```bash
 omagy ralph start --input '{"task":"<task statement>","desired_outcome":"<desired outcome>","known_facts":["<evidence>"],"constraints":["<constraint>"],"unknowns":["<open question>"],"touchpoints":["<likely file/module>"]}' --json
 ```

• If ambiguity is high, gather read-only brownfield facts first. When needed, run /omagy:deep-interview --quick <task> before creating the snapshot.
• Do not continue until Ralph state includes context_snapshot_path.

1. Review progress:

   • Run omagy ralph status --json.
   • Run omagy ralph progress --json.
   • Read the Ralph context snapshot, canonical progress ledger, prior state, plan artifacts, reports, and any current TODOs before choosing the next action.

2. Continue from the real current state:

   • If Stop previously blocked, run omagy ralph next --json.
   • Pick up the incomplete step instead of restarting discovery or re-asking already answered questions.

3. Plan-approved execution gate:

   • If the user asks to execute the latest approved plan, PRD, or test spec, start with:

     omagy ralph --json
     

   • The runtime resolves the latest visible /omagy:ralph "<task>" handoff from the approved PRD, validates the matching test spec, and records approved_plan_path, approved_plan, approved_test_spec_paths, approved_deep_interview_spec_paths, available_agent_types, staffing_summary, and staffing_allocations in Ralph state.

   • For a specific plan or task, use omagy plan handoff --mode ralph --json first only to inspect/diagnose the handoff, then launch Ralph with the exact task text or no task text for the latest approved handoff.

   • If the handoff is missing, ambiguous, or lacks a matching test spec, stop and return to /omagy:plan instead of entering the Ralph loop.

4. Execute with Ultrawork discipline:

   • Split independent work into direct-tool lanes, background evidence lanes, and native agy subagent lanes.
   • Keep ownership clear: the parent agent coordinates, implementation lanes edit only their assigned scope, evidence lanes verify, and sign-off lanes review.
   • Start from Ralph state fields available_agent_types, staffing_summary, and staffing_allocations, then use only available Omagy agent roles such as implementer, explorer, verifier, quality-reviewer, security-reviewer, and architect.

5. Verify completion with fresh evidence:

   • Identify the commands, file reads, artifacts, or manual checks that prove the task is complete.

   • Run fresh verification in the current run and read the output.

   • Record the verification in Ralph's progress ledger:

     omagy ralph record --input '{"kind":"verification","status":"pass","summary":"<verification result>","command":"<command or check>","evidence":["<current-run evidence>"],"phase":"verifying"}' --json
     

   • Every final claim must map to evidence from the current run.

6. Architect verification (required):

   • Ralph's floor is always architect verification.

   • Use STANDARD-style scrutiny for ordinary changes.

   • Use THOROUGH-style scrutiny for broad, cross-module, security, persistence, data-loss, or architectural changes.

   • If the architect lane rejects or raises a concrete blocker, fix the issue and return to Step 5.

   • Record the architect result:

     omagy ralph record --input '{"kind":"architect","status":"pass","summary":"architect approved","evidence":["<architect verdict>"],"phase":"verifying"}' --json
     

7. Mandatory deslop / cleanup pass:

   • After architect approval, run a cleanup pass on Ralph-owned changed files.

   • In Omagy, use /omagy:ai-slop-cleaner for this pass.

   • Use the quality-reviewer lane only as an optional review of the cleanup result, not as the cleanup workflow itself.

   • Scope cleanup to changed files and artifacts owned by this Ralph run.

   • If the prompt contains --no-deslop, skip this step and state that the user explicitly disabled it.

   • Record the cleanup result:

     omagy ralph record --input '{"kind":"deslop","status":"pass","summary":"quality cleanup completed","evidence":["<cleanup evidence>"],"phase":"verifying"}' --json
     

8. Regression re-verification:

   • After cleanup, rerun the relevant tests, build, lint, or focused checks.
   • If cleanup introduced a regression, fix or roll back the cleanup and return to Step 7.

9. Complete through runtime audit:

   • Write a passing Ralph completion audit before final answer:

     omagy ralph complete --input '{"completion_audit":{"passed":true,"prompt_to_artifact_checklist":["<user request item -> artifact/evidence>"],"verification_evidence":["<command, test, or artifact>"]}}' --json
     

   • For large audits, write a repo-relative JSON audit artifact and reference it with completion_audit_path.

   • Do not place prompt_to_artifact_checklist or verification_evidence as bare top-level fields; they must live under completion_audit or in the referenced audit artifact.

   • Before final answer, read back the persisted Ralph state:

     omagy state read --input '{"mode":"ralph"}' --json
     

     Confirm the read-back state has completion_audit.passed === true, a non-empty completion_audit.prompt_to_artifact_checklist, non-empty completion_audit.verification_evidence, and no completion_audit_gate: "blocked" marker.

   • Without a passing audit, omagy hook Stop blocks completion even when the phase says complete or completed.

<Tool_Usage>

• Use omagy ralph start for context snapshot creation and runtime activation.
• Use omagy ralph status --json and omagy ralph next --json for continuation.
• Use omagy state write/read only for compact lifecycle state. Do not embed large markdown in shell JSON.
• Use omagy artifact read/write for PRDs, test specs, reports, audits, and other large artifacts.
• Use /omagy:code-review as read-only evidence. When Ralph owns a review-then-fix loop, feed findings into the next Ralph iteration rather than mutating plain code-review into an auto-fix command.
• Use native agy subagents directly for specialist lanes. Name the lane role and scope in the prompt.
• Use /omagy:cancel or omagy ralph cancel --json only when the user stops the run or a fundamental blocker requires handoff. </Tool_Usage>

<Evidence_Discipline>

• Every final claim must be backed by current-run evidence. Use the current host's actual evidence labels, such as Read(...), Bash(...), Agent(<role>), or omagy ralph progress --json; do not write stale Codex-specific labels such as view_file.
• If the user requests read-only, do not modify files, no source changes, or equivalent, attempt a cleanliness check such as git status --short or an explicit filesystem audit after the task. If the check fails or no reliable check is available, mark workspace cleanliness not verified.
• This cleanliness check is a Ralph completion gate for no-modification requests: run it and record its pass/fail/not-verified result before calling omagy ralph complete. Do not call omagy ralph complete first and backfill cleanliness evidence later.
• completion_audit.verification_evidence must include the cleanliness check command and result when the user requested no source modifications.
• A non-zero verification command exit is failed verification. Do not record it as status:"pass" and do not write completion_audit.passed:true. Failure observation can be reported as observed, but it is not passing verification evidence for Ralph completion.
• Do not write "no source files were modified", "no files were modified", "未修改源代码", or equivalent unless a cleanliness check succeeded in the current run.
• When cleanliness is not verified, use this exact style: "No source-writing tool call was observed; workspace cleanliness is not verified because <cleanliness command> failed or was unavailable."
• The final report and the completion audit checklist must not upgrade an unverified cleanliness result into a verified no-modification claim.
• Do not write "代码保持完全干净", "code remains clean", or equivalent unless the cleanliness check succeeded in the current run.
• If cleanliness is not verified, do not soften the disclaimer with phrases such as "可以确认", "严格遵循无源文件修改", "confirmed no modification", or equivalent. Also do not say "没有任何源文件被修改", "未改变任何工作区文件", "no files were changed", or equivalent. Say only that no source-writing tool call was observed and that workspace cleanliness is not verified.
• When cleanliness is not verified, completion_audit.prompt_to_artifact_checklist must use a neutral left-side label such as "Attempted workspace cleanliness verification" or "尝试验证工作区清洁度"; do not use "No source modification", "Do not modify files", "不修改源代码", or equivalent as the checklist requirement label. </Evidence_Discipline>

State Management

Ralph state is persisted through Omagy workflow/state runtime. Ralph progress is persisted separately in the canonical ledger at .omagy/state/ralph-progress.json or the active session-scoped state directory.

• On start:

  omagy ralph start --input '{"task":"<task>","desired_outcome":"<outcome>","known_facts":["<fact>"],"constraints":["<constraint>"],"unknowns":[],"touchpoints":["<path or module>"]}' --json
  

  The runtime initializes iteration:0 and max_iterations":50 for the active Ralph loop.

• On each iteration:

  omagy ralph record --input '{"kind":"iteration","status":"info","summary":"<what changed or what is next>","iteration":<current>,"phase":"executing","evidence":["<artifact or observation>"]}' --json
  

• On verification/fix transition:

  omagy ralph record --input '{"kind":"verification","status":"pass","summary":"<fresh verification result>","command":"<command>","phase":"verifying","evidence":["<evidence>"]}' --json
  

• On completion:

  omagy ralph complete --input '{"completion_audit":{"passed":true,"prompt_to_artifact_checklist":["<requirement -> evidence>"],"verification_evidence":["<fresh evidence>"]}}' --json
  omagy state read --input '{"mode":"ralph"}' --json
  

  The final answer is allowed only after the read-back state confirms the passing audit. If read-back shows completion_audit_gate: "blocked" or any missing audit evidence, return to the Ralph loop instead of answering final.

• On cancellation:

  omagy ralph cancel --json
  

If iteration >= max_iterations, Omagy marks Ralph with canonical lifecycle outcome blocked instead of looping forever.

Plan Handoff

When entered after /omagy:plan, Ralph must not guess which plan to execute. Use omagy ralph --json (or the slash-command equivalent with no extra task text) so the runtime resolves the latest approved /omagy:ralph launch hint, validates the matching PRD/test-spec pair, and creates the Ralph context from those artifacts. If the handoff cannot prove a matching PRD/test-spec pair, do not start implementation.

State should record:

{
  "approved_plan_path": "<prd path>",
  "approved_plan": {
    "source_path": "<prd path>",
    "test_spec_paths": ["<test spec path>"],
    "deep_interview_spec_paths": [],
    "command": "<launch hint>",
    "task": "<approved task>"
  },
  "available_agent_types": ["implementer", "verifier", "architect"],
  "staffing_summary": "implementer x1 (...); verifier x1 (...); architect x1 (...)",
  "staffing_allocations": []
}

Advanced PRD Mode

Use /omagy:ralph --prd "<task>" or omagy ralph --prd "<task>" when the run is driven by an explicit user-story PRD instead of a loose task prompt. Prompt-side /omagy:ralph activation alone is lighter-weight and does not imply PRD mode.

PRD mode has a startup gate:

• .omagy/prd.json must exist before Ralph starts.
• .omagy/prd.json must be a JSON object.
• If userStories exists, it must be an array.
• Any story marked passes: true, status: "passed", status: "complete", or status: "completed" must include current architect approval through architect_validation or architect_review.
• Approved architect evidence is approved: true, verdict: "approved", verdict: "approve", status: "approved", or status: "approve".

When PRD mode starts successfully, Omagy creates or reuses a canonical .omagy/plans/prd-<timestamp>-<slug>.md snapshot generated from .omagy/prd.json, records prd_mode: true, required_prd_json_path, canonical_prd_path, prd_story_count, prd_completed_story_count, and prd_startup_gate: "passed" in Ralph state, then continues through the normal Ralph loop.

Review-Then-Fix

Plain /omagy:code-review is read-only. Ralph is the write-capable owner of review-then-fix loops:

1. Run /omagy:code-review after implementation or against the requested scope.
2. Treat findings as next-iteration work.
3. Fix the findings.
4. Rerun verification and, when useful, rerun /omagy:code-review.
5. Complete only through Ralph's completion audit.

Scenario Examples

Correct continuation:

1. omagy ralph status --json shows Ralph active at iteration 3.
2. The context snapshot points to the approved PRD and test spec.
3. Continue the remaining fix instead of restarting planning.
4. Verify, architect-review, cleanup, reverify, then complete with audit.

Correct verification before completion:

1. npm test -> current run passes.
2. npm run build -> current run passes.
3. Architect lane returns approved.
4. /omagy:ai-slop-cleaner cleanup pass finds no blocking cleanup or changes are reverified.
5. omagy ralph complete ... records a passing audit.

Claiming completion with "looks good" or "should work" and no fresh evidence. Running a direct implementation from a plan prompt without first resolving `omagy plan handoff --mode ralph --json`.

<Escalation_And_Stop_Conditions>

• Stop and report when a fundamental blocker requires user input, such as missing credentials, unclear requirements that cannot be resolved by inspection, or unavailable external services.
• Stop when the user says stop, cancel, or abort; run the Ralph cancel command.
• Continue when Stop hook reports an active Ralph state.
• If architect verification rejects the result, fix and reverify.
• If the same concrete issue recurs across three or more iterations, report a potential fundamental blocker with evidence.
• Final handoff follows internal/contracts/explicit-terminal-stop-model.md and reports exactly one canonical lifecycle outcome: finished, blocked, failed, userinterlude, or askuserQuestion. </Escalation_And_Stop_Conditions>

<Final_Checklist>

• Context snapshot exists at .omagy/context/{task-slug}-{timestamp}.md.
• Ralph state records context_snapshot_path.
• All requirements from the original user task are met without scope reduction.
• Any approved plan PRD and matching test spec were read and followed.
• No pending or in-progress task remains.
• Fresh current-run verification evidence exists.
• Architect verification passed.
• /omagy:ai-slop-cleaner cleanup/deslop pass completed, unless --no-deslop was explicitly provided.
• Post-cleanup regression verification passed.
• omagy ralph complete recorded a passing completion_audit.
• omagy state read --input '{"mode":"ralph"}' --json read back the persisted audit and confirmed it is passing.
• No bare top-level prompt_to_artifact_checklist or verification_evidence fields were used as completion evidence.
• Stop hook no longer blocks Ralph completion. </Final_Checklist>

## `--no-deslop`

If the user includes --no-deslop, skip the cleanup/deslop pass and state that the user explicitly disabled it. Fresh verification and architect verification are still required.

Visual Tasks

Ralph accepts OMX-aligned visual reference flags on the CLI path:

omagy ralph -i refs/home.png -i refs/detail.png --images-dir screenshots "match the reference UI"

The runtime records these as visual_reference_images and visual_images_dir in Ralph state and adds them to .omagy/ralph/session-instructions.md.

If the task includes screenshots, visual references, or a target URL, Ralph must add a visual verification lane before final completion. Use available agy screenshot/browser/subagent capabilities and persist visual evidence in the completion audit. Do not claim a visual match without current-run visual evidence.

Background and Long Operations

Use the host's available execution surface:

• Quick status checks, file reads, and small commands can run in the foreground.
• Builds, installs, tests, servers, and long-running verification should use agy's long-task, Schedule, or subagent behavior when available.
• If the host does not expose a true background primitive for a command, run it foreground and report that evidence plainly.

Original task: {{PROMPT}}