◯ ─────────── ◯
O U R O B O R O S
◯ ─────────── ◯
The serpent that devours itself to be reborn anew.
Philosophy • Phases • Architecture • Start • Personas
73 modules · 1,292 tests · 97%+ coverage
◈ The Premise
╔════════════════════════════════════════════════════════╗
║ ║
║ 「 HUMANS ARE NOT RATIONAL 」 ║
║ ║
╚════════════════════════════════════════════════════════╝
Human requirements arrive ambiguous, incomplete, contradictory, and surface-level.
If AI executes such input directly → `GIGO…
◯ ─────────── ◯
O U R O B O R O S
◯ ─────────── ◯
The serpent that devours itself to be reborn anew.
Philosophy • Phases • Architecture • Start • Personas
73 modules · 1,292 tests · 97%+ coverage
◈ The Premise
╔════════════════════════════════════════════════════════╗
║ ║
║ 「 HUMANS ARE NOT RATIONAL 」 ║
║ ║
╚════════════════════════════════════════════════════════╝
Human requirements arrive ambiguous, incomplete, contradictory, and surface-level.
If AI executes such input directly → GIGO (Garbage In, Garbage Out).
◈ Philosophy
The Two Ancient Methods
To transmute irrational input into executable truth, we invoke:
| #### ⌬ SOCRATIC QUESTIONING |
"Why do you want this?"
"What if you don't get it?"
"Is that truly necessary?"
"What are you assuming?"
↳ Reveals hidden assumptions
↳ Exposes contradictions
↳ Challenges the obvious
| #### ⌬ ONTOLOGICAL ANALYSIS
"What IS this, really?"
"Symptom or root cause?"
"What's the essence?"
"What must exist first?"
↳ Finds the root problem
↳ Separates essential from accidental
↳ Maps the structure of being
|
These iterate until a Seed crystallizes—a specification with Ambiguity ≤ 0.2.
Only then does execution begin. Only then can it succeed.
The Governing Principle
╭────────────────────────────────────────────────────────────╮
│ │
│ │
│ 「 FRUGAL BY DEFAULT, RIGOROUS IN VERIFICATION 」 │
│ │
│ │
╰────────────────────────────────────────────────────────────╯
| Paradox | Problem | Ouroboros Solution |
|---|---|---|
| Power without Wisdom | Frontier models cost 30x | Start at 1x, escalate only when needed |
| Speed without Judgment | Fast models miss nuance | 3-stage evaluation catches errors |
| Iteration without Direction | Infinite loops | Drift detection + Retrospective |
◈ The Six Phases
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ┃
┃ ┃
┃ ┌─────────┐ ┃
┃ │ PHASE 0 │ B I G B A N G ┃
┃ └────┬────┘ ┃
┃ │ Socratic + Ontological questioning ┃
┃ │ From irrational chaos → crystallized Seed ┃
┃ │ Gate: Ambiguity ≤ 0.2 ┃
┃ ▼ ┃
┃ ┌─────────┐ ┃
┃ │ PHASE 1 │ P A L R O U T E R ┃
┃ └────┬────┘ ┃
┃ │ Progressive Adaptive LLM selection ┃
┃ │ 1x (Frugal) → 10x (Standard) → 30x (Frontier) ┃
┃ │ "Choose your weapon wisely" ┃
┃ ▼ ┃
┃ ┌─────────┐ ┃
┃ │ PHASE 2 │ D O U B L E D I A M O N D ┃
┃ └────┬────┘ ┃
┃ │ Discover → Define → Design → Deliver ┃
┃ │ Diverge to explore, converge to execute ┃
┃ │ Recursive decomposition until atomic ┃
┃ ▼ ┃
┃ ┌─────────┐ ┃
┃ │ PHASE 3 │ R E S I L I E N C E ┃
┃ └────┬────┘ ┃
┃ │ Stagnation detection (4 patterns) ┃
┃ │ Lateral thinking via persona rotation ┃
┃ │ "When stuck, think sideways" ┃
┃ ▼ ┃
┃ ┌─────────┐ ┃
┃ │ PHASE 4 │ E V A L U A T I O N ┃
┃ └────┬────┘ ┃
┃ │ Stage 1: Mechanical ($0) — lint, build, test ┃
┃ │ Stage 2: Semantic ($$) — AC compliance, drift ┃
┃ │ Stage 3: Consensus ($$$$) — multi-model vote ┃
┃ ▼ ┃
┃ ┌─────────┐ ┃
┃ │ PHASE 5 │ S E C O N D A R Y L O O P ┃
┃ └────┬────┘ ┃
┃ │ TODO Registry: defer the trivial ┃
┃ │ Batch processing after primary goal ┃
┃ │ "Pursue the essential" ┃
┃ │ ┃
┃ ╰─────────────────────────── ↺ ──────────────────────────────────────┃
┃ ┃
┃ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
◈ Economic Model
Intelligence has a cost. Ouroboros optimizes it.
| Tier | Cost | When | Philosophy |
|---|---|---|---|
FRUGAL | 1x | complexity < 0.4 | "Most problems are simpler than they appear" |
STANDARD | 10x | complexity < 0.7 | "Pay for quality when it matters" |
FRONTIER | 30x | critical decisions | "Some choices cannot be undone" |
def select_approach(task):
if task.complexity < 0.4:
return Tier.FRUGAL # Start humble
if task.reversible:
return Tier.STANDARD # Move fast
if task.affects_direction:
return Tier.FRONTIER # Think deeply
return Tier.STANDARD
Result: ~85% cost reduction compared to "always use the best model"
◈ Architecture
src/ouroboros/
│
├── core/ ◆ The essence: types, errors, seed, context
│
├── bigbang/ ◇ Phase 0: Interview → Ambiguity → Seed
│
├── routing/ ◇ Phase 1: PAL router, complexity, tiers
│
├── execution/ ◇ Phase 2: Double Diamond, decomposition
│
├── resilience/ ◇ Phase 3: Stagnation, lateral thinking
│
├── evaluation/ ◇ Phase 4: Mechanical, semantic, consensus
│
├── secondary/ ◇ Phase 5: TODO registry, batch scheduler
│
├── orchestrator/ ★ Claude Agent SDK integration
│
├── observability/ ○ Drift control, retrospective, logging
│
├── persistence/ ○ Event sourcing, checkpoints, recovery
│
├── providers/ ○ LiteLLM adapter (100+ models)
│
└── cli/ ○ Command-line interface
◈ The Personas (Lateral Thinking Agents)
When stuck, the system doesn’t retry harder. It switches persona and thinks differently.
| Persona | Strategy | Trigger | Behavior |
|---|---|---|---|
| THE HACKER | "Elegance be damned. Make it work." | Quick fix needed | Hardcode, skip abstractions, brute force |
| THE RESEARCHER | "Stop coding. Read the docs." | Knowledge gap detected | Search, read documentation, find examples |
| THE SIMPLIFIER | "Cut scope in half. Return to MVP." | Overengineering detected | Remove features, reduce complexity |
| THE ARCHITECT | "Question the foundation. Rebuild if needed." | Structural issues | Redesign, refactor core assumptions |
작동 방식: Stagnation Detection (4 patterns) → Persona Rotation → 새로운 관점으로 재시도
◈ The Eternal Cycle
┌─────────────────────────┐
│ │
▼ │
┌───────────────────┐ │
│ │ │
│ S E E D │ │
│ Ambiguity ≤ 0.2 │ │
│ │ │
└─────────┬─────────┘ │
│ │
▼ │
┌───────────────────┐ │
│ │ │
│ E X E C U T E │ │
│ PAL → Diamond │ │
│ │ │
└─────────┬─────────┘ │
│ │
▼ │
┌───────────────────┐ │
│ │ │
│ RETROSPECTIVE │ │
│ Every 3 cycles │ │
│ │ │
└─────────┬─────────┘ │
│ │
┌───────┴───────┐ │
▼ ▼ │
│
Drift OK Drift High │
│ │ │
▼ │ │
Continue ╰────────────────┘
Re-examine Seed
The system doesn’t blindly loop. It questions its own direction.
When drift exceeds threshold, it returns to the beginning— not to restart, but to re-crystallize with new understanding.
◈ Installation
pip install ouroboros-ai
# or
uv pip install ouroboros-ai
◈ Quick Start
Using Claude Code Max Plan (Recommended)
No API key required — uses your Claude Code subscription directly.
# Begin the Big Bang (interactive interview)
ouroboros init start --orchestrator "I want to build a task management CLI"
# Execute via Claude Agent SDK
ouroboros run workflow --orchestrator seed.yaml
From Source (Development)
# Clone
git clone https://github.com/Q00/ouroboros
cd ouroboros
# Install
uv sync
# Begin the Big Bang (interactive interview)
uv run ouroboros init start --orchestrator "I want to build a task management CLI"
# Execute via Claude Agent SDK
uv run ouroboros run workflow --orchestrator seed.yaml
Using External LLM (LiteLLM)
Requires API key (OPENROUTER_API_KEY, ANTHROPIC_API_KEY, etc.)
# Begin the Big Bang
uv run ouroboros init start "I want to build a task management CLI"
# Check status
uv run ouroboros status health
◈ Anti-Patterns
What we explicitly reject:
| ✗ Anti-Pattern | Problem | ✓ Our Solution |
|---|---|---|
| Consensus Everywhere | Cost explosion | Gate-only consensus |
| Frontier First | Wasteful | Frugal first, escalate |
| Infinite Retry | Stagnation | Lateral thinking |
| Immediate Optimization | Yak shaving | TODO registry (defer) |
| Vague Seeds | GIGO | Ambiguity ≤ 0.2 |
◈ Development
# Install all dependencies
uv sync --all-groups
# Run tests
uv run pytest
# Type checking
uv run mypy src/
# Lint
uv run ruff check src/
# Format
uv run ruff format src/
◈ Roadmap
[■■■■■■■■■■] Epic 0 Foundation
[■■■■■■■■■■] Epic 1 Big Bang
[■■■■■■■■■■] Epic 2 PAL Router
[■■■■■■■■■■] Epic 3 Double Diamond
[■■■■■■■■■■] Epic 4 Resilience
[■■■■■■■■■■] Epic 5 Evaluation
[■■■■■■■■■■] Epic 6 Drift Control
[■■■■■■■■■■] Epic 7 Secondary Loop
[■■■■■■■■■■] Epic 8 Orchestrator ✓ Complete
◈ Why "Ouroboros"?
╭──────────╮
╭───╯ ╰───╮
╭─╯ ╰─╮
╭╯ ◯ ← ◯ ╰╮
│ ↗ ↘ │
│ ◯ ⚬ ◯ │
│ ↖ ↙ │
╰╮ ◯ → ◯ ╭╯
╰─╮ ╭─╯
╰───╮ ╭───╯
╰──────────╯
The serpent that devours itself to be reborn.
The ouroboros has symbolized eternal cycles of renewal for millennia.
Software development is no different:
Write → Test → Fail → Learn → Rewrite → Test → ...
The question is not whether to iterate, but how to iterate wisely.
Ouroboros answers:
- Start with truth — Socratic questioning extracts essence
- Be frugal in execution — Don’t waste intelligence on simple problems
- Be rigorous in verification — Critical decisions need consensus
- Trust the cycle — Let the serpent eat its tail and be reborn
"The beginning is the end, and the end is the beginning."
MIT License