Schema Reference
CLEO uses JSON Schema for data validation. This reference documents the core data structures.
Task Object
The fundamental unit of work in CLEO.
{
"id": "T001",
"title": "Implement authentication",
"description": "Add JWT-based auth with refresh tokens",
"status": "pending",
"priority": "high",
"type": "task",
"parentId": null,
"size": "medium",
"labels": ["backend", "security"],
"phase": "core",
"depends": ["T000"],
"files": ["src/auth/jwt.ts"],
"acceptanceCriteria": ["Tests pass", "Code reviewed"],
"notes": [
{
"timestamp": "2025-01-19T12:00:00Z",
"text": "Started implementation"
}
],
"createdAt": "2025-01-19T10:00:00Z",
"updatedAt": "2025-01-19T12:00:00Z",
"completedAt": null
}
Field Reference
Unique task identifier. Format: T followed by digits (e.g., T001, T1234)
Action-oriented task title. Must differ from description.
Detailed task description
Task status. One of: pending, active, blocked, done
Priority level. One of: critical, high, medium, low. Default: medium
Task type. One of: epic, task, subtask. Inferred from hierarchy.
Parent task ID for hierarchy. null for root tasks.
Scope-based size (NOT time). One of: small, medium, large
Array of labels for categorization
Project phase assignment (e.g., setup, core, testing)
Array of task IDs this task depends on
Array of timestamped notes
ISO 8601 creation timestamp
ISO 8601 last modification timestamp
ISO 8601 completion timestamp. null if not complete.
todo.json Structure
{
"_meta": {
"schemaVersion": "2.6.0",
"lastModified": "2025-01-19T12:00:00Z",
"checksum": "sha256:abc123..."
},
"project": {
"currentPhase": "core",
"phases": [
{
"slug": "setup",
"name": "Setup",
"status": "completed"
},
{
"slug": "core",
"name": "Core Development",
"status": "active"
}
]
},
"focus": {
"taskId": "T001",
"setAt": "2025-01-19T12:00:00Z",
"sessionNote": "Working on JWT implementation"
},
"tasks": [
{ /* task object */ }
]
}
Status Transitions
Valid status transitions:
Use cleo complete for the active/pending → done transition. Use cleo reopen for done → pending.
Priority Values
| Priority | Use Case |
|---|
critical | Blocking deployment or other work |
high | Important, needs attention soon |
medium | Normal priority (default) |
low | Nice to have, do when time permits |
Hierarchy Constraints
| Constraint | Value |
|---|
| Maximum depth | 3 levels (epic → task → subtask) |
| Maximum siblings | Unlimited (configurable via hierarchy.maxSiblings) |
| Valid parent types | epic can have tasks, task can have subtasks |
config.json Structure
{
"_meta": {
"schemaVersion": "1.2.0"
},
"archive": {
"daysUntilArchive": 7,
"preserveRecentCount": 3
},
"validation": {
"maxActiveTasks": 1,
"requireDescription": false,
"maxTitleLength": 200
},
"hierarchy": {
"maxDepth": 3,
"maxSiblings": 7,
"autoCompleteParent": true,
"autoCompleteMode": "auto"
},
"defaults": {
"priority": "medium",
"phase": "core"
},
"contextAlerts": {
"enabled": true,
"warningThreshold": 70,
"criticalThreshold": 90
}
}
Session Object
Sessions track multi-agent work coordination.
{
"id": "session_20260119_193457_1e6699",
"status": "active",
"name": "Feature Development",
"agentId": "claude-opus-1",
"scope": {
"type": "epic",
"rootTaskId": "T001",
"computedTaskIds": ["T001", "T002", "T003"]
},
"focus": {
"currentTask": "T002",
"sessionNote": "Implementing auth flow",
"nextAction": "Write unit tests"
},
"startedAt": "2026-01-19T19:34:57Z",
"lastActivity": "2026-01-19T20:15:00Z"
}
Unique session identifier. Format: session_YYYYMMDD_HHMMSS_hash
Session state. One of: active, suspended, ended, closed
Defines what tasks this session can access.
Scope type. One of: task, taskGroup, subtree, epicPhase, epic
Root task ID defining scope boundary
Array of task IDs computed from scope
Current focus state within session.
Currently focused task ID
Session-level progress note
Verification Object
Verification gates for task completion quality.
{
"passed": false,
"round": 1,
"gates": {
"implemented": true,
"testsPassed": true,
"qaPassed": null,
"securityPassed": null,
"documented": false
},
"lastAgent": "coder",
"lastUpdated": "2026-01-19T20:00:00Z",
"failureLog": [
{
"round": 1,
"agent": "coder",
"reason": "Tests failing on edge case",
"timestamp": "2026-01-19T19:45:00Z"
}
]
}
Overall verification status. True when all required gates pass.
Individual verification gates.
Implementation complete. Auto-set by complete command.
Tests pass. Set via cleo verify --gate testsPassed
History of verification failures for debugging.
Error Response Object
All error responses follow this structure.
{
"success": false,
"error": {
"code": "E_VALIDATION_FAILED",
"message": "Task title exceeds maximum length",
"exitCode": 6,
"recoverable": true,
"suggestion": "Shorten title to under 200 characters",
"fix": "cleo update T001 --title \"Shorter title\"",
"alternatives": [
{
"action": "View current task",
"command": "cleo show T001"
}
],
"context": {
"field": "title",
"maxLength": 200,
"actualLength": 250
}
}
}
Error code identifier (e.g., E_VALIDATION_FAILED, E_NOT_FOUND)
CLI exit code for scripting
Whether error can be retried with different input
Copy-paste ready command to resolve the error
Alternative commands to try
Structured error context for debugging
Next Steps
