@cleocode/skills 2026.9.25 → 2026.9.26

package/package.json

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

package/skills/_shared/subagent-protocol-base.md

@@ -221,5 +221,5 @@ If work cannot proceed:
 | Returning full content | Bloats orchestrator context | Return only summary message |
 | Manual JSONL append | No validation, race conditions | Use `cleo research add` |
 | Missing manifest entry | Orchestrator can't find findings | Always create manifest entry |
-| Skipping task start | Protocol violation | Always `cleo start` before work |
+| Skipping task start | Protocol violation | Always `cleo start` before work. If `cleo start` fails with `E_SESSION_UNBOUND` (spawned workers and subagents are already bound), run `cleo session start --scope global --name "<name>"` or `cleo session resume <id>` first. |
 | Incomplete checklist | Protocol violation | Verify all items before return |

package/skills/_shared/task-system-integration.md

@@ -25,7 +25,7 @@ Skills and templates SHOULD reference this file instead of hardcoding CLEO comma
 
 **Purpose**: Mark task as active/in-progress.
 
-**CLEO Default**: `cleo start {{TASK_ID}}`
+**CLEO Default**: `cleo start {{TASK_ID}}`. If `cleo start` fails with `E_SESSION_UNBOUND` (spawned workers and subagents are already bound), run `cleo session start --scope global --name "<name>"` or `cleo session resume <id>` first.
 
 ### Complete Task
 

package/skills/ct-cleo/SKILL.md

@@ -2,14 +2,14 @@
 name: ct-cleo
 description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
 metadata:
-  version: 2.24.1
+  version: 2.24.3
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/session.ts
     - packages/cleo/src/cli/commands/focus.ts
     - packages/cleo/src/cli/commands/sticky.ts
-  lastReviewed: 2026-09-29
+  lastReviewed: 2026-09-30
   stability: stable
 ---
 
@@ -124,13 +124,13 @@ Code-graph answers (`cleo nexus impact`, `context`, `full-context`, `why`, `sear
 
 ## Sessions are terminal-bound (T12500)
 
-`cleo session start` binds the calling agent process (`CLAUDE_CODE_SESSION_ID`,
-`CODEX_THREAD_ID`, …), pane (`TMUX_PANE`, …) or tab (`TERM_SESSION_ID`, …). Session
-mutations from an unbound caller fail with `E_SESSION_UNBOUND` instead of
+`cleo session start` binds the calling agent process (`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, …), pane (`TMUX_PANE`, …), tab (`TERM_SESSION_ID`, …), CI job (`GITHUB_RUN_ID`+`GITHUB_RUN_ATTEMPT`+`GITHUB_JOB`, `CI_JOB_ID`) or ssh login tty (`SSH_TTY`+`SSH_CONNECTION`).
+With no provider key it also walks the process tree (T12864): a known single-agent harness (Kimi, aider, amp, cursor-agent, … — past its per-call `bash -c` shells) or an interactive / script shell becomes the identity, so `session start` then `cleo start` in separate `bash -c` calls share one session; a harness below a human's tab / pane, an ssh login or a CI job gets its own, more specific key, so it must run `cleo session start` itself.
+Any other host (a node / python orchestrator, an IDE extension host, a daemon, anything under pid 1) identifies nobody and keeps the single-session guard: multi-agent hosts and multi-step scripts must set `CLEO_SESSION_ID` (or `CLEO_AGENT_ID`, only in a long-lived host process: under a short-lived one such as `make` the key changes per call) per agent.
+Session mutations from an unbound caller fail with `E_SESSION_UNBOUND` instead of
 guessing the newest session; bind with `cleo session start`, `cleo session resume
-<id>` or `CLEO_SESSION_ID=<id>`, or name the target with `--session <id>`. CI and
-multi-step scripts must export `CLEO_SESSION_ID`. Unattributed mutations warn on
-stderr; `session status` / `briefing` label a guessed session `unbound: true`.
+<id>` or `CLEO_SESSION_ID=<id>`, or name the target with `--session <id>`. Separate one-shot `ssh host 'cleo …'` calls are separate callers: export `CLEO_SESSION_ID` there.
+Unattributed mutations warn on stderr; `session status` / `briefing` label a guessed session `unbound: true`.
 
 - A session a human started in a tab is adopted by Claude Code in that tab
   (also after a Claude restart). An adopter works in it but cannot end it without

package/skills/ct-cleo/references/anti-patterns.md

@@ -16,4 +16,4 @@
 | Returning content | Context bloat | Return only summary message |
 | Pretty-printed JSON | Invalid manifest | Single-line JSON |
 | Loading skills via `@` | Cannot resolve | Skills injected by orchestrator |
-| Skipping task start | Protocol violation | Always `cleo start` first |
+| Skipping task start | Protocol violation | Always `cleo start` first. If `cleo start` fails with `E_SESSION_UNBOUND` (spawned workers and subagents are already bound), run `cleo session start --scope global --name "<name>"` or `cleo session resume <id>` first. |

package/skills/ct-dev-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-dev-workflow
 description: Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.
-version: 3.1.4
+version: 3.1.5
 protocol: contribution
 dependencies: []
 sharedResources:
@@ -14,12 +14,12 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.1.4
+  version: 3.1.5
   tier: core
   install: harness
   covers:
     - .github/workflows/release-prepare.yml
-  lastReviewed: 2026-09-29
+  lastReviewed: 2026-09-30
   stability: stable
 ---
 
@@ -80,6 +80,10 @@ cleo current
 cleo find "relevant query"
 cleo add "Task title" --description "What you're doing" --parent T001
 cleo start T123
+# 3. If 'cleo start' fails with E_SESSION_UNBOUND (spawned workers and
+#    subagents are already bound), bind first, then retry:
+#    cleo session start --scope global --name "<what you are doing>"
+#    (or: cleo session resume <id>)
 ```
 
 ### Commit Message Format
@@ -329,7 +333,7 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
 ```bash
 # Task lifecycle
 cleo current                 # Current task
-cleo start T123              # Start task
+cleo start T123              # Start task (on E_SESSION_UNBOUND: bind a session, see above)
 cleo complete T123           # Mark done
 
 # Find existing work

package/skills/ct-documentor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ct-documentor
 description: Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Carries the CLEO writing and review guides as references and coordinates ct-spec-writer and ct-adr-recorder. 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.17.3
+version: 3.17.4
 protocol: null
 dependencies:
   - ct-spec-writer
@@ -16,13 +16,13 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.17.3
+  version: 3.17.4
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/docs.ts
     - packages/contracts/src/docs-taxonomy.ts
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-30
   stability: stable
 ---
 
@@ -851,7 +851,10 @@ Before completing, verify:
 # 1. Read task details
 cleo show {TASK_ID}
 
-# 2. Start task
+# 2. Start task. If it fails with E_SESSION_UNBOUND (spawned workers and
+#    subagents are already bound), run
+#    'cleo session start --scope global --name "<what you are doing>"'
+#    or 'cleo session resume <id>' first, then retry.
 cleo start {TASK_ID}
 
 # 3. Execute documentation workflow (phases 1-4)

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

@@ -1,7 +1,7 @@
 ---
 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.3
+version: 3.0.4
 protocol: decomposition
 adrRefs:
   - ADR-066
@@ -17,14 +17,14 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.0.3
+  version: 3.0.4
   tier: on-demand
   install: harness
   covers:
     - packages/core/src/validation/protocols/cant/decomposition.cant
     - packages/core/src/validation/protocols/protocols-markdown/decomposition.md
   loomStage: decomposition
-  lastReviewed: 2026-09-28
+  lastReviewed: 2026-09-30
   stability: stable
 ---
 
@@ -59,7 +59,7 @@ Context injection for epic planning and task decomposition tasks spawned via cle
 ### Execution Sequence
 
 1. Read task: `cleo show {{TASK_ID}}`
-2. Start task: `cleo start {{TASK_ID}}`
+2. Start task: `cleo start {{TASK_ID}}`. If `cleo start` fails with `E_SESSION_UNBOUND` (spawned workers and subagents are already bound), run `cleo session start --scope global --name "<name>"` or `cleo session resume <id>` first.
 3. Check existing work: `cleo find "keyword"`, `cleo list --type epic`
 4. Create epic and child tasks
 5. Attach files and link research

package/skills/ct-lead/SKILL.md

@@ -2,13 +2,13 @@
 name: ct-lead
 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 via delegate_task, drain the epic-{TID}.wave-{n} conduit topic 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."
 metadata:
-  version: 1.0.7
+  version: 1.0.8
   tier: core
   install: harness
   covers:
     - packages/core/src/orchestration/lead-rollup.ts
     - packages/core/src/orchestration/waves.ts
-  lastReviewed: 2026-09-29
+  lastReviewed: 2026-09-30
   stability: stable
 ---
 
@@ -69,6 +69,9 @@ cleo orchestrate ready "${EPIC}"
 cleo orchestrate waves "${EPIC}"
 ```
 
+Run these from the epic's project root (or a worktree of it): member order within
+a wave uses the calling session's focus phase, resolved from that project (T12501).
+
 ### 2. Parallel Fanout (one batch)
 
 Issue ONE `delegate_task` call with the full worker list. Each worker gets

package/skills/manifest.json

@@ -226,7 +226,7 @@
     },
     {
       "name": "ct-cleo",
-      "version": "2.24.1",
+      "version": "2.24.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.",
       "path": "skills/ct-cleo",
       "tier": 0,
@@ -566,7 +566,7 @@
     },
     {
       "name": "ct-dev-workflow",
-      "version": "3.1.4",
+      "version": "3.1.5",
       "description": "Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.",
       "path": "skills/ct-dev-workflow",
       "tier": 0,
@@ -642,7 +642,7 @@
     },
     {
       "name": "ct-documentor",
-      "version": "3.17.3",
+      "version": "3.17.4",
       "description": "Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Carries the CLEO writing and review guides as references and coordinates ct-spec-writer and ct-adr-recorder. 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.",
       "path": "skills/ct-documentor",
       "tier": 0,
@@ -728,7 +728,7 @@
     },
     {
       "name": "ct-epic-architect",
-      "version": "3.0.3",
+      "version": "3.0.4",
       "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.",
       "path": "skills/ct-epic-architect",
       "tier": 1,
@@ -965,7 +965,7 @@
     },
     {
       "name": "ct-lead",
-      "version": "1.0.7",
+      "version": "1.0.8",
       "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 via delegate_task, drain the epic-{TID}.wave-{n} conduit topic 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.",
       "path": "skills/ct-lead",
       "tier": 0,