@cleocode/skills 2026.11.4 → 2026.11.5-canary.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cleocode/skills",
3
- "version": "2026.11.4",
3
+ "version": "2026.11.5-canary.1",
4
4
  "description": "CLEO skill definitions - bundled with CLEO monorepo",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",
@@ -2,14 +2,14 @@
2
2
  name: ct-cleo
3
3
  description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
4
4
  metadata:
5
- version: 2.25.9
5
+ version: 2.26.0
6
6
  tier: core
7
7
  install: harness
8
8
  covers:
9
9
  - packages/cleo/src/cli/commands/session.ts
10
10
  - packages/cleo/src/cli/commands/focus.ts
11
11
  - packages/cleo/src/cli/commands/sticky.ts
12
- lastReviewed: 2026-11-10
12
+ lastReviewed: 2026-11-12
13
13
  stability: stable
14
14
  ---
15
15
 
@@ -153,7 +153,7 @@ Unattributed mutations warn on stderr; `session status` / `briefing` label a gue
153
153
  | Find work | `cleo next` → `cleo focus <id>` |
154
154
  | Search tasks | `cleo find "query"` |
155
155
  | Complete task | PR: `Closes: T### AC1,AC2` in the body, merge on green; the sweep closes it. No PR: `cleo done T### --plan` → `cleo verify …` → `cleo complete T###` |
156
- | Run typed gates (the only command that executes them; writes read the cache) | `cleo verify T### --run [--req A,B]` |
156
+ | Run typed gates (error/fail: E_GATE_RUN_FAILED, exit 6; warn/skipped stay successful; writes read the cache) | `cleo verify T### --run [--req A,B]` |
157
157
  | Save memory | `cleo memory observe "..." --title "..."` |
158
158
  | Spawn subagent | `cleo orchestrate spawn <taskId> --tier 2` |
159
159
  | Create a Saga | `cleo saga create --title "..." --acceptance "..."` |
@@ -2,7 +2,7 @@
2
2
  name: ct-lead
3
3
  description: "Phase Lead orchestration playbook for spawning and supervising a parallel worker swarm in one wave. Use when spawned by ct-orchestrator with role=orchestrator to fan out N leaf workers in one `cleo orchestrate fanout` call, read worker completion messages on AgentMBX plus pipeline_manifest, await rollupWaveStatus convergence, and return ONE rolled-up contract string to the parent Orchestrator. Triggers: 'phase lead', 'wave lead', 'supervise wave', 'fan out workers', 'aggregate worker results', 'rollup wave', any task with role=orchestrator that is itself a child of another orchestrator. Implements ADR-070 hierarchical orchestration."
4
4
  metadata:
5
- version: 1.9.0
5
+ version: 1.10.0
6
6
  tier: core
7
7
  install: harness
8
8
  covers:
@@ -55,13 +55,20 @@ above are enforced by your tool list, not by your discipline (T14363):
55
55
  | Your instructions | Your prompt is the appended system prompt (you cannot Read files) |
56
56
  | Your session | You run under your OWN CLEO session (`CLEO_SESSION_ID`, also passed to the runner), so `review verdict` and `merge train` act as you. Ending the run ends that session and frees the epic |
57
57
  | One command tool | `mcp__cleo-lead__cleo_run` runs one argv (never a shell string) when it matches the lead allow-list: read, plan, dispatch and review verbs of `cleo` and `gh`. Anything else, including pipes and redirection, is refused before a process starts |
58
- | Your mailbox | The project lead mailbox is claimed for your session once your spawn is admitted (right before you start) and released when you exit. A lead record keeps one lead per epic while your `claude` process or the `cleo` CLI lives (each recorded with its start time, so a reused pid never counts) (`E_LEAD_RUNNING` for a second one, however long you run); a dead lead's record (killed before its hooks ran, or its Orca terminal closed after its session ended) is reaped (mailbox, session unless already ended, temp dir, record) by the next `cleo orchestrate lead` (reported under `data.lead.reaped`, or `error.details.reaped` when the new lead is refused) or by `cleo orchestrate status` (`data.reapedLeads`). A record is removed only with proof: every process gone (an unreadable start time on a live pid counts as alive) and the session ended; otherwise it is kept with a `keptReason` and a new lead is refused with `E_LEAD_RECORD_KEPT`. `data.lead.mailbox` says whether the claim held |
58
+ | Your mailbox | Your first action is to claim the exact epic mailbox from your prompt through `mbx_identity`, or register it with role `lead` if absent. Registration also holds it in your running provider session; never pre-claim a provider that has not started or take over a live holder. The runner refuses dispatch until `agentmbx status` confirms your exact session holds that name with role `lead`, and rechecks on each dispatch. The mailbox is released when you exit. A lead record keeps one lead per epic while your `claude` process or the `cleo` CLI lives (each recorded with its start time, so a reused pid never counts) (`E_LEAD_RUNNING` for a second one); different epics have independent mailboxes. Dead leads are reaped by the next `cleo orchestrate lead` or `status`, with cleanup reported under `reaped`/`reapedLeads`. Unproven cleanup keeps the record with `keptReason` and refuses a replacement with `E_LEAD_RECORD_KEPT`. `data.lead.mailbox` reports a verified holder or pending bootstrap |
59
59
  | Background dispatch | `cleo orchestrate fanout` / `spawn-execute` start workers in the background. Each worker gets its own worktree (a provisioning failure refuses the spawn, never the project root), a durable worker record, and your mailbox in its prompt |
60
60
  | Report contract | A worker returns the Return Format Contract: `conclusion:`, `blocker:` and one `proof:` line per item, 100 words at most. A report with no proof is not a completion; detail belongs in the PR body |
61
61
 
62
62
  Commands the allow-list does not hold (for example `cleo manifest append`)
63
63
  are out of reach: put that content in your returned contract instead.
64
64
 
65
+ Scope status with `cleo orchestrate status <epicId>` (or `--epic <epicId>`);
66
+ omit the epic for overall project status. File each finding through the runner
67
+ with `cleo add "Finding title" --type task --parent <epicId> --acceptance "AC1|AC2"`.
68
+ Only task creation is allowed, with a required parent and acceptance criteria;
69
+ `--description` is optional. Task updates, other task types, JSON input and
70
+ validation bypasses remain unavailable.
71
+
65
72
  ## Operational Rules
66
73
 
67
74
  | ID | Rule | Practical Meaning |
@@ -91,12 +98,21 @@ The parent Orchestrator spawns you with a resolved prompt containing:
91
98
 
92
99
  ### 1. Pre-flight (name your mailbox before spawn)
93
100
 
94
- Run `mbx_whoami` for your AgentMBX name; if it shows no identity, claim one
95
- with `mbx_identity` before any other mbx tool. Then build each worker's prompt
101
+ Run `mbx_whoami` for your AgentMBX name; if unbound, list identities and claim
102
+ your exact prompted name, or register it with role `lead` if absent. Confirm
103
+ the name and role before dispatch. Then build each worker's prompt
96
104
  with `cleo orchestrate spawn <taskId> --lead-mbx <you>` (LEAD-005): the
97
105
  prompt's Agent Coordination section names your mailbox. With
98
106
  `orchestrate.leadWorker.v1` on, `cleo orchestrate fanout` and `spawn-execute`
99
- fill in the project's recorded lead mailbox when none is given (T14379).
107
+ use your verified epic mailbox when called through the guarded lead runner.
108
+ Manual spawns use the recorded project mailbox only while AgentMBX confirms
109
+ a live holder; an unheld explicit `--lead-mbx` refuses (T14477).
110
+ Project and epic names follow AgentMBX's exact 2–40 character lowercase
111
+ letter/digit/hyphen rule. Epic names normalize the configured base and epic id,
112
+ with a hash of the full inputs retained through truncation. Unheld defaults
113
+ are omitted with a warning; the CLI never claims before the provider starts.
114
+ These coordinator identities do not designate, replace or claim AgentMBX's
115
+ owner-designated project lead; that owner-controlled identity stays separate.
100
116
  Claude Code
101
117
  Agent-tool subagents share their parent's identity, so they return results
102
118
  directly instead of mailing them. Agent messages travel over AgentMBX, not
@@ -2,7 +2,7 @@
2
2
  name: ct-orchestrator
3
3
  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."
4
4
  metadata:
5
- version: 4.18.0
5
+ version: 4.19.0
6
6
  tier: core
7
7
  install: harness
8
8
  covers:
@@ -29,6 +29,8 @@ exclusions apply to the coordinator's current Run; `orca orchestration run-curre
29
29
  proves rebinding and clears the old exclusions. Enable the agent, then use
30
30
  `orca orchestration run-create --from <coordinator> --objective <new-goal>` to bind
31
31
  a fresh Run. Before a Run exists, exclusions last only for that dispatch invocation.
32
+ A first start that fails before worker-start is sent records `not_launched` and is
33
+ retired, so it never fences a later spawn; a retry's unsent start stays replayable.
32
34
  Fanout serializes Orca admissions so followers use the first proven Run; workers
33
35
  still execute concurrently. An unknown first start fences further unbound starts.
34
36
  Unknown launch outcomes retain their exact record ID and custody and never
@@ -406,8 +408,17 @@ binary on an absolute path outside the project with args `mcp`, so a repo's `.mc
406
408
  plant it; otherwise the lead gets the runner alone and `data.lead.mcpWarning` says why. A
407
409
  provider that cannot strip tools refuses the spawn (`E_LEAD_TOOLS_UNSTRIPPED`). The lead's prompt
408
410
  is composed with role `lead` (ct-lead excerpts) and passed as its appended system prompt. It runs
409
- in the project root under its OWN CLEO session (no worktree, no worker record). The lead mailbox
410
- is claimed once the spawn is admitted and released when the lead exits. A lead record
411
+ in the project root under its OWN CLEO session (no worktree, no worker record). Admission records
412
+ an epic mailbox generated from the configured base, project id and epic id. Names follow
413
+ AgentMBX's 2–40 character lowercase letter/digit/hyphen rule, retaining a full-input hash
414
+ through truncation so separate epics stay independent. Unheld defaults warn when omitted. The running lead's
415
+ first action claims or registers that name through its own `mbx_identity` tools with role
416
+ `lead`; registration also holds it. A CLI cannot pre-claim an endpoint that does not exist.
417
+ The runner refuses spawn, spawn-execute, fanout and handoff until AgentMBX confirms the
418
+ exact provider session holds it with role `lead`, and rechecks each dispatch. Worker prompts
419
+ name only destinations whose live holder is verified, including explicit `--lead-mbx`.
420
+ Different epics use independent coordinator mailboxes; none replaces or designates the
421
+ owner-controlled AgentMBX project lead. Exit releases the session's mailbox. A lead record
411
422
  (`.cleo/leads/<epic>.json`) holds one lead per epic while its `claude` process or the `cleo` CLI lives, each matched on pid
412
423
  AND start time so a reused pid never blocks the epic (a second gets
413
424
  `E_LEAD_RUNNING`); a lead killed before its hooks ran is reaped (mailbox, CLEO session, temp dir)
@@ -527,7 +538,7 @@ When operating without continuous HITL oversight, additional constraints apply:
527
538
  | `cleo orchestrate ready T1575` | Parallel-safe tasks in current wave |
528
539
  | `cleo orchestrate spawn T1586 --json` | Generate resolved spawn prompt |
529
540
  | `cleo orchestrate next T1575` | Suggest next task |
530
- | `cleo orchestrate status` | Status plus durable worker records (`workers`) |
541
+ | `cleo orchestrate status T1575` | Epic status plus durable worker records (`workers`); omit the ID for overall project status, or use `--epic T1575` |
531
542
  | `cleo saga rollup <sagaId>` | Cross-Epic status aggregation when orchestrating a multi-Epic Saga (ADR-073) |
532
543
  | `cleo saga members <sagaId>` | Member Epics of a Saga (parent_id containment — NOT `task_relations.groups`) |
533
544
  | `cleo find "query"` | Search tasks |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: ct-task-executor
3
3
  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.
4
- version: 2.11.0
4
+ version: 2.12.0
5
5
  protocol: implementation
6
6
  adrRefs:
7
7
  - ADR-070
@@ -17,7 +17,7 @@ compatibility:
17
17
  - gemini-cli
18
18
  license: MIT
19
19
  metadata:
20
- version: 2.11.0
20
+ version: 2.12.0
21
21
  tier: core
22
22
  install: harness
23
23
  covers:
@@ -137,6 +137,9 @@ A database or service started for a test run must not outlive it. A `docker run`
137
137
  ### Post-Execution
138
138
 
139
139
  1. **Verify against criteria** - Check each acceptance criterion. `cleo verify <id> --run`
140
+ returns `E_GATE_RUN_FAILED` (exit 6) for error/fail results, with captured evidence
141
+ and per-failure recovery hints in `error.details`; advisory warn and manual skipped
142
+ results remain successful. Resolve the reported cause before retrying. This
140
143
  is the only command that executes the typed gates; evidence writes, `cleo done` and
141
144
  `cleo complete` read the cached passes and execute nothing (pass `--run-typed` to opt
142
145
  in). `--run --req REQ-A,REQ-B` runs only those gates and leaves the other gates'
@@ -227,7 +227,7 @@
227
227
  },
228
228
  {
229
229
  "name": "ct-cleo",
230
- "version": "2.25.9",
230
+ "version": "2.26.0",
231
231
  "description": "CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.",
232
232
  "path": "skills/ct-cleo",
233
233
  "tier": 0,
@@ -886,7 +886,7 @@
886
886
  },
887
887
  {
888
888
  "name": "ct-lead",
889
- "version": "1.9.0",
889
+ "version": "1.10.0",
890
890
  "description": "Phase Lead orchestration playbook for spawning and supervising a parallel worker swarm in one wave. Use when spawned by ct-orchestrator with role=orchestrator to fan out N leaf workers in one `cleo orchestrate fanout` call, read worker completion messages on AgentMBX plus pipeline_manifest, await rollupWaveStatus convergence, and return ONE rolled-up contract string to the parent Orchestrator. Triggers: 'phase lead', 'wave lead', 'supervise wave', 'fan out workers', 'aggregate worker results', 'rollup wave', any task with role=orchestrator that is itself a child of another orchestrator. Implements ADR-070 hierarchical orchestration.",
891
891
  "path": "skills/ct-lead",
892
892
  "tier": 0,
@@ -922,7 +922,7 @@
922
922
  },
923
923
  {
924
924
  "name": "ct-orchestrator",
925
- "version": "4.18.0",
925
+ "version": "4.19.0",
926
926
  "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.",
927
927
  "path": "skills/ct-orchestrator",
928
928
  "tier": 0,
@@ -1410,7 +1410,7 @@
1410
1410
  },
1411
1411
  {
1412
1412
  "name": "ct-task-executor",
1413
- "version": "2.11.0",
1413
+ "version": "2.12.0",
1414
1414
  "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.",
1415
1415
  "path": "skills/ct-task-executor",
1416
1416
  "tier": 0,