ouroboros

# Ouroboros - Development Environment

> This CLAUDE.md is for **local development only**. End users install via:
> ```
> claude plugin marketplace add Q00/ouroboros
> claude plugin install ouroboros@ouroboros
> ```
> Once installed as a plugin, skills/hooks/agents work natively without this file.

## ooo Commands (Dev Mode)

When the user types any of these commands, read the corresponding SKILL.md file and follow its instructions exactly:

| Input | Action |
|-------|--------|
| `ooo` (bare, no subcommand) | Read `skills/welcome/SKILL.md` and follow it |
| `ooo auto ...` | Read `skills/auto/SKILL.md` and follow it |
| `ooo interview ...` | Read `skills/interview/SKILL.md` and follow it |
| `ooo seed` | Read `skills/seed/SKILL.md` and follow it |
| `ooo run` | Read `skills/run/SKILL.md` and follow it |
| `ooo evaluate` or `ooo eval` | Read `skills/evaluate/SKILL.md` and follow it |
| `ooo evolve ...` | Read `skills/evolve/SKILL.md` and follow it |
| `ooo unstuck` or `ooo stuck` or `ooo lateral` | Read `skills/unstuck/SKILL.md` and follow it |
| `ooo status` or `ooo drift` | Read `skills/status/SKILL.md` and follow it |
| `ooo ralph` | Read `skills/ralph/SKILL.md` and follow it |
| `ooo tutorial` | Read `skills/tutorial/SKILL.md` and follow it |
| `ooo setup` | Read `skills/setup/SKILL.md` and follow it |
| `ooo welcome` | Read `skills/welcome/SKILL.md` and follow it |
| `ooo cancel` | Read `skills/cancel/SKILL.md` and follow it |
| `ooo config` | Read `skills/config/SKILL.md` and follow it |
| `ooo qa` or `ooo qa ...` | Read `skills/qa/SKILL.md` and follow it |
| `ooo help` | Read `skills/help/SKILL.md` and follow it |
| `ooo update` | Read `skills/update/SKILL.md` and follow it |
| `ooo pm` or `ooo pm ...` | Read `skills/pm/SKILL.md` and follow it |
| `ooo brownfield` or `ooo brownfield ...` | Read `skills/brownfield/SKILL.md` and follow it |
| `ooo publish` or `ooo publish ...` | Read `skills/publish/SKILL.md` and follow it |
| `ooo resume-session` | Read `skills/resume-session/SKILL.md` and follow it |

**Important**: Do NOT use the Skill tool. Read the file with the Read tool and execute its instructions directly.

## Agents

Bundled agents live in `src/ouroboros/agents/`. When a skill references an agent (e.g., `ouroboros:socratic-interviewer`), read its definition from `src/ouroboros/agents/{name}.md` and adopt that role. Use `OUROBOROS_AGENTS_DIR` or `.claude-plugin/agents/` only for explicit custom overrides.

<!-- ooo:START -->
<!-- ooo:VERSION:0.26.0 -->
# Ouroboros — Specification-First AI Development

> Before telling AI what to build, define what should be built.
> As Socrates asked 2,500 years ago — "What do you truly know?"
> Ouroboros turns that question into an evolutionary AI workflow engine.

Most AI coding fails at the input, not the output. Ouroboros fixes this by
**exposing hidden assumptions before any code is written**.

1. **Socratic Clarity** — Question until ambiguity ≤ 0.2
2. **Ontological Precision** — Solve the root problem, not symptoms
3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs

```
Interview → Seed → Execute → Evaluate
    ↑                           ↓
    └─── Evolutionary Loop ─────┘
```

## ooo Commands

Each command loads its agent/MCP on-demand. Details in each skill file.

| Command | Loads |
|---------|-------|
| `ooo` | — |
| `ooo auto` | MCP: `ouroboros_auto` |
| `ooo interview` | `ouroboros:socratic-interviewer` |
| `ooo seed` | `ouroboros:seed-architect` |
| `ooo run` | MCP required |
| `ooo evolve` | MCP: `evolve_step` |
| `ooo evaluate` | `ouroboros:evaluator` |
| `ooo qa` | `ouroboros:qa-judge` |
| `ooo unstuck` | `ouroboros:{persona}` |
| `ooo status` | MCP: `session_status` |
| `ooo ralph` | Persistent loop until verified |
| `ooo tutorial` | Interactive hands-on learning |
| `ooo setup` | — |
| `ooo help` | — |
| `ooo update` | PyPI version check + upgrade |
| `ooo publish` | `gh` CLI — Seed to GitHub Issues |
| `ooo resume-session` | Restore previous Claude Code session context |

## Agents

Loaded on-demand — not preloaded.

**Core**: socratic-interviewer, ontologist, seed-architect, evaluator, qa-judge, contrarian
**Support**: hacker, simplifier, researcher, architect
<!-- ooo:END -->

# Ouroboros - Development Environment

> This AGENTS.md is for **local development only**. End users install via:
> ```
> Codex plugin marketplace add Q00/ouroboros
> Codex plugin add ouroboros@ouroboros
> ```
> Once installed as a plugin, skills/hooks/agents work natively without this file.

## ooo Commands (Dev Mode)

When the user types any of these commands, read the corresponding SKILL.md file and follow its instructions exactly:

| Input | Action |
|-------|--------|
| `ooo` (bare, no subcommand) | Read `skills/welcome/SKILL.md` and follow it |
| `ooo auto ...` | Read `skills/auto/SKILL.md` and follow it |
| `ooo interview ...` | Read `skills/interview/SKILL.md` and follow it |
| `ooo seed` | Read `skills/seed/SKILL.md` and follow it |
| `ooo run` | Read `skills/run/SKILL.md` and follow it |
| `ooo evaluate` or `ooo eval` | Read `skills/evaluate/SKILL.md` and follow it |
| `ooo evolve ...` | Read `skills/evolve/SKILL.md` and follow it |
| `ooo unstuck` or `ooo stuck` or `ooo lateral` | Read `skills/unstuck/SKILL.md` and follow it |
| `ooo status` or `ooo drift` | Read `skills/status/SKILL.md` and follow it |
| `ooo ralph` | Read `skills/ralph/SKILL.md` and follow it |
| `ooo tutorial` | Read `skills/tutorial/SKILL.md` and follow it |
| `ooo setup` | Read `skills/setup/SKILL.md` and follow it |
| `ooo welcome` | Read `skills/welcome/SKILL.md` and follow it |
| `ooo cancel` | Read `skills/cancel/SKILL.md` and follow it |
| `ooo qa` or `ooo qa ...` | Read `skills/qa/SKILL.md` and follow it |
| `ooo help` | Read `skills/help/SKILL.md` and follow it |
| `ooo update` | Read `skills/update/SKILL.md` and follow it |
| `ooo pm` or `ooo pm ...` | Read `skills/pm/SKILL.md` and follow it |
| `ooo brownfield` or `ooo brownfield ...` | Read `skills/brownfield/SKILL.md` and follow it |
| `ooo publish` or `ooo publish ...` | Read `skills/publish/SKILL.md` and follow it |
| `ooo resume-session` | Read `skills/resume-session/SKILL.md` and follow it |

**Important**: Do NOT use the Skill tool. Read the file with the Read tool and execute its instructions directly.

## Agents

Bundled agents live in `src/ouroboros/agents/`. When a skill references an agent (e.g., `ouroboros:socratic-interviewer`), read its definition from `src/ouroboros/agents/{name}.md` and adopt that role. Use `OUROBOROS_AGENTS_DIR` or `.Codex-plugin/agents/` only for explicit custom overrides.

<!-- ooo:START -->
<!-- ooo:VERSION:0.26.0 -->
# Ouroboros — Specification-First AI Development

> Before telling AI what to build, define what should be built.
> As Socrates asked 2,500 years ago — "What do you truly know?"
> Ouroboros turns that question into an evolutionary AI workflow engine.

Most AI coding fails at the input, not the output. Ouroboros fixes this by
**exposing hidden assumptions before any code is written**.

1. **Socratic Clarity** — Question until ambiguity ≤ 0.2
2. **Ontological Precision** — Solve the root problem, not symptoms
3. **Evolutionary Loops** — Each evaluation cycle feeds back into better specs

```
Interview → Seed → Execute → Evaluate
    ↑                           ↓
    └─── Evolutionary Loop ─────┘
```

## ooo Commands

Each command loads its agent/MCP on-demand. Details in each skill file.

| Command | Loads |
|---------|-------|
| `ooo` | — |
| `ooo auto` | MCP: `ouroboros_start_auto` |
| `ooo interview` | `ouroboros:socratic-interviewer` |
| `ooo seed` | `ouroboros:seed-architect` |
| `ooo run` | MCP required |
| `ooo evolve` | MCP: `evolve_step` |
| `ooo evaluate` | `ouroboros:evaluator` |
| `ooo qa` | `ouroboros:qa-judge` |
| `ooo unstuck` | `ouroboros:{persona}` |
| `ooo status` | MCP: `session_status` |
| `ooo ralph` | Persistent loop until verified |
| `ooo tutorial` | Interactive hands-on learning |
| `ooo setup` | — |
| `ooo help` | — |
| `ooo update` | PyPI version check + upgrade |
| `ooo publish` | `gh` CLI — Seed to GitHub Issues |
| `ooo resume-session` | Restore previous Codex session context |

## Agents

Loaded on-demand — not preloaded.

**Core**: socratic-interviewer, ontologist, seed-architect, evaluator, qa-judge, contrarian
**Support**: hacker, simplifier, researcher, architect
<!-- ooo:END -->

# Ouroboros

> Pins an acceptance spec and omits any verify command or expected output from the worker's contract

Ouroboros transforms vague ideas into verified, working codebases by replacing ad-hoc prompting with a structured workflow: interview, crystallize, execute, evaluate, evolve. It sits between the user and their AI runtime (Claude Code, Codex CLI, or others).

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.

## Core Concepts

- Seed Spec: An immutable YAML specification auto-generated from a Socratic interview. Contains project description, acceptance criteria (AC) tree, constraints, and architecture decisions. The seed is the single source of truth for what should be built. In the happy path, users never create seeds manually — the interview produces one automatically. Manual seed authoring is an advanced workflow (see `docs/guides/seed-authoring.md`).
- Acceptance Criteria (AC) Tree: A hierarchical decomposition of requirements. Each AC has a status (pending, in_progress, passed, failed) and can contain children. The tree is the unit of progress tracking.
- Interview: A Socratic dialogue that extracts hidden assumptions and crystallizes vague requirements into a structured seed spec. Auto-generates the seed on completion.
- Evaluation Pipeline: Three-stage verification (mechanical checks, LLM-based review, consensus gating) that determines whether acceptance criteria are met.
- Event Sourcing: All state changes are persisted as immutable events in a SQLite EventStore (~/.ouroboros/ouroboros.db). The system can reconstruct any past state from events.
- Evolution Loop: After evaluation, the system can evolve the spec and re-execute, creating an iterative refinement cycle.
- Drift Detection: Monitors whether execution is diverging from the original seed spec intent.
- Lineage: Tracks the causal chain of events and decisions through the workflow.

## Architecture Layers

- Plugin Layer: Skills (Claude Code slash commands via `ooo`) and agents that interface with the user. Skills map to `skills/*/SKILL.md`.
- Core Layer: Seed spec management, AC tree lifecycle, event sourcing, lineage tracking. Located in `src/ouroboros/core/`.
- Orchestrator: Coordinates execution strategy, manages level context, routes tasks to appropriate backends. Located in `src/ouroboros/orchestrator/`.
- Evaluation: Three-stage pipeline (mechanical, LLM, consensus), artifact collection, language-specific checks. Located in `src/ouroboros/evaluation/`.
- Execution: Subagent management for parallel AC execution. Located in `src/ouroboros/execution/`.
- Routing: Complexity analysis, task routing, model escalation/downgrade. Located in `src/ouroboros/routing/`.
- Persistence: SQLAlchemy-based event store with migration support. Located in `src/ouroboros/persistence/`.
- Presentation: Textual TUI (dashboard, execution, logs, debug, lineage screens) and Typer CLI. Located in `src/ouroboros/tui/` and `src/ouroboros/cli/`.
- MCP: Model Context Protocol server/client for tool integration. Located in `src/ouroboros/mcp/`.
- Observability: Drift detection and retrospective analysis. Located in `src/ouroboros/observability/`.
- Resilience: Retry and recovery strategies. Located in `src/ouroboros/resilience/`.

## Two CLI Paths

- `ooo` (Claude Code): Slash-command skills invoked inside a Claude Code session. Primary recommended path. Commands: `ooo setup`, `ooo interview "idea"`, `ooo run`, `ooo evaluate`, `ooo evolve`, `ooo status`, `ooo unstuck`, `ooo cancel`.
- `ouroboros` (Typer CLI): Standalone CLI installed via `pip install ouroboros-ai`. Fallback path. Subcommands: `ouroboros interview`, `ouroboros run`, `ouroboros config`, `ouroboros status`, `ouroboros cancel`, `ouroboros setup`, `ouroboros tui`, `ouroboros mcp`.

## Commands / Skills

- setup: Guided onboarding wizard. Configures runtime backend and project settings.
- interview (aliases: socratic): Socratic interview to crystallize vague requirements into a seed spec. Auto-generates the seed on completion.
- seed (aliases: crystallize): Generate validated seed specifications from interview results. Automatically invoked by interview in the happy path — most users never call this directly. Manual seed authoring is an advanced workflow.
- ouroboros-run (invoked as `ooo run`, alias: execute): Execute a seed specification through the workflow engine. Decomposes ACs into tasks and runs them via the configured backend.
- evaluate (aliases: eval): Three-stage verification pipeline. Runs mechanical checks, LLM review, and consensus gating against acceptance criteria.
- evolve: Start or monitor an evolutionary development loop. Iterates on evaluation findings.
- ouroboros-status (invoked as `ooo status`, alias: drift): Check session status and measure goal drift against the seed spec.
- unstuck (aliases: stuck, lateral): Break through stagnation with lateral thinking personas.
- cancel (aliases: kill, abort): Cancel stuck or orphaned executions.
- ouroboros-config (invoked as `ooo config`): Open the Ouroboros settings UI.
- ouroboros-help (invoked as `ooo help`): Show available commands and usage.
- welcome: First-run welcome message and orientation.
- tutorial: Interactive tutorial walkthrough.

## Key File Structure

```
ouroboros/
  skills/             # Skill implementations (*/SKILL.md)
  src/ouroboros/
    cli/              # Typer CLI entry point and command groups
      main.py         # App definition, registers: init, run, config, status, cancel, mcp, setup, tui
      commands/       # CLI command implementations
      formatters/     # Rich console output (tables, panels, progress)
    core/             # Seed spec, lineage, file locking, text utilities
    orchestrator/     # Execution strategy, level context, MCP config
    evaluation/       # Pipeline, trigger, models, artifact collector, mechanical checks
    execution/        # Subagent management
    events/           # Event definitions (decomposition, evaluation, interview, ontology, lineage)
    persistence/      # SQLAlchemy event store, migrations
    routing/          # Complexity analysis, router, escalation, downgrade
    tui/              # Textual TUI application
      screens/        # Dashboard v2/v3, execution, logs, debug, lineage, confirm-rewind
      widgets/        # AC tree, cost tracker, phase progress, drift meter, parallel graph
      components/     # Event log, progress, token tracker, agents panel
    mcp/              # Model Context Protocol integration
      server/         # MCP server with security
      client/         # MCP client manager, protocol, adapter
      tools/          # Tool registry, dashboard tools
      resources/      # Resource handlers
    observability/    # Drift detection, retrospective
    resilience/       # Retry and recovery
    config/           # Configuration models
    agents/           # Agent prompt package (src/ouroboros/agents)
    plugin/           # Plugin system (skills, agents, orchestration)
    providers/        # Runtime backend providers
    evolution/        # Regression detection, projector
    verification/     # Verifier models
    strategies/       # Execution strategies
    bigbang/          # Project bootstrapping
    codex/            # Codex CLI integration
  docs/
    getting-started.md        # Single onboarding source of truth
    architecture.md           # System design and component overview
    config-reference.md       # Configuration keys and defaults
    platform-support.md       # Supported platforms and runtimes
    runtime-capability-matrix.md  # Feature comparison across backends
    guides/                   # User guides (seed authoring, TUI, evaluation)
    runtime-guides/           # Backend-specific configuration (claude-code, codex)
    api/                      # API reference (core, MCP)
    contributing/             # Contributor guides (architecture, testing, patterns)
  tests/              # Test suite
  examples/           # Example projects
  pyproject.toml      # Package metadata: ouroboros-ai, requires Python >=3.12
```

## Runtime Backends

Ouroboros supports multiple AI runtime backends configured via `orchestrator.runtime_backend`:
- Claude Code: Primary recommended backend. Uses Claude Code sessions with MCP tool integration.
- Codex CLI: OpenAI Codex CLI as an alternative backend.
- Additional backends can be integrated via the provider system.

## Event Model

All workflow state is event-sourced. Key event categories:
- Decomposition events: AC tree creation and updates
- Evaluation events: Stage results, consensus outcomes
- Interview events: Question-answer pairs, crystallization
- Ontology events: Concept and relationship tracking
- Lineage events: Causal chain tracking

## Documentation

- Onboarding: `docs/getting-started.md`
- Architecture: `docs/architecture.md`
- API Reference: `docs/api/core.md`, `docs/api/mcp.md`
- Runtime Guides: `docs/runtime-guides/claude-code.md`, `docs/runtime-guides/codex.md`
- Contributing: `docs/contributing/`