Task Storage & Boulder State Schema

Relevant source files

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

• src/features/claude-tasks/types.ts
• src/features/claude-tasks/AGENTS.md
• src/agents/hephaestus.ts
• src/agents/prometheus/plan-generation.ts
• src/tools/delegate-task/constants.ts
• sisyphus-prompt.md

The Task Storage and Boulder State systems provide a standardized, Claude Code-compatible mechanism for managing work objectives within the OhMyOpenCode ecosystem. These systems ensure that complex, multi-step engineering tasks are decomposed into atomic, trackable units that can be executed by specialized agents while maintaining full visibility for the orchestrator.

At its core, the system utilizes a Zod-validated schema to define task properties and state transitions. This infrastructure supports both persistent project-wide tasks and transient session-scoped objectives, enabling agents like Atlas and Sisyphus to coordinate parallel execution waves and verify completion via explicit Agent-Executed QA scenarios.

Sources: src/features/claude-tasks/AGENTS.md, sisyphus-prompt.md

Task Schema and Data Model

The task schema defines the structural requirements for every work unit. It represents a transition from legacy systems by introducing imperative subjects and explicit dependency tracking through blocking relationships.

Task Object Structure

Field	Type	Description
id	string	Unique identifier generated as T-{uuid}.
subject	string	Imperative summary of the task (e.g., "Run tests").
description	string	Detailed requirements and context.
status	TaskStatus	Current state: pending, in_progress, completed, or deleted.
activeForm	string	Present continuous form for UI display (e.g., "Running tests").
blocks	string[]	List of Task IDs that depend on this task's completion.
blockedBy	string[]	List of Task IDs that must be completed before this task starts.
owner	string	The agent name currently assigned to the task.
metadata	Record<string, unknown>	Extensible storage for task-specific context.

Sources: src/features/claude-tasks/AGENTS.md:14-36, src/features/claude-tasks/types.ts

Entity Relationship Diagram

The following diagram illustrates the relationships between tasks and their dependency management.

Task Lifecycle and State Discipline

The system enforces strict "Todo Discipline" to ensure that multi-step work remains trackable and recoverable. Agents are forbidden from batch-completing tasks or proceeding without explicitly updating the status to in_progress.

State Transition Flow

Execution Constraints

• Atomic Breakdown: Any work requiring two or more steps must be initialized via todowrite or TaskCreate.
• Single Active Task: Agents should only mark one task as in_progress at a time.
• Immediate Updates: Completion must be marked immediately after verification, never batched at the end of a session.

Sources: src/agents/hephaestus.ts:46-60, sisyphus-prompt.md:292-310

Storage and Retrieval Mechanisms

Tasks are persisted in a specific directory structure, often utilizing file-based locks to ensure atomic writes. The system distinguishes between project-level storage and session-specific temporary notepads.

Storage Hierarchy

Function	Purpose
getTaskDir	Retrieves the primary task storage path based on project configuration.
writeJsonAtomic	Ensures data integrity by writing to a temporary file before renaming.
acquireLock	Implements a file-based lock with a 30-second stale threshold for concurrency.
getSessionTaskDir	Provides a scoped directory for tasks unique to an agent session.
findTaskAcrossSessions	Allows the orchestrator to locate a task ID regardless of which session created it.

Sources: src/features/claude-tasks/AGENTS.md:40-52

Plan Storage Paths

Work plans generated by the Prometheus agent are strictly enforced to reside in specific locations:

• Plans: .sisyphus/plans/{plan-name}.md
• Drafts: .sisyphus/drafts/{name}.md
• Notepads: .sisyphus/notepads/{plan-name}/ (used for cumulative intelligence across stateless subagents).

Sources: src/agents/prometheus/identity-constraints.ts:108-120, src/tools/delegate-task/constants.ts:315-325

Dependency and Parallel Execution Mapping

For complex projects, the schema facilitates the creation of a Parallel Execution Graph. Tasks are grouped into "Waves" based on their blockedBy relationships.

Execution Wave Structure

Verification and Success Criteria

A task is not considered "completed" within the Boulder State until it passes agent-executable verification. Human intervention (e.g., "User manually tests") is explicitly forbidden in the plan schema.

Verification Matrix

Deliverable Type	Primary Tool	Evidence Required
Frontend/UI	Playwright	DOM assertions, Screenshots in .sisyphus/evidence/.
TUI/CLI	interactive_bash	Captured terminal output, Exit code 0.
API/Backend	Bash / curl	HTTP status codes, JSON field validation.
Code Change	lsp_diagnostics	Zero errors returned at the project level.

Sources: src/agents/prometheus/plan-template.ts:105-135, sisyphus-prompt.md:265-275

The state of a task must be updated based on these concrete failure or success indicators. If three consecutive verification attempts fail, the agent is required to revert to the last known working state and consult the Oracle agent.

Sources: src/agents/hephaestus.ts:340-355, sisyphus-prompt.md:248-260