Atlas Orchestrator
Relevant source files
The following files were used as context for generating this wiki page:
Atlas is the Master Orchestrator of the OhMyOpenCode project, serving as the conductor for all AI agent workflows. Its primary role is to coordinate, delegate, and verify the execution of complex work plans generated by planning agents like Prometheus. Atlas does not write code itself; instead, it manages specialized subagents—such as Sisyphus or Hephaestus—to perform implementation tasks while maintaining a rigorous quality assurance gate through project-level verification.
Sources: src/agents/atlas/default.ts:10-20, AGENTS.md:144-150
Core Architecture and Role
Atlas operates as a high-level manager that holds up the entire workflow by coordinating every task within a .sisyphus/plans/*.md file. It follows a "Conductor" philosophy, where it maintains the global state and context while delegating specific atomic actions to specialized workers.
Operational Philosophy
- Conduct, Don't Play: Atlas never modifies source code directly.
- Verification First: Subagents are considered "stateless" and potentially unreliable; Atlas verifies every change using LSP diagnostics, build commands, and test suites.
- Parallelism: Atlas identifies independent tasks within a plan and dispatches multiple subagents simultaneously to maximize throughput.
Sources: src/agents/atlas/default.ts:16-24, src/agents/atlas/gpt.ts:12-18
Workflow Logic
The following diagram illustrates the standard execution loop Atlas follows when processing a work plan.
The Atlas workflow emphasizes state management via a "Notepad" system and continuous verification.
Sources: src/agents/atlas/default.ts:110-180, src/agents/atlas/gpt.ts:115-160
Task Delegation System
Atlas uses the delegate_task() API to spawn specialized subagents. It chooses between specific agent types or domain-optimized "Categories" combined with "Skills."
Delegation Categories
Categories determine the underlying model and behavioral profile used for a task.
| Category | Optimized Model | Purpose |
|---|---|---|
visual-engineering | google/gemini-3-pro | Frontend, UI/UX, styling, and animations. |
ultrabrain | openai/gpt-5.2-codex | Complex architecture and deep logical reasoning. |
deep | openai/gpt-5.2-codex | Goal-oriented autonomous problem solving. |
artistry | google/gemini-3-pro | Creative, unconventional, or novel ideas. |
quick | claude-haiku-4-5 | Trivial tasks, typos, or single-file modifications. |
writing | gemini-3-flash | Documentation and technical prose. |
Sources: src/tools/delegate-task/constants.ts:123-145, src/agents/atlas/gpt.ts:75-85
Mandatory Prompt Structure
Every delegation call issued by Atlas must adhere to a strict 6-section prompt structure to ensure subagents have sufficient context, as they are essentially stateless.
- TASK: The exact quote of the checkbox item from the plan.
- EXPECTED OUTCOME: Precise deliverables and file paths.
- REQUIRED TOOLS: Whitelist of tools the subagent is allowed to use.
- MUST DO: Positive constraints (e.g., "Follow pattern in X").
- MUST NOT DO: Negative constraints (e.g., "Do NOT add dependencies").
- CONTEXT: Notepad paths and "Inherited Wisdom" from previous tasks.
Sources: src/agents/atlas/default.ts:50-85, src/agents/atlas/gpt.ts:90-110
Notepad and State Management
Because subagents are stateless, Atlas maintains a "Notepad" system to persist intelligence across the lifecycle of a project plan. This allows later tasks to benefit from "Inherited Wisdom" discovered during earlier phases.
Notepad Structure
Notepads are stored in .sisyphus/notepads/{plan-name}/ and typically include:
learnings.md: Coding conventions and discovered patterns.decisions.md: Architectural choices and rationale.issues.md: Gotchas, problems, and technical debt encountered.problems.md: Unresolved blockers.
Sources: src/agents/atlas/default.ts:133-148, src/agents/atlas/gpt.ts:125-135
Session Continuity
When a subagent fails a task, Atlas does not start a fresh session. Instead, it uses the session_id from the failed delegation to "Resume" the same agent. This preserves the agent's memory of what it has already explored and tried, resulting in significant token savings and better error recovery.
Sources: src/agents/atlas/default.ts:184-205, sisyphus-prompt.md:255-265
Verification and QA Protocol
Atlas acts as the ultimate quality gate. It never trusts a subagent's self-report and performs its own verification after every delegation.
Verification is performed at the project level, not just the file level, to catch regressions in related modules.
Sources: src/agents/atlas/default.ts:240-260, src/agents/atlas/gpt.ts:145-160
Conclusion
The Atlas Orchestrator is critical for the reliable execution of complex AI-driven development. By strictly separating the management of work (Atlas) from the execution of work (Subagents), the system enforces a level of discipline that prevents common AI failure modes like scope creep, pattern drift, and unverified regressions. Its use of session resumes and the Notepad system ensures that the orchestrator maintains a coherent "brain" across potentially hundreds of stateless subagent invocations.
Sources: src/agents/atlas/default.ts:10-15, src/agents/atlas/gpt.ts:12-20