ckb/.agents/skills/ckb-init/SKILL.md

---
name: ckb-init
description: Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, full default skill set, LICENSE/VERSION, and empty wiki/ scaffold as this project - inside a target folder, sourcing the template either from this repo's own files or by pulling a fresh clone of the canonical ckb repo (or a user-supplied fork/mirror URL) into a scratch folder, so it works even when run outside an existing KB. The target folder is typically empty, or a new project that doesn't have a KB yet. Use when the user asks to "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", "create a knowledge base with this schema", "pull the ckb repo into this folder", "clone the wiki template into <dir>", or calls it a "wiki initializer". Also use when they name a release channel or branch to bootstrap from - "initialize from the test branch", "set up a dev KB from experimental", "bootstrap from <url> branch <name>" - since the template repo keeps main (stable), test (release candidate) and experimental (development) branches, and main is the default. Do not confuse with a generic `init` skill that documents an existing codebase - this one creates the Cascade KB pattern itself, empty, ready for its first ingest. Distinct from `ckb-upgrade`, which catches an *existing* populated KB up with template changes rather than bootstrapping a new one.
---

# Cascade KB init skill

## Purpose

Copy the Cascade Knowledge Base *schema* - not its content - into a new
target folder: the directory structure, the `AGENTS.md`/`CLAUDE.md`
system prompt that defines how the KB behaves, the full default skill set,
`LICENSE` and `VERSION`, the generic `README`/`MANUAL` docs, and the empty
`wiki/` scaffold (routing table, overview, log, error book, entity/graph
indexes). The result is a new, empty KB that behaves exactly like this one,
ready for its first `raw/inbox/` drop and "Ingest."

The template it copies from is either this repo's own files or 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, not
only from inside an existing KB, and what "pull the repo into a folder to
set up a wiki" means in practice. Either way it is a one-way copy into a
different folder, and the clone is scratch: it never becomes the new KB's
`.git/`.

It never reads or writes anything in the template source's `raw/`,
`wiki/entities/`, `wiki/graph/edges.json`, or `outputs/` - those hold that
project's actual accumulated knowledge, which is exactly what should *not*
travel into a fresh KB. (For catching an *already-populated* KB up with
newer template files without losing its accumulated content, see
`ckb-upgrade` instead - that skill does the same source-of-truth copying
this one does, but merges it into an existing KB rather than a blank
folder.)

## Trigger phrases

- "set up a new wiki like this one" / "initialize a new cascade KB"
- "bootstrap a wiki here" / "create a knowledge base with this schema"
- "wiki initializer" / "clone this KB structure into a new project"
- "pull the ckb repo into `<dir>` and set up the wiki structure"
- "initialize a KB from `<url>`" / "get the latest template and bootstrap a KB"

## 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/MANUAL 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:

```bash
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:

```bash
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-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.

### Step 6 - Write `AGENTS.md` and the `CLAUDE.md` symlink

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.
- `MANUAL.md` and `MANUAL.pl.md` - the task-oriented user guide.
- `CHANGELOG.md` and `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.

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:

```yaml
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). A fresh KB has no modules, so at init time the file holds the
`template:` block alone.

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:

```bash
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

- **Target is the current repo itself, or a parent/ancestor of it** - refuse
  and explain why: this would either overwrite the live KB you're running
  from, or nest a KB inside itself. Ask for a genuinely separate path.
- **Target is on a different filesystem/drive or requires elevated
  permissions** - if directory creation fails, report the exact error
  rather than retrying with escalated permissions.
- **User wants only *some* of the wiki template files** (e.g. just the
  directory structure, no `AGENTS.md`) - honor that; the steps above are
  the default full scaffold, not an all-or-nothing bundle.
- **Clone fails and there's no local KB to fall back on** - stop and report
  the raw git error. Don't hand-write an approximation of the scaffold from
  memory; a KB whose `AGENTS.md` is a paraphrase is worse than no KB.
- **User asks to clone the template repo straight into the target** - point
  out that this gives them the template's git history and files rather than
  a fresh KB, and offer both: a plain `git clone` (if that's really what
  they want) or the scratch-clone-then-init flow, which is the default.
- **Target already contains a `.git/`** - proceed with the scaffold, but
  skip Step 11's `git init`/commit and say so; committing into someone
  else's repo is theirs to decide.
- **Scratch clone path already exists** (a previous run died mid-way) -
  remove it before cloning (`rm -rf`), and remove it again when done. Never
  reuse a half-cloned scratch dir.
- **This repo's own `AGENTS.md` or template `wiki/` files have since
  drifted from each other** (e.g. one mentions a directory the other
  doesn't) - fix the drift in *this* repo first if noticed, then copy the
  corrected version. Don't propagate a known inconsistency into a new KB.

---

*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*