Specification-first AI development with Ouroboros

Q00

Posted on Aug 9 • Edited on Aug 10

Disclosure: I work on this project. Every number below was read out of the source, and I have included the file and line so you can check it rather than take my word for it.

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 ----+

Enter fullscreen mode Exit fullscreen mode

• 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)

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

Above 0.2 the system keeps asking instead of letting you start on a foundation it thinks is shaky. The threshold is 0.20 at auto/interview_driver.py:125, and the weights are 0.40 / 0.30 / 0.30 at bigbang/ambiguity.py:48-50.

You can overrule it. Passing force=true bypasses the gate deliberately, and the code says so in as many words: “force=True intentionally bypasses BOTH the ambiguity threshold” (mcp/tools/authoring_handlers.py:1378). So this is a default that argues with you, not a lock. I think that is the right call, because a gate you cannot override eventually gets worked around in worse ways. But it does mean the guarantee is softer than “it will not let you.”

The evolutionary loop has a matching gate on the way out. It converges when ontology similarity between the last two generations reaches 0.95, and only if that generation’s evaluation was approved: high similarity with a rejected evaluation does not count (evolution/convergence.py:144, :148). A separate detector watches for stagnation: if that similarity sits unchanged for three straight generations, the loop stops as “not progressing” rather than calling it converged (convergence.py:54), and oscillation and repetitive-feedback detection run alongside so it doesn’t spin on a question it already answered.

The weights are hardcoded. 40% goal, 30% constraints, 30% success criteria. That is somebody’s judgment call rather than a derived constant, and it is worth knowing that before you trust the number. What I like is that it is an arbitrary you can go read and recompute, instead of one buried in a prompt.

How it actually runs

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 the terminal directly (ouroboros run seed.yaml, ouroboros status executions, and so on).

ooo ralph runs the evolutionary loop 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 it does not fix

It will not make the first attempt better code. The model is the same model. What changes is that the input to that attempt is something you agreed to out loud, and there is a paper trail (the seed, the ledger, the evaluation stages) to read afterward instead of reconstructing what you meant from a diff.

It also costs you the thing some people came for. If your actual want is to type one line and walk away, an interview that keeps asking is friction, and calling that friction a feature does not make it stop being friction. The bet is that the questions are cheaper than the rework. That bet is wrong for a throwaway script and I would not use it there.

Try the part that takes 30 seconds

You do not have to install anything to judge the idea. Open the scoring code and see whether you agree with the weights:

bigbang/ambiguity.py:48-50: 40% goal, 30% constraints, 30% success criteria.

If you want to run it:

curl -fsSL https://raw.githubusercontent.com/Q00/ouroboros/main/scripts/install.sh | bash

Enter fullscreen mode Exit fullscreen mode

Then, inside your agent session:

> ooo interview "I want to build a task management CLI"

Enter fullscreen mode Exit fullscreen mode

The interview is the whole pitch. If it asks you something you had not decided yet, that is the product working. If it asks you three things you had already written in the prompt, that is a bug and I would like to see the transcript.

MIT, Python 3.12+, runtime guides per CLI: github.com/Q00/ouroboros.

The question I actually want answered

Everybody agrees vague prompts are the problem. Almost nobody agrees on who should fix it. Three positions I keep running into:

1. The model should ask. Clarification is the model’s job and a harness that does it is a workaround for a weak model.
2. The harness should ask, because you want the same questions every time regardless of which model is behind it.
3. Neither should ask. Write a better prompt.

I built around position 2 and the ambiguity score is what that position looks like in code. If you hold 1 or 3, I would rather hear the argument than the star.

Where do you catch it today? During the interview, at review, or three files in?