From c57ddceffd09d28db68018333ca49dbe2142bb2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Kope=C4=87?= Date: Wed, 11 Nov 2026 20:57:39 +0100 Subject: [PATCH] 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/.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 --- .agents/modules/convert/README.md | 82 ++ .agents/modules/convert/README.pl.md | 86 ++ .../convert/fragments/agents-routing.md | 16 + .../convert/fragments/gitignore.snippet | 1 + .agents/modules/convert/module.yaml | 56 ++ .../modules/convert/scaffold/styles-README.md | 26 + .../convert/skills/ckb-convert/SKILL.md | 151 ++++ .../skills/ckb-convert/scripts/convert.py | 746 ++++++++++++++++++ .agents/modules/voice/README.md | 69 ++ .agents/modules/voice/README.pl.md | 73 ++ .../modules/voice/fragments/agents-routing.md | 20 + .../modules/voice/fragments/gitignore.snippet | 1 + .agents/modules/voice/module.yaml | 45 ++ .../modules/voice/skills/ckb-voice/SKILL.md | 238 ++++++ .../skills/ckb-voice/references/ai-signs.md | 139 ++++ .../ckb-voice/references/calibration.md | 86 ++ .../ckb-voice/references/good-writing.md | 158 ++++ .../ckb-voice/references/profile-template.md | 49 ++ .../skills/ckb-voice/references/rules.md | 188 +++++ .agents/skills/ckb-module/SKILL.md | 7 +- README.md | 7 +- README.pl.md | 7 + VERSION | 2 +- docs/CHANGELOG.md | 4 +- docs/CHANGELOG.pl.md | 4 +- docs/MANUAL.md | 2 + docs/MANUAL.pl.md | 2 + docs/decisions/0020-voice-module.md | 89 +++ docs/decisions/0021-convert-module.md | 90 +++ docs/decisions/README.md | 2 + tests/evals/README.md | 2 + .../ckb-module/install-convert/case.json | 53 ++ .../evals/ckb-module/install-voice/case.json | 56 ++ tests/unit/test_convert.py | 146 ++++ 34 files changed, 2697 insertions(+), 6 deletions(-) create mode 100644 .agents/modules/convert/README.md create mode 100644 .agents/modules/convert/README.pl.md create mode 100644 .agents/modules/convert/fragments/agents-routing.md create mode 100644 .agents/modules/convert/fragments/gitignore.snippet create mode 100644 .agents/modules/convert/module.yaml create mode 100644 .agents/modules/convert/scaffold/styles-README.md create mode 100644 .agents/modules/convert/skills/ckb-convert/SKILL.md create mode 100644 .agents/modules/convert/skills/ckb-convert/scripts/convert.py create mode 100644 .agents/modules/voice/README.md create mode 100644 .agents/modules/voice/README.pl.md create mode 100644 .agents/modules/voice/fragments/agents-routing.md create mode 100644 .agents/modules/voice/fragments/gitignore.snippet create mode 100644 .agents/modules/voice/module.yaml create mode 100644 .agents/modules/voice/skills/ckb-voice/SKILL.md create mode 100644 .agents/modules/voice/skills/ckb-voice/references/ai-signs.md create mode 100644 .agents/modules/voice/skills/ckb-voice/references/calibration.md create mode 100644 .agents/modules/voice/skills/ckb-voice/references/good-writing.md create mode 100644 .agents/modules/voice/skills/ckb-voice/references/profile-template.md create mode 100644 .agents/modules/voice/skills/ckb-voice/references/rules.md create mode 100644 docs/decisions/0020-voice-module.md create mode 100644 docs/decisions/0021-convert-module.md create mode 100644 tests/evals/ckb-module/install-convert/case.json create mode 100644 tests/evals/ckb-module/install-voice/case.json create mode 100644 tests/unit/test_convert.py diff --git a/.agents/modules/convert/README.md b/.agents/modules/convert/README.md new file mode 100644 index 0000000..730894b --- /dev/null +++ b/.agents/modules/convert/README.md @@ -0,0 +1,82 @@ +# `convert` module + +*Read this in: **English** | [Polski](README.pl.md)* + +Opt-in. Install with "install the convert module"; remove with "uninstall +the convert module". Nothing in here is active until installed. + +## What it does + +The KB writes Markdown. The people you send things to want a Word file or a +PDF that looks like the rest of your company's documents. This module turns +any Markdown file in the KB into **`.docx`, `.odt`, PDF or HTML** through +[pandoc](https://pandoc.org), in a **house style**, so nobody picks fonts, +sizes or margins by hand. + +| Skill | Does | +|---|---| +| `ckb-convert` | Converts a file in a named style; creates a style from a few settings or from your company's Word template; changes, checks and lists styles. | + +Say "give me the status report as a Word file" or "convert this answer to +PDF". The first time, it asks once how the house style should look. + +## Styles + +A style is a Word file, `templates/styles/.docx`. pandoc takes fonts, +sizes, colours, spacing, page size, margins, header and footer from it and +ignores its text. You get one in one of three ways: + +- **Describe it**: "make a house style with Georgia 11pt, navy headings, A4". +- **Bring your own**: "use Company.dotx as the house style". The agent copies + it in and tells you which styles pandoc needs that your template lacks. +- **Edit it by hand** in Word or LibreOffice: change the *styles* (Normal, + Body Text, Title, Heading 1–6, Table), not the text, and save as `.docx`. + +Several styles can live side by side ("convert it in the board style"). +`.css` styles HTML, and an optional `.odt` styles ODT directly. + +PDF and ODT are made from the styled `.docx` with LibreOffice, so all formats +look the same. Without LibreOffice, PDF falls back to a pandoc PDF engine and +won't follow the Word style. You'll be told when that happens. + +## What changes on the way + +The Markdown file is never changed and is always kept. In the converted +copy: + +- frontmatter becomes the title, author (without the e-mail) and date, and the + first `# Heading` becomes the title when there's none; +- `` left over from a template are dropped; +- `[[Wikilinks]]` and links to KB paths become plain text, because they'd be + dead in a Word file (say "keep the links" to keep them); web links stay; +- code blocks, tables, task lists and images come through as they are. + +## Settings + +In `ckb.yaml`, under the module's entry. Change them by asking ("make PDF +the default", "always add a table of contents"): + +```yaml +config: + style: house # templates/styles/house.docx + format: docx # docx | odt | pdf | html + out_dir: outputs/documents/ # a file already in outputs/ converts beside itself + toc: false + number_sections: false + keep_links: false +``` + +## Requirements + +- **pandoc**, for every conversion. The install doesn't need it, so a + teammate without it can still clone the KB; they're told how to get it the + first time they convert. +- **LibreOffice**, optional, for PDF and ODT in the house style. +- Python 3.8+ like every other KB script. Nothing is installed without asking. + +## Good to know + +- **Fonts aren't embedded** in a `.docx`. Choose fonts your readers have. +- **Uninstalling keeps your styles**: `templates/styles/` stays. +- **Macro templates** (`.docm`, `.dotm`) are refused; save a copy as `.docx` + or `.dotx` first. diff --git a/.agents/modules/convert/README.pl.md b/.agents/modules/convert/README.pl.md new file mode 100644 index 0000000..d924684 --- /dev/null +++ b/.agents/modules/convert/README.pl.md @@ -0,0 +1,86 @@ +# Moduł `convert` + +*Przeczytaj w: [English](README.md) | **Polski*** + +Opcjonalny. Instalacja: „install the convert module”, usunięcie: „uninstall +the convert module”. Dopóki nie jest zainstalowany, nic z tego folderu nie +działa. + +## Co robi + +Baza pisze w Markdownie. Ludzie, do których coś wysyłasz, chcą pliku Worda +albo PDF-a, który wygląda jak reszta dokumentów w firmie. Ten moduł zamienia +dowolny plik Markdown z bazy na **`.docx`, `.odt`, PDF lub HTML** przez +[pandoc](https://pandoc.org), w **stylu firmowym**, więc nikt nie dobiera +ręcznie czcionek, rozmiarów ani marginesów. + +| Skill | Co robi | +|---|---| +| `ckb-convert` | Konwertuje plik w wybranym stylu; tworzy styl z kilku ustawień albo z firmowego szablonu Worda; zmienia, sprawdza i wypisuje style. | + +Powiedz „give me the status report as a Word file” albo „convert this answer +to PDF”. Za pierwszym razem padnie jedno pytanie o to, jak ma wyglądać styl +firmowy. + +## Style + +Styl to plik Worda, `templates/styles/.docx`. pandoc bierze z niego +czcionki, rozmiary, kolory, odstępy, format strony, marginesy, nagłówek i +stopkę, a jego treść pomija. Styl można zdobyć na trzy sposoby: + +- **Opisać go**: „make a house style with Georgia 11pt, navy headings, A4”. +- **Przynieść własny**: „use Company.dotx as the house style”. Agent go + skopiuje i powie, których stylów potrzebnych pandocowi brakuje w szablonie. +- **Poprawić ręcznie** w Wordzie lub LibreOffice: zmieniać *style* (Normal, + Body Text, Title, Heading 1–6, Table), nie treść, i zapisać jako `.docx`. + +Stylów może być kilka („convert it in the board style”). `.css` +ustala wygląd HTML, a opcjonalny `.odt` wygląd ODT. + +PDF i ODT powstają ze sformatowanego `.docx` przez LibreOffice, więc +wszystkie formaty wyglądają tak samo. Bez LibreOffice PDF robi silnik PDF +pandoca i styl Worda nie jest stosowany. Agent o tym powie. + +## Co się zmienia po drodze + +Plik Markdown nigdy się nie zmienia i zawsze zostaje. W skonwertowanej +kopii: + +- frontmatter staje się tytułem, autorem (bez adresu e-mail) i datą, a + pierwszy nagłówek `#` staje się tytułem, gdy frontmatter go nie ma; +- komentarze `` pozostałe z szablonu znikają; +- `[[Wikilinki]]` i linki do ścieżek w bazie stają się zwykłym tekstem, bo w + pliku Worda byłyby martwe („keep the links” je zostawia); linki do stron + WWW zostają; +- bloki kodu, tabele, listy zadań i obrazy przechodzą bez zmian. + +## Ustawienia + +W `ckb.yaml`, we wpisie modułu. Zmienia się je prośbą („make PDF the +default”, „always add a table of contents”): + +```yaml +config: + style: house # templates/styles/house.docx + format: docx # docx | odt | pdf | html + out_dir: outputs/documents/ # plik już leżący w outputs/ trafia obok siebie + toc: false + number_sections: false + keep_links: false +``` + +## Wymagania + +- **pandoc** do każdej konwersji. Instalacja modułu go nie wymaga, więc + osoba z zespołu bez pandoca nadal może sklonować bazę; przy pierwszej + konwersji dowie się, jak go zainstalować. +- **LibreOffice**, opcjonalnie, do PDF i ODT w stylu firmowym. +- Python 3.8+, jak każdy skrypt bazy. Nic nie jest instalowane bez pytania. + +## Warto wiedzieć + +- **Czcionki nie są osadzane** w `.docx`. Wybieraj czcionki, które mają + czytelnicy. +- **Odinstalowanie zostawia style**: `templates/styles/` zostaje. +- **Szablony z makrami** (`.docm`, `.dotm`) są odrzucane; najpierw zapisz + kopię jako `.docx` lub `.dotx`. diff --git a/.agents/modules/convert/fragments/agents-routing.md b/.agents/modules/convert/fragments/agents-routing.md new file mode 100644 index 0000000..f1519cb --- /dev/null +++ b/.agents/modules/convert/fragments/agents-routing.md @@ -0,0 +1,16 @@ +## MODULE: convert + +Markdown in this KB becomes Word, ODT, PDF or HTML through pandoc, in a house +style: `templates/styles/.docx`. Settings are under the `convert` +entry of `kb_modules:` in `ckb.yaml`. + +- A request for a document as `.docx`, `.odt`, `.pdf` or `.html` ("as a Word + file", "send me a PDF") goes through `ckb-convert`, after the Markdown is + final (after `ckb-voice`, when that module is installed). The Markdown is + always kept beside the converted file. +- Styles are the user's files: create or change one only on request, and + never edit a style the user supplied (`--from`) unless asked. + +| User intent | Skill | +|---|---| +| Convert Markdown to Word/ODT/PDF/HTML, or create, change, check or list a house style | `ckb-convert` | diff --git a/.agents/modules/convert/fragments/gitignore.snippet b/.agents/modules/convert/fragments/gitignore.snippet new file mode 100644 index 0000000..2a8d190 --- /dev/null +++ b/.agents/modules/convert/fragments/gitignore.snippet @@ -0,0 +1 @@ +# convert module: nothing extra to ignore (styles in templates/styles/ are tracked). diff --git a/.agents/modules/convert/module.yaml b/.agents/modules/convert/module.yaml new file mode 100644 index 0000000..312e975 --- /dev/null +++ b/.agents/modules/convert/module.yaml @@ -0,0 +1,56 @@ +# Cascade KB module manifest — read by `ckb-module` on install/uninstall. +# See docs/decisions/0021-convert-module.md. +name: convert +title: Document conversion with house styles +version: 1.0.0 +requires_kb_schema: "1.7" +summary: > + Turns any Markdown file in the KB (a document from a template, a kept + answer, a report, a wiki page) into Word, OpenDocument, PDF or HTML through + pandoc, in a named house style kept in templates/styles/, so nobody has to + pick fonts, sizes or margins by hand. + +skills: + - ckb-convert + +# Created on install, never removed on uninstall: it holds the user's styles. +scaffold: + - path: templates/styles/ + from: scaffold/styles-README.md + as: templates/styles/README.md + note: House styles, one NAME.docx per style (NAME.odt and NAME.css optional). + +agents_fragment: fragments/agents-routing.md +gitignore_fragment: fragments/gitignore.snippet + +# Written under this module's `config:` in ckb.yaml on install; ckb-convert +# owns them afterwards ("make PDF the default", "use the board style"). +default_config: + style: house # templates/styles/