ckb/docs/decisions/README.md
Michał Kopeć bf2cc8e8aa Template 1.23.0: agent-knowledge release 2, schema 1.6
Schema 1.6, all fields optional (D-0014):
- F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`,
  `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews
- F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred
- F21 `tags` against the new `wiki/tags.md`, lint check 19,
  retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags
- F9 profiles in workload/profiles/, protected `## Rules` on project
  scope pages, precedence AGENTS.md > Rules > profile
- F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill

Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the
bash/PowerShell fallbacks); open threads no longer print twice.
ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight
shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:06:02 +01:00

4 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-reset may wipe it, and a fresh ckb-init starts 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
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