@cleocode/core 2026.3.45 → 2026.3.47

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/issue-templates/bug_report.yml

@@ -0,0 +1,143 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in CLEO
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Bug Report
+
+        Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it.
+
+        **If you're using an AI agent** (Claude Code, Cursor, etc.) to file this issue, the agent should run the diagnostic commands below and paste the output directly.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: |
+        Describe the bug clearly. What did you expect to happen vs what actually happened?
+      placeholder: |
+        When I ran `cleo add "My task"`, I expected a new task to be created, but instead I got an error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: |
+        Provide the exact commands you ran, in order. Include the full command with all flags.
+      placeholder: |
+        1. `cleo init my-project`
+        2. `cleo session start --scope epic:T001 --auto-focus --name "test"`
+        3. `cleo add "Test task" --parent T001`
+        4. See error below
+    validations:
+      required: true
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Error output
+      description: |
+        Paste the full error output. If CLEO returned JSON, paste the complete JSON response.
+        Use `cleo <command> 2>&1` to capture both stdout and stderr.
+      render: shell
+      placeholder: |
+        $ cleo add "Test task" --parent T001
+        {
+          "success": false,
+          "error": {
+            "code": "E_PARENT_NOT_FOUND",
+            "message": "Parent task T001 does not exist",
+            "exit": 10
+          }
+        }
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen instead?
+      placeholder: |
+        I expected the task to be created as a child of T001.
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Environment diagnostics
+      description: |
+        Run this command and paste the output:
+        ```bash
+        echo "--- CLEO Diagnostics ---" && echo "CLEO version: $(cleo version 2>/dev/null || echo 'not installed')" && echo "Node version: $(node --version 2>/dev/null || echo 'not found')" && echo "Install location: $(which cleo 2>/dev/null || echo 'not found')" && echo "OS: $(uname -srm 2>/dev/null || echo 'unknown')" && echo "Shell: $SHELL" && echo "Initialized: $(test -f .cleo/tasks.db && echo 'yes' || echo 'no')"
+        ```
+      render: shell
+      placeholder: |
+        --- CLEO Diagnostics ---
+        CLEO version: 2026.3.15
+        Node version: v24.0.0
+        Install location: /usr/local/bin/cleo
+        OS: Linux 6.5.0-44-generic x86_64
+        Shell: /bin/bash
+        Initialized: yes
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation method
+      description: How did you install CLEO?
+      options:
+        - "npm install -g @cleocode/cleo"
+        - "npx @cleocode/cleo"
+        - "Built from source (cloned monorepo)"
+        - "Other (describe below)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: How much does this impact your workflow?
+      options:
+        - "Blocker - Cannot use CLEO at all"
+        - "Major - Core feature broken, no workaround"
+        - "Moderate - Feature broken but workaround exists"
+        - "Minor - Cosmetic or edge case"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: agent-usage
+    attributes:
+      label: Are you using an AI agent?
+      description: Are you (or your AI agent) filing this issue?
+      options:
+        - "Yes - AI agent filed this issue"
+        - "Yes - Human filing with AI agent assistance"
+        - "No - Filing manually"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: |
+        Any other details that might help. Examples:
+        - Contents of `.cleo/config.json` (if relevant)
+        - Output of `cleo doctor`
+        - Screenshots or screen recordings
+        - Related issues or PRs
+      placeholder: |
+        This started happening after I updated from 2026.2.x to 2026.3.x...
+    validations:
+      required: false

package/templates/issue-templates/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://github.com/cleocode/cleo/tree/main/docs
+    about: Read the CLEO documentation before opening an issue
+  - name: Discussions
+    url: https://github.com/cleocode/cleo/discussions
+    about: Ask questions and share ideas in GitHub Discussions

package/templates/issue-templates/feature_request.yml

@@ -0,0 +1,125 @@
+name: Feature Request
+description: Suggest a new feature or improvement for CLEO
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Feature Request
+
+        Help us improve CLEO! Describe what you'd like to see added or changed.
+
+        **If you're using an AI agent** to submit this, provide as much context as possible about the use case and workflow.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or use case
+      description: |
+        What problem does this feature solve? Describe the situation where you need this.
+        Focus on the *problem*, not the solution.
+      placeholder: |
+        When working on a large project with 50+ tasks, I need to filter tasks by multiple
+        labels at once, but `cleo list` only supports filtering by a single label...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: |
+        How do you think this should work? Include example commands, expected output, or behavior.
+      placeholder: |
+        Add multi-label filtering to `cleo list`:
+        ```bash
+        cleo list --labels "bug,priority-high"
+        cleo list --labels "bug" --labels "priority-high"  # AND logic
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        Have you tried any workarounds? Are there other approaches that could solve this?
+      placeholder: |
+        Currently I pipe through jq manually:
+        ```bash
+        cleo list --json | jq '.[] | select(.labels | contains(["bug", "priority-high"]))'
+        ```
+        This works but is cumbersome and not discoverable for new users.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Feature area
+      description: Which part of CLEO does this relate to?
+      options:
+        - "Task management (add, update, complete, list)"
+        - "Session management (start, end, resume, scope)"
+        - "Hierarchy (epics, subtasks, dependencies)"
+        - "Search and filtering (find, list filters)"
+        - "Output and formatting (JSON, human-readable)"
+        - "Validation and data integrity"
+        - "Installation and setup"
+        - "MCP server integration"
+        - "Documentation"
+        - "AI agent workflow (skills, orchestrator, protocols)"
+        - "@cleocode/core package API"
+        - "Provider adapters (Claude Code, Cursor, OpenCode)"
+        - "Other"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: How big is this change?
+      options:
+        - "Small - Single command or flag addition"
+        - "Medium - Multiple components, moderate complexity"
+        - "Large - Cross-cutting change, new subsystem"
+        - "Not sure"
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Your environment (optional)
+      description: |
+        If this feature depends on your environment, run this and paste the output:
+        ```bash
+        echo "CLEO: $(cleo version 2>/dev/null || echo 'not installed')" && echo "Node: $(node --version)" && echo "OS: $(uname -srm)" && echo "Shell: $SHELL"
+        ```
+      render: shell
+    validations:
+      required: false
+
+  - type: dropdown
+    id: agent-usage
+    attributes:
+      label: Are you using an AI agent?
+      description: Are you (or your AI agent) filing this request?
+      options:
+        - "Yes - AI agent filed this request"
+        - "Yes - Human filing with AI agent assistance"
+        - "No - Filing manually"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: |
+        Links, screenshots, references to other tools that do this well, or anything else.
+    validations:
+      required: false

package/templates/issue-templates/help_question.yml

@@ -0,0 +1,99 @@
+name: Help / Question
+description: Ask for help using CLEO or understanding a feature
+title: "[Question]: "
+labels: ["question", "help"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Help / Question
+
+        Need help with CLEO? Ask here. No question is too basic.
+
+        **Before asking**, please check:
+        - [`cleo help`](https://github.com/cleocode/cleo) - Built-in help
+        - [Documentation](https://github.com/cleocode/cleo/tree/main/docs) - User guides
+        - [Existing issues](https://github.com/cleocode/cleo/issues?q=is%3Aissue+label%3Aquestion) - Someone may have asked already
+
+  - type: textarea
+    id: question
+    attributes:
+      label: What do you need help with?
+      description: |
+        Describe what you're trying to do and where you're stuck.
+      placeholder: |
+        I'm trying to set up CLEO for a new project, but I'm not sure how sessions
+        and scopes work together. When I run `cleo session start`, it asks for a scope...
+    validations:
+      required: true
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What have you tried?
+      description: |
+        What commands have you run or documentation have you read?
+      placeholder: |
+        I've tried:
+        1. `cleo help session`
+        2. Reading docs/guides/
+        3. Running `cleo session start --name "test"` but got an error about scope
+    validations:
+      required: true
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Relevant output (if any)
+      description: |
+        If you're getting errors, paste the output here.
+      render: shell
+    validations:
+      required: false
+
+  - type: dropdown
+    id: topic
+    attributes:
+      label: Topic area
+      description: What area is your question about?
+      options:
+        - "Installation and setup"
+        - "Getting started / first use"
+        - "Task management (add, update, complete)"
+        - "Sessions and scopes"
+        - "Epics, subtasks, hierarchy"
+        - "Dependencies and blocking"
+        - "Search and filtering"
+        - "MCP server / AI agent integration"
+        - "Configuration"
+        - "Migration / upgrading"
+        - "@cleocode/core package API"
+        - "Provider adapters (Claude Code, Cursor, OpenCode)"
+        - "Other"
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Your environment
+      description: |
+        Run this command and paste the output:
+        ```bash
+        echo "CLEO: $(cleo version 2>/dev/null || echo 'not installed')" && echo "Node: $(node --version)" && echo "OS: $(uname -srm)" && echo "Shell: $SHELL"
+        ```
+      render: shell
+    validations:
+      required: false
+
+  - type: dropdown
+    id: agent-usage
+    attributes:
+      label: Are you using an AI agent?
+      description: Are you (or your AI agent) asking this question?
+      options:
+        - "Yes - AI agent filed this question"
+        - "Yes - Human filing with AI agent assistance"
+        - "No - Filing manually"
+    validations:
+      required: true

package/templates/skillsmp.json.example

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://cleo-dev.com/schemas/v1/skillsmp.schema.json",
+  "endpoint": "https://www.agentskills.in/api",
+  "apiKey": "",
+  "defaultInstallLocation": "project",
+  "timeout": 30,
+  "retries": 3,
+  "cache": {
+    "enabled": true,
+    "searchTtlMinutes": 5,
+    "contentTtlMinutes": 60
+  },
+  "validation": {
+    "checkSchemaVersion": true,
+    "requireSignature": false,
+    "allowedPublishers": []
+  },
+  "security": {
+    "sandboxMode": true,
+    "restrictedCommands": ["rm", "dd", "mkfs", "fdisk"],
+    "maxFileSize": 10485760
+  },
+  "logging": {
+    "level": "info",
+    "logInstalls": true,
+    "logSearches": false
+  }
+}