- 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>
4.9 KiB
4.9 KiB
| type | tldr | status | decided_on | decided_by | affects | confidence | quality | last_updated | freshness_window_days | retention |
|---|---|---|---|---|---|---|---|---|---|---|
| decision | Markdown leaves the KB as Word/ODT/PDF/HTML through an opt-in `convert` module — pandoc does the conversion, the look is a named reference .docx in templates/styles/ that a stdlib script can build or adjust from a few settings or copy from a company .docx/.dotx, PDF and ODT go through LibreOffice from the styled .docx so every format matches, and the Markdown stays the source. | accepted | 2026-11-11 | Michał Kopeć | .agents/modules/convert/, tests/unit/test_convert.py, tests/evals/ckb-module/install-convert/, README.md, docs/MANUAL.md, docs/CHANGELOG.md | 0.75 | 0.8 | 2026-11-11 | 365 | high |
D-0021 — A convert module for documents that leave as Office files
Status: Accepted · Decided: 2026-11-11 · Deciders: Michał Kopeć
Context
ckb-document, kept answers and reports all write Markdown. The people they
go to want a Word file or a PDF in the company's look. ckb-document Step 4
says to make a .docx "with the general document skills", which leaves the
fonts, sizes and margins to whatever the agent picks each time. Michał wanted
a pandoc front end with design templates, so users get a consistent document
without thinking about typography.
Decision
- An opt-in module (D-0001 pattern),
convert, with one skill,ckb-convert, and one stdlib script,convert.py. pandoc is a system tool not every KB needs. - A style is a reference
.docxintemplates/styles/<name>.docx, pandoc's own mechanism: it takes styles, page setup, header and footer from it and ignores the text. Optional<name>.odtand<name>.csscover ODT and HTML.templates/already holds the user's document templates and isn't a retrieval layer.ckb-documentlists onlytemplates/*.md, so the subfolder doesn't clash. - Styles from settings, not by hand.
new-style/edit-stylecopy pandoc's default reference and patch body font, heading font, body size, heading colour, paper (A4/Letter) and margins straight intostyles.xml,theme1.xmland the bodysectPr, keeping the schema's child order so Word opens the result.--fromtakes a company.docxor.dotx(content type rewritten) andcheck-stylelists the styles pandoc uses that it lacks. Anything richer (logos, cover pages) is edited in Word, and the skill says so. - One look for every format. PDF and ODT are produced by LibreOffice from
the styled
.docx, in a private profile so an open LibreOffice doesn't block it. Without LibreOffice, PDF falls back to a pandoc PDF engine and the skill reports that the style wasn't applied. - KB Markdown is cleaned for an outside reader, in the copy only:
frontmatter → title/author/date/lang metadata (e-mail dropped), the
leading
# H1→ title, template comments dropped, wikilinks and KB-path links → text (keep_linksopts out), code blocks untouched. - The Markdown stays the source, always kept. An existing converted file
is never overwritten without
--force; the skill asks, since it may have been edited in Word. - Settings in
ckb.yamlthroughdefault_config(D-0020):style,format,out_dir,toc,number_sections,keep_links. - Hook through the
AGENTS.mdblock, as D-0020 did: any request for an Office/PDF file goes throughckb-convert, afterckb-voicewhen that is installed.ckb-documentis unchanged. - pandoc is a non-blocking dependency of the install. The module is committed and shared, and a teammate without pandoc gets install instructions at first use rather than a blocked install for everyone.
Alternatives considered
- python-docx or the general docx skill to build documents directly. These need a third-party package or produce a different look per run, and they can't read the Markdown the KB already has. pandoc is the standard tool for exactly this conversion.
- Ship a binary
house.docxin the module. A binary in the template repo, and a single fixed look. Generating it from pandoc's default plus settings keeps the repo text-only and the look adjustable. - pandoc's LaTeX route for PDF. It needs a TeX install and a second style
definition that drifts from the Word one. LibreOffice reuses the
.docx. - Edit
ckb-documentto convert. That would cover one producer only. Answers, reports and wiki pages need conversion too.
Consequences
- No new page types or fields; no schema change.
- Fonts aren't embedded in
.docx; a rare font shows as a substitute. The README and skill say so. - The XML patching covers the settings listed and nothing else. A company
template with unusual structure gets
check-styleand a pointer to Word. - Tests:
tests/unit/test_convert.py(clean-up always; style patching and conversion when pandoc is present) and an install eval,ckb-module/install-convert, not yet run.