Template 1.13.0: conversation autosave switch with per-machine hook check
- ckb.yaml: conversations.autosave (default false). On, Rule E saves every session at its end without asking; ckb-add-conversation toggles it on request. - Per-machine half: autosave_hook.py --check/--install/--remove manages a Claude Code Stop hook in gitignored .claude/settings.local.json. Rule E runs --check at session start when autosave is on and asks before changing machine configuration; toggling the switch asks the same. - save_conversation.py --from-hook reads transcript_path from hook stdin. - ckb-init writes the block, ckb-upgrade leaves it alone. - Manual, READMEs and changelog in English and Polish; Polish changelog also gains the missing 1.11.1 and 1.12.0 rows. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
parent
6b7f0222c6
commit
29bb631b27
15 changed files with 327 additions and 22 deletions
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-add-conversation
|
||||
description: Save the current Claude Code conversation (or an earlier session of this project) verbatim into raw/saved-conversations/<YYYY-MM-DD>/ as the original JSONL plus a readable Markdown rendering, and search those saved conversations when asked what was discussed or instructed before. Saved conversations never enter retrieval or the wiki on their own. Use for "save this conversation", "save the chat", "archive this session", "keep a copy of our talk", and for "did we discuss X", "what did I tell you about X", "what did I ask you to do about Y last time", "find the conversation where ...".
|
||||
description: Save the current Claude Code conversation (or an earlier session of this project) verbatim into raw/saved-conversations/<YYYY-MM-DD>/ as the original JSONL plus a readable Markdown rendering, and search those saved conversations when asked what was discussed or instructed before. Saved conversations never enter retrieval or the wiki on their own. Use for "save this conversation", "save the chat", "archive this session", "keep a copy of our talk", for "did we discuss X", "what did I tell you about X", "what did I ask you to do about Y last time", "find the conversation where ...", and for toggling the autosave switch: "save conversations automatically", "turn on/off conversation autosave", "stop saving every conversation".
|
||||
---
|
||||
|
||||
# Add conversation skill
|
||||
|
|
@ -24,8 +24,10 @@ What this skill is **not**:
|
|||
- Not ingest. A saved conversation becomes wiki knowledge only when the user
|
||||
copies its `.md` into `raw/inbox/` and says "Ingest" — the copy is theirs
|
||||
to make, so the choice of what enters the wiki stays explicit.
|
||||
- Not automatic. The agent asks at session end (Rule E) and saves only on a
|
||||
clear yes. Never save because a session "seems important".
|
||||
- Not automatic by default. The agent asks at session end (Rule E) and
|
||||
saves only on a clear yes. Never save because a session "seems
|
||||
important". The one exception is the `autosave` switch below, which the
|
||||
user turns on deliberately.
|
||||
|
||||
## Where transcripts come from
|
||||
|
||||
|
|
@ -120,6 +122,71 @@ with the header the script would write, see `INDEX_HEADER` in the script).
|
|||
Tell the user once that the readable `.md` can be produced later by re-running
|
||||
the script with `--from <that jsonl>` once Python is available.
|
||||
|
||||
## The autosave switch
|
||||
|
||||
`ckb.yaml` carries:
|
||||
|
||||
```yaml
|
||||
conversations:
|
||||
autosave: false # true: save every session's transcript at session end without asking
|
||||
```
|
||||
|
||||
With `autosave: true`, Rule E saves the conversation at session end without
|
||||
asking and reports the path in one line; the workload note names the file as
|
||||
usual. With `false` or no block at all, the agent asks once, as described
|
||||
above. The switch is repo-level and committed, so everyone working in this
|
||||
KB gets the same behaviour.
|
||||
|
||||
**Toggling it on request** ("save conversations automatically", "turn off
|
||||
autosave"): read `ckb.yaml`, change only the `autosave` value, write the
|
||||
file back with everything else byte-for-byte intact (`template:` and
|
||||
`kb_modules:` belong to other skills). Add the `conversations:` block if it
|
||||
is missing. Confirm the new value in one line, then run the per-machine
|
||||
check described below and ask about the hook. When turning it on, say once
|
||||
that every session will become a tracked file in the repo, including
|
||||
whatever file contents and command output the agent prints — the caveat in
|
||||
Save Step 2 no longer gets a chance to be said per session.
|
||||
|
||||
**The per-machine half.** The agent-side rule saves at session end only
|
||||
when the agent reaches that step; a session killed mid-turn is not saved. A
|
||||
Claude Code `Stop` hook closes that gap: it runs `save_conversation.py
|
||||
--from-hook` after every turn, and the script updates the same files in
|
||||
place. The hook reads the transcript path from the hook's stdin JSON, so the
|
||||
right session is saved even when several run in parallel.
|
||||
|
||||
Hooks are machine configuration, not template: they live in
|
||||
`.claude/settings.local.json`, which is gitignored. So the switch in
|
||||
`ckb.yaml` travels with the repo, and every machine that opens the repo has
|
||||
to be brought in line separately. `scripts/autosave_hook.py` does that:
|
||||
|
||||
```bash
|
||||
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --check # exit 0 = consistent, 1 = action needed
|
||||
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --install # merge the hook into settings.local.json
|
||||
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --remove # take it out, leave the rest intact
|
||||
```
|
||||
|
||||
`--install` takes `--python <cmd>` so the hook command uses the interpreter
|
||||
that actually works on this machine (resolve `<python>` as `AGENTS.md` §3
|
||||
describes and pass it). It merges into an existing file and refuses to
|
||||
touch one that is not valid JSON.
|
||||
|
||||
**Never change machine configuration silently.** Two moments call for the
|
||||
check, and both end in a question, not an action:
|
||||
|
||||
1. *Session start* (Rule E) — when `autosave: true`, run `--check`. On exit 1
|
||||
tell the user in one line what is out of line and ask whether to
|
||||
install (or remove) the hook on this machine. Apply only on a yes. If
|
||||
they decline, do not ask again this session; autosave then relies on the
|
||||
session-end rule alone, which is worth saying once.
|
||||
2. *Toggling the switch* — right after flipping `autosave` in `ckb.yaml`,
|
||||
run `--check` and ask the same question, so the switch and this machine
|
||||
agree from the first session. Turning autosave off and leaving the hook
|
||||
installed would keep saving every session, which is exactly what the
|
||||
user just asked to stop.
|
||||
|
||||
Without Python the hook cannot run either, so there is nothing to install:
|
||||
say so once and rely on the session-end rule.
|
||||
|
||||
## How to run this skill — Recall
|
||||
|
||||
Triggers: "did we discuss X", "have we talked about X before", "what did I
|
||||
|
|
|
|||
126
.agents/skills/ckb-add-conversation/scripts/autosave_hook.py
Normal file
126
.agents/skills/ckb-add-conversation/scripts/autosave_hook.py
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Check, install or remove the per-machine Claude Code Stop hook that makes
|
||||
conversation autosave mechanical.
|
||||
|
||||
autosave_hook.py --check # one line of status; exit 0 = nothing to do, 1 = action needed
|
||||
autosave_hook.py --install # add the hook to .claude/settings.local.json (merge, never overwrite)
|
||||
autosave_hook.py --remove # take it out again, leaving everything else intact
|
||||
|
||||
The hook lives in .claude/settings.local.json, which is per machine and
|
||||
gitignored. It runs save_conversation.py --from-hook after every turn, so the
|
||||
transcript on disk is always current even if the session dies mid-turn.
|
||||
Python 3.8+, standard library only.
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
SETTINGS = Path(".claude") / "settings.local.json"
|
||||
SCRIPT = ".agents/skills/ckb-add-conversation/scripts/save_conversation.py"
|
||||
MARK = "save_conversation.py --from-hook"
|
||||
|
||||
|
||||
def read_yaml_autosave(path=Path("ckb.yaml")) -> bool:
|
||||
"""Minimal reader: find `autosave:` under `conversations:`. No YAML parser needed."""
|
||||
if not path.exists():
|
||||
return False
|
||||
in_block = False
|
||||
for raw in path.read_text(encoding="utf-8").splitlines():
|
||||
line = raw.split("#", 1)[0].rstrip()
|
||||
if not line.strip():
|
||||
continue
|
||||
if not line.startswith((" ", "\t")):
|
||||
in_block = line.strip() == "conversations:"
|
||||
continue
|
||||
if in_block and line.strip().startswith("autosave:"):
|
||||
return line.split(":", 1)[1].strip().lower() in ("true", "yes", "on")
|
||||
return False
|
||||
|
||||
|
||||
def load_settings():
|
||||
if not SETTINGS.exists():
|
||||
return {}
|
||||
try:
|
||||
return json.loads(SETTINGS.read_text(encoding="utf-8") or "{}")
|
||||
except json.JSONDecodeError as e:
|
||||
sys.exit(f"error: {SETTINGS} is not valid JSON ({e}); fix it by hand before installing the hook")
|
||||
|
||||
|
||||
def hook_command(python: str) -> str:
|
||||
return f"{python} {SCRIPT} --from-hook >/dev/null 2>&1 || true"
|
||||
|
||||
|
||||
def installed(settings) -> bool:
|
||||
for group in settings.get("hooks", {}).get("Stop", []) or []:
|
||||
for h in group.get("hooks", []) or []:
|
||||
if MARK in str(h.get("command", "")):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def install(python: str):
|
||||
s = load_settings()
|
||||
if installed(s):
|
||||
print(f"already installed in {SETTINGS}")
|
||||
return
|
||||
s.setdefault("hooks", {}).setdefault("Stop", []).append(
|
||||
{"hooks": [{"type": "command", "command": hook_command(python)}]})
|
||||
SETTINGS.parent.mkdir(parents=True, exist_ok=True)
|
||||
SETTINGS.write_text(json.dumps(s, indent=2) + "\n", encoding="utf-8")
|
||||
print(f"installed Stop hook in {SETTINGS}: {hook_command(python)}")
|
||||
|
||||
|
||||
def remove():
|
||||
s = load_settings()
|
||||
if not installed(s):
|
||||
print(f"not installed in {SETTINGS}")
|
||||
return
|
||||
groups = []
|
||||
for group in s["hooks"]["Stop"]:
|
||||
kept = [h for h in group.get("hooks", []) if MARK not in str(h.get("command", ""))]
|
||||
if kept:
|
||||
group["hooks"] = kept
|
||||
groups.append(group)
|
||||
if groups:
|
||||
s["hooks"]["Stop"] = groups
|
||||
else:
|
||||
del s["hooks"]["Stop"]
|
||||
if not s["hooks"]:
|
||||
del s["hooks"]
|
||||
SETTINGS.write_text(json.dumps(s, indent=2) + "\n", encoding="utf-8")
|
||||
print(f"removed Stop hook from {SETTINGS}")
|
||||
|
||||
|
||||
def check() -> int:
|
||||
auto = read_yaml_autosave()
|
||||
have = installed(load_settings()) if SETTINGS.exists() else False
|
||||
if auto and not have:
|
||||
print(f"autosave: on in ckb.yaml, Stop hook NOT installed in {SETTINGS} — ask the user, then --install")
|
||||
return 1
|
||||
if not auto and have:
|
||||
print(f"autosave: off in ckb.yaml, but a Stop hook is still installed in {SETTINGS} — ask the user, then --remove")
|
||||
return 1
|
||||
print(f"autosave: {'on, hook installed' if auto else 'off, no hook'}")
|
||||
return 0
|
||||
|
||||
|
||||
def main(argv=None):
|
||||
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
g = ap.add_mutually_exclusive_group(required=True)
|
||||
g.add_argument("--check", action="store_true")
|
||||
g.add_argument("--install", action="store_true")
|
||||
g.add_argument("--remove", action="store_true")
|
||||
ap.add_argument("--python", default="python3", help="interpreter to put in the hook command (default python3)")
|
||||
a = ap.parse_args(argv)
|
||||
if a.check:
|
||||
return check()
|
||||
if a.install:
|
||||
install(a.python)
|
||||
else:
|
||||
remove()
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
|
|
@ -9,6 +9,7 @@ Markdown rendering next to it, then updates raw/saved-conversations/index.md.
|
|||
save_conversation.py --list # list this project's sessions, newest first
|
||||
save_conversation.py --session <id> # save a specific session (id or unique prefix)
|
||||
save_conversation.py --from <file.jsonl> # save a transcript file given explicitly
|
||||
save_conversation.py --from-hook # Claude Code hook: read {"transcript_path": ...} from stdin
|
||||
save_conversation.py --title "..." # override the derived title
|
||||
save_conversation.py --dry-run # say what would be written, write nothing
|
||||
|
||||
|
|
@ -266,6 +267,8 @@ def main(argv=None):
|
|||
ap.add_argument("--list", action="store_true", help="list this project's sessions and exit")
|
||||
ap.add_argument("--session", help="session id (or unique prefix) to save; default: most recently written")
|
||||
ap.add_argument("--from", dest="from_file", help="save this transcript file instead of looking one up")
|
||||
ap.add_argument("--from-hook", action="store_true",
|
||||
help="read Claude Code hook JSON from stdin and save its transcript_path")
|
||||
ap.add_argument("--title", help="override the derived title")
|
||||
ap.add_argument("--root", default=".", help="KB root (default: current directory)")
|
||||
ap.add_argument("--today", help="override the save date, YYYY-MM-DD (tests)")
|
||||
|
|
@ -275,6 +278,14 @@ def main(argv=None):
|
|||
root = Path(args.root).resolve()
|
||||
today = args.today or datetime.now().strftime("%Y-%m-%d")
|
||||
|
||||
if args.from_hook:
|
||||
try:
|
||||
hook = json.load(sys.stdin)
|
||||
except (json.JSONDecodeError, ValueError):
|
||||
sys.exit("error: --from-hook expects hook JSON on stdin")
|
||||
args.from_file = hook.get("transcript_path")
|
||||
if not args.from_file:
|
||||
sys.exit("error: hook JSON carries no transcript_path")
|
||||
if args.from_file:
|
||||
src = Path(args.from_file).expanduser().resolve()
|
||||
if not src.is_file():
|
||||
|
|
|
|||
|
|
@ -263,8 +263,10 @@ a fresh KB by accident is easy, and the local working tree is exactly how it
|
|||
happens.
|
||||
|
||||
`ckb.yaml` is also the modules manifest (`ckb-module` owns the `kb_modules:`
|
||||
list). A fresh KB has no modules, so at init time the file holds the
|
||||
`template:` block alone.
|
||||
list) and carries the conversation autosave switch (`ckb-add-conversation`
|
||||
owns `conversations:`). A fresh KB has no modules, so at init time the file
|
||||
holds the `template:` block, an empty `kb_modules: []`, and
|
||||
`conversations:` with `autosave: false`.
|
||||
|
||||
For `LICENSE`, copy the Apache License 2.0 text, but **ask the user first**
|
||||
whether to keep the copyright line as-is (appropriate if this new KB is
|
||||
|
|
|
|||
|
|
@ -298,8 +298,9 @@ Only if `template_upgrade_available` and at least one item was accepted:
|
|||
- If the user switched channel for this run (Step 0), write the new
|
||||
`branch:` into `ckb.yaml`'s `template:` block now that the switch has
|
||||
actually happened. Create the file with just that block if it doesn't
|
||||
exist; if it does, edit only `template:` and leave `kb_modules:` exactly
|
||||
as found — that list belongs to `ckb-module`. Persisting the branch is
|
||||
exist; if it does, edit only `template:` and leave `kb_modules:` and
|
||||
`conversations:` exactly as found — those belong to `ckb-module` and
|
||||
`ckb-add-conversation`. Persisting the branch is
|
||||
what stops the *next* upgrade from silently pulling the KB back to
|
||||
whichever channel it was on before.
|
||||
|
||||
|
|
|
|||
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -18,5 +18,7 @@ outputs/teaching
|
|||
.env
|
||||
__pycache__/
|
||||
*.pyc
|
||||
# Per-machine Claude Code settings (e.g. the conversation autosave Stop hook). Never shared.
|
||||
.claude/settings.local.json
|
||||
# Local scratch for ideas about changing the template. Never committed, never part of the template.
|
||||
ideas/
|
||||
|
|
|
|||
28
AGENTS.md
28
AGENTS.md
|
|
@ -15,7 +15,7 @@ Maintain this root layout:
|
|||
|
||||
```
|
||||
├── .agents/modules/ # Optional modules, inert until installed
|
||||
├── ckb.yaml # Repo manifest: template branch, installed modules
|
||||
├── ckb.yaml # Repo manifest: template branch, installed modules, conversation autosave
|
||||
├── docs/ # Manual, changelog, OpenSpec guide, template design records
|
||||
│ └── decisions/ # The template's own ADRs (D-0001…) — not KB content
|
||||
├── tests/ # Fixture KB + smoke test for the deterministic scripts
|
||||
|
|
@ -277,6 +277,19 @@ bash .agents/skills/ckb-lint/scripts/lint_quick.sh
|
|||
powershell -ExecutionPolicy Bypass -File .agents/skills/ckb-lint/scripts/lint_quick.ps1 # Windows
|
||||
```
|
||||
|
||||
When `ckb.yaml` has `conversations.autosave: true`, run a third check:
|
||||
|
||||
```bash
|
||||
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --check
|
||||
```
|
||||
|
||||
Exit 1 means this machine's configuration does not match the switch (the
|
||||
Stop hook that makes autosave mechanical is missing, or is still installed
|
||||
after autosave was turned off). Ask once whether to change
|
||||
`.claude/settings.local.json` accordingly, and apply only on a yes —
|
||||
`ckb-add-conversation` owns the details. Skip the check entirely when
|
||||
autosave is off and no hook file exists; stay quiet on exit 0.
|
||||
|
||||
`git status` covers unsynchronized history — if there are uncommitted
|
||||
changes or the branch is ahead/behind its remote-tracking branch, say so and
|
||||
suggest `ckb-sync-changes`. `--quick` covers knowledge rot: one line stating
|
||||
|
|
@ -288,11 +301,14 @@ is non-zero and suggest `ckb-lint`; stay quiet when it is clean.
|
|||
At session end, update `workload/` and repeat the unsynchronized-change
|
||||
check. Do not fetch or push unless the user asks.
|
||||
|
||||
Also at session end, when the session did real work (ingested, answered,
|
||||
decided, changed files), ask once whether to save the conversation with
|
||||
`ckb-add-conversation`, the same way the sync check is a suggestion and not
|
||||
an action. Skip the question for a trivial session. Save only on a clear
|
||||
yes; never save on your own initiative.
|
||||
Also at session end, read `conversations.autosave` in `ckb.yaml`:
|
||||
|
||||
- `true` — save the conversation with `ckb-add-conversation` without
|
||||
asking, and report the saved path in one line.
|
||||
- `false` or absent — when the session did real work (ingested, answered,
|
||||
decided, changed files), ask once whether to save, the same way the sync
|
||||
check is a suggestion and not an action. Skip the question for a trivial
|
||||
session. Save only on a clear yes; never save on your own initiative.
|
||||
|
||||
### Rule F: Demand-Driven Context
|
||||
When the KB cannot answer something, identify the missing knowledge and
|
||||
|
|
|
|||
12
README.md
12
README.md
|
|
@ -419,10 +419,13 @@ add yourself.
|
|||
|
||||
- **Session start** → read `wiki/index.md` and the latest workload summary;
|
||||
run `git status` and `lint_report.py --quick`; suggest `ckb-sync-changes`
|
||||
or `ckb-lint` only when either reports something
|
||||
or `ckb-lint` only when either reports something; when conversation
|
||||
autosave is on, also check this machine has the gitignored Stop hook in
|
||||
`.claude/settings.local.json` and ask before installing it
|
||||
- **Session end** → append to `workload/`; repeat the unsynchronized-change
|
||||
check; after a session that did real work, ask once whether to save the
|
||||
conversation (`ckb-add-conversation`) - saved only on a yes
|
||||
conversation (`ckb-add-conversation`) - saved only on a yes, or without
|
||||
asking when `conversations.autosave: true` is set in `ckb.yaml`
|
||||
- **Every turn that touches the KB** → a note in `workload/` (Rule D)
|
||||
- **Unanswerable question** → a `wiki/query-gaps.md` entry, the one write
|
||||
`ckb-retrieve` owns; answers are never filed back as pages automatically
|
||||
|
|
@ -518,7 +521,10 @@ conversations stay outside retrieval: questions are still answered from the
|
|||
wiki alone. You can ask about the conversations themselves ("did we discuss
|
||||
X", "what did I tell you about Y") and get the exact exchange quoted back.
|
||||
To bring one into the wiki, copy its `.md` into `raw/inbox/` and say
|
||||
"Ingest". Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
|
||||
"Ingest". Say "save conversations automatically" to flip
|
||||
`conversations.autosave` in `ckb.yaml`, after which every session is saved
|
||||
at its end without a question. Skill:
|
||||
`.agents/skills/ckb-add-conversation/SKILL.md`.
|
||||
|
||||
### Quiz Mode (on demand)
|
||||
Ask to be quizzed on the wiki ("quiz me on X", "test my knowledge") for a
|
||||
|
|
|
|||
|
|
@ -460,7 +460,10 @@ albo zaplanowanego agenta.
|
|||
|
||||
- **Start sesji** → odczyt `wiki/index.md` i ostatniego podsumowania
|
||||
workload; `git status` i `lint_report.py --quick`; sugestia
|
||||
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi
|
||||
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi;
|
||||
przy włączonym autozapisie rozmów sprawdza też, czy ta maszyna ma hook
|
||||
`Stop` w ignorowanym przez gita `.claude/settings.local.json`, i pyta
|
||||
przed jego zainstalowaniem
|
||||
- **Koniec sesji** → dopisanie do `workload/`; powtórzenie sprawdzenia
|
||||
niezsynchronizowanych zmian
|
||||
- **Każda tura dotykająca KB** → notatka w `workload/` (Reguła D)
|
||||
|
|
@ -570,7 +573,9 @@ w tym folderze. Zapisane rozmowy pozostają poza wyszukiwaniem: na pytania
|
|||
agent nadal odpowiada wyłącznie z wiki. Możesz natomiast pytać o same
|
||||
rozmowy („czy rozmawialiśmy o X", „co ci mówiłem o Y") i dostać zacytowaną
|
||||
dokładną wymianę zdań. Aby przenieść rozmowę do wiki, skopiuj jej `.md` do
|
||||
`raw/inbox/` i powiedz „Ingest". Skill:
|
||||
`raw/inbox/` i powiedz „Ingest". Powiedz „save conversations automatically",
|
||||
aby przełączyć `conversations.autosave` w `ckb.yaml` - od tej pory każda
|
||||
sesja jest zapisywana na końcu bez pytania. Skill:
|
||||
`.agents/skills/ckb-add-conversation/SKILL.md`.
|
||||
|
||||
### Tryb quizu (na żądanie)
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.12.0
|
||||
1.13.0
|
||||
|
|
|
|||
6
ckb.yaml
6
ckb.yaml
|
|
@ -1,8 +1,12 @@
|
|||
# Cascade KB manifest — repo-level configuration, not the wiki's content contract
|
||||
# (kb_schema_version stays in wiki/index.md). Written by ckb-init, read by
|
||||
# ckb-upgrade (template:) and ckb-module (kb_modules:).
|
||||
# ckb-upgrade (template:), ckb-module (kb_modules:) and ckb-add-conversation
|
||||
# (conversations:).
|
||||
template:
|
||||
repo: https://git.wierzbowa.cloud/michal/ckb.git
|
||||
branch: main # main | test | experimental
|
||||
|
||||
kb_modules: []
|
||||
|
||||
conversations:
|
||||
autosave: false # true: save every session's transcript at session end without asking
|
||||
|
|
|
|||
|
|
@ -284,7 +284,8 @@ docs. Independent of the content schema above.
|
|||
|
||||
| Version | Date | What landed | Schema |
|
||||
|---|---|---|---|
|
||||
| **1.12.0** | 2026-10-16 | `ckb-add-conversation`: on request, copies the session's Claude Code transcript (JSONL, byte for byte) into `raw/saved-conversations/<date>/` with a readable `.md` rendering and an `index.md`; answers "did we discuss X" / "what did I tell you about Y" from those files. Saved conversations are outside retrieval and outside ingest until the user copies one into `raw/inbox/`. Rule E asks once at session end whether to save; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (tier 3) and `ckb-init` know the folder; smoke test renders a fixture transcript | 1.5 |
|
||||
| **1.13.0** | 2026-10-16 | Conversation autosave switch: `conversations.autosave` in `ckb.yaml` (default `false`). On, Rule E saves every session at its end without asking; `ckb-add-conversation` toggles it on request ("save conversations automatically"). Per-machine half: `autosave_hook.py --check/--install/--remove` manages a Claude Code `Stop` hook in gitignored `.claude/settings.local.json`; Rule E runs the check at session start when autosave is on and asks before changing machine configuration; `save_conversation.py --from-hook` takes the transcript path from hook stdin. `ckb-init` writes the block, `ckb-upgrade` leaves it alone | 1.5 |
|
||||
| 1.12.0 | 2026-10-16 | `ckb-add-conversation`: on request, copies the session's Claude Code transcript (JSONL, byte for byte) into `raw/saved-conversations/<date>/` with a readable `.md` rendering and an `index.md`; answers "did we discuss X" / "what did I tell you about Y" from those files. Saved conversations are outside retrieval and outside ingest until the user copies one into `raw/inbox/`. Rule E asks once at session end whether to save; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (tier 3) and `ckb-init` know the folder; smoke test renders a fixture transcript | 1.5 |
|
||||
| 1.11.1 | 2026-10-09 | Five defects fixed, all reported by a downstream KB. `retrieve_candidates.py`: `load_pages` walks sorted, so a golden expectation no longer encodes one machine's directory order (the smoke test failed on a clean clone); a source cited by N pages now corroborates all N instead of whichever page was walked first. `lint_report.py` check 12: a cited directory is legal and unfingerprinted, no longer reported as missing (same fix in `lint_quick.sh`/`.ps1`). Check 8: a root-log `POINTER` is no longer read as a duplicate of the decisions-log entry it points at. Check 13: a quote attributed to a conversation or a person counts as attributed, not unattributed. `AGENTS.md` §2 documents directory citations and the two attribution shapes; fixture KB covers all three lint regressions | 1.5 |
|
||||
| 1.11.0 | 2026-09-29 | Python made optional where it can be: `<python>` interpreter resolution (`python3`/`python`/`py -3`) in `AGENTS.md`; per-OS install guide in the manual; `lint_quick.sh`/`.ps1` fallback for the session-start check (smoke-tested against `--quick`); manual lint checklist and no-script retrieval path; exporters state Python as a hard requirement; inline `python3 -c` dropped from `ckb-upgrade`/`ckb-reset`; D-0003. Lint check 13 matches each Crux block only against the source attributed under it (multi-source Crux no longer cross-fails; wrapped quotes matched as one block); fixture KB gains a second source | 1.5 |
|
||||
| 1.10.0 | 2026-09-24 | Skill descriptions and bodies slimmed (edge cases → `references/`); `retrieve_candidates.py` takes over rank fusion; docs moved to `docs/`, template ADRs restored to `docs/decisions/`; `tests/` fixture + `smoke.sh`; `ckb.yaml` shipped; Rule B names the decisions-log exception; scaffold `overview.md` describes content, not schema; "Sync the wiki" trigger dropped | 1.5 |
|
||||
|
|
|
|||
|
|
@ -291,7 +291,10 @@ Niezależna od schematu treści powyżej.
|
|||
|
||||
| Wersja | Data | Co weszło | Schemat |
|
||||
|---|---|---|---|
|
||||
| **1.11.0** | 2026-09-29 | Python opcjonalny tam, gdzie to możliwe: wybór interpretera `<python>` (`python3`/`python`/`py -3`) w `AGENTS.md`; instrukcja instalacji per system w podręczniku; zapasowe `lint_quick.sh`/`.ps1` dla kontroli na starcie sesji (testowane smoke wobec `--quick`); ręczna lista kontrolna lintu i ścieżka wyszukiwania bez skryptu; eksporty deklarują Pythona jako wymóg twardy; usunięte wbudowane `python3 -c` z `ckb-upgrade`/`ckb-reset`; D-0003. Kontrola lintu 13 porównuje każdy blok Crux tylko ze źródłem przypisanym pod nim (Crux z wielu źródeł już nie daje fałszywych wyników; cytaty łamane na kilka linii sprawdzane jako jeden blok); KB testowy zyskuje drugie źródło | 1.5 |
|
||||
| **1.13.0** | 2026-10-16 | Przełącznik autozapisu rozmów: `conversations.autosave` w `ckb.yaml` (domyślnie `false`). Po włączeniu Reguła E zapisuje każdą sesję na jej końcu bez pytania; `ckb-add-conversation` przełącza go na żądanie („save conversations automatically”). Połowa per maszyna: `autosave_hook.py --check/--install/--remove` zarządza hookiem `Stop` Claude Code w ignorowanym przez gita `.claude/settings.local.json`; Reguła E uruchamia kontrolę na starcie sesji przy włączonym autozapisie i pyta przed zmianą konfiguracji maszyny; `save_conversation.py --from-hook` bierze ścieżkę transkryptu ze stdin hooka. `ckb-init` zapisuje blok, `ckb-upgrade` go nie rusza | 1.5 |
|
||||
| 1.12.0 | 2026-10-16 | `ckb-add-conversation`: na żądanie kopiuje transkrypt sesji Claude Code (JSONL, bajt w bajt) do `raw/saved-conversations/<data>/` wraz z czytelną wersją `.md` i `index.md`; odpowiada na „did we discuss X” / „what did I tell you about Y” z tych plików. Zapisane rozmowy są poza wyszukiwaniem i poza ingestem, dopóki użytkownik nie skopiuje jednej do `raw/inbox/`. Reguła E pyta raz na końcu sesji, czy zapisać; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (poziom 3) i `ckb-init` znają ten folder; test smoke renderuje transkrypt z fixture | 1.5 |
|
||||
| 1.11.1 | 2026-10-09 | Pięć usterek naprawionych, wszystkie zgłoszone przez KB pochodną. `retrieve_candidates.py`: `load_pages` przechodzi katalogi w kolejności posortowanej, więc oczekiwany wynik testu nie koduje już kolejności katalogów jednej maszyny (test smoke nie przechodził na czystym klonie); źródło cytowane przez N stron potwierdza teraz wszystkie N, a nie tylko pierwszą napotkaną. `lint_report.py` kontrola 12: cytowany katalog jest legalny i bez skrótu, nie jest już zgłaszany jako brakujący (ta sama poprawka w `lint_quick.sh`/`.ps1`). Kontrola 8: `POINTER` w dzienniku głównym nie jest już czytany jako duplikat wpisu dziennika decyzji, na który wskazuje. Kontrola 13: cytat przypisany do rozmowy lub osoby liczy się jako przypisany, nie jako nieprzypisany. `AGENTS.md` §2 dokumentuje cytowanie katalogów i dwie formy atrybucji; KB testowy pokrywa wszystkie trzy regresje lintu | 1.5 |
|
||||
| 1.11.0 | 2026-09-29 | Python opcjonalny tam, gdzie to możliwe: wybór interpretera `<python>` (`python3`/`python`/`py -3`) w `AGENTS.md`; instrukcja instalacji per system w podręczniku; zapasowe `lint_quick.sh`/`.ps1` dla kontroli na starcie sesji (testowane smoke wobec `--quick`); ręczna lista kontrolna lintu i ścieżka wyszukiwania bez skryptu; eksporty deklarują Pythona jako wymóg twardy; usunięte wbudowane `python3 -c` z `ckb-upgrade`/`ckb-reset`; D-0003. Kontrola lintu 13 porównuje każdy blok Crux tylko ze źródłem przypisanym pod nim (Crux z wielu źródeł już nie daje fałszywych wyników; cytaty łamane na kilka linii sprawdzane jako jeden blok); KB testowy zyskuje drugie źródło | 1.5 |
|
||||
| 1.10.0 | 2026-09-24 | Odchudzone opisy i treści skilli (przypadki brzegowe → `references/`); `retrieve_candidates.py` przejmuje fuzję rankingów; dokumentacja przeniesiona do `docs/`, ADR-y szablonu przywrócone w `docs/decisions/`; fixture `tests/` + `smoke.sh`; dołączony `ckb.yaml`; Reguła B nazywa wyjątek dziennika decyzji; szkieletowy `overview.md` opisuje treść, nie schemat; usunięty wyzwalacz „Sync the wiki” | 1.5 |
|
||||
| 1.9.0 | 2026-09-22 | Kanały wydawnicze: gałęzie `main`/`test`/`experimental`, świadome gałęzi `ckb-init` i `ckb-upgrade`, blok `template:` w `ckb.yaml` | 1.5 |
|
||||
| 1.8.0 | 2026-09-21 | Siedem pomysłów zaadaptowanych z Graftu: crux/notes/skróty źródeł, tryb `--quick` lintu, ranking po stopniu wejściowym, promień rażenia w ingeście, dokończony słownik krawędzi | → 1.5 |
|
||||
|
|
|
|||
|
|
@ -696,6 +696,20 @@ I tell you about naming last week", "what did I ask you to do about the
|
|||
export". The agent searches the saved `.md` files and quotes the exact
|
||||
exchange, with the date.
|
||||
|
||||
If you would rather not be asked, say "save conversations automatically":
|
||||
the agent flips `autosave: true` under `conversations:` in `ckb.yaml`, and
|
||||
from then on every session is saved at its end without a question. "Turn
|
||||
off autosave" flips it back. The switch is committed with the repo, so it
|
||||
applies to everyone working in that KB. Because it is a rule the agent
|
||||
follows at session end, a session that is killed mid-turn would be missed -
|
||||
so the feature has a per-machine half: a Claude Code `Stop` hook in
|
||||
`.claude/settings.local.json` (gitignored) that re-saves the transcript
|
||||
after every turn. The agent never installs it on its own. When autosave is
|
||||
on, the session-start check notices a machine where the hook is missing (or
|
||||
one where autosave was turned off but the hook is still there) and asks
|
||||
once whether to change that machine's configuration; it applies the change
|
||||
only if you say yes. Each machine that opens the repo gets asked once.
|
||||
|
||||
If a conversation holds knowledge that belongs in the wiki, copy its `.md`
|
||||
into `raw/inbox/` and say "Ingest" - the copy is yours to make, so nothing
|
||||
enters the wiki without you choosing it. Note that a transcript is
|
||||
|
|
@ -865,6 +879,7 @@ scripts' output.
|
|||
| "Reset the wiki" / "Make this a clean template" | **Destructive.** Deletes accumulated knowledge and restores the empty scaffold, after an inventory and a typed confirmation | `ckb-reset` |
|
||||
| "Sync changes" / "Sync with git" | Commits, pulls, resolves conflicts, pushes to `origin` | `ckb-sync-changes` |
|
||||
| "Save this conversation" | Copies the session transcript (JSONL + readable `.md`) into `raw/saved-conversations/<date>/`; outside retrieval | `ckb-add-conversation` |
|
||||
| "Save conversations automatically" / "Turn off autosave" | Flips `conversations.autosave` in `ckb.yaml`; on, every session is saved at its end without asking | `ckb-add-conversation` |
|
||||
| "Did we discuss X" / "What did I tell you about X" | Searches saved conversations and quotes the exchange | `ckb-add-conversation` |
|
||||
| "Quiz me on X" | One-off scored knowledge test | `ckb-quiz` |
|
||||
| "Teach me the wiki" / "Teach me about X" | Plans and runs a spaced-out course with progress tracking | `ckb-teach-me` |
|
||||
|
|
|
|||
|
|
@ -457,6 +457,9 @@ Agent przypomina o tym również sam, automatycznie: na początku i na końcu
|
|||
sesji pracy wykonuje szybkie, tylko-do-odczytu sprawdzenie, czy jest coś
|
||||
niezacommitowanego lub niewypchniętego, i informuje, czy warto uruchomić
|
||||
„sync changes” — nigdy nie wypycha zmian samodzielnie, bez twojej prośby.
|
||||
W tym samym duchu na końcu sesji, w której wykonano realną pracę, pyta raz,
|
||||
czy zapisać rozmowę (zob. „Zapisywanie rozmowy” w Przykładach użycia) — i
|
||||
zapisuje tylko wtedy, gdy się zgodzisz.
|
||||
|
||||
### Budowanie współdzielonej kaskady (synchronizacja na poziomie KB)
|
||||
|
||||
|
|
@ -707,6 +710,46 @@ W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał d
|
|||
`raw/inbox/` i powiedz „Ingest”, albo po prostu powiedz agentowi w
|
||||
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
|
||||
|
||||
### Zapisywanie rozmowy
|
||||
|
||||
Powiedz „save this conversation”, a agent skopiuje transkrypt sesji do
|
||||
`raw/saved-conversations/<RRRR-MM-DD>/` — oryginalny plik JSONL, który
|
||||
przechowuje Claude Code, bajt w bajt, plus czytelną wersję `.md` tej samej
|
||||
wymiany zdań (twoje wiadomości i odpowiedzi agenta dosłownie, wywołania
|
||||
narzędzi jako jednolinijkowe notatki, wyniki narzędzi skrócone, prywatne
|
||||
rozumowanie agenta pominięte). `raw/saved-conversations/index.md` wymienia
|
||||
wszystko, co zapisano. Wcześniejsze sesje tego samego projektu też można
|
||||
zapisać: poproś, a agent wyświetli listę do wyboru.
|
||||
|
||||
Zapisane rozmowy są celowo **poza** wiki. Na pytania agent nadal odpowiada
|
||||
wyłącznie z `wiki/`, `linked/` i `libs/` — transkrypt sam z siebie nigdy
|
||||
nie staje się dowodem. Możesz natomiast pytać o same rozmowy: „czy
|
||||
rozmawialiśmy o przełączeniu rozliczeń”, „co ci mówiłem o nazewnictwie w
|
||||
zeszłym tygodniu”, „o co cię prosiłem w sprawie eksportu”. Agent przeszukuje
|
||||
zapisane pliki `.md` i cytuje dokładną wymianę zdań wraz z datą.
|
||||
|
||||
Jeśli wolisz nie być pytany, powiedz „save conversations automatically”:
|
||||
agent przestawi `autosave: true` w bloku `conversations:` w `ckb.yaml` i od
|
||||
tej pory każda sesja jest zapisywana na końcu bez pytania. „Turn off
|
||||
autosave” przestawia z powrotem. Przełącznik jest commitowany z
|
||||
repozytorium, więc dotyczy wszystkich pracujących w tej KB. Ponieważ jest to
|
||||
reguła, którą agent wykonuje na końcu sesji, sesja przerwana w połowie tury
|
||||
zostałaby pominięta — dlatego funkcja ma też połowę per maszyna: hook
|
||||
`Stop` Claude Code w `.claude/settings.local.json` (ignorowanym przez gita),
|
||||
który ponownie zapisuje transkrypt po każdej turze. Agent nigdy nie
|
||||
instaluje go samodzielnie. Przy włączonym autozapisie kontrola na starcie
|
||||
sesji zauważa maszynę, na której hooka brakuje (albo taką, na której
|
||||
autozapis wyłączono, a hook wciąż jest), i pyta raz, czy zmienić
|
||||
konfigurację tej maszyny; zmianę wprowadza tylko po twojej zgodzie. Każda
|
||||
maszyna otwierająca repozytorium zostaje zapytana raz.
|
||||
|
||||
Jeśli rozmowa zawiera wiedzę, która należy do wiki, skopiuj jej `.md` do
|
||||
`raw/inbox/` i powiedz „Ingest” — kopię robisz ty, więc nic nie trafia do
|
||||
wiki bez twojego wyboru. Pamiętaj, że transkrypt jest dosłowny: zawiera
|
||||
wszystko, co agent wypisał w trakcie sesji (zawartość plików, wyniki
|
||||
poleceń), i staje się śledzonym plikiem w repozytorium.
|
||||
Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
|
||||
|
||||
### Indeksowanie zewnętrznego źródła
|
||||
|
||||
Powiedz:
|
||||
|
|
@ -875,6 +918,9 @@ lub `main`; z `--update` po zamierzonej zmianie wyjścia skryptów.
|
|||
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |
|
||||
| „Zresetuj wiki” / „Zrób z tego czysty szablon” | **Destrukcyjne.** Usuwa zgromadzoną wiedzę i odtwarza pusty szkielet, po inwentarzu i potwierdzeniu wpisaną frazą | `ckb-reset` |
|
||||
| „Sync changes” / „Sync with git” | Commituje, pobiera, rozwiązuje konflikty, wypycha do `origin` | `ckb-sync-changes` |
|
||||
| „Save this conversation” | Kopiuje transkrypt sesji (JSONL + czytelne `.md`) do `raw/saved-conversations/<data>/`; poza wyszukiwaniem | `ckb-add-conversation` |
|
||||
| „Did we discuss X” / „What did I tell you about X” | Przeszukuje zapisane rozmowy i cytuje wymianę zdań | `ckb-add-conversation` |
|
||||
| „Save conversations automatically” / „Turn off autosave” | Przestawia `conversations.autosave` w `ckb.yaml`; po włączeniu każda sesja jest zapisywana na końcu bez pytania | `ckb-add-conversation` |
|
||||
| „Quiz me on X” | Jednorazowy, punktowany sprawdzian wiedzy | `ckb-quiz` |
|
||||
| „Teach me the wiki” / „Teach me about X” | Planuje i prowadzi rozłożony w czasie kurs ze śledzeniem postępu | `ckb-teach-me` |
|
||||
| „Onboard me on X” / „Where do I start with X” | Krótka, prowadzona kolejność czytania po grafie | `ckb-onboard-me` |
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue