--- type: decision tldr: 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. status: accepted decided_on: 2026-10-29 decided_by: Michał Kopeć affects: AGENTS.md, templates/, .agents/skills/ckb-document/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-reset/, docs/MANUAL.md confidence: 0.85 quality: 0.8 last_updated: 2026-10-29 freshness_window_days: 365 retention: 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//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.