@cleocode/cleo 2026.2.5 → 2026.2.6

package/packages/ct-skills/skills/_shared/placeholders.json

@@ -0,0 +1,433 @@
+{
+  "$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": "claudedocs/agent-outputs",
+      "description": "Output directory path for agent artifacts",
+      "default": "claudedocs/agent-outputs"
+    },
+    {
+      "token": "MANIFEST_PATH",
+      "type": "path",
+      "example": "claudedocs/agent-outputs/MANIFEST.jsonl",
+      "description": "Path to MANIFEST.jsonl file",
+      "default": "claudedocs/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 working on task"
+      },
+      {
+        "token": "TASK_CURRENT_CMD",
+        "default": "cleo current",
+        "description": "Command to show current task"
+      },
+      {
+        "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/packages/ct-skills/skills/_shared/skill-chaining-patterns.md

@@ -0,0 +1,240 @@
+# 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