OmoiOS AGENTS.md

AGENTS.md — AI Coding Agent Guide for OmoiOS

This document helps AI coding agents (Claude Code, Cursor, Copilot Workspace, Windsurf, etc.) understand and contribute to OmoiOS efficiently.

What is OmoiOS?

OmoiOS is a spec-driven, multi-agent orchestration system. Users describe a feature, OmoiOS plans it (requirements → design → tasks), executes it with autonomous AI agents in isolated sandboxes, and creates a PR. The core promise: "Start a feature before bed. Wake up to a PR."

Production: Frontend at https://omoios.dev, API at https://api.omoios.dev

Read These First

Document	Purpose	When to read
ARCHITECTURE.md	System design, service map, data flow	Before any backend work
UI.md	Frontend routes, components, state, design system	Before any frontend work
backend/CLAUDE.md	Backend conventions, patterns, anti-patterns	Before writing Python
CLAUDE.md	Monorepo structure, dev commands, ports	Always
CONTRIBUTING.md	Branch conventions, PR process, testing	Before submitting changes
docs/rules/	Per-mistake rules — tripwires we've already hit (SQLAlchemy session handling, reserved column names, feature flag gotchas)	Before editing dependencies, route handlers, or models

Repository Map

senior_sandbox/
├── backend/omoi_os/
│   ├── api/
│   │   ├── main.py              # FastAPI app + lifespan (25+ services initialized)
│   │   └── routes/              # 38 route files by domain
│   ├── services/                # Business logic (~40 service files)
│   │   ├── models/                  # SQLAlchemy 2.0 models (~77 model classes)
│   ├── workers/                 # Background workers (orchestrator, sandbox)
│   └── config.py                # OmoiBaseSettings (YAML + env)
│
├── backend/config/
│   ├── base.yaml                # Default application settings
│   └── test.yaml                # Test overrides
│
├── backend/tests/
│   ├── unit/                    # Fast isolated tests
│   ├── integration/             # Multi-component tests
│   └── e2e/                     # Full workflow tests
│
├── frontend/
│   ├── app/                     # Next.js 15 App Router
│   │   ├── (app)/               # Authenticated routes (command, projects, sandboxes, etc.)
│   │   ├── (auth)/              # Login, register, OAuth callback
│   │   └── (dashboard)/         # Root redirect to /command
│   ├── components/
│   │   ├── ui/                  # ShadCN primitives (40+) — do not modify
│   │   ├── layout/              # App shell (MainLayout, IconRail, ContextualPanel)
│   │   ├── panels/              # Sidebar panels (route-aware)
│   │   └── {domain}/            # Domain components (command, spec, sandbox, etc.)
│   │   ├── hooks/                   # 29 React Query + Zustand hooks (one per domain)
│   ├── lib/api/                 # HTTP client + domain-specific API functions
│   └── providers/               # Context providers (Query, Auth, Theme, PostHog)
│
├── subsystems/spec-sandbox/     # Spec execution runtime
├── docs/
│   ├── proposals/               # OmoiOS Improvement Proposals (OIPs)
│   │   ├── page_flows/              # 24 page-by-page UI flow docs
│   ├── user_journey/            # End-to-end user journey docs
│   │   └── architecture/            # 14 system deep-dive docs
└── Justfile                     # Task runner (just --list for all commands)