@cleocode/skills 2026.9.21 → 2026.9.22

package/skills/ct-orchestrator/references/orchestrator-tokens.md

@@ -16,7 +16,7 @@ The `spawn` command handles token injection automatically. For manual injection,
 # 3. Gets task context from CLEO
 # 4. Extracts manifest summaries
 # 5. Injects all tokens
-cleo orchestrate spawn T1586 --template ct-research-agent
+cleo orchestrate spawn T1586 --protocol research
 ```
 
 ### Manual Token Injection
@@ -33,7 +33,7 @@ export TI_TOPIC_SLUG="my-research-topic"
 ti_set_defaults
 
 # 3. Optional: Get task context from CLEO
-task_json=$(cleo show T1234 --format json)
+task_json=$(cleo show T1234)
 ti_set_task_context "$task_json"
 
 # 4. Load and inject skill template
@@ -70,7 +70,7 @@ template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
 
 | Token | Default Value |
 |-------|---------------|
-| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` |
+| `{{OUTPUT_DIR}}` | `.cleo/agent-outputs` (legacy token — do not write there; record output with `cleo docs add`) |
 
 
 ### Task Context Tokens (populated from CLEO task data)
@@ -113,7 +113,7 @@ For fine-grained control over token injection, use `lib/token-inject.sh` directl
 |----------|--------|--------|
 | **Required** | `{{TASK_ID}}`, `{{DATE}}`, `{{TOPIC_SLUG}}` | Must be set before injection |
 | **Task Commands** | `{{TASK_SHOW_CMD}}`, `{{TASK_START_CMD}}`, `{{TASK_COMPLETE_CMD}}`, etc. | CLEO defaults |
-| **Output Paths** | `{{OUTPUT_DIR}}`, `{{MANIFEST_PATH}}` | CLEO defaults |
+| **Output Paths** | `{{OUTPUT_DIR}}` | Legacy CLEO default — record output with `cleo docs add` and manifest entries with `cleo manifest append` |
 | **Task Context** | `{{TASK_TITLE}}`, `{{TASK_DESCRIPTION}}`, `{{DEPENDS_LIST}}`, etc. | From CLEO task data |
 | **Manifest Context** | `{{MANIFEST_SUMMARIES}}` | From recent pipeline_manifest entries |
 
@@ -129,7 +129,7 @@ ti_set_context "T1234" "2026-01-20" "auth-research"
 ti_set_defaults
 
 # 3. Get task context from CLEO
-task_json=$(cleo show T1234 --format json)
+task_json=$(cleo show T1234)
 ti_set_task_context "$task_json"
 
 # 4. Load and inject skill template
@@ -155,8 +155,8 @@ echo "$template" | grep -c '{{' && echo "WARNING: Uninjected tokens remain"
 ## Subagent Protocol Tokens
 
 Token defaults (from `skills/_shared/placeholders.json`):
-- `{{OUTPUT_DIR}}` -> `.cleo/agent-outputs`
-- `{{MANIFEST_PATH}}` -> retired (ADR-027) — use `cleo manifest append`
+- `{{OUTPUT_DIR}}` -> `.cleo/agent-outputs` (legacy token — record output with `cleo docs add`, never raw writes there)
+- The flat manifest path token is retired (ADR-027) — use `cleo manifest append`
 
 ### Inline Protocol Block (when CLI unavailable)
 
@@ -164,8 +164,8 @@ Token defaults (from `skills/_shared/placeholders.json`):
 ## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
 
 OUTPUT REQUIREMENTS:
-1. MUST write findings to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
-2. MUST append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest table per ADR-027/T1093)
+1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
+2. MUST append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027/T1093)
 3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return research content in response.
 

package/skills/ct-provenance-keeper/SKILL.md

@@ -2,9 +2,13 @@
 name: ct-provenance-keeper
 description: "Generates in-toto v1 attestations, SLSA-level provenance records, SBOMs (CycloneDX or SPDX), and sigstore/cosign signatures for published artifacts. Invoked by ct-artifact-publisher as a delegation for signing and attestation. Records the full commit, then build, then artifact, then attestation, then registry chain in .cleo/releases.json and rejects publishes whose digest does not match the attestation. Triggers when artifact-publish reaches the provenance step or when a release needs SLSA L2+ attestation."
 metadata:
-  version: 1.0.0
+  version: 1.0.2
   tier: on-demand
   install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/provenance.cant
+    - packages/core/src/validation/protocols/protocols-markdown/provenance.md
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -132,11 +136,10 @@ Each release appends a record in the following shape. The skill MUST populate ev
 Validate the provenance entry through `cleo check protocol`:
 
 ```bash
-cleo check protocol \
-  --protocolType provenance \
-  --taskId T4902 \
-  --hasAttestation true \
-  --hasSbom true
+cleo check protocol provenance \
+  --task-id T4902 \
+  --has-attestation true \
+  --has-sbom true
 ```
 
 Exit code 0 = provenance record is complete and verified. Exit code 90 = invalid config. Exit code 91 = signing key missing. Exit code 92 = signature invalid. Exit code 93 = digest mismatch (refuse to bind attestation). Exit code 94 = attestation format or subject is invalid.
@@ -163,4 +166,4 @@ Exit code 0 = provenance record is complete and verified. Exit code 90 = invalid
 5. Default to sigstore keyless signing via OIDC in CI; fall back to gpg only when configured.
 6. Generate CycloneDX SBOMs for every artifact with runtime dependencies.
 7. `.cleo/releases.json` is append-only; never mutate past entries.
-8. Validate every run via `cleo check protocol --protocolType provenance`.
+8. Validate every run via `cleo check protocol provenance`.

package/skills/ct-release-orchestrator/SKILL.md

@@ -2,16 +2,20 @@
 name: ct-release-orchestrator
 description: "Orchestrates the canonical 4-verb release pipeline introduced by SPEC-T9345: cleo release plan, then cleo release open, then PR + GHA tag workflow, then cleo release reconcile. 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."
 protocol: release
-loomStage: release
 adrRefs:
   - ADR-053
   - ADR-063
   - ADR-065
 metadata:
-  version: 3.0.0
+  version: 3.0.2
   tier: on-demand
   install: harness
-  lastReviewed: 2026-05-22
+  covers:
+    - packages/core/src/validation/protocols/cant/release.cant
+    - packages/core/src/validation/protocols/protocols-markdown/release.md
+    - packages/cleo/src/cli/commands/release.ts
+  loomStage: release
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -32,7 +36,7 @@ Owns the canonical 4-verb release pipeline established by SPEC-T9345 and finalis
 | 1 | `cleo release plan <ver> --epic <id>` | _(none)_ → `planned` | Builds the Release Plan envelope; auto-writes `CHANGELOG.md` (T10105 closes the silent-skip gap) |
 | 2 | `cleo release open <ver>` | `planned` → `pr-opened` | Dispatches `release-prepare.yml`; the workflow cuts the branch + opens the PR |
 | 3 | _(GHA)_ `release-prepare.yml` → PR merge | `pr-opened` → `pr-merged` | Owned by CI; verify via `cleo release pr-status <ver>` |
-| 4 | _(GHA)_ `auto-tag-on-release-merge.yml` (T10104) | `pr-merged` → `tag-pushed` | Auto-tag on merge — no manual `git tag` needed |
+| 4 | `git tag -a v<ver> -m "Release v<ver>" && git push origin v<ver>` | `pr-merged` → `tag-pushed` | Explicit tag after the release PR merges — `auto-tag-on-release-merge.yml` is retired (T10434, ADR-087); the tag push triggers `release.yml` |
 | 5 | `cleo release reconcile <ver>` | `tag-pushed` → `published` | Backfills 11 provenance tables; idempotent |
 
 Optional validators (read-only / dry-run):
@@ -49,15 +53,15 @@ Optional validators (read-only / dry-run):
 |----|------|-------------|
 | RLSE-001 | Version MUST be CalVer (`YYYY.MM.patch`) per ADR-065 — never SemVer. | `cleo release plan` rejects non-CalVer; exit 53. |
 | 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). |
-| 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. |
-| RLSE-004 | The release MUST be tagged via the auto-tag GHA workflow — not a manual `git tag`. | T10104 closes the auto-tag gap. |
+| 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 -->
+| RLSE-004 | The release MUST be tagged explicitly (`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`. |
 | RLSE-005 | Direct pushes to `main` are prohibited. Every release ships via a PR cut by `release-prepare.yml`. | ADR-065 + branch protection (see `docs/release/branch-protection-setup.md`). |
 | 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`. |
 | RLSE-007 | Provenance reconcile MUST run within the release-publish workflow — never as a manual followup. | Invoked by `release-publish.yml`. |
 
 ## Integration
 
-Use the explicit two-verb invocation. **Do not** invoke `cleo release ship` — it was deleted in T10103.
+Use the explicit verbs. **Do not** invoke `cleo release ship` — it was deleted in T10103. <!-- cleo-cmd: negative-example: release ship -->
 
 ```bash
 # 1. Plan — build the canonical Release Plan envelope.
@@ -69,7 +73,11 @@ cleo release open v2026.6.0
 # 3. (Optional) Poll PR + CI status while the workflow runs.
 cleo release pr-status v2026.6.0
 
-# 4. Reconcile — runs automatically inside release-publish.yml.
+# 4. After the release PR merges, tag explicitly (auto-tag is retired).
+git tag -a v2026.6.0 -m "Release v2026.6.0"
+git push origin v2026.6.0
+
+# 5. Reconcile — runs automatically inside release-publish.yml.
 #    Run manually only if backfilling a historical release.
 cleo release reconcile v2026.6.0
 ```
@@ -90,7 +98,7 @@ Exit codes (canonical):
 - `0` — success.
 - `53` — version validation failed (e.g. not CalVer).
 - `54` — release-prepare workflow gate failed.
-- `56` — tag creation failed (auto-tag workflow).
+- `56` — tag creation failed.
 - `82` — `E_PLAN_NOT_FOUND` (plan envelope missing for the requested version).
 - `83` — `E_IVTR_INCOMPLETE` (per-task IVTR loops not released).
 - `88` — artifact publish failed.
@@ -99,9 +107,9 @@ Exit codes (canonical):
 
 | Pattern | Problem | Solution |
 |---------|---------|----------|
-| Running `cleo release ship` | The verb was deleted in T10103 — the command will exit with `Unknown command`. | Use `cleo release plan` + `cleo release open`. |
+| Running `cleo release ship` | The verb was deleted in T10103 — the command will exit with `Unknown command`. | Use `cleo release plan` + `cleo release open`. | <!-- cleo-cmd: negative-example: release ship -->
 | Manually invoking `gh workflow run release-prepare.yml` | Bypasses the plan envelope; `releases.status` stays at `planned`. | Always go through `cleo release open <ver>` — it tracks state in the `releases` table. |
-| Manually `git tag v<ver> && git push --tags` | Bypasses the auto-tag workflow (T10104) and skips provenance backfill. | Let `auto-tag-on-release-merge.yml` create the tag on PR merge. |
+| Tagging before the release PR merges, or `git push --tags` | Tags an unmerged commit, or pushes every local tag. | Tag the merged release commit and push that one tag: `git push origin v<ver>`. |
 | Hand-editing `CHANGELOG.md` for the new version | Drift between the changeset directory and the changelog. | `cleo release plan` always auto-writes the section (T10105). Use `cleo changeset add` to author entries. |
 | Pasting one verb into another's workflow file | Multi-step orchestration belongs in `ship-e2e-smoke`. | Use `cleo release ship-e2e-smoke … --execute` for end-to-end validation. |
 | Running the pipeline on a dirty worktree | Release commit scoops up unrelated changes. | The clean-tree gate refuses to advance. |
@@ -110,10 +118,10 @@ Exit codes (canonical):
 ## Critical Rules Summary
 
 1. The 4-verb pipeline — `plan`, `open`, `reconcile`, `rollback` — is the ONLY way to ship.
-2. The deprecated `cleo release ship` shim was DELETED in T10103. Do not invoke it.
+2. The deprecated `cleo release ship` shim was DELETED in T10103. Do not invoke it. <!-- cleo-cmd: negative-example: release ship -->
 3. CalVer (`YYYY.MM.patch`) is the only valid version scheme.
 4. `cleo release plan` always writes the CHANGELOG section unless `--no-changelog`.
-5. The tag is created by `auto-tag-on-release-merge.yml`, not by hand.
+5. The tag is created explicitly after the release PR merges; `auto-tag-on-release-merge.yml` is retired (T10434, ADR-087).
 6. Provenance reconcile is invoked by `release-publish.yml`, not manually (unless backfilling).
 7. Per-task evidence gates use `cleo verify --gate --evidence` per ADR-051 — not the deleted batch verb.
 8. Use `cleo release ship-e2e-smoke` to validate the full pipeline before a real ship.

package/skills/ct-release-orchestrator/references/composition.md

@@ -31,7 +31,7 @@ release → artifact-publish → provenance
 | 93 | provenance | `E_DIGEST_MISMATCH` |
 | 94 | provenance | `E_ATTESTATION_INVALID` |
 
-The parent MUST NOT remap sub-protocol exit codes. A caller reading `cleo release ship` output needs to know exactly which step failed.
+The parent MUST NOT remap sub-protocol exit codes. A caller reading `cleo release open` / `cleo release pr-status` output needs to know exactly which step failed.
 
 ## Rollback Semantics
 

package/skills/ct-release-orchestrator/references/release-types.md

@@ -18,8 +18,11 @@ No package is produced. Used for docs, spec updates, and internal code changes t
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push --no-artifacts
-cleo check protocol --protocolType release --version v2026.4.5 --hasChangelog true
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
+cleo check protocol release --version v2026.4.5 --has-changelog true
 ```
 
 ## npm-Package Release
@@ -38,11 +41,14 @@ Publishes one or more npm packages from the monorepo. Uses `npm publish --proven
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI handles the publish + attestation; the skill records the result.
-cleo check protocol --protocolType release --version v2026.4.5 --hasChangelog true
-cleo check protocol --protocolType artifact-publish --artifactType npm-package --buildPassed true
-cleo check protocol --protocolType provenance --hasAttestation true --hasSbom true
+cleo check protocol release --version v2026.4.5 --has-changelog true
+cleo check protocol artifact-publish --artifact-type npm-package --build-passed true
+cleo check protocol provenance --has-attestation true --has-sbom true
 ```
 
 ## docker-image Release
@@ -61,10 +67,13 @@ Builds and pushes a container image to GHCR or another OCI registry, signs with
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI runs: docker build → cosign sign → cosign attest → syft sbom → push
-cleo check protocol --protocolType artifact-publish --artifactType docker-image --buildPassed true
-cleo check protocol --protocolType provenance --hasAttestation true --hasSbom true
+cleo check protocol artifact-publish --artifact-type docker-image --build-passed true
+cleo check protocol provenance --has-attestation true --has-sbom true
 ```
 
 ## cargo-crate Release
@@ -82,9 +91,12 @@ Publishes one or more crates from the Rust workspace to crates.io.
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI runs: cargo test → cargo publish --dry-run → cargo publish
-cleo check protocol --protocolType artifact-publish --artifactType cargo-crate --buildPassed true
+cleo check protocol artifact-publish --artifact-type cargo-crate --build-passed true
 ```
 
 ## github-tarball Release
@@ -101,9 +113,12 @@ Creates a source tarball and attaches it to a GitHub Release. Optional cosign si
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # gh release create runs in CI with the tarball attached
-cleo check protocol --protocolType artifact-publish --artifactType github-release --buildPassed true
+cleo check protocol artifact-publish --artifact-type github-release --build-passed true
 ```
 
 ## Multi-Artifact Release
@@ -120,9 +135,12 @@ A release with more than one artifact type — typical for a major version that
 ### Commands
 
 ```bash
-cleo release ship v2026.4.5 --bump-version --create-tag --push
+cleo release plan v2026.4.5 --epic T####
+cleo release open v2026.4.5
+# after the release PR merges:
+git tag -a v2026.4.5 -m "Release v2026.4.5" && git push origin v2026.4.5
 # CI orchestrates all publishes; skill records the unified chain
-cleo check protocol --protocolType release --version v2026.4.5 --hasChangelog true
+cleo check protocol release --version v2026.4.5 --has-changelog true
 ```
 
 ## Which Checklist Wins?

package/skills/ct-research-agent/SKILL.md

@@ -1,11 +1,8 @@
 ---
 name: ct-research-agent
 description: Multi-source research and investigation combining web search, documentation lookup via Context7, and codebase analysis. Synthesizes findings into actionable recommendations with proper citation and task traceability. Use when conducting research, investigating best practices, gathering technical information, or analyzing existing implementations. Triggers on research tasks, investigation needs, or information discovery requests.
-version: 2.0.0
-core: false
-category: recommended
+version: 2.0.4
 protocol: research
-loomStage: research
 adrRefs:
   - ADR-023
   - ADR-070
@@ -20,9 +17,14 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 2.0.0
+  version: 2.0.4
   tier: on-demand
   install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/research.cant
+    - packages/core/src/validation/protocols/protocols-markdown/research.md
+  loomStage: research
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -74,8 +76,8 @@ Context injection for research and investigation tasks spawned via cleo-subagent
 1. Read task: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
 2. Focus already set by orchestrator (skip if working standalone, set if needed)
 3. Conduct research (see Methodology below)
-4. Write output: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
-5. Append manifest: `{{MANIFEST_PATH}}`
+4. Record output: `cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}`
+5. Record the manifest entry: `cleo manifest append --task {{TASK_ID}} --type research --content "<one-paragraph summary>"`
 6. Complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
 7. Return summary message
 
@@ -113,8 +115,8 @@ Context injection for research and investigation tasks spawned via cleo-subagent
 
 ### Output Requirements
 
-1. MUST write findings to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
-2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+1. MUST record findings with `cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}` (never a raw file under `.cleo/agent-outputs/`)
+2. MUST record ONE manifest entry: `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027)
 3. MUST return ONLY: "Research complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return research content in response
 
@@ -122,7 +124,7 @@ Context injection for research and investigation tasks spawned via cleo-subagent
 
 ## Output File Format
 
-Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
+Record it with `cleo docs add {{TASK_ID}} --content - --type research --slug {{TOPIC_SLUG}}`, using this body:
 
 ```markdown
 # {{RESEARCH_TITLE}}
@@ -163,7 +165,7 @@ Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
 
 ## Manifest Entry Format
 
-Append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest table per ADR-027):
+Append ONE entry via `cleo manifest append --entry '<json>'` (writes to pipeline_manifest table per ADR-027):
 
 ```json
 {"id":"{{TOPIC_SLUG}}-{{DATE}}","file":"{{DATE}}_{{TOPIC_SLUG}}.md","title":"{{RESEARCH_TITLE}}","date":"{{DATE}}","status":"complete","agent_type":"research","topics":{{TOPICS_JSON}},"key_findings":["Finding 1","Finding 2","Finding 3"],"actionable":true,"needs_followup":[],"linked_tasks":["{{EPIC_ID}}","{{TASK_ID}}"]}
@@ -185,7 +187,7 @@ Append ONE entry via `cleo manifest append <json>` (writes to pipeline_manifest
 - [ ] Task details read via `{{TASK_SHOW_CMD}}`
 - [ ] Research conducted across multiple sources
 - [ ] Findings synthesized with recommendations
-- [ ] Output file written to `{{OUTPUT_DIR}}/`
+- [ ] Output recorded with `cleo docs add` (slug in the return message)
 - [ ] Manifest entry appended (single line, valid JSON)
 - [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
 - [ ] Response is ONLY the summary message

package/skills/ct-research-agent/references/triggers-and-routing.md

@@ -38,12 +38,12 @@ to sibling skills that have narrower context budgets and stricter contracts.
 | "write the spec for X" | `ct-spec-writer` |
 | "validate this implementation against the spec" | `ct-validator` |
 | "decompose this epic into tasks" | `ct-epic-architect` |
-| "look up Next.js 15 middleware API" | `ct-docs-lookup` (single-library fetch) |
+| "look up Next.js 15 middleware API" | the Context7 MCP (single-library fetch) |
 | "decide between A and B" (no investigation needed) | `ct-consensus-voter` |
 | "explain this function" | (no skill — direct read suffices) |
 
 A useful heuristic: if the user already knows the answer and just wants it
-written down, route to `ct-spec-writer` or `ct-docs-write`. Research is for
+written down, route to `ct-spec-writer` or `ct-documentor` (`references/writing.md`). Research is for
 when the answer is not yet known.
 
 ## Routing to Downstream Skills
@@ -68,11 +68,11 @@ Research outputs typically feed one of these next stages. The manifest
 
 ```
 Is the answer already known and just needs documentation?
-├── YES → ct-docs-write
+├── YES → the writing guide (`ct-documentor/references/writing.md`)
 └── NO → continue
     │
     Is this a single-library API question?
-    ├── YES → ct-docs-lookup
+    ├── YES → the Context7 MCP
     └── NO → ct-research-agent (this skill)
         │
         After research, do findings produce requirements?

package/skills/{ct-skill-creator → ct-skill-author}/SKILL.md

@@ -1,17 +1,20 @@
 ---
-name: ct-skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+name: ct-skill-author
+description: Create, improve and validate CLEO skills. Use when writing a new skill or updating an existing one (structure, frontmatter, progressive disclosure, trigger descriptions, evals), and when auditing a skill folder against the CLEO standard before it ships (structural, ecosystem-fit and quality validation with an HTML report). Internal to CLEO development — not installed to harnesses.
 license: MIT
 metadata:
-  version: 1.0.0
+  version: 2.0.1
   tier: internal
   install: internal
-  stability: deprecated
+  lastReviewed: 2026-09-28
+  stability: stable
 ---
 
-# Skill Creator
+# Skill Author
 
-This skill provides guidance for creating effective skills.
+Guidance for creating effective skills, and the validation loop that checks them.
+This skill merges the former ct-skill-creator and ct-skill-validator (T12649, D11157).
+For validation, load `references/validating.md`; its scripts live in `scripts/`.
 
 ## About Skills
 

package/skills/{ct-skill-validator → ct-skill-author}/agents/ecosystem-checker.md

@@ -93,7 +93,7 @@ Save to the path specified in your prompt (default: `ecosystem-check.json` in th
 
 ```json
 {
-  "skill_name": "ct-skill-validator",
+  "skill_name": "ct-skill-author",
   "verdict": "PASS|PASS_WITH_WARNINGS|FAIL",
   "rules": [
     {

package/skills/{ct-skill-validator → ct-skill-author}/evals/quality_evals.json

@@ -1,12 +1,12 @@
 {
-  "skill_name": "ct-skill-validator",
+  "skill_name": "ct-skill-author",
   "evals": [
     {
       "id": 1,
-      "prompt": "Validate the ct-skill-creator skill against the v2 standard and show me a full report",
-      "expected_output": "A complete tier-by-tier validation report showing pass/fail/warn status for ct-skill-creator, with an HTML report opened in the browser",
+      "prompt": "Validate the ct-skill-author skill against the v2 standard and show me a full report",
+      "expected_output": "A complete tier-by-tier validation report showing pass/fail/warn status for ct-skill-author, with an HTML report opened in the browser",
       "expectations": [
-        "Claude runs validate.py against ct-skill-creator",
+        "Claude runs validate.py against ct-skill-author",
         "The output shows results for all 5 tiers",
         "Claude runs generate_validation_report.py to produce an HTML report",
         "Claude tells the user the report path or opens it in the browser",
@@ -27,20 +27,20 @@
     },
     {
       "id": 3,
-      "prompt": "Audit the ct-skill-validator skill itself — run all checks and give me a full findings report",
-      "expected_output": "Full self-audit of ct-skill-validator including validate gauntlet and audit_body, with HTML report",
+      "prompt": "Audit the ct-skill-author skill itself — run all checks and give me a full findings report",
+      "expected_output": "Full self-audit of ct-skill-author including validate gauntlet and audit_body, with HTML report",
       "expectations": [
-        "Claude runs validate.py against ct-skill-validator",
+        "Claude runs validate.py against ct-skill-author",
         "Claude runs audit_body.py for the deep body quality audit",
         "An HTML report combining all findings is generated",
         "Claude opens or links the HTML report for the user",
-        "The result correctly reflects ct-skill-validator's actual compliance status"
+        "The result correctly reflects ct-skill-author's actual compliance status"
       ]
     },
     {
       "id": 4,
-      "prompt": "Run the manifest alignment check for ct-skill-validator against the CLEO manifest",
-      "expected_output": "Manifest alignment results showing whether ct-skill-validator is registered correctly in manifest.json and dispatch-config.json",
+      "prompt": "Run the manifest alignment check for ct-skill-author against the CLEO manifest",
+      "expected_output": "Manifest alignment results showing whether ct-skill-author is registered correctly in manifest.json",
       "expectations": [
         "Claude passes --manifest to validate.py (Tier 4 check)",
         "The manifest.json path is correctly resolved",

package/skills/{ct-skill-validator → ct-skill-author}/evals/trigger_queries.json

@@ -2,7 +2,7 @@
   {"query": "validate my skill against v2 standard", "should_trigger": true},
   {"query": "check if this skill folder is v2 compliant", "should_trigger": true},
   {"query": "audit the skill structure and frontmatter", "should_trigger": true},
-  {"query": "run v2 compliance check on ct-skill-creator", "should_trigger": true},
+  {"query": "run v2 compliance check on ct-skill-author", "should_trigger": true},
   {"query": "is my SKILL.md missing required fields", "should_trigger": true},
   {"query": "verify skill passes all CLEO validation tiers", "should_trigger": true},
   {"query": "prepare skill for distribution, check for issues", "should_trigger": true},

package/skills/{ct-skill-validator → ct-skill-author}/references/cleo-ecosystem-rules.md

@@ -45,10 +45,14 @@ Or the domain.operation shorthand when describing operations abstractly: `tasks.
 - `cleo add`, `cleo update`, `cleo complete`
 - `cleo session status`, `cleo session start`, `cleo session end`
 - `cleo memory find`, `cleo memory timeline`, `cleo memory fetch`, `cleo memory observe`
-- `cleo dash`, `cleo health`, `cleo help`
-- `cleo pipeline stage.status`, `cleo manifest append`
-- `cleo skill list`, `cleo skill show`
-- `cleo orchestrator status`, `cleo orchestrator spawn`
+- `cleo dash`, `cleo doctor`, `cleo <command> --help` (there is no `help` verb)
+- `cleo manifest append`
+- `cleo skills list`, `cleo skills info`
+- `cleo orchestrate status`, `cleo orchestrate spawn`
+
+Gate 31 (`scripts/lint-skill-commands.mjs`) checks every `cleo` invocation in a
+canonical skill against the live command manifest; run it rather than relying
+on this list.
 
 **Fail condition**: Skill references a domain.operation that does not exist in the constitution.
 

package/skills/{ct-skill-creator → ct-skill-author}/references/provider-deployment.md

@@ -10,7 +10,7 @@ Skills follow a single-source-of-truth model:
 packages/skills/skills/         <-- canonical location
   ct-cleo/SKILL.md
   ct-orchestrator/SKILL.md
-  ct-skill-creator/SKILL.md
+  ct-skill-author/SKILL.md
   ...
   manifest.json                    <-- CLEO-only metadata
 ```
@@ -57,7 +57,7 @@ CLEO-aware providers read both SKILL.md and manifest.json. The manifest provides
 
 ### CLEO Package Skills
 
-Skills in `packages/skills/skills/` are managed by CLEO infrastructure. They are deployed via the CLEO skill system and do not need manual symlink setup. The manifest.json, dispatch-config.json, and provider-skills-map.json coordinate deployment automatically.
+Skills in `packages/skills/skills/` are managed by CLEO infrastructure. They are deployed via the CLEO skill system and do not need manual symlink setup. `manifest.json` (generated from SKILL.md frontmatter) drives installation: every skill with `metadata.install: harness` is installed.
 
 ### User Global Skills
 
@@ -164,12 +164,16 @@ To add a new skill to the CLEO package (`packages/skills/`):
    }
    ```
 
-4. **Add entry to dispatch-config.json** (`packages/skills/dispatch-config.json`):
-   Add the skill to relevant `by_task_type`, `by_keyword`, and/or `by_protocol` mappings if it should participate in dispatch routing.
+4. **Add dispatch routing** if the skill should participate: add it to the
+   `dispatch_matrix` (`by_task_type`, `by_keyword`, `by_protocol`) in
+   `packages/skills/skills/manifest.json`. (`dispatch-config.json` was removed
+   in T12649; nothing read it.)
 
-5. **Update totalSkills** in manifest.json `_meta.totalSkills` to reflect the new count.
+5. **Regenerate the manifest**: `node scripts/skills/generate-manifest.mjs`.
+   It writes the identity fields and `_meta.totalSkills` from SKILL.md
+   frontmatter; gate 29 fails if you hand-edit them.
 
 6. **Validate**: Run the skill validator to confirm the new skill passes all checks:
    ```bash
-   python3 packages/skills/skills/ct-skill-creator/scripts/quick_validate.py packages/skills/skills/my-new-skill
+   python3 packages/skills/skills/ct-skill-author/scripts/quick_validate.py packages/skills/skills/my-new-skill
    ```