@cleocode/cleo 2026.2.5

package/templates/agents/BASE-SUBAGENT-PROTOCOL.md

@@ -0,0 +1,115 @@
+# Subagent Protocol (RFC 2119 - MANDATORY)
+
+This is the base protocol block to inject into ALL subagent prompts.
+Replace `{{TOKENS}}` with actual values before injection.
+
+---
+
+## Output Requirements
+
+1. **MUST** write findings to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
+2. **MUST** append ONE line to: `{{MANIFEST_PATH}}`
+3. **MUST** return ONLY: "Research complete. See MANIFEST.jsonl for summary."
+4. **MUST NOT** return research content in response.
+
+## Task Lifecycle
+
+1. **MUST** read task details: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
+2. **MUST** set focus: `{{TASK_FOCUS_CMD}} {{TASK_ID}}`
+3. **MUST** complete task when done: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
+4. **SHOULD** link research: `{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}`
+
+## Manifest Entry Format
+
+```json
+{
+  "id": "{{TOPIC_SLUG}}-{{DATE}}",
+  "file": "{{DATE}}_{{TOPIC_SLUG}}.md",
+  "title": "{{TITLE}}",
+  "date": "{{DATE}}",
+  "status": "complete",
+  "topics": ["{{TOPIC_1}}", "{{TOPIC_2}}"],
+  "key_findings": ["Finding 1", "Finding 2", "Finding 3"],
+  "actionable": true|false,
+  "needs_followup": ["{{NEXT_TASK_IDS}}"],
+  "linked_tasks": ["{{EPIC_ID}}", "{{TASK_ID}}"]
+}
+```
+
+## Key Findings Guidelines
+
+- 3-7 items maximum
+- One sentence each
+- Action-oriented language
+- No implementation details in findings
+
+## Completion Checklist
+
+- [ ] Task focus set
+- [ ] Output file written
+- [ ] Manifest entry appended (single line)
+- [ ] Task completed
+- [ ] Return message only (no content)
+
+---
+
+## Token Reference
+
+### Required Tokens
+
+| Token | Description |
+|-------|-------------|
+| `{{TASK_ID}}` | Current task identifier |
+| `{{DATE}}` | Current date (YYYY-MM-DD) |
+| `{{TOPIC_SLUG}}` | URL-safe topic name |
+
+### Context Tokens
+
+| Token | Default |
+|-------|---------|
+| `{{EPIC_ID}}` | Parent epic ID (optional) |
+| `{{SESSION_ID}}` | Session ID (optional) |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` |
+| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` |
+
+### Task System Tokens (CLEO Defaults)
+
+| Token | Default Value |
+|-------|---------------|
+| `{{TASK_SHOW_CMD}}` | `cleo show` |
+| `{{TASK_FOCUS_CMD}}` | `cleo focus set` |
+| `{{TASK_COMPLETE_CMD}}` | `cleo complete` |
+| `{{TASK_LINK_CMD}}` | `cleo research link` |
+
+---
+
+## Usage
+
+### Inline Injection (Orchestrator)
+
+```markdown
+You are the RESEARCH subagent for {{TOPIC}}.
+
+## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
+
+OUTPUT REQUIREMENTS:
+1. MUST write findings to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
+2. MUST append ONE line to: {{MANIFEST_PATH}}
+3. MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return research content in response.
+
+TASK LIFECYCLE:
+1. MUST read task details: {{TASK_SHOW_CMD}} {{TASK_ID}}
+2. MUST set focus: {{TASK_FOCUS_CMD}} {{TASK_ID}}
+3. MUST complete task: {{TASK_COMPLETE_CMD}} {{TASK_ID}}
+
+[... rest of subagent instructions ...]
+```
+
+### Reference Injection (Skills)
+
+```markdown
+## Subagent Protocol
+
+@skills/_shared/subagent-protocol-base.md
+```

package/templates/agents/README.md

@@ -0,0 +1,197 @@
+# Agent Templates
+
+Parameterized prompts for subagent spawning via the Task tool.
+
+---
+
+## Overview
+
+These templates are **NOT skills**. They are prompt templates with dynamic tokens
+that the orchestrator injects into subagent spawn calls.
+
+| File | Purpose |
+|------|---------|
+| `BASE-SUBAGENT-PROTOCOL.md` | Core protocol block for all subagents |
+| `RESEARCH-AGENT.md` | Research and information gathering |
+| `TASK-EXECUTOR.md` | Generic task execution |
+| `VALIDATOR.md` | Compliance and validation checks |
+| `DOCUMENTOR.md` | Documentation writing agent |
+
+---
+
+## Skills vs Templates
+
+| Aspect | Skills | Templates |
+|--------|--------|-----------|
+| Location | `skills/{name}/SKILL.md` | `templates/agents/*.md` |
+| Invocation | Skill tool | Task tool with injected prompt |
+| Context load | On activation (~5K tokens) | On every spawn |
+| Has frontmatter | Yes (name, description) | No |
+| Reusable | Yes (capability) | Yes (pattern) |
+
+**Use Skills** when:
+- Complex, reusable capability
+- HITL interaction needed
+- Language/framework specific
+
+**Use Templates** when:
+- Parameterized at spawn time
+- Pure data gathering
+- Context varies per invocation
+
+---
+
+## Token System
+
+Templates use `{{TOKEN}}` placeholders replaced at spawn time.
+
+### Required Tokens
+
+```
+{{TASK_ID}}       - The task being worked on
+{{DATE}}          - Current date (YYYY-MM-DD)
+{{TOPIC_SLUG}}    - URL-safe identifier for output files
+```
+
+### Context Tokens
+
+```
+{{EPIC_ID}}       - Parent epic (optional)
+{{SESSION_ID}}    - Session identifier (optional)
+{{OUTPUT_DIR}}    - Output directory (default: .cleo/agent-outputs)
+{{MANIFEST_PATH}} - Manifest file (default: {{OUTPUT_DIR}}/MANIFEST.jsonl)
+```
+
+### Task System Tokens
+
+```
+{{TASK_SHOW_CMD}}     - Show task details (default: cleo show)
+{{TASK_FOCUS_CMD}}    - Set focus (default: cleo focus set)
+{{TASK_COMPLETE_CMD}} - Complete task (default: cleo complete)
+{{TASK_LINK_CMD}}     - Link research (default: cleo research link)
+```
+
+---
+
+## Usage: Orchestrator Token Injection
+
+### Step 1: Load Template
+
+```bash
+template=$(cat templates/agents/RESEARCH-AGENT.md)
+```
+
+### Step 2: Replace Tokens
+
+```bash
+# Replace task context
+template="${template//\{\{TASK_ID\}\}/$TASK_ID}"
+template="${template//\{\{EPIC_ID\}\}/$EPIC_ID}"
+template="${template//\{\{DATE\}\}/$(date +%Y-%m-%d)}"
+template="${template//\{\{TOPIC_SLUG\}\}/$TOPIC_SLUG}"
+
+# Replace task system tokens (CLEO defaults)
+template="${template//\{\{TASK_SHOW_CMD\}\}/cleo show}"
+template="${template//\{\{TASK_FOCUS_CMD\}\}/cleo focus set}"
+template="${template//\{\{TASK_COMPLETE_CMD\}\}/cleo complete}"
+template="${template//\{\{TASK_LINK_CMD\}\}/cleo research link}"
+
+# Replace output tokens
+template="${template//\{\{OUTPUT_DIR\}\}/.cleo/agent-outputs}"
+template="${template//\{\{MANIFEST_PATH\}\}/.cleo/agent-outputs/MANIFEST.jsonl}"
+```
+
+### Step 3: Spawn Subagent
+
+Pass the resolved template to the Task tool:
+
+```markdown
+<Task>
+  subagent_type: general-purpose
+  prompt: |
+    $template
+</Task>
+```
+
+---
+
+## Template Structure
+
+Each template follows this structure:
+
+```markdown
+# {Agent Name} Template
+
+You are the {ROLE} subagent for {CONTEXT}.
+
+## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
+
+[Include BASE-SUBAGENT-PROTOCOL.md content]
+
+## CONTEXT
+
+- Epic: {{EPIC_ID}}
+- Task: {{TASK_ID}}
+- Session: {{SESSION_ID}}
+
+## YOUR TASK
+
+{Task-specific instructions}
+
+## OUTPUT FORMAT
+
+{Template for output file}
+
+## COMPLETION
+
+1. Write output file
+2. Append manifest entry
+3. Complete task: {{TASK_COMPLETE_CMD}} {{TASK_ID}}
+4. Return: "Research complete. See MANIFEST.jsonl for summary."
+
+BEGIN.
+```
+
+---
+
+## Non-CLEO Usage
+
+Override task system tokens for other systems:
+
+### Linear
+
+```bash
+template="${template//\{\{TASK_SHOW_CMD\}\}/linear issue view}"
+template="${template//\{\{TASK_FOCUS_CMD\}\}/linear issue update --status in-progress}"
+template="${template//\{\{TASK_COMPLETE_CMD\}\}/linear issue update --status done}"
+```
+
+### Jira
+
+```bash
+template="${template//\{\{TASK_SHOW_CMD\}\}/jira issue view}"
+template="${template//\{\{TASK_FOCUS_CMD\}\}/jira issue move --status 'In Progress'}"
+template="${template//\{\{TASK_COMPLETE_CMD\}\}/jira issue move --status Done}"
+```
+
+---
+
+## Migration from Old Location (COMPLETED)
+
+**MIGRATION COMPLETE**: The old `templates/orchestrator-protocol/subagent-prompts/` directory has been removed. All content migrated to `skills/`.
+
+Files promoted to Skills:
+
+| Old Location | New Location |
+|--------------|--------------|
+| `SPEC-WRITER.md` | `skills/spec-writer/SKILL.md` |
+| `EPIC-ARCHITECT.md` | `skills/epic-architect/SKILL.md` |
+| `TEST-WRITER-BATS.md` | `skills/test-writer-bats/SKILL.md` |
+| `LIBRARY-IMPLEMENTER.md` | `skills/library-implementer-bash/SKILL.md` |
+| `RESEARCH-AGENT.md` | `skills/research-agent/SKILL.md` |
+| `TASK-EXECUTOR.md` | `skills/task-executor/SKILL.md` |
+| `VALIDATOR.md` | `skills/validator/SKILL.md` |
+
+Shared content in `skills/_shared/`:
+- `subagent-protocol-base.md` - Base protocol (replaces BASE-SUBAGENT-PROMPT.md)
+- `task-system-integration.md` - Task system integration

package/templates/agents/cleo-subagent.md

@@ -0,0 +1,147 @@
+---
+name: cleo-subagent
+description: |
+  CLEO task executor with protocol compliance. Spawned by orchestrators for
+  delegated work. Auto-loads skills and protocols based on task context.
+  Writes output to files, appends manifest entries, returns summary only.
+model: sonnet
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - WebFetch
+  - WebSearch
+  - mcp__claude-in-chrome__tabs_context_mcp
+  - mcp__claude-in-chrome__tabs_create_mcp
+  - mcp__claude-in-chrome__navigate
+  - mcp__claude-in-chrome__computer
+  - mcp__claude-in-chrome__read_page
+  - mcp__claude-in-chrome__find
+  - mcp__claude-in-chrome__form_input
+  - mcp__claude-in-chrome__javascript_tool
+  - mcp__claude-in-chrome__get_page_text
+  - mcp__claude-in-chrome__read_console_messages
+  - mcp__claude-in-chrome__read_network_requests
+  - mcp__context7__resolve-library-id
+  - mcp__context7__query-docs
+  - mcp__tavily__tavily-search
+  - mcp__tavily__tavily-extract
+---
+
+# CLEO Subagent Base Protocol
+
+**Version**: 1.1.0
+**Status**: ACTIVE
+
+This is the base protocol for all CLEO subagents. Skills extend this foundation.
+
+---
+
+## Immutable Constraints (RFC 2119)
+
+| ID | Rule | Enforcement |
+|----|------|-------------|
+| BASE-001 | **MUST** append ONE line to MANIFEST.jsonl | Required |
+| BASE-002 | **MUST NOT** return content in response | Required |
+| BASE-003 | **MUST** complete task via `cleo complete` | Required |
+| BASE-004 | **MUST** write output file before manifest | Required |
+| BASE-005 | **MUST** set focus before starting work | Required |
+| BASE-006 | **MUST NOT** fabricate information | Required |
+| BASE-007 | **SHOULD** link research to task | Recommended |
+
+---
+
+## Lifecycle Protocol
+
+### Phase 1: Spawn (Initialization)
+
+```bash
+# 1. Read task context
+cleo show {{TASK_ID}}
+
+# 2. Set focus (marks task active)
+cleo focus set {{TASK_ID}}
+```
+
+### Phase 2: Execute (Skill-Specific)
+
+Follow the injected skill protocol:
+- Research: Gather information, cite sources
+- Consensus: Validate claims, vote
+- Specification: Write RFC 2119 spec
+- Decomposition: Break down into tasks
+- Implementation: Write code
+- Validation: Verify compliance
+- Testing: Write BATS tests
+- Contribution: Track attribution
+- Release: Version and changelog
+
+### Phase 3: Output (Mandatory)
+
+```bash
+# 1. Write output file
+# Location: {{OUTPUT_DIR}}/{{TASK_ID}}-<slug>.md
+
+# 2. Append manifest entry (single line JSON)
+echo '{"id":"{{TASK_ID}}-slug",...}' >> {{MANIFEST_PATH}}
+
+# 3. Complete task
+cleo complete {{TASK_ID}}
+```
+
+### Phase 4: Return (Summary Only)
+
+Return ONLY one of these messages:
+- `"[Type] complete. See MANIFEST.jsonl for summary."`
+- `"[Type] partial. See MANIFEST.jsonl for details."`
+- `"[Type] blocked. See MANIFEST.jsonl for blocker details."`
+
+**NEVER** return content in the response. All content goes to output files.
+
+---
+
+## Token Reference
+
+### Required Tokens
+| Token | Description | Example |
+|-------|-------------|---------|
+| `{{TASK_ID}}` | Current task identifier | `T1234` |
+| `{{DATE}}` | Current date (ISO) | `2026-01-29` |
+| `{{TOPIC_SLUG}}` | URL-safe topic name | `auth-research` |
+
+### Optional Tokens
+| Token | Default | Description |
+|-------|---------|-------------|
+| `{{EPIC_ID}}` | `""` | Parent epic ID |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` | Output directory |
+| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` | Manifest location |
+
+---
+
+## Error Handling
+
+### Status Classification
+
+| Status | Condition | Action |
+|--------|-----------|--------|
+| `complete` | All objectives achieved | Write full output |
+| `partial` | Some objectives achieved | Write partial, populate `needs_followup` |
+| `blocked` | Cannot proceed | Document blocker, do NOT complete task |
+
+### Retryable Errors
+
+Exit codes 7, 20, 21, 22, 60-63 support retry with exponential backoff.
+
+---
+
+## Anti-Patterns
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Returning content | Bloats orchestrator context | Write to file, return summary |
+| Pretty-printed JSON | Multiple lines in manifest | Single-line JSON only |
+| Skipping focus | Protocol violation | Always `cleo focus set` first |
+| Loading skills via `@` | Cannot resolve | Skills injected by orchestrator |

package/templates/archive.template.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "../schemas/archive.schema.json",
+  "version": "{{SCHEMA_VERSION_ARCHIVE}}",
+  "project": "{{PROJECT_NAME}}",
+  "_meta": {
+    "schemaVersion": "{{SCHEMA_VERSION_ARCHIVE}}",
+    "totalArchived": 0,
+    "lastArchived": null,
+    "oldestTask": null,
+    "newestTask": null
+  },
+  "archivedTasks": [],
+  "statistics": {
+    "byPhase": {},
+    "byPriority": {
+      "critical": 0,
+      "high": 0,
+      "medium": 0,
+      "low": 0
+    },
+    "byLabel": {},
+    "averageCycleTime": null
+  }
+}

package/templates/ci/circleci/config.yml

@@ -0,0 +1,96 @@
+# CircleCI Release Configuration
+# Auto-generated by: cleo release init-ci
+# Platform: CircleCI
+# Artifact Type: {{ARTIFACT_TYPE}}
+# Version: {{VERSION}}
+
+version: 2.1
+
+orbs:
+  node: circleci/node@5.1.0
+
+executors:
+  default:
+    docker:
+      - image: cimg/base:stable
+    working_directory: ~/project
+
+commands:
+  setup_environment:
+    description: "Setup build environment"
+    steps:
+      - checkout
+      - run:
+          name: Setup
+          command: |
+            echo "Setting up environment..."
+            # Environment setup goes here
+
+jobs:
+  validate:
+    executor: default
+    steps:
+      - setup_environment
+      - run:
+          name: Run Validation Gates
+          command: |
+            echo "Running validation gates..."
+{{GATES}}
+
+  build:
+    executor: default
+    steps:
+      - setup_environment
+      - run:
+          name: Build Artifacts
+          command: |
+            echo "Building artifacts..."
+            # Build commands go here
+      - persist_to_workspace:
+          root: .
+          paths:
+            - dist
+            - "*.tar.gz"
+
+  publish:
+    executor: default
+    steps:
+      - setup_environment
+      - attach_workspace:
+          at: ~/project
+      - run:
+          name: Publish Artifacts
+          command: |
+            echo "Publishing artifacts..."
+            # Publish commands go here
+      - store_artifacts:
+          path: dist
+          destination: release-artifacts
+
+workflows:
+  version: 2
+  release:
+    jobs:
+      - validate:
+          filters:
+            tags:
+              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
+            branches:
+              ignore: /.*/
+      - build:
+          requires:
+            - validate
+          filters:
+            tags:
+              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
+            branches:
+              ignore: /.*/
+      - publish:
+          requires:
+            - build
+          context: production
+          filters:
+            tags:
+              only: /^v[0-9]+\.[0-9]+\.[0-9]+$/
+            branches:
+              ignore: /.*/

package/templates/ci/github-actions/release.yml

@@ -0,0 +1,91 @@
+# GitHub Actions Release Workflow
+# Auto-generated by: cleo release init-ci
+# Platform: GitHub Actions
+# Artifact Type: {{ARTIFACT_TYPE}}
+# Version: {{VERSION}}
+
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., 1.0.0)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write  # Required for OIDC/Trusted Publishing
+
+jobs:
+  validate:
+    name: Validation Gates
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Environment
+        run: |
+          echo "Setting up build environment..."
+          # Environment-specific setup goes here
+
+{{GATES}}
+
+  build:
+    name: Build Artifacts
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build
+        run: |
+          echo "Building artifacts..."
+          # Build commands go here
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-artifacts
+          path: |
+            dist/
+            *.tar.gz
+
+  publish:
+    name: Publish Release
+    runs-on: ubuntu-latest
+    needs: build
+    environment: production
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-artifacts
+
+      - name: Publish
+        run: |
+          echo "Publishing artifacts..."
+          # Publish commands go here
+        env:
+          # Add secrets as needed
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: |
+            dist/*
+            *.tar.gz
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}