@cleocode/skills 2026.3.45 → 2026.3.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.3.45",
+  "version": "2026.3.46",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",
@@ -15,5 +15,8 @@
     "type": "git",
     "url": "https://github.com/kryptobaseddev/cleo",
     "directory": "packages/skills"
+  },
+  "scripts": {
+    "validate:ops": "tsx scripts/validate-operations.ts"
   }
 }

package/skills/_shared/manifest-operations.md

@@ -15,7 +15,7 @@ The manifest system provides O(1) append operations and race-condition-free conc
 **Default Paths**:
 - Output directory: `claudedocs/agent-outputs/` (configurable via `agentOutputs.directory`)
 - Manifest file: `MANIFEST.jsonl` (configurable via `agentOutputs.manifestFile`)
-- Full path: `{{OUTPUT_DIR}}/{{MANIFEST_PATH}}`
+- Full path: `{{OUTPUT_DIR}}/MANIFEST.jsonl` (i.e., `claudedocs/agent-outputs/MANIFEST.jsonl`)
 
 **Design Principles**:
 - Append-only writes preserve audit trail
@@ -34,36 +34,23 @@ Create a new manifest entry for agent output.
 **Usage**:
 ```bash
 cleo research add \
-  --title "Entry Title" \
-  --file "path/to/output.md" \
-  --topics "topic1,topic2,topic3" \
-  --findings "Finding 1,Finding 2,Finding 3" \
-  [--status STATUS] \
-  [--task T####] \
-  [--epic T####] \
-  [--actionable | --not-actionable] \
-  [--needs-followup T001,T002] \
-  [--agent-type TYPE]
+  --task T#### \
+  --topic "topic-slug" \
+  [--findings "Finding 1,Finding 2,Finding 3"] \
+  [--sources "source1,source2"]
 ```
 
 **Required Flags**:
 | Flag | Description | Example |
 |------|-------------|---------|
-| `--title` | Human-readable title | `"Authentication Research"` |
-| `--file` | Relative path to output file | `"2026-02-07_auth-research.md"` |
-| `--topics` | Comma-separated topic tags | `"authentication,security,jwt"` |
-| `--findings` | Comma-separated key findings (1-7 items) | `"JWT tokens expire after 1h,OAuth2 preferred,PKCE required"` |
+| `--task` | Task ID to attach research to | `T3154` |
+| `--topic` | Research topic (slug) | `"jwt-authentication"` |
 
 **Optional Flags**:
-| Flag | Default | Valid Values |
-|------|---------|--------------|
-| `--status` | `complete` | `complete`, `partial`, `blocked` |
-| `--task` | none | Task ID (e.g., `T1234`) |
-| `--epic` | none | Epic ID (e.g., `T1200`) |
-| `--actionable` | `true` | Boolean flag |
-| `--not-actionable` | - | Negates actionable |
-| `--needs-followup` | `[]` | Comma-separated task IDs |
-| `--agent-type` | `research` | See Agent Type Values below |
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--findings` | Comma-separated key findings | `"JWT tokens expire in 1h,OAuth2 preferred"` |
+| `--sources` | Comma-separated source references | `"https://example.com,RFC 7519"` |
 
 **Agent Type Values** (RCASD-IVTR+C protocol + workflow types):
 - **Protocol types**: `research`, `consensus`, `specification`, `decomposition`, `implementation`, `contribution`, `release`
@@ -74,21 +61,17 @@ cleo research add \
 **Example**:
 ```bash
 cleo research add \
-  --title "JWT Authentication Best Practices" \
-  --file "2026-02-07_jwt-auth.md" \
-  --topics "authentication,jwt,security" \
-  --findings "Use RS256 for asymmetric signing,Tokens expire in 1h,Refresh tokens stored securely" \
-  --status complete \
   --task T3154 \
-  --actionable \
-  --agent-type research
+  --topic "jwt-authentication" \
+  --findings "Use RS256 for asymmetric signing,Tokens expire in 1h,Refresh tokens stored securely" \
+  --sources "RFC 7519,OWASP JWT Cheat Sheet"
 ```
 
 **Output**: JSON with created entry ID
 ```json
 {
   "success": true,
-  "entryId": "jwt-auth-2026-02-07",
+  "entryId": "jwt-authentication-2026-02-07",
   "manifestPath": "claudedocs/agent-outputs/MANIFEST.jsonl"
 }
 ```
@@ -102,24 +85,26 @@ Update an existing manifest entry.
 **Usage**:
 ```bash
 cleo research update <entry-id> \
-  [--title "New Title"] \
-  [--status STATUS] \
   [--findings "F1,F2,F3"] \
-  [--topics "T1,T2"] \
-  [--actionable | --not-actionable] \
-  [--needs-followup T001,T002]
+  [--sources "S1,S2"] \
+  [--status STATUS]
 ```
 
 **Parameters**:
-- `<entry-id>`: Entry ID from manifest (e.g., `jwt-auth-2026-02-07`)
+- `<entry-id>`: Entry ID from manifest (e.g., `jwt-authentication-2026-02-07`)
 
-**Flags**: Same as `add` command (all optional for update)
+**Flags**:
+| Flag | Description |
+|------|-------------|
+| `--findings` | Updated comma-separated findings |
+| `--sources` | Updated comma-separated sources |
+| `--status` | Updated status (`complete`, `partial`, `blocked`) |
 
 **Example**:
 ```bash
-cleo research update jwt-auth-2026-02-07 \
+cleo research update jwt-authentication-2026-02-07 \
   --status partial \
-  --needs-followup T3155,T3156
+  --findings "Finding 1,Finding 2 (revised)"
 ```
 
 ---
@@ -132,30 +117,24 @@ Query and filter manifest entries.
 ```bash
 cleo research list \
   [--status STATUS] \
-  [--type TYPE] \
-  [--topic TOPIC] \
-  [--since DATE] \
-  [--limit N] \
-  [--actionable]
+  [--task T####] \
+  [--limit N]
 ```
 
 **Filter Options**:
 | Flag | Description | Example |
 |------|-------------|---------|
-| `--status` | Filter by status | `complete`, `partial`, `blocked`, `archived` |
-| `--type` | Filter by agent type | `research`, `implementation`, `validation` |
-| `--topic` | Filter by topic tag | `authentication` |
-| `--since` | Entries since date | `2026-02-01` (ISO 8601: YYYY-MM-DD) |
-| `--limit` | Max results | `20` (default: 20) |
-| `--actionable` | Only actionable entries | Boolean flag |
+| `--status` | Filter by status | `complete`, `partial`, `blocked`, `pending` |
+| `--task` | Filter by task ID | `T3154` |
+| `--limit` | Max results | `20` |
 
 **Example**:
 ```bash
-# Recent research entries
-cleo research list --type research --since 2026-02-01 --limit 10
+# Entries for a specific task
+cleo research list --task T3154 --limit 10
 
-# Actionable partial entries
-cleo research list --status partial --actionable
+# Partial entries
+cleo research list --status partial
 ```
 
 **Output**: JSON array with manifest entries
@@ -235,22 +214,16 @@ Link a research entry to a task (bidirectional association).
 
 **Usage**:
 ```bash
-cleo research link <task-id> <research-id> [--notes "Custom note"]
+cleo research link <research-id> <task-id>
 ```
 
 **Parameters**:
-- `<task-id>`: Task ID (e.g., `T3154`)
 - `<research-id>`: Entry ID from manifest
-
-**Options**:
-| Flag | Description |
-|------|-------------|
-| `--notes` | Custom note text instead of default |
+- `<task-id>`: Task ID (e.g., `T3154`)
 
 **Example**:
 ```bash
-cleo research link T3154 jwt-auth-2026-02-07
-cleo research link T3154 jwt-auth-2026-02-07 --notes "Primary research source"
+cleo research link jwt-auth-2026-02-07 T3154
 ```
 
 **Effects**:
@@ -268,17 +241,8 @@ cleo research show jwt-auth-2026-02-07  # Check linked_tasks
 
 ### cleo research unlink
 
-Remove link between research and task.
-
-**Usage**:
-```bash
-cleo research unlink <task-id> <research-id>
-```
-
-**Example**:
-```bash
-cleo research unlink T3154 jwt-auth-2026-02-07
-```
+> **Note**: Not currently implemented in the CLI. To disassociate research from a task, use
+> `cleo research update <id>` to change status, or remove the link manually from the task record.
 
 ---
 
@@ -302,22 +266,16 @@ cleo research links T3154
 
 ### cleo research pending
 
-Show entries with `needs_followup` (orchestrator handoffs).
+Show entries with `status: pending` (orchestrator handoffs).
 
 **Usage**:
 ```bash
-cleo research pending [--brief]
+cleo research pending
 ```
 
-**Options**:
-| Flag | Description |
-|------|-------------|
-| `--brief` | Minimal output (just IDs and followup tasks) |
-
 **Example**:
 ```bash
 cleo research pending
-cleo research pending --brief
 ```
 
 **Output**: JSON array of entries requiring followup
@@ -344,81 +302,37 @@ Archive old manifest entries to maintain context efficiency.
 
 **Usage**:
 ```bash
-cleo research archive \
-  [--threshold BYTES] \
-  [--percent N] \
-  [--dry-run]
+cleo research archive [--before-date YYYY-MM-DD]
 ```
 
 **Options**:
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--threshold` | `200000` | Archive threshold in bytes (~50K tokens) |
-| `--percent` | `50` | Percentage of oldest entries to archive |
-| `--dry-run` | - | Show what would be archived without changes |
+| Flag | Description |
+|------|-------------|
+| `--before-date` | Archive entries created before this date (ISO 8601) |
 
 **Example**:
 ```bash
-# Preview archival
-cleo research archive --dry-run
-
-# Archive oldest 50% when manifest exceeds 200KB
-cleo research archive --threshold 200000 --percent 50
+# Archive entries older than a cutoff date
+cleo research archive --before-date 2026-01-01
 ```
 
 **Effects**:
-- Moves entries to `{{OUTPUT_DIR}}/archive/MANIFEST-archive.jsonl`
-- Updates status to `archived` in archive file
-- Removes from main manifest to reduce context size
+- Moves matching entries to archive storage
+- Reduces active manifest size for context efficiency
 
 ---
 
 ### cleo research archive-list
 
-List entries from the archive file.
-
-**Usage**:
-```bash
-cleo research archive-list \
-  [--limit N] \
-  [--since DATE]
-```
-
-**Options**:
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--limit` | `50` | Max entries to return |
-| `--since` | none | Filter archived since date (ISO 8601) |
-
-**Example**:
-```bash
-cleo research archive-list --limit 100 --since 2026-01-01
-```
+> **Note**: Not currently implemented in the CLI. To list archived entries, use
+> `cleo research list --status archived` or query the archive file directly.
 
 ---
 
 ### cleo research status
 
-Show manifest size and archival status.
-
-**Usage**:
-```bash
-cleo research status
-```
-
-**Output**: JSON with size metrics
-```json
-{
-  "success": true,
-  "manifest": {
-    "path": "claudedocs/agent-outputs/MANIFEST.jsonl",
-    "size": 153420,
-    "entryCount": 42,
-    "threshold": 200000,
-    "needsArchival": false
-  }
-}
-```
+> **Note**: Not currently implemented as a separate CLI command. Use `cleo research stats`
+> for manifest statistics.
 
 ---
 
@@ -457,106 +371,30 @@ cleo research stats
 
 ### cleo research validate
 
-Validate manifest file integrity and entry format.
-
-**Usage**:
-```bash
-cleo research validate [--fix] [--protocol] [--task T####]
-```
-
-**Options**:
-| Flag | Description |
-|------|-------------|
-| `--fix` | Remove invalid entries (destructive) |
-| `--protocol` | Validate against protocol requirements |
-| `--task` | Validate entries linked to specific task |
-
-**Example**:
-```bash
-# Check integrity
-cleo research validate
-
-# Fix invalid entries
-cleo research validate --fix
-
-# Validate protocol compliance for task outputs
-cleo research validate --protocol --task T3154
-```
-
-**Validation Checks**:
-- Valid JSON syntax per line
-- Required fields present: `id`, `file`, `title`, `date`, `status`, `topics`, `key_findings`, `actionable`
-- Status enum: `complete`, `partial`, `blocked`, `archived`
-- Date format: ISO 8601 (YYYY-MM-DD)
-- Field types: `topics` array, `key_findings` array, `actionable` boolean
-- Agent type validity (protocol + workflow types)
-
-**Exit Codes**:
-- `0`: Validation passed
-- `6`: Validation errors found (`EXIT_VALIDATION_ERROR`)
+> **Note**: Not currently implemented in the CLI. Manifest validation occurs automatically
+> when entries are created via `cleo research add`.
 
 ---
 
 ### cleo research compact
 
-Remove duplicate/obsolete entries from manifest.
-
-**Usage**:
-```bash
-cleo research compact
-```
-
-**Effects**:
-- Removes duplicate entries (same ID)
-- Keeps most recent version of duplicates
-- Atomic operation with backup
+> **Note**: Not currently implemented in the CLI. Use `cleo research archive` to manage
+> manifest size.
 
 ---
 
 ### cleo research get
 
-Get single entry by ID (raw JSON object).
-
-**Usage**:
-```bash
-cleo research get <entry-id>
-```
-
-**Example**:
-```bash
-cleo research get jwt-auth-2026-02-07
-```
-
-**Output**: Raw JSON object (no wrapper)
+> **Note**: Not currently implemented as a separate CLI command. Use `cleo research show <id>`
+> for entry details.
 
 ---
 
 ### cleo research inject
 
-Output the subagent injection template for prompts.
-
-**Usage**:
-```bash
-cleo research inject [--raw] [--clipboard]
-```
-
-**Options**:
-| Flag | Description |
-|------|-------------|
-| `--raw` | Output template without variable substitution |
-| `--clipboard` | Copy to clipboard (pbcopy/xclip) |
-
-**Example**:
-```bash
-# Output with current values
-cleo research inject
-
-# Raw template with {{TOKENS}}
-cleo research inject --raw
-
-# Copy to clipboard
-cleo research inject --clipboard
-```
+> **Note**: Not currently implemented in the CLI. The orchestrator generates fully-resolved
+> subagent prompts via `cleo orchestrator spawn <taskId>` or
+> `mutate({ domain: "orchestrate", operation: "spawn", params: { taskId } })`.
 
 ---
 
@@ -645,13 +483,10 @@ When present, the `audit` field provides operational metadata:
 
 ```bash
 cleo research add \
-  --title "{{TITLE}}" \
-  --file "{{DATE}}_{{TOPIC_SLUG}}.md" \
-  --topics "{{TOPICS_CSV}}" \
-  --findings "{{FINDINGS_CSV}}" \
-  --status complete \
   --task {{TASK_ID}} \
-  --agent-type research
+  --topic "{{TOPIC_SLUG}}" \
+  --findings "{{FINDINGS_CSV}}" \
+  --sources "{{SOURCES_CSV}}"
 ```
 
 3. Link to task: `{{TASK_LINK_CMD}} {{TASK_ID}} {{ENTRY_ID}}`
@@ -668,13 +503,9 @@ cleo research add \
 
 # Record in manifest
 cleo research add \
-  --title "{{TASK_TITLE}} Implementation" \
-  --file "{{OUTPUT_FILE}}" \
-  --topics "{{TASK_LABELS}}" \
-  --findings "Implemented X,Added Y,Modified Z" \
-  --status complete \
   --task {{TASK_ID}} \
-  --agent-type implementation
+  --topic "{{TOPIC_SLUG}}" \
+  --findings "Implemented X,Added Y,Modified Z"
 
 # Complete task
 {{TASK_COMPLETE_CMD}} {{TASK_ID}}
@@ -715,7 +546,7 @@ echo "$json" >> claudedocs/agent-outputs/MANIFEST.jsonl
 
 **Solution**: Use CLI commands
 ```bash
-cleo research add --title "..." --file "..." --topics "..." --findings "..."
+cleo research add --task T#### --topic "..." --findings "..."
 ```
 
 ---
@@ -723,15 +554,15 @@ cleo research add --title "..." --file "..." --topics "..." --findings "..."
 ### ❌ Missing Key Findings
 
 ```bash
-# WRONG - Empty findings array
-cleo research add --findings ""
+# WRONG - No findings provided
+cleo research add --task T#### --topic "auth"
 ```
 
-**Problem**: Manifest is for discovery - empty findings defeat purpose
+**Problem**: Manifest is for discovery — entries without findings defeat the purpose
 
-**Solution**: Always provide 1-7 concise findings
+**Solution**: Always provide concise findings
 ```bash
-cleo research add --findings "Finding 1,Finding 2,Finding 3"
+cleo research add --task T#### --topic "auth" --findings "Finding 1,Finding 2,Finding 3"
 ```
 
 ---
@@ -752,7 +583,7 @@ Here is my research:
 
 **Solution**: Return ONLY summary message
 ```markdown
-Research complete. See MANIFEST.jsonl for summary.
+[Type] complete. See MANIFEST.jsonl for summary.
 ```
 
 ---
@@ -775,27 +606,25 @@ findings=$(cat findings.txt | tr '\n' ',' | sed 's/,$//')
 
 ---
 
-### ❌ Skipping Task Link
+### ❌ Skipping Task ID
 
 ```bash
-# WRONG - No bidirectional association
-cleo research add --title "..." --file "..." --topics "..." --findings "..."
+# WRONG - No association with task
+cleo research add --topic "..." --findings "..."
 # (missing --task flag)
 ```
 
 **Problem**: Research orphaned, cannot be discovered from task
 
-**Solution**: Always link to task
+**Solution**: Always include `--task` flag
 ```bash
 cleo research add \
-  --title "..." \
-  --file "..." \
-  --topics "..." \
-  --findings "..." \
-  --task {{TASK_ID}}
-
-# Or link after creation
-cleo research link {{TASK_ID}} {{ENTRY_ID}}
+  --task {{TASK_ID}} \
+  --topic "..." \
+  --findings "..."
+
+# Or link an existing entry to a task
+cleo research link <entry-id> {{TASK_ID}}
 ```
 
 ---

package/skills/_shared/skill-chaining-patterns.md

@@ -1,5 +1,9 @@
 # Skill Chaining Patterns
 
+> **Reference status**: Not directly `@`-referenced by any ct-* skill SKILL.md. Referenced
+> in ct-epic-architect's `references/skill-aware-execution.md` as a prose pointer. Available
+> for skill authors and orchestrators that need multi-level delegation patterns.
+
 This reference defines patterns for multi-level skill invocation and context propagation across agent boundaries.
 
 ---
@@ -35,8 +39,12 @@ The orchestrator delegates work to a subagent via `orchestrate.spawn` with skill
 
 ### Implementation
 
-```
-# 1. Generate fully-resolved spawn prompt via MCP
+```bash
+# CLI (Primary)
+cleo orchestrator spawn T1234 --json
+
+# MCP (Fallback)
+# 1. Generate fully-resolved spawn prompt
 mutate({ domain: "orchestrate", operation: "spawn", params: { taskId: "T1234" }})
 
 # 2. Provider adapter executes the prompt using its native mechanism
@@ -50,7 +58,7 @@ mutate({ domain: "orchestrate", operation: "spawn", params: { taskId: "T1234" }}
 
 - **Input**: Task ID, skill template, previous manifest key_findings
 - **Output**: Manifest entry with key_findings for next agent
-- **Response**: "Research complete. See MANIFEST.jsonl for summary."
+- **Response**: "[Type] complete. See MANIFEST.jsonl for summary."
 
 ---
 
@@ -169,8 +177,8 @@ Parent reads only key_findings, not full research files.
 ### Rule 2: Minimal Response (MUST)
 
 ```
-Subagent MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
-Subagent MUST NOT return research content in response.
+Subagent MUST return ONLY: "[Type] complete/partial/blocked. See MANIFEST.jsonl for summary/details/blocker details."
+Subagent MUST NOT return output content in response.
 ```
 
 ### Rule 3: File-Based Details (MUST)
@@ -209,7 +217,7 @@ TOPIC_SLUG    # URL-safe topic name
 Before spawning subagent:
 - [ ] Identify appropriate skill for task type
 - [ ] Prepare token context (TASK_ID, DATE, TOPIC_SLUG)
-- [ ] Use `orchestrate.spawn` to generate fully-resolved prompt
+- [ ] CLI: `cleo orchestrator spawn <taskId> --json` or MCP: `orchestrate.spawn`
 - [ ] Verify token resolution is complete (`tokenResolution.fullyResolved`)
 
 Before chaining to another skill: