ckb/.agents/modules/voice/README.md
Michał Kopeć c57ddceffd Template 2.2.0: voice and convert modules
- 2.1.0 new opt-in `voice` module (D-0020): skill ckb-voice rewrites every
  prose file written under apply_to (outputs/answers, documents, reports,
  PROJECT-OVERVIEW) in a voice whose profile is a wiki page,
  wiki/voice/<name>.md (type voice-profile); settings in ckb.yaml (mode,
  profile, writer, apply_to, skip, chat); frozen spans never change, vague
  claims flagged not cut; `writer:` delegates to an external rewriting
  skill such as a personal ghost-writer. ckb-module writes a manifest's
  default_config into the entry's config:. Eval ckb-module/install-voice.
- 2.2.0 new opt-in `convert` module (D-0021): skill ckb-convert and
  convert.py turn Markdown into Word/ODT/PDF/HTML through pandoc with a
  house style in templates/styles/; unit tests and eval
  ckb-module/install-convert.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 20:57:39 +01:00

69 lines
2.9 KiB
Markdown

# `voice` module
*Read this in: **English** | [Polski](README.pl.md)*
Opt-in. Install with "install the voice module"; remove with "uninstall the
voice module". Nothing in here is active until installed.
## What it does
Answers, documents and reports the KB writes for people outside it tend to
read like a model wrote them. This module rewrites them in **your voice**
before they're saved. The voice is a wiki page, `wiki/voice/<name>.md`, so
the team can read it, review it and correct it like any other knowledge.
| Skill | Does |
|---|---|
| `ckb-voice` | Rewrites outgoing text in a voice profile, builds a profile from sample documents, records "we never say X" as it comes up, and changes the settings. |
Once installed, nothing changes until the first profile exists. Say
"calibrate our writing style" and give it a few documents that sound right.
From then on, every new file in `outputs/answers/`, `outputs/documents/`,
`outputs/reports/` and the project overview is written in that voice.
## What changes and what doesn't
The voice changes **wording**: banned AI vocabulary, formulaic structure,
hedging, flat rhythm, and the tone, formality and phrases your profile sets.
It never changes **content**. Frontmatter, `## Sources`, `## Crux` and every
quote, `## Notes`, contradiction markers, code, paths, links, numbers and
names come out exactly as they went in. A rewrite that would alter one of
them is rejected. A vague claim isn't cut, it's flagged for you. Wiki pages
are never rewritten; the wiki stays plain.
## Settings
In `ckb.yaml`, under the module's entry. Change them by asking ("set the
voice mode to ask", "make board the default voice"):
```yaml
config:
mode: auto # auto | ask (once per file) | off
profile: house # the default voice, wiki/voice/house.md
writer: ckb-voice # or another rewriting skill you have, e.g. ghost-writer
apply_to: [outputs/answers/, outputs/documents/, outputs/reports/, PROJECT-OVERVIEW]
skip: [outputs/okf/, outputs/starlight/]
chat: false # true = chat answers too
```
Which voice is used: one named in the request ("in the board voice"), else
the `voice:` set in your own `workload/profiles/` page ("use my own voice by
default"), else `profile`.
## Using your own rewriting skill
If you already have a rewriting skill you like, such as a personal
`ghost-writer` in `~/.claude/skills/`, set `writer: ghost-writer`. The
module still picks the profile from the wiki and still guards the frozen
parts; your skill does the rewriting. If the skill isn't installed on a
teammate's machine, their sessions fall back to `ckb-voice`.
## Safety
- **Profiles are committed.** Everyone who clones the KB sees them. Keep
samples to text you'd share with the team.
- **Third-party voices** ("write like Feynman") are built from published
text and keep only a few lines as a sample.
- **Uninstalling keeps the profiles.** `wiki/voice/` stays as knowledge;
only the automatic rewrite stops.