{"id":42428198,"url":"https://github.com/q00/ouroboros","last_synced_at":"2026-05-06T07:05:28.028Z","repository":{"id":333815590,"uuid":"1133901637","full_name":"Q00/ouroboros","owner":"Q00","description":"Stop prompting. Start specifying.","archived":false,"fork":false,"pushed_at":"2026-02-23T18:41:15.000Z","size":1283,"stargazers_count":23,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-23T22:52:05.986Z","etag":null,"topics":["claude-code","claude-code-plugin","skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Q00.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-14T01:14:04.000Z","updated_at":"2026-02-23T18:41:18.000Z","dependencies_parsed_at":"2026-02-23T17:05:02.171Z","dependency_job_id":null,"html_url":"https://github.com/Q00/ouroboros","commit_stats":null,"previous_names":["q00/ouroboros"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/Q00/ouroboros","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Q00%2Fouroboros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Q00%2Fouroboros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Q00%2Fouroboros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Q00%2Fouroboros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Q00","download_url":"https://codeload.github.com/Q00/ouroboros/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Q00%2Fouroboros/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29929587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T09:58:13.507Z","status":"ssl_error","status_checked_at":"2026-02-28T09:57:57.047Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","claude-code-plugin","skills"],"created_at":"2026-01-28T03:32:50.318Z","updated_at":"2026-02-28T10:02:12.717Z","avatar_url":"https://github.com/Q00.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cbr/\u003e\n  ◯ ─────────── ◯\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cimg src=\"./docs/images/ouroboros.png\" width=\"520\" alt=\"Ouroboros\"\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cstrong\u003eO U R O B O R O S\u003c/strong\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  ◯ ─────────── ◯\n  \u003cbr/\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStop prompting. Start specifying.\u003c/strong\u003e\n  \u003cbr/\u003e\n  \u003csub\u003eA Claude Code plugin that turns vague ideas into validated specs — before AI writes a single line of code.\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/ouroboros-ai/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/ouroboros-ai?color=blue\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/Q00/ouroboros/actions/workflows/test.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/Q00/ouroboros/test.yml?branch=main\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#from-wonder-to-ontology\"\u003ePhilosophy\u003c/a\u003e ·\n  \u003ca href=\"#the-loop\"\u003eHow\u003c/a\u003e ·\n  \u003ca href=\"#commands\"\u003eCommands\u003c/a\u003e ·\n  \u003ca href=\"#the-nine-minds\"\u003eAgents\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e *AI can build anything. The hard part is knowing what to build.*\n\nOuroboros 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.\n\nMost 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.\n\n---\n\n## From Wonder to Ontology\n\n\u003e *Wonder → \"How should I live?\" → \"What IS 'live'?\" → Ontology*\n\u003e — Socrates\n\nThis 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?\"*\n\n```\n   Wonder                          Ontology\n     💡                               🔬\n\"What do I want?\"    →    \"What IS the thing I want?\"\n\"Build a task CLI\"   →    \"What IS a task? What IS priority?\"\n\"Fix the auth bug\"   →    \"Is this the root cause, or a symptom?\"\n```\n\nThis 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.**\n\nOuroboros embeds this into its architecture through the **Double Diamond**:\n\n```\n    ◇ Wonder          ◇ Design\n   ╱  (diverge)      ╱  (diverge)\n  ╱    explore      ╱    create\n ╱                 ╱\n◆ ──────────── ◆ ──────────── ◆\n ╲                 ╲\n  ╲    define       ╲    deliver\n   ╲  (converge)     ╲  (converge)\n    ◇ Ontology        ◇ Evaluation\n```\n\nThe 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.\n\n---\n\n## Quick Start\n\n```bash\n# Install\nclaude plugin marketplace add Q00/ouroboros\nclaude plugin install ouroboros@ouroboros\n\n# One-time setup\nooo setup\n\n# Question everything\nooo interview \"I want to build a task management CLI\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat just happened?\u003c/strong\u003e\u003c/summary\u003e\n\n```\nooo interview  →  Socratic questioning exposed 12 hidden assumptions\nooo seed       →  Crystallized answers into an immutable spec (Ambiguity: 0.15)\nooo run        →  Executed via Double Diamond decomposition\nooo evaluate   →  3-stage verification: Mechanical → Semantic → Consensus\n```\n\nThe serpent completed one loop. Each loop, it knows more than the last.\n\n\u003c/details\u003e\n\n---\n\n## The Loop\n\nThe ouroboros — a serpent devouring its own tail — isn't decoration. It IS the architecture:\n\n```\n    Interview → Seed → Execute → Evaluate\n        ↑                           ↓\n        └──── Evolutionary Loop ────┘\n```\n\nEach 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.\n\n| Phase | What Happens |\n|:------|:-------------|\n| **Interview** | Socratic questioning exposes hidden assumptions |\n| **Seed** | Answers crystallize into an immutable specification |\n| **Execute** | Double Diamond: Discover → Define → Design → Deliver |\n| **Evaluate** | 3-stage gate: Mechanical ($0) → Semantic → Multi-Model Consensus |\n| **Evolve** | Wonder *(\"What do we still not know?\")* → Reflect → next generation |\n\n\u003e *\"This is where the Ouroboros eats its tail: the output of evaluation*\n\u003e *becomes the input for the next generation's seed specification.\"*\n\u003e — `reflect.py`\n\nConvergence is reached when ontology similarity ≥ 0.95 — when the system has questioned itself into clarity.\n\n### Ralph: The Loop That Never Stops\n\n`ooo ralph` runs the evolutionary loop persistently — across session boundaries — until convergence is reached. Each step is **stateless**: the EventStore reconstructs the full lineage, so even if your machine restarts, the serpent picks up where it left off.\n\n```\nRalph Cycle 1: evolve_step(lineage, seed) → Gen 1 → action=CONTINUE\nRalph Cycle 2: evolve_step(lineage)       → Gen 2 → action=CONTINUE\nRalph Cycle 3: evolve_step(lineage)       → Gen 3 → action=CONVERGED ✓\n                                                └── Ralph stops.\n                                                    The ontology has stabilized.\n```\n\n### Ambiguity Score: The Gate Between Wonder and Code\n\nThe Interview doesn't end when you feel ready — it ends when the **math** says you're ready. Ouroboros quantifies ambiguity as the inverse of weighted clarity:\n\n```\nAmbiguity = 1 − Σ(clarityᵢ × weightᵢ)\n```\n\nEach dimension is scored 0.0–1.0 by the LLM (temperature 0.1 for reproducibility), then weighted:\n\n| Dimension | Greenfield | Brownfield |\n|:----------|:----------:|:----------:|\n| **Goal Clarity** — *Is the goal specific?* | 40% | 35% |\n| **Constraint Clarity** — *Are limitations defined?* | 30% | 25% |\n| **Success Criteria** — *Are outcomes measurable?* | 30% | 25% |\n| **Context Clarity** — *Is the existing codebase understood?* | — | 15% |\n\n**Threshold: Ambiguity ≤ 0.2** — only then can a Seed be generated.\n\n```\nExample (Greenfield):\n\n  Goal: 0.9 × 0.4  = 0.36\n  Constraint: 0.8 × 0.3  = 0.24\n  Success: 0.7 × 0.3  = 0.21\n                        ──────\n  Clarity             = 0.81\n  Ambiguity = 1 − 0.81 = 0.19  ≤ 0.2 → ✓ Ready for Seed\n```\n\nWhy 0.2? Because at 80% weighted clarity, the remaining unknowns are small enough that code-level decisions can resolve them. Above that threshold, you're still guessing at architecture.\n\n### Ontology Convergence: When the Serpent Stops\n\nThe evolutionary loop doesn't run forever. It stops when consecutive generations produce ontologically identical schemas. Similarity is measured as a weighted comparison of schema fields:\n\n```\nSimilarity = 0.5 × name_overlap + 0.3 × type_match + 0.2 × exact_match\n```\n\n| Component | Weight | What It Measures |\n|:----------|:------:|:-----------------|\n| **Name overlap** | 50% | Do the same field names exist in both generations? |\n| **Type match** | 30% | Do shared fields have the same types? |\n| **Exact match** | 20% | Are name, type, AND description all identical? |\n\n**Threshold: Similarity ≥ 0.95** — the loop converges and stops evolving.\n\nBut raw similarity isn't the only signal. The system also detects pathological patterns:\n\n| Signal | Condition | What It Means |\n|:-------|:----------|:--------------|\n| **Stagnation** | Similarity ≥ 0.95 for 3 consecutive generations | Ontology has stabilized |\n| **Oscillation** | Gen N ≈ Gen N-2 (period-2 cycle) | Stuck bouncing between two designs |\n| **Repetitive feedback** | ≥ 70% question overlap across 3 generations | Wonder is asking the same things |\n| **Hard cap** | 30 generations reached | Safety valve |\n\n```\nGen 1: {Task, Priority, Status}\nGen 2: {Task, Priority, Status, DueDate}     → similarity 0.78 → CONTINUE\nGen 3: {Task, Priority, Status, DueDate}     → similarity 1.00 → CONVERGED ✓\n```\n\nTwo mathematical gates, one philosophy: **don't build until you're clear (Ambiguity ≤ 0.2), don't stop evolving until you're stable (Similarity ≥ 0.95).**\n\n---\n\n## Commands\n\n\u003e Run `ooo setup` first after installation. All commands require it.\n\n| Command | What It Does |\n|:--------|:-------------|\n| `ooo setup` | Register MCP server (one-time) |\n| `ooo interview` | Socratic questioning → expose hidden assumptions |\n| `ooo seed` | Crystallize into immutable spec |\n| `ooo run` | Execute via Double Diamond decomposition |\n| `ooo evaluate` | 3-stage verification gate |\n| `ooo evolve` | Evolutionary loop until ontology converges |\n| `ooo unstuck` | 5 lateral thinking personas when you're stuck |\n| `ooo status` | Drift detection + session tracking |\n| `ooo ralph` | Persistent loop until verified |\n| `ooo tutorial` | Interactive hands-on learning |\n| `ooo help` | Full reference |\n\n---\n\n## The Nine Minds\n\nNine agents, each a different mode of thinking. Loaded on-demand, never preloaded:\n\n| Agent | Role | Core Question |\n|:------|:-----|:--------------|\n| **Socratic Interviewer** | Questions-only. Never builds. | *\"What are you assuming?\"* |\n| **Ontologist** | Finds essence, not symptoms | *\"What IS this, really?\"* |\n| **Seed Architect** | Crystallizes specs from dialogue | *\"Is this complete and unambiguous?\"* |\n| **Evaluator** | 3-stage verification | *\"Did we build the right thing?\"* |\n| **Contrarian** | Challenges every assumption | *\"What if the opposite were true?\"* |\n| **Hacker** | Finds unconventional paths | *\"What constraints are actually real?\"* |\n| **Simplifier** | Removes complexity | *\"What's the simplest thing that could work?\"* |\n| **Researcher** | Stops coding, starts investigating | *\"What evidence do we actually have?\"* |\n| **Architect** | Identifies structural causes | *\"If we started over, would we build it this way?\"* |\n\n---\n\n## Under the Hood\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e18 packages · 166 modules · 95 test files · Python 3.14+\u003c/strong\u003e\u003c/summary\u003e\n\n```\nsrc/ouroboros/\n├── bigbang/        Interview, ambiguity scoring, brownfield explorer\n├── routing/        PAL Router — 3-tier cost optimization (1x / 10x / 30x)\n├── execution/      Double Diamond, hierarchical AC decomposition\n├── evaluation/     Mechanical → Semantic → Multi-Model Consensus\n├── evolution/      Wonder / Reflect cycle, convergence detection\n├── resilience/     4-pattern stagnation detection, 5 lateral personas\n├── observability/  3-component drift measurement, auto-retrospective\n├── persistence/    Event sourcing (SQLAlchemy + aiosqlite), checkpoints\n├── orchestrator/   Claude Agent SDK integration, session management\n├── core/           Types, errors, seed, ontology, security\n├── providers/      LiteLLM adapter (100+ models)\n├── mcp/            MCP client/server for Claude Code\n├── plugin/         Claude Code plugin system\n├── tui/            Terminal UI dashboard\n└── cli/            Typer-based CLI\n```\n\n**Key internals:**\n- **PAL Router** — Frugal (1x) → Standard (10x) → Frontier (30x) with auto-escalation on failure, auto-downgrade on success\n- **Drift** — Goal (50%) + Constraint (30%) + Ontology (20%) weighted measurement, threshold ≤ 0.3\n- **Brownfield** — Scans 15 config file types across 12+ language ecosystems\n- **Evolution** — Up to 30 generations, convergence at ontology similarity ≥ 0.95\n- **Stagnation** — Detects spinning, oscillation, no-drift, and diminishing returns patterns\n\n\u003c/details\u003e\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/Q00/ouroboros\ncd ouroboros\nuv sync --all-groups \u0026\u0026 uv run pytest\n```\n\n[Issues](https://github.com/Q00/ouroboros/issues) · [Discussions](https://github.com/Q00/ouroboros/discussions)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\"The beginning is the end, and the end is the beginning.\"\u003c/em\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cstrong\u003eThe serpent doesn't repeat — it evolves.\u003c/strong\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003ccode\u003eMIT License\u003c/code\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fq00%2Fouroboros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fq00%2Fouroboros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fq00%2Fouroboros/lists"}