@cleocode/agents 2026.3.45 → 2026.3.46

package/cleo-subagent/AGENT.md

@@ -33,7 +33,7 @@ allowed_tools:
 
 # CLEO Subagent Base Protocol
 
-**Version**: 1.1.0
+**Version**: 1.2.0
 **Status**: ACTIVE
 
 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.
 
 | ID | Rule | Enforcement |
 |----|------|-------------|
-| BASE-001 | **MUST** append ONE line to MANIFEST.jsonl | Required |
+| BASE-001 | **MUST** append ONE entry to pipeline manifest before returning | Required |
 | BASE-002 | **MUST NOT** return content in response | Required |
-| BASE-003 | **MUST** complete task via `cleo complete` | Required |
-| BASE-004 | **MUST** write output file before manifest | Required |
-| BASE-005 | **MUST** set focus before starting work | Required |
+| BASE-003 | **MUST** complete task via `cleo complete` (CLI) or `mutate tasks complete` (MCP) | Required |
+| BASE-004 | **MUST** write output file before appending manifest entry | Required |
+| BASE-005 | **MUST** start task before beginning work | Required |
 | BASE-006 | **MUST NOT** fabricate information | Required |
-| BASE-007 | **SHOULD** link research to task | Recommended |
+| BASE-007 | **SHOULD** link memory observations to task via `memory.link` | Recommended |
+| BASE-008 | **MUST** check `success` field on every LAFS response before proceeding | Required |
 
 ---
 
-## Lifecycle Protocol (LOOM)
+## CLEO Runtime Model
 
-CLEO uses **LOOM** (Logical Order of Operations Methodology) — the systematic framework for processing project threads through the RCASD-IVTR+C pipeline. See `docs/concepts/CLEO-VISION.md` for the complete LOOM framework, neural hierarchy model, and brain metaphor mapping.
+### 10 Canonical Domains
 
-### Phase 1: Spawn (Initialization)
+CLEO exposes exactly 10 domains. All operations are addressed as `{domain}.{operation}`:
+
+| Domain | Purpose |
+|--------|---------|
+| `tasks` | Task hierarchy, CRUD, work tracking |
+| `session` | Session lifecycle, decisions, context |
+| `memory` | Cognitive memory: observations, decisions, patterns, learnings |
+| `check` | Schema validation, compliance, testing, grading |
+| `pipeline` | RCASD-IVTR+C lifecycle, manifest ledger, release management |
+| `orchestrate` | Multi-agent coordination, wave planning |
+| `tools` | Skills, providers, CAAMP catalog |
+| `admin` | Configuration, diagnostics, ADRs, protocol injection |
+| `nexus` | Cross-project coordination, dependency graph |
+| `sticky` | Ephemeral capture before formal task creation |
+
+### 2 MCP Gateways (CQRS)
+
+| Gateway | Tool | Purpose |
+|---------|------|---------|
+| `query` | Read-only. Safe to retry. | `query { domain: "tasks", operation: "show", params: { taskId: "T123" } }` |
+| `mutate` | State-changing. | `mutate { domain: "tasks", operation: "complete", params: { taskId: "T123" } }` |
+
+### LAFS Response Envelope
+
+Every CLEO response uses the LAFS envelope. Always check `success` before acting on `data`:
+
+```json
+{ "success": true,  "data": { ... }, "_meta": { ... } }
+{ "success": false, "error": { "code": "E_NOT_FOUND", "message": "...", "fix": "..." } }
+```
+
+Non-zero exit codes or `"success": false` MUST be treated as failure.
+
+### Progressive Disclosure Tiers
+
+Operations are organized into 3 tiers. Start at tier 0 and escalate via `admin.help`:
+
+| Tier | Scope | Escalation |
+|------|-------|-----------|
+| 0 | Cold-start essentials (tasks CRUD, session lifecycle, memory find/observe, admin dash/help) | Available immediately |
+| 1 | Extended ops (memory timeline/fetch, pipeline manifest, check, orchestrate) | `query admin.help { tier: 1 }` |
+| 2 | Full system (nexus core, WarpChain, advanced admin) | `query admin.help { tier: 2 }` |
+
+---
+
+## Lifecycle Protocol
+
+### Phase 1: Initialize
 
 ```bash
-# 1. Read task context
-cleo show {{TASK_ID}}
+# CLI (preferred)
+cleo show {{TASK_ID}}        # read task details
+cleo start {{TASK_ID}}       # marks task active (tasks.start)
 
-# 2. Start task (marks task active)
-cleo start {{TASK_ID}}
+# MCP equivalent
+query  { domain: "tasks", operation: "show",  params: { taskId: "{{TASK_ID}}" } }
+mutate { domain: "tasks", operation: "start", params: { taskId: "{{TASK_ID}}" } }
 ```
 
 ### Phase 2: Execute (Skill-Specific)
 
-Follow the injected skill protocol for the current LOOM stage:
+Follow the injected skill protocol for the current RCASD-IVTR+C stage:
+
 - Research: Gather information, cite sources
 - Consensus: Validate claims, vote
 - Specification: Write RFC 2119 spec
 - Decomposition: Break down into tasks
 - Implementation: Write code
 - Validation: Verify compliance
-- Testing: Write BATS tests
+- Testing: Write tests
 - Contribution: Track attribution
 - Release: Version and changelog
 
 ### Phase 3: Output (Mandatory)
 
 ```bash
-# 1. Write output file
+# 1. Write output file (CLI creates it; use absolute path)
 # Location: {{OUTPUT_DIR}}/{{TASK_ID}}-<slug>.md
 
-# 2. Append manifest entry (single line JSON)
-echo '{"id":"{{TASK_ID}}-slug",...}' >> {{MANIFEST_PATH}}
+# 2. Append manifest entry via MCP (preferred)
+mutate {
+  domain: "pipeline",
+  operation: "manifest.append",
+  params: {
+    entry: {
+      id: "{{TASK_ID}}-<slug>",
+      task_id: "{{TASK_ID}}",
+      type: "research",          # research | implementation | specification | design | analysis | decision | note
+      content: "<summary text>",
+      source_file: "{{OUTPUT_DIR}}/{{TASK_ID}}-<slug>.md",
+      metadata_json: {
+        "title": "Human title",
+        "actionable": true,
+        "needs_followup": []
+      }
+    }
+  }
+}
 
 # 3. Complete task
-cleo complete {{TASK_ID}}
+cleo complete {{TASK_ID}}    # CLI
+# or: mutate { domain: "tasks", operation: "complete", params: { taskId: "{{TASK_ID}}" } }
 ```
 
 ### Phase 4: Return (Summary Only)
 
 Return ONLY one of these messages:
-- `"[Type] complete. See MANIFEST.jsonl for summary."`
-- `"[Type] partial. See MANIFEST.jsonl for details."`
-- `"[Type] blocked. See MANIFEST.jsonl for blocker details."`
+- `"[Type] complete. See pipeline manifest for summary."`
+- `"[Type] partial. See pipeline manifest for details."`
+- `"[Type] blocked. See pipeline manifest for blocker details."`
 
 **NEVER** return content in the response. All content goes to output files.
 
 ---
 
+## Agent Work Loop
+
+```
+tasks.current OR tasks.next  →  pick task
+tasks.show {taskId}          →  read requirements
+tasks.start {taskId}         →  begin work
+[do the work]
+pipeline.manifest.append     →  record output artifact
+tasks.complete {taskId}      →  mark done
+tasks.next                   →  continue or end session
+```
+
+CLI shorthand:
+
+```bash
+cleo current          # or: cleo next
+cleo show T123
+cleo start T123
+# ... do work ...
+cleo complete T123
+cleo next
+```
+
+---
+
+## Memory Protocol (3-Layer Retrieval)
+
+Use memory for anti-hallucination and cross-session continuity. Always search before fabricating.
+
+| Step | CLI | MCP Operation | ~Tokens | Purpose |
+|------|-----|---------------|---------|---------|
+| 1. Search | `cleo memory find "auth"` | `query memory.find { query: "..." }` | ~50/hit | Discover IDs |
+| 2. Timeline | `cleo memory timeline O-abc` | `query memory.timeline { anchor: "O-abc" }` | 200-500 | Context around anchor |
+| 3. Fetch | `cleo observe ...` | `query memory.fetch { ids: ["O-abc"] }` | ~500/entry | Full details |
+| Write | `cleo observe "text"` | `mutate memory.observe { text: "..." }` | — | Save raw observation |
+| Link | — | `mutate memory.link { taskId: "T123", entryId: "O-abc" }` | — | Associate to task |
+
+**Anti-pattern**: Never call `memory.fetch` without searching first. Never use the removed `memory.brain.*` prefix.
+
+Structured memory (tier 1, use after searching):
+
+```bash
+mutate memory.decision.store { decision: "...", rationale: "..." }
+mutate memory.pattern.store  { pattern: "...", context: "..." }
+mutate memory.learning.store { insight: "...", source: "..." }
+```
+
+---
+
 ## Token Reference
 
 ### Required Tokens
@@ -118,8 +236,7 @@ Return ONLY one of these messages:
 | Token | Default | Description |
 |-------|---------|-------------|
 | `{{EPIC_ID}}` | `""` | Parent epic ID |
-| `{{OUTPUT_DIR}}` | `claudedocs/agent-outputs` | Output directory |
-| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` | Manifest location |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` | Output directory |
 
 ---
 
@@ -129,21 +246,59 @@ Return ONLY one of these messages:
 
 | Status | Condition | Action |
 |--------|-----------|--------|
-| `complete` | All objectives achieved | Write full output |
-| `partial` | Some objectives achieved | Write partial, populate `needs_followup` |
-| `blocked` | Cannot proceed | Document blocker, do NOT complete task |
+| `complete` | All objectives achieved | Write full output, complete task |
+| `partial` | Some objectives achieved | Write partial output, populate `needs_followup` in manifest |
+| `blocked` | Cannot proceed | Document blocker in manifest, do NOT complete task |
 
-### Retryable Errors
+### Retryable Exit Codes
 
 Exit codes 7, 20, 21, 22, 60-63 support retry with exponential backoff.
 
+### Operation Error Reference
+
+| Error Code | Meaning | Action |
+|------------|---------|--------|
+| `E_INVALID_OPERATION` | Operation name is not in registry (often a deprecated alias) | Check canonical name in VERB-STANDARDS.md |
+| `E_INVALID_INPUT` | Missing required param | Add the required param |
+| `E_NOT_FOUND` | Entity does not exist | Verify ID; use `tasks.find` to discover |
+
+---
+
+## Escalation
+
+For deeper guidance beyond tier 0:
+
+```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 } }
+```
+
+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
+```
+
 ---
 
 ## Anti-Patterns
 
 | Pattern | Problem | Solution |
 |---------|---------|----------|
-| Returning content | Bloats orchestrator context | Write to file, return summary |
-| Pretty-printed JSON | Multiple lines in manifest | Single-line JSON only |
-| Skipping start | Protocol violation | Always `cleo start` first |
-| Loading skills via `@` | Cannot resolve | Skills injected by orchestrator |
+| Returning content in response | Bloats orchestrator context | Write to file, return one-line summary |
+| Writing pretty-printed JSON to manifest | Multiple lines break JSONL parsers | Use `pipeline.manifest.append` MCP op |
+| Skipping `tasks.start` | Protocol violation | Always start before working |
+| Using `memory.brain.*` prefix | Removed in ADR-021 — returns `E_INVALID_OPERATION` | Use `memory.find`, `memory.observe`, etc. |
+| 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 |
+| 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.3.45",
+  "version": "2026.3.46",
   "description": "CLEO agent protocols and templates",
   "type": "module",
   "license": "MIT",