@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/skills/ct-orchestrator/references/orchestrator-compliance.md

@@ -0,0 +1,271 @@
+# Orchestrator: Protocol Compliance
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on protocol enforcement, validation requirements, compliance verification, retry protocols, or anti-patterns
+
+## Protocol Enforcement Requirements
+
+### MUST Inject Protocol Block
+
+Every Task tool spawn **MUST** include the protocol block. Verification:
+
+```bash
+# 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:
+
+| Status | Valid Return Message |
+|--------|---------------------|
+| Complete | "Research complete. See MANIFEST.jsonl for summary." |
+| Partial | "Research partial. See MANIFEST.jsonl for details." |
+| Blocked | "Research blocked. See MANIFEST.jsonl for blocker details." |
+
+Any other return format indicates protocol violation.
+
+### MUST Verify Manifest Entry
+
+After EACH subagent spawn completes, verify manifest entry exists:
+
+```bash
+# 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'")' "{{MANIFEST_PATH}}"
+
+# 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
+```
+
+### MUST Verify Research Link
+
+After subagent completion, verify research is linked to task:
+
+```bash
+# 1. Check task for linked research
+linked=$(cleo show "$task_id" | jq -r '.task.linkedResearch // empty')
+
+# 2. If missing, orchestrator MUST link
+if [[ -z "$linked" ]]; then
+    echo "WARN: Research not linked to task $task_id - orchestrator linking..."
+    cleo research link "$task_id" "$research_id"
+fi
+
+# 3. Verify link succeeded
+if ! cleo show "$task_id" | jq -e '.task.linkedResearch' &>/dev/null; then
+    echo "ERROR: Failed to link research $research_id to task $task_id"
+    echo "ACTION: Manual intervention required"
+fi
+```
+
+**Note**: Subagents SHOULD link research during execution. Orchestrator verification ensures no orphaned research artifacts.
+
+### Enforcement Sequence
+
+```
+1. 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
+5.5. Verify handoff pattern ->  Manifest key_findings used, NOT TaskOutput
+5.6. Extract handoff context ->  key_findings + file path for next spawn
+6. Verify research link   ->  cleo show <task> | check linkedResearch
+7. Link if missing        ->  cleo research link <task> <research-id>
+8. Continue or escalate   ->  Only spawn next if manifest AND link confirmed
+```
+
+---
+
+## Anti-Patterns (Protocol Violations)
+
+| Violation | Detection | Recovery |
+|-----------|-----------|----------|
+| Missing protocol block | `grep -q "SUBAGENT PROTOCOL"` fails | Re-inject via `cleo research inject` |
+| Invalid return message | Not in allowed format list | Mark as violation, re-spawn |
+| No manifest entry | `cleo research show` returns error | Re-spawn with explicit manifest requirement |
+| No research link | `jq '.task.linkedResearch'` empty | Orchestrator links via `cleo research link` |
+| Spawning before verification | Multiple agents, missing entries | Stop, verify all, then resume |
+| Using TaskOutput for results | TOOL-001 violation | Read manifest key_findings only |
+
+---
+
+## Step 7.5: Handoff Validation
+
+After each subagent returns, orchestrator MUST validate handoff compliance:
+
+```bash
+# 1. Verify manifest entry (already in Step 5)
+manifest_entry=$(cleo research show "$research_id" --json)
+
+# 2. Extract handoff context (NOT TaskOutput)
+key_findings=$(echo "$manifest_entry" | jq -r '.key_findings[]')
+output_file=$(echo "$manifest_entry" | jq -r '.file')
+
+# 3. Build next spawn prompt with handoff
+next_prompt="## Context from Previous Agent
+Key Findings:
+$key_findings
+
+Reference file (if details needed): $output_file
+
+## Your Task
+..."
+
+# 4. CRITICAL: Do NOT call TaskOutput
+# TaskOutput violates TOOL-001 and breaks handoff chain
+```
+
+### Handoff Validation Checks
+
+| Check | Constraint | Action if Failed |
+|-------|------------|------------------|
+| key_findings extracted | HNDOFF-001 | Re-query manifest |
+| file path included | HNDOFF-003 | Add to prompt |
+| TaskOutput NOT called | TOOL-001 | Block, re-spawn |
+
+---
+
+## Step 7: Compliance Verification
+
+After each subagent returns, orchestrator **MUST** verify compliance:
+
+```bash
+source 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:**
+| Check | Rule | Severity if Failed |
+|-------|------|-------------------|
+| Manifest entry exists | OUT-002 | high |
+| Research link present | Task linkage | medium |
+| Return format valid | OUT-003 | low |
+| Handoff via manifest | HNDOFF-001 | high |
+| No TaskOutput usage | TOOL-001 | critical |
+
+---
+
+## Epic Completion: Compliance Report
+
+Before marking an epic complete, orchestrator **MUST** generate compliance summary:
+
+```bash
+source 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:
+
+```bash
+# 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:**
+| Condition | Action |
+|-----------|--------|
+| `compliance_pass_rate < 80%` | Log violation, re-spawn with explicit checklist |
+| `retry_count > 2` | Escalate to human, mark task blocked |
+| `critical` severity | Immediate escalation, no retry |

package/packages/ct-skills/skills/ct-orchestrator/references/orchestrator-handoffs.md

@@ -0,0 +1,85 @@
+# Handoff Chain Protocol
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on manifest-mediated handoffs, handoff constraints, prompt templates, or anti-patterns
+
+## Overview
+
+Orchestrator coordinates work through **manifest-mediated handoffs**. Content flows between subagents via files, not through orchestrator context.
+
+## Architecture
+
+```
+Orchestrator (Tier 0)
+    │
+    ├─ Spawns Agent A with task instructions
+    │   └─ A completes → writes output file + manifest entry
+    │
+    ├─ Reads MANIFEST.jsonl → extracts key_findings (3-7 items)
+    │   └─ Does NOT read full output file
+    │   └─ Does NOT use TaskOutput tool
+    │
+    ├─ Spawns Agent B with handoff context
+    │   └─ Prompt includes: "Previous agent found: [key_findings]"
+    │   └─ Prompt includes: "If details needed, read [file path from manifest]"
+    │   └─ B reads full file directly if needed
+    │
+    └─ Continue chain...
+```
+
+## Handoff Constraints (RFC 2119)
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| HNDOFF-001 | Orchestrator MUST read only manifest `key_findings` | Not full output files |
+| HNDOFF-002 | Orchestrator MUST include `key_findings` in next spawn prompt | Context continuity |
+| HNDOFF-003 | Orchestrator MUST include file path for detailed reference | Subagent can read if needed |
+| HNDOFF-004 | Subagents MAY read previous agent output files directly | Full context when needed |
+| HNDOFF-005 | Orchestrator MUST NOT process or analyze subagent content | Delegation enforcement |
+
+## Handoff Prompt Template
+
+When spawning Agent B after Agent A completes:
+
+```markdown
+## Context from Previous Agent
+
+**Previous Task**: {A's task ID} - {A's title}
+**Key Findings**:
+{bullet list from manifest key_findings}
+
+**Reference**: If you need detailed information, read: {file path from manifest}
+
+## Your Task
+{B's instructions}
+```
+
+## Example Handoff
+
+```bash
+# 1. Agent A completes, manifest shows:
+# {"key_findings": ["OAuth2 recommended", "JWT for sessions", "30-day token expiry"]}
+
+# 2. Orchestrator reads manifest summary
+cleo research show A-research-id
+
+# 3. Orchestrator spawns Agent B with context:
+# "Previous research found: OAuth2 recommended, JWT for sessions, 30-day token expiry.
+#  If you need details, read: claudedocs/agent-outputs/2026-01-31_A-research.md
+#  Your task: Implement the authentication module based on these findings."
+```
+
+## Anti-Pattern: Direct Content Flow
+
+**WRONG** (content through orchestrator):
+```
+A completes → Orchestrator reads TaskOutput →
+Orchestrator analyzes content → Spawns B
+```
+
+**CORRECT** (manifest-mediated):
+```
+A completes → Orchestrator reads manifest key_findings →
+Orchestrator spawns B with key_findings + file reference →
+B reads file directly if needed
+```

package/packages/ct-skills/skills/ct-orchestrator/references/orchestrator-patterns.md

@@ -0,0 +1,164 @@
+# Common HITL Patterns
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need executable workflow patterns for specific orchestrator scenarios
+
+Executable workflows for typical orchestrator scenarios.
+
+## Pattern: Starting Fresh Epic
+
+```bash
+# 1. HITL creates epic
+cleo add "Implement auth system" --type epic --size large --phase core
+
+# 2. Start orchestrator session
+cleo session start --scope epic:T1575 --auto-start
+
+# 3. Spawn planning subagent (decomposition protocol)
+cleo orchestrator spawn T1575  # Auto-detects epic → uses decomposition protocol
+
+# 4. Wait for decomposition completion
+cleo research show <research-id>
+
+# 5. Continue with wave-0 tasks
+cleo orchestrator next --epic T1575
+```
+
+## Pattern: Resuming Interrupted Work
+
+```bash
+# 1. Check state on conversation start
+cleo orchestrator start --epic T1575
+# Shows: session active, current T1586, next task T1589
+
+# 2. Check for incomplete subagent work
+cleo research pending
+# Shows: needs_followup: ["T1586"]
+
+# 3. Resume focused task or spawn followup
+cleo show T1586 --brief
+cleo orchestrator spawn T1586  # Re-spawn if needed
+```
+
+## Pattern: Handling Manifest Followups
+
+```bash
+# 1. Query manifest for pending items
+cleo research pending
+# Returns: { "T1586": ["Add error handling", "Write tests"] }
+
+# 2. Create child tasks for followups
+cleo add "Add error handling to auth" --parent T1586 --depends T1586
+cleo add "Write auth tests" --parent T1586 --depends T1586
+
+# 3. Spawn for new tasks
+cleo orchestrator next --epic T1575
+cleo orchestrator spawn T1590
+```
+
+## Pattern: Parallel Execution
+
+```bash
+# 1. Analyze dependency waves
+cleo orchestrator analyze T1575
+# Shows: Wave 0: T1578, T1580, T1582 (no deps)
+
+# 2. Verify parallel safety
+cleo orchestrator ready --epic T1575
+# Returns: ["T1578", "T1580", "T1582"]
+
+# 3. Spawn multiple subagents (different sessions)
+# Session A spawns T1578
+# Session B spawns T1580
+# Session C spawns T1582
+
+# 4. Monitor completion via manifest
+cleo research list --status complete --limit 10
+```
+
+## Pattern: Phase-Aware Orchestration
+
+```bash
+# 1. Check current phase
+cleo phase show
+# Returns: "core"
+
+# 2. Get tasks in current phase
+cleo orchestrator ready --epic T1575 --phase core
+
+# 3. Spawn within phase context
+cleo orchestrator spawn T1586
+
+# 4. When phase complete, advance
+cleo phases stats
+cleo phase advance  # Move to testing phase
+```
+
+## Pattern: Quality Gates Workflow
+
+```bash
+# 1. Subagent completes implementation
+# Returns: "Implementation complete. See MANIFEST.jsonl for summary."
+
+# 2. Orchestrator verifies output
+cleo research show <research-id>
+cleo show T1586
+
+# 3. Spawn validation subagent
+cleo orchestrator spawn T1590  # Validation task
+
+# 4. Set verification gates
+cleo verify T1586 --gate testsPassed
+cleo verify T1586 --gate qaPassed
+cleo verify T1586 --all
+
+# 5. Parent epic auto-completes when all children verified
+```
+
+## Pattern: Release Workflow
+
+**Release tasks use the `release` protocol** via `cleo release` commands.
+
+```bash
+# 1. Verify all epic tasks complete
+cleo list --parent T1575 --status pending  # Should be empty
+
+# 2. Run pre-release validation
+./tests/run-all-tests.sh
+cleo validate
+
+# 3. Create and ship release
+cleo release create v0.85.0 --tasks T001,T002,T003
+cleo release ship v0.85.0 --bump-version --create-tag --push
+
+# Preview without changes:
+cleo release ship v0.85.0 --bump-version --dry-run
+```
+
+**IMPORTANT**: `dev/release-version.sh` is **DEPRECATED** (since v0.78.0).
+Always use `cleo release create` → `cleo release ship`.
+
+See `protocols/release.md` for the full release protocol specification.
+
+## Full RCSD-to-Release Lifecycle
+
+```bash
+# RCSD PIPELINE (setup phase)
+cleo orchestrator spawn T100  # research protocol
+cleo orchestrator spawn T101  # consensus protocol
+cleo orchestrator spawn T102  # specification protocol
+cleo orchestrator spawn T103  # decomposition protocol
+
+# EXECUTION (core phase)
+cleo orchestrator spawn T104  # implementation protocol
+cleo orchestrator spawn T105  # implementation protocol
+# ...more implementation tasks...
+
+# CONTRIBUTION (tracked automatically)
+# contribution protocol auto-triggers for shared resources
+
+# RELEASE (polish phase)
+cleo release create v0.74.0 --tasks T104,T105
+cleo release ship v0.74.0 --bump-version --create-tag --push
+cleo session end --note "Feature X released v0.74.0"
+```

package/packages/ct-skills/skills/ct-orchestrator/references/orchestrator-recovery.md

@@ -0,0 +1,113 @@
+# Orchestrator: Error Recovery
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on error handling, recovery procedures, context budget monitoring, or session lifecycle management
+
+## Error Recovery
+
+| Failure | Detection | Recovery |
+|---------|-----------|----------|
+| No output file | `test -f <path>` fails | Re-spawn with clearer instructions |
+| No manifest entry | `{{RESEARCH_SHOW_CMD}}` fails | Manual entry or re-spawn |
+| Task not completed | Status != done | Orchestrator completes manually |
+| Partial status | `status: partial` | Spawn continuation agent |
+| Blocked status | `status: blocked` | Flag for human review |
+
+---
+
+## Context Budget Monitoring
+
+```bash
+# Check current context usage
+cleo orchestrator context
+
+# With specific token count
+cleo orchestrator context --tokens 5000
+```
+
+**Status Thresholds**:
+| Status | Usage | Action |
+|--------|-------|--------|
+| `ok` | <70% | Continue orchestration |
+| `warning` | 70-89% | Delegate current work soon |
+| `critical` | >=90% | STOP - Delegate immediately |
+
+---
+
+## Session Lifecycle Management
+
+Orchestrator sessions may span multiple Claude conversations. This is expected and supported by design.
+
+### Session Timeout and Retention
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Session timeout | 72 hours | Active sessions auto-end after 72h inactivity |
+| Auto-end threshold | 7 days | `retention.autoEndActiveAfterDays` config |
+| Stale session cleanup | Manual | Use `cleo session gc` for cleanup |
+
+**Key points:**
+- Sessions can legitimately span multiple days of work
+- Long-running orchestration work is expected
+- Sessions persist across Claude conversation boundaries
+
+### Cleanup Commands
+
+```bash
+# Standard garbage collection (ended/suspended sessions only)
+cleo session gc
+
+# Include stale active sessions (>7 days old by default)
+cleo session gc --include-active
+
+# Preview what would be cleaned
+cleo session gc --dry-run
+cleo session gc --include-active --dry-run
+```
+
+### Configuration
+
+```bash
+# View current retention settings
+cleo config get retention
+
+# Adjust auto-end threshold for active sessions
+cleo config set retention.autoEndActiveAfterDays 14  # Extend to 2 weeks
+```
+
+### Best Practices
+
+1. **Session end on completion**: Always end sessions when work completes
+   ```bash
+   cleo session end --note "Epic T1575 phase 1 complete"
+   ```
+
+2. **Session suspend for long waits**: Suspend when blocked on external factors
+   ```bash
+   cleo session suspend --note "Awaiting code review"
+   ```
+
+3. **Periodic cleanup**: Run garbage collection periodically to remove stale sessions
+   ```bash
+   cleo session gc --include-active
+   ```
+
+4. **Multi-day work**: No need to restart sessions daily - orchestrator sessions are designed for extended work periods
+
+---
+
+## Validation
+
+```bash
+# 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
+```