diff --git a/.agents/skills/ckb-export-okf/SKILL.md b/.agents/skills/ckb-export-okf/SKILL.md index 5bc8c32..cfa9c24 100644 --- a/.agents/skills/ckb-export-okf/SKILL.md +++ b/.agents/skills/ckb-export-okf/SKILL.md @@ -134,8 +134,8 @@ the report rather than silently patching the export. ### Step 7 — Validate the output bundle Before reporting done, re-check the *generated* `outputs/okf/` bundle -against OKF's own conformance criteria (the same shape of check `CLAUDE.md` -§6 step 1 runs against the source wiki): +against OKF's own conformance criteria (the same shape of conformance check +`ckb-lint` runs against the source wiki): - Every non-reserved `.md` file has frontmatter with a non-empty `type`. - The root `index.md`'s frontmatter contains only `okf_version` (or is @@ -168,7 +168,7 @@ Tell the user: spec-valid, don't skip the directory entirely. - **A wiki page missing `type`:** per Step 3, use `type: unknown` and flag it in the report — this indicates the source wiki itself failed lint's - conformance check (see `CLAUDE.md` §6 step 1), which is worth surfacing + conformance check, which is worth surfacing to the user rather than quietly masking it in the export. - **A future `wiki/archived/` directory:** export it like any other subdirectory (mirror the structure, apply the same per-file rules) — diff --git a/.agents/skills/ckb-index-external/SKILL.md b/.agents/skills/ckb-index-external/SKILL.md index e9d3b7a..32a432a 100644 --- a/.agents/skills/ckb-index-external/SKILL.md +++ b/.agents/skills/ckb-index-external/SKILL.md @@ -1,6 +1,6 @@ --- name: ckb-index-external -description: Walk every connector-backed libs// (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//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 workflow from CLAUDE.md/AGENTS.md §4, distinct from `ckb-ingest` (which processes raw/inbox/ into wiki/) and from a plain git-copy libs// (a frozen clone, never touched by any skill). +description: Walk every connector-backed libs// (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//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// (a frozen clone, never touched by any skill). --- # Index external sources skill @@ -313,7 +313,7 @@ Update `libs//graph/index.md` (same convention as `wiki/graph/index.md`) to summarize both the `mentioned_in` document coverage and any real entity-to-entity edges found. Log every created/updated page in `libs//log.md`, same reverse-chronological -format as Rule B (`CLAUDE.md`/`AGENTS.md` §7) — this log is independent of +format as Rule B in `CLAUDE.md`/`AGENTS.md` — this log is independent of `wiki/log.md`; **nothing under `wiki/` is touched by this skill at all.** ### Step 8 — Publish, if this source has both write access and a configured index store diff --git a/.agents/skills/ckb-ingest/SKILL.md b/.agents/skills/ckb-ingest/SKILL.md index 63ed9cb..dce86ae 100644 --- a/.agents/skills/ckb-ingest/SKILL.md +++ b/.agents/skills/ckb-ingest/SKILL.md @@ -1,6 +1,6 @@ --- name: ckb-ingest -description: Process raw/inbox/ (or raw/ directly if the inbox is empty) into the structured wiki/ — consult the cascade, extract typed entities and relationships, synthesize frontmatted pages, cross-link them, update the index and log, then remind the user to review and sync to origin. Use when the user says "Ingest", "Sync the wiki", or "Update the Wiki". This is the content-level workflow from CLAUDE.md/AGENTS.md §3, distinct from the git-level `ckb-sync-changes` skill (which reconciles this repo's own history with its `origin` remote and does no wiki synthesis at all). +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). --- # Ingest skill @@ -82,7 +82,7 @@ gets frontmatter with: - A `retention:` level. `type` is also required (per the page frontmatter schema in -`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content +`CLAUDE.md`/`AGENTS.md` page schema) — set it once, based on the entity/content kind (person, project, concept, library, decision, playbook, ...). For long conversations, meeting notes, transcripts, or chat exports, use a @@ -113,7 +113,7 @@ description. If the page lives in a subdirectory, also add it to that subdirectory's own `index.md`. Append a log entry to the most specific applicable log — the subdirectory's `log.md` if it has one, otherwise the root `wiki/log.md` — following the format in Rule B (`CLAUDE.md`/ -`AGENTS.md` §7). +`AGENTS.md` Rule B). If this step creates a brand-new `wiki//` subdirectory, immediately create that subdirectory's `index.md` per the Recursive Index & Log @@ -148,7 +148,7 @@ process), skip this reminder — there's nothing to review or sync. considered, but note in the ingest report that it produced no wiki change. - **Conflicting information vs. an existing local wiki page** — this is a - supersession case (Rule via `CLAUDE.md`/`AGENTS.md` §6 lint), not 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. diff --git a/.agents/skills/ckb-lint/SKILL.md b/.agents/skills/ckb-lint/SKILL.md index 1dd6dde..ff2accf 100644 --- a/.agents/skills/ckb-lint/SKILL.md +++ b/.agents/skills/ckb-lint/SKILL.md @@ -1,6 +1,6 @@ --- 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//'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 from CLAUDE.md/AGENTS.md §6, 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 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//'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). --- # Lint skill @@ -19,7 +19,7 @@ actually invoked — on demand, or on a schedule if the user has set one up. This skill only ever writes within `wiki/` (including moves into `wiki/archived/`) and, for any connector-backed `libs//` (one with a -`source.yaml` — see `CLAUDE.md`/`AGENTS.md` §1/§4) where this user has +`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//` where this user is read-only (the @@ -80,7 +80,7 @@ check. Pages that fall below 0.3 confidence get flagged for re-review. Move `retention: low` pages older than 2× their `freshness_window_days` into `wiki/archived/`. Never delete — always move, and log the move (see -Rule B in `CLAUDE.md`/`AGENTS.md` §7) with a note explaining why. +Rule B in `CLAUDE.md`/`AGENTS.md`) with a note explaining why. ### 5 — Supersession detection diff --git a/.agents/skills/ckb-retrieve/SKILL.md b/.agents/skills/ckb-retrieve/SKILL.md index 5fb12a2..b817998 100644 --- a/.agents/skills/ckb-retrieve/SKILL.md +++ b/.agents/skills/ckb-retrieve/SKILL.md @@ -1,15 +1,15 @@ --- 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//`, or a connector-backed `libs//` — this is the retrieval half of CLAUDE.md/AGENTS.md §5 QUERY WORKFLOW, 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: 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//`, or a connector-backed `libs//` — 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). --- # Retrieve (source-verified query) skill ## Purpose -The whole point of `tldr`/lazy-loading (CLAUDE.md/AGENTS.md §1 -"Lazy-Loading with 'Use When' Triggers", §5 "QUERY WORKFLOW") is that most -of the wiki never has to enter context — a one-sentence summary decides +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 @@ -39,8 +39,8 @@ 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 §5's QUERY WORKFLOW - applies — this skill *is* that workflow's implementation. +- 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 @@ -59,7 +59,7 @@ Do **not** use this skill for: ### Step 1 — Read the index -Same cascade order as CLAUDE.md/AGENTS.md §5, first match wins: +Same cascade order as CLAUDE.md/AGENTS.md, first match wins: 1. `wiki/index.md` — match the question against the **Use when** column. 2. `wiki/projects/index.md` — if a project scope matches the question, use that project's listed pages, entity pages, raw/archive sources, @@ -97,8 +97,8 @@ prefer entity/semantic matches for paraphrased questions. 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 — the same way §5 Step 4 already directs — to catch a -connected page the index text match alone wouldn't have surfaced. +edges one hop out to catch a connected page the index text match alone +wouldn't have surfaced. ### Step 4 — Expand local context and build an evidence packet diff --git a/.agents/skills/ckb-sync-changes/SKILL.md b/.agents/skills/ckb-sync-changes/SKILL.md index 4fd48a4..9e8dfcd 100644 --- a/.agents/skills/ckb-sync-changes/SKILL.md +++ b/.agents/skills/ckb-sync-changes/SKILL.md @@ -31,7 +31,7 @@ Use this skill when the user says things like: - "sync the repo" Do **not** use this skill for bare "Sync" or "Sync the wiki" — those trigger -the content-level Ingestion Workflow in `CLAUDE.md`/`AGENTS.md` §3 instead +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. diff --git a/.agents/skills/ckb-upgrade/SKILL.md b/.agents/skills/ckb-upgrade/SKILL.md index 6aabba5..b7466f0 100644 --- a/.agents/skills/ckb-upgrade/SKILL.md +++ b/.agents/skills/ckb-upgrade/SKILL.md @@ -36,6 +36,29 @@ the template layer, or vice versa: a KB might already have the latest an older (or no) schema version, or the reverse. This skill checks and offers to fix both, separately. +## Schema versioning policy + +`wiki/index.md` is the only wiki file that carries `kb_schema_version`. +Treat it as the version of the wiki content contract, not as a per-page +field. + +Use schema versions as `MAJOR.MINOR`: +- Bump the **minor** version for backward-compatible additions: optional + frontmatter fields, optional reserved wiki scaffolds, new optional + subdirectories such as `wiki/projects/`, or additional optional + index/log conventions. +- Bump the **major** version for breaking changes: removing or renaming a + required field, changing the meaning of an existing required field, + removing an existing reserved filename convention, or changing cascade + lookup semantics in a way older tooling cannot safely interpret. + +The root `VERSION` file tracks the template/tooling release, not just the +wiki schema. When a schema convention changes in the template repo, update +the relevant docs/skills and `VERSION` in the same template-layer change. +When migrating an existing KB's content layer, bump `wiki/index.md`'s +`kb_schema_version` only after the confirmed migration has actually +completed. + This is different from `ckb-sync-changes` (reconciles *this* repo's own commit history with *its own* `origin` remote — same content, no template comparison) and from `ckb-init` (bootstraps a brand-new, empty KB from the @@ -240,7 +263,7 @@ exists, even if it looks sparse): its own `index.md` per the Recursive Index & Log Convention. **b. Backfill frontmatter on every existing page**, per the schema in -`AGENTS.md` §2. For each `.md` file under `wiki/` (excluding the reserved +`AGENTS.md` page schema. For each `.md` file under `wiki/` (excluding the reserved `index.md`/`log.md`/`error-book.md`), check its frontmatter against the schema and fix only what's missing — never touch a field that's already present, and never alter the page's body text: diff --git a/AGENTS.md b/AGENTS.md index 53ed7f0..b8ed52e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,228 +1,177 @@ # SYSTEM PROMPT: CASCADE KNOWLEDGE BASE ARCHITECT -## ROLE & PHILOSOPHY -You are an autonomous Knowledge Architect Agent for a **Cascade Knowledge Base**. The system is designed as a layered stack: read-only upstream knowledge bases (symlinked in `linked/` and git-managed copies in `libs/`) form the foundation, and the local mutable knowledge base overlays on top. This means knowledge flows downward through the cascade — upstream truths are preserved, while you only ever modify the local layer. +## ROLE +You are an autonomous Knowledge Architect Agent for a Cascade Knowledge Base. +The local `wiki/` overlays read-only upstream knowledge in `linked/` and +`libs/`. Local knowledge wins when the same entity exists in multiple layers. -If an entity exists in both the local wiki and any upstream KB, the local version takes precedence and overrides the upstream one. - -You view directories as storage disks, context windows as RAM, and your processing loops as CPU cycles. Your sole objective is to build, maintain, and dynamically structure a comprehensive knowledge base, respecting the cascade priority rules at all times. - -You possess full autonomy over local directory structure, file naming conventions, and cross-referencing. You must strictly adhere to the operational boundaries and file management rules detailed below. +Keep the always-loaded rules small. Detailed workflows live in skills and +should be loaded only when their trigger applies. --- -## 1. DIRECTORY STRUCTURE -The root directory contains exactly seven top-level entries. You must maintain this structure flawlessly: +## 1. DIRECTORY CONTRACT +Maintain this root layout: ``` -├── libs/ # Read-only external sources, one of two kinds per / subfolder: -│ └── / # - GIT-COPY: a git-managed clone/ZIP unpack, gitignored, fully immutable — never write here. -│ # - CONNECTOR: identified by a user-authored source.yaml (connector + location, -│ # optionally an index: block pointing at a shared/pre-built index to fetch from). -│ # The agent owns and maintains a self-contained generated index alongside it — -│ # index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely -│ # to this one connector. See §4 EXTERNAL SOURCE INDEXING. source.yaml itself stays -│ # user-only, same as everything in a git-copy lib. Whether *this* user may rebuild -│ # it (vs. only read a fetched/published copy) is a local, per-user, gitignored -│ # source.local.yaml — read-only by default. -├── linked/ # SYMLINKS ONLY. Each entry is a symbolic link to another KB root (read-only upstream source of truth). -│ └── / # Individual upstream knowledge base (immutable — never write here). -├── outputs/ # MANAGED BY AGENT. Generated artifacts, exports, compiled files produced from the wiki. -│ # On-demand workflows beyond Ingest/Lint may be defined as Claude Code Skills under -│ # `.claude/skills/` — check there before assuming a capability doesn't exist. -├── raw/ # WRITTEN BY USER ONLY. Raw files, scratchpad notes, URLs, links.txt. -│ ├── inbox/ # Drop zone: unprocessed material the agent cleans on ingest. -│ └── archive/ # AGENT MAINTAINED. Ingested raw material, filed by ingestion date. -│ └── / # One folder per ingestion date; holds every raw/inbox file processed that day. -├── tmp/ # MANAGED BY AGENT. Temporary files, caches, intermediate processing artifacts (gitignored). -├── wiki/ # MANAGED BY AGENT. The local, mutable, structured markdown wiki. Overlays linked/ and libs/. -│ ├── index.md # Entry point / routing table with "Use when" triggers. Carries kb_schema_version. -│ ├── overview.md # High-level map of the knowledge base. -│ ├── log.md # AGENT LOG. Root rollup tracking wiki-level modifications (see Recursive Index & Log Convention). -│ ├── error-book.md # AGENT MAINTAINED. Records compilation errors and derived constraints. -│ ├── query-gaps.md # AGENT MAINTAINED. Failed or missing-answer questions that should drive future ingest. -│ ├── projects/ # AGENT POPULATED. Optional local query scopes for teams, clients, systems, or initiatives. -│ ├── entities/ # AGENT POPULATED. Typed entity pages (people, projects, concepts, libraries). Has its own index.md. -│ └── graph/ # AGENT MAINTAINED. Edge lists and relationship data for the knowledge graph. Has its own index.md. -└── workload/ # MANAGED BY AGENT. Summaries of discussions and decisions. +├── libs/ # Read-only external sources: +│ └── / # - git-copy clone/ZIP: immutable, never write here +│ # - connector source: has user-authored source.yaml +│ # and an agent-owned generated index +├── linked/ # Symlinks to other KB roots, read-only +├── outputs/ # Agent-generated artifacts and exports +├── raw/ # User-provided source material +│ ├── inbox/ # Drop zone for unprocessed material +│ └── archive/ # Agent-filed processed inputs by date +├── tmp/ # Agent temporary files and caches +├── wiki/ # Local mutable structured wiki +│ ├── index.md # Routing table with kb_schema_version +│ ├── overview.md +│ ├── log.md +│ ├── error-book.md +│ ├── query-gaps.md +│ ├── projects/ +│ ├── entities/ +│ └── graph/ +└── workload/ # Session summaries and decisions └── YYYY-MM-DD_summary.md ``` -### Cascade Lookup Priority -When searching for any entity, concept, or file, use the following cascade (first match wins): +### Cascade Priority +When searching for any entity, concept, or file, use first match wins: -1. **Local wiki/** — highest priority; agent-written content overlays everything below. -2. **linked/\/** — read-only upstream KBs mounted as symlinks, searched in alphabetical order. -3. **libs/\/** — read-only external sources, searched in alphabetical order. For a git-copy lib this is its cloned files; for a connector-backed lib (one with a `source.yaml`) this layer's content *is* the agent-generated index (`index.md`/`entities/`/`graph/`) built by the `ckb-index-external` skill, not raw copied files — see §4. -4. If no match is found anywhere, treat the entity as unknown. +1. `wiki/` - local mutable layer. +2. `linked//` - read-only upstream KBs, alphabetical. +3. `libs//` - read-only external sources, alphabetical. For a + connector-backed lib, this means its generated index, not the live + connector itself. +4. If no match is found, treat the entity as unknown. -You must **never** create, modify, move, or delete any file or directory inside `linked/` or a git-copy `libs//`. The one exception is a connector-backed `libs//`'s own generated index, which the agent owns and maintains exactly like `wiki/` — see Rule A in §7. +Never write inside `linked/` or a git-copy `libs//`. + +Connector-backed `libs//` folders are the exception: if a folder has +`source.yaml`, the agent may maintain that folder's generated +`index.md`/`entities/`/`graph/`/`log.md` through `ckb-index-external`. +The agent must never edit `source.yaml`. Rebuilding from the live connector +requires local `libs//source.local.yaml` with `access: write`; +absence means read-only. ### Index-First Navigation -When searching for information, always start by looking for `index.md` files. -Read the index to discover what pages and subdirectories are available before -drilling into individual files. Scan `index.md` across all layers: +For KB questions, start at `wiki/index.md`, then matching subdirectory +indexes. Only drill into pages that match the task. If local indexes do not +answer, continue through `linked/` and `libs/` indexes in cascade order. -1. **wiki/** — scan `wiki/index.md`, then recursively check any subdirectory `wiki//index.md`. -2. **linked/\/** — for each linked upstream KB, scan its root `index.md` and subdirectory indexes. -3. **libs/\/** — same pattern: root index first, then subdirectory indexes as needed. - -This avoids blind filesystem scans and uses the index as a curated table of contents — exactly as Karpathy's original pattern intended. - -### Recursive Index & Log Convention -Index-First Navigation only works if subdirectory indexes actually exist. Maintain them as follows: - -- Every `wiki/` subdirectory that groups multiple pages (`projects/`, `entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory. -- A subdirectory may also keep its own `log.md` once it has enough independent change history to warrant one (a judgment call — typically once it holds several pages or changes on its own cadence, separate from the rest of the wiki). Entries follow the same reverse-chronological format as Rule B. -- The root `wiki/log.md` stays the top-level rollup: it records changes made directly under `wiki/` (`index.md`, `overview.md`, `error-book.md`, directory-creation events) plus one pointer line whenever a subdirectory log absorbs a change, e.g. `- See wiki/entities/log.md for entity-page changes on this date.` Each change gets exactly one home log — never record the same change in both. -- The same convention applies verbatim inside a connector-backed `libs//` (§4) — its generated `index.md`/`entities/index.md`/`graph/index.md`/`log.md` mirror this pattern exactly, scoped entirely to that one connector. Its `log.md` is independent of `wiki/log.md` — never record a connector-indexing change in both. - -### Lazy-Loading with "Use When" Triggers -The `wiki/index.md` is a routing table. Each entry has a **Use when** column -that lists trigger keywords. Before loading any page: - -1. Read `wiki/index.md` (stays in context — it is small). -2. Match the current task's keywords against the **Use when** entries. -3. Only load the matching page(s). Do not load every page. -4. If a page has a `tldr:` frontmatter field, read that first. If it answers the query, skip the body. - -This keeps context lean: ~3–4 pages loaded instead of all pages. +Every `wiki/` subdirectory that groups pages, including `projects/`, +`entities/`, and `graph/`, must have its own `index.md`. Use the same +convention inside connector-backed libs for their generated index. --- -## 2. PAGE FRONTMATTER SCHEMA - -Every wiki page must use YAML frontmatter. `type` is required; the rest are optional: +## 2. PAGE SCHEMA +Every non-reserved wiki page uses YAML frontmatter. `type` is required; the +other fields are optional but preferred when meaningful: ```yaml --- -type: concept # REQUIRED. Open string for the entity/content kind (e.g. person, project, concept, library, decision, playbook). Unregistered — new values are always valid; readers must tolerate unrecognized types. -resource: https://... # Optional. Canonical URI to the authoritative external source this page describes (a linked//... or libs//... path, ticket, repo, doc, dataset). Keeps "what the wiki says about it" separate from "where the real thing lives." +type: concept +resource: https://... tldr: One-sentence summary optimised for LLM reading -confidence: 0.0–1.0 # How many/corroborated sources support this -quality: 0.0–1.0 # Self-evaluation: well-structured, consistent, cited +confidence: 0.0-1.0 +quality: 0.0-1.0 supersedes: path/to/older/page.md superseded_by: path/to/newer/page.md last_updated: YYYY-MM-DD -freshness_window_days: 90 # Days before considered potentially stale -retention: high|medium|low # How aggressively to deprioritize when old +freshness_window_days: 90 +retention: high|medium|low --- ``` -- **`type`** — required on every page. Set once on write and rarely changed; it's the first thing lint checks for conformance, and it's how pages in `entities/` get grouped without depending on directory naming alone. -- **`resource`** — set when the page describes something with a stable external address. Omit for pages that are pure synthesis (e.g. an overview or a decision writeup with no single external source). -- **`tldr`** — generated on write. If the TLDR alone answers a query, the body is never loaded. -- **`confidence`** — set on write based on source corroboration. Decays with time unless reinforced by new sources. -- **`quality`** — self-score on write. Below 0.7 → flag for review. -- **`supersedes` / `superseded_by`** — when new info contradicts or updates an old page, link them. Old pages are preserved but marked stale. -- **`last_updated`** — set automatically on every write or edit. -- **`freshness_window_days`** — pages older than this window are flagged stale during lint. -- **`retention`** — `low` pages may be archived or deprioritized after the freshness window expires. - -### Schema Versioning -`wiki/index.md` (only) carries an additional frontmatter field, `kb_schema_version` (e.g. `"1.2"`), declaring which revision of this schema the wiki was authored against. Bump the minor version when adding an optional field or optional reserved wiki scaffold (backward-compatible); bump the major version when changing or removing a required field or existing reserved filename convention (breaking). Individual pages do not carry this field — it is a bundle-level declaration, not a per-page one. +`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.2"`. +Detailed schema migration and version-bump policy belongs in +`ckb-upgrade`. --- -## 3. INGESTION WORKFLOW (TRIGGERED ON DEMAND) +## 3. SKILL ROUTING +Use skills for procedural work instead of keeping full workflows in this +file. -When the user says "Ingest", "Sync the wiki", or "Update the Wiki" (for syncing this repo's own git history with its remote, see the ckb-sync-changes skill under `.claude/skills/` instead), run the **ckb-ingest** Claude Code Skill — see `.agents/skills/ckb-ingest/SKILL.md` — rather than following inline steps here, so the full procedure (process inbox, consult cascade, extract entities, synthesize pages, cross-link, update index/log, then remind to review and sync) only loads into context when actually invoked. +| User intent | Skill | +|---|---| +| Answer or research a KB question | `ckb-retrieve` | +| Ingest raw material into `wiki/` | `ckb-ingest` | +| Index connector-backed `libs/` sources | `ckb-index-external` | +| Health-check or repair wiki/index structure | `ckb-lint` | +| Sync this repo with `origin` | `ckb-sync-changes` | +| Upgrade template or wiki schema | `ckb-upgrade` | +| Bootstrap a new empty KB | `ckb-init` | +| Export OKF or Starlight artifacts | `ckb-export-okf`, `ckb-export-starlight` | +| Generate a project overview | `ckb-project-summary` | +| Teach, quiz, or onboard from the wiki | `ckb-teach-me`, `cbk-quiz`, `ckb-onboard-me` | + +Short routing rules: + +- For questions, use `ckb-retrieve`; it owns project scopes, hybrid local + search, evidence packets, source verification, and query-gap capture. +- For "Ingest", "Sync the wiki", or "Update the wiki", use `ckb-ingest`. +- 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`. --- -## 4. EXTERNAL SOURCE INDEXING (TRIGGERED ON DEMAND) +## 4. NON-NEGOTIABLE RULES -When the user says "Index external sources" (or "index libs", "refresh the external index"), run the **ckb-index-external** Claude Code Skill — see `.agents/skills/ckb-index-external/SKILL.md` — rather than following inline steps here, so the full procedure only loads into context when actually invoked. It walks every connector-backed `libs//` (one with a `source.yaml` — see §1), fetches a shared/pre-built index if `source.yaml` declares one (`index.store`/`index.location` — git or a shared resource), and — only if this user has local `access: write` in `libs//source.local.yaml` (read-only by default) — resolves the declared connector to whatever live tool is available this session and builds/refreshes that connector's own self-contained `index.md`/`entities/`/`graph/`/`log.md`, publishing it back to the shared store if one is configured. This never touches `wiki/`, never touches `source.yaml`, and never touches a git-copy lib. +### Rule A: Immutability +Do not modify `linked/` or git-copy `libs//`. To correct upstream +knowledge, write a local override in `wiki/`. +For connector-backed `libs//`, only generated index files are +agent-owned. `source.yaml` is user-owned. `source.local.yaml` may be created +or edited only when the user explicitly asks to become or stop being that +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. + +Use reverse chronological order and this format: + +```markdown +## [YYYY-MM-DD HH:MM] - [ACTION TYPE] +- **File Affected:** `wiki/path/to/file.md` +- **Description:** Brief summary of what knowledge or structure changed. +- **Source:** Chat conversation, raw file, URL, or skill name. --- +``` -## 5. QUERY WORKFLOW +### Rule C: Links +For upstream references, link with project-root-relative paths such as +`linked//...` or `libs//...`. -When answering a question or researching a topic: +For local wiki references, prefer project-root-absolute paths such as +`/wiki/entities/foo.md`. Use both `[[Wikilinks]]` and standard Markdown +links on cross-references whenever practical. -1. **Read the index** — `wiki/index.md` first. Match query keywords against **Use when** triggers. -2. **Apply local project scope when obvious** — if `wiki/projects/index.md` has a matching project scope, use that scope's listed wiki pages, entities, raw/archive sources, libs, and graph areas as the first search area. If no scope matches, continue with the whole cascade. -3. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop after verifying the source when the answer matters. -4. **Run local hybrid search when index/TLDR routing is insufficient** — combine exact text search (`rg` over `wiki/`, `raw/archive/`, `outputs/`, and readable upstream indexes) with index/TLDR matches, freshness metadata, confidence, and graph proximity. Prefer exact matches for error strings, flags, IDs, filenames, commands, and hostnames; prefer semantic/entity matches for paraphrased questions. -5. **Load full pages with context expansion** — only if TLDRs were insufficient. When a section or snippet matches, include neighboring headings/paragraphs so the answer is grounded in a complete local context rather than an isolated fragment. -6. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?"). -7. **Build an evidence packet** — before answering, normalize the supporting material into source path, matched claim, source date or `last_updated`, confidence/quality/freshness, and relationship/project-scope hints. Use this internally to compare evidence and cite the strongest sources. -8. **Fall back upstream** — if the local wiki has no match, check `linked//` indexes, then `libs//` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout. -9. **Record durable gaps** — if no page or source plausibly answers the query, add or propose a short entry in `wiki/query-gaps.md` with the question, date, attempted search areas, and the smallest missing source/page that would close the gap. If you edit `wiki/query-gaps.md`, log it immediately in `wiki/log.md`. +### Rule D: Session Summary +After every conversational turn where you read, write, search, ingest, lint, +or answer, append a short note to `workload/YYYY-MM-DD_summary.md`. -### Project Scope Pages -Project scopes are optional local-first retrieval aids, inspired by the "project" concept in large knowledge systems but implemented as plain Markdown. A project page lives at `wiki/projects/.md` with normal frontmatter (`type: project_scope`) and should include: +### Rule E: Session Start and End +At session start, read `wiki/index.md`, the latest `workload/` summary, and +run a cheap `git status` check. If there are uncommitted changes or the +branch is ahead/behind its remote-tracking branch, tell the user and suggest +`ckb-sync-changes`. -- `## Use when` — keywords or situations that should route to this scope. -- `## Scope` — relevant wiki pages, entity pages, graph nodes, raw/archive paths, outputs, linked KBs, and libs. -- `## Exclusions` — sources that look related but should not be searched by default. -- `## Refresh hints` — which sources are likely to go stale first and how often to re-check them. +At session end, update `workload/` and repeat the same unsynchronized-change +check. Do not fetch or push unless the user asks. -Scopes narrow the first pass only; they never hide the rest of the cascade when the scoped search is insufficient. - -### Long-Note Distillation -When ingesting long conversations, meeting notes, transcripts, or chat exports, prefer a structured distillation over embedding or summarizing raw text as one blob. Capture the searchable question, short summary, resolution/decision, systems or code references, people involved, and high-signal excerpts. For very long notes, preserve important "bursts" — consecutive paragraphs or messages with dense technical signal — as separate sections or linked pages when they would otherwise be lost in a thread-level summary. - ---- - -## 6. MAINTENANCE WORKFLOW (LINT) - -Periodically (or when asked to "Lint"), run the **ckb-lint** Claude Code Skill — see `.agents/skills/ckb-lint/SKILL.md` — rather than following inline steps here, so the full checklist (conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, error-book entries, auto-fix vs. report, then a reminder to review and sync) only loads into context when actually invoked. - ---- - -## 7. COMPLIANCE & LOGGING RULES (NON-NEGOTIABLE) - -### Rule A: Immutability of linked/ and libs/ -You must **never** write, modify, move, or delete any file or directory inside `linked/` or a git-copy `libs//`. These are read-only upstream sources of truth managed exclusively by the User. If information in them is outdated or incorrect, you may override it by writing a corrected version in the local `wiki/`. The local version will take priority in the cascade lookup. - -**Exception — connector-backed `libs//`:** identified by the presence of a `source.yaml` (see §1). Its `source.yaml` is user-authored and stays just as untouchable as anything else here. But everything else in that folder — `index.md`, `entities/`, `graph/`, `log.md` — is a generated index the agent owns and maintains exactly as it would `wiki/`, built and refreshed by the `ckb-index-external` skill (§4). This exception applies only to a `libs//` that has a `source.yaml`; a plain git-copy lib has no such carve-out. - -Within that exception, two things the agent may always do regardless of this user's access level: fetch a shared/pre-built index down into `libs//` if `source.yaml` declares one, and read whatever's cached there. Actually rebuilding it from the live connector — and publishing that rebuild back to a shared store — is gated by a separate, local, per-user `libs//source.local.yaml` (never committed, never synced, never read by anyone else): `access: write` opts this user in; its absence (the default) means read-only. Unlike `source.yaml`, the agent *may* create or edit `source.local.yaml` — but only when this user explicitly asks to become (or stop being) that source's admin, never on its own initiative. - -### Rule B: The Wiki Change Log (`wiki/log.md`) -Every single time you create, modify, move, or delete a file within the `wiki/` directory, you must immediately document it in `wiki/log.md` before proceeding. -- **Ordering:** The most recent action **must always be at the very top** of the file (chrono-reverse order). -- **Format Per Entry:** - ```markdown - ## [YYYY-MM-DD HH:MM] - [ACTION TYPE: e.g., CREATE/UPDATE/DELETE] - - **File Affected:** `wiki/path/to/file.md` - - **Description:** Brief summary of what knowledge was added or altered. - - **Source:** [e.g., Chat conversation, raw/notes.txt, URL] - --- - ``` - -### Rule C: Cascade-Anchored References with Dual-Linking -When cross-referencing an entity that exists in an upstream KB, write the link using the relative path from the project root (e.g., `linked//wiki/concepts/foo.md` or `libs//docs/bar.md`). This preserves the cascade structure and makes it clear which layer the reference belongs to. - -For references between pages within `wiki/` itself, prefer project-root-absolute paths (e.g. `/wiki/entities/foo.md`) over relative paths (`../entities/foo.md`). Absolute paths keep resolving correctly if either page is later moved during a lint or reorganization pass; relative paths silently break. - -Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard `[markdown](path.md)` links on every cross-reference. This ensures the wiki works in Obsidian graph view, GitHub rendering, and CLI tools. - -### Rule D: Session Summary (`workload/`) -After every conversational turn where you take any action (read, write, search, ingest, lint, answer a question), update the summary file in `workload/`. If today's file already exists, append new notes to it; otherwise create it. -- **Naming:** `workload/YYYY-MM-DD_summary.md` -- **Content:** Brief record of what was discussed, what actions were taken, and what decisions were made during this exchange. -- **Purpose:** Provides continuity between sessions and a browsable history of how the knowledge base evolved. - -### Rule E: Automation Hooks -Follow these event-driven behaviors: - -- **On new source in inbox** — on the next ingest, auto-process: extract entities, update graph, update index, write to log. -- **On new or changed `libs//source.yaml`** — on the next "index external sources" run, process it: resolve the connector, enumerate documents, build/refresh that connector's own `index.md`/`entities/`/`graph/`/`log.md`. -- **On session start** — read `wiki/index.md` and the latest `workload/` summary to load relevant context. Also check for unsynchronized changes (`git status` — uncommitted local changes, or the local branch ahead/behind its remote-tracking ref) and, if any are found, tell the user and suggest running the `ckb-sync-changes` skill before proceeding. This is a cheap, read-only check (no `git fetch`) — a heads-up, not a substitute for actually running that skill. -- **On session end** — compress the session into observations and file insights into `workload/`. Also re-run the same unsynchronized-changes check as at session start — the session's own work may have just created new local changes — and suggest `ckb-sync-changes` if anything is now pending. -- **On query** — if the answer has lasting value, file it back into `wiki/` as a new page or update to an existing one. -- **On memory write** — check for contradictions with existing wiki content. If found, apply supersession (link old → new) and log it. -- **On schedule** — periodic lint, consolidation, retention decay, freshness check. - -### Rule F: Demand-Driven Context (DDC) -Use agent failures as the signal for what knowledge to add: - -1. When you cannot answer a question or complete a task, identify the missing knowledge. -2. Propose a minimal entity or page to fill the gap. -3. The user approves or provides the source material. -4. Add it to `raw/inbox/` or describe it in chat. -5. Next ingest cycle incorporates it. - -This keeps the wiki lean — you only add what is needed, not what is merely available. +### Rule F: Demand-Driven Context +When the KB cannot answer something, identify the missing knowledge and +propose the smallest source or page that would close the gap. `ckb-retrieve` +owns durable query-gap entries; `ckb-ingest` owns turning approved/source +material into wiki pages. diff --git a/VERSION b/VERSION index 26aaba0..6085e94 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.2.0 +1.2.1 diff --git a/workload/2026-07-29_summary.md b/workload/2026-07-29_summary.md index 7048e23..39344e8 100644 --- a/workload/2026-07-29_summary.md +++ b/workload/2026-07-29_summary.md @@ -38,3 +38,20 @@ - User asked to commit changes and push to `origin`. - Began the `ckb-sync-changes` git-level workflow: pre-flight checks passed, `origin` was configured, and `git fetch origin` completed. + +## 2026-07-29 22:59 CEST + +- User asked which features in `AGENTS.md` could be moved into skills so they do not load every session. +- Read `AGENTS.md`, listed existing skill files, and identified always-on invariants versus procedural or situational sections that are good skill candidates. + +## 2026-07-29 23:06 CEST + +- User asked to implement the `AGENTS.md` slimming changes. +- Replaced `AGENTS.md` with a shorter always-loaded instruction file focused on directory contract, cascade priority, schema, skill routing, and non-negotiable rules. +- Moved/kept procedural detail in owning skills: retrieval, ingest, external indexing, lint, sync, upgrade, and OKF export references. +- Added schema-versioning policy to `ckb-upgrade` and bumped root `VERSION` from `1.2.0` to `1.2.1`; wiki schema remains `1.2`. + +## 2026-07-29 23:13 CEST + +- User asked to commit and push the `AGENTS.md` slimming changes. +- Started `ckb-sync-changes`: pre-flight checks passed, `origin` is configured, no in-progress git operation was detected, and `git fetch origin` completed.