Core Architecture and Event Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Core Architecture of the OhMyOpenCode system is built upon a decoupled, agent-centric model designed to separate strategic planning from technical execution. This architecture follows a strict lifecycle where different specialized agents manage specific phases of a task, ensuring high-quality output, deterministic execution, and automated verification. The system moves through distinct stages: Consultation (Metis), Planning (Prometheus), Review (Momus), and Orchestrated Execution (Atlas/Hephaestus).
Central to this lifecycle is the principle of "Planning ≠ Doing." The planning phase is handled by Prometheus, which acts as a strategic consultant, while the implementation is delegated to autonomous workers like Hephaestus or orchestrated by Atlas. This separation prevents "AI slop" and ensures that every code change is backed by a verified plan and rigorous QA scenarios.
Sources: src/agents/prometheus/identity-constraints.ts:15-35, sisyphus-prompt.md:21-35
Agent Roles and Hierarchy
The architecture utilizes a specialized hierarchy where agents are categorized by their reasoning capabilities and operational roles.
Primary Orchestrators and Advisors
- Atlas: The "Master Orchestrator" who coordinates multiple subagents, manages parallel execution, and verifies all results. Atlas never writes code directly but manages the execution of the work plan.
- Prometheus: The strategic planner. It conducts interviews, gathers requirements, and generates a structured work plan in Markdown.
- Oracle: A high-IQ, read-only advisor used for complex architectural decisions, multi-system tradeoffs, and debugging hard problems.
- Metis: A pre-planning consultant that analyzes user requests to detect ambiguities and over-engineering patterns before the planner begins.
Specialized Workers and Subagents
- Hephaestus: An autonomous deep worker optimized for end-to-end task completion, multi-file refactoring, and codebase pattern matching.
- Sisyphus: The primary agent identity that handles general engineering tasks, delegation, and verification.
- Momus: A ruthless plan reviewer that validates the executability of work plans before they are passed to an orchestrator.
Sources: src/agents/atlas/gpt.ts:16-25, src/agents/oracle.ts:14-30, src/agents/metis.ts:14-25, src/agents/momus.ts:15-28
The Event Lifecycle: From Intent to Execution
The lifecycle of a user request follows a deterministic path through the agent ecosystem. This process ensures that no code is written without a verified plan and that all work is tracked via a task/todo system.
Phase 1: Intent Gate and Consultation
Every request enters through an "Intent Gate." The system first scans for specific skill triggers (like git-master or playwright). If the request is complex, Metis is invoked to classify the intent (Refactoring, Build from Scratch, Research, etc.) and identify hidden requirements.
Phase 2: Strategic Planning (Prometheus)
Prometheus conducts an interview to clear a "Clearance Checklist." Once requirements are clear, it transitions to plan generation. It mandatory registers a 8-step todo list and consults Metis for a final gap analysis.
| Checklist Item | Requirement |
|---|---|
| Core Objective | Clearly defined and understood |
| Scope Boundaries | Explicit IN/OUT boundaries established |
| Technical Approach | Decided and validated |
| Test Strategy | TDD/Tests-after/None confirmed |
| QA Scenarios | Agent-executable scenarios defined |
Sources: src/agents/prometheus/identity-constraints.ts:81-95, src/agents/prometheus/plan-generation.ts:21-45
Phase 3: Plan Review (Momus)
Before execution, the work plan is submitted to Momus. Momus finds "blocking issues" only, such as non-existent file references or impossible tasks. If approved (OKAY), the lifecycle moves to execution. If rejected, the plan returns to Prometheus for fixing.
Phase 4: Orchestrated Execution (Atlas)
Atlas analyzes the approved plan, builds a parallelization map, and delegates individual tasks using the task() tool. Atlas follows a "Notepad Protocol" to maintain state across different subagent sessions.
The Execution Loop:
- Analyze Plan: Parse incomplete checkboxes and identify parallel groups.
- Pre-Delegation: Read "Notepad" wisdom (learnings, decisions).
- Invoke Task: Delegate to specialized subagents with a 6-section prompt.
- Project-Level QA: Verify every change using
lsp_diagnostics, builds, and tests.
Sources: src/agents/atlas/gpt.ts:101-145, src/agents/hephaestus.ts:200-220
Task and Todo Discipline
A core architectural constraint is the mandatory use of the task/todo system for any multi-step work. This serves as the "execution backbone" and ensures session continuity.
Todo Workflow Protocol
- Creation:
TodoWritemust be called at the start of any multi-step task to provide an atomic breakdown. - In Progress: Agents must mark exactly one task as
in_progressbefore starting. - Completion: Tasks must be marked
completedimmediately after verification. Batch-completing is strictly forbidden.
Sources: src/agents/hephaestus.ts:15-50, sisyphus-prompt.md:248-270
Verification and Success Criteria
The architecture enforces a "Zero Human Intervention" principle for verification. Every task must be verifiable by the agent using automated tools.
| Deliverable Type | Verification Tool | Evidence Required |
|---|---|---|
| Frontend/UI | Playwright | DOM assertions and Screenshots |
| TUI/CLI | interactive_bash (tmux) | Stdout/Stderr capture and Exit codes |
| API/Backend | Bash (curl) | HTTP status codes and JSON response parsing |
| Code Structure | LSP / Diagnostics | Zero errors in modified files |
Sources: src/agents/hephaestus.ts:265-285, src/agents/prometheus/plan-template.ts:100-125
Conclusion
The OhMyOpenCode architecture ensures software quality by enforcing a strict lifecycle where planning is decoupled from execution. By utilizing a multi-agent system with clear boundaries—Consultant (Metis), Planner (Prometheus), Reviewer (Momus), and Orchestrator (Atlas)—the system maintains high technical standards, automates regression testing, and provides a transparent, trackable workflow for developers. This cycle of "Plan, Review, Execute, Verify" minimizes common AI implementation failures and ensures code matches existing project patterns.