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

# Ralph

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

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

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

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

     ```bash
     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:

     ```bash
     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:

     ```bash
     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:

     ```bash
     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:

     ```bash
     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:

     ```bash
     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`.
</Steps>

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

  ```bash
  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**:

  ```bash
  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**:

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

- **On completion**:

  ```bash
  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**:

  ```bash
  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:

```json
{
  "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

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

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

<Bad>
Claiming completion with "looks good" or "should work" and no fresh evidence.
</Bad>

<Bad>
Running a direct implementation from a plan prompt without first resolving
`omagy plan handoff --mode ralph --json`.
</Bad>

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

<Advanced>
## `--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:

```bash
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.
</Advanced>

Original task:
{{PROMPT}}