ct-cleo

CLEO Protocol Guide

CLEO is the task management protocol for AI coding agents. It provides structured task tracking, session management, and multi-agent coordination with anti-hallucination validation.

Operation set: 164 operations (97 query + 67 mutate) across 10 canonical domains.

MCP-First Workflow

MCP is the primary entry point. Use query for reads and mutate for writes.

Tier-0 Read Operations (query) — Always Available

Tier-1 Read Operations (query) — After Session Init

Tier-0 Write Operations (mutate) — Always Available

Tier-1 Write Operations (mutate) — After Session Init

Canonical Decision Tree

Every agent MUST use this tree to select the minimum-cost operation path.

Entry Point: Session Start (MANDATORY)

Agent starts work
│
├── STEP 1: query session.status
│   ├── Active session exists
│   │   └── query session.handoff.show  → resume prior context, then STEP 2
│   └── No active session
│       └── mutate session.start {scope: "task:TXXX" | "epic:TXXX"}
│
├── STEP 2: query admin.dash  → project overview, active epic, blockers
│
├── STEP 3: query tasks.current  → is a task already in progress?
│   ├── Yes → continue that task (skip STEP 4)
│   └── No → STEP 4
│
└── STEP 4: query tasks.next  → what to work on next
    └── query tasks.show {taskId}  → full task requirements

Anti-pattern blocked: Never skip session.status. Resuming without handoff.show loses prior context and causes duplicate work.

Goal: Discover Work

I need to find what to work on
│
├── What should I do next (auto-selected)?
│   └── query tasks.next  [tier 0]
│       └── query tasks.show {taskId}  [tier 0]  → full details
│
├── I know keywords — search for a specific task
│   └── query tasks.find {query: "..."}  [tier 0]
│       ├── Found one match → query tasks.show {taskId}
│       └── Need to browse children of a known parent
│           └── query tasks.list {parentId: "TXXX"}  [tier 1]  ← ONLY with parentId filter
│               ANTI-PATTERN: tasks.list with no parentId = full dump, never do this
│
├── I need a prioritized planning view (upcoming tasks, blockers, dependencies)
│   └── query tasks.plan  [tier 0]
│
├── I need the full task hierarchy under a parent
│   └── (discover via tasks.find first, then)
│   └── query tasks.tree {taskId}  [tier 1]  → subtask hierarchy
│
├── I need to see what's blocking a task
│   └── query tasks.blockers {taskId}  [tier 1]
│
└── I need leverage-sorted discovery (highest-impact tasks first)
    └── query tasks.analyze  [tier 1]

Goal: Memory Operations

I need to save or recall information across sessions
│
├── Save an observation right now (free-form)
│   └── mutate memory.observe {text, title?}  [tier 0]
│
├── Search for something I or a prior agent observed
│   └── query memory.find {query: "..."}  [tier 0]  ← ALWAYS start here (cheap)
│       └── Found interesting IDs → query memory.timeline {anchorId}  [tier 1]
│           └── Need full content → query memory.fetch {ids: [...]}  [tier 1]
│       3-LAYER PATTERN: find → timeline → fetch (never skip to fetch directly)
│
├── Save a structured decision (with rationale, alternatives, taskId)
│   └── mutate memory.decision.store {decision, rationale, taskId, alternatives?}  [tier 1]
│       └── Recall: query memory.decision.find {query, taskId?}  [tier 1]
│
└── Associate a memory entry with a task (research linking protocol)
    └── mutate memory.link {memoryId, taskId}  [tier 1]

Anti-pattern blocked: Never call memory.fetch without first calling memory.find. Fetching without filtering returns all entries (expensive).

Goal: Multi-Agent Coordination

I need to coordinate agent work (orchestrator role)
│
├── I am the orchestrator — start coordinating an epic
│   └── mutate orchestrate.start {epicId}  [tier 1]
│       └── query orchestrate.status  [tier 1]  → current orchestration state
│
├── Spawn a subagent for a task
│   └── (1) mutate orchestrate.validate {taskId}  [tier 1]  → pre-spawn gate check
│       (2) mutate orchestrate.spawn {taskId, skillIds?}  [tier 1]  → spawn prep
│
└── I am a subagent — complete my work and report
    └── mutate pipeline.manifest.append {entry}  [tier 1]  ← MANDATORY per BASE protocol
        mutate tasks.complete {taskId}  [tier 0]

Subagent BASE protocol: Every subagent MUST append one entry to MANIFEST.jsonl via pipeline.manifest.append BEFORE calling tasks.complete. Omitting this is a protocol violation (exit code 62).

Goal: Track Session Context

I need to manage session lifecycle or read session state
│
├── Check whether a session is active
│   └── query session.status  [tier 0]  ← FIRST, always
│
├── Resume prior context after a restart
│   └── query session.handoff.show  [tier 0]
│
├── Get a composite cold-start briefing (combines status + handoff)
│   └── query session.briefing.show  [tier 0]
│
├── Start a new session
│   └── mutate session.start {scope: "task:TXXX" | "epic:TXXX"}  [tier 0]
│       RULE: scope is required — no unscoped sessions
│
├── End the current session (triggers debrief + handoff generation)
│   └── mutate session.end  [tier 0]
│
└── Browse past sessions
    └── query session.find {query: "..."}  [tier 1]  ← NOT session.list unfiltered
        └── Full session record: query session.show {sessionId}  [tier 1]

Goal: Discover Available Skills

I need to know what skills or providers are available
│
├── List all installed skills (cold-start safe)
│   └── query tools.skill.list  [tier 0]
│       └── Detail on a specific skill: query tools.skill.show {skillId}  [tier 1]
│
└── Detect active provider
    └── query tools.provider.detect  [tier 0]

Goal: System Information

I need system or configuration info
│
├── What is the overall project state?
│   └── query admin.dash  [tier 0]  ← mandatory efficiency sequence step 2
│
├── What operations are available at this tier?
│   └── query admin.help  [tier 0]  → tier 0 + tier 1 ops
│       └── query admin.help {tier:2}  → reveals tier-2 ops + escalation hints
│
└── Inspect configuration
    └── query admin.config.show  [tier 1]

CLI Fallback

When MCP tools are unavailable, use ct (alias for cleo).

ct find "query"            # Search (99% less context than list)
ct find --id T1234         # Search by ID
ct show T1234              # Full task details
ct add "Task title"        # Create task
ct complete T1234          # Complete task
ct start T1234             # Start working on task
ct dash                    # Project overview (admin.dash equivalent)

ct sticky add "Quick note"     # Create sticky note
ct sticky list                 # List active stickies
ct sticky show SN-001          # Show sticky details

Task Discovery (Context Efficiency)

MUST use efficient commands — find for discovery, show for details:

• list includes full notes arrays (huge context cost)
• find returns minimal fields only (99% less context)
• Use show only when you need full details for a specific task

Context Bloat Anti-Patterns

Anti-Pattern Reference

Progressive Disclosure

Load only what you need. Escalate tiers when the task demands it:

Stay at Tier 0 (default — 80% of work):

• Single task execution (implement, fix, test)
• Task discovery and status updates
• Session start/end

Escalate to Tier 1 when:

• Managing pipeline stages or manifest entries
• Running validation/compliance checks
• Working with memory (timeline, fetch, decisions, patterns)
• Orchestrating multi-agent workflows

Escalate to Tier 2 when (via admin.help {tier:2} first):

• WarpChain pipeline operations (pipeline.chain.*)
• Behavioral grading (check.grade)
• Cross-project nexus deep queries (nexus.resolve, nexus.graph)
• Data export/import (admin.export, admin.import)

Session Protocol

Sessions track work context across agent interactions.

Quick Start

# 1. CHECK session state first (always)
ct session status

# 2. RESUME or START
ct session resume <id>
# OR (only if no suitable session):
ct session start --scope epic:T001

# 3. WORK
ct current / ct next / ct complete T005 / ct start T006

# 4. END (ALWAYS when stopping)
ct complete <id>
ct session end

MCP Session Operations

query({ domain: "session", operation: "status" })
query({ domain: "session", operation: "handoff.show" })
mutate({ domain: "session", operation: "start", params: { scope: "epic:T001" }})
mutate({ domain: "session", operation: "end", params: { note: "Progress" }})

Error Handling

CRITICAL: NEVER ignore exit codes. Failed commands = tasks NOT created/updated.

After EVERY command:

1. Exit code 0 = success, 1-22 = error, 100+ = special (not error)
2. JSON "success": false = operation failed
3. Execute error.fix — copy-paste-ready fix command

RCASD-IVTR+C Lifecycle (LOOM)

LOOM (Logical Order of Operations Methodology) is the systematic framework for how CLEO processes project threads through the RCASD-IVTR+C pipeline. See docs/concepts/CLEO-VISION.md for the complete LOOM framework.

Lifecycle: See references/loom-lifecycle.md for gate enforcement and subagent architecture.

Pipeline Awareness

Epics follow the RCASD-IVTR+C lifecycle managed through pipeline stages. Use pipeline.stage.status to check where an epic is in its lifecycle:

Time Estimates Prohibited

• MUST NOT estimate hours, days, weeks, or temporal duration
• MUST use relative sizing: small / medium / large
• SHOULD describe scope, complexity, dependencies when asked

References

For detailed guidance on specific topics, see:

• Session Protocol: references/session-protocol.md
• LOOM Lifecycle: references/loom-lifecycle.md
• Anti-Patterns: references/anti-patterns.md
• Operation Constitution: docs/specs/CLEO-OPERATION-CONSTITUTION.md
• Verb Standards: docs/specs/VERB-STANDARDS.md
• Decision Tree source: .cleo/agent-outputs/T5610-decision-tree.md