@cleocode/skills 2026.5.84 → 2026.5.87

package/skills/ct-docs-write/references/cleo-style-guide.md

@@ -0,0 +1,234 @@
+# CLEO Style Guide
+
+The canonical style guide lives at
+`packages/skills/skills/_shared/cleo-style-guide.md` and is consumed
+by both ct-docs-write and ct-docs-review. This reference makes the
+guide's most-violated rules concrete with positive/negative examples
+and the rationale for each.
+
+## The Three Pillars
+
+CLEO documentation is **conversational, clear, and user-focused**.
+Every other rule supports one of these three. When in doubt, ask:
+"would I say this to a colleague in a chat?"
+
+### Pillar 1: Conversational
+
+Write the way you talk to a colleague — not the way a corporate press
+release would. The contraction rule is the most distinctive marker.
+
+CLEO USES contractions. Many style guides ban them; CLEO does the
+opposite. "Don't" reads more like a colleague than "do not".
+
+| Avoid | Prefer | Why |
+|-------|--------|-----|
+| utilize | use | "utilize" is just "use" wearing a suit |
+| reference (verb) | see, look at | "reference" makes things sound bureaucratic |
+| offerings | products, features | "offerings" sounds like a press release |
+| we will use HTTPS | use HTTPS | imperative > first-person future |
+| cannot, do not | can't, don't | contractions read more conversationally |
+| it is recommended that | use | passive recommendation = no recommendation |
+
+### Pillar 2: Clear
+
+Lead with what to do. Explain after. Bury nothing.
+
+Headings state the point. Vague headings make the reader scan the body
+to learn whether to read it.
+
+| Vague heading | Clear heading |
+|---------------|---------------|
+| Configuration | Configure release pipeline before first ship |
+| Authentication | Authenticate with API tokens |
+| Performance | Set timeout to 30s on slow networks |
+| Common issues | Solve E_VALIDATION errors |
+| Setup | Install dependencies and run init |
+| Notes | Use environment variables for secrets |
+
+The pattern: action verb + object + (qualifier). Vague nouns alone
+fail the test.
+
+### Pillar 3: User-Focused
+
+CLEO docs say "people" and "companies", not "users". This is jarring
+the first time you switch; once you do, the writing reads more
+concrete.
+
+| Avoid | Prefer |
+|-------|--------|
+| users can | people can |
+| our users | our customers, or "the companies using CLEO" |
+| user input | what people type |
+| user experience | what people see |
+| end-user | (the same — only when "user" is part of a compound) |
+
+The exception: when "user" is part of a compound technical term
+("end-user", "user-agent", "user-space"), it stays. Only the standalone
+"user" gets replaced.
+
+## Forbidden Phrases
+
+These never appear in CLEO docs. The review skill rejects them on sight.
+
+### "easy" / "simple" / "just"
+
+These words assume you know the reader's context — and you don't. What
+is easy for you may be intimidating for them. Removing these words
+costs nothing and makes the doc respectful.
+
+| Bad | Good |
+|-----|------|
+| Setting up SAML is easy. Just follow these steps. | Set up SAML with these steps. |
+| It's simple to configure the cache. | Configure the cache by setting `cacheTimeout`. |
+| You can just import the helper. | Import the helper from `@cleocode/contracts`. |
+
+### "obviously" / "of course"
+
+Same problem as "easy" — they patronize the reader. If something is
+obvious, it doesn't need to be said. If it's not, calling it obvious
+makes the reader feel stupid.
+
+### "click here" / "read more here"
+
+Link text must describe the destination. The naked words "here" or
+"this" tell the reader nothing about where the link goes.
+
+| Bad | Good |
+|-----|------|
+| Click [here](url) to learn about SAML. | See the [SAML configuration guide](url). |
+| For more info, [read this](url). | Read the [release pipeline ADR](url). |
+| You can [download it here](url). | Download [the CLEO CLI binary](url). |
+
+### "etc." / "and so on"
+
+Be specific or cut the sentence. Trailing-off phrases signal you
+didn't finish thinking.
+
+| Bad | Good |
+|-----|------|
+| Use environment variables, config files, etc. | Use environment variables or config files. |
+| You can run tests, lint, format, and so on. | Run lint, format, build, then tests. |
+
+### "we" (when referring to CLEO)
+
+When talking about CLEO features, say "CLEO" or "it" — not "we".
+"We" is for the human team, not the system.
+
+| Bad | Good |
+|-----|------|
+| We use a per-skill token budget. | CLEO uses a per-skill token budget. |
+| We will deprecate this in 2026-Q3. | This feature is deprecated as of 2026-Q3. |
+| Our orchestrator manages... | The orchestrator manages... |
+
+## Code Block Discipline
+
+Code blocks always have a language tag.
+
+````markdown
+GOOD:
+```bash
+pnpm run test
+```
+
+GOOD:
+```typescript
+import { foo } from "@cleocode/contracts";
+```
+
+BAD (no tag):
+```
+pnpm run test
+```
+
+BAD (abbreviated tag):
+```ts
+import { foo } from "@cleocode/contracts";
+```
+````
+
+Use full names: `bash`, `typescript`, `tsx`, `python`, `rust`, `json`,
+`yaml`, `markdown`. Avoid `js`, `ts`, `py`, `rs`.
+
+When the command depends on a working directory or other context, say
+so in a comment within the block:
+
+````markdown
+```bash
+# In the project root
+pnpm run test
+```
+
+```typescript
+// packages/cleo/src/foo.ts
+import { bar } from "@cleocode/contracts";
+```
+````
+
+## Format Conventions
+
+| Element | Convention |
+|---------|-----------|
+| **Bold** | UI element names: "Click the **Submit** button" |
+| `Code` | Code symbols, variables, commands, filenames |
+| _Italic_ | New terms (on first mention) only |
+| `[link text](url)` | Descriptive link text always |
+| Numbered list | When order matters |
+| Bulleted list | When items are peers |
+| Table | When items have parallel structure |
+| Heading | State the point, not the topic |
+
+### Spelling and Punctuation
+
+- **American spelling.** "color" not "colour", "behavior" not "behaviour".
+- **Serial commas.** "a, b, and c" with the comma before "and".
+- **One space after periods.** Not two.
+- **Em dashes.** Use `—` (em dash) for parenthetical breaks. Not `--` or
+  ` - ` with surrounding spaces.
+- **Quote marks.** Straight (`"`) in code; curly (`"`) in prose (your
+  editor handles this).
+
+## Audience-Matching
+
+Match complexity to audience. The biggest stylistic failure is mismatch.
+
+| Audience | Tone | Code examples | Conceptual depth |
+|----------|------|---------------|------------------|
+| End-user (using CLEO) | Conversational, practical | Realistic, copy-paste | Low — they want to ship |
+| Agent (LLM consuming docs) | Dense, structured | Schemas, JSON | Medium — context-economical |
+| Maintainer (contributing) | Technical, precise | Code with internals | High — internal architecture |
+
+End-user docs say "Run `cleo show T123` to see the task." Maintainer
+docs say "The `cleo show` handler dispatches via `dispatch.ts:107`
+through the LAFS envelope wrapper at `packages/cleo/src/dispatch.ts`."
+
+## Headings: One Pattern
+
+Use sentence case (only the first word and proper nouns capitalized).
+
+| Bad | Good |
+|-----|------|
+| # How To Configure The Release Pipeline | # How to configure the release pipeline |
+| ## Common Issues With Authentication | ## Common issues with authentication |
+| ### Pre-Flight Checks | ### Pre-flight checks |
+
+Exception: ADRs use title case for their title because they are formal
+documents — but their internal headings use sentence case.
+
+## Hidden Drift
+
+These violations sneak through review most often:
+
+1. "easy"/"simple" inside code comments (review may skip code blocks)
+2. "users" in alt text on images
+3. Title case headings in newly-added sections of an otherwise
+   sentence-case doc
+4. Trailing "etc." inside a longer list
+5. "we" in the description field of frontmatter
+
+Run grep before declaring done:
+
+```bash
+for word in easy simple just obviously "click here" "read more"; do
+  grep -in "$word" <new-file>
+done
+```

package/skills/ct-docs-write/references/markdown-patterns.md

@@ -0,0 +1,329 @@
+# Markdown Patterns
+
+Concrete patterns for the code blocks, tables, lists, and other
+markdown constructs that appear most often in CLEO docs. The right
+pattern in the right place compresses information; the wrong pattern
+makes the doc feel cluttered.
+
+## Code Block Patterns
+
+### Pattern: Instructions in Sequence
+
+When the reader runs commands in order, separate each by prose that
+states the outcome — not interjections inside the block.
+
+````markdown
+GOOD:
+Run the migration:
+
+```bash
+pnpm run migrate
+```
+
+You should see "Migration complete" with no error output.
+
+Then start the dev server:
+
+```bash
+pnpm run dev
+```
+
+It boots on port 3000 by default.
+
+BAD (interjections buried in code):
+
+```bash
+# (Remember to run migration before this)
+pnpm run dev
+```
+
+BAD (multiple commands smashed together):
+
+```bash
+pnpm run migrate
+# then
+pnpm run dev
+```
+````
+
+The good pattern lets the reader pause between steps and confirm
+each one. The bad patterns force them to read the comments to learn
+the structure.
+
+### Pattern: Annotated Output
+
+When showing what command output looks like, use a separate code block
+with the language `text` (or no language):
+
+````markdown
+Run:
+
+```bash
+cleo show T9567
+```
+
+You see:
+
+```text
+T9567 — E-SKILLS-DEPTH-BACKFILL
+Status: pending
+Acceptance:
+  1. Each of 6+ stub skills gains references/ with min 3 docs each
+  ...
+```
+````
+
+Do NOT mix command and output in one block — it confuses syntax
+highlighters and makes copy-paste error-prone.
+
+### Pattern: TypeScript with Path Comment
+
+When showing TypeScript that lives at a specific path, lead with a
+path comment:
+
+````markdown
+```typescript
+// packages/cleo/src/commands/release-plan.ts
+import { defineCommand } from "citty";
+
+export const releasePlan = defineCommand({
+  meta: { name: "plan", description: "..." },
+  // ...
+});
+```
+````
+
+The path comment gives the reader the "where" before the "what".
+
+## Table Patterns
+
+### Pattern: Comparison Table
+
+Use when the reader is choosing between options.
+
+```markdown
+| Approach | Pros | Cons | Use when |
+|----------|------|------|----------|
+| A | fast, simple | limited | quick scripts |
+| B | flexible, typed | more setup | production code |
+| C | minimal | runtime cost | very small projects |
+```
+
+The "Use when" column is the punchline — readers scan the comparison
+table to find their use case.
+
+### Pattern: Reference Table
+
+Use when listing options, flags, or enum values.
+
+```markdown
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--verbose` | false | Print full execution trace |
+| `--epic <id>` | (required) | Epic to release |
+| `--no-tag` | false | Skip the tag step |
+```
+
+Default column makes the reader's reading order clear: read row,
+notice it has a sensible default, move on. Without the default
+column, the reader has to mentally guess what happens when they
+don't specify the flag.
+
+### Pattern: Status Table
+
+Use for state machines or status codes.
+
+```markdown
+| Status | Meaning | Next states |
+|--------|---------|-------------|
+| pending | Created, not yet started | active |
+| active | In progress | done, blocked |
+| blocked | Awaiting dependency | active, cancelled |
+| done | Complete | — |
+```
+
+The "Next states" column makes the state machine readable as a table.
+
+### Anti-pattern: Too Many Columns
+
+Tables wider than 5 columns become illegible on mobile and look like
+data dumps. If you have more dimensions, split into multiple tables.
+
+```markdown
+BAD:
+| Name | Status | Date | Owner | Priority | Estimate | Description | Notes |
+
+GOOD (split):
+| Name | Status | Date | Owner |
+|------|--------|------|-------|
+| ... | ... | ... | ... |
+
+For details and estimates, see the [task tracker]...
+```
+
+## List Patterns
+
+### Pattern: Numbered for Sequence
+
+Use when order matters and the reader will follow steps.
+
+```markdown
+1. Install the CLI: `pnpm i -g @cleocode/cleo`
+2. Initialize a project: `cleo init`
+3. Open the first task: `cleo next`
+```
+
+### Pattern: Bulleted for Peers
+
+Use when items are independent.
+
+```markdown
+The release pipeline runs these gates:
+
+- Lint and format
+- Build
+- Type-check
+- Unit tests
+- Integration tests
+- Security scan
+```
+
+### Pattern: Definition List
+
+For term + definition pairs, use bold-prefixed bullets:
+
+```markdown
+- **Orchestrator** — the agent that dispatches subagents.
+- **Worker** — an agent spawned for a leaf task.
+- **Lead** — a middle-tier agent supervising one wave.
+```
+
+The em-dash separator reads cleanly. Don't use a colon (looks like
+prose); don't use a hyphen alone (too thin).
+
+## Link Patterns
+
+### Pattern: Inline Reference
+
+```markdown
+The release pipeline is defined in [ADR-065](../.cleo/adrs/ADR-065-release-pipeline.md).
+```
+
+### Pattern: Section Reference
+
+```markdown
+See [§Worktree Discipline](#worktree-discipline) below for the full constraint.
+```
+
+### Pattern: External + Citation Comment
+
+```markdown
+The default cache behavior changed in [Next.js 15](https://nextjs.org/blog/next-15)
+— retrieved 2026-05-19.
+```
+
+The retrieval date is essential when citing an external page that may
+change. Without it, the reader can't tell whether the citation is
+still accurate.
+
+## Callout Patterns
+
+CLEO docs use bold-prefixed paragraphs rather than custom admonitions
+(no special syntax).
+
+```markdown
+**Note:** This feature requires CLEO v2026.5.81 or later.
+
+**Warning:** Running this command on a dirty working tree will lose changes.
+
+**Tip:** Use `cleo find` instead of `cleo list` for browsing.
+```
+
+The three callout types: Note (informational), Warning (potential
+foot-gun), Tip (efficiency improvement). Don't invent new ones.
+
+## Image Patterns
+
+### Pattern: Scoped UI Screenshot
+
+```markdown
+![The release pipeline dashboard showing three green checks](./images/release-dashboard.png)
+```
+
+The alt text describes what the image conveys, not what it is. "Three
+green checks" is meaningful; "Dashboard screenshot" is not.
+
+### Pattern: Diagram with Mermaid
+
+```markdown
+```mermaid
+graph LR
+  A[Task created] --> B[Wave dispatched]
+  B --> C[Worker completes]
+  C --> D[Manifest appended]
+  D --> E[Task closed]
+```
+```
+
+Mermaid renders inline in GitHub and most markdown viewers. Prefer
+over PNG diagrams for anything textual — Mermaid is editable in
+source control.
+
+## Frontmatter Patterns
+
+YAML frontmatter goes at the very top, between `---` fences.
+
+```markdown
+---
+title: How to configure the release pipeline
+date: 2026-05-19
+audience: maintainer
+status: draft
+---
+
+# How to configure the release pipeline
+...
+```
+
+The first H1 in the body matches the title field. Keeping both in sync
+is the writer's job.
+
+## Footnote and Aside Patterns
+
+CLEO docs avoid markdown footnotes — they break in many renderers.
+Use inline parenthetical references instead.
+
+```markdown
+GOOD:
+The orchestrator dispatches via `cleo orchestrate spawn` (see
+`packages/cleo/src/commands/orchestrate/spawn.ts:107`).
+
+BAD:
+The orchestrator dispatches via `cleo orchestrate spawn`[^1].
+
+[^1]: See `packages/cleo/src/commands/orchestrate/spawn.ts:107`.
+```
+
+## Whitespace and Structure
+
+- One blank line between sections.
+- Two blank lines around H1 headings (rare in CLEO docs — usually
+  only one H1 per file).
+- No trailing whitespace.
+- Final newline at end of file (POSIX requirement).
+- Tables: align the `|` separators by eye in source; it makes diff
+  review easier.
+
+## Final-Pass Checklist
+
+Before declaring a doc done, run through:
+
+- [ ] All code blocks have language tags.
+- [ ] All links have descriptive text (no "here", "this").
+- [ ] All tables ≤ 5 columns.
+- [ ] All headings state the point (not just the topic).
+- [ ] All "users" replaced with "people" or "companies".
+- [ ] All contractions present (don't, can't, won't).
+- [ ] No "easy", "simple", "just", "obviously".
+- [ ] Title and frontmatter title match.
+- [ ] Final newline present.

package/skills/ct-documentor/SKILL.md

@@ -229,3 +229,14 @@ Append ONE line to `{{MANIFEST_PATH}}`:
 - [ ] Output file written with "Files NOT Created" section
 - [ ] Manifest entry appended
 - [ ] Task completed via `cleo complete`
+
+---
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/chain-orchestration.md` — when to invoke lookup/write/review, input shapes, review loop budget
+- `references/doc-types-and-templates.md` — Diátaxis grid plus CLEO-native (ADR, agent-output, skill) templates
+- `references/style-coordination.md` — tone pillars, forbidden phrases, link/code/table discipline
+- `references/anti-patterns.md` — twelve documentation coordination failure modes