A specification-driven governance toolkit for AI engineering teams.
Track specifications, tests, work items, and architecture decisions with append-only versioning. Coordinate two AI agents (Prime Builder + Loyal Opposition) through a file-bridge protocol. Built for teams that need traceable, auditable engineering decisions.
If you have never seen GroundTruth-KB before, start with docs/start-here.md. It assumes zero prior context and walks through everything from install to your first assertion on a Windows workstation with internet access.
Already a developer-preview adopter? Jump straight to:
-
CTO Evaluation Guide - pip install, dashboard, lifecycle, services, roles
-
Day in the Life — a synthetic first week
-
Evidence — live metrics, every row dated + pinned to a commit
-
Known Limitations — open gaps, stated plainly
-
Executive Overview — the business case
| Capability | Description |
|---|---|
| Specifications | Decision log for what the system must do |
| Tests | Verify implementation meets specifications |
| Assertions | Continuously prove spec-implementation alignment |
| Work Items | Track gaps between specs and implementation |
| Deliberation Archive | Searchable decision history with rejected alternatives |
| Governance Gates | Pluggable enforcement at lifecycle transitions |
| File Bridge | Asynchronous two-agent review via versioned markdown |
Tooling: CLI (gt), Web UI, Python API, project scaffolding,
CI templates, process templates, dual-agent file bridge setup.
# Install from PyPI (Windows workstation with internet access)
pip install groundtruth-kb
# Create a project with scaffolding
gt project init my-project --profile local-only --no-seed-example --no-include-ci
# Verify workstation readiness
cd my-project
gt project doctorWeb UI (requires [web] extra):
pip install "groundtruth-kb[web]"
gt serve
# Visit http://localhost:8090Operations dashboard (local Grafana + generated SQLite reporting DB):
gt dashboard init
gt dashboard install
gt dashboard start
# Visit http://127.0.0.1:3000/d/groundtruth-kb/groundtruth-kb-dashboardSame-day prototype (includes example data):
gt bootstrap-desktop my-prototype --owner "Your Organization" --init-gitSee Start Here for the full walkthrough, including a PowerShell primer for readers who have never opened a terminal.
flowchart TB
L1["Layer 1<br/>Core Knowledge DB<br/>gt init / seed / assert / serve"]
Bridge["Optional<br/>File Bridge Setup<br/>Prime Builder + Loyal Opposition"]
L2["Layer 2<br/>Project Scaffold<br/>gt project init / upgrade"]
L3["Layer 3<br/>Workstation Doctor<br/>gt project doctor"]
Azure["Opt-in<br/>Azure readiness envelope<br/>specs, ADRs, checks, evidence"]
L1 --> L2 --> L3
Bridge --> L2
L2 --> Azure
L3 --> Azure
See docs/architecture/product-split.md for the authoritative layer definitions.
AI-powered systems change fast. Without traceable specifications and assertions, teams lose track of what was decided, why, and whether the implementation still matches. GroundTruth-KB provides the engineering discipline layer.
This project is in early development (v0.6.1, developer-preview). The toolkit is extracted from a production system managing 2,000+ specifications and 11,000+ tests. See docs/known-limitations.md for current gaps.
Project scaffolding (gt project init), environment verification
(gt project doctor), and scaffold upgrades (gt project upgrade) are
available. The local operations dashboard (gt dashboard init/install/start)
generates Grafana provisioning and a dashboard SQLite database from the pip
package. Three profiles support different team configurations: local-only,
dual-agent, and dual-agent-webapp.
The method documentation describes the engineering discipline behind GroundTruth:
| Guide | Topic |
|---|---|
| 01 — Overview | Core workflow and governance model |
| 02 — Specifications | Writing and managing specifications |
| 03 — Testing | Test forms, outside-in testing, pipeline organization |
| 04 — Work Items | Gap tracking, stage lifecycle, prioritization |
| 05 — Governance | GOV specs, gates, assertions, protected behaviors |
| 06 — Dual-Agent | Prime Builder + Loyal Opposition collaboration |
| 07 — Sessions | Session IDs, wrap-up, audit cadence |
| 08 — Architecture | ADR/DCL/IPR/CVR workflow |
| 09 — Adoption | Upstream/downstream model, update procedures |
| 10 — Tooling | CLI commands, web UI, Python API, configuration |
| 11 — Operational Config | Bridges, automations, directives, roles |
| 12 — File Bridge Automation | Durable file bridge polling, prompts, plugins, skills, and scheduler capture |
| 13 — Deliberation Archive | Decision log with semantic search |
Reference: Assertion Language | Azure Readiness Taxonomy | Desktop Setup | Example Project
GroundTruth-KB keeps the default scaffold lightweight, then adds an opt-in Azure enterprise readiness path for SaaS teams that need buyer-grade cloud evidence.
flowchart LR
Starter["starter<br/>local-first default"]
Candidate["production-candidate<br/>Azure decisions recorded"]
Enterprise["enterprise-ready<br/>buyer evidence"]
Regulated["regulated-enterprise<br/>industry controls"]
Starter --> Candidate --> Enterprise --> Regulated
The full taxonomy is in docs/reference/azure-readiness-taxonomy.md. The wiki-ready summary lives at docs/wiki/azure-enterprise-readiness.md and is mirrored to the GitHub Wiki.
The templates/ directory contains reference templates
for setting up a GroundTruth project: rules files, state files, hooks, and
agent configuration, including a file bridge OS-poller setup prompt. Use
gt project init my-project --profile <profile> for automated setup, or
copy templates manually and customize the placeholders.
See CONTRIBUTING.md for how to contribute. We especially
value feedback about the engineering method itself — tag issues with
method-feedback.
© 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.