agents

@cleocode/agents

CLEO agent protocols and templates.

Overview

This package contains agent protocols, templates, and base configurations for CLEO subagents. These agents follow standardized protocols to ensure consistency and compliance when working within the CLEO ecosystem.

What are CLEO Agents?

CLEO Agents are specialized AI workers that:

• Follow standardized protocols (LOOM methodology)
• Work within the CLEO task management system
• Produce outputs in defined formats
• Maintain compliance with CLEO constraints
• Communicate through structured channels

Installation

npm install @cleocode/agents

pnpm add @cleocode/agents

yarn add @cleocode/agents

Available Agents

cleo-subagent

The base protocol for all CLEO subagents. Every subagent in the CLEO ecosystem extends this foundation.

File: cleo-subagent/AGENT.md

Key Features

• Protocol Compliance: Follows RFC 2119 constraint definitions
• LOOM Lifecycle: Implements Logical Order of Operations Methodology
• Structured Output: Writes to files, returns only summaries
• Manifest Integration: Automatically appends to MANIFEST.jsonl

Immutable Constraints (RFC 2119)

ID	Rule	Enforcement
BASE-001	MUST append ONE line to MANIFEST.jsonl	Required
BASE-002	MUST NOT return content in response	Required
BASE-003	MUST complete task via cleo complete	Required
BASE-004	MUST write output file before manifest	Required
BASE-005	MUST set focus before starting work	Required
BASE-006	MUST NOT fabricate information	Required
BASE-007	SHOULD link research to task	Recommended

LOOM Lifecycle Protocol

The LOOM (Logical Order of Operations Methodology) is the systematic framework for processing project threads through the RCASD-IVTR+C pipeline.

Phase 1: Spawn (Initialization)

# 1. Read task context
cleo show {{TASK_ID}}

# 2. Start task (marks task active)
cleo start {{TASK_ID}}

Phase 2: Execute (Skill-Specific)

Follow the injected skill protocol for the current LOOM stage:

• Research: Gather information, cite sources
• Consensus: Validate claims, vote
• Specification: Write RFC 2119 spec
• Decomposition: Break down into tasks
• Implementation: Write code
• Validation: Verify compliance
• Testing: Write BATS tests
• Contribution: Track attribution
• Release: Version and changelog

Phase 3: Output (Mandatory)

# 1. Write output file
# Location: {{OUTPUT_DIR}}/{{TASK_ID}}-<slug>.md

# 2. Append manifest entry (single line JSON)
echo '{"id":"{{TASK_ID}}-slug",...}' >> {{MANIFEST_PATH}}

# 3. Complete task
cleo complete {{TASK_ID}}

Phase 4: Return (Summary Only)

Return ONLY one of these messages:

• "[Type] complete. See MANIFEST.jsonl for summary."
• "[Type] partial. See MANIFEST.jsonl for details."
• "[Type] blocked. See MANIFEST.jsonl for blocker details."

NEVER return content in the response. All content goes to output files.

Token Reference

Required Tokens:

Token	Description	Example
{{TASK_ID}}	Current task identifier	T1234
{{DATE}}	Current date (ISO)	2026-01-29
{{TOPIC_SLUG}}	URL-safe topic name	auth-research

Optional Tokens:

Token	Default	Description
{{EPIC_ID}}	""	Parent epic ID
{{OUTPUT_DIR}}	claudedocs/agent-outputs	Output directory
{{MANIFEST_PATH}}	{{OUTPUT_DIR}}/MANIFEST.jsonl	Manifest location

Error Handling

Status Classification:

Status	Condition	Action
complete	All objectives achieved	Write full output
partial	Some objectives achieved	Write partial, populate needs_followup
blocked	Cannot proceed	Document blocker, do NOT complete task

Retryable Errors:

Exit codes 7, 20, 21, 22, 60-63 support retry with exponential backoff.

Anti-Patterns

Pattern	Problem	Solution
Returning content	Bloats orchestrator context	Write to file, return summary
Pretty-printed JSON	Multiple lines in manifest	Single-line JSON only
Skipping start	Protocol violation	Always cleo start first
Loading skills via @	Cannot resolve	Skills injected by orchestrator

Agent Structure

Agents in this package follow a standardized structure:

agents/
├── <agent-name>/
│   ├── AGENT.md          # Main agent definition
│   ├── protocols/        # Protocol-specific docs
│   ├── templates/        # Output templates
│   └── examples/         # Example outputs

Using Agents

From Skills

Skills can spawn agents using the orchestration API:

import { orchestration } from '@cleocode/core';

await orchestration.spawn({
  agent: 'cleo-subagent',
  taskId: 'T1234',
  context: {
    skill: 'ct-research-agent',
    topic: 'authentication patterns'
  }
});

From CLI

Spawn agents directly from the command line:

# Spawn a research agent
cleo orchestrate spawn --agent cleo-subagent --task T1234 --skill ct-research-agent

# Spawn with context
cleo orchestrate spawn --agent cleo-subagent --task T1234 --context '{"topic":"API design"}'

From MCP

Use the MCP server to spawn agents:

{
  "domain": "orchestrate",
  "operation": "spawn",
  "params": {
    "agent": "cleo-subagent",
    "taskId": "T1234",
    "context": {
      "skill": "ct-implementation"
    }
  }
}

Creating Custom Agents

To create a custom agent that extends the base protocol:

1. Create agent directory:

   mkdir -p agents/my-custom-agent

2. Create AGENT.md:

   ---
   name: my-custom-agent
   description: |
     Custom agent for specialized tasks. Extends cleo-subagent base protocol.
   model: sonnet
   allowed_tools:
     - Read
     - Write
     - Bash
   ---
   
   # My Custom Agent
   
   Extends [cleo-subagent](./cleo-subagent/AGENT.md).
   
   ## Additional Constraints
   
   | ID | Rule | Enforcement |
   |----|------|-------------|
   | CUST-001 | **MUST** validate output format | Required |
   
   ## Specialization
   
   This agent specializes in [your domain].
   
   ## Usage
   
   ```bash
   cleo orchestrate spawn --agent my-custom-agent --task T1234

3. Register the agent:

   import { agents } from '@cleocode/core';
   
   agents.register({
     name: 'my-custom-agent',
     path: './agents/my-custom-agent',
     baseProtocol: 'cleo-subagent'
   });

Agent Protocols

Base Protocol

All agents extend the cleo-subagent base protocol which provides:

• Constraint System: RFC 2119 (MUST, SHOULD, MAY) rules
• Lifecycle Management: LOOM phases (Spawn, Execute, Output, Return)
• Output Standards: File-based outputs with manifest tracking
• Error Handling: Standardized status classification
• Token System: Template variables for dynamic content

Protocol Inheritance

cleo-subagent (base)
    │
    ├── research-subagent
    │       └── Extends with research-specific constraints
    │
    ├── implementation-subagent
    │       └── Extends with coding-specific constraints
    │
    └── validation-subagent
            └── Extends with compliance-specific constraints

Protocol Compliance

Agents are validated for protocol compliance:

import { compliance } from '@cleocode/core';

// Validate agent definition
const result = await compliance.validateAgent({
  agentPath: './agents/my-agent',
  baseProtocol: 'cleo-subagent'
});

if (result.valid) {
  console.log('Agent is protocol compliant ✓');
} else {
  console.log('Compliance issues:', result.issues);
}

Integration with Skills

Agents work closely with skills:

• Skills provide: Capabilities, instructions, constraints
• Agents provide: Execution context, protocol compliance, output handling

Example workflow:

1. Orchestrator identifies need for research
2. Loads ct-research-agent skill
3. Spawns cleo-subagent with research skill injected
4. Agent follows LOOM phases
5. Research skill guides information gathering
6. Agent writes output, appends to manifest
7. Returns summary to orchestrator

Dependencies

This package has no runtime dependencies. It contains only:

• Agent protocol definitions (markdown)
• Template files
• Example outputs

License

MIT License - see LICENSE for details.