@cleocode/skills 2.0.0

package/skills/ct-orchestrator/references/orchestrator-recovery.md

@@ -0,0 +1,113 @@
+# Orchestrator: Error Recovery
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on error handling, recovery procedures, context budget monitoring, or session lifecycle management
+
+## Error Recovery
+
+| Failure | Detection | Recovery |
+|---------|-----------|----------|
+| No output file | `test -f <path>` fails | Re-spawn with clearer instructions |
+| No manifest entry | `{{RESEARCH_SHOW_CMD}}` fails | Manual entry or re-spawn |
+| Task not completed | Status != done | Orchestrator completes manually |
+| Partial status | `status: partial` | Spawn continuation agent |
+| Blocked status | `status: blocked` | Flag for human review |
+
+---
+
+## Context Budget Monitoring
+
+```bash
+# Check current context usage
+cleo orchestrator context
+
+# With specific token count
+cleo orchestrator context --tokens 5000
+```
+
+**Status Thresholds**:
+| Status | Usage | Action |
+|--------|-------|--------|
+| `ok` | <70% | Continue orchestration |
+| `warning` | 70-89% | Delegate current work soon |
+| `critical` | >=90% | STOP - Delegate immediately |
+
+---
+
+## Session Lifecycle Management
+
+Orchestrator sessions may span multiple Claude conversations. This is expected and supported by design.
+
+### Session Timeout and Retention
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Session timeout | 72 hours | Active sessions auto-end after 72h inactivity |
+| Auto-end threshold | 7 days | `retention.autoEndActiveAfterDays` config |
+| Stale session cleanup | Manual | Use `cleo session gc` for cleanup |
+
+**Key points:**
+- Sessions can legitimately span multiple days of work
+- Long-running orchestration work is expected
+- Sessions persist across Claude conversation boundaries
+
+### Cleanup Commands
+
+```bash
+# Standard garbage collection (ended/suspended sessions only)
+cleo session gc
+
+# Include stale active sessions (>7 days old by default)
+cleo session gc --include-active
+
+# Preview what would be cleaned
+cleo session gc --dry-run
+cleo session gc --include-active --dry-run
+```
+
+### Configuration
+
+```bash
+# View current retention settings
+cleo config get retention
+
+# Adjust auto-end threshold for active sessions
+cleo config set retention.autoEndActiveAfterDays 14  # Extend to 2 weeks
+```
+
+### Best Practices
+
+1. **Session end on completion**: Always end sessions when work completes
+   ```bash
+   cleo session end --note "Epic T1575 phase 1 complete"
+   ```
+
+2. **Session suspend for long waits**: Suspend when blocked on external factors
+   ```bash
+   cleo session suspend --note "Awaiting code review"
+   ```
+
+3. **Periodic cleanup**: Run garbage collection periodically to remove stale sessions
+   ```bash
+   cleo session gc --include-active
+   ```
+
+4. **Multi-day work**: No need to restart sessions daily - orchestrator sessions are designed for extended work periods
+
+---
+
+## Validation
+
+```bash
+# Full protocol validation
+cleo orchestrator validate
+
+# Validate for specific epic
+cleo orchestrator validate --epic T1575
+
+# Validate specific subagent output
+cleo orchestrator validate --subagent research-id-2026-01-18
+
+# Manifest only
+cleo orchestrator validate --manifest
+```

package/skills/ct-orchestrator/references/orchestrator-spawning.md

@@ -0,0 +1,271 @@
+# Orchestrator: Subagent Spawning
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on spawning subagents, skill dispatch, template selection, or programmatic spawning workflows
+
+## Subagent Spawning
+
+### Quick Spawn Workflow
+
+```bash
+# 1. Get next ready task
+cleo orchestrator next --epic T1575
+
+# 2. Generate spawn command with prompt
+cleo orchestrator spawn T1586
+
+# 3. Or specify a skill template
+cleo orchestrator spawn T1586 --template ct-research-agent
+cleo orchestrator spawn T1586 --template RESEARCH-AGENT  # aliases work
+```
+
+### Manual Spawn (when CLI spawn unavailable)
+
+Use Task tool with `subagent_type="general-purpose"` and include:
+1. Subagent protocol block (RFC 2119 requirements)
+2. Context from previous agents (manifest `key_findings` ONLY)
+3. Clear task definition and completion criteria
+
+### Spawn Output
+
+The `spawn` command returns:
+- `taskId`: Target task
+- `template`: Skill used
+- `topicSlug`: Slugified topic name
+- `outputFile`: Expected output filename
+- `prompt`: Complete prompt ready for Task tool
+
+---
+
+## Skill Dispatch Rules
+
+Use the appropriate skill for each task type. The `spawn` command accepts skill names in multiple formats.
+
+### Skill Selection Matrix
+
+| Task Type | Skill | Trigger Keywords |
+|-----------|-------|------------------|
+| Generic implementation | `ct-task-executor` | "implement", "execute task", "do the work", "build component" |
+| Research/investigation | `ct-research-agent` | "research", "investigate", "gather info", "explore options" |
+| Epic/project planning | `ct-epic-architect` | "create epic", "plan tasks", "decompose", "wave planning" |
+| Specification writing | `ct-spec-writer` | "write spec", "define protocol", "RFC", "specification" |
+| Test writing (BATS) | `ct-test-writer-bats` | "write tests", "BATS", "bash tests", "integration tests" |
+| Bash library creation | `ct-library-implementer-bash` | "create library", "bash functions", "lib/*.sh" |
+| Compliance validation | `ct-validator` | "validate", "verify", "check compliance", "audit" |
+| Documentation | `ct-documentor` | "write docs", "document", "update README" |
+
+### Skill Name Aliases
+
+The `spawn` command supports multiple name formats:
+
+| Format | Example |
+|--------|---------|
+| Full name | `ct-task-executor`, `ct-research-agent` |
+| Uppercase | `TASK-EXECUTOR`, `RESEARCH-AGENT` |
+| Lowercase | `task-executor`, `research-agent` |
+| Short aliases | `EXECUTOR`, `RESEARCH`, `BATS`, `SPEC` |
+
+### Skill Paths
+
+```
+skills/ct-epic-architect/SKILL.md
+skills/ct-spec-writer/SKILL.md
+skills/ct-research-agent/SKILL.md
+skills/ct-test-writer-bats/SKILL.md
+skills/ct-library-implementer-bash/SKILL.md
+skills/ct-task-executor/SKILL.md
+skills/ct-validator/SKILL.md
+skills/ct-documentor/SKILL.md
+```
+
+---
+
+## Complete Spawning Workflow
+
+### Automated Workflow (Recommended)
+
+```bash
+# Step 1: Get ready task
+cleo orchestrator next --epic T1575
+# Returns: { nextTask: { id: "T1586", title: "...", priority: "high" } }
+
+# Step 2: Generate spawn prompt (handles all token injection)
+spawn_result=$(cleo orchestrator spawn T1586)
+
+# Step 3: Extract prompt and use with Task tool
+prompt=$(echo "$spawn_result" | jq -r '.result.prompt')
+# Pass $prompt to Task tool
+```
+
+---
+
+## Programmatic Spawning with orchestrator_spawn_for_task()
+
+For advanced automation, use the `orchestrator_spawn_for_task()` function from `lib/orchestrator-spawn.sh`. This consolidates the manual 6-step workflow into a single function call.
+
+### Basic Usage
+
+```bash
+source lib/orchestrator-spawn.sh
+
+# Prepare complete subagent prompt for a task
+prompt=$(orchestrator_spawn_for_task "T1234")
+
+# With explicit skill override (bypasses auto-dispatch)
+prompt=$(orchestrator_spawn_for_task "T1234" "ct-research-agent")
+
+# With target model validation
+prompt=$(orchestrator_spawn_for_task "T1234" "" "sonnet")
+```
+
+### What orchestrator_spawn_for_task() Does
+
+The function performs these steps automatically:
+
+| Step | Action | Details |
+|------|--------|---------|
+| 1 | Read task from CLEO | `cleo show T1234 --format json` |
+| 2 | Select skill | Auto-dispatch from task type/labels or use override |
+| 3 | Validate skill | Check compatibility with target model |
+| 4 | Inject protocol | Load skill template + subagent protocol |
+| 5 | Set tokens | `{{TASK_ID}}`, `{{DATE}}`, `{{TOPIC_SLUG}}`, `{{EPIC_ID}}` |
+| 6 | **Validate protocol** | **MANDATORY check for SUBAGENT PROTOCOL marker** |
+| 7 | Return prompt | Complete JSON with prompt ready for Task tool |
+
+### Protocol Validation (MANDATORY)
+
+Step 6 validates that the generated prompt contains the `SUBAGENT PROTOCOL` marker. This is **mandatory** and will fail loudly if missing:
+
+- **Exit code**: `EXIT_PROTOCOL_MISSING` (60)
+- **Fix command**: `cleo research inject`
+- **Validation function**: `orchestrator_verify_protocol_injection()`
+
+If validation fails, the spawn is **blocked** and you must fix the skill template or manually inject the protocol block.
+
+### Return Value Structure
+
+```json
+{
+  "_meta": { "command": "orchestrator", "operation": "spawn_for_task" },
+  "success": true,
+  "result": {
+    "taskId": "T1234",
+    "skill": "ct-research-agent",
+    "topicSlug": "auth-implementation",
+    "date": "2026-01-20",
+    "epicId": "T1200",
+    "outputFile": "2026-01-20_auth-implementation.md",
+    "spawnTimestamp": "2026-01-20T15:30:00Z",
+    "targetModel": "auto",
+    "taskContext": {
+      "title": "Implement auth module",
+      "description": "Full task description..."
+    },
+    "instruction": "Use Task tool to spawn subagent with the following prompt:",
+    "prompt": "Complete injected prompt content..."
+  }
+}
+```
+
+### Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `orchestrator_spawn_for_task()` | Main function - prepare single task spawn |
+| `orchestrator_spawn_batch()` | Prepare prompts for multiple tasks |
+| `orchestrator_spawn_preview()` | Preview skill selection without injection |
+
+### Complete Workflow Example
+
+```bash
+#!/usr/bin/env bash
+# Example: Spawn research subagent for task T1586
+
+source lib/orchestrator-spawn.sh
+
+# 1. Generate spawn result (includes all tokens and context)
+spawn_result=$(orchestrator_spawn_for_task "T1586")
+
+# 2. Check success
+if [[ $(echo "$spawn_result" | jq -r '.success') != "true" ]]; then
+    echo "Spawn failed: $(echo "$spawn_result" | jq -r '.error.message')" >&2
+    exit 1
+fi
+
+# 3. Extract prompt for Task tool
+prompt=$(echo "$spawn_result" | jq -r '.result.prompt')
+output_file=$(echo "$spawn_result" | jq -r '.result.outputFile')
+skill=$(echo "$spawn_result" | jq -r '.result.skill')
+
+# 4. Log spawn metadata
+echo "Spawning $skill for task T1586"
+echo "Expected output: $output_file"
+
+# 5. Pass $prompt to Task tool (in orchestrator context)
+# The Task tool invocation would include:
+#   - description: "Execute task T1586 with $skill"
+#   - prompt: $prompt
+```
+
+### Debug Mode
+
+Enable debug output for troubleshooting:
+
+```bash
+export ORCHESTRATOR_SPAWN_DEBUG=1
+prompt=$(orchestrator_spawn_for_task "T1234")
+# Logs to stderr: [orchestrator-spawn] DEBUG: ...
+```
+
+---
+
+### Manual Workflow
+
+#### Step 1: Identify Task Type
+
+```bash
+# Check task details
+cleo show T1234 | jq '{title, description, labels}'
+```
+
+#### Step 2: Select Skill
+
+Match task keywords to skill selection matrix above.
+
+#### Step 3: Prepare Context
+
+```bash
+source lib/token-inject.sh
+
+# Set required tokens
+ti_set_context "T1234" "$(date +%Y-%m-%d)" "auth-implementation"
+
+# Set defaults and get task context
+ti_set_defaults
+task_json=$(cleo show T1234 --format json)
+ti_set_task_context "$task_json"
+```
+
+#### Step 4: Load Skill Template
+
+```bash
+template=$(ti_load_template "skills/ct-task-executor/SKILL.md")
+```
+
+#### Step 5: Spawn Subagent
+
+Use Task tool with:
+1. Injected skill template
+2. Subagent protocol block
+3. Context from previous agents (manifest `key_findings` ONLY)
+4. Clear task definition and completion criteria
+
+#### Step 6: Monitor Completion
+
+```bash
+# Check manifest for completion
+{{RESEARCH_SHOW_CMD}} <research-id>
+
+# Or use jq
+jq -s '.[-1] | {id, status, key_findings}' {{MANIFEST_PATH}}
+```

package/skills/ct-orchestrator/references/orchestrator-tokens.md

@@ -0,0 +1,180 @@
+# Orchestrator: Token Injection System
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on token injection, placeholder values, manual token setup, or helper functions for template processing
+
+## Token Injection System
+
+The `spawn` command handles token injection automatically. For manual injection, use `lib/token-inject.sh`.
+
+### Automatic (via spawn command)
+
+```bash
+# The spawn command automatically:
+# 1. Loads the skill template
+# 2. Sets required context tokens
+# 3. Gets task context from CLEO
+# 4. Extracts manifest summaries
+# 5. Injects all tokens
+cleo orchestrator spawn T1586 --template ct-research-agent
+```
+
+### Manual Token Injection
+
+```bash
+source lib/token-inject.sh
+
+# 1. Set required tokens
+export TI_TASK_ID="T1234"
+export TI_DATE="$(date +%Y-%m-%d)"
+export TI_TOPIC_SLUG="my-research-topic"
+
+# 2. Set CLEO defaults (task commands, output paths)
+ti_set_defaults
+
+# 3. Optional: Get task context from CLEO
+task_json=$(cleo show T1234 --format json)
+ti_set_task_context "$task_json"
+
+# 4. Load and inject skill template
+template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
+```
+
+---
+
+## Token Reference
+
+**Source of Truth**: `skills/_shared/placeholders.json`
+
+### Required Tokens
+
+| Token | Description | Pattern | Example |
+|-------|-------------|---------|---------|
+| `{{TASK_ID}}` | CLEO task identifier | `^T[0-9]+$` | `T1234` |
+| `{{DATE}}` | ISO date | `YYYY-MM-DD` | `2026-01-20` |
+| `{{TOPIC_SLUG}}` | URL-safe topic name | `[a-zA-Z0-9_-]+` | `auth-research` |
+
+### Task Command Tokens (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 Tokens (CLEO defaults)
+
+| Token | Default Value |
+|-------|---------------|
+| `{{OUTPUT_DIR}}` | `claudedocs/agent-outputs` |
+| `{{MANIFEST_PATH}}` | `claudedocs/agent-outputs/MANIFEST.jsonl` |
+
+### Task Context Tokens (populated from CLEO task data)
+
+| Token | Source | Description |
+|-------|--------|-------------|
+| `{{TASK_NAME}}` | `task.title` | Task title |
+| `{{TASK_DESCRIPTION}}` | `task.description` | Full description |
+| `{{TASK_INSTRUCTIONS}}` | `task.description` | Execution instructions |
+| `{{DELIVERABLES_LIST}}` | `task.deliverables` | Expected outputs |
+| `{{ACCEPTANCE_CRITERIA}}` | Extracted | Completion criteria |
+| `{{DEPENDS_LIST}}` | `task.depends` | Completed dependencies |
+| `{{MANIFEST_SUMMARIES}}` | MANIFEST.jsonl | Key findings from previous agents |
+| `{{NEXT_TASK_IDS}}` | Dependency analysis | Tasks unblocked after completion |
+
+---
+
+## Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `ti_set_defaults()` | Set CLEO defaults for unset tokens |
+| `ti_validate_required()` | Verify required tokens are set |
+| `ti_inject_tokens()` | Replace `{{TOKEN}}` patterns |
+| `ti_load_template()` | Load file and inject tokens |
+| `ti_set_context()` | Set TASK_ID, DATE, TOPIC_SLUG in one call |
+| `ti_set_task_context()` | Populate task context tokens from CLEO JSON |
+| `ti_extract_manifest_summaries()` | Get key_findings from recent manifest entries |
+| `ti_list_tokens()` | Show all tokens with current values |
+
+---
+
+## Token Injection with lib/token-inject.sh
+
+For fine-grained control over token injection, use `lib/token-inject.sh` directly.
+
+### Token Categories
+
+| Category | Tokens | Source |
+|----------|--------|--------|
+| **Required** | `{{TASK_ID}}`, `{{DATE}}`, `{{TOPIC_SLUG}}` | Must be set before injection |
+| **Task Commands** | `{{TASK_SHOW_CMD}}`, `{{TASK_START_CMD}}`, `{{TASK_COMPLETE_CMD}}`, etc. | CLEO defaults |
+| **Output Paths** | `{{OUTPUT_DIR}}`, `{{MANIFEST_PATH}}` | CLEO defaults |
+| **Task Context** | `{{TASK_TITLE}}`, `{{TASK_DESCRIPTION}}`, `{{DEPENDS_LIST}}`, etc. | From CLEO task data |
+| **Manifest Context** | `{{MANIFEST_SUMMARIES}}` | From recent MANIFEST.jsonl entries |
+
+### Manual Token Injection Example
+
+```bash
+source lib/token-inject.sh
+
+# 1. Set required tokens
+ti_set_context "T1234" "2026-01-20" "auth-research"
+
+# 2. Set CLEO defaults for task commands and paths
+ti_set_defaults
+
+# 3. Get task context from CLEO
+task_json=$(cleo show T1234 --format json)
+ti_set_task_context "$task_json"
+
+# 4. Load and inject skill template
+template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
+
+# 5. Verify tokens were injected
+echo "$template" | grep -c '{{' && echo "WARNING: Uninjected tokens remain"
+```
+
+### Key Functions
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `ti_set_context()` | Set required tokens | `ti_set_context "T1234" "" "topic"` |
+| `ti_set_defaults()` | Set CLEO command defaults | `ti_set_defaults` |
+| `ti_set_task_context()` | Populate from CLEO JSON | `ti_set_task_context "$task_json"` |
+| `ti_extract_manifest_summaries()` | Get recent findings | `ti_extract_manifest_summaries 5` |
+| `ti_load_template()` | Load and inject file | `ti_load_template "path/to/SKILL.md"` |
+| `ti_list_tokens()` | Debug token values | `ti_list_tokens` |
+
+---
+
+## Subagent Protocol Tokens
+
+Token defaults (from `skills/_shared/placeholders.json`):
+- `{{OUTPUT_DIR}}` -> `claudedocs/agent-outputs`
+- `{{MANIFEST_PATH}}` -> `claudedocs/agent-outputs/MANIFEST.jsonl`
+
+### Inline Protocol Block (when CLI unavailable)
+
+```markdown
+## 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.
+
+CLEO INTEGRATION:
+1. MUST read task details: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
+2. MUST start task: `{{TASK_START_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}}`  <- RECOMMENDED
+
+**Research Linking Note**: If subagent fails to link research, orchestrator will link on verification.
+This ensures bidirectional traceability between tasks and their research artifacts.
+```