ckb/docs/decisions/0008-document-templates.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

3.6 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision Document templates are the user's own Markdown files in a root templates/ folder, outside the cascade and the template layer; a comment per section is the brief the agent follows, and ckb-document fills one template into outputs/documents/, asking its questions in one round and leaving TODO lines where it has nothing to say. accepted 2026-10-29 Michał Kopeć AGENTS.md, templates/, .agents/skills/ckb-document/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-reset/, docs/MANUAL.md 0.85 0.8 2026-10-29 365 high

D-0008 — Document templates live in templates/ and are filled by ckb-document

Status: Accepted · Decided: 2026-10-29 · Deciders: Michał Kopeć

Context

Some documents get written again and again with the same shape: a status report, a handover note, meeting minutes. Each time the agent was briefed from scratch, in chat, on what the sections were and where the content should come from. The brief belongs in a file the user owns and the agent reads.

Decision

  1. A root templates/ folder holds document templates. It is the user's content: not a cascade layer (retrieval never reads it), not part of the template layer (ckb-upgrade creates it only when it is missing and never overwrites a file in it), and never touched by ckb-reset. A template in linked/<name>/templates/ may be used read-only when nothing local matches.
  2. A template is a Markdown file with type: template frontmatter. Headings give the document its shape and are kept. An HTML comment under a heading is the agent's brief for that section: it can say to ask the user, name a source, set a length, or say when to drop the section. It is followed and removed. Everything else is boilerplate, copied as is. {{date}}, {{author}} and {{slug}} are filled automatically; any other {{placeholder}} is asked for once. An optional output: sets the path.
  3. ckb-document fills a template. It reads the whole template first, asks every question in one message, resolves named sources through the cascade index-first, and writes to outputs/documents/ with type: document frontmatter naming the template, the date, the author and the pages used. It never overwrites a file and never fills a gap with a guess: a missing source or answer becomes a TODO: line. Markdown is the only format it writes; other formats come from the general document skills, from that Markdown.
  4. One example ships, templates/status-report.md, with a one-page templates/README.md. ckb-init copies both; after that they are the user's.

Alternatives considered

  • wiki/templates/ was rejected: templates are not knowledge, would show up in retrieval and lint, and would be wiped by a reset.
  • raw/templates/ was rejected: raw/ is ingest material, and an empty inbox makes ingest read raw/ directly.
  • A placeholder mini-language (typed directives such as @ask, @source) was rejected in favour of plain-language comments. The agent reads instructions well; the user should not learn a syntax.

Consequences

  • The word "template" now has two meanings in this repo. Docs say "document template" for the files in templates/ and keep "the template" for the tooling layer; the routing table's disambiguation sends "upgrade the template" to ckb-upgrade.
  • Generated documents are tracked in git under outputs/documents/, so a shared KB accumulates them. That is intended: they are deliverables, not build artifacts.