Quick start

This page takes you from an empty repository to a bootstrapped, validated project model. It assumes you have a coding agent you can prompt (Claude Code, Cursor, Codex, OpenCode, VS Code, and other MCP clients all work) and commit access to the repository.

Kibi is meant to be run by your agent, not by hand, so the recommended setup is one prompt. The manual commands are still there if you want them.

1. Check the prerequisites

Kibi runs on Node.js 22+, and its deterministic checks run on SWI-Prolog. SWI-Prolog ships with Kibi as a per-platform npm package, so on Linux (x64 or arm64, glibc 2.28+) and macOS (Apple silicon or Intel) there is nothing else to install; the setup brings it along.

On other platforms, such as Alpine (musl) or native Windows, install SWI-Prolog 9.0+ yourself and make sure swipl is on your PATH (on Windows, running Kibi inside WSL uses the bundled build). Platform instructions, the KIBI_SWIPL override, and what to do if an install skipped the bundled runtime are in the installation guide.

2. Paste the setup prompt into your agent (recommended)

From your repository, give your coding agent this prompt:

Set up Kibi (https://github.com/Looted/kibi) in this repository, then bootstrap its knowledge base.

1. Install: confirm Node.js 22+ is available. With the package manager this repository already uses, add kibi-core, kibi-cli and kibi-mcp as dev dependencies. Do not skip optional dependencies; the bundled SWI-Prolog runtime is one.
2. Initialize: run every `kibi` command through the package manager's local runner (npm: `npm exec -- kibi <command>`). Run `kibi init`; if it reports a problem, run `kibi doctor` and fix what it names. If this platform has no bundled SWI-Prolog, tell me what to install and stop.
3. Connect: register the project-local `kibi-mcp` server for the agent host you are running in, following https://looted.github.io/kibi/guide/connect-an-agent.html. Prefer project-scoped configuration, and ask me before installing a plugin or changing global settings. Until the kb_* tools are visible to you, use Kibi's CLI JSON routes instead.
4. Bootstrap: run `kibi skills load kibi-bootstrap --format markdown` and follow that skill exactly. It starts by asking me where product intent lives outside the code (issue trackers, wikis, specs) and which sources to trust; read them through the connectors you have and cite them. Show me the complete plan and its hash, and write nothing until I approve it.
5. Verify: run `kibi check` and `kibi status`, fix anything they report, and summarize what was added. Do not commit; I will review the changes.

The agent installs kibi-core, kibi-cli, and kibi-mcp with your package manager, runs kibi init to create the .kb/ layout and the Git hooks that keep it synchronized, and registers Kibi's MCP server for itself. Re-running kibi init completes missing directories and schema files while preserving existing knowledge and schema files. A hook you already have is never edited. With a hook manager (lefthook, husky, the pre-commit framework), kibi init installs no hooks and prints the configuration to add; kibi init --print-hook all --format lefthook prints it again, as the installation guide shows. It also writes a Kibi section into AGENTS.md (imported from CLAUDE.md) and a package.json prepare step that installs the hooks, so a fresh clone of the repository, by a teammate or a cloud agent, is told about Kibi and gets the hooks on its first install; its first Kibi query compiles the branch's store. Each of these is a setup choice you can turn off. Some agents only see new MCP tools after a restart; until then they use the same operations through the CLI.

Next it interviews you. Code shows what the software does but rarely why, so the agent asks where product intent already lives (issue trackers such as Jira or YouTrack, wikis, specs, decision logs), which of those sources are authoritative and which are stale, and what it cannot reach yet. It reads the sources through the connectors it has, then combines what they say with what it finds in the codebase into a read-only bootstrap plan. Each requirement taken from a source cites the ticket or page it came from. Nothing is written until you approve it: the agent shows you the complete plan and its hash, you approve, and it applies the plan in one audited step, then validates the result. It then deepens the result in the normal Kibi workflow: it authors claims the plan could not write, proposes scenarios from acceptance criteria and models predicates for the new requirements.

npm install --save-dev kibi-core kibi-cli kibi-mcp
npm exec -- kibi init

3. Approve the bootstrap plan

Read the plan the agent shows you. Check that requirements cite the sources you trust, answer any remaining questions the planner raises, and correct any product call it got wrong before you approve. Kibi never contacts your tracker or wiki itself; it records what the agent read and binds it into the plan's hash.

Bootstrap plans bind approval to the current workspace and KB snapshot, including the journal generation and revision. A changed KB requires a new plan and matching approval. How the planner picks candidates and how a large plan is applied, tracked and resumed after an interruption are covered under kb_plan_bootstrap and kb_apply_plan.

4. Look at the proof state

After bootstrap, ask your agent for the health report — or run it yourself:

npm exec -- kibi report --open

You get a self-contained HTML page. The headline is a count, such as "0 of 12 current requirements fully tested end-to-end." An honest zero on day one is a successful report: it exists to make gaps explicit. Read the health report explains the rows.

5. Work normally

From here, prompt as usual. Ask for features, fixes, refactors. Your agent keeps the requirements, scenarios, tests, and code links in step with the code, and Kibi's validation gates run in the background on every change. Useful manual commands:

npm exec -- kibi status   # branch, snapshot freshness, migration state
npm exec -- kibi search login
npm exec -- kibi gaps req --format table

Upgrading

After you update the Kibi packages, ask your agent to run kibi migrate, or run it yourself. It shows a plan and its hash and changes nothing; kibi migrate --apply-safe --approved-plan-hash <hash> applies the automatic steps you approved. Everything Kibi cannot decide for you, such as an exception nobody has approved or two requirements that supersede each other, stays in the plan as a review item. What each KB schema version changes is listed under kibi migrate in the CLI reference.

Next steps

• Connect your coding agent — per-client configuration.
• Modeling requirements — how intent becomes structured knowledge.
• Publish requirement health — put the report and badge on GitHub Pages.