Ouroboros: Dừng prompt, bắt đầu specify – Agent OS cho AI coding workflow có thể replay được

Tóm tắt nhanh:

• Ouroboros là một Agent OS mã nguồn mở do Q00 phát triển, biến công việc AI coding non-deterministic thành replayable, observable, policy-bound execution contract.
• Triết lý cốt lõi: “Stop prompting. Start specifying.” – thay thế prompt ad-hoc bằng workflow specification-first với 5 phase: Interview → Seed → Execute → Evaluate → Evolve.
• Tương thích đa nền tảng AI coding: Claude Code, Codex CLI, OpenCode, Hermes, Gemini CLI, GitHub Copilot CLI, Kiro CLI.
• Cấu trúc 3 layer: kernel (ouroboros), apps (ouroboros-plugins), shell (ourocode) – giống Linux OS thực thụ.
• Ambiguity Score (≤ 0.2) chặn code phát sinh khi spec còn mơ hồ; 3-stage evaluation gate (Mechanical → Semantic → Multi-Model Consensus) đảm bảo verification tự động.
• PAL Router tối ưu chi phí 3 tier: Frugal (1x) → Standard (10x) → Frontier (30x) – auto-escalate khi fail, auto-downgrade khi success.
• Nine Minds – 9 agent persona chuyên biệt (Socratic Interviewer, Ontologist, Contrarian, Hacker, Simplifier…) load on-demand.
• Cài đặt một dòng lệnh, yêu cầu Python ≥ 3.12, license mã nguồn mở.

Bất kỳ ai làm việc nghiêm túc với Claude Code, Cursor hay Codex CLI đều biết một sự thật khó chịu: AI hiếm khi fail vì không đủ capability – nó fail vì human input không đủ rõ ràng. Bạn gõ “Build me a task management CLI”, agent đoán mò 12 giả định ẩn (CLI hay GUI? local file hay cloud? single user hay team? deletable hay archivable?), build một thứ trông có vẻ ổn, rồi bạn phải rework hết.

Đây chính xác là vấn đề mà Ouroboros đặt vào trung tâm. Tên dự án lấy từ biểu tượng cổ – con rắn nuốt đuôi chính mình – phản ánh kiến trúc vòng lặp tiến hóa: output của mỗi evaluation trở thành input cho thế hệ spec tiếp theo, cho đến khi hệ thống thực sự hiểu nó đang build cái gì.

Khác với “prompt engineering” thông thường, Ouroboros áp dụng triết lý specification-first lấy cảm hứng từ Socratic method và Double Diamond design framework. Trước khi một dòng code được viết, hệ thống phải đi qua interview ép bạn lộ ra giả định ngầm, crystallize thành spec immutable, rồi mới thực thi.

Kiến trúc 3 layer của Ouroboros

Giống bất kỳ OS thực thụ nào, Ouroboros chia thành kernel layer (primitive ổn định), application layer (domain workflow), và shell (giao diện người dùng). Ba repo, một stack:

• Kernel (Q00/ouroboros) – Agent OS core: Seed, Ledger, Runtime, MCP, safety boundaries. Đây là repo chính.
• Apps (Q00/ouroboros-plugins) – plugin contract user-level, compose primitive thành domain workflow cài được (PR operation, Jira sync, incident, release).
• Shell (Q00/ourocode) – terminal client native, surface MCP state, interview question, wonderTool decision như first-class TUI element.

Kernel sở hữu contract: mỗi action trở thành Seed-bound, ledger-recorded, replayable event – bất kể LLM nào execute. Plugin declare scoped capability để workflow stay auditable. Ourocode là cockpit terminal thống nhất.

Các tính năng cốt lõi

Socratic Interview phơi bày giả định ngầm

Phase đầu tiên (ooo interview) – thay vì để agent đoán intent, một Socratic agent đặt câu hỏi truy vấn từng giả định ẩn. Với prompt “Build me a task management CLI”, hệ thống có thể đào lên 12 hidden assumption chưa nói rõ. Output cuối là Ambiguity Score từ 0-1, định lượng bằng công thức:

Ambiguity = 1 - Σ(clarity_i × weight_i)

Weight phụ thuộc context: greenfield 40% goal clarity / 30% constraint / 30% success criteria; brownfield trọng hơn về constraint vì code legacy đã có rất nhiều ràng buộc thực tế.

Seed: spec immutable lock intent

Khi Ambiguity ≤ 0.2, interview chuyển sang Seed – crystallize câu trả lời thành spec immutable với acceptance criteria, ontology, constraint. Spec này lock intent trước khi code, tránh “architecture drift mid-build” – một vấn đề kinh điển khi developer thay đổi ý giữa session.

Double Diamond execution

Phase Execute không phải một loạt prompt chạy thẳng đến code. Ouroboros áp dụng Double Diamond:

• Diamond 1 (Socratic): Wonder (diverge) → Ontology (converge) – hỏi “What IS this, really?”
• Diamond 2 (Pragmatic): Design (diverge) → Evaluation (converge) – tạo option, chọn delivery verified

Cách phân chia này đảm bảo bạn không design cái chưa hiểu.

3-stage evaluation gate

Đây là điểm khác biệt lớn so với “vibe-check” QA của AI coding thông thường. Mỗi artifact đi qua ba tầng:

• Mechanical (free): kiểm tra syntactic, linting, type check, test pass/fail – cost zero.
• Semantic: LLM single-model đánh giá xem code có đúng intent không.
• Multi-Model Consensus: nhiều model độc lập vote – giảm bias của một LLM nhất định.

Pass cả ba mới được merge. Nếu fail, loop quay về Evolve.

Evolve: vòng lặp ouroboros

Phase Evolve là nơi con rắn nuốt đuôi: output của Evaluate trở thành input cho seed thế hệ tiếp theo. Convergence đạt khi ontology similarity ≥ 0.95 – hệ thống đã question chính nó vào sự rõ ràng. Mặc định tối đa 30 generation.

Ralph: vòng lặp persistent stateless

ooo ralph chạy evolutionary loop persistent xuyên session boundary. EventStore reconstruct full lineage, nên dù máy restart, serpent vẫn pick up đúng chỗ. Đây là feature đắt giá cho workflow dài hơi cần chạy hàng giờ hoặc qua đêm.

PAL Router: tối ưu chi phí 3 tier

Mọi LLM call đều qua PAL Router với 3 tier auto-routing:

• Frugal (1x) – GPT-4o-mini, Claude Haiku – cho task đơn giản
• Standard (10x) – Claude Sonnet, GPT-4o – cho task vừa
• Frontier (30x) – Claude Opus, GPT-5 – cho task khó

Auto-escalate khi fail, auto-downgrade khi success – bạn không phải config thủ công từng call.

Nine Minds: 9 agent persona on-demand

Mỗi persona là một mode thinking, load on-demand, không bao giờ preload:

• Socratic Interviewer – chỉ hỏi, không build
• Ontologist – tìm essence, không tìm symptom
• Seed Architect – crystallize spec từ dialogue
• Evaluator – 3-stage verification
• Contrarian – challenge mọi assumption
• Hacker – tìm path không quy ước
• Simplifier – bỏ complexity
• Researcher – dừng code, bắt đầu investigate
• Architect – identify structural cause

Hướng dẫn cài đặt Ouroboros

Yêu cầu Python ≥ 3.12.

Cài một dòng lệnh (auto-detect)

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

Installer tự phát hiện Claude Code, Codex CLI, và Hermes CLI – register MCP server cho từng cái. Với OpenCode, Kiro hay Copilot CLI, cần chạy thêm ouroboros setup --runtime <tên>.

Cài qua pip/uv/pipx

pip install ouroboros-ai                    # base
pip install 'ouroboros-ai[claude]'          # + Claude Code
pip install 'ouroboros-ai[litellm]'         # + LiteLLM multi-provider (100+ model)
pip install 'ouroboros-ai[mcp]'             # + MCP server/client
pip install 'ouroboros-ai[tui]'             # + Textual TUI
pip install 'ouroboros-ai[all]'             # tất cả

ouroboros setup

Cài Claude Code plugin only

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

Rồi chạy ooo setup trong Claude Code session.

Cài cho GitHub Copilot CLI

gh auth login
pipx install 'ouroboros-ai[mcp]'
ouroboros setup --runtime copilot

Setup script discover model live qua GitHub Copilot models API và register MCP config vào ~/.copilot/mcp-config.json. Model ID Anthropic hyphenated (claude-opus-4-6) được auto-map sang dotted Copilot form (claude-opus-4.6) – config cũ vẫn dùng được khi switch backend.

Cài cho Kiro CLI

pip install 'ouroboros-ai[claude]'
ouroboros setup           # detect Kiro CLI, register MCP server

Set OUROBOROS_RUNTIME=kiro trong .env.

Sử dụng Ouroboros: Workflow điển hình

Bước 1: Khởi động interview

Trong session AI agent của bạn (Claude Code, Codex…), gõ:

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

Socratic agent bắt đầu hỏi. Trả lời từng câu – hệ thống score Ambiguity sau mỗi vòng. Khi đạt ngưỡng (≤ 0.2), proceed.

Bước 2: Crystallize Seed

> ooo seed

Hệ thống tạo file seed.yaml immutable chứa toàn bộ spec, acceptance criteria, ontology, constraint. File này commit vào git được – chia sẻ với team như source of truth.

Bước 3: Execute

> ooo run

Double Diamond decomposition kick in. PAL Router routing model theo từng subtask. Bạn có thể follow tiến trình qua MCP pane hoặc ouroboros status executions.

Bước 4: Evaluate

> ooo evaluate

3-stage gate chạy tự động. Nếu fail, hệ thống không silently merge mà chuyển sang Evolve.

Bước 5: Evolve hoặc Ralph

> ooo evolve           # one generation
> ooo ralph            # persistent loop until convergence

ooo ralph chạy liên tục qua nhiều generation cho đến khi ontology converge (≥ 0.95 similarity). Phù hợp để chạy qua đêm hoặc trong CI pipeline.

Bước 6: Khi bí, gọi unstuck

> ooo unstuck

5 lateral thinking persona vào cuộc, đề xuất hướng đi mới khi bạn thấy bế tắc.

Một số mẹo và lưu ý

Đối với brownfield project (codebase có sẵn), chạy ooo brownfield trước – hệ thống tự scan config file đa ngôn ngữ và adjust ambiguity weight phù hợp (trọng constraint nhiều hơn).

Khi cần handoff spec sang team development, dùng ooo publish để publish Seed thành GitHub Epic/Task issues qua gh CLI – tích hợp seamless với team workflow.

Nếu chạy nhiều execution song song và bị stuck, ouroboros cancel execution --all clean up triệt để. ooo resume-session để re-attach session đang chạy dở.

Vì Ouroboros bind action qua EventStore (SQLAlchemy + aiosqlite), toàn bộ history replayable. Đây là cơ sở để bạn audit “tại sao agent đưa ra quyết định này” sau vài tuần – không thể với prompt ad-hoc.

Ouroboros đại diện cho một làn sóng mới trong AI tooling: không thay thế AI agent, mà cung cấp OS layer cho chúng vận hành có kỷ luật. Đối với indie developer làm side project nhỏ, đây có thể là overkill. Nhưng với team đang dùng AI coding agent ở production scale – nơi audit, replay, policy bound là yêu cầu thực sự – Ouroboros là một dự án đáng theo dõi sát.