Boulder State Management
Relevant source files
The following files were used as context for generating this wiki page:
Boulder State Management refers to the system within the Oh-My-OpenCode project responsible for maintaining the "boulder"—the persistent state of complex, multi-step engineering tasks. This system ensures that planning, requirement gathering, and execution remain synchronized across different agents and session turns.
The high-level goal of this management system is to provide a "backup brain" for agents like Prometheus and Sisyphus, preventing context loss during long-running tasks or parallel execution waves. It relies on a structured lifecycle involving drafts for working memory and formalized work plans for execution tracking.
Sources: src/agents/sisyphus.ts:31, src/agents/prometheus/identity-constraints.ts:145
Core Components and Architecture
The architecture of Boulder State Management is centered around three primary stages: Interview (Discovery), Plan Generation (Formalization), and Execution (Implementation).
1. Draft as Working Memory
During the initial "Interview Mode," the system utilizes a draft file as external memory. This prevents context loss in long conversations and ensures that the final plan is based on all gathered research and user decisions.
- Location:
.sisyphus/drafts/{name}.md - Update Trigger: Drafts are updated after every meaningful user response, agent research result, or technical decision.
- Content: Requirements, technical decisions, research findings, and scope boundaries.
Sources: src/agents/prometheus/identity-constraints.ts:145-177, src/agents/prometheus/interview-mode.ts:208-228
2. The Formal Work Plan
Once requirements are clear, the boulder state transitions from a draft to a formal work plan. This plan acts as the source of truth for execution agents (Sisyphus/Hephaestus).
- Location:
.sisyphus/plans/{plan-name}.md - Constraint: The system enforces a "Single Plan Mandate," where everything for a specific request must go into one file, even if it contains over 50 TODOs.
- Integrity Protocol: To prevent content loss, the system uses a strict write protocol where the first call creates the file and subsequent updates must use an Edit tool or specific append logic.
Sources: src/agents/prometheus/identity-constraints.ts:111-143, src/agents/prometheus/plan-generation.ts:104-106
3. Execution Tracking (TODOs)
Execution state is managed through a granular TODO system. This provides real-time visibility into progress and allows the project to maintain state even if a session is interrupted.
Sources: src/agents/sisyphus.ts:37-75
Data Flow and Transitions
The state management lifecycle follows a strict progression from discovery to verified completion.
State Transition Diagram
The following diagram illustrates how the "Boulder" (task state) moves through the system:
This diagram shows the flow from initial request through the drafting phase, formal planning, and the execution loop with verification.
Sources: src/agents/prometheus/plan-generation.ts:47-65, src/agents/prometheus/identity-constraints.ts:145-155, src/agents/sisyphus.ts:348-360
State Management Lifecycle
Phase 1: Requirement Gathering
In this phase, the system classifies user intent (e.g., Trivial, Refactoring, Architecture) and updates the draft state accordingly. A "Clearance Checklist" must be fully satisfied (all YES) before state can transition to planning.
| Checkpoint | Requirement |
|---|---|
| Core Objective | Clearly defined? |
| Scope Boundaries | IN/OUT established? |
| Technical Approach | Decided? |
| Test Strategy | Confirmed (TDD/None/QA)? |
Sources: src/agents/prometheus/identity-constraints.ts:184-192, src/agents/prometheus/interview-mode.ts:11-30
Phase 2: Plan Formalization
The transition to a formal plan involves a mandatory consultation with "Metis" for gap analysis. The system then registers a set of standardized planning TODOs (plan-1 through plan-8) to ensure accountability.
The sequence demonstrates the collaborative planning state transition involving the Metis gap analysis agent.
Sources: src/agents/prometheus/plan-generation.ts:67-106
Phase 3: Execution and Verification
During execution, Sisyphus manages the boulder by breaking the plan into parallel "waves." Every task requires evidence-based verification before the state is marked as "Completed."
Evidence Requirements:
- File Edits: Must have clean
lsp_diagnostics. - Builds: Must have Exit Code 0.
- Tests: Must pass or have documented pre-existing failures.
Sources: src/agents/sisyphus.ts:311-325, src/agents/prometheus/plan-template.ts:119-150
Storage and Paths
The Boulder State Management system adheres to strict path enforcement to ensure data integrity and agent compatibility.
| Storage Type | Allowed Path | Purpose |
|---|---|---|
| Drafts | .sisyphus/drafts/*.md | Active conversation memory and research findings. |
| Plans | .sisyphus/plans/*.md | The definitive work plan and source of truth for execution. |
| Evidence | .sisyphus/evidence/ | Screenshots, terminal outputs, and API response logs. |
| Notepads | .sisyphus/notepads/ | Cumulative intelligence shared between stateless subagents. |
Sources: src/agents/prometheus/identity-constraints.ts:98-110, src/agents/prometheus/plan-template.ts:153-160
Conclusion
Boulder State Management is the foundation of autonomous work in Oh-My-OpenCode. By enforcing a strict write protocol for plans, maintaining a continuous draft for research, and requiring evidence for task completion, the system ensures that complex engineering boulders are successfully rolled to completion without context loss or structural decay.
Sources: src/agents/prometheus/identity-constraints.ts:111-143, src/agents/sisyphus.ts:400-410