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
Verification status: Run-only results are executed_unverified until ooo evaluate <session_id> performs formal 3-stage verification

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

Start background execution with ouroboros_start_execute_seed:

Tool: ouroboros_start_execute_seed
Arguments:
  seed_content: <the seed YAML>
  model_tier: "medium"  (or as specified by user)
  max_iterations: 10    (or as specified by user)

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: relay compact progress in the main session.

TUI surfacing at job start (RFC #1392):

After job_id, session_id, and execution_id are returned, surface the live dashboard once for this run before entering the relay loop:
- 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 offer once: "Want a live dashboard? I can open the TUI in a new terminal window with ouroboros tui open." Remember the answer for this session and do not repeat the offer during the same run.
- 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.
- Always keep the in-session compact progress relay below as the baseline; the dashboard is additive, not a replacement for relay updates.
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>

I will wait in low-token relay mode and report only meaningful state changes.
For full details later: `ouroboros_ac_tree_hud(session_id=<session_id>)`
```
Rationale: the main chat session must wait for MCP calls. Frequent full-tree polling burns context without improving execution. The user usually wants "what is it doing now?" rather than the whole tree, so use compact job read-model snapshots and narrate them like a brief live relay.

Low-token relay loop with ouroboros_job_wait (recommended default).

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"

  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.

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 with ouroboros_job_result:

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

Poll that job with ouroboros_job_wait / ouroboros_job_status
Fetch its verdict with ouroboros_job_result
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 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: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.

run

/ouroboros:run

Usage

How It Works