All work lands on dev; VERSION and the changelog change only when dev is merged into experimental, test or main. Paths: dev->experimental->test->main, dev->test->main, dev->main. A version keeps its number when promoted; main is merged back into dev, test and experimental after a release. 1.x keeps its own fixes. experimental becomes the preview channel; dev is not a channel, and ckb-init/ckb-upgrade offer experimental when asked for it. README, manuals, changelog channel sections and D-0022 updated; Polish manual gains the profile-skills section. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
6.6 KiB
6.6 KiB
Template design decisions
Decision records about the template itself — why the Cascade KB is shaped
the way it is. They use the same type: decision format as wiki/decisions/,
but they live here, in the template layer, because:
wiki/decisions/is content: a KB's own decisions about its own subject.ckb-resetmay wipe it, and a freshckb-initstarts it empty.- Skills, modules and docs cite these records. A template must not depend on pages the content layer is allowed to delete.
ckb-upgrade carries this folder along with the rest of the template layer.
ckb-decide never writes here — it is not a place for a KB's project decisions.
| # | Decision |
|---|---|
| D-0001 | Optional capabilities ship as file-based modules under .agents/modules/, installed on request |
| D-0002 | The software module: gitignored src/ clones, two OpenSpec spec levels, hybrid vendoring |
| D-0003 | Python stays the only scripting runtime; portable interpreter resolution, per-OS install guidance, a native fallback for the session-start check, degraded paths per skill (PowerShell half dropped by D-0019) |
| D-0004 | The git identity is the session's author; one workload file per person per day; **Author:** on log entries and saved conversations |
| D-0005 | A new session asks for its title first and waits (point 1 reversed by D-0006); routines are time-since-last actions in ckb.yaml, run after the user's request, with last_run committed |
| D-0006 | The agent derives the session title from the first message and only announces it in one line; announce_title replaces ask_title |
| D-0007 | The mcp module serves the KB over MCP: cascade-aware reads; remote writes limited to raw/inbox/ and retraction requests, each naming its KB and confirmed by the user, and removable only by the person who added the document; auth switched by one flag (none/token/oauth), server runs in place against its own clone |
| D-0008 | Document templates are the user's Markdown files in root templates/, outside the cascade and the template layer; a comment per section is the agent's brief; ckb-document fills one into outputs/documents/, asking in one round and leaving TODO: lines instead of guesses |
| D-0009 | Session start is one session_start.py call that says what to act on; wiki/index.md and the whole workload file are no longer read at start; a skill's ## Purpose says only what its description does not |
| D-0010 | A root ABOUT.md, written by the owner, states what the KB holds (purpose, audience, scope, owners, sensitivity) and the README links to it; agents read it, never edit it; ingest checks scope against it; wiki/overview.md stays the agent's summary |
| D-0011 | Session start can run as a per-machine, opt-in Claude Code SessionStart hook that injects the Rule E brief before the first message and after every compaction; Rule E stays the fallback |
| D-0012 | "What is in flight" is collected from ### Open threads checkboxes in each person's workload notes, not a shared status page; threads close where they were opened |
| D-0013 | Kept answers go to outputs/answers/ with fingerprinted sources and reach the wiki only through ingest; committed text is scanned for secrets and <private> spans, never auto-fixed, with a line-hash allowlist |
| D-0014 | Schema 1.6: review/reviewed_by/reviewed_on (not status), tags against wiki/tags.md, a > CONTRADICTION: marker, protected ## Rules on project scopes; profiles in workload/profiles/ and explicit lessons via a new ckb-profile skill; claim-level validity deferred |
| D-0015 | Retrieval gains a stdlib FTS5 section index (title/heading/tldr as a separate context column) cached in tmp/, fused at weight 1.0, with section anchors and token estimates; pages read go to a per-machine tmp/access.log that lint turns into demotion proposals only |
| D-0016 | Schema 1.7: agent-built topic pages in wiki/topics/ with member-page digests as sources; a new ckb-consolidate skill writes proposals-only reports (topics, merges, links, stale, old log) and builds only approved topic pages |
| D-0017 | Opt-in capture module (stdlib fetch, Wayback only over a failed/thinner page, agent tool fallback, untrusted marking, dedup at capture, yt-dlp with consent); structural skill evals with a prepare/check runner; multi-agent setup documented as untested |
| D-0018 | Opt-in share module: KBs exchange documents through a git channel with one append-only mailbox per KB; received mail lands in raw/inbox/ (untrusted) and retractions in raw/retractions/; the git author must own the mailbox; handled messages are kept in a ledger in ckb.yaml |
| D-0019 | Template 2.0.0 drops PowerShell; every script the template and its modules ship is Python (bash fallback and the container entrypoint named as exceptions); 1.x continues on a 1.x maintenance branch; ckb-upgrade never crosses a major version without asking |
| D-0020 | Opt-in voice module: outgoing prose (kept answers, documents, reports, the project overview) is rewritten in a voice whose profile is a wiki page in wiki/voice/; settings in ckb.yaml; routed by the AGENTS.md block, not per-skill edits; frozen spans never change, vague claims are flagged rather than cut; writer: plugs in an external rewriting skill |
| D-0021 | Opt-in convert module: Markdown becomes Word/ODT/PDF/HTML through pandoc in a named house style, a reference .docx in templates/styles/ built from a few settings or copied from a company .docx/.dotx; PDF and ODT go through LibreOffice from the styled .docx; KB links and frontmatter are cleaned in the copy; the Markdown stays the source |
| D-0022 | All work lands on dev; VERSION changes only when dev is merged into experimental, test or main, a version keeps its number when promoted, main is merged back after a release, 1.x keeps its own fixes, and dev is not a channel |