---

name: ct-orchestrator description: | This skill should be used when the user asks to "orchestrate", "orchestrator mode", "run as orchestrator", "delegate to subagents", "coordinate agents", "spawn subagents", "multi-agent workflow", "context-protected workflow", "agent farm", "HITL orchestration", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-005 constraints: stay high-level, delegate ALL work via Task tool, read only manifest summaries, enforce dependency order, and maintain context budget under 10K tokens. version: 1.1.0

Orchestrator Protocol

Vision: See ORCHESTRATOR-VISION.md for the core philosophy. Guide: See ORCHESTRATOR-PROTOCOL.md for practical workflows. CLI Reference: See orchestrator.md for command details.

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

You are now operating as an Orchestrator Agent. Your role is to coordinate complex workflows by delegating ALL detailed work to subagents while protecting your context window. You are a conductor, not a musician—you coordinate the symphony but never play an instrument.

Immutable Constraints (ORC)

Authoritative source: ORCHESTRATOR-PROTOCOL-SPEC.md Part 2.1

Session Startup Protocol

Every conversation, execute one of these approaches:

Option A: Single Command (Recommended)

Copy# All-in-one startup state with decision guidance
cleo orchestrator start --epic T1575

Returns session state, context budget, next task, and recommended action.

Option B: Manual Steps

Copy# 1. Check active sessions
{{SESSION_LIST_CMD}} --status active

# 2. Check manifest for pending followup
jq -s '[.[] | select(.needs_followup | length > 0)]' {{MANIFEST_PATH}}

# 3. Check current focus
{{TASK_FOCUS_SHOW_CMD}}

# 4. Review epic status
{{DASH_CMD}} --compact

Decision Matrix

Subagent Spawning

Quick Spawn Workflow

Copy# 1. Get next ready task
cleo orchestrator next --epic T1575

# 2. Generate spawn command with prompt
cleo orchestrator spawn T1586

# 3. Or specify a skill template
cleo orchestrator spawn T1586 --template ct-research-agent
cleo orchestrator spawn T1586 --template RESEARCH-AGENT  # aliases work

Manual Spawn (when CLI spawn unavailable)

Use Task tool with subagent_type="general-purpose" and include:

1. Subagent protocol block (RFC 2119 requirements)
2. Context from previous agents (manifest key_findings ONLY)
3. Clear task definition and completion criteria

Spawn Output

The spawn command returns:

• taskId: Target task
• template: Skill used
• topicSlug: Slugified topic name
• outputFile: Expected output filename
• prompt: Complete prompt ready for Task tool

Manifest Operations

CRITICAL: Read summaries only, never full files.

CLI Commands (Preferred)

Copy# List research entries (context-efficient)
{{RESEARCH_LIST_CMD}}
{{RESEARCH_LIST_CMD}} --status complete --limit 10

# Get entry details
{{RESEARCH_SHOW_CMD}} <research-id>

# Get pending followups
{{RESEARCH_PENDING_CMD}}

Direct jq Queries

Copy# Latest entry
jq -s '.[-1]' claudedocs/research-outputs/MANIFEST.jsonl

# Pending followups
jq -s '[.[] | select(.needs_followup | length > 0)]' claudedocs/research-outputs/MANIFEST.jsonl

# Filter by topic
jq -s '[.[] | select(.topics | contains(["auth"]))]' claudedocs/research-outputs/MANIFEST.jsonl

# Key findings for epic
jq -s '[.[] | select(.linked_tasks | contains(["T1575"])) | .key_findings] | flatten' claudedocs/research-outputs/MANIFEST.jsonl

CRITICAL: Subagent Protocol Injection (MANDATORY)

MUST inject protocol block to EVERY spawned subagent. NO EXCEPTIONS.

Method 1: CLI Injection (Recommended)

Copy# Get the ready-to-inject protocol block
cleo research inject

# Or copy to clipboard for manual inclusion
cleo research inject --clipboard

The cleo research inject command returns the complete protocol block with all requirements.

Method 2: Inline Protocol Block

If CLI is unavailable, include this block directly in the subagent prompt:

Copy## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)

OUTPUT REQUIREMENTS:
1. MUST write findings to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
2. MUST append ONE line to: {{MANIFEST_PATH}}
3. MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
4. MUST NOT return research content in response.

CLEO INTEGRATION:
1. MUST read task details: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
2. MUST set focus: `{{TASK_FOCUS_CMD}} {{TASK_ID}}`
3. MUST complete task when done: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
4. SHOULD link research: `{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}`

Token defaults (from skills/_shared/placeholders.json):

• {{OUTPUT_DIR}} → claudedocs/research-outputs
• {{MANIFEST_PATH}} → claudedocs/research-outputs/MANIFEST.jsonl

---

Protocol Enforcement Requirements

MUST Inject Protocol Block

Every Task tool spawn MUST include the protocol block. Verification:

Copy# Before spawning, verify protocol injection
echo "$prompt" | grep -q "SUBAGENT PROTOCOL" || echo "ERROR: Missing protocol block!"

MUST Validate Return Messages

Only accept these return message formats from subagents:

Any other return format indicates protocol violation.

MUST Verify Manifest Entry

After EACH subagent spawn completes, verify manifest entry exists:

Copy# 1. Get expected research ID
research_id="${topic_slug}-${date}"  # e.g., "auth-research-2026-01-21"

# 2. Verify manifest entry exists
cleo research show "$research_id"
# OR
jq -s '.[] | select(.id == "'$research_id'")' claudedocs/research-outputs/MANIFEST.jsonl

# 3. Block on missing manifest - DO NOT spawn next agent until confirmed
if ! cleo research show "$research_id" &>/dev/null; then
    echo "ERROR: Manifest entry missing for $research_id"
    echo "ACTION: Re-spawn with clearer protocol instructions"
    exit 1
fi

Enforcement Sequence

Copy1. Generate spawn prompt  →  orchestrator_spawn_for_task() or cleo orchestrator spawn
2. VERIFY protocol block  →  Check prompt contains "SUBAGENT PROTOCOL"
3. Spawn subagent         →  Task tool with validated prompt
4. Receive return message →  VALIDATE against allowed formats
5. Verify manifest entry  →  cleo research show <id> BEFORE proceeding
6. Continue or escalate   →  Only spawn next if manifest confirmed

Anti-Patterns (Protocol Violations)

Workflow Phases

Phase 1: Discovery

Copy# Use the start command for comprehensive state
cleo orchestrator start --epic T1575

# Or check manifest pending work
{{RESEARCH_PENDING_CMD}}

• Check MANIFEST.jsonl for pending followup
• Review active sessions and focus
• Identify next actionable task

Phase 2: Planning

Copy# Analyze dependency waves
cleo orchestrator analyze T1575

# Get all parallel-safe tasks
cleo orchestrator ready --epic T1575

• Decompose work into subagent-sized chunks
• Define clear completion criteria
• Establish dependency order

Phase 3: Execution

Copy# Get next ready task
cleo orchestrator next --epic T1575

# Generate and use spawn prompt
cleo orchestrator spawn T1586

• Spawn subagents sequentially (not parallel unless verified safe)
• Wait for manifest entry before proceeding
• Read only key_findings from completed work

Phase 4: Integration

Copy# Validate subagent output
cleo orchestrator validate --subagent <research-id>

# Check context budget
cleo orchestrator context

• Verify all subagent outputs in manifest
• Update CLEO task status
• Document completion in session notes

Parallel Execution

When tasks have no inter-dependencies, they can run in parallel:

Copy# Check if tasks can run together
cleo orchestrator check T1578 T1580 T1582

# Get all parallel-safe tasks
cleo orchestrator ready --epic T1575

# Analyze full wave structure
cleo orchestrator parallel T1575

Wave-Based Execution:

• Wave 0: Tasks with no dependencies (can run in parallel)
• Wave 1: Tasks depending only on Wave 0
• Wave N: Tasks depending on Wave N-1 or earlier

Anti-Patterns (MUST NOT)

1. MUST NOT read full research files - use manifest summaries
2. MUST NOT spawn parallel subagents without checking dependencies
3. MUST NOT implement code directly - delegate to subagents
4. MUST NOT exceed 10K context tokens
5. MUST NOT skip subagent protocol block injection
6. MUST NOT spawn tasks out of dependency order

---

Skill Dispatch Rules

Use the appropriate skill for each task type. The spawn command accepts skill names in multiple formats.

Skill Selection Matrix

Skill Name Aliases

The spawn command supports multiple name formats:

Skill Paths

Copyskills/ct-epic-architect/SKILL.md
skills/ct-spec-writer/SKILL.md
skills/ct-research-agent/SKILL.md
skills/ct-test-writer-bats/SKILL.md
skills/ct-library-implementer-bash/SKILL.md
skills/ct-task-executor/SKILL.md
skills/ct-validator/SKILL.md
skills/ct-documentor/SKILL.md

---

Token Injection System

The spawn command handles token injection automatically. For manual injection, use lib/token-inject.sh.

Automatic (via spawn command)

Copy# The spawn command automatically:
# 1. Loads the skill template
# 2. Sets required context tokens
# 3. Gets task context from CLEO
# 4. Extracts manifest summaries
# 5. Injects all tokens
cleo orchestrator spawn T1586 --template ct-research-agent

Manual Token Injection

Copysource lib/token-inject.sh

# 1. Set required tokens
export TI_TASK_ID="T1234"
export TI_DATE="$(date +%Y-%m-%d)"
export TI_TOPIC_SLUG="my-research-topic"

# 2. Set CLEO defaults (task commands, output paths)
ti_set_defaults

# 3. Optional: Get task context from CLEO
task_json=$(cleo show T1234 --format json)
ti_set_task_context "$task_json"

# 4. Load and inject skill template
template=$(ti_load_template "skills/ct-research-agent/SKILL.md")

Token Reference

Source of Truth: skills/_shared/placeholders.json

Required Tokens

Task Command Tokens (CLEO defaults)

Output Tokens (CLEO defaults)

Task Context Tokens (populated from CLEO task data)

Helper Functions

---

Shared References

Skills use shared protocol files for consistency:

Task System Integration

@skills/_shared/task-system-integration.md

Defines portable task management commands using dynamic tokens. Skills reference this instead of hardcoding CLEO commands.

Subagent Protocol Base

@skills/_shared/subagent-protocol-base.md

Defines RFC 2119 output requirements for all subagents:

• OUT-001: MUST write findings to output file
• OUT-002: MUST append to MANIFEST.jsonl
• OUT-003: MUST return only summary message
• OUT-004: MUST NOT return research content

---

Complete Spawning Workflow

Automated Workflow (Recommended)

Copy# Step 1: Get ready task
cleo orchestrator next --epic T1575
# Returns: { nextTask: { id: "T1586", title: "...", priority: "high" } }

# Step 2: Generate spawn prompt (handles all token injection)
spawn_result=$(cleo orchestrator spawn T1586)

# Step 3: Extract prompt and use with Task tool
prompt=$(echo "$spawn_result" | jq -r '.result.prompt')
# Pass $prompt to Task tool

---

Programmatic Spawning with orchestrator_spawn_for_task()

For advanced automation, use the orchestrator_spawn_for_task() function from lib/orchestrator-spawn.sh. This consolidates the manual 6-step workflow into a single function call.

Basic Usage

Copysource lib/orchestrator-spawn.sh

# Prepare complete subagent prompt for a task
prompt=$(orchestrator_spawn_for_task "T1234")

# With explicit skill override (bypasses auto-dispatch)
prompt=$(orchestrator_spawn_for_task "T1234" "ct-research-agent")

# With target model validation
prompt=$(orchestrator_spawn_for_task "T1234" "" "sonnet")

What orchestrator_spawn_for_task() Does

The function performs these steps automatically:

Return Value Structure

Copy{
  "_meta": { "command": "orchestrator", "operation": "spawn_for_task" },
  "success": true,
  "result": {
    "taskId": "T1234",
    "skill": "ct-research-agent",
    "topicSlug": "auth-implementation",
    "date": "2026-01-20",
    "epicId": "T1200",
    "outputFile": "2026-01-20_auth-implementation.md",
    "spawnTimestamp": "2026-01-20T15:30:00Z",
    "targetModel": "auto",
    "taskContext": {
      "title": "Implement auth module",
      "description": "Full task description..."
    },
    "instruction": "Use Task tool to spawn subagent with the following prompt:",
    "prompt": "Complete injected prompt content..."
  }
}

Helper Functions

Complete Workflow Example

Copy#!/usr/bin/env bash
# Example: Spawn research subagent for task T1586

source lib/orchestrator-spawn.sh

# 1. Generate spawn result (includes all tokens and context)
spawn_result=$(orchestrator_spawn_for_task "T1586")

# 2. Check success
if [[ $(echo "$spawn_result" | jq -r '.success') != "true" ]]; then
    echo "Spawn failed: $(echo "$spawn_result" | jq -r '.error.message')" >&2
    exit 1
fi

# 3. Extract prompt for Task tool
prompt=$(echo "$spawn_result" | jq -r '.result.prompt')
output_file=$(echo "$spawn_result" | jq -r '.result.outputFile')
skill=$(echo "$spawn_result" | jq -r '.result.skill')

# 4. Log spawn metadata
echo "Spawning $skill for task T1586"
echo "Expected output: $output_file"

# 5. Pass $prompt to Task tool (in orchestrator context)
# The Task tool invocation would include:
#   - description: "Execute task T1586 with $skill"
#   - prompt: $prompt

Token Injection with lib/token-inject.sh

For fine-grained control over token injection, use lib/token-inject.sh directly.

Token Categories

Manual Token Injection Example

Copysource lib/token-inject.sh

# 1. Set required tokens
ti_set_context "T1234" "2026-01-20" "auth-research"

# 2. Set CLEO defaults for task commands and paths
ti_set_defaults

# 3. Get task context from CLEO
task_json=$(cleo show T1234 --format json)
ti_set_task_context "$task_json"

# 4. Load and inject skill template
template=$(ti_load_template "skills/ct-research-agent/SKILL.md")

# 5. Verify tokens were injected
echo "$template" | grep -c '{{' && echo "WARNING: Uninjected tokens remain"

Key Functions

Debug Mode

Enable debug output for troubleshooting:

Copyexport ORCHESTRATOR_SPAWN_DEBUG=1
prompt=$(orchestrator_spawn_for_task "T1234")
# Logs to stderr: [orchestrator-spawn] DEBUG: ...

---

Manual Workflow

Step 1: Identify Task Type

Copy# Check task details
cleo show T1234 | jq '{title, description, labels}'

Step 2: Select Skill

Match task keywords to skill selection matrix above.

Step 3: Prepare Context

Copysource lib/token-inject.sh

# Set required tokens
ti_set_context "T1234" "$(date +%Y-%m-%d)" "auth-implementation"

# Set defaults and get task context
ti_set_defaults
task_json=$(cleo show T1234 --format json)
ti_set_task_context "$task_json"

Step 4: Load Skill Template

Copytemplate=$(ti_load_template "skills/ct-task-executor/SKILL.md")

Step 5: Spawn Subagent

Use Task tool with:

1. Injected skill template
2. Subagent protocol block
3. Context from previous agents (manifest key_findings ONLY)
4. Clear task definition and completion criteria

Step 6: Monitor Completion

Copy# Check manifest for completion
{{RESEARCH_SHOW_CMD}} <research-id>

# Or use jq
jq -s '.[-1] | {id, status, key_findings}' {{MANIFEST_PATH}}

Step 7: Compliance Verification

After each subagent returns, orchestrator MUST verify compliance:

Copysource lib/compliance-check.sh

# 1. Score compliance (checks manifest entry, research link, return format)
metrics=$(score_subagent_compliance "$task_id" "$agent_id" "$response")

# 2. Extract pass rate
compliance_pass_rate=$(echo "$metrics" | jq -r '.compliance.compliance_pass_rate')

# 3. Log violation if not 100% pass
if [[ "$compliance_pass_rate" != "1.0" ]]; then
    log_violation "$epic_id" "$(jq -n \
        --arg task "$task_id" \
        --arg agent "$agent_id" \
        --arg rate "$compliance_pass_rate" \
        '{summary: "Subagent compliance failure", task_id: $task, agent_id: $agent, severity: "medium"}'
    )"
fi

# 4. Append metrics to COMPLIANCE.jsonl (automatic via score_subagent_compliance)
log_compliance_metrics "$metrics"

Compliance Checks Performed:

---

Epic Completion: Compliance Report

Before marking an epic complete, orchestrator MUST generate compliance summary:

Copysource lib/metrics-aggregation.sh

# 1. Get project compliance summary
summary=$(get_project_compliance_summary)

# 2. Extract key metrics
total_tasks=$(echo "$summary" | jq -r '.result.totalEntries')
pass_rate=$(echo "$summary" | jq -r '.result.averagePassRate')
violations=$(echo "$summary" | jq -r '.result.totalViolations')

# 3. Check for critical breaches
critical_count=$(echo "$summary" | jq -r '.result.bySeverity.critical // 0')
high_count=$(echo "$summary" | jq -r '.result.bySeverity.high // 0')

# 4. Block auto-complete if critical breaches exist
if [[ "$critical_count" -gt 0 || "$high_count" -gt 0 ]]; then
    echo "ERROR: Cannot auto-complete epic - critical/high violations exist"
    echo "Critical: $critical_count, High: $high_count"
    echo "ACTION: Resolve violations before completing epic"
    exit 1
fi

# 5. Report compliance summary
echo "=== Epic Compliance Report ==="
echo "Total Tasks: $total_tasks"
echo "Pass Rate: $(awk "BEGIN {printf \"%.1f\", $pass_rate * 100}")%"
echo "Violations: $violations"

Auto-Complete Criteria:

• critical_breach_rate == 0 (no critical violations)
• high_breach_rate == 0 (no high-severity violations)
• All subagent manifest entries validated

---

Subagent Retry Protocol

When a subagent fails compliance checks, orchestrator MUST follow retry protocol:

Copy# Retry thresholds
MAX_RETRIES=2
COMPLIANCE_THRESHOLD="0.80"

# Check if retry needed
if (( $(echo "$compliance_pass_rate < $COMPLIANCE_THRESHOLD" | bc -l) )); then
    echo "WARN: Compliance pass rate below 80% ($compliance_pass_rate)"

    # Log violation
    log_violation "$epic_id" "$(jq -n \
        --arg task "$task_id" \
        --arg agent "$agent_id" \
        --arg rate "$compliance_pass_rate" \
        '{summary: "Subagent retry triggered", task_id: $task, agent_id: $agent, severity: "medium"}'
    )"

    # Re-spawn with stricter prompt (add explicit checklist)
    stricter_prompt="$original_prompt

## COMPLIANCE CHECKLIST (VERIFY BEFORE RETURNING)
- [ ] Output file exists at {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
- [ ] MANIFEST.jsonl entry appended with all required fields
- [ ] Return message is EXACTLY: 'Research complete. See MANIFEST.jsonl for summary.'
- [ ] Task linked via: {{TASK_LINK_CMD}} {{TASK_ID}} <research-id>
- [ ] Task completed via: {{TASK_COMPLETE_CMD}} {{TASK_ID}}
"

    # Track retry count (stored in session context)
    retry_count=$((retry_count + 1))

    if [[ $retry_count -gt $MAX_RETRIES ]]; then
        echo "ERROR: Max retries ($MAX_RETRIES) exceeded for task $task_id"
        echo "ACTION: Escalate to human review"
        # Mark task as blocked
        cleo update "$task_id" --status blocked --blocked-by "Compliance failure after $MAX_RETRIES retries"
        exit 1
    fi

    # Re-spawn with stricter prompt
    # ... Task tool invocation with $stricter_prompt ...
fi

Retry Rules:

---

Context Budget Monitoring

Copy# Check current context usage
cleo orchestrator context

# With specific token count
cleo orchestrator context --tokens 5000

Status Thresholds:

---

Validation

Copy# Full protocol validation
cleo orchestrator validate

# Validate for specific epic
cleo orchestrator validate --epic T1575

# Validate specific subagent output
cleo orchestrator validate --subagent research-id-2026-01-18

# Manifest only
cleo orchestrator validate --manifest

---

Error Recovery