Skip to content

AGENTS.md

Latest commit

 

History

History
170 lines (128 loc) · 8.83 KB

AGENTS.md

File metadata and controls

170 lines (128 loc) · 8.83 KB

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)

Critical Rules

These rules prevent common mistakes. Violating them causes build failures or runtime crashes.

Backend

  1. Never use metadata or registry as SQLAlchemy column names. They are reserved by SQLAlchemy's declarative API and cause InvalidRequestError on import. Use change_metadata, item_metadata, etc.

  2. Always use omoi_os.utils.datetime.utc_now() instead of datetime.utcnow(). The former returns timezone-aware datetimes compatible with the database.

  3. Use structured_output() for LLM calls that need structured data. Never manually parse JSON from LLM responses.

    from omoi_os.services.llm_service import get_llm_service
llm = get_llm_service()
result = await llm.structured_output(prompt="...", output_type=MyPydanticModel)

  4. Settings go in YAML, secrets go in .env. Application settings in config/base.yaml, secret keys/passwords in .env. Settings classes extend OmoiBaseSettings.

  5. Two separate service initialization points exist. api/main.py (API server) and workers/orchestrator_worker.py (background worker) initialize different service sets. They run as separate processes and do not share state. See the Service Availability Matrix in ARCHITECTURE.md.

Frontend

  1. Check components/ui/ before creating new primitives. 40+ ShadCN components are available. Don't reinvent Button, Card, Dialog, etc.

  2. One hook per domain in hooks/. Follow the pattern in useProjects.ts or useSpecs.ts. Use React Query for server state.

  3. API calls go through lib/api/client.ts. Add domain-specific files to lib/api/ (e.g., projects.ts, specs.ts). Never call fetch directly.

  4. Route groups: (app) for authenticated pages, (auth) for auth flows, root for public pages.

Common Tasks

Add a new API endpoint

  1. Create or edit a route file in backend/omoi_os/api/routes/
  2. Add the service method in backend/omoi_os/services/
  3. Register the route in backend/omoi_os/api/main.py if it's a new router
  4. Add tests in backend/tests/
  5. Run just test to verify

Add a new frontend page

  1. Create page.tsx in the correct frontend/app/ route group
  2. Add a sidebar panel in components/panels/ if needed, register in ContextualPanel.tsx
  3. Create domain hooks in hooks/ and API functions in lib/api/
  4. Use existing ShadCN components from components/ui/

Add a new database model

  1. Create the model in backend/omoi_os/models/
  2. Create an Alembic migration: cd backend && uv run alembic revision -m "description"
  3. Apply it: uv run alembic upgrade head
  4. Never use metadata or registry as column names

Propose a feature

Write an OIP (OmoiOS Improvement Proposal) following the template in docs/proposals/TEMPLATE.md. See docs/proposals/README.md for the process.

Development Commands

just --list          # All available commands
just dev-all         # Full stack with hot-reload
just test            # Affected tests only (via testmon)
just test-all        # Full test suite
just format          # Auto-format code
just check           # Lint + type checks

Ports: PostgreSQL 15432, Redis 16379, Backend API 18000, Frontend 3000

Finding Things

What you need Where to look
API route for a feature backend/omoi_os/api/routes/ — files named by domain
Business logic backend/omoi_os/services/ — 40+ service files
Database schema backend/omoi_os/models/ — SQLAlchemy models
Frontend page frontend/app/(app)/ — route structure matches URL
React component frontend/components/{domain}/ — grouped by domain
Data fetching hook frontend/hooks/use{Domain}.ts
API client function frontend/lib/api/{domain}.ts
Type definitions frontend/lib/api/types.ts
Page flow documentation docs/page_flows/ — 24 documented flows
User journey documentation docs/user_journey/ — end-to-end journey docs
Architecture deep-dives docs/architecture/01-*.md through 14-*.md
Improvement proposals docs/proposals/ — OIP system
Config settings backend/config/base.yaml
Test examples backend/tests/unit/, backend/tests/integration/

Architecture Summary

OmoiOS has four core systems:

  1. Planning — Spec State Machine converts feature ideas through EXPLORE → PRD → REQUIREMENTS → DESIGN → TASKS → SYNC → COMPLETE. Each phase has an LLM evaluator (quality gate).

  2. Execution — OrchestratorWorker dispatches tasks to Daytona sandboxes where ClaudeSandboxWorker runs using the Claude Agent SDK. Three modes: exploration, implementation, validation.

  3. Discovery — DiscoveryService enables adaptive branching when agents find new requirements during execution. A Phase 3 agent can spawn Phase 1 investigation tasks.

  4. Readjustment — MonitoringLoop runs Guardian (trajectory analysis, 60s), Conductor (coherence + duplicate detection, 5min), and Health Check (30s). Can redirect, refocus, or stop agents.

See ARCHITECTURE.md for the full diagram and deep-dive links.