@cleocode/skills 2026.5.84 → 2026.5.87

package/skills/ct-docs-write/SKILL.md

@@ -105,4 +105,160 @@ Not: "(remember to run X before Y...)" buried in a paragraph.
 | take a look at             | reference          |
 | can't, don't               | cannot, do not     |
 | **Filter** button          | \`Filter\` button  |
-| Check out [the docs](link) | Click [here](link) |
+| Check out [the docs](link) | Click [here](link) |
+
+## The Three Pillars (Why)
+
+CLEO documentation has three principles. Every rule supports one of them.
+
+1. **Conversational.** Read aloud — does it sound like you talking? CLEO docs
+   use contractions (don't, can't) where many style guides ban them. The
+   contractions are deliberate; they make the writing feel like a colleague
+   talking, not a corporate press release.
+
+2. **Clear.** Lead with what to do; explain after. Headings state the point,
+   not just the topic. "Configure release pipeline before first ship" beats
+   "Configuration" every time.
+
+3. **User-focused.** Say "people" and "companies" — not "users". The user
+   construct is for systems; people are the readers. This change is jarring
+   the first time, then becomes second nature.
+
+## Forbidden Phrases (Most Common Failures)
+
+These ship to PR, get caught in review, and create rework. Avoid them up
+front.
+
+- "easy" / "simple" / "just" — patronizing; you don't know the reader's context
+- "obviously" / "of course" — same problem
+- "click here" / "read more here" — link text must describe the destination
+- "etc." / "and so on" — be specific, or cut the sentence
+- "we" referring to CLEO — say "CLEO" or "it"
+
+## Audience-Matching
+
+Match complexity to audience. Mismatch is the biggest style failure.
+
+| Audience | Tone | Code examples | Depth |
+|----------|------|---------------|-------|
+| End-user | Conversational, second-person | Realistic, copy-paste | Low |
+| Agent (LLM) | Dense, structured | Schemas, JSON | Medium |
+| Maintainer | Technical, third-person | Code with internals | High |
+
+Declare the audience in frontmatter — `audience: end-user | agent | maintainer`
+— so reviewers can apply the right rubric.
+
+## Through SDK (preferred)
+
+CLEO docs are first-class records in the docs SSoT — not loose markdown files.
+Always write through `cleo docs add` so the doc gets a slug, a type, an owner,
+and a content-addressed blob that downstream consumers can fetch by slug.
+
+### Write a draft attached to a task
+
+```bash
+cleo docs add T1234 docs/drafts/saml-setup.md \
+  --type note \
+  --slug saml-setup-draft \
+  --desc "Conversational SAML setup walkthrough — pre-review"
+```
+
+- `--type` MUST be one of `spec | adr | research | handoff | note | llm-readme`.
+  For user-facing prose use `note`; for end-user docs use `note` or `spec`
+  depending on whether the doc carries REQ-XXX requirements.
+- `--slug` is the human-friendly handle for retrieval. Use kebab-case. If the
+  slug is already taken the CLI returns `E_SLUG_TAKEN` with 3 alternatives —
+  pick one rather than overwriting silently.
+- The owner ID (`T1234` above) auto-classifies the attachment by prefix:
+  `T###` → task, `ses_*` → session, `O-*` → observation.
+
+### Publish to a git-tracked path (when the doc must live on disk)
+
+```bash
+cleo docs publish --for T1234 --to docs/saml-setup.md
+```
+
+Atomic tmp-then-rename. The published file ships in the next commit; the
+SSoT blob remains canonical and continues to track future versions.
+
+### Fetch the doc back by slug
+
+```bash
+cleo docs fetch saml-setup-draft       # latest version
+cleo docs versions --for T1234         # list every SHA version
+```
+
+Slug-based fetch is the contract used by reviewers, downstream skills, and
+the docs graph — never grep the filesystem for the file you just wrote.
+
+### List docs by type
+
+```bash
+cleo docs list --type note --project   # every note in this project
+cleo docs list --task T1234            # everything attached to a task
+```
+
+## Deprecated: Direct filesystem
+
+The legacy "write straight to `docs/` and commit" pattern is deprecated.
+The drift between the working file and the docs SSoT is real: published
+files go stale, types are inferred ad-hoc from path, and slug-based
+retrieval becomes impossible. Migrate to `cleo docs add --type X --slug Y`
+for every new doc — and use `cleo docs sync --from <path> --for <ownerId>`
+to back-fill existing on-disk files into the SSoT.
+
+## Output Location
+
+Documentation blobs live in the docs SSoT; published copies on disk go in
+`docs/` for end-user and maintainer content. Agent-facing protocol docs
+(skill references, agent-outputs) go in
+`packages/skills/skills/<name>/references/` or `.cleo/agent-outputs/`.
+Never mix audiences in one location.
+
+## When to Update Instead of Create
+
+The MAINTAIN, DON'T DUPLICATE rule from ct-documentor applies here too.
+Before creating any new file:
+
+1. Run `Glob: docs/**/*.md` and `Grep: <topic-keywords> path=docs/` to find
+   prior coverage.
+2. If a prior page exists, UPDATE that page. Add a section if needed.
+3. If multiple prior pages cover the topic in fragments, propose a
+   consolidation to the documentor coordinator before writing.
+4. Only create a new file when no existing location fits.
+
+The cost of duplicate documentation is paid by every future reader —
+they find one page or the other depending on search keywords, and the
+two versions inevitably drift.
+
+## Final-Pass Checklist
+
+Before declaring the draft done:
+
+- [ ] All code blocks have explicit language tags (`bash`, `typescript`, not `ts`).
+- [ ] All links have descriptive text (no "here", "this").
+- [ ] All headings state the point in sentence case.
+- [ ] All "users" replaced with "people" or "companies".
+- [ ] Contractions present (don't, can't, won't).
+- [ ] No "easy", "simple", "just", "obviously" anywhere (including code comments).
+- [ ] Frontmatter title and H1 match.
+- [ ] Audience declared in frontmatter.
+- [ ] Final newline at end of file.
+
+Run grep for the forbidden phrases before completing:
+
+```bash
+for word in easy simple just obviously "click here" "read more"; do
+  grep -in "$word" <new-file>
+done
+```
+
+---
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/cleo-style-guide.md` — the three pillars, forbidden phrases, format conventions, hidden drift
+- `references/markdown-patterns.md` — code-block / table / list / link / callout patterns with positive/negative examples
+- `references/audience-targeting.md` — end-user / agent / maintainer profiles, mixed-audience pitfalls, re-targeting

package/skills/ct-docs-write/__tests__/skill-docs-write.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Regression test for ct-docs-write/SKILL.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.
+ * If a future edit drops the SDK section, this test breaks the build so
+ * the writing protocol can't silently regress to the deprecated pattern.
+ *
+ * @task T9641
+ * @epic T9629
+ * @saga T9625
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const thisFile = fileURLToPath(import.meta.url);
+const skillRoot = resolve(dirname(thisFile), '..');
+const skillPath = join(skillRoot, 'SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+
+describe('ct-docs-write SKILL.md — SDK-first contract (T9641)', () => {
+  it('teaches `cleo docs add` as the canonical write path', () => {
+    expect(skillContent).toContain('cleo docs add');
+  });
+
+  it('mentions the closed-set --type taxonomy', () => {
+    expect(skillContent).toMatch(/spec\s*\|\s*adr\s*\|\s*research\s*\|\s*handoff\s*\|\s*note\s*\|\s*llm-readme/);
+  });
+
+  it('shows --slug as the human-friendly retrieval handle', () => {
+    expect(skillContent).toContain('--slug');
+    expect(skillContent).toContain('kebab-case');
+  });
+
+  it('shows `cleo docs publish --for ... --to ...` for git-tracked publication', () => {
+    expect(skillContent).toMatch(/cleo docs publish\s+--for[\s\S]+--to/);
+  });
+
+  it('shows `cleo docs fetch` for slug-based retrieval', () => {
+    expect(skillContent).toContain('cleo docs fetch');
+  });
+
+  it('marks the old direct-filesystem path as deprecated with a migration note', () => {
+    expect(skillContent).toContain('Deprecated: Direct filesystem');
+    // Migration must point at the SDK
+    expect(skillContent).toMatch(/cleo docs (add|sync)/);
+  });
+
+  it('references E_SLUG_TAKEN so callers know how to handle collisions', () => {
+    expect(skillContent).toContain('E_SLUG_TAKEN');
+  });
+});

package/skills/ct-docs-write/references/audience-targeting.md

@@ -0,0 +1,305 @@
+# Audience Targeting
+
+CLEO docs serve three audiences with very different needs. Writing
+without identifying the audience produces docs that satisfy none.
+This reference defines each audience's profile and how to tune the
+draft to fit.
+
+## Three Audiences
+
+| Audience | Profile | Reading goal |
+|----------|---------|--------------|
+| End-user | Uses CLEO to ship their own software | "Help me do this thing now" |
+| Agent | LLM consuming the doc as context | "Give me the structure I need" |
+| Maintainer | Contributes to CLEO itself | "Show me how this works internally" |
+
+Identifying the audience is the first step in any documentation task.
+The downstream choices — tone, depth, examples, structure — all flow
+from this single decision.
+
+## End-User Audience
+
+The end-user has installed CLEO and wants to use it. They are a
+developer or a tech-comfortable team lead. They are working — not
+exploring.
+
+### Tone
+
+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`,
+and CLEO walks through the gates one by one.
+```
+
+### Depth
+
+Show the action; show the outcome; show the recovery if it fails.
+Do not explain why unless the why directly affects behavior.
+
+```markdown
+GOOD (end-user):
+Run `cleo release ship 2026.5.82 --epic T9567`.
+
+You see:
+- The 12 release steps run in order.
+- CI status streams in real-time.
+- On success, the tag is pushed and the PR merges.
+
+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`,
+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/...`
+```
+
+### Examples
+
+Realistic. Copy-paste-able. With expected output.
+
+```markdown
+GOOD:
+```bash
+$ cleo show T9567
+T9567 — E-SKILLS-DEPTH-BACKFILL
+Status: pending
+Acceptance:
+  1. Each of 6+ stub skills gains references/ with min 3 docs each
+  ...
+```
+```
+
+### Structure
+
+How-to or tutorial template. The reader scans for steps; give them
+steps.
+
+## Agent Audience
+
+The agent is an LLM — Claude, GPT, a CLEO subagent. It consumes the
+doc as context for completing a task. Its needs are very different
+from the human's.
+
+### Tone
+
+Dense, structured, declarative. Bullet points and tables over prose.
+
+```markdown
+GOOD (agent):
+Worker contract:
+1. cd to worktree path (provided in spawn prompt)
+2. read task with `cleo show <ID>`
+3. implement; commit on task branch
+4. verify each gate with `cleo verify --gate X --evidence Y`
+5. complete with `cleo complete <ID>`
+6. observe learning with `cleo memory observe`
+
+BAD (agent, too narrative):
+When the worker starts up, it first navigates to the worktree the
+orchestrator created. This is important because all subsequent
+operations need to happen inside the worktree's boundary. After
+arrival, the worker reads the task it was assigned...
+```
+
+### Depth
+
+Maximum useful. The agent can absorb dense reference material; it
+prefers structured data to prose framing.
+
+### Examples
+
+Schemas, JSON, command sequences. Show the data shape directly.
+
+```markdown
+Manifest entry shape:
+
+```json
+{
+  "id": "<topic>-<date>",
+  "file": "<filename>",
+  "title": "<title>",
+  "status": "complete" | "partial" | "blocked",
+  "agent_type": "research" | "spec" | "implementation" | ...,
+  "topics": ["<tag>", "<tag>"],
+  "key_findings": ["<sentence>", ...],
+  "actionable": true | false,
+  "needs_followup": ["<task-id>", ...],
+  "linked_tasks": ["<epic-id>", "<task-id>"]
+}
+```
+```
+
+### Structure
+
+Reference template. Tables. Bullet lists. The agent doesn't need
+warm-up prose.
+
+## Maintainer Audience
+
+The maintainer is a CLEO contributor — they have read the codebase
+and want to understand or modify the internals. They are exploring
+or making architectural decisions.
+
+### Tone
+
+Technical, precise, third-person.
+
+```markdown
+GOOD (maintainer):
+The release pipeline is implemented as a 12-stage state machine in
+`packages/cleo/src/commands/release/`. Stages are pure functions
+that take a `ReleaseContext` and return either `{ ok: true, ctx }`
+or `{ ok: false, error }`. The dispatcher in `pipeline.ts` runs
+stages in declared order, short-circuiting on failure.
+
+BAD (maintainer, too casual):
+Releases work through this cool 12-step thing. Each step is a
+function that either works or doesn't. If a step fails, we stop.
+```
+
+### Depth
+
+Maximum. Internal symbols, file paths, design decisions. The reader
+is expected to follow links into the codebase.
+
+### Examples
+
+Code excerpts with the actual implementation. Reference to ADRs
+and prior discussions.
+
+```markdown
+The dispatcher signature is:
+
+```typescript
+// packages/cleo/src/commands/release/pipeline.ts
+export async function runPipeline(
+  stages: Stage[],
+  ctx: ReleaseContext
+): Promise<Result<ReleaseContext, ReleaseError>>;
+```
+
+See ADR-065 for the gate-ordering rationale.
+```
+
+### Structure
+
+Explanation template often. Mermaid diagrams for flows. Cross-references
+to ADRs.
+
+## Mixed-Audience Pitfalls
+
+The most common style failure is mixing audiences within a single doc.
+
+### Pitfall: End-user doc with maintainer aside
+
+```markdown
+BAD:
+Run `cleo release ship`.
+
+(Internally, this dispatches through `dispatch.ts` to the release
+handler registered via the registry pattern...)
+
+Then check that the PR opens.
+```
+
+The aside is for maintainers, not end-users. End-users don't care
+about `dispatch.ts`. Either:
+- Cut the aside.
+- Move it to a separate maintainer doc.
+- Link to it as "for more details, see [release pipeline internals]".
+
+### Pitfall: Maintainer doc with consumer hand-holding
+
+```markdown
+BAD:
+The release pipeline runs gates in order — that means each step
+happens one after another, like steps on a staircase. (You go up
+one step at a time, right?)
+```
+
+Maintainer-audience readers know what "in order" means. Patronizing
+them wastes their time.
+
+### Pitfall: Agent doc with narrative warm-up
+
+```markdown
+BAD (agent doc):
+Welcome to the worker protocol! In this guide, we'll walk through
+the steps you'll follow as a worker. We're excited to have you on
+board. Let's get started!
+
+(Then 200 lines of actual protocol.)
+```
+
+Agent readers want the protocol immediately. The warm-up is pure
+token waste.
+
+## Tagging Audience in Frontmatter
+
+Every CLEO doc SHOULD declare its audience in frontmatter:
+
+```markdown
+---
+title: How to ship a release
+audience: end-user
+type: how-to
+---
+```
+
+The audience tag lets reviewers, future maintainers, and automated
+style checks apply the right rubric. Without it, the reader has to
+infer from tone — and inference is error-prone.
+
+## Audience-Specific Conventions
+
+| Element | End-user | Agent | Maintainer |
+|---------|----------|-------|------------|
+| Pronoun | "you" | (none — declarative) | "the X", "we" rarely |
+| Verb mood | Imperative | Declarative | Descriptive |
+| Code examples | Realistic, with output | Schemas, JSON | Code excerpts with paths |
+| Internal refs | Avoid | None | Heavy |
+| ADR refs | Rarely | Rarely | Heavy |
+| Diagrams | Sometimes | Rarely | Often (Mermaid) |
+| Warm-up | One sentence | None | Context paragraph |
+
+## Re-Targeting
+
+When a doc is mis-audienced, the fix is usually structural — not
+tonal. Re-target by:
+
+1. Re-classify the audience in frontmatter.
+2. Restructure to the new audience's template.
+3. Strip content that doesn't fit (maintainer details from end-user
+   doc; warm-up from agent doc).
+4. Add content that does fit (verification steps for end-user;
+   internal links for maintainer).
+
+Re-targeting a long doc is sometimes more expensive than splitting it.
+A doc that genuinely serves two audiences should be two docs with
+cross-links — not one doc trying to do both.
+
+## Cross-Audience References
+
+When a doc primarily serves audience A but the reader from audience B
+might land on it (via search, link, etc.), add a footer pointer:
+
+```markdown
+> Are you contributing to CLEO? See the [maintainer's deep dive
+> on release internals](../internals/release-pipeline.md) instead.
+```
+
+The pointer respects B's time without polluting A's reading flow.
+
+## Self-Check
+
+Before declaring a draft done:
+
+- [ ] Frontmatter declares the audience.
+- [ ] Tone matches the audience profile.
+- [ ] Depth matches what the audience needs.
+- [ ] No content from a different audience snuck in.
+- [ ] Cross-references to other-audience docs added if relevant.