llms.txt · diff
git:20261113.04f6f79 to git:20261113.3310935
63 added, 16 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
> 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 generated from interview results or already-agreed requirements. 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 host-skill flow, confirm the agreed goal, request `ooo seed`, and inspect the returned YAML before execution; interview completion alone does not establish that a Seed exists. The standalone CLI and Auto have separate generation flows. See `skills/seed/SKILL.md`; manual YAML 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 clarifies requirements. After its closure checks and user confirmation of the agreed goal, the host Interview skill suggests `ooo seed`; this does not itself produce a Seed artifact.
- 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: PAL router — picks a model tier per unit of work and escalates it on retry (no complexity scoring, no downgrade). Located in `src/ouroboros/orchestrator/model_routing.py` and `src/ouroboros/orchestrator/route_escalation.py`.
- 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): Skills invoked inside a Claude Code session. Primary recommended path. Invoke setup explicitly with `/ouroboros:setup`; other commands include `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`.
+ - `ooo` (Claude Code): Skills invoked inside a Claude Code session. Primary recommended path. Invoke setup explicitly with `/ouroboros:setup`; other commands include `ooo interview "idea"`, `ooo run`, `ooo evaluate`, `ooo evolve`, `ooo status`, `ooo unstuck`, `ooo cancel`. Every skill is listed under Commands / Skills below.
+ - `ouroboros` (Typer CLI): Standalone CLI installed via `pip install ouroboros-ai`. Fallback path. Subcommands: see CLI Commands below.
+ ## CLI Commands
+
+ Every top-level command `ouroboros --help` lists; `ouroboros <command> --help` shows its options. Rendered from the CLI registry by `scripts/gen-llms-catalog.py`.
+
+ <!-- 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 -->
+
## Commands / Skills
- - setup: Guided onboarding wizard. Configures runtime backend and project settings.
- - interview (aliases: socratic): Clarify vague requirements through Socratic questioning. After closure checks and goal confirmation, the host skill suggests `ooo seed`.
- - seed (aliases: crystallize): Generate a Seed from interview results or already-agreed context. Request `ooo seed` in the host-skill flow and inspect the returned YAML. Calling the skill is distinct from manually authoring YAML, which 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.
+ A skill runs as `ooo <name>` (or `/ouroboros:<name>`), and an alias works the same way; a skill marked "invoke as `/ouroboros:<name>`" runs only when that command is typed explicitly. Rendered from `skills/*/SKILL.md` by `scripts/gen-llms-catalog.py`.
+ <!-- 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` (aliases: `kill`, `abort`): Cancel stuck or orphaned executions
+ - `config` (aliases: `ouroboros-config`): Open or drive the Ouroboros settings GUI (browser, TUI, or conversational fallback)
+ - `evaluate` (aliases: `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` (aliases: `ouroboros-help`): Ouroboros command reference and troubleshooting guidance for installation, MCP, status, and recovery
+ - `idk` (aliases: `dont-know`, `calibrate`): Calibrate interview explanations from the user's stated understanding
+ - `interview` (aliases: `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` (aliases: `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` (aliases: `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).
+ - `setup` (invoke as `/ouroboros:setup`): Guided onboarding wizard for Ouroboros setup
+ - `status` (aliases: `ouroboros-status`, `drift`): Check session status and measure goal drift
+ - `tutorial` (invoke as `/ouroboros:tutorial`): Interactive tutorial teaching Ouroboros hands-on
+ - `unstuck` (aliases: `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
+ - `welcome` (invoke as `/ouroboros:welcome`): First-touch experience for new Ouroboros users
+ <!-- generated:skills end -->
+
## 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
+ main.py # App definition; registers every command under CLI Commands
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/`