@cleocode/cleo 2026.2.5

package/templates/ci/gitlab-ci/release.yml

@@ -0,0 +1,61 @@
+# GitLab CI Release Pipeline
+# Auto-generated by: cleo release init-ci
+# Platform: GitLab CI
+# Artifact Type: {{ARTIFACT_TYPE}}
+# Version: {{VERSION}}
+
+stages:
+  - validate
+  - build
+  - publish
+
+variables:
+  ARTIFACT_TYPE: "{{ARTIFACT_TYPE}}"
+  VERSION: "{{VERSION}}"
+
+.base:
+  image: ubuntu:latest
+  before_script:
+    - echo "Setting up environment..."
+    # Environment setup goes here
+
+validate:
+  extends: .base
+  stage: validate
+  script:
+    - echo "Running validation gates..."
+{{GATES}}
+  only:
+    - tags
+    - /^v[0-9]+\.[0-9]+\.[0-9]+$/
+
+build:
+  extends: .base
+  stage: build
+  script:
+    - echo "Building artifacts..."
+    # Build commands go here
+  artifacts:
+    paths:
+      - dist/
+      - "*.tar.gz"
+    expire_in: 1 week
+  only:
+    - tags
+
+publish:
+  extends: .base
+  stage: publish
+  script:
+    - echo "Publishing artifacts..."
+    # Publish commands go here
+  environment:
+    name: production
+  dependencies:
+    - build
+  only:
+    - tags
+  # Secrets configured in GitLab CI/CD variables:
+  # - NPM_TOKEN
+  # - PYPI_TOKEN
+  # etc.

package/templates/cleo-gitignore

@@ -0,0 +1,62 @@
+# CLEO Project Data - Selective Git Tracking
+#
+# Strategy: Track core task/config files, ignore transient/generated data.
+#
+# TRACKED (not listed here, so git picks them up):
+#   todo.json, todo-archive.json, config.json, sessions.json,
+#   project-context.json, todo-log.jsonl, .sequence,
+#   templates/, schemas/
+#
+# IGNORED (listed below):
+
+# Lock and temp files
+*.lock
+*.tmp
+
+# Operational backups (runtime safety nets, not source)
+.backups/
+backups/
+
+# Metrics and telemetry exports
+metrics/
+
+# Audit logs (high-volume, session-specific)
+audit-log-*.json
+
+# Context state (transient session data)
+.context-state.json
+.context-state-session_*.json
+context-states/
+
+# SQLite WAL/journal files (transient database state)
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Research artifacts (agent working data)
+research/
+
+# RCSD pipeline state (generated per-epic)
+rcsd/
+
+# Session working files
+.current-session
+.git-checkpoint-state
+
+# Backup metadata
+backup-metadata.json
+
+# Corrupted/backup copies of data files
+*.corrupted
+*.bak
+*.bak*
+*.backup-*
+
+# Agent outputs (generated by LLM agents, not source)
+agent-outputs/
+
+# Cache directories
+.cache/
+
+# Note: tasks.db is intentionally NOT ignored.
+# CLEO tracks the SQLite database in git for data safety.

package/templates/config.template.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "../schemas/config.schema.json",
+  "version": "{{SCHEMA_VERSION_CONFIG}}",
+  "_meta": {
+    "schemaVersion": "{{SCHEMA_VERSION_CONFIG}}",
+    "createdAt": "{{TIMESTAMP}}",
+    "updatedAt": "{{TIMESTAMP}}"
+  },
+
+  "archive": {
+    "enabled": true,
+    "daysUntilArchive": 7,
+    "maxCompletedTasks": 15,
+    "preserveRecentCount": 3,
+    "archiveOnSessionEnd": true,
+    "autoArchiveOnComplete": false
+  },
+
+  "logging": {
+    "enabled": true,
+    "retentionDays": 30,
+    "level": "standard",
+    "logSessionEvents": true
+  },
+
+  "validation": {
+    "strictMode": false,
+    "checksumEnabled": true,
+    "enforceAcceptance": true,
+    "requireDescription": false,
+    "maxActiveTasks": 1,
+    "validateDependencies": true,
+    "detectCircularDeps": true
+  },
+
+  "defaults": {
+    "priority": "medium",
+    "phase": "core",
+    "labels": []
+  },
+
+  "session": {
+    "requireSession": true,
+    "requireSessionNote": true,
+    "requireNotesOnComplete": true,
+    "warnOnNoFocus": true,
+    "allowNestedSessions": true,
+    "allowParallelAgents": true,
+    "autoStartSession": true,
+    "autoDiscoveryOnStart": true,
+    "sessionTimeoutHours": 72
+  },
+
+  "multiSession": {
+    "enabled": true,
+    "maxConcurrentSessions": 5,
+    "maxActiveTasksPerScope": 1,
+    "scopeValidation": "strict",
+    "allowNestedScopes": true,
+    "allowScopeOverlap": false
+  },
+
+  "release": {
+    "gates": [],
+    "changelog": {
+      "enabled": true,
+      "autoGenerate": false,
+      "source": "CHANGELOG.md",
+      "outputs": []
+    }
+  },
+
+  "display": {
+    "showArchiveCount": true,
+    "showLogSummary": true,
+    "warnStaleDays": 30
+  },
+
+  "output": {
+    "defaultFormat": "text",
+    "showColor": true,
+    "showUnicode": true,
+    "showProgressBars": true,
+    "csvDelimiter": ",",
+    "dateFormat": "iso8601",
+    "showCompactTitles": false,
+    "maxTitleLength": 80
+  },
+
+  "cli": {
+    "aliases": {
+      "ls": "list",
+      "done": "complete",
+      "new": "add",
+      "edit": "update",
+      "rm": "archive",
+      "check": "validate"
+    },
+    "plugins": {
+      "enabled": true,
+      "directories": ["~/.cleo/plugins", "./.cleo/plugins"],
+      "autoDiscover": true
+    },
+    "debug": {
+      "enabled": true,
+      "validateMappings": true,
+      "checksumVerify": true,
+      "showTimings": false
+    }
+  },
+
+  "backup": {
+    "enabled": true,
+    "directory": ".cleo/backups",
+    "maxSnapshots": 10,
+    "maxSafetyBackups": 5,
+    "maxIncremental": 10,
+    "maxArchiveBackups": 3,
+    "safetyRetentionDays": 7
+  },
+
+  "cancellation": {
+    "cascadeConfirmThreshold": 10,
+    "requireReason": true,
+    "daysUntilArchive": 3,
+    "allowCascade": true,
+    "defaultChildStrategy": "block"
+  },
+
+  "contextAlerts": {
+    "enabled": true,
+    "minThreshold": "warning",
+    "triggerCommands": ["complete", "focus", "add", "session"],
+    "suppressDuration": 0
+  },
+
+  "orchestrator": {
+    "contextThresholds": {
+      "warning": 70,
+      "critical": 80
+    },
+    "autoStopOnCritical": true,
+    "hitlSummaryOnPause": true
+  },
+
+  "agentOutputs": {
+    "directory": ".cleo/agent-outputs",
+    "manifestFile": "MANIFEST.jsonl",
+    "archiveDir": "archive",
+    "archiveDays": 30
+  },
+
+  "retention": {
+    "maxArchivedSessions": 100,
+    "autoArchiveEndedAfterDays": 30,
+    "autoDeleteArchivedAfterDays": 90,
+    "contextStateRetentionDays": 7,
+    "cleanupOnSessionEnd": true,
+    "dryRunByDefault": true,
+    "maxSessionsInMemory": 100,
+    "autoEndActiveAfterDays": 7
+  },
+
+  "project": {
+    "status": {
+      "health": "unknown",
+      "lastCheck": null,
+      "schemaVersions": {
+        "todo": "{{SCHEMA_VERSION_TODO}}",
+        "config": "{{SCHEMA_VERSION_CONFIG}}",
+        "archive": "{{SCHEMA_VERSION_ARCHIVE}}",
+        "log": "{{SCHEMA_VERSION_LOG}}"
+      },
+      "validation": {
+        "lastValidated": null,
+        "passed": false,
+        "errors": [],
+        "warnings": []
+      },
+      "injection": {
+        "CLAUDE.md": "not_found",
+        "AGENTS.md": "not_found",
+        "GEMINI.md": "not_found"
+      }
+    }
+  }
+}

package/templates/global-config.template.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "./schemas/global-config.schema.json",
+  "version": "{{SCHEMA_VERSION_GLOBAL_CONFIG}}",
+  "output": {
+    "defaultFormat": "text",
+    "showColor": true,
+    "showUnicode": true,
+    "showProgressBars": true,
+    "dateFormat": "iso8601",
+    "showCompactTitles": false,
+    "maxTitleLength": 80
+  },
+  "display": {
+    "showArchiveCount": true,
+    "showLogSummary": true,
+    "warnStaleDays": 30
+  },
+  "cli": {
+    "aliases": {
+      "ls": "list",
+      "done": "complete",
+      "new": "add",
+      "edit": "update",
+      "rm": "archive",
+      "check": "validate",
+      "tags": "labels",
+      "overview": "dash"
+    },
+    "plugins": {
+      "enabled": true,
+      "directories": [
+        "~/.cleo/plugins",
+        "./.cleo/plugins"
+      ],
+      "autoDiscover": true
+    },
+    "debug": {
+      "enabled": false,
+      "validateMappings": true,
+      "checksumVerify": true,
+      "showTimings": false
+    }
+  },
+  "defaults": {
+    "priority": "medium",
+    "labels": []
+  },
+  "multiSession": {
+    "enabled": true,
+    "maxConcurrentSessions": 5,
+    "maxActiveTasksPerScope": 1,
+    "scopeValidation": "strict",
+    "allowNestedScopes": true,
+    "allowScopeOverlap": false
+  }
+}

package/templates/hooks/precompact-safestop.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# CLEO PreCompact Hook - Emergency Safestop Fallback
+# Triggers when Claude Code auto-compact fires (95% context usage)
+#
+# INSTALLATION:
+#   Copy to ~/.claude/hooks/ or configure in ~/.claude/settings.json:
+#   {
+#     "hooks": {
+#       "PreCompact": [{
+#         "type": "command",
+#         "command": "~/.cleo/hooks/precompact-safestop.sh",
+#         "timeout": 30
+#       }]
+#     }
+#   }
+#
+# This hook provides emergency fallback when an agent doesn't self-stop
+# at the critical (90%) threshold. At 95%, Claude Code triggers PreCompact,
+# and this hook ensures CLEO session state is properly saved.
+
+set -euo pipefail
+
+# Find CLEO project directory
+find_cleo_dir() {
+    local dir="$PWD"
+    while [[ "$dir" != "/" ]]; do
+        if [[ -d "$dir/.cleo" ]]; then
+            echo "$dir/.cleo"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    echo ""
+}
+
+CLEO_DIR="${CLEO_PROJECT_DIR:-$(find_cleo_dir)}"
+SESSION_FILE="${CLEO_DIR:-.cleo}/.current-session"
+LOG_FILE="${CLEO_DIR:-.cleo}/safestop.log"
+
+log_message() {
+    local timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    echo "[$timestamp] $1" >> "$LOG_FILE" 2>/dev/null || true
+    echo "[CLEO] $1" >&2
+}
+
+# Check if CLEO session is active
+if [[ -n "$CLEO_DIR" && -f "$SESSION_FILE" ]]; then
+    SESSION_ID=$(cat "$SESSION_FILE" 2>/dev/null || echo "")
+
+    if [[ -n "$SESSION_ID" ]]; then
+        log_message "PreCompact triggered - initiating emergency safestop"
+
+        # Find cleo command
+        CLEO_CMD="${CLEO_HOME:-$HOME/.cleo}/bin/cleo"
+        if [[ ! -x "$CLEO_CMD" ]]; then
+            CLEO_CMD=$(which cleo 2>/dev/null || echo "")
+        fi
+
+        if [[ -n "$CLEO_CMD" && -x "$CLEO_CMD" ]]; then
+            # Run safestop with emergency flag
+            HANDOFF_FILE="${CLEO_DIR}/handoff-emergency-$(date +%s).json"
+
+            "$CLEO_CMD" safestop \
+                --reason "precompact-emergency" \
+                --commit \
+                --handoff "$HANDOFF_FILE" \
+                2>&1 | tee -a "$LOG_FILE" || true
+
+            log_message "Emergency safestop completed. Handoff: $HANDOFF_FILE"
+
+            # Signal to Claude that safestop was performed
+            echo ""
+            echo "⚠️ CLEO Emergency Safestop executed at PreCompact (95% context)."
+            echo "Session ended. Handoff saved to: $HANDOFF_FILE"
+            echo "Resume with: cleo session resume $SESSION_ID"
+        else
+            log_message "ERROR: cleo command not found, cannot perform safestop"
+            echo "⚠️ PreCompact triggered but cleo command not found" >&2
+        fi
+    else
+        log_message "PreCompact triggered but session file empty"
+    fi
+else
+    # No active CLEO session - just log
+    if [[ -n "$CLEO_DIR" ]]; then
+        log_message "PreCompact triggered but no active CLEO session"
+    fi
+    # Silent exit - don't interfere with normal Claude Code operation
+fi

package/templates/log.template.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../schemas/log.schema.json",
+  "version": "{{SCHEMA_VERSION_LOG}}",
+  "project": "{{PROJECT_NAME}}",
+  "_meta": {
+    "schemaVersion": "{{SCHEMA_VERSION_LOG}}",
+    "totalEntries": 0,
+    "firstEntry": null,
+    "lastEntry": null,
+    "entriesPruned": 0
+  },
+  "entries": []
+}

package/templates/migrations.template.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "../schemas/migrations.schema.json",
+  "_meta": {
+    "schemaVersion": "{{SCHEMA_VERSION_MIGRATIONS}}",
+    "lastChecked": null
+  },
+  "appliedMigrations": []
+}

package/templates/orchestrator-protocol/PLACEHOLDER-REGISTRY.md

@@ -0,0 +1,150 @@
+# Template Placeholder Registry
+
+**Version**: 1.0.0
+**Status**: Active
+**Updated**: 2026-01-19
+
+Canonical registry for all template placeholders used in orchestrator protocol templates.
+
+---
+
+## Universal Placeholders (all templates)
+
+| Placeholder | Type | Example | Description |
+|-------------|------|---------|-------------|
+| `{TASK_ID}` | string | T1234 | CLEO task ID |
+| `{DATE}` | string | 2026-01-19 | ISO date (YYYY-MM-DD) |
+| `{OUTPUT_DIR}` | path | .cleo/agent-outputs | Output directory path |
+| `{SESSION_ID}` | string | session_20260119_143500_abc123 | Current CLEO session ID |
+| `{EPIC_ID}` | string | T1000 | Parent epic ID |
+| `{EPIC_TITLE}` | string | Authentication System | Parent epic title |
+
+---
+
+## Context-Specific Placeholders
+
+### RESEARCH-AGENT Template
+
+| Placeholder | Type | Example | Description |
+|-------------|------|---------|-------------|
+| `{TOPIC_SLUG}` | string | auth-token-rotation | Slugified topic name (lowercase, hyphenated) |
+| `{RESEARCH_ID}` | string | auth-token-2026-01-19 | Research entry ID for manifest |
+| `{TOPIC_TITLE}` | string | Authentication Token Rotation | Human-readable topic name |
+
+### EPIC-ARCHITECT Template
+
+| Placeholder | Type | Example | Description |
+|-------------|------|---------|-------------|
+| `{FEATURE_SLUG}` | string | user-authentication | Slugified feature name (lowercase, hyphenated) |
+| `{FEATURE_NAME}` | string | User Authentication | Human-readable feature name |
+| `{FEATURE_DESCRIPTION}` | string | Implement JWT-based authentication... | Full description from epic |
+
+### TASK-EXECUTOR Template
+
+| Placeholder | Type | Example | Description |
+|-------------|------|---------|-------------|
+| `{TASK_TITLE}` | string | Implement login endpoint | Task title from CLEO |
+| `{TASK_DESCRIPTION}` | string | Create POST /api/login... | Task description from CLEO |
+| `{DEPENDS_LIST}` | string | T1001, T1002 | Comma-separated dependency IDs |
+
+### VALIDATOR Template
+
+| Placeholder | Type | Example | Description |
+|-------------|------|---------|-------------|
+| `{TEST_SCOPE}` | string | unit\|integration\|e2e | Test scope to execute |
+| `{TARGET_PATH}` | path | src/auth/ | Path to validate |
+
+---
+
+## Manifest Entry Placeholders
+
+Used when constructing MANIFEST.jsonl entries:
+
+| Placeholder | Type | Example | Description |
+|-------------|------|---------|-------------|
+| `{MANIFEST_ID}` | string | topic-2026-01-19 | Unique manifest entry ID |
+| `{MANIFEST_FILE}` | string | 2026-01-19_topic-slug.md | Output filename |
+| `{MANIFEST_TITLE}` | string | Research on Topic | Entry title |
+| `{MANIFEST_STATUS}` | enum | complete\|partial\|blocked | Entry status |
+| `{MANIFEST_TOPICS}` | array | ["auth", "security"] | Topic tags |
+| `{MANIFEST_FINDINGS}` | array | ["Finding 1", "Finding 2"] | Key findings (3-7 items) |
+| `{LINKED_TASKS}` | array | ["T1234", "T1235"] | Related CLEO task IDs |
+| `{NEEDS_FOLLOWUP}` | array | ["T1236"] | Tasks requiring follow-up |
+
+---
+
+## Placeholder Resolution
+
+### CLI Auto-Resolution
+
+The `cleo orchestrator spawn` command auto-resolves placeholders:
+
+```bash
+cleo orchestrator spawn T1586 --template RESEARCH-AGENT
+```
+
+Resolves `{TASK_ID}` to `T1586`, `{DATE}` to current date, etc.
+
+### Manual Resolution
+
+When building prompts manually:
+
+```bash
+# Get task details
+cleo show T1586 --format json
+
+# Get session ID
+cleo session status --format json | jq -r '.sessionId'
+
+# Get epic context
+cleo show $(cleo show T1586 --format json | jq -r '.parentId') --format json
+```
+
+---
+
+## Placeholder Conventions
+
+### Naming Rules
+
+- **ALL_CAPS** with underscores for multi-word names
+- Enclosed in **curly braces** `{PLACEHOLDER}`
+- Descriptive names that indicate content type
+
+### Type Constraints
+
+| Type | Format | Validation |
+|------|--------|------------|
+| string | Any UTF-8 text | Non-empty |
+| date | YYYY-MM-DD | ISO 8601 |
+| path | Unix path | Valid path characters |
+| enum | Pipe-separated | Exact match required |
+| array | JSON array | Valid JSON |
+
+### Default Values
+
+| Placeholder | Default |
+|-------------|---------|
+| `{DATE}` | Current date |
+| `{OUTPUT_DIR}` | `.cleo/agent-outputs` |
+| `{MANIFEST_STATUS}` | `complete` |
+| `{NEEDS_FOLLOWUP}` | `[]` (empty array) |
+
+---
+
+## Adding New Placeholders
+
+When creating new templates:
+
+1. Check this registry for existing placeholders
+2. Reuse existing placeholders when semantically equivalent
+3. Add new placeholders to appropriate section above
+4. Document type, example, and description
+5. Update `cleo orchestrator spawn` if auto-resolution needed
+
+---
+
+## Revision History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-19 | Initial registry |