@cleocode/skills 2026.10.27 → 2026.11.1-canary.2
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 +4 -4
- package/skills/ct-cleo/references/planning-loop.md +7 -3
- package/skills/ct-cleo/references/session-protocol.md +6 -8
- package/skills/ct-dev-workflow/SKILL.md +56 -77
- package/skills/ct-documentor/SKILL.md +52 -6
- package/skills/ct-orchestrator/SKILL.md +24 -29
- package/skills/ct-orchestrator/references/orchestrator-patterns.md +20 -22
- package/skills/ct-orchestrator/references/orchestrator-tokens.md +1 -1
- package/skills/ct-release-orchestrator/SKILL.md +45 -8
- package/skills/ct-task-executor/SKILL.md +10 -7
- package/skills/ct-task-executor/references/acceptance-criteria-mapping.md +1 -1
- package/skills/ct-task-executor/references/anti-patterns.md +4 -4
- package/skills/ct-task-executor/references/evidence-and-gates.md +43 -1
- package/skills/ct-task-executor/references/implementation-patterns.md +6 -5
- package/skills/manifest.json +7 -7
package/package.json
CHANGED
package/skills/ct-cleo/SKILL.md
CHANGED
|
@@ -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.
|
|
5
|
+
version: 2.25.1
|
|
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-10-
|
|
12
|
+
lastReviewed: 2026-10-28
|
|
13
13
|
stability: stable
|
|
14
14
|
---
|
|
15
15
|
|
|
@@ -152,7 +152,7 @@ Unattributed mutations warn on stderr; `session status` / `briefing` label a gue
|
|
|
152
152
|
| End session (from another terminal) | `cleo session end --session <id>` |
|
|
153
153
|
| Find work | `cleo next` → `cleo focus <id>` |
|
|
154
154
|
| Search tasks | `cleo find "query"` |
|
|
155
|
-
| Complete task | `cleo
|
|
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
156
|
| Run typed gates (the only command that executes them; 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` |
|
|
@@ -463,4 +463,4 @@ BRAIN ID going forward.
|
|
|
463
463
|
|
|
464
464
|
## Evidence must prove task criteria
|
|
465
465
|
|
|
466
|
-
|
|
466
|
+
A merged PR closes its `Closes:` tasks once `CI` is green on its exact head and a non-author reviewer recorded `met` for each AC (`cleo review verdict`); the merge sweep records `pr:`, `ci:` and `satisfies:`, so no agent step follows the merge (ADR-099; preview with `cleo done --from-merge <pr> --dry-run`). No-PR work records its own results: plan with `cleo done <id> --plan` (it never plans a whole-suite `tool:test`, T13647), then the atoms in `cleo briefing inject --section evidence`, each linked with `satisfies:T1234#AC1`. Run tests, typechecks and builds one at a time through `cleo run --wait --class <test|build|full-build> -- <cmd>` (exit 75: not admitted yet, wait and retry); never wrap `cleo run` or `cleo verify` in another queue or wrapper, and never raise heap or worker counts (`NODE_OPTIONS`, `--maxWorkers`). A changed criterion invalidates its recorded proof. Completing a child preserves an open parent whose own criteria remain unproven; child waivers never transfer to parent criteria.
|
|
@@ -34,9 +34,13 @@ gates work only where a project turns on the stage gate (below).
|
|
|
34
34
|
|
|
35
35
|
## 3. Verify
|
|
36
36
|
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
|
|
37
|
+
- PR work: the PR body names each task and its ACs (`Closes: T#### AC1,AC2`, or
|
|
38
|
+
`Refs:` for partial delivery). A non-author reviewer records a verdict per AC
|
|
39
|
+
on the PR head (`cleo review verdict`). Merge on green `CI`; the merge sweep
|
|
40
|
+
closes the task. Check the lines first with
|
|
41
|
+
`cleo done --from-merge <pr> --dry-run`.
|
|
42
|
+
- No-PR work: `cleo done <id> --plan`, record each gate with
|
|
43
|
+
`cleo verify <id> --gate <gate> --evidence "<atoms>"`, then `cleo complete <id>`.
|
|
40
44
|
|
|
41
45
|
## Spawn protocols are labels
|
|
42
46
|
|
|
@@ -144,16 +144,14 @@ cleo skills info ct-orchestrator
|
|
|
144
144
|
|
|
145
145
|
## Release Workflow
|
|
146
146
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
147
|
+
A release is one command (ADR-099). Merge all code through PRs first; `cut`
|
|
148
|
+
picks the newest commit on `origin/main` whose `CI` is green, builds the notes
|
|
149
|
+
from the changesets since the last tag, and creates the tag that starts
|
|
150
|
+
`release.yml`. Provenance is reconciled automatically by the merge sweep.
|
|
150
151
|
|
|
151
152
|
```bash
|
|
152
|
-
cleo release
|
|
153
|
-
cleo release
|
|
154
|
-
cleo release pr-status v2026.MM.N # poll the release PR + CI
|
|
155
|
-
git tag -a v2026.MM.N -m "Release v2026.MM.N" && git push origin v2026.MM.N
|
|
156
|
-
cleo release reconcile v2026.MM.N # backfill provenance
|
|
153
|
+
cleo release cut v2026.MM.N --dry-run # sha, CI run, notes, packages, task report
|
|
154
|
+
cleo release cut v2026.MM.N # tag and publish
|
|
157
155
|
```
|
|
158
156
|
|
|
159
157
|
## Project Context
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ct-dev-workflow
|
|
3
3
|
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.
|
|
4
|
-
version: 3.
|
|
4
|
+
version: 3.4.0
|
|
5
5
|
protocol: contribution
|
|
6
6
|
dependencies: []
|
|
7
7
|
sharedResources:
|
|
@@ -14,7 +14,7 @@ compatibility:
|
|
|
14
14
|
- gemini-cli
|
|
15
15
|
license: MIT
|
|
16
16
|
metadata:
|
|
17
|
-
version: 3.
|
|
17
|
+
version: 3.4.0
|
|
18
18
|
tier: core
|
|
19
19
|
install: harness
|
|
20
20
|
covers:
|
|
@@ -26,16 +26,15 @@ metadata:
|
|
|
26
26
|
- packages/core/src/hooks.ts
|
|
27
27
|
- packages/core/templates/git-hooks/**
|
|
28
28
|
- packages/contracts/src/git-hooks.ts
|
|
29
|
-
lastReviewed: 2026-10-
|
|
29
|
+
lastReviewed: 2026-10-29
|
|
30
30
|
stability: stable
|
|
31
31
|
---
|
|
32
32
|
|
|
33
33
|
# Development Workflow Context Injection
|
|
34
34
|
|
|
35
35
|
Opt-in unified-hook releases use the numbered `vYYYY.MM.N-canary.N` channel
|
|
36
|
-
through
|
|
37
|
-
|
|
38
|
-
not advance to `latest`. Preserve registry retries and installed-package soak
|
|
36
|
+
through `cleo release cut` and the OIDC workflow. The version suffix picks the npm
|
|
37
|
+
dist-tag, so publication stays on `canary` and does not advance to `latest`. Preserve registry retries and installed-package soak
|
|
39
38
|
checks. Stable promotion needs the separately retained, source-bound live harness
|
|
40
39
|
and hosted VidaPeps pilot evidence; missing or unavailable verification holds it.
|
|
41
40
|
The stable target may follow the canary base when npm has already advanced, but
|
|
@@ -303,70 +302,38 @@ git push origin HEAD
|
|
|
303
302
|
# - Installation test
|
|
304
303
|
```
|
|
305
304
|
|
|
306
|
-
### G5:
|
|
305
|
+
### G5: Pull request
|
|
307
306
|
|
|
308
|
-
|
|
307
|
+
Every change reaches main through a PR. The body names each task and the ACs the
|
|
308
|
+
PR delivers, one line per task (ADR-099):
|
|
309
309
|
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
# 2. Execute
|
|
315
|
-
./dev/bump-version.sh patch
|
|
316
|
-
|
|
317
|
-
# 3. Validate
|
|
318
|
-
./dev/validate-version.sh
|
|
319
|
-
|
|
320
|
-
# 4. Reinstall locally
|
|
321
|
-
./install.sh --force
|
|
322
|
-
cleo version
|
|
310
|
+
```
|
|
311
|
+
Closes: T1456 AC1,AC2
|
|
312
|
+
Refs: T1400 AC3
|
|
323
313
|
```
|
|
324
314
|
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
315
|
+
`Closes:` completes the task once its ACs are covered; `Refs:` binds ACs for
|
|
316
|
+
partial delivery. The PR text never waives an AC. Check the lines against the
|
|
317
|
+
store before merge:
|
|
328
318
|
|
|
329
319
|
```bash
|
|
330
|
-
|
|
331
|
-
|
|
320
|
+
cleo done --from-merge <pr> --dry-run
|
|
321
|
+
```
|
|
332
322
|
|
|
333
|
-
|
|
334
|
-
|
|
323
|
+
A reviewer that is not the author records a verdict per AC on the PR head
|
|
324
|
+
(`cleo review packet <pr> --task T1456`, then `cleo review verdict`). Merge on
|
|
325
|
+
green `CI`; the merge sweep closes the task and records its evidence. No step
|
|
326
|
+
follows the merge.
|
|
335
327
|
|
|
336
|
-
|
|
337
|
-
git push origin HEAD
|
|
328
|
+
### G6: Release
|
|
338
329
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
# - Creates GitHub Release
|
|
342
|
-
# - Generates release notes
|
|
343
|
-
# - Uploads artifacts
|
|
344
|
-
```
|
|
330
|
+
Commits never bump versions or tag. Each user-facing change carries a
|
|
331
|
+
`.changeset/` entry, and a release is one command run by the lead:
|
|
345
332
|
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
Linux `Unit Tests` shard green (a docs-only push that skipped the tests does
|
|
351
|
-
not count). It sets `skip-macos-tests=true` when the newest completed nightly
|
|
352
|
-
or `macos-main.yml` (main-push, never cancelled mid-run, pending pushes coalesce;
|
|
353
|
-
T13143, T13187) run with macOS jobs for
|
|
354
|
-
one of those commits is green. A `ci.yml` push run still queued or in progress
|
|
355
|
-
is polled for up to 10 minutes first (T13823). The SHA travels as
|
|
356
|
-
`verified-sha` and the proving run's id as `reused-ci-run`; the workflow
|
|
357
|
-
ignores the skips if it checks out another commit or `verified-sha` is empty,
|
|
358
|
-
and re-reads the reused run from the API (push to main, success, every Linux
|
|
359
|
-
shard green, same tree: the exact commit, or one it extends only by
|
|
360
|
-
whole-path-allowlisted plan, changeset `.md` and CHANGELOG.md files; T13825)
|
|
361
|
-
before it skips the Linux shards, naming the run in the
|
|
362
|
-
summary and the bump-PR body. Otherwise the 8 Linux and 8 macOS test shards run, and the reason names
|
|
363
|
-
the newest main commit that has a green macOS run. The decision is in the run
|
|
364
|
-
summary.
|
|
365
|
-
|
|
366
|
-
**Bump-PR merge.** Its `pull_request` runs stay `action_required` (no GitHub
|
|
367
|
-
App), so the orchestrator admin-merges once the dispatched `CI` run on the PR
|
|
368
|
-
head SHA is green: `gh pr merge <n> --admin --merge` — see
|
|
369
|
-
`docs/release/merge-queue-runbook.md`.
|
|
333
|
+
```bash
|
|
334
|
+
cleo release cut v2026.MM.N --dry-run # green sha, notes, packages, task report
|
|
335
|
+
cleo release cut v2026.MM.N # tags; release.yml builds and publishes
|
|
336
|
+
```
|
|
370
337
|
|
|
371
338
|
---
|
|
372
339
|
|
|
@@ -385,16 +352,27 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
|
|
|
385
352
|
|
|
386
353
|
### Do I Need a Version Bump?
|
|
387
354
|
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
355
|
+
No. Add a `.changeset/` entry for user-facing changes; versions and tags come
|
|
356
|
+
from `cleo release cut`.
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## PR Cadence (D11212)
|
|
361
|
+
|
|
362
|
+
Many small PRs, each tied to a task group, so every change is traceable from
|
|
363
|
+
task to PR to release (spec: `cleo docs fetch pr-cadence`):
|
|
364
|
+
|
|
365
|
+
- **One PR per task group.** A PR delivers one task, or a few tasks that cannot
|
|
366
|
+
land apart. Never bundle unrelated tasks to save a CI run.
|
|
367
|
+
- **Small.** Reviewable in one sitting. Split a large task into PRs that each
|
|
368
|
+
keep `main` green: `Refs:` on each, `Closes:` on the last.
|
|
369
|
+
- **Name the tasks.** One body line per task: `Closes: T#### AC1,AC2` or
|
|
370
|
+
`Refs: T#### AC3`. The `PR Task Lines` check flags a PR with none or with a
|
|
371
|
+
malformed line. A change no task owns takes the `no-task` label.
|
|
372
|
+
- **Changeset** with the same `tasks:` for user-facing changes; release notes
|
|
373
|
+
are built from them.
|
|
374
|
+
- **Batch at release time, not in PRs.** PRs merge one at a time on green
|
|
375
|
+
`CI`; `cleo release cut` ships everything merged since the last tag.
|
|
398
376
|
|
|
399
377
|
---
|
|
400
378
|
|
|
@@ -408,7 +386,7 @@ head SHA is green: `gh pr merge <n> --admin --merge` — see
|
|
|
408
386
|
# Task lifecycle
|
|
409
387
|
cleo current # Current task
|
|
410
388
|
cleo start T123 # Start task (on E_SESSION_UNBOUND: bind a session, see above)
|
|
411
|
-
cleo complete T123 # Mark done
|
|
389
|
+
cleo complete T123 # Mark done (no-PR work; PR work closes on merge)
|
|
412
390
|
|
|
413
391
|
# Find existing work
|
|
414
392
|
cleo find "query" # Search tasks
|
|
@@ -464,11 +442,12 @@ Co-Authored-By: Claude <noreply@anthropic.com>
|
|
|
464
442
|
EOF
|
|
465
443
|
)"
|
|
466
444
|
|
|
467
|
-
# 6. Push
|
|
445
|
+
# 6. Push and open a PR whose body says `Closes: T1456 AC1,AC2`
|
|
468
446
|
git push origin HEAD
|
|
447
|
+
gh pr create --fill
|
|
448
|
+
cleo done --from-merge <pr> --dry-run
|
|
469
449
|
|
|
470
|
-
# 7.
|
|
471
|
-
cleo complete T1456
|
|
450
|
+
# 7. Merge on green CI after the per-AC review; the merge sweep closes T1456
|
|
472
451
|
```
|
|
473
452
|
|
|
474
453
|
### Example 2: Documentation Only
|
|
@@ -492,11 +471,11 @@ Co-Authored-By: Claude <noreply@anthropic.com>
|
|
|
492
471
|
EOF
|
|
493
472
|
)"
|
|
494
473
|
|
|
495
|
-
# 5. Push
|
|
474
|
+
# 5. Push and open a PR whose body says `Closes: T1550 AC1`
|
|
496
475
|
git push origin HEAD
|
|
476
|
+
gh pr create --fill
|
|
497
477
|
|
|
498
|
-
# 6.
|
|
499
|
-
cleo complete T1550
|
|
478
|
+
# 6. Merge on green CI after the per-AC review; the merge sweep closes T1550
|
|
500
479
|
```
|
|
501
480
|
|
|
502
481
|
---
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ct-documentor
|
|
3
3
|
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.
|
|
4
|
-
version: 3.
|
|
4
|
+
version: 3.33.0
|
|
5
5
|
protocol: null
|
|
6
6
|
dependencies:
|
|
7
7
|
- ct-spec-writer
|
|
@@ -16,13 +16,13 @@ compatibility:
|
|
|
16
16
|
- gemini-cli
|
|
17
17
|
license: MIT
|
|
18
18
|
metadata:
|
|
19
|
-
version: 3.
|
|
19
|
+
version: 3.33.0
|
|
20
20
|
tier: core
|
|
21
21
|
install: harness
|
|
22
22
|
covers:
|
|
23
23
|
- packages/cleo/src/cli/commands/docs.ts
|
|
24
24
|
- packages/contracts/src/docs-taxonomy.ts
|
|
25
|
-
lastReviewed: 2026-10-
|
|
25
|
+
lastReviewed: 2026-10-28
|
|
26
26
|
stability: stable
|
|
27
27
|
---
|
|
28
28
|
|
|
@@ -64,11 +64,30 @@ ratio from the docs audit log, loose-markdown count (gitignore-aware scan),
|
|
|
64
64
|
`docs_wikilinks` edge count, and live `decision_adr_links` count. Use it for
|
|
65
65
|
pilot baseline comparisons — it never writes.
|
|
66
66
|
|
|
67
|
+
`cleo docs rot` (T14111) is the docs-rot check every cycle runs. A doc declares
|
|
68
|
+
the code it documents in frontmatter, `covers:` with repo globs (the skill
|
|
69
|
+
`metadata.covers` grammar); write it into the store doc and republish, never
|
|
70
|
+
the mirror alone. The report reads git only: **stale** (covered code changed on
|
|
71
|
+
main after the doc did), **duplicates** (same body, near-identical titles),
|
|
72
|
+
**orphans** (a covers glob matching nothing, a `docs/` file nothing names).
|
|
73
|
+
`--changed <base>..<head>` lists the docs a merged change left stale (the
|
|
74
|
+
post-merge sweep labels its tasks `docs-update`); `--strict` exits 2 on any
|
|
75
|
+
finding, and the release cut runs it. When you change covered code, update the
|
|
76
|
+
doc in the same PR.
|
|
77
|
+
|
|
67
78
|
`cleo docs doctor` (T13447) audits the docs store — dangling `local-file`
|
|
68
79
|
pointers, docVersion skew vs the audit log, empty topics/related_tasks,
|
|
69
|
-
`docs_wikilinks` drift, legacy store surfaces, stale drafts
|
|
70
|
-
|
|
71
|
-
|
|
80
|
+
`docs_wikilinks` drift, legacy store surfaces, stale drafts, and
|
|
81
|
+
`docs_publications` ledger rows whose mirror is gone (including dead worktree
|
|
82
|
+
paths) or stale (T14117) — and with `--apply` repairs them after creating a
|
|
83
|
+
backup automatically. The ledger syncs across devices, so a row is pruned
|
|
84
|
+
only when its mirror is provably gone (absent from HEAD and the default
|
|
85
|
+
branch, or in a removed worktree of this device) and its blob stays
|
|
86
|
+
referenced elsewhere; absolute paths and other devices' paths are only
|
|
87
|
+
reported. Each pruned row is first appended to
|
|
88
|
+
`.cleo/audit/docs-publications-prune.jsonl`, and stale mirrors are only
|
|
89
|
+
reported (republish, or ingest the edit with `cleo docs update`). Use it for store
|
|
90
|
+
hygiene checks; it never edits doc content.
|
|
72
91
|
|
|
73
92
|
`cleo docs migrate` (T13360) imports legacy docs + history into the re-keyed
|
|
74
93
|
conduit store inside the migration safety harness (pre-step backup, verified
|
|
@@ -155,6 +174,14 @@ materializing through `cleo docs add` + (optionally) `cleo docs publish`.
|
|
|
155
174
|
|
|
156
175
|
---
|
|
157
176
|
|
|
177
|
+
## Kinds and names (T14107 · D11210)
|
|
178
|
+
|
|
179
|
+
One kind per published directory; `cleo docs list-types` prints them (adr, spec, plan, research, guide, concept, reference, migration, release-note, note; handoffs are store-only and never published). Name a doc by its subject: lowercase kebab-case, at most 64 characters, with no task id, session id or date in it. The ADR number and the release-note version are allowed. Task and decision links and dates go in the doc's metadata. `cleo docs add` refuses a new slug that breaks the rule with `E_DOC_NAME_RULE` and a subject-only suggestion (existing docs keep their names and still read, update and fetch), CLEO's own minted slugs (ADR allocation, the spawn `{{TOPIC_SLUG}}`) follow it, and `cleo check canon docs` refuses a tracked doc whose name breaks the rule, naming the `git mv` that fixes it; the rule is implemented once in `packages/core/src/docs/doc-name-rule.ts` (`docNameViolation`), and names that broke it before it existed are in the shrink-only `scripts/.docs-name-baseline.json`.
|
|
180
|
+
|
|
181
|
+
## Update before create (T14109 · D11210)
|
|
182
|
+
|
|
183
|
+
Before adding a doc, find the one that already covers the subject and update it. `cleo docs add` refuses a likely duplicate with `E_DOC_DUPLICATE`: same content, a similar slug of the same kind, a similar title, or text that mostly repeats an existing doc. The refusal names the existing doc's slug and title and the commands to read it (`cleo docs fetch <slug>`) and update it (`cleo docs update <slug>`). Add a new doc anyway only when it really is different, with `--new-because "<why it is not the existing doc>"`; the reason is recorded in `.cleo/audit/docs-new-because.jsonl`. `--allow-similar` alone no longer bypasses the check.
|
|
184
|
+
|
|
158
185
|
## Decision: update vs supersede vs create (T10168 · Saga T9855 / E12)
|
|
159
186
|
|
|
160
187
|
Before adding a new doc, ALWAYS ask: is this **a new doc**, **a change to an existing doc**, or **a replacement for an existing doc**? Prefer the canonical six-verb path (`add` / `update` / `fetch` / `list` / `remove` / `publish`). Legacy verbs annotated below.
|
|
@@ -785,6 +812,25 @@ BEFORE creating ANY new file, you MUST:
|
|
|
785
812
|
4. Only create new files when NO suitable location exists
|
|
786
813
|
```
|
|
787
814
|
|
|
815
|
+
### Modernize a messy docs folder (T14113)
|
|
816
|
+
|
|
817
|
+
To clean up a whole tree (task- or date-named files, duplicates, split
|
|
818
|
+
category folders), use `cleo docs modernize` instead of moving files by hand:
|
|
819
|
+
|
|
820
|
+
```bash
|
|
821
|
+
cleo docs modernize docs --out plan.json # dry run: kind, slug, keep/rename/merge-into/delete + reasons
|
|
822
|
+
cleo docs modernize --apply --plan plan.json # apply the reviewed plan; prints a receipt runId
|
|
823
|
+
cleo docs modernize --rollback dm-20261028-150000-abc123 # reverse that run
|
|
824
|
+
cleo docs modernize --store # stored docs: re-kind, re-slug (old slug stays an alias), renumber colliding ADRs
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
Ambiguous classify and merge calls are judged by System One
|
|
828
|
+
(`docs.modernize.classify`, `docs.modernize.merge`; rule fallback when it is
|
|
829
|
+
unreachable) and recorded on each plan row. Apply stores survivors, folds
|
|
830
|
+
duplicates in, supersedes the removed docs, rewrites relative links to
|
|
831
|
+
`[[slug]]` wikilinks (recorded as `links-to` graph edges) and keeps every
|
|
832
|
+
replaced byte under `.cleo/modernize/<runId>/` for rollback.
|
|
833
|
+
|
|
788
834
|
---
|
|
789
835
|
|
|
790
836
|
## Workflow Phases
|
|
@@ -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.2.0
|
|
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-28
|
|
12
12
|
stability: stable
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -117,10 +117,13 @@ the stage gate (see Plan).
|
|
|
117
117
|
|
|
118
118
|
### Verify
|
|
119
119
|
|
|
120
|
-
-
|
|
121
|
-
`
|
|
122
|
-
|
|
123
|
-
its own work.
|
|
120
|
+
- PR work (ADR-099): the worker's PR body names each task and its ACs
|
|
121
|
+
(`Closes: T#### AC1,AC2`, or `Refs:` for partial delivery). A reviewer agent that is
|
|
122
|
+
not the author reviews the PR head from `cleo review packet <pr> --task <id>` and
|
|
123
|
+
records `cleo review verdict` per AC; the implementer never reviews its own work.
|
|
124
|
+
Merge on green `CI`; the merge sweep closes the task. A worker that fails its
|
|
125
|
+
criteria is re-spawned with the feedback.
|
|
126
|
+
- No-PR work: `cleo done <id> --plan`, then `cleo verify` per gate, then `cleo complete`.
|
|
124
127
|
|
|
125
128
|
### Contribution (cross-cutting)
|
|
126
129
|
|
|
@@ -349,38 +352,30 @@ When operating without continuous HITL oversight, additional constraints apply:
|
|
|
349
352
|
| `cleo show T1234` | Full task details |
|
|
350
353
|
| `cleo add "Task" --parent T1575` | Create child task |
|
|
351
354
|
| `cleo start T1586` / `cleo complete T1586` | Task lifecycle |
|
|
352
|
-
| `cleo verify T1586 --gate <g> --evidence <atoms>` | Evidence-based gate write (ADR-051) |
|
|
355
|
+
| `cleo verify T1586 --gate <g> --evidence <atoms>` | Evidence-based gate write, no-PR work (ADR-051) |
|
|
356
|
+
| `cleo review packet <pr> --task T1586` | Diff and AC text for a non-author reviewer (ADR-099) |
|
|
357
|
+
| `cleo done --from-merge <pr> --dry-run` | Check a PR's `Closes:`/`Refs:` lines before merge |
|
|
358
|
+
| `cleo release cut v2026.MM.N --dry-run` | Preview a release; drop `--dry-run` to tag and publish |
|
|
353
359
|
| `cleo manifest list --filter pending` | Followup items |
|
|
354
360
|
| `cleo session end --note "summary"` | End session with handoff context |
|
|
355
361
|
|
|
356
362
|
## Evidence-Based Completion (ADR-051 / T832)
|
|
357
363
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
364
|
+
PR work closes through the merge sweep (Verify, above): it records `pr:`, `ci:`
|
|
365
|
+
and the `satisfies:` links the reviewer's `met` verdicts bind, so no step follows
|
|
366
|
+
the merge (ADR-099). The rest of this section is for no-PR work, typed gates no CI
|
|
367
|
+
job runs, and PRs merged before the sweep shipped.
|
|
362
368
|
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
| `implemented` | `commit:<sha>` AND `files:<comma-separated>` |
|
|
368
|
-
| `testsPassed` | `ci:<pr>` once the PR merged, when the project sets `evidence.ciSatisfies`; else `tool:test-affected` when `testing.affectedCommand` is configured; else `test-run:<vitest-json>` OR `tool:test` |
|
|
369
|
-
| `qaPassed` | `ci:<pr>` under the same two conditions; else `tool:biome` AND `tool:tsc` (OR `tool:pnpm-build`) |
|
|
370
|
-
| `documented` | `files:<docs-path>` OR `url:<doc-url>` |
|
|
371
|
-
| `securityPassed` | `tool:security-scan` OR `note:<waiver>` |
|
|
372
|
-
| `cleanupDone` | `note:<summary>` |
|
|
373
|
-
|
|
374
|
-
Orchestrator workflow for each completing task:
|
|
369
|
+
Every `cleo verify` gate write requires programmatic evidence; `--all` without
|
|
370
|
+
`--evidence` is rejected, and gates are re-validated at complete time (files changed
|
|
371
|
+
between `verify` and `complete` trigger `E_EVIDENCE_STALE`). Atoms per gate:
|
|
372
|
+
`cleo briefing inject --section evidence`.
|
|
375
373
|
|
|
376
374
|
```bash
|
|
377
|
-
|
|
378
|
-
# 2. Orchestrator plans, then records (cleo done picks affected → ci → full):
|
|
379
|
-
cleo done <taskId> --plan
|
|
375
|
+
cleo done <taskId> --plan # names the evidence each gate needs
|
|
380
376
|
cleo verify <taskId> --gate implemented --evidence "commit:$(git rev-parse HEAD);files:<list>"
|
|
381
|
-
cleo verify <taskId> --gate testsPassed --evidence "
|
|
382
|
-
cleo verify <taskId> --gate qaPassed --evidence "
|
|
383
|
-
# 3. Close:
|
|
377
|
+
cleo verify <taskId> --gate testsPassed --evidence "tool:test-affected" # else test-run:<json> or tool:test
|
|
378
|
+
cleo verify <taskId> --gate qaPassed --evidence "tool:lint;tool:typecheck"
|
|
384
379
|
cleo complete <taskId>
|
|
385
380
|
```
|
|
386
381
|
|
|
@@ -108,10 +108,11 @@ cleo show T1586
|
|
|
108
108
|
# 3. Spawn validation subagent
|
|
109
109
|
cleo orchestrate spawn T1590 # Validation task
|
|
110
110
|
|
|
111
|
-
# 4.
|
|
112
|
-
cleo
|
|
113
|
-
cleo verify T1586 --gate
|
|
114
|
-
cleo verify T1586 --
|
|
111
|
+
# 4. Record gate evidence (every gate needs programmatic evidence; bare --all is rejected)
|
|
112
|
+
cleo done T1586 --plan # names the atoms each gate needs
|
|
113
|
+
cleo verify T1586 --gate testsPassed --evidence "ci:<pr>" # or tool:test-affected
|
|
114
|
+
cleo verify T1586 --gate qaPassed --evidence "ci:<pr>" # or tool:lint;tool:typecheck
|
|
115
|
+
cleo complete T1586
|
|
115
116
|
|
|
116
117
|
# 5. Parent epic auto-completes when all children verified
|
|
117
118
|
```
|
|
@@ -120,25 +121,22 @@ cleo verify T1586 --all
|
|
|
120
121
|
|
|
121
122
|
**Release tasks use the `release` protocol** via `cleo release` commands.
|
|
122
123
|
|
|
124
|
+
A release is one command (ADR-099). Every change reaches main through a merged PR
|
|
125
|
+
first; the merge sweep has already closed their tasks.
|
|
126
|
+
|
|
123
127
|
```bash
|
|
124
|
-
# 1.
|
|
125
|
-
cleo list --parent T1575 --status pending
|
|
126
|
-
|
|
127
|
-
# 2.
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
cleo release plan v0.85.0 --tasks T001,T002,T003
|
|
133
|
-
cleo release open v0.85.0
|
|
134
|
-
cleo release pr-status v0.85.0
|
|
135
|
-
git tag -a v0.85.0 -m "Release v0.85.0" && git push origin v0.85.0
|
|
136
|
-
cleo release reconcile v0.85.0
|
|
128
|
+
# 1. Check the epic: closing tasks are merged with green CI, sweep pending
|
|
129
|
+
cleo list --parent T1575 --status pending
|
|
130
|
+
|
|
131
|
+
# 2. Preview: the green sha, its CI run, notes, packages, migrations, task report
|
|
132
|
+
cleo release cut v0.85.0 --dry-run
|
|
133
|
+
|
|
134
|
+
# 3. Tag and publish (release.yml builds, publishes and records the verdict)
|
|
135
|
+
cleo release cut v0.85.0
|
|
137
136
|
```
|
|
138
137
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
`cleo release plan` → `open` → tag → `reconcile`.
|
|
138
|
+
Provenance is reconciled automatically by the merge sweep. The old plan, open and
|
|
139
|
+
pr-status verbs and the hand-pushed tag are retired (T14114).
|
|
142
140
|
|
|
143
141
|
See `src/protocols/release.md` for the full release protocol specification.
|
|
144
142
|
|
|
@@ -158,7 +156,7 @@ cleo orchestrate spawn T105 # implementation protocol
|
|
|
158
156
|
# contribution protocol auto-triggers for shared resources
|
|
159
157
|
|
|
160
158
|
# RELEASE (polish phase)
|
|
161
|
-
cleo release
|
|
162
|
-
cleo release
|
|
159
|
+
cleo release cut v0.74.0 --dry-run
|
|
160
|
+
cleo release cut v0.74.0
|
|
163
161
|
cleo session end --note "Feature X released v0.74.0"
|
|
164
162
|
```
|
|
@@ -52,7 +52,7 @@ template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
|
|
|
52
52
|
|-------|-------------|---------|---------|
|
|
53
53
|
| `{{TASK_ID}}` | CLEO task identifier | `^T[0-9]+$` | `T1234` |
|
|
54
54
|
| `{{DATE}}` | ISO date | `YYYY-MM-DD` | `2026-01-20` |
|
|
55
|
-
| `{{TOPIC_SLUG}}` |
|
|
55
|
+
| `{{TOPIC_SLUG}}` | The task's subject in kebab-case: no task id, session id or date (the doc naming rule, T14129) | `[a-zA-Z0-9_-]+` | `auth-research` |
|
|
56
56
|
|
|
57
57
|
### Task Command Tokens (CLEO defaults)
|
|
58
58
|
|
|
@@ -1,21 +1,23 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ct-release-orchestrator
|
|
3
|
-
description: "Orchestrates the
|
|
3
|
+
description: "Orchestrates CLEO releases. Default (T14102): cleo release cut {version} tags the newest main commit with green CI, and release.yml writes the CHANGELOG from changesets, publishes, and opens an auto-merging CHANGELOG + version PR; cleo release reconcile records provenance. The SPEC-T9345 4-verb pipeline (cleo release plan, cleo release open, PR + tag) stays one release as a fallback (T14114). The deprecated cleo release ship monolith was deleted in T10103 — do not invoke it. Use ship-e2e-smoke to validate the full pipeline end-to-end (dry-run by default). The full verb-to-state map is in docs/release/verb-matrix.md. Use when shipping a new version, validating the release pipeline end-to-end, or promoting a completed epic to released status."
|
|
4
4
|
protocol: release
|
|
5
5
|
adrRefs:
|
|
6
6
|
- ADR-053
|
|
7
7
|
- ADR-063
|
|
8
8
|
- ADR-065
|
|
9
9
|
metadata:
|
|
10
|
-
version: 3.
|
|
10
|
+
version: 3.5.0
|
|
11
11
|
tier: on-demand
|
|
12
12
|
install: harness
|
|
13
13
|
covers:
|
|
14
14
|
- packages/core/src/validation/protocols/cant/release.cant
|
|
15
15
|
- packages/core/src/validation/protocols/protocols-markdown/release.md
|
|
16
16
|
- packages/cleo/src/cli/commands/release.ts
|
|
17
|
+
- packages/core/src/release/cut.ts
|
|
18
|
+
- packages/core/src/release/authorization.ts
|
|
17
19
|
loomStage: release
|
|
18
|
-
lastReviewed: 2026-
|
|
20
|
+
lastReviewed: 2026-11-01
|
|
19
21
|
stability: stable
|
|
20
22
|
---
|
|
21
23
|
|
|
@@ -53,6 +55,34 @@ Owns the canonical 4-verb release pipeline established by SPEC-T9345 and finalis
|
|
|
53
55
|
|
|
54
56
|
**Single release PR (T13825, owner choice 2026-10-16).** `node scripts/release-run.mjs <ver> --epic <id> --notes-review <file> [--execute]` runs plan → independent notes review (`{"reviewer","notesSha256","approved":true}` by someone other than the operator, for the plan's exact `meta.releaseNotes`) → `release/plan-<ver>` (one commit, plan + CHANGELOG.md, on the default branch's HEAD, made through the GitHub API) → `cleo release open <ver> --ref release/plan-<ver>` → waits for release-prepare and the bump PR's dispatched `CI` on its exact head → version-only assert against the merge-base → `gh pr merge --admin --merge --match-head-commit` plus the `.cleo/audit/force-bypass.jsonl` line → explicit `git tag -a` on the merge commit and push. The bump PR carries the plan and the bump. Dry-run by default; every step resumes on re-run. `--ref` alone dispatches on any plan branch; preflight skips carry over only when it adds release-plan files alone.
|
|
55
57
|
|
|
58
|
+
## One-command release (default, T14102)
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
cleo release cut v2026.10.28 --lead lead.md # report: commit, notes, packages, migrations, task status, confirm command
|
|
62
|
+
cleo release cut v2026.10.28 --sha <sha> --lead lead.md --yes # the printed confirm command: tags that commit
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Confirmation (D11212).** Nothing is tagged without `--yes`; without it the cut reports and prints the exact confirm command, pinned to the previewed sha. With `--yes`, an active standing release authorization covering the version, or the `release.agentCut` setting, allows the tag (an agent); otherwise the cut asks on the controlling terminal (`/dev/tty`) and tags only when the version is typed exactly, refusing with `E_RELEASE_NOT_AUTHORIZED` (and naming the scope to grant) when there is no terminal. The typed confirmation stops casual misuse only: a caller that drives a pseudo-terminal can still type the version. The audit row records `allowedBy` (`tty-confirm`, `authorization:<id>` or `setting:release.agentCut=<level>@<scope>`).
|
|
66
|
+
|
|
67
|
+
**Agent cut setting (T14170, D11221).** `release.agentCut` is `off` (default), `canary`, `prerelease` or `stable`; an agent sets it with `cleo config set release.agentCut canary --scope global`, with no terminal or owner password. Each level covers its own scope and every narrower one: `canary` covers `-canary.N`, `prerelease` any prerelease, `stable` everything. A project value (even `off`) shadows the global one. A cut it allows reports `allowedBy`, a warning naming the setting, and an audit row with `scope` and `settingSource`; when it does not cover the version and there is no terminal, the refusal names the exact `cleo config set` command.
|
|
68
|
+
|
|
69
|
+
**Standing authorization (T14141, D11215).** The owner grants it at a terminal with the owner-auth password: `cleo release authorize --scope canary|prerelease|stable|<version> --expires 7d --reason "<why>" [--uses <n>]` (at most 30d; no use limit unless `--uses`). It is signed with the enrolled owner key (`cleo config owner-enroll`), stored in `.cleo/release-authorizations.json` and the global store, recorded as an owner decision, and audited in `.cleo/audit/release-authorizations.jsonl`. `cleo release authorize --list` shows each grant's state; `--revoke <id>` (owner password too) ends one now with a signed revocation, and the revocation count is sealed in `.cleo/owner-settings.json` (commit it). An edited, unsigned or one-sided grant is ignored; an edited, unsigned or shortened revocation list makes every grant tampered (fail closed). `cleo doctor` reports both. A cut it allows carries `Authorized-by: <id>` in the tag message.
|
|
70
|
+
|
|
71
|
+
- **Commit:** the newest first-parent commit of `origin/main` whose `CI` check run concluded `success`; `--sha` pins one, which must itself be green. Nothing reruns the test suites: CI already passed that tree.
|
|
72
|
+
- **Notes:** the changesets added since the previous release tag, led by `--lead` (stored as the tag annotation). A changeset no merged PR brought in is refused (`E_RELEASE_UNMERGED_CHANGESET`); no green commit is `E_RELEASE_NO_GREEN_COMMIT`.
|
|
73
|
+
- **Docs rot (T14111):** the dry run shows `cleo docs rot` findings; a real stable cut refuses with `E_DOCS_ROT` before tagging while any stale, duplicate or orphaned doc remains; on a prerelease (canary) it is a warning only.
|
|
74
|
+
- **Provenance:** the merge sweep reconciles the newest stable tag automatically once its GitHub release exists (ADR-099); there is no manual reconcile step.
|
|
75
|
+
- **Cleanup (T14142):** the report shows the plan for the release tasks' worktrees and `task/*` branches, plus nested repository copies proven redundant (clean, every ref on origin) only inside the worktrees of the release's done or cancelled tasks; a confirmed cut applies it after the tag. A cleanup failure never fails the cut, and changesets naming no task skip it.
|
|
76
|
+
- **Which checkout (T14160):** `cut` runs every git and gh call, the docs-rot scan and `checkoutAtMain` in the checkout it is started from (a CLEO worktree, or the project root); it never runs git in another checkout. From a worktree the merge sweep and the cleanup, which work on the project checkout, are skipped and named in the report.
|
|
77
|
+
- **Task status is reported, never gated.** Green CI on the sha is the gate; a pending task does not block the cut.
|
|
78
|
+
- **Tag:** an annotated `v<ver>` made through the GitHub API with your `gh` token, which starts `release.yml`. It runs `cleo release write-changelog`, publishes, and on a stable release opens `release/v<ver>`, a CHANGELOG + version PR that auto-merges on green and never blocks the release.
|
|
79
|
+
|
|
80
|
+
**Gates (all re-checked):** the version is CalVer for this month, above every release tag and main's `package.json`; the commit is first-parent on `origin/main` with every `release.prRequiredWorkflows` check (app-pinned, push run) green; the local checkout is at `origin/main`; CI is judged again right before the tag; every real cut writes a row to `.cleo/audit/release-cut.jsonl`. `release.yml` runs `cleo release verify-tag` before publishing, so a hand-pushed or dispatched tag on an untested tree never ships.
|
|
81
|
+
|
|
82
|
+
**Rollback.** A bad tag before `release.yml` publishes: cancel the run (`gh run cancel <id>`) and delete the tag (`git push origin :refs/tags/v<ver>`), then cut again. After publish, fix forward with the next version. If `changelog-pr` fails after a publish, re-run that job, or open the PR by hand from main: `cleo release write-changelog <ver> --ref v<ver>` plus `node scripts/version-all.mjs --set <ver>`.
|
|
83
|
+
|
|
84
|
+
The plan/open pipeline below stays for one release as a fallback; T14114 deletes it.
|
|
85
|
+
|
|
56
86
|
## Canonical Pipeline
|
|
57
87
|
|
|
58
88
|
| Step | Verb / Workflow | Owns transition | Notes |
|
|
@@ -79,10 +109,10 @@ Optional validators (read-only / dry-run):
|
|
|
79
109
|
| RLSE-001 | Version MUST be CalVer (`YYYY.MM.patch`) per ADR-065 — never SemVer. | `cleo release plan` rejects non-CalVer; exit 53. |
|
|
80
110
|
| RLSE-002 | `CHANGELOG.md` MUST be updated before the tag — always-write is the default behaviour of `cleo release plan` (T9784 deleted the manual changelog verb). | Plan envelope refuses to advance to `pr-opened` if the changeset directory is unparseable (T10105). |
|
|
81
111
|
| RLSE-003 | All per-task evidence gates MUST be recorded via `cleo verify <task> --gate <g> --evidence …` BEFORE `cleo complete`. The legacy `cleo release verify` batch verb was deleted in T9540. | ADR-051 per-task evidence ritual. | <!-- cleo-cmd: negative-example: release verify -->
|
|
82
|
-
| RLSE-004 | The release MUST be tagged explicitly (`git tag -a v<ver>` + `git push origin v<ver>`
|
|
83
|
-
| RLSE-005 | Direct pushes to `main` are prohibited.
|
|
112
|
+
| RLSE-004 | The release MUST be tagged explicitly: by `cleo release cut` (API tag on the green sha), or on the fallback path with `git tag -a v<ver>` + `git push origin v<ver>` after the release PR merges. | Auto-tag was retired in T10434 / ADR-087: `GITHUB_TOKEN` tag pushes did not reliably trigger `release.yml`. |
|
|
113
|
+
| RLSE-005 | Direct pushes to `main` are prohibited. A cut release reaches main's CHANGELOG and versions through `release.yml`'s auto-merging `release/v<ver>` PR; the fallback path through the PR `release-prepare.yml` cuts. | ADR-065 + branch protection (see `docs/release/branch-protection-setup.md`). |
|
|
84
114
|
| RLSE-006 | Version MUST be consistent across all workspace targets resolved by `resolveVersionBumpTargets` (root package.json + every workspace package + Cargo workspace). | Version-bump preflight in `release-prepare.yml`. |
|
|
85
|
-
| RLSE-007 | Provenance reconcile
|
|
115
|
+
| RLSE-007 | Provenance reconcile runs automatically: the merge sweep calls `reconcileLatestRelease` once the GitHub release exists (ADR-099). Run `cleo release reconcile <ver>` only to recover. | T14101 merge sweep. |
|
|
86
116
|
|
|
87
117
|
## Integration
|
|
88
118
|
|
|
@@ -101,11 +131,18 @@ cleo release open v2026.6.0 --no-commit-plan
|
|
|
101
131
|
# 3. (Optional) Poll PR + CI status while the workflow runs.
|
|
102
132
|
cleo release pr-status v2026.6.0
|
|
103
133
|
|
|
104
|
-
# 4.
|
|
134
|
+
# 4. Before the tag, prove macOS on the owner's Mac (T14104): release-prepare
|
|
135
|
+
# runs no macOS shards. Check out the exact commit to tag, then:
|
|
136
|
+
node scripts/release-mac-smoke.mjs
|
|
137
|
+
# Builds it, snapshots the real stores into a sandbox (outside the backup
|
|
138
|
+
# rotation), runs the built CLI in a sandboxed HOME and writes evidence +
|
|
139
|
+
# SHA256SUMS to .cleo/release-smoke/<sha>/. Exit 0 = every command passed.
|
|
140
|
+
|
|
141
|
+
# 5. After the release PR merges, tag explicitly (auto-tag is retired).
|
|
105
142
|
git tag -a v2026.6.0 -m "Release v2026.6.0"
|
|
106
143
|
git push origin v2026.6.0
|
|
107
144
|
|
|
108
|
-
#
|
|
145
|
+
# 6. Reconcile — runs automatically inside release-publish.yml.
|
|
109
146
|
# Run manually only if backfilling a historical release.
|
|
110
147
|
cleo release reconcile v2026.6.0
|
|
111
148
|
```
|
|
@@ -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.
|
|
4
|
+
version: 2.9.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.
|
|
20
|
+
version: 2.9.0
|
|
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-28
|
|
33
33
|
stability: stable
|
|
34
34
|
---
|
|
35
35
|
|
|
@@ -103,6 +103,7 @@ Context injection for implementation tasks spawned via cleo-subagent. Provides d
|
|
|
103
103
|
3. Execute instructions (see Methodology below)
|
|
104
104
|
4. Verify deliverables against acceptance criteria
|
|
105
105
|
5. Record output: `cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC_SLUG}}`
|
|
106
|
+
- Update before create (T14109): when a doc on the topic exists, `cleo docs update <slug>` it. `cleo docs add` refuses a likely duplicate with `E_DOC_DUPLICATE` and names the existing doc; pass `--new-because "<why>"` only for a truly new doc.
|
|
106
107
|
6. Record the manifest entry: `cleo manifest append --task {{TASK_ID}} --type implementation --content "<one-paragraph summary>"`
|
|
107
108
|
7. Complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
|
|
108
109
|
8. Return summary message
|
|
@@ -145,9 +146,11 @@ A database or service started for a test run must not outlive it. A `docker run`
|
|
|
145
146
|
`cwd`; a locked stage also needs `--reason`. Then verify that gate again.
|
|
146
147
|
2. **Document completion** - Write detailed output file
|
|
147
148
|
3. **Update manifest** - Append summary entry
|
|
148
|
-
4. **Complete task** -
|
|
149
|
-
|
|
150
|
-
|
|
149
|
+
4. **Complete task** - PR work: put `Closes: <id> AC1,AC2` (or `Refs:` for partial
|
|
150
|
+
delivery) in the PR body and check it with `cleo done --from-merge <pr> --dry-run`.
|
|
151
|
+
Once a non-author reviewer records `met` per AC and the PR merges on green `CI`, the
|
|
152
|
+
merge sweep closes the task; no step follows the merge (ADR-099). No-PR work:
|
|
153
|
+
`cleo done <id> --plan`, record what it names, then `cleo complete <id>`.
|
|
151
154
|
Completion merges the task branch into the local default branch only for a worktree
|
|
152
155
|
CLEO provisioned, only when the main checkout is already on that branch with no
|
|
153
156
|
uncommitted tracked changes, and never pushes; a hand-made `task/<id>` branch is
|
|
@@ -220,7 +223,7 @@ Record it with `cleo docs add {{TASK_ID}} --content - --type note --slug {{TOPIC
|
|
|
220
223
|
|
|
221
224
|
## Acceptance Criteria Verification
|
|
222
225
|
|
|
223
|
-
Record each criterion's changed artifacts and actual verification results. A merged PR
|
|
226
|
+
Record each criterion's changed artifacts and actual verification results. A merged PR closes the tasks its body names (`Closes:`) when `CI` is green on its exact head and an independent reviewer recorded `met` for each AC (`cleo review verdict`); the PR text alone never satisfies an AC (ADR-099). Hand-recorded atoms are for no-PR work: 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). A change with unit and e2e tests can record both runs in one write, `test-run:<vitest.json>;test-run:<playwright.json>` (Playwright `--reporter=json`): their passing test files cover the change together. Rust and Python suites record `test-run:` from a JUnit XML report (cargo nextest, pytest `--junitxml`) or libtest JSON lines (`cargo test -- --format json`).
|
|
224
227
|
|
|
225
228
|
|
|
226
229
|
| Criterion | Status | Notes |
|
|
@@ -53,7 +53,7 @@ condition."
|
|
|
53
53
|
| Count | "with N files", "≥3 entries" | `find -type f | wc -l` |
|
|
54
54
|
| Length/size | "≥50 lines", "≥10K bytes" | `wc -l`, `wc -c` |
|
|
55
55
|
| Linkage | "linked from", "referenced in" | `grep -F` |
|
|
56
|
-
| Tests pass | "all tests pass", "no regressions" | `ci:<pr>`
|
|
56
|
+
| Tests pass | "all tests pass", "no regressions" | PR work: green `CI` on the PR head, recorded as `ci:<pr>` by the merge sweep; no-PR work: `tool:test-affected` (with `testing.affectedCommand`), a targeted `test-run:<json>`, or `tool:test` |
|
|
57
57
|
| Lint clean | "biome check passes" | `pnpm biome check .` |
|
|
58
58
|
| Build clean | "compiles", "type-checks" | `pnpm run build && pnpm run typecheck` |
|
|
59
59
|
| Spec match | "satisfies REQ-NNN" | manual trace + test |
|
|
@@ -22,10 +22,10 @@ token spend on the task.
|
|
|
22
22
|
1. Start with `cleo done <TASK_ID> --plan`. It picks the cheapest valid
|
|
23
23
|
evidence (affected, then CI, then full) and shows each tool's cache
|
|
24
24
|
state.
|
|
25
|
-
2.
|
|
26
|
-
|
|
27
|
-
needed.
|
|
28
|
-
3.
|
|
25
|
+
2. PR work: green `CI` on the PR head is the run. The merge sweep
|
|
26
|
+
records `ci:<pr>` for `testsPassed` and `qaPassed`; no local run and
|
|
27
|
+
no step after the merge are needed.
|
|
28
|
+
3. No-PR work: use `tool:test-affected` when `testing.affectedCommand` is
|
|
29
29
|
configured, else `test-run:<json>` from a targeted run of the test
|
|
30
30
|
files you changed (or `tool:test`).
|
|
31
31
|
4. While iterating, run only the failing or changed test files.
|
|
@@ -11,6 +11,12 @@ canonical names, and the failure modes most often hit.
|
|
|
11
11
|
Every task carries six standard gates. Optional gates may be added per
|
|
12
12
|
task; the standard set is non-negotiable.
|
|
13
13
|
|
|
14
|
+
For PR work the merge sweep records these gates itself when the PR merges:
|
|
15
|
+
`pr:<n>;files:<changed paths>` for `implemented`, `ci:<n>` for `testsPassed`
|
|
16
|
+
and `qaPassed`, each with the `satisfies:` links an independent reviewer's
|
|
17
|
+
`met` verdicts bind (ADR-099). The atoms below are for no-PR work, typed
|
|
18
|
+
gates no CI job runs, and PRs merged before the sweep shipped.
|
|
19
|
+
|
|
14
20
|
| Gate | Meaning | Evidence kind |
|
|
15
21
|
|------|---------|---------------|
|
|
16
22
|
| implemented | Code change exists | `commit:<sha>` + `files:<list>` |
|
|
@@ -89,13 +95,47 @@ cache when a cached result is suspect.
|
|
|
89
95
|
|
|
90
96
|
The merged PR's required CI checks, green on its merge commit (needs
|
|
91
97
|
`evidence.ciSatisfies: true`). Satisfies `testsPassed` and `qaPassed`
|
|
92
|
-
with no local run
|
|
98
|
+
with no local run. The merge sweep records it for every PR whose body
|
|
99
|
+
names the task (`Closes:`/`Refs:`); record it by hand only for a PR merged
|
|
100
|
+
before the sweep shipped.
|
|
93
101
|
|
|
94
102
|
```bash
|
|
95
103
|
cleo verify T### --gate testsPassed --evidence "ci:1234"
|
|
96
104
|
cleo verify T### --gate qaPassed --evidence "ci:1234"
|
|
97
105
|
```
|
|
98
106
|
|
|
107
|
+
### `deploy:<provider>/<deploymentId>@<sha>|<probe-url>`
|
|
108
|
+
|
|
109
|
+
A probed deployment of `<sha>` (T14083). CLEO GETs the probe URL at verify:
|
|
110
|
+
it must return 2xx and name the deployed SHA in an `X-Commit` or `X-Version`
|
|
111
|
+
header or in the body, and that SHA must contain the task's implemented
|
|
112
|
+
commits. It satisfies only the gates the project lists in
|
|
113
|
+
`evidence.deploySatisfies`: none by default, and never `testsPassed` unless
|
|
114
|
+
listed. A probe naming no SHA is refused; serve the SHA, then verify again.
|
|
115
|
+
The probe URL must not carry the SHA itself (`/health?sha=…` is refused: an
|
|
116
|
+
echoing endpoint would prove nothing).
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
cleo verify T### --gate documented --evidence "deploy:railway/dpl_9f3c@1a2b3c4d|https://api.example.com/health"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### `ci-run:<runId>`
|
|
123
|
+
|
|
124
|
+
A green run of `.github/workflows/repeat-run.yml` (T14149). This route is for a
|
|
125
|
+
criterion that needs a heavy or repeated run, which you never run locally or
|
|
126
|
+
waive. CLEO checks the run on GitHub and its uploaded report: the workflow,
|
|
127
|
+
dispatched on the default branch, latest attempt green, every one of the N runs
|
|
128
|
+
green, and a commit that contains the task's implemented work. The repeated
|
|
129
|
+
test file must be one the task changed, or one a linked criterion names. It
|
|
130
|
+
links criteria and never satisfies `testsPassed` alone, so record it in the
|
|
131
|
+
same write as the gate's other evidence. Record a `ci-run:` within 90 days of
|
|
132
|
+
the run, the artifact's retention; completion doesn't need the artifact.
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
gh workflow run repeat-run.yml -f test=packages/core/src/x/__tests__/y.test.ts -f runs=50
|
|
136
|
+
cleo verify T### --gate testsPassed --evidence "ci:1234;ci-run:40812345678;satisfies:T####AC2"
|
|
137
|
+
```
|
|
138
|
+
|
|
99
139
|
### `test-run:<json-path>`
|
|
100
140
|
|
|
101
141
|
Path to a vitest JSON output file. Re-validated by hash. Preferred for
|
|
@@ -148,6 +188,8 @@ they document, they do not prove. Reserve for `cleanupDone`,
|
|
|
148
188
|
|
|
149
189
|
The full per-task ritual, in order:
|
|
150
190
|
|
|
191
|
+
No-PR work (PR work closes through the merge sweep instead):
|
|
192
|
+
|
|
151
193
|
```bash
|
|
152
194
|
# 1. Implement and verify locally (run only the failing/changed test files)
|
|
153
195
|
pnpm biome check --write .
|
|
@@ -138,11 +138,12 @@ cleo done <TASK_ID> --plan # 4. tests: affected → ci → full (zero new fail
|
|
|
138
138
|
git diff --stat HEAD # 5. verify scope matches intent
|
|
139
139
|
```
|
|
140
140
|
|
|
141
|
-
Step 4 never means a manual full suite.
|
|
142
|
-
|
|
143
|
-
`
|
|
144
|
-
|
|
145
|
-
run only the failing or changed test
|
|
141
|
+
Step 4 never means a manual full suite. PR work needs no local evidence
|
|
142
|
+
run: green `CI` on the PR head is the proof, and the merge sweep records
|
|
143
|
+
`ci:<pr>` (ADR-099). No-PR work records `tool:test-affected` when
|
|
144
|
+
`testing.affectedCommand` is configured, else `test-run:<json>` from the
|
|
145
|
+
changed test files. While iterating, run only the failing or changed test
|
|
146
|
+
files.
|
|
146
147
|
|
|
147
148
|
Note: `pnpm run build` (esbuild) does NOT run the strict TS project-reference
|
|
148
149
|
typecheck. Always run `pnpm run typecheck` separately before tagging or
|
package/skills/manifest.json
CHANGED
|
@@ -226,7 +226,7 @@
|
|
|
226
226
|
},
|
|
227
227
|
{
|
|
228
228
|
"name": "ct-cleo",
|
|
229
|
-
"version": "2.
|
|
229
|
+
"version": "2.25.1",
|
|
230
230
|
"description": "CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.",
|
|
231
231
|
"path": "skills/ct-cleo",
|
|
232
232
|
"tier": 0,
|
|
@@ -566,7 +566,7 @@
|
|
|
566
566
|
},
|
|
567
567
|
{
|
|
568
568
|
"name": "ct-dev-workflow",
|
|
569
|
-
"version": "3.
|
|
569
|
+
"version": "3.4.0",
|
|
570
570
|
"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.",
|
|
571
571
|
"path": "skills/ct-dev-workflow",
|
|
572
572
|
"tier": 0,
|
|
@@ -642,7 +642,7 @@
|
|
|
642
642
|
},
|
|
643
643
|
{
|
|
644
644
|
"name": "ct-documentor",
|
|
645
|
-
"version": "3.
|
|
645
|
+
"version": "3.33.0",
|
|
646
646
|
"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.",
|
|
647
647
|
"path": "skills/ct-documentor",
|
|
648
648
|
"tier": 0,
|
|
@@ -1001,7 +1001,7 @@
|
|
|
1001
1001
|
},
|
|
1002
1002
|
{
|
|
1003
1003
|
"name": "ct-orchestrator",
|
|
1004
|
-
"version": "4.
|
|
1004
|
+
"version": "4.2.0",
|
|
1005
1005
|
"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.",
|
|
1006
1006
|
"path": "skills/ct-orchestrator",
|
|
1007
1007
|
"tier": 0,
|
|
@@ -1167,8 +1167,8 @@
|
|
|
1167
1167
|
},
|
|
1168
1168
|
{
|
|
1169
1169
|
"name": "ct-release-orchestrator",
|
|
1170
|
-
"version": "3.
|
|
1171
|
-
"description": "Orchestrates the
|
|
1170
|
+
"version": "3.5.0",
|
|
1171
|
+
"description": "Orchestrates CLEO releases. Default (T14102): cleo release cut {version} tags the newest main commit with green CI, and release.yml writes the CHANGELOG from changesets, publishes, and opens an auto-merging CHANGELOG + version PR; cleo release reconcile records provenance. The SPEC-T9345 4-verb pipeline (cleo release plan, cleo release open, PR + tag) stays one release as a fallback (T14114). The deprecated cleo release ship monolith was deleted in T10103 — do not invoke it. Use ship-e2e-smoke to validate the full pipeline end-to-end (dry-run by default). The full verb-to-state map is in docs/release/verb-matrix.md. Use when shipping a new version, validating the release pipeline end-to-end, or promoting a completed epic to released status.",
|
|
1172
1172
|
"path": "skills/ct-release-orchestrator",
|
|
1173
1173
|
"tier": 1,
|
|
1174
1174
|
"deliveryTier": "on-demand",
|
|
@@ -1489,7 +1489,7 @@
|
|
|
1489
1489
|
},
|
|
1490
1490
|
{
|
|
1491
1491
|
"name": "ct-task-executor",
|
|
1492
|
-
"version": "2.
|
|
1492
|
+
"version": "2.9.0",
|
|
1493
1493
|
"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.",
|
|
1494
1494
|
"path": "skills/ct-task-executor",
|
|
1495
1495
|
"tier": 0,
|