kb-framework-template

AI-native Knowledge Base Framework — a reusable template repository for building structured, version-aware, confidence-tagged knowledge bases that are consumed by AI agents.

Owner: René Sebastian Kaup (LinkedIn) Status: ✅ v1.0 functionally complete + Iteration 2 hardening. Architecture, governance, the interactive /kb-setup agent, the /import pipeline, the consistency gate, and the optional skills pipeline are all in place. Iteration 2 added a note scaffolder (/new-note), two more note types (troubleshooting, decision-record), five deeper structural gate checks, a self-test harness with CI, a committed sample instance (_examples/claude-code-kb), and a generic discovery-tools slot. Iteration 3 added a generalized self-audit framework (/kb-audit, Supervisor + two independent tracks, 6-dimension maturity model) and a generic human onboarding template (01-meta/ONBOARDING.md).

Verify it yourself

Fastest -- run the framework self-test (instantiates throwaway copies, asserts the gate passes on clean KBs and fails on injected drift):

pwsh ./tools/Test-Framework.ps1     # expect: RESULT: PASS -- N/N cases met expectation
                                    # (the kb-query case is SKIPPED unless Node + `npm ci` in tools/kb-query/)

Or instantiate into a throwaway copy and run the gate by hand:

1. Copy the repo (excluding .git) to a scratch folder.
2. Run /kb-setup (or call tools/Initialize-KB.ps1 with a kb-setup.config.json).
3. Run tools/Check-KBConsistency.ps1 -- it should report RESULT: PASS -- 0 blocking problems.

Or just gate the committed sample: tools/Check-KBConsistency.ps1 -RepoRoot ./_examples/claude-code-kb.

---

What this repository is

This repo is a domain-agnostic template. After running an interactive AI setup agent (/kb-setup), it can be adapted to any knowledge domain (e.g. a software platform, a product, a regulatory area) and then used to collect knowledge for AI agents.

It generalizes a mature, production-proven knowledge base into reusable framework machinery:

• Three-layer progressive-disclosure architecture — L0 routing → L1 domain MOCs → L2 atomic notes → L3 references
• Governance system — rules for adding/extending knowledge, a new-vs-extend decision tree, a glossary, an import pipeline
• Confidence tagging — every claim is source- and trust-tagged
• Front-matter contract — mandatory metadata on every artifact, mechanically gated
• Six note types — concept, how-to, reference, q-and-a, troubleshooting, decision-record (ADR)
• Note scaffolder — /new-note (tools/New-Note.ps1) writes correct front-matter + a MOC routing row for you
• Sprint methodology — board/ledger/decisions, lessons-learned, lifecycle checklist
• Claude Code integration — CLAUDE.md, slash-commands, skill-build pipeline
• Quality gates — consistency checker (17 checks under a stable fold-in numbering contract: front-matter, links, counters, duplicate ids, MOC paths, orphans, staleness, sprint-dossier completeness, human-review visibility, skill coverage, ...), commit-message hygiene, CI workflows
• Graph retrieval (optional) — tools/kb-query/ + /kb-query: serverless SPARQL over the front-matter graph (Oxigraph WASM, auto-rebuild, coverage manifest) for aggregation, related_notes traversal, confidence epistemics and time slices — with a routing rule that keeps lexical lookups on grep
• Self-test harness — tools/Test-Framework.ps1 proves the toolchain on every push (CI)
• Sample instance — _examples/claude-code-kb shows a real, gate-green KB with all six note types
• Discovery slot — tools/discovery/ generic skeleton for source-acquisition feeding /import
• Agent rig -- rig/ setup guides + assets for the optional machine-side tooling around a KB instance (MarkItDown file converter for /import, Playwright browser MCP, Outlook MCP)
• Human onboarding — 01-meta/ONBOARDING.md gentle end-to-end entry path for new colleagues (Git, gates, sprints, audits, sub-agent orchestration)
• Self-audit framework — 01-meta/governance/audits/ periodic maturity + quality review (/kb-audit: Supervisor + two independent tracks, 6-dimension CMMI model, read-only, evidence-based)

How it will be used (target flow)

1. Clone/use this template for a new knowledge domain.
2. (Optional) Pick a use-case profile. The profiles/ folder (see profiles/README.md) ships four ready overlay packs -- product-platform, second-brain, consulting, team-org -- each with a ready domain taxonomy + operating playbooks. Apply one with tools/Apply-Profile.ps1 -Profile <name>, then delete the rest. Or skip this and start fully generic. (profiles/ is optional + removable, so this README does not hard-link into it.)
3. Run the interactive setup agent (/kb-setup) — it interviews you (domain, sources, taxonomy; or uses your chosen profile's preset) and fills in all placeholders.
4. Start collecting knowledge using the /import pipeline and the governance rules. The rig/ folder documents the optional machine-side tooling that widens what /import and research sessions can do (file converter, browser MCP, mail/calendar MCP) -- install what your workflows need, or delete the folder.
5. Optionally build Claude Skills from the corpus, and -- for a product/platform KB whose subject system has a documented API -- a governed, read-only MCP so agents can query the live system alongside the static notes. The mcp/ folder is a guide only (mcp/README.md + mcp/GUIDE.md): it teaches how to build and extend one; it ships no code (the template is PowerShell/Windows-centric, an MCP is an optional Python/uv companion). Not needed for a personal or non-product KB -- delete mcp/ if so.

Editor tip: the KB is plain Markdown, so any editor works. Obsidian pairs well (optional, per-instance) — the template ships no .obsidian/ config; set one up yourself if you want it. See 01-meta/ONBOARDING.md J5.

Where this repository lives

GitHub is the leading copy: github.com/K4uP/kb-framework-template -- development, issues, releases. The framework is additionally mirrored to a private Azure DevOps project for consumers who do not work on GitHub. Both hosts carry identical history: the mirror is fed by a dual-push remote, so a single git push updates both and they cannot silently drift.

git remote set-url --add --push origin <leading-remote-url>
git remote set-url --add --push origin <mirror-remote-url>

The quality gates therefore exist twice and call the same scripts under tools/: .github/workflows/ on GitHub, azure-pipelines.yml on Azure DevOps. The CI files are thin wrappers -- the verdict lives in the scripts, so the two hosts can only differ in trigger plumbing, never in what passes. Two Azure-specific setup notes are documented in the header of the pipeline file: Microsoft-hosted agents need a parallelism grant on private projects, and PR validation must come from a Build Validation branch policy because Azure DevOps ignores the pr: key for Azure Repos. A KB instantiated from this template that lives on only one host can simply delete the other host's CI file.

---

License

This framework template is licensed under the MIT License — free to use, copy, modify, and distribute with attribution.

Scope note: the MIT license covers the reusable framework machinery in this repository only. Knowledge bases you create from this template are your own — their content and license are yours to choose (set {{LICENSE_KIND}} during /kb-setup and add a LICENSE to the instance).