Architecture Overview

CLEO system architecture, design principles, and core components

Architecture Overview

CLEO is a production-grade task management system designed specifically for AI coding agents. This document covers the core architecture and design principles.

Design Principles

CLEO is built on three foundational pillars:

Anti-Hallucination First

Multi-layer validation prevents AI-generated errors from corrupting task data

Atomic Operations

Every file modification uses atomic write patterns - no partial writes, no corruption

Session Continuity

Complete audit trails and automatic backups enable seamless work across sessions

System Invariants

These properties must ALWAYS be true:

Invariant	Description
Single Source of Truth	todo.json is authoritative for active tasks
Immutable History	Log entries never modified or deleted
Fail-Safe Operations	Atomic file operations with validation
Schema-First	JSON Schema validation prevents corruption
Idempotent Scripts	Safe to run multiple times
Zero-Config Defaults	Sensible defaults, optional customization

Directory Structure

~/.cleo/                    # Global installation
├── schemas/                # JSON Schema definitions
├── templates/              # Template files
├── scripts/                # Executable scripts
├── lib/                    # Shared libraries
├── docs/                   # Documentation
└── completions/            # Shell completions

.cleo/                      # Project-level data
├── todo.json              # Active tasks
├── todo-archive.json      # Completed tasks
├── config.json            # Configuration
├── todo-log.json          # Audit trail
├── sessions.json          # Session state
└── .backups/              # Automatic backups

Data Files

todo.json

Purpose: Active task storage (source of truth)

Structure:

{
  "_meta": {
    "schemaVersion": "2.6.0",
    "lastModified": "2025-01-19T12:00:00Z",
    "checksum": "sha256..."
  },
  "project": {
    "currentPhase": "core"
  },
  "focus": {
    "taskId": "T001",
    "sessionNote": "Working on auth"
  },
  "tasks": [...]
}

todo-archive.json

Purpose: Completed task storage

Contains: Tasks moved after completion via cleo archive

todo-log.json

Purpose: Immutable audit trail

Contains: Append-only log of all operations with timestamps

config.json

Purpose: Project configuration

Contains: Archive settings, validation rules, defaults

Core Components

Validation Pipeline

1. Schema Validation

   JSON Schema validation on every write operation

2. Semantic Validation

   Cross-file integrity checks, valid status transitions

3. Anti-Hallucination Checks

   Duplicate detection, timestamp validation, ID uniqueness

4. Atomic Write

   temp file → validate → backup → rename

Atomic Write Pattern

All file modifications follow this pattern:

1. Write to temporary file
2. Validate against JSON Schema
3. Create backup of original
4. Atomic rename to replace original
5. Log operation to audit trail

This pattern ensures no partial writes - either the entire operation succeeds or the original file is preserved.

Backup System

CLEO implements a two-tier backup system:

Tier	Purpose	Location
Tier 1	Atomic write safety	.cleo/.backups/todo.json.1-10
Tier 2	Point-in-time recovery	.cleo/backups/{type}/

Tier 1 backups are automatic on every write operation with numbered rotation (last 10).

Tier 2 backups are manual or pre-destructive operation snapshots with metadata and checksums.

Anti-Hallucination Mechanisms

CLEO implements four layers of protection:

Layer 1: Schema

JSON Schema Enforcement

Every task must conform to todo.schema.json:

• Required fields: id, title, status
• Status enum: pending, active, blocked, done
• Valid timestamp formats
• Correct data types

Layer 2: Semantic

Cross-File Integrity

• ID uniqueness across todo.json and todo-archive.json
• No duplicate task descriptions
• Valid parent references
• Dependency cycle detection

Layer 3: Temporal

Timestamp Validation

• No future timestamps
• Logical ordering (created < modified)
• Session boundary consistency

Layer 4: Content

Content Validation

• Title differs from description
• Action-oriented titles
• Phase existence validation
• Label format checking

Extension Points

CLEO provides several extension mechanisms:

Extension	Purpose	Location
Hooks	Pre/post operation callbacks	hooks/
Validators	Custom validation rules	lib/validators/
Formatters	Custom output formats	lib/formatters/
Commands	New CLI commands	scripts/

Performance Considerations

CLEO is optimized for 1000+ tasks:

• File locking prevents race conditions
• Indexed operations for fast lookups
• Lazy loading for archive access
• Efficient JSON parsing with jq streaming

Next Steps

Data Flows

Visual workflows and operation diagrams

Anti-Hallucination

Deep dive into validation mechanisms