TRUGS — Traceable Recursive Universal Graph Specification

Maintained by: TRUGS LLC

What is TRUGS?

TRUGS is a JSON graph specification for representing structured information. A TRUG is a JSON file with three components:

1. Nodes — typed things (functions, pages, chapters, tasks, parties)
2. Edges — named relationships between things (feeds, governs, depends_on)
3. Hierarchy — organization via parent/child containment using metric levels

CORE + BRANCH = Complete TRUG. CORE defines the universal structure every TRUG must satisfy. BRANCHES define domain-specific vocabularies.

flowchart LR
    S["TRUG/L sentence<br/>(233 words)"] <-->|compile/decompile| G["TRUG graph<br/>(nodes · edges · hierarchy)"]
    G -.validates against.-> C["CORE<br/>(7 boundaries · 16 rules)"]
    G -.extends.-> B["BRANCH<br/>(domain vocabulary)"]

Loading

The sentence IS the program. The graph IS the AST. Every valid TRUG/L sentence compiles to a graph losslessly, and every graph decompiles back to a sentence.

Install

pip install trugs

As of 2.0.0 (breaking), trugs ships the specification only — no CLIs. Spec content (CORE, TRL vocabulary, reference papers) is packaged as data. The 2.0.0 release also adds 21 SI level prefixes (YOTTA…YOCTO) as a new part of speech for hierarchy transition markers — see SPEC_vocabulary.md §9. For the tg CLI and all tooling, install the sibling package:

pip install trugs-tools    # provides the `tg` binary (36 operations)
tg --help

See TRUGS-LLC/TRUGS-TOOLS for the unified tg CLI — validation, memory, compliance, AAA protocol, and more.

Migrating from trugs 1.x? The pre-2.0 package shipped tg validate, tg memory, etc. as entry points. In 2.0.0 those move to trugs-tools. Migration is one additional install: pip install trugs-tools and every tg <op> command works identically.

TRUGS Language

TRUGS includes a formalized subset of English — 233 words drawn from computation, law, and SI prefixes — where every valid sentence compiles to a TRUG graph and every graph decompiles back to a sentence. Losslessly.

PARTY system SHALL FILTER ALL ACTIVE RECORD
  THEN SORT RESULT
  THEN WRITE RESULT TO ENDPOINT output
  OR RETRY BOUNDED 3 WITHIN 60s.

Every word is from the vocabulary. The sentence IS the program. The graph IS the AST.

See TRUGS_LANGUAGE/ for the complete specification.

Specification

Document	Description
CORE.md	7 boundaries, 10 primitive classes (~131 primitives), 16 validation rules, composition type system
BRANCHES.md	Domain-specific vocabularies (Python, Web, Writer, Knowledge, etc.)
SPEC_fundamentals.md	Core concepts and structure
SPEC_validation.md	Validation rules with implementations
SCHEMA.md	JSON schema reference

Language

Document	Description
SPEC_vocabulary.md	233 words, 9 parts of speech, formal definitions
SPEC_grammar.md	BNF grammar, composition rules, 12 validation rules
SPEC_examples.md	30 parsed examples across 13 patterns
language.trug.json	The opening TRUG — the language defining itself

Tools — via trugs-tools

All operations below use the unified tg CLI from the sibling trugs-tools package (pip install trugs-tools). 36 operations under 21 top-level verbs + 3 sub-namespaces.

Verb	Usage	Description
tg validate	tg validate <file>	Enforces all 16 CORE rules
tg validate	tg validate --all <dir>	Batch validation
tg get	tg get <file> <node_id>	Read a node
tg update	tg update <file> <node_id> --set key=value	Update a node
tg delete	tg delete <file> <node_id>	Delete a node and its edges
tg unlink	tg unlink <file> --from X --to Y	Remove an edge

See SPEC_cli.md in the trugs-tools repo for the full command surface.

Legacy (trugs 1.2.x only): the same operations were available as python tools/validate.py, python tools/tget.py, etc. in the 1.x tools/ directory; that directory was removed at trugs 2.0.0 — use the tg CLI from trugs-tools instead.

Examples

The EXAMPLES/ directory contains sample TRUGs for 7 domains at varying complexity levels. All 7 examples pass validation.

This repo, as a TRUG

This repository describes itself as a TRUG. folder.trug.json at the repo root is the machine-readable index — every top-level folder, every reference document, every public tool has a node, with typed edges to the specs and standards it implements or describes.

# What's in this repo?
tg ls .

# What does the language-graph builder implement (and what tests it)?
tg get folder.trug.json tools_build_language_trug --edges

# Does the graph match the filesystem?
tg check .

CI runs make check (formatting, lint, types, tests, and the TRUG checks via tg) plus trug compliance . on every push and PR — this README's section list, the spec index, the tool table above all correspond to nodes you can traverse programmatically. When the TRUG drifts from the prose or the filesystem, CI fails. We dogfood our own dogfood.

Use It

TRUGS-AGENT — copy one file into your project and your LLM speaks TRL, follows a 9-phase development protocol, tracks projects as graphs, and maintains persistent memory. Seven standalone components:

Component	What It Does
FOLDER	Machine-readable filesystem index — one JSON graph per folder
AAA	9-phase development protocol — plan before code, audit before ship
EPIC	Portfolio tracker as a traversable graph
MEMORY	Persistent context across sessions
TRUGGING	Methodology for describing a codebase with TRUGs and TRL
WEB_HUB	Curated web resource graph
NDA	Complete example — all systems applied to a mutual NDA

Building on TRUGS

CORE and Language are maintained by TRUGS LLC. The 233-word vocabulary, grammar, and validation rules are the specification — they don't change without a spec revision.

Branches are where the community builds. If your domain needs vocabulary that doesn't exist (medical, financial, legal, robotics, etc.), build a branch:

1. Define your domain's node types and edge relations
2. Use CORE primitives as your foundation
3. Add domain-specific words to your opening TRUG
4. Validate your TRUGs against CORE

You don't need permission. Build it, use it, share it. Once enough people are using a branch in the same domain, we'll work with the community to formalize it into the specification.

Implementations are welcome. Build tools that read, write, validate, or execute TRUGs in any language. The spec is the contract — implement it however you want.

License

The TRUGS specification and reference tools are released under the Apache License 2.0. Anyone may implement the standard.