Task Schema and Todo Sync
Relevant source files
The following files were used as context for generating this wiki page:
The Task Schema and Todo Sync system provides a structured framework for managing, tracking, and synchronizing multi-step engineering work within the OhMyOpenCode ecosystem. It ensures that complex objectives are decomposed into atomic, verifiable units of work that can be executed by specialized agents while maintaining real-time visibility for the user.
This system bridges the gap between high-level strategic planning (handled by agents like Prometheus) and autonomous execution (handled by agents like Sisyphus). It utilizes a formal JSON-based task schema and a synchronization mechanism that pushes local updates to the OpenCode Todo API, ensuring consistency across the agent's "boulder" state and external tracking interfaces.
Sources: src/features/claude-tasks/AGENTS.md, src/agents/sisyphus/default.ts:47-66
Task Data Model
The core of the system is a strictly defined Task interface. This schema supports hierarchical relationships, dependency tracking (blocking/blockedBy), and session-specific metadata to ensure continuity across agent turns.
Task Schema Definition
| Field | Type | Description |
|---|---|---|
id | string | Auto-generated unique identifier (format: T-{uuid}). |
subject | string | A short, descriptive title for the task. |
description | string (Optional) | Detailed technical context or instructions. |
status | enum | Current state: pending, in_progress, completed, or deleted. |
blocks | string[] | Array of IDs representing tasks that depend on this one. |
blockedBy | string[] | Array of IDs representing tasks that must finish before this starts. |
threadID | string | Associated session/thread ID for context preservation. |
parentID | string (Optional) | ID of the parent task for hierarchical grouping. |
Sources: src/features/claude-tasks/types.ts, src/features/claude-tasks/AGENTS.md:12-25
Task State Transitions
The system enforces a non-negotiable workflow for status updates to prevent "black box" execution. Agents are required to mark tasks as in_progress before starting and completed immediately upon verification.
The state diagram illustrates the lifecycle of a task from creation to completion, emphasizing the requirement for atomic updates.
Sources: src/agents/sisyphus/default.ts:40-52, src/features/claude-tasks/types.ts
Todo Synchronization and Persistence
Tasks are persisted as individual JSON files within the .sisyphus/tasks/ directory. The system employs atomic write operations (writing to a temp file then renaming) and file-based locking to handle concurrent access by multiple subagents.
Sync Workflow
Updates to the local task state are automatically synchronized with the OpenCode Todo API. This ensures that the user-facing UI always reflects the agent's current progress.
The flow diagram depicts the persistence and synchronization logic used to maintain task integrity across sessions.
Sources: src/features/claude-tasks/AGENTS.md:33-40, src/agents/sisyphus/default.ts:54-66
Formatting and Granularity Rules
To maintain high execution quality, the system mandates a specific format for todo titles. Every task must encode four critical elements: WHERE, HOW, WHY, and EXPECTED RESULT.
The Title Contract
The mandatory format is: "[WHERE] [HOW] to [WHY] - expect [RESULT]"
- Example:
"src/utils/validation.ts: Add validateEmail() for input sanitization - returns boolean" - Granularity: Each task must be a single atomic action completable in 1-3 tool calls. If a task requires editing multiple files or complex logic, it must be split into sub-tasks.
Sources: src/hooks/todo-description-override/description.ts:5-24, src/agents/prometheus/identity-constraints.ts:108-115
Planning and Registration
The planning phase, primarily driven by the Prometheus agent, involves the immediate registration of a "Plan Execution" todo list. This list acts as the backbone for the subsequent execution loop.
Mandatory Plan Registration
When a work plan is generated, the following meta-tasks are registered:
- Metis Consultation: Gap analysis and risk assessment.
- Plan Generation: Writing the structured
.sisyphus/plans/*.mdfile. - Self-Review: Classifying gaps as critical, minor, or ambiguous.
- User Summary: Presenting decisions and requesting input if needed.
- Momus Review: High-accuracy verification loop (optional).
- Cleanup: Deleting temporary drafts once the plan is finalized.
Sources: src/agents/prometheus/plan-generation.ts:16-30, src/agents/prometheus/gpt.ts:166-180
Execution Logic
The Sisyphus agent follows a "Task Discipline" protocol, which requires creating tasks before starting any non-trivial work. This serves as a primary coordination mechanism for parallel execution waves.
The sequence diagram shows the interaction between the planner, orchestrator, and the underlying task storage during a typical work cycle.
Sources: src/agents/sisyphus/default.ts:70-85, src/agents/prometheus/plan-generation.ts:32-45
Summary of Key Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| Task Schema | Defines the structure of a task and its relationships. | src/features/claude-tasks/types.ts |
| Storage Engine | Handles atomic JSON writes and file-based locking. | src/features/claude-tasks/storage.ts |
| Todo Tracker | Manages the live state and title formatting of todos. | src/hooks/todo-description-override/description.ts |
| Sync Hook | Pushes local task updates to the external Todo API. | src/features/claude-tasks/AGENTS.md |
| Plan Agent | Generates the initial task sequence for complex work. | src/agents/prometheus/plan-generation.ts |
The Task Schema and Todo Sync system is the functional "memory" and "backbone" of the project's autonomous capabilities, ensuring that every agent action is trackable, verifiable, and aligned with the user's original intent.
Sources: src/agents/sisyphus/default.ts:60-70, src/features/claude-tasks/AGENTS.md