Orchestrator Protocol

Multi-agent coordination for complex projects with context preservation

Orchestrator Protocol

One orchestrator. Zero implementation. Infinite subagents.

The Core Problem

You are a solo developer working with Claude Code. You want to:

1. Interact with ONE Claude Code session across an entire project lifecycle
2. Have that conversation last as long as possible without context exhaustion
3. Complete complex multi-phase work without losing continuity
4. Leverage AI for the ENTIRE lifecycle: research, spec, implement, test, document, release

The fundamental tension: Claude’s context window is finite. Projects are not.

A typical feature epic involves thousands of lines of code changes, dozens of files, multiple test suites, and documentation updates. If Claude tries to hold all of this in context, the conversation dies within hours.

The Vision

You speak to ONE Claude Code instance - the orchestrator. This orchestrator NEVER implements anything directly. Instead, it:

Plans

Decomposes work into dependency waves

Spawns

Creates specialized subagents for each task

Reads

Only compact summaries of output

Coordinates

Manages handoffs between agents

The orchestrator is a conductor, not a musician. It coordinates the symphony but never plays an instrument.

The Mantra

Stay high-level. Delegate everything. Read only manifests. Spawn in order.

Phrase	Meaning	Enforcement
Stay high-level	Orchestrator reasons about what to do, never how	ORC-001
Delegate everything	Zero code, zero file reading, zero implementation	ORC-002
Read only manifests	Subagents write summaries; orchestrator reads ONLY those	ORC-003
Spawn in order	Respect CLEO dependency graph; wave-based execution	ORC-004

This mantra is not a guideline - it is an immutable constraint. Violation breaks the protocol.

Architecture Overview

The 5 Immutable Constraints

ORC-001

MUST stay high-level; MUST NOT implement code

Rationale: Context preservation. If orchestrator implements, context explodes.

# Orchestrator DOES
"Task T1234 requires JWT implementation. Spawning ct-task-executor..."

# Orchestrator NEVER
"Here's the JWT middleware code: function verifyToken(req, res, next) {...}"

ORC-002

MUST delegate ALL work to subagents via Task tool

Rationale: Each subagent gets fresh 200K context; separation of concerns.

# Spawn command
cleo orchestrator spawn T1234

ORC-003

MUST NOT read full files (>100 lines) into context

Rationale: Manifests are O(1) lookup; files are O(n) token consumption.

# Orchestrator reads
cat MANIFEST.jsonl | jq -s '.[-1].key_findings'

# Orchestrator NEVER reads
cat src/auth/jwt-middleware.ts

ORC-004

MUST spawn agents in dependency order

Rationale: Spawning T3 before T1 completes = wasted work and conflicts.

cleo orchestrator analyze T001  # Shows dependency waves
cleo orchestrator next --epic T001  # Next task in order

ORC-005

MUST maintain context budget under 10K tokens

Rationale: Leaves room for YOUR ongoing conversation with the orchestrator.

Wave-Based Execution

Tasks are grouped by dependency depth for parallel execution:

Wave Computation Algorithm

1. Extract Dependencies

   Parse dependency graph from CLEO tasks

2. Calculate Depth

   Each task: depth = 0 if no deps, else max(parent depths) + 1

3. Group by Depth

   Tasks with same depth form a wave

4. Spawn in Order

   Complete all tasks in wave N before starting wave N+1

Manifest-Based Handoff

Context efficiency: ~200 tokens/entry vs ~5000+ tokens for full file reads (25x savings)

Each subagent appends exactly ONE line to MANIFEST.jsonl:

{
  "id": "auth-jwt-2026-01-19",
  "title": "JWT Authentication Research",
  "status": "complete",
  "key_findings": [
    "JWT tokens should use RS256 with 15min expiry",
    "Refresh tokens require HttpOnly cookie storage",
    "Rate limiting: 5 attempts per minute per IP"
  ],
  "needs_followup": ["T1234"],
  "linked_tasks": ["T1230", "T1234"]
}

The orchestrator reads ONLY key_findings - never the full output file.

Epic Types Supported

Feature

New capability: Research → Spec → Implement → Test → Document

Bug Fix

Defect correction: Reproduce → Diagnose → Fix → Verify

Research

Investigation: Survey → Analyze → Synthesize → Report

Refactor

Code improvement: Analyze → Plan → Execute → Validate

Migration

System transition: Assess → Plan → Execute → Cutover

Brownfield

Existing codebase: Understand → Integrate → Adapt → Test

Greenfield

New project: Design → Bootstrap → Implement → Launch

Phase Discipline

Phase	Purpose	Skills Used
Setup	Foundation and planning	ct-research-agent, ct-spec-writer, ct-epic-architect
Core	Main implementation	ct-task-executor, ct-library-implementer-bash
Testing	Validation and QA	ct-test-writer-bats, ct-validator
Polish	Refinement and docs	ct-documentor, ct-validator
Maintenance	Ongoing support	ct-task-executor, ct-research-agent

Verification Gates

Epics auto-complete when all children are done AND verified:

Session Continuity

Startup Protocol

The orchestrator executes this on every new conversation:

# 1. Check for pending work
cat MANIFEST.jsonl | jq -s '[.[] | select(.needs_followup | length > 0)]'

# 2. Check active sessions
cleo session list --status active

# 3. Check current focus
cleo focus show

# 4. Review epic status
cleo dash --compact

Decision Matrix

Condition	Action
Active session with focus	Resume; continue focused task
Active session, no focus	Query manifest needs_followup; spawn next
No session, manifest has followup	Create session; spawn for followup
No session, no followup	Ask HITL for direction

The orchestrator never starts from zero. It always checks external state first.

Why This Works

Traditional vs. Orchestrator

Traditional	Orchestrator
One agent does everything	Many agents, one coordinator
Context exhausted at ~50K tokens	Conversation runs for days/weeks
Lost state between sessions	CLEO + MANIFEST = perfect continuity
Flat task list	Epic → Task → Subtask with dependencies
”Done” = code committed	”Done” = verified through gates

The Math

• Orchestrator context budget: 10K tokens
• Each subagent context: 200K tokens
• Manifest entry: ~200 tokens (3-7 key_findings)
• 100 subagent completions = 20K tokens in manifest summaries

With careful manifest management, you can coordinate hundreds of subagent executions while keeping the orchestrator conversation alive.

Orchestrator Commands

# Analyze dependency waves
cleo orchestrator analyze T001

# Get next task (respects dependencies)
cleo orchestrator next --epic T001

# Spawn subagent for task
cleo orchestrator spawn T1234

# List parallel-safe tasks
cleo orchestrator ready --epic T001

# Graceful shutdown on context limit
cleo safestop --reason "context-limit" --handoff ./handoff.json

Next Steps

Epic Architect Skill

Create comprehensive epics with task decomposition

Multi-Agent Guide

Run multiple concurrent sessions

Sessions Guide

Master session lifecycle management

Context Monitoring

Track and manage context usage