ct-cleo

CLEO Protocol Guide

Full protocol content lives in ~/.cleo/templates/CLEO-INJECTION.md. Emit any section with: cleo briefing inject --section <name>

Supported sections: session-start · work-loop · triggers · task-creation · task-discovery · task-relationships · session-commands · memory · nexus · orchestration · playbooks · documents · error-handling · pre-complete-gate · spawn-tiers · rules · memory-jit · escalation

Quick Reference

Skill-Specific Extensions

• Task hierarchy, Saga commands, add-batch decomposition, docs policy, and CLI output details live in CLEO-INJECTION.md; emit task-creation, documents, and pre-complete-gate when needed.
• For add-batch input, The top-level JSON MUST be an array of task objects, not an object wrapper like { "tasks": [...] }.
• Dry-run count semantics: /data/count and /data/wouldCreate predict writes; /data/insertedCount must be 0 for dry-run.
• Mutation output paths: use /data/created/0, /data/updated/0, and /data/deleted/0; never parse legacy full records.
• Docs path policy and strict preflight: keep docs repo-relative. Do not pass arbitrary external absolute paths. The canonical six-verb docs path is add, update, fetch, list, remove, publish (T10516). Use cleo docs list for discovery; cleo docs list-types (ADVANCED) and DocKindRegistry resolve runtime kinds when list is insufficient.

Task Relationship Systems — depends, blockedBy, relates

CLEO has three distinct relationship systems with different storage, semantics, and CLI exposure. Do not conflate them.

Key distinction

• depends controls execution order (wave planning, cleo next eligibility). It is a hard dependency.
• blockedBy is a status annotation — it does NOT link to another task, it just explains why this task is blocked.
• relates is informational linkage — it does NOT block execution, but it records that two tasks have a semantic relationship (e.g. "T1001 supersedes T1002" or "T1003 duplicates T1004").

CRITICAL: Do NOT use relates for execution gates

relates is never a blocking dependency. If task B must wait for task A to finish, use --depends:

# CORRECT — execution dependency
cleo add "Implement auth" --depends T1001,T1002

# WRONG — relates does NOT block execution
cleo relates add T1003 T1001 blocks "waiting for auth"

Common pitfall: using blockedBy for task IDs

--blocked-by expects a string reason, not task IDs. To express "this task is blocked until that task finishes", use --depends:

# CORRECT
cleo add "Implement auth" --depends T1001

# WRONG — blocked-by is free text, not a task reference
cleo update T1003 --blocked-by T1001

cleo relates command reference

# Add a semantic relationship
cleo relates add T1001 T1002 supersedes "T1002 is absorbed into the new auth flow"

# List relations for a task
cleo relates list T1001

# Remove a relation
cleo relates remove T1001 T1002

# Suggest related tasks based on shared attributes
cleo relates suggest T1001 --threshold=50

# Discover related tasks using various methods
cleo relates discover T1001

Valid relation types: blocks, related, duplicates, absorbs, fixes, extends, supersedes.

Schema types mismatch note

The DB schema TASK_RELATION_TYPES (related, blocks, duplicates, absorbs, fixes, extends, supersedes) must match the runtime types. The CLI cleo relates add accepts the DB schema types. Always normalize to the DB enum before persisting.

Task Hierarchy (PM-Core V2 — ADR-088)

Canonical source: docs/adr/ADR-088-pm-core-v2-workgraph-relations-completion-criteria.md. Legacy charter ADR-073 remains authoritative for pre-PM-Core V2 semantics; ADR-088 governs the PM-Core V2 target. The T10638 migration removed legacy task_relations.groups hierarchy reads and the dual-shape label='saga' fallback — containment is now read exclusively from tasks.parent_id.

Containment (I1): tasks.parent_id is the only containment edge. Direct children, ancestor/descendant traversal, closure rollups, and default parent completion are all derived from parent_id. The parent matrix is:

Storage (I2): All IDs stored as T####; type column discriminates tier (not label). Prefixes (SG-, E-) are DISPLAY + import-mapping only.

Non-containment (I3): task_relations is for secondary graph semantics ONLY — dependency, ordering, cross-reference, evidence, supersession, provenance. A task_relations row MUST NOT satisfy containment, child listing, ancestor/descendant traversal, parent rollup, parent completion, nesting-budget, or closure semantics. The groups relation type is retired for hierarchy; do not use task_relations.groups for parent/child semantics.

Typed Completion Criteria (PM-Core V2)

PM-Core V2 introduces typed acceptance criteria — task_acceptance_criteria.kind is one of:

Key rules:

• A parent with children uses child_task criteria by default; these are deterministic projections from parent_id containment (the T10639 child_task-projection backfill derives parent completion from child state — mixed-criteria mode is migration-only or explicit advanced scope).
• text and evidence_bound criteria must NOT use target_task_id.
• Cancelled children do NOT automatically satisfy parent completion; they require waiver or replacement evidence.
• Adding or reopening required child work under a done parent reopens affected ancestors.

Saga Operations (PM-Core V2)

Saga-level orchestration is first-class. Saga membership uses parent_id containment (NOT task_relations.groups). Use saga IDs directly with orchestrate commands:

# Saga-level ready frontier — parallel-safe tasks across all member epics
cleo orchestrate ready <sagaId>

# Saga-level dependency waves — unified wave plan across all member epics
cleo orchestrate waves <sagaId>

# Saga status rollup — completion %, member counts
cleo saga rollup <sagaId>

# Saga membership listing via parent_id containment
cleo saga members <sagaId>

Epic-level fallback: If saga-level orchestrate fails, enumerate member epics from cleo saga members <sagaId> and call cleo orchestrate ready <epicId> for each member individually. Do not use task_relations.groups as a fallback for hierarchy — it is non-containment only per I3.

WorkGraph (PM-Core V2 — T10632/T10633/T10634)

The WorkGraph subsystem provides scaffold validation (T10632), atomic application (T10633), and planning document generation (T10634):

Example — dry-run a scaffold before applying:

# Validate scaffold payload
cleo workgraph validate --file scaffold.json --dry-run

# Apply validated scaffold atomically
cleo workgraph apply --file scaffold.json

Task Context (PM-Core V2 — T10629/T10630/T10631)

Bounded task context with token budgeting for agent ergonomics:

The task-context pack is surfaced for agents via cleo focus <taskId> (compact, for prompt injection) and cleo orchestrate report <taskId> (full grouped readiness). Do not confuse this with cleo context, which is the separate context-WINDOW usage monitor (cleo context status / cleo context check).

Example — get the task-context pack for agent use:

# Full grouped readiness report for a task
cleo orchestrate report <taskId>

# Compact context pack for prompt injection
cleo focus <taskId>

BRAIN Decision-Store — Durable Architecture Decisions

Architectural decisions belong in the BRAIN decision-store, not in adrs markdown blobs or agent-outputs ledgers. Use cleo memory commands to create, find, and cite decisions by durable BRAIN decision IDs.

Why BRAIN decisions over markdown ledgers:

• Decisions are durable, queryable, and have source provenance (source_table, source_rowid)
• Decision IDs disambiguate overloaded D0xx/AGT-* identifiers via provenance tracking
• The decision-store supports lifecycle tracking (pending → accepted → superseded)
• Memory link pattern: cite a BRAIN decision ID in task descriptions, then cleo memory fetch <id> for full context

Migration rule: When you encounter a decision ONLY in a markdown ledger (.cleo/adrs/, .cleo/agent-outputs/), store it in the BRAIN with cleo memory store --type decision and cite the BRAIN ID going forward.