/ouroboros:ralph
MCP-owned Ralph loop around background evolve_step jobs. "The boulder never stops."
Usage
ooo ralph --lineage-id <lineage_id>
/ouroboros:ralph --lineage-id <lineage_id>
# For a plain natural-language request, run `ooo interview` + `ooo seed` first,
# then call the MCP tool with a fresh lineage_id and the validated Seed YAML.
Trigger keywords: "ralph", "don't stop", "must complete", "until it works", "keep going"
How It Works
Ralph is owned by the ouroboros_ralph MCP tool. In non-plugin runtimes, the
tool starts one background Ralph job, runs repeated evolve_step generations
inside that job, and stops only when QA passes, convergence is reached, a
terminal evolution action occurs, cancellation is requested, or
max_generations is reached. In OpenCode plugin mode, the MCP tool returns a
delegated_to_plugin envelope with job_id=None; the bridge plugin dispatches
a child Task session that owns the loop instead of creating a local JobManager
job.
The client skill should not reimplement the loop. Deterministic frontmatter
dispatch is limited to the router's named --lineage-id option so raw trailing
text is never treated as lineage identity. Raw natural-language
ooo ralph "<request>" input must flow through the validated Seed path before
any mutating Ralph loop starts. Until a lineage id and optional Seed YAML are
prepared, ouroboros_ralph returns structured input guidance instead of
starting a job. Once the inputs are prepared, start the MCP-owned Ralph surface
once, then follow either the returned job tools path or the OpenCode Task widget
path.
Instructions
When the user invokes this skill:
Load MCP Tools (Required first)
The Ouroboros MCP tools are often registered as deferred tools that must be
explicitly loaded before use. Do this before preparing input or calling Ralph:
- Use the active runtime's tool-discovery capability to find and load the Ralph/job MCP tools:
tool discovery query: "+ouroboros ralph job"
- The loaded tools may be exposed under plugin-prefixed names such as
mcp__plugin_ouroboros_ouroboros__ouroboros_ralph. Use the actual tool
names returned by runtime tool discovery; the bare names below are the canonical MCP
tool names for documentation.
- Confirm that
ouroboros_ralph and the job tools (ouroboros_job_wait,
ouroboros_job_status, ouroboros_job_result, and
ouroboros_cancel_job) are callable. If the tools are unavailable, stop and
tell the user that Ralph requires the Ouroboros MCP runtime.
Ralph Flow
Prepare lineage input:
- If the user provides an existing
lineage_id and explicitly wants to
continue it, reuse that lineage_id and omit seed_content unless they
explicitly provide an updated Seed.
- If the user provides Seed YAML for a new Ralph run, use it as
seed_content and generate a fresh lineage_id for this run. Keep
lineage_id separate from Seed, interview, and session IDs so separate
Ralph runs over the same Seed do not collide.
- If the user provides only a plain natural-language request, do not treat
it as a direct
ooo ralph "<request>" command, do not freehand Seed YAML,
and do not pass raw text as seed_content. Route through the authoritative
Seed path first: ooo interview to capture requirements, then ooo seed /
ouroboros_generate_seed to produce validated Seed YAML with the normal
ambiguity gate. After Seed generation, call the MCP tool with a fresh
lineage_id and that validated Seed YAML as seed_content; do not use the
raw request text. If an interview/seed session already exists in context,
reuse that validated Seed output instead of regenerating it.
Start Ralph by calling ouroboros_ralph with:
lineage_id: existing lineage id for an explicit continuation, otherwise a
freshly generated stable id for this Ralph run, such as
ralph-<short-slug>-<uuid>; do not use a Seed/interview id by itself
seed_content: valid Seed YAML for generation 1 when starting a new lineage
execute: default true
parallel: default true
skip_qa: default false
project_dir: explicit target project directory when known
max_generations: default 10 unless the user requests a tighter bound
Handle the start response:
If response.meta.job_id is present, report it concisely and retain the
job cursor from response.meta.cursor:
[Ralph] Started background loop: <job_id>
Lineage: <lineage_id>
Live view: <dashboard_url, or `ouroboros tui open`>
A read-only observer will post meaningful progress, attention, and terminal
events here. This conversation remains available for other safe work.
If response.meta.job_observer is unavailable, recover it from the final
<!-- ouroboros-job-observer-v1 base64 ... --> content sentinel. Fail
closed unless the bounded payload passes canonical v1 validation and its
job identity matches the visible start receipt. Use that ID only as an
identity anchor, never to reconstruct tools or arguments. Reject validation
failure or any mismatch between structured and inline surfaces.
If the structured or recovered job_observer is present and the host
supports an independent child session, spawn exactly one read-only
observer and pass that contract unchanged. The observer exclusively owns
job wait/result calls and the cursor. The main session retains only user
conversation, explicit on-demand status, and cancellation when the user
requests it. The main session must not poll the same job while the observer
is active. It may refine requirements, perform read-only review, or work in
an unrelated isolated worktree; check active-worker conflicts before
writing to Ralph's workspace.
On Codex, call spawn_agent exactly once with task_name="run_observer";
wait is not a spawn, and do not claim an observer until a live child
ID/path is returned. Once acknowledged, keep the parent turn open with
wait_agent calls of at most 60 seconds while the observer is active. Child
send_message calls only enqueue mailbox events and cannot revive an ended
parent turn. Relay meaningful updates and wait again until terminal.
On OMP, submit exactly one native Task child named RunObserver, require
its live agent/job ID, and use the host wait/inbox relay until terminal.
User input may interrupt the wait; handle it and resume
waiting while observation remains active unless the user asks to stop live
observation or replaces the active request. Then end only the relay loop,
keep the durable job running, and offer next-turn or explicit-status catch-
up. If the observer child fails, is cancelled, or exits before a terminal
summary, use that same fallback instead of waiting indefinitely. This relay
loop must not poll the Ouroboros job or take cursor ownership. If spawn
fails, do not promise live proactive relays: the detached worker continues
after the stdio turn, and the main session catches up from durable events
on the next interaction or explicit status request. Keep the main turn open
in the fallback polling loop only when the user asked for live watching.
If response.meta.status == "delegated_to_plugin" and
response.meta.job_id is None, report that OpenCode plugin mode delegated
the loop to a child Task session. Do not call ouroboros_job_wait,
ouroboros_job_result, or ouroboros_cancel_job without a job id; follow
the host Task widget/session lifecycle instead.
Monitor non-plugin job progress in the polling owner when a job_id exists.
The delegated observer is the default owner. Use the main-session loop below
only when no independent child session exists and the user explicitly asked
for live watching; otherwise catch up on the next parent turn. Never run both
loops:
ouroboros_job_wait(job_id, cursor, timeout_seconds=120, stream="linked", wait_for="attention_or_ac_change") for long polling;
after every wait/status response, update cursor = response.meta.cursor
ouroboros_job_status(job_id) for a quick status check
ouroboros_job_result(job_id) when the job is terminal
ouroboros_cancel_job(job_id) if the user says stop/cancel
Observer events are concise: relay phase/progress changes in 1-2 lines,
surface attention_required immediately, present terminal as the final
result, distinguish Synapse queued from runtime-proven applied, surface
rejected/uncertain delivery immediately, and suppress unchanged heartbeats or
raw tool output. Render every relay in the user's current conversation
language; preserve raw event codes only when exact diagnostics help.
Interpret structured subtypes: report run configuration, total ACs and
dependency/parallel levels, first scheduled ACs, bounded Discover targets,
current model/harness changes, level transitions, and verified AC completion.
Say "currently running with" because later generations may escalate or switch
harnesses. Never forward raw commands or model reasoning.
When a new generation starts, do not just report the generation number —
lineage.generation.started carries an ac_focus block
(active_ac_indices, frozen_ac_indices, active_ac_descriptions,
reason). Report WHAT the generation is redoing, e.g.
"Gen 7: 2/5 AC 재작업 — 'CSV export writes summary.csv', 'CLI exits 0 on
--help' (3 AC는 이전 PASS 증거로 frozen)". When ac_focus is absent or
every AC is active with reason "initial/full generation", say the full AC
graph is being executed. Never quote verify commands or expected outputs —
descriptions only.
When the user asks a live AC a read-only question or provides additive intent,
reload +ouroboros session signal, call
ouroboros_session_signal_targets for the observed execution, and select the
semantically relevant AC without asking for internal IDs. Use
mode="inform" for assurance/questions and omit fallback_mode in that
mode. For implementation refinement use
contract_effect="additive", source="user", mode="redirect", and explicit
fallback_mode="after_turn" with the exact discovered guards. Shared goal/AC/
constraint/non-goal changes require an approved shared successor.
On non-plugin job termination, the polling owner fetches
ouroboros_job_result(job_id) and
summarize the final job result and next step:
- Success / convergence: summarize the final generation output, QA verdict,
and any
worktree_path / worktree_branch returned in job metadata. Do not
present ooo evaluate as an automatic next step for Ralph results: the
Ralph job contract preserves the evolution lineage_id, but it does not
reliably preserve a separate execution session_id for the evaluate
workflow. If a valid execution session_id is explicitly available from a
separate run result, keep it distinct from the Ralph lineage_id and follow
the ooo evaluate <session_id> contract; otherwise state that formal
evaluation needs a real execution session and should not be invoked from the
Ralph lineage id alone.
- Max generations / failure: summarize the stop reason and suggest
ooo unstuck, ooo interview, or a narrower Ralph retry
- Cancelled: confirm cancellation and preserve the job id for later inspection
On OpenCode plugin delegation, rely on the child Task result as the
terminal surface. Summarize the Task completion/error state and lineage id; do
not claim a local Ralph job can be polled or cancelled.
Active Conductor decision policy
For attention_required, use at most one short-lived read-only verifier. If the
host has no verifier primitive, surface the evidence and do not mutate.
Otherwise VERIFY → DECIDE from recommended_host_actions → LOG selected with
ouroboros_record_conductor_decision → ACT only a menu-listed registered tool →
LOG exactly one completed, failed, or declined outcome. Ralph may apply a
conductor directive only to the first and sole bounded successor generation
(max_generations=1), and only when it is deterministic and non-relaxing. Never
silently retry or weaken the approved shared contract.
These are English canonical host instructions. Render them naturally in the
user's conversation language.
Tool Mapping
| Skill action |
MCP tool |
| Start Ralph loop |
ouroboros_ralph |
| Wait for progress |
ouroboros_job_wait |
| Fetch final result |
ouroboros_job_result |
| Cancel loop |
ouroboros_cancel_job |
| Inspect current status |
ouroboros_job_status |
The Boulder Never Stops
This is the key phrase. Ralph does not give up:
- Each failure is data for the next attempt.
- Verification drives the loop.
- Only success, convergence, terminal failure, cancellation, or max-generation
limits stop it.
RFC #1392 State Breadcrumb Footer
Your final response MUST end with exactly one breadcrumb footer line:
◆ <current state> → next: <recommended action>
Derive <current state> from live session state via ouroboros_session_status when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear Step N of M footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the next: clause. The breadcrumb line must be the last line of the response.
1---
2name: ralph
3description: "MCP-owned Ralph loop around background evolve_step jobs"
4mcp_tool: ouroboros_ralph
5mcp_args:
6 lineage_id: "$lineage_id"
7metadata:
8 source: https://skillmd.com/skills/q00/ralph
9---
10
11# /ouroboros:ralph
12
13MCP-owned Ralph loop around background `evolve_step` jobs. "The boulder never stops."
14
15## Usage
16
17```
18ooo ralph --lineage-id <lineage_id>
19/ouroboros:ralph --lineage-id <lineage_id>
20
21# For a plain natural-language request, run `ooo interview` + `ooo seed` first,
22# then call the MCP tool with a fresh lineage_id and the validated Seed YAML.
23```
24
25**Trigger keywords:** "ralph", "don't stop", "must complete", "until it works", "keep going"
26
27## How It Works
28
29Ralph is owned by the `ouroboros_ralph` MCP tool. In non-plugin runtimes, the
30tool starts one background Ralph job, runs repeated `evolve_step` generations
31inside that job, and stops only when QA passes, convergence is reached, a
32terminal evolution action occurs, cancellation is requested, or
33`max_generations` is reached. In OpenCode plugin mode, the MCP tool returns a
34`delegated_to_plugin` envelope with `job_id=None`; the bridge plugin dispatches
35a child Task session that owns the loop instead of creating a local JobManager
36job.
37
38The client skill should not reimplement the loop. Deterministic frontmatter
39dispatch is limited to the router's named `--lineage-id` option so raw trailing
40text is never treated as lineage identity. Raw natural-language
41`ooo ralph "<request>"` input must flow through the validated Seed path before
42any mutating Ralph loop starts. Until a lineage id and optional Seed YAML are
43prepared, `ouroboros_ralph` returns structured input guidance instead of
44starting a job. Once the inputs are prepared, start the MCP-owned Ralph surface
45once, then follow either the returned job tools path or the OpenCode Task widget
46path.
47
48## Instructions
49
50When the user invokes this skill:
51
52### Load MCP Tools (Required first)
53
54The Ouroboros MCP tools are often registered as deferred tools that must be
55explicitly loaded before use. Do this before preparing input or calling Ralph:
56
571. Use the active runtime's tool-discovery capability to find and load the Ralph/job MCP tools:
58 ```
59 tool discovery query: "+ouroboros ralph job"
60 ```
612. The loaded tools may be exposed under plugin-prefixed names such as
62 `mcp__plugin_ouroboros_ouroboros__ouroboros_ralph`. Use the actual tool
63 names returned by runtime tool discovery; the bare names below are the canonical MCP
64 tool names for documentation.
653. Confirm that `ouroboros_ralph` and the job tools (`ouroboros_job_wait`,
66 `ouroboros_job_status`, `ouroboros_job_result`, and
67 `ouroboros_cancel_job`) are callable. If the tools are unavailable, stop and
68 tell the user that Ralph requires the Ouroboros MCP runtime.
69
70### Ralph Flow
71
721. **Prepare lineage input**:
73 - If the user provides an existing `lineage_id` and explicitly wants to
74 continue it, reuse that `lineage_id` and omit `seed_content` unless they
75 explicitly provide an updated Seed.
76 - If the user provides Seed YAML for a new Ralph run, use it as
77 `seed_content` and generate a fresh `lineage_id` for this run. Keep
78 `lineage_id` separate from Seed, interview, and session IDs so separate
79 Ralph runs over the same Seed do not collide.
80 - If the user provides only a plain natural-language request, do not treat
81 it as a direct `ooo ralph "<request>"` command, do not freehand Seed YAML,
82 and do not pass raw text as `seed_content`. Route through the authoritative
83 Seed path first: `ooo interview` to capture requirements, then `ooo seed` /
84 `ouroboros_generate_seed` to produce validated Seed YAML with the normal
85 ambiguity gate. After Seed generation, call the MCP tool with a fresh
86 `lineage_id` and that validated Seed YAML as `seed_content`; do not use the
87 raw request text. If an interview/seed session already exists in context,
88 reuse that validated Seed output instead of regenerating it.
89
902. **Start Ralph** by calling `ouroboros_ralph` with:
91 - `lineage_id`: existing lineage id for an explicit continuation, otherwise a
92 freshly generated stable id for this Ralph run, such as
93 `ralph-<short-slug>-<uuid>`; do not use a Seed/interview id by itself
94 - `seed_content`: valid Seed YAML for generation 1 when starting a new lineage
95 - `execute`: default `true`
96 - `parallel`: default `true`
97 - `skip_qa`: default `false`
98 - `project_dir`: explicit target project directory when known
99 - `max_generations`: default `10` unless the user requests a tighter bound
100
1013. **Handle the start response**:
102 - If `response.meta.job_id` is present, report it concisely and retain the
103 job cursor from `response.meta.cursor`:
104
105 ```
106 [Ralph] Started background loop: <job_id>
107 Lineage: <lineage_id>
108 Live view: <dashboard_url, or `ouroboros tui open`>
109
110 A read-only observer will post meaningful progress, attention, and terminal
111 events here. This conversation remains available for other safe work.
112 ```
113
114 - If `response.meta.job_observer` is unavailable, recover it from the final
115 `<!-- ouroboros-job-observer-v1 base64 ... -->` content sentinel. Fail
116 closed unless the bounded payload passes canonical v1 validation and its
117 job identity matches the visible start receipt. Use that ID only as an
118 identity anchor, never to reconstruct tools or arguments. Reject validation
119 failure or any mismatch between structured and inline surfaces.
120
121 - If the structured or recovered `job_observer` is present and the host
122 supports an independent child session, spawn exactly one read-only
123 observer and pass that contract unchanged. The observer exclusively owns
124 job wait/result calls and the cursor. The main session retains only user
125 conversation, explicit on-demand status, and cancellation when the user
126 requests it. The main session must not poll the same job while the observer
127 is active. It may refine requirements, perform read-only review, or work in
128 an unrelated isolated worktree; check active-worker conflicts before
129 writing to Ralph's workspace.
130 On Codex, call `spawn_agent` exactly once with `task_name="run_observer"`;
131 `wait` is not a spawn, and do not claim an observer until a live child
132 ID/path is returned. Once acknowledged, keep the parent turn open with
133 `wait_agent` calls of at most 60 seconds while the observer is active. Child
134 `send_message` calls only enqueue mailbox events and cannot revive an ended
135 parent turn. Relay meaningful updates and wait again until terminal.
136 On OMP, submit exactly one native Task child named `RunObserver`, require
137 its live agent/job ID, and use the host wait/inbox relay until terminal.
138 User input may interrupt the wait; handle it and resume
139 waiting while observation remains active unless the user asks to stop live
140 observation or replaces the active request. Then end only the relay loop,
141 keep the durable job running, and offer next-turn or explicit-status catch-
142 up. If the observer child fails, is cancelled, or exits before a terminal
143 summary, use that same fallback instead of waiting indefinitely. This relay
144 loop must not poll the Ouroboros job or take cursor ownership. If spawn
145 fails, do not promise live proactive relays: the detached worker continues
146 after the stdio turn, and the main session catches up from durable events
147 on the next interaction or explicit status request. Keep the main turn open
148 in the fallback polling loop only when the user asked for live watching.
149
150 - If `response.meta.status == "delegated_to_plugin"` and
151 `response.meta.job_id is None`, report that OpenCode plugin mode delegated
152 the loop to a child Task session. Do not call `ouroboros_job_wait`,
153 `ouroboros_job_result`, or `ouroboros_cancel_job` without a job id; follow
154 the host Task widget/session lifecycle instead.
155
1564. **Monitor non-plugin job progress in the polling owner** when a `job_id` exists.
157
158 The delegated observer is the default owner. Use the main-session loop below
159 only when no independent child session exists and the user explicitly asked
160 for live watching; otherwise catch up on the next parent turn. Never run both
161 loops:
162
163 - `ouroboros_job_wait(job_id, cursor, timeout_seconds=120, stream="linked", wait_for="attention_or_ac_change")` for long polling;
164 after every wait/status response, update `cursor = response.meta.cursor`
165 - `ouroboros_job_status(job_id)` for a quick status check
166 - `ouroboros_job_result(job_id)` when the job is terminal
167 - `ouroboros_cancel_job(job_id)` if the user says stop/cancel
168
169 Observer events are concise: relay phase/progress changes in 1-2 lines,
170 surface `attention_required` immediately, present `terminal` as the final
171 result, distinguish Synapse `queued` from runtime-proven `applied`, surface
172 rejected/uncertain delivery immediately, and suppress unchanged heartbeats or
173 raw tool output. Render every relay in the user's current conversation
174 language; preserve raw event codes only when exact diagnostics help.
175 Interpret structured subtypes: report run configuration, total ACs and
176 dependency/parallel levels, first scheduled ACs, bounded Discover targets,
177 current model/harness changes, level transitions, and verified AC completion.
178 Say "currently running with" because later generations may escalate or switch
179 harnesses. Never forward raw commands or model reasoning.
180
181 When a new generation starts, do not just report the generation number —
182 `lineage.generation.started` carries an `ac_focus` block
183 (`active_ac_indices`, `frozen_ac_indices`, `active_ac_descriptions`,
184 `reason`). Report WHAT the generation is redoing, e.g.
185 "Gen 7: 2/5 AC 재작업 — 'CSV export writes summary.csv', 'CLI exits 0 on
186 --help' (3 AC는 이전 PASS 증거로 frozen)". When `ac_focus` is absent or
187 every AC is active with reason "initial/full generation", say the full AC
188 graph is being executed. Never quote verify commands or expected outputs —
189 descriptions only.
190
191 When the user asks a live AC a read-only question or provides additive intent,
192 reload `+ouroboros session signal`, call
193 `ouroboros_session_signal_targets` for the observed execution, and select the
194 semantically relevant AC without asking for internal IDs. Use
195 `mode="inform"` for assurance/questions and omit `fallback_mode` in that
196 mode. For implementation refinement use
197 `contract_effect="additive"`, `source="user"`, `mode="redirect"`, and explicit
198 `fallback_mode="after_turn"` with the exact discovered guards. Shared goal/AC/
199 constraint/non-goal changes require an approved shared successor.
200
2015. **On non-plugin job termination**, the polling owner fetches
202 `ouroboros_job_result(job_id)` and
203 summarize the final job result and next step:
204 - Success / convergence: summarize the final generation output, QA verdict,
205 and any `worktree_path` / `worktree_branch` returned in job metadata. Do not
206 present `ooo evaluate` as an automatic next step for Ralph results: the
207 Ralph job contract preserves the evolution `lineage_id`, but it does not
208 reliably preserve a separate execution `session_id` for the evaluate
209 workflow. If a valid execution `session_id` is explicitly available from a
210 separate run result, keep it distinct from the Ralph `lineage_id` and follow
211 the `ooo evaluate <session_id>` contract; otherwise state that formal
212 evaluation needs a real execution session and should not be invoked from the
213 Ralph lineage id alone.
214 - Max generations / failure: summarize the stop reason and suggest
215 `ooo unstuck`, `ooo interview`, or a narrower Ralph retry
216 - Cancelled: confirm cancellation and preserve the job id for later inspection
217
2186. **On OpenCode plugin delegation**, rely on the child Task result as the
219 terminal surface. Summarize the Task completion/error state and lineage id; do
220 not claim a local Ralph job can be polled or cancelled.
221
222### Active Conductor decision policy
223
224For `attention_required`, use at most one short-lived read-only verifier. If the
225host has no verifier primitive, surface the evidence and do not mutate.
226Otherwise VERIFY → DECIDE from `recommended_host_actions` → LOG `selected` with
227`ouroboros_record_conductor_decision` → ACT only a menu-listed registered tool →
228LOG exactly one `completed`, `failed`, or `declined` outcome. Ralph may apply a
229conductor directive only to the first and sole bounded successor generation
230(`max_generations=1`), and only when it is deterministic and non-relaxing. Never
231silently retry or weaken the approved shared contract.
232
233These are English canonical host instructions. Render them naturally in the
234user's conversation language.
235
236## Tool Mapping
237
238| Skill action | MCP tool |
239| --- | --- |
240| Start Ralph loop | `ouroboros_ralph` |
241| Wait for progress | `ouroboros_job_wait` |
242| Fetch final result | `ouroboros_job_result` |
243| Cancel loop | `ouroboros_cancel_job` |
244| Inspect current status | `ouroboros_job_status` |
245
246## The Boulder Never Stops
247
248This is the key phrase. Ralph does not give up:
249
250- Each failure is data for the next attempt.
251- Verification drives the loop.
252- Only success, convergence, terminal failure, cancellation, or max-generation
253 limits stop it.
254
255## RFC #1392 State Breadcrumb Footer
256
257Your final response MUST end with exactly one breadcrumb footer line:
258
259```
260◆ <current state> → next: <recommended action>
261```
262
263Derive `<current state>` from live session state via `ouroboros_session_status` when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear `Step N of M` footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the `next:` clause. The breadcrumb line must be the last line of the response.