Sisyphus & Junior
Relevant source files
The following files were used as context for generating this wiki page:
Sisyphus is the primary orchestrator agent within the oh-my-opencode project, designed to manage complex engineering tasks through a combination of autonomous execution and delegation to specialized subagents. Operating as the "dev team lead," Sisyphus leverages advanced orchestration capabilities to parse requirements, adapt to codebase maturity, and ensure task completion through a rigorous TODO-based enforcement system.
Sisyphus-Junior (often referred to in the context of delegate_task categories) represents the specialized execution layer. When Sisyphus delegates a task using a specific category and skill set, it effectively spawns a domain-optimized instance (Junior) to perform technical work such as frontend engineering, deep research, or atomic commits. This hierarchical structure allows the system to maintain a lean context for the primary agent while utilizing specialized models for domain-specific implementation.
Sources: README.md, src/agents/sisyphus.ts:241-255, sisyphus-prompt.md:46-55
Core Architecture and Identity
Sisyphus is defined by its identity as an SF Bay Area senior engineer. It is built to "roll the boulder" of code development relentlessly. The architecture follows a multi-tier delegation model where Sisyphus acts as the central intelligence, coordinating with specialized advisors and executors.
Agent Hierarchy
The system categorizes agents into functional roles to optimize token usage and reasoning quality:
| Agent Name | Role | Primary Responsibility |
|---|---|---|
| Sisyphus | Primary | Main orchestrator, intent classification, and team lead. |
| Atlas | Orchestrator | Execution of multi-task work plans via delegate_task. |
| Prometheus | Planner | Strategic planning, requirement gathering, and plan generation. |
| Oracle | Advisor | High-IQ reasoning for architecture and hard debugging. |
| Librarian | Researcher | External documentation and remote codebase analysis. |
| Explore | Researcher | Fast contextual grep for internal codebase exploration. |
Sources: src/agents/sisyphus.ts:244-250, AGENTS.md:129-138, sisyphus-prompt.md:16-25
Orchestration Flow
The following diagram illustrates how Sisyphus processes a user request and coordinates with the ecosystem:
The flow moves from initial intent classification to research, planning, and finally execution by Junior agents.
Sources: sisyphus-prompt.md:65-95, src/agents/atlas/default.ts:16-25, src/agents/prometheus/identity-constraints.ts:10-30
Sisyphus-Junior: The Execution Layer
Sisyphus-Junior is the conceptual "worker" agent spawned when delegate_task() is called with a specific category. Unlike the primary Sisyphus, which manages the "big picture," Junior instances are stateless, domain-specific, and strictly bound by the instructions provided in the delegation prompt.
Delegation Categories
Sisyphus-Junior is configured by selecting a category that optimizes the model for a specific domain:
- visual-engineering: Optimized for Frontend, UI/UX, and animations.
- ultrabrain: Used for deep logical reasoning and complex architecture.
- artistry: For creative or novel ideas.
- quick: For trivial, single-file changes or typo fixes.
- writing: Technical writing and documentation.
Sources: sisyphus-prompt.md:27-35, src/agents/sisyphus.ts:21-30
Skill Injection
Junior's capabilities are further refined by injecting "Skills." These are mandatory specialized workflows:
- playwright: Required for all browser-related automation.
- frontend-ui-ux: Provides designer-level aesthetic judgment.
- git-master: Handles atomic commits and history search.
Sources: sisyphus-prompt.md:213-225, src/agents/sisyphus.ts:252-258
Task and Session Management
A critical component of Sisyphus's reliability is its "Bouldering" mode, enforced through TODO management and session continuity.
The TODO System
Sisyphus and its orchestrators (Atlas) are mandated to create TODO lists before starting any non-trivial task. This is a non-negotiable mechanism to prevent "AI slop" and ensure accountability.
- Step 1:
TaskCreateorTodoWriteatomic steps immediately upon request. - Step 2: Mark steps as
in_progress(strictly one at a time). - Step 3: Mark steps as
completedimmediately upon verification (no batching).
Sources: src/agents/sisyphus.ts:46-75, src/agents/atlas/default.ts:77-87
Session Continuity (session_id)
To maintain efficiency, Sisyphus uses session_id to resume subagents. This preserves the full conversation context, preventing Junior from re-reading files or repeating failed exploration paths.
The use of session_id saves approximately 70% of tokens on follow-up tasks and retries.
Sources: src/agents/sisyphus.ts:314-335, src/agents/atlas/default.ts:145-165
Operating Constraints
Sisyphus and Junior operate under strict "Hard Blocks" and "Anti-Patterns" to maintain codebase integrity.
Prohibited Actions
| Category | Forbidden Action |
|---|---|
| Implementation | Suppressing type errors (as any, @ts-ignore). |
| Logic | Empty catch blocks (catch(e) {}). |
| Testing | Deleting failing tests to force a "pass" status. |
| Orchestration | Delegating without evaluating and justifying skill selection. |
| Planning | Prometheus writing code files or performing implementations. |
Sources: sisyphus-prompt.md:435-445, src/agents/prometheus/identity-constraints.ts:18-30, AGENTS.md:106-127
Verification Protocol
No task is considered complete without verifiable evidence. Sisyphus and Atlas act as the QA gate:
- LSP Diagnostics: Must be clean on all changed files.
- Build Verification:
bun run buildmust return exit code 0. - Test Verification:
bun testmust pass all relevant suites. - Manual Verification: Reading changed files to ensure requirements are met.
Sources: src/agents/atlas/default.ts:124-143, sisyphus-prompt.md:415-425
Conclusion
The Sisyphus & Junior system transforms the AI agent from a simple code generator into a structured engineering team. By separating strategic planning (Prometheus), orchestration (Atlas), and domain-specific execution (Junior), the project ensures high-quality, verifiable output that follows established codebase patterns while minimizing context-window bloat.