ralph Skill | Agent Skills

Response language follows language setting in .agents/oma-config.yaml if configured.
Follow .agents/skills/_shared/core/execution-policy.md for authorization, clarification, verification, and completion. Execute required steps on the selected path in dependency order; apply documented branch and skip conditions.
Follow .agents/skills/_shared/core/code-intelligence.md: discover configured tools and use native scoped search if unavailable or timed out. Do not install or track repositories automatically.
Persist coordination artifacts through .agents/skills/_shared/runtime/memory-protocol.md; file state is independent of code-intelligence MCP tools.
This workflow does NOT stop until all completion criteria pass or safeguards trigger.
Follow the context-loading guide. Read .agents/skills/_shared/core/context-loading.md and load only task-relevant resources.

Vendor Detection

Before starting, determine your runtime environment by following .agents/skills/_shared/core/vendor-detection.md. The detected vendor determines how ultrawork spawns agents internally.

Phase 0: INIT (DO NOT SKIP)

Step 0.1: Load Prerequisites

Read .agents/skills/_shared/core/context-loading.md for resource loading strategy.
Read .agents/skills/_shared/runtime/memory-protocol.md for memory protocol.
Read .agents/workflows/ralph/resources/judge-protocol.md for JUDGE rules.
Read .agents/skills/_shared/runtime/event-spec.md for the L1 event protocol and oma state emit (used by the EXEC checkpoint in Step 1.2).

Step 0.2: Define Completion Criteria

Analyze the user's request and define verifiable completion criteria. Each criterion MUST have:

criteria:
  - id: C{N}
    description: "<what to achieve>"
    verification: "<how to verify — test result, non-emitting check, file existence, command output>"
    status: PENDING
    fail_count: 0                   # updated once per JUDGE by judge-protocol.md
    previous_status: null           # last non-null status from prior iteration
    regressed_at_iteration: null    # iteration number when PASS → FAIL transition was detected
    affected_paths: []              # optional glob list — only set when verification takes >30s
                                    # used by judge-protocol's cache rules; see judge-protocol.md § "Caching for Heavy Verification"

Rules:

Ground every criterion in a mechanically verifiable check (test assertion, non-emitting type check, exit code, file existence). Include a build/compile/package command only when the user explicitly requested a build, per the shared execution policy.
Lock criteria directly into session memory and output them in the execution trace; proceed immediately to Step 0.3 and Phase 1 without halting for interactive confirmation (Ralph is an autonomous persistent execution loop)

Step 0.3: Initialize Session

Generate a sessionId ({YYYYMMDD-HHmmss} timestamp). All ralph memory files for this run are session-scoped with this suffix, per memory-protocol session-scoped naming. Never write to an unsuffixed session-ralph.md — consecutive ralph runs must not overwrite each other.
Set max_iterations: 5 (default safeguard)
Set current_iteration: 0
Load prior-session context (cross-session memory):
1. Use the memory list tool to find previous session-ralph-*.md files. If any exist, read the most recent one and extract: final criteria statuses, BLOCKED items with their failure evidences, and any safeguard trigger.
2. If lessons-{sessionId}.md exists in the memory base path, read it.
3. If any current criterion overlaps a previously BLOCKED item, carry the prior failure evidence as context for EXEC and retry unless explicitly excluded by the user request.
Record session start using memory write tool:
- Create session-ralph-{sessionId}.md in the memory base path
- Include: session start time, user request summary, completion criteria, max_iterations, and prior-session findings loaded in step 4 (or none)

Phase 1: EXEC

Step 1.1: Prepare Ultrawork Input

Compose the ultrawork input based on current iteration:

Iteration 1: Full user request with all PENDING criteria
Iteration 2+: REMAINING (FAIL + REGRESSED) criteria from previous JUDGE result, with:
- Previous JUDGE results as context (what failed and why)
- Suggested actions from JUDGE
- Already-PASSED criteria excluded from implementation scope (do not re-implement), but they remain in JUDGE scope (will be re-verified to detect regressions)

Step 1.2: Execute Ultrawork

EXEC-entry checkpoint (MANDATORY — emit before delegating). This records, in the auditable L1 event log, that this iteration delegates to the full ultrawork workflow. A run without this event is a non-compliant run.

oma state emit "decision.made" '{"subject":"ralph.exec-delegated","decision":"Delegate this iteration to the full ultrawork 5-phase workflow.","rationale":"Ralph EXEC must run ultrawork in full; abridging, substituting, or skipping phases for cost/stability/time reasons is forbidden without explicit user approval."}'
oma state verify --workflow ralph --checkpoint exec-delegated

Delegate to the ultrawork workflow:

Read and follow .agents/workflows/ultrawork.md step by step.
Pass the prepared input as the task description, and pass this ralph run's sessionId as ultrawork's session id. Ultrawork must keep plan task IDs, claims, receipts, and run-scoped reports under that identity so Step 1.3 can match the evidence.
Ultrawork handles all vendor-specific agent spawning internally.
Wait for ultrawork to complete all 5 phases (PLAN, IMPL, VERIFY, REFINE, SHIP).
Do NOT abridge ultrawork. If you believe the environment (subagent instability, cost, time) warrants reducing fan-out or collapsing phases, STOP and ask the user first. Single-judgment substitution of ultrawork's structure is forbidden — see the Anti-Circumvention gate in Step 1.3.

Step 1.3: Verify EXEC Artifacts (Anti-Circumvention Gate)

Prose instructions ("run ultrawork in full") are advisory and can be rationalized away. This gate verifies the work mechanically — by its artifacts, not by your own narration. Ultrawork's 5 phases each leave a durable trace; a single-agent shortcut cannot produce them without actually doing the work.

Run the deterministic verifier from the repo root:

oma ralph verify --json --session-id {sessionId} --newer-than {iteration_start_iso}

--session scopes the plan artifact to this iteration's session id; --newer-than (this iteration's EXEC start time, ISO-8601) excludes stale artifacts from earlier iterations. Supply both for repeated iterations; missing identity cannot prove an iteration.
The command checks the artifact table below, prints a structured result (ok, checks, missing, remediation), and exits non-zero on failure. On failure it also appends a gate.failed L1 event automatically.
The JSON verdict IS the gate result. Do NOT substitute your own narration for it, and do NOT proceed on a non-zero exit.
If the CLI is unavailable, report the gate as unverified. File existence cannot substitute for execution evidence. Resolve {memBase} from memoryConfig.basePath (default .agents/state/memories).
Follow .agents/skills/_shared/runtime/result-contract.md: QA and REFINE receipts must match this session and a task ID in the plan, include successful checks for the current working tree, and bind the report, plan and phase log by content hash.

| # | Artifact | Proves phase ran | |---|----------|------------------| | A1 | {memBase}/session-ultrawork.md with this iteration's phase-completion records | PLAN + gate progression | | A2 | .agents/results/plan-{sessionId}.json | PLAN produced a real task breakdown | | A3 | {memBase}/result-qa*.md or .agents/results/result-qa*.md (VERIFY) | a distinct QA agent ran — absent if IMPL was the only spawn. CLI fallback writes result-qa-agent* to {memBase}; Claude-native qa-reviewer writes result-qa* to .agents/results/ | | A4 | {memBase}/result-refactor*.md or .agents/results/result-refactor*.md (REFINE) | a distinct Refactor agent ran — same naming split (refactor-engineer on the native path). Legacy result-debug* from older runs is also accepted |

Decision:

ok: true (exit 0) → the required local execution evidence is current. Proceed to Step 1.4.
ok: false (exit 1, missing non-empty) → treat EXEC as NOT performed (the iteration was abridged to implementation-only, regardless of what the EXEC narration claims). Do NOT advance to JUDGE as if work completed. Instead:
1. Record the violation in session-ralph-{sessionId}.md: exec-circumvention detected at iteration {N}: missing {artifact}.
2. Emit the audit event:
```
oma state emit "decision.made" '{"subject":"ralph.exec-circumvention","decision":"EXEC artifacts incomplete — ultrawork did not run in full.","rationale":"Required VERIFY/REFINE agent result files are absent; the iteration was abridged."}'
```
3. Report the missing or stale evidence, repair the authorized work, and retry the gate. Apply .agents/skills/_shared/core/execution-policy.md; ask only when repair needs a material missing decision or new authorization. Do NOT retry with the same missing evidence.

REFINE skip exception: ultrawork permits skipping REFINE for trivial tasks (< 50 lines, see ultrawork REFINE_GATE skip conditions). If REFINE was legitimately skipped, A4 may be absent — but session-ultrawork.md MUST record the documented skip reason. "No A4 and no recorded skip reason" is a circumvention, not a skip. oma ralph verify implements this rule: a recorded skip reason reports A4 as skip-recorded (passing), an unrecorded absence reports missing (failing).

Step 1.4: Record EXEC Completion

Increment current_iteration
Use memory edit tool to record EXEC completion for iteration {current_iteration} in session-ralph-{sessionId}.md

Phase 2: JUDGE

Step 2.1: Independent Verification (Spawned Judge)

The judge is a separate agent with fresh context — not a role the orchestrator plays. The orchestrator that drove EXEC shares context with the implementation and cannot self-judge without rationalization risk. Spawning is the default; inline judging is a recorded exception.

Compose the judge brief. It contains ONLY:
- The current criteria snapshot: id, description, verification method, status, previous_status, fail_count, regressed_at_iteration, affected_paths, and prior verification evidence
- The verification cache records from session-ralph-{sessionId}.md (if any)
- The required output format (Step 2.2) and a pointer to .agents/workflows/ralph/resources/judge-protocol.md
- Do NOT include EXEC narration, implementation summaries, or any claim about what was fixed. The judge verifies what IS, not what was intended.
Spawn the judge via Per-Agent Dispatch (see Vendor Detection):
- If Claude Code and target vendor is Claude: Agent(subagent_type="qa-reviewer", prompt="<judge brief>. Follow .agents/workflows/ralph/resources/judge-protocol.md. Follow the protocol's verification and cache rules and write the JUDGE result to memory as result-judge-{sessionId}-iter{N}.md.")
- Otherwise, or when native dispatch is unavailable: oma agent spawn qa-agent judge-prompt.md {sessionId} --task-id {judge_task.id} -w {workspace}
- Verification is mechanical (run command, check exit code/output) — a lower-cost model tier is acceptable where the runtime supports per-agent model selection.
Wait for the judge claim and result-qa-{judge_task.id}-{runId}-{sessionId}.md, then read it as the JUDGE result.

Inline fallback (exception): only if subagent spawning is unavailable in the current runtime, perform the verification inline. Record judge-inline-fallback at iteration {N} in session-ralph-{sessionId}.md and emit:

oma state emit "decision.made" '{"subject":"ralph.judge-inline-fallback","decision":"Run JUDGE inline in the orchestrator context.","rationale":"Subagent spawning unavailable in this runtime; judge independence is downgraded for this iteration."}'

Apply Verification Execution Order, including prior PASS criteria, and its heavy-verification cache rules. The judge uses the shared execution policy when selecting or executing checks.

Step 2.2: Produce JUDGE Result

The judge writes JUDGE Result Format, the updated criterion state, and Remaining Items when required. Status transitions and verdict computation are defined only in that protocol.

Step 2.3: Apply JUDGE Result

Validate the returned evidence and state against Criterion State Transitions, then persist the result in session memory. The judge applies the transition once; the coordinator must not increment counters or apply it again. If the result is inconsistent, return it to the judge for correction against the original snapshot.

Phase 2 → Decision Gate

Evaluate the JUDGE result:

→ Terminal verdict (COMPLETED or PARTIAL)

If the judge returns COMPLETED or PARTIAL:

PARTIAL: report blocked items and their evidence as unresolved
COMPLETED: report full completion
Use memory edit tool to record final results in session-ralph-{sessionId}.md

Output completion summary:

## Ralph Complete — Iteration {N}/{max}

PASSED: C1, C2, ...
BLOCKED: C3 (if any)

Total iterations: {N}

Workflow ends.

→ REPLAN (Any criterion is FAIL or REGRESSED)

If any criterion has status FAIL or REGRESSED, proceed to Phase 3.

→ SAFEGUARD (max_iterations reached)

If current_iteration >= max_iterations:

Force stop regardless of FAIL criteria

Report partial completion:

## Ralph Safeguard — Max Iterations Reached ({max})

PASSED: C1, ...
FAILED: C2, ... (still unresolved)
BLOCKED: C3, ... (if any)

Recommendation: Review FAILED criteria manually or increase max_iterations.

Use memory edit tool to record safeguard trigger in session-ralph-{sessionId}.md
Workflow ends.

Phase 3: REPLAN

Step 3.1: Extract Remaining Work

From the JUDGE result, collect criteria with status FAIL or REGRESSED. Treat the two classes separately:

FAIL (first-time or persistent failures): list each with its reason and suggested_action
REGRESSED (previously PASS, now FAIL): list each with previous-pass iteration, the inter-iteration diff that likely caused the regression, and a regression-specific suggested_action.
Include previous iteration's JUDGE evidence as context
Explicitly state which criteria are PASS (do not re-implement, but do not exclude from next JUDGE either)
Explicitly state which criteria are BLOCKED (do not retry)

Step 3.2: Narrow Scope

Compose a focused task description containing the remaining work, separating regressions from first-fail items so ultrawork's reasoning differs:

## Ralph Iteration {N+1} — Remaining Work

### Already Complete (DO NOT re-implement; will be re-verified by JUDGE)
- C1: <description> PASS

### Blocked (DO NOT retry)
- C3: <description> BLOCKED (failed 3x)

### Regressed (was passing — diagnose what broke it; minimal fix that preserves recent changes)
- C4: <description>
  - Last passed at: iteration {N}
  - Failed at: iteration {current}
  - Files changed since last pass: <list of modified paths>
  - Failure evidence: <evidence>
  - Suggested action: diff-aware diagnosis — identify which change in the listed files broke C4, fix that specifically without reverting the criterion that change was made for

### To Fix (first-time or persistent failures)
- C2: <description>
  - Previous failure: <evidence>
  - Suggested action: <action>

Why separate Regressed from To Fix: ultrawork prompts that frame work as "fix from scratch" vs "diagnose a regression" produce different reasoning paths. Regressed items should trigger diff-based investigation, not greenfield re-implementation.

Step 3.3: Loop Back

Use memory edit tool to record REPLAN in session-ralph-{sessionId}.md
Return to Phase 1: EXEC with the narrowed scope

Summary

Phase 0: INIT → Define criteria, load prior sessions, initialize session
    ↓
Phase 1: EXEC → Run ultrawork (full or narrowed scope)
    ↓
Phase 2: JUDGE → Spawned fresh-context judge verifies each criterion
    ↓
Decision: COMPLETED? → End
          SAFEGUARD? → Force end
          FAIL? → Phase 3
    ↓
Phase 3: REPLAN → Extract remaining, narrow scope
    ↓
    └──→ Phase 1 (loop)

| Phase | Purpose | Key Action | |---------|----------------------------|-----------------------------------| | INIT | Define success criteria | Verifiable criteria + prior-session load + session init | | EXEC | Implementation | Delegate to ultrawork | | JUDGE | Independent verification | Spawned judge; evidence-based pass/fail per criterion | | REPLAN | Scope narrowing | Extract FAIL + REGRESSED items, separated by class |

Agent Skills: ralph

Install this agent skill to your local

Skill Files