ouroboros-run

Files (1)

• SKILL.md

SKILL.md (first lines)

# /ouroboros:ouroboros-run

Execute a Seed specification through the Ouroboros workflow engine as a background job. A completed run enqueues formal evaluation by default, and a rejection continues through a bounded Ralph loop.

## Usage

```
/ouroboros:ouroboros-run [seed_file_or_content]
```

## Instructions

### Loading MCP tools (deferred-schema guard)

Ouroboros tools may be deferred, and a schema loaded on one turn can unload by the next. Immediately before each `ouroboros_*` call, load it with the active runtime's tool-discovery capability: `"+ouroboros execute"` for `ouroboros_start_execute_seed`, `ouroboros_job_wait`, `ouroboros_job_result`, and `ouroboros_ac_tree_hud`; `"+ouroboros session signal"` for `ouroboros_session_signal_targets` and `ouroboros_session_signal`. A call whose schema is not loaded fails with "Invalid tool parameters". If the tool is already callable, discovery is a no-op and an empty result is expected. Use the **Fallback (No MCP Server)** section only when the tools are genuinely absent.

### Execution Steps

1. **Do not create or switch branches yourself.** For a background execution
   job, `use_worktree` defaults to true: the server runs the task in its own
   worktree and reports `worktree_path` / `worktree_branch` in the job result.
   Tell the user the task was isolated only when those fields are present. A
   `dispatch_mode="plugin"` response delegates to a child session and carries
   no worktree.

2. **Get the Seed.** Read a given file path with the active runtime's `inspect_code` capability, use inline YAML directly, or otherwise take the most recently generated Seed in the conversation.

   Before a fresh start, do not ask about an efficiency policy unless the user
   raised it or `execution.default_policy` in `~/.ouroboros/config.yaml` is
   explicitly `ask`. Otherwise omit both arguments: the server applies the
   configured default (quality-first when nothing is configured), and its start
   receipt names the running policy and the change command. If the user did
   choose, or the config says `ask`, map the choice 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 infer it from the efficiency choice. Do not
   ask again on resume: the server restores the persisted policy and rejects a
   resume-time change.

3. **Start background execution:**
   ```
   Tool: ouroboros_start_execute_seed
   Arguments:
     seed_content: <the seed YAML>
     efficiency_mode: <only when chosen: adaptive or quality_first>
     frugality_assurance: <only when chosen: observe, off, or explicit strict>
     session_id: <only when resuming an existing session>
   ```
   Omit `model_tier` by default so the runtime selects automatically. Include
   `model_tier: <user choice>` only when the user explicitly requested a tier.
   The call returns at once with `job_id`, `session_id`, and `execution_id`.

4. **Hand off.** Relay the server's start receipt (IDs, backends, `Efficiency Mode` with any change command, dashboard). Then add:
   - Live view: if `execution.tui_autolaunch: true` (or legacy top-level `tui_autolaunch: true`) is set, run `ouroboros tui open`; otherwise offer it once without blocking. If it prints a manual command (headless, SSH), relay that once.
   - Observation: a confirmed read-only observer (step 5), or durable catch-up mode.
   - This conversation stays available: the user can refine requirements, review code, or work on an unrelated task in an isolated worktree; check for active-worker conflicts before editing this run's workspace.

5. **Delegate observation to exactly one observer.** The start result carries
   `response.meta.job_observer`, a read-only observer contract with its own wait
   and result tools, `instructions`, `restrictions`, and fallback. If the
   structured meta is missing, recover the contract from the final
   `<!-- ouroboros-job-observer-v1 base64 ... -->` content sentinel and fail
   closed: if there is more than one sentinel or it is not at the end of the
   text, the bounded payload does not decode to an object whose only key is
   `job_observer`, that contract fails canonical v1 validation (it must equal,
   field for field, the v1 contract the server builds from its own `job_id`,
   `cursor`, `session_id`, `execution_id`, and `follow_result_job_keys`, so a
   changed tool, argument, or instruction, or an extra field, fails), its
   `job_id` differs from the visible start receipt, or the structured and inline
   contracts differ, do not spawn an observer and report a transport-integrity
   failure. Never rebuild the contract from visible IDs.

   With a valid contract and an independent child-session primitive, spawn
   exactly one observer through the active runtime's `orchestrate_subagents`
   capability and pass the contract unchanged. It owns the job cursor, follows
   the contract (including `follow_result_job_keys` for chained evaluation and
   Ralph), and stays read-only. Claim an observer only after the spawn returns
   a live child ID/path. The main session must not poll the same job while the
   observer owns it. If plugin mode already delegated the whole execution (no
   `job_id`), follow that child's lifecycle instead.

   - A `wait` call or a parent job-status poll is not a spawn. The contract's
     `host_lifecycle` and the runtime's `orchestrate_subagents` guidance name
     the concrete spawn and wait mechanics; pass the contract unchanged in the
     child message. After the live child ID returns, if the runtime cannot
     wake a parent turn that already ended when the child posts (a child
     message only queues for the parent), keep the parent turn open with the
     host's child-wait primitive in waits of at most 60 seconds. Relay
     meaningful updates and wait again until the terminal summary. User input may interrupt the wait; handle it and
     resume unless the user asks to stop live observation or replaces the
     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 early, use that same catch-up instead of waiting
     indefinitely. The relay loop must not poll Ouroboros job tools or touch the
     observer's cursor.

   If no child can be created, do not claim an observer or promise live
   messages. The detached worker survives the stdio MCP turn: say progress is
   durable and will be caught up on the next turn or an explicit status
   request. Keep the turn open only when the user explicitly asked for live
   watching (step 6).

   **Relaying observer events.** Relay each meaningful event in 1-2 lines;
   suppress unchanged heartbeats, raw tool output, commands, and reasoning.
   - `run_configuration`: runtime/harness, starting model or tier when known,
     efficiency mode, frugality assurance.
   - `execution_plan`: total ACs, dependency/parallel levels, and the first
     scheduled AC summaries.
   - `discovery_summary`: bounded targets and purpose.
   - `level_started` / `level_completed`, `ac_routing` / `harness_changed`
     ("currently running with"), `ac_attempt_judged`: only real changes.
   - `ac_accepted` / `ac_rejected`: the AC's final acceptance and compact
     disposition evidence.

From Q00/ouroboros, MIT.

More from Q00/ouroboros