Q00/ouroboros

# /ouroboros:auto

Run the full-quality auto pipeline from a single task description.

## Dispatch requirement

This skill must be executed by invoking MCP tool `ouroboros_start_auto`. Do not
manually inspect repositories, run shell commands, query GitHub, edit files, or
otherwise emulate the auto pipeline. The background starter returns `job_id`
and `auto_session_id` quickly; retain both. If `ouroboros_start_auto` or a
required job wait/result tool is unavailable, stop and report that the required
MCP tool is unavailable. A manual fallback is not an `ooo auto` run.

If a started auto job returns `detached`, `blocked`, `failed`, or another

# /ouroboros:brownfield

Manage the registry of existing git repositories and linked worktrees, and the default repos used as interview context. The registry lives in the Ouroboros DB: listing, defaults, and search read it and never walk the filesystem. Only `scan` walks the disk.

```
ooo brownfield                # List registered repos and set defaults (scans only if none are registered)
ooo brownfield scan           # Rescan the scan root and refresh the search index
ooo brownfield defaults       # Show current defaults
ooo brownfield find <topic>   # Rank registered repos by relevance to a topic
ooo brownfield set 6,18,19    # Set defaults by repo numbers
ooo brownfield detect [path]  # Author mechanical.toml via one AI call
```

## Loading MCP tools (deferred-schema guard)

# /ouroboros:cancel

Cancel stuck or orphaned executions and background jobs through the Ouroboros MCP tools, which work on hosts without shell access.

```
/ouroboros:cancel                 # list this project's active executions, ask which to cancel
/ouroboros:cancel <id>            # cancel one execution (orch_... or execution id) or job (job_...)
/ouroboros:cancel --all           # cancel every running or paused execution of this project
```

## Instructions

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

# /ouroboros:ouroboros-config

Edit `~/.ouroboros/config.yaml`: global and per-stage runtime and model choices, the LLM backend, install badges for missing CLIs, and env-override warnings.

```
ooo config
/ouroboros:ouroboros-config
```

## Instructions

Pick the branch by one question: **can the user open a browser pointed at this machine?** Run commands with the active runtime's `run_shell` capability.

### Branch A: local harness on the user's own machine

# /ouroboros:evaluate

Evaluate an execution session with the three-stage verification pipeline.

```
/ouroboros:evaluate <session_id> [artifact]
```

## Stage authority

1. **Mechanical** (lint, build, test, static analysis, coverage; no model cost): the only stage that can grant approval. At least one configured check must run and all must pass.
2. **Semantic** (AC compliance, goal alignment, drift): advisory. Can withhold approval and give feedback; cannot grant it.
3. **Consensus** (multi-model, only on uncertainty or request): advisory. A rejection withholds approval; an approval cannot grant it or lift a Stage 2 block.

# ooo evolve - Evolutionary Loop

Start, monitor, or rewind an evolutionary loop that refines the ontology and acceptance criteria across generations.

```
Gen 1: Seed → Execute(all ACs) → Judge → Gate
Gen 2+: Wonder(failed ACs) → Reflect(active ACs only) → Execute(active) → Gate(all)
...until the gate passes, the loop stagnates, or 30 generations are reached
```

## Usage

```
ooo evolve "build a task management CLI"              # start

# /ouroboros:ouroboros-help

Full reference guide for Ouroboros power users.

## Usage

```
ooo help
/ouroboros:ouroboros-help
```

## What Is Ouroboros?

A specification-first workflow engine: it turns vague ideas into a validated

# /ouroboros:idk

Calibrate the language used by `ooo interview` without weakening the interview itself.

## Usage

```text
ooo idk <terms I do not know, or what I understand about them>
/ouroboros:idk <terms I do not know, or what I understand about them>
```

Examples:

```text

# /ouroboros:interview

Socratic interview that turns a vague request into the goals, constraints, and acceptance criteria a Seed needs.

## Required Skill Capabilities

- `ask_user`: ask human-judgment questions through the active runtime's `ask_user` capability.
- `inspect_code`: answer repo-local factual questions from exact local files before asking the user.
- `call_mcp`: use Ouroboros MCP tools for persistent interview state and seed generation.
- `orchestrate_subagents`: run advisory lanes and the Seed-ready Acceptance Guard lanes.
- `run_lateral_review`: invoke lateral thinking subagents before milestone turns and direct-answer synthesis.
- `web_research`: fetch current external facts only when the interview genuinely depends on them.
- `refine_answer`: confirm structured interpretations of free-text answers before forwarding them (Refine gate).
- `maintain_ledger`: keep ambiguity, gates, and unresolved decisions visible in the main session.

# Start Ouroboros

Read `../welcome/SKILL.md` and follow its instructions exactly. This is the
explicit Marketplace-plugin entry point for a bare `ooo` message before any
runtime-specific setup has run.

## RFC #1392 State Breadcrumb Footer

Your final response MUST end with exactly one breadcrumb footer line:

```
◆ <current state> → next: <recommended action>
```

# /ouroboros:pm

PM-focused Socratic interview that produces a Product Requirements Document (PRD).

## Required Skill Capabilities

- `ask_user`: ask the user through the active runtime's `ask_user` capability.
- `call_mcp`: `ouroboros_pm_interview` holds the interview state and writes the PRD.
- `orchestrate_subagents`: run the evidence lanes each question carries.
- `refine_answer`: confirm the structured answer before it is sent (Refine gate).
- `run_shell`: copy the finished PRD to the clipboard, when available.

## Instructions

# /ouroboros:publish

Convert a Seed into a GitHub Epic issue plus Task issues. Works entirely through the `gh` CLI (no MCP), creates new issues only, and never modifies existing ones.

```
ooo publish [seed_path]
/ouroboros:publish [seed_path]
```

## Instructions

Run commands with the active runtime's `run_shell` capability and ask every question with the active runtime's `ask_user` capability.

### Step 1: Prerequisites

# /ouroboros:qa

Fast single-pass quality verdict with actionable suggestions for any artifact: code, documents, API responses, test output, or custom content. For formal three-stage verification of an execution, use `ooo evaluate`.

```
ooo qa [file_path | artifact_text]
ooo qa                                     # recent execution output
/ouroboros:qa [file_path | artifact_text]
```

The QA Judge scores the artifact against a quality bar on Correctness, Completeness, Quality, Intent Alignment, and Domain-Specific dimensions:

| Score | Verdict | Loop action |
|-------|---------|-------------|

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

The `ouroboros_ralph` tool owns the loop (do not reimplement it): one background job runs repeated `evolve_step` generations until QA pass, convergence, a terminal evolution action, cancellation, or `max_generations`. Router dispatch reads only the named `--lineage-id` option, never trailing text.

## Instructions

# /ouroboros:resume-session

Recover in-flight Ouroboros sessions after an unexpected MCP server disconnect. The name avoids shadowing Claude Code's built-in `/resume`.

```
ooo resume-session [--all]
/ouroboros:resume-session
```

## Instructions

1. Run with the active runtime's `run_shell` capability:

   ```

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

Generate a validated Seed specification from an interview or from requirements this conversation already settled.

## Required Skill Capabilities

`ask_user` (the active runtime's user-question surface), `inspect_code`, `call_mcp`, `orchestrate_subagents` (lateral persona payloads), `run_shell` (audit-trail and prefs writes), `refine_answer` (confirm free-form decisions), `maintain_ledger` (QA scores, candidate decisions, rejected proposals).

## Usage

```
ooo seed [session_id]
/ouroboros:seed [session_id]
```

# /ouroboros:setup

Guided Ouroboros setup inside a Claude Code session.

> Other runtimes (Codex, Copilot, OpenCode, and others) configure through the
> CLI instead, for example `ouroboros setup --runtime codex` or
> `ouroboros setup --runtime copilot`. See
> [Getting Started](https://github.com/Q00/ouroboros/blob/main/docs/getting-started.md).

## Usage

```
ooo setup
/ouroboros:setup

# /ouroboros:ouroboros-status

Check an execution session's status and, on request, measure drift from the Seed goal.

```
/ouroboros:ouroboros-status [session_id]
```

## 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 session status"` for `ouroboros_session_status` and `ouroboros_measure_drift`. 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 only when the tool is genuinely absent.

# /ouroboros:tutorial

Interactive tutorial that teaches Ouroboros through hands-on experience.

## Usage

```
ooo tutorial
/ouroboros:tutorial
```

## Principles

1. Show something useful in the first 30 seconds.

# /ouroboros:unstuck

Break through stagnation, or advise on a hard choice, with lateral thinking personas. **Solo** runs one persona; **debate** runs several in parallel and synthesizes them.

## Usage

```
ooo lateral                       # debate: all 5 lateral personas
ooo lateral <persona>             # solo: one persona
ooo lateral debate <p1> <p2> ...  # debate with explicit members
ooo lateral @all                  # debate preset (the only preset)
```

## Personas (lateral pool)

# /ouroboros:update

Upgrade Ouroboros without changing the installation's manager, environment, or optional-dependency profile.

```
ooo update
/ouroboros:update
```

## Instructions

The native command is the single source of truth. Run it with the active runtime's `run_shell` capability.

1. Run `ouroboros update --check`.

# /ouroboros:welcome

Interactive onboarding for new Ouroboros users.

## Usage

```
/ouroboros:welcome              # First-time or update onboarding
/ouroboros:welcome --skip       # Skip welcome, mark as shown
/ouroboros:welcome --force      # Force re-run welcome even if shown
```

## Instructions

# Run

This fixture keeps dispatch metadata in YAML frontmatter while the markdown
body contains text that looks similar enough to catch accidental whole-file
parsing.

```yaml
mcp_tool: body_should_not_be_loaded
mcp_args:
  seed_path: body-value
  cwd: body-cwd
aliases:
  - body-alias
```