/ouroboros:ouroboros-run
Execute a Seed specification through the Ouroboros workflow engine.
Usage
/ouroboros:ouroboros-run [seed_file_or_content]
Trigger keywords: "ouroboros run", "execute seed"
How It Works
- Input: Provide seed YAML content directly or a path to a
.yaml file
- Validation: Seed is parsed and validated (goal, constraints, acceptance criteria, ontology)
- Execution: The orchestrator runs the workflow with PAL routing
- Progress: Real-time progress updates via session tracking
- Result: Execution summary with pass/fail status
- Convergence: completed runs enqueue formal evaluation by default. An
explicit rejection continues through a bounded Ralph loop until approved or
the configured evolution budget/stop condition is reached.
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. You MUST perform this step before proceeding.
- Use the active runtime's tool-discovery capability to find and load the execution MCP tools:
tool discovery query: "+ouroboros execute"
- The tools will typically be named with prefix
mcp__plugin_ouroboros_ouroboros__ (e.g., ouroboros_execute_seed, ouroboros_session_status). After runtime tool discovery returns, the tools become callable.
- If the tools are callable — already exposed, or loaded by discovery — proceed with the steps below. An empty discovery result for already-exposed tools is expected, not a failure. Skip to the Fallback section only if they are genuinely absent (no Ouroboros MCP server).
IMPORTANT: Do NOT skip this step. Do NOT assume MCP tools are unavailable just because they don't appear in your immediate tool list. They are almost always available as deferred tools that need to be loaded first.
CRITICAL — deferred-schema guard (prevents "Invalid tool parameters"):
This skill makes execution MCP calls across multiple turns, and each turn runs
in a fresh tool context. A deferred tool's schema loaded on one turn is NOT
guaranteed to still be loaded on the next. If you call any execution ouroboros_*
MCP tool while its schema is not loaded in the current turn, the runtime
rejects the call with "Invalid tool parameters" before it reaches the server.
Therefore: immediately before EVERY execution MCP call in this skill, re-run
tool discovery query: "+ouroboros execute" to reload the execution tool family,
including ouroboros_start_execute_seed, ouroboros_job_wait,
ouroboros_ac_tree_hud, and ouroboros_job_result (idempotent — a no-op when
already loaded). If the load returns no matching tool (and the tool is not already callable — an empty load for an already-exposed tool is an expected no-op, not absence), switch to the documented
fallback instead of retrying the failing call.
Execution Steps
Detect git workflow (before any code changes):
- Read the project's
CLAUDE.md for git workflow preferences
- If PR-based workflow detected and currently on
main/master:
- Create a feature branch:
ooo/run/<session_id>
- All code changes go to this branch
- If no preference: use current branch (backward compatible)
Check if the user provided seed content or a file path:
- If a file path: Read the file with the Read tool
- If inline YAML: Use directly
- If neither: Check conversation history for a recently generated seed
Before a fresh start, when the user has not already chosen an efficiency
policy, first check the persistent default: when execution.default_policy
in ~/.ouroboros/config.yaml is efficient or quality_first, do not ask —
omit both arguments and the server applies the configured default (the start
handoff still reports the resolved policy). When it is ask or unset, ask
in outcome language:
- Efficient execution — start parallel/decomposed work economically and
strengthen the route only when recovery requires it. Send
efficiency_mode="adaptive" and frugality_assurance="observe".
- Quality-first execution — keep child work at the parent starting tier.
Send
efficiency_mode="quality_first" and frugality_assurance="off".
frugality_assurance="strict" is a separate explicit opt-in because it may
spend extra work on proof. Never enable it merely because efficient execution
was chosen. Do not ask again on resume; the server restores the persisted
policy and rejects an attempted resume-time change.
Start background execution with ouroboros_start_execute_seed:
Tool: ouroboros_start_execute_seed
Arguments:
seed_content: <the seed YAML>
efficiency_mode: <adaptive or quality_first>
frugality_assurance: <observe, off, or explicit strict>
max_iterations: 10 (or as specified by user)
Omit model_tier by default so the runtime selects automatically. Include
model_tier: <user choice> only when the user explicitly requested a tier.
This returns immediately with a job_id, session_id, and execution_id.
If resuming an existing session, include session_id:
Tool: ouroboros_start_execute_seed
Arguments:
seed_content: <the seed YAML>
session_id: <existing session ID>
Recommended monitoring stance: delegate observation to one child session.
TUI surfacing at job start (RFC #1392):
After job_id, session_id, and execution_id are returned, surface a live
view once without delaying execution or observer delegation:
If response.meta.dashboard_url exists, show it as the primary live view.
If execution.tui_autolaunch: true (or legacy top-level
tui_autolaunch: true) is present in the loaded Ouroboros config, run
ouroboros tui open unconditionally and mention the dashboard in one
short line.
Otherwise mention once that the TUI can be opened in a new terminal with
ouroboros tui open. Offer to open it, but do not block the run waiting for
an answer. Remember the answer for this session and do not repeat the offer.
If the user accepts, run ouroboros tui open.
If ouroboros tui open reports a manual command because the environment
is headless, SSH, or unsupported, relay that command once and continue.
The dashboard is an external observer. It does not change which chat
session owns MCP polling.
After IDs are returned, print only this short handoff:
Execution started in background.
Job ID: <job_id>
Session ID: <session_id>
Execution ID: <execution_id>
Live view: <dashboard_url, or `ouroboros tui open`>
Runtime/harness: <response.meta.runtime_backend>
LLM backend: <response.meta.llm_backend>
Efficiency: <response.meta.efficiency_mode>
Frugality assurance: <response.meta.frugality_assurance>
Observation: <confirmed read-only child observer, or durable catch-up mode>.
With a confirmed observer, meaningful progress, attention, and completion
events will be posted here. Without one, the run still survives this turn
and I will catch up from durable events on your next message or status request.
This conversation stays available while the run continues.
We can refine requirements, inspect or review code, or work on an unrelated
task in an isolated worktree. I will check for active-worker conflicts before
editing this run's workspace.
For full details later: `ouroboros_ac_tree_hud(session_id=<session_id>)`
Text-only host compatibility (OMP and similar bridges):
If response.meta.job_observer is unavailable, inspect the response content
for the final sentinel block:
<!-- ouroboros-job-observer-v1 base64
<payload>
-->
Base64-decode <payload>, then fail closed unless it passes the canonical v1
validation implemented by extract_job_observer_inline_handoff: exactly one
bounded terminal sentinel; fixed protocol, role, ownership, wait/result tools,
restrictions, and follow-result keys; internally consistent IDs; and a
job_id matching the visible start receipt. Use visible Job/Session/Execution
IDs only as identity anchors, never to reconstruct the nested contract. If
structured and inline surfaces differ or validation fails, do not spawn an
observer; report a transport-integrity failure.
When a structured or recovered job_observer is present and the host has an
independent child/subagent session primitive, spawn exactly one observer
session and pass that object unchanged. Codex uses spawn_agent, OMP uses
one native Task child, and Claude Code uses one Task/Agent child. The observer must:
On Codex, call the native spawn_agent primitive exactly once with
task_name="run_observer" and include the structured or recovered
job_observer unchanged in the child message. A wait call is not a spawn.
Require the spawn result to return a live child ID/path before saying an
observer is connected or before ending the start turn.
On OMP, submit exactly one Task item named RunObserver with the recovered
or structured contract unchanged, require the returned live agent/job ID,
and use the host wait/inbox relay until the observer returns terminal.
A job-status poll in the parent is not an observer spawn.
remain read-only: no repository edits, execution control, or worker fan-out;
own the job cursor exclusively and reload deferred MCP schemas immediately
before each observer tool call;
call the declared wait.tool with the declared arguments, update its local
cursor from response meta, and repeat until terminal;
call the declared result.tool after terminal status;
follow any job IDs named by follow_result_job_keys, including chained
formal evaluation, before returning one compact final summary;
send sparse progress notices only when the host supports child-to-parent
messages and the state meaningfully changes.
The main session must not poll the same job while the observer owns it. It may
continue the user conversation, refine requirements, perform read-only
inspection/review, handle explicit status/control requests, or work on an
unrelated task in an isolated worktree. Before writing to the active run's
workspace, check for overlap with worker files or isolate the work. If
job_id is absent because plugin mode already delegated the whole execution,
follow that plugin child lifecycle instead.
On Codex, a confirmed observer also requires a parent relay loop. After
spawn_agent returns a live child ID/path, keep the parent turn open with
wait_agent calls of at most 60 seconds. A child send_message only queues a
mailbox event and cannot wake a parent turn that has already ended. Relay
meaningful observer updates, then wait again until the child returns its
terminal summary. User input may interrupt the wait; handle it and resume the
relay loop while the observer 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 wait loop must never call Ouroboros job tools or compete for the
observer's cursor.
Handle observer messages as events, not as a transcript:
phase_changed / progress_advanced: relay at most 1-2 concise lines.
Interpret the structured subtype, not raw logs:
run_configuration: state the current runtime/harness, starting model or
tier when known, efficiency mode, and frugality assurance. If the exact
model is not known yet, say it will be reported by the first routing event.
execution_plan: state total ACs, total dependency/parallel levels,
whether work can run in parallel, and the first scheduled AC summaries.
discovery_summary: say which bounded targets the AC is examining and
the purpose; never expose search queries, raw commands, or reasoning.
level_started / level_completed: say which parallel level is active
or finished and the meaningful success/failure counts.
ac_routing / harness_changed: say "currently running with" and report
only initial routing or a real model/tier/harness change.
ac_verified: report the completed AC and its compact assurance evidence.
attention_required: surface the blocker or pending decision immediately
and ask the user only when human judgment is required.
terminal: fetch/present the final result and any chained evaluation.
- Synapse
.queued / .delivering: say the exact AC has a pending or claimed
intent signal and name
the effective boundary; do not claim application yet.
- Synapse
.applied / .completed: confirm runtime-proven application and
relay the bounded AC reply when present.
- Synapse
.rejected / .delivery_uncertain: surface immediately and never
claim the AC changed course.
- Suppress unchanged heartbeats and raw tool output.
Render every relay in the user's current conversation language. Keep event
codes and effective-mode values unchanged only when exact diagnostics help.
These are English canonical host instructions. Phrase the facts naturally in
the active conversation language.
This ownership split is the default for SOL-class models: the main model
performs one start handoff, while a small isolated context owns the repetitive
wait/result state machine.
If child creation is unavailable, fails, or returns no live child, do not
claim that an observer exists or promise live proactive messages. The
detached worker survives the stdio MCP turn. Tell the user that progress is
durable and will be caught up on the next parent turn or explicit status
request. Keep the turn open only when the user explicitly asked for live
watching; then use the fallback below.
Fallback: low-token relay loop in the main session.
Use this only when response.meta.job_observer is absent, the host has no
independent child session primitive, and the user explicitly asked to keep
watching in the current turn. Do not run it in parallel with a delegated
observer. Otherwise end the turn safely and catch up from the same cursor on
the next parent turn.
Use ouroboros_job_wait, not repeated ouroboros_ac_tree_hud, for routine
monitoring. Keep the latest cursor and previous progress counters from the
tool meta payload.
This loop is intentionally harness/model friendly:
- Treat
response.meta as the source of truth.
- Do not parse
response.text for counts, status, or cursor.
- Use
response.text only as a human-readable current-message hint.
- Keep all local monitor state in simple scalar variables.
- Emit at most one short relay message per changed response.
- Always continue to final
ouroboros_job_result after a terminal status.
cursor = <cursor from start/status response, or 0>
prev_status = "running"
prev_phase = null
prev_ac_completed = 0
prev_sub_ac_completed = 0
prev_message = null
loop:
Tool: ouroboros_job_wait
Arguments:
job_id: <job_id from step 3>
cursor: <cursor>
timeout_seconds: 180
view: "summary"
stream: "linked"
wait_for: "attention_or_ac_change"
cursor = response.meta.cursor
if response.meta.changed is false:
# Do not narrate unless the user explicitly asked for heartbeat updates.
continue
status = response.meta.status
phase = response.meta.current_phase
ac_completed = response.meta.ac_completed
ac_total = response.meta.ac_total
sub_ac_completed = response.meta.sub_ac_completed
sub_ac_total = response.meta.sub_ac_total
# The metadata field names remain legacy-compatible; relay them to users as Task/Subtask progress.
message_hint = first non-empty non-metadata line from response.text, or null
# Build one short relay update from structured fields.
if status in ["completed", "failed", "cancelled", "interrupted"]:
print terminal_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
break
if ac_completed > prev_ac_completed:
print task_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
elif sub_ac_completed > prev_sub_ac_completed:
print subtask_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
elif phase != prev_phase or status != prev_status:
print phase_or_status_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
elif message_hint != prev_message:
print current_work_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
prev_status = status
prev_phase = phase
prev_ac_completed = ac_completed or prev_ac_completed
prev_sub_ac_completed = sub_ac_completed or prev_sub_ac_completed
prev_message = message_hint or prev_message
Notes:
timeout_seconds: 180 means the MCP call can block for up to 3 minutes.
This keeps the main session available often enough for a live relay while
still avoiding noisy polling.
- Use
view: "compact" for very long jobs or when the user only wants a
heartbeat. The raw tool may still return legacy text such as
job_x | running | AC 3/17; relay that to users as Task progress.
- Use
view: "summary" for normal monitoring. It includes the job message
plus Task/Subtask counts derived from legacy ac_completed/sub_ac_completed
metadata fields.
- Use
view: "full" only when the user asks for detailed job status.
Relay style examples:
In progress: Deliver is at Task 1/3 and Subtask 12/16. Current work is the Subtask 3 regression test.
Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.
Completed: execution finished. Fetching the final job result now.
Relay output contract for other harnesses/models:
- One update should be 1-2 sentences or 1 compact line.
- Include
phase, Task completed/total and Subtask completed/total when present.
- Include the current work hint only if it changes.
- Never include the full task tree in routine relay output.
- Never include raw JSON, raw meta dumps, or repeated unchanged cursor lines.
- Terminal statuses must be explicit: completed, failed, cancelled, or interrupted.
Do not paste the full raw tool output unless the user asks for raw status.
Do not add speculative ETA unless the tool provides one.
Synapse intent refinement: When the user gives additive implementation
intent during an active run, the main session owns target selection; never ask
the user for internal AC/session IDs.
Immediately before each Synapse call, reload its deferred schemas with
tool discovery query: "+ouroboros session signal".
- Take
execution_id from the start result or observer contract and call
ouroboros_session_signal_targets(execution_id=...).
- Match the user's meaning against each target's
ac_content, display path,
and current HUD activity when needed. One active target may be selected
directly. With multiple targets, select only when one is materially more
relevant; ask a short user-language clarification only for genuine ties.
- For additive implementation refinement, call
ouroboros_session_signal
with the selected target's exact scope/attempt/execution guards,
contract_effect="additive", source="user", mode="redirect", and
fallback_mode="after_turn". Copy expected_contract_version when target
discovery supplies it, and create one stable idempotency key for this exact
user turn. If the target went stale, rediscover once instead of asking for
IDs.
- When the user asks the AC a read-only question or requests assurance rather
than an implementation change, use
mode="inform" and
contract_effect="additive", and omit fallback_mode entirely because it
is valid only for redirect. Synapse runs a no-tools reply turn when the
runtime supports it; relay the bounded reply from the completed event.
- Tell the user which AC was selected and report the returned effective mode.
Wait for observer
.applied or .completed before saying it was reflected.
Never use Synapse to change approved goals, ACs, constraints, or non-goals;
those require an approved shared successor or replacement contract.
Active Conductor attention handling: recommended_host_actions is the
authoritative menu. Never invent a mutating tool call.
- VERIFY with at most one short-lived read-only host child using the supplied
evidence IDs. If the host has no verifier primitive, surface the attention
and stop before mutation.
- DECIDE among the ordered menu actions. Engine-owned retry/routing must be
closed before any successor action is considered.
- LOG
phase="selected" through
ouroboros_record_conductor_decision before ACT. For a specification
change in run mode, obtain explicit user approval and bind its receipt.
- ACT only when the menu names a currently registered MCP tool. A corrective
successor must preserve the approved contract unless the user approved the
shared specification change.
- LOG exactly one terminal
completed, failed, or declined outcome. Do
not silently retry a failed conductor action.
Use ouroboros_ac_tree_hud only for manual drill-down or anomaly checks.
Do not call full tree HUD in the normal polling loop.
Use these targeted calls:
# Explicit short HUD, useful for a one-off check
Tool: ouroboros_ac_tree_hud
Arguments:
session_id: <session_id>
cursor: <cursor>
view: "summary"
# Lowest-token one-line HUD
Tool: ouroboros_ac_tree_hud
Arguments:
session_id: <session_id>
cursor: <cursor>
view: "compact"
# Full tree only when user asks "show details", progress looks stuck,
# or debugging requires seeing the task/subtask structure.
Tool: ouroboros_ac_tree_hud
Arguments:
session_id: <session_id>
cursor: <cursor>
view: "tree"
max_nodes: 30
Treat unchanged cursor=<cursor> from explicit compact/summary views as a
no-op. Do not explain it to the user unless they explicitly asked for
heartbeat messages.
Fetch final result in the polling owner with ouroboros_job_result.
The delegated observer performs this call on the default path. The main
session performs it only on the fallback path from step 6.
Tool: ouroboros_job_result
Arguments:
job_id: <job_id>
Present the execution results to the user:
- Show success/failure status
- Show session ID (for later status checks)
- Show execution summary
Post-execution QA and formal evaluation (automatic):
ouroboros_start_execute_seed automatically runs QA after execution.
The QA verdict is included in the final job result text. This QA check is
not the formal 3-stage evaluator. On servers that return
chained_evaluate_job_id, the run has already enqueued the formal
evaluator as a separate bounded background job.
To skip: pass skip_qa: true to the tool.
If the final run result meta contains chained_evaluate_job_id:
- The current polling owner continues with that job ID
- Fetch its verdict with
ouroboros_job_result after terminal status
- Render APPROVED when
final_approved: true; otherwise render not approved and list failed ACs or the failure reason from the evaluation result
- If the evaluate job failed or timed out, keep the run success intact and show
Next: ooo evaluate <session_id> as the manual retry
- If the evaluation result contains
chained_ralph_job_id, continue observing
that job before presenting the final outcome. Report approval/convergence or
the bounded Ralph stop reason; do not call the run blocked merely because
its first evaluation was rejected.
If chained_evaluate_job_id is absent, keep the legacy path verbatim:
- PASS:
Next: ooo evaluate <session_id> for formal 3-stage verification
- REVISE: Show differences/suggestions, then
Next: Fix the issues above, then ooo run to retry -- or ooo unstuck if blocked
- FAIL/ESCALATE:
Next: Review failures above, then ooo run to retry -- or ooo unstuck if blocked
Fallback (No MCP Server)
If the MCP server is not available, inform the user:
Ouroboros MCP server is not configured.
To enable full execution mode, run: /ouroboros:setup
Without MCP, you can still:
- Use /ouroboros:interview for requirement clarification
- Use /ouroboros:seed to generate specifications
- Manually implement the seed specification
Example
User: /ouroboros:ouroboros-run seed.yaml
[Reads seed.yaml, validates, starts background execution]
Background execution started.
Job ID: job_a1b2c3d4e5f6
Session ID: orch_x1y2z3
Execution ID: exec_m1n2o3
[Relay]
In progress: Deliver is at Task 1/3 and Subtask 12/16.
Current work is finishing the workflow routing Subtask.
[Relay]
Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.
Execution is complete. Fetching the final job result now.
[Fetching final result...]
Result:
Seed Execution SUCCESS
========================
Session ID: orch_x1y2z3
Goal: Build a CLI task manager
Duration: 45.2s
Messages Processed: 12
Verification Status: executed_unverified
Formal Evaluation: NOT evaluated by the 3-stage evaluator
Next: `ooo evaluate orch_x1y2z3` for formal 3-stage verification
# Newer server path:
Verification Status: evaluation_enqueued
Chained Evaluation Job ID: job_eval987
[Poll ouroboros_job_wait/job_status, then fetch ouroboros_job_result]
Formal Evaluation Verdict: APPROVED
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: ouroboros-run
3description: "Execute a Seed specification through the workflow engine"
4aliases: [execute]
5mcp_tool: ouroboros_execute_seed
6mcp_args:
7 seed_path: "$1"
8 cwd: "$CWD"
9metadata:
10 source: https://skillmd.com/skills/q00/ouroboros-run
11---
12
13# /ouroboros:ouroboros-run
14
15Execute a Seed specification through the Ouroboros workflow engine.
16
17## Usage
18
19```
20/ouroboros:ouroboros-run [seed_file_or_content]
21```
22
23**Trigger keywords:** "ouroboros run", "execute seed"
24
25## How It Works
26
271. **Input**: Provide seed YAML content directly or a path to a `.yaml` file
282. **Validation**: Seed is parsed and validated (goal, constraints, acceptance criteria, ontology)
293. **Execution**: The orchestrator runs the workflow with PAL routing
304. **Progress**: Real-time progress updates via session tracking
315. **Result**: Execution summary with pass/fail status
326. **Convergence**: completed runs enqueue formal evaluation by default. An
33 explicit rejection continues through a bounded Ralph loop until approved or
34 the configured evolution budget/stop condition is reached.
35
36## Instructions
37
38When the user invokes this skill:
39
40### Load MCP Tools (Required first)
41
42The Ouroboros MCP tools are often registered as **deferred tools** that must be explicitly loaded before use. **You MUST perform this step before proceeding.**
43
441. Use the active runtime's tool-discovery capability to find and load the execution MCP tools:
45 ```
46 tool discovery query: "+ouroboros execute"
47 ```
482. The tools will typically be named with prefix `mcp__plugin_ouroboros_ouroboros__` (e.g., `ouroboros_execute_seed`, `ouroboros_session_status`). After runtime tool discovery returns, the tools become callable.
493. If the tools are callable — already exposed, or loaded by discovery — proceed with the steps below. An empty discovery result for already-exposed tools is expected, not a failure. Skip to the **Fallback** section only if they are genuinely absent (no Ouroboros MCP server).
50
51**IMPORTANT**: Do NOT skip this step. Do NOT assume MCP tools are unavailable just because they don't appear in your immediate tool list. They are almost always available as deferred tools that need to be loaded first.
52
53**CRITICAL — deferred-schema guard (prevents "Invalid tool parameters"):**
54This skill makes execution MCP calls across multiple turns, and each turn runs
55in a fresh tool context. A deferred tool's schema loaded on one turn is NOT
56guaranteed to still be loaded on the next. If you call any execution `ouroboros_*`
57MCP tool while its schema is not loaded in the **current** turn, the runtime
58rejects the call with **"Invalid tool parameters"** before it reaches the server.
59Therefore: **immediately before EVERY execution MCP call in this skill, re-run
60`tool discovery query: "+ouroboros execute"`** to reload the execution tool family,
61including `ouroboros_start_execute_seed`, `ouroboros_job_wait`,
62`ouroboros_ac_tree_hud`, and `ouroboros_job_result` (idempotent — a no-op when
63already loaded). If the load returns no matching tool (and the tool is not already callable — an empty load for an already-exposed tool is an expected no-op, not absence), switch to the documented
64fallback instead of retrying the failing call.
65
66### Execution Steps
67
681. **Detect git workflow** (before any code changes):
69 - Read the project's `CLAUDE.md` for git workflow preferences
70 - If PR-based workflow detected and currently on `main`/`master`:
71 - Create a feature branch: `ooo/run/<session_id>`
72 - All code changes go to this branch
73 - If no preference: use current branch (backward compatible)
74
752. Check if the user provided seed content or a file path:
76 - If a file path: Read the file with the Read tool
77 - If inline YAML: Use directly
78 - If neither: Check conversation history for a recently generated seed
79
80 Before a fresh start, when the user has not already chosen an efficiency
81 policy, first check the persistent default: when `execution.default_policy`
82 in `~/.ouroboros/config.yaml` is `efficient` or `quality_first`, do not ask —
83 omit both arguments and the server applies the configured default (the start
84 handoff still reports the resolved policy). When it is `ask` or unset, ask
85 in outcome language:
86
87 - **Efficient execution** — start parallel/decomposed work economically and
88 strengthen the route only when recovery requires it. Send
89 `efficiency_mode="adaptive"` and `frugality_assurance="observe"`.
90 - **Quality-first execution** — keep child work at the parent starting tier.
91 Send `efficiency_mode="quality_first"` and `frugality_assurance="off"`.
92
93 `frugality_assurance="strict"` is a separate explicit opt-in because it may
94 spend extra work on proof. Never enable it merely because efficient execution
95 was chosen. Do not ask again on resume; the server restores the persisted
96 policy and rejects an attempted resume-time change.
97
983. **Start background execution** with `ouroboros_start_execute_seed`:
99 ```
100 Tool: ouroboros_start_execute_seed
101 Arguments:
102 seed_content: <the seed YAML>
103 efficiency_mode: <adaptive or quality_first>
104 frugality_assurance: <observe, off, or explicit strict>
105 max_iterations: 10 (or as specified by user)
106 ```
107 Omit `model_tier` by default so the runtime selects automatically. Include
108 `model_tier: <user choice>` only when the user explicitly requested a tier.
109 This returns immediately with a `job_id`, `session_id`, and `execution_id`.
110
1114. If resuming an existing session, include `session_id`:
112 ```
113 Tool: ouroboros_start_execute_seed
114 Arguments:
115 seed_content: <the seed YAML>
116 session_id: <existing session ID>
117 ```
118
1195. **Recommended monitoring stance: delegate observation to one child session.**
120
121 **TUI surfacing at job start (RFC #1392):**
122
123 After `job_id`, `session_id`, and `execution_id` are returned, surface a live
124 view once without delaying execution or observer delegation:
125
126 - If `response.meta.dashboard_url` exists, show it as the primary live view.
127
128 - If `execution.tui_autolaunch: true` (or legacy top-level
129 `tui_autolaunch: true`) is present in the loaded Ouroboros config, run
130 `ouroboros tui open` unconditionally and mention the dashboard in one
131 short line.
132 - Otherwise mention once that the TUI can be opened in a new terminal with
133 `ouroboros tui open`. Offer to open it, but do not block the run waiting for
134 an answer. Remember the answer for this session and do not repeat the offer.
135 - If the user accepts, run `ouroboros tui open`.
136 - If `ouroboros tui open` reports a manual command because the environment
137 is headless, SSH, or unsupported, relay that command once and continue.
138 - The dashboard is an external observer. It does not change which chat
139 session owns MCP polling.
140
141 After IDs are returned, print only this short handoff:
142
143 ```
144 Execution started in background.
145 Job ID: <job_id>
146 Session ID: <session_id>
147 Execution ID: <execution_id>
148 Live view: <dashboard_url, or `ouroboros tui open`>
149 Runtime/harness: <response.meta.runtime_backend>
150 LLM backend: <response.meta.llm_backend>
151 Efficiency: <response.meta.efficiency_mode>
152 Frugality assurance: <response.meta.frugality_assurance>
153
154 Observation: <confirmed read-only child observer, or durable catch-up mode>.
155 With a confirmed observer, meaningful progress, attention, and completion
156 events will be posted here. Without one, the run still survives this turn
157 and I will catch up from durable events on your next message or status request.
158 This conversation stays available while the run continues.
159 We can refine requirements, inspect or review code, or work on an unrelated
160 task in an isolated worktree. I will check for active-worker conflicts before
161 editing this run's workspace.
162 For full details later: `ouroboros_ac_tree_hud(session_id=<session_id>)`
163 ```
164
165 **Text-only host compatibility (OMP and similar bridges):**
166
167 If `response.meta.job_observer` is unavailable, inspect the response content
168 for the final sentinel block:
169
170 ```text
171 <!-- ouroboros-job-observer-v1 base64
172 <payload>
173 -->
174 ```
175
176 Base64-decode `<payload>`, then fail closed unless it passes the canonical v1
177 validation implemented by `extract_job_observer_inline_handoff`: exactly one
178 bounded terminal sentinel; fixed protocol, role, ownership, wait/result tools,
179 restrictions, and follow-result keys; internally consistent IDs; and a
180 `job_id` matching the visible start receipt. Use visible Job/Session/Execution
181 IDs only as identity anchors, never to reconstruct the nested contract. If
182 structured and inline surfaces differ or validation fails, do not spawn an
183 observer; report a transport-integrity failure.
184
185 When a structured or recovered `job_observer` is present and the host has an
186 independent child/subagent session primitive, spawn exactly one observer
187 session and pass that object unchanged. Codex uses `spawn_agent`, OMP uses
188 one native Task child, and Claude Code uses one Task/Agent child. The observer must:
189
190 - On Codex, call the native `spawn_agent` primitive exactly once with
191 `task_name="run_observer"` and include the structured or recovered
192 `job_observer` unchanged in the child message. A `wait` call is not a spawn.
193 - Require the spawn result to return a live child ID/path before saying an
194 observer is connected or before ending the start turn.
195 - On OMP, submit exactly one Task item named `RunObserver` with the recovered
196 or structured contract unchanged, require the returned live agent/job ID,
197 and use the host wait/inbox relay until the observer returns terminal.
198 A job-status poll in the parent is not an observer spawn.
199
200 - remain read-only: no repository edits, execution control, or worker fan-out;
201 - own the job cursor exclusively and reload deferred MCP schemas immediately
202 before each observer tool call;
203 - call the declared `wait.tool` with the declared arguments, update its local
204 cursor from response meta, and repeat until terminal;
205 - call the declared `result.tool` after terminal status;
206 - follow any job IDs named by `follow_result_job_keys`, including chained
207 formal evaluation, before returning one compact final summary;
208 - send sparse progress notices only when the host supports child-to-parent
209 messages and the state meaningfully changes.
210
211 The main session must not poll the same job while the observer owns it. It may
212 continue the user conversation, refine requirements, perform read-only
213 inspection/review, handle explicit status/control requests, or work on an
214 unrelated task in an isolated worktree. Before writing to the active run's
215 workspace, check for overlap with worker files or isolate the work. If
216 `job_id` is absent because plugin mode already delegated the whole execution,
217 follow that plugin child lifecycle instead.
218
219 On Codex, a confirmed observer also requires a parent relay loop. After
220 `spawn_agent` returns a live child ID/path, keep the parent turn open with
221 `wait_agent` calls of at most 60 seconds. A child `send_message` only queues a
222 mailbox event and cannot wake a parent turn that has already ended. Relay
223 meaningful observer updates, then wait again until the child returns its
224 terminal summary. User input may interrupt the wait; handle it and resume the
225 relay loop while the observer remains active unless the user asks to stop
226 live observation or replaces the active request. Then end only the relay
227 loop, keep the durable job running, and offer next-turn or explicit-status
228 catch-up. If the observer child fails, is cancelled, or exits before a
229 terminal summary, use that same fallback instead of waiting indefinitely.
230 This wait loop must never call Ouroboros job tools or compete for the
231 observer's cursor.
232
233 Handle observer messages as events, not as a transcript:
234
235 - `phase_changed` / `progress_advanced`: relay at most 1-2 concise lines.
236 Interpret the structured subtype, not raw logs:
237 - `run_configuration`: state the current runtime/harness, starting model or
238 tier when known, efficiency mode, and frugality assurance. If the exact
239 model is not known yet, say it will be reported by the first routing event.
240 - `execution_plan`: state total ACs, total dependency/parallel levels,
241 whether work can run in parallel, and the first scheduled AC summaries.
242 - `discovery_summary`: say which bounded targets the AC is examining and
243 the purpose; never expose search queries, raw commands, or reasoning.
244 - `level_started` / `level_completed`: say which parallel level is active
245 or finished and the meaningful success/failure counts.
246 - `ac_routing` / `harness_changed`: say "currently running with" and report
247 only initial routing or a real model/tier/harness change.
248 - `ac_verified`: report the completed AC and its compact assurance evidence.
249 - `attention_required`: surface the blocker or pending decision immediately
250 and ask the user only when human judgment is required.
251 - `terminal`: fetch/present the final result and any chained evaluation.
252 - Synapse `.queued` / `.delivering`: say the exact AC has a pending or claimed
253 intent signal and name
254 the effective boundary; do not claim application yet.
255 - Synapse `.applied` / `.completed`: confirm runtime-proven application and
256 relay the bounded AC reply when present.
257 - Synapse `.rejected` / `.delivery_uncertain`: surface immediately and never
258 claim the AC changed course.
259 - Suppress unchanged heartbeats and raw tool output.
260
261 Render every relay in the user's current conversation language. Keep event
262 codes and effective-mode values unchanged only when exact diagnostics help.
263 These are English canonical host instructions. Phrase the facts naturally in
264 the active conversation language.
265
266 This ownership split is the default for SOL-class models: the main model
267 performs one start handoff, while a small isolated context owns the repetitive
268 wait/result state machine.
269
270 If child creation is unavailable, fails, or returns no live child, do not
271 claim that an observer exists or promise live proactive messages. The
272 detached worker survives the stdio MCP turn. Tell the user that progress is
273 durable and will be caught up on the next parent turn or explicit status
274 request. Keep the turn open only when the user explicitly asked for live
275 watching; then use the fallback below.
276
2776. **Fallback: low-token relay loop in the main session.**
278
279 Use this only when `response.meta.job_observer` is absent, the host has no
280 independent child session primitive, and the user explicitly asked to keep
281 watching in the current turn. Do not run it in parallel with a delegated
282 observer. Otherwise end the turn safely and catch up from the same cursor on
283 the next parent turn.
284
285 Use `ouroboros_job_wait`, not repeated `ouroboros_ac_tree_hud`, for routine
286 monitoring. Keep the latest cursor and previous progress counters from the
287 tool meta payload.
288
289 This loop is intentionally harness/model friendly:
290 - Treat `response.meta` as the source of truth.
291 - Do not parse `response.text` for counts, status, or cursor.
292 - Use `response.text` only as a human-readable current-message hint.
293 - Keep all local monitor state in simple scalar variables.
294 - Emit at most one short relay message per changed response.
295 - Always continue to final `ouroboros_job_result` after a terminal status.
296
297 ```
298 cursor = <cursor from start/status response, or 0>
299 prev_status = "running"
300 prev_phase = null
301 prev_ac_completed = 0
302 prev_sub_ac_completed = 0
303 prev_message = null
304
305 loop:
306 Tool: ouroboros_job_wait
307 Arguments:
308 job_id: <job_id from step 3>
309 cursor: <cursor>
310 timeout_seconds: 180
311 view: "summary"
312 stream: "linked"
313 wait_for: "attention_or_ac_change"
314
315 cursor = response.meta.cursor
316
317 if response.meta.changed is false:
318 # Do not narrate unless the user explicitly asked for heartbeat updates.
319 continue
320
321 status = response.meta.status
322 phase = response.meta.current_phase
323 ac_completed = response.meta.ac_completed
324 ac_total = response.meta.ac_total
325 sub_ac_completed = response.meta.sub_ac_completed
326 sub_ac_total = response.meta.sub_ac_total
327 # The metadata field names remain legacy-compatible; relay them to users as Task/Subtask progress.
328 message_hint = first non-empty non-metadata line from response.text, or null
329
330 # Build one short relay update from structured fields.
331 if status in ["completed", "failed", "cancelled", "interrupted"]:
332 print terminal_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
333 break
334
335 if ac_completed > prev_ac_completed:
336 print task_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
337 elif sub_ac_completed > prev_sub_ac_completed:
338 print subtask_progress_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
339 elif phase != prev_phase or status != prev_status:
340 print phase_or_status_relay(status, phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total)
341 elif message_hint != prev_message:
342 print current_work_relay(phase, ac_completed, ac_total, sub_ac_completed, sub_ac_total, message_hint)
343
344 prev_status = status
345 prev_phase = phase
346 prev_ac_completed = ac_completed or prev_ac_completed
347 prev_sub_ac_completed = sub_ac_completed or prev_sub_ac_completed
348 prev_message = message_hint or prev_message
349 ```
350
351 Notes:
352 - `timeout_seconds: 180` means the MCP call can block for up to 3 minutes.
353 This keeps the main session available often enough for a live relay while
354 still avoiding noisy polling.
355 - Use `view: "compact"` for very long jobs or when the user only wants a
356 heartbeat. The raw tool may still return legacy text such as
357 `job_x | running | AC 3/17`; relay that to users as Task progress.
358 - Use `view: "summary"` for normal monitoring. It includes the job message
359 plus Task/Subtask counts derived from legacy `ac_completed`/`sub_ac_completed`
360 metadata fields.
361 - Use `view: "full"` only when the user asks for detailed job status.
362
363 Relay style examples:
364 - `In progress: Deliver is at Task 1/3 and Subtask 12/16. Current work is the Subtask 3 regression test.`
365 - `Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.`
366 - `Completed: execution finished. Fetching the final job result now.`
367
368 Relay output contract for other harnesses/models:
369 - One update should be 1-2 sentences or 1 compact line.
370 - Include `phase`, Task completed/total and Subtask completed/total when present.
371 - Include the current work hint only if it changes.
372 - Never include the full task tree in routine relay output.
373 - Never include raw JSON, raw meta dumps, or repeated unchanged cursor lines.
374 - Terminal statuses must be explicit: completed, failed, cancelled, or interrupted.
375
376 Do not paste the full raw tool output unless the user asks for raw status.
377 Do not add speculative ETA unless the tool provides one.
378
379 **Synapse intent refinement:** When the user gives additive implementation
380 intent during an active run, the main session owns target selection; never ask
381 the user for internal AC/session IDs.
382
383 Immediately before each Synapse call, reload its deferred schemas with
384 `tool discovery query: "+ouroboros session signal"`.
385
386 1. Take `execution_id` from the start result or observer contract and call
387 `ouroboros_session_signal_targets(execution_id=...)`.
388 2. Match the user's meaning against each target's `ac_content`, display path,
389 and current HUD activity when needed. One active target may be selected
390 directly. With multiple targets, select only when one is materially more
391 relevant; ask a short user-language clarification only for genuine ties.
392 3. For additive implementation refinement, call `ouroboros_session_signal`
393 with the selected target's exact scope/attempt/execution guards,
394 `contract_effect="additive"`, `source="user"`, `mode="redirect"`, and
395 `fallback_mode="after_turn"`. Copy `expected_contract_version` when target
396 discovery supplies it, and create one stable idempotency key for this exact
397 user turn. If the target went stale, rediscover once instead of asking for
398 IDs.
399 4. When the user asks the AC a read-only question or requests assurance rather
400 than an implementation change, use `mode="inform"` and
401 `contract_effect="additive"`, and omit `fallback_mode` entirely because it
402 is valid only for redirect. Synapse runs a no-tools reply turn when the
403 runtime supports it; relay the bounded reply from the completed event.
404 5. Tell the user which AC was selected and report the returned effective mode.
405 Wait for observer `.applied` or `.completed` before saying it was reflected.
406
407 Never use Synapse to change approved goals, ACs, constraints, or non-goals;
408 those require an approved shared successor or replacement contract.
409
410 **Active Conductor attention handling:** `recommended_host_actions` is the
411 authoritative menu. Never invent a mutating tool call.
412
413 1. VERIFY with at most one short-lived read-only host child using the supplied
414 evidence IDs. If the host has no verifier primitive, surface the attention
415 and stop before mutation.
416 2. DECIDE among the ordered menu actions. Engine-owned retry/routing must be
417 closed before any successor action is considered.
418 3. LOG `phase="selected"` through
419 `ouroboros_record_conductor_decision` before ACT. For a specification
420 change in run mode, obtain explicit user approval and bind its receipt.
421 4. ACT only when the menu names a currently registered MCP tool. A corrective
422 successor must preserve the approved contract unless the user approved the
423 shared specification change.
424 5. LOG exactly one terminal `completed`, `failed`, or `declined` outcome. Do
425 not silently retry a failed conductor action.
426
4277. **Use `ouroboros_ac_tree_hud` only for manual drill-down or anomaly checks.**
428
429 Do not call full tree HUD in the normal polling loop.
430
431 Use these targeted calls:
432
433 ```
434 # Explicit short HUD, useful for a one-off check
435 Tool: ouroboros_ac_tree_hud
436 Arguments:
437 session_id: <session_id>
438 cursor: <cursor>
439 view: "summary"
440
441 # Lowest-token one-line HUD
442 Tool: ouroboros_ac_tree_hud
443 Arguments:
444 session_id: <session_id>
445 cursor: <cursor>
446 view: "compact"
447
448 # Full tree only when user asks "show details", progress looks stuck,
449 # or debugging requires seeing the task/subtask structure.
450 Tool: ouroboros_ac_tree_hud
451 Arguments:
452 session_id: <session_id>
453 cursor: <cursor>
454 view: "tree"
455 max_nodes: 30
456 ```
457
458 Treat `unchanged cursor=<cursor>` from explicit compact/summary views as a
459 no-op. Do not explain it to the user unless they explicitly asked for
460 heartbeat messages.
461
4628. **Fetch final result in the polling owner** with `ouroboros_job_result`.
463
464 The delegated observer performs this call on the default path. The main
465 session performs it only on the fallback path from step 6.
466 ```
467 Tool: ouroboros_job_result
468 Arguments:
469 job_id: <job_id>
470 ```
471
4729. Present the execution results to the user:
473 - Show success/failure status
474 - Show session ID (for later status checks)
475 - Show execution summary
476
47710. **Post-execution QA and formal evaluation** (automatic):
478 `ouroboros_start_execute_seed` automatically runs QA after execution.
479 The QA verdict is included in the final job result text. This QA check is
480 **not** the formal 3-stage evaluator. On servers that return
481 `chained_evaluate_job_id`, the run has already enqueued the formal
482 evaluator as a separate bounded background job.
483 To skip: pass `skip_qa: true` to the tool.
484
485 If the final run result meta contains `chained_evaluate_job_id`:
486 - The current polling owner continues with that job ID
487 - Fetch its verdict with `ouroboros_job_result` after terminal status
488 - Render **APPROVED** when `final_approved: true`; otherwise render not approved and list failed ACs or the failure reason from the evaluation result
489 - If the evaluate job failed or timed out, keep the run success intact and show `Next: ooo evaluate <session_id>` as the manual retry
490 - If the evaluation result contains `chained_ralph_job_id`, continue observing
491 that job before presenting the final outcome. Report approval/convergence or
492 the bounded Ralph stop reason; do not call the run blocked merely because
493 its first evaluation was rejected.
494
495 If `chained_evaluate_job_id` is absent, keep the legacy path verbatim:
496 - **PASS**: `Next: ooo evaluate <session_id> for formal 3-stage verification`
497 - **REVISE**: Show differences/suggestions, then `Next: Fix the issues above, then ooo run to retry -- or ooo unstuck if blocked`
498 - **FAIL/ESCALATE**: `Next: Review failures above, then ooo run to retry -- or ooo unstuck if blocked`
499
500## Fallback (No MCP Server)
501
502If the MCP server is not available, inform the user:
503
504```
505Ouroboros MCP server is not configured.
506To enable full execution mode, run: /ouroboros:setup
507
508Without MCP, you can still:
509- Use /ouroboros:interview for requirement clarification
510- Use /ouroboros:seed to generate specifications
511- Manually implement the seed specification
512```
513
514## Example
515
516```
517User: /ouroboros:ouroboros-run seed.yaml
518
519[Reads seed.yaml, validates, starts background execution]
520
521Background execution started.
522Job ID: job_a1b2c3d4e5f6
523Session ID: orch_x1y2z3
524Execution ID: exec_m1n2o3
525
526[Relay]
527In progress: Deliver is at Task 1/3 and Subtask 12/16.
528Current work is finishing the workflow routing Subtask.
529
530[Relay]
531Level update: parallel level 1/1 has finished, and Task progress advanced to 3/3.
532Execution is complete. Fetching the final job result now.
533
534[Fetching final result...]
535
536Result:
537 Seed Execution SUCCESS
538 ========================
539 Session ID: orch_x1y2z3
540 Goal: Build a CLI task manager
541 Duration: 45.2s
542 Messages Processed: 12
543 Verification Status: executed_unverified
544 Formal Evaluation: NOT evaluated by the 3-stage evaluator
545
546 Next: `ooo evaluate orch_x1y2z3` for formal 3-stage verification
547
548 # Newer server path:
549 Verification Status: evaluation_enqueued
550 Chained Evaluation Job ID: job_eval987
551 [Poll ouroboros_job_wait/job_status, then fetch ouroboros_job_result]
552 Formal Evaluation Verdict: APPROVED
553```
554
555## RFC #1392 State Breadcrumb Footer
556
557Your final response MUST end with exactly one breadcrumb footer line:
558
559```
560◆ <current state> → next: <recommended action>
561```
562
563Derive `<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.