@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/protocols/agent-protocol.md

@@ -0,0 +1,260 @@
+# CLEO Agent Protocol
+
+**Version**: 1.0.0
+**Type**: Agent Reference
+**Audience**: LLM agents operating CLEO CLI
+
+---
+
+## Commands
+
+| Command | Purpose | Output Key |
+|---------|---------|------------|
+| ct find "query" | Search tasks | .tasks[].id |
+| ct find --id 142 | ID search | .tasks[].id |
+| ct show T### | Task details | .task |
+| ct add "Title" | Create task | .task.id |
+| ct add "Title" --parent T### | Create subtask | .task.id |
+| ct done T### | Complete task | .completedAt |
+| ct update T### --status active | Update status | .task |
+| ct start T### | Start working on task | .task |
+| ct current | Current task | .task |
+| ct next | Suggest task | .recommendation.taskId |
+| ct session list | List sessions | .sessions[] |
+| ct session start --scope epic:T### --auto-start --name "..." | Start session | .session.id |
+| ct session end --note "..." | End session | .session |
+| ct session resume ID | Resume session | .session |
+| ct session status | Current session | .session |
+| ct dash | Project overview | .summary |
+| ct context | Context usage | .context |
+| ct archive | Archive done tasks | .archived[] |
+| ct exists T### | Check existence | .exists |
+| ct list --parent T### | Children only | .tasks[] |
+
+## Session Sequence
+
+1. `ct session list` - Check existing sessions
+2. `ct session start --scope epic:T### --auto-start --name "Name"` OR `ct session resume ID`
+3. `ct start T###` - Start working on task
+4. Execute work on current task
+5. `ct complete T###` - Mark done
+6. `ct start T###` - Next task (or `ct next`)
+7. `ct archive` - Clean up done tasks
+8. `ct session end --note "Progress summary"` - ALWAYS end
+
+**CRITICAL**: Session start requires BOTH `--scope` AND `--auto-start` (or `--start T###`)
+
+## Exit Codes
+
+### General (0-8)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 0 | SUCCESS | - | - |
+| 1 | GENERAL_ERROR | Yes | Check error.message |
+| 2 | INVALID_INPUT | Yes | Fix arguments |
+| 3 | FILE_ERROR | No | Check permissions |
+| 4 | NOT_FOUND | Yes | `ct find` to locate ID |
+| 5 | DEPENDENCY_ERROR | No | Install missing tool |
+| 6 | VALIDATION_ERROR | Yes | Check field lengths, escape \$ |
+| 7 | LOCK_TIMEOUT | Yes | Retry after delay |
+| 8 | CONFIG_ERROR | Yes | `ct doctor` to diagnose |
+
+### Hierarchy (10-19)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 10 | PARENT_NOT_FOUND | Yes | `ct exists <parentId>` first |
+| 11 | DEPTH_EXCEEDED | Yes | Max 3 levels (epic->task->subtask) |
+| 12 | SIBLING_LIMIT | Yes | Check parent children count |
+| 13 | INVALID_PARENT_TYPE | Yes | Subtasks cannot have children |
+| 14 | CIRCULAR_REFERENCE | No | Check dependency graph |
+| 15 | ORPHAN_DETECTED | Yes | Verify parent exists |
+| 16 | HAS_CHILDREN | Yes | Delete children first or use --cascade |
+| 17 | TASK_COMPLETED | Yes | Use `ct archive` instead |
+| 18 | CASCADE_FAILED | No | Manual intervention required |
+| 19 | HAS_DEPENDENTS | Yes | Use --orphan flag |
+
+### Concurrency (20-22)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 20 | CHECKSUM_MISMATCH | Yes | Retry (file changed externally) |
+| 21 | CONCURRENT_MODIFICATION | Yes | Retry after delay |
+| 22 | ID_COLLISION | Yes | Retry (regenerates ID) |
+
+### Session (30-39)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 30 | SESSION_EXISTS | Yes | `ct session list`, resume existing |
+| 31 | SESSION_NOT_FOUND | Yes | `ct session list` for valid IDs |
+| 32 | SCOPE_CONFLICT | Yes | End conflicting session first |
+| 33 | SCOPE_INVALID | Yes | Verify epic exists |
+| 34 | TASK_NOT_IN_SCOPE | Yes | End session, restart with correct scope |
+| 35 | TASK_CLAIMED | Yes | `ct next` for unclaimed task |
+| 36 | SESSION_REQUIRED | Yes | `ct session start` first |
+| 37 | SESSION_CLOSE_BLOCKED | No | Complete pending tasks first |
+| 38 | START_REQUIRED | Yes | `ct start T###` |
+| 39 | NOTES_REQUIRED | Yes | Add `--note "..."` |
+
+### Verification (40-47)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 40 | VERIFICATION_INIT_FAILED | Yes | Check task state |
+| 41 | GATE_UPDATE_FAILED | Yes | Retry |
+| 42 | INVALID_GATE | Yes | Check valid gate names |
+| 43 | INVALID_AGENT | Yes | Check valid agent names |
+| 44 | MAX_ROUNDS_EXCEEDED | Yes | Review implementation |
+| 45 | GATE_DEPENDENCY | Yes | Complete prerequisite gate |
+| 46 | VERIFICATION_LOCKED | No | Requires manual unlock |
+| 47 | ROUND_MISMATCH | Yes | Sync round number |
+
+### Context Safeguard (50-54)
+
+| Code | Constant | Action |
+|------|----------|--------|
+| 50 | CONTEXT_WARNING | Continue, reduce output |
+| 51 | CONTEXT_CAUTION | Prioritize completion |
+| 52 | CONTEXT_CRITICAL | Run `ct safestop` |
+| 53 | CONTEXT_EMERGENCY | Immediate `ct safestop` |
+| 54 | CONTEXT_STALE | Re-check context state |
+
+### Protocol/Orchestrator (60-67)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 60 | PROTOCOL_MISSING | Yes | Add protocol injection block |
+| 61 | INVALID_RETURN_MESSAGE | Yes | Fix return format |
+| 62 | MANIFEST_ENTRY_MISSING | Yes | Append MANIFEST.jsonl entry |
+| 63 | SPAWN_VALIDATION_FAILED | Yes | Fix spawn parameters |
+| 64 | AUTONOMOUS_BOUNDARY | No | Requires HITL decision |
+| 65 | HANDOFF_REQUIRED | No | Generate handoff document |
+| 66 | RESUME_FAILED | Yes | Check session/handoff validity |
+| 67 | CONCURRENT_SESSION | Yes | End other session first |
+
+**NOTE**: Codes 60-67 have a known collision between protocol validation (RCSD) and orchestrator functions. They are isolated by usage context.
+
+### Nexus (70-79)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 70 | NEXUS_NOT_INITIALIZED | Yes | Run nexus init |
+| 71 | NEXUS_PROJECT_NOT_FOUND | Yes | Register project first |
+| 72 | NEXUS_PERMISSION_DENIED | No | Check permissions |
+| 73 | NEXUS_INVALID_SYNTAX | Yes | Fix query syntax |
+| 74 | NEXUS_SYNC_FAILED | Yes | Retry sync |
+| 75 | NEXUS_REGISTRY_CORRUPT | No | Manual repair needed |
+| 76 | NEXUS_PROJECT_EXISTS | Yes | Already registered |
+| 77 | NEXUS_QUERY_FAILED | Yes | Retry or refine query |
+| 78 | NEXUS_GRAPH_ERROR | Yes | Retry |
+| 79 | NEXUS_RESERVED | - | Reserved |
+
+### Lifecycle (80-84)
+
+| Code | Constant | Recoverable | Recovery |
+|------|----------|:-----------:|----------|
+| 80 | LIFECYCLE_GATE_FAILED | Yes | Complete prerequisite RCSD stages |
+| 81 | AUDIT_MISSING | Yes | Add required audit fields |
+| 82 | CIRCULAR_VALIDATION | No | Assign different validator |
+| 83 | LIFECYCLE_TRANSITION_INVALID | No | Follow RCSD->IVTR sequence |
+| 84 | PROVENANCE_REQUIRED | Yes | Add provenance fields |
+
+### Special (100+) - NOT errors
+
+| Code | Constant | Meaning | Agent Action |
+|------|----------|---------|-------------|
+| 100 | NO_DATA | Query returned empty | Do NOT retry. No matching data. |
+| 101 | ALREADY_EXISTS | Resource exists | Treat as success. |
+| 102 | NO_CHANGE | No-op (idempotent) | Treat as success. Do NOT retry. |
+
+## Error Recovery Decision Trees
+
+### Exit 34 (TASK_NOT_IN_SCOPE)
+```
+1. ct session status           -> get current scope
+2. ct show T###                -> get task's parent epic
+3. ct session end --note "Scope mismatch"
+4. ct session start --scope epic:<parentId> --auto-start --name "Name"
+5. RETRY original command
+```
+
+### Exit 35 (TASK_CLAIMED)
+```
+1. ct next                     -> get unclaimed task suggestion
+2. ct start <suggested>        -> switch to unclaimed task
+```
+
+### Exit 38 (START_REQUIRED)
+```
+1. ct start T###               -> start working on target task
+2. RETRY original command
+```
+
+### Exit 100 (NO_DATA) with session start
+```
+1. ct session list             -> check existing sessions
+2. IF sessions exist: ct session resume <id>
+3. ELSE: ct session start --scope epic:T### --auto-start --name "Name"
+```
+
+## State Transitions
+
+| From | To | Via Command |
+|------|----|-------------|
+| pending | active | `ct start T###` |
+| pending | blocked | `ct update T### --status blocked` |
+| pending | done | `ct complete T###` |
+| active | pending | `ct start <other>` (stops current) |
+| active | blocked | `ct update T### --status blocked` |
+| active | done | `ct complete T###` |
+| blocked | pending | `ct update T### --status pending` |
+| blocked | active | `ct start T###` |
+| done | active | `ct reopen T###` |
+
+Valid statuses: `pending` | `active` | `blocked` | `done`
+
+## JSON Output Format
+
+All commands return:
+```json
+{"_meta":{"command":"...","timestamp":"...","version":"..."},"success":true,...}
+```
+
+Errors return:
+```json
+{"_meta":{...},"success":false,"error":{"code":"E_...","exitCode":N,"message":"...","fix":"ct ...","alternatives":[{"action":"...","command":"ct ..."}]}}
+```
+
+**Parsing patterns**:
+- Success check: `jq '.success'`
+- Error code: `jq '.error.code'`
+- Fix command: `jq -r '.error.fix'`
+- Results field: `jq -r '._meta.resultsField'` -> tells which key has primary data
+
+## Constraints
+
+| Rule | Value |
+|------|-------|
+| Hierarchy depth | Max 3 (epic -> task -> subtask) |
+| Siblings per parent | Max configurable (default varies) |
+| Valid statuses | pending, active, blocked, done |
+| ID format | T### (sequential, immutable) |
+| Shell escaping | Escape `$` as `\$` in arguments |
+| Context efficiency | Use `find` (not `list`) for discovery |
+| Discovery pattern | `find` -> `show` for details |
+
+## Subagent Protocol
+
+1. `ct start T###` - Start task before work
+2. Execute implementation work
+3. Write output file to designated path
+4. Append ONE line to `MANIFEST.jsonl` (compact JSON, no pretty-print)
+5. `ct complete T###` - Mark task done
+6. Return summary message ONLY (no file content)
+
+**Manifest entry format**:
+```json
+{"id":"T###-slug","file":"path","title":"...","date":"YYYY-MM-DD","status":"complete","agent_type":"...","topics":[],"key_findings":[],"actionable":true,"needs_followup":[],"linked_tasks":["T###"]}
+```