Most AI coding tools fail before they write a single line of code. The prompt was vague, and the model quietly filled the gaps with assumptions you never agreed to.
You ask for "a task management CLI." The model picks a data model, a priority scheme, a persistence layer — all reasonable, none of them yours. You find out three files in, during review, and you rework it. That's the loop most of us are stuck in: prompt, guess, rework, repeat.
Ouroboros is an open-source Agent OS that fixes the input instead of the output. It's a local-first runtime layer that sits in front of Claude Code, Codex CLI, OpenCode, Gemini CLI, GitHub Copilot CLI, Kiro, Hermes, Pi, and Zcode, and replaces ad-hoc prompting with a five-stage, replayable workflow: interview, seed, execute, evaluate, evolve.
The real problem is unclear intent
Ouroboros' own framing of this is a simple table:
| Problem | What happens | Ouroboros fix |
|---|---|---|
| Vague prompts | AI guesses, you rework | Socratic interview exposes hidden assumptions |
| No spec | Architecture drifts mid-build | Immutable seed spec locks intent before code |
| Manual QA | "Looks good" isn't verification | 3-stage automated evaluation gate |
The fix targets clarity, not capability.
The loop
Interview -> Seed -> Execute -> Evaluate
^ |
+---- Evolutionary Loop ----+
- Interview: Socratic questioning surfaces the assumptions you didn't know you were making.
- Seed: your answers crystallize into an immutable specification: acceptance criteria, ontology, constraints.
- Execute: the seed runs through a Double Diamond decomposition (Discover → Define → Design → Deliver).
- Evaluate: a 3-stage gate: Mechanical (free, deterministic checks) → Semantic → Multi-Model Consensus.
- Evolve: the evaluation output feeds back into the next generation's seed, and the cycle repeats until the system stops learning anything new.
Each cycle is meant to converge, not just repeat. The stopping condition isn't a timer or a step count. It's math.
The interview ends when the math says so
This is the part I found most concrete. Ouroboros scores ambiguity as the inverse of weighted clarity across four dimensions (goal, constraints, success criteria, and context for existing codebases):
Ambiguity = 1 - Sum(clarity_i * weight_i)
A greenfield example from the README:
Goal: 0.9 * 0.4 = 0.36
Constraint: 0.8 * 0.3 = 0.24
Success: 0.7 * 0.3 = 0.21
------
Clarity = 0.81
Ambiguity = 1 - 0.81 = 0.19 <= 0.2 -> Ready for Seed
A Seed, the immutable spec that execution is built from, can't be generated until ambiguity drops to 0.2 or below. Above that threshold, you're still guessing at architecture, so the system keeps asking questions instead of letting you (or the agent) start writing code on a shaky foundation.
The evolutionary loop has a matching gate on the way out: it stops when ontology similarity between consecutive generations reaches 0.95, with separate detection for stagnation, oscillation, and repetitive feedback so it doesn't spin forever on a question it already answered.
Trying it
curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash
Then, inside a supported AI coding agent session:
> ooo interview "I want to build a task management CLI"
The installer auto-detects which supported runtime you're using (Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, Hermes, Gemini, Kiro CLI, Pi CLI, Zcode) and registers the MCP server where the host supports it. Everything after ooo interview (seed generation, execution, evaluation, the evolve loop) is driven from inside that same session. There's also a plain ouroboros CLI for running things from the terminal directly (ouroboros run seed.yaml, ouroboros status executions, and so on).
There's also ooo ralph, which runs the evolutionary loop persistently across session boundaries. If your machine restarts mid-loop, it reconstructs the lineage from an event store and picks up where it left off rather than starting over.
What this changes in practice
Ouroboros makes the input to your first try something you actually agreed to — a paper trail (the seed, the ledger, the evaluation stages) you can inspect afterward instead of reconstructing intent from a diff. It won't guarantee better code on the first attempt; it guarantees you know what you asked for.
If you've felt the specific pain of "the AI built something reasonable, just not the thing I meant," a spec-first loop like this is worth a look. It's MIT-licensed, Python 3.12+, and the repo has runtime guides for each supported CLI: github.com/Q00/ouroboros.
Top comments (1)
I like the choice to attack ambiguity before execution. The part I would want to see measured is whether the clarity score predicts fewer rollback cycles after the first seed, not just a cleaner prompt. If it does, that becomes a useful control surface rather than another prompting ritual.