3.6 KiB
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
- 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-upgradecreates it only when it is missing and never overwrites a file in it), and never touched byckb-reset. A template inlinked/<name>/templates/may be used read-only when nothing local matches. - A template is a Markdown file with
type: templatefrontmatter. 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 optionaloutput:sets the path. ckb-documentfills a template. It reads the whole template first, asks every question in one message, resolves named sources through the cascade index-first, and writes tooutputs/documents/withtype: documentfrontmatter 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 aTODO:line. Markdown is the only format it writes; other formats come from the general document skills, from that Markdown.- One example ships,
templates/status-report.md, with a one-pagetemplates/README.md.ckb-initcopies 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 readraw/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" tockb-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.