ouroboros-run

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

1. **Input**: Provide seed YAML content directly or a path to a `.yaml` file
2. **Validation**: Seed is parsed and validated (goal, constraints, acceptance criteria, ontology)
3. **Execution**: The orchestrator runs the workflow with PAL routing
4. **Progress**: Real-time progress updates via session tracking
5. **Result**: Execution summary with pass/fail status
6. **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.**

1. Use the active runtime's tool-discovery capability to find and load the execution MCP tools:
   ```
   tool discovery query: "+ouroboros execute"
   ```
2. 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.
3. 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

1. **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)

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

3. **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`.

4. If resuming an existing session, include `session_id`:
   ```
   Tool: ouroboros_start_execute_seed
   Arguments:
     seed_content: <the seed YAML>
     session_id: <existing session ID>
   ```

5. **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.
   -