@dzangolab/repokb

CLI tool that drops a knowledge base into a project: a knowledge/ directory in Open Knowledge Format (OKF) v0.2, five Claude Code skills that read from and write to it, and a REPOKB.md the project's AGENTS.md imports so every session consults it.

The code is the source of truth for what the system does. The knowledge base is the source of truth for why, how we learned it, and what to watch out for.

Usage

Requires Node.js 20.12 or later. Run it from the root of the project you want to document - nothing to install:

npx @dzangolab/repokb init

To get the repokb binary on your PATH instead:

npm install -g @dzangolab/repokb
repokb init

Scaffolding a knowledge base

repokb init asks where the knowledge base should live, defaulting to knowledge/, then writes four things: the bundle itself, the five skills as a repokb plugin under .claude/skills/repokb/, a REPOKB.md at the project root referenced from the project's AGENTS.md as @REPOKB.md (with CLAUDE.md importing @AGENTS.md, so Claude Code picks it up), and a .gitignore inside the knowledge base keeping _log/ out of version control.

REPOKB.md holds the instructions rather than injecting them into AGENTS.md, so updating them is a file replacement instead of a merge into a file you own.

repokb init

| Option | Effect | | ------------------ | ------------------------------------------------------------------------------- | | -d, --dir <name> | Directory to hold the knowledge base. Default knowledge, and skips the prompt | | -b, --bootstrap | Hand off to Claude Code when the scaffolding is done, skipping the prompt | | --no-bootstrap | Scaffold only, and never hand off | | -h, --help | Show help for the command | | -V, --version | Print the version (on repokb itself) |

repokb init --dir second-brain

The name must be a single directory name - no path separators, not . or .., not wiki (used inside the bundle), and not starting with _ (which marks an operational directory). Every template reference is rewritten to match the name you choose, so --dir second-brain produces skills that talk about second-brain/, not knowledge/.

Resyncing a knowledge base

repokb resync finds the knowledge base in the current directory, installs any skill the project does not have yet - so a knowledge base scaffolded by an older version gains /repokb:resync - and hands off to Claude Code to run it. Skills already present are kept as they are.

repokb resync

| Option | Effect | | ------------------ | ------------------------------------------------------------------------- | | -d, --dir <name> | Directory holding the knowledge base. Default: detected | | --handoff | Hand off to Claude Code when the skills are in place, skipping the prompt | | --no-handoff | Install missing skills only, and never hand off | | -h, --help | Show help for the command |

Detection looks for a top-level directory holding an index.md with okf_version and an AGENTS.md. Pass --dir when there is more than one.

The skills

repokb init installs all five as a single Claude Code plugin, so they share the repokb namespace and are invoked as /repokb:<skill>:

.claude/skills/repokb/
  .claude-plugin/plugin.json
  skills/
    load/ init/ resync/ ingest/ ingest-conversation/

Claude Code discovers the plugin when a session starts - restart any session that was already running before repokb init.

/repokb:load - read the knowledge base

Loads the index hierarchy first, then only the concepts that matter, and reports the trust and freshness of everything it loaded.

| Invocation | Loads | | ------------------------------- | --------------------------------------------------------------- | | /repokb:load | Indexes plus the orientation set, from wiki/ | | /repokb:load <topic> | Indexes, then everything relevant to <topic> | | /repokb:load --section <name> | Every concept in one section, e.g. --section architecture | | /repokb:load --full | Every concept document in the bundle, _sources/ included | | /repokb:load --audit | Health report only: staleness, trust, index drift, broken links |

Use it at the start of a session, before answering questions about how the repo works, and before changing an unfamiliar part of it.

/repokb:init - bootstrap from the repository

Run once, after scaffolding. Researches the codebase in three passes - map the surfaces, trace representative end-to-end flows, then verify against tests and history - and writes concept documents across every section the code supports: architecture, components, CI, security, operations, local setup, conventions, troubleshooting and the rest. Every material statement is cited to a repo://path#L12-L48 span, and you are asked only what the code genuinely cannot answer. It writes as soon as it has a plan - the bundle is empty, so there is nothing to overwrite, and every page it writes is a draft until a human reviews it.

| Invocation | Effect | | ------------------------------- | -------------------------------------------------------------------- | | /repokb:init | Research, plan, write | | /repokb:init --dry-run | Produce the plan and stop; write nothing | | /repokb:init --section <name> | Bootstrap one section only, e.g. --section ci | | /repokb:init --depth <level> | How far the tracing pass goes: deep (default), standard, quick | | /repokb:init --no-questions | Never ask - open questions are written into the documents instead |

/repokb:resync - bring the wiki back in line with the code

Run whenever the code has moved on. Re-explores the repository and compares it with the wiki in two ways. Each page's generated.at is its baseline, and git shows what changed in the files it cites since then. Separately, the surfaces /repokb:init would map are checked against every cited path, to find systems no page covers. Each page is then left alone, has its citations re-anchored, is corrected, or is deprecated, and uncovered systems get new draft pages.

It changes a page only on evidence that its code changed, edits in place rather than regenerating, and carries forward the rationale the code cannot recover. Pages that are human-reviewed or human-written are never edited directly - the change is proposed with its evidence and applied only once you confirm it. _sources/ is out of scope: re-run /repokb:ingest to refresh external material.

| Invocation | Effect | | --------------------------------- | ------------------------------------------------------------------- | | /repokb:resync | Detect, research, plan, write | | /repokb:resync --dry-run | Produce the drift report and plan; write nothing | | /repokb:resync --section <name> | Resync one section only, e.g. --section ci | | /repokb:resync --since <ref> | Use a git ref as the baseline for every page, e.g. --since v0.4.0 | | /repokb:resync --no-questions | Never ask - proposals for reviewed pages are reported, not applied |

/repokb:ingest - pull in external material

Extracts a source, distills it into concept documents under knowledge/_sources/external/, archives the original in knowledge/raw/, and updates the affected index.md and the day's log file.

| Invocation | Effect | | ----------------------------------------------- | ------------------------------------------------------ | | /repokb:ingest <url> | Web page or online document | | /repokb:ingest <path> | Local file: pdf, docx, image, md, txt, csv, video | | /repokb:ingest <path-or-url> --into <section> | Route to a section other than _sources/external | | /repokb:ingest <url> --deep | Follow and ingest linked sub-pages of a doc site | | /repokb:ingest <path> --verbatim | Also keep a full extraction alongside the distillation |

An ADR is archived verbatim under knowledge/raw/adrs/ whatever its status, and stays there - the record itself never becomes a wiki document. Only a decided one - accepted, rejected, deprecated, or accepted - is then distilled into _sources/, with the wiki concepts it bears on updated to match. An ADR still under discussion is archived and nothing else, so the wiki never presents a proposal as settled.

/repokb:ingest-conversation - capture a working session

Distills what a session established - decisions made, constraints discovered, bugs diagnosed, approaches ruled out - into concept documents, and writes a session record under knowledge/_sources/conversations/. The conversation itself is archived as verbatim as it can be under knowledge/raw/conversations/, named to match its session record, so the exact wording survives the distillation.

| Invocation | Effect | | -------------------------------------------- | ------------------------------------------------------------------------ | | /repokb:ingest-conversation | Triage the whole session and write what is durable | | /repokb:ingest-conversation <focus> | Only what relates to <focus> | | /repokb:ingest-conversation --dry-run | Show the triage and proposed routing, write nothing | | /repokb:ingest-conversation --session-only | Write only the transcript and session record, skip promoting to concepts |

What gets scaffolded

knowledge/
  index.md          # bundle root - table of contents, carries okf_version and repokb_version
  .gitignore        # keeps _log/ out of version control
  AGENTS.md         # the authoring contract every writer reads first
  CLAUDE.md         # imports AGENTS.md for Claude Code
  wiki/             # what this repository knows about itself
    architecture/ ci/ components/ conventions/ domain/
    local/ operations/ reference/ security/ troubleshooting/ ui/
  raw/              # originals behind ingested material - human-only
    images/ pdfs/ documents/ adrs/ conversations/ others/
  _log/             # change history, one file per day - git-ignored
  _sources/         # ingested external material
    external/ conversations/

Every concept document carries OKF provenance and trust metadata, and /repokb:load reports it on every load: status: draft means inferred rather than confirmed, a missing verified key means nobody has checked it, and a past stale_after means possibly out of date.