Sync: local changes as of 2026-11-12T07:13:05Z

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-11-12 08:13:05 +01:00
parent 56c0511ac7
commit a80c3d43a4
4 changed files with 394 additions and 0 deletions

View file

@ -98,6 +98,24 @@ If the target folder already looks like a KB (it has a `wiki/` or
`AGENTS.md` already), the agent stops and asks before touching anything. It
won't silently overwrite an existing knowledge base.
### Creating or joining a shared wiki from anywhere
Two skills are meant for your own agent profile (`~/.claude/skills/`), not
for a KB, so they work before any KB exists on your machine. Install them
once from [`user-skills/`](../user-skills/README.md):
- **`ckb-create`** - "Create a new wiki in `~/kb/team` with origin
`<url>`". Give it an *empty* repository on your git host. It fetches the
current template, builds the KB with that template's `ckb-init`, commits
on `main` and pushes, then gives you a line to forward to colleagues.
- **`ckb-join`** - "Join the knowledge base at `<url>`", optionally "into
`<folder>`". It clones the KB, checks it really is one, and tells you
what still needs fixing on your machine: git identity, symlinks on
Windows, `linked/` mounts that point at someone else's disk, Python.
Neither skill commits to an existing KB. After either one, open the folder
in your agent and carry on there.
### Building on top of someone else's wiki
A Cascade KB can sit on top of one or more *upstream* knowledge bases,

42
user-skills/README.md Normal file
View file

@ -0,0 +1,42 @@
# Profile skills
Skills a person installs **once in their own agent profile**, not inside a
knowledge base. They work from any folder, before any KB exists on the
machine. `ckb-init` and `ckb-upgrade` never copy this folder into a KB.
| Skill | What it does | Say |
|---|---|---|
| `ckb-create` | Creates a new KB in a folder and publishes it to an empty git remote, ready for colleagues | "Create a new wiki in `~/kb/team` with origin `<url>`" |
| `ckb-join` | Clones an existing KB from its origin URL, checks it works on this machine | "Join the knowledge base at `<url>`" (optionally "into `<folder>`") |
`ckb-create` holds no scaffold logic of its own: it fetches the template at
run time and follows that version's `ckb-init`. An old copy in a profile
therefore still builds a current KB.
## Install
Claude Code (macOS / Linux):
```bash
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git /tmp/ckb
mkdir -p ~/.claude/skills
cp -R /tmp/ckb/user-skills/ckb-create /tmp/ckb/user-skills/ckb-join ~/.claude/skills/
rm -rf /tmp/ckb
```
Windows (PowerShell):
```powershell
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git $env:TEMP\ckb
New-Item -ItemType Directory -Force $HOME\.claude\skills | Out-Null
Copy-Item -Recurse $env:TEMP\ckb\user-skills\ckb-create, $env:TEMP\ckb\user-skills\ckb-join $HOME\.claude\skills\
Remove-Item -Recurse -Force $env:TEMP\ckb
```
Other agents: copy the two folders into that agent's user-level skills
directory, or point it at the `SKILL.md` files.
To update, repeat the copy. To remove, delete the two folders.
If your profile also has an old `ckb-init` copy, you can remove it:
`ckb-init` belongs inside a KB, and `ckb-create` covers the from-anywhere case.

View file

@ -0,0 +1,181 @@
---
name: ckb-create
description: Create a brand-new shared Cascade Knowledge Base in a folder and publish it to an empty git remote, so colleagues can join it straight away — fetches the current template, scaffolds the KB with that template's own ckb-init, commits on `main`, adds the given URL as `origin` and pushes. Installed in a user's profile, so it works from any folder. Use for "create a new wiki in this folder with this origin", "start a shared knowledge base", "new KB for the team", "set up a wiki and push it to our git server". Not for a local-only scaffold with no remote (that is ckb-init inside a KB) or for joining a KB that already exists on the remote (that is ckb-join).
---
# Create a shared Cascade KB
## Purpose
One action from "I have an empty remote repo" to "the team can clone a
working KB". This skill lives in a person's profile (`~/.claude/skills/`),
not in any KB, so it never gets upgraded with the template. It therefore
holds **no scaffold knowledge of its own**: it fetches the template and
follows the `ckb-init` that ships with it, then does the publishing that
`ckb-init` deliberately leaves out.
Never pushes to a remote that already has commits, never force-pushes,
never creates the remote repository itself (that is the git host's job and
the user's permissions).
## How to run this skill
### Step 1 — Collect the three inputs
- **Target folder** — where the new KB lives on this machine. Resolve to an
absolute path and say it back before writing anything. A relative path is
relative to the current working directory, not to any KB.
- **Origin URL** — the remote repository, already created on the host
(GitHub, GitLab, Gitea, Azure DevOps…) and **empty**: no README, no
licence, no `.gitignore`. If the user has not created it yet, tell them
to, and to leave "initialise with README" unticked.
- **Template channel** (optional) — `main` unless the user names `test`,
`experimental`, or a fork/mirror URL. Same rules as `ckb-init`'s
"Which branch" table.
Ask only for what is missing, in one message.
### Step 2 — Pre-flight
Run these and stop on the first failure, reporting git's own error:
```bash
git --version
git config user.name; git config user.email
git ls-remote <origin-url>
```
- **No git identity** — every log entry and commit in a Cascade KB carries
the author, so a team KB needs one. Ask for name and email and set them
with `git config --global` only on a yes; otherwise stop.
- **`ls-remote` fails** — authentication or a wrong URL. Report the raw
error, suggest checking the URL and that the user can push to it
(SSH key, credential helper, personal access token). Don't guess a
corrected URL.
- **`ls-remote` prints any refs** — the remote is not empty. Stop: "That
remote already has history. If it is an existing KB, say *join the
knowledge base at `<url>`* instead; if it only has an auto-generated
README, delete the repo and recreate it empty, or tell me to proceed and
I'll stop before pushing." Never merge an unrelated history here.
- **Target folder** — apply `ckb-init`'s Step 2 rules (an existing `wiki/`
or `AGENTS.md` means stop and ask). Additionally, if the target is already
inside a git work tree (`git -C <target> rev-parse --is-inside-work-tree`),
stop: a shared KB needs its own repository, not a subfolder of another.
### Step 3 — Fetch the template
```bash
rm -rf <scratch>
git clone --depth 1 --branch <branch> <template-url> <scratch>
git -C <scratch> rev-parse --short HEAD
cat <scratch>/VERSION
```
`<template-url>` defaults to `https://git.wierzbowa.cloud/michal/ckb.git`.
`<scratch>` is a fresh temp directory outside the target (`mktemp -d`, or
the session scratchpad). Note the URL, branch, short hash and `VERSION` for
the report.
### Step 4 — Scaffold with the template's own `ckb-init`
Read `<scratch>/.agents/skills/ckb-init/SKILL.md` (and its
`references/edge-cases.md` if a case comes up) and follow it with:
- **template source** = the scratch clone (its Step 3a, already done — do
not clone again);
- **target** = the folder from Step 1 (its Steps 1–2 are already done);
- `ckb.yaml`'s `template:` block = the template URL and branch from Step 3.
Ask the questions `ckb-init` asks (the `ABOUT.md` purpose sentence, the
`LICENSE` copyright line). Those answers matter more for a shared KB, since
everyone will see them.
**Two overrides to `ckb-init`, because this KB is shared:**
- Its Step 11 is **not optional** and not "ask first": initialise the
repository on `main` — the branch `ckb-sync-changes` assumes:
```bash
git -C <target> init -b main
```
(On git older than 2.28: `git init` then `git symbolic-ref HEAD refs/heads/main`.)
- Its "don't add a remote and don't push" is replaced by Step 6 below.
If `ckb-init` in the fetched template differs from what this skill
expects (renamed steps, a new step), the fetched `ckb-init` wins: it is
the current contract, this skill is only the wrapper.
### Step 5 — First commit
```bash
cd <target>
test -L CLAUDE.md && test -L .claude/skills # both must be symlinks
git add .
git status --short | head -50 # show what goes in
git commit -m "Initialize Cascade Knowledge Base from ckb template v<VERSION>"
```
`git add .` is safe here and only here: the folder holds nothing but the
fresh scaffold, and its `.gitignore` is already in place. If `git status`
shows anything that is not scaffold (a stray `.env`, files that were in the
folder before), stop and ask before committing it. If either symlink check
fails, fix it before committing (`ln -s AGENTS.md CLAUDE.md`,
`ln -s ../.agents/skills .claude/skills`) — a team member who clones a KB
whose `CLAUDE.md` is a plain copy gets a stale system prompt.
### Step 6 — Publish
```bash
git remote add origin <origin-url>
git push -u origin main
git ls-remote origin refs/heads/main # must equal: git rev-parse HEAD
```
If the push is rejected, report the raw error and stop — the remote gained
history after Step 2, or the user lacks push rights. Never `--force`.
### Step 7 — Clean up and report
```bash
rm -rf <scratch>
```
Tell the user, briefly:
- the folder, the origin URL, and that `main` is pushed and tracking
`origin/main`;
- the template source (URL, branch, short hash, `VERSION`); name the channel
in words if it is not `main`;
- what they answered for `ABOUT.md` and `LICENSE`;
- **how colleagues join**, as a line they can forward:
> Install the `ckb-join` skill, then say: *join the knowledge base at
> `<origin-url>`*. Or by hand: `git clone <origin-url>` and open the
> folder in your agent.
- that they must grant those colleagues access on the git host — this
skill cannot;
- next step: open the folder in the agent (`cd <target> && claude`) so the
KB's own skills load, drop material into `raw/inbox/` and say *Ingest*;
"sync changes" shares the result.
## Edge cases
- **Remote has only a host-generated README/licence** — still "not empty".
Recreating the repo empty is cleaner than merging; offer that first. If
the user insists on keeping it, finish Steps 3–5, then hand over to the
new KB's own `ckb-sync-changes`, whose unrelated-histories path asks how
to merge.
- **Template clone fails** — report the raw error and stop. Don't fall back
to a stale `ckb-init` in the user's profile or to a scaffold from memory.
- **The user runs this from inside another KB** — fine; the target must
still be a separate folder outside it (`ckb-init`'s edge case on nesting
applies). The current KB's own rules (log, workload note) apply to the
current session as usual; nothing is written into the current KB.
- **Windows** — `ckb-init`'s symlinks need Developer Mode or an elevated
shell, and `git config core.symlinks true`. If symlinks can't be created,
stop before Step 5 and say so; don't commit copies.
- **SSH vs HTTPS** — use the URL exactly as given; the joiner can use
either form of the same repository.
---
*Licensed under the Apache License, Version 2.0 —
<http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -0,0 +1,153 @@
---
name: ckb-join
description: Join an existing shared Cascade Knowledge Base by its git origin URL — clone it into a folder (given, or a sensible default), check that it really is a Cascade KB, verify git identity, symlinks and upstream mounts, and leave it ready to open in the agent. Installed in a user's profile, so it works from any folder. Use for "join the knowledge base at this URL", "join our wiki", "get me set up on the team KB", "clone our wiki into this folder", "I've been invited to a KB". Not for creating a new KB (ckb-create) or for syncing a KB you already have (ckb-sync-changes inside it).
---
# Join a shared Cascade KB
## Purpose
Turn an origin URL into a working local copy of a team KB, and tell the
person what (if anything) is still missing on their machine. This skill
lives in a person's profile (`~/.claude/skills/`), not in any KB; once the
clone exists, the KB's own skills take over.
Read-only towards the shared history: it clones, inspects and reports. It
never commits, pushes, or edits files in the KB. Anything it can't fix
without writing to the KB is reported, not done.
## How to run this skill
### Step 1 — Inputs
- **Origin URL** — required. Ask if missing.
- **Folder** — optional. Default: `<current working directory>/<repo-name>`,
where `<repo-name>` is the last path segment of the URL without `.git`.
If the current directory is itself inside a git work tree or a KB, don't
default into it — ask where to put the clone instead.
Resolve the folder to an absolute path and say it back before cloning.
### Step 2 — Pre-flight
```bash
git --version
git config user.name; git config user.email
git ls-remote --symref <origin-url> HEAD
```
- **No git identity** — the KB stamps every log entry, workload note and
commit with it, so colleagues see who changed what. Ask for name and
email and set them with `git config --global` on a yes. If they decline,
continue but say the agent will fall back to the OS user name.
- **`ls-remote` fails** — report git's raw error. The usual causes: the
person hasn't been granted access yet (ask the KB owner), or no
credentials for that host (SSH key, credential helper, token). Stop.
- **`ls-remote` returns nothing** — the remote is empty: nobody has
published a KB there. Say so and suggest the owner runs `ckb-create`.
Stop.
- **Folder exists**:
- empty → clone into it;
- already a clone of the same remote (`git -C <folder> remote get-url
origin` matches) → nothing to clone; say "you've already joined — open
the folder and say *sync changes* to update", then go to Step 4 to
check it;
- anything else → stop and ask for another folder. Never clone over
existing files.
### Step 3 — Clone
```bash
git clone <origin-url> <folder>
```
Clone the remote's default branch (shown by `ls-remote --symref`). If it is
not `main`, say so: the KB's `ckb-sync-changes` assumes `main`, so the owner
should either rename the branch or know that sync will need adjusting.
On Windows, clone with `git clone -c core.symlinks=true …` so `CLAUDE.md`
and `.claude/skills` arrive as symlinks (needs Developer Mode or an
elevated shell).
### Step 4 — Check it is a working Cascade KB
From the folder:
```bash
test -f AGENTS.md && test -f wiki/index.md && test -f ckb.yaml
test -L CLAUDE.md && test -L .claude/skills
cat VERSION
grep kb_schema_version wiki/index.md
```
- **`AGENTS.md` or `wiki/index.md` missing** — this is not a Cascade KB (or
not a finished one). Say what was found, leave the clone in place, and
ask whether to delete it. Never delete without a yes.
- **Symlinks are plain files** — symlinks were not checked out (typically
Windows without `core.symlinks`). The agent would read a stale or empty
system prompt and see no skills. Tell the user how to fix it on their
machine: enable Developer Mode, `git config core.symlinks true`, then
`git checkout -- CLAUDE.md .claude/skills`. Don't commit anything.
Then report what the KB brings with it, from the files alone:
- **Purpose** — the `tldr` or first lines of `ABOUT.md`.
- **Template** — `VERSION`, and `ckb.yaml`'s `template:` branch if it is not
`main`.
- **Modules** — `ckb.yaml`'s `kb_modules:`; for `software`, note that
`src/` clones are not shared through this repo and must be cloned
separately if the person needs them.
- **Upstream mounts** —
- `linked/<name>` symlinks: check each target exists on this machine
(`test -e linked/<name>`). A dangling one points at a path on the
owner's machine; the person needs that upstream KB locally at the same
relative location, or their own symlink (not committed) to it.
- `libs/<name>/` with `source.yaml`: connector-backed, its generated index
came with the clone; nothing to do unless they are asked to be its admin.
- `libs/` folders mentioned in `wiki/` or the docs but absent: git-copy
libs are gitignored, so they never arrive with a clone. List them and
say who to ask for the source.
- **Python** — the first of `python3`, `python`, `py -3` that reports 3.x.
If none, say once that the KB still works on its fallback paths and point
to "Prerequisites" in its `docs/MANUAL.md`.
### Step 5 — Session brief (optional, when Python is available)
```bash
cd <folder> && <python> .agents/skills/ckb-lint/scripts/session_start.py --title "Joined the knowledge base"
```
Show the `ckb check:` and `routines:` lines only if they need action. Don't
act on them here — that happens in a session inside the KB.
### Step 6 — Report
Keep it short:
- the folder, the origin, the branch, and the KB's purpose line;
- anything from Step 4 the person has to fix on their machine, each with
its one-line fix — or "nothing to fix";
- **next step:** open the folder in the agent (`cd <folder> && claude`) so
the KB's own skills and rules load. Good first things to say there:
*set up my profile*, *onboard me on <topic>*, or a question. *Sync
changes* pulls colleagues' work and shares theirs.
## Edge cases
- **The person already has a ZIP copy of the KB** — a ZIP has no `origin`.
Clone fresh into a new folder rather than wiring git into the unpacked
copy; if they made local changes there, they can copy those files over
after the clone and sync.
- **They were given a URL to the upstream template (`…/ckb.git`)** rather
than a team KB — that repo is the template itself. Joining it is almost
never what they want; ask whether they meant to *create* a new KB
(`ckb-create`) or have a team KB URL.
- **Large repository** — fine to clone in full; don't use `--depth`, since
`ckb-sync-changes` merges and needs history.
- **Several KBs** — each is its own folder and its own clone; nothing is
shared between them unless one mounts the other under `linked/`.
---
*Licensed under the Apache License, Version 2.0 —
<http://www.apache.org/licenses/LICENSE-2.0>.*