DESIGN:OS Knowledge Builder (design-os-knowledge-builder)

Ontology-first knowledge packs: claims with verifiable sources, and a ledger-backed stopping gate.

Freeze web pages and documents as sources, promote evidence into claims that quote them, and let verify check every quote against the frozen file. An agent skill (skills/es-knowledge-forge/) teaches Claude Code, Codex, Gemini CLI, and Antigravity the workflow.

---

Why this exists

Raw RAG chunks and scraped markdown files pollute agent context windows with unverified claims, missing provenance, and prompt-injection risks. design-os-knowledge-builder compiles raw sources into structured knowledge packs (UKMC.v2, with UKMC.v1 still supported) where a claim is only as good as the quote and hash that back it, and where a research run stops only when its ledger says it is enough. This repository stores no topic files. Packs live in an external knowledge root you choose (<knowledge-root>/<domain>/<topic>), apart from the tool.

Dimension	Generic AI / Manual Workflow	DESIGN:OS Knowledge Builder (DESIGN:OS)
Provenance & Trust	Unattributed markdown scrapes with zero hash verification	Mandatory source_attribution (uri, sha256, license, trust_tier) on every node
Prompt-Injection Safety	External web text mixed directly into system instructions	Explicit quarantine.is_external_untrusted isolation and sanitization
Failure Prevention	Happy-path notes that omit edge cases	Mandatory ## When to Use / When NOT and >= 5 concrete ## Failure Modes per node
Context Efficiency	Monolithic dumps that blow the 200k context window	Progressive disclosure (SKILL.md router -> domain index -> leaf node)
Privacy & Telemetry	Opaque cloud telemetry or unverified third-party APIs	Zero telemetry — 100% local execution (PRIVACY.md audited)

---

Quickstart

1. Install the plugin or CLI

In Claude Code:

/plugin marketplace add jangtrinh/design-os-knowledge-builder
/plugin install design-os-knowledge-builder@design-os-knowledge-builder

Or from your terminal (Codex, Gemini CLI, Antigravity, OpenCode, or standalone CLI):

git clone https://github.com/jangtrinh/design-os-knowledge-builder.git
cd design-os-knowledge-builder
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
python3 -m knowledge_builder.cli --help
# Or run directly from the checkout without installing:
PYTHONPATH=src python3 -m knowledge_builder.cli --help

2. Ask in plain English

Open your project in your AI coding agent and describe what you need:

"Build an ontology-first knowledge pack on : freeze the sources, promote claims, cite them from a document, then run the stopping gate."

"Check this knowledge pack: run verify --claims and pack check, and list the claims no document cites."

"Add a claim to this pack from a verified evidence atom and cite it in the concept document."

3. Verify your setup

python3 scripts/self_check.py

---

What it makes

Every pack is checked by deterministic commands (verify, pack check, gate) rather than by an agent's say-so.

Deliverable	Best for	Output	Check
Ontology-first pack	Domain knowledge where every claim must quote a frozen source	ontology.yaml, claims/, sources/, documents, _evidence/<run>/	pack check (verify --claims + stopping gate)
Index and object sets	Letting an agent query a pack instead of re-reading it	index.json, query results	index refuses a stale index
Agent skill	Teaching an agent to build and check packs	skills/es-knowledge-forge/	python3 scripts/self_check.py

---

Installation

Choose the setup that matches your AI coding agent. Every option installs the same canonical skill (skills/es-knowledge-forge/SKILL.md) and /doctor diagnostic suite.

Claude Code

Run these two commands inside Claude Code:

/plugin marketplace add jangtrinh/design-os-knowledge-builder
/plugin install design-os-knowledge-builder@design-os-knowledge-builder

OpenAI Codex

Install to your personal Codex skills directory:

git clone https://github.com/jangtrinh/design-os-knowledge-builder.git /tmp/design-os-knowledge-builder
mkdir -p ~/.codex/skills/es-knowledge-forge ~/.codex/prompts
cp -R /tmp/design-os-knowledge-builder/skills/es-knowledge-forge/* ~/.codex/skills/es-knowledge-forge/
cp /tmp/design-os-knowledge-builder/prompts/doctor.md ~/.codex/prompts/es-knowledge-forge-doctor.md
rm -rf /tmp/design-os-knowledge-builder

Gemini CLI & Google Antigravity

git clone https://github.com/jangtrinh/design-os-knowledge-builder.git /tmp/design-os-knowledge-builder
mkdir -p ~/.gemini/skills/es-knowledge-forge
cp -R /tmp/design-os-knowledge-builder/skills/es-knowledge-forge/* ~/.gemini/skills/es-knowledge-forge/
rm -rf /tmp/design-os-knowledge-builder

OpenCode, Cursor, Windsurf & Other Agent Harnesses

git clone https://github.com/jangtrinh/design-os-knowledge-builder.git /tmp/design-os-knowledge-builder
mkdir -p ~/.agents/skills/es-knowledge-forge
cp -R /tmp/design-os-knowledge-builder/skills/es-knowledge-forge/* ~/.agents/skills/es-knowledge-forge/
rm -rf /tmp/design-os-knowledge-builder

The skill is a plain folder: SKILL.md routes, rules.md, concepts.md and look.md hold the judgment, and build.py, validate.py and look.py do the mechanics with the Python standard library only. They call the knowledge_builder tool, so either keep a checkout next to the skill, pass --repo-root <checkout>, or run python3 -m venv .venv && . .venv/bin/activate && pip install -e . from the checkout. A copied skill is a snapshot: re-copy it after you update the repository.

This is the beginning of the README. Read the rest at the original. Read the full README ↗