@cleocode/skills 2026.9.24 → 2026.9.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.9.24",
+  "version": "2026.9.25",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-orchestrator/SKILL.md

@@ -2,7 +2,7 @@
 name: ct-orchestrator
 description: "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \"orchestrate\", \"orchestrator mode\", \"run as orchestrator\", \"delegate to subagents\", \"coordinate agents\", \"spawn subagents\", \"multi-agent workflow\", \"context-protected workflow\", \"agent farm\", \"HITL orchestration\", \"pipeline management\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime."
 metadata:
-  version: 4.0.5
+  version: 4.0.7
   tier: core
   install: harness
   covers:
@@ -174,12 +174,18 @@ since harness shells keep neither cwd nor env between calls (the git shim reads
 
 ### Valid Return Messages
 
-Capture exactly one `cleo manifest append` receipt (shorthand OR rich entry). Verify that same receipt has `success: true`, `data.appended: true`, and a nonempty `entryId`, then read it with `cleo manifest show <entryId>`. Never append again merely to capture or verify the receipt. On append or readback failure, report the failure; do not claim "Manifest appended". Static prompt checks do not prove storage or provider workflow success.
+Append exactly once and capture the id with `--field /data/entryId` (ADR-086: never pipe the receipt through `python3`/`jq`). A nonempty `ENTRY_ID` must then read back with `cleo manifest show "$ENTRY_ID"`. Never append again merely to verify. On append or readback failure, return `blocked` with `manifest:none`; do not claim an entry. Static prompt checks do not prove storage or provider workflow success. The manifest `--type` is the protocol's own type (`consensus`, `specification`, `architecture_decision`, ... — T12521).
 
-After successful verification, subagents MUST return exactly one of:
-- `"[Type] complete. Manifest appended to pipeline_manifest."`
-- `"[Type] partial. Manifest appended to pipeline_manifest."`
-- `"[Type] blocked. Manifest appended to pipeline_manifest."`
+After verification, subagents MUST return exactly this compressed block (T12521):
+
+```
+[Type] <complete|partial|blocked>. manifest:<entryId>
+commits: <sha7,sha7|none>
+gates: <gate>=<pass|fail|skip> ...
+blocker: <≤12 words|none>
+```
+
+blocker: none when complete; required when partial/blocked. `manifest:none` only for `partial`/`blocked`; fill every `<...>` placeholder (validators reject `<`/`>` in the entry id). Validators (`checkReturnMessageFormat`, `checkReturnFormat`, `validateReturnMessage`) still accept the legacy one-liner `"[Type] <complete|partial|blocked>. Manifest appended to pipeline_manifest."`.
 
 > Detailed spawn workflow, manual protocol injection, skill dispatch matrix: `references/orchestrator-spawning.md`
 

package/skills/ct-orchestrator/references/SUBAGENT-PROTOCOL-BLOCK.md

@@ -1,21 +1,33 @@
 # Subagent Protocol Block
 
-Copy and include this block in EVERY subagent prompt spawned via Task tool.
+Include this block in EVERY subagent prompt spawned via Task tool. It matches the
+spawn prompt's Return Format Contract and Manifest Protocol blocks (T12521).
 
 ## Standard Protocol Block
 
-```
+````
 ## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
 
-OUTPUT REQUIREMENTS:
-1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
-2. MUST append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027/T1093)
-3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
-4. MUST NOT return research content in response.
-
-MANIFEST ENTRY FORMAT:
-{"id":"YYYY-MM-DD_{topic}","timestamp":"ISO8601","task_id":"TXXXX","agent":"agent-name","status":"complete","key_findings":["finding1","finding2"],"needs_followup":["next-task-id"],"file":"YYYY-MM-DD_{topic}.md"}
-```
+OUTPUT:
+1. MUST record findings: `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}`. Never a raw file under `.cleo/agent-outputs/`.
+2. MUST append ONE entry to SQLite `pipeline_manifest` (ADR-027/T1093) and read it back:
+   ENTRY_ID=$(cleo manifest append --task {{TASK_ID}} --type <protocol> \
+     --content "<work, commits, gates>" --status completed \
+     --field /data/entryId) || exit 1
+   [ -n "$ENTRY_ID" ] || exit 1
+   cleo manifest show "$ENTRY_ID" >/dev/null || exit 1
+   `--status`: completed, partial or blocked (actual progress). Do not append again to verify.
+3. MUST NOT return research content, findings, diffs or prose.
+4. MUST return EXACTLY this block, nothing else:
+   <Type> <complete|partial|blocked>. manifest:<entryId>
+   commits: <sha7,sha7|none>
+   gates: <gate>=<pass|fail|skip> ...
+   blocker: <≤12 words|none>
+   blocker: none when complete; required when partial/blocked.
+   Append or readback failed → `<Type> blocked. manifest:none` + `blocker: manifest append failed`. Never claim an entry you did not read back.
+
+HITL: never ask the human. Return `<Type> blocked. manifest:<entryId>` + blocker: with {question, options[{label,description}], recommended} in the manifest; the orchestrator asks via the ask tool.
+````
 
 ## Usage
 
@@ -28,15 +40,11 @@ When spawning a subagent via Task tool:
 
 ## Example Subagent Prompt
 
-```
+````
 You are the {ROLE} subagent. Your job is to complete CLEO task {TASK_ID}.
 
 ## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
-OUTPUT REQUIREMENTS:
-1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
-2. MUST append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027/T1093)
-3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
-4. MUST NOT return research content in response.
+<Standard Protocol Block above, with {{TASK_ID}} and --type filled in>
 
 ## CONTEXT
 - Epic: {EPIC_ID} ({EPIC_TITLE})
@@ -50,17 +58,35 @@ OUTPUT REQUIREMENTS:
 {DETAILED_INSTRUCTIONS}
 
 BEGIN EXECUTION.
+````
+
+Example return:
+
+```
+Research complete. manifest:T1599-research-20260929
+commits: none
+gates: implemented=pass
+blocker: none
 ```
 
-## Manifest Entry Schema
+## Rich Manifest Entry
+
+The shorthand above is preferred. The rich form is
+`cleo manifest append --entry '<json>'`, captured and read back the same way
+(`ENTRY_ID=$(cleo manifest append --entry '<json>' --field /data/entryId)`, same guard).
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| id | string | Yes | Unique identifier (YYYY-MM-DD_{topic}) |
-| timestamp | string | Yes | ISO 8601 timestamp |
-| task_id | string | Yes | CLEO task ID (e.g., T1599) |
-| agent | string | Yes | Agent identifier |
-| status | string | Yes | "complete" or "partial" |
-| key_findings | array | Yes | Summary points (max 5) |
+| id | string | Yes | Unique id, e.g. `T1599-research-<YYYYMMDDHHMMSS>` |
+| file | string | Yes | Output path |
+| title | string | Yes | Headline, max 120 chars |
+| date | string | Yes | `YYYY-MM-DD` |
+| status | string | Yes | `completed`, `partial` or `blocked` |
+| agent_type | string | Yes | Protocol type (`research`, `consensus`, ...) |
+| topics | array | Yes | Topic tags |
+| actionable | boolean | Yes | Needs follow-up action |
+| key_findings | array | No | Summary points (max 5) |
 | needs_followup | array | No | Task IDs requiring followup |
-| file | string | Yes | Output filename |
+| linked_tasks | array | No | Task IDs; the first becomes the manifest task id |
+
+Missing required fields → `E_VALIDATION_FAILED`. Link tasks via `linked_tasks[]`, not `task_id`.

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

@@ -16,9 +16,18 @@ echo "$prompt" | grep -q "SUBAGENT PROTOCOL" || echo "ERROR: Missing protocol bl
 
 ### MUST Validate Return Messages
 
-Only accept these return message formats from subagents:
+Only accept these return message formats from subagents. The compressed block (T12521) is what spawn prompts ask for:
 
-| Status | Valid Return Message |
+```
+Research <complete|partial|blocked>. manifest:<entryId>
+commits: <sha7,sha7|none>
+gates: <gate>=<pass|fail|skip> ...
+blocker: <≤12 words|none>
+```
+
+Line 1 is required; `commits:`, `gates:` and `blocker:` may each appear once, and `blocker` is not `none` only for `partial`/`blocked`. The legacy one-liner stays valid:
+
+| Status | Legacy Return Message |
 |--------|---------------------|
 | Complete | "Research complete. Manifest appended to pipeline_manifest." |
 | Partial | "Research partial. Manifest appended to pipeline_manifest." |

package/skills/ct-task-executor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-task-executor
 description: General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.
-version: 2.7.5
+version: 2.7.6
 protocol: implementation
 adrRefs:
   - ADR-070
@@ -17,7 +17,7 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 2.7.5
+  version: 2.7.6
   tier: core
   install: harness
   covers:
@@ -163,7 +163,7 @@ The routing prints a one-line info message to stderr (suppress with
 
 1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
 2. MUST record ONE manifest entry: `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027)
-3. MUST return ONLY: "Implementation complete. Manifest appended to pipeline_manifest."
+3. MUST return ONLY the compressed block: `Implementation complete. manifest:<entryId>` then `commits:`, `gates:` and `blocker: none` lines (T12521; the legacy one-liner "Implementation complete. Manifest appended to pipeline_manifest." is still accepted)
 4. MUST NOT return implementation details in response
 
 ---
@@ -261,7 +261,7 @@ If all deliverables cannot be produced:
 3. Set manifest `"status": "partial"`
 4. Add blocking items to `needs_followup`
 5. Complete task (partial work is progress)
-6. Return: "Implementation partial. Manifest appended to pipeline_manifest."
+6. Return the compressed block with `Implementation partial. manifest:<entryId>` and a `blocker:` line (≤12 words)
 
 ### Blocked Execution
 
@@ -271,7 +271,7 @@ If work cannot proceed (missing dependencies, access issues, unclear requirement
 2. Set manifest `"status": "blocked"`
 3. Add blocker details to `needs_followup`
 4. Do NOT complete task
-5. Return: "Implementation blocked. Manifest appended to pipeline_manifest."
+5. Return the compressed block with `Implementation blocked. manifest:<entryId>` and a `blocker:` line (≤12 words)
 
 ### Acceptance Criteria Failure
 

package/skills/manifest.json

@@ -983,7 +983,7 @@
     },
     {
       "name": "ct-orchestrator",
-      "version": "4.0.5",
+      "version": "4.0.7",
       "description": "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \\\"orchestrate\\\", \\\"orchestrator mode\\\", \\\"run as orchestrator\\\", \\\"delegate to subagents\\\", \\\"coordinate agents\\\", \\\"spawn subagents\\\", \\\"multi-agent workflow\\\", \\\"context-protected workflow\\\", \\\"agent farm\\\", \\\"HITL orchestration\\\", \\\"pipeline management\\\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime.",
       "path": "skills/ct-orchestrator",
       "tier": 0,
@@ -1472,7 +1472,7 @@
     },
     {
       "name": "ct-task-executor",
-      "version": "2.7.5",
+      "version": "2.7.6",
       "description": "General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.",
       "path": "skills/ct-task-executor",
       "tier": 0,