Core Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• src/agents/prometheus/identity-constraints.ts
• src/agents/prometheus/plan-generation.ts
• src/agents/atlas/gpt.ts
• src/agents/hephaestus.ts
• src/agents/metis.ts
• src/agents/momus.ts
• AGENTS.md

The Core Architecture of oh-my-opencode is centered around a multi-model agent orchestration system designed to automate complex software engineering workflows. The system separates high-level strategic planning, rigorous review, and autonomous execution into specialized roles, ensuring high-quality outputs through structured "loops" and strict identity constraints.

The architecture follows a modular pattern where agents communicate through delegation, shared state (drafts and notepads), and a robust task management system. This structure allows the system to scale from simple file modifications to complex, repository-wide refactoring tasks.
Sources: AGENTS.md, src/agents/prometheus/identity-constraints.ts:10-30

Multi-Agent Orchestration Framework

The system utilizes an tiered orchestration model where specialized agents handle distinct phases of the development lifecycle. This hierarchy ensures that no single model is overwhelmed by the dual requirements of planning and execution.

Agent Hierarchy and Roles

The orchestration is primarily managed by Atlas, which serves as the "Master Orchestrator." Atlas does not perform code edits but coordinates other agents to fulfill a work plan.

Agent	Tier	Primary Responsibility	Model (Default)
Atlas	Orchestrator	Coordination, delegation, and project-level verification.	Claude 3.5 Sonnet
Prometheus	Strategist	Multi-phase planning, requirement gathering, and work plan generation.	Claude 4.5 Opus
Metis	Consultant	Pre-planning analysis, ambiguity detection, and guardrail definition.	High-IQ Reasoning Model
Momus	Reviewer	Ruthless plan verification to ensure executability and reference validity.	Expensive Reasoning Model
Hephaestus	Executor	Autonomous deep worker for complex implementation and refactoring.	GPT-5.2 Codex
Sisyphus	Orchestrator	Primary orchestrator and general worker.	Claude 4.5 Opus

Sources: AGENTS.md:167-180, src/agents/atlas/gpt.ts:16-25, src/agents/metis.ts:10-20, src/agents/hephaestus.ts:114-125

The Planning and Execution Loop

The core workflow is a three-phase transition from initial intent to verified deployment:

1. Phase 1: Interview & Analysis (Metis/Prometheus): Requirements are clarified, and the codebase is explored to identify patterns.
2. Phase 2: Plan Generation & Review (Prometheus/Momus): A single, atomic work plan is generated and reviewed for blocking issues.
3. Phase 3: Orchestrated Execution (Atlas/Hephaestus): The plan is broken into parallel "waves" and executed by implementation agents.

Strategic Planning (Prometheus)

Prometheus is governed by strict identity constraints. It is a planner, not an implementer. It is strictly forbidden from writing code or modifying source files (except within the .sisyphus/ directory).

Intent Classification

Before planning, the system classifies requests into intent types to determine the interview strategy:

• Trivial/Simple: Fast turnaround, minimal interview.
• Refactoring: Focus on safety, regression prevention, and impact mapping.
• Build from Scratch: Discovery-focused, identifying existing patterns to maintain consistency.
• Architecture: Strategic focus involving multi-system tradeoffs; requires Oracle consultation.

Sources: src/agents/prometheus/identity-constraints.ts:16-40, src/agents/prometheus/interview-mode.ts:10-35

Mandatory Work Plan Structure

All plans generated by Prometheus must follow a standardized Markdown template located in .sisyphus/plans/{name}.md.

Section	Requirement
TL;DR	Deliverables, effort estimate, and critical path.
Verification Strategy	Universal Rule: Zero human intervention. All tasks must be agent-verifiable.
Execution Strategy	Tasks grouped into parallel waves to maximize throughput.
TODOs	Atomic implementation + test units with recommended agent profiles and skills.

Sources: src/agents/prometheus/plan-template.ts:10-40, src/agents/prometheus/plan-template.ts:150-180

Execution & Verification (Atlas & Hephaestus)

Once a plan is approved by Momus, Atlas manages the execution by delegating tasks.

The "Notepad" Protocol

Because subagents are stateless, Atlas maintains "Cumulative Intelligence" via a notepad system. Before every delegation, Atlas reads from .sisyphus/notepads/ and injects "Inherited Wisdom" (conventions, previous decisions, and discovered issues) into the subagent's prompt.
Sources: src/agents/atlas/gpt.ts:185-200

Autonomous Implementation (Hephaestus)

For deep engineering tasks, Hephaestus operates with "Judicious Initiative." It follows an Explore-First protocol, attempting to find missing information using tools like gh, git, and grep before ever asking the user a clarifying question.

Task Management and State

The system relies on a non-negotiable task discipline to provide visibility and enable recovery.

• State Persistence: Interviews are recorded in .sisyphus/drafts/. Orchestration context is stored in .sisyphus/notepads/.
• Atomic Progress: Every multi-step task must be registered using TodoWrite or TaskCreate. Agents must update status to in_progress before starting and completed immediately upon finishing a step.
• Verification Gates: Atlas serves as the final QA gate. It verifies subagent claims by running lsp_diagnostics, bun run build, and bun test independently.

Sources: src/agents/prometheus/identity-constraints.ts:173-195, src/agents/atlas/gpt.ts:203-215, src/agents/hephaestus.ts:50-75

Summary

The core architecture of oh-my-opencode establishes a robust, fail-safe environment for AI-driven development. By enforcing a separation of concerns between planning (Prometheus), reviewing (Momus/Metis), and executing (Atlas/Hephaestus), the system minimizes "AI slop" and ensures that code changes are consistent with existing project patterns and strictly verified through automated testing.