Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script

- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
  phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
  reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
  docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
  D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
  Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
  base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-09-24 20:45:09 +02:00
parent 6c0d70976c
commit 7863115b74
74 changed files with 2598 additions and 1629 deletions

View file

@ -26,6 +26,10 @@ path, owner. **That page is the durable artifact; the clone is a convenience.**
Plus: `src/` and `openspec/` scaffold, a routing block in `AGENTS.md`, `.gitignore`
rules for `src/*`, and the `repository`/`component`/`spec` types.
Graph verbs these skills write, from the base vocabulary in
`wiki/graph/index.md`: `ckb-code-map` — `part_of`, `depends_on`, `owns`;
`ckb-spec` — `implements`. No new verbs are introduced.
## Two spec levels
Specs live at **both** levels, and the split is the point:
@ -54,14 +58,14 @@ no implementer, or a repo-level spec whose parent was archived, is a finding.
## Setting up OpenSpec
See [OPENSPEC.md](../../../OPENSPEC.md) ([Polski](../../../OPENSPEC.pl.md)) for
See [docs/OPENSPEC.md](../../../docs/OPENSPEC.md) ([Polski](../../../docs/OPENSPEC.pl.md)) for
install steps, the daily propose → apply → archive loop, and the reason
`openspec init` must never run at the KB root.
## Design record
- [D-0001](../../../wiki/decisions/0001-opt-in-file-based-kb-modules.md) — why modules are files in the repo.
- [D-0002](../../../wiki/decisions/0002-software-module-design.md) — why gitignored clones, both spec levels, hybrid vendoring.
- [D-0001](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md) — why modules are files in the repo.
- [D-0002](../../../docs/decisions/0002-software-module-design.md) — why gitignored clones, both spec levels, hybrid vendoring.
---

View file

@ -1,5 +1,5 @@
# Cascade KB module manifest — read by `ckb-module` on install/uninstall.
# See wiki/decisions/0001-opt-in-file-based-kb-modules.md for why modules are
# See docs/decisions/0001-opt-in-file-based-kb-modules.md for why modules are
# files in the repo rather than native agent plugins.
name: software
title: Software / source-code KB
@ -48,7 +48,7 @@ schema_additions:
- implemented_by # KB-root spec -> repo-level specs implementing it
# External dependency. The module reports its absence rather than substituting
# its own workflow — see wiki/decisions/0002-software-module-design.md.
# its own workflow — see docs/decisions/0002-software-module-design.md.
depends_on:
- name: openspec
scope: src-repo-level-only

View file

@ -107,7 +107,7 @@ KB-root spec layer instead — don't run it and don't clean up afterwards.
Install is `npm install -g @fission-ai/openspec@latest` (Node 20.19.0+), then
`openspec init` in the repo; `openspec update` after a CLI upgrade. See
[OPENSPEC.md](../../../../OPENSPEC.md) for the user-facing guide.
[docs/OPENSPEC.md](../../../../docs/OPENSPEC.md) for the user-facing guide.
If OpenSpec is not installed (`command -v openspec` fails, or the repo has no
`openspec/`), **say so plainly and stop** rather than improvising:

View file

@ -1,52 +1,24 @@
---
name: ckb-decide
description: Record a decision into wiki/decisions/ as a numbered decision record — what was decided, by whom, when, why, what it affects, and which earlier decision it supersedes or reverses — and answer questions about decisions already recorded ("what did we decide about X", "show decision 7", "which decisions are still open", "what changed the database choice"). Use when the user says "record a decision", "log a decision", "we decided ...", "ADR", "decision record", or asks what/when/why/by whom something was decided. Distinct from `ckb-ingest` (which turns raw source material into entity pages) and from `ckb-retrieve` (general KB questions — this skill is the decisions-scoped path, and hands off to it for anything wider).
description: Record a numbered, append-only decision record in wiki/decisions/, or answer questions about decisions already recorded. Use for "record a decision", "we decided ...", "ADR", "decision record", or when asked what/why/who/when something was decided, what superseded it, or which decisions are still open.
---
# Decision log skill
## Purpose
A decision is a different kind of knowledge from an entity page. An entity
page describes what something *is*, and gets rewritten as understanding
improves. A decision record describes what was chosen *at a point in time*,
by whom, and why — and is never rewritten to reflect a later change of mind.
When the choice changes, a new decision supersedes the old one and both stay
on the record. That's the whole point: the value is in being able to ask
"why is it like this?" and get the reasoning, the people, and the date, not
just the current state.
A decision records what was chosen at a point in time, by whom, and why. Unlike an
entity page it is never rewritten to reflect a later change of mind — a new decision
supersedes the old one and both stay on the record.
This skill owns both halves of that:
This skill owns both **recording** (turning "we decided X" into a numbered, linked,
logged record under `wiki/decisions/`, supersession wired in both directions) and
**looking up** (answering questions about decisions already recorded, scoped to
`wiki/decisions/` rather than the whole wiki).
- **Recording** — turning "we decided X" into a numbered, linked, logged
decision record under `wiki/decisions/`, with the supersession links wired
in both directions.
- **Looking up** — answering questions about decisions already recorded,
scoped to `wiki/decisions/` rather than searching the whole wiki.
It writes only inside `wiki/` (`wiki/decisions/`, `wiki/decisions/index.md`,
`wiki/decisions/log.md`, `wiki/graph/edges.json`, and a pointer line in
`wiki/log.md`). It never edits an existing decision's substance — see
Rule: decisions are append-only, below.
## Trigger phrases
**Recording:**
- "record a decision" / "log a decision" / "add a decision record" / "write an ADR"
- "we decided ..." / "we've agreed to ..." / "the call was ..."
- "we're reversing ..." / "that supersedes decision N"
**Looking up:**
- "what did we decide about X" / "why do we ... ?" (when the answer is a decision)
- "show decision 7" / "show me D-0007"
- "which decisions are still open" / "what's proposed but not accepted"
- "who decided X" / "when did we decide X"
- "what decisions affect <project/system/person>"
- "what superseded decision N" / "what changed the X decision"
For a question that only *touches* decisions as part of a wider answer, use
`ckb-retrieve` instead and let it pull decision pages in as one source
among many. This skill is for when decisions themselves are the subject.
Writes only inside `wiki/`: `wiki/decisions/`, its `index.md` and `log.md`,
`wiki/graph/edges.json`, and a pointer line in `wiki/log.md`. Never edits an existing
decision's substance — see Rule: decisions are append-only, below.
## The decision record format
@ -297,27 +269,7 @@ actually Anna") — fix that in place and note the correction in the log entry.
## Edge cases
- **No `wiki/decisions/` directory yet** — create it along with `index.md`
and `log.md` (using the scaffold this template ships), then record the
decision as `0001-…`.
- **The user describes a decision that was already recorded** — don't create
a duplicate. Point at the existing record and ask whether they want to
supersede it, correct it, or leave it.
- **A decision with no clear decider** ("we just kind of settled on it") —
record `decided_by: unknown` rather than guessing or attributing it to
whoever is in the room. Unattributed is a fact; misattributed is a defect.
- **A decision that was never actually made** ("we should probably...") —
record it as `status: proposed` with no `decided_on`, or don't record it at
all. Ask which; a proposal filed as `accepted` is the most damaging failure
mode this skill has.
- **A decision that reverses a reversal** — normal chaining. Each link points
one step back; the chain is the history.
- **Bulk import of historical decisions** (a meeting-notes backlog) — that's
`ckb-ingest`'s job for the extraction, then this skill's format for the
pages. Record them in chronological order so the numbers run in the same
order as the decisions.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,29 @@
# ckb-decide — edge cases
Reference material for the `ckb-decide` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **No `wiki/decisions/` directory yet** — create it along with `index.md`
and `log.md` (using the scaffold this template ships), then record the
decision as `0001-…`.
- **The user describes a decision that was already recorded** — don't create
a duplicate. Point at the existing record and ask whether they want to
supersede it, correct it, or leave it.
- **A decision with no clear decider** ("we just kind of settled on it") —
record `decided_by: unknown` rather than guessing or attributing it to
whoever is in the room. Unattributed is a fact; misattributed is a defect.
- **A decision that was never actually made** ("we should probably...") —
record it as `status: proposed` with no `decided_on`, or don't record it at
all. Ask which; a proposal filed as `accepted` is the most damaging failure
mode this skill has.
- **A decision that reverses a reversal** — normal chaining. Each link points
one step back; the chain is the history.
- **Bulk import of historical decisions** (a meeting-notes backlog) — that's
`ckb-ingest`'s job for the extraction, then this skill's format for the
pages. Record them in chronological order so the numbers run in the same
order as the decisions.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -1,40 +1,20 @@
---
name: ckb-export-okf
description: Export the local wiki/ knowledge base as an Open Knowledge Format (OKF) v0.1-conformant bundle at outputs/okf/, so any generic OKF tool can consume it. Use when the user asks to "export the wiki as OKF", "generate the OKF bundle", "export to OKF", "publish the OKF export", or "sync outputs/okf".
description: Export wiki/ as an Open Knowledge Format (OKF) v0.1-conformant bundle at outputs/okf/, so any generic OKF tool can consume it. Use for "export the wiki as OKF", "generate the OKF bundle", "export to OKF", or "sync outputs/okf".
---
# Export to OKF skill
## Purpose
Regenerate `outputs/okf/` from the current `wiki/` tree as a bundle that
conforms to Google's Open Knowledge Format (OKF) v0.1 spec
(https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md),
so any generic OKF consumer (e.g. Google's reference graph visualizer) can
read this knowledge base without needing to understand this repo's richer,
more opinionated schema (`confidence`, `quality`, `retention`, `supersedes`,
dual-linking, the cascade layers). This is a one-way, on-demand export —
`wiki/` stays the authoritative source; `outputs/okf/` is always a derived
artifact of it, never edited by hand and never fed back in.
Regenerate `outputs/okf/` from the current `wiki/` tree as a bundle conforming to
Google's Open Knowledge Format (OKF) v0.1
([spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)),
so a generic OKF consumer can read this KB without understanding its richer schema.
The whole transform — frontmatter remapping, link rewriting, index and log
regeneration, conformance validation — is done by a deterministic Python
script, not by reading and rewriting every page by hand. The mapping is a
fixed ruleset over a wiki that will keep growing, and a mechanical transform
like this belongs in code, not in per-page model reasoning. Nothing in this
skill needs an LLM to run correctly; the model's job is to invoke the script
and relay its report.
This skill only runs when explicitly invoked — it is deliberately not part
of the always-loaded `CLAUDE.md`/`AGENTS.md` Ingest/Lint workflows.
## Trigger phrases
Use this skill when the user says things like:
- "export the wiki as OKF" / "export to OKF"
- "generate the OKF bundle" / "regenerate outputs/okf"
- "publish the OKF export"
- "sync outputs/okf with the wiki"
One-way and on-demand: `wiki/` stays authoritative, `outputs/okf/` is always derived,
never hand-edited, never fed back in. The whole transform is done by a deterministic
Python script — the model's job is to invoke it and relay its report.
## How to run this skill
@ -137,23 +117,7 @@ exists (cross-cascade `linked/`/`libs/` references are exempt by design).
## Edge cases
- **Empty `wiki/entities/` or `wiki/graph/`:** their `index.md` is still
regenerated, as an H1 with an empty bullet list. An empty index is
spec-valid; the directory is never skipped.
- **A future `wiki/<newtopic>/` subdirectory:** handled automatically — the
script discovers directories dynamically, mirrors them, and generates an
index for each. No script changes needed.
- **A future `wiki/archived/`:** exported like any other subdirectory. OKF
has no notion of archival status; `retention`/`freshness_window_days`
already ride along as extension fields for any consumer that cares.
- **Non-markdown files in `wiki/`** (e.g. `graph/edges.json`): copied
verbatim into the same relative position and listed in their directory's
index. Dotfiles (`.gitadd`) are skipped.
- **Re-running with no wiki changes:** produces byte-identical output — every
directory walk and generated list is sorted. If a run is ever
nondeterministic, that's a bug in the script, not expected behavior.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,25 @@
# ckb-export-okf — edge cases
Reference material for the `ckb-export-okf` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Empty `wiki/entities/` or `wiki/graph/`:** their `index.md` is still
regenerated, as an H1 with an empty bullet list. An empty index is
spec-valid; the directory is never skipped.
- **A future `wiki/<newtopic>/` subdirectory:** handled automatically — the
script discovers directories dynamically, mirrors them, and generates an
index for each. No script changes needed.
- **A future `wiki/archived/`:** exported like any other subdirectory. OKF
has no notion of archival status; `retention`/`freshness_window_days`
already ride along as extension fields for any consumer that cares.
- **Non-markdown files in `wiki/`** (e.g. `graph/edges.json`): copied
verbatim into the same relative position and listed in their directory's
index. Dotfiles (`.gitadd`) are skipped.
- **Re-running with no wiki changes:** produces byte-identical output — every
directory walk and generated list is sorted. If a run is ever
nondeterministic, that's a bug in the script, not expected behavior.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -1,38 +1,20 @@
---
name: ckb-export-starlight
description: Export the local wiki/ knowledge base into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use when the user asks to "export the wiki to Starlight", "generate the docs site", "export as Astro Starlight", "build a human-readable wiki site", or "publish the knowledge base as a website".
description: Export wiki/ into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use for "export the wiki to Starlight", "generate the docs site", "build a human-readable wiki site", or "publish the knowledge base as a website".
---
# Export to Astro Starlight skill
## Purpose
Regenerate `outputs/starlight/` from the current `wiki/` tree so it can be
built and served as an Astro + Starlight documentation website — a
human-readable, browsable version of this knowledge base (unlike
`ckb-export-okf`, which targets machine/tool consumption). This is a one-way,
on-demand export — `wiki/` stays the authoritative source; `outputs/starlight/`
is always a derived artifact of it, never edited by hand and never fed back
in.
Regenerate `outputs/starlight/` from the current `wiki/` tree so it can be built and
served as an Astro + Starlight documentation website — a human-readable, browsable
version of this KB (unlike `ckb-export-okf`, which targets machine consumption).
This skill only runs when explicitly invoked — it is deliberately not part
of the always-loaded `CLAUDE.md`/`AGENTS.md` Ingest/Lint workflows.
The heavy lifting (frontmatter remapping, link rewriting, asset copying,
sidebar generation) is done by a deterministic Python script, not by
reading and rewriting every page by hand — the wiki now has 60+ pages, and
a mechanical transform like this belongs in code, not in per-page model
reasoning. Nothing in this skill needs an LLM to run correctly; the model's
job is just to ask the two setup questions below, invoke the script, and
relay its report.
## Trigger phrases
Use this skill when the user says things like:
- "export the wiki to Starlight" / "export as Astro Starlight"
- "generate the docs site" / "build the Starlight site"
- "publish the knowledge base as a website"
- "sync outputs/starlight"
One-way and on-demand: `wiki/` stays authoritative, `outputs/starlight/` is always
derived, never hand-edited, never fed back in. The transform is done by a
deterministic Python script — the model asks the two setup questions below, invokes
the script, and relays its report.
## How to run this skill
@ -133,20 +115,7 @@ The script prints, and you should summarize back to the user:
## Edge cases
- **A future `wiki/<newtopic>/` subdirectory:** handled automatically —
the script discovers top-level `wiki/` subdirectories dynamically and
adds a sidebar `autogenerate` group for each; no script changes needed.
- **Re-running with no wiki changes:** should produce byte-identical
output (directory listings are sorted before writing). If asset copying
or link rewriting ever introduces nondeterminism, that's a bug in the
script, not expected behavior.
- **A wiki page with no `tldr`:** `description` is simply omitted from
that page's frontmatter — Starlight tolerates a missing description.
- **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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,22 @@
# ckb-export-starlight — edge cases
Reference material for the `ckb-export-starlight` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **A future `wiki/<newtopic>/` subdirectory:** handled automatically —
the script discovers top-level `wiki/` subdirectories dynamically and
adds a sidebar `autogenerate` group for each; no script changes needed.
- **Re-running with no wiki changes:** should produce byte-identical
output (directory listings are sorted before writing). If asset copying
or link rewriting ever introduces nondeterminism, that's a bug in the
script, not expected behavior.
- **A wiki page with no `tldr`:** `description` is simply omitted from
that page's frontmatter — Starlight tolerates a missing description.
- **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>.*

View file

@ -1,89 +1,45 @@
---
name: ckb-index-external
description: Walk every connector-backed libs/<name>/ (identified by a source.yaml declaring a live external source — SharePoint, Google Drive, a plain URL, or another connector) and build/refresh a self-contained generated index for it — index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely to that one connector. Indexing goes beyond one page per document: for every document found, it also extracts the people, organizations, projects, decisions, systems, and processes that document actually discusses into their own thin, pointer-style entity pages (evidence back to the specific documents that mention them, not a second copy of wiki/'s synthesis), so the index supports "what do we know about X / what's the process for Y" lookups, not just "what documents exist at this source". The index can optionally be published to (and fetched from) a shared location — a git repo or a shared resource — declared in source.yaml, so most users just read an already-built index instead of re-scanning the live source. Read vs. write access to a given source is a per-user, local-only setting (libs/<name>/source.local.yaml, gitignored) — read-only by default, so one or two designated admins can maintain a source for everyone else. Never touches wiki/, never touches source.yaml, never touches a git-copy lib. Use when the user says "index external sources", "index libs", "refresh the external index", or "scan the SharePoint/Drive folder". This is the on-demand external-source workflow routed by CLAUDE.md/AGENTS.md, distinct from `ckb-ingest` (which processes raw/inbox/ into wiki/) and from a plain git-copy libs/<name>/ (a frozen clone, never touched by any skill).
description: Build or refresh the generated index (index.md/entities/graph/log.md) inside each connector-backed libs/<name>/ — one declaring a live external source via source.yaml, such as SharePoint, Google Drive, or a URL. Indexes both the documents found and the people, projects, decisions and processes those documents discuss. Use for "index external sources", "index libs", "refresh the external index", or "scan the SharePoint/Drive folder".
---
# Index external sources skill
## Purpose
Give `libs/<name>/` a second population mode alongside the existing
git-copy one: a `libs/<name>/source.yaml` declares a *live* external
source — a SharePoint folder, a Google Drive folder, a plain URL, or
another connector — that the user doesn't want to fully mirror locally.
This skill walks that source and builds a small, self-contained index of
what's there, using the same `index.md`/`graph`/`log.md` shape `wiki/`
already uses, rooted at `libs/<name>/` instead.
A `libs/<name>/source.yaml` declares a *live* external source — SharePoint, Google
Drive, a plain URL, another connector — that the user does not want to mirror
locally. This skill walks that source and builds a self-contained index rooted at
`libs/<name>/`, using the same `index.md`/`entities/`/`graph/`/`log.md` shape `wiki/`
uses.
The index holds two kinds of pages, and both matter for retrieval:
The index holds two kinds of pages:
- **Document pages** — one per source item found (one per email, one per
file, one per SharePoint page), the original design. These answer "what
exists at this source".
- **Entity and process pages** — one per person, organization, project,
decision, system, or named process that those documents actually
*discuss*, extracted the same way `ckb-ingest` extracts entities into
`wiki/`, but kept deliberately thin here: a `tldr` plus a list of which
document(s) mention it and what they say, not a full synthesis. These
answer "what do we know about X" without forcing whoever's asking to
read every document's `tldr` by hand looking for a name. A document-only
index is fine for browsing a source but too narrow for actually
retrieving information out of it — that's what this second pass fixes.
- **Document pages** — one per source item found. These answer "what exists here".
- **Entity and process pages** — one per person, organization, project, decision,
system or named process those documents *discuss*, kept deliberately thin: a `tldr`
plus which documents mention it and what they say, not a full synthesis. These
answer "what do we know about X" without reading every document's `tldr` by hand.
This is deliberately **not** blended into the main `wiki/entities/` or
`wiki/graph/edges.json` — the generated index lives entirely inside its own
`libs/<name>/`, at the lowest cascade layer, the same way a git-cloned
KB's own files would. If something in it needs to override or correct what
the connector says, that's what writing the corrected version into `wiki/`
is for (cascade priority already covers that — `wiki/` always wins). Where
an extracted entity already has a full page in `wiki/entities/`, this
skill's own page for it stays thin and points there rather than
re-synthesizing — see Step 6.
The index stays entirely inside its own `libs/<name>/`, at the lowest cascade layer —
never blended into `wiki/entities/` or `wiki/graph/edges.json`. To override what the
connector says, write the correction into `wiki/`; cascade priority already covers it.
Where an extracted entity already has a full `wiki/entities/` page, this skill's page
stays thin and points there (Step 6).
Two refinements on top of that base design:
Two refinements on top of that:
- **Shared, pre-built indexes.** `source.yaml` can declare *where the
already-built index lives* (a git repo, or a shared resource such as a
network path or another connector-reachable location). Every run checks
that location: if it already has an index, fetch it; if it doesn't yet,
a write-access user's run is what creates it there for the first time.
Either way, a read-only user just gets whatever's already there — they
never have to build the index from scratch themselves.
- **Read vs. write access, per user, per source.** Building/refreshing an
index from the live connector is gated by a **local, per-user** setting
(`libs/<name>/source.local.yaml`, never committed) — read-only by
default. This lets a team designate one or two people as the "admin" of
a given external source, while everyone else just consumes whatever
index the admin has already published, without needing their own
connector authorization or triggering redundant/conflicting rebuilds.
- **Shared, pre-built indexes.** `source.yaml` can declare where the already-built
index lives (a git repo, or a shared resource). Every run checks that location and
fetches what is there; a write-access user's run is what creates it the first time.
A read-only user never builds an index from scratch.
- **Read vs. write access, per user, per source.** Rebuilding from the live connector
is gated by `libs/<name>/source.local.yaml` (never committed), read-only by default,
so a team can designate one or two admins per source.
This skill only ever writes within a connector-backed `libs/<name>/` (never
`source.yaml` itself, never a git-copy lib, never anything under `wiki/`)
— and it never touches this repo's own git remote; pushing the resulting
changes is a separate, explicit step (see Step 8).
## Trigger phrases
Use this skill when the user says:
- "Index external sources"
- "Index libs"
- "Refresh the external index"
- "Scan the SharePoint/Drive folder" (or similarly names a specific
connector)
- "Make me the admin for `<source>`" / "give me write access to `<source>`"
/ "I don't want write access to `<source>` anymore" — a lighter-weight
request that only touches that one source's `source.local.yaml` (see
Configuration below) and doesn't necessarily trigger a full re-index in
the same turn unless the user also asks for one.
Do **not** use this skill for "Ingest" / "Sync the wiki" (that's
`ckb-ingest` — raw material into `wiki/`, unrelated to `libs/`), for
"Lint" (that's `ckb-lint`, which now also health-checks a connector's own
generated index, but doesn't build it in the first place), or for
answering a question against an index that already exists (that's
`ckb-retrieve`, which reads what this skill built and always verifies
against the underlying source before answering — this skill never answers
questions, only builds/refreshes the index).
Writes only within a connector-backed `libs/<name>/` — never `source.yaml` itself,
never a git-copy lib, never anything under `wiki/`. Never touches this repo's git
remote; pushing is a separate, explicit step (Step 8).
## Configuration
@ -433,77 +389,7 @@ was read-only with nothing new to fetch), skip this reminder.
## Edge cases
- **No connector-backed `libs/<name>/` exists** — report that and explain
how to add one; don't touch anything.
- **`source.local.yaml` doesn't exist yet for a source** — treat as
read-only; this is the correct default, not a misconfiguration worth
flagging loudly. Mention once, briefly, how to become the admin
(`access: write` in that file) if the user seems to expect a rebuild.
- **Everyone is read-only and nothing has ever been published** — report
that clearly rather than silently doing nothing; this is the one case
worth flagging as a real gap (nobody can currently index this source).
- **Connector not authorized this session** — report which one and how to
authorize it (claude.ai connector settings / `claude mcp` / `/mcp`),
skip that source, keep going with the rest. Never ask the user for
tokens or callback URLs.
- **Fetching a published index (Step 3) fails or the remote is
unreachable** — report it and fall back to whatever's already cached
locally in `libs/<name>/` from a previous fetch, rather than blocking
the whole run; don't let a transient network issue block a read-only
user from seeing the last-known index.
- **Re-running against an already-indexed source** — refresh existing
document *and* entity/process pages in place (update
`tldr`/`last_updated`/`confidence`/`source_fingerprint`/`source_checked`,
add newly-seen `mentioned_in` edges); never duplicate a document's or
entity's page, and carry every `## Notes` section across untouched.
- **A document's fingerprint is unchanged since the last run** — don't
re-summarize it. Advance `source_checked` to today, leave `last_updated`,
`tldr`, and `confidence` exactly as they were, and spend the run's budget
on the documents that did change. On a large source this is most of them,
and it is the difference between a re-index that costs a full pass and one
that costs a listing.
- **A document's fingerprint changed** — re-fetch and re-summarize it, and
say so in the report. A changed fingerprint on a document some wiki page
cites is worth calling out by name: that wiki page was built from a version
of this document that no longer exists.
- **A previously-indexed document is no longer found at the source** —
don't delete its page. Update its `tldr` with a note ("No longer found
at source as of YYYY-MM-DD") and set `retention: low`, so the existing
`ckb-lint` retention sweep archives it naturally on a later pass — no new
archival mechanism needed. Leave any entity pages that cite it alone;
the citation is still historically accurate even if the document itself
is gone.
- **An extracted entity already has a full page in `wiki/entities/`** —
keep this connector-side page thin (evidence/`mentioned_in` pointers
only, `resource:` set to the wiki page) rather than re-deriving
everything the wiki page already says; that duplication is exactly what
the cascade design is meant to avoid.
- **A document is dense with names/topics and extracting every one would
produce dozens of near-duplicate pages** — extract what's clearly named
and substantively discussed (not every passing mention), and prefer
updating an existing entity page's "Mentioned in" list over creating a
marginal new one. Don't force artificial granularity just to maximize
page count.
- **A document yields no extractable entity beyond itself** — that's fine;
its Step 5 document page is the only page it produces. Not every
document needs to feed Step 6.
- **A source is very large** — cap what gets fully fetched/summarized in
one run and explicitly report what was skipped (e.g. "42 of ~300
documents summarized this pass — re-run to continue"). Never silently
truncate while implying full coverage.
- **Write access but publishing (Step 8) conflicts with a newer version
someone else already pushed** — this is why Step 3 (fetch) always runs
first, even for write-access users: rebuild on top of the latest fetched
state rather than blindly overwriting it. If a real conflict still shows
up at publish time, report it rather than force-pushing over it.
- **`libs/<name>/` has both real content files and a `source.yaml`** —
ambiguous and out of scope for this skill to resolve; report it and stop
for that folder (this is the same case `ckb-lint`'s external-source
config check flags).
- **`source.yaml` is missing `connector` or `location`** — report it as
malformed and skip that source; don't guess at intent.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,79 @@
# ckb-index-external — edge cases
Reference material for the `ckb-index-external` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **No connector-backed `libs/<name>/` exists** — report that and explain
how to add one; don't touch anything.
- **`source.local.yaml` doesn't exist yet for a source** — treat as
read-only; this is the correct default, not a misconfiguration worth
flagging loudly. Mention once, briefly, how to become the admin
(`access: write` in that file) if the user seems to expect a rebuild.
- **Everyone is read-only and nothing has ever been published** — report
that clearly rather than silently doing nothing; this is the one case
worth flagging as a real gap (nobody can currently index this source).
- **Connector not authorized this session** — report which one and how to
authorize it (claude.ai connector settings / `claude mcp` / `/mcp`),
skip that source, keep going with the rest. Never ask the user for
tokens or callback URLs.
- **Fetching a published index (Step 3) fails or the remote is
unreachable** — report it and fall back to whatever's already cached
locally in `libs/<name>/` from a previous fetch, rather than blocking
the whole run; don't let a transient network issue block a read-only
user from seeing the last-known index.
- **Re-running against an already-indexed source** — refresh existing
document *and* entity/process pages in place (update
`tldr`/`last_updated`/`confidence`/`source_fingerprint`/`source_checked`,
add newly-seen `mentioned_in` edges); never duplicate a document's or
entity's page, and carry every `## Notes` section across untouched.
- **A document's fingerprint is unchanged since the last run** — don't
re-summarize it. Advance `source_checked` to today, leave `last_updated`,
`tldr`, and `confidence` exactly as they were, and spend the run's budget
on the documents that did change. On a large source this is most of them,
and it is the difference between a re-index that costs a full pass and one
that costs a listing.
- **A document's fingerprint changed** — re-fetch and re-summarize it, and
say so in the report. A changed fingerprint on a document some wiki page
cites is worth calling out by name: that wiki page was built from a version
of this document that no longer exists.
- **A previously-indexed document is no longer found at the source** —
don't delete its page. Update its `tldr` with a note ("No longer found
at source as of YYYY-MM-DD") and set `retention: low`, so the existing
`ckb-lint` retention sweep archives it naturally on a later pass — no new
archival mechanism needed. Leave any entity pages that cite it alone;
the citation is still historically accurate even if the document itself
is gone.
- **An extracted entity already has a full page in `wiki/entities/`** —
keep this connector-side page thin (evidence/`mentioned_in` pointers
only, `resource:` set to the wiki page) rather than re-deriving
everything the wiki page already says; that duplication is exactly what
the cascade design is meant to avoid.
- **A document is dense with names/topics and extracting every one would
produce dozens of near-duplicate pages** — extract what's clearly named
and substantively discussed (not every passing mention), and prefer
updating an existing entity page's "Mentioned in" list over creating a
marginal new one. Don't force artificial granularity just to maximize
page count.
- **A document yields no extractable entity beyond itself** — that's fine;
its Step 5 document page is the only page it produces. Not every
document needs to feed Step 6.
- **A source is very large** — cap what gets fully fetched/summarized in
one run and explicitly report what was skipped (e.g. "42 of ~300
documents summarized this pass — re-run to continue"). Never silently
truncate while implying full coverage.
- **Write access but publishing (Step 8) conflicts with a newer version
someone else already pushed** — this is why Step 3 (fetch) always runs
first, even for write-access users: rebuild on top of the latest fetched
state rather than blindly overwriting it. If a real conflict still shows
up at publish time, report it rather than force-pushing over it.
- **`libs/<name>/` has both real content files and a `source.yaml`** —
ambiguous and out of scope for this skill to resolve; report it and stop
for that folder (this is the same case `ckb-lint`'s external-source
config check flags).
- **`source.yaml` is missing `connector` or `location`** — report it as
malformed and skip that source; don't guess at intent.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -1,39 +1,19 @@
---
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 routed by CLAUDE.md/AGENTS.md, 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).
description: Process raw/inbox/ (or raw/ directly if the inbox is empty) into the structured wiki/: extract typed entities and relationships, synthesize frontmatted pages, cross-link them, then update the index and log. Use for "Ingest" or "Update the wiki". Never for a phrase containing "sync" — that is git, `ckb-sync-changes`.
---
# 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.
Turn raw, unstructured material in `raw/inbox/` (notes, links, pasted text, scratch
files) into the local, mutable, structured `wiki/` — the top cascade layer overlaying
the read-only KBs in `linked/` and `libs/`. This is the primary way the wiki grows.
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 8).
## 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.
Writes only to `wiki/` and moves processed files within `raw/`. Never touches
`linked/` or `libs/`, and never touches this repo's git remote; pushing is a separate,
explicit step (Step 8).
## How to run this skill
@ -270,24 +250,7 @@ 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 8 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 handled consistently with `ckb-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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,26 @@
# ckb-ingest — edge cases
Reference material for the `ckb-ingest` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Inbox and `raw/` both empty** — report that there's nothing to
ingest. Don't touch `wiki/`, and skip the Step 8 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 handled consistently with `ckb-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>.*

View file

@ -1,44 +1,27 @@
---
name: ckb-init
description: Bootstrap a brand-new Cascade Knowledge Base - the same directory structure, AGENTS.md/CLAUDE.md system prompt, full default skill set, LICENSE/VERSION, and empty wiki/ scaffold as this project - inside a target folder, sourcing the template either from this repo's own files or by pulling a fresh clone of the canonical ckb repo (or a user-supplied fork/mirror URL) into a scratch folder, so it works even when run outside an existing KB. The target folder is typically empty, or a new project that doesn't have a KB yet. Use when the user asks to "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", "create a knowledge base with this schema", "pull the ckb repo into this folder", "clone the wiki template into <dir>", or calls it a "wiki initializer". Also use when they name a release channel or branch to bootstrap from - "initialize from the test branch", "set up a dev KB from experimental", "bootstrap from <url> branch <name>" - since the template repo keeps main (stable), test (release candidate) and experimental (development) branches, and main is the default. Do not confuse with a generic `init` skill that documents an existing codebase - this one creates the Cascade KB pattern itself, empty, ready for its first ingest. Distinct from `ckb-upgrade`, which catches an *existing* populated KB up with template changes rather than bootstrapping a new one.
description: Bootstrap a brand-new, empty Cascade Knowledge Base in a target folder — directory structure, AGENTS.md/CLAUDE.md, the default skill set, LICENSE/VERSION, docs, and an empty wiki/ scaffold — sourcing the template from this repo or from a fresh clone of the canonical ckb repo, so it works from outside an existing KB. Use for "set up a new wiki like this one", "initialize a new cascade KB", "bootstrap a wiki here", or "clone the wiki template into <dir>".
---
# Cascade KB init skill
## Purpose
Copy the Cascade Knowledge Base *schema* - not its content - into a new
target folder: the directory structure, the `AGENTS.md`/`CLAUDE.md`
system prompt that defines how the KB behaves, the full default skill set,
`LICENSE` and `VERSION`, the generic `README`/`MANUAL` docs, and the empty
`wiki/` scaffold (routing table, overview, log, error book, entity/graph
indexes). The result is a new, empty KB that behaves exactly like this one,
ready for its first `raw/inbox/` drop and "Ingest."
Copy the Cascade KB *schema* — not its content — into a new target folder: the
directory structure, the `AGENTS.md`/`CLAUDE.md` system prompt, the default skill set,
`LICENSE` and `VERSION`, the generic docs, and the empty `wiki/` scaffold. The result
is a new, empty KB that behaves exactly like this one, ready for its first
`raw/inbox/` drop and "Ingest."
The template it copies from is either this repo's own files or a fresh
shallow clone of the canonical template repo pulled into a scratch folder
(Step 3) - the latter is what makes this skill usable from anywhere, not
only from inside an existing KB, and what "pull the repo into a folder to
set up a wiki" means in practice. Either way it is a one-way copy into a
different folder, and the clone is scratch: it never becomes the new KB's
`.git/`.
The template comes either from this repo's own files or from a fresh shallow clone of
the canonical template repo pulled into a scratch folder (Step 3) — the latter is what
makes this skill usable from anywhere. Either way it is a one-way copy, and the clone
is scratch: it never becomes the new KB's `.git/`.
It never reads or writes anything in the template source's `raw/`,
`wiki/entities/`, `wiki/graph/edges.json`, or `outputs/` - those hold that
project's actual accumulated knowledge, which is exactly what should *not*
travel into a fresh KB. (For catching an *already-populated* KB up with
newer template files without losing its accumulated content, see
`ckb-upgrade` instead - that skill does the same source-of-truth copying
this one does, but merges it into an existing KB rather than a blank
folder.)
## Trigger phrases
- "set up a new wiki like this one" / "initialize a new cascade KB"
- "bootstrap a wiki here" / "create a knowledge base with this schema"
- "wiki initializer" / "clone this KB structure into a new project"
- "pull the ckb repo into `<dir>` and set up the wiki structure"
- "initialize a KB from `<url>`" / "get the latest template and bootstrap a KB"
Never reads or writes the template source's `raw/`, `wiki/entities/`,
`wiki/graph/edges.json`, or `outputs/` — that is accumulated knowledge, which is
exactly what should not travel into a fresh KB. To catch an *already-populated* KB up
with newer template files, use `ckb-upgrade` instead.
## How to run this skill
@ -71,7 +54,7 @@ specifically.
### Step 3 - Resolve the template source
Everything this skill copies (`AGENTS.md`, `LICENSE`, `VERSION`, the
README/MANUAL docs, `.gitignore`, the `wiki/` scaffold, the skill set) comes
README, `docs/`, `.gitignore`, the `wiki/` scaffold, the skill set) comes
from one *template source*. There are two, and they produce the same result:
**a) A fresh clone of the canonical template repo (default when this skill
@ -244,13 +227,17 @@ actual project entity):
at this template's own canonical repo) unless the user says the new KB
should point somewhere else - it's what lets the new KB's own
`ckb-upgrade` find template updates later.
- `MANUAL.md` and `MANUAL.pl.md` - the task-oriented user guide.
- `CHANGELOG.md` and `CHANGELOG.pl.md` - the full page schema reference plus
- `docs/MANUAL.md` and `docs/MANUAL.pl.md` - the task-oriented user guide;
`docs/OPENSPEC*.md` - the software-module guide; `docs/decisions/` - the
template's own design records (D-0001, D-0002), which skills cite.
- `docs/CHANGELOG.md` and `docs/CHANGELOG.pl.md` - the full page schema reference plus
the schema and template version histories. Copy verbatim: the history
belongs to the template, not to the new KB, and a fresh KB starts on the
version that history ends at.
- `VERSION` - copy the exact current value; the new KB starts life on the
same template version it was just cloned from.
- `tests/` - the fixture KB, golden files and `smoke.sh`, copied wholesale so
the new KB can verify its own template layer after an upgrade.
Then write `ckb.yaml` at the new KB's root, recording where its tooling came
from so its own `ckb-upgrade` knows what to check later:
@ -430,34 +417,7 @@ Tell the user:
## Edge cases
- **Target is the current repo itself, or a parent/ancestor of it** - refuse
and explain why: this would either overwrite the live KB you're running
from, or nest a KB inside itself. Ask for a genuinely separate path.
- **Target is on a different filesystem/drive or requires elevated
permissions** - if directory creation fails, report the exact error
rather than retrying with escalated permissions.
- **User wants only *some* of the wiki template files** (e.g. just the
directory structure, no `AGENTS.md`) - honor that; the steps above are
the default full scaffold, not an all-or-nothing bundle.
- **Clone fails and there's no local KB to fall back on** - stop and report
the raw git error. Don't hand-write an approximation of the scaffold from
memory; a KB whose `AGENTS.md` is a paraphrase is worse than no KB.
- **User asks to clone the template repo straight into the target** - point
out that this gives them the template's git history and files rather than
a fresh KB, and offer both: a plain `git clone` (if that's really what
they want) or the scratch-clone-then-init flow, which is the default.
- **Target already contains a `.git/`** - proceed with the scaffold, but
skip Step 11's `git init`/commit and say so; committing into someone
else's repo is theirs to decide.
- **Scratch clone path already exists** (a previous run died mid-way) -
remove it before cloning (`rm -rf`), and remove it again when done. Never
reuse a half-cloned scratch dir.
- **This repo's own `AGENTS.md` or template `wiki/` files have since
drifted from each other** (e.g. one mentions a directory the other
doesn't) - fix the drift in *this* repo first if noticed, then copy the
corrected version. Don't propagate a known inconsistency into a new KB.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

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

View file

@ -1,55 +1,29 @@
---
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. Also runs the same checks against each connector-backed libs/<name>/'s own generated index (see ckb-index-external), plus a source.yaml validity check, without ever touching a git-copy lib or a connector's source.yaml itself. 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 routed by CLAUDE.md/AGENTS.md, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all).
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift — auto-fixing what is safe and reporting the rest. Also checks each connector-backed libs/<name>/ generated index. Use for "Lint", "health-check the wiki", "check the wiki", or a scheduled wiki health check.
---
# 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.
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. Maintenance, not growth — it never adds new
knowledge the way `ckb-ingest` does.
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.
**Detection** is mechanical, so it runs as a read-only Python script (Step 0) rather
than per-page model reasoning. What the script cannot decide is what this skill is
for: which findings to auto-fix, which to leave for the user, whether two pages
genuinely supersede one another, and whether a cluster of findings is a systemic
pattern worth an error-book entry. Read the report, then do that work.
The **detection** half of this checklist is mechanical — a fixed set of
frontmatter, date, link, graph, and index/log rules over a tree that keeps
growing — so it runs as a read-only Python script rather than as per-page
model reasoning (Step 0 below). What the script cannot decide is what this
skill is actually for: which findings to auto-fix, which to leave for the
user, whether two pages genuinely supersede one another, and whether a
cluster of findings is a systemic pattern worth an error-book entry. Read
the script's report, then do that work.
This skill only ever writes within `wiki/` (including moves into
`wiki/archived/`) and, for any connector-backed `libs/<name>/` (one with a
`source.yaml` — see `CLAUDE.md`/`AGENTS.md` directory contract) where this user has
local `access: write` (see `ckb-index-external`), within that connector's
own agent-owned generated index (`index.md`/`entities/`/`graph/`/`log.md`).
For a connector-backed `libs/<name>/` where this user is read-only (the
default), findings against that index are reported only, never auto-fixed
— the same access gate `ckb-index-external` applies to rebuilding applies
here too. It never touches `linked/`, a git-copy `libs/<name>/`, or a
connector's `source.yaml`/`source.local.yaml` — those stay immutable or
user-owned — 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).
Writes only within `wiki/` (including moves into `wiki/archived/`) and, for a
connector-backed `libs/<name>/` where this user has local `access: write` (see
`ckb-index-external`), within that connector's own generated index. Where the user is
read-only — the default — findings against that index are reported, never auto-fixed.
Never touches `linked/`, a git-copy lib, a connector's `source.yaml`/
`source.local.yaml`, or this repo's git remote; pushing is a separate, explicit step.
## How to run this skill
@ -318,37 +292,7 @@ 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 `total findings: 0`
report is a valid outcome; say so plainly rather than hunting for
something to say.
- **A page's frontmatter is unparseable** (not just missing `type`, but
invalid YAML) — the script reports it under conformance and skips it in
the later checks rather than reasoning from a half-parsed page. Surface
it prominently and fix the frontmatter first; a page can't be judged
stale, orphaned, or archivable until it parses.
- **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** — produces the
same report each time (pass `--today` to pin the date if you need a
byte-identical one); don't invent variation just to seem active.
- **A changed fingerprint and a diverged crux quote on the same page** —
one incident, not two. The source was edited; fix the page once against
the new content and re-stamp both the digest and the quote together.
- **Every page in the wiki lacks fingerprints** — a wiki built before this
convention. Don't stamp them all in one pass; that produces a tree of
digests attesting to nothing anyone verified. Report the count, and
backfill as pages are touched for other reasons.
- **The script errors out or isn't runnable** (no Python 3, unreadable
tree) — say so and fall back to working the numbered checks by hand
rather than reporting a clean bill of health you didn't actually verify.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,39 @@
# ckb-lint — edge cases
Reference material for the `ckb-lint` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Wiki is empty or near-empty** — report that there's little to lint
yet; don't fabricate findings to look thorough. A `total findings: 0`
report is a valid outcome; say so plainly rather than hunting for
something to say.
- **A page's frontmatter is unparseable** (not just missing `type`, but
invalid YAML) — the script reports it under conformance and skips it in
the later checks rather than reasoning from a half-parsed page. Surface
it prominently and fix the frontmatter first; a page can't be judged
stale, orphaned, or archivable until it parses.
- **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** — produces the
same report each time (pass `--today` to pin the date if you need a
byte-identical one); don't invent variation just to seem active.
- **A changed fingerprint and a diverged crux quote on the same page** —
one incident, not two. The source was edited; fix the page once against
the new content and re-stamp both the digest and the quote together.
- **Every page in the wiki lacks fingerprints** — a wiki built before this
convention. Don't stamp them all in one pass; that produces a tree of
digests attesting to nothing anyone verified. Report the count, and
backfill as pages are touched for other reasons.
- **The script errors out or isn't runnable** (no Python 3, unreadable
tree) — say so and fall back to working the numbered checks by hand
rather than reporting a clean bill of health you didn't actually verify.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -1,6 +1,6 @@
---
name: ckb-module
description: Install, list, or uninstall an optional Cascade KB module from .agents/modules/<name>/ — copying its skills into .agents/skills/, creating its scaffold directories, appending its routing block to AGENTS.md and its rules to .gitignore, and recording it in the root ckb.yaml manifest. Use when the user says "install the software module", "add the <name> module", "what modules are available", "which modules are installed", "uninstall the <name> module", or asks to make this KB handle source code / a capability the base KB doesn't have. Distinct from `ckb-init` (bootstraps a whole new KB) and `ckb-upgrade` (catches the template layer up with upstream); this skill toggles optional capabilities within an existing KB.
description: Install, list, or uninstall an optional Cascade KB module from .agents/modules/<name>/. Use for "install the <name> module", "what modules are available", "which modules are installed", "uninstall the <name> module", or a request for a capability the base KB lacks, such as handling source code.
---
# Module skill
@ -8,23 +8,16 @@ description: Install, list, or uninstall an optional Cascade KB module from .age
## Purpose
The base KB ships every skill always-loaded. Some capabilities are only useful to
*some* knowledge bases, and their skill descriptions would otherwise sit in
context for every KB that will never need them.
*some* knowledge bases, and their skill descriptions would otherwise sit in context
for every KB that will never need them.
Optional capabilities therefore live in `.agents/modules/<name>/` — present in the
repo, inert until installed. This skill is the install/uninstall path. See
[D-0001](/wiki/decisions/0001-opt-in-file-based-kb-modules.md) for why this is
[D-0001](/docs/decisions/0001-opt-in-file-based-kb-modules.md) for why this is
files-in-the-repo rather than a native agent plugin: a module is a property of the
knowledge base, so it must travel with a clone and work for any agent that reads
`AGENTS.md`.
## Trigger phrases
- "install the `<name>` module" / "add the `<name>` module" / "enable `<name>`"
- "what modules are available" / "which modules are installed"
- "uninstall the `<name>` module" / "remove `<name>`" / "disable `<name>`"
- "make this KB handle source code" (→ offer the `software` module)
## The manifest
Installed modules are recorded in `ckb.yaml` at the repo root:
@ -160,19 +153,7 @@ On "what modules are available": list `.agents/modules/*/module.yaml` with each
## Edge cases
- **A module directory with no `module.yaml`** — not a module. Report it as
malformed; don't try to infer its contents from its file layout.
- **The user asks for a capability no module provides** — say so, and don't
install a near-match hoping it fits. Offer to note it in `wiki/query-gaps.md`.
- **`ckb-upgrade` brought a newer version of an installed module** — the installed
skill copies are stale. Offer to reinstall; show what changed before doing it.
- **Markers missing at uninstall** (someone hand-edited `AGENTS.md`) — don't
guess at the block's boundaries. Show the fragment and ask the user to remove
it, or point at exactly what to delete.
- **A module's skill was renamed upstream** — treat as collision (Step 2), ask.
Don't delete the old name automatically.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,21 @@
# ckb-module — edge cases
Reference material for the `ckb-module` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **A module directory with no `module.yaml`** — not a module. Report it as
malformed; don't try to infer its contents from its file layout.
- **The user asks for a capability no module provides** — say so, and don't
install a near-match hoping it fits. Offer to note it in `wiki/query-gaps.md`.
- **`ckb-upgrade` brought a newer version of an installed module** — the installed
skill copies are stale. Offer to reinstall; show what changed before doing it.
- **Markers missing at uninstall** (someone hand-edited `AGENTS.md`) — don't
guess at the block's boundaries. Show the fragment and ask the user to remove
it, or point at exactly what to delete.
- **A module's skill was renamed upstream** — treat as collision (Step 2), ask.
Don't delete the old name automatically.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -1,31 +1,20 @@
---
name: ckb-onboard-me
description: Given a topic, walk the wiki knowledge graph and print a guided reading order — a mini tour. Produces a short overview of the topic plus the best sequence of wiki pages to read and what you'll find in each, ordered so prerequisites come before the pages that build on them. Use when the user says "onboard me on X", "give me a reading order for X", "where do I start with X", "walk me through X", "mini tour of X", "guided tour of X", or "what should I read to understand X".
description: Walk the wiki knowledge graph for a topic and print a guided reading order — a short overview plus the best sequence of pages to read, prerequisites first. Use for "onboard me on X", "where do I start with X", "walk me through X", "mini tour of X", or "what should I read to understand X".
---
# Onboard me (guided wiki tour) skill
## Purpose
Turn a topic into a **reading order**: a short scene-setting overview followed
by an ordered list of wiki pages to read, each with a one-line note on what
you'll find there and why it comes at that point. It's a mini onboarding tour
built by walking the knowledge graph outward from the topic, so a newcomer
learns things in a sensible order — foundations first, then the topic itself,
then what builds on it.
Turn a topic into a **reading order**: a short scene-setting overview followed by an
ordered list of wiki pages, each with a one-line note on what you'll find there and
why it comes at that point. Built by walking the knowledge graph outward from the
topic — foundations first, then the topic, then what builds on it.
This skill is **read-only**. It never writes to `wiki/`, so it does not touch
`wiki/log.md`. It synthesizes a route through existing knowledge; it does not
add new claims. If the wiki has nothing on the topic, say so — don't invent a
tour.
## Trigger phrases
Use this skill when the user says things like:
- "onboard me on X" / "get me up to speed on X"
- "where do I start with X" / "what should I read to understand X"
- "give me a reading order for X" / "reading list for X"
- "walk me through X" / "mini tour of X" / "guided tour of X"
**Read-only.** Never writes to `wiki/`, so it never touches `wiki/log.md`. It
synthesizes a route through existing knowledge; it adds no new claims. If the wiki has
nothing on the topic, say so — don't invent a tour.
## How to run this skill
@ -126,23 +115,7 @@ Close with a short offer: to go deeper on any single step, to widen the tour
## Edge cases
- **Anchor has no edges and no outgoing links** — the tour is just the anchor.
Print its overview and say it's currently a standalone page with no mapped
connections; suggest an Ingest may add links later.
- **Topic spans several disconnected clusters** — if the graph walk finds two
unrelated groups, present them as two short mini-tours under one topic rather
than forcing a single misleading sequence.
- **Broken edge (points to a missing page)** — skip it silently in the tour,
but mention at the end that the graph has a dangling edge so the user can run
Lint. Do not fabricate the missing page.
- **Very fresh material in `workload/` not yet in the wiki** — this skill tours
`wiki/` only. If the user expects a topic that was just discussed but not yet
ingested, note that it isn't in the wiki yet and point them at Ingest.
- **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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,25 @@
# ckb-onboard-me — edge cases
Reference material for the `ckb-onboard-me` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Anchor has no edges and no outgoing links** — the tour is just the anchor.
Print its overview and say it's currently a standalone page with no mapped
connections; suggest an Ingest may add links later.
- **Topic spans several disconnected clusters** — if the graph walk finds two
unrelated groups, present them as two short mini-tours under one topic rather
than forcing a single misleading sequence.
- **Broken edge (points to a missing page)** — skip it silently in the tour,
but mention at the end that the graph has a dangling edge so the user can run
Lint. Do not fabricate the missing page.
- **Very fresh material in `workload/` not yet in the wiki** — this skill tours
`wiki/` only. If the user expects a topic that was just discussed but not yet
ingested, note that it isn't in the wiki yet and point them at Ingest.
- **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>.*

View file

@ -1,30 +1,21 @@
---
name: ckb-project-summary
description: Generate or refresh a one-to-two-page project overview at the repo root, synthesized entirely from the current wiki/ contents — overview paragraph, project state, actions and their status, risks, and assumptions. Use when the user asks for "a project summary", "project overview", "give me the state of the project", "where do things stand", "summarize the project", or wants a quick top-level snapshot without reading the whole wiki.
description: Generate or refresh a one-to-two-page project overview at the repo root, synthesized from current wiki/ contents: overview, project state, actions and their status, risks, and assumptions. Use for "project summary", "project overview", "where do things stand", or "summarize the project".
---
# Project summary skill
## Purpose
Produce a short, standalone snapshot of the project at repo root - something
a busy stakeholder can read in two minutes without opening `wiki/` at all.
Everything in it must trace back to what the wiki actually says; this is a
synthesis of existing knowledge, not a place to add new claims or guesses.
Produce a short, standalone snapshot of the project at repo root — something a busy
stakeholder can read in two minutes without opening `wiki/` at all. Everything in it
must trace back to what the wiki actually says; this is a synthesis of existing
knowledge, not a place to add new claims or guesses.
This is a one-way, on-demand export - `wiki/` stays the authoritative
source; the generated overview file is always a derived, refreshable
snapshot. Re-running the skill regenerates it from whatever the wiki says
One-way and on-demand: `wiki/` stays authoritative and the generated overview is a
derived, refreshable snapshot. Re-running regenerates it from whatever the wiki says
*now*; it does not append to the previous version.
## Trigger phrases
Use this skill when the user says things like:
- "give me a project summary" / "project overview"
- "where do things stand" / "what's the state of the project"
- "summarize the project" / "one-pager" / "two-pager"
- "catch me up on the project"
## How to run this skill
### Step 1 - Identify the project
@ -163,20 +154,7 @@ whatever the wiki says at that moment, not what it said today.
## Edge cases
- **Empty or near-empty project entity page** - write a short, honest
Overview and State, and let Actions/Risks/Assumptions be genuinely short
rather than inventing content to fill the template.
- **Conflicting information between two source pages** - prefer the page
with the more recent `last_updated`; if they're the same date, note the
conflict briefly in Project State rather than silently picking one.
- **`PROJECT-OVERVIEW.md` already exists** - overwrite it; this file is
always meant to reflect the current wiki, not accumulate history. If the
user wants history, that's what `wiki/log.md` and `workload/` are for.
- **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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,22 @@
# ckb-project-summary — edge cases
Reference material for the `ckb-project-summary` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Empty or near-empty project entity page** - write a short, honest
Overview and State, and let Actions/Risks/Assumptions be genuinely short
rather than inventing content to fill the template.
- **Conflicting information between two source pages** - prefer the page
with the more recent `last_updated`; if they're the same date, note the
conflict briefly in Project State rather than silently picking one.
- **`PROJECT-OVERVIEW.md` already exists** - overwrite it; this file is
always meant to reflect the current wiki, not accumulate history. If the
user wants history, that's what `wiki/log.md` and `workload/` are for.
- **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>.*

View file

@ -7,11 +7,10 @@ description: Quiz the user on knowledge captured in the wiki. Reads wiki pages,
## 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.
---
Turn the wiki into a live, scored quiz: read the relevant pages, generate questions
grounded in actual facts from them, run them one at a time with immediate feedback,
and deliver a final score with a brief verdict. It should feel like a game —
fast-paced, specific, and satisfying to get right.
## How to run this skill
@ -191,13 +190,7 @@ Wait for the answer. If yes, go back to Step 2 with the new parameters. If no, c
## 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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,15 @@
# ckb-quiz — edge cases
Reference material for the `ckb-quiz` skill. Read when a
run hits an unusual situation the main steps don't cover.
**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>.*

View file

@ -1,6 +1,6 @@
---
name: ckb-reset
description: DESTRUCTIVE — empty this knowledge base back to a clean template, deleting every accumulated wiki page, decision record, graph edge, log entry, workload summary and (on request) raw/outputs material, then restoring the empty scaffold that `ckb-init` would create. Use when the user says "reset the wiki", "empty the wiki", "clean this KB out", "make this a clean template", "wipe the knowledge base", or wants to turn a working KB back into a distributable template. Always inventories what would be destroyed and takes explicit confirmation before deleting anything. Never touches the template layer (AGENTS.md, skills, modules, docs) or `src/`.
description: DESTRUCTIVE — empty this knowledge base back to a clean template, deleting every accumulated wiki page, decision record, graph edge, log entry and workload summary, then restoring the empty scaffold. Always inventories what would be destroyed and takes typed confirmation first. Use for "reset the wiki", "empty the wiki", "clean this KB out", or "wipe the knowledge base".
---
# Reset skill
@ -12,16 +12,10 @@ shouldn't ship with it — decisions made about this project, workload summaries
entity pages, graph edges. This skill returns it to the shape `ckb-init` creates:
same structure, same schema, no knowledge.
It is the only skill in this KB that deletes knowledge on purpose. Everything
below is written on the assumption that **getting this wrong destroys work that
took a long time to accumulate**, and that "the user asked for it" is not enough
on its own — people ask for this in the wrong repo.
## Trigger phrases
- "reset the wiki" / "empty the wiki" / "wipe the knowledge base"
- "clean this KB out" / "make this a clean template"
- "turn this back into a template" / "strip the content but keep the structure"
It is the only skill in this KB that deletes knowledge on purpose. Everything below is
written on the assumption that **getting this wrong destroys work that took a long
time to accumulate**, and that "the user asked for it" is not enough on its own —
people ask for this in the wrong repo.
## Non-negotiable safety rules
@ -29,7 +23,7 @@ on its own — people ask for this in the wrong repo.
after it.** Not "proceed?" before you know the scale — the count is the thing
that makes the answer meaningful.
2. **Never touch the template layer.** `AGENTS.md`, `CLAUDE.md`, `.agents/`,
`.claude/`, `LICENSE`, `VERSION`, `README*`, `MANUAL*`, `OPENSPEC*`,
`.claude/`, `LICENSE`, `VERSION`, `README*`, `docs/`, `tests/`,
`.gitignore`, `ckb.yaml`, `.git/`. Those *are* the template.
3. **Never touch `src/`.** Those are independent repositories holding code this
skill has no business deleting. Not even with confirmation — tell the user to
@ -176,26 +170,7 @@ everything until it is. That sentence is the last safety net, so don't omit it.
## Edge cases
- **Already clean** — say so and change nothing. Don't rewrite identical scaffold
files to look busy.
- **Run in a KB that is not a template** — this skill can't tell the difference,
so if the wiki holds substantial content (say, 50+ pages or any decision
records), name that in the confirmation: "This KB has 12 decision records —
templates don't usually have those. Are you in the right repository?" Ask once;
don't refuse if they confirm.
- **`linked/` symlinks** — never follow them when deleting. `rm -rf linked/foo`
where `foo` is a symlink to another KB is catastrophic and silent. Remove the
*link*, never its target, and prefer leaving tier 5 alone.
- **Partial failure mid-delete** — stop, report exactly what was and wasn't
deleted, and point at the restore point. Don't continue on the theory that
finishing is tidier.
- **User asks to reset "everything including the skills"** — that's not a reset,
it's deleting the KB. Say so and point at `ckb-init` for a fresh one elsewhere.
- **Module installed** — module-created page types (`repository`, `component`,
`spec`) are wiki content and reset with tier 1. The module itself stays
installed unless tier 6 was chosen.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,28 @@
# ckb-reset — edge cases
Reference material for the `ckb-reset` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Already clean** — say so and change nothing. Don't rewrite identical scaffold
files to look busy.
- **Run in a KB that is not a template** — this skill can't tell the difference,
so if the wiki holds substantial content (say, 50+ pages or any decision
records), name that in the confirmation: "This KB has 12 decision records —
templates don't usually have those. Are you in the right repository?" Ask once;
don't refuse if they confirm.
- **`linked/` symlinks** — never follow them when deleting. `rm -rf linked/foo`
where `foo` is a symlink to another KB is catastrophic and silent. Remove the
*link*, never its target, and prefer leaving tier 5 alone.
- **Partial failure mid-delete** — stop, report exactly what was and wasn't
deleted, and point at the restore point. Don't continue on the theory that
finishing is tidier.
- **User asks to reset "everything including the skills"** — that's not a reset,
it's deleting the KB. Say so and point at `ckb-init` for a fresh one elsewhere.
- **Module installed** — module-created page types (`repository`, `component`,
`spec`) are wiki content and reset with tier 1. The module itself stays
installed unless tier 6 was chosen.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -1,59 +1,36 @@
---
name: ckb-retrieve
description: Governs how a question actually gets answered from the knowledge base. An index entry — a wiki page's `tldr`, a connector-index document/entity page — is deliberately compressed so lazy-loading stays cheap; that compression also means it can be incomplete, paraphrased loosely, or stale relative to the real source. This skill makes "go verify against the source before answering" a standing step, not an optional last resort: every time a page surfaced by the index looks relevant enough to actually ground part of the answer, follow it to its underlying source material — a wiki page's own `## Sources` citations into `raw/archive/`/`outputs/`, or a connector-index page's `resource:` pointer back to the live connector item — before treating its content as settled. Use whenever answering a question or researching a topic from `wiki/`, `linked/<name>/`, or a connector-backed `libs/<name>/` — this is the retrieval workflow routed by CLAUDE.md/AGENTS.md, always in play, not something the user needs to name explicitly. Distinct from `ckb-onboard-me` (produces a reading-order tour, not an answer to a specific question) and from the write-side skills `ckb-ingest`/`ckb-index-external`/`ckb-lint` (build or repair the index; this skill only ever reads it, plus the sources behind it).
description: Answer a question or research a topic from wiki/, linked/<name>/, or a connector-backed libs/<name>/. Index entries (a page's tldr, a connector-index entry) are compressed and can be stale, so this skill makes verifying a surfaced page against its underlying source a standing step before grounding an answer on it. Always in play for KB questions; the user need not name it.
---
# Retrieve (source-verified query) skill
## Purpose
The whole point of `tldr`/lazy-loading (CLAUDE.md/AGENTS.md index-first
navigation and skill routing) is that most of the wiki never has to enter
context — a one-sentence summary decides
whether a page is worth opening at all. That's the right trade for
*deciding relevance*. It's the wrong trade for *grounding an answer*: a
`tldr` is a compression of whatever the page's author judged important at
write time, a connector-index entity page is (per `ckb-index-external`)
deliberately a thin pointer rather than a synthesis, and either can have
drifted from the primary material since — a source updated, a nuance
dropped, a paraphrase that's subtly wrong.
Index-first navigation means most of the wiki never enters context: a one-sentence
`tldr` decides whether a page is worth opening. That's the right trade for *deciding
relevance* and the wrong one for *grounding an answer* — a `tldr` compresses whatever
the author judged important at write time, a connector-index entity page is
deliberately a thin pointer, and either can have drifted from the primary material
since.
This skill closes that gap: once a page looks relevant enough to actually
use in an answer, don't stop at its `tldr` or even its full synthesized
body — follow it to the source material that page was built from, and
answer from there. It's the difference between citing what the index
*says about* the evidence and citing the evidence.
This skill closes that gap: once a page looks relevant enough to actually use in an
answer, don't stop at its `tldr` or even its full synthesized body — follow it to the
source material it was built from and answer from there. It is the difference between
citing what the index *says about* the evidence and citing the evidence.
This skill is **read-only**. It never writes to `wiki/`, `libs/<name>/`,
or anywhere else — it only reads what already exists (the index, and the
source material behind it) to answer the question in front of it. If
verification surfaces a real gap or contradiction worth fixing in the
wiki, say so and suggest `ckb-lint`/`ckb-ingest` rather than editing
anything mid-answer.
**Read-only, with one exception.** It reads the index and the sources behind it and
never edits a page mid-answer — a gap or contradiction it surfaces is reported and
handed to `ckb-lint`/`ckb-ingest`. The one write it owns is `wiki/query-gaps.md`: a
question the cascade could not answer is recorded there (Step 7), logged in
`wiki/log.md` like any other wiki change.
## Trigger phrases
This is the default retrieval path for **any** question answered from the
knowledge base — the user does not need to name this skill. Typical
prompts that should route here:
- A direct question answerable from the wiki ("what do we know about X",
"what's the status of Y", "who owns Z").
- "Look up X" / "check the wiki for X" / "search for X".
- Mid-conversation moments where CLAUDE.md/AGENTS.md routes a KB question
to retrieval — this skill *is* that workflow's implementation.
Do **not** use this skill for:
- Building or refreshing an index in the first place — that's
`ckb-ingest` (raw material → `wiki/`) or `ckb-index-external`
(connector → `libs/<name>/`). This skill only ever consumes what those
produced.
- A guided reading order across many pages on a topic — that's
`ckb-onboard-me`. This skill answers one question with verified
evidence; it doesn't produce a curriculum.
- Health-checking the index's own structure (frontmatter, staleness,
broken links) — that's `ckb-lint`. Verification failures found here
(Edge cases, below) are worth mentioning to the user as a possible lint
finding, but this skill doesn't run the lint checklist itself.
The mechanical half — gathering ranked lists from each signal and fusing them — runs
as `scripts/retrieve_candidates.py`, for the same reason lint's detection runs as a
script: a fixed procedure over a growing tree belongs in code, not in per-question
model arithmetic. Judgment stays here: what the question actually asks, which
candidates carry the same claim, and whether the source still says what the page
says.
## How to run this skill
@ -82,110 +59,69 @@ Same cascade order as CLAUDE.md/AGENTS.md, first match wins:
suggest "index external sources" rather than querying the live
connector ad hoc from inside this skill.
### Step 2 — Shortlist every page that looks relevant
Read the `tldr` of every page the index match surfaced — don't stop at
the first plausible hit. A question is often best answered by
triangulating two or three pages (e.g. a concept page plus the specific
person/decision page that qualifies it), and a page whose `tldr` looks
only tangential can still be hiding the exact fact needed in its body or
its Sources. Keep the shortlist to what's plausibly relevant; this isn't
"open everything," it's "don't stop at one."
If index/TLDR matching is not enough, run a local hybrid pass before
giving up: use `rg` for exact tokens across `wiki/`, `raw/archive/`,
`outputs/`, `raw/inbox/`, and readable upstream indexes; combine those
hits with project-scope matches, entity/title/TLDR matches, graph
proximity, freshness, confidence, and quality. Prefer exact text matches
for error strings, commands, flags, filenames, hostnames, IDs, and other
literals; prefer entity/semantic matches for paraphrased questions.
Sweep `raw/inbox/` even though nothing there has been ingested yet.
Material dropped an hour ago can already hold the answer, and finding it
there is also the clearest possible signal that an `ckb-ingest` run is
overdue — mention that. Say plainly when an answer rests on un-ingested
inbox material rather than on a synthesized page.
Keep each signal's hits as its own ranked list rather than merging them by
eye as you go. Step 4 needs the separate orderings.
### Step 3 — Walk the graph for anything the shortlist missed
If a shortlisted page has edges in `wiki/graph/edges.json` (or a
connector's own `graph/edges.json`), follow `depends_on`/`uses`/`caused`
edges one hop out to catch a connected page the index text match alone
wouldn't have surfaced.
For "who knows about X" and "who owns X" questions — both advertised in
the trigger phrases above — the graph is the primary lookup rather than a
fallback. Read the `has_expertise_in` and `owns` edges pointing at the
topic entity and answer from the people or teams on the other end,
ordered by how many distinct sources evidence each edge. Where no such
edge exists yet, fall back to authorship evidence: who the `## Sources`
material actually shows answering questions on that topic. Say which of
the two grounded the answer, since an inferred expert is a weaker claim
than a recorded one.
While the edge file is open, build one more ranked list for Step 4:
**in-degree** — for each candidate already on the shortlist, how many edges
point *at* it.
### Step 2 — Run the candidate script
```bash
python3 -c "import json,collections;e=json.load(open('wiki/graph/edges.json'))['edges'];\
c=collections.Counter(x['to'] for x in e);print(c.most_common(20))"
python3 .agents/skills/ckb-retrieve/scripts/retrieve_candidates.py "<the question>" [--scope <project-slug>]
```
Centrality is a genuinely different signal from every other one in Step 4:
text match, freshness, confidence and quality are all properties of a page in
isolation, while in-degree is what the rest of the KB has to say about it. A
page a dozen others depend on is usually the one that settles a question;
a leaf page with an identical `tldr` usually isn't. Rank only the candidates
already shortlisted — this ranks the shortlist, it doesn't widen it. Skip the
list entirely when `edges.json` is empty or every candidate has in-degree 0,
since a list with no ordering contributes nothing to the fusion.
It builds one ranked list per signal — exact `rg` hits across `wiki/`,
`raw/archive/`, `raw/inbox/`, `outputs/`, `linked/*/` and connector-backed
`libs/*/`; title/`tldr` token overlap; pages a matching `wiki/projects/` scope
lists; one-hop graph neighbours of the text-matched shortlist; in-degree; and
a confidence×quality×freshness "trust" list — then fuses them with reciprocal
rank fusion (`weight / (k + rank)`, `k = 10`, exact-match weighted 2.0 when the
question carries literal tokens, in-degree 0.5, trust 0.3). A page ranked third
by three signals beats one ranked first by a single signal; consensus is the
point. `--json` gives the same result as data.
### Step 4 — Fuse the signals, dedupe, then rerank
Read the whole output, not the first line. Each candidate shows which lists it
came from and at what rank, its `tldr`, `STALE`/`INBOX`/`SUPERSEDED` flags, and
any `raw/archive/` or `outputs/` file it cites that the script folded in as
corroboration rather than counting as a second source.
Signals disagree, and none of them is trustworthy alone: an exact `rg` hit
can sit in a page that answers a different question, and a confident TLDR
match can be a loose paraphrase of something stale. Don't settle that by
picking a favourite signal — fuse the ranked lists from Step 2.
Two lines of the header matter on their own:
**Fuse.** For every candidate, sum `weight / (k + rank)` across each list
it appears in, where `rank` is its 1-based position in that list. Use
`k = 10` and a default `weight` of 1.0. A page ranked third in three
different lists beats one ranked first in a single list; consensus is the
whole point.
- **`raw/inbox/ hits`** — un-ingested material already holds something
relevant. It can answer the question, and it is the clearest signal an
`ckb-ingest` run is overdue; say both.
- **`graph: empty`** — the graph and in-degree lists were skipped, so the
fusion rests on text signals alone. Say so if it affects confidence.
Give the in-degree list a weight *below* 1.0 (around 0.5 is a reasonable
start). Centrality is a prior, not evidence — it says a page matters
generally, not that it answers this question — so it should break ties
between comparable candidates without ever promoting a page the text signals
didn't surface.
### Step 3 — Shortlist, and walk the graph for what the text missed
`k = 10` is deliberately smaller than the `k = 60` rank fusion is usually
quoted with. 60 is tuned for retrievers returning hundreds of candidates,
and against the dozen-or-so a local wiki produces it flattens every score
into near-identical values. Raise a list's weight when the question
warrants it — for a pasted error string, command, flag, or ID, weight the
exact-match list around 2.0, because no amount of title/TLDR similarity
should outrank a literal match on the token the user actually pasted.
Keep every candidate that is plausibly relevant — not just the top one. A
question is often best answered by triangulating two or three pages (a concept
page plus the person or decision page that qualifies it), and a page whose
`tldr` looks tangential can hide the exact fact in its body or `## Sources`.
This isn't "open everything"; it's "don't stop at one."
**Dedupe.** Collapse candidates carrying the *same claim* into one entry
before ranking further. Step 6 actively manufactures these: a `wiki/`
page, the `raw/archive/` file it cites, and a connector-index page whose
`resource:` points back at that same wiki page are three hits for one
fact. Keep whichever sits closest to the primary material and record the
others as corroboration, not as independent evidence. Three views of one
claim are not three sources.
For "who knows about X" / "who owns X", the graph is the primary lookup, not a
fallback: read the `has_expertise_in` and `owns` edges pointing at the topic
entity and answer from the people on the other end, ordered by how many
distinct sources evidence each edge. Where no such edge exists, fall back to
authorship evidence — who the `## Sources` material actually shows answering on
that topic — and say which of the two grounded the answer; an inferred expert
is a weaker claim than a recorded one.
**Rerank.** Score each surviving candidate 0–10 on how well it answers
*the literal question asked*, not on how well it matches the query's
vocabulary, then keep the best handful and drop the rest. This is the same
agent making a deliberate second pass, not a separate model. The point is
that relevance judgment happens explicitly, over the shortlist, in one
place — rather than being folded silently into how the final answer gets
drafted.
If decisions *are* the subject, hand off to `ckb-decide` (Step 1.4). A
superseded decision that surfaces here is history, not noise — say so rather
than silently answering from the current one.
### Step 4 — Dedupe by claim, then rerank against the literal question
The script folds a cited archive file into the page that cites it; the rest of
dedupe is judgment. Collapse candidates carrying the *same claim* into one
entry: a `wiki/` page, a connector-index page whose `resource:` points back at
it, and a `linked/` mirror of the same fact are three hits for one claim. Keep
whichever sits closest to the primary material and record the others as
corroboration. Three views of one claim are not three sources.
Then score each survivor 0–10 on how well it answers *the question as asked*,
not how well it matches the question's vocabulary — the fusion measured the
latter. Keep the best handful, drop the rest. This is the same agent making a
deliberate second pass, in one place, rather than folding relevance judgment
silently into how the answer gets drafted.
### Step 5 — Expand local context and build an evidence packet
@ -195,8 +131,8 @@ For every result that survived Step 4, keep a small evidence packet with:
- source date or `last_updated`
- freshness/confidence/quality signals, when available
- project-scope or graph relationship hints, when relevant
- which signals it was fused from, its rerank score, and anything it
absorbed during dedupe — this is what Step 7 draws caveats from
- which signals it was fused from (the script's `ranks`), its rerank score,
and anything it absorbed during dedupe — this is what Step 7 draws caveats from
When a match is a section, heading, or snippet inside a larger Markdown
file, include nearby headings/paragraphs before deciding what it means.
@ -272,65 +208,21 @@ un-ingested `raw/inbox/` material, or was checked against a cached
connector index rather than a live re-fetch, say so in a short clause next
to the claim it qualifies. Surface a conflict between two live pages the
same way, even when neither is marked `superseded_by` yet. The metadata
already exists and Step 4 already put it in front of you; the failure mode
already exists and the script's flags already put it in front of you; the failure mode
is answering confidently *from* a stale or contested page without passing
that on, which leaves the reader no way to weigh it.
If no page anywhere is even plausibly relevant, say so — don't verify
against a source that has nothing to do with the question just to appear
thorough, and don't fabricate an answer either. For durable missing
knowledge, add or propose a short `wiki/query-gaps.md` entry with the
knowledge, add a short `wiki/query-gaps.md` entry under `## Open` with the
question, date, search areas tried, and the smallest missing source/page
that would close the gap. If you edit `wiki/query-gaps.md`, update
`wiki/log.md` immediately.
that would close the gap — this is the one write this skill owns. Log it in
`wiki/log.md` immediately (Rule B).
## Edge cases
- **Only one signal returned anything** — fusion is a no-op, so don't run
the arithmetic for show. The rerank still applies (it's the check that
the one list actually answers the question rather than merely matching
its wording), and dedupe still applies as soon as Step 6 pulls in a
page's own cited source.
- **A cited source file no longer exists** (moved, renamed, or cleaned
up) — say so plainly rather than silently falling back to the `tldr` as
if it had been verified. Flag it as a likely `ckb-lint` finding (a
broken `Sources` reference) rather than treating it as a dead end.
- **A page's `## Crux` quote is no longer found in the source it cites** —
the fingerprint check will usually catch this first, but where it doesn't
(no fingerprint recorded, or a source edited without the page being
rebuilt), answer from the source and report the divergence. A quote that
has drifted from its source is a stronger lint finding than a stale date,
because it is a page asserting something the evidence no longer says.
- **Connector item unreachable or connector not authorized this
session** — state clearly that the answer is based on the cached
connector index, not a live re-check, and name which connector would
need authorizing to go further.
- **Question is low-stakes and the matched page is high-confidence,
recently updated, and well within its `freshness_window_days`** — still
open the source at least once to ground the answer; skip only a *second*
redundant read if the same source has already been opened earlier in
the same retrieval pass for another part of the same question.
- **Many pages are relevant and reading every cited source in full would
be excessive** — prioritize the sources that actually carry the
specific fact the question needs, not every source any shortlisted page
has ever cited. Say what was skipped rather than silently narrowing
without a note.
- **The "source" is itself a generated artifact** (e.g. an
`outputs/emails/*.md` draft cited as a wiki page's Source) rather than
raw external material — that's still the source relative to the wiki
page; no further hop beyond it is required.
- **A connector-index entity/process page's `resource:` points at a full
`wiki/entities/` page** (per `ckb-index-external`'s thin-page
convention) — treat the wiki page as the real source to verify against;
the connector page is just the pointer that got you there.
- **Nothing in the index is even plausibly relevant** — say the knowledge
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
material) or `ckb-index-external` (for a connector-backed source) if
that seems like the actual gap. For durable gaps, record or propose a
`wiki/query-gaps.md` entry. Don't stretch a weak match into an answer
just to have one.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,53 @@
# ckb-retrieve — edge cases
Reference material for the `ckb-retrieve` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Only one signal returned anything** — fusion is a no-op, so don't run
the arithmetic for show. The rerank still applies (it's the check that
the one list actually answers the question rather than merely matching
its wording), and dedupe still applies as soon as Step 6 pulls in a
page's own cited source.
- **A cited source file no longer exists** (moved, renamed, or cleaned
up) — say so plainly rather than silently falling back to the `tldr` as
if it had been verified. Flag it as a likely `ckb-lint` finding (a
broken `Sources` reference) rather than treating it as a dead end.
- **A page's `## Crux` quote is no longer found in the source it cites** —
the fingerprint check will usually catch this first, but where it doesn't
(no fingerprint recorded, or a source edited without the page being
rebuilt), answer from the source and report the divergence. A quote that
has drifted from its source is a stronger lint finding than a stale date,
because it is a page asserting something the evidence no longer says.
- **Connector item unreachable or connector not authorized this
session** — state clearly that the answer is based on the cached
connector index, not a live re-check, and name which connector would
need authorizing to go further.
- **Question is low-stakes and the matched page is high-confidence,
recently updated, and well within its `freshness_window_days`** — still
open the source at least once to ground the answer; skip only a *second*
redundant read if the same source has already been opened earlier in
the same retrieval pass for another part of the same question.
- **Many pages are relevant and reading every cited source in full would
be excessive** — prioritize the sources that actually carry the
specific fact the question needs, not every source any shortlisted page
has ever cited. Say what was skipped rather than silently narrowing
without a note.
- **The "source" is itself a generated artifact** (e.g. an
`outputs/emails/*.md` draft cited as a wiki page's Source) rather than
raw external material — that's still the source relative to the wiki
page; no further hop beyond it is required.
- **A connector-index entity/process page's `resource:` points at a full
`wiki/entities/` page** (per `ckb-index-external`'s thin-page
convention) — treat the wiki page as the real source to verify against;
the connector page is just the pointer that got you there.
- **Nothing in the index is even plausibly relevant** — say the knowledge
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
material) or `ckb-index-external` (for a connector-backed source) if
that seems like the actual gap. For durable gaps, record or propose a
`wiki/query-gaps.md` entry. Don't stretch a weak match into an answer
just to have one.
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*

View file

@ -0,0 +1,352 @@
#!/usr/bin/env python3
"""Mechanical half of ckb-retrieve: gather ranked candidate lists from several
local signals and fuse them with reciprocal rank fusion.
python3 retrieve_candidates.py "question text" [--root DIR] [--k 10]
[--top 12] [--scope SLUG] [--json]
Signals, each its own ranked list (weight in brackets):
exact rg/grep hits on literal tokens, across wiki/, raw/archive/, raw/inbox/,
outputs/, linked/*/ and connector-backed libs/*/ [1.0, or 2.0
when the question carries literal-looking tokens]
tldr title + tldr token overlap for every frontmatter page [1.0]
scope pages listed by a matching wiki/projects/ scope page [1.0]
graph one-hop neighbours of the text-matched shortlist [0.7]
indegree how many edges point at a shortlisted page [0.5]
trust confidence x quality x freshness, over the shortlist [0.3]
Fused score = sum(weight / (k + rank)) over the lists a candidate appears in.
`k` defaults to 10: a local wiki yields a dozen candidates, not hundreds, and
k=60 flattens them into near-identical scores.
The script ranks; it does not judge. Dedupe-by-claim, rerank against the literal
question, and source verification stay with the skill. It never writes.
"""
import argparse
import json
import os
import re
import shutil
import subprocess
import sys
from collections import Counter, defaultdict
from datetime import date, datetime
from pathlib import Path
STOP = set("""a an and are as at be by for from how in is it of on or that the this to
was we what when where which who why with do does did our your their about into
""".split())
MD_EXCLUDE = {"index.md", "log.md"}
# ---------------------------------------------------------------- parsing ---
def parse_frontmatter(text):
if not text.startswith("---\n"):
return {}, text
end = text.find("\n---", 4)
if end < 0:
return {}, text
fm = {}
for line in text[4:end].splitlines():
m = re.match(r"^([A-Za-z_][\w-]*):\s*(.*)$", line)
if m:
fm[m.group(1)] = m.group(2).strip().strip('"').strip("'")
return fm, text[end + 4:]
def title_of(body, fallback):
m = re.search(r"^#\s+(.+)$", body, re.M)
return m.group(1).strip() if m else fallback
def tokens(s):
return [t for t in re.findall(r"[a-z0-9][a-z0-9_./:-]{1,}", s.lower()) if t not in STOP and len(t) > 1]
def literal_tokens(q):
"""Things that should match exactly: quoted phrases, paths, flags, ids, error-ish strings."""
lits = re.findall(r'"([^"]{3,})"|\'([^\']{3,})\'|`([^`]{2,})`', q)
out = [next(x for x in t if x) for t in lits]
for t in re.findall(r"\S+", q):
if re.search(r"[/\\.\-_]\w|^--?\w|\d{2,}|[A-Z]{2,}-\d+|^[A-Z][A-Z0-9_]{3,}$", t) and len(t) > 2:
out.append(t.strip(",.;:?!()"))
return list(dict.fromkeys(out))
def is_fresh(fm, today):
lu, win = fm.get("last_updated"), fm.get("freshness_window_days")
if not lu or not win:
return None
try:
return (today - datetime.strptime(lu, "%Y-%m-%d").date()).days <= int(win)
except ValueError:
return None
# ---------------------------------------------------------------- corpus ----
def page_roots(root):
yield root / "wiki"
linked = root / "linked"
if linked.is_dir():
for d in sorted(linked.iterdir()):
if d.is_dir():
yield d
libs = root / "libs"
if libs.is_dir():
for d in sorted(libs.iterdir()):
if d.is_dir() and (d / "source.yaml").exists():
yield d # connector index only; a git-copy lib is not indexed here
def load_pages(root):
pages = {}
for base in page_roots(root):
for p in base.rglob("*.md"):
if p.name in MD_EXCLUDE or "/.git/" in p.as_posix():
continue
try:
text = p.read_text(encoding="utf-8", errors="replace")
except OSError:
continue
fm, body = parse_frontmatter(text)
if not fm.get("type") and base.name == "wiki":
continue
rel = p.relative_to(root).as_posix()
pages[rel] = {
"path": rel, "fm": fm, "title": title_of(body, p.stem),
"sources": re.findall(r"^\s*-\s+`([^`]+)`", body.split("## Sources", 1)[1].split("\n## ", 1)[0], re.M)
if "## Sources" in body else [],
}
return pages
def load_edges(root):
edges = []
for f in [root / "wiki/graph/edges.json", *root.glob("libs/*/graph/edges.json")]:
if f.exists():
try:
edges += json.loads(f.read_text(encoding="utf-8")).get("edges", [])
except (OSError, ValueError):
pass
return edges
def norm_ref(ref):
return ref.lstrip("/").removeprefix("wiki/").removesuffix(".md")
# ---------------------------------------------------------------- signals ---
def signal_exact(root, toks, lits):
"""Ranked by (distinct tokens matched, total hits)."""
targets = [d for d in ["wiki", "raw/archive", "raw/inbox", "outputs", "linked"] if (root / d).exists()]
targets += [d.relative_to(root).as_posix() for d in (root / "libs").glob("*") if (d / "source.yaml").exists()]
if not targets:
return [], set()
needles = list(dict.fromkeys(lits + [t for t in toks if len(t) >= 4]))[:12]
per_file = defaultdict(lambda: [set(), 0])
rg = shutil.which("rg")
for n in needles:
if rg:
cmd = [rg, "-c", "-i", "-F", "--follow", "--no-messages", "-g", "!*.json", "-g", "!.git", "--", n, *targets]
else:
cmd = ["grep", "-r", "-c", "-i", "-F", "--exclude=*.json", "--exclude-dir=.git", "--", n, *targets]
try:
out = subprocess.run(cmd, cwd=root, capture_output=True, text=True, timeout=30).stdout
except (OSError, subprocess.TimeoutExpired):
continue
for line in out.splitlines():
path, _, cnt = line.rpartition(":")
if not path or not cnt.isdigit() or int(cnt) == 0:
continue
per_file[path][0].add(n)
per_file[path][1] += int(cnt)
ranked = sorted(per_file.items(), key=lambda kv: (-len(kv[1][0]), -kv[1][1], kv[0]))
inbox = {p for p in per_file if p.startswith("raw/inbox/")}
return [p for p, _ in ranked], inbox
def signal_tldr(pages, toks):
qs = set(toks)
scored = []
for rel, pg in pages.items():
hay = set(tokens(pg["title"] + " " + pg["fm"].get("tldr", "")))
hit = len(qs & hay)
if hit:
scored.append((-(hit / max(len(qs), 1)), -hit, rel))
return [r for _, _, r in sorted(scored)]
def signal_scope(root, pages, toks, forced):
proj = root / "wiki/projects"
if not proj.is_dir():
return [], None
qs = set(toks)
best, best_hit = None, 0
for p in proj.glob("*.md"):
if p.name == "index.md":
continue
if forced and p.stem == forced:
best = p
break
pg = pages.get(p.relative_to(root).as_posix())
hit = len(qs & set(tokens((pg["title"] if pg else "") + " " + (pg["fm"].get("tldr", "") if pg else "") + " " + p.stem)))
if hit > best_hit:
best, best_hit = p, hit
if not best:
return [], None
body = best.read_text(encoding="utf-8", errors="replace")
refs = re.findall(r"\]\(([^)]+\.md)\)|\[\[([^\]]+)\]\]|`((?:wiki|raw|libs|outputs)/[^`]+)`", body)
listed = []
for a, b, c in refs:
r = norm_ref(a or b or c)
cand = next((rel for rel in pages if norm_ref(rel) == r or rel.endswith(r + ".md")), None)
if cand and cand not in listed:
listed.append(cand)
return listed, best.relative_to(root).as_posix()
def signal_graph(edges, pages, shortlist):
short = {norm_ref(s) for s in shortlist}
neigh = Counter()
for e in edges:
a, b = norm_ref(str(e.get("from", ""))), norm_ref(str(e.get("to", "")))
if a in short and b not in short:
neigh[b] += 1
if b in short and a not in short:
neigh[a] += 1
out = []
for n, _ in neigh.most_common():
cand = next((rel for rel in pages if norm_ref(rel) == n or rel.endswith("/" + n + ".md")), None)
if cand:
out.append(cand)
return out
def signal_indegree(edges, shortlist):
indeg = Counter(norm_ref(str(e.get("to", ""))) for e in edges)
scored = [(indeg[norm_ref(s)], s) for s in shortlist if indeg[norm_ref(s)] > 0]
return [s for _, s in sorted(scored, key=lambda x: (-x[0], x[1]))]
def signal_trust(pages, shortlist, today):
scored = []
for s in shortlist:
pg = pages.get(s)
if not pg:
continue
fm = pg["fm"]
try:
c, q = float(fm.get("confidence", 0.5)), float(fm.get("quality", 0.5))
except ValueError:
c, q = 0.5, 0.5
fresh = is_fresh(fm, today)
f = 1.0 if fresh in (True, None) else 0.5
scored.append((-(c * q * f), s))
return [s for _, s in sorted(scored)]
# ---------------------------------------------------------------- fusion ----
def rrf(lists, k):
score, ranks = defaultdict(float), defaultdict(dict)
for name, (items, w) in lists.items():
for i, item in enumerate(items, 1):
score[item] += w / (k + i)
ranks[item][name] = i
return sorted(score.items(), key=lambda kv: (-kv[1], kv[0])), ranks
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("query")
ap.add_argument("--root", default=".")
ap.add_argument("--k", type=int, default=10)
ap.add_argument("--top", type=int, default=12)
ap.add_argument("--scope", help="force a wiki/projects/<slug> scope instead of matching one")
ap.add_argument("--today", help="YYYY-MM-DD, for reproducible freshness")
ap.add_argument("--json", action="store_true")
a = ap.parse_args()
root = Path(a.root).resolve()
today = datetime.strptime(a.today, "%Y-%m-%d").date() if a.today else date.today()
toks, lits = tokens(a.query), literal_tokens(a.query)
pages, edges = load_pages(root), load_edges(root)
exact, inbox_hits = signal_exact(root, toks, lits)
tldr = signal_tldr(pages, toks)
scope, scope_page = signal_scope(root, pages, toks, a.scope)
shortlist = list(dict.fromkeys(tldr[:a.top] + [e for e in exact[:a.top] if e in pages] + scope))
graph = signal_graph(edges, pages, shortlist)
indeg = signal_indegree(edges, shortlist)
trust = signal_trust(pages, shortlist, today)
lists = {
"exact": (exact, 2.0 if lits else 1.0),
"tldr": (tldr, 1.0),
"scope": (scope, 1.0),
"graph": (graph, 0.7),
"indegree": (indeg, 0.5),
"trust": (trust, 0.3),
}
fused, ranks = rrf({n: v for n, v in lists.items() if v[0]}, a.k)
# Fold a cited raw/archive or outputs/ hit into the wiki page that cites it:
# same claim, one candidate, corroboration recorded rather than double-counted.
cited_by = {}
for rel, pg in pages.items():
for src in pg["sources"]:
cited_by.setdefault(src.lstrip("/"), rel)
results, absorbed = [], defaultdict(list)
for item, sc in fused:
owner = cited_by.get(item)
if owner and owner in dict(fused):
absorbed[owner].append(item)
continue
results.append((item, sc))
results = results[:a.top]
out = {
"query": a.query, "k": a.k, "literal_tokens": lits, "scope_page": scope_page,
"inbox_hits": sorted(inbox_hits), "empty_graph": not edges,
"candidates": [],
}
for item, sc in results:
pg = pages.get(item)
fm = pg["fm"] if pg else {}
out["candidates"].append({
"path": item, "score": round(sc, 4), "ranks": ranks[item],
"title": pg["title"] if pg else None, "type": fm.get("type"), "tldr": fm.get("tldr"),
"last_updated": fm.get("last_updated"), "stale": (is_fresh(fm, today) is False) if pg else None,
"confidence": fm.get("confidence"), "quality": fm.get("quality"),
"superseded_by": fm.get("superseded_by"),
"sources": pg["sources"] if pg else [], "corroborated_by": absorbed.get(item, []),
"from_inbox": item.startswith("raw/inbox/"),
})
if a.json:
json.dump(out, sys.stdout, indent=2, ensure_ascii=False)
print()
return
print(f"query: {a.query}")
if lits:
print(f"literal tokens (exact list weighted 2.0): {', '.join(lits)}")
if scope_page:
print(f"scope: {scope_page}")
if out["empty_graph"]:
print("graph: empty — graph/indegree lists skipped")
if inbox_hits:
print(f"raw/inbox/ hits ({len(inbox_hits)}): un-ingested material — an ingest is overdue")
print()
for i, c in enumerate(out["candidates"], 1):
flags = [f for f, on in [("STALE", c["stale"]), ("INBOX", c["from_inbox"]), ("SUPERSEDED", c["superseded_by"])] if on]
rk = " ".join(f"{n}:{r}" for n, r in sorted(c["ranks"].items()))
print(f"{i:2}. {c['score']:.4f} {c['path']} [{rk}]" + (f" {' '.join(flags)}" if flags else ""))
if c["tldr"]:
print(f" {c['tldr']}")
if c["corroborated_by"]:
print(f" corroborated by: {', '.join(c['corroborated_by'])}")
if not out["candidates"]:
print("no candidates — nothing in the cascade matches; consider a wiki/query-gaps.md entry")
if __name__ == "__main__":
main()

View file

@ -1,6 +1,6 @@
---
name: ckb-sync-changes
description: Reconcile this repo's git history with its origin remote — pull down remote commits, commit any local working-tree changes, resolve any conflicts with the user, then push. Use when the user asks to "sync changes", "sync with git", "sync with the remote", "sync with origin", "push and pull my changes", "reconcile git", or "sync the repo". This is a git-level operation, distinct from the content-level "Sync the wiki" / "Ingest" workflow in CLAUDE.md, which processes raw/inbox/ into structured wiki/ pages.
description: Reconcile this repo's git history with its origin remote: pull remote commits, commit local working-tree changes, resolve any conflicts with the user, then push. Pure git mechanics, no wiki synthesis. Use for "sync changes", "sync with origin", "push and pull my changes", or "reconcile git".
---
# Sync changes skill
@ -8,32 +8,15 @@ description: Reconcile this repo's git history with its origin remote — pull d
## Purpose
Keep this repo's local working tree and its `origin` remote in sync in both
directions: pull remote commits down, commit local file changes, resolve any
conflicts with the user, then push. `wiki/`, `outputs/`, `workload/`, and
every other tracked path are treated as opaque files at this layer — this
skill only does git mechanics (stage/commit/fetch/merge/push). It never
invokes the Ingestion Workflow, never re-derives entities/graph/index/log
content, and never tries to semantically reconcile markdown or frontmatter —
a conflicted file is just text with conflict markers until the user says
directions: pull remote commits down, commit local file changes, resolve any conflicts
with the user, then push. Every tracked path is opaque at this layer — this skill does
git mechanics only. It never invokes the ingestion workflow, never re-derives
entity/graph/index/log content, and never semantically reconciles markdown or
frontmatter; a conflicted file is just text with conflict markers until the user says
otherwise.
Unlike the `ckb-export-okf` skill, this skill **does** commit and push on its
own once conflicts (if any) are resolved — that automation was explicitly
requested for this skill.
## Trigger phrases
Use this skill when the user says things like:
- "sync changes"
- "sync with git" / "sync with the remote" / "sync with origin"
- "push and pull my changes"
- "reconcile git"
- "sync the repo"
Do **not** use this skill for bare "Sync" or "Sync the wiki" — those trigger
the content-level ingest workflow routed by `CLAUDE.md`/`AGENTS.md` instead
(processing `raw/inbox/` into `wiki/`), which this skill has nothing to do
with.
Unlike the export skills, this one **does** commit and push on its own once conflicts
(if any) are resolved — that automation was explicitly requested for this skill.
## How to run this skill
@ -232,25 +215,7 @@ blocker.
## Edge cases
- **Nothing to do on either side** — report "already in sync," make no
commits, run no push.
- **Local changes only, remote unchanged** — commit, fast-forward push, no
merge/conflict step needed.
- **Remote changes only, local clean** — fast-forward merge, nothing to
commit, nothing to push; report "pulled N commits, nothing local to
push."
- **Push rejected twice in a row** — stop, report the raw git error, do not
force and do not retry a third time.
- **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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,27 @@
# ckb-sync-changes — edge cases
Reference material for the `ckb-sync-changes` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **Nothing to do on either side** — report "already in sync," make no
commits, run no push.
- **Local changes only, remote unchanged** — commit, fast-forward push, no
merge/conflict step needed.
- **Remote changes only, local clean** — fast-forward merge, nothing to
commit, nothing to push; report "pulled N commits, nothing local to
push."
- **Push rejected twice in a row** — stop, report the raw git error, do not
force and do not retry a third time.
- **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>.*

View file

@ -1,39 +1,25 @@
---
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).
description: Turn the wiki into a personalised teaching curriculum — plan a single session or a spaced series (duration, frequency, optional .ics reminders), teach one portion per session using varied techniques, and track progress across calls, re-teaching weak spots first. Use for "teach me the wiki", "teach me about X", "run a teaching session", or "continue my lessons".
---
# 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:
Turn the wiki into a taught course, not a lookup table or a one-off quiz. Two modes
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.
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) — 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.
---
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.
## How to run this skill
@ -297,31 +283,7 @@ END:VCALENDAR
## 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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,33 @@
# ckb-teach-me — edge cases
Reference material for the `ckb-teach-me` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **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>.*

View file

@ -1,40 +1,27 @@
---
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". Also use when they name a release channel - "upgrade from the test branch", "check experimental for updates", "switch this KB to the stable channel" - since the template repo keeps main (stable), test (release candidate) and experimental (development) branches; the branch this KB tracks is recorded in ckb.yaml's template block and defaults to main. 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.
description: Check the canonical Cascade KB template repo for a newer version and upgrade this KB's template layer (AGENTS.md/CLAUDE.md, .agents/skills/, LICENSE, VERSION, docs, base .gitignore) in place, and — only with explicit confirmation — migrate existing wiki/ content up to the current kb_schema_version. Use for "upgrade the wiki", "check for a newer template version", "pull in the latest skills", or a named release channel (main/test/experimental).
---
# 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:
A Cascade KB drifts from the canonical template as that template gains skills, fixes,
or schema refinements. This skill answers "am I behind, and can I catch up?" without
risking the knowledge collected since. It treats a KB as 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`/
`CHANGELOG.md`/`CHANGELOG.pl.md`, and the base `.gitignore` rules. Compared via the root `VERSION` file. Freely
- **Template layer** — how the KB behaves: `AGENTS.md`/`CLAUDE.md`,
`.agents/skills/*`, `LICENSE`, `VERSION`, `README*`, `docs/`, `tests/`,
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.
- **Content layer** — everything the KB has learned: `wiki/` plus `raw/`, `outputs/`,
`workload/`. Compared via `wiki/index.md`'s `kb_schema_version` (a KB predating that
convention counts as "unversioned" and behind by default). **Never** touched
automatically — a migration only runs after explicit confirmation (Steps 3 and 7),
and even then only ever adds or backfills structure, never rewrites the substance of
what a page says.
## Schema versioning policy
@ -68,15 +55,6 @@ 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 0 — Resolve which repo and branch to compare against
@ -202,9 +180,11 @@ The template layer is exactly these paths — never anything under `wiki/`,
symlink)
- `LICENSE`
- `VERSION`
- `README.md`, `README.pl.md`, `MANUAL.md`, `MANUAL.pl.md`,
`CHANGELOG.md`, `CHANGELOG.pl.md` — whichever exist upstream (an older
local KB may not have some of these yet). Take the changelogs from
- `README.md`, `README.pl.md`, and everything under `docs/` (`MANUAL*`,
`CHANGELOG*`, `OPENSPEC*`, `decisions/`) — whichever exist upstream. A KB
older than template 1.10 keeps these at the repo root; move them into
`docs/` as part of the upgrade and say so.
- `tests/` — the template's fixture KB and smoke test, taken wholesale. Take the changelogs from
upstream wholesale rather than merging: they record the template's
history, which the upstream copy is authoritative about.
- `.agents/skills/<name>/**` for every skill folder present in
@ -230,7 +210,7 @@ clone's copy:
- **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)
especially for `AGENTS.md`, which the [manual](../../../docs/MANUAL.md)
explicitly tells users they're free to edit. Never silently overwrite;
queue it for Step 5.
@ -440,73 +420,7 @@ other than the template project itself.
## Edge cases
- **`ckb.yaml` exists but has no `template:` block** — a KB created before
this convention. Treat it as canonical repo on `main`, and add the block
once an upgrade is actually applied. Don't write it on a check-only run.
- **`ckb.yaml` names a branch that no longer exists upstream** (a dev branch
that was merged and deleted) — report it with the list of branches that do
exist, and ask which to move to. Don't guess: a deleted `experimental` may
mean "its work is in `main` now" or "it was abandoned", and those lead to
different answers.
- **User asks to switch channel but declines every proposed change** — the
switch didn't happen, so don't persist the new branch. They looked at
another channel and chose not to take it; recording it would make the next
run pull from a channel they rejected.
- **Local `VERSION` is ahead of the target branch** — see Step 2. Report it
as "ahead", never as "up to date", and treat any downgrade as an explicit,
separately-confirmed operation.
- **Template repo is this very repo** (the template project upgrading
itself) — the comparison is between branches of one repo rather than
between two repos. That's valid, and the usual flow is `experimental` →
`test` → `main`; but say plainly that this is a self-upgrade, since the
"local vs upstream" framing in the report reads oddly otherwise.
- **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>.*
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.

View file

@ -0,0 +1,75 @@
# ckb-upgrade — edge cases
Reference material for the `ckb-upgrade` skill. Read when a
run hits an unusual situation the main steps don't cover.
- **`ckb.yaml` exists but has no `template:` block** — a KB created before
this convention. Treat it as canonical repo on `main`, and add the block
once an upgrade is actually applied. Don't write it on a check-only run.
- **`ckb.yaml` names a branch that no longer exists upstream** (a dev branch
that was merged and deleted) — report it with the list of branches that do
exist, and ask which to move to. Don't guess: a deleted `experimental` may
mean "its work is in `main` now" or "it was abandoned", and those lead to
different answers.
- **User asks to switch channel but declines every proposed change** — the
switch didn't happen, so don't persist the new branch. They looked at
another channel and chose not to take it; recording it would make the next
run pull from a channel they rejected.
- **Local `VERSION` is ahead of the target branch** — see Step 2. Report it
as "ahead", never as "up to date", and treat any downgrade as an explicit,
separately-confirmed operation.
- **Template repo is this very repo** (the template project upgrading
itself) — the comparison is between branches of one repo rather than
between two repos. That's valid, and the usual flow is `experimental` →
`test` → `main`; but say plainly that this is a self-upgrade, since the
"local vs upstream" framing in the report reads oddly otherwise.
- **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>.*

View file

@ -15,6 +15,10 @@ Maintain this root layout:
```
├── .agents/modules/ # Optional modules, inert until installed
├── ckb.yaml # Repo manifest: template branch, installed modules
├── docs/ # Manual, changelog, OpenSpec guide, template design records
│ └── decisions/ # The template's own ADRs (D-0001…) — not KB content
├── tests/ # Fixture KB + smoke test for the deterministic scripts
├── libs/ # Read-only external sources:
│ └── <name>/ # - git-copy clone/ZIP: immutable, never write here
│ # - connector source: has user-authored source.yaml
@ -102,7 +106,7 @@ source_checked: YYYY-MM-DD # when that digest was last verified
```
### Page Body Sections
Four body sections are reserved across the whole KB. All are optional, but
Three body sections are reserved across the whole KB. All are optional, but
where present they mean exactly this and nothing else:
- **`## Sources`** — where this page came from. One bullet per source, each
@ -159,36 +163,20 @@ file.
| Generate a project overview | `ckb-project-summary` |
| Teach, quiz, or onboard from the wiki | `ckb-teach-me`, `ckb-quiz`, `ckb-onboard-me` |
Short routing rules:
Disambiguation, only where the table alone is ambiguous:
- For questions, use `ckb-retrieve`; it owns project scopes, hybrid local
search, rank fusion across signals, dedupe/rerank, expertise and
ownership lookups, evidence packets, source verification, answer
caveats, and query-gap capture.
- For "Ingest", "Sync the wiki", or "Update the wiki", use `ckb-ingest`.
- For "record a decision", "we decided ...", or a question whose subject is a
decision (what/why/who/when, what superseded it, what is still open), use
`ckb-decide`. For a wider question that merely touches decisions, stay in
`ckb-retrieve`.
- For "Index external sources", "index libs", or "refresh the external
index", use `ckb-index-external`.
- For "Lint" or "health-check the wiki", use `ckb-lint`.
- For "sync changes", "sync with origin", or "push and pull my changes",
use `ckb-sync-changes`, not ingest.
- For "upgrade the wiki" or "check for a newer template version", use
`ckb-upgrade`. The template repo keeps three branches — `main` (stable),
`test` (release candidate), `experimental` (development) — and a request
naming one ("upgrade from `test`", "switch to the stable channel") routes
here too. Which branch this KB tracks lives in `ckb.yaml`'s `template:`
block and defaults to `main`; `ckb-init` names it the same way when
bootstrapping.
- For "install/uninstall the `<name>` module", "what modules are
available", or a request for a capability the base KB lacks (such as
handling source code), use `ckb-module`.
- For "reset the wiki", "empty the wiki", or "make this a clean template",
use `ckb-reset`. It deletes accumulated knowledge, so it always shows an
inventory and takes a typed confirmation first, and never touches the
template layer or `src/`.
- `ckb-ingest` turns raw material into pages; `ckb-sync-changes` only does git
mechanics. "Sync" alone always means git — ingest is triggered by "Ingest"
or "Update the wiki", never by a phrase containing "sync".
- `ckb-decide` owns questions whose *subject* is a decision (what/why/who/when,
what superseded it, what is still open). A wider question that merely touches
decisions stays in `ckb-retrieve`.
- `ckb-upgrade` also takes a request naming a release channel. The template repo
keeps `main` (stable), `test` (release candidate) and `experimental`
(development); which branch this KB tracks lives in `ckb.yaml`'s `template:`
block and defaults to `main`.
- `ckb-reset` deletes accumulated knowledge, so it always shows an inventory and
takes a typed confirmation first, and never touches the template layer or `src/`.
---
@ -205,7 +193,11 @@ source's admin.
### Rule B: Wiki Change Log
Every create, update, move, or delete inside `wiki/` must be logged
immediately in `wiki/log.md` before proceeding.
immediately, before proceeding, in exactly one log: `wiki/decisions/log.md`
for anything under `wiki/decisions/`, `wiki/log.md` for everything else.
When the decisions log absorbs a change, `wiki/log.md` gets a one-line
`POINTER` entry naming it — never a second full entry. `ckb-lint` flags a
change recorded in both.
Use reverse chronological order and this format:

285
README.md
View file

@ -9,17 +9,19 @@ 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 —
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)).
worked examples for every use case - see [docs/MANUAL.md](docs/MANUAL.md)
([Polski](docs/MANUAL.pl.md)).
If this KB documents software you're building, the optional `software` module
adds `src/` repositories and spec-driven development — see
[OPENSPEC.md](OPENSPEC.md) ([Polski](OPENSPEC.pl.md)).
adds `src/` repositories and spec-driven development - see
[docs/OPENSPEC.md](docs/OPENSPEC.md) ([Polski](docs/OPENSPEC.pl.md)).
For the page schema in full, and for how both version numbers got where they
are, see [CHANGELOG.md](CHANGELOG.md) ([Polski](CHANGELOG.pl.md)).
are, see [docs/CHANGELOG.md](docs/CHANGELOG.md) ([Polski](docs/CHANGELOG.pl.md)).
Why the template is shaped the way it is - its own design decisions - is in
[docs/decisions/](docs/decisions/README.md).
### Release channels
@ -27,9 +29,9 @@ The template repo keeps three branches. They are not interchangeable:
| Branch | What it is | Who should track it |
|---|---|---|
| `main` | **Stable** — the released template | Everyone, by default |
| `test` | **Release candidate** — validated before merging to `main` | Anyone helping validate a release, or needing a landed-but-unshipped fix |
| `experimental` | **Development** — active work, may be broken or reverted | People developing the template itself |
| `main` | **Stable** - the released template | Everyone, by default |
| `test` | **Release candidate** - validated before merging to `main` | Anyone helping validate a release, or needing a landed-but-unshipped fix |
| `experimental` | **Development** - active work, may be broken or reverted | People developing the template itself |
Both `ckb-init` and `ckb-upgrade` default to `main`. To use another channel,
just say which: *"initialize from the test branch"*, *"check experimental for
@ -50,6 +52,9 @@ A KB with no `ckb.yaml` (or no `template:` block) is treated as tracking
## Directory Structure
```
├── ckb.yaml # Repo manifest: template branch tracked, installed modules
├── docs/ # Manual, changelog, OpenSpec guide, and decisions/ — the template's own ADRs
├── tests/ # Fixture KB + smoke test for the deterministic scripts (tests/smoke.sh)
├── libs/ # Read-only external sources — git-copy clones (gitignored) OR
│ # connector configs (source.yaml) with a self-contained generated index
├── linked/ # Read-only upstream KBs mounted as symlinks
@ -59,7 +64,7 @@ A KB with no `ckb.yaml` (or no `template:` block) is treated as tracking
├── tmp/ # Temporary files, caches (gitignored)
├── wiki/ # Local structured markdown wiki (agent-managed)
│ ├── index.md # Routing table with "Use when" triggers + kb_schema_version
│ ├── overview.md # High-level map
│ ├── overview.md # What this KB covers — content, not schema
│ ├── log.md # Root rollup change log
│ ├── error-book.md # Compilation errors & derived constraints
│ ├── query-gaps.md # Failed or missing-answer questions for future ingest
@ -75,7 +80,7 @@ A KB with no `ckb.yaml` (or no `template:` block) is treated as tracking
## Cascade Priority
When searching, layers are checked in order — first match wins:
When searching, layers are checked in order - first match wins:
```
wiki/ (highest) ← agent writes here, always wins
@ -85,26 +90,26 @@ libs/A/ (lowest) ← git-managed external KB copies, or a connector's own
```
The agent never writes to `linked/` or a git-copy `libs/<name>/`. To correct
upstream content, write the right version in `wiki/` — it takes precedence
upstream content, write the right version in `wiki/` - it takes precedence
automatically. The one exception is a connector-backed `libs/<name>/` (see
"External Source Connectors & Indexing" below) — the agent owns and
"External Source Connectors & Indexing" below) - the agent owns and
maintains its generated index exactly as it would `wiki/`.
---
## Features
Every feature below is a skill under `.agents/skills/`. A skill loads into
context only when invoked; `AGENTS.md` carries the routing and the
non-negotiable rules, nothing more.
### Inbox-Driven Workflow
Drop any raw material (notes, articles, links) into `raw/inbox/` without
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
organizing. On "Ingest" (or "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.
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
For long conversations, meeting notes, transcripts, or chat exports, ingest
uses a structured distillation rather than treating the whole file as one
@ -115,7 +120,7 @@ that deserve to stay findable on their own.
"High-signal" is an explicit test, not a judgment call, or every excerpt
looks worth keeping and the page becomes a second copy of the transcript.
An excerpt earns its own retrievable section only if it carries a term rare
across the wiki (checked with `rg -c` — a distinguishing search handle, not
across the wiki (checked with `rg -c` - a distinguishing search handle, not
a word already on twenty pages), runs to roughly 200 characters or more, and
is corroborated by something later in the material agreeing with, acting on,
or correcting it. Fail any one and the content still lands in the page, just
@ -126,8 +131,8 @@ unambiguously alone.
### Lazy-Loading Index with "Use When" Triggers
`wiki/index.md` is a routing table. Each entry has a **Use when** column
listing trigger keywords. The agent reads the index first (stays in context),
matches keywords against the task, and only loads matching pages. This
drops context overhead from ~12K to ~3.2K tokens per task.
matches keywords against the task, and only loads matching pages. The
index stays small; the pages it points at don't have to.
### TLDR-First Query Layer
Every page carries a one-sentence `tldr` in frontmatter. When querying, the
@ -149,7 +154,7 @@ question, the agent falls back to the full cascade.
When index/TLDR routing is not enough, the agent can combine several local
signals before answering:
- exact text search with `rg` for error strings, commands, flags, filenames,
hostnames, ticket IDs, and other literal tokens — including across
hostnames, ticket IDs, and other literal tokens - including across
`raw/inbox/`, so material dropped an hour ago and not yet ingested can
still answer a question (and flags that an ingest is overdue)
- semantic/entity matches from page titles, TLDRs, project scopes, and graph
@ -159,20 +164,24 @@ signals before answering:
- context expansion around a matched section, so answers are grounded in the
neighboring headings and paragraphs rather than a lone snippet
Each signal produces its own ranked list, and the lists are then fused
rather than resolved by picking a favourite: every candidate scores
Gathering and fusing those signals is mechanical, so it runs as a script -
`.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py` - the same way
lint's detection does; the agent reads its ranked output and does the
judgment (dedupe by claim, rerank against the literal question, source
verification). Each signal produces its own ranked list, and the lists are
then fused rather than resolved by picking a favourite: every candidate scores
`weight / (k + rank)` summed across the lists it appears in, so a page
ranked third by three signals beats one ranked first by a single signal.
`k` is 10, deliberately smaller than the 60 rank fusion is usually quoted
with — 60 is tuned for retrievers returning hundreds of candidates and
with - 60 is tuned for retrievers returning hundreds of candidates and
flattens all scores into near-identical values against the dozen a local
wiki produces. Literal-token queries up-weight the exact-match list, since
no amount of title similarity should outrank a match on the exact string
someone pasted.
Fused candidates are then deduplicated by claim — a wiki page, the
Fused candidates are then deduplicated by claim - a wiki page, the
`raw/archive/` file it cites, and a connector page pointing back at it are
three hits for one fact, not three sources — and reranked 0–10 on how well
three hits for one fact, not three sources - and reranked 0–10 on how well
each answers the literal question rather than how well it matches the
question's wording. Same agent, deliberate second pass, no separate model.
@ -196,8 +205,7 @@ that on.
"Who knows about X" and "who owns X" are direct graph lookups rather than
full-text guesses. Ingest records `has_expertise_in` edges when someone
demonstrably answers questions or explains decisions on a topic, and
`owns` edges for declared responsibility over a system, area, or decision
— both from demonstrated evidence only, never inferred from meeting
`owns` edges for declared responsibility over a system, area, or decision - both from demonstrated evidence only, never inferred from meeting
attendance or job title. Where no edge exists yet, retrieval falls back to
authorship evidence and says which of the two grounded the answer, since
an inferred expert is a weaker claim than a recorded one.
@ -210,7 +218,7 @@ alternatives that lost, and what it `affects`. A `status` field
actually in force, and an optional `review_on` date marks it for revisiting.
Decision pages are **append-only**. When the choice changes, a *new* decision
supersedes the old one — `supersedes`/`superseded_by` are set on both sides,
supersedes the old one - `supersedes`/`superseded_by` are set on both sides,
the old page's status becomes `superseded` or `reversed`, and its original
context and rationale stay untouched. That is what makes "why is it like
this?" answerable years later, and what turns "we use Postgres" into "we use
@ -248,14 +256,14 @@ source_checked: YYYY-MM-DD # when that digest was last verified
---
```
- **type** — required; unregistered string, new values always valid, readers tolerate unrecognized ones
- **resource** — optional pointer to the live/authoritative source, kept separate from the wiki's own commentary
- **confidence** — set on write, decays with time, reinforced by new sources
- **quality** — self-scored on write, pages below 0.7 flagged for review
- **supersedes / superseded_by** — when new info replaces old, link them
- **freshness_window_days** — pages older than this get flagged during lint
- **retention** — low pages are archived after 2× freshness window
- **source_fingerprint / source_checked** — a digest of the material the page
- **type** - required; unregistered string, new values always valid, readers tolerate unrecognized ones
- **resource** - optional pointer to the live/authoritative source, kept separate from the wiki's own commentary
- **confidence** - set on write, decays with time, reinforced by new sources
- **quality** - self-scored on write, pages below 0.7 flagged for review
- **supersedes / superseded_by** - when new info replaces old, link them
- **freshness_window_days** - pages older than this get flagged during lint
- **retention** - low pages are archived after 2× freshness window
- **source_fingerprint / source_checked** - a digest of the material the page
was synthesized from, plus when it was last confirmed. A freshness window is
a guess that a source *might* have moved; a fingerprint is a fact about
whether it *did*, and lint checks it mechanically.
@ -266,17 +274,17 @@ Four `##` headings mean something specific everywhere in the KB:
| Section | What it holds |
|---|---|
| `## Sources` | one bullet per source, each with a fingerprint |
| `## Crux` | verbatim quotes from those sources — evidence, never paraphrase |
| `## Crux` | verbatim quotes from those sources - evidence, never paraphrase |
| `## Notes` | human-authored and **protected**: no skill rewrites it, ever |
`## Crux` is what lets a question be answered from the page instead of from
the archive: a summary can drift silently, a quote either still matches its
source or it doesn't. `## Notes` is the inverse guarantee — on pages the agent
source or it doesn't. `## Notes` is the inverse guarantee - on pages the agent
regenerates (connector indexes, code maps), it is the one place an annotation
survives the next rebuild.
`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.5"`), declaring
which revision of this schema the wiki was authored against — bump minor for
which revision of this schema the wiki was authored against - bump minor for
additive optional fields, major for breaking changes.
### Entity Extraction & Knowledge Graph
@ -284,7 +292,7 @@ During ingest, the agent extracts typed entities (people, projects, libraries,
concepts, systems) and stores them as pages in `wiki/entities/`. Typed
relationships are recorded in `wiki/graph/edges.json`, using a closed
vocabulary where each verb is defined by the question it answers (see
`wiki/graph/index.md`) — structural ones (`part_of`, `uses`, `depends_on`,
`wiki/graph/index.md`) - structural ones (`part_of`, `uses`, `depends_on`,
`produces`, `configures`, `validates`, `implements`, `caused`, `contradicts`,
`supersedes`) plus people-to-topic ones (`has_expertise_in`, `owns`). Queries can walk the
graph to discover connected pages (e.g. "what depends on Redis?") or to
@ -292,17 +300,20 @@ answer "who knows about X" directly.
### Recursive Index & Log Convention
Any `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`,
future topic folders) keeps its own `index.md` — a plain link list, no
frontmatter — so subdirectory navigation stays lazy instead of requiring a
future topic folders) keeps its own `index.md` - a plain link list, no
frontmatter - so subdirectory navigation stays lazy instead of requiring a
full scan. A subdirectory can also keep its own `log.md` once it has enough
independent history; `wiki/log.md` stays the root-level rollup and never
duplicates a change a subdirectory log already recorded.
duplicates a change a subdirectory log already recorded - it carries a
one-line `POINTER` entry instead. `wiki/decisions/log.md` is the one
subdirectory log the base scaffold ships with, and Rule B in `AGENTS.md`
names it as the exception.
### External Source Connectors & Indexing (on demand)
A `libs/<name>/` folder supports a second population mode alongside the
existing git-copy one: a small user-authored `libs/<name>/source.yaml`
declaring a *live* external source — a SharePoint folder, a Google Drive
folder, a plain URL, or another connector — that you don't want to fully
declaring a *live* external source - a SharePoint folder, a Google Drive
folder, a plain URL, or another connector - that you don't want to fully
mirror locally:
```yaml
connector: sharepoint
@ -310,9 +321,8 @@ location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports
description: "Finance team's shared reports folder"
refresh_interval_days: 7 # optional, defaults to 30
```
`refresh_interval_days` tunes cadence per source — a folder that churns
daily deserves a shorter window than a quarterly archive that barely moves
— and sets the `freshness_window_days` stamped on that source's generated
`refresh_interval_days` tunes cadence per source - a folder that churns
daily deserves a shorter window than a quarterly archive that barely moves - and sets the `freshness_window_days` stamped on that source's generated
pages. Both "index external sources" and "Lint" report a source that's
overdue against it, and say by how much, so a read-only user knows which
admin to chase rather than quietly trusting a copy three weeks past due.
@ -320,19 +330,19 @@ admin to chase rather than quietly trusting a copy three weeks past due.
Say "index external sources" and the agent walks it, resolving `connector`
to whatever live tool is available that session (a connected Microsoft
365/Google Drive MCP tool, or `WebFetch` for a plain URL), and builds a
self-contained generated index inside that same `libs/<name>/` —
self-contained generated index inside that same `libs/<name>/` -
`index.md`/`entities/`/`graph/`/`log.md`, mirroring `wiki/`'s own shape via
the Recursive Index & Log Convention above, but scoped entirely to that one
connector. This is a deliberate design choice: the index is **not** blended
into the main `wiki/entities/`/`wiki/graph/edges.json` — it stays separated
connector. The index is **not** blended
into the main `wiki/entities/`/`wiki/graph/edges.json` - it stays separated
at the `libs/` cascade layer, the same way a git-cloned KB's own files
already are. `source.yaml` itself stays user-only, never written by the
agent.
Two refinements on top of that:
- **Shared, pre-built indexes.** `source.yaml` can add an optional `index:`
block declaring *where the already-built index lives* — a git repo, or a
- Shared, pre-built indexes. `source.yaml` can add an optional `index:`
block declaring *where the already-built index lives* - a git repo, or a
shared resource such as a network path or another connector-reachable
location:
```yaml
@ -341,22 +351,21 @@ Two refinements on top of that:
location: "https://github.com/org/finance-index-cache.git"
ref: main # optional — branch, tag, or subpath hint within that store
```
Every run checks that location: if it already has an index, fetch it —
Every run checks that location: if it already has an index, fetch it -
most people just read what's already there instead of building it
themselves. If it doesn't yet, that's the normal first-time state, not an
error: a write-access user's very next run is what creates and publishes
it there, with no separate "initialize" step.
- **Read vs. write, per user, per source.** Whether *this* user can
- Read vs. write, per user, per source. Whether *this* user can
actually rebuild an index (versus only read a fetched/published one) is a
separate, local, gitignored `libs/<name>/source.local.yaml` — read-only
separate, local, gitignored `libs/<name>/source.local.yaml` - read-only
by default. Setting `access: write` there opts a given machine/user in as
that source's admin, so a team can designate one or two people to
maintain a source while everyone else just reads the result — no
maintain a source while everyone else just reads the result - no
redundant rebuilding, no need for every user to have their own connector
authorization.
Implemented as a Claude Code Skill — see
`.agents/skills/ckb-index-external/SKILL.md`.
Skill: `.agents/skills/ckb-index-external/SKILL.md`.
### Dual-Linking (Wikilinks + Markdown)
Every cross-reference uses both `[[Wikilinks]]` (Obsidian-compatible) and
@ -368,25 +377,22 @@ so links survive later file moves.
### Self-Healing Lint
Periodically (or on demand), the agent health-checks the wiki:
- **Conformance** — flags any page missing parseable frontmatter or a `type` field
- **Freshness** — flags pages past their `freshness_window_days`
- **Confidence decay** — reduces confidence on unreinforced pages
- **Retention sweep** — archives `retention: low` pages past 2× window
- **Supersession detection** — finds contradictions, links old→new
- **Orphan detection** — finds pages with no inbound links
- **Graph consistency** — verifies all edges point to existing entities
- **Index/log consistency** — verifies every subdirectory has an index.md and no change is double-logged
- **Source fingerprints** — recomputes each cited source's digest and flags pages whose evidence has actually changed, not merely aged
- **Crux verbatimness** — flags a quoted excerpt that no longer appears in the source it cites
- **Connector cadence** — flags a connector-backed source whose generated index is overdue against its `refresh_interval_days`, and by how much
- **Error Book** — records systemic issues with root cause and fix
- **Conformance** - flags any page missing parseable frontmatter or a `type` field
- **Freshness** - flags pages past their `freshness_window_days`
- **Confidence decay** - reduces confidence on unreinforced pages
- **Retention sweep** - archives `retention: low` pages past 2× window
- **Supersession detection** - finds contradictions, links old→new
- **Orphan detection** - finds pages with no inbound links
- **Graph consistency** - verifies all edges point to existing entities
- **Index/log consistency** - verifies every subdirectory has an index.md and no change is double-logged
- **Source fingerprints** - recomputes each cited source's digest and flags pages whose evidence has actually changed, not merely aged
- **Crux verbatimness** - flags a quoted excerpt that no longer appears in the source it cites
- **Connector cadence** - flags a connector-backed source whose generated index is overdue against its `refresh_interval_days`, and by how much
- **Error Book** - records systemic issues with root cause and fix
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.
`origin` once you're happy with it. Skill: `.agents/skills/ckb-lint/SKILL.md`.
### Conflict Resolution (Supersession)
When new information contradicts an existing page, the agent adds
@ -402,20 +408,25 @@ source citations, and consistency with the rest of the wiki. Pages below
Systematic errors (orphan links, formatting issues, cross-page contradictions)
are recorded in `wiki/error-book.md` with root cause, applied fix, and a
reusable constraint to prevent recurrence. Two-layer repair:
- **Layer 1** — deterministic auto-fix for structural issues
- **Layer 2** — agent reasoning pass for semantic/cross-page issues
- **Layer 1** - deterministic auto-fix for structural issues
- **Layer 2** - agent reasoning pass for semantic/cross-page issues
### Automation Hooks
- **New source** → auto-ingest on next "Ingest" command
- **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
### Session Conventions
These are rules the agent follows from `AGENTS.md`, not hooks wired into the
harness - nothing in `.claude/` runs on its own. If you want any of them
enforced mechanically, that is a Claude Code hook or a scheduled agent you
add yourself.
- **Session start** → read `wiki/index.md` and the latest workload summary;
run `git status` and `lint_report.py --quick`; suggest `ckb-sync-changes`
or `ckb-lint` only when either reports something
- **Session end** → append to `workload/`; repeat the unsynchronized-change
check
- **Every turn that touches the KB** → a note in `workload/` (Rule D)
- **Unanswerable question** → a `wiki/query-gaps.md` entry, the one write
`ckb-retrieve` owns; answers are never filed back as pages automatically
- **Lint on demand** → "Lint" runs the full check; there is no built-in
schedule
### Demand-Driven Context (DDC)
The wiki grows based on actual agent failures rather than upfront curation:
@ -424,8 +435,6 @@ The wiki grows based on actual agent failures rather than upfront curation:
3. User approves or provides source material
4. Next ingest incorporates it
Converges to a stable KB after ~20–30 cycles.
### Session Summaries
After every conversational action, the agent appends to
`workload/YYYY-MM-DD_summary.md`. This provides continuity between sessions
@ -433,37 +442,36 @@ and a browsable history of how the KB evolved. The agent reads the latest
summary on session start to pick up where it left off.
### Change Log
Every wiki modification is immediately logged in `wiki/log.md` in reverse
chronological order (most recent first), recording what changed, why, and
the source.
Every wiki modification is immediately logged in exactly one log, in reverse
chronological order: `wiki/decisions/log.md` for anything under
`wiki/decisions/`, `wiki/log.md` for everything else, with a one-line
`POINTER` in the root log when the decisions log absorbs a change. Lint
flags a change recorded in both.
### OKF Export (on demand)
The wiki can be exported as an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
v0.1-conformant bundle at `outputs/okf/`, consumable by any generic OKF tool
(e.g. Google's reference graph visualizer) without disturbing the richer
internal schema (`confidence`/`quality`/`retention`/`supersedes`/dual-linking)
that OKF doesn't natively understand. Implemented as a Claude Code Skill —
see `.agents/skills/ckb-export-okf/SKILL.md` — rather than baked into
`CLAUDE.md`/`AGENTS.md`, so the mapping ruleset only loads into context when
actually invoked. A deterministic Python script
(`scripts/export_okf.py`) does the whole transform — frontmatter remapping,
that OKF doesn't natively understand. A deterministic Python script
(`scripts/export_okf.py`) does the whole transform - frontmatter remapping,
link rewriting, index and log regeneration, and an OKF conformance pass over
its own output — so the export is reproducible rather than re-reasoned page
its own output - so the export is reproducible rather than re-reasoned page
by page; the agent runs it and relays the report. `outputs/okf/` is
gitignored — it's a fully-regenerated build artifact, so each machine/tool
regenerates it on demand rather than carrying it in git history.
gitignored - it's a fully-regenerated build artifact, so each machine/tool
regenerates it on demand rather than carrying it in git history. Skill:
`.agents/skills/ckb-export-okf/SKILL.md`.
### Starlight Export (on demand)
The wiki can also be exported into an Astro + Starlight-consumable form at
`outputs/starlight/`, producing a human-readable documentation website —
`outputs/starlight/`, producing a human-readable documentation website -
unlike the OKF export, which targets machine/tool consumption. A
deterministic Python script (`scripts/export_starlight.py`) handles
frontmatter remapping, dual-link collapsing, wikilink resolution, asset
copying, and sidebar generation; the agent's job is just to ask the two
setup questions (export scope: full runnable scaffold vs. content-only;
whether to include the log/error-book meta pages) and relay the script's
report. Also on-demand and skill-only — see
`.agents/skills/ckb-export-starlight/SKILL.md`. Like `outputs/okf/`,
report. Skill: `.agents/skills/ckb-export-starlight/SKILL.md`. Like `outputs/okf/`,
`outputs/starlight/` is gitignored as a regenerated build artifact.
### Decision Log (on demand)
@ -486,7 +494,7 @@ itself, then what builds on it). Never writes to `wiki/`. See
### Project Summary (on demand)
Ask for "a project summary" (or "where do things stand", "catch me up on the
project") to regenerate `PROJECT-OVERVIEW.md` at the repo root — a
project") to regenerate `PROJECT-OVERVIEW.md` at the repo root - a
one-to-two-page snapshot (overview, project state, actions & status, risks,
assumptions) synthesized entirely from the current `wiki/` contents and its
knowledge graph. Always overwritten in full on re-run, never hand-appended
@ -496,18 +504,17 @@ to. See `.agents/skills/ckb-project-summary/SKILL.md`.
This repo's own git history can be reconciled with its `origin` remote on
demand: local changes get committed, remote changes get pulled and merged,
any conflicts are presented to the user file-by-file to resolve, then the
result is pushed automatically. Say "sync changes" to trigger it. Also
implemented as a Claude Code Skill — see
`.claude/skills/ckb-sync-changes/SKILL.md` — and deliberately distinct from the
content-level "Sync the wiki" / "Ingest" workflow, which processes
`raw/inbox/` into structured `wiki/` pages and has nothing to do with git.
result is pushed automatically. Say "sync changes" to trigger it. It has
nothing to do with "Ingest", which turns `raw/inbox/` into `wiki/` pages and
never touches git. "Sync" on its own always means git. Skill:
`.agents/skills/ckb-sync-changes/SKILL.md`.
### 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
score, and closes with a verdict. Stateless - nothing is saved between
runs. See `.agents/skills/ckb-quiz/SKILL.md`.
### Guided Teaching Curriculum (on demand)
@ -516,8 +523,8 @@ 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
`.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,
@ -540,13 +547,13 @@ advancing. Never writes to `wiki/`. See
2. **Drop raw material** into `raw/inbox/` (notes, links, articles).
3. **Tell an agent to "Ingest"** — it processes the inbox, consults the
3. **Tell an agent to "Ingest"** - it processes the inbox, consults the
cascade, extracts entities, and writes structured markdown into `wiki/`.
4. **Ask questions** — the agent uses the index for routing, TLDRs for
4. **Ask questions** - the agent uses the index for routing, TLDRs for
quick answers, and the graph for relationship discovery.
5. **Periodically ask to "Lint"** — the agent health-checks everything,
5. **Periodically ask to "Lint"** - the agent health-checks everything,
auto-fixes what it can, and reports issues.
---
@ -560,7 +567,7 @@ advancing. Never writes to `wiki/`. See
Skills live in one shared location, `.agents/skills/`, so any agent tooling
that reads that convention picks them up. `.claude/skills` is a symlink to
`.agents/skills` — Claude Code sees the same skill set without a second
`.agents/skills` - Claude Code sees the same skill set without a second
copy to keep in sync.
---
@ -569,30 +576,26 @@ copy to keep in sync.
- Upstream KBs (`linked/` and git-copy `libs/`) are **never modified** by
agents. A connector-backed `libs/<name>/` (one with a `source.yaml`) is
the one exception — the agent owns and maintains its generated index,
the one exception - the agent owns and maintains its generated index,
but only for a user who's opted themselves into `access: write` locally
(see the next point); everyone else's copy stays read-only.
- To correct upstream content, write the correct version in `wiki/` — it wins.
- To correct upstream content, write the correct version in `wiki/` - it wins.
- Use `raw/inbox/` for anything unprocessed; the agent clears it on ingest.
- The `wiki/index.md` routing table is the most important file — keep it current.
- The `wiki/index.md` routing table is the most important file - keep it current.
- Confidence, quality, and freshness let you trust the right content and
flag the rest for review.
- The `tmp/` directory is gitignored, and so is most of `libs/` — but not
all of it: a git-copy `libs/<name>/`'s cloned content stays gitignored as
before, while a connector-backed `libs/<name>/`'s `source.yaml` and its
generated `index.md`/`entities/`/`graph/`/`log.md` are tracked, since
they're synthesized knowledge worth sharing via "sync changes," not a
disposable build artifact. `libs/<name>/source.local.yaml` (per-user
read/write setting) is the one exception that stays gitignored right
alongside them — it's personal machine state, never meant to sync.
`outputs/` itself is
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. `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.
- `tmp/` is gitignored. So is most of `libs/`, with one split: a git-copy
`libs/<name>/` stays gitignored, while a connector-backed one has its
`source.yaml` and generated `index.md`/`entities/`/`graph/`/`log.md`
tracked. That index is synthesized knowledge worth sharing via "sync
changes", not a build artifact. `libs/<name>/source.local.yaml` is the
exception inside the exception: personal machine state, never synced.
- `outputs/` is tracked, but `outputs/okf/` and `outputs/starlight/` are
not. Each is reproducible from `wiki/` on demand, so there is nothing to
reconcile by carrying it in history. Commit hand-maintained artifacts
under `outputs/` as normal.
- `outputs/teaching/` is gitignored too. Learning plans and session progress
are personal, not shared KB content.
---

View file

@ -13,14 +13,16 @@ 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)).
znajdziesz w [docs/MANUAL.pl.md](docs/MANUAL.pl.md) ([English](docs/MANUAL.md)).
Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny moduł
`software` dodaje repozytoria w `src/` i pracę sterowaną specyfikacją — zobacz
[OPENSPEC.pl.md](OPENSPEC.pl.md) ([English](OPENSPEC.md)).
[docs/OPENSPEC.pl.md](docs/OPENSPEC.pl.md) ([English](docs/OPENSPEC.md)).
Pełny schemat strony oraz historię obu numerów wersji znajdziesz w
[CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)).
[docs/CHANGELOG.pl.md](docs/CHANGELOG.pl.md) ([English](docs/CHANGELOG.md)).
Dlaczego szablon wygląda tak, a nie inaczej — jego własne decyzje projektowe —
opisuje [docs/decisions/](docs/decisions/README.md).
### Kanały wydawnicze
@ -51,6 +53,9 @@ KB bez `ckb.yaml` (albo bez bloku `template:`) jest traktowana jako śledząca
## Struktura katalogów
```
├── ckb.yaml # Manifest repozytorium: śledzona gałąź szablonu, zainstalowane moduły
├── docs/ # Podręcznik, changelog, przewodnik OpenSpec i decisions/ — własne ADR-y szablonu
├── tests/ # Baza-fixture + test dymny deterministycznych skryptów (tests/smoke.sh)
├── libs/ # Zewnętrzne źródła tylko do odczytu — kopie git (w .gitignore) LUB
│ # konfiguracje konektora (source.yaml) z własnym generowanym indeksem
├── linked/ # Zewnętrzne bazy wiedzy tylko do odczytu, montowane jako dowiązania symboliczne
@ -60,7 +65,7 @@ KB bez `ckb.yaml` (albo bez bloku `template:`) jest traktowana jako śledząca
├── 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
│ ├── overview.md # Czego dotyczy ta KB — treść, nie schemat
│ ├── log.md # Główny dziennik zmian (rollup)
│ ├── error-book.md # Błędy kompilacji i wyprowadzone ograniczenia
│ ├── decisions/ # Numerowane, tylko-dopisywane zapisy decyzji + własny index.md i log.md
@ -94,18 +99,18 @@ poniżej) — agent zarządza jego generowanym indeksem tak samo, jak `wiki/`.
## Funkcje
Każda funkcja poniżej to skill w `.agents/skills/`. Skill ładuje się do
kontekstu dopiero po wywołaniu; `AGENTS.md` zawiera tylko routing i reguły
nienegocjowalne, nic więcej.
### 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
porządkowania. Po komendzie „Ingest" (lub „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.
zmiany do `origin`, gdy będziesz z nich zadowolony. Skill:
`.agents/skills/ckb-ingest/SKILL.md`.
Dla długich rozmów, notatek ze spotkań, transkryptów lub eksportów czatu
ingest używa strukturalnej destylacji, zamiast traktować cały plik jako jedną
@ -130,7 +135,7 @@ czytać samodzielnie.
`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.
strony. Indeks pozostaje mały; strony, na które wskazuje, nie muszą.
### Warstwa zapytań oparta na TLDR
Każda strona zawiera jednozdaniowe podsumowanie `tldr` we frontmatterze.
@ -165,8 +170,12 @@ lokalnych sygnałów przed odpowiedzią:
- rozszerzenie kontekstu wokół dopasowanej sekcji, aby odpowiedzi były
osadzone w sąsiadujących nagłówkach i akapitach, a nie w samotnym urywku
Każdy sygnał tworzy własną listę rankingową, a listy są następnie łączone,
zamiast rozstrzygania przez wybór ulubionego sygnału: każdy kandydat zbiera
Zebranie i połączenie tych sygnałów jest mechaniczne, więc wykonuje je
skrypt — `.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py` — tak
samo jak detekcję w lincie; agent czyta jego ranking i wykonuje osąd
(deduplikacja według twierdzenia, przerankowanie względem dosłownego pytania,
weryfikacja źródła). Każdy sygnał tworzy własną listę rankingową, a listy są
następnie łączone, zamiast rozstrzygania przez wybór ulubionego sygnału: każdy kandydat zbiera
`weight / (k + rank)` zsumowane po listach, na których występuje, więc strona
na trzecim miejscu w trzech listach wygrywa ze stroną pierwszą w jednej.
`k` wynosi 10, celowo mniej niż zwykle cytowane 60 — 60 jest dostrojone do
@ -317,7 +326,10 @@ 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.
zmiany już zapisanej w dzienniku podkatalogu — zamiast tego dostaje
jednolinijkowy wpis `POINTER`. `wiki/decisions/log.md` to jedyny dziennik
podkatalogu w bazowym szkielecie, a Reguła B w `AGENTS.md` wymienia go jako
wyjątek.
### Konektory zewnętrznych źródeł i indeksowanie (na żądanie)
Folder `libs/<name>/` obsługuje drugi sposób zasilania, obok istniejącej
@ -345,14 +357,14 @@ dla zwykłego adresu URL), i zbuduje samodzielny, generowany indeks wewnątrz
tego samego `libs/<name>/` — `index.md`/`entities/`/`graph/`/`log.md`,
odzwierciedlający strukturę `wiki/` opisaną w Rekurencyjnej konwencji
indeksu i dziennika powyżej, ale ograniczony wyłącznie do tego jednego
konektora. To celowa decyzja projektowa: ten indeks **nie** jest wmieszany
konektora. Ten indeks **nie** jest wmieszany
w główne `wiki/entities/`/`wiki/graph/edges.json` — pozostaje oddzielony na
warstwie kaskady `libs/`, tak samo jak pliki sklonowanej przez git KB. Sam
`source.yaml` pozostaje wyłącznie twój, agent nigdy go nie zapisuje.
Dwa rozszerzenia na tym fundamencie:
- **Współdzielone, wcześniej zbudowane indeksy.** `source.yaml` może
- Współdzielone, wcześniej zbudowane indeksy. `source.yaml` może
dodać opcjonalny blok `index:`, który deklaruje, *gdzie już zbudowany
indeks się znajduje* — repozytorium git albo zasób współdzielony, np.
ścieżka sieciowa lub inna lokalizacja dostępna przez konektor:
@ -368,7 +380,7 @@ Dwa rozszerzenia na tym fundamencie:
normalny stan przy pierwszym uruchomieniu, a nie błąd: kolejne
uruchomienie użytkownika z dostępem do zapisu jest tym, które go tam
tworzy i publikuje — bez osobnego kroku „inicjalizacji".
- **Odczyt vs. zapis, per użytkownik, per źródło.** Czy *ten* użytkownik
- Odczyt vs. zapis, per użytkownik, per źródło. Czy *ten* użytkownik
może faktycznie przebudować indeks (a nie tylko czytać pobraną/
opublikowaną wersję) to odrębne, lokalne, ignorowane przez git
`libs/<name>/source.local.yaml` — domyślnie tylko do odczytu. Ustawienie
@ -378,8 +390,7 @@ Dwa rozszerzenia na tym fundamencie:
bez zbędnego, wielokrotnego przebudowywania i bez potrzeby, żeby każdy
użytkownik miał własną autoryzację konektora.
Zaimplementowane jako Claude Code Skill — zobacz
`.agents/skills/ckb-index-external/SKILL.md`.
Skill: `.agents/skills/ckb-index-external/SKILL.md`.
### Podwójne linkowanie (Wikilinks + Markdown)
Każde odwołanie krzyżowe używa zarówno `[[Wikilinks]]` (kompatybilnych z
@ -418,10 +429,7 @@ Okresowo (lub na żądanie) agent sprawdza kondycję wiki:
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.
z nich zadowolony. Skill: `.agents/skills/ckb-lint/SKILL.md`.
### Rozwiązywanie konfliktów (Supersesja)
Gdy nowa informacja przeczy istniejącej stronie, agent dodaje linki
@ -444,20 +452,23 @@ zapobiegającym powtórce. Naprawa dwuwarstwowa:
- **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
### Konwencje sesji
To reguły, których agent przestrzega na podstawie `AGENTS.md`, a nie haki
wpięte w narzędzie — nic w `.claude/` nie uruchamia się samo. Jeśli chcesz,
by któraś była wymuszana mechanicznie, dodajesz ją sam jako hook Claude Code
albo zaplanowanego agenta.
- **Start sesji** → odczyt `wiki/index.md` i ostatniego podsumowania
workload; `git status` i `lint_report.py --quick`; sugestia
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi
- **Koniec sesji** → dopisanie do `workload/`; powtórzenie sprawdzenia
niezsynchronizowanych zmian
- **Każda tura dotykająca KB** → notatka w `workload/` (Reguła D)
- **Pytanie bez odpowiedzi** → wpis w `wiki/query-gaps.md`, jedyny zapis,
który należy do `ckb-retrieve`; odpowiedzi nigdy nie są automatycznie
zapisywane jako strony
- **Lint na żądanie** → „Lint" uruchamia pełną kontrolę; nie ma wbudowanego
harmonogramu
### Kontekst napędzany zapotrzebowaniem (Demand-Driven Context, DDC)
Wiki rośnie na podstawie rzeczywistych niepowodzeń agenta, a nie z góry
@ -467,8 +478,6 @@ narzuconej kuracji:
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
@ -477,9 +486,11 @@ 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.
Każda modyfikacja wiki jest natychmiast logowana w dokładnie jednym
dzienniku, w kolejności odwrotnie chronologicznej: `wiki/decisions/log.md`
dla wszystkiego pod `wiki/decisions/`, `wiki/log.md` dla reszty, z
jednolinijkowym `POINTER` w dzienniku głównym, gdy zmianę wchłania dziennik
decyzji. Lint zgłasza zmianę zapisaną w obu.
### Eksport OKF (na żądanie)
Wiki może zostać wyeksportowana jako zgodny z
@ -488,17 +499,15 @@ 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. Cały transform —
którego OKF natywnie nie rozumie. Cały transform —
przemapowanie frontmatteru, przepisanie linków, regeneracja indeksów i
dzienników oraz sprawdzenie zgodności z OKF na własnym wyjściu — wykonuje
deterministyczny skrypt Python (`scripts/export_okf.py`), więc eksport jest
odtwarzalny zamiast wyprowadzany na nowo strona po stronie; agent uruchamia
skrypt i przekazuje raport. `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.
na żądanie zamiast przenosić go w historii gita. Skill:
`.agents/skills/ckb-export-okf/SKILL.md`.
### Eksport Starlight (na żądanie)
Wiki może też zostać wyeksportowana do formy skonsumowalnej przez Astro +
@ -510,8 +519,8 @@ 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
przekazanie raportu skryptu. Skill: `.agents/skills/ckb-export-starlight/SKILL.md`.
Podobnie jak
`outputs/okf/`, `outputs/starlight/` jest w `.gitignore` jako regenerowalny
artefakt budowania.
@ -549,11 +558,9 @@ 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.
Nie ma to nic wspólnego z „Ingest", który zamienia `raw/inbox/` na strony
`wiki/` i nie dotyka gita. Samo „sync" zawsze oznacza gita. Skill:
`.agents/skills/ckb-sync-changes/SKILL.md`.
### Tryb quizu (na żądanie)
Poproś o odpytanie z wiki („quiz me on X", „sprawdź moją wiedzę"), aby
@ -638,22 +645,19 @@ synchronizacji.
bieżąco.
- Confidence, quality i freshness pozwalają ufać właściwej treści i
oflagowywać resztę do przeglądu.
- Katalog `tmp/` jest w `.gitignore`, podobnie jak większość `libs/` — ale
nie cały: zawartość kopii git w `libs/<name>/` pozostaje w `.gitignore`
jak dawniej, natomiast `source.yaml` konektora i jego generowany
`index.md`/`entities/`/`graph/`/`log.md` są śledzone, ponieważ to
zsyntetyzowana wiedza warta udostępnienia przez „sync changes", a nie
jednorazowy artefakt budowania. `libs/<name>/source.local.yaml`
(osobiste ustawienie odczytu/zapisu) to jedyny wyjątek, który zostaje w
`.gitignore` razem z nimi — to osobisty stan komputera, nigdy
przeznaczony do synchronizacji. 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.
- `tmp/` jest w `.gitignore`. Podobnie większość `libs/`, z jednym
podziałem: kopia git w `libs/<name>/` pozostaje ignorowana, natomiast
konektorowy `libs/<name>/` ma śledzone `source.yaml` oraz generowane
`index.md`/`entities/`/`graph/`/`log.md`. Ten indeks to zsyntetyzowana
wiedza warta udostępnienia przez „sync changes", a nie artefakt budowania.
`libs/<name>/source.local.yaml` to wyjątek w wyjątku: osobisty stan
maszyny, nigdy nie synchronizowany.
- `outputs/` jest śledzony, ale `outputs/okf/` i `outputs/starlight/` nie.
Każdy z nich da się odtworzyć z `wiki/` na żądanie, więc nie ma czego
uzgadniać w historii gita. Ręcznie utrzymywane artefakty w `outputs/`
commituj normalnie.
- `outputs/teaching/` też jest ignorowany. Plany nauki i postęp sesji są
osobiste, nie są współdzieloną treścią KB.
---

View file

@ -1 +1 @@
1.9.0
1.10.0

8
ckb.yaml Normal file
View file

@ -0,0 +1,8 @@
# Cascade KB manifest — repo-level configuration, not the wiki's content contract
# (kb_schema_version stays in wiki/index.md). Written by ckb-init, read by
# ckb-upgrade (template:) and ckb-module (kb_modules:).
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main # main | test | experimental
kb_modules: []

View file

@ -10,12 +10,12 @@ thing:
| Number | Lives in | Describes | Who bumps it |
|---|---|---|---|
| `kb_schema_version` | frontmatter of `wiki/index.md` | the **content contract** — what a page may contain and what those fields mean | `ckb-upgrade` (on a confirmed migration), `ckb-module` (additively, on install) |
| Template version | [`VERSION`](VERSION) | the **tooling layer** — `AGENTS.md`, the skills, the scripts, the docs | `ckb-upgrade`, when it pulls a newer template |
| `kb_schema_version` | frontmatter of `wiki/index.md` | the **content contract** - what a page may contain and what those fields mean | `ckb-upgrade` (on a confirmed migration), `ckb-module` (additively, on install) |
| Template version | [`VERSION`](../VERSION) | the **tooling layer** - `AGENTS.md`, the skills, the scripts, the docs | `ckb-upgrade`, when it pulls a newer template |
They move independently on purpose. You can take a newer set of skills
without touching a single wiki page, and a wiki authored against an older
schema keeps working — that is what the schema version is for.
schema keeps working - that is what the schema version is for.
**Versioning policy.** Bump the **minor** version for an additive change: a
new optional field, a new optional body section, a new optional scaffold
@ -41,7 +41,7 @@ so any page written since 2026-07-13 is still valid today.
Every `.md` file under `wiki/` except the reserved ones (`index.md`,
`log.md`) carries YAML frontmatter. Only `type` is required; the rest are
optional, and preferred where meaningful. The parser is deliberately simple —
optional, and preferred where meaningful. The parser is deliberately simple -
flat `key: value` pairs only, no nesting.
| Field | Required | Meaning |
@ -56,11 +56,11 @@ flat `key: value` pairs only, no nesting.
| `last_updated` | no | `YYYY-MM-DD`. When the *page* last changed. |
| `freshness_window_days` | no | Days before lint flags the page as stale. Typical: 90 for a wiki page, 365 for a decision, 30 for a connector-indexed document. |
| `retention` | no | `high` / `medium` / `low`. A `low` page is archived (never deleted) after 2× its freshness window. |
| `source_fingerprint` | no | *(1.5)* Digest of the source this page was built from — `sha256:<8 hex>` for a local file, or `etag:<value>` / `mtime:<iso8601>` for a connector item. |
| `source_checked` | no | *(1.5)* `YYYY-MM-DD` — when that digest was last verified. Distinct from `last_updated`: a re-check that finds nothing changed advances this and leaves `last_updated` alone. |
| `source_fingerprint` | no | *(1.5)* Digest of the source this page was built from - `sha256:<8 hex>` for a local file, or `etag:<value>` / `mtime:<iso8601>` for a connector item. |
| `source_checked` | no | *(1.5)* `YYYY-MM-DD` - when that digest was last verified. Distinct from `last_updated`: a re-check that finds nothing changed advances this and leaves `last_updated` alone. |
`wiki/index.md` alone carries `kb_schema_version`. It is a bundle-level
declaration, not a per-page one — individual pages never carry it.
declaration, not a per-page one - individual pages never carry it.
### Frontmatter — decision pages
@ -71,7 +71,7 @@ add:
|---|---|---|
| `status` | **yes** | `proposed` / `accepted` / `rejected` / `superseded` / `reversed`. The vocabulary is defined in `wiki/decisions/index.md` and validated by lint. |
| `decided_on` | for `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, the date the call was made. |
| `decided_by` | when known | Comma-separated names. Where genuinely unknown, write `unknown` rather than omitting the field — "we don't know who decided this" is itself worth recording. |
| `decided_by` | when known | Comma-separated names. Where genuinely unknown, write `unknown` rather than omitting the field - "we don't know who decided this" is itself worth recording. |
| `affects` | no | Comma-separated wiki paths this decision constrains. |
| `review_on` | no | `YYYY-MM-DD` to revisit. Lint reports these once the date passes. |
@ -102,7 +102,7 @@ that has merely aged.
#### `## Crux`
Verbatim excerpts from those sources — evidence, never paraphrase — attributed
Verbatim excerpts from those sources - evidence, never paraphrase - attributed
to the source bullet they came from:
```markdown
@ -117,7 +117,7 @@ Three to ten lines is the working range. A Crux approaching the length of the
summary above it has stopped being evidence and become a second copy of the
source. Two things follow from quoting rather than paraphrasing: a question
can often be answered from the page instead of the archive, and drift becomes
visible — a summary can wander from its source silently, a quote either still
visible - a summary can wander from its source silently, a quote either still
matches or it does not.
A page with no quotable source simply has no `## Crux`. An empty or
@ -134,8 +134,8 @@ drop this section; regeneration preserves it byte-for-byte.
<!-- Yours. Never rewritten by any skill. -->
```
This matters most on pages the agent *regenerates* — connector indexes, code
maps — where everything else is discarded and rebuilt on the next run. It is
This matters most on pages the agent *regenerates* - connector indexes, code
maps - where everything else is discarded and rebuilt on the next run. It is
the only place an annotation survives. Decision pages deliberately have no
`## Notes`: nothing regenerates them, and an append-only record with a freely
editable annotation block invites exactly the retroactive revision the
@ -145,7 +145,7 @@ append-only rule exists to prevent.
Relationships live in `wiki/graph/edges.json` (and each connector index's own
`graph/edges.json`). The vocabulary is closed, and each verb is defined by the
question it answers — if a proposed edge answers none of them, it belongs in
question it answers - if a proposed edge answers none of them, it belongs in
the page's prose instead.
| Verb | Question it answers | Since |
@ -166,7 +166,7 @@ the page's prose instead.
| `owns` | Who is responsible for this? | 1.3 |
| `mentioned_in` | Which source document discusses this? | 1.2 (lib indexes only) |
Record one direction per relationship — `part_of`, `supersedes`,
Record one direction per relationship - `part_of`, `supersedes`,
`depends_on` and `uses` are canonical, and the inverse is not stored as a
second edge. Record edges only from demonstrated evidence; an absent edge
beats a fabricated one, and a padded graph degrades retrieval rather than
@ -199,22 +199,22 @@ Adopted from an analysis of [trailhq/Graft](https://github.com/trailhq/Graft),
a context layer for coding agents that keeps a derived code graph in sync via
content hashes rather than dates, and protects a user-authored block on every
regenerated node. Graft's store is disposable and regenerable; this one is not,
so most of its design does not transfer — but several mechanisms do, and two
so most of its design does not transfer - but several mechanisms do, and two
of them closed real gaps here.
**Added:**
- **`## Crux`** — verbatim source excerpts alongside the synthesis. Lets
- `## Crux` - verbatim source excerpts alongside the synthesis. Lets
`ckb-retrieve` ground an answer without a round-trip to the archive (when
the fingerprint still matches), and makes drift detectable.
- **`## Notes`** — human-authored and protected everywhere. This closed a real
- `## Notes` - human-authored and protected everywhere. This closed a real
gap: `ckb-index-external` regenerates connector pages wholesale, so an
annotation written there was previously destroyed on the next refresh.
- **`## Sources`** — formalised as a reserved section with one fingerprinted
- `## Sources` - formalised as a reserved section with one fingerprinted
bullet per source. Previously an informal convention that `ckb-retrieve`
relied on but no skill actually specified.
- **`source_fingerprint` / `source_checked`** frontmatter.
- **Edge verbs** `part_of`, `produces`, `configures`, `validates`,
- `source_fingerprint` / `source_checked` frontmatter.
- Edge verbs `part_of`, `produces`, `configures`, `validates`,
`implements`. `part_of` fixed a live inconsistency: `ckb-code-map` had been
writing it since template 1.7.0 while the schema never declared it.
@ -228,7 +228,7 @@ of them closed real gaps here.
Ingest had been additive-first, which is how a wiki accumulates two pages
that quietly disagree.
- `ckb-retrieve` fuses graph in-degree as one ranked list among several,
weighted below 1.0 — centrality is a prior, not evidence.
weighted below 1.0 - centrality is a prior, not evidence.
- Rule E (session start) now runs `lint_report.py --quick` alongside
`git status`: a deterministic one-line knowledge-rot signal costing no
model tokens.
@ -236,7 +236,7 @@ of them closed real gaps here.
(the protected-`## Notes` rule).
**Compatibility:** fully additive. A 1.4 page with none of the new sections or
fields is valid 1.5. A migration will never manufacture a `## Crux` —
fields is valid 1.5. A migration will never manufacture a `## Crux` -
inventing quotes is precisely the failure that section exists to prevent.
### 1.4 — 2026-09-01 · decision records
@ -252,7 +252,7 @@ guess. Owned by the `ckb-decide` skill.
**Added:** the `has_expertise_in` and `owns` edge verbs, making "who knows
about X" and "who owns X" a graph lookup rather than a full-text search.
Recorded only from demonstrated evidence — attending a meeting is not
Recorded only from demonstrated evidence - attending a meeting is not
expertise, and a job title is not ownership.
### 1.2 — 2026-07-29 · query scopes, gaps, and connector-backed libs
@ -279,30 +279,31 @@ There was never a 1.0: versioning began with the first published schema.
## Template version history
The tooling layer — `AGENTS.md`/`CLAUDE.md`, the skills, the scripts, the
The tooling layer - `AGENTS.md`/`CLAUDE.md`, the skills, the scripts, the
docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| **1.9.0** | 2026-09-22 | Release channels: `main`/`test`/`experimental` branches, branch-aware `ckb-init` and `ckb-upgrade`, `template:` block in `ckb.yaml` | 1.5 |
| **1.10.0** | 2026-09-24 | Skill descriptions and bodies slimmed (edge cases → `references/`); `retrieve_candidates.py` takes over rank fusion; docs moved to `docs/`, template ADRs restored to `docs/decisions/`; `tests/` fixture + `smoke.sh`; `ckb.yaml` shipped; Rule B names the decisions-log exception; scaffold `overview.md` describes content, not schema; "Sync the wiki" trigger dropped | 1.5 |
| 1.9.0 | 2026-09-22 | Release channels: `main`/`test`/`experimental` branches, branch-aware `ckb-init` and `ckb-upgrade`, `template:` block in `ckb.yaml` | 1.5 |
| 1.8.0 | 2026-09-21 | Seven ideas adopted from Graft: crux/notes/fingerprints, `--quick` lint mode, in-degree ranking, ingest blast radius, completed edge vocabulary | → 1.5 |
| 1.7.0 | 2026-09-20 | Opt-in modules (`.agents/modules/`, `ckb-module`, `ckb.yaml`); the `software` module with `ckb-code-map` and `ckb-spec`; `ckb-reset`; OpenSpec docs | 1.4 |
| 1.6.1 | 2026-09-01 | Fixed false-positive broken-edge findings in the lint graph check | 1.4 |
| 1.6.0 | 2026-09-01 | `ckb-decide`; detection half of lint moved into `lint_report.py`; OKF export moved into `export_okf.py` | → 1.4 |
| 1.3.0 | 2026-08-06 | Rank fusion, dedupe and rerank in `ckb-retrieve`; expertise and ownership lookups | → 1.3 |
| 1.2.1 | 2026-07-29 | `AGENTS.md` compressed — workflows moved out into skills, leaving a small always-loaded rule set | 1.2 |
| 1.2.1 | 2026-07-29 | `AGENTS.md` compressed - workflows moved out into skills, leaving a small always-loaded rule set | 1.2 |
| 1.2.0 | 2026-07-29 | Project scopes, query gaps, source-verified retrieval | → 1.2 |
| 1.1.0 | 2026-07-20 | Connector-backed `libs/` with self-contained external source indexing (`ckb-index-external`) | 1.1 \* |
| 1.0.0 | 2026-07-17 | First tagged template: full skill set, `LICENSE`, `MANUAL`, bilingual docs | 1.1 |
\* Connector-backed libs shipped as tooling in 1.1.0, but the schema only
recorded them — the `source.yaml` contract, the generated index shape, the
`mentioned_in` verb — at 1.2, nine days later. The two numbers catching up
recorded them - the `source.yaml` contract, the generated index shape, the
`mentioned_in` verb - at 1.2, nine days later. The two numbers catching up
with each other like this is normal, and is why the schema column shows what
was in effect *after* each template release rather than what the release was
about.
Versions 1.4.0 and 1.5.0 were never published — the template jumped from
Versions 1.4.0 and 1.5.0 were never published - the template jumped from
1.3.0 to 1.6.0 on 2026-09-01.
---
@ -314,9 +315,9 @@ The template repo keeps three branches, and the version histories above track
| Branch | What it is | Who should track it |
|---|---|---|
| `main` | **Stable** — the released template | Everyone, by default |
| `test` | **Release candidate** — validated before merging to `main` | Anyone helping validate a release |
| `experimental` | **Development** — active work, may be broken or reverted | People developing the template itself |
| `main` | **Stable** - the released template | Everyone, by default |
| `test` | **Release candidate** - validated before merging to `main` | Anyone helping validate a release |
| `experimental` | **Development** - active work, may be broken or reverted | People developing the template itself |
The branch a KB tracks lives in `ckb.yaml`:
@ -331,7 +332,7 @@ you switch. No `ckb.yaml` and no `template:` block both mean `main`.
One consequence worth knowing: a KB that took tooling from `test` or
`experimental` can sit on a `VERSION` that `main` has not released yet.
Comparing it against `main` then finds nothing newer — which is true, but is
Comparing it against `main` then finds nothing newer - which is true, but is
**not** the same as "up to date", and `ckb-upgrade` reports it as "ahead"
rather than as current. Moving such a KB back to `main` is a *downgrade*: it
can remove skills and lower `kb_schema_version` below what local pages are
@ -346,7 +347,7 @@ Say **"upgrade the wiki"** or **"check for a newer template version"**. To use
a different channel, name it: *"upgrade from the test branch"*, *"check
experimental"*, *"switch back to stable"*. The
`ckb-upgrade` skill checks the canonical template repo, updates the tooling
layer in place, and — separately, and only after you explicitly confirm —
layer in place, and - separately, and only after you explicitly confirm -
migrates existing `wiki/` content up to the current schema while preserving
every fact already collected.
@ -356,15 +357,20 @@ intends to change, batches anything it had to infer (such as a missing `type`)
for your confirmation, and logs every touched page in `wiki/log.md` marked as
a schema-migration backfill rather than new knowledge.
Template 1.10 moved `MANUAL*`, `CHANGELOG*` and `OPENSPEC*` from the repo
root into `docs/`. A KB upgrading from 1.9 or older has them at the root;
`ckb-upgrade` moves them and updates the links in `README*`. Nothing under
`wiki/` is affected.
Because every schema version so far has been additive, an older wiki keeps
working unmigrated. Migration is worth doing to make the newer checks
meaningful — backfilled fingerprints are what give lint anything to verify —
meaningful - backfilled fingerprints are what give lint anything to verify -
not because anything is broken without it.
---
## Version & License
Current template version: [VERSION](VERSION). Current schema version: the
Current template version: [VERSION](../VERSION). Current schema version: the
`kb_schema_version` field in `wiki/index.md`. Licensed under the
[Apache License 2.0](LICENSE).
[Apache License 2.0](../LICENSE).

View file

@ -11,7 +11,7 @@ Istnieją **dwa niezależne numery wersji** i nie są tym samym:
| Numer | Mieszka w | Opisuje | Kto go podnosi |
|---|---|---|---|
| `kb_schema_version` | frontmatter `wiki/index.md` | **kontrakt treści** — co strona może zawierać i co te pola znaczą | `ckb-upgrade` (przy potwierdzonej migracji), `ckb-module` (addytywnie, przy instalacji) |
| Wersja szablonu | [`VERSION`](VERSION) | **warstwa narzędziowa** — `AGENTS.md`, skille, skrypty, dokumentacja | `ckb-upgrade`, gdy pobiera nowszy szablon |
| Wersja szablonu | [`VERSION`](../VERSION) | **warstwa narzędziowa** — `AGENTS.md`, skille, skrypty, dokumentacja | `ckb-upgrade`, gdy pobiera nowszy szablon |
Poruszają się niezależnie i jest to celowe. Możesz wziąć nowszy zestaw skilli
bez dotykania choćby jednej strony wiki, a wiki napisane pod starszy schemat
@ -208,17 +208,17 @@ przenosi — ale kilka mechanizmów tak, a dwa z nich zamknęły tu realne luki.
**Dodano:**
- **`## Crux`** — dosłowne fragmenty źródeł obok syntezy. Pozwala
- `## Crux` — dosłowne fragmenty źródeł obok syntezy. Pozwala
`ckb-retrieve` ugruntować odpowiedź bez powrotu do archiwum (gdy skrót się
wciąż zgadza) i czyni odpływ od źródła wykrywalnym.
- **`## Notes`** — pisane przez człowieka i chronione wszędzie. To zamknęło
- `## Notes` — pisane przez człowieka i chronione wszędzie. To zamknęło
realną lukę: `ckb-index-external` regeneruje strony konektora w całości,
więc napisana tam adnotacja ginęła dotąd przy kolejnym odświeżeniu.
- **`## Sources`** — sformalizowane jako sekcja zastrzeżona z jednym
- `## Sources` — sformalizowane jako sekcja zastrzeżona z jednym
punktem ze skrótem na źródło. Wcześniej nieformalna konwencja, na której
`ckb-retrieve` polegało, ale której żaden skill faktycznie nie określał.
- **`source_fingerprint` / `source_checked`** we frontmatterze.
- **Czasowniki krawędzi** `part_of`, `produces`, `configures`, `validates`,
- `source_fingerprint` / `source_checked` we frontmatterze.
- Czasowniki krawędzi `part_of`, `produces`, `configures`, `validates`,
`implements`. `part_of` naprawiło żywą niespójność: `ckb-code-map`
zapisywał go od szablonu 1.7.0, a schemat nigdy go nie deklarował.
@ -291,7 +291,8 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.9.0** | 2026-09-22 | Kanały wydawnicze: gałęzie `main`/`test`/`experimental`, świadome gałęzi `ckb-init` i `ckb-upgrade`, blok `template:` w `ckb.yaml` | 1.5 |
| **1.10.0** | 2026-09-24 | Odchudzone opisy i treści skilli (przypadki brzegowe → `references/`); `retrieve_candidates.py` przejmuje fuzję rankingów; dokumentacja przeniesiona do `docs/`, ADR-y szablonu przywrócone w `docs/decisions/`; fixture `tests/` + `smoke.sh`; dołączony `ckb.yaml`; Reguła B nazywa wyjątek dziennika decyzji; szkieletowy `overview.md` opisuje treść, nie schemat; usunięty wyzwalacz „Sync the wiki” | 1.5 |
| 1.9.0 | 2026-09-22 | Kanały wydawnicze: gałęzie `main`/`test`/`experimental`, świadome gałęzi `ckb-init` i `ckb-upgrade`, blok `template:` w `ckb.yaml` | 1.5 |
| 1.8.0 | 2026-09-21 | Siedem pomysłów zaadaptowanych z Graftu: crux/notes/skróty źródeł, tryb `--quick` lintu, ranking po stopniu wejściowym, promień rażenia w ingeście, dokończony słownik krawędzi | → 1.5 |
| 1.7.0 | 2026-09-20 | Opcjonalne moduły (`.agents/modules/`, `ckb-module`, `ckb.yaml`); moduł `software` z `ckb-code-map` i `ckb-spec`; `ckb-reset`; dokumentacja OpenSpec | 1.4 |
| 1.6.1 | 2026-09-01 | Naprawa fałszywie dodatnich znalezisk uszkodzonych krawędzi w kontroli grafu | 1.4 |
@ -363,6 +364,11 @@ brakujące `type`), do twojego potwierdzenia i loguje każdą dotkniętą stron
`wiki/log.md` z adnotacją, że to uzupełnienie migracyjne schematu, a nie nowa
wiedza.
Szablon 1.10 przeniósł `MANUAL*`, `CHANGELOG*` i `OPENSPEC*` z katalogu
głównego do `docs/`. KB aktualizowana z 1.9 lub starszej ma je w katalogu
głównym; `ckb-upgrade` przenosi je i poprawia linki w `README*`. Nic pod
`wiki/` nie jest dotknięte.
Ponieważ każda dotychczasowa wersja schematu była addytywna, starsze wiki
działa bez migracji. Migrację warto zrobić po to, żeby nowsze kontrole miały
sens — uzupełnione skróty źródeł dają lintowi cokolwiek do weryfikacji — a
@ -372,6 +378,6 @@ nie dlatego, że bez niej coś jest zepsute.
## Wersja i licencja
Aktualna wersja szablonu: [VERSION](VERSION). Aktualna wersja schematu: pole
Aktualna wersja szablonu: [VERSION](../VERSION). Aktualna wersja schematu: pole
`kb_schema_version` w `wiki/index.md`. Licencja:
[Apache License 2.0](LICENSE).
[Apache License 2.0](../LICENSE).

View file

@ -3,16 +3,16 @@
*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). For the page schema in full and the version
(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). For the page schema in full and the version
histories behind it, see [CHANGELOG.md](CHANGELOG.md). This document is
task-oriented: "I want to do X — what do I say, and what happens?"
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
`AGENTS.md`). You don't need exact wording - the trigger phrases shown are
examples, not magic words; the agent matches intent.
---
@ -22,7 +22,7 @@ examples, not magic words; the agent matches intent.
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)
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)
@ -34,7 +34,7 @@ examples, not magic words; the agent matches intent.
### If you're reading this inside an existing Cascade KB
Nothing to do — the structure already exists (`wiki/`, `raw/`, `outputs/`,
Nothing to do - the structure already exists (`wiki/`, `raw/`, `outputs/`,
etc.). Skip to [§2](#2-adding-knowledge).
### Starting a brand-new one elsewhere
@ -43,8 +43,8 @@ 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
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`.
@ -52,14 +52,13 @@ first `raw/inbox/` drop. See `.agents/skills/ckb-init/SKILL.md`.
The template can come from two places: this repo's own files, or a fresh
shallow clone of the canonical template repo (or any fork/mirror URL you
name) pulled into a scratch folder. Say "pull the latest template and set
up a KB in \<folder\>" — or run it from outside any KB at all — and the
up a KB in \<folder\>" - or run it from outside any KB at all - and the
agent clones first, then builds the scaffold from that. The clone is
scratch only: the new KB gets its own git history (the agent asks before
running `git init`), not the template's.
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.
`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
@ -77,13 +76,13 @@ which stay entirely read-only. There are three ways to mount one:
git clone https://github.com/org/external-kb ./libs/external-kb
```
Don't want to use git? Most git hosts also offer a "Download ZIP"
option on the repo's page — download it and unpack the contents
option on the repo's page - download it and unpack the contents
straight into `./libs/external-kb` instead. You end up with the same
frozen, read-only copy either way; the only difference is you won't be
able to `git pull` it later to refresh — to update it, just re-download
able to `git pull` it later to refresh - to update it, just re-download
the ZIP and unpack it over the old contents.
- **Connector** (a live external source you *don't* want a full local
copy of — a SharePoint folder, a Google Drive folder, or another
copy of - a SharePoint folder, a Google Drive folder, or another
connected source): create `libs/<name>/source.yaml` yourself:
```yaml
connector: sharepoint
@ -93,42 +92,41 @@ which stay entirely read-only. There are three ways to mount one:
then say "index external sources." The agent reads the config, connects
to whatever's available that session (a connected Microsoft 365/Google
Drive tool, or a plain URL fetch), and builds a short index of what it
finds — one entry per document — inside that same `libs/<name>/` folder.
finds - one entry per document - inside that same `libs/<name>/` folder.
See [§6](#6-use-cases) for a worked example and what the result looks
like.
Two things worth knowing up front about a connector source:
- **You don't have to build the index yourself.** `source.yaml` can add
an `index:` block pointing at an already-built index — a git repo, or
a shared resource — so you just fetch what someone else already
Before you rely on a connector source:
- You don't have to build the index yourself. `source.yaml` can add
an `index:` block pointing at an already-built index - a git repo, or
a shared resource - so you just fetch what someone else already
indexed instead of scanning the live source yourself. Every run checks
that location first: if there's already an index there, you get it; if
there isn't yet (the normal state before anyone's run this with write
access), that's not an error — whoever has write access is the one
access), that's not an error - whoever has write access is the one
whose next run creates and publishes it there for the first time.
- **Building/refreshing is opt-in per person, per source.** By default,
everyone is read-only for a connector source — nobody's agent will
- Building and refreshing are opt-in, per person, per source. By default,
everyone is read-only for a connector source - nobody's agent will
scan the live connector on their behalf unless they've explicitly said
so. Say "make me the admin for `<source>`" to opt yourself in (this
writes a local, personal `libs/<name>/source.local.yaml` — never
committed, never seen by anyone else). This is deliberate: it lets one
or two people maintain a source for the whole team instead of everyone
redundantly re-scanning it.
- **You can set how often it should be refreshed.** Add an optional
writes a local, personal `libs/<name>/source.local.yaml` - never
committed, never seen by anyone else). One or two people maintain a
source for the whole team; nobody else re-scans it.
- You can set how often it should be refreshed. Add an optional
`refresh_interval_days: 7` to `source.yaml` (it defaults to 30). A
folder that churns daily wants a shorter window than a quarterly
archive nobody touches. Both "index external sources" and "Lint" then
tell you when a source is overdue and by how much — which matters most
tell you when a source is overdue and by how much - which matters most
if you're read-only for it, since knowing *which* source has gone
stale is what lets you go ask the person who maintains it.
Either way, once it's mounted, just ask questions normally — the agent
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 a
git-copy `libs/<name>/` directly; if something there is wrong or outdated,
you fix it by writing the corrected version into your own local `wiki/`,
which always wins. (A connector-backed `libs/<name>/` is the one place the
agent *does* write on your behalf — see [§6](#6-use-cases) — but only its
agent *does* write on your behalf - see [§6](#6-use-cases) - but only its
generated index, and only the build/refresh part if you're that source's
admin; `source.yaml` itself always stays yours to edit, never the agent's.)
@ -140,11 +138,11 @@ 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`
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)
> "Ingest." (or "Update the wiki" - same thing; never a phrase with "sync" in it, that is git)
Example:
@ -161,7 +159,7 @@ Example:
For a long transcript, the agent doesn't just write one summary page. It
pulls out the searchable question, the summary, the resolution, the systems
and people involved — and promotes individual passages to their own
and people involved - and promotes individual passages to their own
findable sections when they'd otherwise be lost inside a summary. That last
part has a deliberate bar: a passage has to contain a genuinely specific
term (a flag, an error string, a clause, a version), run to a couple of
@ -173,20 +171,19 @@ again, which defeats the point of ingesting 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`.
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
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.
silently - it identifies the gap and proposes a minimal page to fill it.
Example:
@ -194,7 +191,7 @@ Example:
> **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
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.
@ -205,7 +202,7 @@ source or page that would make the answer available next time.
### D. Record a decision
When a call gets made — a technology choice, a process change, a policy —
When a call gets made - a technology choice, a process change, a policy -
say:
> "Record a decision: we're moving billing to Postgres. Alice and Bob
@ -214,7 +211,7 @@ say:
The agent writes a numbered record under `wiki/decisions/` with the decision,
who decided, when, the rationale, the alternatives, and what it affects. If
it replaces an earlier decision, it links the two in both directions and
marks the old one superseded — without touching the old page's reasoning.
marks the old one superseded - without touching the old page's reasoning.
Anything you leave out, it asks for in one round; if you're mid-flow, say so
and it records what you gave it and tells you which fields it left open.
@ -227,17 +224,16 @@ Then ask about them however you like:
> "What superseded decision 3?"
The answer always comes with who and when attached, and says plainly when a
decision is proposed rather than accepted, or has since been superseded —
so you don't act on something that isn't in force. Implemented by the
`ckb-decide` skill.
decision is proposed rather than accepted, or has since been superseded -
so you don't act on something that isn't in force. Skill: `ckb-decide`.
Two things worth knowing:
Two rules:
- **Decisions are append-only.** "Actually, we changed our mind" creates a
- Decisions are append-only. "Actually, we changed our mind" creates a
*new* decision that supersedes the old one; it never edits the old one's
reasoning. That's deliberate — the history is the point. Genuine
reasoning. The history is the point. Genuine
transcription errors ("I said Alice, it was Anna") do get fixed in place.
- **A proposal is not a decision.** If it wasn't actually settled, it's
- A proposal is not a decision. If it wasn't actually settled, it's
recorded as `proposed` with no decision date, and shows up when you ask
what's still open.
@ -256,7 +252,7 @@ local wiki; this just gives repeated questions a better starting area.
## 3. Keeping it tidy
Say, whenever you like (there's no fixed schedule — do it after a big
Say, whenever you like (there's no fixed schedule - do it after a big
ingest, or just periodically):
> "Lint."
@ -272,43 +268,43 @@ This runs a health check across the whole wiki:
- broken graph edges get fixed or removed
- missing/duplicate index and log entries get corrected
- connector-backed sources whose index is overdue for a refresh get
flagged, with how overdue they are — useful even if you're read-only for
flagged, with how overdue they are - useful even if you're read-only for
that source, since it tells you who to chase
- **pages whose source has actually changed** get flagged — see below
- **quotes that no longer appear in the source they cite** get flagged
- pages whose source has actually changed get flagged - see below
- quotes that no longer appear in the source they cite get flagged
- recurring systemic issues get written into `wiki/error-book.md`
The last two are worth understanding, because they're the difference
between "this page is old" and "this page is wrong".
The last two are the difference between "this page is old" and "this page
is wrong".
Every page records a fingerprint of the material it was built from. Staleness
by date is a guess: a page written a year ago may still be perfectly accurate.
A fingerprint is not a guess — the agent recomputes it and either the source
A fingerprint is not a guess - the agent recomputes it and either the source
is byte-for-byte what the page was written against, or somebody edited it.
When a source changes, the page built on it goes to the top of the list,
ahead of anything that has merely aged.
Pages also quote their sources directly, in a `## Crux` section — a few
Pages also quote their sources directly, in a `## Crux` section - a few
verbatim lines carrying the actual claim, underneath the agent's summary of
it. Two things follow from that. When you ask a question, the agent can often
answer from the quote instead of re-reading the whole source, and show you the
words rather than its paraphrase of them. And when a quote stops matching its
source, that's a page asserting, in quotation marks, something its evidence no
longer says — the strongest finding lint produces, and the agent will never
longer says - the strongest finding lint produces, and the agent will never
"fix" it by quietly editing the quote to match.
The detection half runs as a read-only Python script
(`scripts/lint_report.py`), so the same wiki always produces the same
findings list — the agent reads that report and then does the parts that
findings list - the agent reads that report and then does the parts that
need judgment (supersession, ambiguous orphans, error-book entries, and
deciding what to fix versus what to hand back to you). 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 —
safely can on its own and reports the rest for you to decide. Like Ingest,
it finishes by reminding you to review and sync. Skill:
`.agents/skills/ckb-lint/SKILL.md`.
### Starting over: resetting to a clean template
Sometimes you want the *shape* of a knowledge base without its contents —
Sometimes you want the *shape* of a knowledge base without its contents -
typically because this repo doubles as the template you hand to other
people, and it has accumulated decisions, workload summaries and entity
pages that shouldn't ship with it.
@ -326,12 +322,12 @@ so it is built to be hard to trigger by accident:
2. **It asks how far to go.** Six tiers, chosen individually: wiki knowledge,
workload history, `raw/` source material, `outputs/`, external sources,
and installed modules. Only the first is on by default. `libs/`,
`linked/` and modules default to *no* — `linked/` holds symlinks into
`linked/` and modules default to *no* - `linked/` holds symlinks into
other people's knowledge bases, and it will remove a link but never
follow one.
3. **It counts before it asks.** You get an inventory — how many pages, how
3. **It counts before it asks.** You get an inventory - how many pages, how
many decision records (listed by number and title), how many graph edges,
plus anything marked `retention: high` — and one line on what survives.
plus anything marked `retention: high` - and one line on what survives.
4. **It wants a typed phrase**, not a "yes". And if you change the scope in
your reply, it re-counts and asks again, because you agreed to a number
and the number moved.
@ -346,17 +342,16 @@ What it never touches, with or without confirmation: the template layer
holds independent code repositories this command has no business deleting.
One deliberate quirk: unlike every other skill, this one does **not** write a
`workload/` session note — that entry would be the first thing in a directory
`workload/` session note - that entry would be the first thing in a directory
it has just emptied. It tells you so in its report.
Implemented by the `ckb-reset` skill —
`.agents/skills/ckb-reset/SKILL.md`.
Skill: `.agents/skills/ckb-reset/SKILL.md`.
---
## 4. Syncing — with yourself, and with other people
There are two entirely different kinds of "sync" here — don't confuse
There are two entirely different kinds of "sync" here - don't confuse
them:
| | Ingest / Lint | Sync changes |
@ -372,8 +367,8 @@ 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
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.
@ -385,35 +380,33 @@ to paste the URL first:
>
> **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) —
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.
You don't have to `git clone` it to get a working copy, either — if you'd
You don't have to `git clone` it to get a working copy, either - if you'd
rather not use git at all, download it as a ZIP from that page and unpack
it locally; you'll have the exact same files and can point your agent at
the unpacked folder right away. The one thing you'll be missing is a
configured `origin`, so "sync changes" and "upgrade the wiki" won't have
anything to push to or compare against yet — run `git init` in the
anything to push to or compare against yet - run `git init` in the
unpacked folder and add the URL above as `origin` (`git remote add origin
https://git.wierzbowa.cloud/michal/ckb`) whenever you're ready for those.
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`.
changes" is how each person's changes reach everyone else - and how theirs
reach you. 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.
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
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
@ -425,7 +418,7 @@ schedule, independently.
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
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
@ -442,22 +435,22 @@ one:
| Branch | What it is | Who should be on it |
|---|---|---|
| `main` | **Stable** — the released template | You, unless you have a reason not to be |
| `test` | **Release candidate** — validated before it reaches `main` | You're helping validate a release, or you need a fix that's landed but not shipped |
| `experimental` | **Development** — active work, may be broken or reverted | You're developing the template itself |
| `main` | **Stable** - the released template | You, unless you have a reason not to be |
| `test` | **Release candidate** - validated before it reaches `main` | You're helping validate a release, or you need a fix that's landed but not shipped |
| `experimental` | **Development** - active work, may be broken or reverted | You're developing the template itself |
To use a different one, just say which:
> "Upgrade from the test branch." / "Check experimental for updates." /
> "Switch this KB back to the stable channel."
Whichever you pick sticks — it's recorded in `ckb.yaml`, so the next upgrade
Whichever you pick sticks - it's recorded in `ckb.yaml`, so the next upgrade
stays on the same channel rather than quietly pulling you back to `main`. The
same goes at creation time: *"initialize from the experimental branch"*.
One thing to watch. If you're tracking `test` or `experimental`, your KB can
sit on a version `main` hasn't released yet. Checking against `main` then
finds nothing newer — the agent will tell you you're **ahead**, not that
finds nothing newer - the agent will tell you you're **ahead**, not that
you're up to date, because those are different situations. Going back to
`main` from there is a *downgrade*: it can remove skills and roll the schema
back below what your pages are written against. You'll be asked to confirm
@ -469,27 +462,27 @@ to its own declared schema.
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
- **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`
- **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.
`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.
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
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.
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),
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`
@ -499,8 +492,8 @@ you'll get a distinct, explicit question:
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
- 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
@ -509,17 +502,17 @@ If you say yes, the agent:
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
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
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`.
template project's own working copy. Skill:
`.agents/skills/ckb-upgrade/SKILL.md`.
---
@ -533,19 +526,19 @@ Just ask, in plain language:
The agent reads `wiki/index.md` first to find relevant pages. If a matching
project scope exists under `wiki/projects/`, it searches that scope first.
Then it checks one-line `tldr` fields, runs exact local search for literal
tokens when needed, expands context around matching sections, 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.
Then it runs `retrieve_candidates.py`, which gathers exact-match, `tldr`,
project-scope, graph and trust signals into one fused ranking, expands
context around matching sections, 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.
Two things about that worth knowing as a user:
Two details matter as a user:
- **It searches `raw/inbox/` too.** Something you dropped in this morning
- It searches `raw/inbox/` too. Something you dropped in this morning
and haven't ingested yet can still answer your question. The agent will
tell you when an answer came from un-ingested material, which doubles as
a nudge that "Ingest" is overdue.
- **Answers carry their own caveats.** If the page behind an answer is past
- Answers carry their own caveats. If the page behind an answer is past
its freshness window, scored low on confidence, or was read from a cached
connector index instead of a live check, the answer says so next to the
claim. If two pages disagree and neither has been marked superseded yet,
@ -560,7 +553,7 @@ Two things about that worth knowing as a user:
These are answered from the knowledge graph directly rather than by
keyword-searching for names. Ingest records an expertise or ownership edge
when the source material actually shows someone answering questions on a
topic or holding declared responsibility for it — not from having attended
topic or holding declared responsibility for it - not from having attended
a meeting or from a job title. If nobody has a recorded edge yet, the agent
falls back to who the archived sources show answering that kind of question
and tells you it's inferring rather than reporting.
@ -571,16 +564,16 @@ smallest source to drop into `raw/inbox/`.
### Learn from the wiki
**Quick test of what you know** — say:
**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.
running score. Nothing is saved afterward - it's a one-off check.
`.agents/skills/ckb-quiz/SKILL.md`.
**A proper course, spread over time** — say:
**A proper course, spread over time** - say:
> "Teach me the wiki." / "Teach me about the supplier onboarding process."
@ -590,32 +583,31 @@ 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
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:
**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
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:
**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
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:
**A machine-readable export for other tools** - say:
> "Export the wiki as OKF."
@ -624,27 +616,27 @@ 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:
**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
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
**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
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
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.
@ -657,7 +649,7 @@ Say:
This walks every `libs/<name>/` that has a `source.yaml` (see
[§1](#building-on-top-of-someone-elses-wiki)) and builds a short index of
what it finds — one entry per document, plus an overview page — entirely
what it finds - one entry per document, plus an overview page - entirely
inside that same `libs/<name>/` folder. Nothing under `wiki/` is touched.
Example:
@ -677,7 +669,7 @@ Example:
> `libs/finance-reports/index.md` (an overview of the source) plus one
> page per document under `libs/finance-reports/entities/`, cross-linked
> via `libs/finance-reports/graph/edges.json`. It logs everything in
> `libs/finance-reports/log.md` — a log that's entirely separate from
> `libs/finance-reports/log.md` - a log that's entirely separate from
> `wiki/log.md`, since this index is scoped to that one connector rather
> than blended into your main wiki. It finishes by reminding you to review
> the result and say "sync changes" once you're happy with it.
@ -686,24 +678,23 @@ If a connector needs authorizing (e.g. a SharePoint or Google Drive
connection that isn't set up yet), the agent tells you which one and where
to authorize it, then continues with any other configured sources rather
than stopping the whole run. Run "index external sources" again any time
the source has changed — it refreshes existing entries in place rather
the source has changed - it refreshes existing entries in place rather
than duplicating them, and never deletes a page for a document that's
disappeared from the source (it flags it instead, so a later "Lint" pass
archives it naturally). Implemented by the `ckb-index-external` skill —
`.agents/skills/ckb-index-external/SKILL.md`.
archives it naturally). Skill: `.agents/skills/ckb-index-external/SKILL.md`.
**Who's allowed to build it, and where it's shared.** By default, nobody
has write access to a connector source until they say so — this keeps a
has write access to a connector source until they say so - this keeps a
team of, say, ten people from all redundantly scanning the same SharePoint
folder. Say:
> "Make me the admin for finance-reports."
This writes a personal `libs/finance-reports/source.local.yaml` with
`access: write` — never committed, never seen by your teammates. Anyone
`access: write` - never committed, never seen by your teammates. Anyone
without that file is read-only for that source: if they say "index
external sources," the agent won't touch the live connector on their
behalf at all — it just reports what's already indexed (or tells them
behalf at all - it just reports what's already indexed (or tells them
plainly that nothing has been indexed yet and who to ask).
If the finance team wants everyone reading the *same* index rather than
@ -718,35 +709,35 @@ index:
```
The very first time anyone runs "index external sources" after that block
is added, `https://github.com/finance-team/index-cache.git` is empty —
is added, `https://github.com/finance-team/index-cache.git` is empty -
that's expected, not an error. Every run checks it first: read-only users
just see "nothing published yet, ask the admin"; the admin's run is what
actually creates it there, since a write-access run always rebuilds from
the live connector and pushes the result to that location, whether or not
anything was there before. From then on, whenever *anyone* says "index
external sources," the agent first fetches whatever's already published
there — read-only users stop right there; the admin also rebuilds from the
there - read-only users stop right there; the admin also rebuilds from the
live connector and pushes the refreshed index back to that same location,
so the next person's fetch picks it up. Leave the `index:` block out
entirely (the simplest setup, and the right default for a single small
team) and the index just lives
directly inside `libs/finance-reports/` in this KB's own repo, shared the
normal way via "sync changes" — exactly like the plain example above.
normal way via "sync changes" - exactly like the plain example above.
---
## 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.
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
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.
There is one exception that runs the other way. On any page the agent
*regenerates* — a connector index, a code map — everything you write is
*regenerates* - a connector index, a code map - everything you write is
normally lost on the next rebuild. So every such page ends with a `## Notes`
section that no skill will ever touch:
@ -756,39 +747,55 @@ section that no skill will ever touch:
<!-- Yours. Never rewritten by any skill. -->
```
Write whatever you want there — that this document is obsolete, that the
Write whatever you want there - that this document is obsolete, that the
person named in it has left, who to actually ask. It is carried across
rebuilds byte-for-byte. Anything you write *above* that heading on a
generated page will be overwritten.
| 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/`. |
| `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>/` (git-copy, no `source.yaml`) | **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 it. |
| `libs/<name>/source.yaml` (connector) | **You, only** | Declares the connector, location, optionally how often it should be refreshed (`refresh_interval_days:`), and optionally where a shared/pre-built index lives (`index:`). The agent reads it but never writes it — same as anything else upstream. |
| `libs/<name>/source.local.yaml` (connector) | **You** (or the agent, only when you explicitly ask to become/stop being that source's admin) | Per-person, per-machine `access: write`/`read` setting — never committed, never seen by anyone else. Absent = read-only, the default. |
| `libs/<name>/{index.md,entities/,graph/,log.md}` (connector) | Agent-generated, **you can freely edit** | The agent's own index of that one connector's source, built/refreshed by "Index external sources" — but only if you have `access: write` locally; read-only users just get a fetched copy. Structurally the same deal as the main `wiki/` row below — feel free to correct an entry by hand, then run "Lint" (it now also checks connector-backed indexes, respecting the same read/write split). Scoped entirely to that connector; never blended into `wiki/`. **Only `## Notes` survives a rebuild** — put anything you want to keep there. |
| `wiki/decisions/` | Agent-generated, **edit with care** | Same as the rest of `wiki/` mechanically, but these are append-only by convention: correct a typo or a misattributed name freely, and don't rewrite a decision's context or rationale to match a later view — record a superseding decision instead, so the history survives. |
| `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. |
| `libs/<name>/source.yaml` (connector) | **You, only** | Declares the connector, location, optionally how often it should be refreshed (`refresh_interval_days:`), and optionally where a shared/pre-built index lives (`index:`). The agent reads it but never writes it - same as anything else upstream. |
| `libs/<name>/source.local.yaml` (connector) | **You** (or the agent, only when you explicitly ask to become/stop being that source's admin) | Per-person, per-machine `access: write`/`read` setting - never committed, never seen by anyone else. Absent = read-only, the default. |
| `libs/<name>/{index.md,entities/,graph/,log.md}` (connector) | Agent-generated, **you can freely edit** | The agent's own index of that one connector's source, built/refreshed by "Index external sources" - but only if you have `access: write` locally; read-only users just get a fetched copy. Structurally the same deal as the main `wiki/` row below - feel free to correct an entry by hand, then run "Lint" (it now also checks connector-backed indexes, respecting the same read/write split). Scoped entirely to that connector; never blended into `wiki/`. **Only `## Notes` survives a rebuild** - put anything you want to keep there. |
| `wiki/decisions/` | Agent-generated, **edit with care** | Same as the rest of `wiki/` mechanically, but these are append-only by convention: correct a typo or a misattributed name freely, and don't rewrite a decision's context or rationale to match a later view - record a superseding decision instead, so the history survives. |
| `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*`, `docs/`, `tests/`, `ckb.yaml` | 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. |
---
### Where the template's own decisions live
`docs/decisions/` holds the template's design records (D-0001, D-0002…) in
the same format as `wiki/decisions/`, but as part of the template layer:
skills and docs cite them, so they must survive a `ckb-reset` and travel with
`ckb-upgrade`. Your KB's own decisions still go to `wiki/decisions/` via
"record a decision" - never here.
### Checking a template release
`tests/smoke.sh` runs the deterministic scripts (`lint_report.py`,
`retrieve_candidates.py`) against the fixture KB in `tests/fixtures/` and
diffs the result with `tests/expected/`. Run it before merging anything to
`test` or `main`; run it with `--update` after an intended change to the
scripts' output.
## 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` |
| "Pull the ckb repo into \<folder\> and set up the wiki" | Clones the template repo to a scratch dir, then bootstraps an empty KB from it | `ckb-init` |
| "Ingest" / "Sync the wiki" / "Update the wiki" | Processes `raw/inbox/` into structured `wiki/` pages | `ckb-ingest` |
| "Ingest" / "Update the wiki" | Processes `raw/inbox/` into structured `wiki/` pages | `ckb-ingest` |
| "Record a decision: ..." / "we decided ..." | Writes a numbered decision record under `wiki/decisions/` | `ckb-decide` |
| "What did we decide about X" / "who decided X" / "what's still open" | Answers from the decision records, with who/when/status attached | `ckb-decide` |
| "Lint" | Health-checks the wiki, auto-fixes what it safely can | `ckb-lint` |

View file

@ -4,9 +4,9 @@
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)). Pełny schemat strony wraz z historią obu
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)). Pełny schemat strony wraz z historią obu
numerów wersji znajdziesz w [CHANGELOG.pl.md](CHANGELOG.pl.md). Ten dokument
jest zorientowany na zadania:
„chcę zrobić X — co mam powiedzieć i co się wtedy stanie?”
@ -102,8 +102,8 @@ podpięcia:
samego folderu `libs/<name>/`. Zobacz [§6](#6-przykłady-użycia) po
omówiony przykład i to, jak wygląda wynik.
Dwie rzeczy warto wiedzieć z góry o źródle typu konektor:
- **Nie musisz sam budować indeksu.** `source.yaml` może dodać blok
Zanim oprzesz się na źródle typu konektor:
- Nie musisz sam budować indeksu. `source.yaml` może dodać blok
`index:` wskazujący na już zbudowany indeks — repozytorium git albo
zasób współdzielony — dzięki czemu po prostu pobierasz to, co ktoś
inny już zaindeksował, zamiast samodzielnie skanować żywe źródło.
@ -112,16 +112,16 @@ podpięcia:
zanim ktokolwiek z dostępem do zapisu to uruchomił), to nie błąd —
ten, kto ma dostęp do zapisu, tworzy go tam i publikuje przy swoim
kolejnym uruchomieniu.
- **Budowanie/odświeżanie jest opcjonalne, per osoba, per źródło.**
- Budowanie i odświeżanie są opcjonalne, per osoba, per źródło.
Domyślnie każdy jest tylko-do-odczytu dla źródła typu konektor —
agent nikogo nie przeskanuje żywego konektora w jego imieniu, jeśli
wyraźnie tego nie zadeklarował. Powiedz „make me the admin for
`<source>`", żeby się na to zapisać (tworzy to lokalny, osobisty plik
`libs/<name>/source.local.yaml` — nigdy niecommitowany, nigdy
niewidoczny dla współpracowników). To celowe: pozwala jednej lub dwóm
niewidoczny dla współpracowników). Pozwala to jednej lub dwóm
osobom utrzymywać źródło dla całego zespołu, zamiast żeby każdy
redundantnie je skanował.
- **Możesz ustawić, jak często ma być odświeżane.** Dodaj opcjonalne
- Możesz ustawić, jak często ma być odświeżane. Dodaj opcjonalne
`refresh_interval_days: 7` do `source.yaml` (domyślnie 30). Folder
zmieniający się codziennie potrzebuje krótszego okna niż kwartalne
archiwum, którego nikt nie tyka. Wtedy zarówno „index external
@ -154,7 +154,7 @@ 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)
> „Ingest.” (lub „Update the wiki” — to samo; nigdy fraza zawierająca „sync”, to jest git)
Przykład:
@ -182,8 +182,7 @@ jego zingestowania.
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`.
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
### B. Po prostu powiedz agentowi coś w rozmowie
@ -238,16 +237,14 @@ Potem pytaj, jak chcesz:
Odpowiedź zawsze przychodzi z informacją kto i kiedy, i wprost mówi, gdy
decyzja jest propozycją, a nie decyzją obowiązującą, albo została już
zastąpiona — żebyś nie działał na czymś, co nie obowiązuje. Zaimplementowane
przez skill `ckb-decide`.
zastąpiona — żebyś nie działał na czymś, co nie obowiązuje. Skill: `ckb-decide`.
Dwie rzeczy warte zapamiętania:
Dwie zasady:
- **Decyzje są tylko do dopisywania.** „Właściwie zmieniliśmy zdanie" tworzy
*nową* decyzję zastępującą starą; nigdy nie edytuje uzasadnienia starej. To
celowe — historia jest tu sednem. Zwykłe błędy zapisu („powiedziałem Alice,
- Decyzje są tylko do dopisywania. „Właściwie zmieniliśmy zdanie" tworzy
*nową* decyzję zastępującą starą; nigdy nie edytuje uzasadnienia starej. Historia jest tu sednem. Zwykłe błędy zapisu („powiedziałem Alice,
a było Anna") poprawiane są w miejscu.
- **Propozycja to nie decyzja.** Jeśli sprawa nie została rozstrzygnięta,
- Propozycja to nie decyzja. Jeśli sprawa nie została rozstrzygnięta,
zapisywana jest jako `proposed` bez daty decyzji i pojawia się, gdy pytasz,
co jest jeszcze otwarte.
@ -287,9 +284,9 @@ To uruchamia przegląd kondycji całej wiki:
- konektorowe źródła, których indeks jest zaległy do odświeżenia, zostają
oflagowane wraz z informacją o ile — przydatne nawet jeśli masz do tego
źródła dostęp tylko do odczytu, bo mówi ci, kogo dopytać
- **strony, których źródło faktycznie się zmieniło**, zostają oflagowane —
- strony, których źródło faktycznie się zmieniło, zostają oflagowane —
patrz niżej
- **cytaty, których nie ma już w źródle**, na które się powołują, zostają
- cytaty, których nie ma już w źródle, na które się powołują, zostają
oflagowane
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`
@ -318,8 +315,7 @@ znalezisk — agent czyta ten raport, a potem wykonuje części wymagające
osądu (supersesja, niejednoznaczne sieroty, wpisy do księgi błędów oraz
decyzja, co naprawić, a co oddać tobie). 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`.
synchronizacji. Skill: `.agents/skills/ckb-lint/SKILL.md`.
### Zaczynanie od zera: reset do czystego szablonu
@ -367,8 +363,7 @@ Jedna celowa osobliwość: w odróżnieniu od każdego innego skilla ten **nie**
zapisuje notatki sesji w `workload/` — byłby to pierwszy wpis w katalogu,
który właśnie opróżnił. Informuje o tym w raporcie.
Zaimplementowane przez skill `ckb-reset` —
`.agents/skills/ckb-reset/SKILL.md`.
Skill: `.agents/skills/ckb-reset/SKILL.md`.
---
@ -421,8 +416,7 @@ 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`.
Skill: `.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ś
@ -541,8 +535,7 @@ 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`.
kopia robocza projektu szablonu. Skill: `.agents/skills/ckb-upgrade/SKILL.md`.
---
@ -556,20 +549,21 @@ Po prostu zapytaj, zwykłym językiem:
Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony. Jeśli
istnieje pasujący zakres projektu pod `wiki/projects/`, przeszukuje najpierw
ten zakres. Potem sprawdza jednolinijkowe pola `tldr`, w razie potrzeby
uruchamia dokładne wyszukiwanie lokalne dla literalnych tokenów, rozszerza
kontekst wokół dopasowanych sekcji, przechodzi po grafie wiedzy w poszukiwaniu
powiązanych faktów i sięga do `linked/`/`libs/`, jeśli lokalna wiki nic nie ma.
ten zakres. Potem uruchamia `retrieve_candidates.py`, który zbiera sygnały dokładnych
dopasowań, `tldr`, zakresu projektu, grafu i zaufania w jeden połączony
ranking, rozszerza kontekst wokół dopasowanych sekcji, 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.
Dwie rzeczy warte wiedzenia jako użytkownik:
Dwa szczegóły mają znaczenie dla użytkownika:
- **Przeszukuje też `raw/inbox/`.** Coś, co wrzuciłeś dziś rano i czego jeszcze
- Przeszukuje też `raw/inbox/`. Coś, co wrzuciłeś dziś rano i czego jeszcze
nie zingestowałeś, nadal może odpowiedzieć na twoje pytanie. Agent powie ci,
kiedy odpowiedź pochodzi z niezingestowanego materiału, co jednocześnie
sygnalizuje, że „Ingest" jest zaległy.
- **Odpowiedzi noszą własne zastrzeżenia.** Jeśli strona stojąca za odpowiedzią
- Odpowiedzi noszą własne zastrzeżenia. Jeśli strona stojąca za odpowiedzią
przekroczyła okno świeżości, ma niską pewność albo została przeczytana z
zapisanego indeksu konektora zamiast z żywego źródła, odpowiedź mówi o tym
obok danego twierdzenia. Jeśli dwie strony są ze sobą sprzeczne, a żadna nie
@ -722,8 +716,7 @@ ponownie w każdej chwili, gdy źródło się zmieni — odświeża istniejące
wpisy w miejscu, zamiast je duplikować, i nigdy nie usuwa strony dla
dokumentu, który zniknął ze źródła (zamiast tego oflagowuje ją, żeby
kolejny przebieg „Lint” zarchiwizował ją naturalnie). Zaimplementowane
przez skill `ckb-index-external` —
`.agents/skills/ckb-index-external/SKILL.md`.
Skill: `.agents/skills/ckb-index-external/SKILL.md`.
**Kto może go budować i gdzie jest współdzielony.** Domyślnie nikt nie ma
dostępu do zapisu w źródle typu konektor, dopóki tego nie zadeklaruje — to
@ -816,17 +809,32 @@ na stronie generowanej, zostanie nadpisane.
| `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. |
| `LICENSE`, `VERSION`, `README*`, `docs/`, `tests/`, `ckb.yaml` | 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. |
---
### Gdzie leżą własne decyzje szablonu
`docs/decisions/` przechowuje zapisy projektowe szablonu (D-0001, D-0002…) w
tym samym formacie co `wiki/decisions/`, ale jako część warstwy szablonu:
skille i dokumentacja się na nie powołują, więc muszą przetrwać `ckb-reset` i
podróżować z `ckb-upgrade`. Decyzje twojej KB nadal trafiają do
`wiki/decisions/` przez „record a decision” — nigdy tutaj.
### Sprawdzanie wydania szablonu
`tests/smoke.sh` uruchamia deterministyczne skrypty (`lint_report.py`,
`retrieve_candidates.py`) na bazie-fixture w `tests/fixtures/` i porównuje
wynik z `tests/expected/`. Uruchom go przed scaleniem czegokolwiek do `test`
lub `main`; z `--update` po zamierzonej zmianie wyjścia skryptów.
## 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` |
| „Pull the ckb repo into \<folder\> and set up the wiki” | Klonuje repozytorium szablonu do katalogu roboczego, a potem zakłada z niego pustą KB | `ckb-init` |
| „Ingest” / „Sync the wiki” / „Update the wiki” | Przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` | `ckb-ingest` |
| „Ingest” / „Update the wiki” | Przetwarza `raw/inbox/` na ustrukturyzowane strony `wiki/` | `ckb-ingest` |
| „Zapisz decyzję: ...” / „zdecydowaliśmy ...” | Zapisuje numerowany rekord decyzji pod `wiki/decisions/` | `ckb-decide` |
| „Co zdecydowaliśmy w sprawie X” / „kto zdecydował X” / „co jest otwarte” | Odpowiada z zapisów decyzji, z autorem, datą i statusem | `ckb-decide` |
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |

View file

@ -5,8 +5,8 @@
How to add [OpenSpec](https://openspec.dev) to a Cascade KB that documents
software you're building, and how it fits alongside the wiki.
This is a human guide. The agent's own rules live in the `software` module —
[.agents/modules/software/](.agents/modules/software/README.md) — which must be
This is a human guide. The agent's own rules live in the `software` module -
[.agents/modules/software/](../.agents/modules/software/README.md) - which must be
installed before any of this applies. Say **"install the software module"**.
---
@ -31,7 +31,7 @@ them apart:
| Question | Where it lives | Who writes it |
|---|---|---|
| What *is* the code? | `wiki/entities/` — `repository` and `component` pages | `ckb-code-map` |
| What *is* the code? | `wiki/entities/` - `repository` and `component` pages | `ckb-code-map` |
| What *should* it do? | `openspec/specs/` | `ckb-spec` + OpenSpec |
| What did we *choose*, and why? | `wiki/decisions/` | `ckb-decide` |
@ -40,7 +40,7 @@ proposal states what should become true next. You write the spec before the
code, the agent implements against it, and the archived change becomes part of
the permanent record.
If something doesn't constrain future behaviour, it isn't a spec — it's a
If something doesn't constrain future behaviour, it isn't a spec - it's a
decision. Say "record a decision" instead.
## 2. Read this before you run `openspec init`
@ -54,7 +54,7 @@ this repository both of those are load-bearing:
- `.claude/skills` is a **symlink** to `.agents/skills`. Anything OpenSpec writes
there lands in your KB's own skill set.
- `CLAUDE.md` is a **symlink** to `AGENTS.md` — the KB's system prompt. They are
- `CLAUDE.md` is a **symlink** to `AGENTS.md` - the KB's system prompt. They are
one file, so a marker block written to "both" is written twice to the same
place.
@ -87,13 +87,13 @@ generated instruction files.
**Uninstalling from a repo** means removing its `openspec/` directory, its
generated tool files, and the OpenSpec marker blocks from that repo's
`AGENTS.md` / `CLAUDE.md` by hand — the CLI doesn't unwind those for you.
`AGENTS.md` / `CLAUDE.md` by hand - the CLI doesn't unwind those for you.
## 4. The two spec levels
Specs live in two places on purpose.
**KB root — `openspec/`** — cross-cutting capabilities that span several `src/`
**KB root - `openspec/`** - cross-cutting capabilities that span several `src/`
repos. The *what* and *why* that no single repo owns.
This layer is managed by the `ckb-spec` skill, **not** by the OpenSpec CLI.
@ -101,7 +101,7 @@ There's no code beneath it and no repo for it to govern, so OpenSpec's
repo-shaped workflow doesn't apply. It's tracked in the KB's git history, like
every other piece of knowledge here.
**Per repo — `src/<repo>/openspec/`** — how that repo implements those
**Per repo - `src/<repo>/openspec/`** - how that repo implements those
capabilities. The *how*. This is OpenSpec's native case: managed by the CLI and
its own instructions, travelling with the code and riding along in that repo's
pull requests.
@ -124,7 +124,7 @@ From inside a repo that's been initialized, the loop is
Useful alongside: `openspec list`, `openspec status`, `openspec view` (an
interactive dashboard).
For the KB-root layer there's no CLI — just say **"write a cross-cutting spec
For the KB-root layer there's no CLI - just say **"write a cross-cutting spec
for X"** and `ckb-spec` handles it.
## 6. How specs reach the wiki
@ -134,7 +134,7 @@ a parallel universe next to your knowledge base.
**Archived change → decision record.** An applied-and-archived change is a
decision that was made and acted on. The agent *offers* to record it under
`wiki/decisions/` — the proposal's reasoning becomes Context and Rationale, the
`wiki/decisions/` - the proposal's reasoning becomes Context and Rationale, the
delta becomes the Decision, rejected options become Alternatives considered.
It offers rather than doing it automatically, deliberately. Not every routine
@ -144,7 +144,7 @@ them stops being worth reading.
**Spec → entity page.** Current KB-root specs surface in `wiki/entities/` as thin
`type: spec` pages, so questions like "what is this supposed to do?" get answered
from the index without opening the spec tree. The spec file stays the source of
truth — the wiki page is a pointer, not a copy.
truth - the wiki page is a pointer, not a copy.
**Level → level.** Root specs and repo specs link to each other (§7).
@ -162,11 +162,11 @@ rather than a silent second source of truth.
Say **"sync the specs"** (or run `lint`) and you get four checks:
1. Root specs with no implementer — *specified, but nobody's building it.*
2. Repo specs whose parent is missing or archived — *building against something
1. Root specs with no implementer - *specified, but nobody's building it.*
2. Repo specs whose parent is missing or archived - *building against something
that's no longer true.*
3. One-sided links, either direction.
4. Root specs older than the mapped commit of every repo implementing them —
4. Root specs older than the mapped commit of every repo implementing them -
*possible drift, worth a look.*
None of these are auto-fixed. Each is a statement about intent, and only you know
@ -194,9 +194,9 @@ edit a repo's OpenSpec files to match this KB's conventions.
- [OpenSpec documentation](https://openspec.dev/docs/installation) ·
[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) ·
[@fission-ai/openspec on npm](https://www.npmjs.com/package/@fission-ai/openspec)
- Design records: [D-0001](wiki/decisions/0001-opt-in-file-based-kb-modules.md),
[D-0002](wiki/decisions/0002-software-module-design.md)
- Design records: [D-0001](decisions/0001-opt-in-file-based-kb-modules.md),
[D-0002](decisions/0002-software-module-design.md)
---
*Licensed under the Apache License, Version 2.0 — see [LICENSE](LICENSE).*
*Licensed under the Apache License, Version 2.0 - see [LICENSE](../LICENSE).*

View file

@ -6,7 +6,7 @@ Jak dodać [OpenSpec](https://openspec.dev) do Cascade KB, które dokumentuje
tworzone przez Ciebie oprogramowanie, i jak to współgra z wiki.
To przewodnik dla człowieka. Zasady dla samego agenta są w module `software` —
[.agents/modules/software/](.agents/modules/software/README.md) — który musi być
[.agents/modules/software/](../.agents/modules/software/README.md) — który musi być
zainstalowany, zanim cokolwiek z poniższych zacznie obowiązywać. Powiedz:
**„zainstaluj moduł software”**.
@ -201,9 +201,9 @@ bazy.
- [Dokumentacja OpenSpec](https://openspec.dev/docs/installation) ·
[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) ·
[@fission-ai/openspec na npm](https://www.npmjs.com/package/@fission-ai/openspec)
- Rekordy projektowe: [D-0001](wiki/decisions/0001-opt-in-file-based-kb-modules.md),
[D-0002](wiki/decisions/0002-software-module-design.md)
- Rekordy projektowe: [D-0001](decisions/0001-opt-in-file-based-kb-modules.md),
[D-0002](decisions/0002-software-module-design.md)
---
*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](LICENSE).*
*Udostępniane na licencji Apache License 2.0 — zobacz [LICENSE](../LICENSE).*

View file

@ -0,0 +1,78 @@
---
type: decision
tldr: Optional KB capabilities ship as file-based modules under `.agents/modules/<name>/`, installed into the KB on request, rather than as native Claude Code plugins.
status: accepted
decided_on: 2026-09-20
decided_by: Michał Kopeć
affects: AGENTS.md, .agents/modules/
confidence: 0.9
quality: 0.8
last_updated: 2026-09-20
freshness_window_days: 365
retention: high
---
# D-0001 — Optional KB capabilities ship as file-based modules, not native plugins
**Status:** Accepted · **Decided:** 2026-09-20 · **Deciders:** Michał Kopeć
## Context
The base KB ships fourteen `ckb-*` skills, all always loaded. Some capabilities
are only useful to *some* knowledge bases — the first concrete case being a KB
that documents software the user is building (see
[[D-0002]] / [D-0002](/docs/decisions/0002-software-module-design.md)). Adding
those skills unconditionally would grow the always-loaded skill-description
budget for every KB, including ones that will never need them.
Three mechanisms were on the table for making a capability opt-in. The KB is
deliberately agent-agnostic: `AGENTS.md` is the source of truth and `CLAUDE.md`
is a symlink to it (git mode `120000`), as is `.claude/skills` → `.agents/skills`.
That symlink arrangement is a confirmed preference, and it means anything written
to `.agents/skills/` is visible to Claude Code for free.
## Decision
Optional capabilities are packaged as **file-based modules** stored in
`.agents/modules/<name>/` and installed into the KB on explicit request. A
module may contribute skills (into `.agents/skills/`), directory scaffold, a
routing block appended to `AGENTS.md`, and `.gitignore` rules. Installation is
recorded in a root manifest listing the installed modules and their config;
uninstalling reverses it.
## Rationale
A module is a property of *the knowledge base*, not of the machine or the agent
reading it. File-based modules travel with a clone, so a cloned KB stays
self-describing, and they work for any agent that reads `AGENTS.md` — not only
Claude Code. Shipping module content outside `.agents/skills/` until install
keeps the always-loaded skill budget flat for KBs that don't opt in.
## Consequences
- A `ckb-module`-style install/uninstall path is needed.
- `ckb-init` should offer modules at bootstrap; `ckb-upgrade` must not delete
module-installed skills it doesn't recognise upstream, and must also upgrade
`.agents/modules/`.
- `ckb-lint` gains validation of the module manifest.
- Module skills are authored so they could *also* be published as a native
Claude Code plugin later without a rewrite — this decision doesn't foreclose
that, it just declines to make it the primary mechanism.
- Because `.claude/skills` is a symlink, an installer writes `.agents/skills/`
only; no duplicate copy to keep in sync.
## Alternatives considered
- **Always-shipped skills that self-gate on a flag** — no install step and
trivially upgradeable, but every skill description stays in context for every
KB regardless of relevance. Rejected: that budget degrades quietly.
- **Native Claude Code plugin** (`.claude-plugin/plugin.json` + marketplace) —
real enable/disable and no file copying, but serves only Claude Code, breaking
the dual-headed `AGENTS.md`/`CLAUDE.md` contract, and installs per-machine
rather than per-KB. Rejected as the primary mechanism, not ruled out as an
additional distribution channel.
## Sources
Chat conversation, 2026-09-20 — design evaluation of a source-code/software KB
mode. See `workload/2026-09-20_summary.md`.

View file

@ -0,0 +1,113 @@
---
type: decision
tldr: The `software` module keeps code as gitignored plain clones in `src/`, runs OpenSpec at both KB-root and per-repo level with a hybrid vendor/depend split, and links the two spec levels with `implements`/`implemented_by`.
status: accepted
decided_on: 2026-09-20
decided_by: Michał Kopeć
affects: /docs/decisions/0001-opt-in-file-based-kb-modules.md, /wiki/index.md
confidence: 0.85
quality: 0.8
last_updated: 2026-09-20
freshness_window_days: 365
retention: high
---
# D-0002 — Design of the opt-in `software` module
**Status:** Accepted · **Decided:** 2026-09-20 · **Deciders:** Michał Kopeć
## Context
Some knowledge bases document software the user is actively building. In that
case the source code lives in `src/`, usually as one or more *independent* git
repositories with their own remotes — a git repo inside a git repo. The user
also wants OpenSpec-driven iterative development available in that mode.
This is the first concrete module under
[[D-0001]] / [D-0001](/docs/decisions/0001-opt-in-file-based-kb-modules.md),
and four sub-questions had to be settled: how code is hosted, where specs live,
whether OpenSpec's own workflow instructions are vendored or depended on, and
how two spec levels avoid becoming two sources of truth.
## Decision
**Code hosting.** `src/<repo>/` holds plain clones, gitignored (`src/*`, as
`libs/*` already is). No submodules. Because the code may be absent from a
fresh clone, each repo also gets a durable `type: repository` entity page in
`wiki/` recording its remote URL, default branch, language, build command,
`src/` path, and owner — that page, not the clone, is the durable artifact.
**`src/` is not a cascade layer.** It is primary evidence, like `raw/archive/`:
`ckb-retrieve` may open and cite it when verifying a claim, but it never answers
"what is entity X", and `ckb-ingest` does not treat code as inbox material.
**Spec location — both levels.** OpenSpec runs at the KB root (cross-cutting
capabilities spanning multiple `src/` repos) *and* inside each `src/<repo>/`
(implementation specs that travel with the code in its own repo).
**Vendoring — hybrid.** The KB-root spec layer is served by a module-owned
skill, because a KB-root `openspec/` is not a normal OpenSpec repo install (no
code beneath it, no single repo it governs) and the module must own instructions
for it regardless. The per-`src`-repo layer delegates to OpenSpec's own native
install and instructions, and the module reports plainly when OpenSpec is
missing rather than substituting its own workflow. The module additionally owns
the bridge in both directions: an archived OpenSpec change becomes a
`wiki/decisions/NNNN-*.md` record, and current specs sync into `type: spec`
entity pages.
**Drift rule.** KB-level specs state *what* and *why* across repos; `src`-level
specs state *how* a given repo implements it. The two are linked by
`implements:` / `implemented_by:` frontmatter, which becomes graph edges.
`ckb-lint` gains checks for KB-level specs with no implementer and `src`-level
specs whose parent was archived or superseded.
## Rationale
Gitignored clones avoid embedded-repo warnings and keep code out of KB history,
while each repo keeps pushing to its own origin; submodules would pin commits
that go stale against daily work in `src/`. Specs at both levels reflect a real
distinction — cross-repo contracts genuinely differ from per-repo implementation
— and the hybrid vendoring split follows from that same distinction rather than
splitting the difference: only the level OpenSpec doesn't natively serve is
owned locally. The `implements`/`implemented_by` link exists specifically so the
two-level arrangement produces a lint signal when the levels disagree, instead
of two silently divergent truths.
## Consequences
- `.gitignore` gains `src/*` rules.
- New frontmatter types `repository`, `component`, `spec`, and optional `repo:`,
`commit:`, `spec_id:`, `implements:`, `implemented_by:` fields — a
`kb_schema_version` bump to `1.5`, additive only.
- Module skills needed: a code-mapping skill (`src/<repo>` → entity pages, with
a recorded commit hash so staleness is detectable) and a KB-root OpenSpec +
bridge skill.
- `ckb-sync-changes` must never `git add` under `src/`, and should report each
`src/` repo's dirty/ahead state separately.
- `ckb-retrieve` gains code as a verification source; `ckb-lint` gains the src
and spec-drift checks; OKF and Starlight exports exclude `src/`.
- The module is unusable at the `src/` level until OpenSpec is installed
separately — it is not on PATH as of this decision.
## Alternatives considered
- **Git submodules for `src/`** — code travels with the KB and is pinned to a
commit, which is genuinely attractive for "what did the wiki describe at that
point". Rejected for submodule friction on every sync and pins going stale.
- **Specs only inside each `src/` repo** — OpenSpec's native case, nothing to
own locally, but no home for contracts spanning several repos.
- **Specs only at KB root** — one place to look, but specs stop travelling with
the code they govern and fall out of the repo's own PR flow.
- **Vendoring OpenSpec's workflow wholesale** — self-contained, works with
nothing installed, tailorable to KB conventions. Rejected: it means
maintaining a fork of an external workflow, and `ckb-upgrade` would have two
upstreams to track.
- **Depending on OpenSpec at both levels** — nothing to maintain, but leaves the
KB-root layer with no instructions at all, since OpenSpec doesn't serve that
case.
## Sources
Chat conversation, 2026-09-20 — design evaluation of a source-code/software KB
mode, including the user's explicit choices on mechanism, code hosting, spec
location, and vendoring. See `workload/2026-09-20_summary.md`.

18
docs/decisions/README.md Normal file
View file

@ -0,0 +1,18 @@
# Template design decisions
Decision records about the **template itself** — why the Cascade KB is shaped
the way it is. They use the same `type: decision` format as `wiki/decisions/`,
but they live here, in the template layer, because:
- `wiki/decisions/` is content: a KB's *own* decisions about its *own*
subject. `ckb-reset` may wipe it, and a fresh `ckb-init` starts it empty.
- Skills, modules and docs cite these records. A template must not depend on
pages the content layer is allowed to delete.
`ckb-upgrade` carries this folder along with the rest of the template layer.
`ckb-decide` never writes here — it is not a place for a KB's project decisions.
| # | Decision |
|---|---|
| [D-0001](0001-opt-in-file-based-kb-modules.md) | Optional capabilities ship as file-based modules under `.agents/modules/`, installed on request |
| [D-0002](0002-software-module-design.md) | The `software` module: gitignored `src/` clones, two OpenSpec spec levels, hybrid vendoring |

31
tests/expected/lint.json Normal file
View file

@ -0,0 +1,31 @@
{
"today": "2026-09-24",
"trees": [
{
"label": "wiki/",
"documents": 14,
"conformance": [],
"freshness": [],
"confidence": [],
"retention": [],
"decisions": [],
"orphans": [],
"graph": [],
"index_log": [],
"evidence": [],
"crux": [],
"hubs": [
[
"entities/atlas-retry-policy",
2
],
[
"entities/maria-nowak",
1
]
]
}
],
"sources": [],
"findings": 0
}

View file

@ -0,0 +1,230 @@
{
"query": "how many times does Atlas retry a failed batch",
"k": 10,
"literal_tokens": [],
"scope_page": "wiki/projects/atlas.md",
"inbox_hits": [],
"empty_graph": false,
"candidates": [
{
"path": "wiki/entities/atlas-retry-policy.md",
"score": 0.3432,
"ranks": {
"exact": 1,
"tldr": 1,
"scope": 1,
"indegree": 1,
"trust": 2
},
"title": "Atlas retry policy",
"type": "concept",
"tldr": "Atlas retries a failed batch three times with exponential backoff, then parks it in the dead-letter queue.",
"last_updated": "2026-09-01",
"stale": false,
"confidence": "0.9",
"quality": "0.8",
"superseded_by": null,
"sources": [
"raw/archive/2026-09-01/kickoff-notes.md"
],
"corroborated_by": [
"raw/archive/2026-09-01/kickoff-notes.md"
],
"from_inbox": false
},
{
"path": "wiki/entities/maria-nowak.md",
"score": 0.2838,
"ranks": {
"exact": 7,
"tldr": 3,
"scope": 2,
"indegree": 2,
"trust": 3
},
"title": "Maria Nowak",
"type": "person",
"tldr": "Platform lead on the Atlas migration; explained the retry policy at kickoff.",
"last_updated": "2026-09-01",
"stale": false,
"confidence": "0.8",
"quality": "0.8",
"superseded_by": null,
"sources": [
"raw/archive/2026-09-01/kickoff-notes.md"
],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/decisions/0001-three-retries-then-dlq.md",
"score": 0.1939,
"ranks": {
"exact": 2,
"tldr": 2,
"trust": 1
},
"title": "D-0001 — Three retries then dead-letter",
"type": "decision",
"tldr": "Failed Atlas batches retry three times with exponential backoff, then go to the dead-letter queue.",
"last_updated": "2026-09-01",
"stale": false,
"confidence": "0.9",
"quality": "0.8",
"superseded_by": null,
"sources": [
"raw/archive/2026-09-01/kickoff-notes.md"
],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/projects/atlas.md",
"score": 0.147,
"ranks": {
"exact": 8,
"tldr": 4,
"trust": 5
},
"title": "Atlas",
"type": "project",
"tldr": "Query scope for the Atlas migration — retry policy, kickoff notes, platform team.",
"last_updated": "2026-09-01",
"stale": false,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/overview.md",
"score": 0.1381,
"ranks": {
"exact": 10,
"tldr": 5,
"trust": 4
},
"title": "Overview",
"type": "overview",
"tldr": "Fixture KB covering the Atlas migration kickoff — one concept, one person, one decision.",
"last_updated": "2026-09-01",
"stale": false,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/entities/index.md",
"score": 0.0714,
"ranks": {
"exact": 4
},
"title": null,
"type": null,
"tldr": null,
"last_updated": null,
"stale": null,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/decisions/index.md",
"score": 0.0667,
"ranks": {
"exact": 5
},
"title": null,
"type": null,
"tldr": null,
"last_updated": null,
"stale": null,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/index.md",
"score": 0.0625,
"ranks": {
"exact": 6
},
"title": null,
"type": null,
"tldr": null,
"last_updated": null,
"stale": null,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/log.md",
"score": 0.0526,
"ranks": {
"exact": 9
},
"title": null,
"type": null,
"tldr": null,
"last_updated": null,
"stale": null,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/decisions/log.md",
"score": 0.0476,
"ranks": {
"exact": 11
},
"title": null,
"type": null,
"tldr": null,
"last_updated": null,
"stale": null,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
},
{
"path": "wiki/projects/index.md",
"score": 0.0455,
"ranks": {
"exact": 12
},
"title": null,
"type": null,
"tldr": null,
"last_updated": null,
"stale": null,
"confidence": null,
"quality": null,
"superseded_by": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
}
]
}

View file

@ -0,0 +1,13 @@
# Kickoff notes — Atlas migration
Attendees: Maria Nowak (platform lead), Jan Kowalski.
## Access
FDEs need the VDI *and* a Jira account before day one; the VDI request
alone takes ten working days.
## Decisions
Maria explained the retry policy: Atlas retries a failed batch three times
with exponential backoff, then parks it in the dead-letter queue.

View file

@ -0,0 +1,23 @@
---
type: decision
tldr: Failed Atlas batches retry three times with exponential backoff, then go to the dead-letter queue.
status: accepted
decided_on: 2026-09-01
decided_by: Maria Nowak
affects: /wiki/entities/atlas-retry-policy.md
confidence: 0.9
quality: 0.8
last_updated: 2026-09-01
freshness_window_days: 365
retention: high
---
# D-0001 — Three retries then dead-letter
## Decision
Retry three times with exponential backoff, then park in the DLQ.
## Sources
- `raw/archive/2026-09-01/kickoff-notes.md` — sha256:a97984a4 (checked 2026-09-01)

View file

@ -0,0 +1,3 @@
# Decisions
* **[Accepted]** [D-0001 — Three retries then dead-letter](0001-three-retries-then-dlq.md) — Failed Atlas batches retry three times with backoff, then dead-letter.

View file

@ -0,0 +1,7 @@
# Decisions Change Log
## [2026-09-01 10:05] - CREATE
- **File Affected:** `wiki/decisions/0001-three-retries-then-dlq.md`
- **Description:** Recorded retry policy decision from kickoff.
- **Source:** ckb-decide
---

View file

@ -0,0 +1,31 @@
---
type: concept
tldr: Atlas retries a failed batch three times with exponential backoff, then parks it in the dead-letter queue.
confidence: 0.9
quality: 0.8
last_updated: 2026-09-01
freshness_window_days: 365
retention: high
source_fingerprint: sha256:a97984a4
source_checked: 2026-09-01
---
# Atlas retry policy
Atlas retries a failed batch three times with exponential backoff before
parking it in the dead-letter queue. Explained by [[entities/maria-nowak]] /
[Maria Nowak](/wiki/entities/maria-nowak.md) at kickoff.
## Sources
- `raw/archive/2026-09-01/kickoff-notes.md` — sha256:a97984a4 (checked 2026-09-01)
## Crux
> Atlas retries a failed batch three times
> with exponential backoff, then parks it in the dead-letter queue.
— `raw/archive/2026-09-01/kickoff-notes.md`, under "Decisions"
## Notes
<!-- Yours. Never rewritten by any skill. -->

View file

@ -0,0 +1,4 @@
# Entities
- [Atlas retry policy](atlas-retry-policy.md) — Atlas retries a failed batch three times with exponential backoff, then dead-letters it.
- [Maria Nowak](maria-nowak.md) — Platform lead on the Atlas migration.

View file

@ -0,0 +1,25 @@
---
type: person
tldr: Platform lead on the Atlas migration; explained the retry policy at kickoff.
confidence: 0.8
quality: 0.8
last_updated: 2026-09-01
freshness_window_days: 365
retention: medium
source_fingerprint: sha256:a97984a4
source_checked: 2026-09-01
---
# Maria Nowak
Platform lead. Explained the [[entities/atlas-retry-policy]] /
[Atlas retry policy](/wiki/entities/atlas-retry-policy.md) at kickoff.
## Sources
- `raw/archive/2026-09-01/kickoff-notes.md` — sha256:a97984a4 (checked 2026-09-01)
## Crux
> Maria explained the retry policy
— `raw/archive/2026-09-01/kickoff-notes.md`, under "Decisions"

View file

@ -0,0 +1,10 @@
---
type: error-book
tldr: Known ingest/lint errors for the fixture KB.
last_updated: 2026-09-01
---
# Error Book
| Date | Error | Root Cause | Fix / Constraint |
|------|-------|-----------|------------------|

View file

@ -0,0 +1,5 @@
{"version": 1, "last_updated": "2026-09-01", "edges": [
{"from": "entities/maria-nowak", "to": "entities/atlas-retry-policy", "type": "has_expertise_in", "source": "raw/archive/2026-09-01/kickoff-notes.md"},
{"from": "decisions/0001-three-retries-then-dlq", "to": "entities/atlas-retry-policy", "type": "affects"},
{"from": "decisions/0001-three-retries-then-dlq", "to": "entities/maria-nowak", "type": "decided_by"}
]}

View file

@ -0,0 +1,3 @@
# Graph
Edge list in `edges.json`.

21
tests/fixtures/minimal-kb/wiki/index.md vendored Normal file
View file

@ -0,0 +1,21 @@
---
kb_schema_version: "1.5"
---
# Knowledge Base Index
| Page | Description | Use when |
|------|-------------|----------|
| [Overview](overview.md) | What this KB covers | Getting started |
| [Log](log.md) | Root change log | Reviewing changes |
| [Error Book](error-book.md) | Known ingest/lint errors | Debugging |
| [Projects](projects/index.md) | Query scopes | Narrowing search |
| [Query Gaps](query-gaps.md) | Unanswered questions | Tracking gaps |
| [Decisions](decisions/index.md) | Decision records | Why/who/when |
| [Entities](entities/index.md) | Entity pages | Looking up a person or concept |
| [Graph](graph/index.md) | Relationships | What depends on what |
## Entity Pages
- [Atlas retry policy](entities/atlas-retry-policy.md) — how Atlas retries failed batches
- [Maria Nowak](entities/maria-nowak.md) — platform lead on Atlas

17
tests/fixtures/minimal-kb/wiki/log.md vendored Normal file
View file

@ -0,0 +1,17 @@
# Wiki Change Log
## [2026-09-01 10:00] - CREATE
- **File Affected:** `wiki/entities/atlas-retry-policy.md`
- **Description:** Concept page from kickoff notes.
- **Source:** ckb-ingest
---
## [2026-09-01 10:00] - CREATE
- **File Affected:** `wiki/entities/maria-nowak.md`
- **Description:** Person page from kickoff notes.
- **Source:** ckb-ingest
---
## [2026-09-01 10:05] - POINTER
- **File Affected:** `wiki/decisions/log.md`
- **Description:** Decision D-0001 recorded; see decisions log.
- **Source:** ckb-decide
---

View file

@ -0,0 +1,10 @@
---
type: overview
tldr: Fixture KB covering the Atlas migration kickoff — one concept, one person, one decision.
last_updated: 2026-09-01
---
# Overview
Fixture knowledge base for the template's smoke test. Covers the Atlas
migration kickoff only.

View file

@ -0,0 +1,12 @@
---
type: project
tldr: Query scope for the Atlas migration — retry policy, kickoff notes, platform team.
last_updated: 2026-09-01
---
# Atlas
Search first:
- [[entities/atlas-retry-policy]] / [Atlas retry policy](/wiki/entities/atlas-retry-policy.md)
- [[entities/maria-nowak]] / [Maria Nowak](/wiki/entities/maria-nowak.md)
- `raw/archive/2026-09-01/kickoff-notes.md`

View file

@ -0,0 +1,3 @@
# Projects
- [Atlas](atlas.md) — Atlas migration scope

View file

@ -0,0 +1,11 @@
---
type: log
tldr: Questions the fixture KB could not answer yet.
last_updated: 2026-09-01
---
# Query Gaps
## Open
## Resolved

31
tests/smoke.sh Executable file
View file

@ -0,0 +1,31 @@
#!/usr/bin/env bash
# Template smoke test: run the deterministic scripts against the fixture KB and
# compare with the golden output. Exit non-zero on any drift.
#
# tests/smoke.sh # check
# tests/smoke.sh --update # regenerate the golden files after an intended change
set -euo pipefail
cd "$(dirname "$0")/.."
FIX=tests/fixtures/minimal-kb
TODAY=2026-09-24
LINT=.agents/skills/ckb-lint/scripts/lint_report.py
RETR=.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
( cd "$FIX" && python3 "../../../$LINT" --json --today "$TODAY" ) > "$TMP/lint.json"
python3 "$RETR" "how many times does Atlas retry a failed batch" --root "$FIX" --today "$TODAY" --json > "$TMP/retrieve.json"
if [[ "${1:-}" == "--update" ]]; then
cp "$TMP/lint.json" tests/expected/lint.json
cp "$TMP/retrieve.json" tests/expected/retrieve.json
echo "golden files updated"; exit 0
fi
fail=0
for f in lint retrieve; do
if ! diff -u "tests/expected/$f.json" "$TMP/$f.json"; then echo "DRIFT: $f"; fail=1; fi
done
top=$(python3 -c "import json;print(json.load(open('$TMP/retrieve.json'))['candidates'][0]['path'])")
[[ "$top" == "wiki/entities/atlas-retry-policy.md" ]] || { echo "retrieve: expected atlas-retry-policy first, got $top"; fail=1; }
[[ $fail -eq 0 ]] && echo "smoke: OK"
exit $fail

View file

@ -13,22 +13,25 @@ If a proposed edge doesn't answer one of these, it doesn't belong in the graph
| Verb | Question it answers | Written by |
|---|---|---|
| `part_of` | Where does this live? What is it a piece of? | `ckb-ingest`, `ckb-code-map` |
| `part_of` | Where does this live? What is it a piece of? | `ckb-ingest` |
| `uses` | What does this reach for at runtime? | `ckb-ingest`, `ckb-index-external` |
| `depends_on` | What breaks if I change this? | `ckb-ingest`, `ckb-code-map` |
| `depends_on` | What breaks if I change this? | `ckb-ingest` |
| `produces` | Where does this output come from? | `ckb-ingest` |
| `configures` | What changes this thing's behaviour? | `ckb-ingest` |
| `validates` | What checks, tests, or judges this? | `ckb-ingest` |
| `implements` | What contract must this honour? | `ckb-ingest`, `ckb-spec` |
| `implements` | What contract must this honour? | `ckb-ingest` |
| `caused` | Why did this happen? | `ckb-ingest` |
| `contradicts` | What disagrees with this, unresolved? | `ckb-ingest`, `ckb-lint` |
| `supersedes` | What replaced this, and what did it replace? | `ckb-ingest`, `ckb-decide`, `ckb-lint` |
| `decided_by` | Who made this call? | `ckb-decide` |
| `affects` | What does this decision constrain? | `ckb-decide` |
| `has_expertise_in` | Who can answer questions on this? | `ckb-ingest` |
| `owns` | Who is responsible for this? | `ckb-ingest`, `ckb-code-map` |
| `owns` | Who is responsible for this? | `ckb-ingest` |
| `mentioned_in` | Which source document discusses this? | `ckb-index-external` (lib indexes only) |
An installed module may write these same verbs from its own skills; its
README says which. The vocabulary itself does not change on install.
Conventions:
* **One direction per relationship.** `part_of`, `supersedes`, `depends_on`,

View file

@ -16,4 +16,18 @@ Each entry uses this format:
Changes to pages under `wiki/decisions/` live in `wiki/decisions/log.md`
instead, per the Recursive Index & Log Convention.
*(No entries yet.)*
## [2026-09-24 20:10] - UPDATE
- **File Affected:** `wiki/overview.md`
- **Description:** Rewritten as a content overview scaffold (scope, topics, sources, navigation); schema description removed — it lives in AGENTS.md and docs/CHANGELOG.md.
- **Source:** Concept review, chat conversation.
---
## [2026-09-24 20:10] - UPDATE
- **File Affected:** `wiki/graph/index.md`
- **Description:** "Written by" column now names base skills only; module skills documented in the module README instead.
- **Source:** Concept review, chat conversation.
---
## [2026-09-24 20:10] - UPDATE
- **File Affected:** `wiki/query-gaps.md`
- **Description:** Dropped freshness_window_days/retention from the scaffold page so a clean template no longer reports rot.
- **Source:** Concept review, chat conversation.
---

View file

@ -1,80 +1,32 @@
---
type: overview
tldr: High-level map of the cascade knowledge base's directory structure, frontmatter schema, and layering rules.
last_updated: 2026-09-21
tldr: What this knowledge base is about, who it is for, and where its knowledge comes from — filled in by the first ingest.
last_updated: 2026-09-24
---
# Knowledge Base Overview
This is the local (mutable) layer of a cascade knowledge base.
It sits above read-only upstream KBs in `../linked/` and `../libs/`.
*(Empty template. `ckb-ingest` fills the sections below from the material it
processes and keeps them current. The KB's rules and page schema are **not**
described here — they live in `AGENTS.md` and `docs/CHANGELOG.md`, and
duplicating them on a content page only lets the copies drift.)*
## Cascade Priority
1. **wiki/** (local) — highest priority, agent-managed
2. **linked/\<name\>/** (symlinked) — read-only upstream source of truth
3. **libs/\<name\>/** (git-managed) — read-only external KBs
## Scope
When the same entity exists in multiple layers, the local version wins.
What this KB covers and what it deliberately does not.
## Directory Structure
```
.
├── libs/ # Git-managed external KBs (read-only, gitignored)
├── linked/ # Symlinks to upstream KBs (read-only)
├── outputs/ # Generated artifacts from the wiki
├── raw/ # User-provided source material
│ └── inbox/ # Drop zone for unprocessed material
├── tmp/ # Temporary files, caches (gitignored)
├── wiki/ # Local structured wiki (agent-managed)
│ ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
│ ├── projects/ # Optional local query scopes
│ ├── decisions/ # Numbered, append-only decision records
│ ├── entities/ # Typed entity pages
│ └── graph/ # Edge lists and relationship data
└── workload/ # Summaries of discussions and decisions
```
## Main topics
## Page Frontmatter
Every wiki page carries YAML frontmatter with a required `type` field, plus
optional `resource`, `tldr`, `confidence`, `quality`, `supersedes`,
`freshness_window_days`, `retention`, `source_fingerprint`, and
`source_checked`. Pages with `type: decision` add
`status`, `decided_on`, `decided_by`, `affects`, and `review_on`. `wiki/index.md` additionally
declares `kb_schema_version` for the bundle as a whole.
See AGENTS.md for the full schema.
The handful of entities, projects, and decisions a newcomer should know
exist, each linked — `[[entities/...]]` / `[…](/wiki/entities/….md)`.
## Reserved Page Sections
Three `##` headings mean the same thing on every page in every layer:
## Sources of knowledge
* **`## Sources`** — one bullet per source, each carrying a fingerprint
(`sha256:` for a local file, `etag:`/`mtime:` for a connector item) and the
date it was last checked. This is what makes drift detectable mechanically
rather than by calendar.
* **`## Crux`** — verbatim excerpts from those sources, attributed to the
bullet they came from. Evidence, never paraphrase: a quote either still
matches its source or it doesn't.
* **`## Notes`** — human-authored and **protected**. No skill rewrites,
reflows, or drops it; regeneration preserves it byte-for-byte.
Where the material comes from: which `raw/` drops, which `linked/` KBs,
which connector-backed `libs/`. One line each.
## Decision Records
`wiki/decisions/` holds one numbered page per decision (`NNNN-slug.md`),
recording what was decided, by whom, on what date, why, and which earlier
decision it supersedes or reverses. Decision pages are **append-only**: the
substance is never rewritten to match a later change of mind — a new decision
supersedes the old one and both stay on the record, so "why is it like this?"
keeps its original answer. Decision-specific frontmatter is `status`,
`decided_on`, `decided_by`, and optionally `affects` and `review_on`; the
existing `supersedes`/`superseded_by` pair carries the history. The
`ckb-decide` skill records them and answers questions about them.
## How to navigate
## Recursive Indexes
`entities/`, `graph/`, `decisions/`, and optional topic folders such as
`projects/` each carry their own `index.md` so navigation stays lazy — read `wiki/index.md`
first, then only descend into a subdirectory index if its contents are
relevant to the current task.
## Local-First Retrieval Aids
Project scope pages in `wiki/projects/` can group related sources so a query
starts narrow before falling back to the full cascade. `wiki/query-gaps.md`
records questions the wiki could not answer yet, turning failed searches into
small ingest targets.
Start at [index.md](index.md) and follow the **Use when** column; project
scopes in [projects/](projects/index.md) narrow a search; decisions have
their own [index](decisions/index.md).

View file

@ -4,8 +4,6 @@ tldr: Local queue of questions the wiki could not answer yet, used to drive dema
confidence: 1.0
quality: 0.8
last_updated: 2026-09-20
freshness_window_days: 30
retention: medium
---
# Query Gaps

View file

@ -0,0 +1,87 @@
## Skill context-budget optimisation
Audited all 16 `ckb-*` skills for always-loaded and per-invocation context cost,
then applied five changes:
1. **Descriptions rewritten** to routing-hint length (1,925w -> 840w). The
"Distinct from X..." disambiguation prose was removed; it duplicated
AGENTS.md section 3, which is also always loaded.
2. **AGENTS.md section 3 prose trimmed** — the routing table stays; the bullets
below it now cover only genuinely ambiguous pairs plus the release-channel
and reset-safety facts that live nowhere else. 1,611w -> 1,472w.
3. **`## Trigger phrases` sections deleted** from all 15 skills that had one
(1,190w). Routing has already happened by the time a body loads.
4. **`## Purpose` sections collapsed** to a few lines each, preserving every
write-scope constraint (which paths a skill may and may not touch).
5. **`## Edge cases` extracted** to `<skill>/references/edge-cases.md` in all 16
skills (4,888w moved out of line), with a pointer stub in SKILL.md. First use
of progressive disclosure in this skill set.
Net: always-loaded ~6.1k -> ~3.9k tokens; SKILL.md bodies 36,242w -> 29,085w.
No behaviour changed — every procedural step is intact. `lint --quick` clean.
Not done, flagged to user: VERSION/CHANGELOG bump for this template-layer change.
## Concept review of the KB project
Read AGENTS.md, README/MANUAL/CHANGELOG/OPENSPEC headings and key sections,
the whole wiki/ scaffold, .gitignore, the software module manifest, the lint
script's check list, and the ingest/retrieve/reset/upgrade procedures, then
cross-checked them against each other. Findings delivered in chat: Rule B vs
decisions/log.md, template files linking wiped D-0001/D-0002, module skills
named in the base graph vocabulary, ckb-retrieve "read-only" vs its Step 7
query-gap write, README "Automation Hooks" describing nothing wired, overview.md
as a lagging third copy of the schema, query-gaps.md scaffold rotting on a
30-day window, hand-executed rank fusion in ckb-retrieve. No files changed.
## Review findings applied (template 1.9.0 -> 1.10.0)
- AGENTS.md: Rule B names the decisions-log exception (one home log + POINTER);
"Four" -> "Three" reserved sections; directory contract adds ckb.yaml, docs/,
tests/; "Sync the wiki" removed as an ingest trigger everywhere (AGENTS,
ckb-ingest description, README/MANUAL EN+PL).
- docs/: MANUAL*, CHANGELOG*, OPENSPEC* moved out of the root (git mv);
D-0001/D-0002 restored from restore-point 0c06cb6 into docs/decisions/ with a
README; all six referrers repointed (module.yaml, ckb-module, OPENSPEC EN/PL,
module README, ckb-spec). ckb-init/ckb-upgrade/ckb-reset file lists updated.
- ckb-retrieve: Purpose now "read-only with one exception" (query-gaps write);
Steps 2-4 rewritten around scripts/retrieve_candidates.py (RRF over exact,
tldr, scope, graph, in-degree, trust lists; folds cited archive files into
the citing page as corroboration). Judgment steps kept in prose.
- wiki scaffold: graph/index.md names base skills only (module README lists
its verbs); query-gaps.md lost its 30-day freshness window; overview.md is
now a content-overview scaffold, not a schema copy. All three logged in
wiki/log.md.
- tests/: fixtures/minimal-kb (2 entities, 1 decision, scope page, edges,
archived source with matching sha256), expected/*.json, smoke.sh (lint --json
+ retrieve --json diffed against golden; asserts top candidate). Passes.
- ckb.yaml written (template: main, kb_modules: []).
- README EN/PL: "Automation Hooks" -> "Session Conventions" (honest about no
hooks); Change Log and Recursive Index sections state the decisions-log rule;
hybrid retrieval names the script; tree shows ckb.yaml/docs/tests; links
point into docs/. MANUAL EN/PL: sync phrasing, retrieval paragraph, §7 row,
new sub-sections on docs/decisions and tests/smoke.sh. CHANGELOG EN/PL: 1.10.0
row + docs/ move note in Migrating. VERSION 1.10.0.
- Not done: deleting the empty root .env (auto-mode classifier blocked rm) —
left for the user. Nothing committed.
- Verified: tests/smoke.sh OK, lint --quick clean, no stale root links,
no "Sync the wiki" outside changelog history.
## ghost-writer pass over README, MANUAL, OPENSPEC, CHANGELOG (EN + PL)
Edited in place (git holds the originals). Vocabulary scan was clean; no
"not X but Y"; the dominant tell was em-dash density (~5 per 300 words).
- EN: em dashes in prose -> spaced hyphens, code fences and headings kept
(TOC anchors intact); wrapped dashes rejoined.
- Both languages: the "Implemented as a Claude Code Skill ... rather than
baked into AGENTS.md ..." sentence repeated 5x in README and 7x in MANUAL
collapsed to one intro sentence under Features plus "Skill: <path>."; two
unsourced figures cut (~12K->3.2K tokens, ~20-30 cycles); "This is a
deliberate design choice"/"To celowa decyzja" narration removed; "**Sentence.**"
bold-lead bullets made plain (README connector section, MANUAL x7, CHANGELOG
x5); a "Two things worth knowing" intro that listed three items fixed; the
16-line Tips bullet split into three.
- PL punctuation left as is (the em dash is standard Polish typography, not
an AI tell); content edits mirrored line for line.
Verified: 0 broken links, smoke OK, lint --quick clean.