@cleocode/cleo 2026.2.9 → 2026.3.0

package/skills/_shared/subagent-protocol-base.md

@@ -1,221 +0,0 @@
-# Subagent Protocol Base Reference
-
-**Provenance**: @task T3155, @epic T3147
-**Version**: 1.0.1
-**Updated**: 2026-02-07
-
-This reference defines the RFC 2119 protocol for subagent output and handoff.
-All subagents operating under an orchestrator MUST follow this protocol.
-
----
-
-## Output Requirements (RFC 2119)
-
-### Mandatory Rules
-
-| ID | Rule | Compliance |
-|----|------|------------|
-| OUT-001 | MUST write findings to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md` | Required |
-| OUT-002 | MUST append ONE line to `{{MANIFEST_PATH}}` | Required |
-| OUT-003 | MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary." | Required |
-| OUT-004 | MUST NOT return research content in response | Required |
-
-### Rationale
-
-- **OUT-001**: Persistent storage for orchestrator and future agents
-- **OUT-002**: Manifest enables O(1) lookup of key findings
-- **OUT-003**: Minimal response preserves orchestrator context
-- **OUT-004**: Full content would bloat orchestrator context window
-
----
-
-## Output File Format
-
-Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
-
-```markdown
-# {{TITLE}}
-
-## Summary
-
-{{2-3 sentence overview}}
-
-## Findings
-
-### {{Category 1}}
-
-{{Details}}
-
-### {{Category 2}}
-
-{{Details}}
-
-## Recommendations
-
-{{Action items}}
-
-## Sources
-
-{{Citations/references}}
-
-## Linked Tasks
-
-- Epic: {{EPIC_ID}}
-- Task: {{TASK_ID}}
-```
-
----
-
-## Manifest Entry Format
-
-@skills/_shared/manifest-operations.md
-
-Use `cleo research add` to create manifest entries instead of manual JSONL appends.
-
-**Quick Reference**:
-```bash
-cleo research add \
-  --title "{{TITLE}}" \
-  --file "{{DATE}}_{{TOPIC_SLUG}}.md" \
-  --topics "topic1,topic2,topic3" \
-  --findings "Finding 1,Finding 2,Finding 3" \
-  --status complete \
-  --task {{TASK_ID}} \
-  --agent-type research
-```
-
-See the reference above for:
-- Complete CLI command syntax
-- Field definitions and constraints
-- Agent type values (RCSD-IVTR + workflow types)
-- Manifest entry schema
-- Anti-patterns to avoid
-
----
-
-## Task Lifecycle Integration
-
-Reference: @skills/_shared/task-system-integration.md
-
-### Execution Sequence
-
-```
-1. Read task:    {{TASK_SHOW_CMD}} {{TASK_ID}}
-2. Start task:   {{TASK_START_CMD}} {{TASK_ID}}
-3. Do work:      [skill-specific execution]
-4. Write output: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
-5. Create manifest entry: cleo research add [flags]
-6. Complete:     {{TASK_COMPLETE_CMD}} {{TASK_ID}}
-7. Return:       "Research complete. See MANIFEST.jsonl for summary."
-```
-
----
-
-## Research Linking
-
-### Link Research to Task
-
-```bash
-{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}
-```
-
-**Purpose**: Associate research output with originating task for bidirectional discovery.
-
-**CLEO Default**: `cleo research link {{TASK_ID}} {{RESEARCH_ID}}`
-
-**When to Link**:
-- SHOULD link after writing research output to manifest
-- SHOULD link when research directly supports task objectives
-- MAY skip if research is exploratory/tangential
-
-### Verify Link
-
-```bash
-{{TASK_SHOW_CMD}} {{TASK_ID}}
-# Check: linkedResearch array contains research ID
-```
-
-### Benefits
-
-| Benefit | Description |
-|---------|-------------|
-| Bidirectional discovery | Task → Research and Research → Task |
-| Context preservation | Future agents can find prior research |
-| Audit trail | Complete record of work artifacts |
-
----
-
-## Completion Checklist
-
-Before returning, verify:
-
-- [ ] Task started via `{{TASK_START_CMD}}`
-- [ ] Output file written to `{{OUTPUT_DIR}}/`
-- [ ] Manifest entry created via `cleo research add`
-- [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
-- [ ] Response is ONLY the summary message
-
----
-
-## Token Reference
-
-### Required Tokens (MUST be provided)
-
-| Token | Description | Example |
-|-------|-------------|---------|
-| `{{TASK_ID}}` | Current task identifier | `T1234` |
-| `{{DATE}}` | Current date | `2026-01-19` |
-| `{{TOPIC_SLUG}}` | URL-safe topic name | `authentication-research` |
-
-### Optional Tokens (defaults available)
-
-| Token | Default | Description |
-|-------|---------|-------------|
-| `{{EPIC_ID}}` | `""` | Parent epic ID |
-| `{{SESSION_ID}}` | `""` | Session identifier |
-| `{{OUTPUT_DIR}}` | `claudedocs/agent-outputs` | Output directory |
-| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` | Manifest location |
-
-### Task System Tokens (CLEO defaults)
-
-| Token | CLEO Default |
-|-------|--------------|
-| `{{TASK_SHOW_CMD}}` | `cleo show` |
-| `{{TASK_START_CMD}}` | `cleo start` |
-| `{{TASK_COMPLETE_CMD}}` | `cleo complete` |
-| `{{TASK_LINK_CMD}}` | `cleo research link` |
-
----
-
-## Error Handling
-
-### Partial Completion
-
-If work cannot complete fully:
-
-1. Write partial findings to output file
-2. Set manifest `"status": "partial"`
-3. Add blocking reason to `needs_followup`
-4. Complete task (partial work is still progress)
-5. Return: "Research partial. See MANIFEST.jsonl for details."
-
-### Blocked Status
-
-If work cannot proceed:
-
-1. Write blocking analysis to output file
-2. Set manifest `"status": "blocked"`
-3. Add blocker details to `needs_followup`
-4. Do NOT complete task (leave for orchestrator decision)
-5. Return: "Research blocked. See MANIFEST.jsonl for blocker details."
-
----
-
-## Anti-Patterns
-
-| Pattern | Problem | Solution |
-|---------|---------|----------|
-| Returning full content | Bloats orchestrator context | Return only summary message |
-| Manual JSONL append | No validation, race conditions | Use `cleo research add` |
-| Missing manifest entry | Orchestrator can't find findings | Always create manifest entry |
-| Incomplete checklist | Protocol violation | Verify all items before return |

package/skills/_shared/task-system-integration.md

@@ -1,232 +0,0 @@
-# Task System Integration Reference
-
-This reference defines portable task management commands using dynamic tokens.
-Skills and templates SHOULD reference this file instead of hardcoding CLEO commands.
-
----
-
-## Task Lifecycle Commands
-
-### Read Task Details
-
-```bash
-{{TASK_SHOW_CMD}} {{TASK_ID}}
-```
-
-**Purpose**: Get full task context before starting work.
-
-**CLEO Default**: `cleo show {{TASK_ID}}`
-
-### Start Task
-
-```bash
-{{TASK_START_CMD}} {{TASK_ID}}
-```
-
-**Purpose**: Mark task as active/in-progress.
-
-**CLEO Default**: `cleo start {{TASK_ID}}`
-
-### Complete Task
-
-```bash
-{{TASK_COMPLETE_CMD}} {{TASK_ID}}
-```
-
-**Purpose**: Mark task as done after work completes.
-
-**CLEO Default**: `cleo complete {{TASK_ID}}`
-
-### Link Research
-
-```bash
-{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}
-```
-
-**Purpose**: Associate research output with task.
-
-**CLEO Default**: `cleo research link {{TASK_ID}} {{RESEARCH_ID}}`
-
----
-
-## Query Commands
-
-### List Tasks
-
-```bash
-{{TASK_LIST_CMD}} [--status STATUS] [--parent EPIC_ID]
-```
-
-**CLEO Default**: `cleo list`
-
-### Find Tasks
-
-```bash
-{{TASK_FIND_CMD}} "query"
-```
-
-**CLEO Default**: `cleo find`
-
-### Add Task
-
-```bash
-{{TASK_ADD_CMD}} "Title" [OPTIONS]
-```
-
-**CLEO Default**: `cleo add`
-
----
-
-## File Attachment
-
-### Attach Files to Task
-
-```bash
-{{TASK_ADD_CMD}} "Title" --files "path1,path2"
-```
-
-Or update existing task:
-
-```bash
-cleo update {{TASK_ID}} --files "path1,path2"
-```
-
-**Purpose**: Attach context files for agent reference.
-
-**CLEO Default**: `cleo add/update --files "paths"`
-
-**Storage**: `.files` array in task JSON
-
-### When to Use --files vs Research Link
-
-| Method | Use Case | Storage |
-|--------|----------|---------|
-| `--files` | Reference existing docs, code files | Task `.files` array |
-| `research link` | Connect subagent research outputs | Task `.linkedResearch` array |
-
-### Guidelines
-
-- **SHOULD** use `--files` for input context (specs, designs, code files)
-- **SHOULD** use `research link` for output artifacts (research findings)
-- **MAY** combine both for comprehensive task context
-
----
-
-## CLEO-Specific Extensions
-
-When the task system is CLEO, these additional commands are available:
-
-| Command | Purpose |
-|---------|---------|
-| `cleo current` | Show current active task |
-| `cleo session start` | Begin work session |
-| `cleo session end` | End work session |
-| `cleo analyze` | Task triage with scoring |
-| `cleo deps {{TASK_ID}}` | Check task dependencies |
-| `cleo tree --parent {{EPIC_ID}}` | Visualize hierarchy |
-
-### Session Lifecycle
-
-Sessions persist across Claude conversations and support long-running work.
-
-**Key Behaviors**:
-- Sessions receive timeout warning after **72 hours** of inactivity
-- Active sessions are auto-ended after **7 days** (configurable via `retention.autoEndActiveAfterDays`)
-- Ended/suspended sessions can be cleaned up with `cleo session gc`
-- Stale active sessions (72h+) cleaned with `cleo session gc --include-active`
-
-**Session Commands**:
-
-| Command | Purpose |
-|---------|---------|
-| `cleo session start --scope epic:{{EPIC_ID}}` | Begin scoped session |
-| `cleo session end --note "summary"` | End session properly |
-| `cleo session list` | Check existing sessions |
-| `cleo session resume <id>` | Resume previous session |
-| `cleo session gc` | Clean up ended/suspended sessions |
-| `cleo session gc --include-active` | Also clean stale active sessions |
-
-**Best Practices**:
-- **MUST** check `cleo session list` before starting new sessions
-- **SHOULD** end sessions properly with `cleo session end --note "summary"` to avoid accumulation
-- **SHOULD** use `cleo session gc` periodically to clean up old ended/suspended sessions
-- **MAY** use `cleo session gc --include-active` to clean stale active sessions (72h+ inactive)
-- Long-running sessions (multi-day work) are expected and supported
-
----
-
-## Token Defaults
-
-When tokens are not explicitly configured, assume CLEO defaults:
-
-| Token | Default Value |
-|-------|---------------|
-| `{{TASK_SHOW_CMD}}` | `cleo show` |
-| `{{TASK_START_CMD}}` | `cleo start` |
-| `{{TASK_COMPLETE_CMD}}` | `cleo complete` |
-| `{{TASK_LINK_CMD}}` | `cleo research link` |
-| `{{TASK_LIST_CMD}}` | `cleo list` |
-| `{{TASK_FIND_CMD}}` | `cleo find` |
-| `{{TASK_ADD_CMD}}` | `cleo add` |
-| `{{OUTPUT_DIR}}` | `claudedocs/agent-outputs` |
-| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` |
-
----
-
-## Usage in Skills
-
-Reference this file from SKILL.md:
-
-```markdown
-### Task System Integration
-
-@skills/_shared/task-system-integration.md
-
-Execute lifecycle commands:
-1. Read task: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
-2. Start task: `{{TASK_START_CMD}} {{TASK_ID}}`
-3. Complete: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
-```
-
----
-
-## Usage in Templates
-
-Include task lifecycle section in templates:
-
-```markdown
-### Task Lifecycle
-
-1. MUST read task details: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
-2. MUST start task: `{{TASK_START_CMD}} {{TASK_ID}}`
-3. MUST complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
-4. SHOULD link research: `{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}`
-```
-
----
-
-## Non-CLEO Configurations
-
-### Linear
-
-```yaml
-TASK_SHOW_CMD: "linear issue view"
-TASK_START_CMD: "linear issue update --status in-progress"
-TASK_COMPLETE_CMD: "linear issue update --status done"
-```
-
-### Jira
-
-```yaml
-TASK_SHOW_CMD: "jira issue view"
-TASK_START_CMD: "jira issue move --status 'In Progress'"
-TASK_COMPLETE_CMD: "jira issue move --status 'Done'"
-```
-
-### GitHub Issues
-
-```yaml
-TASK_SHOW_CMD: "gh issue view"
-TASK_START_CMD: "gh issue edit --add-label 'in-progress'"
-TASK_COMPLETE_CMD: "gh issue close"
-```

package/skills/_shared/testing-framework-config.md

@@ -1,110 +0,0 @@
-# Testing Framework Configuration
-
-CLEO supports 16 testing frameworks. Configure your project's testing setup in `.cleo/config.json`:
-
-## Framework Examples
-
-### Node.js with Vitest (TypeScript)
-```json
-{
-  "validation": {
-    "testing": {
-      "framework": "vitest",
-      "command": "vitest run",
-      "directory": "tests",
-      "testFilePatterns": ["**/*.test.ts"]
-    }
-  }
-}
-```
-
-### Node.js with Jest
-```json
-{
-  "validation": {
-    "testing": {
-      "framework": "jest",
-      "command": "jest --passWithNoTests",
-      "testFilePatterns": ["**/*.test.js", "**/*.spec.js"]
-    }
-  }
-}
-```
-
-### Python with pytest
-```json
-{
-  "validation": {
-    "testing": {
-      "framework": "pytest",
-      "command": "pytest -v",
-      "directory": "tests",
-      "testFilePatterns": ["**/test_*.py"]
-    }
-  }
-}
-```
-
-### Rust with Cargo
-```json
-{
-  "validation": {
-    "testing": {
-      "framework": "cargo",
-      "command": "cargo test"
-    }
-  }
-}
-```
-
-### Go
-```json
-{
-  "validation": {
-    "testing": {
-      "framework": "go",
-      "command": "go test ./..."
-    }
-  }
-}
-```
-
-## Supported Frameworks
-
-| Framework | Extension | Ecosystem |
-|-----------|-----------|-----------|
-| bats | .bats | Bash |
-| jest, vitest, playwright, cypress, mocha, ava, uvu, tap | .test.js/.ts | Node.js |
-| node:test, deno, bun | .test.ts | Runtime built-ins |
-| pytest | _test.py | Python |
-| go | _test.go | Go |
-| cargo | .rs | Rust |
-| custom | varies | Any |
-
-## Validation Gates
-
-Enable test validation before releases:
-```json
-{
-  "validation": {
-    "testing": {
-      "requirePassingTests": true,
-      "runOnComplete": true
-    }
-  }
-}
-```
-
-## Auto-Detection
-
-Run `cleo init --detect` to automatically configure your project based on manifest files (package.json, Cargo.toml, pyproject.toml, etc.).
-
-```bash
-# Preview detection
-cleo init --detect --dry-run
-
-# Apply configuration
-cleo init --detect
-```
-
-See `docs/guides/project-config.mdx` for full documentation.

package/skills/agentskills-integrate.md

@@ -1,104 +0,0 @@
-# Integrate skills into your agent
-
-> How to add Agent Skills support to your agent or tool.
-
-This guide explains how to add skills support to an AI agent or development tool.
-
-## Integration approaches
-
-The two main approaches to integrating skills are:
-
-**Filesystem-based agents** operate within a computer environment (bash/unix) and represent the most capable option. Skills are activated when models issue shell commands like `cat /path/to/my-skill/SKILL.md`. Bundled resources are accessed through shell commands.
-
-**Tool-based agents** function without a dedicated computer environment. Instead, they implement tools allowing models to trigger skills and access bundled assets. The specific tool implementation is up to the developer.
-
-## Overview
-
-A skills-compatible agent needs to:
-
-1. **Discover** skills in configured directories
-2. **Load metadata** (name and description) at startup
-3. **Match** user tasks to relevant skills
-4. **Activate** skills by loading full instructions
-5. **Execute** scripts and access resources as needed
-
-## Skill discovery
-
-Skills are folders containing a `SKILL.md` file. Your agent should scan configured directories for valid skills.
-
-## Loading metadata
-
-At startup, parse only the frontmatter of each `SKILL.md` file. This keeps initial context usage low.
-
-### Parsing frontmatter
-
-```
-function parseMetadata(skillPath):
-    content = readFile(skillPath + "/SKILL.md")
-    frontmatter = extractYAMLFrontmatter(content)
-
-    return {
-        name: frontmatter.name,
-        description: frontmatter.description,
-        path: skillPath
-    }
-```
-
-### Injecting into context
-
-Include skill metadata in the system prompt so the model knows what skills are available.
-
-Follow your platform's guidance for system prompt updates. For example, for Claude models, the recommended format uses XML:
-
-```xml  theme={null}
-<available_skills>
-  <skill>
-    <name>pdf-processing</name>
-    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
-    <location>/path/to/skills/pdf-processing/SKILL.md</location>
-  </skill>
-  <skill>
-    <name>data-analysis</name>
-    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
-    <location>/path/to/skills/data-analysis/SKILL.md</location>
-  </skill>
-</available_skills>
-```
-
-For filesystem-based agents, include the `location` field with the absolute path to the SKILL.md file. For tool-based agents, the location can be omitted.
-
-Keep metadata concise. Each skill should add roughly 50-100 tokens to the context.
-
-## Security considerations
-
-Script execution introduces security risks. Consider:
-
-* **Sandboxing**: Run scripts in isolated environments
-* **Allowlisting**: Only execute scripts from trusted skills
-* **Confirmation**: Ask users before running potentially dangerous operations
-* **Logging**: Record all script executions for auditing
-
-## Reference implementation
-
-The [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) library provides Python utilities and a CLI for working with skills.
-
-For example:
-
-**Validate a skill directory:**
-
-```
-skills-ref validate <path>
-```
-
-**Generate `<available_skills>` XML for agent prompts:**
-
-```
-skills-ref to-prompt <path>...
-```
-
-Use the library source code as a reference implementation.
-
-
----
-
-> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://agentskills.io/llms.txt