@cleocode/skills 2026.5.125 → 2026.5.127

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.
Files changed (5) hide show
  1. package/package.json +1 -1
  2. package/skills/ct-cleo/SKILL.md +31 -3
  3. package/skills/ct-documentor/SKILL.md +55 -29
  4. package/skills/ct-orchestrator/SKILL.md +2 -2
  5. package/skills.json +4 -4
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cleocode/skills",
3
- "version": "2026.5.125",
3
+ "version": "2026.5.127",
4
4
  "description": "CLEO skill definitions - bundled with CLEO monorepo",
5
5
  "main": "index.js",
6
6
  "types": "index.d.ts",
package/skills/ct-cleo/SKILL.md CHANGED
@@ -2,8 +2,8 @@
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.0
6
- lastReviewed: 2026-05-26
5
+ version: 2.6.0
6
+ lastReviewed: 2026-05-27
7
7
  stability: stable
8
8
  ---
9
9
 
@@ -33,6 +33,9 @@ Supported sections: `session-start` · `work-loop` · `triggers` · `task-creati
33
33
  | Saga-level waves | `cleo orchestrate waves <sagaId>` |
34
34
  | Saga rollup | `cleo saga rollup <sagaId>` |
35
35
  | List Saga members | `cleo saga members <sagaId>` |
36
+ | Attach doc to task | `cleo docs add T### file.md --type note --slug handle` |
37
+ | Read a doc | `cleo docs fetch <slug>` |
38
+ | Browse docs | `cleo docs list --task T###` |
36
39
 
37
40
  ## Skill-Specific Extensions
38
41
 
@@ -40,7 +43,7 @@ Supported sections: `session-start` · `work-loop` · `triggers` · `task-creati
40
43
  - For add-batch input, The top-level JSON MUST be an array of task objects, not an object wrapper like `{ "tasks": [...] }`.
41
44
  - Dry-run count semantics: `/data/count` and `/data/wouldCreate` predict writes; `/data/insertedCount` must be `0` for dry-run.
42
45
  - Mutation output paths: use `/data/created/0`, `/data/updated/0`, and `/data/deleted/0`; never parse legacy full records.
43
- - Docs path policy and strict preflight: keep docs repo-relative, Do not pass arbitrary external absolute paths, and discover runtime kinds with `cleo docs list-types` / `DocKindRegistry`.
46
+ - Docs path policy and strict preflight: keep docs repo-relative. Do not pass arbitrary external absolute paths. The canonical six-verb docs path is **add, update, fetch, list, remove, publish** (T10516). Use `cleo docs list` for discovery; `cleo docs list-types` (ADVANCED) and `DocKindRegistry` resolve runtime kinds when `list` is insufficient.
44
47
 
45
48
  ### Task Relationship Systems — depends, blockedBy, relates
46
49
 
@@ -216,3 +219,28 @@ cleo orchestrate report <taskId>
216
219
  # Compact context for prompt injection
217
220
  cleo focus <taskId>
218
221
  ```
222
+
223
+ ## BRAIN Decision-Store — Durable Architecture Decisions
224
+
225
+ Architectural decisions belong in the BRAIN decision-store, not in adrs markdown
226
+ blobs or agent-outputs ledgers. Use `cleo memory` commands to create, find, and
227
+ cite decisions by durable BRAIN decision IDs.
228
+
229
+ | Need | Command |
230
+ |------|---------|
231
+ | Store a decision | `cleo memory store --type decision --content "..." --title "..."` |
232
+ | Search decisions | `cleo memory decision-find --query <term>` |
233
+ | Find by type | `cleo memory find <term> --type decision` |
234
+ | Fetch full record | `cleo memory fetch <decisionId>` |
235
+ | List by epic | `cleo memory decision-find --epic <epicId>` |
236
+ | Check status | `cleo memory fetch <id>` → check `confirmation_state` field |
237
+
238
+ **Why BRAIN decisions over markdown ledgers:**
239
+ - Decisions are durable, queryable, and have source provenance (`source_table`, `source_rowid`)
240
+ - Decision IDs disambiguate overloaded D0xx/AGT-* identifiers via provenance tracking
241
+ - The decision-store supports lifecycle tracking (pending → accepted → superseded)
242
+ - Memory link pattern: cite a BRAIN decision ID in task descriptions, then `cleo memory fetch <id>` for full context
243
+
244
+ **Migration rule:** When you encounter a decision ONLY in a markdown ledger
245
+ (`.cleo/adrs/`, `.cleo/agent-outputs/`), store it in the BRAIN with
246
+ `cleo memory store --type decision` and cite the BRAIN ID going forward.
package/skills/ct-documentor/SKILL.md CHANGED
@@ -1,14 +1,14 @@
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. Coordinates ct-docs-lookup, ct-docs-write, ct-docs-review, 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.14.0
4
+ version: 3.15.0
5
5
  tier: 3
6
6
  core: false
7
7
  category: specialist
8
8
  protocol: null
9
9
  metadata:
10
- version: 3.14.0
11
- lastReviewed: 2026-05-24
10
+ version: 3.15.0
11
+ lastReviewed: 2026-05-27
12
12
  stability: stable
13
13
  dependencies:
14
14
  - ct-docs-lookup
@@ -35,12 +35,37 @@ license: MIT
35
35
 
36
36
  ---
37
37
 
38
- ## Purpose
38
+ ## Canonical Docs Command Path (T10516 — T11048)
39
39
 
40
- Context injection for documentation tasks spawned via cleo-subagent. Orchestrates documentation workflows by coordinating specialized skills for lookup, writing, and review.
40
+ The agent-facing docs surface is simplified to six canonical verbs. Use these as the
41
+ primary workflow. Legacy verbs remain available but are **advanced or migration
42
+ surfaces** — do not present them as the default path to agents.
43
+
44
+ | Canonical Verb | Purpose | When to Use |
45
+ |---------------|---------|-------------|
46
+ | `add` | Create a new doc attached to a task/session | First write of any canonical doc |
47
+ | `update` | Patch/replace an existing doc's content | Fixes, extensions, refreshes |
48
+ | `fetch` | Retrieve a doc by slug | Reading, reviewing, verifying |
49
+ | `list` | Browse docs by owner, type, or project | Discovery, checking what exists |
50
+ | `remove` | Detach a doc from an owner | Cleanup, de-duplication |
51
+ | `publish` | Mirror an SSoT blob to a git-tracked path | When a doc must live on disk |
52
+
53
+ **Legacy verbs** (advanced / migration surfaces only):
54
+ `supersede`, `find --similar`, `graph`, `versions`, `sync`, `search`,
55
+ `merge`, `rank`, `generate`, `export`, `schema`, `list-types`,
56
+ `serve`/`open`/`stop`/`viewer-status`, `status`/`gap-check`, `import`,
57
+ `publish-pr`.
58
+
59
+ For discovery (`find`, `search`, `schema`, `list-types`), prefer `cleo docs list`
60
+ first — it returns slug + owner + type without forcing a filesystem walk. Use
61
+ legacy discovery verbs only when `list` is insufficient.
41
62
 
42
63
  ---
43
64
 
65
+ ## Purpose
66
+
67
+ Context injection for documentation tasks spawned via cleo-subagent. Orchestrates documentation workflows by coordinating specialized skills for lookup, writing, and review.
68
+
44
69
  ## Skill Coordination
45
70
 
46
71
  | Skill | Purpose | Invoke When |
@@ -80,53 +105,55 @@ materializing through `cleo docs add` + (optionally) `cleo docs publish`.
80
105
 
81
106
  ## Decision: update vs supersede vs create (T10168 · Saga T9855 / E12)
82
107
 
83
- 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**?
108
+ 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.
84
109
 
85
110
  ```
86
111
  ┌─────────────────────────────────────────────────────────────────────┐
87
112
  │ Question │ Verb │
88
113
  ├─────────────────────────────────────────────────────────────────────┤
89
114
  │ Same idea, fixing/extending content? │ cleo docs update <slug> │
90
- │ → typo in ADR-076 │ (T10161 — in-place patch) │
115
+ │ → typo in ADR-076 │ (canonical — T10161) │
91
116
  │ → adding a clarifying paragraph │ │
92
117
  │ → refreshing a stale section │ │
93
118
  │ │
94
119
  │ Replacing the whole canonical model? │ cleo docs supersede │
95
- │ → "saga model v2" replaces v1 │ <old> <new> (T10162) │
96
- │ → ADR-080 replaces ADR-073 │ (lifecycle flip + lineage)│
120
+ │ → "saga model v2" replaces v1 │ <old> <new> │
121
+ │ → ADR-080 replaces ADR-073 │ (ADVANCED — T10162) │
97
122
  │ → new architecture supplants old │ │
98
123
  │ │
99
- │ Genuinely new idea? │ cleo docs find --similar │
100
- │ → drafting a new spec │ <slug> FIRST (T10163) │
101
- │ → fresh ADR for a new concern │ → if no hit, cleo docs add│
102
- │ → recording a new investigation │ → if hit, route to update │
124
+ │ Genuinely new idea? │ cleo docs list FIRST │
125
+ │ → drafting a new spec │ (canonical discovery) │
126
+ │ → fresh ADR for a new concern │ → if no hit, docs add │
127
+ │ → recording a new investigation │ → if hit, docs update │
103
128
  │ │
104
129
  │ Tracing the lineage graph? │ cleo docs graph │
105
- │ → "what does this doc replace?" │ --root <slug> (T10164) │
106
- │ → "what tasks reference this ADR?" │ │
130
+ │ → "what does this doc replace?" │ --root <slug> │
131
+ │ → "what tasks reference this ADR?" │ (ADVANCED — T10164) │
107
132
  └─────────────────────────────────────────────────────────────────────┘
108
133
  ```
109
134
 
135
+ **Canonical discovery path**: `cleo docs list` (browse by owner/type) → `cleo docs fetch <slug>` (read). Reserve `cleo docs find --similar` (ADVANCED — T10163) for near-duplicate collision checks and `cleo docs search` for semantic queries.
136
+
110
137
  ### Examples
111
138
 
112
- - **"Fix a typo in ADR-076 saga-first-class"** → `cleo docs update adr-076-saga-first-class --body /tmp/fixed.md --message "fix typo in §2"`. NOT a new doc. NOT a supersession. Just patch in place; T10161 squashes patches within a 5-minute window so consecutive typo fixes don't bloat the audit log.
139
+ - **"Fix a typo in ADR-076 saga-first-class"** - `cleo docs update adr-076-saga-first-class --file /tmp/fixed.md --message "fix typo in §2"` (canonical - T10161). NOT a new doc. NOT a supersession. Just patch in place; T10161 squashes patches within a 5-minute window so consecutive typo fixes don't bloat the audit log.
113
140
 
114
- - **"Replace the entire saga-orchestration model with v2"** → `cleo docs add T9999 v2.md --type adr --slug adr-080-saga-orchestration-v2` followed by `cleo docs supersede adr-073-above-epic-naming adr-080-saga-orchestration-v2 --reason "v2 canonicalizes the SG- prefix + 4-tier hierarchy"`. Both rows survive in the attachments table; readers see `lifecycle_status=superseded` on v1 and `supersedes=adr-073` on v2.
141
+ - **"Replace the entire saga-orchestration model with v2" (ADVANCED)** - `cleo docs add T9999 v2.md --type adr --slug adr-080-saga-orchestration-v2` followed by `cleo docs supersede adr-073-above-epic-naming adr-080-saga-orchestration-v2 --reason "v2 canonicalizes the SG- prefix + 4-tier hierarchy"`. Both rows survive in the attachments table; readers see `lifecycle_status=superseded` on v1 and `supersedes=adr-073` on v2.
115
142
 
116
- - **"Drafting a new spec for the BRAIN recovery pipeline"** → FIRST run `cleo docs find --similar brain-recovery` (T10163). If similarity > 0.85 against an existing draft, ROUTE the request into `cleo docs update` instead — the existing draft is the canonical surface. If no near-match, proceed with `cleo docs add T#### draft.md --type spec --slug spec-brain-recovery-pipeline`.
143
+ - **"Drafting a new spec for the BRAIN recovery pipeline"** - FIRST run `cleo docs list --type spec` to browse existing specs (canonical discovery). If a matching spec exists, use `cleo docs update`. If no match, proceed with `cleo docs add T#### draft.md --type spec --slug spec-brain-recovery-pipeline`. The `cleo docs find --similar brain-recovery` path is the ADVANCED collision-detection surface - use only when `list` is insufficient.
117
144
 
118
- - **"Auditing the supersession chain for ADR-039"** → `cleo docs graph --root adr-039-lafs-envelope-unification --depth 3`. Returns a DocProvenanceGraph envelope (T10166 contract) with nodes + edges, optionally `--format dot` for graphviz visualization.
145
+ - **"Auditing the supersession chain for ADR-039" (ADVANCED)** - `cleo docs graph --root adr-039-lafs-envelope-unification --depth 3`. Returns a DocProvenanceGraph envelope (T10166 contract) with nodes + edges, optionally `--format dot` for graphviz visualization.
119
146
 
120
147
  ### Anti-patterns (INSTANT REJECTION)
121
148
 
122
149
  - ❌ Calling `cleo docs add` with a slug that's only a typo-distance away from an existing doc — the auto-warn (T10167) fires `W_SLUG_SIMILAR`; respect it and route to `cleo docs update` instead of bypassing with `--allow-similar`.
123
150
  - ❌ Editing a `.cleo/adrs/*.md` file directly with `Write` — bypasses the SSoT writer; T10366 `WriterRegistry` is the chokepoint and the docs SSoT will reconcile auto-emit drift.
124
- - ❌ Creating a new doc when an existing one needs updating — bloats the attachments table and breaks lineage. The decision tree above resolves this — when in doubt, run `cleo docs find --similar <proposed-slug>` first.
151
+ - ❌ Creating a new doc when an existing one needs updating — bloats the attachments table and breaks lineage. The decision tree above resolves this — when in doubt, run `cleo docs list` first, or `cleo docs find --similar <proposed-slug>` (ADVANCED) as a last resort.
125
152
 
126
153
  ## Through SDK (preferred)
127
154
 
128
- Documentation work flows through the docs SSoT in three steps —
129
- add, publish, fetch. Use the slug-based contract so downstream consumers
155
+ Documentation work flows through the docs SSoT using the canonical six-verb path:
156
+ **add, update, fetch, list, remove, publish**. Use the slug-based contract so downstream consumers
130
157
  can retrieve docs without grepping the filesystem.
131
158
 
132
159
  ### Add a doc attached to a task
@@ -639,16 +666,15 @@ cleo docs versions --for T1234 # list every SHA version
639
666
  Slug-based fetch is the contract used by reviewers, downstream skills, and
640
667
  the docs graph — never grep the filesystem for the file you just wrote.
641
668
 
642
- ### List + sync
669
+ ### List + sync / versions
643
670
 
644
671
  ```bash
645
- cleo docs list --type spec --project # every spec in this project
646
- cleo docs list --task T1234 # everything attached to a task
647
- cleo docs sync --from docs/legacy.md --for T1234 --type note --slug legacy-doc
672
+ cleo docs list --type spec --project # canonical: every spec in this project
673
+ cleo docs list --task T1234 # canonical: everything attached to a task
674
+ cleo docs versions --for T1234 # ADVANCED: list every SHA version
675
+ cleo docs sync --from docs/legacy.md --for T1234 --type note --slug legacy-doc # ADVANCED: back-fill on-disk file into SSoT
648
676
  ```
649
677
 
650
- `cleo docs sync` back-fills an existing on-disk file into the SSoT.
651
-
652
678
  ---
653
679
 
654
680
  ## Deprecated: Direct filesystem
@@ -712,7 +738,7 @@ when scanning canonical docs — `cleo docs list` returns slug + owner + type
712
738
  without forcing a filesystem walk.
713
739
 
714
740
  ```bash
715
- # SSoT-first discovery (preferred)
741
+ # SSoT-first discovery (preferred — canonical six-verb path)
716
742
  cleo docs list --project # all docs for this project
717
743
  cleo docs list --type {TYPE} --project # docs filtered by canonical type
718
744
  cleo docs fetch {SUSPECTED_SLUG} # check if a slug exists
package/skills/ct-orchestrator/SKILL.md CHANGED
@@ -67,11 +67,11 @@ Runs **autonomously on every incoming issue**. Decomposes ideas into executable
67
67
  |-------|---------|---------------|
68
68
  | **Research** | Investigate codebase, gather context, explore options | Explorer (lightweight) |
69
69
  | **Consensus** | Validate approach, identify risks, get HITL alignment | Lead (reasoning) |
70
- | **Architecture** | Choose patterns, integration points, write ADRs | Lead (reasoning) |
70
+ | **Architecture** | Choose patterns, integration points, store decisions in BRAIN decision-store | Lead (reasoning) |
71
71
  | **Specification** | Write formal spec with RFC 2119 language, acceptance criteria | Lead (reasoning) |
72
72
  | **Decomposition** | Break into atomic tasks with deps under epic(s) | Lead (reasoning) |
73
73
 
74
- **RCASD output**: Epic(s) with child tasks, spec documents attached, dependency graph defined, acceptance criteria on every task.
74
+ **RCASD output**: Epic(s) with child tasks, spec documents attached, dependency graph defined, acceptance criteria on every task. Architecture decisions stored in BRAIN decision-store via `cleo memory store --type decision`, not in adrs markdown blobs.
75
75
 
76
76
  ### IVTR Phase (Execution)
77
77
 
package/skills.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "version": "2.1.0",
3
- "generated": "2026-05-24T00:00:00Z",
3
+ "generated": "2026-05-27T00:00:00Z",
4
4
  "skills": [
5
5
  {
6
6
  "name": "ct-cleo",
7
7
  "description": "CLEO task management protocol - core guidance for session, task, and workflow operations. Provides CLI-based workflow, session protocol, task discovery patterns, RCSD lifecycle overview, error handling, the Human Render Contract (ADR-077), and the CLI Output Contract (ADR-086). Load this skill for detailed CLEO protocol guidance.",
8
- "version": "2.3.0",
8
+ "version": "2.5.0",
9
9
  "path": "skills/ct-cleo/SKILL.md",
10
10
  "references": [
11
11
  "skills/ct-cleo/references/session-protocol.md",
@@ -27,8 +27,8 @@
27
27
  ],
28
28
  "license": "MIT",
29
29
  "metadata": {
30
- "version": "2.3.0",
31
- "lastReviewed": "2026-05-24",
30
+ "version": "2.5.0",
31
+ "lastReviewed": "2026-05-27",
32
32
  "stability": "stable"
33
33
  }
34
34
  },