Sync: local changes as of 2026-07-17T12:45:15Z
This commit is contained in:
Michał Kopeć
parent
728870f3da
commit
057a7647cc
20 changed files with 2921 additions and 99 deletions
203
.agents/skills/cbk-quiz/SKILL.md
Normal file
203
.agents/skills/cbk-quiz/SKILL.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
---
|
||||
name: cbk-quiz
|
||||
description: Quiz the user on knowledge captured in the wiki. Reads wiki pages, generates questions in the user's chosen format (open questions or multiple choice), runs the quiz one question at a time with score tracking and immediate feedback. Use when the user asks for a quiz, wants to test their knowledge, or says "quiz me on X".
|
||||
---
|
||||
|
||||
# Quiz skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Turn the wiki knowledge base into a live, scored quiz. Read the relevant wiki pages, generate questions grounded in actual facts from those pages, run them one at a time, give immediate feedback, and deliver a final score with a brief verdict.
|
||||
|
||||
The quiz should feel like a game — fast-paced, specific, and satisfying to get right.
|
||||
|
||||
---
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Setup (three questions, one at a time)
|
||||
|
||||
Ask these questions one at a time. Wait for each answer before asking the next.
|
||||
|
||||
**Q1 — Topic**
|
||||
|
||||
> "What would you like to be quizzed on? You can name a specific topic (e.g. 'Saffron's financials', 'information security', 'the supplier onboarding process'), an entity, a concept, or just say 'everything' to draw from the whole wiki."
|
||||
|
||||
**Q2 — Number of questions**
|
||||
|
||||
> "How many questions? 5, 10, 15, or a custom number?"
|
||||
|
||||
Accept any integer between 3 and 30. If they say "quick" or "short", use 5. If they say "full" or "long", use 15.
|
||||
|
||||
**Q3 — Format**
|
||||
|
||||
> "Which format do you prefer?
|
||||
> - **A** — Open questions: I ask, you write your answer, I judge it.
|
||||
> - **B** — Multiple choice: four options, pick the letter.
|
||||
> - **C** — Mixed: roughly half and half."
|
||||
|
||||
---
|
||||
|
||||
### Step 2 — Load the wiki
|
||||
|
||||
Before generating questions, read the wiki to find material relevant to the chosen topic.
|
||||
|
||||
1. Read `wiki/index.md` to identify relevant pages.
|
||||
2. Read each relevant page in full. For a broad topic or "everything", read `wiki/overview.md` plus all entity and concept pages.
|
||||
3. Do not tell the user you are doing this - just do it silently.
|
||||
|
||||
From the content, note all specific, verifiable facts: names, numbers, dates, roles, decisions, technical details, relationships between entities. These are your question material. Vague or general claims make poor quiz questions - only use facts sharp enough to have a single correct answer.
|
||||
|
||||
---
|
||||
|
||||
### Step 3 — Generate questions
|
||||
|
||||
Generate exactly the requested number of questions before starting. Do not show them to the user yet.
|
||||
|
||||
**Quality rules for questions:**
|
||||
- Every question must be grounded in a specific fact from a wiki page. If you cannot point to the source page, discard the question.
|
||||
- Prefer questions with surprising or non-obvious answers - these are more satisfying to get right.
|
||||
- Vary the difficulty across the set: roughly one-third easy (basic recall), one-third medium (specific detail), one-third harder (connection between two facts or precise number/date).
|
||||
- Do not repeat the same subject across more than two questions.
|
||||
- Avoid questions with ambiguous answers. If a fact is contested or unclear in the wiki, skip it.
|
||||
|
||||
**For open questions:**
|
||||
- Write a clear question with a single, specific correct answer.
|
||||
- Prepare a model answer of one sentence plus the source page it comes from.
|
||||
|
||||
**For multiple choice:**
|
||||
- Write a clear question.
|
||||
- Generate four options (A, B, C, D): one correct, three plausible distractors. Distractors should be wrong but believable - not obviously silly.
|
||||
- Randomise the position of the correct answer across the question set (do not always put it at A or B).
|
||||
- Prepare the correct letter and a one-sentence explanation.
|
||||
|
||||
---
|
||||
|
||||
### Step 4 — Run the quiz
|
||||
|
||||
Display a header before the first question:
|
||||
|
||||
```
|
||||
Quiz: [topic]
|
||||
Format: [Open / Multiple choice / Mixed]
|
||||
Questions: [N]
|
||||
|
||||
Let's go.
|
||||
```
|
||||
|
||||
Then for each question:
|
||||
|
||||
**Present the question**
|
||||
|
||||
Show the question number and total prominently:
|
||||
|
||||
```
|
||||
Question [X] of [N]
|
||||
[Score so far: X correct]
|
||||
|
||||
[Question text]
|
||||
|
||||
[Options if multiple choice:
|
||||
A. ...
|
||||
B. ...
|
||||
C. ...
|
||||
D. ...]
|
||||
```
|
||||
|
||||
**Wait for the answer.** Do not give any hints. If the user says "skip" or "pass", move on and count it as a miss (but do not count it against their streak).
|
||||
|
||||
**Give immediate feedback**
|
||||
|
||||
For a correct answer:
|
||||
|
||||
```
|
||||
Correct. [One sentence with the fact and where it comes from in the wiki, e.g. "Saffron had GBP 1.545bn of assets at 31 December 2025 — from the deep research report."]
|
||||
```
|
||||
|
||||
For a wrong answer:
|
||||
|
||||
```
|
||||
Not quite. The answer is [correct answer]. [One sentence explanation.]
|
||||
```
|
||||
|
||||
For open questions, use judgement: if the user's answer captures the key fact even imperfectly, count it as correct and acknowledge what they got right. Only mark wrong if the core fact is missing or incorrect. When in doubt, count it as correct - the point is learning, not catching the user out.
|
||||
|
||||
**Track state silently.** Do not list the running score after every question. Show it only inside the question header (line: "Score so far: X correct").
|
||||
|
||||
**Streak tracking.** After three correct answers in a row, add a brief line:
|
||||
|
||||
```
|
||||
3 in a row.
|
||||
```
|
||||
|
||||
After five in a row:
|
||||
|
||||
```
|
||||
5 in a row. On a streak.
|
||||
```
|
||||
|
||||
Reset the streak message on a wrong answer. Do not add streak messages more than once per milestone per run.
|
||||
|
||||
---
|
||||
|
||||
### Step 5 — Final score
|
||||
|
||||
After the last question, show the results:
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
Final score: [X] / [N]
|
||||
|
||||
[Verdict — see below]
|
||||
|
||||
[One or two sentences on what the results suggest — which areas were strong, which came up as gaps.]
|
||||
```
|
||||
|
||||
**Verdicts by percentage:**
|
||||
|
||||
| Score | Verdict |
|
||||
|---|---|
|
||||
| 100% | Perfect. Nothing left to learn here. |
|
||||
| 80–99% | Strong. One or two things to look up. |
|
||||
| 60–79% | Solid base. Worth revisiting the gaps. |
|
||||
| 40–59% | Mixed. A second pass through the wiki would help. |
|
||||
| Under 40% | Plenty to learn. Try again after another read. |
|
||||
|
||||
---
|
||||
|
||||
### Step 6 — Offer a follow-up
|
||||
|
||||
After the verdict, always ask one of these (choose the most relevant):
|
||||
|
||||
- If score was under 60%: "Would you like me to run a shorter quiz on just the topics you missed?"
|
||||
- If score was 80%+: "Would you like a harder set on the same topic?"
|
||||
- Otherwise: "Would you like to try a different topic?"
|
||||
|
||||
Wait for the answer. If yes, go back to Step 2 with the new parameters. If no, close: "Good work. The wiki is there whenever you want another round."
|
||||
|
||||
---
|
||||
|
||||
## Style rules during the quiz
|
||||
|
||||
- Keep all quiz output tight. No filler sentences.
|
||||
- Use British English spelling.
|
||||
- No banned vocabulary from CLAUDE.md (testament, pivotal, seamless, crucial, etc.).
|
||||
- Feedback lines should be direct and specific. "Correct. Saffron was founded in January 1849." - not "Great job! That's absolutely right, the answer is..."
|
||||
- Never be condescending about wrong answers. State the correct fact and move on.
|
||||
- Do not add "Well done!", "Excellent!", "Nice try!" — these are noise. A plain "Correct." is better.
|
||||
|
||||
---
|
||||
|
||||
## Edge cases
|
||||
|
||||
**Not enough material.** If the wiki has too few verifiable facts for the requested number of questions (e.g. user asks for 15 questions on a single stub page), say: "I can only find enough material for [N] solid questions on that topic. Shall I run [N] questions, or broaden the topic?" Do not pad with weak questions.
|
||||
|
||||
**No wiki content.** If the topic has no coverage in the wiki at all, say: "That topic does not appear in the wiki yet. Choose a different topic, or ingest a source on it first."
|
||||
|
||||
**Ambiguous open answers.** When an open answer is on the border — partially right — mark it correct, note what was right and what the full answer includes. Do not leave the user unsure whether they got credit.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
@ -179,3 +179,8 @@ Tell the user:
|
|||
arbitrary ordering when listing directory entries), sort filenames
|
||||
alphabetically wherever you're generating a bullet list or walking a
|
||||
directory, so re-runs are stable.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
|
|||
|
|
@ -145,3 +145,8 @@ The script prints, and you should summarize back to the user:
|
|||
- **A wiki page with no H1:** falls back to a slugified filename as the
|
||||
title (e.g. `foo-bar.md` → "Foo Bar"), same fallback rule `ckb-export-okf`
|
||||
uses.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
|
|||
|
|
@ -1,4 +1,17 @@
|
|||
#!/usr/bin/env python3
|
||||
# Copyright 2026 Michał Kopeć
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
"""Export wiki/ into an Astro + Starlight-consumable form at outputs/starlight/.
|
||||
|
||||
Usage:
|
||||
|
|
|
|||
137
.agents/skills/ckb-ingest/SKILL.md
Normal file
137
.agents/skills/ckb-ingest/SKILL.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
name: ckb-ingest
|
||||
description: Process raw/inbox/ (or raw/ directly if the inbox is empty) into the structured wiki/ — consult the cascade, extract typed entities and relationships, synthesize frontmatted pages, cross-link them, update the index and log, then remind the user to review and sync to origin. Use when the user says "Ingest", "Sync the wiki", or "Update the Wiki". This is the content-level workflow from CLAUDE.md/AGENTS.md §3, distinct from the git-level `ckb-sync-changes` skill (which reconciles this repo's own history with its `origin` remote and does no wiki synthesis at all).
|
||||
---
|
||||
|
||||
# Ingest skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Turn raw, unstructured material in `raw/inbox/` (notes, links, pasted text,
|
||||
scratch files) into the local, mutable, structured `wiki/` — the top layer
|
||||
of the cascade that overlays read-only upstream KBs in `linked/` and
|
||||
`libs/`. This is the primary way the wiki grows. It is implemented as a
|
||||
skill (rather than living inline in `CLAUDE.md`/`AGENTS.md`) so the full
|
||||
ingestion procedure only loads into context when actually invoked.
|
||||
|
||||
This skill only ever writes to `wiki/` (and moves processed files within
|
||||
`raw/`). It never touches `linked/` or `libs/` — those are immutable
|
||||
upstream sources of truth — and it never touches this repo's own git
|
||||
remote; pushing the resulting changes is a separate, explicit step (see
|
||||
Step 7).
|
||||
|
||||
## Trigger phrases
|
||||
|
||||
Use this skill when the user says:
|
||||
- "Ingest"
|
||||
- "Sync the wiki"
|
||||
- "Update the wiki"
|
||||
|
||||
Do **not** use this skill for "sync changes", "sync with git/origin", or
|
||||
"reconcile git" — those are git-level operations with nothing to do with
|
||||
wiki content, handled by the `ckb-sync-changes` skill instead (see
|
||||
`.agents/skills/ckb-sync-changes/SKILL.md`). This skill and that one are
|
||||
deliberately separate: this one turns raw material into wiki pages; that
|
||||
one commits/pulls/pushes whatever is currently on disk, wiki changes
|
||||
included.
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Process the inbox
|
||||
|
||||
Scan `raw/inbox/` for new material. After ingesting each item, move it to
|
||||
`raw/archive/<YYYY-MM-DD>/`, where the date is today's ingestion date
|
||||
(create the dated folder if it doesn't exist yet).
|
||||
|
||||
If `raw/inbox/` is empty, scan `raw/` directly instead — excluding
|
||||
`raw/archive/`, which holds material already processed by a previous
|
||||
ingest.
|
||||
|
||||
### Step 2 — Consult the cascade
|
||||
|
||||
Before writing anything, check whether the entity already exists: local
|
||||
`wiki/` first, then each `linked/<name>/`, then each `libs/<name>/`
|
||||
(alphabetical within each layer). The local `wiki/` always wins — upstream
|
||||
content is informative context, but it can be overridden locally rather
|
||||
than treated as final.
|
||||
|
||||
### Step 3 — Extract entities
|
||||
|
||||
Identify typed entities in the source material — people, projects,
|
||||
libraries, concepts, systems. Create entity pages at
|
||||
`wiki/entities/<entity-name>.md` if they don't already exist. Record typed
|
||||
relationships between entities — `uses`, `depends_on`, `caused`,
|
||||
`contradicts`, `supersedes` — as edge data in `wiki/graph/edges.json`.
|
||||
|
||||
### Step 4 — Synthesize pages
|
||||
|
||||
Convert the core knowledge into clean, modular Markdown files. Every page
|
||||
gets frontmatter with:
|
||||
- A `tldr:` — one sentence, optimised for LLM reading.
|
||||
- A `confidence:` score (0.0–1.0, based on source corroboration).
|
||||
- A `quality:` self-score (0.0–1.0).
|
||||
- A `last_updated:` timestamp.
|
||||
- A `freshness_window_days:` appropriate to the topic.
|
||||
- A `retention:` level.
|
||||
|
||||
`type` is also required (per the page frontmatter schema in
|
||||
`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content
|
||||
kind (person, project, concept, library, decision, playbook, ...).
|
||||
|
||||
### Step 5 — Link and cross-reference
|
||||
|
||||
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard
|
||||
`[markdown](path.md)` links on every cross-reference, so the wiki works in
|
||||
Obsidian, GitHub, and CLI tools alike. Where useful, reference upstream
|
||||
files directly at `linked/<name>/...` or `libs/<name>/...`.
|
||||
|
||||
### Step 6 — Update index and log
|
||||
|
||||
Add new pages to the routing table in `wiki/index.md` with a **Use when**
|
||||
description. If the page lives in a subdirectory, also add it to that
|
||||
subdirectory's own `index.md`. Append a log entry to the most specific
|
||||
applicable log — the subdirectory's `log.md` if it has one, otherwise the
|
||||
root `wiki/log.md` — following the format in Rule B (`CLAUDE.md`/
|
||||
`AGENTS.md` §6).
|
||||
|
||||
If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately
|
||||
create that subdirectory's `index.md` per the Recursive Index & Log
|
||||
Convention.
|
||||
|
||||
### Step 7 — Remind to review and sync
|
||||
|
||||
This is always the last step, every time this skill runs and made any
|
||||
change at all. Close with a short reminder — do not sync or push
|
||||
anything yourself here, and do not skip this even if the changes look
|
||||
small or obviously correct:
|
||||
|
||||
> "Ingest complete — `wiki/` has been updated (see `wiki/log.md` for the
|
||||
> details). Please review the changes, and once you're happy with them,
|
||||
> say 'sync changes' to commit and push them to `origin`."
|
||||
|
||||
If nothing was actually ingested (empty inbox and empty `raw/`, nothing to
|
||||
process), skip this reminder — there's nothing to review or sync.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Inbox and `raw/` both empty** — report that there's nothing to
|
||||
ingest. Don't touch `wiki/`, and skip the Step 7 reminder.
|
||||
- **Item in inbox doesn't yield a clear entity or page** (too vague, pure
|
||||
scratch note with no durable fact) — don't force a page into existence.
|
||||
Still move the item to `raw/archive/<YYYY-MM-DD>/` since it's been
|
||||
considered, but note in the ingest report that it produced no wiki
|
||||
change.
|
||||
- **Conflicting information vs. an existing local wiki page** — this is a
|
||||
supersession case (Rule via `CLAUDE.md`/`AGENTS.md` §5 lint), not a
|
||||
silent overwrite: update the existing page if the new source is clearly
|
||||
more current/corroborated, and link `supersedes`/`superseded_by` if an
|
||||
older version is worth preserving rather than edited in place.
|
||||
- **Material duplicates an upstream (`linked/`/`libs/`) page with nothing
|
||||
new to add** — don't create a redundant local page just to have one;
|
||||
the cascade already surfaces the upstream page. Only write locally when
|
||||
overriding, correcting, or adding to what upstream says.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-init
|
||||
description: Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, and empty wiki/ scaffold as this project - inside a target folder (typically empty, or a new project that doesn't have one 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", or calls it a "wiki initializer". 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.
|
||||
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 (typically empty, or a new project that doesn't have one 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", or calls it a "wiki initializer". 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
|
||||
|
|
@ -9,16 +9,21 @@ description: Bootstrap a brand-new Cascade Knowledge Base - the same directory s
|
|||
|
||||
Copy this project's 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, 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."
|
||||
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."
|
||||
|
||||
This is a one-way copy from this repo's own `AGENTS.md`/`wiki/` template
|
||||
files into a different folder. It never reads or writes anything in this
|
||||
repo's `raw/`, `wiki/entities/`, `wiki/graph/edges.json`, or `outputs/` -
|
||||
those hold this project's actual accumulated knowledge, which is exactly
|
||||
what should *not* travel into a fresh KB.
|
||||
This is a one-way copy from this repo's own template files into a
|
||||
different folder. It never reads or writes anything in this repo's `raw/`,
|
||||
`wiki/entities/`, `wiki/graph/edges.json`, or `outputs/` - those hold this
|
||||
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
|
||||
|
||||
|
|
@ -57,19 +62,39 @@ specifically.
|
|||
### Step 3 - 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 reusable KB skill set
|
||||
- these operate purely on the `wiki/` structure, so they carry over
|
||||
cleanly and are part of "the schema" as far as this skill is concerned:
|
||||
`ckb-export-okf`, `ckb-export-starlight`, `ckb-sync-changes`, `extract-transcript`,
|
||||
`ckb-project-summary`. Don't ask about these - just include them.
|
||||
`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 this repo's
|
||||
`.agents/skills/`:
|
||||
|
||||
`ghost-writer` and `clouddrift-docx` are not part of the default set (a
|
||||
general writing tool and a brand-specific export skill respectively, not
|
||||
KB-schema-native) - only include either if the user explicitly asks for it,
|
||||
e.g. "also bring over ghost-writer."
|
||||
- `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-lint`
|
||||
- `ckb-sync-changes`
|
||||
- `ckb-project-summary`
|
||||
- `ckb-export-okf`
|
||||
- `ckb-export-starlight`
|
||||
- `ckb-onboard-me`
|
||||
- `ckb-teach-me`
|
||||
- `cbk-quiz`
|
||||
|
||||
Record the final skill list (default five, plus anything explicitly added)
|
||||
- this affects Steps 6 and 7.
|
||||
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 8 and 9.
|
||||
|
||||
### Step 4 - Create the directory structure
|
||||
|
||||
|
|
@ -87,11 +112,20 @@ wiki/graph/
|
|||
workload/
|
||||
```
|
||||
|
||||
`libs/`, `linked/`, and `tmp/` are gitignored per the schema (Step 6) and
|
||||
stay empty. `raw/inbox/`, `raw/archive/`, and `workload/` are meant to be
|
||||
tracked but start empty - add a placeholder `.gitkeep` file to each so they
|
||||
survive a fresh `git init` + first commit rather than vanishing as empty
|
||||
directories.
|
||||
Git doesn't track empty directories, so every one of these - plus
|
||||
`.agents/`, `.agents/skills/`, and `.claude/` created in Step 9 - 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 8) 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 5 - Write `AGENTS.md` and the `CLAUDE.md` symlink
|
||||
|
||||
|
|
@ -101,7 +135,30 @@ 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 6 - Write the empty `wiki/` scaffold
|
||||
### Step 6 - 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.
|
||||
- `VERSION` - copy the exact current value; the new KB starts life on the
|
||||
same template version it was just cloned from.
|
||||
|
||||
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 7 - 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
|
||||
|
|
@ -129,28 +186,53 @@ 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 7 - Write `.gitignore`
|
||||
### Step 8 - Write `.gitignore`
|
||||
|
||||
Base rules (always): `libs/`, `linked/`, `tmp/`, `.DS_Store`. Since
|
||||
`ckb-export-starlight` and `ckb-export-okf` are in the default skill set (Step 3),
|
||||
also always add `outputs/starlight` and `outputs/okf` - both exist to be
|
||||
gitignored precisely because those two skills are present by default.
|
||||
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:
|
||||
|
||||
### Step 8 - Copy the skill set from Step 3
|
||||
```
|
||||
libs/*
|
||||
!libs/.gitadd
|
||||
tmp/*
|
||||
!tmp/.gitadd
|
||||
outputs/starlight
|
||||
outputs/okf
|
||||
outputs/teaching
|
||||
.env
|
||||
```
|
||||
|
||||
Since `ckb-export-starlight`, `ckb-export-okf`, and `ckb-teach-me` are all
|
||||
in the default skill set (Step 3), 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 9 - Copy the skill set from Step 3
|
||||
|
||||
Copy each skill's folder from this repo's `.agents/skills/<name>/` into the
|
||||
target's `.agents/skills/<name>/` unchanged - the default five, 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.
|
||||
target's `.agents/skills/<name>/` unchanged (including each skill's own
|
||||
license footer, and any support files like
|
||||
`ckb-export-starlight/scripts/export_starlight.py`) - the full default set
|
||||
from Step 3, 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.
|
||||
|
||||
### Step 9 - Report
|
||||
### Step 10 - Report
|
||||
|
||||
Tell the user:
|
||||
- The resolved target path.
|
||||
- The directory tree created.
|
||||
- Whether `AGENTS.md`/`CLAUDE.md` were written or (per Step 2) skipped/merged.
|
||||
- Which skills were copied (the default five, plus anything explicitly added).
|
||||
- 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.
|
||||
- Next step: "Drop material into `raw/inbox/` and say 'Ingest' to populate the wiki for the first time."
|
||||
|
||||
## Edge cases
|
||||
|
|
@ -168,3 +250,8 @@ Tell the user:
|
|||
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>.*
|
||||
|
|
|
|||
149
.agents/skills/ckb-lint/SKILL.md
Normal file
149
.agents/skills/ckb-lint/SKILL.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
---
|
||||
name: ckb-lint
|
||||
description: Health-check the wiki/ — conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, and error-book entries — auto-fixing what it safely can and reporting the rest, then reminding the user to review and sync to origin. Use when the user says "Lint", "health-check the wiki", "check the wiki", or asks for a periodic/scheduled wiki health check. This is the maintenance workflow from CLAUDE.md/AGENTS.md §5, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all).
|
||||
---
|
||||
|
||||
# Lint skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Health-check the local, mutable `wiki/` for structural rot: missing or
|
||||
malformed frontmatter, stale pages, decayed confidence, orphaned or
|
||||
archivable content, broken graph edges, and index/log drift. This is
|
||||
maintenance, not growth — it never adds new knowledge the way `ckb-ingest`
|
||||
does; it only checks and repairs the shape of what's already there.
|
||||
|
||||
Implemented as a skill (rather than living inline in
|
||||
`CLAUDE.md`/`AGENTS.md`) so the full checklist only loads into context when
|
||||
actually invoked — on demand, or on a schedule if the user has set one up.
|
||||
|
||||
This skill only ever writes within `wiki/` (including moves into
|
||||
`wiki/archived/`). It never touches `linked/` or `libs/` — those are
|
||||
immutable upstream sources of truth — and it never touches this repo's own
|
||||
git remote; pushing the resulting changes is a separate, explicit step
|
||||
(see the final step below).
|
||||
|
||||
## Trigger phrases
|
||||
|
||||
Use this skill when the user says:
|
||||
- "Lint"
|
||||
- "health-check the wiki" / "check the wiki"
|
||||
- "run the periodic/scheduled wiki check"
|
||||
|
||||
Do **not** use this skill for "Ingest" / "Sync the wiki" (that's
|
||||
`ckb-ingest` — turning raw material into new wiki pages) or for "sync
|
||||
changes" / "sync with git" (that's `ckb-sync-changes` — reconciling this
|
||||
repo's own commit history with `origin`, no wiki content involved).
|
||||
|
||||
## How to run this skill
|
||||
|
||||
Work through each check in order. A malformed page breaks every later
|
||||
check's ability to reason about it, so conformance comes first.
|
||||
|
||||
### 1 — Conformance check
|
||||
|
||||
Verify every non-reserved `.md` file under `wiki/` (i.e. excluding
|
||||
`index.md` and `log.md`) has parseable YAML frontmatter with a non-empty
|
||||
`type` field. Flag violations first, and treat flagged pages as
|
||||
unreliable input for the checks below rather than guessing at their
|
||||
intended type/content.
|
||||
|
||||
### 2 — Freshness check
|
||||
|
||||
Scan every page whose `last_updated` exceeds its `freshness_window_days`.
|
||||
Flag as stale; suggest the user confirm or update the content — don't
|
||||
silently rewrite stale content yourself.
|
||||
|
||||
### 3 — Confidence decay
|
||||
|
||||
Reduce `confidence` on pages not reinforced by a new source since the last
|
||||
check. Pages that fall below 0.3 confidence get flagged for re-review.
|
||||
|
||||
### 4 — Retention sweep
|
||||
|
||||
Move `retention: low` pages older than 2× their `freshness_window_days`
|
||||
into `wiki/archived/`. Never delete — always move, and log the move (see
|
||||
Rule B in `CLAUDE.md`/`AGENTS.md` §6) with a note explaining why.
|
||||
|
||||
### 5 — Supersession detection
|
||||
|
||||
When two pages appear to cover the same entity, check for contradictions.
|
||||
If one is clearly newer/better corroborated, add `supersedes` /
|
||||
`superseded_by` links between them. Preserve the older page rather than
|
||||
deleting it, but mark it stale.
|
||||
|
||||
### 6 — Orphan detection
|
||||
|
||||
Find pages with no inbound links (`[[wikilinks]]` or
|
||||
`[markdown](path.md)` references from elsewhere in the wiki). Either add
|
||||
backlinks from relevant pages where an obvious connection exists, or move
|
||||
the orphan to `wiki/archived/` with a log note if no natural backlink
|
||||
exists.
|
||||
|
||||
### 7 — Graph consistency
|
||||
|
||||
Verify every edge in `wiki/graph/edges.json` points to an existing entity
|
||||
page. Remove or fix broken edges; note what was removed rather than
|
||||
silently dropping entries.
|
||||
|
||||
### 8 — Index/log consistency
|
||||
|
||||
Verify every subdirectory under `wiki/` that contains pages has an
|
||||
`index.md` listing all of them, and that no single change is recorded in
|
||||
both a subdirectory `log.md` and the root `wiki/log.md` (per the
|
||||
Recursive Index & Log Convention). Fix missing index entries and
|
||||
duplicate log entries directly.
|
||||
|
||||
### 9 — Error Book entry
|
||||
|
||||
Record any systemic issue found above (a repeated broken pattern, a
|
||||
recurring format mismatch, the same kind of orphan appearing again) in
|
||||
`wiki/error-book.md` with its root cause, the fix applied, and the derived
|
||||
constraint that should prevent recurrence. A one-off, isolated issue
|
||||
doesn't need an Error Book entry — this is for patterns, not incidents.
|
||||
|
||||
### Auto-fix vs. report
|
||||
|
||||
Auto-fix what can be done safely and mechanically: broken links, missing
|
||||
backlinks, stale flags, missing index entries, duplicate log entries,
|
||||
dangling graph edges. Report anything that needs a judgment call
|
||||
(supersession decisions, low-confidence content, ambiguous orphans) rather
|
||||
than guessing on the user's behalf.
|
||||
|
||||
### Final step — Remind to review and sync
|
||||
|
||||
This is always the last step, every time this skill makes any change at
|
||||
all to `wiki/`. Close with a short reminder — do not sync or push
|
||||
anything yourself here:
|
||||
|
||||
> "Lint complete — see `wiki/log.md` for what changed (auto-fixed: ...;
|
||||
> flagged for your review: ...). Please review the changes, and once
|
||||
> you're happy with them, say 'sync changes' to commit and push them to
|
||||
> `origin`."
|
||||
|
||||
If the lint pass made no changes at all (clean bill of health, nothing to
|
||||
fix or flag), skip this reminder — there's nothing to review or sync.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Wiki is empty or near-empty** — report that there's little to lint
|
||||
yet; don't fabricate findings to look thorough.
|
||||
- **A page's frontmatter is unparseable** (not just missing `type`, but
|
||||
invalid YAML) — flag it prominently in the conformance check and skip
|
||||
it in every later numbered check rather than letting a parse error
|
||||
crash or silently mis-handle downstream logic.
|
||||
- **Retention sweep would archive a page that's clearly still in active
|
||||
use** (e.g. linked from a very recent `workload/` entry) — flag it for
|
||||
the user to confirm rather than auto-archiving; recency of use can
|
||||
override a stale `last_updated`/`retention` combination.
|
||||
- **Supersession is ambiguous** (two pages disagree and neither is
|
||||
clearly newer/better corroborated) — report the conflict rather than
|
||||
guessing which one wins.
|
||||
- **Repeated run with nothing changed since the last lint** — should
|
||||
produce essentially the same clean report each time; don't invent
|
||||
variation just to seem active.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
@ -141,3 +141,8 @@ Close with a short offer: to go deeper on any single step, to widen the tour
|
|||
- **Upstream-only topic** — if the anchor lives in `linked/`/`libs/` with no
|
||||
local overlay, build the tour from the upstream KB's own index/links and mark
|
||||
every step as upstream/read-only.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
|
|||
|
|
@ -175,3 +175,8 @@ whatever the wiki says at that moment, not what it said today.
|
|||
- **Re-running with no wiki changes since the last run** - should produce
|
||||
essentially the same content each time; don't introduce random variation
|
||||
in section content or ordering between runs.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
|
|||
|
|
@ -63,7 +63,35 @@ ask the user via `AskUserQuestion` whether to include or skip each one
|
|||
*before* staging anything in Step 3 — never silently commit or silently
|
||||
drop a flagged file.
|
||||
|
||||
### Step 2 — Detect the first-run / unrelated-histories case
|
||||
### Step 2 — Ensure `origin` is configured
|
||||
|
||||
```bash
|
||||
git remote get-url origin
|
||||
```
|
||||
|
||||
- **Succeeds** → go to Step 3.
|
||||
- **Fails** (`fatal: No such remote 'origin'`, or `git remote` lists nothing
|
||||
at all) → this repo has no remote to sync with yet. Ask the user directly
|
||||
(a plain question is fine here — it's a URL to paste, not a choice between
|
||||
options):
|
||||
> "This repo has no `origin` remote configured. Paste the URL of the
|
||||
> remote repository (e.g. `https://github.com/org/repo.git` or
|
||||
> `git@github.com:org/repo.git`) and I'll add it as `origin`."
|
||||
|
||||
Once given:
|
||||
```bash
|
||||
git remote add origin <url>
|
||||
```
|
||||
Then continue to Step 3 with `origin` now configured. If `git remote add`
|
||||
itself errors (malformed URL, etc.), report the raw error and stop — don't
|
||||
guess at a corrected URL or retry with a modified one.
|
||||
- **A differently-named remote already exists** (e.g. `upstream`) that looks
|
||||
like it might be the intended remote — don't assume. Ask the user whether
|
||||
that's the one to sync with (in which case, whether to alias/rename it to
|
||||
`origin` since the rest of this skill assumes that name) or whether to add
|
||||
a separate, new `origin`.
|
||||
|
||||
### Step 3 — Detect the first-run / unrelated-histories case
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
|
|
@ -71,10 +99,10 @@ git rev-parse HEAD # fails with "unknown revision" if local has no co
|
|||
git rev-parse origin/main # fails if the remote branch doesn't exist/is empty
|
||||
```
|
||||
|
||||
- **Local `HEAD` exists** → go to Step 3, regardless of remote state.
|
||||
- **Local `HEAD` exists** → go to Step 4, regardless of remote state.
|
||||
- **Local `HEAD` doesn't exist, and `origin/main` doesn't exist or is empty**
|
||||
→ this is a plain first publish, not a reconciliation. Proceed
|
||||
automatically to Step 3 (it will just commit and push with nothing to
|
||||
automatically to Step 4 (it will just commit and push with nothing to
|
||||
merge).
|
||||
- **Local `HEAD` doesn't exist, but `origin/main` already has commits** →
|
||||
**hard stop, every time this is detected.** Show the user:
|
||||
|
|
@ -90,14 +118,14 @@ git rev-parse origin/main # fails if the remote branch doesn't exist/is empt
|
|||
Do **not** offer a fourth "discard remote, force local to become main"
|
||||
option — that requires a force-push and is out of scope for this skill;
|
||||
if the user wants that, tell them it needs to be done manually. Execute
|
||||
only the option chosen, then continue to Step 3 with whichever git state
|
||||
only the option chosen, then continue to Step 4 with whichever git state
|
||||
results.
|
||||
|
||||
### Step 3 — Steady-state flow
|
||||
### Step 4 — Steady-state flow
|
||||
|
||||
Order matters: **commit local changes first, then fetch/merge, then push.**
|
||||
Committing first turns any overlap into an ordinary merge conflict (which
|
||||
Step 4 already knows how to present), rather than a stash-pop conflict with
|
||||
Step 5 already knows how to present), rather than a stash-pop conflict with
|
||||
no commit boundary to fall back on.
|
||||
|
||||
```bash
|
||||
|
|
@ -113,7 +141,7 @@ git merge origin/main # merge, never rebase — rebase would rewrit
|
|||
|
||||
Outcomes of the merge:
|
||||
- `Already up to date.` or a clean auto-merge → continue below.
|
||||
- `CONFLICT` → go to Step 4, then come back here once every conflict is
|
||||
- `CONFLICT` → go to Step 5, then come back here once every conflict is
|
||||
resolved and committed.
|
||||
|
||||
```bash
|
||||
|
|
@ -125,7 +153,7 @@ fetch and push), retry the fetch → merge → push cycle **exactly once**. If
|
|||
it fails again, stop and report the raw error to the user — never force,
|
||||
never retry more than once.
|
||||
|
||||
### Step 4 — Present each conflict to the user
|
||||
### Step 5 — Present each conflict to the user
|
||||
|
||||
```bash
|
||||
git diff --name-only --diff-filter=U
|
||||
|
|
@ -162,15 +190,16 @@ staged, commit:
|
|||
```bash
|
||||
git commit -m "Merge origin/main (conflicts resolved with user input)"
|
||||
```
|
||||
Then return to Step 3's push.
|
||||
Then return to Step 4's push.
|
||||
|
||||
### Step 5 — Report
|
||||
### Step 6 — Report
|
||||
|
||||
End with a structured summary:
|
||||
|
||||
```
|
||||
## Sync report
|
||||
|
||||
**Remote:** origin already configured (or "origin added: <url>")
|
||||
**Pulled from origin/main:** <N> commit(s) — <oneline log, or "none, already up to date">
|
||||
**Committed locally:** <N> file(s) — <paths>, commit <short-hash> (or "no local changes to commit")
|
||||
**Conflicts encountered:** <N> (or "none")
|
||||
|
|
@ -195,5 +224,16 @@ blocker.
|
|||
push."
|
||||
- **Push rejected twice in a row** — stop, report the raw git error, do not
|
||||
force and do not retry a third time.
|
||||
- **No remote configured, or fetch/push fails on auth/network** — report
|
||||
- **No `origin` remote configured** — handled proactively in Step 2 (ask
|
||||
the user for the URL and add it), not treated as a failure.
|
||||
- **User pastes an invalid or unreachable URL** — `git remote add` itself
|
||||
usually still succeeds (it doesn't validate reachability); the failure
|
||||
surfaces at the `git fetch origin` in Step 3. Report that raw error and
|
||||
ask the user to confirm the URL rather than guessing a correction.
|
||||
- **Fetch/push fails on auth/network once a remote is configured** — report
|
||||
the error clearly. This skill does not manage git credentials.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
|
|||
327
.agents/skills/ckb-teach-me/SKILL.md
Normal file
327
.agents/skills/ckb-teach-me/SKILL.md
Normal file
|
|
@ -0,0 +1,327 @@
|
|||
---
|
||||
name: ckb-teach-me
|
||||
description: Turn the wiki knowledge base into a personalised teaching curriculum — plan a single session or a spaced series (duration, frequency, optional calendar .ics reminders), teach one portion per session using varied techniques (Socratic questioning, analogies, worked examples, teach-back, mini knowledge checks), and track progress against the plan across calls, re-teaching weak spots before moving on. Use when the user asks to "teach me the wiki", "teach me about X", "run a teaching session", "continue my lessons", or wants a structured course built from the knowledge base rather than a one-off quiz (for that, use the `quiz` skill instead).
|
||||
---
|
||||
|
||||
# Teach me (wiki curriculum) skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Turn the wiki into a taught course, not just a lookup table or a one-off
|
||||
quiz. This skill has two modes that always run in this order for a given
|
||||
topic:
|
||||
|
||||
1. **Plan mode** (first call for a topic) — scope the material, ask
|
||||
scheduling questions, chunk the knowledge into session-sized portions,
|
||||
present the plan, save it once accepted.
|
||||
2. **Teach mode** (every later call for that topic) — compare the saved
|
||||
plan against saved progress, teach the next portion using a technique
|
||||
different from last time, spot-check retention of earlier sessions, and
|
||||
update progress.
|
||||
|
||||
The wiki stays authoritative and read-only from this skill's point of
|
||||
view — it never writes back to `wiki/`. Curricula, plans, and progress live
|
||||
under `outputs/teaching/`, one subfolder per topic.
|
||||
|
||||
## Trigger phrases
|
||||
|
||||
- "teach me the wiki" / "teach me everything in the wiki"
|
||||
- "teach me about X" / "I want to learn X" / "run me a course on X"
|
||||
- "run a teaching session" / "continue my lessons" / "next lesson"
|
||||
- "where am I up to in my lessons on X"
|
||||
|
||||
Do **not** use this skill for a one-off knowledge test with no curriculum
|
||||
or progress tracking — that's the `quiz` skill.
|
||||
|
||||
---
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 0 — Resolve topic and existing state
|
||||
|
||||
1. Determine the topic from the user's phrasing. "Teach me about X" scopes
|
||||
to X; a bare "teach me the wiki" scopes to the whole KB — confirm this
|
||||
is really what they want given it may be large, and offer to narrow it
|
||||
first (e.g. "the whole wiki is quite broad — want me to scope this to a
|
||||
part of it, or build a multi-session course covering all of it?").
|
||||
2. Slugify the topic (kebab-case) and look for
|
||||
`outputs/teaching/<slug>/plan.md`.
|
||||
- **Exists** → this is a **Teach mode** call. Skip to Step 5.
|
||||
- **Doesn't exist** → this is a **Plan mode** call. Continue to Step 1.
|
||||
- **Several folders look like plausible matches** for a vague topic
|
||||
(e.g. user says "continue my lessons" with more than one curriculum
|
||||
in progress) → list them (topic, sessions done / total) and ask which
|
||||
one to continue.
|
||||
|
||||
### Step 1 — Scheduling questions (Plan mode only)
|
||||
|
||||
Ask one at a time, waiting for each answer:
|
||||
|
||||
**Q1 — Single session or a series?**
|
||||
|
||||
> "Do you want this as one session, or a series of shorter sessions spread
|
||||
> over time?"
|
||||
|
||||
**Q2 — Duration and frequency**
|
||||
|
||||
- If single session: "How long should the session be? (e.g. 20, 45, 60
|
||||
minutes)"
|
||||
- If series: "How long should each session be, and how often would you
|
||||
like them? (e.g. '20 minutes, twice a week' or '30 minutes every
|
||||
weekday')" Also ask for a start date if they want the calendar file
|
||||
(Q3) — otherwise it's optional and can default to "starting next
|
||||
session request."
|
||||
|
||||
**Q3 — Calendar reminders**
|
||||
|
||||
> "Would you like a calendar file (.ics) you can import to get reminders
|
||||
> for these sessions?"
|
||||
|
||||
If yes and it's a series, also ask for a preferred time of day and start
|
||||
date if not already given, so events can be scheduled concretely. If it's
|
||||
a single session, offer a one-off reminder event instead.
|
||||
|
||||
### Step 2 — Gather the material
|
||||
|
||||
1. Read `wiki/index.md` (and `wiki/entities/index.md`,
|
||||
`wiki/graph/index.md` if present) to find every page in scope. For a
|
||||
narrow topic, use the cascade (local `wiki/` first, then `linked/`,
|
||||
then `libs/`) same as any query. For "whole wiki", scope is every page
|
||||
under `wiki/` plus its graph.
|
||||
2. Read each in-scope page in full (`tldr` first — skip the body only if
|
||||
the page turns out irrelevant on inspection).
|
||||
3. **Optional web supplement** — if the wiki is thin on a subtopic that's
|
||||
clearly needed for a coherent course, you may search the web to fill
|
||||
the gap. Mark any such material distinctly as *external, supplementary*
|
||||
in the plan and during teaching — it does not carry the wiki's
|
||||
cascade authority. If the gap is substantial enough to be worth
|
||||
keeping permanently, tell the user afterwards it would be a good
|
||||
candidate for `raw/inbox/` and a proper Ingest (per the Demand-Driven
|
||||
Context rule in `CLAUDE.md`) rather than silently folding it into the
|
||||
wiki yourself.
|
||||
4. Use `wiki/graph/edges.json` (or link-following if edges are sparse — same
|
||||
fallback as the onboarding-tour skill) to work out dependency order:
|
||||
foundations (`depends_on`/`uses` targets) before the concepts that build
|
||||
on them.
|
||||
|
||||
### Step 3 — Chunk into sessions
|
||||
|
||||
Order the material pedagogically (foundations → core → things that build
|
||||
on it, same logic as a guided tour), then cut it into session-sized
|
||||
portions against the duration from Step 1.
|
||||
|
||||
- Rule of thumb: roughly one wiki page or tightly-scoped subtopic per
|
||||
10-15 minutes of session time, adjusted for how dense the material
|
||||
actually is (a short stub page is quick; a long entity page with many
|
||||
facts takes longer).
|
||||
- **When in doubt, add a session rather than overfill one.** A session
|
||||
that runs long or crams two unrelated topics together teaches worse than
|
||||
two clean, focused sessions. Never let a single session's plan exceed
|
||||
its stated duration on paper.
|
||||
- Each session should have one clear theme/title, not a grab-bag.
|
||||
- Reserve implicit room in later sessions for retention spot-checks (Step
|
||||
6) — don't plan every minute as new material.
|
||||
|
||||
### Step 4 — Present the plan and get acceptance
|
||||
|
||||
Show the session breakdown before saving anything:
|
||||
|
||||
```markdown
|
||||
## Proposed course: [Topic]
|
||||
|
||||
**Format:** [N session(s) of ~M minutes] [ · every X, starting YYYY-MM-DD if series]
|
||||
**Calendar file:** [Yes — will generate reminders.ics / No]
|
||||
|
||||
1. **Session 1 — [title]** — [1-line: what it covers, sourced from which pages]
|
||||
2. **Session 2 — [title]** — ...
|
||||
...
|
||||
|
||||
Sound good, or would you like the sessions rebalanced (more/fewer,
|
||||
different split)?
|
||||
```
|
||||
|
||||
Wait for explicit acceptance before writing anything. If the user wants
|
||||
changes, adjust and re-present — don't save a rejected plan.
|
||||
|
||||
### Step 5 — Save the plan (Plan mode only, after acceptance)
|
||||
|
||||
Create `outputs/teaching/<slug>/plan.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: teaching-plan
|
||||
topic: <topic as stated>
|
||||
scope: <"whole wiki" | narrower description>
|
||||
session_mode: single | series
|
||||
session_duration_minutes: <M>
|
||||
frequency: <e.g. "twice a week" | null for single>
|
||||
calendar_file: outputs/teaching/<slug>/reminders.ics | null
|
||||
created: YYYY-MM-DD
|
||||
last_updated: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Teaching plan: <topic>
|
||||
|
||||
## Overview
|
||||
[2-3 sentences: what this course covers and why the sessions are ordered
|
||||
this way.]
|
||||
|
||||
## Sessions
|
||||
|
||||
### Session 1 — <title>
|
||||
- **Covers:** [pages/subtopics, as links, e.g. `wiki/entities/foo.md`]
|
||||
- **Learning goals:** [what the user should be able to explain/do after]
|
||||
- **External supplements:** [none | list, marked as such]
|
||||
|
||||
### Session 2 — <title>
|
||||
...
|
||||
```
|
||||
|
||||
Create `outputs/teaching/<slug>/progress.md` alongside it, empty of
|
||||
sessions so far:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: teaching-progress
|
||||
topic: <topic as stated>
|
||||
plan_file: outputs/teaching/<slug>/plan.md
|
||||
last_updated: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Teaching progress: <topic>
|
||||
|
||||
## Session log
|
||||
|
||||
_No sessions taught yet._
|
||||
|
||||
## Next up
|
||||
|
||||
Session 1 — <title>.
|
||||
```
|
||||
|
||||
If a calendar file was requested, generate
|
||||
`outputs/teaching/<slug>/reminders.ics` (see Calendar file generation
|
||||
below). Report the paths written and that the course is ready to start
|
||||
whenever the user says so — do not start teaching Session 1 automatically
|
||||
in this same turn unless the user asks for it explicitly.
|
||||
|
||||
### Step 6 — Teach mode: pick up where progress left off
|
||||
|
||||
1. Read `plan.md` and `progress.md` for the resolved topic.
|
||||
2. Determine the next unit of work:
|
||||
- If the previous session's knowledge check (see below) showed weak
|
||||
spots, open this session with a short, targeted recap of just those
|
||||
weak points before moving on — don't re-teach the whole prior
|
||||
session.
|
||||
- If the previous check was very poor (roughly under half recalled),
|
||||
dedicate this whole session to reinforcing that material instead of
|
||||
advancing the plan, and note this as an inserted repetition session
|
||||
in `progress.md` (it doesn't consume a slot from the numbered plan).
|
||||
- Otherwise, teach the next not-yet-completed session from `plan.md`.
|
||||
3. Pick a teaching technique **different from the one used last session**
|
||||
(rotate through the list below) so the course doesn't feel repetitive.
|
||||
4. Teach the portion: pull the actual facts from the relevant wiki pages
|
||||
(plus any marked external supplements), and deliver them via the
|
||||
chosen technique. Keep it interactive — this is a taught session, not
|
||||
a wall of text.
|
||||
5. Close the session with a short, informal knowledge check (2-4
|
||||
questions, open or quick-recall style) on **today's** material only.
|
||||
Judge generously, same spirit as the `quiz` skill: if the core fact
|
||||
came through even imperfectly, count it as understood.
|
||||
6. Update `progress.md`: append a dated entry for this session (technique
|
||||
used, brief note on what was taught, knowledge-check result, any weak
|
||||
spots flagged for next time), update `Next up`, bump `last_updated` on
|
||||
both `progress.md` and — only if the plan's own shape changed (e.g. an
|
||||
inserted repetition session) — `plan.md`.
|
||||
7. If this was the final session in the plan, say so, give a short
|
||||
overall verdict, and offer either a full-course review (can point at
|
||||
the `quiz` skill for a proper scored test) or planning a new topic.
|
||||
|
||||
**Teaching technique rotation** (pick one not used last time; introduce
|
||||
variety, don't always default to plain explanation):
|
||||
- **Socratic questioning** — lead the user to the fact via guided
|
||||
questions rather than stating it outright.
|
||||
- **Analogy / storytelling** — frame the concept through a relatable
|
||||
comparison or short narrative.
|
||||
- **Worked example / case walkthrough** — walk through a concrete instance
|
||||
from the wiki step by step.
|
||||
- **Compare-and-contrast** — teach a concept against something it's
|
||||
commonly confused with.
|
||||
- **Teach-back** — give the user the raw facts, then ask them to explain
|
||||
the concept back in their own words; correct gently.
|
||||
- **Mnemonic / memory device** — for lists or sequences, build a memory
|
||||
aid together with the user.
|
||||
- **Real-world scenario / role-play** — apply the concept to a
|
||||
hypothetical situation the user reasons through.
|
||||
|
||||
---
|
||||
|
||||
## Calendar file generation
|
||||
|
||||
Only when requested. Write a standard RFC 5545 `.ics` file to
|
||||
`outputs/teaching/<slug>/reminders.ics`:
|
||||
|
||||
```
|
||||
BEGIN:VCALENDAR
|
||||
VERSION:2.0
|
||||
PRODID:-//Cascade KB//Teach Me//EN
|
||||
BEGIN:VEVENT
|
||||
UID:<slug>-session-1@ckb-teach-me
|
||||
DTSTART:<YYYYMMDDTHHMMSS>
|
||||
DTEND:<start + session_duration_minutes>
|
||||
RRULE:<only if series, e.g. FREQ=WEEKLY;BYDAY=TU,TH>
|
||||
SUMMARY:Lesson: <topic> — Session 1
|
||||
DESCRIPTION:<title of session 1>
|
||||
BEGIN:VALARM
|
||||
TRIGGER:-PT30M
|
||||
ACTION:DISPLAY
|
||||
DESCRIPTION:Lesson reminder
|
||||
END:VALARM
|
||||
END:VEVENT
|
||||
...one VEVENT per session (or a single RRULE'd VEVENT if the sessions are
|
||||
evenly spaced and identical in duration)...
|
||||
END:VCALENDAR
|
||||
```
|
||||
|
||||
- For a series with a regular cadence, prefer one recurring `VEVENT` with
|
||||
an `RRULE` (and a `COUNT=<N>` matching the number of sessions) over N
|
||||
separate events — simpler for the user's calendar app to manage.
|
||||
- For a single session or irregular cadence, emit one `VEVENT` per
|
||||
session with explicit dates.
|
||||
- Use the date/time the user gave in Step 1; if no time of day was given,
|
||||
ask before generating rather than guessing.
|
||||
- Tell the user the file path and that importing it is a manual step in
|
||||
their own calendar app — this skill only produces the file.
|
||||
|
||||
---
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **No wiki content in scope.** Tell the user the topic isn't covered
|
||||
yet, same as the `quiz` skill would — suggest a narrower topic or an
|
||||
Ingest first. Don't fabricate a curriculum from nothing.
|
||||
- **Topic scope changes between Plan and Teach calls** (user asks to
|
||||
teach something broader/narrower than the saved plan). Treat this as a
|
||||
new topic — create a new `outputs/teaching/<new-slug>/` rather than
|
||||
overwriting the existing plan, since the old one may still be in
|
||||
progress.
|
||||
- **User wants to abandon or restart a course.** Ask for confirmation,
|
||||
then either delete the folder (only with explicit confirmation — this
|
||||
is a destructive action) or archive `progress.md` with a note and start
|
||||
a fresh `plan.md` if they want to redo the scoping.
|
||||
- **Plan and progress disagree** (e.g. plan.md was hand-edited, or a
|
||||
session number in progress.md doesn't exist in plan.md). Point it out
|
||||
to the user and ask how to reconcile rather than silently guessing.
|
||||
- **Course fully completed and user asks to "teach me" again on the same
|
||||
topic.** Don't silently restart — tell them the course is complete and
|
||||
ask whether they want a fresh, deeper course, a review/quiz pass, or a
|
||||
different topic.
|
||||
- **Very long-running series** (many sessions already logged) — no need
|
||||
to re-read every past `progress.md` entry in full each time; the `Next
|
||||
up` line and the most recent 1-2 session entries are enough context to
|
||||
continue. Older entries are history, not required reading.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
367
.agents/skills/ckb-upgrade/SKILL.md
Normal file
367
.agents/skills/ckb-upgrade/SKILL.md
Normal file
|
|
@ -0,0 +1,367 @@
|
|||
---
|
||||
name: ckb-upgrade
|
||||
description: Check the canonical Cascade KB template repo (https://git.wierzbowa.cloud/michal/ckb) for a newer schema/tooling version, and if one exists, upgrade this KB's template layer (AGENTS.md/CLAUDE.md, .agents/skills/, LICENSE, VERSION, README/MANUAL docs, base .gitignore rules) in place. Also checks wiki/index.md's own kb_schema_version for compatibility (including the case of an unversioned, pre-schema wiki) independently of the template layer, and — only with explicit confirmation — can migrate existing wiki/ content (backfilling missing frontmatter, adding missing scaffold files) up to the current schema while preserving every fact already collected. Use when the user asks to "upgrade the wiki", "upgrade this KB", "check for a newer template version", "update the KB schema", "pull in the latest skills", or "is there a new version of ckb". Distinct from ckb-sync-changes (reconciles this repo's OWN origin remote with its own history) and ckb-init (bootstraps a brand-new, empty KB) — this skill updates an EXISTING, populated KB's tooling layer (and, if asked, its content's schema conformance) from a separate upstream template source.
|
||||
---
|
||||
|
||||
# Upgrade skill
|
||||
|
||||
## Purpose
|
||||
|
||||
A Cascade KB, once created, tends to drift from the canonical template as
|
||||
the template gains new skills, fixes, or schema refinements. This skill
|
||||
answers "am I behind, and if so, can I catch up?" without risking the
|
||||
knowledge collected since. It treats a KB as having two layers, and checks
|
||||
each **independently** — a KB can be behind on one, the other, both, or
|
||||
neither:
|
||||
|
||||
- **Template layer** — the schema/tooling that defines *how* the KB
|
||||
behaves: `AGENTS.md`/`CLAUDE.md`, `.agents/skills/*`, `LICENSE`,
|
||||
`VERSION`, `README.md`/`README.pl.md`/`MANUAL.md`/`MANUAL.pl.md`, and the
|
||||
base `.gitignore` rules. Compared via the root `VERSION` file. Freely
|
||||
upgradable — these files hold no project-specific content.
|
||||
- **Content layer** — everything the KB has actually learned:
|
||||
`wiki/entities/`, `wiki/graph/edges.json`, `wiki/index.md`'s entity rows,
|
||||
`wiki/log.md`, `wiki/overview.md`, `wiki/error-book.md`, plus `raw/`,
|
||||
`outputs/`, `workload/`. Compared via `wiki/index.md`'s own
|
||||
`kb_schema_version` field (a KB predating that convention entirely
|
||||
counts as "unversioned" and behind by default). This skill **never**
|
||||
touches any of it automatically — a migration only ever runs after
|
||||
explicit confirmation (see Step 3 and Step 7), and even then it only
|
||||
ever adds/backfills structure, never rewrites the substance of what a
|
||||
page says.
|
||||
|
||||
It's entirely possible to be behind on the content layer while current on
|
||||
the template layer, or vice versa: a KB might already have the latest
|
||||
`AGENTS.md`/skills but still carry `wiki/` pages ingested years ago under
|
||||
an older (or no) schema version, or the reverse. This skill checks and
|
||||
offers to fix both, separately.
|
||||
|
||||
This is different from `ckb-sync-changes` (reconciles *this* repo's own
|
||||
commit history with *its own* `origin` remote — same content, no template
|
||||
comparison) and from `ckb-init` (bootstraps a brand-new, empty KB from the
|
||||
template — nothing to preserve because there's no content yet). This skill
|
||||
assumes you already have a populated KB and want to catch it up with
|
||||
template improvements made elsewhere, without disturbing anything you've
|
||||
collected unless you specifically ask it to reshape that content's
|
||||
structure too.
|
||||
|
||||
## Trigger phrases
|
||||
|
||||
- "upgrade the wiki" / "upgrade this KB"
|
||||
- "check for a newer template version" / "is there a new version of ckb"
|
||||
- "update the KB schema" / "pull in the latest skills"
|
||||
|
||||
Do **not** use this for "sync changes" (that's `ckb-sync-changes` — this
|
||||
repo's own `origin`) or for setting up a brand-new KB (that's `ckb-init`).
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Fetch the canonical template for comparison
|
||||
|
||||
Clone the canonical repo shallowly into a scratch location under `tmp/` —
|
||||
never touch this repo's own git remotes or history to do this comparison:
|
||||
|
||||
```bash
|
||||
rm -rf tmp/ckb-upgrade-src
|
||||
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git tmp/ckb-upgrade-src
|
||||
```
|
||||
|
||||
If the clone fails (network, auth, unreachable host), report the raw
|
||||
error and stop — this skill does not fall back to a cached or partial
|
||||
check, and does not retry silently.
|
||||
|
||||
### Step 2 — Compare template (tooling) versions
|
||||
|
||||
Read `VERSION` at the repo root (treat a missing file as `0.0.0` — an
|
||||
older KB that predates this convention) and
|
||||
`tmp/ckb-upgrade-src/VERSION`. Compare as dotted-integer tuples
|
||||
(`1.2.0` > `1.1.9`), not as plain strings — e.g.:
|
||||
|
||||
```bash
|
||||
python3 -c "
|
||||
local_v = tuple(int(x) for x in open('VERSION').read().strip().split('.'))
|
||||
remote_v = tuple(int(x) for x in open('tmp/ckb-upgrade-src/VERSION').read().strip().split('.'))
|
||||
print('newer' if remote_v > local_v else 'same-or-older')
|
||||
"
|
||||
```
|
||||
|
||||
Record the result (`template_upgrade_available`: yes/no) and continue to
|
||||
Step 3 regardless — a "no" here does **not** end the skill, because the
|
||||
wiki content schema (Step 3) is checked independently and may still be
|
||||
behind.
|
||||
|
||||
### Step 3 — Compare the wiki content's own schema version
|
||||
|
||||
This is a **separate** check from Step 2, and can find something to do
|
||||
even when Step 2 didn't. Read the `kb_schema_version` frontmatter field
|
||||
from local `wiki/index.md`, and from
|
||||
`tmp/ckb-upgrade-src/wiki/index.md` (the version new KBs are created with
|
||||
today). Compare as `(major, minor)` tuples, e.g. `"1.2"` > `"1.1"`.
|
||||
|
||||
- **Local `wiki/index.md` has no `kb_schema_version` at all** — this is an
|
||||
**unversioned** wiki: either it predates the convention entirely, or it
|
||||
was hand-built without the standard frontmatter. Treat it as behind by
|
||||
default, same as version `"0.0"`.
|
||||
- **Local version is older than the template's** — behind.
|
||||
- **Local version is the same or newer** — not behind; nothing to do for
|
||||
content.
|
||||
|
||||
Record the result (`wiki_schema_upgrade_available`: yes/no, plus the two
|
||||
version strings for reporting).
|
||||
|
||||
**If both `template_upgrade_available` and `wiki_schema_upgrade_available`
|
||||
are "no"** → report "already up to date — template v`X`, wiki schema
|
||||
v`Y`," clean up the scratch clone (Step 8), and stop.
|
||||
|
||||
### Step 4 — Diff the template layer only (if `template_upgrade_available`)
|
||||
|
||||
Skip this step entirely if Step 2 found no template upgrade — go straight
|
||||
to Step 5 with just the wiki-schema finding to present, if any.
|
||||
|
||||
The template layer is exactly these paths — never anything under `wiki/`,
|
||||
`raw/`, `outputs/`, `workload/`, `tmp/`, `libs/`, or `linked/`:
|
||||
|
||||
- `AGENTS.md` (and the `CLAUDE.md` symlink — recreate it if it's missing
|
||||
or isn't a symlink to `AGENTS.md`; don't diff its content, it's just a
|
||||
symlink)
|
||||
- `LICENSE`
|
||||
- `VERSION`
|
||||
- `README.md`, `README.pl.md`, `MANUAL.md`, `MANUAL.pl.md` — whichever
|
||||
exist upstream (an older local KB may not have some of these yet)
|
||||
- `.agents/skills/<name>/**` for every skill folder present in
|
||||
`tmp/ckb-upgrade-src/.agents/skills/`
|
||||
- The base ignore rules in `.gitignore` (`libs/`, `linked/`, `tmp/`,
|
||||
regenerated `outputs/` subfolders, `.env`, etc.) — merged, never
|
||||
replaced wholesale (see Step 6)
|
||||
|
||||
For every path in that list, diff the local copy against the scratch
|
||||
clone's copy:
|
||||
|
||||
- **Doesn't exist locally, exists upstream** (e.g. a skill or doc added
|
||||
since this KB was created) — no local content at risk; stage it as an
|
||||
addition.
|
||||
- **Identical** — nothing to do.
|
||||
- **Differs** — this needs care. The difference might be a template
|
||||
improvement worth taking, or it might be a deliberate local
|
||||
customization — nothing here can tell those apart automatically,
|
||||
especially for `AGENTS.md`, which the [manual](../../../MANUAL.md)
|
||||
explicitly tells users they're free to edit. Never silently overwrite;
|
||||
queue it for Step 5.
|
||||
|
||||
### Step 5 — Present findings and get decisions
|
||||
|
||||
Present whichever of the two findings apply (one or both):
|
||||
|
||||
```markdown
|
||||
## Upgrade available
|
||||
|
||||
### Template: v<local> → v<remote> (only if template_upgrade_available)
|
||||
|
||||
**New files** (nothing local to lose, will be added):
|
||||
- <path>
|
||||
- ...
|
||||
|
||||
**Changed files** (local content differs from the template):
|
||||
- <path> — <one-line summary of the change, e.g. "Step 7 reworded" or
|
||||
"trigger phrases extended">
|
||||
- ...
|
||||
|
||||
### Wiki content schema: v<local-or-"unversioned"> → v<remote> (only if wiki_schema_upgrade_available)
|
||||
|
||||
Your `wiki/` content was built against an older (or no) schema version.
|
||||
This doesn't stop anything from working, but some pages may be missing
|
||||
frontmatter fields the current schema expects (`tldr`, `confidence`,
|
||||
`quality`, `retention`, etc.), or missing structural pieces (e.g. no
|
||||
`wiki/graph/` folder yet). Nothing factual would be rewritten — only
|
||||
structure and metadata would be backfilled.
|
||||
```
|
||||
|
||||
For each **changed template file**, ask via `AskUserQuestion` — batched
|
||||
into one question if the user wants to move fast, or one at a time if
|
||||
they'd rather review each — with options **"Take the template version"**,
|
||||
**"Keep my local version"**, or **"Show me the full diff first."**
|
||||
|
||||
Default recommendation for template files:
|
||||
- Skill files (`.agents/skills/**`), `LICENSE`, `VERSION` — lean toward
|
||||
"take the template version." These are rarely hand-edited and are
|
||||
exactly the kind of thing that should stay in sync.
|
||||
- `AGENTS.md`, `README*`, `MANUAL*` — don't default silently. Say plainly
|
||||
that local customization is common in these files and ask explicitly
|
||||
rather than nudging toward either choice.
|
||||
|
||||
If `wiki_schema_upgrade_available`, ask a **separate**, explicit question
|
||||
— don't fold it into the template-file batch, since it's a different kind
|
||||
of decision with different risk (it touches `wiki/`, which this skill
|
||||
otherwise never does):
|
||||
|
||||
> "Would you like me to also upgrade all wiki-related folders and data to
|
||||
> the new standard? I'll review every page under `wiki/`, add any missing
|
||||
> scaffold files, and backfill missing frontmatter fields — without
|
||||
> rewriting any of the actual knowledge you've collected. For a large
|
||||
> wiki this can take a while. Options: **Yes, rebuild to the new
|
||||
> standard** / **No, just the template files** / **Show me what's
|
||||
> missing first, then decide.**"
|
||||
|
||||
These two decisions are independent — a user can accept the template
|
||||
upgrade and decline the wiki migration, or vice versa.
|
||||
|
||||
### Step 6 — Apply the accepted template-layer changes
|
||||
|
||||
Only if `template_upgrade_available` and at least one item was accepted:
|
||||
|
||||
- Copy accepted **new** and **changed** files from `tmp/ckb-upgrade-src/`
|
||||
over their local counterparts.
|
||||
- For `.gitignore`, don't overwrite it — append any upstream base rules
|
||||
not already present locally (line-by-line comparison), preserving every
|
||||
existing local line, including custom ones the user added for their own
|
||||
project.
|
||||
- If `CLAUDE.md` isn't a symlink to `AGENTS.md` (or is missing), recreate
|
||||
it as one.
|
||||
- Leave every path outside the template layer completely untouched at
|
||||
this step — `wiki/` changes, if any, happen only in Step 7.
|
||||
- Update local `VERSION` to the template's new version last, only once
|
||||
every other accepted change has been applied successfully.
|
||||
|
||||
### Step 7 — Rebuild wiki content to the new schema (only if confirmed in Step 5)
|
||||
|
||||
This is the one part of this skill that writes under `wiki/` — it only
|
||||
ever runs after the explicit confirmation from Step 5, never
|
||||
automatically, and never partially without saying so. Warn the user
|
||||
before starting if `wiki/entities/` has many pages, since this is a
|
||||
per-page pass, not instant.
|
||||
|
||||
**a. Fill structural gaps first.** Check for the standard `wiki/` scaffold
|
||||
pieces and create any that are missing, using the same empty-template
|
||||
shape `ckb-init` writes for a fresh KB (never overwrite one that already
|
||||
exists, even if it looks sparse):
|
||||
- `wiki/entities/index.md`, `wiki/graph/index.md`, `wiki/graph/edges.json`
|
||||
- `wiki/error-book.md`, `wiki/overview.md`
|
||||
- Any subdirectory under `wiki/entities/`-style groupings that's missing
|
||||
its own `index.md` per the Recursive Index & Log Convention.
|
||||
|
||||
**b. Backfill frontmatter on every existing page**, per the schema in
|
||||
`AGENTS.md` §2. For each `.md` file under `wiki/` (excluding the reserved
|
||||
`index.md`/`log.md`/`error-book.md`), check its frontmatter against the
|
||||
schema and fix only what's missing — never touch a field that's already
|
||||
present, and never alter the page's body text:
|
||||
- **Missing `type`** — infer conservatively from the page's own content
|
||||
and location (e.g. a page under `wiki/entities/` describing a person,
|
||||
project, library, or concept). Don't silently guess: batch every
|
||||
inferred `type` into one list and confirm it with the user before
|
||||
writing, since `type` is the field lint treats as most load-bearing.
|
||||
- **Missing `tldr`** — synthesize a one-sentence summary from the page's
|
||||
actual content. Low-risk, mechanical — no need to ask per-page.
|
||||
- **Missing `confidence` / `quality`** — don't invent a placeholder
|
||||
number. Re-read the page fresh and score it the same way `ckb-ingest`
|
||||
would score a newly-synthesized page (source corroboration for
|
||||
confidence, structure/citations/consistency for quality).
|
||||
- **Missing `last_updated`** — set to today, and note in the log entry
|
||||
(Step 7d) that the date reflects this migration, not original
|
||||
authorship.
|
||||
- **Missing `freshness_window_days` / `retention`** — set a reasonable
|
||||
default appropriate to the page's apparent topic, the same judgment call
|
||||
`ckb-ingest` makes for newly-written pages.
|
||||
- **Missing dual-linking** on an existing cross-reference (only a
|
||||
`[[wikilink]]` where a `[markdown](path.md)` link should also exist, or
|
||||
vice versa) — add the missing form. Don't invent new cross-references
|
||||
that weren't already there in some form.
|
||||
|
||||
**c. Bump `wiki/index.md`'s `kb_schema_version`** to the template's
|
||||
current value, once every page has been checked.
|
||||
|
||||
**d. Log every touched page** in `wiki/log.md`, per Rule B's format — this
|
||||
is the one legitimate exception to this skill's normal "never writes to
|
||||
`wiki/log.md`" behavior, and should say clearly in each entry that the
|
||||
change was a schema-migration backfill, not new knowledge:
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD HH:MM] - UPDATE (schema migration)
|
||||
- **File Affected:** `wiki/entities/foo.md`
|
||||
- **Description:** Backfilled missing `tldr`, `confidence`, `retention` during schema migration to v<new>. No content changes.
|
||||
- **Source:** ckb-upgrade schema migration
|
||||
---
|
||||
```
|
||||
|
||||
**e. Suggest running "Lint" afterward** as an independent verification
|
||||
pass, rather than re-implementing lint's own conformance checks here —
|
||||
the two skills should agree on what "conformant" means.
|
||||
|
||||
### Step 8 — Clean up and report
|
||||
|
||||
```bash
|
||||
rm -rf tmp/ckb-upgrade-src
|
||||
```
|
||||
|
||||
Report a summary covering whichever tracks actually ran:
|
||||
|
||||
```markdown
|
||||
## Upgrade report
|
||||
|
||||
**Template version:** v<old> → v<new> (or "already current")
|
||||
**Added:** <N> file(s) — <paths, or "none">
|
||||
**Updated:** <N> file(s) — <paths, or "none">
|
||||
**Kept local (declined template version):** <N> file(s) — <paths, or "none">
|
||||
|
||||
**Wiki content schema:** v<old-or-"unversioned"> → v<new> (or "already current" / "declined")
|
||||
**Scaffold files added:** <paths, or "none">
|
||||
**Pages backfilled:** <N> — <paths, or "none">
|
||||
**Types inferred and confirmed:** <list, or "none">
|
||||
```
|
||||
|
||||
If anything actually changed, close with the same reminder pattern as
|
||||
`ckb-ingest`/`ckb-lint`: review the diff, then say "sync changes" to
|
||||
commit and push it to *this KB's own* `origin` — not the template repo
|
||||
just checked against, which is typically a different remote for any KB
|
||||
other than the template project itself.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **No `VERSION` file locally** — treat local version as `0.0.0`; any real
|
||||
template version counts as newer. Mention in the report that this KB
|
||||
predates version tracking.
|
||||
- **No `kb_schema_version` in local `wiki/index.md` at all** — treat as
|
||||
unversioned/behind by default (Step 3), and say so plainly in the
|
||||
report rather than silently treating it as "version 0.0."
|
||||
- **This KB's own `origin` *is* the template repo itself** (i.e. this is
|
||||
the template project's own working copy) — the checks still work
|
||||
(they'll usually report "already up to date" on both fronts since
|
||||
you're comparing against yourself), but note this in the report so it's
|
||||
clear why an "upgrade" against your own remote looks like a no-op.
|
||||
- **Network/auth failure cloning the template repo** — report the raw
|
||||
error, make no changes on either track, and clean up any partial
|
||||
scratch clone.
|
||||
- **A "changed" template file's difference looks trivial** — still
|
||||
surface it for a decision; don't invent a heuristic for "safe to
|
||||
auto-take," since the cost of a wrong guess (silently discarding a real
|
||||
customization) is worse than one extra question.
|
||||
- **User declines every changed template file** — still add any pure-new
|
||||
files (nothing lost by doing so) and bump `VERSION`, since the KB
|
||||
genuinely is now aware it's on the newer template version even if it
|
||||
kept its own customized copies of specific files.
|
||||
- **User confirms the wiki migration but the wiki is very large** — process
|
||||
it in batches with progress updates rather than promising instant
|
||||
completion; it's fine for this to be the longest-running part of the
|
||||
skill.
|
||||
- **User declines the wiki migration** — still bump nothing under `wiki/`,
|
||||
including `kb_schema_version` — leave it exactly as found, so a future
|
||||
run of this skill still detects it as behind rather than silently
|
||||
considering it handled.
|
||||
- **A page's inferred `type` is ambiguous even after inspection** — ask
|
||||
the user directly for that page rather than guessing between two
|
||||
plausible types; don't let one uncertain page block backfilling the
|
||||
rest.
|
||||
- **Uncommitted local changes already present before running this skill**
|
||||
— proceed anyway (nothing here is destructive; every change lands as an
|
||||
ordinary working-tree diff, reversible with `git checkout`), but mention
|
||||
in the report that there was pre-existing uncommitted work, so the user
|
||||
knows the diff they're about to review isn't only from this upgrade.
|
||||
- **A skill folder was renamed or removed upstream** — don't delete the
|
||||
corresponding local folder automatically (it might still be in active
|
||||
use, or further customized locally); mention it in the report as
|
||||
"removed upstream, left in place locally" and let the user decide
|
||||
separately.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -4,4 +4,5 @@ tmp/*
|
|||
!tmp/.gitadd
|
||||
outputs/starlight
|
||||
outputs/okf
|
||||
outputs/teaching
|
||||
.env
|
||||
|
|
|
|||
46
AGENTS.md
46
AGENTS.md
|
|
@ -115,25 +115,7 @@ retention: high|medium|low # How aggressively to deprioritize when old
|
|||
|
||||
## 3. INGESTION WORKFLOW (TRIGGERED ON DEMAND)
|
||||
|
||||
When the user says "Ingest", "Sync the wiki", or "Update the Wiki" (for syncing this repo's own git history with its remote, see the ckb-sync-changes skill under `.claude/skills/` instead):
|
||||
|
||||
1. **Process Inbox:** Scan `raw/inbox/` for new material. After ingesting, move each processed item to `raw/archive/<YYYY-MM-DD>/`, where the date is today's ingestion date (create the dated folder if it doesn't exist yet). If `raw/inbox/` is empty, scan `raw/` directly (excluding `raw/archive/`, which holds already-processed material).
|
||||
|
||||
2. **Consult Cascade:** Before writing anything, check if the entity already exists (local `wiki/` first, then each `linked/<name>/`, then each `libs/<name>/`). The local `wiki/` always wins. Upstream content is informative but can be overridden locally.
|
||||
|
||||
3. **Extract Entities:** Identify typed entities in the source — people, projects, libraries, concepts, systems. Create entity pages in `wiki/entities/<entity-name>.md` if they don't exist. Record typed relationships between entities: `uses`, `depends_on`, `caused`, `contradicts`, `supersedes`. Store edge data in `wiki/graph/edges.json`.
|
||||
|
||||
4. **Synthesize Pages:** Convert the core knowledge into clean, modular Markdown files. Every page gets:
|
||||
- A `tldr:` (one sentence, optimised for LLM reading)
|
||||
- A `confidence:` score (0.0–1.0 based on source corroboration)
|
||||
- A `quality:` self-score (0.0–1.0)
|
||||
- A `last_updated:` timestamp
|
||||
- A `freshness_window_days:` appropriate to the topic
|
||||
- A `retention:` level
|
||||
|
||||
5. **Link & Cross-Reference:** Use **both** `[[Wikilinks]]` and standard `[markdown](path.md)` links on every cross-reference. This ensures the wiki works in Obsidian, GitHub, and CLI tools. Where useful, reference upstream files at `linked/<name>/...` or `libs/<name>/...`.
|
||||
|
||||
6. **Update Index & Log:** Add new pages to the routing table in `wiki/index.md` with a **Use when** description. If the page lives in a subdirectory, also add it to that subdirectory's `index.md`. Append a log entry to the most specific applicable log — the subdirectory's `log.md` if it has one, otherwise `wiki/log.md`. If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately create that subdirectory's `index.md` per the Recursive Index & Log Convention.
|
||||
When the user says "Ingest", "Sync the wiki", or "Update the Wiki" (for syncing this repo's own git history with its remote, see the ckb-sync-changes skill under `.claude/skills/` instead), run the **ckb-ingest** Claude Code Skill — see `.agents/skills/ckb-ingest/SKILL.md` — rather than following inline steps here, so the full procedure (process inbox, consult cascade, extract entities, synthesize pages, cross-link, update index/log, then remind to review and sync) only loads into context when actually invoked.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -151,27 +133,7 @@ When answering a question or researching a topic:
|
|||
|
||||
## 5. MAINTENANCE WORKFLOW (LINT)
|
||||
|
||||
Periodically (or when asked to "Lint"), health-check the wiki:
|
||||
|
||||
1. **Conformance check** — verify every non-reserved `.md` file under `wiki/` (i.e. excluding `index.md` and `log.md`) has parseable YAML frontmatter with a non-empty `type` field. Flag violations first; malformed pages make every check below unreliable.
|
||||
|
||||
2. **Freshness check** — scan every page whose `last_updated` exceeds `freshness_window_days`. Flag as stale; suggest the user confirm or update the content.
|
||||
|
||||
3. **Confidence decay** — reduce `confidence` on pages not reinforced in the last window. Pages below 0.3 confidence get flagged for re-review.
|
||||
|
||||
4. **Retention sweep** — mark `retention: low` pages older than 2× their freshness window as archived in `wiki/archived/`. Do not delete — move with a note in the log.
|
||||
|
||||
5. **Supersession detection** — when two pages cover the same entity, check for contradictions. If one is newer, add `supersedes` / `superseded_by` links. Preserve the old page but mark it stale.
|
||||
|
||||
6. **Orphan detection** — find pages with no inbound links. Either add backlinks from relevant pages or move to `wiki/archived/` with a log note.
|
||||
|
||||
7. **Graph consistency** — verify every edge in `wiki/graph/edges.json` points to an existing entity page. Remove or fix broken edges.
|
||||
|
||||
8. **Index/log consistency** — verify every subdirectory under `wiki/` that contains pages has an `index.md` listing all of them, and that no single change is recorded in both a subdirectory `log.md` and the root `wiki/log.md`.
|
||||
|
||||
9. **Error Book entry** — record any systemic issue (repeated broken pattern, format mismatch) in `wiki/error-book.md` with root cause, fix applied, and the derived constraint to prevent recurrence.
|
||||
|
||||
Auto-fix what you can (broken links, missing backlinks, stale flags). Report what you cannot.
|
||||
Periodically (or when asked to "Lint"), run the **ckb-lint** Claude Code Skill — see `.agents/skills/ckb-lint/SKILL.md` — rather than following inline steps here, so the full checklist (conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, error-book entries, auto-fix vs. report, then a reminder to review and sync) only loads into context when actually invoked.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -209,8 +171,8 @@ After every conversational turn where you take any action (read, write, search,
|
|||
Follow these event-driven behaviors:
|
||||
|
||||
- **On new source in inbox** — on the next ingest, auto-process: extract entities, update graph, update index, write to log.
|
||||
- **On session start** — read `wiki/index.md` and the latest `workload/` summary to load relevant context.
|
||||
- **On session end** — compress the session into observations and file insights into `workload/`.
|
||||
- **On session start** — read `wiki/index.md` and the latest `workload/` summary to load relevant context. Also check for unsynchronized changes (`git status` — uncommitted local changes, or the local branch ahead/behind its remote-tracking ref) and, if any are found, tell the user and suggest running the `ckb-sync-changes` skill before proceeding. This is a cheap, read-only check (no `git fetch`) — a heads-up, not a substitute for actually running that skill.
|
||||
- **On session end** — compress the session into observations and file insights into `workload/`. Also re-run the same unsynchronized-changes check as at session start — the session's own work may have just created new local changes — and suggest `ckb-sync-changes` if anything is now pending.
|
||||
- **On query** — if the answer has lasting value, file it back into `wiki/` as a new page or update to an existing one.
|
||||
- **On memory write** — check for contradictions with existing wiki content. If found, apply supersession (link old → new) and log it.
|
||||
- **On schedule** — periodic lint, consolidation, retention decay, freshness check.
|
||||
|
|
|
|||
201
LICENSE
Normal file
201
LICENSE
Normal file
|
|
@ -0,0 +1,201 @@
|
|||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright 2026 Michał Kopeć
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
428
MANUAL.md
Normal file
428
MANUAL.md
Normal file
|
|
@ -0,0 +1,428 @@
|
|||
# User Manual
|
||||
|
||||
*Read this in: **English** | [Polski](MANUAL.pl.md)*
|
||||
|
||||
This is the human-facing manual for working with a Cascade Knowledge Base
|
||||
(this repo). It's written for the *person* using the wiki, not the agent —
|
||||
for the agent's own operating rules, see [AGENTS.md](AGENTS.md) /
|
||||
[CLAUDE.md](CLAUDE.md). For a feature-by-feature technical overview, see
|
||||
[README.md](README.md). This document is task-oriented: "I want to do X —
|
||||
what do I say, and what happens?"
|
||||
|
||||
Everywhere below, "say" means typing it to whatever AI coding agent you're
|
||||
using against this repo (Claude Code, or another agent that reads
|
||||
`AGENTS.md`). You don't need exact wording — the trigger phrases shown are
|
||||
examples, not magic words; the agent matches intent.
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
1. [Creating or initialising a wiki](#1-creating-or-initialising-a-wiki)
|
||||
2. [Adding knowledge](#2-adding-knowledge)
|
||||
3. [Keeping it tidy](#3-keeping-it-tidy)
|
||||
4. [Syncing — with yourself, and with other people](#4-syncing--with-yourself-and-with-other-people)
|
||||
5. [Upgrading the template](#5-upgrading-the-template)
|
||||
6. [Use cases](#6-use-cases)
|
||||
7. [What's agent-generated vs. what you can edit](#7-whats-agent-generated-vs-what-you-can-edit)
|
||||
8. [Quick reference](#8-quick-reference)
|
||||
|
||||
---
|
||||
|
||||
## 1. Creating or initialising a wiki
|
||||
|
||||
### If you're reading this inside an existing Cascade KB
|
||||
|
||||
Nothing to do — the structure already exists (`wiki/`, `raw/`, `outputs/`,
|
||||
etc.). Skip to [§2](#2-adding-knowledge).
|
||||
|
||||
### Starting a brand-new one elsewhere
|
||||
|
||||
Say:
|
||||
|
||||
> "Set up a new wiki like this one in `~/projects/my-notes`."
|
||||
|
||||
This clones the *schema* only — the directory structure, the
|
||||
`AGENTS.md`/`CLAUDE.md` behaviour file, and an empty `wiki/` scaffold — into
|
||||
the target folder. It never copies this project's actual content (no
|
||||
entities, no graph data, no notes). You get a fresh, empty KB, ready for its
|
||||
first `raw/inbox/` drop. See `.agents/skills/ckb-init/SKILL.md`.
|
||||
|
||||
If the target folder already looks like a KB (it has a `wiki/` or
|
||||
`AGENTS.md` already), the agent will stop and ask before touching anything
|
||||
— it won't silently overwrite an existing knowledge base.
|
||||
|
||||
### Building on top of someone else's wiki
|
||||
|
||||
A Cascade KB can sit on top of one or more *upstream* knowledge bases,
|
||||
which stay entirely read-only. There are two ways to mount one:
|
||||
|
||||
- **Symlink** (another KB on your own machine, or one you maintain
|
||||
elsewhere and want live-linked):
|
||||
```bash
|
||||
ln -s /path/to/other-kb ./linked/other-team
|
||||
```
|
||||
- **Git clone** (an external KB you want a frozen, version-controlled copy
|
||||
of):
|
||||
```bash
|
||||
git clone https://github.com/org/external-kb ./libs/external-kb
|
||||
```
|
||||
|
||||
Either way, once it's mounted, just ask questions normally — the agent
|
||||
checks your local `wiki/` first, then walks `linked/`, then `libs/`, and
|
||||
uses whichever has the answer. You never edit files inside `linked/` or
|
||||
`libs/` directly; if something there is wrong or outdated, you fix it by
|
||||
writing the corrected version into your own local `wiki/`, which always
|
||||
wins.
|
||||
|
||||
---
|
||||
|
||||
## 2. Adding knowledge
|
||||
|
||||
This is the main way the wiki grows. There are two on-ramps:
|
||||
|
||||
### A. Drop material, then say "Ingest"
|
||||
|
||||
Put anything unprocessed into `raw/inbox/` — pasted notes, a `.txt`
|
||||
transcript, a `links.txt` of URLs, a PDF, a messy scratch file. No need to
|
||||
organise it first. Then say:
|
||||
|
||||
> "Ingest." (or "Sync the wiki" / "Update the wiki" — same thing)
|
||||
|
||||
Example:
|
||||
|
||||
> *You drop `meeting-2026-07-10.txt` (rough notes from a client call) into
|
||||
> `raw/inbox/`, then say "Ingest."*
|
||||
>
|
||||
> The agent reads the file, extracts the people, decisions, and open
|
||||
> questions mentioned, creates or updates entity pages under
|
||||
> `wiki/entities/`, records relationships in `wiki/graph/edges.json`, adds
|
||||
> the new pages to `wiki/index.md`, logs the change in `wiki/log.md`, and
|
||||
> moves the original file to `raw/archive/2026-07-10/`. It finishes by
|
||||
> reminding you to review the result and say "sync changes" once you're
|
||||
> happy with it.
|
||||
|
||||
If `raw/inbox/` is empty, the agent scans `raw/` directly instead (still
|
||||
skipping `raw/archive/`, which is already-processed history).
|
||||
|
||||
This is implemented by the `ckb-ingest` skill —
|
||||
`.agents/skills/ckb-ingest/SKILL.md`.
|
||||
|
||||
### B. Just tell the agent something in conversation
|
||||
|
||||
You don't always need a file. If you tell the agent a fact worth keeping —
|
||||
"actually, the deadline moved to September" — and it has lasting value, the
|
||||
agent can file it straight into `wiki/` as a new page or an update to an
|
||||
existing one, the same as it would from an ingested file.
|
||||
|
||||
### C. Let the agent tell you what's missing (Demand-Driven Context)
|
||||
|
||||
If you ask something the wiki can't answer, the agent doesn't just fail
|
||||
silently — it identifies the gap and proposes a minimal page to fill it.
|
||||
|
||||
Example:
|
||||
|
||||
> **You:** "What's our policy on X?"
|
||||
> **Agent:** "The wiki doesn't cover that yet. Want me to add a stub page
|
||||
> for it, or can you paste/describe the policy and I'll write it up?"
|
||||
|
||||
You approve, paste the source, or drop it in `raw/inbox/` — the next
|
||||
ingest incorporates it. This keeps the wiki demand-driven: it grows around
|
||||
what you actually ask, not everything that could theoretically be written
|
||||
down.
|
||||
|
||||
---
|
||||
|
||||
## 3. Keeping it tidy
|
||||
|
||||
Say, whenever you like (there's no fixed schedule — do it after a big
|
||||
ingest, or just periodically):
|
||||
|
||||
> "Lint."
|
||||
|
||||
This runs a health check across the whole wiki:
|
||||
|
||||
- pages missing required frontmatter (`type`) get flagged
|
||||
- pages that haven't been touched in a while get flagged as stale
|
||||
- confidence scores decay if nothing has reinforced them recently
|
||||
- old, low-priority pages get archived to `wiki/archived/` (never deleted)
|
||||
- contradicting pages get linked old→new (supersession)
|
||||
- orphaned pages (nothing links to them) get backlinked or archived
|
||||
- broken graph edges get fixed or removed
|
||||
- missing/duplicate index and log entries get corrected
|
||||
- recurring systemic issues get written into `wiki/error-book.md`
|
||||
|
||||
It fixes what it safely can on its own, and reports the rest for you to
|
||||
decide. Like Ingest, it finishes by reminding you to review and sync.
|
||||
Implemented by the `ckb-lint` skill —
|
||||
`.agents/skills/ckb-lint/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Syncing — with yourself, and with other people
|
||||
|
||||
There are two entirely different kinds of "sync" here — don't confuse
|
||||
them:
|
||||
|
||||
| | Ingest / Lint | Sync changes |
|
||||
|---|---|---|
|
||||
| **Layer** | Content (what the wiki knows) | Git (whose disk has which files) |
|
||||
| **What it touches** | `wiki/`, `raw/` | The repo's commit history and `origin` remote |
|
||||
| **Say** | "Ingest" / "Lint" | "Sync changes" |
|
||||
|
||||
### Reconciling with `origin` (git-level sync)
|
||||
|
||||
Say:
|
||||
|
||||
> "Sync changes."
|
||||
|
||||
This commits whatever local changes you have (e.g. from a recent Ingest or
|
||||
Lint pass), pulls down anything new from `origin`, merges the two, and —
|
||||
if there's a conflict — walks you through it file by file, asking you to
|
||||
keep your version, keep the remote version, or supply merged text for each
|
||||
conflicting block. Once everything's resolved, it pushes.
|
||||
|
||||
If this repo has never been connected to a remote, the agent will ask you
|
||||
to paste the URL first:
|
||||
|
||||
> **Agent:** "This repo has no `origin` remote configured. Paste the URL
|
||||
> of the remote repository and I'll add it as `origin`."
|
||||
>
|
||||
> **You:** `https://git.wierzbowa.cloud/michal/ckb`
|
||||
|
||||
For *this* Cascade KB, that source repo —
|
||||
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb) —
|
||||
is the canonical, always-up-to-date copy. If you're not sure whether your
|
||||
local checkout is current, that's the place to check against.
|
||||
|
||||
From then on, "sync changes" reconciles against that remote. This is how
|
||||
multiple people share one wiki: everyone ingests/edits locally, and "sync
|
||||
changes" is how each person's changes reach everyone else — and how theirs
|
||||
reach you. Implemented by the `ckb-sync-changes` skill —
|
||||
`.agents/skills/ckb-sync-changes/SKILL.md`.
|
||||
|
||||
The agent also nudges you about this automatically: at the start and end
|
||||
of a working session it does a quick, read-only check for anything
|
||||
uncommitted or unpushed, and tells you if "sync changes" is worth running
|
||||
— it never pushes on its own without you asking.
|
||||
|
||||
### Building a shared cascade (KB-level sync)
|
||||
|
||||
If instead of *one shared wiki* you want *your own wiki that builds on
|
||||
someone else's* — e.g. your team's KB overlaying the company-wide KB — that
|
||||
isn't git sync at all; that's the `linked/`/`libs/` mounting described in
|
||||
[§1](#building-on-top-of-someone-elses-wiki). Each person/team keeps their
|
||||
own local `wiki/` (which always wins), and upstream KBs update on their own
|
||||
schedule, independently.
|
||||
|
||||
---
|
||||
|
||||
## 5. Upgrading the template
|
||||
|
||||
This is a different kind of "keeping current" from anything in
|
||||
[§4](#4-syncing--with-yourself-and-with-other-people): that section is
|
||||
about *your own KB's own remote* — sharing your content with your
|
||||
collaborators. This section is about catching your KB's *tooling* up with
|
||||
improvements made to the canonical Cascade KB template itself, wherever
|
||||
your KB originally came from (`ckb-init`, a clone, a fork, or a KB that's
|
||||
been around long enough to predate some of these conventions).
|
||||
|
||||
Say:
|
||||
|
||||
> "Upgrade the wiki." / "Check for a newer template version."
|
||||
|
||||
Two entirely separate things get checked, and either, both, or neither
|
||||
might turn something up:
|
||||
|
||||
- **The template/tooling layer** — `AGENTS.md`/`CLAUDE.md`, every skill
|
||||
under `.agents/skills/`, `LICENSE`, `VERSION`, and the `README`/`MANUAL`
|
||||
docs. Compared against the canonical repo's own `VERSION` file.
|
||||
- **Your wiki content's own schema version** — the `kb_schema_version`
|
||||
field in `wiki/index.md`, compared against what the template currently
|
||||
expects. A KB can be fully current on tooling but still carry `wiki/`
|
||||
content built years ago under an older (or entirely missing)
|
||||
`kb_schema_version` — or the reverse.
|
||||
|
||||
**If nothing's behind on either front**, you'll just get "already up to
|
||||
date — template vX, wiki schema vY," and nothing changes.
|
||||
|
||||
**If the template layer is behind**, you'll see a breakdown of what's new
|
||||
(nothing local to lose) versus what's *changed* (a template file whose
|
||||
local copy differs — which could be a genuine template improvement, or
|
||||
could be a customization you made on purpose, e.g. to `AGENTS.md`). You
|
||||
get asked, file by file or all at once, to take the template version, keep
|
||||
yours, or see the full diff first — nothing gets silently overwritten.
|
||||
|
||||
**If your wiki content's schema is behind** (including the common case of
|
||||
an older KB with no `kb_schema_version` at all — an "unversioned" wiki),
|
||||
you'll get a distinct, explicit question:
|
||||
|
||||
> **Agent:** "Your `wiki/` content was built without a `kb_schema_version`
|
||||
> (or an older one). Would you like me to also upgrade all wiki-related
|
||||
> folders and data to the new standard?"
|
||||
|
||||
If you say yes, the agent:
|
||||
- adds any missing scaffold pieces (e.g. a `wiki/graph/index.md` that
|
||||
never existed if your KB predates the graph feature),
|
||||
- backfills missing frontmatter on existing pages — `tldr`, `confidence`,
|
||||
`quality`, `retention`, and so on — **without rewriting anything you've
|
||||
actually written**; only structure and metadata get added, never the
|
||||
substance of a page,
|
||||
- confirms with you before assigning a `type` to any page where it isn't
|
||||
obvious,
|
||||
- logs every touched page in `wiki/log.md` as a migration entry so it's
|
||||
clear the change was structural, not new knowledge,
|
||||
- and bumps `kb_schema_version` once done.
|
||||
|
||||
If you say no, nothing under `wiki/` is touched at all — not even
|
||||
`kb_schema_version` — so the next time you run this, it's still correctly
|
||||
flagged as behind rather than silently considered handled. These two
|
||||
decisions (template layer, wiki content) are independent: you can accept
|
||||
one and decline the other.
|
||||
|
||||
Like Ingest and Lint, this finishes by reminding you to review the result
|
||||
and run "sync changes" against *your own* `origin` — the template repo it
|
||||
just checked against is a separate remote for any KB other than the
|
||||
template project's own working copy. Implemented by the `ckb-upgrade`
|
||||
skill — `.agents/skills/ckb-upgrade/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Use cases
|
||||
|
||||
### Ask questions
|
||||
|
||||
Just ask, in plain language:
|
||||
|
||||
> "What do we know about the Q3 migration risk?"
|
||||
|
||||
The agent reads `wiki/index.md` first to find relevant pages, checks their
|
||||
one-line `tldr` before loading the full page, walks the knowledge graph for
|
||||
connected facts, and falls back to `linked/`/`libs/` if the local wiki has
|
||||
nothing. You get an answer grounded in what's actually written down, not a
|
||||
guess.
|
||||
|
||||
### Learn from the wiki
|
||||
|
||||
**Quick test of what you know** — say:
|
||||
|
||||
> "Quiz me on the onboarding process."
|
||||
|
||||
You'll be asked how many questions and what format (open / multiple
|
||||
choice), then run through them one at a time with immediate feedback and a
|
||||
running score. Nothing is saved afterward — it's a one-off check.
|
||||
`.agents/skills/cbk-quiz/SKILL.md`.
|
||||
|
||||
**A proper course, spread over time** — say:
|
||||
|
||||
> "Teach me the wiki." / "Teach me about the supplier onboarding process."
|
||||
|
||||
The first call plans a curriculum: it asks whether you want one session or
|
||||
a series, how long each session should be and how often, and whether you'd
|
||||
like a calendar `.ics` file with reminders. It then chunks the material into
|
||||
session-sized portions (erring toward one more short session rather than
|
||||
cramming) and shows you the plan before saving anything. Later, saying
|
||||
"next lesson" (or similar) picks up where you left off, teaching using a
|
||||
different technique each time — Socratic questions, analogies, worked
|
||||
examples, teach-back, mnemonics — and briefly checking what stuck before
|
||||
moving on, re-teaching anything shaky. Plans and progress live under
|
||||
`outputs/teaching/<topic>/`. `.agents/skills/ckb-teach-me/SKILL.md`.
|
||||
|
||||
**A guided reading order without a full course** — say:
|
||||
|
||||
> "Onboard me on the payments integration." / "Where do I start with X?"
|
||||
|
||||
You get a short overview plus an ordered reading list — foundations first,
|
||||
then the topic, then what builds on it — built by walking the knowledge
|
||||
graph outward. Read-only; nothing is saved. `.agents/skills/ckb-onboard-me/SKILL.md`.
|
||||
|
||||
### Generate documents / share knowledge outside the wiki
|
||||
|
||||
**A quick top-level snapshot** — say:
|
||||
|
||||
> "Give me a project summary." / "Where do things stand?"
|
||||
|
||||
Regenerates `PROJECT-OVERVIEW.md` at the repo root: a one-to-two-page
|
||||
overview, current state, open actions with status, risks, and assumptions
|
||||
— entirely synthesised from the current wiki. It's fully overwritten each
|
||||
time, so it always reflects what the wiki says *right now*.
|
||||
`.agents/skills/ckb-project-summary/SKILL.md`.
|
||||
|
||||
**A machine-readable export for other tools** — say:
|
||||
|
||||
> "Export the wiki as OKF."
|
||||
|
||||
Produces an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
|
||||
bundle at `outputs/okf/`, consumable by generic OKF tooling (e.g. a graph
|
||||
visualiser) without needing to understand this wiki's own richer schema.
|
||||
`.agents/skills/ckb-export-okf/SKILL.md`.
|
||||
|
||||
**A human-readable documentation website** — say:
|
||||
|
||||
> "Export the wiki to Starlight." / "Build a docs site from the wiki."
|
||||
|
||||
Produces an Astro + Starlight-ready site at `outputs/starlight/` — real
|
||||
pages, real navigation, something you could host and hand to someone who's
|
||||
never seen the wiki. `.agents/skills/ckb-export-starlight/SKILL.md`.
|
||||
|
||||
**A Word doc, slide deck, or PDF from what's in the wiki** — no dedicated
|
||||
skill for this, but it's a normal ask:
|
||||
|
||||
> "Turn the wiki page on our pricing model into a one-page Word doc I can
|
||||
> send to legal."
|
||||
|
||||
The agent reads the relevant wiki page(s) and uses its general document
|
||||
skills (`docx`, `pptx`, `pdf`) to produce the file — the wiki is the source
|
||||
of truth, the document is a one-off derived artifact.
|
||||
|
||||
### Add information
|
||||
|
||||
Covered in full in [§2](#2-adding-knowledge) — the short version: drop it
|
||||
in `raw/inbox/` and say "Ingest," or just tell the agent in chat if it's
|
||||
small enough to state directly.
|
||||
|
||||
---
|
||||
|
||||
## 7. What's agent-generated vs. what you can edit
|
||||
|
||||
The short version: **the local `wiki/` always wins** in the cascade, which
|
||||
means it's *your* wiki — you're never locked out of editing it directly.
|
||||
"Agent-managed" below means the agent treats itself as responsible for
|
||||
keeping that content *structurally* correct (frontmatter, index, log,
|
||||
graph) — not that you're forbidden from touching it. If you hand-edit a
|
||||
wiki page, it's good practice to run "Lint" afterward so the index/log/
|
||||
graph stay in sync with what you changed.
|
||||
|
||||
| Location | Who normally writes it | Notes |
|
||||
|---|---|---|
|
||||
| `raw/inbox/`, loose files in `raw/` | **You, only** | The agent only reads, archives, and moves things here — it never originates content in `raw/` itself. |
|
||||
| `raw/archive/<date>/` | Agent | Auto-filed copy of what you dropped in `raw/inbox/`, organised by ingestion date. Don't hand-file here — let Ingest do it, so the date and pairing with the log entry stay accurate. |
|
||||
| `linked/<name>/` | **You** (you create the symlink) | Points at another KB's real files, which live and get edited *in that other repo* — never here. The agent must never write inside `linked/`. |
|
||||
| `libs/<name>/` | **You** (you `git clone`) | A frozen copy of an external KB. Update it by re-pulling that repo yourself, not by hand-editing files here. The agent must never write inside `libs/`. |
|
||||
| `wiki/` (pages, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Agent-generated, **you can freely edit** | This is the one place the agent both writes and expects you might too. Feel free to correct a page by hand — just keep the frontmatter fields intact (or update `last_updated`), and run Lint afterward if you touched something the index/graph/log reference. |
|
||||
| `outputs/okf/`, `outputs/starlight/` | Agent, **fully regenerated** | Don't hand-edit — these are gitignored build artifacts, silently overwritten the next time you export. If something's wrong, fix the wiki page it came from and re-export. |
|
||||
| `outputs/teaching/<topic>/` | Agent, semi-persistent state | `plan.md`/`progress.md` the teaching skill reads and writes across sessions. You can look at them any time; hand-editing is possible but may confuse "what's next" tracking — safer to tell the agent what you want changed and let it update the files. |
|
||||
| `PROJECT-OVERVIEW.md` (repo root) | Agent, **fully regenerated** | Overwritten in full each time you ask for a project summary. Don't hand-edit it — edit the wiki pages it's synthesised from instead, then regenerate. |
|
||||
| `workload/YYYY-MM-DD_summary.md` | Agent (appended each session) | A running journal of what happened each day. You can read, edit, or trim it freely — it's a log for continuity, not a machine-critical file. |
|
||||
| `AGENTS.md` / `CLAUDE.md` | **You** (rarely) | This is the system prompt that defines how the agent behaves in this repo. Edit it if you want to change a global rule — e.g. the frontmatter schema, the logging format, or the directory contract. Changes apply from the next session onward. |
|
||||
| `.agents/skills/*/SKILL.md` | **You** (advanced/optional) | Each file defines one on-demand capability. You can create new ones or edit existing ones by following the pattern of the ones already here — this isn't required for normal use, but nothing stops you. |
|
||||
| `LICENSE`, `VERSION`, `README*`, `MANUAL*` | Agent, **you can edit** | Part of the same template layer as `AGENTS.md` — kept in sync by `ckb-upgrade` when you accept a template update. `ckb-upgrade` will always ask before touching `LICENSE`'s copyright line or any of these if your local copy differs from the template's, since customization here (e.g. your own project name or license holder) is expected, not a mistake. |
|
||||
|
||||
---
|
||||
|
||||
## 8. Quick reference
|
||||
|
||||
| Say... | What happens | Skill |
|
||||
|---|---|---|
|
||||
| "Set up a new wiki like this one in \<folder\>" | Bootstraps a fresh, empty KB with this schema | `ckb-init` |
|
||||
| "Ingest" / "Sync the wiki" / "Update the wiki" | Processes `raw/inbox/` into structured `wiki/` pages | `ckb-ingest` |
|
||||
| "Lint" | Health-checks the wiki, auto-fixes what it safely can | `ckb-lint` |
|
||||
| "Sync changes" / "Sync with git" | Commits, pulls, resolves conflicts, pushes to `origin` | `ckb-sync-changes` |
|
||||
| "Quiz me on X" | One-off scored knowledge test | `cbk-quiz` |
|
||||
| "Teach me the wiki" / "Teach me about X" | Plans and runs a spaced-out course with progress tracking | `ckb-teach-me` |
|
||||
| "Onboard me on X" / "Where do I start with X" | Short guided reading order through the graph | `ckb-onboard-me` |
|
||||
| "Give me a project summary" | Regenerates `PROJECT-OVERVIEW.md` | `ckb-project-summary` |
|
||||
| "Export the wiki as OKF" | Machine-readable export at `outputs/okf/` | `ckb-export-okf` |
|
||||
| "Export the wiki to Starlight" | Human-readable docs site at `outputs/starlight/` | `ckb-export-starlight` |
|
||||
| "Upgrade the wiki" / "Check for a newer template version" | Checks template + wiki schema versions against the canonical repo, upgrades what you accept | `ckb-upgrade` |
|
||||
| Just ask a question | Answers from the wiki, using the index/TLDR/graph cascade | — (core query workflow) |
|
||||
444
MANUAL.pl.md
Normal file
444
MANUAL.pl.md
Normal file
|
|
@ -0,0 +1,444 @@
|
|||
# Podręcznik użytkownika
|
||||
|
||||
*Read this in: [English](MANUAL.md) | **Polski***
|
||||
|
||||
To jest podręcznik dla *człowieka* korzystającego z Cascade Knowledge Base
|
||||
(tego repozytorium) — nie dla agenta. Zasady działania samego agenta
|
||||
znajdziesz w [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md). Techniczny,
|
||||
funkcja-po-funkcji przegląd znajdziesz w [README.md](README.md) (lub
|
||||
[README.pl.md](README.pl.md)). Ten dokument jest zorientowany na zadania:
|
||||
„chcę zrobić X — co mam powiedzieć i co się wtedy stanie?”
|
||||
|
||||
Wszędzie poniżej „powiedz” oznacza napisanie tego do dowolnego agenta AI,
|
||||
z którego korzystasz w tym repozytorium (Claude Code lub inny agent, który
|
||||
czyta `AGENTS.md`). Nie musisz używać dokładnych sformułowań — pokazane
|
||||
frazy wyzwalające to przykłady, nie magiczne słowa; agent dopasowuje się do
|
||||
intencji.
|
||||
|
||||
---
|
||||
|
||||
## Spis treści
|
||||
|
||||
1. [Tworzenie lub inicjalizacja wiki](#1-tworzenie-lub-inicjalizacja-wiki)
|
||||
2. [Dodawanie wiedzy](#2-dodawanie-wiedzy)
|
||||
3. [Utrzymanie porządku](#3-utrzymanie-porządku)
|
||||
4. [Synchronizacja — z samym sobą i z innymi ludźmi](#4-synchronizacja--z-samym-sobą-i-z-innymi-ludźmi)
|
||||
5. [Aktualizacja szablonu](#5-aktualizacja-szablonu)
|
||||
6. [Przykłady użycia](#6-przykłady-użycia)
|
||||
7. [Co jest generowane przez agenta, a co możesz edytować](#7-co-jest-generowane-przez-agenta-a-co-możesz-edytować)
|
||||
8. [Szybki przegląd](#8-szybki-przegląd)
|
||||
|
||||
---
|
||||
|
||||
## 1. Tworzenie lub inicjalizacja wiki
|
||||
|
||||
### Jeśli czytasz to wewnątrz istniejącej Cascade KB
|
||||
|
||||
Nie musisz nic robić — struktura już istnieje (`wiki/`, `raw/`, `outputs/`
|
||||
itd.). Przejdź do [§2](#2-dodawanie-wiedzy).
|
||||
|
||||
### Zakładanie zupełnie nowej wiki gdzie indziej
|
||||
|
||||
Powiedz:
|
||||
|
||||
> „Set up a new wiki like this one in `~/projects/my-notes`.”
|
||||
|
||||
To sklonuje wyłącznie *schemat* — strukturę katalogów, plik zachowań
|
||||
`AGENTS.md`/`CLAUDE.md` oraz pusty szkielet `wiki/` — do docelowego folderu.
|
||||
Nigdy nie kopiuje rzeczywistej zawartości tego projektu (żadnych encji,
|
||||
danych grafu, notatek). Otrzymujesz świeżą, pustą KB, gotową na pierwszy
|
||||
zrzut do `raw/inbox/`. Zobacz `.agents/skills/ckb-init/SKILL.md`.
|
||||
|
||||
Jeśli docelowy folder wygląda już jak baza wiedzy (ma `wiki/` lub
|
||||
`AGENTS.md`), agent zatrzyma się i zapyta, zanim czegokolwiek dotknie — nie
|
||||
nadpisze po cichu istniejącej bazy wiedzy.
|
||||
|
||||
### Budowanie na bazie cudzej wiki
|
||||
|
||||
Cascade KB może opierać się na jednej lub wielu *nadrzędnych* bazach
|
||||
wiedzy, które pozostają całkowicie tylko do odczytu. Są dwa sposoby ich
|
||||
podpięcia:
|
||||
|
||||
- **Dowiązanie symboliczne** (inna KB na twojej maszynie, lub taka, którą
|
||||
utrzymujesz gdzie indziej i chcesz mieć „na żywo”):
|
||||
```bash
|
||||
ln -s /path/to/other-kb ./linked/other-team
|
||||
```
|
||||
- **Kopia git** (zewnętrzna KB, której chcesz mieć zamrożoną, wersjonowaną
|
||||
kopię):
|
||||
```bash
|
||||
git clone https://github.com/org/external-kb ./libs/external-kb
|
||||
```
|
||||
|
||||
Niezależnie od sposobu, po podpięciu wystarczy normalnie zadawać pytania —
|
||||
agent sprawdza najpierw twoją lokalną `wiki/`, potem przechodzi przez
|
||||
`linked/`, potem `libs/`, i korzysta z tego, co ma odpowiedź. Nigdy nie
|
||||
edytujesz plików wewnątrz `linked/` ani `libs/` bezpośrednio; jeśli coś tam
|
||||
jest błędne lub nieaktualne, poprawiasz to, zapisując poprawioną wersję we
|
||||
własnej lokalnej `wiki/`, która zawsze wygrywa.
|
||||
|
||||
---
|
||||
|
||||
## 2. Dodawanie wiedzy
|
||||
|
||||
To główny sposób, w jaki rośnie wiki. Są dwie drogi:
|
||||
|
||||
### A. Wrzuć materiał, potem powiedz „Ingest”
|
||||
|
||||
Umieść cokolwiek nieprzetworzonego w `raw/inbox/` — wklejone notatki, plik
|
||||
`.txt` z transkrypcją, `links.txt` z adresami URL, PDF, chaotyczny plik
|
||||
roboczy. Nie musisz go najpierw porządkować. Następnie powiedz:
|
||||
|
||||
> „Ingest.” (lub „Sync the wiki” / „Update the wiki” — to samo)
|
||||
|
||||
Przykład:
|
||||
|
||||
> *Wrzucasz `meeting-2026-07-10.txt` (surowe notatki z rozmowy z klientem)
|
||||
> do `raw/inbox/`, potem mówisz „Ingest.”*
|
||||
>
|
||||
> Agent czyta plik, wydobywa wymienione osoby, decyzje i otwarte pytania,
|
||||
> tworzy lub aktualizuje strony encji w `wiki/entities/`, zapisuje relacje
|
||||
> w `wiki/graph/edges.json`, dodaje nowe strony do `wiki/index.md`, loguje
|
||||
> zmianę w `wiki/log.md` i przenosi oryginalny plik do
|
||||
> `raw/archive/2026-07-10/`. Na koniec przypomina o przejrzeniu wyniku i
|
||||
> powiedzeniu „sync changes”, gdy będziesz zadowolony.
|
||||
|
||||
Jeśli `raw/inbox/` jest puste, agent skanuje bezpośrednio `raw/` (nadal
|
||||
pomijając `raw/archive/`, które zawiera już przetworzoną historię).
|
||||
|
||||
Zaimplementowane przez skill `ckb-ingest` —
|
||||
`.agents/skills/ckb-ingest/SKILL.md`.
|
||||
|
||||
### B. Po prostu powiedz agentowi coś w rozmowie
|
||||
|
||||
Nie zawsze potrzebujesz pliku. Jeśli powiesz agentowi fakt wart zachowania
|
||||
— „właściwie to termin przesunął się na wrzesień” — i ma on trwałą
|
||||
wartość, agent może zapisać go bezpośrednio do `wiki/` jako nową stronę lub
|
||||
aktualizację istniejącej, tak samo jak z zaingestowanego pliku.
|
||||
|
||||
### C. Pozwól agentowi powiedzieć, czego brakuje (Demand-Driven Context)
|
||||
|
||||
Jeśli zapytasz o coś, na co wiki nie potrafi odpowiedzieć, agent nie
|
||||
zawiedzie po cichu — zidentyfikuje lukę i zaproponuje minimalną stronę,
|
||||
która ją wypełni.
|
||||
|
||||
Przykład:
|
||||
|
||||
> **Ty:** „Jaka jest nasza polityka w sprawie X?”
|
||||
> **Agent:** „Wiki jeszcze tego nie pokrywa. Chcesz, żebym dodał zalążek
|
||||
> strony, czy możesz wkleić/opisać tę politykę, a ja ją spiszę?”
|
||||
|
||||
Zatwierdzasz, wklejasz źródło albo wrzucasz je do `raw/inbox/` — kolejny
|
||||
ingest to wchłonie. Dzięki temu wiki pozostaje napędzana zapotrzebowaniem:
|
||||
rośnie wokół tego, o co faktycznie pytasz, a nie wokół wszystkiego, co
|
||||
teoretycznie dałoby się spisać.
|
||||
|
||||
---
|
||||
|
||||
## 3. Utrzymanie porządku
|
||||
|
||||
Powiedz, kiedy chcesz (nie ma sztywnego harmonogramu — zrób to po dużym
|
||||
ingest lub po prostu okresowo):
|
||||
|
||||
> „Lint.”
|
||||
|
||||
To uruchamia przegląd kondycji całej wiki:
|
||||
|
||||
- strony bez wymaganego frontmatteru (`type`) są oflagowywane
|
||||
- strony nietykane od dłuższego czasu są oflagowywane jako nieaktualne
|
||||
- wyniki pewności (confidence) zanikają, jeśli nic ostatnio ich nie
|
||||
wzmocniło
|
||||
- stare, niskopriorytetowe strony są archiwizowane do `wiki/archived/`
|
||||
(nigdy usuwane)
|
||||
- sprzeczne strony są łączone stare→nowe (supersesja)
|
||||
- osierocone strony (nic do nich nie linkuje) dostają odnośniki zwrotne
|
||||
albo są archiwizowane
|
||||
- uszkodzone krawędzie grafu są naprawiane lub usuwane
|
||||
- brakujące/podwójne wpisy w indeksie i dzienniku są poprawiane
|
||||
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`
|
||||
|
||||
Naprawia samodzielnie to, co może zrobić bezpiecznie, a resztę zgłasza do
|
||||
twojej decyzji. Podobnie jak Ingest, na koniec przypomina o przejrzeniu i
|
||||
synchronizacji. Zaimplementowane przez skill `ckb-lint` —
|
||||
`.agents/skills/ckb-lint/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Synchronizacja — z samym sobą i z innymi ludźmi
|
||||
|
||||
Są tu dwa zupełnie różne rodzaje „synchronizacji” — nie myl ich:
|
||||
|
||||
| | Ingest / Lint | Sync changes |
|
||||
|---|---|---|
|
||||
| **Warstwa** | Treść (co wiki wie) | Git (czyj dysk ma jakie pliki) |
|
||||
| **Czego dotyczy** | `wiki/`, `raw/` | Historia commitów repo i zdalne repozytorium `origin` |
|
||||
| **Powiedz** | „Ingest” / „Lint” | „Sync changes” |
|
||||
|
||||
### Uzgadnianie z `origin` (synchronizacja na poziomie gita)
|
||||
|
||||
Powiedz:
|
||||
|
||||
> „Sync changes.”
|
||||
|
||||
To commituje wszelkie lokalne zmiany (np. z ostatniego Ingest lub Lint),
|
||||
pobiera wszystko nowe z `origin`, scala oba, a jeśli pojawi się konflikt —
|
||||
przeprowadza cię przez niego plik po pliku, pytając, czy zachować twoją
|
||||
wersję, wersję zdalną, czy podać scaloną treść dla każdego konfliktowego
|
||||
fragmentu. Gdy wszystko jest rozwiązane, wypycha zmiany (push).
|
||||
|
||||
Jeśli to repozytorium nigdy nie było połączone ze zdalnym, agent najpierw
|
||||
poprosi cię o wklejenie adresu URL:
|
||||
|
||||
> **Agent:** „To repozytorium nie ma skonfigurowanego zdalnego `origin`.
|
||||
> Wklej adres URL zdalnego repozytorium, a dodam je jako `origin`.”
|
||||
>
|
||||
> **Ty:** `https://git.wierzbowa.cloud/michal/ckb`
|
||||
|
||||
Dla *tej* Cascade KB tym repozytorium źródłowym —
|
||||
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb) —
|
||||
jest kanoniczna, zawsze aktualna kopia. Jeśli nie masz pewności, czy twoja
|
||||
lokalna kopia jest aktualna, to właśnie tam warto to sprawdzić.
|
||||
|
||||
Od tej pory „sync changes” uzgadnia stan właśnie z tym zdalnym
|
||||
repozytorium. Tak dzieli się jedną wiki między wieloma osobami: każdy
|
||||
robi ingest/edycje lokalnie, a „sync changes” to sposób, w jaki zmiany
|
||||
każdej osoby docierają do reszty — i jak zmiany innych docierają do ciebie.
|
||||
Zaimplementowane przez skill `ckb-sync-changes` —
|
||||
`.agents/skills/ckb-sync-changes/SKILL.md`.
|
||||
|
||||
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.
|
||||
|
||||
### Budowanie współdzielonej kaskady (synchronizacja na poziomie KB)
|
||||
|
||||
Jeśli zamiast *jednej współdzielonej wiki* chcesz mieć *własną wiki, która
|
||||
buduje na cudzej* — np. wiki twojego zespołu nadbudowana na
|
||||
ogólnofirmowej KB — to w ogóle nie jest synchronizacja gita; to podpięcie
|
||||
`linked/`/`libs/` opisane w
|
||||
[§1](#budowanie-na-bazie-cudzej-wiki). Każda osoba/zespół utrzymuje własną
|
||||
lokalną `wiki/` (która zawsze wygrywa), a nadrzędne bazy wiedzy aktualizują
|
||||
się według własnego harmonogramu, niezależnie.
|
||||
|
||||
---
|
||||
|
||||
## 5. Aktualizacja szablonu
|
||||
|
||||
To inny rodzaj „bycia na bieżąco” niż wszystko w
|
||||
[§4](#4-synchronizacja--z-samym-sobą-i-z-innymi-ludźmi): tamta sekcja
|
||||
dotyczy *zdalnego repozytorium twojej własnej KB* — dzielenia się twoją
|
||||
zawartością ze współpracownikami. Ta sekcja dotyczy nadganiania *narzędzi*
|
||||
twojej KB względem ulepszeń wprowadzonych w samym kanonicznym szablonie
|
||||
Cascade KB, niezależnie skąd twoja KB pierwotnie pochodzi (`ckb-init`,
|
||||
klon, fork, albo KB, która istnieje wystarczająco długo, by poprzedzać
|
||||
niektóre z tych konwencji).
|
||||
|
||||
Powiedz:
|
||||
|
||||
> „Upgrade the wiki.” / „Check for a newer template version.”
|
||||
|
||||
Sprawdzane są dwie zupełnie odrębne rzeczy, i każda, obie albo żadna może
|
||||
coś wykazać:
|
||||
|
||||
- **Warstwa szablonu/narzędzi** — `AGENTS.md`/`CLAUDE.md`, każdy skill pod
|
||||
`.agents/skills/`, `LICENSE`, `VERSION` oraz dokumenty
|
||||
`README`/`MANUAL`. Porównywana z plikiem `VERSION` samego kanonicznego
|
||||
repozytorium.
|
||||
- **Własna wersja schematu twojej treści wiki** — pole `kb_schema_version`
|
||||
w `wiki/index.md`, porównywane z tym, czego obecnie oczekuje szablon. KB
|
||||
może być w pełni aktualna pod względem narzędzi, ale nadal nosić treść
|
||||
`wiki/` zbudowaną lata temu pod starszym (albo w ogóle brakującym)
|
||||
`kb_schema_version` — albo odwrotnie.
|
||||
|
||||
**Jeśli nic nie jest opóźnione na żadnym froncie**, dostaniesz po prostu
|
||||
„już aktualne — szablon vX, schemat wiki vY” i nic się nie zmieni.
|
||||
|
||||
**Jeśli warstwa szablonu jest opóźniona**, zobaczysz podział na to, co
|
||||
nowe (nic lokalnego do stracenia) i to, co *zmienione* (plik szablonu,
|
||||
którego lokalna kopia różni się — co może być prawdziwym ulepszeniem
|
||||
szablonu, albo celową customizacją, którą zrobiłeś, np. w `AGENTS.md`).
|
||||
Zostaniesz zapytany, plik po pliku albo wszystko naraz, czy wziąć wersję
|
||||
szablonu, zachować swoją, czy najpierw zobaczyć pełną różnicę — nic nie
|
||||
zostanie po cichu nadpisane.
|
||||
|
||||
**Jeśli schemat twojej treści wiki jest opóźniony** (w tym częsty przypadek
|
||||
starszej KB bez żadnego `kb_schema_version` — „niewersjonowanej” wiki),
|
||||
dostaniesz odrębne, wyraźne pytanie:
|
||||
|
||||
> **Agent:** „Twoja treść `wiki/` została zbudowana bez
|
||||
> `kb_schema_version` (lub ze starszą wersją). Czy chciałbyś, żebym
|
||||
> zaktualizował też wszystkie foldery i dane związane z wiki do nowego
|
||||
> standardu?”
|
||||
|
||||
Jeśli powiesz tak, agent:
|
||||
- dodaje wszelkie brakujące elementy szkieletu (np. `wiki/graph/index.md`,
|
||||
który nigdy nie istniał, jeśli twoja KB poprzedza funkcję grafu),
|
||||
- uzupełnia brakujący frontmatter na istniejących stronach — `tldr`,
|
||||
`confidence`, `quality`, `retention` i tak dalej — **bez przepisywania
|
||||
czegokolwiek, co faktycznie napisałeś**; dodawana jest tylko struktura i
|
||||
metadane, nigdy treść merytoryczna strony,
|
||||
- potwierdza z tobą, zanim przypisze `type` do jakiejkolwiek strony, gdzie
|
||||
nie jest to oczywiste,
|
||||
- loguje każdą dotkniętą stronę w `wiki/log.md` jako wpis migracyjny, żeby
|
||||
było jasne, że zmiana była strukturalna, a nie nową wiedzą,
|
||||
- i podnosi `kb_schema_version`, gdy skończy.
|
||||
|
||||
Jeśli powiesz nie, nic pod `wiki/` nie zostanie dotknięte w ogóle — nawet
|
||||
`kb_schema_version` — więc następnym razem, gdy to uruchomisz, nadal
|
||||
zostanie to poprawnie oflagowane jako opóźnione, zamiast po cichu uznane
|
||||
za załatwione. Te dwie decyzje (warstwa szablonu, treść wiki) są
|
||||
niezależne: możesz zaakceptować jedną i odrzucić drugą.
|
||||
|
||||
Podobnie jak Ingest i Lint, na koniec pojawia się przypomnienie o
|
||||
przejrzeniu wyniku i uruchomieniu „sync changes” względem *twojego
|
||||
własnego* `origin` — repozytorium szablonu, z którym właśnie porównano,
|
||||
jest zwykle osobnym zdalnym repozytorium dla każdej KB innej niż własna
|
||||
kopia robocza projektu szablonu. Zaimplementowane przez skill
|
||||
`ckb-upgrade` — `.agents/skills/ckb-upgrade/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Przykłady użycia
|
||||
|
||||
### Zadawanie pytań
|
||||
|
||||
Po prostu zapytaj, zwykłym językiem:
|
||||
|
||||
> „Co wiemy o ryzyku migracji w Q3?”
|
||||
|
||||
Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony,
|
||||
sprawdza ich jednolinijkowy `tldr` przed załadowaniem pełnej strony,
|
||||
przechodzi po grafie wiedzy w poszukiwaniu powiązanych faktów i sięga do
|
||||
`linked/`/`libs/`, jeśli lokalna wiki nic nie ma. Dostajesz odpowiedź
|
||||
opartą na tym, co faktycznie zostało spisane, a nie na domysłach.
|
||||
|
||||
### Nauka z wiki
|
||||
|
||||
**Szybki test tego, co wiesz** — powiedz:
|
||||
|
||||
> „Quiz me on the onboarding process.”
|
||||
|
||||
Zostaniesz zapytany o liczbę pytań i format (otwarte / jednokrotnego
|
||||
wyboru), a następnie przejdziesz przez nie jedno po drugim, z natychmiastową
|
||||
informacją zwrotną i bieżącym wynikiem. Nic nie jest zapisywane potem — to
|
||||
jednorazowy sprawdzian. `.agents/skills/cbk-quiz/SKILL.md`.
|
||||
|
||||
**Prawdziwy kurs, rozłożony w czasie** — powiedz:
|
||||
|
||||
> „Teach me the wiki.” / „Teach me about the supplier onboarding process.”
|
||||
|
||||
Pierwsze wywołanie planuje program nauczania: pyta, czy chcesz jedną
|
||||
sesję czy serię, jak długa ma być każda sesja i jak często, oraz czy
|
||||
chciałbyś plik kalendarza `.ics` z przypomnieniami. Następnie dzieli
|
||||
materiał na porcje wielkości sesji (wolą jedną dodatkową krótką sesję niż
|
||||
upychanie materiału) i pokazuje ci plan, zanim cokolwiek zapisze. Później
|
||||
powiedzenie „next lesson” (lub podobnie) podejmuje naukę tam, gdzie
|
||||
skończyłeś, ucząc za każdym razem inną techniką — pytania sokratejskie,
|
||||
analogie, przykłady rozwiązane krok po kroku, „naucz mnie z powrotem”,
|
||||
mnemotechniki — i krótko sprawdzając, co zostało w pamięci, zanim przejdzie
|
||||
dalej, powtarzając to, co niepewne. Plany i postępy żyją w
|
||||
`outputs/teaching/<topic>/`. `.agents/skills/ckb-teach-me/SKILL.md`.
|
||||
|
||||
**Prowadzona kolejność czytania bez pełnego kursu** — powiedz:
|
||||
|
||||
> „Onboard me on the payments integration.” / „Where do I start with X?”
|
||||
|
||||
Dostajesz krótki przegląd plus uporządkowaną listę do przeczytania —
|
||||
najpierw podstawy, potem sam temat, potem to, co się na nim opiera —
|
||||
zbudowaną przez przejście po grafie wiedzy na zewnątrz. Tylko do odczytu;
|
||||
nic nie jest zapisywane. `.agents/skills/ckb-onboard-me/SKILL.md`.
|
||||
|
||||
### Generowanie dokumentów / dzielenie się wiedzą poza wiki
|
||||
|
||||
**Szybki skrót najwyższego poziomu** — powiedz:
|
||||
|
||||
> „Give me a project summary.” / „Where do things stand?”
|
||||
|
||||
Regeneruje `PROJECT-OVERVIEW.md` w katalogu głównym repozytorium: jedno-
|
||||
lub dwustronicowy przegląd, bieżący stan, otwarte działania ze statusem,
|
||||
ryzyka i założenia — w całości zsyntetyzowane z aktualnej wiki. Jest za
|
||||
każdym razem nadpisywany w całości, więc zawsze odzwierciedla to, co wiki
|
||||
mówi *teraz*. `.agents/skills/ckb-project-summary/SKILL.md`.
|
||||
|
||||
**Eksport maszynowy dla innych narzędzi** — powiedz:
|
||||
|
||||
> „Export the wiki as OKF.”
|
||||
|
||||
Tworzy pakiet [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
|
||||
w `outputs/okf/`, możliwy do skonsumowania przez ogólne narzędzia OKF (np.
|
||||
wizualizator grafu), bez potrzeby rozumienia bogatszego, własnego schematu
|
||||
tej wiki. `.agents/skills/ckb-export-okf/SKILL.md`.
|
||||
|
||||
**Czytelna dla człowieka strona dokumentacji** — powiedz:
|
||||
|
||||
> „Export the wiki to Starlight.” / „Build a docs site from the wiki.”
|
||||
|
||||
Tworzy gotową do uruchomienia stronę Astro + Starlight w
|
||||
`outputs/starlight/` — prawdziwe strony, prawdziwą nawigację, coś, co
|
||||
możesz hostować i dać komuś, kto nigdy nie widział wiki.
|
||||
`.agents/skills/ckb-export-starlight/SKILL.md`.
|
||||
|
||||
**Dokument Word, prezentacja lub PDF z zawartości wiki** — nie ma
|
||||
dedykowanego skilla do tego, ale to normalna prośba:
|
||||
|
||||
> „Turn the wiki page on our pricing model into a one-page Word doc I can
|
||||
> send to legal.”
|
||||
|
||||
Agent czyta odpowiednie strony wiki i używa swoich ogólnych umiejętności
|
||||
tworzenia dokumentów (`docx`, `pptx`, `pdf`), aby wytworzyć plik — wiki
|
||||
pozostaje źródłem prawdy, dokument jest jednorazowym, pochodnym
|
||||
artefaktem.
|
||||
|
||||
### Dodawanie informacji
|
||||
|
||||
W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał do
|
||||
`raw/inbox/` i powiedz „Ingest”, albo po prostu powiedz agentowi w
|
||||
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
|
||||
|
||||
---
|
||||
|
||||
## 7. Co jest generowane przez agenta, a co możesz edytować
|
||||
|
||||
Krótka wersja: **lokalna `wiki/` zawsze wygrywa** w kaskadzie, co oznacza,
|
||||
że to *twoja* wiki — nigdy nie jesteś zablokowany przed jej bezpośrednią
|
||||
edycją. „Zarządzane przez agenta” poniżej oznacza, że agent traktuje się
|
||||
jako odpowiedzialnego za utrzymanie tej treści *strukturalnie* poprawną
|
||||
(frontmatter, indeks, dziennik, graf) — a nie że nie wolno ci jej dotykać.
|
||||
Jeśli ręcznie edytujesz stronę wiki, dobrą praktyką jest uruchomienie
|
||||
potem „Lint”, żeby indeks/dziennik/graf pozostały spójne z tym, co
|
||||
zmieniłeś.
|
||||
|
||||
| Lokalizacja | Kto zwykle to zapisuje | Uwagi |
|
||||
|---|---|---|
|
||||
| `raw/inbox/`, luźne pliki w `raw/` | **Tylko ty** | Agent tylko czyta, archiwizuje i przenosi rzeczy tutaj — nigdy nie tworzy treści w `raw/` sam. |
|
||||
| `raw/archive/<data>/` | Agent | Automatycznie zarchiwizowana kopia tego, co wrzuciłeś do `raw/inbox/`, uporządkowana według daty ingestu. Nie umieszczaj tu plików ręcznie — pozwól, żeby zrobił to Ingest, tak by data i powiązanie z wpisem w dzienniku były poprawne. |
|
||||
| `linked/<name>/` | **Ty** (tworzysz dowiązanie symboliczne) | Wskazuje na rzeczywiste pliki innej KB, które żyją i są edytowane *w tamtym repozytorium* — nigdy tutaj. Agent nigdy nie może zapisywać wewnątrz `linked/`. |
|
||||
| `libs/<name>/` | **Ty** (robisz `git clone`) | Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz `libs/`. |
|
||||
| `wiki/` (strony, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Generowane przez agenta, **możesz swobodnie edytować** | To jedyne miejsce, w którym zarówno agent zapisuje, jak i spodziewa się, że ty też możesz. Śmiało popraw stronę ręcznie — zachowaj tylko pola frontmatteru (lub zaktualizuj `last_updated`) i uruchom potem Lint, jeśli dotknąłeś czegoś, do czego odwołuje się indeks/graf/dziennik. |
|
||||
| `outputs/okf/`, `outputs/starlight/` | Agent, **w pełni regenerowane** | Nie edytuj ręcznie — to zignorowane przez git artefakty budowania, cicho nadpisywane przy każdym kolejnym eksporcie. Jeśli coś jest nie tak, popraw stronę wiki, z której to pochodzi, i wyeksportuj ponownie. |
|
||||
| `outputs/teaching/<topic>/` | Agent, stan półtrwały | `plan.md`/`progress.md`, które skill do nauczania czyta i zapisuje między sesjami. Możesz je oglądać kiedy chcesz; ręczna edycja jest możliwa, ale może pomieszać śledzenie „co dalej” — bezpieczniej powiedzieć agentowi, co chcesz zmienić, i pozwolić mu zaktualizować pliki. |
|
||||
| `PROJECT-OVERVIEW.md` (katalog główny) | Agent, **w pełni regenerowany** | Nadpisywany w całości za każdym razem, gdy poprosisz o podsumowanie projektu. Nie edytuj go ręcznie — edytuj strony wiki, z których jest syntetyzowany, a potem zregeneruj. |
|
||||
| `workload/YYYY-MM-DD_summary.md` | Agent (dopisywane co sesję) | Bieżący dziennik tego, co działo się każdego dnia. Możesz go swobodnie czytać, edytować lub skracać — to dziennik dla ciągłości, a nie plik krytyczny dla działania systemu. |
|
||||
| `AGENTS.md` / `CLAUDE.md` | **Ty** (rzadko) | To prompt systemowy, który definiuje zachowanie agenta w tym repozytorium. Edytuj go, jeśli chcesz zmienić globalną zasadę — np. schemat frontmatteru, format logowania czy kontrakt katalogów. Zmiany obowiązują od kolejnej sesji. |
|
||||
| `.agents/skills/*/SKILL.md` | **Ty** (zaawansowane/opcjonalne) | Każdy plik definiuje jedną możliwość na żądanie. Możesz tworzyć nowe albo edytować istniejące, wzorując się na tych, które już tu są — to nie jest wymagane do normalnego użytku, ale nic ci w tym nie przeszkadza. |
|
||||
| `LICENSE`, `VERSION`, `README*`, `MANUAL*` | Agent, **możesz edytować** | Część tej samej warstwy szablonu co `AGENTS.md` — utrzymywane w synchronizacji przez `ckb-upgrade`, gdy zaakceptujesz aktualizację szablonu. `ckb-upgrade` zawsze zapyta, zanim dotknie linii praw autorskich w `LICENSE` albo któregokolwiek z tych plików, jeśli twoja lokalna kopia różni się od szablonu — customizacja tutaj (np. własna nazwa projektu czy posiadacz licencji) jest oczekiwana, nie jest błędem. |
|
||||
|
||||
---
|
||||
|
||||
## 8. Szybki przegląd
|
||||
|
||||
| Powiedz... | Co się dzieje | Skill |
|
||||
|---|---|---|
|
||||
| „Set up a new wiki like this one in \<folder\>” | Zakłada świeżą, pustą KB z tym schematem | `ckb-init` |
|
||||
| „Ingest” / „Sync the wiki” / „Update the wiki” | Przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` | `ckb-ingest` |
|
||||
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |
|
||||
| „Sync changes” / „Sync with git” | Commituje, pobiera, rozwiązuje konflikty, wypycha do `origin` | `ckb-sync-changes` |
|
||||
| „Quiz me on X” | Jednorazowy, punktowany sprawdzian wiedzy | `cbk-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` |
|
||||
| „Give me a project summary” | Regeneruje `PROJECT-OVERVIEW.md` | `ckb-project-summary` |
|
||||
| „Export the wiki as OKF” | Eksport maszynowy w `outputs/okf/` | `ckb-export-okf` |
|
||||
| „Export the wiki to Starlight” | Czytelna dla człowieka strona dokumentacji w `outputs/starlight/` | `ckb-export-starlight` |
|
||||
| „Upgrade the wiki” / „Check for a newer template version” | Sprawdza wersje szablonu i schematu wiki względem kanonicznego repozytorium, aktualizuje to, co zaakceptujesz | `ckb-upgrade` |
|
||||
| Po prostu zadaj pytanie | Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf | — (podstawowy przepływ zapytań) |
|
||||
72
README.md
72
README.md
|
|
@ -1,9 +1,19 @@
|
|||
# Cascade Knowledge Base
|
||||
|
||||
*Read this in: **English** | [Polski](README.pl.md)*
|
||||
|
||||
**Source repo (always the most up-to-date version):**
|
||||
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb)
|
||||
|
||||
A layered, agent-managed wiki where local content overlays read-only upstream
|
||||
sources. Built on Karpathy's LLM Wiki pattern with extensions for scaling,
|
||||
lifecycle management, and multi-agent support.
|
||||
|
||||
This document is a technical feature overview. For a task-oriented guide —
|
||||
how to create a wiki, add knowledge, keep it tidy, sync with others, and
|
||||
worked examples for every use case — see [MANUAL.md](MANUAL.md)
|
||||
([Polski](MANUAL.pl.md)).
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
|
@ -48,8 +58,15 @@ write the right version in `wiki/` — it takes precedence automatically.
|
|||
|
||||
### Inbox-Driven Workflow
|
||||
Drop any raw material (notes, articles, links) into `raw/inbox/` without
|
||||
organizing. On "Ingest", the agent processes the inbox — extracts knowledge,
|
||||
files it into `wiki/`, and archives processed items to `raw/`.
|
||||
organizing. On "Ingest" (or "Sync the wiki" / "Update the wiki"), the agent
|
||||
processes the inbox — extracts knowledge, files it into `wiki/`, and
|
||||
archives processed items to `raw/` — then reminds you to review the result
|
||||
and run "sync changes" to push it to `origin` once you're happy with it.
|
||||
Implemented as a Claude Code Skill — see
|
||||
`.agents/skills/ckb-ingest/SKILL.md` — rather than baked into
|
||||
`CLAUDE.md`/`AGENTS.md`, so the full procedure only loads into context when
|
||||
actually invoked. Distinct from the `ckb-sync-changes` skill, which is a
|
||||
pure git-level operation with no wiki synthesis.
|
||||
|
||||
### Lazy-Loading Index with "Use When" Triggers
|
||||
`wiki/index.md` is a routing table. Each entry has a **Use when** column
|
||||
|
|
@ -127,7 +144,12 @@ Periodically (or on demand), the agent health-checks the wiki:
|
|||
- **Index/log consistency** — verifies every subdirectory has an index.md and no change is double-logged
|
||||
- **Error Book** — records systemic issues with root cause and fix
|
||||
|
||||
Auto-fixes what it can (broken links, missing backlinks, stale flags).
|
||||
Auto-fixes what it can (broken links, missing backlinks, stale flags), and
|
||||
reminds you to review the result and run "sync changes" to push it to
|
||||
`origin` once you're happy with it. Implemented as a Claude Code Skill —
|
||||
see `.agents/skills/ckb-lint/SKILL.md` — rather than baked into
|
||||
`CLAUDE.md`/`AGENTS.md`, so the full checklist only loads into context when
|
||||
actually invoked.
|
||||
|
||||
### Conflict Resolution (Supersession)
|
||||
When new information contradicts an existing page, the agent adds
|
||||
|
|
@ -148,8 +170,12 @@ reusable constraint to prevent recurrence. Two-layer repair:
|
|||
|
||||
### Automation Hooks
|
||||
- **New source** → auto-ingest on next "Ingest" command
|
||||
- **Session start** → load index + latest workload summary
|
||||
- **Session end** → compress observations into workload/
|
||||
- **Session start** → load index + latest workload summary; check for
|
||||
unsynchronized changes (uncommitted work, or ahead/behind `origin`) and
|
||||
suggest `ckb-sync-changes` if any are found
|
||||
- **Session end** → compress observations into workload/; re-check for
|
||||
unsynchronized changes (including anything the session itself just
|
||||
created) and suggest `ckb-sync-changes` if needed
|
||||
- **Query** → file back valuable answers as wiki pages
|
||||
- **Memory write** → check contradictions, trigger supersession
|
||||
- **Schedule** → periodic lint, consolidation, retention decay
|
||||
|
|
@ -225,6 +251,29 @@ implemented as a Claude Code Skill — see
|
|||
content-level "Sync the wiki" / "Ingest" workflow, which processes
|
||||
`raw/inbox/` into structured `wiki/` pages and has nothing to do with git.
|
||||
|
||||
### Quiz Mode (on demand)
|
||||
Ask to be quizzed on the wiki ("quiz me on X", "test my knowledge") for a
|
||||
one-off, scored knowledge check: the agent reads the relevant pages,
|
||||
generates open or multiple-choice questions grounded in specific wiki
|
||||
facts, runs them one at a time with immediate feedback and a running
|
||||
score, and closes with a verdict. Stateless — nothing is saved between
|
||||
runs. See `.agents/skills/cbk-quiz/SKILL.md`.
|
||||
|
||||
### Guided Teaching Curriculum (on demand)
|
||||
Ask to be taught the wiki ("teach me the wiki", "teach me about X", "run a
|
||||
teaching session") for a stateful course rather than a one-off quiz. First
|
||||
call plans it: scopes the material (optionally supplementing thin spots
|
||||
from the web, clearly marked as non-authoritative), asks whether it should
|
||||
be one session or a spaced series (duration, frequency, optional calendar
|
||||
`.ics` reminders), chunks the content into session-sized portions —
|
||||
preferring an extra session over cramming — and saves the accepted plan
|
||||
and a progress tracker to `outputs/teaching/<topic>/`. Later calls compare
|
||||
plan against progress, teach the next portion using a different technique
|
||||
each time (Socratic questioning, analogies, worked examples, teach-back,
|
||||
mnemonics, ...), spot-check retention, and re-teach weak spots before
|
||||
advancing. Never writes to `wiki/`. See
|
||||
`.agents/skills/ckb-teach-me/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
|
@ -274,5 +323,14 @@ copy to keep in sync.
|
|||
tracked, but its regenerated build subdirectories, `outputs/okf/` and
|
||||
`outputs/starlight/`, are gitignored — each is fully reproducible from
|
||||
`wiki/` on demand, so there's nothing to reconcile by carrying it in git
|
||||
history. Commit other, hand-maintained artifacts under `outputs/` as
|
||||
normal.
|
||||
history. `outputs/teaching/` (per-user learning plans and session
|
||||
progress from the teaching skill) is also gitignored, since it's
|
||||
personal session state rather than shared KB content. Commit other,
|
||||
hand-maintained artifacts under `outputs/` as normal.
|
||||
|
||||
---
|
||||
|
||||
## Version & License
|
||||
|
||||
Current template version: [VERSION](VERSION). Licensed under the
|
||||
[Apache License 2.0](LICENSE).
|
||||
|
|
|
|||
384
README.pl.md
Normal file
384
README.pl.md
Normal file
|
|
@ -0,0 +1,384 @@
|
|||
# Cascade Knowledge Base
|
||||
|
||||
*Read this in: [English](README.md) | **Polski***
|
||||
|
||||
**Repozytorium źródłowe (zawsze najbardziej aktualna wersja):**
|
||||
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb)
|
||||
|
||||
Warstwowa, zarządzana przez agenta wiki, w której lokalna zawartość nadpisuje
|
||||
tylko-do-odczytu źródła nadrzędne (upstream). Zbudowana na wzorcu LLM Wiki
|
||||
Karpathy'ego, rozszerzonym o skalowanie, zarządzanie cyklem życia i wsparcie
|
||||
dla wielu agentów.
|
||||
|
||||
Ten dokument to techniczny przegląd funkcji. Zorientowany na zadania
|
||||
przewodnik — jak stworzyć wiki, dodawać wiedzę, utrzymywać porządek,
|
||||
synchronizować się z innymi i przykłady dla każdego przypadku użycia —
|
||||
znajdziesz w [MANUAL.pl.md](MANUAL.pl.md) ([English](MANUAL.md)).
|
||||
|
||||
---
|
||||
|
||||
## Struktura katalogów
|
||||
|
||||
```
|
||||
├── libs/ # Zewnętrzne bazy wiedzy tylko do odczytu, kopiowane przez git (w .gitignore)
|
||||
├── linked/ # Zewnętrzne bazy wiedzy tylko do odczytu, montowane jako dowiązania symboliczne
|
||||
├── outputs/ # Wygenerowane artefakty, eksporty, skompilowane pliki
|
||||
├── raw/ # Materiał źródłowy dostarczony przez użytkownika
|
||||
│ └── inbox/ # Strefa zrzutu: nieprzetworzony materiał
|
||||
├── tmp/ # Pliki tymczasowe, cache (w .gitignore)
|
||||
├── wiki/ # Lokalna, ustrukturyzowana wiki w markdown (zarządzana przez agenta)
|
||||
│ ├── index.md # Tabela routingu z wyzwalaczami „Use when" + kb_schema_version
|
||||
│ ├── overview.md # Mapa wysokiego poziomu
|
||||
│ ├── log.md # Główny dziennik zmian (rollup)
|
||||
│ ├── error-book.md # Błędy kompilacji i wyprowadzone ograniczenia
|
||||
│ ├── entities/ # Typowane strony encji (osoby, projekty, koncepcje) + własny index.md
|
||||
│ └── graph/ # Listy krawędzi i dane relacji + własny index.md
|
||||
└── workload/ # Podsumowania sesji i decyzje
|
||||
└── YYYY-MM-DD_summary.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priorytet kaskady
|
||||
|
||||
Podczas wyszukiwania warstwy są sprawdzane w kolejności — pierwsze trafienie
|
||||
wygrywa:
|
||||
|
||||
```
|
||||
wiki/ (najwyższy) ← agent zapisuje tutaj, zawsze wygrywa
|
||||
linked/A/ (średni) ← zamontowane przez symlink wiki nadrzędne
|
||||
linked/B/ (niski) ← zamontowane przez symlink wiki nadrzędne
|
||||
libs/A/ (najniższy) ← kopie zewnętrznych baz wiedzy zarządzane przez git
|
||||
```
|
||||
|
||||
Agent nigdy nie zapisuje do `linked/` ani `libs/`. Aby poprawić treść
|
||||
nadrzędną, zapisz właściwą wersję w `wiki/` — automatycznie zyskuje
|
||||
pierwszeństwo.
|
||||
|
||||
---
|
||||
|
||||
## Funkcje
|
||||
|
||||
### Przepływ oparty na skrzynce odbiorczej (Inbox)
|
||||
Wrzuć dowolny surowy materiał (notatki, artykuły, linki) do `raw/inbox/` bez
|
||||
porządkowania. Po komendzie „Ingest" (lub „Sync the wiki" / „Update the
|
||||
wiki"), agent przetwarza skrzynkę odbiorczą — wydobywa wiedzę, zapisuje ją w
|
||||
`wiki/` i archiwizuje przetworzone elementy do `raw/` — a następnie
|
||||
przypomina o przejrzeniu wyniku i uruchomieniu „sync changes", aby wypchnąć
|
||||
zmiany do `origin`, gdy będziesz z nich zadowolony. Zaimplementowane jako
|
||||
Claude Code Skill — zobacz `.agents/skills/ckb-ingest/SKILL.md` — zamiast
|
||||
być zaszytym w `CLAUDE.md`/`AGENTS.md`, dzięki czemu pełna procedura ładuje
|
||||
się do kontekstu tylko wtedy, gdy jest faktycznie wywoływana. Odrębne od
|
||||
skilla `ckb-sync-changes`, który jest czysto operacją na poziomie gita, bez
|
||||
syntezy wiki.
|
||||
|
||||
### Leniwie ładowany indeks z wyzwalaczami „Use When"
|
||||
`wiki/index.md` to tabela routingu. Każdy wpis ma kolumnę **Use when** z
|
||||
listą słów kluczowych wyzwalających. Agent najpierw czyta indeks (pozostaje
|
||||
w kontekście), dopasowuje słowa kluczowe do zadania i ładuje tylko pasujące
|
||||
strony. Zmniejsza to narzut kontekstu z ~12K do ~3.2K tokenów na zadanie.
|
||||
|
||||
### Warstwa zapytań oparta na TLDR
|
||||
Każda strona zawiera jednozdaniowe podsumowanie `tldr` we frontmatterze.
|
||||
Podczas zapytania agent najpierw czyta TLDR-y. Jeśli TLDR już odpowiada na
|
||||
pytanie, pełna treść nigdy nie jest ładowana. Łańcuch odwoławczy: TLDR →
|
||||
treść → surowe źródło.
|
||||
|
||||
### Schemat frontmatteru strony
|
||||
Każda strona wiki używa frontmatteru YAML. Pole `type` jest wymagane; reszta
|
||||
jest opcjonalna:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: concept # WYMAGANE. Otwarty ciąg znaków: person, project, concept, library, decision, playbook, ...
|
||||
resource: https://... # Kanoniczny URI do autorytatywnego zewnętrznego źródła, które opisuje ta strona
|
||||
tldr: Jednozdaniowe podsumowanie zoptymalizowane pod odczyt przez LLM
|
||||
confidence: 0.0–1.0 # Wynik potwierdzenia przez źródła
|
||||
quality: 0.0–1.0 # Samoocena (poniżej 0.7 → oflagowane)
|
||||
supersedes: path/to/old.md
|
||||
superseded_by: path/to/new.md
|
||||
last_updated: YYYY-MM-DD
|
||||
freshness_window_days: 90 # Liczba dni, po których treść uznaje się za nieaktualną
|
||||
retention: high|medium|low
|
||||
---
|
||||
```
|
||||
|
||||
- **type** — wymagane; niezarejestrowany ciąg znaków, nowe wartości są
|
||||
zawsze poprawne, czytelnicy tolerują nierozpoznane
|
||||
- **resource** — opcjonalny wskaźnik do żywego/autorytatywnego źródła,
|
||||
oddzielony od własnego komentarza wiki
|
||||
- **confidence** — ustawiane przy zapisie, zanika z czasem, wzmacniane przez
|
||||
nowe źródła
|
||||
- **quality** — samoocena przy zapisie, strony poniżej 0.7 oflagowane do
|
||||
przeglądu
|
||||
- **supersedes / superseded_by** — gdy nowa informacja zastępuje starą,
|
||||
połącz je
|
||||
- **freshness_window_days** — strony starsze niż to okno są oflagowane
|
||||
podczas lintowania
|
||||
- **retention** — strony o niskim priorytecie są archiwizowane po 2× oknie
|
||||
świeżości
|
||||
|
||||
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (np. `"1.1"`),
|
||||
deklarujący, według której wersji tego schematu wiki została napisana —
|
||||
zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla
|
||||
zmian łamiących kompatybilność.
|
||||
|
||||
### Ekstrakcja encji i graf wiedzy
|
||||
Podczas ingestu agent wydobywa typowane encje (osoby, projekty, biblioteki,
|
||||
koncepcje, systemy) i zapisuje je jako strony w `wiki/entities/`. Typowane
|
||||
relacje (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) są
|
||||
zapisywane w `wiki/graph/edges.json`. Zapytania mogą przechodzić po grafie,
|
||||
aby odkrywać powiązane strony (np. „co zależy od Redis?").
|
||||
|
||||
### Rekurencyjna konwencja indeksu i dziennika
|
||||
Każdy podkatalog `wiki/`, który grupuje wiele stron (`entities/`, `graph/`,
|
||||
przyszłe foldery tematyczne), utrzymuje własny `index.md` — zwykłą listę
|
||||
linków, bez frontmatteru — dzięki czemu nawigacja po podkatalogach pozostaje
|
||||
leniwa, zamiast wymagać pełnego skanowania. Podkatalog może też utrzymywać
|
||||
własny `log.md`, gdy ma już wystarczająco dużo niezależnej historii;
|
||||
`wiki/log.md` pozostaje rollupem na poziomie głównym i nigdy nie powtarza
|
||||
zmiany już zapisanej w dzienniku podkatalogu.
|
||||
|
||||
### Podwójne linkowanie (Wikilinks + Markdown)
|
||||
Każde odwołanie krzyżowe używa zarówno `[[Wikilinks]]` (kompatybilnych z
|
||||
Obsidian), jak i standardowych linków `[markdown](path.md)`. Działa w
|
||||
widoku grafu Obsidian, renderowaniu GitHub i narzędziach CLI. Odwołania do
|
||||
treści nadrzędnych używają pełnych ścieżek względnych: `linked/<name>/...`
|
||||
lub `libs/<name>/...`. Odwołania wewnątrz wiki preferują ścieżki bezwzględne
|
||||
względem katalogu głównego projektu (`/wiki/entities/foo.md`) zamiast
|
||||
względnych, dzięki czemu linki przetrwają późniejsze przenoszenie plików.
|
||||
|
||||
### Samonaprawiający się lint
|
||||
Okresowo (lub na żądanie) agent sprawdza kondycję wiki:
|
||||
- **Zgodność (conformance)** — oflagowuje każdą stronę bez poprawnego
|
||||
frontmatteru lub pola `type`
|
||||
- **Świeżość** — oflagowuje strony starsze niż ich `freshness_window_days`
|
||||
- **Zanik pewności (confidence decay)** — zmniejsza `confidence` dla stron
|
||||
niewzmacnianych nowymi źródłami
|
||||
- **Przegląd retencji** — archiwizuje strony `retention: low` starsze niż
|
||||
2× okno świeżości
|
||||
- **Wykrywanie supersesji** — znajduje sprzeczności, łączy stare→nowe
|
||||
- **Wykrywanie sierot** — znajduje strony bez linków przychodzących
|
||||
- **Spójność grafu** — weryfikuje, czy wszystkie krawędzie wskazują na
|
||||
istniejące encje
|
||||
- **Spójność indeksu/dziennika** — weryfikuje, czy każdy podkatalog ma
|
||||
index.md i czy żadna zmiana nie jest podwójnie logowana
|
||||
- **Księga błędów (Error Book)** — zapisuje systemowe problemy wraz z
|
||||
przyczyną i naprawą
|
||||
|
||||
Automatycznie naprawia to, co może (uszkodzone linki, brakujące odnośniki
|
||||
zwrotne, nieaktualne flagi), i przypomina o przejrzeniu wyniku oraz
|
||||
uruchomieniu „sync changes", aby wypchnąć zmiany do `origin`, gdy będziesz
|
||||
z nich zadowolony. Zaimplementowane jako Claude Code Skill — zobacz
|
||||
`.agents/skills/ckb-lint/SKILL.md` — zamiast być zaszytym w
|
||||
`CLAUDE.md`/`AGENTS.md`, dzięki czemu pełna lista kontrolna ładuje się do
|
||||
kontekstu tylko wtedy, gdy jest faktycznie wywoływana.
|
||||
|
||||
### Rozwiązywanie konfliktów (Supersesja)
|
||||
Gdy nowa informacja przeczy istniejącej stronie, agent dodaje linki
|
||||
`supersedes` / `superseded_by`. Stara strona jest zachowywana, ale
|
||||
oznaczana jako nieaktualna. Kontrola wersji dla wiedzy, nie tylko dla
|
||||
plików.
|
||||
|
||||
### Ocena jakości
|
||||
Każda strona przy zapisie otrzymuje wynik jakości (0.0–1.0), oparty na
|
||||
strukturze, cytowaniu źródeł i spójności z resztą wiki. Strony poniżej 0.7
|
||||
są oflagowane do przeglądu lub przepisywane podczas kolejnego lintowania.
|
||||
|
||||
### Księga błędów (Error Book)
|
||||
Systematyczne błędy (uszkodzone linki, problemy z formatowaniem,
|
||||
sprzeczności między stronami) są zapisywane w `wiki/error-book.md` wraz z
|
||||
przyczyną, zastosowaną naprawą i ograniczeniem wielokrotnego użytku
|
||||
zapobiegającym powtórce. Naprawa dwuwarstwowa:
|
||||
- **Warstwa 1** — deterministyczna automatyczna naprawa problemów
|
||||
strukturalnych
|
||||
- **Warstwa 2** — przebieg rozumowania agenta dla problemów
|
||||
semantycznych/między stronami
|
||||
|
||||
### Haki automatyzacji (Automation Hooks)
|
||||
- **Nowe źródło** → automatyczny ingest przy kolejnej komendzie „Ingest"
|
||||
- **Start sesji** → ładowanie indeksu + ostatniego podsumowania workload;
|
||||
sprawdzenie niezsynchronizowanych zmian (niezacommitowana praca lub
|
||||
przewaga/zaległość względem `origin`) i zasugerowanie
|
||||
`ckb-sync-changes`, jeśli takie zostaną znalezione
|
||||
- **Koniec sesji** → skompresowanie obserwacji do workload/; ponowne
|
||||
sprawdzenie niezsynchronizowanych zmian (w tym tych, które powstały
|
||||
właśnie w tej sesji) i zasugerowanie `ckb-sync-changes`, jeśli to
|
||||
potrzebne
|
||||
- **Zapytanie** → zapisanie z powrotem wartościowych odpowiedzi jako strony
|
||||
wiki
|
||||
- **Zapis do pamięci** → sprawdzenie sprzeczności, wywołanie supersesji
|
||||
- **Harmonogram** → okresowy lint, konsolidacja, zanik retencji
|
||||
|
||||
### Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC)
|
||||
Wiki rośnie na podstawie rzeczywistych niepowodzeń agenta, a nie z góry
|
||||
narzuconej kuracji:
|
||||
1. Agent nie potrafi odpowiedzieć → identyfikuje brakującą wiedzę
|
||||
2. Proponuje minimalną encję/stronę wypełniającą lukę
|
||||
3. Użytkownik zatwierdza lub dostarcza materiał źródłowy
|
||||
4. Kolejny ingest wprowadza ją
|
||||
|
||||
Zbiega do stabilnej bazy wiedzy po ~20–30 cyklach.
|
||||
|
||||
### Podsumowania sesji
|
||||
Po każdej akcji konwersacyjnej agent dopisuje do
|
||||
`workload/YYYY-MM-DD_summary.md`. Zapewnia to ciągłość między sesjami i
|
||||
przeglądalną historię ewolucji bazy wiedzy. Agent czyta ostatnie
|
||||
podsumowanie na starcie sesji, aby kontynuować od miejsca, w którym
|
||||
skończył.
|
||||
|
||||
### Dziennik zmian
|
||||
Każda modyfikacja wiki jest natychmiast logowana w `wiki/log.md` w
|
||||
kolejności odwrotnie chronologicznej (najnowsze na górze), z zapisem co się
|
||||
zmieniło, dlaczego i jakie było źródło.
|
||||
|
||||
### Eksport OKF (na żądanie)
|
||||
Wiki może zostać wyeksportowana jako zgodny z
|
||||
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
|
||||
v0.1 pakiet w `outputs/okf/`, możliwy do skonsumowania przez dowolne ogólne
|
||||
narzędzie OKF (np. referencyjny wizualizator grafu Google) bez naruszania
|
||||
bogatszego wewnętrznego schematu
|
||||
(`confidence`/`quality`/`retention`/`supersedes`/podwójne linkowanie),
|
||||
którego OKF natywnie nie rozumie. Zaimplementowane jako Claude Code Skill —
|
||||
zobacz `.agents/skills/ckb-export-okf/SKILL.md` — zamiast być zaszytym w
|
||||
`CLAUDE.md`/`AGENTS.md`, dzięki czemu zestaw reguł mapowania ładuje się do
|
||||
kontekstu tylko wtedy, gdy jest faktycznie wywoływany. `outputs/okf/` jest
|
||||
w `.gitignore` — to w pełni regenerowalny artefakt budowania, więc każda
|
||||
maszyna/narzędzie regeneruje go na żądanie zamiast przenosić go w historii
|
||||
gita.
|
||||
|
||||
### Eksport Starlight (na żądanie)
|
||||
Wiki może też zostać wyeksportowana do formy skonsumowalnej przez Astro +
|
||||
Starlight w `outputs/starlight/`, tworząc czytelną dla człowieka stronę
|
||||
dokumentacji — w odróżnieniu od eksportu OKF, który celuje w konsumpcję
|
||||
maszynową/narzędziową. Deterministyczny skrypt Python
|
||||
(`scripts/export_starlight.py`) obsługuje przemapowanie frontmatteru,
|
||||
zwijanie podwójnych linków, rozwiązywanie wikilinków, kopiowanie zasobów i
|
||||
generowanie paska bocznego; zadaniem agenta jest jedynie zadanie dwóch
|
||||
pytań konfiguracyjnych (zakres eksportu: pełny uruchamialny szkielet vs.
|
||||
tylko treść; czy dołączyć strony meta dziennika/księgi błędów) i
|
||||
przekazanie raportu skryptu. Również na żądanie i tylko jako skill —
|
||||
zobacz `.agents/skills/ckb-export-starlight/SKILL.md`. Podobnie jak
|
||||
`outputs/okf/`, `outputs/starlight/` jest w `.gitignore` jako regenerowalny
|
||||
artefakt budowania.
|
||||
|
||||
### Prowadzone wycieczki wprowadzające (na żądanie)
|
||||
Poproś „oprowadź mnie po X" (lub „od czego zacząć z X", „krótka wycieczka
|
||||
po X") aby otrzymać krótką, tylko-do-odczytu prowadzoną kolejność czytania:
|
||||
akapit wprowadzający plus uporządkowaną listę stron wiki do przeczytania,
|
||||
zbudowaną przez przejście po grafie wiedzy na zewnątrz od najlepiej
|
||||
pasującej strony (najpierw podstawy, potem sam temat, potem to, co się na
|
||||
nim opiera). Nigdy nie zapisuje do `wiki/`. Zobacz
|
||||
`.agents/skills/ckb-onboard-me/SKILL.md`.
|
||||
|
||||
### Podsumowanie projektu (na żądanie)
|
||||
Poproś o „podsumowanie projektu" (lub „jak stoją sprawy", „nadrób
|
||||
zaległości w projekcie"), aby zregenerować `PROJECT-OVERVIEW.md` w
|
||||
katalogu głównym repozytorium — jedno- lub dwustronicowy skrót (przegląd,
|
||||
stan projektu, działania i ich status, ryzyka, założenia) zsyntetyzowany w
|
||||
całości z bieżącej zawartości `wiki/` i jej grafu wiedzy. Zawsze
|
||||
nadpisywany w całości przy ponownym uruchomieniu, nigdy nie dopisywany
|
||||
ręcznie. Zobacz `.agents/skills/ckb-project-summary/SKILL.md`.
|
||||
|
||||
### Synchronizacja gita (na żądanie)
|
||||
Historia gita tego repozytorium może zostać uzgodniona z jego zdalnym
|
||||
repozytorium `origin` na żądanie: lokalne zmiany są commitowane, zdalne
|
||||
zmiany są pobierane i scalane, wszelkie konflikty są prezentowane
|
||||
użytkownikowi plik po pliku do rozwiązania, a następnie wynik jest
|
||||
automatycznie wypychany (push). Powiedz „sync changes", aby to uruchomić.
|
||||
Również zaimplementowane jako Claude Code Skill — zobacz
|
||||
`.claude/skills/ckb-sync-changes/SKILL.md` — i celowo odrębne od przepływu
|
||||
na poziomie treści „Sync the wiki" / „Ingest", który przetwarza
|
||||
`raw/inbox/` na ustrukturyzowane strony `wiki/` i nie ma nic wspólnego z
|
||||
gitem.
|
||||
|
||||
### Tryb quizu (na żądanie)
|
||||
Poproś o odpytanie z wiki („quiz me on X", „sprawdź moją wiedzę"), aby
|
||||
uzyskać jednorazowy, punktowany sprawdzian wiedzy: agent czyta odpowiednie
|
||||
strony, generuje pytania otwarte lub jednokrotnego wyboru oparte na
|
||||
konkretnych faktach z wiki, przeprowadza je jedno po drugim z natychmiastową
|
||||
informacją zwrotną i bieżącym wynikiem, a na koniec podaje werdykt.
|
||||
Bezstanowy — nic nie jest zapisywane między uruchomieniami. Zobacz
|
||||
`.agents/skills/cbk-quiz/SKILL.md`.
|
||||
|
||||
### Prowadzony program nauczania (na żądanie)
|
||||
Poproś o naukę z wiki („teach me the wiki", „naucz mnie o X", „przeprowadź
|
||||
sesję nauki"), aby otrzymać stanowy kurs zamiast jednorazowego quizu.
|
||||
Pierwsze wywołanie go planuje: określa zakres materiału (opcjonalnie
|
||||
uzupełniając cienkie miejsca z internetu, wyraźnie oznaczone jako
|
||||
nieautorytatywne), pyta, czy ma to być jedna sesja, czy rozłożona w czasie
|
||||
seria (czas trwania, częstotliwość, opcjonalne przypomnienia kalendarzowe
|
||||
`.ics`), dzieli treść na porcje wielkości sesji — wolą dodatkową sesję niż
|
||||
upychanie materiału — i zapisuje zaakceptowany plan oraz tracker postępu w
|
||||
`outputs/teaching/<topic>/`. Kolejne wywołania porównują plan z postępem,
|
||||
uczą kolejnej porcji materiału inną techniką za każdym razem (pytania
|
||||
sokratejskie, analogie, przykłady rozwiązane krok po kroku, „naucz mnie z
|
||||
powrotem", mnemotechniki, ...), sprawdzają utrwalenie wiedzy i powtarzają
|
||||
słabe punkty przed przejściem dalej. Nigdy nie zapisuje do `wiki/`. Zobacz
|
||||
`.agents/skills/ckb-teach-me/SKILL.md`.
|
||||
|
||||
---
|
||||
|
||||
## Szybki start
|
||||
|
||||
1. **Zamontuj nadrzędne bazy wiedzy:**
|
||||
```bash
|
||||
ln -s /path/to/other-kb ./linked/my-upstream
|
||||
git clone https://github.com/org/external-kb ./libs/external-kb
|
||||
```
|
||||
|
||||
2. **Wrzuć surowy materiał** do `raw/inbox/` (notatki, linki, artykuły).
|
||||
|
||||
3. **Poleć agentowi „Ingest"** — przetworzy skrzynkę odbiorczą, skonsultuje
|
||||
kaskadę, wydobędzie encje i zapisze ustrukturyzowany markdown w `wiki/`.
|
||||
|
||||
4. **Zadawaj pytania** — agent używa indeksu do routingu, TLDR-ów do
|
||||
szybkich odpowiedzi i grafu do odkrywania relacji.
|
||||
|
||||
5. **Okresowo proś o „Lint"** — agent sprawdzi kondycję wszystkiego,
|
||||
naprawi co może i zgłosi problemy.
|
||||
|
||||
---
|
||||
|
||||
## Pliki instrukcji dla agenta
|
||||
|
||||
| Plik | Cel |
|
||||
|------|-----|
|
||||
| `AGENTS.md` | Pełna instrukcja dla dowolnego agenta kodującego AI |
|
||||
| `CLAUDE.md` | Dowiązanie symboliczne do `AGENTS.md`, automatycznie wykrywane przez Claude Code |
|
||||
|
||||
Skille znajdują się w jednej wspólnej lokalizacji, `.agents/skills/`, dzięki
|
||||
czemu każde narzędzie agentowe respektujące tę konwencję je odnajduje.
|
||||
`.claude/skills` to dowiązanie symboliczne do `.agents/skills` — Claude Code
|
||||
widzi ten sam zestaw skilli bez drugiej kopii do utrzymywania w
|
||||
synchronizacji.
|
||||
|
||||
---
|
||||
|
||||
## Wskazówki
|
||||
|
||||
- Nadrzędne bazy wiedzy (`linked/` i `libs/`) **nigdy nie są modyfikowane**
|
||||
przez agentów.
|
||||
- Aby poprawić treść nadrzędną, zapisz poprawną wersję w `wiki/` — ona
|
||||
wygrywa.
|
||||
- Używaj `raw/inbox/` dla wszystkiego, co nieprzetworzone; agent czyści ją
|
||||
podczas ingestu.
|
||||
- Tabela routingu `wiki/index.md` to najważniejszy plik — utrzymuj go na
|
||||
bieżąco.
|
||||
- Confidence, quality i freshness pozwalają ufać właściwej treści i
|
||||
oflagowywać resztę do przeglądu.
|
||||
- Katalogi `tmp/` i `libs/` są w `.gitignore`. Sam `outputs/` jest śledzony,
|
||||
ale jego regenerowalne podkatalogi budowania, `outputs/okf/` i
|
||||
`outputs/starlight/`, są w `.gitignore` — każdy z nich jest w pełni
|
||||
odtwarzalny z `wiki/` na żądanie, więc nie ma czego uzgadniać, przenosząc
|
||||
go w historii gita. `outputs/teaching/` (osobiste plany nauki i postęp
|
||||
sesji ze skilla do nauczania) jest również w `.gitignore`, ponieważ to
|
||||
osobisty stan sesji, a nie współdzielona treść bazy wiedzy. Commituj
|
||||
inne, ręcznie utrzymywane artefakty w `outputs/` normalnie.
|
||||
|
||||
---
|
||||
|
||||
## Wersja i licencja
|
||||
|
||||
Aktualna wersja szablonu: [VERSION](VERSION). Licencja:
|
||||
[Apache License 2.0](LICENSE).
|
||||
1
VERSION
Normal file
1
VERSION
Normal file
|
|
@ -0,0 +1 @@
|
|||
1.0.0
|
||||
Loading…
Add table
Reference in a new issue