ouroboros

◯ ─────────── ◯



O U R O B O R O S

◯ ─────────── ◯

Stop prompting. Start specifying.
_{A Codex-native workflow that turns vague ideas into validated specs — before AI writes a single line of code.}

Quick Start · Philosophy · How · Commands · Agents

AI can build anything. The hard part is knowing what to build.

Ouroboros is a specification-first AI development system. It applies Socratic questioning and ontological analysis to expose your hidden assumptions — before a single line of code is written.

Most AI coding fails at the input, not the output. The bottleneck isn't AI capability. It's human clarity. Ouroboros fixes the human, not the machine.

From Wonder to Ontology

Wonder → "How should I live?" → "What IS 'live'?" → Ontology — Socrates

This is the philosophical engine behind Ouroboros. Every great question leads to a deeper question — and that deeper question is always ontological: not "how do I do this?" but "what IS this, really?"

   Wonder                          Ontology
     💡                               🔬
"What do I want?"    →    "What IS the thing I want?"
"Build a task CLI"   →    "What IS a task? What IS priority?"
"Fix the auth bug"   →    "Is this the root cause, or a symptom?"

This is not abstraction for its own sake. When you answer "What IS a task?" — deletable or archivable? solo or team? — you eliminate an entire class of rework. The ontological question is the most practical question.

Ouroboros embeds this into its architecture through the Double Diamond:

    ◇ Wonder          ◇ Design
   ╱  (diverge)      ╱  (diverge)
  ╱    explore      ╱    create
 ╱                 ╱
◆ ──────────── ◆ ──────────── ◆
 ╲                 ╲
  ╲    define       ╲    deliver
   ╲  (converge)     ╲  (converge)
    ◇ Ontology        ◇ Evaluation

The first diamond is Socratic: diverge into questions, converge into ontological clarity. The second diamond is pragmatic: diverge into design options, converge into verified delivery. Each diamond requires the one before it — you cannot design what you haven't understood.

Quick Start

Step 1 — Set Codex auth (in your terminal):

export OPENAI_API_KEY="your-openai-key"

Step 2 — Install dependencies:

uv sync

Step 3 — Start building in a Codex session at this repo root:

ooo help
ooo interview "I want to build a task management CLI"
ooo seed
ooo run

Primary path docs: docs/running-with-codex.md

Legacy Claude Path (Optional)

Claude-specific setup is still available as a compatibility path: docs/running-with-claude-code.md

ooo interview  →  Socratic questioning exposed 12 hidden assumptions
ooo seed       →  Crystallized answers into an immutable spec (Ambiguity: 0.15)
ooo run        →  Executed via Double Diamond decomposition
ooo evaluate   →  3-stage verification: Mechanical → Semantic → Consensus

The Loop

The ouroboros — a serpent devouring its own tail — isn't decoration. It IS the architecture:

    Interview → Seed → Execute → Evaluate
        ↑                           ↓
        └──── Evolutionary Loop ────┘

Each cycle doesn't repeat — it evolves. The output of evaluation feeds back as input for the next generation, until the system truly knows what it's building.