@cleocode/cleo 2026.2.5

package/templates/orchestrator-protocol/README.md

@@ -0,0 +1,162 @@
+# Orchestrator Protocol Templates
+
+> **Vision**: See [ORCHESTRATOR-VISION.md](../../docs/ORCHESTRATOR-VISION.md) for the core philosophy.
+>
+> **The Mantra**: *Stay high-level. Delegate everything. Read only manifests. Spawn in order.*
+
+Reusable templates for the CLEO Orchestrator Protocol.
+
+## Quick Start
+
+### 1. Enable Protocol (Skill-Based - Recommended)
+
+```bash
+# Option A: On-demand activation
+# Say "activate orchestrator mode" or use Skill tool
+
+# Option B: Install to project for persistent availability
+cleo orchestrator skill --install
+```
+
+### 2. Initialize Research Directory
+
+```bash
+cleo research init
+```
+
+### 3. Start Orchestrating
+
+```bash
+cleo orchestrator start --epic T001
+cleo orchestrator spawn T002
+```
+
+## Activation Methods
+
+| Method | When to Use | How |
+|--------|-------------|-----|
+| Skill (recommended) | Most workflows | `Skill: orchestrator` or natural language |
+| CLI install | Persistent project setup | `cleo orchestrator skill --install` |
+| CLAUDE.md injection | **DEPRECATED** | Do not use |
+
+**Why skill-based?** See [migration notes](#legacy-claudemd-injection-deprecated) below.
+
+## Directory Structure
+
+```
+orchestrator-protocol/
+  README.md                  # This file
+  PLACEHOLDER-REGISTRY.md    # Template placeholder definitions
+
+skills/                      # Skill definitions (migrated from subagent-prompts/)
+  _shared/                   # Shared references for all skills
+  spec-writer/SKILL.md       # Specification writing
+  epic-architect/SKILL.md    # Epic planning and decomposition
+  test-writer-bats/SKILL.md  # BATS test writing
+  library-implementer-bash/SKILL.md  # Bash library implementation
+  research-agent/SKILL.md    # Research and investigation
+  task-executor/SKILL.md     # General task execution
+  validator/SKILL.md         # Testing and validation
+```
+
+**Archived**: `docs/archive/ORCHESTRATOR-INJECT.md` (deprecated CLAUDE.md injection)
+
+## Skills (Migrated)
+
+Skills have replaced subagent prompt templates. Each skill is self-contained with:
+- `SKILL.md` - Main skill definition with frontmatter
+- `references/` - Optional supporting documentation
+- `examples/` - Optional usage examples
+
+| Skill | Use Case | Location |
+|-------|----------|----------|
+| spec-writer | Specification writing | `skills/spec-writer/` |
+| epic-architect | Epic planning | `skills/epic-architect/` |
+| test-writer-bats | BATS test writing | `skills/test-writer-bats/` |
+| library-implementer-bash | Bash library implementation | `skills/library-implementer-bash/` |
+| research-agent | Research tasks | `skills/research-agent/` |
+| task-executor | General task work | `skills/task-executor/` |
+| validator | Testing/validation | `skills/validator/` |
+
+### Placeholders
+
+Templates use `{PLACEHOLDER}` syntax:
+
+| Placeholder | Description |
+|-------------|-------------|
+| `{TASK_ID}` | CLEO task ID (e.g., T1586) |
+| `{TASK_TITLE}` | Task title |
+| `{TASK_NAME}` | Slugified task name |
+| `{EPIC_ID}` | Parent epic ID |
+| `{EPIC_TITLE}` | Parent epic title |
+| `{SESSION_ID}` | Current session ID |
+| `{DATE}` | Today's date (YYYY-MM-DD) |
+| `{OUTPUT_DIR}` | Research output directory |
+| `{TOPIC_SLUG}` | Slugified topic name |
+| `{DEPENDS_LIST}` | Comma-separated dependencies |
+| `{MANIFEST_SUMMARIES}` | Key findings from prior agents |
+| `{TASK_INSTRUCTIONS}` | Task description |
+
+## Usage
+
+### CLI (Recommended)
+
+```bash
+# Auto-fills all placeholders
+cleo orchestrator spawn T1586
+
+# With specific template
+cleo orchestrator spawn T1586 --template RESEARCH-AGENT
+```
+
+### Manual
+
+1. Read skill:
+```bash
+cat skills/task-executor/SKILL.md
+```
+
+2. Replace placeholders manually
+
+3. Spawn via Task tool
+
+## Customization
+
+### Add New Skill
+
+1. Create directory under `skills/`
+2. Add `SKILL.md` with YAML frontmatter
+3. Add `references/` for supporting docs
+4. Use standard placeholders
+
+### Modify Existing
+
+Edit skills in `skills/<skill-name>/`. Changes take effect on next spawn.
+
+## Legacy: CLAUDE.md Injection (DEPRECATED)
+
+> **Do NOT use CLAUDE.md injection for the orchestrator protocol.**
+
+**Why deprecated?**
+
+CLAUDE.md injection affects ALL agents including subagents, breaking the orchestrator pattern:
+
+| Problem | Impact |
+|---------|--------|
+| Subagents read CLAUDE.md | They also try to orchestrate |
+| Context overhead | Orchestrator rules loaded in every agent |
+| Role confusion | Workers try to delegate instead of execute |
+| Protocol violations | Nested orchestration breaks dependency tracking |
+
+**Migration steps:**
+
+1. Remove any `<!-- ORCHESTRATOR:START -->` blocks from your CLAUDE.md
+2. Run: `cleo orchestrator skill --install`
+3. Activate skill when orchestrator mode is needed
+
+## Documentation
+
+- [Orchestrator Protocol Guide](../../docs/guides/ORCHESTRATOR-PROTOCOL.md)
+- [CLI Reference](../../docs/commands/orchestrator.md)
+- [Example Session](../../docs/examples/orchestrator-example-session.md)
+- [Skill Directory](../../skills/orchestrator/README.md)

package/templates/sessions.template.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "../schemas/sessions.schema.json",
+  "version": "{{SCHEMA_VERSION_SESSIONS}}",
+  "project": "{{PROJECT_NAME}}",
+  "_meta": {
+    "schemaVersion": "{{SCHEMA_VERSION_SESSIONS}}",
+    "checksum": "",
+    "lastModified": "{{TIMESTAMP}}",
+    "totalSessionsCreated": 0
+  },
+  "config": {
+    "maxConcurrentSessions": 5,
+    "maxActiveTasksPerScope": 1,
+    "scopeValidation": "strict",
+    "allowNestedScopes": true,
+    "allowScopeOverlap": false
+  },
+  "sessions": [],
+  "sessionHistory": []
+}

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
+  }
+}

package/templates/skillsmp.json.example.md

@@ -0,0 +1,214 @@
+# SkillsMP Configuration Reference
+
+**File**: `~/.cleo/skillsmp.json` (global) or `./.cleo/skillsmp.json` (project)
+
+Configuration file for the SkillsMP (Skills Marketplace) integration in CLEO.
+
+---
+
+## Configuration Fields
+
+### Core Settings
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `$schema` | string | (see example) | JSON Schema reference for validation |
+| `endpoint` | string | `https://www.agentskills.in/api` | SkillsMP API endpoint URL |
+| `apiKey` | string | `""` | API key for authenticated requests (optional for public skills) |
+| `defaultInstallLocation` | enum | `"project"` | Default install location: `"project"` or `"global"` |
+| `timeout` | number | `30` | Request timeout in seconds |
+| `retries` | number | `3` | Number of retry attempts for failed requests |
+
+### Cache Settings
+
+Controls local caching of API responses to reduce network calls.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `cache.enabled` | boolean | `true` | Enable response caching |
+| `cache.searchTtlMinutes` | number | `5` | Cache duration for search results (minutes) |
+| `cache.contentTtlMinutes` | number | `60` | Cache duration for skill content (minutes) |
+
+### Validation Settings
+
+Controls skill validation and verification during installation.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `validation.checkSchemaVersion` | boolean | `true` | Verify skill schema version compatibility |
+| `validation.requireSignature` | boolean | `false` | Require cryptographic signature on skills |
+| `validation.allowedPublishers` | array | `[]` | Whitelist of trusted publishers (empty = allow all) |
+
+### Security Settings
+
+Sandbox and execution safety controls.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `security.sandboxMode` | boolean | `true` | Run skill validation in sandbox |
+| `security.restrictedCommands` | array | (see example) | Blocked shell commands in skill content |
+| `security.maxFileSize` | number | `10485760` | Max skill file size in bytes (10MB default) |
+
+### Logging Settings
+
+Controls diagnostic output and audit trails.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `logging.level` | enum | `"info"` | Log level: `"debug"`, `"info"`, `"warn"`, `"error"` |
+| `logging.logInstalls` | boolean | `true` | Log skill installation events |
+| `logging.logSearches` | boolean | `false` | Log search queries (verbose) |
+
+---
+
+## API Key Handling
+
+### Security Notes
+
+⚠️ **CRITICAL**: Never commit API keys to version control.
+
+**Recommended practices**:
+1. Use environment variable: `SKILLSMP_API_KEY`
+2. Store in global config: `~/.cleo/skillsmp.json`
+3. Add `.cleo/skillsmp.json` to `.gitignore`
+4. Use project config only for public/read-only access
+
+### Priority Order
+
+API key resolution order (first found wins):
+1. Environment variable: `$SKILLSMP_API_KEY`
+2. Project config: `./.cleo/skillsmp.json`
+3. Global config: `~/.cleo/skillsmp.json`
+4. No key (public access only)
+
+### Example: Environment Variable Setup
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export SKILLSMP_API_KEY="your-api-key-here"
+
+# Or set per-command
+SKILLSMP_API_KEY="key" cleo skill search "terraform"
+```
+
+---
+
+## Installation
+
+### Global Configuration (Recommended)
+
+```bash
+# Copy example to global location
+cp templates/skillsmp.json.example ~/.cleo/skillsmp.json
+
+# Edit with your API key
+nano ~/.cleo/skillsmp.json
+```
+
+### Project Configuration
+
+```bash
+# Copy example to project location
+cp templates/skillsmp.json.example ./.cleo/skillsmp.json
+
+# Add to .gitignore
+echo ".cleo/skillsmp.json" >> .gitignore
+```
+
+---
+
+## Validation
+
+Verify configuration syntax:
+
+```bash
+# Check if config is valid JSON
+jq empty ~/.cleo/skillsmp.json
+
+# Validate against schema (if ajv-cli installed)
+ajv validate -s schemas/skillsmp.schema.json -d ~/.cleo/skillsmp.json
+```
+
+---
+
+## Examples
+
+### Minimal Configuration (Public Access)
+
+```json
+{
+  "endpoint": "https://www.agentskills.in/api"
+}
+```
+
+### Development Configuration (Verbose Logging)
+
+```json
+{
+  "endpoint": "https://www.agentskills.in/api",
+  "cache": {
+    "enabled": false
+  },
+  "logging": {
+    "level": "debug",
+    "logSearches": true
+  }
+}
+```
+
+### Enterprise Configuration (Strict Security)
+
+```json
+{
+  "endpoint": "https://skills.enterprise.internal/api",
+  "apiKey": "${SKILLSMP_API_KEY}",
+  "defaultInstallLocation": "project",
+  "validation": {
+    "requireSignature": true,
+    "allowedPublishers": ["verified-publisher-1", "verified-publisher-2"]
+  },
+  "security": {
+    "sandboxMode": true,
+    "maxFileSize": 5242880
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| `Connection timeout` | Increase `timeout` value or check network |
+| `API key invalid` | Verify key in config or environment variable |
+| `Skill validation failed` | Check `validation.checkSchemaVersion` or disable strict mode |
+| `Cache stale` | Lower TTL values or disable cache |
+
+### Debug Mode
+
+Enable verbose logging:
+
+```bash
+# Temporary debug
+cleo skill search "query" --debug
+
+# Persistent debug
+cleo config set skillsmp.logging.level debug
+```
+
+---
+
+## See Also
+
+- **Full Documentation**: `docs/commands/skill.md`
+- **Schema Definition**: `schemas/skillsmp.schema.json`
+- **CLI Reference**: `cleo skill --help`
+- **SkillsMP API Docs**: https://www.agentskills.in/docs
+
+---
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-27

package/templates/subagent-protocol/INJECT.md

@@ -0,0 +1,32 @@
+# Subagent Injection Template
+
+Copy this block into every research subagent prompt. Replace `{output_dir}` with your project's path.
+
+---
+
+```
+OUTPUT REQUIREMENTS (RFC 2119):
+1. MUST write findings to: {output_dir}/YYYY-MM-DD_{topic-slug}.md
+2. MUST append ONE line to: {output_dir}/MANIFEST.jsonl
+3. MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return research content in response.
+
+Manifest entry format (single line):
+{"id":"topic-YYYY-MM-DD","file":"YYYY-MM-DD_topic.md","title":"Title","date":"YYYY-MM-DD","status":"complete|partial|blocked","agent_type":"research|implementation|validation|documentation|analysis","topics":["t1"],"key_findings":["Finding 1","Finding 2"],"actionable":true,"needs_followup":[]}
+
+Output file format:
+# {Title}
+**Date**: YYYY-MM-DD | **Agent**: {type} | **Status**: complete|partial|blocked
+
+## Executive Summary
+{3-5 sentences}
+
+## Findings
+{content}
+
+## Recommendations
+{list}
+
+## Open Questions
+{unresolved}
+```

package/templates/subagent-protocol/README.md

@@ -0,0 +1,76 @@
+# Subagent Research Output Protocol
+
+**v2.0.0** | RFC 2119 Compliant | Project-Agnostic
+
+Persistent research output management for Claude Code orchestrator/subagent workflows.
+
+## Problem Solved
+
+- Subagent outputs disappear in ephemeral `/tmp` files
+- Parallel subagents cause race conditions on shared manifest
+- Orchestrator context overflows reading full research files
+- No standard format for research handoff
+
+## Solution
+
+- **JSONL manifest** - append-only, no race conditions
+- **Structured output files** - consistent format for all research
+- **Injection template** - copy-paste block for subagent prompts
+- **RFC 2119 language** - unambiguous requirements
+
+## Installation
+
+```bash
+# From this template directory
+mkdir -p /path/to/project/.cleo/agent-outputs
+cp SUBAGENT_PROTOCOL.md INJECT.md MANIFEST.jsonl /path/to/project/.cleo/agent-outputs/
+```
+
+Or with a one-liner:
+
+```bash
+# Set your target project
+TARGET=/path/to/project/.cleo/agent-outputs
+mkdir -p "$TARGET" && cp SUBAGENT_PROTOCOL.md INJECT.md MANIFEST.jsonl "$TARGET/"
+```
+
+## Configuration
+
+Edit the config block in `SUBAGENT_PROTOCOL.md` for your project:
+
+```yaml
+output_dir: .cleo/agent-outputs  # Change this
+manifest_file: MANIFEST.jsonl
+archive_dir: .cleo/agent-outputs/archive
+```
+
+## Usage
+
+### Orchestrator
+
+1. Read `INJECT.md` for the template block
+2. Include injection block in every research subagent prompt
+3. Read `MANIFEST.jsonl` for summaries (not full files)
+
+```bash
+# Get all research summaries
+cat MANIFEST.jsonl | jq -s '.[] | {id, title, key_findings}'
+```
+
+### Subagent
+
+1. Write findings to `{output_dir}/YYYY-MM-DD_{topic-slug}.md`
+2. Append ONE line to `MANIFEST.jsonl`
+3. Return ONLY: `Research complete. See MANIFEST.jsonl for summary.`
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SUBAGENT_PROTOCOL.md` | Full specification |
+| `INJECT.md` | Copy-paste template for prompts |
+| `MANIFEST.jsonl` | Append-only research index |
+
+## License
+
+MIT - Use freely in any project.

package/templates/subagent-protocol/SUBAGENT_PROTOCOL.md

@@ -0,0 +1,135 @@
+# Subagent Research Output Protocol v2.0.0
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
+
+---
+
+## Configuration
+
+```yaml
+output_dir: .cleo/agent-outputs
+manifest_file: MANIFEST.jsonl
+archive_dir: .cleo/agent-outputs/archive
+```
+
+Projects MUST set `output_dir` to their preferred location. All paths below reference this configuration.
+
+---
+
+## Subagent Requirements
+
+### Output File
+
+Subagents MUST write findings to: `{output_dir}/YYYY-MM-DD_{topic-slug}.md`
+
+File format:
+
+```markdown
+# {Title}
+**Date**: YYYY-MM-DD | **Agent**: {agent-type} | **Status**: complete|partial|blocked
+
+---
+
+## Executive Summary
+{3-5 sentences max}
+
+---
+
+## Findings
+{detailed content}
+
+---
+
+## Recommendations
+{numbered list}
+
+---
+
+## Open Questions
+{unresolved items}
+```
+
+### Manifest Entry
+
+Subagents MUST append ONE line to `{output_dir}/{manifest_file}`:
+
+```json
+{"id":"topic-slug-YYYY-MM-DD","file":"YYYY-MM-DD_topic-slug.md","title":"Human Title","date":"YYYY-MM-DD","status":"complete","agent_type":"research","topics":["tag1","tag2"],"key_findings":["Finding 1","Finding 2"],"actionable":true,"needs_followup":[]}
+```
+
+Field requirements:
+| Field | Required | Constraint |
+|-------|----------|------------|
+| id | MUST | Unique slug with date |
+| file | MUST | Matches output filename |
+| title | MUST | Human-readable |
+| date | MUST | ISO 8601 date |
+| status | MUST | `complete`, `partial`, or `blocked` |
+| agent_type | SHOULD | `research`, `implementation`, `validation`, `documentation`, or `analysis` (default: `research`) |
+| topics | MUST | Array, 1+ items |
+| key_findings | MUST | Array, 3-7 items, one sentence each |
+| actionable | MUST | Boolean |
+| needs_followup | MUST | Array, MAY be empty |
+
+### Response
+
+Subagents MUST return ONLY: `Research complete. See {manifest_file} for summary.`
+
+Subagents MUST NOT return research content in the response.
+
+---
+
+## Orchestrator Requirements
+
+Orchestrators MUST include the injection block (see INJECT.md) in every research subagent prompt.
+
+Orchestrators MUST NOT read full research files into context.
+
+Orchestrators SHOULD read only `{manifest_file}` for research summaries.
+
+Orchestrators MAY use targeted Grep/Read with line limits for specific details.
+
+---
+
+## Manifest Operations
+
+### Read all entries
+```bash
+cat {output_dir}/MANIFEST.jsonl | jq -s '.'
+```
+
+### Query specific fields
+```bash
+cat {output_dir}/MANIFEST.jsonl | jq -s '.[] | {id, title, key_findings}'
+```
+
+### Rebuild from files (recovery)
+```bash
+for f in {output_dir}/*.md; do
+  title=$(head -1 "$f" | sed 's/^# //')
+  echo "Found: $title"
+done
+```
+
+---
+
+## Cleanup
+
+Files older than 30 days with `actionable: false` MAY be archived:
+
+```bash
+mv {output_dir}/old-file.md {archive_dir}/
+```
+
+Archived entries SHOULD remain in `{manifest_file}` with status updated to `archived`.
+
+---
+
+## Compliance
+
+A subagent is compliant if:
+1. Output file exists at specified path
+2. Manifest entry appended (file contains entry with matching `id`)
+3. Response contains only the required completion message
+
+Non-compliant outputs SHOULD be flagged by orchestrator for manual review.