CLEO Vision

The task management protocol for solo developers and their AI coding agents

CLEO Vision

The contract between you and your AI coding agent.

Mission Statement

CLEO provides a structured protocol that:

Prevents Hallucination

Four-layer validation ensures AI-generated data is always correct

Maintains Context

Immutable audit trails preserve state across sessions

Enables Reliable Workflows

Atomic operations and exit codes for programmatic handling

Scales Complexity

Orchestrated multi-agent coordination for complex projects

One developer. One AI agent. One source of truth.

Core Philosophy

Agent-First Design

CLEO is built for LLM agents first, with human accessibility second. When your primary “user” is Claude Code, everything changes:

Dimension	Human User	LLM Agent
Input	Natural language, flexibility	Structured data, constraints
Errors	Reads error messages	Branches on exit codes
Validation	Trusts own judgment	Needs external ground truth
Context	Maintains mental model	Loses context between sessions
Completion	Knows when “done”	Needs explicit success criteria

Five Founding Principles

1. Simplicity

   Flat sequential IDs (T001, T042) that never change, regardless of hierarchy restructuring

2. Flat Structures

   Three-level hierarchy maximum: Epic -> Task -> Subtask. Research shows this is optimal for navigation.

3. Computed Metrics

   No time estimates; scope-based sizing only. AI cannot accurately predict duration.

4. Portability

   Single installation (~/.cleo/), per-project initialization (.cleo/)

5. Dual Readability

   JSON for agents (default), human-readable on request (--human)

Anti-Hallucination Protocol

Every operation undergoes four-layer validation:

Layer 1: Schema

JSON Schema Enforcement

• Structure validation
• Type checking
• Enum constraints (status: pending|active|blocked|done)
• Format validation (ISO 8601 timestamps, T### IDs)

Layer 2: Semantic

Cross-File Integrity

• ID uniqueness across todo.json + archive
• Timestamp sanity (not future, completedAt > createdAt)
• Content pairing (title != description)
• Duplicate detection

Layer 3: Cross-File

Referential Integrity

• Log entries reference valid IDs
• Archive consistency
• Synchronized updates

Layer 4: State Machine

Transition Validation

• Valid status transitions only
• Configuration policy enforcement
• Constraint checking

Atomic Operations

No partial writes. No data corruption. Full rollback on any failure.

Every file modification follows this pattern:

The Contract

When you use CLEO with Claude Code, you establish a formal contract:

Stable Identity

Tasks are identified by stable IDs (T001) that never change, regardless of hierarchy restructuring

Machine-Parseable Output

All output is JSON by default, enabling programmatic handling

Numeric Exit Codes

All errors have numeric exit codes for branching logic

Validation First

All operations validate first, fail fast on invalid input

Persistent State

All state is persisted in todo.json as single source of truth

Audit Trail

All changes are logged in immutable audit trail (todo-log.json)

Atomic Writes

All writes are atomic with automatic backup and rollback

This contract enables reliable, repeatable AI-assisted development.

Daily Workflow

Morning Routine

cleo session start
cleo dash              # See project state
cleo focus show        # What was I working on?
cleo next --explain    # What should I do next?

During Work

cleo focus set T042              # Start task
cleo update T042 --notes "..."   # Document progress
cleo complete T042               # Finish task

End of Day

cleo session end --note "Completed auth flow, tests passing"

What CLEO Solves

Problem	CLEO Solution
Claude forgets yesterday’s context	Session notes + audit logs
Unclear which tasks are actually done	Verification gates + status tracking
Hallucinated task references	ID validation on every operation
Context degrades over long sessions	Manifest-based handoffs
Complex workflows overwhelm context	Orchestrator with 10K token budget

Summary

CLEO bridges the gap between human intention and AI execution:

For Developers

A shared memory system that maintains continuity across coding sessions

For AI Agents

Structured protocols that prevent hallucination and enable reliable workflows

Next Steps

Architecture

Deep dive into CLEO system components

Orchestrator

Multi-agent coordination for complex projects

Quick Start

Get started with CLEO in 5 minutes

Sessions Guide

Master session management for context preservation