Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The oh-my-opencode project is structured as a multi-agent orchestration system designed for autonomous software engineering. It utilizes a specialized hierarchy of agents, each with distinct roles: strategic planning, coordination, execution, and expert consultation. The system operates on a "Plan-First" philosophy, where implementation is strictly separated from planning to ensure codebase integrity and decision completeness.
The architecture follows a tiered execution model where a Master Orchestrator (Atlas) coordinates specialized agents (like Sisyphus) to execute tasks derived from comprehensive work plans generated by a Strategic Planner (Prometheus). This ensures that every modification to the codebase is backed by a verified, "decision-complete" plan.
Agent Hierarchy and Roles
The system's core architecture is defined by the interaction between several specialized agent types. These agents are categorized by their function within the development lifecycle.
Core Agent Types
| Agent | Category | Primary Responsibility |
|---|---|---|
| Prometheus | Strategic Planner | Conducts interviews, explores codebase, and generates "decision-complete" work plans. |
| Atlas | Master Orchestrator | Coordinates the execution of work plans and manages the "Final Verification Wave." |
| Sisyphus | Orchestrator/Executor | Performs the actual engineering work or delegates it to specialized subagents. |
| Metis | Pre-Planning Advisor | Analyzes requests for ambiguity and identifies hidden intentions before planning begins. |
| Oracle | Technical Advisor | Provides high-IQ reasoning for complex architecture and hard debugging scenarios. |
| Momus | Plan Reviewer | Ruthlessly reviews work plans to catch blockers and verify file references. |
Sources: [src/agents/prometheus/gpt.ts], [src/agents/atlas/gpt-prompt-sections.ts], [src/agents/metis.ts], [src/agents/oracle.ts], [src/agents/momus.ts]
System Flow Diagram
This diagram illustrates the high-level workflow from a user request to the final verified implementation.
Sources: [src/agents/prometheus/gpt.ts:47-110], [src/agents/metis.ts:31-60], [src/agents/momus.ts:140-160]
The Planning Lifecycle (Prometheus & Metis)
The architecture mandates that no code is written without a plan. This phase is governed by the "Strategic Planning Consultant," Prometheus, often preceded by Metis.
Intent Classification
Before any planning occurs, the system classifies the user's intent into tiers (Trivial, Standard, Architecture) to determine the depth of the subsequent interview and exploration.
Sources: [src/agents/prometheus/gpt.ts:62-71], [src/agents/prometheus/interview-mode.ts:13-35]
Exploration and Interview
Prometheus follows a "Explore Before Asking" principle. It launches background agents to map codebase patterns before asking the user clarifying questions. Findings are recorded in a draft file (.sisyphus/drafts/*.md) which acts as the agent's "backup brain."
Sources: [src/agents/prometheus/gpt.ts:33-40], [src/agents/prometheus/gpt.ts:114-135]
Work Plan Generation
A plan is considered "decision-complete" when the executor needs zero judgment calls. The generated plan (saved to .sisyphus/plans/*.md) includes:
- Parallel Execution Waves: Tasks grouped to maximize throughput.
- QA Scenarios: Mandatory "Happy Path" and "Failure" scenarios for every task.
- Final Verification Wave: A set of four parallel reviews (Plan Compliance, Code Quality, Manual QA, and Scope Fidelity).
Sources: [src/agents/prometheus/gpt.ts:25-30], [src/agents/prometheus/plan-template.ts:145-210]
Execution and Orchestration (Atlas & Sisyphus)
Once a plan is reviewed by Momus and approved, Atlas takes over the orchestration.
The Orchestration Loop
Atlas parses the .sisyphus/plans/*.md file and manages the task state. It maintains a "Notepad" (.sisyphus/notepads/) to store learnings and issues encountered during execution.
Sources: [src/agents/atlas/gpt-prompt-sections.ts:46-65]
Execution Sequence Diagram
This diagram shows the interaction between the Orchestrator and Implementation agents.
Sources: [src/agents/atlas/gpt-prompt-sections.ts:77-135], [src/agents/sisyphus/default.ts:335-365]
Technical Constraints and Safety
The architecture enforces strict boundaries to prevent "AI slop" and unauthorized modifications.
- Prometheus MD-Only Hook: Prometheus is strictly blocked from writing anything except Markdown files in specific
.sisyphus/directories. - Task/Todo Discipline: All multi-step work must be tracked via
todowriteorTaskCreatetools to provide real-time visibility and recovery points. - Manual QA Mandate: For anything user-facing, agents must execute manual QA (via Playwright or interactive bash) and show evidence of the actual output.
Sources: [src/agents/prometheus/gpt.ts:54-58], [src/agents/sisyphus/default.ts:13-40], [src/hooks/keyword-detector/ultrawork/gpt.ts:133-145]
Specialized Advisors
The system leverages "Expert" agents for specific high-stakes decisions:
- Oracle: Invoked for architecture decisions, multi-system tradeoffs, or when a fix fails 2+ times. It operates with a "pragmatic minimalism" framework, biasing toward simplicity and existing patterns.
- Metis: Acts as a pre-planning buffer to catch unstated requirements and prevent over-engineering. It categorizes tasks into specific strategies (e.g., Refactoring vs. Build from Scratch).
Sources: [src/agents/oracle.ts:10-25], [src/agents/metis.ts:31-50]
The oh-my-opencode architecture provides a robust, multi-layered environment where planning, execution, and verification are handled by specialized agents to ensure production-grade software engineering outcomes.