@cleocode/cleo 2026.3.28 → 2026.3.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/cleo",
-  "version": "2026.3.28",
+  "version": "2026.3.30",
   "description": "CLEO V2 - TypeScript task management CLI for AI coding agents",
   "mcpName": "io.github.kryptobaseddev/cleo-mcp-server",
   "type": "module",
@@ -65,6 +65,11 @@
   ],
   "author": "CLEO Development Team",
   "license": "MIT",
+  "workspaces": [
+    "packages/contracts",
+    "packages/shared",
+    "packages/adapters/*"
+  ],
   "files": [
     "dist",
     "migrations",
@@ -77,12 +82,11 @@
     "packages/ct-skills/skills",
     "completions",
     "server.json",
-    "bin",
-    ".claude-plugin"
+    "bin"
   ],
   "dependencies": {
     "@cleocode/caamp": "^1.7.0",
-    "@cleocode/lafs-protocol": "^1.6.0",
+    "@cleocode/lafs-protocol": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",

package/packages/ct-skills/skills/ct-memory/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ct-memory
+version: 1.0.0
+description: Brain memory protocol with progressive disclosure for anti-hallucination and context recall
+triggers:
+  - memory
+  - brain
+  - recall
+  - remember
+  - anti-hallucination
+---
+
+# ct-memory -- Brain Memory Protocol
+
+## Purpose
+
+Ensures LLM agents never start conversations with amnesia. Provides structured memory access through CLEO's brain system using progressive disclosure.
+
+## Tier 0: Session Start (ALWAYS run on first interaction)
+
+1. The memory bridge (.cleo/memory-bridge.md) is already loaded via CLEO-INJECTION.md @-reference
+2. If the bridge content feels stale (>2 hours old), refresh:
+   - `query memory brain.search {query: "session task decision", limit: 10}`
+3. Check for anti-patterns to avoid:
+   - `query memory brain.search {query: "mistake error avoid warning", limit: 5}`
+4. If results are relevant, fetch details:
+   - `query memory brain.fetch {ids: ["O-xxx", "O-yyy"]}`
+
+## Tier 1: During Work (run when topic-relevant)
+
+### Before Making Decisions
+
+- `query memory brain.search {query: "decision ADR architecture", limit: 5}`
+- Check if a similar decision was already made
+
+### Before Repeating Work
+
+- `query memory brain.search {query: "{current-topic}", limit: 10}`
+- Avoid re-doing work that's already been completed
+
+### After Completing Significant Work
+
+- `mutate memory brain.observe {text: "Completed X using approach Y. Key learning: Z", title: "Work completion"}`
+
+### Anti-Hallucination Protocol
+
+Before stating facts about the codebase or project:
+
+1. Search brain: `query memory brain.search {query: "{claim-topic}", limit: 5}`
+2. If results exist, verify your claim matches stored knowledge
+3. If no results, state your uncertainty clearly
+
+## Tier 2: Deep Recall (run when specifically needed)
+
+### Full Timeline
+
+- `query memory brain.timeline {anchor: "O-xxx", depthBefore: 5, depthAfter: 5}`
+- Understand chronological context around a specific observation
+
+### Cross-Project Knowledge (via NEXUS)
+
+- `query nexus search {query: "pattern", scope: "global"}`
+- Search across all CLEO-managed projects
+
+## MCP Resources (Alternative to search)
+
+For providers that support MCP resources:
+
+- `ReadResource("cleo://memory/recent")` -- last 15 observations
+- `ReadResource("cleo://memory/learnings")` -- active learnings with confidence
+- `ReadResource("cleo://memory/patterns")` -- patterns to follow/avoid
+- `ReadResource("cleo://memory/handoff")` -- last session handoff
+
+## Token Budget Guidelines
+
+| Operation | ~Tokens | When |
+|-----------|---------|------|
+| memory-bridge.md (auto-loaded) | 200-400 | Always (free) |
+| brain.search | 50/hit | Discovery |
+| brain.fetch | 500/entry | Details |
+| brain.timeline | 200-500 | Context |
+| MCP resources | 200-500 | On-demand |
+
+Stay within LAFS MVI budget: start minimal, escalate only when needed.

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.kryptobaseddev/cleo-mcp-server",
   "title": "CLEO MCP Server",
   "description": "Task management for AI coding agents — CQRS 2-gateway pattern, 200 ops across 10 domains",
-  "version": "2026.3.27",
+  "version": "2026.3.30",
   "websiteUrl": "https://github.com/kryptobaseddev/cleo",
   "repository": {
     "url": "https://github.com/kryptobaseddev/cleo.git",

package/templates/CLEO-INJECTION.md

@@ -96,6 +96,17 @@ mutate memory brain.observe {text: "Found auth uses JWT", title: "Auth discovery
 - Fetching all entries without searching first (expensive)
 - Skipping brain.search and going straight to brain.fetch
 
+## Memory Bridge
+
+CLEO auto-generates `.cleo/memory-bridge.md` from brain.db content. This file is `@`-referenced
+in AGENTS.md so providers automatically load project memory context at session start.
+
+**Contents**: Last session handoff, key learnings, active patterns, recent decisions, recent observations.
+
+**Refreshes on**: `session.end`, `tasks.complete`, `memory.observe` (decisions), `cleo refresh-memory`.
+
+If the file is missing, run `cleo init` or `cleo refresh-memory` to regenerate it.
+
 ## Escalation
 
 For deeper guidance beyond this minimal protocol:

package/.claude-plugin/CLAUDE.md

@@ -1,25 +0,0 @@
-<cleo-brain-context>
-# CLEO Brain — Recent Memory
-
-- [D] 2026-03-02 Five-Wave Implementation Plan Created for Claude-Mem Replacement
-- [D] 2026-02-25 4-Feature Architecture Plan for Session Briefing, Bug Tracking, Planning, and Ha
-- [O] 2026-02-25 Session Engine Core Module Delegation Confirmed
-- [O] 2026-02-25 Session Domain Handler Engine Dependencies
-- [O] 2026-02-27 Created Agent Team "session-cleanup" for Waves 3-5
-- [O] 2026-03-02 Mutate Gateway Architecture for State-Modifying Operations
-- [O] 2026-02-25 4-Feature Architecture Plan for Session Briefing, Bug Tracking, Planning, and Ha
-- [O] 2026-03-01 Examined Bootstrap Brain State Loading with Speed Tiers
-- [O] 2026-02-27 ADR-009 Section 5 Documents BRAIN Capabilities by Domain
-- [O] 2026-02-28 Created Task for Phase 4 Skill Logic and Subagent Tier Integration
-- [O] 2026-02-28 Handoff and Debrief Implementation Architecture Revealed
-- [O] 2026-03-02 Five-Wave Implementation Plan Created for Claude-Mem Replacement
-- [O] 2026-02-28 Memory-Related Tasks Reveal Pending Consolidation Work
-- [O] 2026-02-28 Session CLI Commands Expose Start, Stop, and Handoff Operations
-- [O] 2026-02-27 claude-mem Observation Taxonomy and Mode-Based Configuration
-- [O] 2026-02-28 Assigned Phase 4 Task to Third Parallel Implementation Agent
-- [O] 2026-02-25 Wave 2-4 Engine Refactoring Tasks Reveal Increasing Complexity
-- [O] 2026-03-01 Epic B Phase 1 Specifications: Complete brain.db Schema with 6 Tables and FTS5 S
-- [O] 2026-03-02 CLEO-INJECTION v2.1.0 Minimal Template - 110 Lines Exceeds Test Constraint
-- [O] 2026-02-27 Validation Index Barrel Exports - Re-export Layer
-- [O] 2026-02-27 Drizzle Migration History - Seven Existing Migrations
-</cleo-brain-context>

package/.claude-plugin/README.md

@@ -1,315 +0,0 @@
-# CLEO Claude Code Plugin
-
-**Version**: 0.70.1
-**Status**: Optional Enhancement
-**Architecture**: Hybrid (Injection + Plugin)
-
----
-
-## Overview
-
-CLEO uses a **hybrid approach** for multi-agent integration:
-
-| Component | Purpose | Support |
-|-----------|---------|---------|
-| **Injection System** | Multi-agent task management | 16+ agents (Claude, Cursor, Windsurf, Gemini, etc.) |
-| **Plugin System** | Claude Code hooks | Claude Code only |
-
-**Most users need injection only.** The plugin adds optional Claude Code-specific hooks for advanced users.
-
----
-
-## Architecture
-
-### Primary: Injection System
-
-The injection system provides CLEO task management to **all LLM agents** via registry-based auto-discovery:
-
-**Location**: `schemas/agent-registry.json`
-**Agents Supported**: claude-code, cursor, windsurf, gemini, copilot, roo-code, cline, continue, aider, bolt, replit, lovable, v0, devin, and more.
-
-**How it works**:
-1. `cleo init` discovers installed agents automatically
-2. Injects task management instructions to agent config files
-3. Agents reference external docs via `@~/.cleo/docs/TODO_Task_Management.md`
-4. Works with any agent that supports config file injection
-
-**Supported files**: `CLAUDE.md`, `CURSOR.md`, `.windsurfrules`, `GEMINI.md`, etc.
-
-### Optional: Plugin System
-
-The plugin adds **Claude Code-specific hooks** for terminal integration:
-
-**Location**: `.claude-plugin/`
-**Capabilities**: SessionStart hook for automatic session binding
-**Limitation**: Claude Code only (not portable to other agents)
-
-**What the plugin provides**:
-- **SessionStart Hook**: Auto-binds CLEO session to Claude terminal via `CLEO_SESSION` env var
-- **TTY Integration**: Seamless session continuity across Claude Code restarts
-
-**What it does NOT provide**:
-- ❌ Slash commands (future enhancement)
-- ❌ Custom agents (future enhancement)
-- ❌ Portability to other agents (injection system handles this)
-
----
-
-## When to Use Plugin
-
-### Use Injection Only (Default) ✓
-
-**Recommended for**:
-- Multi-agent workflows (Cursor, Windsurf, Gemini, etc.)
-- Standard Claude Code usage
-- Users who don't need automatic session binding
-
-**What you get**:
-- Full CLEO task management (`cleo` CLI)
-- Multi-session support
-- Orchestration and subagents
-- Works in all supported agents
-
-### Add Plugin (Advanced) ⚡
-
-**Recommended for**:
-- Heavy Claude Code users
-- Multi-session power users
-- Users who want automatic session binding
-
-**What you get**:
-- Everything from injection system
-- **PLUS**: SessionStart hook for automatic `CLEO_SESSION` binding
-- **PLUS**: TTY-aware session continuity
-
----
-
-## Installation
-
-### Default Installation (Injection Only)
-
-```bash
-# Install CLEO with multi-agent support
-curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash
-
-# Setup agent configurations (auto-discovers installed agents)
-cleo init
-
-# Verify injection
-cleo doctor
-```
-
-**Result**: CLEO works in all supported agents via injection system.
-
-### Advanced Installation (Injection + Plugin)
-
-```bash
-# Install CLEO with Claude Code plugin
-curl -fsSL https://github.com/kryptobaseddev/cleo/releases/latest/download/install.sh | bash -s -- --with-plugin
-
-# Setup agent configurations
-cleo init
-
-# Verify both injection and plugin
-cleo doctor
-```
-
-**Result**: CLEO works in all agents + Claude Code gets SessionStart hook.
-
----
-
-## Plugin Structure
-
-```
-.claude-plugin/
-├── plugin.json           # Plugin manifest
-├── hooks/
-│   ├── hooks.json       # Hook configuration
-│   └── scripts/
-│       └── session-start.sh   # SessionStart hook implementation
-└── README.md            # This file
-```
-
-### plugin.json
-
-Plugin manifest defining capabilities:
-
-```json
-{
-  "name": "cleo",
-  "version": "0.70.1",
-  "capabilities": {
-    "task_management": true,
-    "multi_session": true,
-    "orchestration": true
-  },
-  "hooks": {
-    "enabled": true,
-    "directory": "hooks",
-    "manifest": "hooks/hooks.json"
-  }
-}
-```
-
-### hooks.json
-
-Hook configuration for SessionStart event:
-
-```json
-{
-  "SessionStart": [{
-    "matcher": "*",
-    "hooks": [{
-      "type": "command",
-      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
-      "timeout": 10
-    }]
-  }]
-}
-```
-
-### session-start.sh
-
-Auto-binds active CLEO session to Claude terminal:
-
-**What it does**:
-1. Checks for active CLEO session (`.cleo/.current-session`)
-2. Verifies session is active via `cleo session status`
-3. Exports `CLEO_SESSION` env var for terminal
-4. Creates `.cleo/.session-env` for manual sourcing (if needed)
-
-**Exit conditions** (silent):
-- CLEO not installed
-- No `.cleo` directory (not a CLEO project)
-- No active session
-- Session inactive/ended
-
----
-
-## Usage
-
-### With Injection Only
-
-Standard CLI workflow:
-
-```bash
-# Start session manually
-cleo session start --scope epic:T1074 --auto-focus
-
-# Use cleo commands with CLEO_SESSION env var
-export CLEO_SESSION="session_20260127_123456_abc123"
-cleo list --parent T1074
-cleo complete T1087
-
-# End session
-cleo session end --note "Completed plugin docs"
-```
-
-### With Plugin
-
-Plugin auto-binds session on Claude Code start:
-
-```bash
-# Start session (manually or via orchestrator)
-cleo session start --scope epic:T1074 --auto-focus
-
-# Claude Code starts → plugin auto-exports CLEO_SESSION
-# ✓ CLEO session bound: session_20260127_123456_abc123
-
-# Use cleo commands (no manual export needed)
-cleo list --parent T1074
-cleo complete T1087
-
-# End session
-cleo session end --note "Completed plugin docs"
-```
-
-**Key difference**: Plugin eliminates manual `export CLEO_SESSION=...` step.
-
----
-
-## Hybrid Benefits
-
-| Benefit | Injection | Plugin |
-|---------|-----------|--------|
-| Multi-agent support | ✓ | ❌ |
-| Claude Code support | ✓ | ✓ |
-| Task management | ✓ | ✓ |
-| Multi-session | ✓ | ✓ |
-| Auto session binding | ❌ | ✓ |
-| TTY continuity | ❌ | ✓ |
-
-**Philosophy**: Injection provides portability, plugin provides polish.
-
----
-
-## Decision Tree
-
-```
-Do you use Claude Code exclusively?
-├─ Yes
-│   └─ Do you want automatic session binding?
-│       ├─ Yes → Install with --with-plugin
-│       └─ No  → Install default (injection only)
-└─ No (multi-agent workflow)
-    └─ Install default (injection only)
-```
-
----
-
-## Troubleshooting
-
-### Plugin Not Working
-
-**Symptom**: SessionStart hook not firing
-
-**Check**:
-1. Plugin installed: `ls .claude-plugin/`
-2. Hooks enabled: `cat .claude-plugin/plugin.json | jq '.hooks.enabled'`
-3. CLEO session active: `cleo session status`
-4. Claude Code version: Plugin requires Claude Code 1.0.0+
-
-### Session Not Auto-Binding
-
-**Symptom**: `CLEO_SESSION` not set after Claude Code start
-
-**Check**:
-1. Active session exists: `cat .cleo/.current-session`
-2. Session is active: `cleo session status`
-3. Hook script executable: `ls -l .claude-plugin/hooks/scripts/session-start.sh`
-4. Manual test: `bash .claude-plugin/hooks/scripts/session-start.sh`
-
-### Injection vs Plugin Conflict
-
-**Symptom**: Duplicate task management instructions
-
-**Resolution**: No conflict. Injection and plugin are complementary:
-- Injection: Provides task management docs to agent
-- Plugin: Provides terminal integration hooks
-
-Both can coexist safely.
-
----
-
-## Future Enhancements
-
-**Planned plugin features** (not in v0.70.1):
-- Slash commands (`/cleo add "Task"`)
-- Custom agents (`ct-orchestrator`, `ct-epic-architect`)
-- Agent-to-agent communication (consensus protocol)
-- Git workflow integration
-
-**Current status**: Plugin provides SessionStart hook only. All other features use standard CLI.
-
----
-
-## References
-
-- **Injection System**: `schemas/agent-registry.json`
-- **Setup Guide**: `docs/guides/AGENT-REGISTRATION.md`
-- **Subagent Architecture**: `docs/architecture/CLEO-SUBAGENT.md`
-- **Protocol Stack**: `src/protocols/`
-
----
-
-**Key Insight**: CLEO uses injection for portability, plugin for Claude Code polish. Most users need injection only.

package/.claude-plugin/hooks/hooks.json

@@ -1,56 +0,0 @@
-{
-  "description": "CLEO task management and brain memory hooks",
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/brain-start.sh",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/brain-hook.sh session-init",
-            "timeout": 8
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/brain-hook.sh observation",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/brain-hook.sh summarize",
-            "timeout": 30
-          }
-        ]
-      }
-    ]
-  }
-}

package/.claude-plugin/hooks/scripts/brain-context.sh

@@ -1,35 +0,0 @@
-#!/usr/bin/env bash
-# UserPromptSubmit: inject recent CLEO brain observations as context
-# Claude Code reads stdout from this hook and includes it in the session context.
-# Must be fast (<3s) and always exit 0.
-
-CLEO_BIN="${HOME}/.cleo/bin/cleo"
-
-# Bail fast if cleo not available or no .cleo dir
-[[ ! -x "$CLEO_BIN" ]] && exit 0
-[[ ! -d ".cleo" ]] && exit 0
-
-# Query recent brain observations — compact format
-CONTEXT=$("$CLEO_BIN" memory find "session task decision pattern learning" --limit 15 --json 2>/dev/null | \
-  python3 -c "
-import json, sys
-try:
-    d = json.loads(sys.stdin.read())
-    hits = d.get('result', {}).get('results', [])
-    if not hits:
-        sys.exit(0)
-    lines = ['## CLEO Brain Context (recent memories)\n']
-    for h in hits:
-        t = h.get('type', 'observation')
-        icon = {'observation': 'O', 'decision': 'D', 'pattern': 'P', 'learning': 'L'}.get(t, 'O')
-        title = h.get('title', '')[:90]
-        date = h.get('date', '')[:10]
-        lines.append(f'- [{icon}] {date} {title}')
-    print('\n'.join(lines))
-    print()
-except Exception:
-    pass
-" 2>/dev/null || true)
-
-[[ -n "$CONTEXT" ]] && echo "$CONTEXT"
-exit 0

package/.claude-plugin/hooks/scripts/brain-hook.sh

@@ -1,17 +0,0 @@
-#!/usr/bin/env bash
-# Fire-and-forget: send hook event to brain worker
-# Always exits 0 — never blocks Claude Code
-EVENT="$1"
-WORKER_PORT=37778
-
-# Read stdin
-INPUT=$(cat 2>/dev/null || echo '{}')
-
-# Non-blocking curl to worker
-curl -sf --max-time 5 \
-  -X POST "http://127.0.0.1:${WORKER_PORT}/hook" \
-  -H "Content-Type: application/json" \
-  -d "{\"event\":\"${EVENT}\",\"data\":$(echo "$INPUT" | python3 -c 'import json,sys; print(json.dumps(json.load(sys.stdin)))' 2>/dev/null || echo '\"{}\"')}" \
-  >/dev/null 2>&1 || true
-
-exit 0

package/.claude-plugin/hooks/scripts/brain-start.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# SessionStart hook — starts the brain worker if not running
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-node "$SCRIPT_DIR/brain-worker.cjs" start 2>/dev/null &
-disown 2>/dev/null || true
-exit 0