ckb/.agents/skills/ckb-init/SKILL.md
Michał Kopeć 29bb631b27 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>
2026-10-16 09:38:35 +02:00

20 KiB

name description
ckb-init Bootstrap a brand-new, empty Cascade Knowledge Base in a target folder — directory structure, AGENTS.md/CLAUDE.md, the default skill set, LICENSE/VERSION, docs, and an empty wiki/ scaffold — sourcing the template from this repo or from a fresh clone of the canonical ckb repo, so it works from outside an existing KB. Use for "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", or "clone the wiki template into <dir>".

Cascade KB init skill

Purpose

Copy the Cascade KB schema — not its content — into a new target folder: the directory structure, the AGENTS.md/CLAUDE.md system prompt, the default skill set, LICENSE and VERSION, the generic docs, and the empty wiki/ scaffold. The result is a new, empty KB that behaves exactly like this one, ready for its first raw/inbox/ drop and "Ingest."

The template comes either from this repo's own files or from a fresh shallow clone of the canonical template repo pulled into a scratch folder (Step 3) — the latter is what makes this skill usable from anywhere. Either way it is a one-way copy, and the clone is scratch: it never becomes the new KB's .git/.

Never reads or writes the template source's raw/, wiki/entities/, wiki/graph/edges.json, or outputs/ — that is accumulated knowledge, which is exactly what should not travel into a fresh KB. To catch an already-populated KB up with newer template files, use ckb-upgrade instead.

How to run this skill

Step 1 - Confirm the target folder

Ask (if not already given): "Which folder should I initialize the new knowledge base in?" Resolve to an absolute path. This is a filesystem action outside the current repo, so confirm the resolved path back to the user before writing anything - do not assume a relative path means "somewhere under the current project."

If the folder doesn't exist yet, create it after confirming the path. If it exists, check its contents before doing anything else (Step 2).

Step 2 - Don't clobber an existing KB or unrelated project

If the target already contains a wiki/ directory, or an AGENTS.md / CLAUDE.md, stop and ask: "This folder already looks like it has a knowledge base (found <what>). Initializing here could overwrite it. Do you want to proceed anyway, pick a different folder, or only add whatever scaffold pieces are missing?" Never silently overwrite an existing AGENTS.md or populated wiki/ tree.

If the target has other, unrelated files (e.g. it's an existing code project without a KB yet) - that's fine, proceed; the scaffold is added alongside them. Note any top-level name collisions (e.g. an existing wiki/ folder used for something else) and ask before touching those specifically.

Step 3 - Resolve the template source

Everything this skill copies (AGENTS.md, LICENSE, VERSION, the README, docs/, .gitignore, the wiki/ scaffold, the skill set) comes from one template source. There are two, and they produce the same result:

a) A fresh clone of the canonical template repo (default when this skill runs outside a Cascade KB, and always available). Pull the repo into a scratch folder and copy out of it:

rm -rf <scratch>
git clone --depth 1 --branch <branch> https://git.wierzbowa.cloud/michal/ckb.git <scratch>

<scratch> is tmp/ckb-init-src under the current KB when this skill runs inside one (matching ckb-upgrade's convention - that directory is already gitignored), or a system temp path such as /tmp/ckb-init-src when it doesn't.

Use a user-supplied URL instead if they named one ("initialize from <url>") - a fork or an internal mirror is a legitimate template source.

Which branch (the release channel)

The canonical repo keeps three branches, and they are not interchangeable:

Branch What it is Use it when
main Stable. The released template. Always, unless the user says otherwise. This is the default.
test Release candidate. Changes validated before they reach main. The user is helping validate a release, or needs a fix that has landed but not shipped.
experimental Development. Active work; may be broken, may be reverted. The user is developing the template itself, or explicitly wants the newest ideas and accepts the risk.

Default to main. Take a different branch only when the user asks for one, in whatever words: "initialize from the test branch", "use experimental", "set up a dev KB", "bootstrap from <url> branch <name>", "I want the bleeding edge". A fork's branch works the same way - --branch takes any ref the source repo has.

If the user names a branch that does not exist on the source repo, the clone fails with git's own error. Report it and list what does exist (git ls-remote --heads <url>) rather than silently falling back to main: a KB quietly initialized from the wrong channel is exactly the kind of thing nobody notices until an upgrade behaves strangely.

When initializing from test or experimental, say so plainly in the Step 12 report and explain what it means - that this KB will keep pulling from that channel until someone changes it, and that experimental in particular carries no stability promise. Initializing onto a dev channel is a reasonable thing to want; doing it without realizing is not. If git isn't available or the clone fails (network, auth, unreachable host), report the raw error; fall back to (b) if this skill is running inside a Cascade KB, otherwise stop - there is nothing to copy from.

Clone into a scratch path outside the target folder, never into the target itself. Cloning straight into the target would drag the template's own git history, .git/, workload/, and any committed sample content into the new KB; the new KB gets its own history in Step 11 instead. The one exception is if the user explicitly says they want the template repo itself checked out in place (i.e. "just clone ckb into <dir>") - that's a plain git clone, not an init; do that, say so plainly, and skip the rest of these steps.

b) This repo's own working tree (default when this skill runs from inside a Cascade KB and the user hasn't asked for a fresh pull). Copy directly from the current repo's files, exactly as described in the steps below. This is the faster path and is what you want when the current KB is itself the template being propagated - but it copies whatever local, possibly uncommitted, template edits exist here. If the user says "pull the latest", "from the remote", or "from upstream", use (a) instead.

If both are viable and the user hasn't indicated a preference, ask which one - a stale local template and an upstream one that moved are a real difference, not a formality.

For the rest of this skill, "this repo's <path>" means "<path> in the resolved template source" - the steps are identical either way. Note the source (URL + short commit hash, or "local working tree") for the Step 12 report, and delete the scratch clone once Step 10 has finished copying:

rm -rf <scratch>

Step 4 - Default skill set (no need to ask)

The bare scaffold (directory structure + AGENTS.md/CLAUDE.md + empty wiki/ templates) is always included, and so is the full reusable KB skill set - these operate purely on the wiki/ structure (or, for ckb-init and ckb-upgrade themselves, on the schema layer), so they carry over cleanly and are part of "the schema" as far as this skill is concerned. As of this writing, that's every skill under the template source's .agents/skills/:

  • ckb-init (this skill - a new KB can bootstrap further KBs of its own)
  • ckb-upgrade (lets the new KB catch up with template changes later)
  • ckb-ingest
  • ckb-decide
  • ckb-retrieve
  • ckb-index-external
  • ckb-lint
  • ckb-sync-changes
  • ckb-add-conversation
  • ckb-project-summary
  • ckb-export-okf
  • ckb-export-starlight
  • ckb-onboard-me
  • ckb-teach-me
  • ckb-quiz

Don't ask about any of these - just include them.

If, at the time this skill runs, .agents/skills/ also contains skills not in the list above, they're either a newer schema-native addition this document hasn't been updated to mention yet (safe to fold into the default set the same way - they follow the same "operates purely on the KB structure" test) or a project-specific/general-purpose skill someone added for this project only (e.g. a brand-specific export tool or a general writing aid, unrelated to the Cascade KB pattern itself) - in that case, only include it if the user explicitly asks for it by name, e.g. "also bring over <skill-name>."

Record the final skill list (the defaults above, plus anything explicitly added) - this affects Steps 9 and 10.

Step 5 - Create the directory structure

Under the target folder, create:

libs/
linked/
outputs/
raw/inbox/
raw/archive/
tmp/
wiki/entities/
wiki/graph/
wiki/projects/
wiki/decisions/
workload/

Git doesn't track empty directories, so every one of these - plus .agents/, .agents/skills/, and .claude/ created in Step 10 - needs a placeholder to survive a fresh git init and first commit. This repo's own convention is an empty file named .gitadd in each directory (not .gitkeep) - match that convention exactly, so a new KB's directory listing looks identical to this one's.

libs/ and tmp/ are gitignored per the schema (Step 9) except for their own .gitadd placeholder, so they stay effectively empty. linked/ gets a .gitadd too but is not gitignored - it's meant to hold real symlinks, which git tracks natively (as a small blob storing the link target), so nothing extra is needed there. raw/inbox/, raw/archive/, and workload/ are meant to be tracked and start genuinely empty aside from their placeholder.

Copy this repo's AGENTS.md verbatim into the target as AGENTS.md - it is already fully generic (no project-specific content; it is the schema definition). Then create CLAUDE.md in the target as a symlink to AGENTS.md, matching this repo's own convention (one source of truth, readable under either filename).

Step 7 - Write LICENSE, VERSION, and the generic docs

Copy these verbatim from this repo - they're already fully generic (no project-specific content, confirmed by having zero references to any actual project entity):

  • README.md and README.pl.md - the technical feature overview, including the "source repo" pointer at the top. Leave that pointer as-is (pointing at this template's own canonical repo) unless the user says the new KB should point somewhere else - it's what lets the new KB's own ckb-upgrade find template updates later.
  • docs/MANUAL.md and docs/MANUAL.pl.md - the task-oriented user guide; docs/OPENSPEC*.md - the software-module guide; docs/decisions/ - the template's own design records (D-0001, D-0002), which skills cite.
  • docs/CHANGELOG.md and docs/CHANGELOG.pl.md - the full page schema reference plus the schema and template version histories. Copy verbatim: the history belongs to the template, not to the new KB, and a fresh KB starts on the version that history ends at.
  • VERSION - copy the exact current value; the new KB starts life on the same template version it was just cloned from.
  • tests/ - the fixture KB, golden files and smoke.sh, copied wholesale so the new KB can verify its own template layer after an upgrade.

Then write ckb.yaml at the new KB's root, recording where its tooling came from so its own ckb-upgrade knows what to check later:

template:
  repo: https://git.wierzbowa.cloud/michal/ckb.git
  branch: main

Use the URL and branch actually resolved in Step 3 - the user's fork URL if they named one, test/experimental if they asked for that channel. Write this block even for the default main/canonical case: an explicit record is what makes a later channel switch visible, and it costs one file.

If the template source was this repo's own working tree (Step 3b) rather than a clone, record the canonical repo URL and the branch this repo is currently on (git rev-parse --abbrev-ref HEAD), since that is where the new KB's upgrades will actually come from. Where that branch is test or experimental, say so in the Step 12 report - propagating a dev channel into 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) 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 still effectively part of the same umbrella/organization) or update it to their own name/organization (appropriate if this is a genuinely separate project that will accumulate its own content under its own ownership) - don't silently carry over a copyright attribution that may not apply to what the new KB is about to collect.

Step 8 - Write the empty wiki/ scaffold

Create these files in the target, using this repo's current versions as the template and stripping every reference to this project's actual content (Grant Thornton, Cloud Drift, specific entities, etc.) down to the generic structure:

  • wiki/index.md - frontmatter with kb_schema_version only, set to whatever value the template source's own wiki/index.md carries (do not hard-code it here - it moves with the schema). Body: the routing table with just its four fixed infrastructure rows (Overview, Log, Error Book, Entities, Graph) and no entity rows, plus the "## Entity Pages" section with its placeholder note. Use today's date where the template needs one.
  • wiki/overview.md - copy verbatim from this repo (it's already generic - directory tree, cascade priority, frontmatter summary, no project content). Set last_updated to today.
  • wiki/log.md - header and explanation only, no entries.
  • wiki/error-book.md - copy verbatim (already generic: empty table
    • placeholder note). Set last_updated to today.
  • wiki/entities/index.md - header + placeholder note, no entries.
  • wiki/graph/index.md - header + pointer to edges.json, the edge vocabulary table and its conventions verbatim (ckb-ingest, ckb-decide, ckb-index-external, and ckb-lint all write against that closed set, so it is contract, not example content), and a generic "(No edges recorded yet)" placeholder instead of any real coverage line.
  • wiki/graph/edges.json - {"version": 1, "last_updated": "<today>", "edges": []}.
  • wiki/projects/index.md - header + placeholder note, no project scopes yet.
  • wiki/decisions/index.md - header, the status-vocabulary table, and a placeholder note; no decisions yet. Copy the status vocabulary verbatim — ckb-decide and ckb-lint both validate against it.
  • wiki/decisions/log.md - header and explanation only, no entries.
  • wiki/query-gaps.md - header + explanation only, no recorded gaps.

If the template source's wiki/ holds scaffold files beyond this list, carry them over the same way - empty, structure only. The list above is what the schema requires, not a cap.

Do not carry over any entity pages, graph edges, log entries, or overview content specific to this project - the whole point is an empty KB with the same shape.

Step 9 - Write .gitignore

Copy this repo's actual current .gitignore verbatim rather than reconstructing it from memory - it uses a <dir>/* + !<dir>/.gitadd pairing (not a bare <dir>/ line) for directories that should exist as a tracked shell but have their real contents ignored:

libs/*
!libs/.gitadd
!libs/*/
libs/*/*
!libs/*/source.yaml
!libs/*/index.md
!libs/*/log.md
!libs/*/entities/
!libs/*/graph/
# Per-user local override (e.g. source.local.yaml's access: write) — never shared, stays ignored
# by the libs/*/* catch-all above; listed explicitly for clarity, not because it changes behavior.
libs/*/*.local.yaml
tmp/*
!tmp/.gitadd
outputs/starlight
outputs/okf
outputs/teaching
.env

(That libs/ block is what keeps a connector-backed lib's source.yaml and its agent-generated index tracked while ignoring everything else under it - copy it as a unit. If the template source's .gitignore has since changed, its version wins over the snapshot above.)

Since ckb-export-starlight, ckb-export-okf, and ckb-teach-me are all in the default skill set (Step 4), their outputs/ subfolders (outputs/starlight, outputs/okf, outputs/teaching) are gitignored by default too - each exists to be ignored precisely because its skill is present by default. If a future skill set change ever drops one of those three skills from the default set, drop its matching ignore line too; if the user explicitly adds a skill with its own outputs/<x> convention, ask whether it needs a similar ignore line.

Step 10 - Copy the skill set from Step 4

Copy each skill's folder from this repo's .agents/skills/<name>/ into the target's .agents/skills/<name>/ unchanged (including each skill's own license footer, and any support files like ckb-export-okf/scripts/export_okf.py, ckb-export-starlight/scripts/export_starlight.py, ckb-lint/scripts/lint_report.py) - the full default set from Step 4, plus anything explicitly added. Then create .claude/skills in the target as a symlink to ../.agents/skills, matching this repo's convention - do this once, after copying the whole set, not per-skill.

Also copy .agents/modules/ wholesale. Modules are inert until installed, so a new KB carries the full catalogue at zero context cost, and the user can enable one later with ckb-module instead of re-deriving it. Do not install any module into the new KB, and do not create a ckb.yaml: an absent manifest correctly means "nothing installed". If the user has said the new KB is for software they are building, mention the software module and offer to install it after Step 11 — offer, don't assume.

Step 11 - Initialize the new KB's own git history (ask first)

The target is now a complete KB but has no history of its own - and if the template came from a clone (Step 3a), it deliberately carries none of the template's. Ask whether to initialize one:

git init
git add .
git commit -m "Initialize Cascade Knowledge Base from ckb template v<VERSION>"

Only do this if the target isn't already inside a git repo (git rev-parse --is-inside-work-tree from the target) - if it is, say so and leave the staging to the user rather than committing into someone else's repo. Don't add a remote and don't push; that's ckb-sync-changes' job once the user has a remote to point at.

Step 12 - Report

Tell the user:

  • The resolved target path.
  • The template source used: the clone URL, branch, and short commit hash, or "this repo's local working tree" and the branch it was on. Name the channel in words when it isn't main - "this KB tracks experimental, which carries no stability promise; say 'switch to the main channel' to change that."
  • That ckb.yaml records the repo and branch for future upgrades.
  • The directory tree created.
  • Whether AGENTS.md/CLAUDE.md were written or (per Step 2) skipped/merged.
  • Which skills were copied (the full default set, plus anything explicitly added).
  • The VERSION the new KB starts on, and what was decided for LICENSE's copyright line.
  • Whether a git repo was initialized in the target, or why not.
  • Next step: "Drop material into raw/inbox/ and say 'Ingest' to populate the wiki for the first time."

Edge cases

Unusual situations — an empty target, a partial run, a conflicting state, a missing dependency — are catalogued in references/edge-cases.md. Read that file when a run hits something the steps above don't cover; don't load it otherwise.