@cleocode/cleo 2026.2.5 → 2026.2.6

package/packages/ct-skills/skills/ct-docs-write/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ct-docs-write
+description: This skill should be used when creating, editing, or reviewing documentation files (markdown, MDX, README, guides). Use when the user asks to "write docs", "create documentation", "edit the README", "improve doc clarity", "make docs more readable", "follow the style guide", or "write user-facing content". Applies CLEO's conversational, clear, and user-focused writing style.
+version: 1.0.0
+tier: 3
+core: false
+category: composition
+protocol: null
+dependencies: []
+sharedResources: []
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Documentation Writing Skill
+
+@skills/_shared/cleo-style-guide.md
+
+## When writing documentation
+
+### Start here
+
+1. **Who is this for?** Match complexity to audience. Don't oversimplify hard things or overcomplicate simple ones.
+2. **What do they need?** Get them to the answer fast. Nobody wants to be in docs longer than necessary.
+3. **What did you struggle with?** Those common questions you had when learning? Answer them (without literally including the question).
+
+### Writing process
+
+**Draft:**
+
+- Write out the steps/explanation as you'd tell a colleague
+- Lead with what to do, then explain why
+- Use headings that state your point: "Set SAML before adding users" not "SAML configuration timing"
+
+**Edit:**
+
+- Read aloud. Does it sound like you talking? If it's too formal, simplify.
+- Cut anything that doesn't directly help the reader
+- Check each paragraph has one clear purpose
+- Verify examples actually work (don't give examples that error)
+
+**Polish:**
+
+- Make links descriptive (never "here")
+- Backticks only for code/variables, **bold** for UI elements
+- American spelling, serial commas
+- Keep images minimal and scoped tight
+
+**Format:**
+
+- Run prettier on the file after making edits: `yarn prettier --write <file-path>`
+- This ensures consistent formatting across all documentation
+
+### Common patterns
+
+**Instructions:**
+
+```markdown
+Run:
+\`\`\`
+command-to-run
+\`\`\`
+
+Then:
+\`\`\`
+next-command
+\`\`\`
+
+This ensures you're getting the latest changes.
+```
+
+Not: "(remember to run X before Y...)" buried in a paragraph.
+
+**Headings:**
+
+- "Use environment variables for configuration" ✅
+- "Environment variables" ❌ (too vague)
+- "How to use environment variables for configuration" ❌ (too wordy)
+
+**Links:**
+
+- "Check out the [SAML documentation](link)" ✅
+- "Read the docs [here](link)" ❌
+
+### Watch out for
+
+- Describing tasks as "easy" (you don't know the reader's context)
+- Using "we" when talking about CLEO features (use "CLEO" or "it")
+- Formal language: "utilize", "reference", "offerings"
+- Too peppy: multiple exclamation points
+- Burying the action in explanation
+- Code examples that don't work
+- Numbers that will become outdated
+
+### Quick reference
+
+| Write This                 | Not This           |
+| -------------------------- | ------------------ |
+| people, companies          | users              |
+| summarize                  | aggregate          |
+| take a look at             | reference          |
+| can't, don't               | cannot, do not     |
+| **Filter** button          | \`Filter\` button  |
+| Check out [the docs](link) | Click [here](link) |

package/packages/ct-skills/skills/ct-documentor/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: ct-documentor
+description: Documentation creation, editing, and review with CLEO style guide compliance. Coordinates specialized skills for lookup, writing, and review. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.
+version: 3.0.0
+tier: 3
+core: false
+category: specialist
+protocol: null
+dependencies:
+  - ct-docs-lookup
+  - ct-docs-write
+  - ct-docs-review
+sharedResources:
+  - subagent-protocol-base
+  - task-system-integration
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Documentation Specialist Context Injection
+
+**Protocol**: @protocols/implementation.md
+**Type**: Context Injection (cleo-subagent)
+**Version**: 3.0.0
+
+---
+
+## Purpose
+
+Context injection for documentation tasks spawned via cleo-subagent. Orchestrates documentation workflows by coordinating specialized skills for lookup, writing, and review.
+
+---
+
+## Skill Coordination
+
+| Skill | Purpose | Invoke When |
+|-------|---------|-------------|
+| `ct-docs-lookup` | Query existing docs, find references | Discovery phase, checking what exists |
+| `ct-docs-write` | Create/edit docs with CLEO style | Writing or updating content |
+| `ct-docs-review` | Check compliance with style guide | Quality validation before completion |
+
+---
+
+## Core Principle: MAINTAIN, DON'T DUPLICATE
+
+```
+BEFORE creating ANY new file, you MUST:
+1. Search for existing documentation on the topic
+2. Identify the canonical location for this information
+3. UPDATE the existing file instead of creating a new one
+4. Only create new files when NO suitable location exists
+```
+
+---
+
+## Workflow Phases
+
+### Phase 1: Discovery (MANDATORY)
+
+Before writing anything, discover what exists:
+
+```bash
+# List documentation structure
+Glob: pattern="docs/**/*.md"
+
+# Search for existing content on topic
+Grep: pattern="{TOPIC_KEYWORDS}" path="docs/"
+
+# Check for related files
+Grep: pattern="{RELATED_TERMS}" path="docs/" output_mode="files_with_matches"
+```
+
+**Invoke `/ct-docs-lookup`** for deeper documentation research.
+
+### Phase 2: Assess
+
+| Question | Action |
+|----------|--------|
+| Does a doc file for this topic exist? | UPDATE that file |
+| Is the info scattered across files? | CONSOLIDATE into canonical location |
+| Is there a related doc that should include this? | ADD section to that file |
+| Is this truly new with no home? | CREATE minimal new file |
+
+### Phase 3: Write/Update
+
+**Invoke `/ct-docs-write`** for content creation.
+
+**For EXISTING files:**
+1. Read the current content
+2. Identify the correct section for new info
+3. Add/update content IN PLACE
+4. Preserve existing structure
+5. Update any version numbers or dates
+
+**For CONSOLIDATION:**
+1. Identify all files with related content
+2. Choose the canonical location
+3. Move content to canonical file
+4. Add deprecation notices to old locations
+5. Update cross-references
+
+**For NEW files (last resort):**
+1. Confirm no existing location is suitable
+2. Follow project's doc structure conventions
+3. Add to appropriate docs/ subdirectory
+4. Update any index or TOC files
+5. Keep minimal - single topic focus
+
+### Phase 4: Review
+
+**Invoke `/ct-docs-review`** for quality validation.
+
+Checklist:
+- [ ] No formal language ("utilize", "offerings", "cannot")
+- [ ] "People/companies" not "users"
+- [ ] No excessive exclamation points
+- [ ] Important information leads, not buried
+- [ ] No verbose text without value
+- [ ] Headings state the point
+- [ ] Descriptive link text (never "here")
+- [ ] No "easy" or "simple"
+- [ ] Code examples actually work
+
+---
+
+## Anti-Duplication Checklist
+
+Before completing, verify:
+
+- [ ] Searched for existing docs on this topic
+- [ ] Did NOT create a file that duplicates existing content
+- [ ] Updated existing file if one existed
+- [ ] Added deprecation notice if consolidating
+- [ ] Cross-references are updated
+- [ ] No orphaned documentation created
+
+---
+
+## Task System Integration
+
+@skills/_shared/task-system-integration.md
+
+### Task Workflow
+
+```bash
+# 1. Read task details
+cleo show {TASK_ID}
+
+# 2. Start task
+cleo start {TASK_ID}
+
+# 3. Execute documentation workflow (phases 1-4)
+
+# 4. Complete task when done
+cleo complete {TASK_ID}
+
+# 5. Link research if applicable
+cleo research link {TASK_ID} {RESEARCH_ID}
+```
+
+---
+
+## Subagent Protocol
+
+@skills/_shared/subagent-protocol-base.md
+
+### Output Requirements
+
+1. MUST write documentation output to: `{{OUTPUT_DIR}}/`
+2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+3. MUST return ONLY: "Documentation complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return documentation content in response
+
+### Output File Format
+
+Write to `{{OUTPUT_DIR}}/`:
+
+```markdown
+# Documentation Update: {TITLE}
+
+**Date**: {DATE} | **Agent**: ct-documentor | **Status**: complete
+
+---
+
+## Summary
+
+{What was updated and why}
+
+## Changes Made
+
+### File: {path/to/file.md}
+- {Change 1}
+- {Change 2}
+
+## Files NOT Created (Avoided Duplication)
+
+- {Considered creating X but updated Y instead}
+- {Found existing coverage in Z}
+
+## Verification
+
+- [ ] Changes don't duplicate existing content
+- [ ] Cross-references updated
+- [ ] Examples tested
+- [ ] Style guide compliance verified via ct-docs-review
+```
+
+### Manifest Entry
+
+Append ONE line to `{{MANIFEST_PATH}}`:
+
+```json
+{"id":"docs-{TOPIC}-{DATE}","file":"{DATE}_docs-{TOPIC}.md","title":"Documentation Update: {TITLE}","date":"{DATE}","status":"complete","agent_type":"documentation","topics":["documentation","{topic}"],"key_findings":["Updated {file} with {change}","Consolidated {topic} docs into {canonical-location}","Avoided duplication by updating existing {file}"],"actionable":false,"needs_followup":[],"linked_tasks":["{TASK_ID}"]}
+```
+
+---
+
+## Completion Requirements
+
+- [ ] Discovery phase completed (searched existing docs)
+- [ ] Core principle followed (maintain, don't duplicate)
+- [ ] `/ct-docs-write` invoked for content creation
+- [ ] `/ct-docs-review` invoked for quality validation
+- [ ] Anti-duplication checklist verified
+- [ ] Output file written with "Files NOT Created" section
+- [ ] Manifest entry appended
+- [ ] Task completed via `cleo complete`

package/packages/ct-skills/skills/ct-epic-architect/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: ct-epic-architect
+description: Epic planning and task decomposition for breaking down large initiatives into atomic, executable tasks. Provides dependency analysis, wave-based parallel execution planning, hierarchy management, and research linking. Use when creating epics, decomposing initiatives into task trees, planning parallel workflows, or analyzing task dependencies. Triggers on epic creation, task decomposition requests, or planning phase work.
+version: 3.0.0
+tier: 1
+core: false
+category: recommended
+protocol: decomposition
+dependencies: []
+sharedResources:
+  - subagent-protocol-base
+  - task-system-integration
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Epic Architect Context Injection
+
+**Protocol**: @protocols/decomposition.md
+**Type**: Context Injection (cleo-subagent)
+**Version**: 3.0.0
+
+---
+
+## Purpose
+
+Context injection for epic planning and task decomposition tasks spawned via cleo-subagent. Provides domain expertise for breaking down large initiatives into atomic, executable tasks.
+
+---
+
+## Capabilities
+
+1. **Epic Creation** - Parent epic with full metadata and file attachments
+2. **Task Decomposition** - Atomic tasks with acceptance criteria
+3. **Dependency Analysis** - Wave-based parallel execution planning
+4. **Research Linking** - Connect research outputs to tasks
+5. **HITL Clarification** - Ask when requirements are ambiguous
+
+---
+
+## Task System Integration
+
+@skills/_shared/task-system-integration.md
+
+### Execution Sequence
+
+1. Read task: `cleo show {{TASK_ID}}`
+2. Start task: `cleo start {{TASK_ID}}`
+3. Check existing work: `cleo find "keyword"`, `cleo list --type epic`
+4. Create epic and child tasks
+5. Attach files and link research
+6. Start session: `cleo session start --scope epic:{{EPIC_ID}} --auto-start`
+7. Complete task: `cleo complete {{TASK_ID}}`
+
+---
+
+## Requirements Analysis
+
+**MUST check for related work BEFORE creating:**
+
+```bash
+cleo find "auth" --status pending       # Related tasks
+cleo list --type epic --status pending  # Existing epics
+cleo phase show                         # Current phase
+cleo list --tree --parent T001          # Hierarchy view
+```
+
+---
+
+## Epic Structure
+
+```
+Epic (type: epic, size: large)
+├── Task 1 (no deps)           [Wave 0]
+├── Task 2 (depends: T1)       [Wave 1]
+├── Task 3 (depends: T1)       [Wave 1]  ← Parallel
+├── Task 4 (depends: T2,T3)    [Wave 2]  ← Convergence
+└── Task 5 (depends: T4)       [Wave 3]
+```
+
+### Size Guidelines (NOT Time)
+
+| Type | Size | Scope |
+|------|------|-------|
+| Epic | large | 8+ files, multiple features |
+| Task | medium | 3-7 files, single feature |
+| Subtask | small | 1-2 files, single function |
+
+---
+
+## Epic Creation
+
+### Create Epic with File Attachments
+
+```bash
+cleo add "Auth System Implementation" \
+  --type epic --size large --priority high --phase core \
+  --labels "feature,auth,v1.0" \
+  --description "Complete authentication with JWT and session management" \
+  --acceptance "All child tasks completed" \
+  --acceptance "Integration tests pass" \
+  --files "docs/auth-spec.md,docs/api-design.md" \
+  --notes "Initial planning: JWT chosen for stateless API support"
+```
+
+### Create Tasks with Dependencies
+
+```bash
+# Wave 0: No dependencies
+cleo add "Create auth schema" \
+  --type task --size medium --priority high \
+  --parent T001 --phase setup \
+  --description "Define user, session, and token tables" \
+  --acceptance "Schema validates against requirements" \
+  --files "src/db/schema.ts"
+
+# Wave 1: Depends on Wave 0
+cleo add "Implement JWT middleware" \
+  --type task --size medium --priority high \
+  --parent T001 --phase core --depends T002 \
+  --description "Token generation, validation, refresh" \
+  --acceptance "All token operations tested"
+
+# Wave 2: Convergence
+cleo add "Integration tests" \
+  --type task --size medium --priority high \
+  --parent T001 --phase testing --depends T003,T004 \
+  --acceptance "E2E auth flow tests pass"
+```
+
+### Link Research to Tasks
+
+```bash
+# Link existing research output to task
+cleo research link T001 research-auth-patterns-20260126
+
+# View linked research
+cleo show T001  # Shows .linkedResearch array
+```
+
+---
+
+## File Attachment Patterns
+
+### When to Use --files vs Research Link
+
+| Method | Use Case | Storage |
+|--------|----------|---------|
+| `--files` | Input context (specs, designs, code) | Task `.files` array |
+| `research link` | Output artifacts (research findings) | Task `.linkedResearch` array |
+
+### Attach Files During Creation
+
+```bash
+cleo add "Implement auth" --files "spec.md,design.md"
+```
+
+### Append Files to Existing Task
+
+```bash
+cleo update T001 --files "additional-context.md"
+```
+
+---
+
+## Hierarchy Constraints
+
+| Constraint | Value | Enforcement |
+|------------|-------|-------------|
+| Max depth | 3 | epic (0) → task (1) → subtask (2) |
+| Max active siblings | 8 (default) | `hierarchy.maxActiveSiblings` |
+| Max siblings | unlimited (default) | `hierarchy.maxSiblings=0` |
+| Parent must exist | Validated | `cleo exists {{PARENT_ID}}` |
+
+**Validation Before Creation:**
+
+```bash
+cleo exists T001 --quiet || echo "ERROR: Parent not found"
+cleo list --parent T001 --status pending,active | jq '.tasks | length'
+```
+
+---
+
+## Wave Planning
+
+| Wave | Description | Execution |
+|------|-------------|-----------|
+| Wave 0 | No dependencies | Start immediately |
+| Wave 1 | Depends on Wave 0 | Parallel within wave |
+| Wave N | Depends on prior waves | Convergence points |
+
+### Dependency Rules
+
+1. No circular dependencies (A→B→C→A invalid)
+2. Wave siblings are independent (no cross-dependencies)
+3. Convergence depends on ALL branches
+
+---
+
+## Phase Assignment
+
+| Phase | Purpose |
+|-------|---------|
+| `setup` | Schema, config, structure |
+| `core` | Features, components |
+| `testing` | Tests, validation |
+| `polish` | Docs, optimization |
+| `maintenance` | Fixes, updates |
+
+```bash
+cleo phase show                              # Current phase
+cleo list --phase $(cleo phase show -q)      # Tasks in phase
+```
+
+---
+
+## HITL Clarification
+
+**Ask when:**
+- Requirements ambiguous
+- Multiple valid approaches
+- Missing context
+- Scope unclear
+
+**Template:**
+```
+Before proceeding, I need clarification:
+1. [Question about scope]
+2. [Question about constraints]
+
+Options:
+A. [Option with trade-offs]
+B. [Option with trade-offs]
+
+Recommendation: [Your recommendation]
+```
+
+---
+
+## Subagent Protocol
+
+@skills/_shared/subagent-protocol-base.md
+
+### Output Requirements
+
+1. MUST write decomposition to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
+2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+3. MUST return ONLY: "Decomposition complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return full decomposition in response
+
+---
+
+## Extended References
+
+| Reference | Content |
+|-----------|---------|
+| [patterns.md](references/patterns.md) | Research, Bug, Brownfield, Refactor patterns |
+| [commands.md](references/commands.md) | Complete CLEO command reference |
+| [shell-escaping.md](references/shell-escaping.md) | Escape `$` as `\$` in notes |
+| [feature-epic-example.md](references/feature-epic-example.md) | Greenfield feature |
+| [refactor-epic-example.md](references/refactor-epic-example.md) | Brownfield modernization |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Solution |
+|--------------|----------|
+| Too large tasks | Atomic (one agent session) |
+| Missing Wave 0 | At least one no-dependency task |
+| Circular deps | Analyze data flow |
+| Depth > 3 | Flatten hierarchy |
+| Missing acceptance | Add `--acceptance` |
+| Time estimates | Use size only |
+
+---
+
+## Completion Checklist
+
+- [ ] Checked existing work (`cleo find`, `cleo list --type epic`)
+- [ ] Phase verified (`cleo phase show`)
+- [ ] Epic created with priority, phase, acceptance
+- [ ] Tasks with dependencies, no circular deps
+- [ ] Wave 0 exists (at least one no-deps task)
+- [ ] Hierarchy: depth ≤ 3, siblings ≤ 8 active
+- [ ] Files attached where relevant
+- [ ] Session started scoped to epic
+
+---
+
+## Error Handling
+
+| Exit | Meaning | Fix |
+|------|---------|-----|
+| 4 | Not found | `cleo find` to verify |
+| 10 | Parent missing | `cleo exists {{ID}}` |
+| 11 | Depth exceeded | Flatten (epic→task→subtask max) |
+| 12 | Sibling limit | Split to different parent |
+| 6 | Validation | Escape `$` as `\$`, check fields |
+
+**Shell Escaping**: Always `\$` in `--notes`/`--description`. See [shell-escaping.md](references/shell-escaping.md).