@cleocode/cleo 2026.2.8 → 2026.3.0

package/skills/_shared/placeholders.json

@@ -1,433 +0,0 @@
-{
-  "$schema": "https://cleo-dev.com/schemas/v1/placeholders.schema.json",
-  "_meta": {
-    "version": "1.0.0",
-    "description": "Canonical registry of all template placeholders used in orchestrator protocol and skill templates",
-    "lastUpdated": "2026-01-26",
-    "tokenFormat": "{{TOKEN_NAME}}"
-  },
-  "required": [
-    {
-      "token": "TASK_ID",
-      "type": "string",
-      "pattern": "^T[0-9]+$",
-      "example": "T1234",
-      "description": "CLEO task ID"
-    },
-    {
-      "token": "DATE",
-      "type": "string",
-      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
-      "example": "2026-01-19",
-      "description": "ISO date (YYYY-MM-DD)",
-      "default": "$(date +%Y-%m-%d)"
-    },
-    {
-      "token": "TOPIC_SLUG",
-      "type": "string",
-      "pattern": "^[a-zA-Z0-9_-]+$",
-      "example": "auth-token-rotation",
-      "description": "Slugified topic name (lowercase, hyphenated, URL-safe)"
-    }
-  ],
-  "context": [
-    {
-      "token": "EPIC_ID",
-      "type": "string",
-      "pattern": "^T[0-9]+$",
-      "example": "T1000",
-      "description": "Parent epic ID",
-      "default": ""
-    },
-    {
-      "token": "SESSION_ID",
-      "type": "string",
-      "pattern": "^session_[0-9]{8}_[0-9]{6}_[a-f0-9]+$",
-      "example": "session_20260119_143500_abc123",
-      "description": "Current CLEO session ID",
-      "default": ""
-    },
-    {
-      "token": "RESEARCH_ID",
-      "type": "string",
-      "example": "auth-token-2026-01-19",
-      "description": "Research entry ID for manifest",
-      "default": ""
-    },
-    {
-      "token": "TITLE",
-      "type": "string",
-      "example": "Authentication Token Rotation",
-      "description": "Human-readable title",
-      "default": ""
-    },
-    {
-      "token": "OUTPUT_DIR",
-      "type": "path",
-      "example": ".cleo/agent-outputs",
-      "description": "Output directory path for agent artifacts",
-      "default": ".cleo/agent-outputs"
-    },
-    {
-      "token": "MANIFEST_PATH",
-      "type": "path",
-      "example": ".cleo/agent-outputs/MANIFEST.jsonl",
-      "description": "Path to MANIFEST.jsonl file",
-      "default": ".cleo/agent-outputs/MANIFEST.jsonl"
-    }
-  ],
-  "taskCommands": {
-    "_comment": "CLEO task system command tokens - enables portability",
-    "tokens": [
-      {
-        "token": "TASK_SHOW_CMD",
-        "default": "cleo show",
-        "description": "Command to show task details"
-      },
-      {
-        "token": "TASK_START_CMD",
-        "default": "cleo start",
-        "description": "Command to start a task"
-      },
-      {
-        "token": "TASK_FOCUS_SHOW_CMD",
-        "default": "cleo focus show",
-        "description": "Command to show current focus"
-      },
-      {
-        "token": "TASK_COMPLETE_CMD",
-        "default": "cleo complete",
-        "description": "Command to complete task"
-      },
-      {
-        "token": "TASK_LINK_CMD",
-        "default": "cleo research link",
-        "description": "Command to link research to task"
-      },
-      {
-        "token": "TASK_LIST_CMD",
-        "default": "cleo list",
-        "description": "Command to list tasks"
-      },
-      {
-        "token": "TASK_FIND_CMD",
-        "default": "cleo find",
-        "description": "Command to find tasks"
-      },
-      {
-        "token": "TASK_ADD_CMD",
-        "default": "cleo add",
-        "description": "Command to add task"
-      },
-      {
-        "token": "SESSION_LIST_CMD",
-        "default": "cleo session list",
-        "description": "Command to list sessions"
-      },
-      {
-        "token": "SESSION_START_CMD",
-        "default": "cleo session start",
-        "description": "Command to start session"
-      },
-      {
-        "token": "SESSION_END_CMD",
-        "default": "cleo session end",
-        "description": "Command to end session"
-      },
-      {
-        "token": "DASH_CMD",
-        "default": "cleo dash",
-        "description": "Command to show dashboard"
-      },
-      {
-        "token": "RESEARCH_LIST_CMD",
-        "default": "cleo research list",
-        "description": "Command to list research entries"
-      },
-      {
-        "token": "RESEARCH_SHOW_CMD",
-        "default": "cleo research show",
-        "description": "Command to show research entry details"
-      },
-      {
-        "token": "RESEARCH_PENDING_CMD",
-        "default": "cleo research pending",
-        "description": "Command to show pending research followups"
-      },
-      {
-        "token": "RESEARCH_INJECT_CMD",
-        "default": "cleo research inject",
-        "description": "Command to inject subagent protocol block (supports --clipboard flag)"
-      },
-      {
-        "token": "SESSION_GC_CMD",
-        "default": "cleo session gc",
-        "description": "Command for session garbage collection (supports --include-active flag)"
-      },
-      {
-        "token": "TASK_EXISTS_CMD",
-        "default": "cleo exists",
-        "description": "Command to check if task ID exists (exit code 0/1)"
-      },
-      {
-        "token": "TASK_PHASE_CMD",
-        "default": "cleo phase show",
-        "description": "Command to show current project phase"
-      },
-      {
-        "token": "TASK_TREE_CMD",
-        "default": "cleo list --tree",
-        "description": "Command to show task hierarchy tree (use --parent for subtree)"
-      }
-    ]
-  },
-  "manifest": {
-    "_comment": "Tokens used when constructing MANIFEST.jsonl entries",
-    "tokens": [
-      {
-        "token": "MANIFEST_ID",
-        "type": "string",
-        "example": "topic-2026-01-19",
-        "description": "Unique manifest entry ID"
-      },
-      {
-        "token": "MANIFEST_FILE",
-        "type": "string",
-        "example": "2026-01-19_topic-slug.md",
-        "description": "Output filename"
-      },
-      {
-        "token": "MANIFEST_TITLE",
-        "type": "string",
-        "example": "Research on Topic",
-        "description": "Entry title"
-      },
-      {
-        "token": "MANIFEST_STATUS",
-        "type": "enum",
-        "enum": ["complete", "partial", "blocked"],
-        "default": "complete",
-        "description": "Entry status"
-      },
-      {
-        "token": "MANIFEST_TOPICS",
-        "type": "array",
-        "example": ["auth", "security"],
-        "description": "Topic tags"
-      },
-      {
-        "token": "MANIFEST_FINDINGS",
-        "type": "array",
-        "example": ["Finding 1", "Finding 2"],
-        "description": "Key findings (3-7 items)"
-      },
-      {
-        "token": "LINKED_TASKS",
-        "type": "array",
-        "example": ["T1234", "T1235"],
-        "description": "Related CLEO task IDs"
-      },
-      {
-        "token": "NEEDS_FOLLOWUP",
-        "type": "array",
-        "default": [],
-        "description": "Tasks requiring follow-up"
-      }
-    ]
-  },
-  "taskContext": {
-    "_comment": "Task-specific tokens populated by orchestrator from CLEO task data",
-    "tokens": [
-      {
-        "token": "TASK_TITLE",
-        "type": "string",
-        "example": "Implement login endpoint",
-        "description": "Task title from CLEO (task.title)",
-        "source": "task.title"
-      },
-      {
-        "token": "TASK_NAME",
-        "type": "string",
-        "example": "Implement login endpoint",
-        "description": "Alias for TASK_TITLE (for backward compatibility)",
-        "source": "task.title"
-      },
-      {
-        "token": "TASK_DESCRIPTION",
-        "type": "string",
-        "example": "Create POST /api/login endpoint with JWT authentication...",
-        "description": "Task description from CLEO (task.description)",
-        "source": "task.description"
-      },
-      {
-        "token": "TASK_INSTRUCTIONS",
-        "type": "string",
-        "example": "Create POST /api/login endpoint with JWT authentication...",
-        "description": "Task instructions (defaults to task.description, can be custom)",
-        "source": "task.description"
-      },
-      {
-        "token": "TOPICS_JSON",
-        "type": "array",
-        "example": "[\"auth\", \"api\", \"security\"]",
-        "description": "Task labels as JSON array",
-        "source": "task.labels"
-      },
-      {
-        "token": "DEPENDS_LIST",
-        "type": "string",
-        "example": "T1001, T1002",
-        "description": "Comma-separated dependency IDs",
-        "source": "task.depends",
-        "default": ""
-      },
-      {
-        "token": "ACCEPTANCE_CRITERIA",
-        "type": "string",
-        "example": "Tests pass, API responds with valid JWT",
-        "description": "Acceptance criteria (extracted from description or default)",
-        "default": "Task completed successfully per description"
-      },
-      {
-        "token": "DELIVERABLES_LIST",
-        "type": "string",
-        "example": "1. API endpoint\\n2. Unit tests\\n3. Documentation",
-        "description": "List of deliverables (extracted from description or default)",
-        "default": "Implementation per task description"
-      },
-      {
-        "token": "MANIFEST_SUMMARIES",
-        "type": "string",
-        "example": "Previous research found: auth tokens should rotate every 24h",
-        "description": "Context from previous subagent manifest entries",
-        "default": ""
-      },
-      {
-        "token": "NEXT_TASK_IDS",
-        "type": "string",
-        "example": "T1003, T1004",
-        "description": "Follow-up task IDs to add to needs_followup",
-        "default": ""
-      }
-    ]
-  },
-  "skillSpecific": {
-    "epicArchitect": [
-      {
-        "token": "FEATURE_SLUG",
-        "type": "string",
-        "example": "user-authentication",
-        "description": "Slugified feature name"
-      },
-      {
-        "token": "FEATURE_NAME",
-        "type": "string",
-        "example": "User Authentication",
-        "description": "Human-readable feature name"
-      },
-      {
-        "token": "FEATURE_DESCRIPTION",
-        "type": "string",
-        "example": "Implement JWT-based authentication...",
-        "description": "Full description from epic"
-      }
-    ],
-    "validator": [
-      {
-        "token": "TEST_SCOPE",
-        "type": "enum",
-        "enum": ["unit", "integration", "e2e"],
-        "description": "Test scope to execute"
-      },
-      {
-        "token": "TARGET_PATH",
-        "type": "path",
-        "example": "src/auth/",
-        "description": "Path to validate"
-      }
-    ],
-    "taskExecutor": [
-      {
-        "token": "TASK_TITLE",
-        "type": "string",
-        "example": "Implement login endpoint",
-        "description": "Task title (from taskContext.TASK_TITLE)",
-        "inherits": "taskContext.TASK_TITLE"
-      },
-      {
-        "token": "TASK_NAME",
-        "type": "string",
-        "example": "Implement login endpoint",
-        "description": "Alias for TASK_TITLE (from taskContext.TASK_NAME)",
-        "inherits": "taskContext.TASK_NAME"
-      },
-      {
-        "token": "TASK_DESCRIPTION",
-        "type": "string",
-        "example": "Create POST /api/login with JWT auth...",
-        "description": "Task description (from taskContext.TASK_DESCRIPTION)",
-        "inherits": "taskContext.TASK_DESCRIPTION"
-      },
-      {
-        "token": "TASK_INSTRUCTIONS",
-        "type": "string",
-        "example": "1. Create endpoint\\n2. Add JWT validation\\n3. Return token",
-        "description": "Execution instructions (from taskContext.TASK_INSTRUCTIONS)",
-        "inherits": "taskContext.TASK_INSTRUCTIONS"
-      },
-      {
-        "token": "DELIVERABLES_LIST",
-        "type": "string",
-        "example": "1. API endpoint\\n2. Unit tests\\n3. Documentation",
-        "description": "Expected outputs (from taskContext.DELIVERABLES_LIST)",
-        "inherits": "taskContext.DELIVERABLES_LIST"
-      },
-      {
-        "token": "ACCEPTANCE_CRITERIA",
-        "type": "string",
-        "example": "Tests pass, API responds with valid JWT",
-        "description": "Completion criteria (from taskContext.ACCEPTANCE_CRITERIA)",
-        "inherits": "taskContext.ACCEPTANCE_CRITERIA"
-      },
-      {
-        "token": "DEPENDS_LIST",
-        "type": "string",
-        "example": "T1001, T1002",
-        "description": "Completed dependencies (from taskContext.DEPENDS_LIST)",
-        "inherits": "taskContext.DEPENDS_LIST"
-      },
-      {
-        "token": "TOPICS_JSON",
-        "type": "array",
-        "example": "[\"auth\", \"api\"]",
-        "description": "Task labels as JSON (from taskContext.TOPICS_JSON)",
-        "inherits": "taskContext.TOPICS_JSON"
-      },
-      {
-        "token": "MANIFEST_SUMMARIES",
-        "type": "string",
-        "example": "Previous: auth tokens rotate every 24h",
-        "description": "Context from previous agents (from taskContext.MANIFEST_SUMMARIES)",
-        "inherits": "taskContext.MANIFEST_SUMMARIES"
-      },
-      {
-        "token": "NEXT_TASK_IDS",
-        "type": "string",
-        "example": "T1003, T1004",
-        "description": "Follow-up task IDs (from taskContext.NEXT_TASK_IDS)",
-        "inherits": "taskContext.NEXT_TASK_IDS"
-      }
-    ]
-  },
-  "conventions": {
-    "naming": "ALL_CAPS with underscores for multi-word names",
-    "format": "Enclosed in double curly braces: {{TOKEN_NAME}}",
-    "validation": {
-      "string": "Non-empty UTF-8 text",
-      "date": "ISO 8601 (YYYY-MM-DD)",
-      "path": "Unix path with valid characters",
-      "enum": "Exact match required",
-      "array": "Valid JSON array"
-    }
-  }
-}

package/skills/_shared/skill-chaining-patterns.md

@@ -1,240 +0,0 @@
-# Skill Chaining Patterns
-
-This reference defines patterns for multi-level skill invocation and context propagation across agent boundaries.
-
----
-
-## Pattern Overview
-
-| Pattern | Description | Use Case |
-|---------|-------------|----------|
-| Single-level | Orchestrator spawns one skill | Simple task delegation |
-| Skill chaining | Skill invokes other skills | Workflow orchestration |
-| Multi-level | Subagent becomes orchestrator | Complex nested workflows |
-
----
-
-## Pattern 1: Single-Level Spawning
-
-The orchestrator delegates work to a subagent via Task tool with skill injection.
-
-### Flow
-
-```
-┌─────────────────┐
-│   ORCHESTRATOR  │
-│  (ct-orchestrator)
-└────────┬────────┘
-         │ Task tool + skill template
-         ▼
-┌─────────────────┐
-│    SUBAGENT     │
-│ (ct-research-agent)
-└─────────────────┘
-```
-
-### Implementation
-
-```bash
-# Orchestrator prepares context
-source lib/token-inject.sh
-export TI_TASK_ID="T1234"
-export TI_DATE="$(date +%Y-%m-%d)"
-export TI_TOPIC_SLUG="auth-research"
-ti_set_defaults
-
-# Load skill template with tokens
-template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
-
-# Spawn via Task tool (includes subagent protocol block)
-```
-
-### Context Propagation
-
-- **Input**: Task ID, skill template, previous manifest key_findings
-- **Output**: Manifest entry with key_findings for next agent
-- **Response**: "Research complete. See MANIFEST.jsonl for summary."
-
----
-
-## Pattern 2: Skill Chaining
-
-A skill invokes other skills to complete workflow phases. The loaded skill maintains context while delegating specialized work.
-
-### Example: ct-documentor
-
-```
-┌─────────────────────┐
-│   ct-documentor     │ ← Loaded by user request
-│  (Documentation     │
-│   Specialist)       │
-└─────────┬───────────┘
-          │
-    ┌─────┴─────┬────────────┐
-    ▼           ▼            ▼
-┌───────┐  ┌────────┐  ┌─────────┐
-│lookup │  │ write  │  │ review  │
-│(Phase │  │(Phase  │  │(Phase   │
-│   1)  │  │   3)   │  │   4)    │
-└───────┘  └────────┘  └─────────┘
-```
-
-### Skill Invocation Methods
-
-```markdown
-# Via Skill tool (programmatic)
-Skill(skill="ct-docs-lookup")
-Skill(skill="ct-docs-write")
-Skill(skill="ct-docs-review")
-
-# Via slash command (user-facing)
-/ct-docs-lookup
-/ct-docs-write
-/ct-docs-review
-```
-
-### When to Use Skill Chaining
-
-| Scenario | Pattern |
-|----------|---------|
-| Workflow has distinct phases | Chain skills for each phase |
-| Skills share common context | Parent skill maintains state |
-| Quality gates between phases | Invoke review skill before completion |
-| Specialized expertise needed | Delegate to domain-specific skill |
-
-### Context Management
-
-**Within skill chain (same agent)**:
-- Skills share the agent's context window
-- State persists between skill invocations
-- No manifest needed for internal handoffs
-
-**Across agent boundaries**:
-- Use manifest for key_findings only
-- Write detailed output to files
-- Return minimal response to preserve parent context
-
----
-
-## Pattern 3: Multi-Level Orchestration
-
-A subagent can itself become an orchestrator, spawning further subagents for complex nested workflows.
-
-### Flow
-
-```
-┌─────────────────────┐
-│    ORCHESTRATOR     │  Level 0: Main workflow
-│   (ct-orchestrator) │
-└─────────┬───────────┘
-          │ Task tool
-          ▼
-┌─────────────────────┐
-│ SUB-ORCHESTRATOR    │  Level 1: Epic decomposition
-│ (ct-epic-architect) │
-└─────────┬───────────┘
-          │ Task tool
-          ▼
-┌─────────────────────┐
-│    WORKER AGENT     │  Level 2: Task execution
-│ (ct-task-executor)  │
-└─────────────────────┘
-```
-
-### Guidelines for Multi-Level
-
-1. **Depth limit**: SHOULD NOT exceed 3 levels (diminishing returns)
-2. **Context budget**: Each level MUST stay under 10K tokens
-3. **Manifest propagation**: Each level writes to shared manifest
-4. **Response contract**: Each level returns only summary message
-
-### When Multi-Level is Appropriate
-
-| Use Case | Levels | Structure |
-|----------|--------|-----------|
-| Simple research | 1 | Orchestrator → Researcher |
-| Epic planning | 2 | Orchestrator → Architect → Executor |
-| Complex pipeline | 3 | Orchestrator → Coordinator → Workers |
-
----
-
-## Context Boundary Rules
-
-### Rule 1: Manifest for Handoffs (MUST)
-
-```json
-// Subagent appends ONE line to MANIFEST.jsonl
-{"id":"topic-2026-01-20","key_findings":["Finding 1","Finding 2"],"needs_followup":["T1235"]}
-```
-
-Parent reads only key_findings, not full research files.
-
-### Rule 2: Minimal Response (MUST)
-
-```
-Subagent MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
-Subagent MUST NOT return research content in response.
-```
-
-### Rule 3: File-Based Details (MUST)
-
-Detailed findings go to output files, not manifest or response:
-- Full analysis → `{{OUTPUT_DIR}}/YYYY-MM-DD_topic.md`
-- Summary only → `MANIFEST.jsonl` key_findings array
-
-### Rule 4: Token Injection (SHOULD)
-
-Use `lib/token-inject.sh` for dynamic token replacement:
-
-```bash
-# Required tokens for all subagents
-TI_TASK_ID    # Current task identifier
-TI_DATE       # Execution date (YYYY-MM-DD)
-TI_TOPIC_SLUG # URL-safe topic name
-```
-
----
-
-## Anti-Patterns
-
-| Pattern | Problem | Solution |
-|---------|---------|----------|
-| Reading full files at parent | Context explosion | Use manifest key_findings |
-| Returning research content | Context bloat | Return summary message only |
-| Parallel subagent spawning | Race conditions | Sequential spawning only |
-| Deep nesting (4+ levels) | Coordination overhead | Flatten to 3 levels max |
-| Skipping manifest entry | Lost handoff | Always append manifest |
-
----
-
-## Implementation Checklist
-
-Before spawning subagent:
-- [ ] Identify appropriate skill for task type
-- [ ] Prepare token context (TI_TASK_ID, TI_DATE, TI_TOPIC_SLUG)
-- [ ] Load skill template with `ti_load_template()`
-- [ ] Include subagent protocol block in prompt
-
-Before chaining to another skill:
-- [ ] Determine if skill shares context (same agent) or needs delegation
-- [ ] For same-agent: Use `Skill(skill="name")` or `/skill-name`
-- [ ] For new agent: Use Task tool with full protocol injection
-
-Before completion:
-- [ ] Verify manifest entry appended
-- [ ] Confirm output file written
-- [ ] Return ONLY the summary message
-
----
-
-## Reference Skills
-
-| Skill | Demonstrates |
-|-------|--------------|
-| `ct-orchestrator` | Single-level spawning via Task tool |
-| `ct-documentor` | Skill chaining (lookup → write → review) |
-| `ct-epic-architect` | Potential multi-level orchestration |
-
-See also:
-- @skills/_shared/subagent-protocol-base.md
-- @skills/_shared/task-system-integration.md