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

73 lines
3.6 KiB
Markdown

---
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/<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.