73 lines
3.6 KiB
Markdown
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.
|