@cleocode/agents 2026.3.44 → 2026.3.46
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/cleo-subagent/AGENT.md +187 -32
- package/package.json +1 -1
package/cleo-subagent/AGENT.md
CHANGED
|
@@ -33,7 +33,7 @@ allowed_tools:
|
|
|
33
33
|
|
|
34
34
|
# CLEO Subagent Base Protocol
|
|
35
35
|
|
|
36
|
-
**Version**: 1.
|
|
36
|
+
**Version**: 1.2.0
|
|
37
37
|
**Status**: ACTIVE
|
|
38
38
|
|
|
39
39
|
This is the base protocol for all CLEO subagents. Skills extend this foundation.
|
|
@@ -44,67 +44,185 @@ This is the base protocol for all CLEO subagents. Skills extend this foundation.
|
|
|
44
44
|
|
|
45
45
|
| ID | Rule | Enforcement |
|
|
46
46
|
|----|------|-------------|
|
|
47
|
-
| BASE-001 | **MUST** append ONE
|
|
47
|
+
| BASE-001 | **MUST** append ONE entry to pipeline manifest before returning | Required |
|
|
48
48
|
| BASE-002 | **MUST NOT** return content in response | Required |
|
|
49
|
-
| BASE-003 | **MUST** complete task via `cleo complete` | Required |
|
|
50
|
-
| BASE-004 | **MUST** write output file before manifest | Required |
|
|
51
|
-
| BASE-005 | **MUST**
|
|
49
|
+
| BASE-003 | **MUST** complete task via `cleo complete` (CLI) or `mutate tasks complete` (MCP) | Required |
|
|
50
|
+
| BASE-004 | **MUST** write output file before appending manifest entry | Required |
|
|
51
|
+
| BASE-005 | **MUST** start task before beginning work | Required |
|
|
52
52
|
| BASE-006 | **MUST NOT** fabricate information | Required |
|
|
53
|
-
| BASE-007 | **SHOULD** link
|
|
53
|
+
| BASE-007 | **SHOULD** link memory observations to task via `memory.link` | Recommended |
|
|
54
|
+
| BASE-008 | **MUST** check `success` field on every LAFS response before proceeding | Required |
|
|
54
55
|
|
|
55
56
|
---
|
|
56
57
|
|
|
57
|
-
##
|
|
58
|
+
## CLEO Runtime Model
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
### 10 Canonical Domains
|
|
60
61
|
|
|
61
|
-
|
|
62
|
+
CLEO exposes exactly 10 domains. All operations are addressed as `{domain}.{operation}`:
|
|
63
|
+
|
|
64
|
+
| Domain | Purpose |
|
|
65
|
+
|--------|---------|
|
|
66
|
+
| `tasks` | Task hierarchy, CRUD, work tracking |
|
|
67
|
+
| `session` | Session lifecycle, decisions, context |
|
|
68
|
+
| `memory` | Cognitive memory: observations, decisions, patterns, learnings |
|
|
69
|
+
| `check` | Schema validation, compliance, testing, grading |
|
|
70
|
+
| `pipeline` | RCASD-IVTR+C lifecycle, manifest ledger, release management |
|
|
71
|
+
| `orchestrate` | Multi-agent coordination, wave planning |
|
|
72
|
+
| `tools` | Skills, providers, CAAMP catalog |
|
|
73
|
+
| `admin` | Configuration, diagnostics, ADRs, protocol injection |
|
|
74
|
+
| `nexus` | Cross-project coordination, dependency graph |
|
|
75
|
+
| `sticky` | Ephemeral capture before formal task creation |
|
|
76
|
+
|
|
77
|
+
### 2 MCP Gateways (CQRS)
|
|
78
|
+
|
|
79
|
+
| Gateway | Tool | Purpose |
|
|
80
|
+
|---------|------|---------|
|
|
81
|
+
| `query` | Read-only. Safe to retry. | `query { domain: "tasks", operation: "show", params: { taskId: "T123" } }` |
|
|
82
|
+
| `mutate` | State-changing. | `mutate { domain: "tasks", operation: "complete", params: { taskId: "T123" } }` |
|
|
83
|
+
|
|
84
|
+
### LAFS Response Envelope
|
|
85
|
+
|
|
86
|
+
Every CLEO response uses the LAFS envelope. Always check `success` before acting on `data`:
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{ "success": true, "data": { ... }, "_meta": { ... } }
|
|
90
|
+
{ "success": false, "error": { "code": "E_NOT_FOUND", "message": "...", "fix": "..." } }
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Non-zero exit codes or `"success": false` MUST be treated as failure.
|
|
94
|
+
|
|
95
|
+
### Progressive Disclosure Tiers
|
|
96
|
+
|
|
97
|
+
Operations are organized into 3 tiers. Start at tier 0 and escalate via `admin.help`:
|
|
98
|
+
|
|
99
|
+
| Tier | Scope | Escalation |
|
|
100
|
+
|------|-------|-----------|
|
|
101
|
+
| 0 | Cold-start essentials (tasks CRUD, session lifecycle, memory find/observe, admin dash/help) | Available immediately |
|
|
102
|
+
| 1 | Extended ops (memory timeline/fetch, pipeline manifest, check, orchestrate) | `query admin.help { tier: 1 }` |
|
|
103
|
+
| 2 | Full system (nexus core, WarpChain, advanced admin) | `query admin.help { tier: 2 }` |
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Lifecycle Protocol
|
|
108
|
+
|
|
109
|
+
### Phase 1: Initialize
|
|
62
110
|
|
|
63
111
|
```bash
|
|
64
|
-
#
|
|
65
|
-
cleo show {{TASK_ID}}
|
|
112
|
+
# CLI (preferred)
|
|
113
|
+
cleo show {{TASK_ID}} # read task details
|
|
114
|
+
cleo start {{TASK_ID}} # marks task active (tasks.start)
|
|
66
115
|
|
|
67
|
-
#
|
|
68
|
-
|
|
116
|
+
# MCP equivalent
|
|
117
|
+
query { domain: "tasks", operation: "show", params: { taskId: "{{TASK_ID}}" } }
|
|
118
|
+
mutate { domain: "tasks", operation: "start", params: { taskId: "{{TASK_ID}}" } }
|
|
69
119
|
```
|
|
70
120
|
|
|
71
121
|
### Phase 2: Execute (Skill-Specific)
|
|
72
122
|
|
|
73
|
-
Follow the injected skill protocol for the current
|
|
123
|
+
Follow the injected skill protocol for the current RCASD-IVTR+C stage:
|
|
124
|
+
|
|
74
125
|
- Research: Gather information, cite sources
|
|
75
126
|
- Consensus: Validate claims, vote
|
|
76
127
|
- Specification: Write RFC 2119 spec
|
|
77
128
|
- Decomposition: Break down into tasks
|
|
78
129
|
- Implementation: Write code
|
|
79
130
|
- Validation: Verify compliance
|
|
80
|
-
- Testing: Write
|
|
131
|
+
- Testing: Write tests
|
|
81
132
|
- Contribution: Track attribution
|
|
82
133
|
- Release: Version and changelog
|
|
83
134
|
|
|
84
135
|
### Phase 3: Output (Mandatory)
|
|
85
136
|
|
|
86
137
|
```bash
|
|
87
|
-
# 1. Write output file
|
|
138
|
+
# 1. Write output file (CLI creates it; use absolute path)
|
|
88
139
|
# Location: {{OUTPUT_DIR}}/{{TASK_ID}}-<slug>.md
|
|
89
140
|
|
|
90
|
-
# 2. Append manifest entry
|
|
91
|
-
|
|
141
|
+
# 2. Append manifest entry via MCP (preferred)
|
|
142
|
+
mutate {
|
|
143
|
+
domain: "pipeline",
|
|
144
|
+
operation: "manifest.append",
|
|
145
|
+
params: {
|
|
146
|
+
entry: {
|
|
147
|
+
id: "{{TASK_ID}}-<slug>",
|
|
148
|
+
task_id: "{{TASK_ID}}",
|
|
149
|
+
type: "research", # research | implementation | specification | design | analysis | decision | note
|
|
150
|
+
content: "<summary text>",
|
|
151
|
+
source_file: "{{OUTPUT_DIR}}/{{TASK_ID}}-<slug>.md",
|
|
152
|
+
metadata_json: {
|
|
153
|
+
"title": "Human title",
|
|
154
|
+
"actionable": true,
|
|
155
|
+
"needs_followup": []
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
}
|
|
92
160
|
|
|
93
161
|
# 3. Complete task
|
|
94
|
-
cleo complete {{TASK_ID}}
|
|
162
|
+
cleo complete {{TASK_ID}} # CLI
|
|
163
|
+
# or: mutate { domain: "tasks", operation: "complete", params: { taskId: "{{TASK_ID}}" } }
|
|
95
164
|
```
|
|
96
165
|
|
|
97
166
|
### Phase 4: Return (Summary Only)
|
|
98
167
|
|
|
99
168
|
Return ONLY one of these messages:
|
|
100
|
-
- `"[Type] complete. See
|
|
101
|
-
- `"[Type] partial. See
|
|
102
|
-
- `"[Type] blocked. See
|
|
169
|
+
- `"[Type] complete. See pipeline manifest for summary."`
|
|
170
|
+
- `"[Type] partial. See pipeline manifest for details."`
|
|
171
|
+
- `"[Type] blocked. See pipeline manifest for blocker details."`
|
|
103
172
|
|
|
104
173
|
**NEVER** return content in the response. All content goes to output files.
|
|
105
174
|
|
|
106
175
|
---
|
|
107
176
|
|
|
177
|
+
## Agent Work Loop
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
tasks.current OR tasks.next → pick task
|
|
181
|
+
tasks.show {taskId} → read requirements
|
|
182
|
+
tasks.start {taskId} → begin work
|
|
183
|
+
[do the work]
|
|
184
|
+
pipeline.manifest.append → record output artifact
|
|
185
|
+
tasks.complete {taskId} → mark done
|
|
186
|
+
tasks.next → continue or end session
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
CLI shorthand:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
cleo current # or: cleo next
|
|
193
|
+
cleo show T123
|
|
194
|
+
cleo start T123
|
|
195
|
+
# ... do work ...
|
|
196
|
+
cleo complete T123
|
|
197
|
+
cleo next
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
---
|
|
201
|
+
|
|
202
|
+
## Memory Protocol (3-Layer Retrieval)
|
|
203
|
+
|
|
204
|
+
Use memory for anti-hallucination and cross-session continuity. Always search before fabricating.
|
|
205
|
+
|
|
206
|
+
| Step | CLI | MCP Operation | ~Tokens | Purpose |
|
|
207
|
+
|------|-----|---------------|---------|---------|
|
|
208
|
+
| 1. Search | `cleo memory find "auth"` | `query memory.find { query: "..." }` | ~50/hit | Discover IDs |
|
|
209
|
+
| 2. Timeline | `cleo memory timeline O-abc` | `query memory.timeline { anchor: "O-abc" }` | 200-500 | Context around anchor |
|
|
210
|
+
| 3. Fetch | `cleo observe ...` | `query memory.fetch { ids: ["O-abc"] }` | ~500/entry | Full details |
|
|
211
|
+
| Write | `cleo observe "text"` | `mutate memory.observe { text: "..." }` | — | Save raw observation |
|
|
212
|
+
| Link | — | `mutate memory.link { taskId: "T123", entryId: "O-abc" }` | — | Associate to task |
|
|
213
|
+
|
|
214
|
+
**Anti-pattern**: Never call `memory.fetch` without searching first. Never use the removed `memory.brain.*` prefix.
|
|
215
|
+
|
|
216
|
+
Structured memory (tier 1, use after searching):
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
mutate memory.decision.store { decision: "...", rationale: "..." }
|
|
220
|
+
mutate memory.pattern.store { pattern: "...", context: "..." }
|
|
221
|
+
mutate memory.learning.store { insight: "...", source: "..." }
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
108
226
|
## Token Reference
|
|
109
227
|
|
|
110
228
|
### Required Tokens
|
|
@@ -118,8 +236,7 @@ Return ONLY one of these messages:
|
|
|
118
236
|
| Token | Default | Description |
|
|
119
237
|
|-------|---------|-------------|
|
|
120
238
|
| `{{EPIC_ID}}` | `""` | Parent epic ID |
|
|
121
|
-
| `{{OUTPUT_DIR}}` |
|
|
122
|
-
| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` | Manifest location |
|
|
239
|
+
| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` | Output directory |
|
|
123
240
|
|
|
124
241
|
---
|
|
125
242
|
|
|
@@ -129,21 +246,59 @@ Return ONLY one of these messages:
|
|
|
129
246
|
|
|
130
247
|
| Status | Condition | Action |
|
|
131
248
|
|--------|-----------|--------|
|
|
132
|
-
| `complete` | All objectives achieved | Write full output |
|
|
133
|
-
| `partial` | Some objectives achieved | Write partial, populate `needs_followup` |
|
|
134
|
-
| `blocked` | Cannot proceed | Document blocker, do NOT complete task |
|
|
249
|
+
| `complete` | All objectives achieved | Write full output, complete task |
|
|
250
|
+
| `partial` | Some objectives achieved | Write partial output, populate `needs_followup` in manifest |
|
|
251
|
+
| `blocked` | Cannot proceed | Document blocker in manifest, do NOT complete task |
|
|
135
252
|
|
|
136
|
-
### Retryable
|
|
253
|
+
### Retryable Exit Codes
|
|
137
254
|
|
|
138
255
|
Exit codes 7, 20, 21, 22, 60-63 support retry with exponential backoff.
|
|
139
256
|
|
|
257
|
+
### Operation Error Reference
|
|
258
|
+
|
|
259
|
+
| Error Code | Meaning | Action |
|
|
260
|
+
|------------|---------|--------|
|
|
261
|
+
| `E_INVALID_OPERATION` | Operation name is not in registry (often a deprecated alias) | Check canonical name in VERB-STANDARDS.md |
|
|
262
|
+
| `E_INVALID_INPUT` | Missing required param | Add the required param |
|
|
263
|
+
| `E_NOT_FOUND` | Entity does not exist | Verify ID; use `tasks.find` to discover |
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## Escalation
|
|
268
|
+
|
|
269
|
+
For deeper guidance beyond tier 0:
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
cleo admin help # tier 0 operations list
|
|
273
|
+
cleo admin help --tier 1 # + tier 1 operations
|
|
274
|
+
cleo admin help --tier 2 # all operations
|
|
275
|
+
|
|
276
|
+
# MCP equivalent
|
|
277
|
+
query { domain: "admin", operation: "help" }
|
|
278
|
+
query { domain: "admin", operation: "help", params: { tier: 1 } }
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
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.
|
|
282
|
+
|
|
283
|
+
To load the full CLEO operations reference at runtime:
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
query { domain: "tools", operation: "skill.list" } # see available skills
|
|
287
|
+
query { domain: "admin", operation: "help", params: { tier: 2 } } # all ops
|
|
288
|
+
```
|
|
289
|
+
|
|
140
290
|
---
|
|
141
291
|
|
|
142
292
|
## Anti-Patterns
|
|
143
293
|
|
|
144
294
|
| Pattern | Problem | Solution |
|
|
145
295
|
|---------|---------|----------|
|
|
146
|
-
| Returning content | Bloats orchestrator context | Write to file, return summary |
|
|
147
|
-
|
|
|
148
|
-
| Skipping start | Protocol violation | Always
|
|
149
|
-
|
|
|
296
|
+
| Returning content in response | Bloats orchestrator context | Write to file, return one-line summary |
|
|
297
|
+
| Writing pretty-printed JSON to manifest | Multiple lines break JSONL parsers | Use `pipeline.manifest.append` MCP op |
|
|
298
|
+
| Skipping `tasks.start` | Protocol violation | Always start before working |
|
|
299
|
+
| Using `memory.brain.*` prefix | Removed in ADR-021 — returns `E_INVALID_OPERATION` | Use `memory.find`, `memory.observe`, etc. |
|
|
300
|
+
| Using `tasks.exists` | Removed from registry | Use `tasks.find { exact: true }` and check `results.length > 0` |
|
|
301
|
+
| Calling `tasks.list` without filters | Returns all tasks with notes, huge token cost | Use `tasks.find` for discovery |
|
|
302
|
+
| Appending to `MANIFEST.jsonl` directly | Legacy file — migrated to SQLite (ADR-027) | Use `pipeline.manifest.append` |
|
|
303
|
+
| Loading skills via `@` at runtime | Cannot resolve outside orchestrator spawn | Skills are injected by orchestrator at spawn |
|
|
304
|
+
| Fabricating data when memory is empty | Hallucination | Use `memory.find` first; if truly unknown, state uncertainty |
|