@cleocode/skills 2026.9.21 → 2026.9.23

package/skills/ct-codebase-mapper/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: ct-codebase-mapper
-version: 1.0.0
-description: Codebase analysis and mapping for autonomous agent understanding. Builds structured maps of project stack, architecture, conventions, testing, integrations, and concerns.
-category: recommended
+version: 2.0.1
+description: Orient in an unfamiliar or large codebase with CLEO's code-intelligence graph (cleo nexus) and project map (cleo map). Use before planning or editing unfamiliar code, for brownfield onboarding, to find what a change would break, or to map a project's structure, communities and execution flows. Triggers on "map the codebase", "understand this project", "what calls X", "what would break", "brownfield analysis", "project structure".
 protocol: null
 dependencies: []
 compatibility:
@@ -16,71 +15,96 @@ triggers:
   - understand project
   - brownfield analysis
   - project structure
+  - blast radius
 metadata:
-  version: 1.0.0
+  version: 2.0.1
   tier: on-demand
   install: harness
+  covers:
+    - packages/cleo/src/cli/commands/nexus.ts
+    - packages/cleo/src/cli/commands/map.ts
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
 # Codebase Mapper
 
-Structured codebase analysis for autonomous agent understanding.
+Two instruments, used together:
 
-## Quick Start
+- **`cleo nexus`** is the symbol graph: callers, callees, blast radius,
+  communities and execution flows, parsed from source. Use it for any question
+  about how code connects.
+- **`cleo map`** is the project survey: stack, architecture, structure,
+  conventions, testing, integrations and concerns. Use it for the one-page
+  overview, and `--store` to keep the findings in BRAIN.
 
-| Goal | Command | Cost |
-|------|---------|------|
-| Quick analysis | `query admin map` | ~500 tokens |
-| Deep analysis + store | `mutate admin map` | ~800 tokens |
-| Focus on one area | `query admin map {focus: "concerns"}` | ~300 tokens |
-| CLI | `cleo map` / `cleo map --store` | — |
-
-## Progressive Disclosure
-
-### Tier 0: Quick Analysis
+## 1. Check the index before trusting it
 
 ```bash
-cleo map
+cleo nexus status
 ```
 
-Returns structured `CodebaseMapResult` with stack, architecture, structure, conventions, testing, integrations, and concerns.
+Read `nodeCount`, `lastIndexedAt` and `staleFileCount` against `fileCount`.
+Queries auto-refresh up to 25 stale files; beyond that they warn
+`W_NEXUS_INDEX_STALE`. Refresh with `cleo nexus analyze` (incremental; `--full`
+rebuilds). An empty or stale index gives confident-looking but incomplete
+answers — say which you relied on.
 
-### Tier 1: Store to Brain
+## 2. Survey the project
 
 ```bash
-cleo map --store
+cleo map                      # full survey
+cleo map --focus concerns     # one area: stack | architecture | structure |
+                              #   conventions | testing | integrations | concerns
+cleo map --store              # same survey, findings stored to BRAIN
+                              #   (tagged source: 'codebase-map')
 ```
 
-Same analysis, but stores patterns, learnings, and observations to brain.db. Tagged with `source: 'codebase-map'` for filtering.
+## 3. Find the structure
+
+```bash
+cleo nexus clusters               # detected communities (modules that change together)
+cleo nexus flows                  # detected execution flows (entry point → callees)
+cleo nexus search-code "<text>"   # locate a symbol by name, file pattern or keyword
+```
 
-### Tier 2: Focused Analysis
+## 4. Before editing a symbol
 
 ```bash
-cleo map --focus concerns
+cleo nexus impact <symbol>        # blast radius: direct, indirect, transitive callers
+cleo nexus context <symbol>       # callers, callees, community, flows
+cleo nexus full-context <symbol>  # plus BRAIN memories, tasks and conduit threads
 ```
 
-Focus areas: `stack`, `architecture`, `structure`, `conventions`, `testing`, `integrations`, `concerns`.
+`HIGH`/`CRITICAL` impact means review the affected callers before editing.
+`UNKNOWN` means the assessment is incomplete, and `NONE` means nothing was
+detected in the assessed graph — static analysis cannot prove every runtime
+caller, so an empty footprint alone never establishes that a change is safe.
+When a symbol name is ambiguous, pass the qualified candidate the command
+returns and confirm against the source.
 
-## When to Use
+## When to use
 
-- **New project onboarding**: Run `cleo map --store` to build brain.db context
-- **Brownfield init**: `cleo init --map-codebase` runs analysis during initialization
-- **Before epic planning**: Understand project structure before decomposing work
-- **Tech debt assessment**: `query admin map {focus: "concerns"}` for TODOs and large files
+| Situation | Start with |
+|-----------|------------|
+| New or brownfield project | `cleo nexus status`, then `cleo map --store` |
+| Planning an epic in unfamiliar code | `cleo map --focus architecture`, `cleo nexus clusters` |
+| About to change a function or type | `cleo nexus impact <symbol>` |
+| "Who calls this / what does this call?" | `cleo nexus context <symbol>` |
+| Tech-debt review | `cleo map --focus concerns` |
 
-## Output Structure
+## `cleo map` output
 
 ```typescript
 {
-  projectContext: ProjectContext,  // From detectProjectType()
-  stack: StackAnalysis,           // Languages, frameworks, deps
-  architecture: ArchAnalysis,     // Layers, entry points, patterns
-  structure: StructureAnalysis,   // Directory tree with annotations
-  conventions: ConventionAnalysis,// Naming, linting, formatting
-  testing: TestingAnalysis,       // Framework, patterns, coverage
-  integrations: IntegrationAnalysis, // APIs, DBs, CI/CD
-  concerns: ConcernAnalysis,      // TODOs, large files, complexity
+  projectContext: ProjectContext,     // From detectProjectType()
+  stack: StackAnalysis,               // Languages, frameworks, deps
+  architecture: ArchAnalysis,         // Layers, entry points, patterns
+  structure: StructureAnalysis,       // Directory tree with annotations
+  conventions: ConventionAnalysis,    // Naming, linting, formatting
+  testing: TestingAnalysis,           // Framework, patterns, coverage
+  integrations: IntegrationAnalysis,  // APIs, DBs, CI/CD
+  concerns: ConcernAnalysis,          // TODOs, large files, complexity
   analyzedAt: string
 }
 ```

package/skills/ct-consensus-voter/SKILL.md

@@ -2,14 +2,18 @@
 name: ct-consensus-voter
 description: "Runs structured multi-agent voting for decision tasks with confidence scores, conflict detection, and HITL escalation when the threshold is not met. Use when two or more agents must vote on options: architecture choices, tool selection, policy decisions, when a task carries agent_type:analysis, or on phrases like 'reach consensus', 'vote on options', 'resolve the debate', 'pick the best approach'. Produces a voting matrix JSON, enforces the 0.5 threshold, flags ties within 0.1 confidence as contested and escalates to human tiebreak."
 protocol: consensus
-loomStage: consensus
 adrRefs:
   - ADR-015
   - ADR-023
 metadata:
-  version: 1.0.0
+  version: 1.0.2
   tier: on-demand
   install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/consensus.cant
+    - packages/core/src/validation/protocols/protocols-markdown/consensus.md
+  loomStage: consensus
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -134,10 +138,9 @@ On escalation:
 Validate the matrix through `cleo check protocol`:
 
 ```bash
-cleo check protocol \
-  --protocolType consensus \
-  --votingMatrixFile ./.cleo/rcasd/T4797/consensus/T4797-consensus.json \
-  --taskId T4797
+cleo check protocol consensus \
+  --voting-matrix-file ./.cleo/rcasd/T4797/consensus/T4797-consensus.json \
+  --task-id T4797
 ```
 
 Exit code 0 = matrix is valid and verdict is `PROVEN` or `REFUTED`. Exit code 65 = `HANDOFF_REQUIRED` (contested or insufficient evidence). Exit code 61 = `E_PROTOCOL_CONSENSUS` (matrix shape is invalid).
@@ -165,7 +168,7 @@ This skill typically hands off to ct-adr-recorder on a `PROVEN` verdict so the d
 5. Critical-severity conflicts always escalate, regardless of top-option confidence.
 6. Manifest entry MUST set `agent_type: "analysis"` and include the verdict.
 7. On PROVEN, hand off to ct-adr-recorder; on CONTESTED or INSUFFICIENT_EVIDENCE, hand off to HITL.
-8. Always validate via `cleo check protocol --protocolType consensus`.
+8. Always validate via `cleo check protocol consensus`.
 
 ## See also / References
 

package/skills/ct-contribution/SKILL.md

@@ -6,11 +6,8 @@ description: >-
   "consensus workflow", "multi-agent decision", "create contribution",
   "contribution start", "contribution submit", "detect conflicts",
   "weighted consensus", "decision tracking", "conflict resolution".
-version: 1.0.0
-core: false
-category: meta
+version: 1.0.2
 protocol: contribution
-loomStage: contribution
 adrRefs:
   - ADR-015
   - ADR-053
@@ -24,9 +21,14 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 1.0.0
+  version: 1.0.2
   tier: on-demand
   install: harness
+  covers:
+    - packages/core/src/validation/protocols/cant/contribution.cant
+    - packages/core/src/validation/protocols/protocols-markdown/contribution.md
+  loomStage: contribution
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 

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

@@ -1,9 +1,7 @@
 ---
 name: ct-dev-workflow
 description: Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.
-version: 3.1.0
-core: false
-category: specialist
+version: 3.1.3
 protocol: contribution
 dependencies: []
 sharedResources:
@@ -16,10 +14,12 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.1.0
+  version: 3.1.3
   tier: core
   install: harness
-  lastReviewed: 2026-09-18
+  covers:
+    - .github/workflows/release-prepare.yml
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -338,8 +338,8 @@ cleo session end --note "Completed X, Y, Z"
 
 ### Output Requirements
 
-1. MUST write workflow summary to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
-2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+1. MUST record workflow summary with `cleo docs add {{TASK_ID}} --content - --type note --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: "Workflow complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return full commit/release details in response
 

package/skills/ct-documentor/SKILL.md

@@ -1,14 +1,9 @@
 ---
 name: ct-documentor
-description: Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. 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.
-version: 3.16.1
-core: false
-category: specialist
+description: Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Carries the CLEO writing and review guides as references and coordinates ct-spec-writer and ct-adr-recorder. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.
+version: 3.17.3
 protocol: null
 dependencies:
-  - ct-docs-lookup
-  - ct-docs-write
-  - ct-docs-review
   - ct-spec-writer
   - ct-adr-recorder
 sharedResources:
@@ -21,10 +16,13 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.16.1
+  version: 3.17.3
   tier: core
   install: harness
-  lastReviewed: 2026-09-27
+  covers:
+    - packages/cleo/src/cli/commands/docs.ts
+    - packages/contracts/src/docs-taxonomy.ts
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -92,9 +90,9 @@ Context injection for documentation tasks spawned via cleo-subagent. Orchestrate
 
 | Skill | Purpose | Invoke When |
 |-------|---------|-------------|
-| `ct-docs-lookup` | Query existing docs, find references via `cleo docs fetch`/`list` | Discovery phase, checking what exists |
-| `ct-docs-write` | Create/edit docs via `cleo docs add` with CLEO style | Writing or updating content |
-| `ct-docs-review` | Check compliance with style guide, read through `cleo docs fetch` | Quality validation before completion |
+| `cleo docs find` / `list` / `fetch` (and the Context7 MCP for library APIs) | Query existing docs and current external docs | Discovery phase, checking what exists |
+| `references/writing.md` (was ct-docs-write) | Create/edit docs via `cleo docs add` with CLEO style | Writing or updating content |
+| `references/reviewing.md` (was ct-docs-review) | Check compliance with style guide, read through `cleo docs fetch`; PR mode | Quality validation before completion |
 | `ct-spec-writer` | Author specs (REQ-XXX requirements) via `cleo docs add --type spec` | Formal specification work |
 | `ct-adr-recorder` | Author ADRs via `cleo docs add --type adr --slug adr-NNN-...` | Architecture decisions promoted from consensus |
 
@@ -115,8 +113,8 @@ and every owner writes through `cleo docs add` — not raw filesystem writes.
 | `adr` (architecture decisions) | `ct-adr-recorder` | `cleo docs add <ownerId> <path> --type adr --slug adr-<NNN>-<rest>` (TODO T10360 · E3.2 pending: `--title` + auto-`adr-NNN` allocation) |
 | `research` (multi-source investigation) | `ct-research-agent` | `cleo docs add <ownerId> <path> --type research --slug research-<topic>` |
 | `handoff` (session/agent transition) | `ct-documentor` (this skill) | `cleo docs add <ownerId> <path> --type handoff --slug handoff-<context>` |
-| `note` (conversational prose) | `ct-docs-write` | `cleo docs add <ownerId> <path> --type note --slug <kebab-topic>` |
-| `llm-readme` (agent-facing) | `ct-docs-write` | `cleo docs add <ownerId> <path> --type llm-readme --slug <kebab-topic>` |
+| `note` (conversational prose) | `ct-documentor` (`references/writing.md`) | `cleo docs add <ownerId> <path> --type note --slug <kebab-topic>` |
+| `llm-readme` (agent-facing) | `ct-documentor` (`references/writing.md`) | `cleo docs add <ownerId> <path> --type llm-readme --slug <kebab-topic>` |
 
 Hard rule: EVERY canonical-type write goes through the SSoT. The coordinator
 rejects any subagent return that wrote raw markdown into `.cleo/adrs/`,
@@ -159,6 +157,7 @@ Before adding a new doc, ALWAYS ask: is this **a new doc**, **a change to an exi
 ### Examples
 
 - **"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.
+- **"Accept a spec that review signed off"** - `cleo docs update <slug> --status accepted` (T12654). `--status` alone changes only the lifecycle status (draft, proposed, accepted, superseded, archived, deprecated); the stored bytes are kept, so there is no need to re-supply `--file` or `--content`. Any content edit without `--status` resets the doc to `draft`.
 
 - **"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.
 
@@ -205,7 +204,7 @@ This closes the silent-absorption footgun where citty's underlying
 
 ```bash
 # Typo → E_UNKNOWN_FLAG with suggestion
-$ cleo docs add T123 file.md --titel "X"
+$ cleo docs add T123 file.md --titel "X"   # cleo-cmd: negative-example
 {
   "success": false,
   "error": {
@@ -577,9 +576,10 @@ not yet under test.
 
 **Anti-pattern**: do NOT write a `cleo memory observe` manually after a
 `cleo docs add` — the auto-emit already happened, and the duplicate
-observation pollutes the FTS index. Use `cleo memory backfill-docs` (AC4
-of T9976) only to repair attachments that pre-date the auto-emit feature
-or were written outside the SSoT.
+observation pollutes the FTS index. No CLI command back-fills that
+observation for attachments that pre-date the auto-emit feature: the
+`memory backfill-docs` verb planned in T9976 AC4 never shipped. Leave such
+attachments as they are rather than hand-writing a duplicate observation.
 
 #### System-managed exemptions (T10368)
 
@@ -696,7 +696,7 @@ the docs graph — never grep the filesystem for the file you just wrote.
 cleo docs list --type spec --project       # canonical: every spec in this project
 cleo docs list --task T1234                # canonical: everything attached to a task
 cleo docs versions --for T1234             # ADVANCED: list every SHA version
-cleo docs sync --from docs/legacy.md --for T1234 --type note --slug legacy-doc  # ADVANCED: back-fill on-disk file into SSoT
+cleo docs sync --from docs/legacy.md --for T1234  # ADVANCED: back-fill on-disk file into SSoT (no --type/--slug; classify with docs add)
 ```
 
 ---
@@ -773,7 +773,7 @@ Grep: pattern="{TOPIC_KEYWORDS}" path="docs/"
 Grep: pattern="{RELATED_TERMS}" path="docs/" output_mode="files_with_matches"
 ```
 
-**Invoke `/ct-docs-lookup`** for deeper documentation research.
+**Use the Context7 MCP** (`resolve-library-id` → `query-docs`) for current library and framework docs.
 
 ### Phase 2: Assess
 
@@ -786,7 +786,7 @@ Grep: pattern="{RELATED_TERMS}" path="docs/" output_mode="files_with_matches"
 
 ### Phase 3: Write/Update
 
-**Invoke `/ct-docs-write`** for content creation.
+**Load `references/writing.md`** for content creation.
 
 **For EXISTING files:**
 1. Read the current content
@@ -811,7 +811,7 @@ Grep: pattern="{RELATED_TERMS}" path="docs/" output_mode="files_with_matches"
 
 ### Phase 4: Review
 
-**Invoke `/ct-docs-review`** for quality validation.
+**Load `references/reviewing.md`** for quality validation.
 
 Checklist:
 - [ ] No formal language ("utilize", "offerings", "cannot")
@@ -871,14 +871,14 @@ cleo research link {TASK_ID} {RESEARCH_ID}
 
 ### Output Requirements
 
-1. MUST write documentation output to: `{{OUTPUT_DIR}}/`
-2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+1. MUST record documentation output with `cleo docs add {{TASK_ID}} --content - --type <kind> --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: "Documentation complete. Manifest appended to pipeline_manifest."
 4. MUST NOT return documentation content in response
 
 ### Output File Format
 
-Write to `{{OUTPUT_DIR}}/`:
+Record it with `cleo docs add {{TASK_ID}} --content - --type <kind> --slug {{TOPIC_SLUG}}`, using this body:
 
 ```markdown
 # Documentation Update: {TITLE}
@@ -907,12 +907,12 @@ Write to `{{OUTPUT_DIR}}/`:
 - [ ] Changes don't duplicate existing content
 - [ ] Cross-references updated
 - [ ] Examples tested
-- [ ] Style guide compliance verified via ct-docs-review
+- [ ] Style guide compliance verified via `references/reviewing.md`
 ```
 
 ### Manifest Entry
 
-Append ONE line to `{{MANIFEST_PATH}}`:
+Record it with `cleo manifest append --entry '<entry JSON>'` (the flat manifest file is retired, ADR-027):
 
 ```json
 {"id":"docs-{TOPIC}-{DATE}","file":"{DATE}_docs-{TOPIC}.md","title":"Documentation Update: {TITLE}","date":"{DATE}","status":"complete","agent_type":"documentation","topics":["documentation","{topic}"],"key_findings":["Updated {file} with {change}","Consolidated {topic} docs into {canonical-location}","Avoided duplication by updating existing {file}"],"actionable":false,"needs_followup":[],"linked_tasks":["{TASK_ID}"]}
@@ -926,10 +926,10 @@ Append ONE line to `{{MANIFEST_PATH}}`:
 - [ ] Core principle followed (maintain, don't duplicate)
 - [ ] Coordinator pattern followed: every doc-type routed to its owning skill
 - [ ] Every canonical-type write went through `cleo docs add --type X --slug Y`
-- [ ] `/ct-docs-write` invoked for `note`/`llm-readme` content
+- [ ] `references/writing.md` followed for `note`/`llm-readme` content
 - [ ] `/ct-spec-writer` invoked when writing specs (REQ-XXX requirements)
 - [ ] `/ct-adr-recorder` invoked when promoting consensus → ADR
-- [ ] `/ct-docs-review` invoked for quality validation
+- [ ] `references/reviewing.md` applied for quality validation
 - [ ] Anti-duplication checklist verified
 - [ ] Output file written with "Files NOT Created" section
 - [ ] Manifest entry appended

package/skills/{ct-docs-review/__tests__/skill-docs-review.test.ts → ct-documentor/__tests__/reviewing-reference.test.ts}

@@ -1,5 +1,5 @@
 /**
- * Regression test for ct-docs-review/SKILL.md (T9642 / Epic T9629 / Saga T9625).
+ * Regression test for the ct-docs-review content, now ct-documentor/references/reviewing.md (T9642 / Epic T9629 / Saga T9625).
  *
  * Pins the SDK-first review contract: reviewers MUST read docs through
  * `cleo docs fetch <slug>` rather than the working-tree file. Documents
@@ -19,10 +19,11 @@ import { describe, expect, it } from 'vitest';
 
 const thisFile = fileURLToPath(import.meta.url);
 const skillRoot = resolve(dirname(thisFile), '..');
-const skillPath = join(skillRoot, 'SKILL.md');
+// T12649: ct-docs-review merged into ct-documentor/references/reviewing.md (D11157).
+const skillPath = join(skillRoot, 'references', 'reviewing.md');
 const skillContent = readFileSync(skillPath, 'utf-8');
 
-describe('ct-docs-review SKILL.md — SDK-first contract (T9642)', () => {
+describe('ct-documentor references/reviewing.md (was ct-docs-review) — SDK-first contract (T9642)', () => {
   it('teaches `cleo docs fetch` as the canonical read path', () => {
     expect(skillContent).toContain('cleo docs fetch');
   });

package/skills/{ct-docs-write/__tests__/skill-docs-write.test.ts → ct-documentor/__tests__/writing-reference.test.ts}

@@ -1,5 +1,5 @@
 /**
- * Regression test for ct-docs-write/SKILL.md (T9641 / Epic T9629 / Saga T9625).
+ * Regression test for the ct-docs-write content, now ct-documentor/references/writing.md (T9641 / Epic T9629 / Saga T9625).
  *
  * Pins the SDK-first writing contract: every new doc MUST flow through
  * `cleo docs add --type X --slug Y` rather than direct filesystem writes.
@@ -18,10 +18,11 @@ import { describe, expect, it } from 'vitest';
 
 const thisFile = fileURLToPath(import.meta.url);
 const skillRoot = resolve(dirname(thisFile), '..');
-const skillPath = join(skillRoot, 'SKILL.md');
+// T12649: ct-docs-write merged into ct-documentor/references/writing.md (D11157).
+const skillPath = join(skillRoot, 'references', 'writing.md');
 const skillContent = readFileSync(skillPath, 'utf-8');
 
-describe('ct-docs-write SKILL.md — SDK-first contract (T9641)', () => {
+describe('ct-documentor references/writing.md (was ct-docs-write) — SDK-first contract (T9641)', () => {
   it('teaches `cleo docs add` as the canonical write path', () => {
     expect(skillContent).toContain('cleo docs add');
   });

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

@@ -42,12 +42,12 @@ existing page; do not create a sibling.
 **Symptom.** A how-to or reference cites a library API that has been
 renamed, deprecated, or removed.
 
-**Detection cue.** `ct-docs-lookup` was NOT invoked for the topic.
+**Detection cue.** the Context7 MCP was NOT invoked for the topic.
 
 **Root cause.** Documentor coordinator skipped lookup because "I know
 the API" or assumed training data was current.
 
-**Fix.** Always invoke `ct-docs-lookup` when documenting external
+**Fix.** Always invoke the Context7 MCP when documenting external
 library behavior. Training data is stale by definition — Context7 is
 the current source.
 
@@ -118,7 +118,7 @@ was assembled from multiple sources without normalization.
 
 **Fix.** CLEO style is "you" (second person) for how-tos and tutorials;
 "CLEO" (third person) for explanations and references. Apply
-consistently. Pass the choice explicitly to ct-docs-write as input.
+consistently. Pass the choice explicitly to the writing guide (`ct-documentor/references/writing.md`) as input.
 
 ## 8. The Forbidden Word Sneak-In
 
@@ -154,7 +154,7 @@ step bodies.
 
 **Fix.** Tutorials and how-tos use imperative voice — "Run the
 command", "Open the file", "Set the value". Pass that constraint
-explicitly to ct-docs-write.
+explicitly to the writing guide (`ct-documentor/references/writing.md`).
 
 ## 10. The Lost Manifest
 
@@ -172,10 +172,10 @@ of the children appended in a wrong format).
 children — owns the entry. Run:
 
 ```bash
-cleo manifest append <(cat <<EOF
+cleo manifest append --entry "$(cat <<'JSON'
 {"id":"docs-<topic>-<date>", "file":"<path>", "title":"...", ...}
-EOF
-)
+JSON
+)"
 ```
 
 After append, verify with:
@@ -211,6 +211,6 @@ violations the local review didn't catch.
 **Root cause.** Documentor ran review on the draft, but not on the
 PR diff. Integration introduced drift (rebase fixups, merge prose).
 
-**Fix.** Always run `ct-docs-review --mode=pr` on the PR's diff
+**Fix.** Always run `references/reviewing.md` in PR mode on the PR's diff
 before requesting merge. Catches drift that slipped through during
 integration.

package/skills/{ct-docs-write → ct-documentor}/references/audience-targeting.md

@@ -28,8 +28,8 @@ exploring.
 Conversational, practical, second-person.
 
 ```markdown
-You can run the release pipeline manually with `cleo release ship`.
-Just kidding — never use "just". Run it with `cleo release ship`,
+You can run the release pipeline manually with `cleo release plan`.
+Just kidding — never use "just". Run it with `cleo release plan`,
 and CLEO walks through the gates one by one.
 ```
 
@@ -40,7 +40,7 @@ Do not explain why unless the why directly affects behavior.
 
 ```markdown
 GOOD (end-user):
-Run `cleo release ship 2026.5.82 --epic T9567`.
+Run `cleo release plan v2026.5.82 --epic T9567`.
 
 You see:
 - The 12 release steps run in order.
@@ -51,7 +51,7 @@ If a step fails, CLEO stops and prints the failing gate. Fix the issue
 and re-run.
 
 BAD (end-user, too deep):
-The `cleo release ship` command dispatches through `dispatch.ts`,
+The `cleo release plan` command dispatches through `dispatch.ts`,
 loading the `release` handler from the registry built at module
 init. The handler then constructs a release plan using the 12-stage
 state machine defined in `packages/cleo/src/commands/release/...`
@@ -198,7 +198,7 @@ The most common style failure is mixing audiences within a single doc.
 
 ```markdown
 BAD:
-Run `cleo release ship`.
+Run `cleo release plan`.
 
 (Internally, this dispatches through `dispatch.ts` to the release
 handler registered via the registry pattern...)