Skip to main content

Contributing to Trinity

Thank you for your interest in contributing to Trinity. This guide covers everything you need to know -- from our specification-first philosophy to the 16-step development cycle.

1. Overview​

Specification-First Development

Trinity follows a strict specification-first paradigm. Every line of production code is generated from .vibee specifications. You never write implementation code by hand.

ALL CODE MUST BE GENERATED FROM .vibee SPECIFICATIONS

The philosophy is simple:

  • Specifications are the source of truth. If you want to change behavior, change the spec.
  • Code generation is deterministic. The same spec always produces the same output.
  • Testing is automatic. Behaviors defined in specs produce tests by construction.
  • Manual code is forbidden. The only hand-written code lives in the VIBEE compiler itself (src/vibeec/), documentation, and specification files.

This approach guarantees type safety, test coverage for all specified behaviors, and consistency across all 42+ supported language targets.

2. The 16-Step Development Cycle​

MANDATORY 16-Link Development Cycle

Every contribution -- no matter how small -- must follow the 16-step development cycle. Run ./bin/vibee koschei to display the full cycle at any time.

All steps are mandatory. No step may be skipped.

The 16 steps are:

LinkNameDescription
1ANALYZEStudy the problem domain. Read existing specs, understand the architecture, identify what needs to change.
2RESEARCHInvestigate prior art, mathematical foundations, and relevant algorithms. Document findings.
3SPECWrite or update the .vibee specification in specs/tri/. This is the creative step -- all design decisions happen here.
4VALIDATERun ./bin/vibee validate specs/tri/your_spec.vibee to check the specification for syntactic and semantic correctness.
5GENERATERun ./bin/vibee gen specs/tri/your_spec.vibee to produce implementation code in the target language.
6COMPILEBuild the generated output: zig build or zig build test to verify it compiles without errors.
7TESTRun the full test suite: zig build test. Every behavior's test cases must pass.
8BENCHRun zig build bench to measure performance. Record baseline metrics for comparison.
9ITERATEIf tests fail or performance regresses, return to link 3 (SPEC) and refine. Repeat links 3-8 until green.
10REVIEWSelf-review the specification and generated output. Verify the design matches requirements.
11VERDICTWrite a Critical Assessment -- a brutally honest self-criticism of the work (see Section 10).
12TREEPropose exactly 3 TECH TREE options for the next iteration (see Section 8).
13DOCUMENTUpdate relevant documentation if the change affects public APIs or user-facing behavior.
14COMMITCreate a single atomic commit following Conventional Commits.
15PRSubmit a pull request referencing the relevant issue. Include the Critical Assessment and Tech Tree.
16CLOSEOnce merged, verify the chain is closed. All exit criteria must be satisfied.

Minimal Quick Cycle​

For small changes, the essential links are:

# Link 3: Write specification
cat > specs/tri/feature.vibee << 'EOF'
name: feature
version: "1.0.0"
language: zig
module: feature

types:
  MyType:
    fields:
      name: String

behaviors:
  - name: my_func
    given: Input
    when: Action
    then: Result
EOF

# Link 5: Generate code
./bin/vibee gen specs/tri/feature.vibee  # -> trinity/output/feature.zig

# Link 7: Test
zig test trinity/output/feature.zig

# Link 11: Write Critical Assessment (honest self-criticism)
# Link 12: Propose 3 TECH TREE options for next iteration

For Hardware (Verilog/FPGA)​

# Use language: varlog in your spec
./bin/vibee gen specs/tri/feature_fpga.vibee  # -> trinity/output/fpga/feature_fpga.v

Exit Criteria​

EXIT_SIGNAL = ( tests_pass AND spec_complete AND critical_assessment_written AND tech_tree_options_proposed AND committed )

The cycle is only complete when every condition in the exit signal is true.

3. VIBEE Specification Format​

The .vibee File

.vibee files are YAML-based specifications that serve as the single source of truth for all generated code. One spec can target Zig, Verilog, Python, and 39 other languages.

Complete Structure​

name: module_name            # Required: lowercase with underscores
version: "1.0.0"            # Required: semantic version
language: zig                # Required: target language (zig, varlog, python, etc.)
module: module_name          # Required: output module name
description: "Description"   # Optional: human-readable summary
author: "Name"               # Optional: author
license: "MIT"               # Optional: license identifier

constants:
  PHI: 1.6180339887498948
  TRINITY: 3
  DIMENSION: 10000
  PE_MAGIC: 0x5A4D

types:
  # Struct definition
  TypeName:
    fields:
      field1: String
      field2: Int
      field3: Bool
      field4: Float
      field5: List<String>
      field6: Option<Int>
    constraints:
      - "field2 >= 0"
      - "field2 <= 100"

  # Enum definition
  Status:
    enum:
      - active
      - inactive
      - pending

behaviors:
  - name: function_name
    given: Precondition description
    when: Action description
    then: Expected result description
    params:
      - name: input
        type: TypeName
      - name: dimension
        type: Int
    returns: TypeName
    test_cases:
      - name: test_basic
        input:
          input: {field1: "hello", field2: 42}
          dimension: 3
        expected: {field1: "result", field2: 42}

Type Mappings​

VIBEE TypeZigVerilogPythonDescription
String[]const u8N/AstrText data
Inti64integerintInteger
Floatf64realfloatFloating point
BoolboolregboolBoolean
Option<T>?TN/AOptional[T]Optional value
List<T>[]TN/AList[T]Dynamic list

Behaviors: Given-When-Then​

All behaviors use BDD (Behavior-Driven Development) semantics based on Given-When-Then, which maps directly to Hoare logic:

Given: P (precondition)    -->  {P}
When:  A (action)          -->   A
Then:  Q (postcondition)   -->  {Q}

Example:

behaviors:
  - name: bind
    given: Two vectors a and b of same dimension
    when: Element-wise ternary multiplication
    then: Returns bound vector c where c[i] = a[i] * b[i]
    params:
      - name: a
        type: TritVector
      - name: b
        type: TritVector
    returns: TritVector
    test_cases:
      - name: test_bind_identity
        input:
          a: {data: [1, 0, -1], dimension: 3}
          b: {data: [1, 1, 1], dimension: 3}
        expected: {data: [1, 0, -1], dimension: 3}

See the full VIBEE Specification Reference for more detail.

4. What You Can Edit​

Source of Truth

The only code you should ever write by hand lives in specifications, the compiler itself, and documentation. Everything else is generated.

Allowed to Edit​

PathDescription
specs/tri/*.vibeeSpecifications (SOURCE OF TRUTH) -- all design work happens here
src/vibeec/*.zigVIBEE compiler source -- the only hand-written Zig
docs/*.mdDocumentation files
docsite/**Documentation website
examples/*.triExample programs
CLAUDE.mdAI assistant instructions

Never Edit (Auto-Generated)​

PathReason
trinity/output/*.zigGenerated from .vibee specs -- will be overwritten
trinity/output/fpga/*.vGenerated from .vibee specs -- will be overwritten
generated/*.zigGenerated from .vibee specs -- will be overwritten

If you find a bug in generated code, fix the specification or the compiler -- never the output.

5. Code Style Guide​

Zig Conventions​

  • Use 4-space indentation (no tabs).
  • Follow the official Zig Style Guide.
  • Prefer const over var whenever possible.
  • Add doc comments (///) for all public functions.
  • Use @import("std") -- do not alias standard library submodules at file scope unless necessary.
  • Run zig fmt src/ before committing to ensure consistent formatting.

VIBEE Specification Conventions​

  • Use lowercase_with_underscores for module and behavior names.
  • Use PascalCase for type names.
  • Every behavior must include meaningful given, when, and then descriptions -- not placeholders.
  • Include at least one test_case per behavior.
  • Add constraints to types where invariants exist.
  • Keep specifications focused: one module per .vibee file.

Given/When/Then Best Practices​

QualityBadGood
Specificitygiven: Inputgiven: A non-empty vector of dimension N
Action claritywhen: Processingwhen: Computing element-wise ternary product
Verifiabilitythen: Returns resultthen: Returns vector where each trit is product of corresponding input trits

6. Mathematical Foundation​

Trinity is built on a rigorous mathematical foundation connecting the golden ratio, ternary arithmetic, and information theory.

The Trinity Identity​

phi^2 + 1/phi^2 = 3

Where phi = (1 + sqrt(5)) / 2 ~ 1.618 (the golden ratio). This algebraic identity connects the golden ratio to the number 3, which is the optimal integer radix.

Parametric Constant Approximation​

V = n * 3^k * pi^m * phi^p * e^q

Several physical constants can be closely approximated using this parameterization. See Constant Approximation Formulas for details and error analysis.

Why Ternary?​

PropertyBinaryTernaryAdvantage
Values per digit23--
Information density1.00 bits/digit1.58 bits/trit+58.5%
Memory (vs float32)1x1/20x20x savings
Compute modelMultiply-accumulateAdd-onlyNo multiply
Optimal radix--Closest integer to eMathematically optimal

See the full Mathematical Foundations section for proofs and derivations.

7. Genetic Algorithm Parameters​

Evolutionary Optimization Constants

The evolutionary optimization engine in Trinity uses four constants derived from the golden ratio for genetic algorithm optimization. These govern the genetic algorithm that evolves specifications and optimizes generated code.

ConstantSymbolValueDerivationPurpose
Mutation Ratemu0.03821 - 1/phi^(phi+1)Controls random perturbation of candidate solutions. Low value ensures stability -- only ~3.8% of genes mutate per generation, preventing catastrophic loss of good traits.
Crossover Ratechi0.06181/phi^3Governs recombination of parent solutions. At ~6.2%, crossover is selective, combining only the strongest traits from each parent while preserving individual structure.
Selection Pressuresigma1.618phiDetermines how aggressively the fittest individuals are favored. Ensures a balanced tournament where strong candidates win but diversity is maintained.
Elitism Fractionepsilon0.3331/3The fraction of the population that survives unchanged into the next generation. Guarantees that the best third of solutions persist while leaving room for evolution.

These constants are derived from the golden ratio and ternary base to provide a coherent set of hyperparameters. Their effectiveness should be validated empirically for each specific optimization problem.

8. Tech Tree​

Interactive Tech Tree

The Tech Tree maps all development paths in Trinity. View the full interactive version at the Architecture Overview.

Every development cycle ends with proposing 3 TECH TREE options -- one from each of three different branches -- giving reviewers meaningful choices for the project's direction.

The 5 Branches​

BranchFocusKey Areas
COREFoundationVSA operations, ternary VM, packed trit encoding, HybridBigInt, SDK primitives
INFERENCEAI/MLFirebird LLM engine, BitNet b1.58 integration, GGUF model loading, tokenization, transformer layers
OPTIMIZATIONPerformanceSIMD vectorization (AVX2/NEON), cache-friendly layouts, zero-allocation patterns, benchmark suite
DEPLOYMENTDistributionWebAssembly targets, DePIN infrastructure, cross-platform release builds, HTTP API server, Telegram bot
HARDWAREPhysicalVerilog code generation, FPGA synthesis, ternary ALU design, quantum-ready qutrit mappings, phi-engine

How to Propose Tech Tree Options​

At the end of each development cycle (step 12), propose exactly 3 options:

## TECH TREE

### Option A: [CORE] Extend VSA with sparse vector support
- Add sparse encoding to reduce memory for high-dimensional vectors
- Estimated effort: 2 days
- Risk: Low

### Option B: [OPTIMIZATION] AVX-512 path for trit bundling
- 2x throughput on supported hardware
- Estimated effort: 3 days
- Risk: Medium (hardware-specific)

### Option C: [DEPLOYMENT] WebAssembly streaming compilation
- Enable browser-based inference without full download
- Estimated effort: 5 days
- Risk: Medium

9. Commit Convention​

All commits must follow Conventional Commits format.

Prefixes​

PrefixUsageExample
feat:New feature or specificationfeat: add ternary matrix multiplication spec
fix:Bug fix in spec or compilerfix: correct off-by-one in trit packing
docs:Documentation changesdocs: update VSA API reference
refactor:Code restructuring (compiler only)refactor: simplify codegen pipeline
test:Test additions or changestest: add edge cases for bind operation
perf:Performance improvementsperf: SIMD-accelerate bundle3 operation
chore:Build, CI, tooling changeschore: update Zig to 0.13.0

Commit Message Format​

<type>: <short summary in imperative mood>

<optional body: explain WHY, not WHAT>

<optional footer: references, breaking changes>

Example​

feat: add ternary matrix multiplication spec

- Add specs/tri/matmul.vibee with SIMD-aware behaviors
- Includes test cases for AVX2 and NEON paths
- Supports dimensions up to 10000x10000

Refs: #42

Rules​

  • Use imperative mood in the summary line ("add", not "added" or "adds").
  • Keep the summary line under 72 characters.
  • Reference related issues in the footer.
  • One logical change per commit. Do not combine unrelated changes.

10. Critical Assessment​

Mandatory Self-Criticism

Every development cycle must include a Critical Assessment -- a brutally honest assessment of the work's weaknesses. This is not optional. No PR will be accepted without one.

The Critical Assessment serves three purposes:

  1. Intellectual honesty -- forces you to confront what you glossed over.
  2. Review efficiency -- reviewers know exactly where to look for problems.
  3. Iteration fuel -- weaknesses identified here feed directly into the next cycle's Tech Tree options.

Format​

## CRITICAL ASSESSMENT

### What went wrong
- [Specific technical weakness #1]
- [Specific technical weakness #2]
- [What was left incomplete or hacky]

### What I would do differently
- [Concrete alternative approach]
- [Better design decision]

### Honest assessment
[1-3 sentences of unflinching self-evaluation. No hedging, no softening.]

Example​

## CRITICAL ASSESSMENT

### What went wrong
- The sparse vector encoding wastes 12% memory on vectors with density > 0.4
- No benchmarks for the NEON path -- only tested on x86_64
- The constraint validation generates O(n^2) checks; should be O(n)

### What I would do differently
- Use run-length encoding instead of index lists for dense regions
- Set up CI with ARM runners before claiming cross-platform support

### Honest assessment
This implementation works but is mediocre. The happy path is solid, but edge
cases around zero-heavy vectors are undertested and the performance claims are
unsubstantiated on ARM. Needs another full iteration before production use.

11. CLI Commands​

Quick reference for all Trinity CLI commands used during development.

Build Commands​

CommandDescription
zig buildCompile library and all executables
zig build firebirdBuild Firebird LLM CLI (ReleaseFast)
zig build releaseCross-platform release builds (linux/macos/windows)

Test Commands​

CommandDescription
zig build testRun ALL tests (trinity, vsa, vm, firebird, wasm, depin)
zig test src/vsa.zigRun VSA tests only
zig test src/vm.zigRun VM tests only
zig test src/firebird/b2t_integration.zigFirebird integration tests

Benchmark and Examples​

CommandDescription
zig build benchRun performance benchmarks
zig build examplesBuild and run all examples

Format​

CommandDescription
zig fmt src/Format all Zig source code

VIBEE Compiler​

CommandDescription
./bin/vibee gen <spec.vibee>Generate code from specification
./bin/vibee gen-multi <spec> allGenerate for all 42 supported languages
./bin/vibee validate <spec.vibee>Validate specification syntax and semantics
./bin/vibee run <file.999>Execute via bytecode VM
./bin/vibee koscheiDisplay the full development cycle
./bin/vibee chat --model <path>Interactive chat with a model
./bin/vibee serve --port 8080Start the HTTP API server

12. Community​

Getting Help​

Submitting a Pull Request​

  1. Fork the repository and clone your fork.
  2. Create a branch: git checkout -b feat/my-feature
  3. Follow the 16-step development cycle.
  4. Push your branch: git push origin feat/my-feature
  5. Open a PR against main with the following template:
## Summary
Brief description of changes.

## Specification
Link to the .vibee file(s) added or modified.

## Testing
How the changes were tested. Include test output.

## CRITICAL ASSESSMENT
[Your honest self-criticism]

## TECH TREE
[Your 3 options for next iteration]

Code of Conduct​

  • Be respectful and constructive.
  • Focus criticism on code and design, never on people.
  • The Critical Assessment is for self-criticism only -- never direct it at others.
  • Assume good intent. Ask clarifying questions before judging.

Documentation Website​

The documentation site is hosted at https://trinity-site-ghashtag.vercel.app. It auto-deploys from the main branch. The site source lives in docsite/ and uses Docusaurus.

ResourceLink
Repositorygithub.com/gHashTag/trinity
Documentationtrinity-site-ghashtag.vercel.app
VIBEE Guide/docs/vibee
Mathematical Foundations/docs/math-foundations
API Reference/docs/api
Architecture/docs/architecture/overview