llms-full.txt · git:20261113.c9a517b · 2026-11-13 · sha256 5bf9d2984310e539

llms-full.txt git:20261113.c9a517bA

Immutable. This exact content never changes and is served at /api/v1/blob/5bf9d2984310e539.

# 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 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 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