@cleocode/cleo 2026.2.5 → 2026.2.6

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

@@ -0,0 +1,221 @@
+# 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/packages/ct-skills/skills/_shared/task-system-integration.md

@@ -0,0 +1,232 @@
+# 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 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/packages/ct-skills/skills/_shared/testing-framework-config.md

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