ouroboros

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



O U R O B O R O S

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

Stop prompting. Start specifying.
_{A Claude Code plugin 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 — Install the plugin (in your terminal):

claude plugin marketplace add Q00/ouroboros
claude plugin install ouroboros@ouroboros

Step 2 — Run setup (inside a Claude Code session):

# Start Claude Code, then type:
ooo setup

ooo commands are Claude Code skills — they run inside a Claude Code session, not in your terminal. Setup registers the MCP server globally (one-time) and optionally adds an Ouroboros reference block to your project's CLAUDE.md.

Step 3 — Start building:

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

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.