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:
parent
56c0511ac7
commit
a80c3d43a4
4 changed files with 394 additions and 0 deletions
|
|
@ -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
42
user-skills/README.md
Normal 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.
|
||||
181
user-skills/ckb-create/SKILL.md
Normal file
181
user-skills/ckb-create/SKILL.md
Normal 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>.*
|
||||
153
user-skills/ckb-join/SKILL.md
Normal file
153
user-skills/ckb-join/SKILL.md
Normal 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>.*
|
||||
Loading…
Add table
Reference in a new issue