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:
parent
6c0d70976c
commit
7863115b74
74 changed files with 2598 additions and 1629 deletions
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
29
.agents/skills/ckb-decide/references/edge-cases.md
Normal file
29
.agents/skills/ckb-decide/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
25
.agents/skills/ckb-export-okf/references/edge-cases.md
Normal file
25
.agents/skills/ckb-export-okf/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
22
.agents/skills/ckb-export-starlight/references/edge-cases.md
Normal file
22
.agents/skills/ckb-export-starlight/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
79
.agents/skills/ckb-index-external/references/edge-cases.md
Normal file
79
.agents/skills/ckb-index-external/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
26
.agents/skills/ckb-ingest/references/edge-cases.md
Normal file
26
.agents/skills/ckb-ingest/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
36
.agents/skills/ckb-init/references/edge-cases.md
Normal file
36
.agents/skills/ckb-init/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
39
.agents/skills/ckb-lint/references/edge-cases.md
Normal file
39
.agents/skills/ckb-lint/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
21
.agents/skills/ckb-module/references/edge-cases.md
Normal file
21
.agents/skills/ckb-module/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
25
.agents/skills/ckb-onboard-me/references/edge-cases.md
Normal file
25
.agents/skills/ckb-onboard-me/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
22
.agents/skills/ckb-project-summary/references/edge-cases.md
Normal file
22
.agents/skills/ckb-project-summary/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
15
.agents/skills/ckb-quiz/references/edge-cases.md
Normal file
15
.agents/skills/ckb-quiz/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
28
.agents/skills/ckb-reset/references/edge-cases.md
Normal file
28
.agents/skills/ckb-reset/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
53
.agents/skills/ckb-retrieve/references/edge-cases.md
Normal file
53
.agents/skills/ckb-retrieve/references/edge-cases.md
Normal 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>.*
|
||||
352
.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py
Executable file
352
.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py
Executable 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()
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
27
.agents/skills/ckb-sync-changes/references/edge-cases.md
Normal file
27
.agents/skills/ckb-sync-changes/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
33
.agents/skills/ckb-teach-me/references/edge-cases.md
Normal file
33
.agents/skills/ckb-teach-me/references/edge-cases.md
Normal 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>.*
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
75
.agents/skills/ckb-upgrade/references/edge-cases.md
Normal file
75
.agents/skills/ckb-upgrade/references/edge-cases.md
Normal 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>.*
|
||||
54
AGENTS.md
54
AGENTS.md
|
|
@ -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
285
README.md
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
146
README.pl.md
146
README.pl.md
|
|
@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.9.0
|
||||
1.10.0
|
||||
|
|
|
|||
8
ckb.yaml
Normal file
8
ckb.yaml
Normal 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: []
|
||||
|
|
@ -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).
|
||||
|
|
@ -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).
|
||||
|
|
@ -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` |
|
||||
|
|
@ -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` |
|
||||
|
|
@ -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).*
|
||||
|
|
@ -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).*
|
||||
78
docs/decisions/0001-opt-in-file-based-kb-modules.md
Normal file
78
docs/decisions/0001-opt-in-file-based-kb-modules.md
Normal 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`.
|
||||
113
docs/decisions/0002-software-module-design.md
Normal file
113
docs/decisions/0002-software-module-design.md
Normal 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
18
docs/decisions/README.md
Normal 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
31
tests/expected/lint.json
Normal 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
|
||||
}
|
||||
230
tests/expected/retrieve.json
Normal file
230
tests/expected/retrieve.json
Normal 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
|
||||
}
|
||||
]
|
||||
}
|
||||
13
tests/fixtures/minimal-kb/raw/archive/2026-09-01/kickoff-notes.md
vendored
Normal file
13
tests/fixtures/minimal-kb/raw/archive/2026-09-01/kickoff-notes.md
vendored
Normal 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.
|
||||
23
tests/fixtures/minimal-kb/wiki/decisions/0001-three-retries-then-dlq.md
vendored
Normal file
23
tests/fixtures/minimal-kb/wiki/decisions/0001-three-retries-then-dlq.md
vendored
Normal 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)
|
||||
3
tests/fixtures/minimal-kb/wiki/decisions/index.md
vendored
Normal file
3
tests/fixtures/minimal-kb/wiki/decisions/index.md
vendored
Normal 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.
|
||||
7
tests/fixtures/minimal-kb/wiki/decisions/log.md
vendored
Normal file
7
tests/fixtures/minimal-kb/wiki/decisions/log.md
vendored
Normal 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
|
||||
---
|
||||
31
tests/fixtures/minimal-kb/wiki/entities/atlas-retry-policy.md
vendored
Normal file
31
tests/fixtures/minimal-kb/wiki/entities/atlas-retry-policy.md
vendored
Normal 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. -->
|
||||
4
tests/fixtures/minimal-kb/wiki/entities/index.md
vendored
Normal file
4
tests/fixtures/minimal-kb/wiki/entities/index.md
vendored
Normal 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.
|
||||
25
tests/fixtures/minimal-kb/wiki/entities/maria-nowak.md
vendored
Normal file
25
tests/fixtures/minimal-kb/wiki/entities/maria-nowak.md
vendored
Normal 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"
|
||||
10
tests/fixtures/minimal-kb/wiki/error-book.md
vendored
Normal file
10
tests/fixtures/minimal-kb/wiki/error-book.md
vendored
Normal 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 |
|
||||
|------|-------|-----------|------------------|
|
||||
5
tests/fixtures/minimal-kb/wiki/graph/edges.json
vendored
Normal file
5
tests/fixtures/minimal-kb/wiki/graph/edges.json
vendored
Normal 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"}
|
||||
]}
|
||||
3
tests/fixtures/minimal-kb/wiki/graph/index.md
vendored
Normal file
3
tests/fixtures/minimal-kb/wiki/graph/index.md
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Graph
|
||||
|
||||
Edge list in `edges.json`.
|
||||
21
tests/fixtures/minimal-kb/wiki/index.md
vendored
Normal file
21
tests/fixtures/minimal-kb/wiki/index.md
vendored
Normal 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
17
tests/fixtures/minimal-kb/wiki/log.md
vendored
Normal 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
|
||||
---
|
||||
10
tests/fixtures/minimal-kb/wiki/overview.md
vendored
Normal file
10
tests/fixtures/minimal-kb/wiki/overview.md
vendored
Normal 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.
|
||||
12
tests/fixtures/minimal-kb/wiki/projects/atlas.md
vendored
Normal file
12
tests/fixtures/minimal-kb/wiki/projects/atlas.md
vendored
Normal 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`
|
||||
3
tests/fixtures/minimal-kb/wiki/projects/index.md
vendored
Normal file
3
tests/fixtures/minimal-kb/wiki/projects/index.md
vendored
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Projects
|
||||
|
||||
- [Atlas](atlas.md) — Atlas migration scope
|
||||
11
tests/fixtures/minimal-kb/wiki/query-gaps.md
vendored
Normal file
11
tests/fixtures/minimal-kb/wiki/query-gaps.md
vendored
Normal 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
31
tests/smoke.sh
Executable 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
|
||||
|
|
@ -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`,
|
||||
|
|
|
|||
16
wiki/log.md
16
wiki/log.md
|
|
@ -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.
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
87
workload/2026-09-24_summary.md
Normal file
87
workload/2026-09-24_summary.md
Normal 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.
|
||||
Loading…
Add table
Reference in a new issue