evolve

name	evolve
description	Start or monitor an evolutionary development loop

ooo evolve - Evolutionary Loop

Description

Start, monitor, or rewind an evolutionary development loop. The loop iteratively refines the ontology and acceptance criteria across generations until convergence.

Flow

Gen 1: Interview → Seed(O₁) → Execute → Evaluate
Gen 2: Wonder → Reflect → Seed(O₂) → Execute → Evaluate
Gen 3: Wonder → Reflect → Seed(O₃) → Execute → Evaluate
...until ontology converges (similarity ≥ 0.95) or max 30 generations

Usage

Start a new evolutionary loop

ooo evolve "build a task management CLI"

Fast mode (ontology-only, no execution)

ooo evolve "build a task management CLI" --no-execute

Check lineage status

ooo evolve --status <lineage_id>

Rewind to a previous generation

ooo evolve --rewind <lineage_id> <generation_number>

Instructions

Load MCP Tools (Required before Path A/B decision)

The Ouroboros MCP tools are often registered as deferred tools that must be explicitly loaded before use. You MUST perform this step before deciding between Path A and Path B.

1. Use the active runtime's tool-discovery capability to find and load the evolve MCP tools:

   tool discovery query: "+ouroboros evolve"
   

2. The tools will typically be named with prefix mcp__plugin_ouroboros_ouroboros__ (e.g., ouroboros_evolve_step, ouroboros_interview, ouroboros_generate_seed). After runtime tool discovery returns, the tools become callable.
3. If the tools are callable — already exposed, or loaded by discovery — proceed to Path A. An empty discovery result for already-exposed tools is expected, not a failure. Proceed to Path B 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 ouroboros_* 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 ouroboros_* MCP tool while its schema is not loaded in the current turn, the runtime rejects the call with "Invalid tool parameters" before it ever reaches the server. Therefore: immediately before EVERY ouroboros_* MCP call in this skill, re-run the tool-discovery load query for the specific MCP tool or documented tool family you are about to call. Use "+ouroboros evolve" for ouroboros_evolve_step, ouroboros_lineage_status, and the evolve flow's documented tool family; use "+ouroboros interview" before ouroboros_interview, "+ouroboros seed" before ouroboros_generate_seed, and "+ouroboros lateral" before ouroboros_lateral_think. If a 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 / Path B instead of retrying the failing call.

Path A: MCP Available (loaded via runtime tool discovery above)

Starting a new evolutionary loop:

1. Parse the user's input as initial_context
2. Run the interview: call ouroboros_interview with initial_context
3. Complete the interview (3+ rounds until ambiguity ≤ 0.2)
4. Generate seed: call ouroboros_generate_seed with the session_id
5. Call ouroboros_evolve_step with:
   • lineage_id: new unique ID (e.g., lin_<seed_id>)
   • seed_content: the generated seed YAML
   • execute: true (default) for full Execute→Evaluate pipeline, false for fast ontology-only evolution (no seed execution)
6. Check the action in the response:
   • continue → Call ouroboros_evolve_step again with just lineage_id
   • converged → Evolution complete! Display final ontology
   • stagnated → Ontology unchanged for 3+ gens. Consider ouroboros_lateral_think
   • exhausted → Max 30 generations reached. Display best result
   • failed → Check error, possibly retry
7. Repeat step 6 until action ≠ continue
8. When the loop terminates, display a result summary with next step:
   • converged: 📍 Next: Ontology converged! Run ooo evaluate for formal verification
   • stagnated: 📍 Next: ooo unstuck to break through, then ooo evolve --status <lineage_id> to resume
   • exhausted: 📍 Next: ooo evaluate to check best result — or ooo unstuck to try a new approach
   • failed: 📍 Next: Check the error above. ooo status to inspect session, or ooo unstuck if blocked

Checking status:

1. Call ouroboros_lineage_status with the lineage_id
2. Display: generation count, ontology evolution, convergence progress

Rewinding:

1. Call ouroboros_evolve_step with:
   • lineage_id: the lineage to continue from a rewind point
   • seed_content: the seed YAML from the target generation (Future: dedicated ouroboros_evolve_rewind tool)

Path B: Plugin-only (no MCP tools available)

If MCP tools are not available, explain the evolutionary loop concept and suggest installing the Ouroboros MCP server. See Getting Started for install options, then run:

ouroboros mcp serve

Then add to your runtime's MCP configuration (e.g., ~/.claude/mcp.json for Claude Code).

Key Concepts

• Wonder: "What do we still not know?" - examines evaluation results to identify ontological gaps and hidden assumptions
• Reflect: "How should the ontology evolve?" - proposes specific mutations to fields, acceptance criteria, and constraints
• Convergence: Loop stops when ontology similarity ≥ 0.95 between consecutive generations, or after 30 generations max
• Rewind: Each generation is a snapshot. You can rewind to any generation and branch evolution from there
• evolve_step: Runs exactly ONE generation per call. Designed for Ralph integration — state is fully reconstructed from events between calls
• execute flag: true (default) runs full Execute→Evaluate each generation. false skips execution for fast ontology exploration. Previous generation's execution output is fed into Wonder/Reflect for informed evolution
• QA verdict: Each generation's response includes a QA Verdict section (when execute=true and skip_qa is not set). Use the QA score to track quality progression across generations. Pass skip_qa: true to disable