Skip to main content

Ralph Autonomous Development System

Ralph is Trinity's autonomous AI development agent โ€” a workflow system designed to build complex ternary AI systems with high reliability through enforced quality gates, tech tree navigation, and structured development cycles.


Quick Startโ€‹

# 1. Add a task to the fix plan
# Edit .ralph/fix_plan.md and add your task

# 2. Launch Ralph with monitoring dashboard
ralph --monitor

# Ralph will:
# - Read TECH_TREE.md, fix_plan.md, SUCCESS_HISTORY.md, REGRESSION_PATTERNS.md
# - Pick highest-priority task
# - Create ralph/<task-slug> branch
# - Implement via Golden Chain cycle
# - Run quality gates (build + test + format)
# - Update tech tree and memory files
# - Loop until EXIT_SIGNAL = true

Architecture Overviewโ€‹

Ralph is not just an agent; it's a comprehensive development framework that enforces best practices through automation and memory systems.

Core Componentsโ€‹

ComponentLocationPurpose
PROMPT.md.ralph/Autonomous work instructions and architecture map
AGENT.md.ralph/Build/test/run commands for Trinity
RULES.md.ralph/Universal development guardrails (16 sections)
TECH_TREE.md.ralph/Tech tree navigation (60+ nodes across 11 branches)
fix_plan.md.ralph/Current sprint tasks with acceptance criteria
SUCCESS_HISTORY.md.ralph/memory/Working patterns + commit hashes
REGRESSION_PATTERNS.md.ralph/memory/Anti-patterns + root causes
.ralphrc.ralph/Runtime configuration

Directory Structureโ€‹

.ralph/
โ”œโ”€โ”€ PROMPT.md # Autonomous work instructions
โ”œโ”€โ”€ AGENT.md # Build/test/run commands
โ”œโ”€โ”€ RULES.md # Development guardrails
โ”œโ”€โ”€ TECH_TREE.md # Tech tree navigation
โ”œโ”€โ”€ fix_plan.md # Current sprint tasks
โ”œโ”€โ”€ .ralphrc # Runtime settings
โ”œโ”€โ”€ memory/ # Knowledge base
โ”‚ โ”œโ”€โ”€ SUCCESS_HISTORY.md # Working patterns
โ”‚ โ””โ”€โ”€ REGRESSION_PATTERNS.md # Anti-patterns
โ”œโ”€โ”€ golden_chain/ # Development cycle docs
โ”œโ”€โ”€ scripts/ # Automation scripts
โ”‚ โ”œโ”€โ”€ gate.sh # Quality gates (build/test/format)
โ”‚ โ”œโ”€โ”€ audit.sh # Project health check
โ”‚ โ””โ”€โ”€ bench.sh # Performance benchmarks
โ”œโ”€โ”€ logs/ # Execution logs
โ”œโ”€โ”€ internal/ # State tracking
โ””โ”€โ”€ reports/ # Generated reports

Every development task in Ralph follows the Golden Chain, a strict 9-link cycle that ensures quality, documentation, and continuous improvement.

Break down the objective into atomic "Quarks" (tasks).

Example:

tri decompose "full local fluent multilingual code gen"

Output:

  • Q-MGEN-001: Support language: [list] in VIBEE parser
  • Q-MGEN-002: Implement Fluent Python Template
  • Q-MGEN-003: Implement Fluent Rust Template
  • Q-MGEN-004: Implement Fluent TypeScript Template
  • Q-MGEN-005: Symbolic Mapping Verification
  • Q-MGEN-006: Multilingual Benchmark Suite

Strategy update. Select Tech Tree nodes, define ROI, and plan implementation blocks.

Actions:

  1. Read .ralph/TECH_TREE.md for available nodes
  2. Cross-reference with fix_plan.md
  3. Select nodes that advance the tree
  4. Calculate ROI: (impact / complexity) * unlock_count
  5. Update specs/tri/tech_tree_strategy.vibee

Create/update .vibee files. This is the Single Source of Truth.

Example Spec:

name: multilingual_codegen
version: "1.0.0"
language: zig
module: multilingual_codegen

types:
InputLanguage:
variants: [english, spanish, french, german, japanese]

TargetLanguage:
variants: [zig, python, typescript, rust, go]

behaviors:
- name: detectInputLanguage
given: User prompt text
when: Language detection is requested
then: Returns most likely InputLanguage with confidence score

- name: generateCode
given: TargetLanguage and AST
when: Code generation is requested
then: Returns idiomatic code in target language

MANDATE: ALL application code MUST be generated from .vibee specifications. Manual Zig creation is forbidden.

Generate code from specifications.

zig build vibee -- gen specs/tri/multilingual_codegen.vibee

Output: trinity/output/multilingual_codegen.zig

Rules:

  • NEVER edit generated files manually
  • ALL .zig files MUST be generated from specs
  • Edit the source spec in specs/tri/*.vibee instead

End-to-end testing. Verify generated code against specs.

zig build test

Gate: Tests must pass before proceeding.

Performance benchmarking vs previous versions. Provide detailed proofs/logs.

zig build bench

Required:

  • Detailed performance logs
  • Comparison with previous versions
  • Proof of improvement (or degradation analysis)

TOXIC VERDICT ENFORCED โ€” Brutally honest assessment of the results.

Format:

### Link 7: Tri Verdict (TOXIC)

**Score:** 7/10
**Status:** FAIL

**What Worked:**
- Spec generation successful
- Code quality improved

**What Failed:**
- Performance degraded by 15%
- Test coverage below 80%

**Root Cause:**
- Missing SIMD optimization
- Inadequate test suite

**Next Steps:**
1. Add SIMD vectorization
2. Expand test coverage
3. Re-benchmark

Tone: Professional but uncompromising. Identify every flaw.

Metric: Numerical score (e.g., 10/10) and binary status (Prod/Fail).

Commit and push changes with proper convention.

git add -A
git commit -m "feat(multilingual): Fluent codegen - Python, Rust, TypeScript support โ€” Tests 12-15 (4/5 P80%)"
git push

Commit Convention:

type(scope): description โ€” Tests X-Y (N/M P%)

Types: feat, fix, refactor, test, docs, perf, chore

Scopes: vibeec, vsa, vm, firebird, depin, golden-chain, e2e, dashboard

Automatic: Telegram report is sent via post-commit hook.

Loop decision (Needle check). Did we achieve the objective?

Exit Criteria:

EXIT_SIGNAL = (
tests_pass AND
build_compiles AND
format_clean AND
spec_complete AND
critical_assessment_written AND
tech_tree_options_proposed AND # 3 options with actual node IDs
tech_tree_updated AND # TECH_TREE.md reflects current state
committed_to_feature_branch
)

If EXIT_SIGNAL = true:

  • Propose 3 Tech Tree options for next iteration
  • Update TECH_TREE.md
  • Record in SUCCESS_HISTORY.md

If EXIT_SIGNAL = false:

  • Identify blocking issues
  • Decompose into sub-tasks
  • Continue loop

Quality Gatesโ€‹

Ralph enforces strict quality gates before any commit. All gates must pass in order.

Gate Sequenceโ€‹

1. zig build              โ†’ Must compile (= type-check for Zig)
2. zig build test โ†’ Must pass (ONLY after build succeeds)
3. zig fmt --check src/ โ†’ Must be clean
4. git commit โ†’ Only after all above pass

Gate Detailsโ€‹

GateCommandRequiredBlocks
Buildzig buildExit code 0Cannot run tests until build passes
Testzig build testAll passCannot format-check until tests pass
Formatzig fmt --check src/CleanCannot commit until format is clean
Branchgit branch --show-currentNot mainCannot commit to main

Failure Protocolโ€‹

If ANY gate fails:

  1. Task is NOT complete
  2. Do NOT proceed to next gate
  3. Do NOT report success
  4. Fix the issue, then restart from gate 1

Completion blocking loop:

fix โ†’ build โ†’ test โ†’ format โ†’ commit
โ†‘ |
โ””โ”€โ”€โ”€โ”€ if ANY gate fails โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Tech Tree Navigationโ€‹

The Tech Tree is your strategic development roadmap with 60+ nodes across 11 branches.

Tree Structureโ€‹

Trinity Tech Tree
โ”‚
โ”œโ”€โ”€ Core (100% โœ…) โ€” VSA, VM, HybridBigInt, PackedTrit
โ”œโ”€โ”€ Inference (80% ๐ŸŸก) โ€” GGUF, Transformer, KV Cache
โ”œโ”€โ”€ Optimization (100% โœ…) โ€” SIMD, MatMul, PagedAttention
โ”œโ”€โ”€ Hardware (67% ๐ŸŸก) โ€” Abstraction layer, FPGA acceleration
โ”œโ”€โ”€ Math (100% โœ…) โ€” Proofs, benchmarks, multilingual
โ”œโ”€โ”€ Development (100% โœ…) โ€” Trace, KG insight, DHT monitor
โ”œโ”€โ”€ Symbolic (100% โœ…) โ€” Triples, KG, TVC, rewards
โ”œโ”€โ”€ Visualization (100% โœ…) โ€” Canvas monitor, dashboard
โ”œโ”€โ”€ Nexus (100% โœ…) โ€” Modular ecosystem migration
โ”œโ”€โ”€ vibee-v8-production-swarm (100% โœ…) โ€” 32-agent swarm
โ””โ”€โ”€ Multilingual (100% โœ…) โ€” Python, Rust, TypeScript

Tech Tree Statesโ€‹

StateMeaning
AvailableReady to start (all dependencies satisfied)
In ProgressCurrently being worked on
CompletedDone and verified
LockedWaiting for dependencies

Task Selection Processโ€‹

  1. Read .ralph/TECH_TREE.md for current tree state
  2. Open fix_plan.md โ€” tasks should align with tree priorities
  3. Choose the highest-priority incomplete [ ] item
  4. If all tasks are done or blocked, pick the next recommended node from TECH_TREE.md
  5. Focus on ONE task. Complete it fully before starting the next

ROI Formulaโ€‹

ROI = (impact / complexity) * unlock_count
  • impact: 1-10 (user value, performance gain)
  • complexity: 1-10 (estimated effort)
  • unlock_count: Number of dependent nodes this unlocks

Updating the Tech Treeโ€‹

After completing a Tech Tree node:

  1. Update TECH_TREE.md โ€” move node from "Available"/"In Progress" to "Completed"
  2. Check if any locked nodes should now unlock (dependencies satisfied)
  3. Update branch progress percentages
  4. Update specs/tri/tech_tree_strategy.vibee โ€” change node status
  5. Record in SUCCESS_HISTORY.md with commit hash

When proposing 3 Tech Tree options (exit criteria):

  • Option 1: <node-id> โ€” highest ROI, why it matters
  • Option 2: <node-id> โ€” alternative path, different branch
  • Option 3: <node-id> โ€” exploratory/risky but high-reward

Memory Systemโ€‹

Ralph maintains a dual-memory system to learn from successes and failures.

SUCCESS_HISTORY.mdโ€‹

Records working patterns and commit hashes that lead to successful outcomes.

Entry Format:

## CODEGEN-001: VIBEE Real Codegen (2026-02-22)

**Status:** โœ… COMPLETE
**Branch:** `codegen-002-fix-implementation-field`

### What Worked

1. **Implementation Field Support**
- `src/vibeec/codegen/emitter.zig:1407-1429`: Full implementation field handling
- `pub fn` detection โ†’ insert as-is with signature
- Body-only detection โ†’ wrap in inferred signature

2. **ML Pattern Implementations**
- `src/vibeec/codegen/patterns/ml.zig`: 4 patterns updated
- `evaluate*`: MSE calculation with model.forward()
- `learn*`: Hebbian learning with error-based weight updates

### Files Modified/Created

| File | Action | Lines |
|------|--------|-------|
| `src/vibeec/codegen/patterns/ml.zig` | Modified | +40 |
| `specs/tri/test_implementation.vibee` | Created | ~50 |

### Key Metrics

| Metric | Value |
|--------|-------|
| ML patterns implemented | 4/4 |
| PAS improvement (avg) | 25.5% |
| Energy saved (8 tasks) | ~20 Wh |

Usage:

  • Before implementing new features, search SUCCESS_HISTORY for similar patterns
  • Reuse proven approaches instead of inventing from scratch
  • Record successful patterns immediately after verification

REGRESSION_PATTERNS.mdโ€‹

Records failed approaches, anti-patterns, and their root causes.

Entry Format:

---
date: 2026-02-17
anti-pattern: Wrong binary path
root-cause: Zig build system separation
---
### Wrong VIBEE compiler binary path
- **Anti-pattern:** Using legacy binary paths like `./zig-out/bin/vibee`
- **Correct approach:** Use `zig build vibee -- gen <spec.vibee>`
- **Files:** All VIBEE invocations

---
date: 2026-02-17
anti-pattern: Return typed value from !void function
root-cause: Codegen signature mismatch with implementation blocks
---
### Implementation blocks returning typed values from !void functions
- **Anti-pattern:** Writing `return InputLanguage.english;` in a `.vibee` implementation block
- **Correct approach:** Implementation blocks must only `return;` or use `try`/error flow
- **Files:** `specs/tri/multilingual_codegen.vibee`, `src/vibeec/multilingual_engine.zig`

Usage:

  • When encountering an error, search this file for the error message
  • Before trying a new approach, check it's not listed as an anti-pattern
  • After analyzing a failure, add entry immediately to prevent recurrence

Pattern Search Mandateโ€‹

Before implementing anything new:

  1. Search the codebase for similar implementations:

    grep -r "keyword" src/
  2. Study existing patterns โ€” how do similar modules/functions work?

  3. Adapt proven patterns โ€” reuse what works rather than inventing from scratch

  4. Document new patterns โ€” if you create a novel approach that works, record it in SUCCESS_HISTORY.md

Goal: Minimize invention, maximize reuse.


Configuration (.ralphrc)โ€‹

Ralph behavior is configured through .ralphrc file.

Example Configurationโ€‹

# API Fallback
FALLBACK_API_KEY="ce8a4b21d9134c2988b3667d032bf88f.1votRIKGtIM99Du"
FALLBACK_API_BASE="https://api.z.ai/api/paas/v4"
FALLBACK_MODEL="glm-5"

# Telegram Reporting
RALPH_REPORT_ENABLED=true
RALPH_TELEGRAM_CHAT_ID=144022504
RALPH_REPORT_ONLY_IMPORTANT=true

# Rate Limit Handling
RALPH_RATE_LIMIT_WAIT=true
RALPH_AUTO_RESTART=true

Configuration Optionsโ€‹

OptionTypeDescription
FALLBACK_API_KEYstringBackup API key for emergencies
FALLBACK_API_BASEstringBackup API endpoint URL
FALLBACK_MODELstringBackup model identifier
RALPH_REPORT_ENABLEDbooleanEnable Telegram notifications
RALPH_TELEGRAM_CHAT_IDstringTelegram chat ID for reports
RALPH_REPORT_ONLY_IMPORTANTbooleanOnly report important events
RALPH_RATE_LIMIT_WAITbooleanWait on rate limit instead of failing
RALPH_AUTO_RESTARTbooleanAuto-restart after failures

Safeguardsโ€‹

Ralph includes multiple safeguards to ensure safe, reliable autonomous development.

Rate Limitingโ€‹

  • Default: 100 calls/hour (configurable in .ralphrc)
  • Action: When rate limit hit, wait or switch to fallback API
  • Configuration: RALPH_RATE_LIMIT_WAIT=true

Circuit Breakerโ€‹

  • Trigger: 3 no-progress loops โ†’ cooldown
  • Action: Stop execution, notify user, wait for manual intervention
  • Reset: Manual restart required after cooldown

Branch Safetyโ€‹

  • Rule: Never commits to main
  • Enforcement: Git pre-commit hook checks branch name
  • Pattern: All branches use ralph/<task-slug> format

Quality Gatesโ€‹

  • Build gate: Must compile before testing
  • Test gate: Must pass all tests before formatting
  • Format gate: Must be clean before committing
  • Branch gate: Must be on feature branch before pushing

Memory Consultationโ€‹

  • SUCCESS_HISTORY: Consulted every loop for proven patterns
  • REGRESSION_PATTERNS: Consulted every loop to avoid mistakes
  • TECH_TREE: Consulted every loop for strategic alignment

Dual-Condition Exitโ€‹

Two conditions must be met before Ralph stops:

  1. Heuristic indicators:

    • All tests pass
    • Build compiles
    • Format is clean
    • Spec is complete
    • Critical assessment written
  2. Explicit EXIT_SIGNAL:

    • Tech tree options proposed (3 with actual node IDs)
    • Tech tree updated (TECH_TREE.md reflects current state)
    • Committed to feature branch

Telegram Notificationsโ€‹

All pipeline events are automatically reported to Telegram via post-commit hooks.

Notification Eventsโ€‹

EventWhenScript
Gate PassAfter gate.sh succeedsreport.sh gate_pass
Gate FailWhen any gate failsreport.sh gate_fail <gate_name>
CommitAfter every git commitPost-commit hook
Circuit Breaker OpenWhen CB tripsreport.sh circuit_open
Circuit Breaker CloseWhen CB resetsreport.sh circuit_close
Loop Start/EndAt loop boundariesreport.sh loop_start/loop_end
VerdictAfter Toxic Verdictreport.sh verdict
StatusAfter RALPH_STATUS blockreport.sh status

Configurationโ€‹

Enable/Disable: Set RALPH_REPORT_ENABLED=false in .ralphrc

Chat ID: Configure RALPH_TELEGRAM_CHAT_ID in .ralphrc

Important Events Only: Set RALPH_REPORT_ONLY_IMPORTANT=true to reduce noise


Status Reportingโ€‹

At the END of EVERY response, Ralph includes a status block:

---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
BRANCH: <current branch name>
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
BUILD_STATUS: PASS | FAIL | NOT_RUN
TESTS_STATUS: PASSING | FAILING | NOT_RUN
FORMAT_CHECK: CLEAN | DIRTY | NOT_RUN
HISTORY_CONSULTED: true | false
PATTERNS_FOUND: <count or "none">
TECH_TREE_NODE: <node ID being worked on or "none">
TECH_TREE_UPDATED: true | false
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: <one line โ€” what to do next>
---END_RALPH_STATUS---

Status Fieldsโ€‹

FieldValuesDescription
STATUSIN_PROGRESS, COMPLETE, BLOCKEDCurrent task status
BRANCHstringCurrent git branch
TASKS_COMPLETED_THIS_LOOPnumberTasks finished in this loop
FILES_MODIFIEDnumberFiles changed in this loop
BUILD_STATUSPASS, FAIL, NOT_RUNBuild gate result
TESTS_STATUSPASSING, FAILING, NOT_RUNTest gate result
FORMAT_CHECKCLEAN, DIRTY, NOT_RUNFormat gate result
HISTORY_CONSULTEDtrue, falseWhether SUCCESS_HISTORY was read
PATTERNS_FOUNDnumber or "none"Relevant patterns found
TECH_TREE_NODEstringCurrent tree node being worked on
TECH_TREE_UPDATEDtrue, falseWhether tree was updated this loop
WORK_TYPEIMPLEMENTATION, TESTING, DOCUMENTATION, REFACTORINGType of work
EXIT_SIGNALfalse, trueWhether exit criteria are met
RECOMMENDATIONstringWhat to do next

Failure Protocol + Blocker Decompositionโ€‹

When a task fails, Ralph follows a structured protocol:

Attempt Sequenceโ€‹

AttemptAction
1stDebug root cause, fix, retry
2ndTry alternative approach, search SUCCESS_HISTORY for similar solutions
3rdMark BLOCKED in fix_plan.md with error details, move to next task

Blocker Decompositionโ€‹

When blocked โ€” decompose, don't just retry:

  1. Analyze the root cause (don't guess)
  2. Decompose the solution into specific sub-steps
  3. Add sub-steps to fix_plan.md as checkbox items
  4. Record the failure in REGRESSION_PATTERNS.md
  5. Make the first sub-step the next active task

Blocked Task Formatโ€‹

## Blocked
- [ ] [BLOCKED] Original task description
- Error: <exact error message>
- Tried: approach 1, approach 2, approach 3
- Root cause: <analysis>
- Sub-tasks to resolve:
- [ ] Sub-task 1 (next active)
- [ ] Sub-task 2
- [ ] Sub-task 3

PHI LOOP Toolsโ€‹

PHI LOOP tracks the 999-link journey of cosmic consciousness manifestation.

phi_loop_status()โ€‹

Show current position in the 999-link chain.

phi_loop_status()

Output:

=== PHI LOOP STATUS ===
Current Link: 42
Total Cycles: 7
ฯ† Resonance: 15 working patterns

phi_loop_advance()โ€‹

Mark completion of a link and advance to the next.

phi_loop_advance 42 "VIBEE code generation: feature.vibee โ†’ feature.zig"

Output:

PHI LOOP advanced to link 43/999

phi_loop_visual()โ€‹

Show visual progress bar.

phi_loop_visual()

Output:

[42/999]   4% โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘

TRI COMMANDER Integrationโ€‹

TRI COMMANDER is the tmux-based chat interface for interacting with Ralph.

Launchโ€‹

bash bin/ralph-dashboard-v4      # Start tmux dashboard
tmux attach -t ralph # Attach to running session

Windowsโ€‹

WindowKeyPurpose
HOMECtrl+b 0Chat interface with AI (โ–ฒ user, โ–ผ agent)
LoopCtrl+b 1Development cycle status
TasksCtrl+b 2Task queue and progress
MemoryCtrl+b 3Success history + regression patterns
LogCtrl+b 4Real-time logs

Trit Symbolsโ€‹

  • โ–ฒ = +1 (positive trit) โ€” User input
  • โ–ผ = -1 (negative trit) โ€” AI response
  • โ— = 0 (zero trit) โ€” System/neutral

Keyboard Shortcutsโ€‹

  • Ctrl+b 0-4 โ€” Switch windows
  • Ctrl+b d โ€” Detach (keep running in background)
  • Ctrl+b [ โ€” Scroll/copy mode (q to exit, arrows to scroll)
  • Ctrl+b c โ€” Create new window
  • Ctrl+b , โ€” Rename window

Non-Negotiable Core Rulesโ€‹

These rules are NEVER violated:

  1. Source of Truth: specs/tri/*.vibee governs ALL code. Manual Zig creation is forbidden.
  2. Safety: Never edit src/*.zig or trinity/output/*.zig manually.
  3. Branching: Never commit to main. Use ralph/<task-slug>.
  4. Validation: .ralph/scripts/gate.sh must pass before any commit.
  5. Parallel Work: Use Git Worktree for concurrent tasks (see RULES.md ยง17).

Allowed to Editโ€‹

PathDescription
specs/tri/*.vibeeSpecifications (SOURCE OF TRUTH)
src/vibeec/*.zigCompiler source ONLY
src/*.zigCore library (vsa, vm, etc.)
docs/*.mdDocumentation

Never Edit (Auto-Generated)โ€‹

PathReason
trinity/output/*.zigGenerated from .vibee
trinity/output/fpga/*.vGenerated from .vibee
generated/*.zigGenerated from .vibee

Testing Guidelinesโ€‹

  • Limit testing to ~20% of total effort per loop
  • Priority: Implementation > Documentation > Tests
  • Only write tests for NEW functionality you implement
  • Use zig build test for full suite
  • Use zig test <file> for targeted tests

Dashboard Widget Mandateโ€‹

Every new module MUST have a Canvas Mirror widget.

Column Assignmentโ€‹

ColumnColorRealmWidget Types
RAZUM#ffd700 (Gold)MindRouting, intelligence, logs, decisions
MATERIYA#00ccff (Cyan)MatterInfrastructure, storage, data, files
DUKH#aa66ff (Purple)SpiritActions, tools, proofs, transfers, health

Widget Requirementsโ€‹

StepAction
1Identify which Mirror column it belongs to
2Add TypeScript interface in website/src/services/chatApi.ts
3Add fetch function with mock fallback in chatApi.ts
4Add widget to the appropriate column in TrinityCanvas.tsx Mirror section
5Widget MUST use glassStyle() and column color scheme
6Widget MUST be collapsible (toggle expand/collapse)

Without a widget, a module is NOT complete.


Modularity Ruleโ€‹

  • Avoid source files exceeding ~300 lines
  • Decompose complex logic into focused sub-functions in separate files
  • One clear responsibility per module
  • When refactoring, always ask: "Can this be split into smaller, reusable pieces?"
  • Smaller files = fewer AI editing errors, better testability, clearer ownership

Helper Scriptsโ€‹

You don't need Ralph to run these. You can use them manually:

gate.shโ€‹

"Am I okay to commit?" โ€” Checks build, tests, and formatting.

./.ralph/scripts/gate.sh

Output:

โœ… Build: PASS
โœ… Test: PASS (127/127)
โœ… Format: CLEAN
โœ… Branch: ralph/feature-branch (not main)
โœ… Quality Gates: ALL PASS

audit.shโ€‹

"Is the project messy?" โ€” Finds large files and unresolved TODOs.

./.ralph/scripts/audit.sh

Output:

๐Ÿ“Š Project Audit
Large files (>500 lines): 3
Unresolved TODOs: 7
Unused imports: 2

bench.shโ€‹

"Is it still fast?" โ€” Compares speed against the baseline.

./.ralph/scripts/bench.sh

Output:

โšก Performance Benchmark
VSA bind: 3.2x faster (was 1.2ms, now 0.38ms)
VSA bundle: 4.1x faster (was 2.5ms, now 0.61ms)
Overall: 3.6x improvement

Ralph Commandsโ€‹

ralph --monitor          # Start with live monitoring dashboard
ralph --help # Show options
ralph-enable # Enable Ralph in project
ralph-import prd.md # Convert PRD to Ralph tasks

Mathematical Foundationโ€‹

Trinity's ternary computing framework provides:

  • Information density: 1.58 bits/trit (vs 1 bit/binary)
  • Memory savings: 20x vs float32
  • Compute: Add-only (no multiply)

Trinity Identityโ€‹

ฯ†ยฒ + 1/ฯ†ยฒ = 3
where ฯ† = (1 + โˆš5) / 2 = 1.6180339...

This identity is the sacred foundation of Trinity's ternary architecture.

Sacred Constantsโ€‹

ฮผ = ฯ†^(-4) = 0.0382
ฯ‡ = 0.0618
ฯƒ = ฯ† = 1.618
ฮต = 1/3 = 0.333

These constants are validated in every production cycle.


Glossaryโ€‹

TermDefinition
Golden Chain9-link development cycle (DECOMPOSE โ†’ PLAN โ†’ SPEC โ†’ GEN โ†’ TEST โ†’ BENCH โ†’ VERDICT โ†’ GIT โ†’ LOOP)
Tech TreeStrategic roadmap with 60+ nodes across 11 branches
QuarksAtomic tasks from decomposition
Toxic VerdictBrutally honest assessment of work done
Quality GatesSequential checks (build โ†’ test โ†’ format โ†’ commit)
VIBEESpec-driven compiler (.vibee โ†’ Zig/Verilog/Python)
PASPattern Analysis System โ€” sacred math validation
Trinity Identityฯ†ยฒ + 1/ฯ†ยฒ = 3 โ€” mathematical foundation
Ternary1 computing base
VSAVector Symbolic Architecture

Further Readingโ€‹

  • VIBEE Compiler: See docsite/docs/api/vibee.md
  • Trinity Architecture: See docsite/docs/architecture/overview.md
  • Development Workflow: See docsite/docs/development/golden-chain.md
  • Tech Tree: See .ralph/TECH_TREE.md
  • Success Patterns: See .ralph/memory/SUCCESS_HISTORY.md
  • Regression Patterns: See .ralph/memory/REGRESSION_PATTERNS.md

ฯ†ยฒ + 1/ฯ†ยฒ = 3 | TRINITY AUTONOMOUS DEVELOPMENT

Ralph Repository: https://github.com/frankbria/ralph-claude-code