Llm Wiki Governance

> Language: [English](./README.md) | [한국어](./README.ko.md)

LLM-WIKI Governance

Governance for AI-written project docs. llm-wiki-governance is a zero-dependency CLI that keeps an AI coding agent's project knowledge (docs/llm-wiki/) trustworthy and current: it ties every claim to real code, flags docs when that code moves on, keeps AI-written content behind human review, and enforces all of it in CI. Works on any stack, with any agent, and is OKF-compatible.

Why a governance layer?

An LLM wiki — a distilled, interlinked knowledge base an agent reads instead of re-deriving your codebase on every task — is a proven pattern (popularized in 2026, and formalized by Google's Open Knowledge Format). The hard part was never making one. It's keeping it honest.

| Approach | How the agent gets context | The catch | | --- | --- | --- | | RAG | Re-retrieves and re-derives from source on every query | Repetitive, costly, no shared source of truth | | Plain LLM wiki (a Markdown folder, e.g. an OKF project) | Reads a hand-written knowledge base | Goes stale silently → a doc that lies | | Governed LLM wiki (this tool) | Reads the same wiki — but verified, drift-checked, CI-enforced | — |

What "governed" means here:

• Trust states — AI-written docs stay needs_review; only a human promotes to verified. The CLI can never self-approve.
• Evidence + drift — each claim links to a real file/line/symbol; when that source changes, evidence.stale / drift flags the doc for re-review.
• CI-enforced — validate runs in pre-commit / GitHub Actions, so an unreviewed or drifted wiki fails the build instead of rotting quietly.
• Agent-queryable — a read-only MCP server lets agents ask the wiki instead of re-scanning the code.
• Safe by construction — preview-first writes, append-only change log, sensitive-value redaction, and zero runtime dependencies.

Without:  task -> re-scan the codebase -> re-derive structure & rules -> work
With:     task -> read index.md -> read the relevant (verified) wiki docs -> inspect only the source you need -> work

The CLI builds the structure and guardrails; an agent enriches the docs from real code; a human approves verified; CI keeps it honest. Useful for legacy maintenance, feature work, incident response, onboarding, handovers, and sharing project knowledge across agents.

Supported environments

| | | | --- | --- | | Runtime | Node.js ≥ 18.18.0 · Windows, macOS, Linux | | Dependencies | none — no runtime third-party dependencies | | Detects | Node · Python · Go · Rust · JVM · PHP · Ruby · .NET · mobile (Android / Flutter / iOS / React Native) · infra (Docker / Compose / Kubernetes / Helm / Terraform) | | Standards | OKF-compatible — --profile okf-v0.1 validates Open Knowledge Format type/aliases/tags; the core validator accepts OKF type as an alias for doc_type | | Agents / editors | Codex (AGENTS.md), Claude Code (CLAUDE.md), Cursor, GitHub Copilot, Windsurf, Gemini CLI — plus any MCP client via llm-wiki mcp | | Standalone | the CLI (init / validate / audit / graph / stats / CI) works fully without any agent |

Quick start

npm install -D llm-wiki-governance
npx llm-wiki quickstart --write --type frontend --agent claude   # or --agent codex

quickstart --write detects the project, creates the wiki + adapter files, and prints a handoff prompt. Paste that prompt into your agent: it reads docs/llm-wiki/index.md, enriches the docs from real source files, and leaves everything needs_review for you to approve. Preview first with quickstart --dry-run.

Add --skills (or --agent claude|cursor) to also generate invocable, wiki-grounded automation prompts — a Claude skill (/llm-wiki-feature), a Cursor rule, and an agent-neutral prompt — for ongoing feature/fix/docs-sync work, each carrying a snapshot of your project's domain map.

Already have an OKF (or plain Markdown) knowledge folder? Point the CLI at it to add verification, drift detection, and CI without changing the format — --profile okf-v0.1 treats it as first-class.

Recommended agent & model

The CLI needs no model. Only the enrichment step — an agent reading code and writing accurate, source-backed docs — does, and that is where model quality matters most.

| Task | Model tier | | --- | --- | | Wiki enrichment (write/refresh docs from code) | Your agent's strongest reasoning/coding model (e.g. a Claude Opus-class model, a high-reasoning GPT-5-class model, or each tool's top coding model). Accuracy and low hallucination matter here. | | Routine upkeep (docs-sync of small changes, running validate/status) | A mid-tier or economical model is fine. | | The CLI itself (init, validate, audit, graph, stats, mcp server) | No model — pure Node, runs anywhere and in CI. |

The llm-wiki mcp server is deterministic (no model); the agent calling its tools can be any model, following the same enrichment guidance.

Core commands

| Command | What it does | | --- | --- | | quickstart --write | Set up the wiki + adapter, print the agent handoff prompt (--skills also generates automation skills). | | validate | Structure & safety validation for local checks / CI (--strict, --changed). | | audit · status | Full findings report · current wiki state. | | graph · stats | Knowledge graph (text/JSON/Mermaid/DOT) · health snapshot (verified % / enrichment % / evidence coverage). | | drift · fix · migrate | Drift detection & downgrade · scoped safe autofix · contract upgrade (all preview-first). | | handoff · prompt | Agent handoff prompt · repeatable task prompts (feature/fix/refactor/docs-sync/okf-extract). | | mcp | Run the read-only MCP server (see below). |

Full command, option, exit-code, and programmatic-API reference: run npx llm-wiki help (offline), or see PUBLIC_API.md.

Governance in practice

• Verify deliberately. Agent-written docs stay needs_review; a human promotes to verified after reading them. Nothing the CLI does can bypass that.
• Catch drift early. Every doc cites source_files / precise evidence; when those change, evidence.stale and drift flag the doc. Run drift --downgrade to flip stale verified docs back to needs_review.
• Keep it current in the same change. Update the wiki alongside the code (prompt --task docs-sync, or the docs-sync skill), and run validate --changed in pre-commit / CI.
• Let agents self-serve. Point your agent at the mcp server so it queries the wiki as tools instead of re-scanning the code.
• Wire up CI. Copy templates/github-actions/llm-wiki-validate.yml to run validate on every PR, or reference the composite action in one step — uses: Dowon-Kim7949/llm-wiki-governance/.github/actions/validate@v1.7.0 (pin an exact tag).
• Make it readable. graph --format mermaid, stats, and audit --format html help humans see the corpus; it stays Markdown-in-git (renders on GitHub/GitLab, Obsidian, MkDocs — not a static-site generator).

Agent-native (MCP)

llm-wiki mcp runs a Model Context Protocol server over stdio (newline-delimited JSON-RPC 2.0, Node built-ins only — no third-party SDK). Register it in an MCP client:

{ "mcpServers": { "llm-wiki": { "command": "npx", "args": ["-y", "llm-wiki-governance", "mcp"] } } }

It exposes read-only tools — validate, audit, next, status, doctor, stats, graph, explain, handoff, prompt — so an agent can inspect the wiki but never write it. Details: PUBLICAPI.md · [GATEREVIEW.md](./GATE_REVIEW.md) (Gate 11).

Use it from code

Import the package instead of shelling out — handy for CI wrappers, editor integrations, and tests:

import { commands, normalizeOptions, run } from "llm-wiki-governance";

const r = await commands.audit(normalizeOptions({ cwd: process.cwd() }));
// r.command, r.result, r.findings, r.schemaVersion

const code = await run(["validate", "--strict"]); // 0 pass / 1 error / 2 blocked / 3 usage

--format json output carries a top-level schemaVersion so wrappers can pin the contract. Full API in PUBLIC_API.md.

Safety at a glance

Preview-first everywhere (writes only with --write / --apply); verified is human-only in every command; docs/llm-wiki/log.md and existing adapter files are never overwritten; sensitive-looking values are never printed or written; no runtime third-party dependencies. Full scope decisions: [GATEREVIEW.md](./GATEREVIEW.md).

Learn more

• PUBLIC_API.md — full command / option / exit-code / configuration / programmatic-API / MCP reference.
• [GATEREVIEW.md](./GATEREVIEW.md) — accepted safety scopes (fix / migrate / drift / MCP / skills) and release gates.
• [ROADMAP.md](./ROADMAP.md) — direction and shipped history.
• EXAMPLES.md — worked examples · [RELEASECHECKLIST.md](./RELEASE_CHECKLIST.md) — maintainer release steps.
• Community: [CONTRIBUTING.md](./CONTRIBUTING.md) · [CODEOFCONDUCT.md](./CODEOFCONDUCT.md) · [SECURITY.md](./SECURITY.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dowon-Kim7949
• Source: Dowon-Kim7949/llm-wiki-governance
• License: MIT
• Homepage: https://www.npmjs.com/package/llm-wiki-governance

Install and usage instructions live in the source repository linked above.