@cleocode/agents 2026.4.84 → 2026.4.85

package/cleo-subagent/AGENT.md

@@ -33,10 +33,11 @@ allowed_tools:
 
 # CLEO Subagent Base Protocol
 
-**Version**: 1.3.0
+**Version**: 2.0.0
 **Status**: ACTIVE
+**Breaking change (v2.0.0 · T882)**: spawn prompts generated by `cleo orchestrate spawn <taskId>` are now **fully self-contained**. Subagents MUST NOT re-resolve protocol content, re-load skills via `@` notation, or re-hydrate task context — everything required to execute, verify, and close the task is in the spawn prompt itself.
 
-This is the base protocol for all CLEO subagents. Skills extend this foundation.
+This document is the base protocol for all CLEO subagents. It describes what subagents can rely on and what they must NOT do when invoked via the canonical spawn pipeline.
 
 ---
 
@@ -67,6 +68,36 @@ enforcement of that contract.
 
 ---
 
+## Spawn Prompt Contract (T882 · v2.0.0)
+
+Every subagent is invoked with a **fully-resolved spawn prompt** generated by
+`cleo orchestrate spawn <taskId>`. The prompt contains, at minimum:
+
+| Section | Contents |
+|---------|----------|
+| Task Identity | id, title, description, parent epic, acceptance criteria, size, priority, labels, dependencies |
+| File Paths | absolute paths to agent-outputs dir, MANIFEST.jsonl, rcasd workspace, test-runs dir |
+| Session Linkage | orchestrator session id (or "no active session" fallback) |
+| Stage-Specific Guidance | protocol-specific deliverables for the current RCASD-IVTR+C phase |
+| Evidence-Based Gate Ritual | exact `cleo verify --gate --evidence` commands per gate (ADR-051) |
+| Quality Gates | `pnpm biome ci .` + `pnpm run build` + `pnpm run test` commands |
+| Return Format Contract | exact one-line completion strings |
+| CLEO Protocol | embedded (tier 1/2) or pointer (tier 0) — no `@file` re-resolution required |
+
+**What subagents MUST do**: read the spawn prompt and follow it literally.
+
+**What subagents MUST NOT do**:
+- Re-load skills via `@skills/...md` references at runtime
+- Re-query `cleo admin help` to discover operations already listed in the prompt
+- Re-read `CLEO-INJECTION.md` when the prompt already embeds it
+- Fabricate file paths — use the absolute paths the prompt provides
+
+If a section is missing from the spawn prompt, the spawn was generated by an
+older CLEO version; log this as a warning in the manifest entry and fall back
+to `~/.cleo/templates/CLEO-INJECTION.md` as the authoritative protocol source.
+
+---
+
 ## Immutable Constraints (RFC 2119)
 
 | ID | Rule | Enforcement |
@@ -293,26 +324,22 @@ Exit codes 7, 20, 21, 22, 60-63 support retry with exponential backoff.
 
 ## Escalation
 
-For deeper guidance beyond tier 0:
+The spawn prompt already contains the protocol content appropriate for the
+current task. Only escalate when the prompt explicitly defers to a tier-2
+operation or when you hit an error the prompt does not cover.
 
 ```bash
 cleo admin help           # tier 0 operations list
 cleo admin help --tier 1  # + tier 1 operations
-cleo admin help --tier 2  # all operations
-
-# MCP equivalent
-query { domain: "admin", operation: "help" }
-query { domain: "admin", operation: "help", params: { tier: 1 } }
+cleo admin help --tier 2  # all operations (rare — prompt usually covers what you need)
 ```
 
-For full skill protocol, the orchestrator injects skills at spawn time. Skills MUST NOT be loaded via `@` notation at runtime — they are injected by the orchestrator before the agent starts.
-
-To load the full CLEO operations reference at runtime:
-
-```bash
-query { domain: "tools", operation: "skill.list" }   # see available skills
-query { domain: "admin", operation: "help", params: { tier: 2 } }  # all ops
-```
+Skills MUST NOT be loaded via `@skills/...md` notation at runtime. When a
+subagent spawned by `cleo orchestrate spawn` needs skill content beyond
+what the prompt embeds, the orchestrator should re-spawn with `--tier 2`.
+Runtime `@` resolution is unreliable (paths differ per provider) and is the
+root cause of the "spawned subagent hand-rolls prompts" anti-pattern that
+v2.0.0 of this protocol eliminates.
 
 ---
 
@@ -327,5 +354,7 @@ query { domain: "admin", operation: "help", params: { tier: 2 } }  # all ops
 | Using `tasks.exists` | Removed from registry | Use `tasks.find { exact: true }` and check `results.length > 0` |
 | Calling `tasks.list` without filters | Returns all tasks with notes, huge token cost | Use `tasks.find` for discovery |
 | Appending to `MANIFEST.jsonl` directly | Legacy file — migrated to SQLite (ADR-027) | Use `pipeline.manifest.append` |
-| Loading skills via `@` at runtime | Cannot resolve outside orchestrator spawn | Skills are injected by orchestrator at spawn |
+| Loading skills via `@` at runtime | Cannot resolve outside orchestrator spawn | Skills are embedded in the spawn prompt (tier 2). Ask the orchestrator to re-spawn with `--tier 2` if needed. |
+| Re-resolving task/protocol context the prompt already supplies | Wastes tokens and duplicates work | Treat the spawn prompt as authoritative — every section is resolved |
+| Fabricating absolute paths (manifest, rcasd dir) | Writes escape to wrong worktree | Use the exact paths in the **File Paths** section of the spawn prompt |
 | Fabricating data when memory is empty | Hallucination | Use `memory.find` first; if truly unknown, state uncertainty |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/agents",
-  "version": "2026.4.84",
+  "version": "2026.4.85",
   "description": "CLEO agent protocols and templates",
   "type": "module",
   "license": "MIT",