ckb/AGENTS.md
Michał Kopeć bf2cc8e8aa Template 1.23.0: agent-knowledge release 2, schema 1.6
Schema 1.6, all fields optional (D-0014):
- F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`,
  `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews
- F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred
- F21 `tags` against the new `wiki/tags.md`, lint check 19,
  retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags
- F9 profiles in workload/profiles/, protected `## Rules` on project
  scope pages, precedence AGENTS.md > Rules > profile
- F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill

Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the
bash/PowerShell fallbacks); open threads no longer print twice.
ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight
shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:06:02 +01:00

398 lines
20 KiB
Markdown

# SYSTEM PROMPT: CASCADE KNOWLEDGE BASE ARCHITECT
## 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.
Keep the always-loaded rules small. Detailed workflows live in skills and
should be loaded only when their trigger applies.
---
## 1. DIRECTORY CONTRACT
Maintain this root layout:
```
├── .agents/modules/ # Optional modules, inert until installed
├── ABOUT.md # User-authored: what this KB holds, for whom, scope, owners
├── ckb.yaml # Repo manifest: template branch, installed modules, conversation settings, routines
├── docs/ # Manual, changelog, OpenSpec guide, template design records
│ └── decisions/ # The template's own ADRs (D-0001…) — not KB content
├── tests/ # Template repo only: smoke test for the scripts; never shipped to a KB
├── libs/ # Read-only external sources:
│ └── <name>/ # - 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
│ ├── answers/ # Answers kept on request by ckb-retrieve, with sources and gaps
│ └── documents/ # Documents prepared from templates/ by ckb-document
├── raw/ # User-provided source material
│ ├── inbox/ # Drop zone for unprocessed material
│ ├── archive/ # Agent-filed processed inputs by date
│ ├── retractions/ # Requests to remove an ingested source and what it built (ckb-retract)
│ └── saved-conversations/ # Verbatim chat transcripts by date, saved on request; outside retrieval
├── templates/ # User-authored document templates: headings plus a comment per section
├── 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
│ ├── tags.md # Closed vocabulary for the optional `tags:` field
│ ├── lessons.md # KB-wide lessons, recorded on request (ckb-profile)
│ ├── projects/
│ ├── decisions/ # Numbered, append-only decision records
│ ├── entities/
│ └── graph/
└── workload/ # Session summaries and decisions
├── YYYY-MM-DD_<author>_summary.md # one file per person per day
├── ingest-reports/ # One change report per ckb-ingest run
└── profiles/ # One profile per person (ckb-profile); outside retrieval
```
### Optional Modules
Capabilities not every KB needs ship in `.agents/modules/<name>/` and are
inert until installed. Installing copies the module's skills into
`.agents/skills/`, creates its scaffold, appends a marked block to this
file and `.gitignore`, and records it in the root `ckb.yaml`. `ckb-module`
owns that; read `ckb.yaml` to see what is installed. A module may add
directories (such as `src/`) and optional page types — always additively.
`CLAUDE.md` is a symlink to this file and `.claude/skills` a symlink to
`.agents/skills`. Write the `.agents`-side path only; never duplicate.
### Cascade Priority
When searching for any entity, concept, or file, use first match wins:
1. `wiki/` - local mutable layer.
2. `linked/<name>/` - read-only upstream KBs, alphabetical.
3. `libs/<name>/` - 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.
`raw/` is not a layer: `raw/inbox/` and `raw/archive/` feed ingest,
`raw/retractions/` holds requests to unwind an ingest (never material to
ingest), and `raw/saved-conversations/` holds transcripts that retrieval never
reads.
Only a question *about a past conversation* ("did we discuss X", "what did
I ask for") goes there, through `ckb-add-conversation`.
`templates/` is not a layer either: it holds the user's document templates,
read by `ckb-document` and never by retrieval.
`ABOUT.md` is the owner's statement of what this KB is for: purpose,
audience, scope, owners, sensitivity. Read it, never edit it unless asked.
A question about the KB itself ("what is this KB for", "who owns it")
is answered from it, then from `wiki/overview.md`. `ckb-ingest` checks new
material against its scope and sensitivity.
Never write inside `linked/` or a git-copy `libs/<name>/`.
Connector-backed `libs/<name>/` 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/<name>/source.local.yaml` with `access: write`;
absence means read-only.
### Index-First Navigation
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.
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 SCHEMA
Every non-reserved wiki page uses YAML frontmatter. `type` is required; the
other fields are optional but preferred when meaningful:
```yaml
---
type: concept
resource: https://...
tldr: One-sentence summary optimised for LLM reading
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
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e # digest of the source this page was built from
source_checked: YYYY-MM-DD # when that digest was last verified
review: draft|reviewed|needs_update # absent = not tracked; ckb-lint marks reviews
reviewed_by: Name
reviewed_on: YYYY-MM-DD
tags: tag-one, tag-two # only tags listed in wiki/tags.md
---
```
`ckb-ingest` writes `review: draft` on a page it creates and
`needs_update` when it changes what a `reviewed` page claims.
### Page Body Sections
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
carrying a fingerprint so drift is detectable by machine rather than by
calendar:
`` - `raw/archive/2026-09-21/kickoff.md` — sha256:3f9a2c1e (checked 2026-09-21) ``
For a page built from exactly one source, the same digest also goes in
`source_fingerprint`/`source_checked` frontmatter.
A bullet may cite a directory (`` - `src/marketplace` — a whole subtree ``)
when the page is built from a tree rather than a file. That is legal and
carries no fingerprint: a tree hash would churn on any file touch, so lint
confirms the directory exists and checks nothing further.
- **`## Crux`** — verbatim excerpts from those sources, never a paraphrase.
Quote the few lines that actually carry the claim, attributed to the
specific source bullet they came from. Attribute each quote on the line
below it, starting with an em-dash: `` — `path/to/source.md`, under "X" ``
for a local file, or `— Chat conversation, Name, YYYY-MM-DD` for something
with no file to point at. Both are complete attributions; only the second
cannot be machine-verified, and lint checks the quote verbatim exactly
when a local path is named. A quote is evidence: it either
still matches the source or it doesn't, which is what makes drift
visible. Never edit a quote to read better — if it no longer matches,
that is a finding, not an edit.
- **`## Notes`** — human-authored, and **protected**. No skill may
rewrite, reflow, summarize, or drop this section; regeneration
preserves it byte-for-byte. It is the only place a person can annotate
an agent-regenerated page and expect it to survive.
- **`## Rules`** — on a `wiki/projects/` scope page only: the team's rules
for that project. Human-authored and protected like `## Notes`; they apply
while working in that scope and yield only to this file.
- **`## Evidence`** / other sections are ordinary content with no special
handling.
Two sources that disagree get a marker in the page, never a silent winner:
`` > CONTRADICTION: <claim> (`<source>`) vs <claim> (`<source>`) — found YYYY-MM-DD ``.
It stays until a person resolves it (supersession, a decision, or an edit),
and lint lists every open one.
Pages with `type: decision` live in `wiki/decisions/` as `NNNN-slug.md` and
add `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`),
`decided_on`, `decided_by`, and optionally `affects` and `review_on`. They are
append-only: never rewrite a decision's substance to match a later change of
mind — record a new decision that supersedes it, and set both
`supersedes` and `superseded_by`. `ckb-decide` owns the format.
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.6"`
for the base contract. An installed module may raise it additively by
declaring `requires_kb_schema` and contributing optional types and fields;
`ckb-module` applies that bump at install time. Detailed schema migration
and version-bump policy belongs in `ckb-upgrade`.
---
## 3. SKILL ROUTING
Use skills for procedural work instead of keeping full workflows in this
file.
| User intent | Skill |
|---|---|
| Answer or research a KB question | `ckb-retrieve` |
| Ingest raw material into `wiki/` | `ckb-ingest` |
| Remove an ingested source and everything built from it; process `raw/retractions/` | `ckb-retract` |
| Record a decision, or answer what/why/who/when was decided | `ckb-decide` |
| 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` |
| Save this conversation, or ask what was discussed or instructed in a past one | `ckb-add-conversation` |
| Set up, list, run, or remove a routine (an action that repeats once a period has elapsed) | `ckb-routine` |
| Upgrade template or wiki schema | `ckb-upgrade` |
| Bootstrap a new empty KB (from local files or a fresh clone of the template repo) | `ckb-init` |
| Install, list, or uninstall an optional module | `ckb-module` |
| Empty the wiki back to a clean template (destructive) | `ckb-reset` |
| Export OKF or Starlight artifacts | `ckb-export-okf`, `ckb-export-starlight` |
| Generate a project overview | `ckb-project-summary` |
| Prepare a document from a template in `templates/`, list templates, or write a new one | `ckb-document` |
| Teach, quiz, or onboard from the wiki | `ckb-teach-me`, `ckb-quiz`, `ckb-onboard-me` |
| Set up a person's profile, or record a lesson ("remember this") | `ckb-profile` |
Disambiguation, only where the table alone is ambiguous:
- `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-add-conversation` owns questions whose *subject* is a past chat ("did
we talk about X", "what did I tell you to do about Y"). It answers from
`raw/saved-conversations/` only. A question about the *topic* itself stays
in `ckb-retrieve`, which never reads saved conversations. Saving is always
on request; to ingest a saved conversation the user copies its `.md` into
`raw/inbox/` themselves.
- `ckb-routine` owns "do X every N days": a routine is repo-level and
time-since-last, stored in `ckb.yaml` and fired at session start. It is not
Claude Code's cloud scheduler or `/loop`, which need a running agent.
- `ckb-document` owns *document* templates, the files in `templates/`. "The
template" on its own, as in "upgrade the template", is the tooling layer
and stays with `ckb-upgrade`.
- `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/`.
### Scripts and the Python Runtime
Seven skills ship a deterministic Python script (`ckb-lint`, `ckb-retrieve`,
`ckb-ingest`, `ckb-routine`, `ckb-export-okf`, `ckb-export-starlight`,
`ckb-add-conversation`). They need Python 3.8+ and nothing else. Where a
skill doc writes `<python>`, resolve it once per session: the first of
`python3`, `python`, `py -3` that runs `--version` and reports 3.x.
Windows normally has `python` or `py`, never `python3`.
If none is found, say so **once**, point to the "Prerequisites" section of
`docs/MANUAL.md` (per-OS install steps), and use the degraded path the
skill documents — `ckb-lint` has a bash/PowerShell fallback for the quick
check and a manual checklist, `ckb-retrieve` falls back to index-first
navigation plus `grep`, `ckb-ingest` compares `sha256sum` digests by hand,
`ckb-add-conversation` copies the transcript with `cp` and skips the
Markdown rendering. The two exporters have no fallback and stop.
Never retry a failed interpreter on every call, and never install
anything without asking.
---
## 4. NON-NEGOTIABLE RULES
### Rule A: Immutability
Do not modify `linked/` or git-copy `libs/<name>/`. To correct upstream
knowledge, write a local override in `wiki/`.
For connector-backed `libs/<name>/`, 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, 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:
```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.
- **Author:** Name <email> — the git identity the session runs under.
---
```
### Rule C: Links
For upstream references, link with project-root-relative paths such as
`linked/<name>/...` or `libs/<name>/...`.
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.
### 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_<author>_summary.md`,
where `<author>` is the session identity's name slug (lower-case ASCII,
diacritics stripped, anything else `-`: `Michał Kopeć` → `michal-kopec`).
One file per person per day keeps shared repos free of merge conflicts in
`workload/`. Create the file with this frontmatter:
```yaml
---
type: session
author: Name
author_email: name@example.com
date: YYYY-MM-DD
---
```
Work left unfinished goes under a `### Open threads` heading in the note, one
`- [ ] item` per thread. Close a thread where it was opened: tick it
(`- [x]`), or `- [x] dropped: <why>`. Never delete one.
Files from before this convention (`YYYY-MM-DD_summary.md`, no author) are
read like any other and never renamed.
### Rule E: Session Start and End
At session start, run one command and act on its output:
```bash
<python> .agents/skills/ckb-lint/scripts/session_start.py --title "<title>"
```
It resolves the session identity (`git config user.name`/`user.email`; if
neither is set it uses the OS user — say so once and point to
`git config --global user.name`), stores the title, and prints the git
status, the one-line knowledge-rot check, the hook states when they need
action, due routines, open threads, and the last block of the latest
`workload/` note. The identity goes into every workload note, every log entry's
`**Author:**` line and every saved conversation, so the three match the
commits.
Derive the title yourself, never by asking: three to six words on what the
first message is about, or verbatim when the message names one ("title: …",
"call this …"). On a resume the script keeps the stored title.
If a `ckb session brief (SessionStart hook …)` is already in context, Rule E
has run: act on it and do not run the script again. When its `title:` line
says `none`, store the title with the command that line gives. Unless the
output says `announce: no`, the **first reply opens with one line**:
`Conversation title: <title> — say "rename this conversation to …" to change it.`
Say it once per session and never again.
Act only on lines that ask for it, and stay quiet about anything clean:
- `git:` unsynchronized history (uncommitted changes, ahead/behind) → say so
and suggest `ckb-sync-changes`.
- `ckb check:` non-clean → report the line and suggest `ckb-lint`.
- `autosave:` / `start hook:` → ask once whether to change
`.claude/settings.local.json`; apply only on a yes. `ckb-add-conversation`
and `ckb-lint` own the details.
- `threads:` → mention the count in one line; pick a thread up only when the
user asks.
- `profile:` → follow it where this file and project rules leave room.
- `lessons:` → read the ones that bear on the request.
- `routines: DUE` → finish the user's request first; then, in the same turn,
perform each due routine's `do` as if asked, run `--mark <name>` once it
completes, and report it in one line. A `confirm: true` routine is asked
about at the end of the reply instead and runs only on a yes. A failed or
declined routine is not marked. Whenever a skill that some routine's `do`
names is run by hand, mark that routine too. `ckb-routine` owns the details.
Without Python, say so once and do the same by hand: `git status --short
--branch`, `bash .agents/skills/ckb-lint/scripts/lint_quick.sh` (or
`powershell -ExecutionPolicy Bypass -File .agents/skills/ckb-lint/scripts/lint_quick.ps1`
on Windows — four of the six quick checks, crux quotes and budget skipped), the last
block of the latest `workload/` note by filename date, and skip the routine
check.
At session end, update `workload/` and repeat the unsynchronized-change
check. Do not fetch or push unless the user asks. Then read
`conversations.autosave` in `ckb.yaml`:
- `true` — save the conversation with `ckb-add-conversation` without
asking, and report the saved path in one line.
- `false` or absent — when the session did real work (ingested, answered,
decided, changed files), ask once whether to save, the same way the sync
check is a suggestion and not an action. Skip the question for a trivial
session. Save only on a clear yes; never save on your own initiative.
### 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.