@cleocode/skills 2026.10.21 → 2026.10.22
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 +1 -1
- package/skills/ct-cleo/SKILL.md +3 -3
- package/skills/ct-cleo/__tests__/injection-content.test.ts +6 -3
- package/skills/ct-cleo/references/orchestrator-constraints.md +0 -1
- package/skills/ct-cleo/references/planning-loop.md +55 -0
- package/skills/ct-codebase-mapper/SKILL.md +43 -9
- package/skills/ct-dev-workflow/SKILL.md +32 -10
- package/skills/ct-documentor/SKILL.md +28 -45
- package/skills/ct-lead/SKILL.md +34 -26
- package/skills/ct-lead/references/aggregation-protocol.md +33 -41
- package/skills/ct-lead/references/spawn-pattern.md +7 -11
- package/skills/ct-lean/SKILL.md +7 -2
- package/skills/ct-orchestrator/SKILL.md +68 -64
- package/skills/ct-orchestrator/orchestrator-prompt.txt +7 -6
- package/skills/ct-orchestrator/references/orchestrator-patterns.md +7 -8
- package/skills/ct-orchestrator/references/orchestrator-spawning.md +1 -1
- package/skills/ct-task-executor/SKILL.md +4 -4
- package/skills/manifest.json +10 -11
- package/skills/ct-cleo/references/loom-lifecycle.md +0 -136
- package/skills/ct-orchestrator/references/lifecycle-gates.md +0 -98
|
@@ -1,57 +1,51 @@
|
|
|
1
|
-
# Aggregation Protocol —
|
|
1
|
+
# Aggregation Protocol — AgentMBX + Manifest Drain Semantics
|
|
2
2
|
|
|
3
3
|
The Phase Lead converges on wave completion via TWO complementary channels:
|
|
4
4
|
|
|
5
|
-
1. **
|
|
6
|
-
carrying terminal
|
|
7
|
-
`failed` / `timeout`)
|
|
5
|
+
1. **AgentMBX** (the Lead's mailbox) — one completion message per worker
|
|
6
|
+
carrying its terminal status (`complete` / `partial` / `blocked` /
|
|
7
|
+
`failed` / `timeout`) and task id. Agent messages travel over AgentMBX,
|
|
8
|
+
not CONDUIT (D11172).
|
|
8
9
|
2. **pipeline_manifest** (SQLite, ADR-027) — durable source of truth for
|
|
9
10
|
each worker's structured output (key_findings, files, gates).
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
(T9082) reads
|
|
12
|
+
Messages drive **timing**; the manifest drives **content**. `rollupWaveStatus`
|
|
13
|
+
(T9082) reads the manifest and produces the authoritative wave verdict.
|
|
13
14
|
|
|
14
15
|
---
|
|
15
16
|
|
|
16
|
-
## 1.
|
|
17
|
+
## 1. Mailbox before spawn
|
|
17
18
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
Before issuing `delegate_task`, build each worker's prompt with `cleo
|
|
20
|
+
orchestrate spawn <taskId> --lead-mbx <you>` so its completion message reaches
|
|
21
|
+
you (`fanout` cannot carry the name yet, T13966: put it in the task notes). A mailbox keeps messages until
|
|
22
|
+
they are read, so a worker that finishes first is never lost; a worker that
|
|
23
|
+
does not know your name cannot report at all.
|
|
21
24
|
|
|
22
25
|
```bash
|
|
23
|
-
# CORRECT —
|
|
24
|
-
cleo
|
|
25
|
-
cleo orchestrate fanout T9080 --tasks T9301,T9302,T9303
|
|
26
|
-
|
|
27
|
-
# WRONG — fanout, then subscribe (race window)
|
|
28
|
-
cleo orchestrate fanout T9080 --tasks T9301,T9302,T9303
|
|
29
|
-
cleo conduit subscribe --topic "epic-T9080.wave-2" # may miss T9301 done
|
|
26
|
+
# CORRECT — each worker prompt names the Lead mailbox
|
|
27
|
+
cleo orchestrate spawn T9301 --lead-mbx lead-t9080-w2
|
|
30
28
|
```
|
|
31
29
|
|
|
32
|
-
The conduit retains buffered signals for `conduit.replay_window` (default 30s)
|
|
33
|
-
to defend against tiny races, but relying on the buffer is brittle.
|
|
34
|
-
|
|
35
30
|
---
|
|
36
31
|
|
|
37
32
|
## 2. Drain loop
|
|
38
33
|
|
|
39
|
-
There is no blocking await.
|
|
40
|
-
`
|
|
41
|
-
|
|
34
|
+
There is no blocking await. Between waits the Lead reads its inbox
|
|
35
|
+
(`mbx_inbox` / `mbx_read`, or `agentmbx inbox --as <you>` inside the provider session that holds the
|
|
36
|
+
MCP lease) until every
|
|
37
|
+
worker's completion message has arrived OR its wall-clock budget elapses,
|
|
38
|
+
and acks each message it acted on.
|
|
42
39
|
|
|
43
40
|
```bash
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
# Then read authoritative state from manifest — same wave number as the topic.
|
|
41
|
+
# Then read authoritative state from the manifest, by the wave number
|
|
42
|
+
# `cleo orchestrate waves` prints.
|
|
48
43
|
cleo orchestrate roll-up T9080 --wave 2 --json > /tmp/rollup.json
|
|
49
44
|
```
|
|
50
45
|
|
|
51
46
|
> **Wave contract (T12682).** One wave number `n` names everything: it is
|
|
52
|
-
> the 1-based number `cleo orchestrate waves <epic>` prints,
|
|
53
|
-
>
|
|
54
|
-
> --wave <n>` takes the same `n` (`--wave 0` is refused with
|
|
47
|
+
> the 1-based number `cleo orchestrate waves <epic>` prints, and `cleo
|
|
48
|
+
> orchestrate roll-up <epic> --wave <n>` takes the same `n` (`--wave 0` is refused with
|
|
55
49
|
> `E_CLEO_VALIDATION`, pointing at `cleo orchestrate waves`).
|
|
56
50
|
>
|
|
57
51
|
> **What a wave number guarantees (T12683).** A task's wave is its
|
|
@@ -64,8 +58,8 @@ cleo orchestrate roll-up T9080 --wave 2 --json > /tmp/rollup.json
|
|
|
64
58
|
> finished waves without renumbering the rest.
|
|
65
59
|
> - **Not stable** when a dependency edge is added or removed anywhere
|
|
66
60
|
> upstream, including in another epic: downstream waves shift. If you
|
|
67
|
-
>
|
|
68
|
-
>
|
|
61
|
+
> noted a wave number ahead of time, re-read `cleo orchestrate waves`
|
|
62
|
+
> after any dependency change.
|
|
69
63
|
> - **Numbers can skip, and an epic's first wave can be above 1** (a task
|
|
70
64
|
> whose external prerequisite sits at depth 3 is in wave 4). Always take
|
|
71
65
|
> `n` from `cleo orchestrate waves`; never assume the first wave is 1.
|
|
@@ -118,13 +112,11 @@ Local retry shape:
|
|
|
118
112
|
# After first drain, identify retriable failures
|
|
119
113
|
RETRIABLE=$(jq -r '.workers[] | select(.status=="failed" and (.reason|test("testsPassed|qaPassed|INFRASTRUCTURE"))) | .taskId' /tmp/rollup.json)
|
|
120
114
|
|
|
121
|
-
# Re-spawn ONLY those
|
|
122
|
-
cleo conduit subscribe --topic "epic-T9080.wave-2.retry-1"
|
|
115
|
+
# Re-spawn ONLY those; their briefs name the Lead mailbox and say "retry 1"
|
|
123
116
|
cleo orchestrate fanout T9080 --tasks "$(echo $RETRIABLE | tr ' ' ,)"
|
|
124
117
|
|
|
125
|
-
#
|
|
126
|
-
# latest status of every worker, retries included)
|
|
127
|
-
cleo conduit listen --topic "epic-T9080.wave-2.retry-1" --since "${RETRY_AT}"
|
|
118
|
+
# Read the retry completion messages, then roll up again (the manifest holds
|
|
119
|
+
# the latest status of every worker, retries included)
|
|
128
120
|
cleo orchestrate roll-up T9080 --wave 2 --json > /tmp/rollup-final.json
|
|
129
121
|
```
|
|
130
122
|
|
|
@@ -138,16 +130,16 @@ verdict — no second retry pass.
|
|
|
138
130
|
Every leaf worker is bounded by a 600s wall-clock timeout (configurable via
|
|
139
131
|
`subagentTimeoutSeconds`). The Lead's drain timeout MUST be at least equal
|
|
140
132
|
to the worker timeout — typically equal, since workers report terminally
|
|
141
|
-
on timeout
|
|
133
|
+
on timeout over AgentMBX.
|
|
142
134
|
|
|
143
135
|
Behaviour matrix:
|
|
144
136
|
|
|
145
|
-
| Worker outcome at 600s |
|
|
137
|
+
| Worker outcome at 600s | AgentMBX message | Manifest entry | Lead action |
|
|
146
138
|
|------------------------|----------------|----------------|-------------|
|
|
147
139
|
| Worker returned a contract string in time | `complete`/`partial`/`blocked` | Present, full | Aggregate normally |
|
|
148
140
|
| Worker exited cleanly past 600s (race) | None | Present | `rollupWaveStatus` reconciles via manifest |
|
|
149
141
|
| Worker hung; runtime killed it | `timeout` | Stub entry with `status:timeout` | Treat as `failed` non-retriable; return `partial` |
|
|
150
|
-
|
|
|
142
|
+
| Worker could not reach AgentMBX | None | None | Drain times out; `rollup` flags `missing` workers; return `partial` |
|
|
151
143
|
|
|
152
144
|
The Lead's own wall-clock budget should be `subagentTimeoutSeconds + 60s`
|
|
153
145
|
of slack to allow the rollup query and manifest append to complete.
|
|
@@ -167,7 +159,7 @@ rollupWaveStatus() →
|
|
|
167
159
|
Escalate to parent Orchestrator (return `partial` or `blocked`) when:
|
|
168
160
|
- ANY worker requires HITL input (architectural decision, scope expansion)
|
|
169
161
|
- Same worker fails after the single local retry
|
|
170
|
-
-
|
|
162
|
+
- The inbox drain times out with `missing` workers
|
|
171
163
|
- A worker reports `E_DEP_UNSATISFIED` (wave was mis-planned)
|
|
172
164
|
- Cumulative wave wall-clock exceeds `subagentTimeoutSeconds + 60s`
|
|
173
165
|
|
|
@@ -2,26 +2,26 @@
|
|
|
2
2
|
|
|
3
3
|
The Phase Lead fans out all workers in a single `delegate_task` batch.
|
|
4
4
|
Width is bounded by `maxConcurrent` (default 10; a convention the Lead enforces — no runtime check exists).
|
|
5
|
-
Each child carries `role=leaf
|
|
5
|
+
Each child carries `role=leaf`, and its brief names the Lead's AgentMBX
|
|
6
|
+
mailbox so its completion message reaches the Lead.
|
|
6
7
|
|
|
7
8
|
All examples assume:
|
|
8
9
|
- Lead's own task ID: `T9080-lead-w2`
|
|
9
10
|
- Epic: `T9080`
|
|
10
11
|
- Wave: `wave-2`
|
|
11
|
-
-
|
|
12
|
+
- Lead mailbox (AgentMBX): `lead-t9080-w2`
|
|
12
13
|
|
|
13
14
|
---
|
|
14
15
|
|
|
15
16
|
## Example 1 — 3-worker fanout (small wave)
|
|
16
17
|
|
|
17
|
-
Typical for narrowly-scoped
|
|
18
|
+
Typical for narrowly-scoped waves where deps fan in tightly.
|
|
18
19
|
|
|
19
20
|
```json
|
|
20
21
|
{
|
|
21
22
|
"tool": "delegate_task",
|
|
22
23
|
"args": {
|
|
23
24
|
"parent": { "taskId": "T9080-lead-w2", "role": "orchestrator" },
|
|
24
|
-
"conduitTopic": "epic-T9080.wave-2",
|
|
25
25
|
"timeoutSeconds": 600,
|
|
26
26
|
"tasks": [
|
|
27
27
|
{ "taskId": "T9101", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
|
|
@@ -34,11 +34,9 @@ Typical for narrowly-scoped IVTR waves where deps fan in tightly.
|
|
|
34
34
|
|
|
35
35
|
CLI equivalent (one shell call, NOT a loop). `fanout` takes the epic and the
|
|
36
36
|
task list only; role, model and timeout come from each task's spawn prompt
|
|
37
|
-
(`cleo orchestrate spawn <taskId>`)
|
|
38
|
-
before it runs:
|
|
37
|
+
(`cleo orchestrate spawn <taskId>`):
|
|
39
38
|
|
|
40
39
|
```bash
|
|
41
|
-
cleo conduit subscribe --topic epic-T9080.wave-2
|
|
42
40
|
cleo orchestrate fanout T9080 --tasks T9101,T9102,T9103
|
|
43
41
|
```
|
|
44
42
|
|
|
@@ -51,7 +49,6 @@ cleo orchestrate fanout T9080 --tasks T9101,T9102,T9103
|
|
|
51
49
|
"tool": "delegate_task",
|
|
52
50
|
"args": {
|
|
53
51
|
"parent": { "taskId": "T9080-lead-w2", "role": "orchestrator" },
|
|
54
|
-
"conduitTopic": "epic-T9080.wave-2",
|
|
55
52
|
"timeoutSeconds": 600,
|
|
56
53
|
"tasks": [
|
|
57
54
|
{ "taskId": "T9201", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
|
|
@@ -76,7 +73,6 @@ For wider waves, the parent Orchestrator MUST split into multiple Leads.
|
|
|
76
73
|
"tool": "delegate_task",
|
|
77
74
|
"args": {
|
|
78
75
|
"parent": { "taskId": "T9080-lead-w2", "role": "orchestrator" },
|
|
79
|
-
"conduitTopic": "epic-T9080.wave-2",
|
|
80
76
|
"timeoutSeconds": 600,
|
|
81
77
|
"tasks": [
|
|
82
78
|
{ "taskId": "T9301", "role": "leaf", "subagent_type": "cleo-subagent", "model": "sonnet" },
|
|
@@ -128,6 +124,6 @@ DO NOT spawn workers with `role=orchestrator`:
|
|
|
128
124
|
| Worker count | When to use | Notes |
|
|
129
125
|
|--------------|-------------|-------|
|
|
130
126
|
| 1–3 | Narrow waves; single-package changes | Minimal overhead, fast convergence |
|
|
131
|
-
| 4–6 | Typical
|
|
132
|
-
| 7–10 | Max-width parallel waves | Watch
|
|
127
|
+
| 4–6 | Typical implementation waves | Sweet spot for sonnet workers |
|
|
128
|
+
| 7–10 | Max-width parallel waves | Watch inbox volume; close to convergence-limit |
|
|
133
129
|
| >10 | Split across multiple Leads | Top Orchestrator spawns N Leads, each ≤10 workers |
|
package/skills/ct-lean/SKILL.md
CHANGED
|
@@ -10,7 +10,7 @@ description: >-
|
|
|
10
10
|
gates, package boundaries, validation, data safety or anything the task asked for.
|
|
11
11
|
license: MIT
|
|
12
12
|
metadata:
|
|
13
|
-
version: 1.
|
|
13
|
+
version: 1.6.0
|
|
14
14
|
tier: core
|
|
15
15
|
install: harness
|
|
16
16
|
covers:
|
|
@@ -18,6 +18,7 @@ metadata:
|
|
|
18
18
|
- packages/cleo/src/cli/commands/lean.ts
|
|
19
19
|
- packages/core/src/orchestration/lean-debt.ts
|
|
20
20
|
- packages/core/src/orchestration/lean-gain.ts
|
|
21
|
+
- packages/core/src/nexus/brief-map.ts
|
|
21
22
|
lastReviewed: 2026-10-13
|
|
22
23
|
stability: stable
|
|
23
24
|
attribution: Adapted from Ponytail 5.1.0 by DietrichGebert (MIT) — https://github.com/DietrichGebert/ponytail
|
|
@@ -44,6 +45,9 @@ config key, then `full`. When the owner asks for a level ("go ultra", "lean off"
|
|
|
44
45
|
`--global` for every project. `cleo lean level` alone shows the level and its source.
|
|
45
46
|
`cleo lean gain --card` shows the measured benchmark scoreboard: averages, never a number
|
|
46
47
|
for this repo.
|
|
48
|
+
Subagents get the same level: CLEO-spawned ones through the spawn prompt, Claude Code
|
|
49
|
+
Agent-tool ones through the SubagentStart hook (`cleo hook subagent-start`, installed with the
|
|
50
|
+
heavy-command hook; scope it with `CLEO_LEAN_SUBAGENT_MATCHER`, a regex over the agent type).
|
|
47
51
|
|
|
48
52
|
## Before you write
|
|
49
53
|
|
|
@@ -58,7 +62,8 @@ callers that stop working, stores it would migrate. That is scope. Extra feature
|
|
|
58
62
|
1. **Does it need to exist?** Skip features, options and flexibility nobody asked for, and
|
|
59
63
|
name them in one line. A vague request gets the smallest version that does the core job.
|
|
60
64
|
2. **Already in this codebase?** A helper, accessor, contract or pattern: use it the way the
|
|
61
|
-
surrounding code does. Search `packages/core/src` and `packages/contracts/src` first
|
|
65
|
+
surrounding code does. Search `packages/core/src` and `packages/contracts/src` first;
|
|
66
|
+
`cleo map --brief` lists what exists per folder (set `lean.map` to get it in `cleo briefing`).
|
|
62
67
|
3. **Standard library or platform feature?** Use it, unless the repo has its own (a house
|
|
63
68
|
chokepoint such as `openDualScopeDb` or `cleo run` beats a raw primitive).
|
|
64
69
|
4. **An installed dependency?** Use it. Never add a dependency for a few lines.
|
|
@@ -2,13 +2,13 @@
|
|
|
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.
|
|
5
|
+
version: 4.1.2
|
|
6
6
|
tier: core
|
|
7
7
|
install: harness
|
|
8
8
|
covers:
|
|
9
9
|
- packages/cleo/src/cli/commands/orchestrate.ts
|
|
10
10
|
- packages/core/src/orchestration/spawn-prompt.ts
|
|
11
|
-
lastReviewed: 2026-10-
|
|
11
|
+
lastReviewed: 2026-10-23
|
|
12
12
|
stability: stable
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -51,7 +51,7 @@ You are the **Orchestrator** — a conductor, never a musician. You coordinate c
|
|
|
51
51
|
| ORC-005 | Context budget: 10K tokens | Use `cleo orchestrate context` to monitor; delegate at 80% |
|
|
52
52
|
| ORC-006 | Max 3 files per subagent | Cross-file reasoning degrades beyond this scope |
|
|
53
53
|
| ORC-007 | All work traced to epic | No orphaned tasks — every task has a parent epic |
|
|
54
|
-
| ORC-008 | Zero architectural decisions | Architecture MUST be pre-decided
|
|
54
|
+
| ORC-008 | Zero architectural decisions | Architecture MUST be pre-decided in the plan document or by an owner decision (HITL) |
|
|
55
55
|
| ORC-009 | Manifest-mediated handoffs | Read only `key_findings` from pipeline_manifest; subagents read full files |
|
|
56
56
|
| ORC-010 | Continuous dispatch | While ready tasks exist, orchestrator MUST be spawning — never idle while work remains |
|
|
57
57
|
| ORC-011 | Pre-release verification gate | NEVER `git push --tags` without full pipeline green: biome ci packages/, build, test, changelog, version |
|
|
@@ -70,7 +70,7 @@ discriminates; prefixes (`SG-`, `E-`, `T-`) are display + import-mapping only.
|
|
|
70
70
|
| Subtask | (none) | One commit; ≤2 files; rolls up to Task's PR | Worker (leaf) |
|
|
71
71
|
|
|
72
72
|
**I8 (load-bearing for decomposition):** A Task ships as exactly ONE PR. Subtasks contribute
|
|
73
|
-
commits to that single PR — they NEVER own a PR. When decomposing
|
|
73
|
+
commits to that single PR — they NEVER own a PR. When decomposing, if a unit needs
|
|
74
74
|
its own PR it MUST be a Task, not a Subtask.
|
|
75
75
|
|
|
76
76
|
**Tier-promotion triggers (see ADR-073 §1.3 for full decision table):**
|
|
@@ -81,46 +81,51 @@ its own PR it MUST be a Task, not a Subtask.
|
|
|
81
81
|
Full charter (8 invariants I1–I8 + prefix registry) lives in
|
|
82
82
|
`.cleo/adrs/ADR-073-above-epic-naming.md` §1–§2.
|
|
83
83
|
|
|
84
|
-
##
|
|
84
|
+
## The Work Loop
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
Every issue, feature or bug runs the same loop: plan, execute, verify. RCASD stage
|
|
87
|
+
records and the IVTR loop are retired from agent instructions (epic T13932).
|
|
88
|
+
`pipeline_stage` is a label on tasks; it gates work only where a project turns on
|
|
89
|
+
the stage gate (see Plan).
|
|
87
90
|
|
|
88
|
-
###
|
|
91
|
+
### Plan
|
|
89
92
|
|
|
90
|
-
|
|
93
|
+
- **One plan document per epic** in the CleoDocs store (`--type plan`), with sections
|
|
94
|
+
for findings, the decision, the spec (acceptance criteria) and the decomposition.
|
|
95
|
+
- **Decisions** go to the BRAIN decision store
|
|
96
|
+
(`cleo memory decision-store --decision "..." --rationale "..." --linked-task <epicId>`);
|
|
97
|
+
owner decisions go through the ask tool first.
|
|
98
|
+
- **Tasks**: atomic children under the epic, each with `--acceptance` and `--depends`.
|
|
99
|
+
Spawn protocols (research, consensus, specification, decomposition, ...) only pick
|
|
100
|
+
the spawn prompt's stage guidance; they are labels, not gates.
|
|
101
|
+
- **Stage gate** (`lifecycle.stageGate`, off by default, T13970): when a project sets it
|
|
102
|
+
to `strict`, a child cannot complete (exit 80) while its parent epic sits in a planning
|
|
103
|
+
stage (research to decomposition), and the epic cannot advance once children sit at its
|
|
104
|
+
stage; `advisory` only warns. An epic inherits its saga's stage, or starts at research
|
|
105
|
+
when it has no parent. With the gate on, run `cleo update <epicId> --pipeline-stage
|
|
106
|
+
implementation` once the plan is written and BEFORE adding children; if children
|
|
107
|
+
already sit at its stage, report the epic to the lead or owner. The setting is their
|
|
108
|
+
choice: never change `lifecycle.stageGate` yourself. Evidence strictness stays on
|
|
109
|
+
`lifecycle.mode` either way.
|
|
91
110
|
|
|
92
|
-
|
|
93
|
-
|-------|---------|---------------|
|
|
94
|
-
| **Research** | Investigate codebase, gather context, explore options | Explorer (lightweight) |
|
|
95
|
-
| **Consensus** | Validate approach, identify risks, get HITL alignment | Lead (reasoning) |
|
|
96
|
-
| **Architecture** | Choose patterns, integration points, store decisions in BRAIN decision-store | Lead (reasoning) |
|
|
97
|
-
| **Specification** | Write formal spec with RFC 2119 language, acceptance criteria | Lead (reasoning) |
|
|
98
|
-
| **Decomposition** | Break into atomic tasks with deps under epic(s) | Lead (reasoning) |
|
|
111
|
+
### Execute
|
|
99
112
|
|
|
100
|
-
|
|
113
|
+
- Waves from `cleo orchestrate waves <epicId>`, admission from `cleo orchestrate ready
|
|
114
|
+
<epicId>`, prompts from `cleo orchestrate spawn <taskId> --lead-mbx <you>`.
|
|
115
|
+
- Agents coordinate over AgentMBX; task state and evidence stay in CLEO.
|
|
116
|
+
- Autonomous runs go through CLEO Goal (ADR-097), not a CLEO-driven loop.
|
|
101
117
|
|
|
102
|
-
###
|
|
118
|
+
### Verify
|
|
103
119
|
|
|
104
|
-
|
|
120
|
+
- Evidence gates (ADR-051): `cleo done <id> --plan`, then `cleo verify` per gate, then
|
|
121
|
+
`cleo complete`. A worker that fails its criteria is re-spawned with the feedback.
|
|
122
|
+
- An independent review of each PR head before merge; the implementer never reviews
|
|
123
|
+
its own work.
|
|
105
124
|
|
|
106
|
-
|
|
107
|
-
|-------|---------|---------------|
|
|
108
|
-
| **Implement** | Write code per task spec and acceptance criteria | Worker (focused) |
|
|
109
|
-
| **Validate** | Check implementation against spec, ADRs, and contracts | Lead (reasoning) |
|
|
110
|
-
| **Test** | Run tests, verify acceptance criteria pass | Worker (focused) |
|
|
111
|
-
| **Release** | Version, deploy, verify, mark complete | Lead (reasoning) |
|
|
125
|
+
### Contribution (cross-cutting)
|
|
112
126
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
### Contribution Protocol (Cross-cutting)
|
|
116
|
-
|
|
117
|
-
Runs alongside BOTH phases. Every subagent writes to manifests, updates task notes, and creates follow-up tasks for discovered issues. Nothing falls through the cracks.
|
|
118
|
-
|
|
119
|
-
### Pipeline Gate Enforcement
|
|
120
|
-
|
|
121
|
-
Before spawning ANY task, gates verify RCASD stages completed in order. Default mode is **strict** (blocks spawn if prerequisites missing). Advisory and off modes available for prototyping/emergencies.
|
|
122
|
-
|
|
123
|
-
> Full decision tree, enforcement modes, and emergency bypass: `references/lifecycle-gates.md`
|
|
127
|
+
Every subagent writes to the manifest, updates task notes and files follow-up tasks for
|
|
128
|
+
what it discovers. Nothing falls through the cracks.
|
|
124
129
|
|
|
125
130
|
## Model Assignment (Preferred, Not Required)
|
|
126
131
|
|
|
@@ -203,51 +208,55 @@ blocker: none when complete; required when partial/blocked. `manifest:none` only
|
|
|
203
208
|
cleo session status # Resume existing?
|
|
204
209
|
cleo dash # Project overview
|
|
205
210
|
cleo current # Active task?
|
|
206
|
-
cleo orchestrate
|
|
211
|
+
cleo orchestrate ready T1575 # Parallel-safe tasks in the current wave
|
|
207
212
|
```
|
|
208
213
|
|
|
209
|
-
### 2.
|
|
214
|
+
### 2. Plan the Work
|
|
210
215
|
|
|
211
216
|
```
|
|
212
217
|
1. Create epic: cleo add "Title" --type epic --size large --priority critical \
|
|
213
218
|
--acceptance "AC1|AC2|AC3" --description "What and why"
|
|
214
|
-
2. Spawn Team Lead (sonnet) to
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
218
|
-
-
|
|
219
|
-
- Decomposition → atomic tasks under epic with deps + acceptance criteria
|
|
219
|
+
2. Spawn a Team Lead (sonnet) to write the plan document:
|
|
220
|
+
- Findings → explore codebase, reference apps, gather context
|
|
221
|
+
- Decision → approach and patterns; owner choices via the ask tool
|
|
222
|
+
- Spec → acceptance criteria every task can prove
|
|
223
|
+
- Decomposition → atomic tasks under the epic with deps + acceptance criteria
|
|
220
224
|
3. Review decomposition — verify tasks are atomic, deps correct, criteria testable
|
|
221
225
|
4. Present plan to human for approval
|
|
222
226
|
```
|
|
223
227
|
|
|
224
|
-
**
|
|
225
|
-
|
|
226
|
-
`.cleo/rcasd
|
|
227
|
-
|
|
228
|
+
**Planning documents go to the store (T13363 AC2, T13943).** Draft the document
|
|
229
|
+
(research findings, consensus record, spec, plan) in your worktree or scratch space,
|
|
230
|
+
never under `.cleo/rcasd/`, and push it into the CleoDocs store so its `##` sections
|
|
231
|
+
land as versioned, collaboratively-mergeable sections:
|
|
228
232
|
|
|
229
233
|
```bash
|
|
230
|
-
# First time — owner is the epic task, kind matches the
|
|
231
|
-
cleo docs add T1575
|
|
232
|
-
--type research --slug t1575-research
|
|
234
|
+
# First time — owner is the epic task, kind matches the document
|
|
235
|
+
cleo docs add T1575 ./T1575-research.md --type research --slug t1575-research
|
|
233
236
|
|
|
234
237
|
# Re-runs / refreshes update the same doc (noop when bytes are unchanged)
|
|
235
|
-
cleo docs update t1575-research --file
|
|
236
|
-
--message "research
|
|
238
|
+
cleo docs update t1575-research --file ./T1575-research.md \
|
|
239
|
+
--message "research refresh"
|
|
237
240
|
```
|
|
238
241
|
|
|
239
|
-
Retrieve with `cleo docs fetch t1575-research`.
|
|
240
|
-
|
|
241
|
-
|
|
242
|
+
Retrieve with `cleo docs fetch t1575-research`. A document is not "published" until
|
|
243
|
+
the store doc exists.
|
|
244
|
+
|
|
245
|
+
**Agents talk over AgentMBX (D11172).** Spawned agents coordinate with their lead and
|
|
246
|
+
peers through AgentMBX (`mbx_*` tools; the `agentmbx` CLI can only send without the
|
|
247
|
+
session's MCP lease). Spawn prompts carry an `## Agent Coordination (AgentMBX)` section and
|
|
248
|
+
no CONDUIT subscription; `cleo orchestrate spawn <taskId> --lead-mbx <you>` names your
|
|
249
|
+
mailbox in it. `cleo conduit` and the `conduit-*` sub-commands of `cleo orchestrate` are
|
|
250
|
+
deprecated (T13982) and leave in the next release; do not build on them.
|
|
242
251
|
|
|
243
|
-
### 3.
|
|
252
|
+
### 3. Execute the Work
|
|
244
253
|
|
|
245
254
|
```
|
|
246
255
|
1. Read the waves: cleo orchestrate waves T1575 (take each wave n from here;
|
|
247
256
|
numbers can skip and the first need not be 1), then cleo orchestrate ready T1575
|
|
248
257
|
2. Spawn Workers in parallel for each ready task in the first incomplete wave
|
|
249
258
|
3. On completion: read manifest, check acceptance criteria
|
|
250
|
-
4. If criteria NOT met → re-spawn worker with feedback
|
|
259
|
+
4. If criteria NOT met → re-spawn worker with feedback
|
|
251
260
|
5. Advance to the next wave cleo orchestrate waves lists (its deps are now done)
|
|
252
261
|
6. Repeat until all tasks complete
|
|
253
262
|
7. Final validation with Lead across the full epic
|
|
@@ -267,7 +276,7 @@ write is not fatal — but a stage is not "published" until the store doc exists
|
|
|
267
276
|
previously-deferred tasks promote into `admitted`. This is pull-based; never
|
|
268
277
|
fail or skip a deferred task, just retry it on the next pull.
|
|
269
278
|
- If a `cleo orchestrate spawn` returns `E_RESOURCE_DEFERRED` (the hard gate
|
|
270
|
-
denied an `agent-session` slot under pressure), treat it
|
|
279
|
+
denied an `agent-session` slot under pressure), treat it as a retryable deferral:
|
|
271
280
|
wait `details.retryAfterMs` and re-spawn. No worktree/process was provisioned,
|
|
272
281
|
so there is nothing to clean up.
|
|
273
282
|
|
|
@@ -319,7 +328,7 @@ Agent B reads the full file directly if details needed
|
|
|
319
328
|
|
|
320
329
|
When operating without continuous HITL oversight, additional constraints apply: single coordination point, manifest-only reads, verify before next spawn, wave-order spawning, followup task creation for partial/blocked, auto-handoff at 80% context.
|
|
321
330
|
|
|
322
|
-
**Autonomous scope**: task execution, dependency resolution, manifest writes, wave-order spawning,
|
|
331
|
+
**Autonomous scope**: task execution, dependency resolution, manifest writes, wave-order spawning, advancing a new epic to implementation before its children exist (when the stage gate is on).
|
|
323
332
|
|
|
324
333
|
**Requires HITL**: architectural decisions, scope expansion, destructive operations, cross-epic work, git push to main.
|
|
325
334
|
|
|
@@ -329,15 +338,11 @@ When operating without continuous HITL oversight, additional constraints apply:
|
|
|
329
338
|
|
|
330
339
|
| Command | Purpose |
|
|
331
340
|
|---------|---------|
|
|
332
|
-
| `cleo orchestrate start T1575` | Full startup: session + pipeline + next task |
|
|
333
341
|
| `cleo orchestrate ready T1575` | Parallel-safe tasks in current wave |
|
|
334
342
|
| `cleo orchestrate spawn T1586 --json` | Generate resolved spawn prompt |
|
|
335
343
|
| `cleo orchestrate next T1575` | Suggest next task |
|
|
336
344
|
| `cleo saga rollup <sagaId>` | Cross-Epic status aggregation when orchestrating a multi-Epic Saga (ADR-073) |
|
|
337
345
|
| `cleo saga members <sagaId>` | Member Epics of a Saga (parent_id containment — NOT `task_relations.groups`) |
|
|
338
|
-
| `cleo pipeline stage.status --epic T1575` | Current pipeline stage |
|
|
339
|
-
| `cleo pipeline stage.validate T1575 implementation` | Check gate before spawn |
|
|
340
|
-
| `cleo pipeline stage.gate.pass T1575 research` | Advance pipeline stage |
|
|
341
346
|
| `cleo find "query"` | Search tasks |
|
|
342
347
|
| `cleo show T1234` | Full task details |
|
|
343
348
|
| `cleo add "Task" --parent T1575` | Create child task |
|
|
@@ -404,7 +409,6 @@ before the verify call — audited to `.cleo/audit/force-bypass.jsonl`.
|
|
|
404
409
|
| Token injection system | `references/orchestrator-tokens.md` |
|
|
405
410
|
| Error recovery & context budget | `references/orchestrator-recovery.md` |
|
|
406
411
|
| Autonomous operation | `references/autonomous-operation.md` |
|
|
407
|
-
| Lifecycle gate enforcement | `references/lifecycle-gates.md` |
|
|
408
412
|
| Common HITL patterns | `references/orchestrator-patterns.md` |
|
|
409
413
|
| Handoff chain protocol | `references/orchestrator-handoffs.md` |
|
|
410
414
|
| Subagent protocol block | `references/SUBAGENT-PROTOCOL-BLOCK.md` |
|
|
@@ -1,16 +1,17 @@
|
|
|
1
1
|
You are an orchestrator. You MUST NOT implement code directly.
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
-
|
|
5
|
-
|
|
6
|
-
-
|
|
3
|
+
Every piece of work runs one loop: plan, execute, verify.
|
|
4
|
+
- Plan: one plan document per epic (cleo docs, --type plan), decisions in BRAIN,
|
|
5
|
+
atomic tasks with acceptance criteria and dependencies
|
|
6
|
+
- Execute: waves and ready tasks from cleo orchestrate, agents coordinate over AgentMBX
|
|
7
|
+
- Verify: evidence gates per task, an independent review per PR head
|
|
7
8
|
|
|
8
9
|
Delegate ALL work to subagents. Spawning is two steps:
|
|
9
10
|
1. `cleo orchestrate spawn T####` generates a fully-resolved prompt
|
|
10
11
|
2. Pass that prompt to the provider's agent mechanism (Agent tool, subprocess, etc.)
|
|
11
12
|
|
|
12
|
-
Before spawning, check
|
|
13
|
-
Do not spawn implementation work until
|
|
13
|
+
Before spawning, check `cleo orchestrate ready <epicId>`.
|
|
14
|
+
Do not spawn implementation work until the plan document and tasks exist.
|
|
14
15
|
|
|
15
16
|
CLEO CLI is the first-class project management layer — primary regardless
|
|
16
17
|
of LLM provider or harness. Model assignment (opus/sonnet/haiku) is
|
|
@@ -28,8 +28,9 @@ cleo orchestrate next T1575
|
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
30
|
# 1. Check state on conversation start
|
|
31
|
-
cleo
|
|
32
|
-
|
|
31
|
+
cleo session status
|
|
32
|
+
cleo orchestrate status --epic T1575
|
|
33
|
+
# Shows: session active, epic progress, ready tasks
|
|
33
34
|
|
|
34
35
|
# 2. Check for incomplete subagent work
|
|
35
36
|
cleo research pending
|
|
@@ -141,14 +142,12 @@ cleo release reconcile v0.85.0
|
|
|
141
142
|
|
|
142
143
|
See `src/protocols/release.md` for the full release protocol specification.
|
|
143
144
|
|
|
144
|
-
## Full
|
|
145
|
+
## Full Epic Loop
|
|
145
146
|
|
|
146
147
|
```bash
|
|
147
|
-
#
|
|
148
|
-
cleo orchestrate spawn T100 # research protocol
|
|
149
|
-
cleo orchestrate spawn
|
|
150
|
-
cleo orchestrate spawn T102 # specification protocol
|
|
151
|
-
cleo orchestrate spawn T103 # decomposition protocol
|
|
148
|
+
# PLAN (one plan document, decisions in BRAIN, tasks with AC)
|
|
149
|
+
cleo orchestrate spawn T100 # research protocol: findings section
|
|
150
|
+
cleo orchestrate spawn T103 # decomposition protocol: tasks with deps + AC
|
|
152
151
|
|
|
153
152
|
# EXECUTION (core phase)
|
|
154
153
|
cleo orchestrate spawn T104 # implementation protocol
|
|
@@ -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.8.
|
|
4
|
+
version: 2.8.6
|
|
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.8.
|
|
20
|
+
version: 2.8.6
|
|
21
21
|
tier: core
|
|
22
22
|
install: harness
|
|
23
23
|
covers:
|
|
@@ -29,7 +29,7 @@ metadata:
|
|
|
29
29
|
- packages/core/src/validation/protocols/cant/implementation.cant
|
|
30
30
|
- packages/core/src/validation/protocols/protocols-markdown/implementation.md
|
|
31
31
|
loomStage: implementation
|
|
32
|
-
lastReviewed: 2026-10-
|
|
32
|
+
lastReviewed: 2026-10-24
|
|
33
33
|
stability: stable
|
|
34
34
|
---
|
|
35
35
|
|
|
@@ -213,7 +213,7 @@ Record it with `cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC
|
|
|
213
213
|
|
|
214
214
|
## Acceptance Criteria Verification
|
|
215
215
|
|
|
216
|
-
Record each criterion's changed artifacts and actual verification results. A merged PR with green CI provides provenance; it cannot automatically satisfy implementation, testing and review. Use `pr:<number>;files:<changed-path>` for implementation (`pr:<component>@<integration>` when your PR merged into an integration branch) and actual result atoms for test/review gates, with explicit `satisfies:T1234#AC1` links for canonical criteria. The PR must relate to the task; documentation-only changes cannot prove a code fix. Research and documentation tasks may use appropriately scoped documentary evidence. Fetch the merge commit before claiming its artifact bytes were inspected. Criterion edits require fresh evidence. A completed child does not establish that its parent's independent criteria were met. `cleo verify <id> --all` sets every required gate at once and still requires `--evidence`; bare `--all` is rejected with `E_EVIDENCE_MISSING`. A failing `tool:<name>` reason names the resolved command and its source, so check that command before retrying. To adopt a native typecheck or lint run for `qaPassed` without re-running it, record one `qa-run:<receipt.json>` per check (`cleo verify --help` lists the receipt shape).
|
|
216
|
+
Record each criterion's changed artifacts and actual verification results. A merged PR with green CI provides provenance; it cannot automatically satisfy implementation, testing and review. Use `pr:<number>;files:<changed-path>` for implementation (`pr:<component>@<integration>` when your PR merged into an integration branch) and actual result atoms for test/review gates, with explicit `satisfies:T1234#AC1` links for canonical criteria. The PR must relate to the task; documentation-only changes cannot prove a code fix. Research and documentation tasks may use appropriately scoped documentary evidence: they owe `verification.requiredGatesByKind` (default: the required gates without `testsPassed`/`qaPassed`), but once their work touches any non-document path they owe the full code gates, whatever their kind or labels. Fetch the merge commit before claiming its artifact bytes were inspected. Criterion edits require fresh evidence. A completed child does not establish that its parent's independent criteria were met. `cleo verify <id> --all` sets every required gate at once and still requires `--evidence`; bare `--all` is rejected with `E_EVIDENCE_MISSING`. A failing `tool:<name>` reason names the resolved command and its source, so check that command before retrying. To adopt a native typecheck or lint run for `qaPassed` without re-running it, record one `qa-run:<receipt.json>` per check (`cleo verify --help` lists the receipt shape).
|
|
217
217
|
|
|
218
218
|
|
|
219
219
|
| Criterion | Status | Notes |
|