groundtruth-kb 0.4.0

Specification-driven governance toolkit for AI engineering teams

GroundTruth Knowledge DB

A specification-driven governance toolkit for AI engineering teams.

Track specifications, tests, work items, and architecture decisions with append-only versioning. Built for teams that need traceable, auditable engineering decisions.

At a Glance

Capability	Description
Specifications	Decision log for what the system must do
Tests	Verify implementation meets specifications
Work Items	Track gaps between specs and implementation
Architecture Decisions	ADR/DCL workflow for cross-cutting choices
Assertions	Continuously verify spec-implementation alignment
Governance Gates	Pluggable enforcement at lifecycle transitions

Tooling: CLI (gt), Web UI, Python API, project scaffolding, CI templates, process templates, dual-agent file bridge setup.

Architecture

Layer 3: Workstation Doctor    gt project doctor
Layer 2: Project Scaffold      gt project init / upgrade
Layer 1: Core Knowledge DB     gt init / seed / assert / serve
         File Bridge Setup     dual-agent coordination templates [optional]

See the product architecture for details.

Quick Start

# Install from PyPI
pip install groundtruth-kb

# Create a project with scaffolding
gt project init my-project --owner "Your Organization" --init-git

# Inspect the seeded knowledge base
gt --config my-project/groundtruth.toml summary

# Run assertions
gt --config my-project/groundtruth.toml assert

Web UI (requires [web] extra):

pip install "groundtruth-kb[web]"
gt --config my-project/groundtruth.toml serve
# Visit http://localhost:8090

Same-day prototype (includes example data):

gt bootstrap-desktop my-prototype --owner "Your Organization" --init-git

New to GroundTruth? Read The User Journey to see what building a product with GroundTruth looks like end-to-end. Then follow the getting started guide for a 10-step technical walkthrough.

Why?

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 provides the engineering discipline layer.

Status

This project is in early development. The toolkit is extracted from a production system managing 2,000+ specifications and 11,000+ tests.

Project scaffolding (gt project init), environment verification (gt project doctor), and scaffold upgrades (gt project upgrade) are available. Three profiles support different team configurations: local-only, dual-agent, and dual-agent-webapp.

Documentation

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

Reference: Assertion Language | Desktop Setup | Example Project

Getting Started

New to GroundTruth? The getting started guide walks you through setting up the core toolkit: install, init, first spec, first test, assertions, web UI, templates, and CI/CD — in 10 steps.

For a same-day client workstation setup, start with the desktop setup guide.

Process Templates

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.

Contributing

See CONTRIBUTING.md for how to contribute. We especially value feedback about the engineering method itself — tag issues with method-feedback.

License

AGPL-3.0

---

© 2026 Remaker Digital, a DBA of VanDusen & Palmeter, LLC. All rights reserved.