Skip to content

README.md

Latest commit

 

History

History
210 lines (137 loc) · 8.1 KB

README.md

File metadata and controls

210 lines (137 loc) · 8.1 KB

Kibi Wordmark

CI Coverage

Kibi is a repo-local, per-git-branch, queryable knowledge base for software projects. It stores requirements, scenarios, tests, architecture decisions, and more as linked entities, ensuring end-to-end traceability between code and documentation.

Entity Taxonomy

Kibi intentionally supports eight core entity types, organized into two logical groups:

Common Authoring Entities

  • req — Software requirements specifying functionality or constraints.
  • scenario — BDD scenarios describing user behavior (Given/When/Then).
  • test — Executable unit, integration, or e2e test cases.
  • fact — Atomic domain facts and invariants. Supports a strict lane for contradiction-sensitive modeling and a context lane (observation, meta) for bugs and workarounds.

Supporting & System Entities

  • adr — Architecture Decision Records documenting technical choices.
  • flag — Runtime or config gates (feature flags, kill-switches).
  • event — Domain or system events published/consumed by components.
  • symbol — Abstract code symbols (functions, classes, modules).

Why Kibi

Kibi is designed to boost AI agents' memory during software development. It maintains a living, verifiable project memory that:

  • Tracks context across branches — Every git branch gets its own KB snapshot, preserving context as you switch between features
  • Enforces traceability — Links code symbols to requirements, preventing orphan features and technical debt
  • Validates automatically — Rules catch missing requirements, dangling references, and consistency issues
  • Agent-friendly — LLM assistants can query and update knowledge base via MCP without risking file corruption

What You Get

Kibi provides concrete, day-to-day benefits for developers and teams:

  • Requirements Traceability — Track every code symbol back to its requirement. Know why code exists and what business need it addresses.

  • Test Coverage Visibility — See which requirements have tests, which don't, and what's covered at a glance. Ensure nothing slips through the cracks.

  • Architectural Constraints — Link code to ADRs. Know what constraints apply to each symbol and verify architecture decisions are honored.

  • Feature Flag Blast Radius — See what code depends on a runtime/config gate before toggling it. Understand the impact of enabling or disabling a feature.

  • Event-Driven Architecture — Map who publishes and consumes each domain event. Trace event flows and identify couplings across the system.

  • Branch-Local Memory — Every git branch keeps its own KB snapshot. Switch contexts without losing traceability or polluting other branches.

For OpenCode users, bootstrap an existing repo with `/init-kibi` (`kb_autopilot_generate`).

Entity Modeling Note: Use flag for runtime/config gates only. Document bugs and workarounds as fact entities with fact_kind: observation or meta. See Entity Schema and AGENTS.md for the canonical guidance.

Key Components

  • kibi-core — Prolog-based knowledge graph that tracks entities across branches
  • kibi-cli — Command-line interface for automation and hooks
  • kibi-mcp — Model Context Protocol server for LLM integration
  • kibi-opencode — OpenCode plugin that injects Kibi guidance and runs background syncs
  • kibi-vscode — VS Code extension for exploring the knowledge base

Prerequisites

  • SWI-Prolog 9.0+ — Kibi's knowledge graph runs on Prolog

Installation

The recommended way is to install kibi as project dev dependencies:

npm install --save-dev kibi-cli kibi-mcp

For detailed steps, global install alternatives, and troubleshooting, see detailed installation guide.

OpenCode Plugin

Add kibi-opencode to your project opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["kibi-opencode"]
}

OpenCode installs npm plugins declared in plugin automatically at startup.

VS Code Extension

The Kibi VS Code extension provides a TreeView explorer for your knowledge base and built-in MCP integration.

Download the latest .vsix from GitHub Releases, then install it:

  • Command Palette: Ctrl+Shift+P → Extensions: Install from VSIX... → select the file
  • CLI: code --install-extension kibi-vscode-x.x.x.vsix

Every GitHub release includes the latest VS Code extension build as a .vsix artifact.

Repo-local dogfood workflow (this repo)

For contributors to this repository only:

This repository uses local built kibi-mcp and kibi-opencode artifacts during development. If you change package versions or local package wiring used by the OpenCode setup here, rebuild before testing:

bun run build

VS Code MCP

Create .vscode/mcp.json:

{
  "servers": {
    "kibi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kibi-mcp"]
    }
  }
}

For complete installation steps and SWI-Prolog setup, see detailed installation guide.

Quick Start

Initialize kibi in your repository:

# Verify environment prerequisites
npx kibi doctor

# Initialize .kb/ and install git hooks
npx kibi init

# Parse markdown docs and symbols into branch KB
npx kibi sync

# Discover relevant knowledge before exact lookups
npx kibi search auth

# Inspect current branch snapshot and freshness
npx kibi status

# Run integrity checks
npx kibi check

Note: kibi init installs git hooks by default. Hooks automatically sync your KB on branch checkout and merge.

Typical discovery workflow

# Explore the KB first
npx kibi search login

# Then follow up with exact/source-linked queries
npx kibi query req --source src/auth/login.ts --format table

# Check branch attachment and freshness when needed
npx kibi status

# Ask focused reporting questions
npx kibi gaps req --missing-rel specified_by,verified_by --format table
npx kibi coverage --by req --format table

Documentation

Release and Versioning

Kibi uses a two-branch release model with Changesets. Work happens on develop, where version bumps are applied. The master branch is publish-only.

Release Flow

  1. Development: Create changesets on develop as you work.
  2. Versioning: Run bun run version-packages on develop to apply bumps.
  3. Merge: Merge develop into master.
  4. Publish: master CI builds and publishes new versions to npm.

There is no master → develop back-merge.

# Add release metadata (run on develop)
bun run changeset

# Apply version bumps (run on develop)
bun run version-packages

⚠️ Alpha Status: Kibi is in early alpha. Expect breaking changes. Pin exact versions of kibi-cli, kibi-mcp, and kibi-opencode in your projects, and expect to occasionally delete and rebuild your .kb folder when upgrading.