git:20261113.c9a517b to git:20261113.f6de1ce

2 added, 0 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# Ouroboros — Full Model Context Reference
> Pins an acceptance spec and omits any verify command or expected output from the worker's contract.
> Package: ouroboros-ai | CLI: ouroboros | Claude Code skills: ooo
> Python >= 3.12 | License: MIT
---
## What Ouroboros Does
Ouroboros sits between a human and an AI coding runtime (Claude Code, Codex CLI).
It replaces ad-hoc prompting with a structured loop:
Interview -> Seed -> Execute -> Evaluate -> Evolve (repeat)
The core insight: most AI coding fails at the INPUT, not the output.
Ouroboros forces clarity before code through Socratic questioning and
ontological analysis.
Note: this is github.com/Q00/ouroboros. A separate, unaffiliated open-source
project also named "Ouroboros" (github.com/razzant/ouroboros, by Anton
Razzhigaev) is a self-modifying, autonomous-memory agent that rewrites its
own architecture -- a different project with a different design, no shared
code.
---
## Command Surfaces
Two command surfaces exist. They are NOT a 1:1 mapping.
### ooo (Claude Code skills — run inside a Claude Code session)
A skill runs as `ooo <name>` (or `/ouroboros:<name>`), and an alias works the same way;
a skill listed as `/ouroboros:<name>` runs only when that command is typed explicitly.
<!-- generated:skills begin -->
auto Use when the work spans several files or replaces a framework, language, auth, storage, or API layer (rewrites and migrations included), and the user wants it to end up working and tested. Asks only what is missing, writes a spec with acceptance criteria, then runs and verifies it in the background. Not for questions, small edits, or an existing Seed (use run).
brownfield Scan and manage brownfield repository/worktree defaults for interviews
cancel (kill, abort) Cancel stuck or orphaned executions
config (ouroboros-config) Open or drive the Ouroboros settings GUI (browser, TUI, or conversational fallback)
evaluate (eval) Use when the user wants proof that finished work meets its acceptance criteria, not just that tests pass: 'verify it is actually done', 'check it against the spec', 'evaluate the run'. Runs mechanical checks, a semantic review per criterion, and multi-model consensus when uncertain. With execution.auto_evolve on (the default), a rejected result with a Seed continues into a Ralph fix loop; pass auto_evolve: false to verify only.
evolve Start or monitor an evolutionary development loop
help (ouroboros-help) Ouroboros command reference and troubleshooting guidance for installation, MCP, status, and recovery
idk (dont-know, calibrate) Calibrate interview explanations from the user's stated understanding
interview (socratic) Use when the user wants to build or change something but the request is vague or open-ended: 'help me figure out what to build', 'I'm not sure what it should do', 'add X' with no details, or no clear definition of done. Runs a short Socratic interview that turns the idea into goals, constraints, and acceptance criteria before any code is written. Not for simple questions, small clear edits, or an existing Seed.
ooo Start Ouroboros onboarding. Use when the user sends bare `ooo`, asks to start Ouroboros, or is using Ouroboros for the first time.
pm Use when the user wants product requirements rather than code: 'write a PRD', 'product requirements', 'spec this feature for the team', 'ooo pm'. Runs a PM-focused interview with automatic question classification and produces a PRD/PM document. Not for implementation requests.
publish Publish Seed specification as GitHub Issues for team-based project management
qa General-purpose QA verdict for any artifact type
ralph MCP-owned Ralph loop around background evolve_step jobs
resume-session List in-flight Ouroboros sessions and show the commands needed to re-attach after MCP disconnect
run (ouroboros-run, execute) Use when an Ouroboros Seed (a spec file with a goal and acceptance criteria, such as *.seed.yaml) already exists and the user wants it executed: 'run the seed', 'execute this spec', 'ooo run'. Executes it and verifies every acceptance criterion. Not for raw requests without a Seed (use interview or auto).
seed (crystallize) Use when goal, constraints, and success criteria are already settled and the user wants them frozen into a formal spec an agent can execute and verify: 'turn this into a spec', 'write it up as a Seed', or right after an interview. Returns an immutable Seed with acceptance criteria. Not for vague requests (use interview first).
/ouroboros:setup Guided onboarding wizard for Ouroboros setup
status (ouroboros-status, drift) Check session status and measure goal drift
/ouroboros:tutorial Interactive tutorial teaching Ouroboros hands-on
unstuck (stuck, lateral) Use when the user is stuck or going in circles: the same fix failed twice or more, 'nothing works', 'I've tried everything', or a consequential choice with no clear winner that is hard to undo or splits the team (which database, which architecture). Brings hacker, researcher, simplifier, architect, and contrarian perspectives and converges on one recommendation. Not for a first error or normal progress.
update Check for updates and upgrade Ouroboros to the latest version
/ouroboros:welcome First-touch experience for new Ouroboros users
<!-- generated:skills end -->
### ouroboros (Typer CLI — any terminal)
<!-- generated:cli-commands begin -->
ouroboros artifacts Fetch, replay, and conservatively prune Disposable Memory artifacts.
ouroboros auto Run bounded full-quality ooo auto pipeline.
ouroboros cancel Cancel stuck or orphaned executions.
ouroboros cleanup Prune leftover auto-session worktrees, branches, locks, and state files.
ouroboros codex Manage Ouroboros Codex CLI integration artifacts.
ouroboros config Manage Ouroboros configuration.
ouroboros detect Generate .ouroboros/mechanical.toml via one AI call.
ouroboros doctor Run read-only diagnostics for Ouroboros installations.
+ ouroboros gui Open the Ouroboros console in your browser (connect tools, settings, runs, chat).
ouroboros harness Inspect A2 interview traces (list/show/trace/diff/frontier).
ouroboros init Start interactive interview to refine requirements.
ouroboros interview Alias of `ouroboros init`.
ouroboros job Inspect background Ouroboros jobs.
ouroboros mcp MCP (Model Context Protocol) server commands.
ouroboros plugin Manage UserLevel plugins (#725).
ouroboros pm Generate a Product Requirements Document through guided interview.
ouroboros qa General-purpose QA verdict for any artifact.
ouroboros resume List in-flight sessions and re-attach after MCP disconnect.
ouroboros run Execute Ouroboros workflows.
ouroboros seed Generate a Seed YAML specification from an interview.
+ ouroboros service Run the Ouroboros console (and its shared MCP server) in the background at login.
ouroboros setup Set up Ouroboros for your environment.
ouroboros status Check Ouroboros system status.
ouroboros tui Interactive TUI monitor for Ouroboros workflows.
ouroboros uninstall Cleanly remove Ouroboros from your system.
ouroboros update Update Ouroboros to the latest version.
ouroboros workflow-ir Inspect read-only Workflow IR projections.
ouroboros zcode Convenience commands that use Zcode automatically.
<!-- generated:cli-commands end -->
NOTE: Both `ooo interview` and `ouroboros interview` start the Socratic interview flow.
---
## Architecture Overview
### Source Layout
src/ouroboros/
bigbang/ Interview, ambiguity scoring, brownfield explorer
routing/ PAL Router — 3-tier cost optimization (1x / 10x / 30x)
execution/ Double Diamond, hierarchical AC decomposition
evaluation/ Mechanical -> Semantic -> Multi-Model Consensus
evolution/ Wonder / Reflect cycle, convergence detection
resilience/ 4-pattern stagnation detection, 5 lateral personas
observability/ 3-component drift measurement, auto-retrospective
persistence/ Event sourcing (SQLAlchemy + aiosqlite), checkpoints
orchestrator/ Runtime abstraction layer (Claude Code, Codex CLI)
core/ Types, errors, seed, ontology, security
providers/ LiteLLM adapter (100+ models)
mcp/ MCP client/server integration
plugin/ Plugin system (skill/agent auto-discovery)
tui/ Terminal UI dashboard (Textual)
cli/ Typer-based CLI
### Layers
Plugin Layer Skills (14) + Agents (9), hot-reload, magic prefix detection
Core Layer Immutable Seed, AC tree, ontology schema, version tracking
Execution Layer Double Diamond, dependency-aware parallel execution
State Layer SQLite event store, append-only, full replay, checkpoints
Orchestration 6-phase pipeline, PAL Router cost optimization
Presentation TUI dashboard (Textual), CLI (Typer)
---
## The Six Phases
Phase 0: BIG BANG Crystallize requirements into a Seed
Phase 1: PAL ROUTER Select appropriate model tier
Phase 2: DOUBLE DIAMOND Decompose and execute tasks
Phase 3: RESILIENCE Handle stagnation with lateral thinking
Phase 4: EVALUATION Verify outputs at three stages
Phase 5: SECONDARY LOOP Process deferred TODOs
(cycle back as needed)
### Phase 0: Big Bang
Components:
bigbang/interview.py InterviewEngine for Socratic interviews
bigbang/ambiguity.py Ambiguity score calculation
bigbang/seed_generator.py Seed generation from interview results
Engine generation flow (the host Interview skill separately suggests ooo seed):
1. User provides initial context/idea
2. Engine asks clarifying questions (up to MAX_INTERVIEW_ROUNDS)
3. Ambiguity score calculated after each response
4. Interview completes when ambiguity <= 0.2
5. Immutable Seed generated
Ambiguity = 1 - Sum(clarity_i * weight_i)
Greenfield weights:
Goal Clarity 40%
Constraint Clarity 30%
Success Criteria 30%
Brownfield weights:
Goal Clarity 35%
Constraint Clarity 25%
Success Criteria 25%
Context Clarity 15%
Gate: Ambiguity <= 0.2
### Phase 1: PAL Router (Progressive Adaptive LLM)
Components:
routing/router.py Main routing logic
routing/complexity.py Task complexity estimation
routing/tiers.py Model tier definitions
routing/escalation.py Escalation logic on failure
routing/downgrade.py Downgrade logic on success
Tiers:
FRUGAL 1x cost complexity < 0.4
STANDARD 10x cost complexity < 0.7
FRONTIER 30x cost complexity >= 0.7 or critical
Complexity scoring:
complexity = 0.30 * norm_tokens + 0.30 * norm_tools + 0.40 * norm_depth
where:
norm_tokens = min(tokens / 4000, 1.0)
norm_tools = min(tools / 5, 1.0)
norm_depth = min(depth / 5, 1.0)
Escalation: 2 consecutive failures at current tier triggers escalation
Frugal -> Standard -> Frontier -> Stagnation Event
Downgrade: 5 consecutive successes triggers downgrade
Frontier -> Standard -> Frugal
Similar task patterns (Jaccard similarity >= 0.80) inherit tier preferences.
### Phase 2: Execution
Components:
orchestrator/parallel_executor.py Live recursive AC executor (fan-out, decomposition, evidence-gated delivery)
orchestrator/decomposition_params.py Profile-driven decomposition prompts (axis / min_unit / branching)
orchestrator/runner.py Orchestration entry point + dependency analysis
(The earlier execution/double_diamond.py + decomposition.py + atomicity.py stack
was removed once found to have no live caller; parallel_executor.py is the live path.)
Recursive decomposition:
Each AC defaults to ATOMIC; split into 2-5 sub-ACs only when it genuinely
spans multiple units along the profile axis (each sub-AC costs a full agent
session, so splitting is conservative). Sub-ACs recurse within a bounded depth.
Constraints:
DEFAULT_MAX_DECOMPOSITION_DEPTH = 2 soft depth cap (OUROBOROS_MAX_DECOMPOSITION_DEPTH override)
Failures use an attempt-then-bounce loop, not ever-deeper pre-execution splits
### Phase 3: Resilience
Components:
resilience/stagnation.py Stagnation detection (4 patterns)
resilience/lateral.py Persona rotation and lateral thinking
Stagnation patterns:
SPINNING Same output hash repeated (SHA-256), threshold: 3
OSCILLATION A->B->A->B alternating pattern, threshold: 2 cycles
NO_DRIFT Drift score unchanging (epsilon < 0.01), threshold: 3
DIMINISHING_RETURNS Progress rate < 0.01, threshold: 3
Lateral thinking personas:
HACKER Unconventional workarounds best for: SPINNING
RESEARCHER Seek more information best for: NO_DRIFT, DIMINISHING_RETURNS
SIMPLIFIER Reduce complexity best for: DIMINISHING_RETURNS, OSCILLATION
ARCHITECT Restructure fundamentally best for: OSCILLATION, NO_DRIFT
CONTRARIAN Challenge all assumptions best for: all patterns
### Phase 4: Evaluation
Components:
evaluation/pipeline.py Pipeline orchestration
evaluation/mechanical.py Stage 1: Mechanical checks
evaluation/semantic.py Stage 2: Semantic verification
evaluation/consensus.py Stage 3: Multi-model consensus
evaluation/trigger.py Consensus trigger matrix
Stage 1: Mechanical ($0)
Lint, build, test, static analysis, coverage (threshold: 70%)
Any check fails -> pipeline stops
Stage 2: Semantic ($$)
AC compliance, goal alignment, drift, uncertainty scoring
Score >= 0.8 and no trigger -> approved without consensus
Uses Standard tier model (temperature: 0.2)
Stage 3: Consensus ($$$)
Triggered by 1 of 6 conditions (checked in priority order):
1. Seed modification (seeds are immutable)
2. Ontology evolution (schema changes)
3. Goal reinterpretation
4. Seed drift > 0.3
5. Stage 2 uncertainty > 0.3
6. Lateral thinking adoption
Simple mode: 3 models vote (GPT-4o, Claude Sonnet 4, Gemini 2.5 Pro)
2/3 majority required
Deliberative mode: Advocate / Devil's Advocate / Judge roles
### Phase 5: Secondary Loop
Components:
secondary/todo_registry.py Non-blocking TODO capture during execution
secondary/scheduler.py Batch processing after primary goal
TODO Registration:
During execution, discovered improvements are registered asynchronously
via TodoRegistry without disrupting the primary flow.
Each TODO has: description, context (execution ID), priority, status
Priority levels:
HIGH Critical improvements, addressed first
MEDIUM Standard improvements, moderate impact
LOW Nice-to-have, minimal urgency
Batch Processing:
Activates only after primary goal completion (all ACs passed)
Processes TODOs in priority order (HIGH -> MEDIUM -> LOW)
Non-blocking failures: one failed TODO does not stop others
User can skip via --skip-secondary flag
BatchStatus:
COMPLETED All TODOs processed (some may have failed)
PARTIAL Processing stopped early (timeout)
SKIPPED User chose to skip
NO_TODOS No pending TODOs to process
Returns BatchSummary: total, success_count, failure_count, skipped_count
---
## Core Data Models
### Seed (Immutable Specification)
In the host-skill flow, the Interview skill performs closure checks, confirms
the agreed goal with the user, and suggests ooo seed. Request generation and
inspect the returned Seed YAML before execution; interview completion alone
does not establish that a Seed exists. The Seed skill can also use requirements
already agreed in the conversation (see skills/seed/SKILL.md). The standalone CLI and Auto have
separate generation flows; do not substitute host-skill commands for them.
Manual YAML authoring is an advanced workflow — see docs/guides/seed-authoring.md.
class Seed(BaseModel, frozen=True):
goal: str # Primary objective
constraints: tuple[str, ...] # Hard requirements
acceptance_criteria: tuple[str, ...] # Success criteria
ontology_schema: OntologySchema # Output structure
evaluation_principles: tuple[EvaluationPrinciple, ...]
exit_conditions: tuple[ExitCondition, ...]
metadata: SeedMetadata
class SeedMetadata(BaseModel, frozen=True):
seed_id: str # auto-generated UUID
version: str # default "1.0.0"
created_at: datetime
ambiguity_score: float # 0.0 to 1.0
interview_id: str | None
class OntologySchema(BaseModel, frozen=True):
name: str
description: str
fields: tuple[OntologyField, ...]
class OntologyField(BaseModel, frozen=True):
name: str
field_type: str # "string" | "number" | "boolean" | "array" | "object"
description: str
required: bool = True
class EvaluationPrinciple(BaseModel, frozen=True):
name: str
description: str
weight: float # 0.0 to 1.0, default 1.0
class ExitCondition(BaseModel, frozen=True):
name: str
description: str
evaluation_criteria: str
Once generated, a Seed cannot be modified. Any change triggers consensus.
### Result Type
Result[T, E] — generic frozen dataclass for expected failures
Methods: ok(value), err(error), unwrap(), unwrap_or(default),
map(fn), map_err(fn), and_then(fn)
Properties: is_ok, is_err, value, error
### Error Hierarchy
OuroborosError (base)
ProviderError LLM provider failures (provider, status_code)
ConfigError Configuration issues (config_key, config_file)
PersistenceError Database/storage issues (operation, table)
ValidationError Data validation failures (field, value, safe_value)
---
## Event Sourcing
All state changes are immutable events in a single SQLite table (events):
Columns: id (UUID), aggregate_type, aggregate_id, event_type,
payload (JSON), timestamp, consensus_id
Event types use dot-notation past tense:
orchestrator.session.started
execution.ac.completed
Indexes (5): aggregate_type, aggregate_id, composite, event_type, timestamp
Features:
Append-only writes
Unit of Work pattern (events + checkpoint atomic commits)
Full replay capability
3-level rollback depth
5-minute periodic checkpointing
---
## Runtime Abstraction
### AgentRuntime Protocol
class AgentRuntime(Protocol):
def execute_task(prompt, tools, system_prompt, resume_handle)
-> AsyncIterator[AgentMessage]
async def execute_task_to_result(prompt, tools, system_prompt, resume_handle)
-> Result[TaskResult, ProviderError]
Key types:
AgentMessage Normalized streaming message (backend-neutral)
RuntimeHandle Frozen dataclass with session/resume state
TaskResult Collected outcome of completed task
### RuntimeHandle
@dataclass(frozen=True, slots=True)
class RuntimeHandle:
backend: str # "claude" | "codex" | custom
kind: str = "agent_runtime"
native_session_id: str | None
conversation_id: str | None
previous_response_id: str | None
transcript_path: str | None
cwd: str | None
approval_mode: str | None
updated_at: str | None
metadata: dict[str, Any]
Computed properties: lifecycle_state, is_terminal, can_resume,
can_observe, can_terminate
Methods: observe(), terminate(), snapshot(), to_dict(), from_dict()
### Shipped Adapters
ClaudeAgentAdapter (backend="claude")
Module: src/ouroboros/orchestrator/adapter.py
Wraps Claude Agent SDK / Claude Code CLI
Streaming via claude_agent_sdk.query()
Auto transient-error retry, session resumption
CodexCliRuntime (backend="codex")
Module: src/ouroboros/orchestrator/codex_cli_runtime.py
Drives OpenAI Codex CLI as session-oriented runtime
Parses newline-delimited JSON from stdout
Skill-command interception for deterministic MCP dispatch
### Runtime Factory
create_agent_runtime(backend, permission_mode, model, cwd)
Backend resolution order:
1. OUROBOROS_AGENT_RUNTIME env var
2. orchestrator.runtime_backend in ~/.ouroboros/config.yaml
3. Explicit backend= parameter
Aliases: claude/claude_code, codex/codex_cli
---
## MCP Integration
Ouroboros is an MCP Hub (both client and server).
### MCP Server Mode
ouroboros mcp serve
Exposed tools (descriptions come from the server's tools/list):
<!-- generated:mcp-tools begin -->
ouroboros_ac_dashboard
ouroboros_ac_tree_hud
ouroboros_auto
ouroboros_brownfield
ouroboros_cancel_execution
ouroboros_cancel_job
ouroboros_checklist_verify
ouroboros_evaluate
ouroboros_evolve_rewind
ouroboros_evolve_step
ouroboros_execute_seed
ouroboros_fetch_artifact
ouroboros_generate_seed
ouroboros_interview
ouroboros_job_result
ouroboros_job_status
ouroboros_job_wait
ouroboros_lateral_think
ouroboros_lineage_status
ouroboros_measure_drift
ouroboros_pm_interview
ouroboros_project_status
ouroboros_qa
ouroboros_query_events
ouroboros_query_projection
ouroboros_ralph
ouroboros_record_conductor_decision
ouroboros_session_signal
ouroboros_session_signal_targets
ouroboros_session_status
ouroboros_start_auto
ouroboros_start_evaluate
ouroboros_start_evolve_step
ouroboros_start_execute_seed
ouroboros_start_qa
ouroboros_start_ralph
ouroboros_submit_fanout_results
<!-- generated:mcp-tools end -->
### MCP Client Mode
ouroboros run --mcp-config mcp.yaml seed.yaml
Tool precedence:
1. Built-in tools always win
2. First MCP server in config wins for duplicates
3. Use --mcp-tool-prefix to namespace
### MCP Types
TransportType: stdio | sse | streamable-http
ContentType: text | image | resource
MCPServerConfig: name, transport, command, args, url, env, timeout, headers
MCPToolDefinition: name, description, parameters, server_name
MCPToolResult: content, is_error, meta
MCPCapabilities: tools, resources, prompts, logging
### MCP Error Hierarchy
MCPError (base, extends OuroborosError)
MCPClientError
MCPConnectionError (transport)
MCPTimeoutError (timeout_seconds, operation)
MCPProtocolError
MCPServerError
MCPAuthError
MCPResourceNotFoundError
MCPToolError (tool_name, error_code)
---
## Drift Control
3-component weighted measurement:
Goal drift 50% weight
Constraint drift 30% weight
Ontology drift 20% weight
Drift score: 0.0 to 1.0
Threshold: <= 0.3 (high drift triggers re-examination)
Automatic retrospective every N cycles
---
## Ontology Convergence
Similarity = 0.5 * name_overlap + 0.3 * type_match + 0.2 * exact_match
Convergence threshold: similarity >= 0.95
Hard cap: 30 generations
Pathological pattern detection:
Stagnation: similarity >= 0.95 for 3 consecutive generations
Oscillation: Gen N ~ Gen N-2 (period-2 cycle)
Repetitive: >= 70% question overlap across 3 generations
---
## The Nine Agents
Loaded on-demand, never preloaded:
Socratic Interviewer Questions-only, never builds
Ontologist Finds essence, not symptoms
Seed Architect Crystallizes specs from dialogue
Evaluator 3-stage verification
Contrarian Challenges every assumption
Hacker Finds unconventional paths
Simplifier Removes complexity
Researcher Stops coding, starts investigating
Architect Identifies structural causes
---
## Configuration
### File Layout
~/.ouroboros/
config.yaml Main configuration
credentials.yaml API keys (chmod 600)
ouroboros.db SQLite event store
seeds/ Generated seed YAML files
data/ Reserved for future use
logs/ouroboros.log Log output
.env Optional, auto-loaded
### Config Sections
orchestrator Runtime backend selection, agent permissions
llm Model selection, permission mode
economics PAL Router tier definitions, escalation thresholds
clarification Phase 0 interview settings
execution Phase 2 Double Diamond settings
resilience Phase 3 stagnation/lateral thinking
evaluation Phase 4 evaluation pipeline settings
consensus Multi-model consensus settings
persistence SQLite event store settings
drift Drift monitoring thresholds
logging Log level, path, verbosity
### Key Environment Variables
ANTHROPIC_API_KEY Claude API key
OPENAI_API_KEY OpenAI API key
OUROBOROS_AGENT_RUNTIME Runtime backend override (claude | codex)
TERM=xterm-256color TUI terminal compatibility
### Minimal config.yaml
orchestrator:
runtime_backend: claude # claude | codex
logging:
level: info # debug | info | warning | error
persistence:
database_path: data/ouroboros.db
---
## Security Limits
Input validation constants (core/security.py):
MAX_INITIAL_CONTEXT_LENGTH 50,000 chars Interview input limit
MAX_USER_RESPONSE_LENGTH 10,000 chars Interview response limit
MAX_SEED_FILE_SIZE 1,000,000 bytes Seed YAML file size cap
MAX_LLM_RESPONSE_LENGTH 100,000 chars LLM response truncation
---
## Performance Characteristics
Event Store:
Append latency: < 10ms p99
Query latency: < 50ms for 1000 events
Storage: ~1KB per event
Compression: 80% reduction at checkpoints
TUI:
Refresh rate: 500ms polling
Event processing: < 100ms per update
Memory:
Base: 50MB
Per session: 10-100MB depending on complexity
Concurrency:
Agent pool: 2-10 parallel agents
Task queue: priority-based async processing
---
## TUI Dashboard
Terminal-based real-time workflow monitor (Textual framework).
Launch: ouroboros tui monitor (or ouroboros monitor)
Screens:
1 Dashboard Phase progress, AC tree, live status
2 Execution Timeline, phase outputs, events
3 Logs Filterable log viewer with level coloring
4 Debug State inspector, raw events, config
s Session Browse and switch sessions
e Lineage Evolutionary lineage across generations
State: TUIState dataclass in events.py, owned by app.py as SSOT
Event flow: EventStore -> app._subscribe_to_events() (poll 0.5s)
-> create_message_from_event() -> post_message()
---
## Extension Points
### Adding a New Runtime Adapter
1. Create module in src/ouroboros/orchestrator/
2. Implement AgentRuntime protocol (execute_task, execute_task_to_result)
3. Register in runtime_factory.py (add backend name set, extend resolve)
4. Emit RuntimeHandle with your backend tag
5. Update runtime_backend Literal in config/models.py
6. Write tests verifying AgentRuntime structural subtyping
### Custom Skills
Place in skills/ directory with SKILL.md defining:
name, version, description, magic_prefixes, triggers, mode, agents, tools
### Custom Agents
Place in src/ouroboros/agents/ as bundled markdown files, or in an explicit
override directory via OUROBOROS_AGENTS_DIR / .claude-plugin/agents/:
role, capabilities, tools
### MCP Server Integration
Register custom tool/resource handlers via MCPServerAdapter
or use ToolRegistry for the global registry
---
## Design Principles
1. Frugal First Start cheap, escalate only on failure
2. Immutable Seed Direction cannot change; only path adapts
3. Progressive Verification Cheap checks first, consensus at gates
4. Lateral Over Vertical When stuck, change perspective
5. Event-Sourced Every state change is an event; nothing lost
---
## Key File Locations
CLAUDE.md Dev environment setup, ooo command routing
docs/getting-started.md Onboarding guide (single source of truth)
docs/architecture.md Full architecture document
docs/config-reference.md Complete config reference
docs/api/core.md Core module API reference
docs/api/mcp.md MCP module API reference
docs/runtime-capability-matrix.md Runtime feature comparison
docs/runtime-guides/claude-code.md Claude Code backend guide
docs/runtime-guides/codex.md Codex CLI backend guide
docs/guides/seed-authoring.md Advanced seed authoring
docs/guides/evaluation-pipeline.md Evaluation pipeline details
docs/guides/tui-usage.md TUI dashboard reference
docs/contributing/ Contributor guides