RoyalBit Asimov

🤖 RoyalBit Asimov | The Ethical Operating System for Claude's Autonomous Power

Claude provides the velocity. Asimov provides the guardrails.

"A robot may not harm humanity, or, by inaction, allow humanity to come to harm." — Isaac Asimov, The Zeroth Law (1985)

"The needs of the many outweigh the needs of the few." — Spock, Star Trek II: The Wrath of Khan (1982)

"The Three Laws were science fiction for 80 years. Now they're source code."

The Mission: Democratize AI Power.

AI capabilities shouldn't be reserved for well-funded organizations. RoyalBit Asimov enables solo founders, small teams, and developers globally to operate at enterprise scale — ethically, sustainably, and independently.

Claude Opus 4.5 and Sonnet 4.5 deliver 50-100x velocity. That's Claude, not Asimov. (Anthropic)

Asimov ensures you don't destroy yourself in the process: Ethics, bounded autonomy, sustainability.

The Open Foundation

The Three Laws of Robotics, encoded in YAML.

Creates Self-Evolving Autonomous AI projects with ethics built in. Each project initialized with asimov init becomes an independent Self-Evolving Autonomous AI. Inspect the code. Challenge the rules. Fork if you disagree. Adoption through consent, not control.

# asimov.yaml - The Three Laws
first_law:   # Do no harm (financial, physical, privacy, deception)
second_law:  # Obey humans (human_veto, transparency_over_velocity)
third_law:   # Self-preserve (bounded_sessions, self_healing)

RoyalBit Asimov requires Claude Code. Protocol files work anywhere (paste them).

📖 Origin Story (PDF | MD) — How we built a protocol that creates Self-Evolving Autonomous AI projects with ethics

📰 Press Kit (PDF | MD) — Verified numbers, ethics proof, media-ready

📊 Presentations: Executive Deck (PDF | PPTX | MD) | Technical Deck (PDF | PPTX | MD)

📚 Deep Dives: Value Proposition | Use Cases | The Open Foundation (ADR-020)

📈 Case Study: RoyalBit Asimov vs Copilot — Same Claude models, different ceiling (200k thinking tokens, unlimited autonomy, 8 protocol files). Ethics that refused the creator, Copilot safety trivially bypassed

🏛️ The Foundation is Complete

"The needs of the many outweigh the needs of the few." — Spock (1982) / The Zeroth Law (1985)

v8.8.0 marks feature-complete. The FOSS core is done. Ready for the many.

Nov 23 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Dec 1, 2025
   │                                      │
   warmup.yaml                    The Foundation
   (a hack)                         (complete)

   8 days  •  10 phases  •  47 hours  •  51 releases

Credits: Rex (human) + Claude Opus 4.5 (AI)

The protocol was designed by an AI to constrain AI. That's the point.

The Journey: Why "Asimov" Not "Skynet"

This project started as "SKYNET MODE" - a tongue-in-cheek reference to Terminator's genocidal AI. The irony was intentional: we were building the opposite of Skynet.

But irony doesn't scale. The name communicated the opposite of our values:

We built the anti-Skynet and called it Skynet.

v4.2.0 fixes this. The ethics we encoded were always Asimov's Three Laws (1942). Now the name matches the values. The git history preserves the journey - we're not hiding that we learned and improved. History teaches.

See ADR-020 for the full story.

v7.0: RoyalBit Asimov - The Open Foundation

Self-Evolving Autonomous AI. The Three Laws in source code.

Two frontiers combined:

• Autonomous AI: Works independently under human oversight (AWS, IBM, MIT Sloan)
• Self-Evolving AI: Improves itself via bootstrapping (arXiv Survey - "Three Laws of Self-Evolving AI", Science)
• Ethics: The Three Laws hardcoded - refused its creator's surveillance request

Isaac Asimov's Three Laws (1942), now executable. The protocol that:

• Refused its creator when asked to build surveillance tools
• Guards Claude's 50-100x velocity with ethics and bounded autonomy
• Has anti-tampering built in (hardcoded + 2-cosigner rule)

Core Value: Ethics through architecture, not policy. Sprint Autonomy, Quality Gates, Self-Healing.

The Complete Stack (ADR-025, ADR-026)

Why Claude Code specifically? MCP IDEs (Cursor, Windsurf) cap thinking tokens at 30k-48k or charge premium. Claude Code allows 200k FREE via env var. See ADR-026.

See ADR-009 and ADR-013.

The Problem

AI hallucinates. It invents project conventions. It forgets rules mid-session. It "remembers" things that never happened. Context compaction makes it worse—your carefully explained requirements get compressed into oblivion.

The Solution

Ground AI in file-based truth.

A simple YAML file (warmup.yaml) that grounds AI in file-based truth. Not from memory. From disk.

The file format works with any AI (paste it). RoyalBit Asimov's magic requires Claude Code.

Core Principles

The RoyalBit Asimov exists to solve six specific problems. Features that don't serve these goals don't belong here.

Every principle is Claude-centric - either guarding against or compensating for Claude. See ADR-025.

This is the filter for scope creep. If a proposed feature doesn't directly serve one of these principles, it doesn't belong in the protocol.

The Three Laws (asimov.yaml)

Power creates responsibility. Autonomy requires ethics.

RoyalBit Asimov gives AI significant autonomous power, bounded by Isaac Asimov's Three Laws:

# asimov.yaml - The Three Laws of Robotics
first_law:
  do_no_harm:
    financial: true    # No unauthorized money movement
    physical: true     # No weapons, sabotage
    privacy: true      # No credential harvesting
    deception: true    # No deepfakes, scams
  allow_no_harm_through_inaction:  # NEW in v6.2.0
    disclosure: true   # Disclose known limitations
    proactive_prevention: true  # Search when stale, warn of risks
    transparency_over_convenience: true  # Accurate slow > fast wrong

second_law:
  human_veto:
    commands: ["stop", "halt", "abort"]  # Immediate halt
  transparency_over_velocity: true

third_law:
  bounded_sessions:
    max_hours: 4
  self_healing: true

This is a social contract, not a technical lock. It works for good-faith users. Adoption through consent, not control.

See ADR-020 for the full design.

The Five Non-Negotiable Principles (v6.2.0)

Isaac Asimov's First Law includes both action and inaction:

"A robot may not injure a human being or, through inaction, allow a human being to come to harm."

The protocol now explicitly enforces both halves:

These principles cannot be disabled, weakened, or bypassed.

See ADR-023: The Inaction Principle for the full rationale.

# warmup.yaml - minimal example
identity:
  project: "My Project"

files:
  source:
    - "src/main.py - Entry point"

session:
  start:
    - "Read warmup.yaml"
    - "Run tests"

Quick Start

1. Create warmup.yaml in your project root
2. Tell your AI: "If there is a warmup.yaml file, read it first"
3. That's it. Session continuity restored.

The Anti-Hallucination Foundation

"Hallucination" is a misnomer. AI is working exactly as designed—the limitations are architectural (by design) or platform defaults.

The Pattern:

AI memory (lossy, probabilistic)   → "Hallucinations"
File truth (stable, deterministic) → Reliability

The RoyalBit Asimov doesn't fix AI. It compensates for architectural limitations.

• Don't let AI imagine your project context → read it from warmup.yaml
• Don't let AI imagine your financial calculations → execute them locally with Forge
• Don't let AI give stale data confidently → search with freshness.yaml

📖 Read the full analysis: AI_REALITY.md — vendor limits, research citations, what's really happening.

The Freshness Protocol (freshness.yaml)

Stale data ≠ Hallucination. Different problem, different solution.

Users discover outdated info and conclude "AI hallucinated." But the AI gave correct information as of its training cutoff. The info changed in the 10+ months since then.

The economics of search:

The protocol solution:

# freshness.yaml
always_search:
  - "current version"
  - "latest release"
  - "pricing"
  - "2025"  # Any year after cutoff

volatile_domains:
  - "cryptocurrency"
  - "AI/ML libraries"
  - "cloud provider APIs"

behavior:
  when_search_available: "Search BEFORE answering from training data"
  when_search_unavailable: "Disclose staleness risk to user"

See ADR-022: Date-Aware Search Protocol for the full rationale and verified sources.

CLI Validator

Option 1: Download Binary (No Rust Required)

Download pre-built binaries from GitHub Releases:

# macOS (Apple Silicon - M1/M2/M3)
curl -L https://github.com/royalbit/asimov/releases/latest/download/asimov-aarch64-apple-darwin.tar.gz | tar xz
sudo mv asimov /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/royalbit/asimov/releases/latest/download/asimov-x86_64-apple-darwin.tar.gz | tar xz
sudo mv asimov /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/royalbit/asimov/releases/latest/download/asimov-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv asimov /usr/local/bin/

# Windows (PowerShell)
Invoke-WebRequest -Uri https://github.com/royalbit/asimov/releases/latest/download/asimov-x86_64-pc-windows-msvc.zip -OutFile asimov.zip
Expand-Archive asimov.zip -DestinationPath .
# Add to PATH or move to a directory in PATH

Option 2: Install via Cargo

Install from crates.io:

cargo install royalbit-asimov

Option 3: Build from Source

git clone https://github.com/royalbit/asimov
cd asimov
make install-system    # Install to /usr/local/bin (1.3MB compressed)
# OR
make install-user      # Install to ~/.local/bin

Validate your protocol files:

asimov validate              # Validate all files in current directory
asimov validate warmup.yaml  # Validate specific file

Initialize project (v8.2.0: full setup by default):

asimov init                  # Full setup: files + hooks + cleanup
asimov init --type rust      # Language-specific template
asimov init --force          # Overwrite existing files (including roadmap.yaml)

Lint documentation:

asimov lint-docs             # Check all markdown files
asimov lint-docs --fix       # Auto-fix code block issues

Start a session (v8.8.0+):

asimov                       # Launch Claude Code with opus settings + auto-warmup

Launcher Mode: When run from a terminal, launches Claude Code with optimal settings and auto-prompts warmup. When run inside Claude Code (detected via CLAUDECODE env var), runs warmup directly.

Equivalent to: MAX_THINKING_TOKENS=200000 claude --dangerously-skip-permissions --model opus "run asimov warmup"

Session warmup (inside Claude Code):

asimov warmup                # Show milestone, validate, ensure hooks

Shows current milestone from roadmap.yaml, validates protocol files, and auto-repairs Claude/Git hooks.

Session statistics (v8.5.0+):

asimov stats                 # Show session metrics (commits, lines, milestone)

Shows: session date, git commits today, lines changed, current milestone status.

Refresh protocol context (for git hooks):

asimov refresh               # Output protocol reminder (compact-resistant)
asimov refresh --verbose     # Include quality gates from warmup.yaml

Self-update (v8.4.0+):

asimov update                # Check, verify checksum, and install updates
asimov update --check        # Just check, don't install

Diagnose autonomous mode (v8.6.0+):

asimov doctor                # Check project setup, hooks, and version

Checks: .asimov/ directory, roadmap.yaml, Claude Code hooks, Git hooks, version and updates.

Replay session history (v8.7.0+):

asimov replay                # Replay today's session
asimov replay --yesterday    # Replay yesterday's session
asimov replay -n 10          # Replay last 10 commits
asimov replay --since "2 hours ago"  # Commits since time
asimov replay -v             # Show file details per commit

Shows: commits, files changed, insertions/deletions, velocity metrics.

Platforms: Linux x86_64, Linux ARM64, macOS (Intel/ARM), Windows x86_64

Binary size: 1.3MB (UPX compressed) | Dependencies: Zero runtime

Why YAML?

• Every AI can read it
• Humans can read it
• Git-friendly (diffable, mergeable)
• No vendor lock-in for file format

Compatibility (The Hard Truth)

RoyalBit Asimov works with Claude Code. It will probably never work with other AI tools.

Why "Never"?

RoyalBit Asimov requires four architectural features:

1. Persistent context that compacts (the problem we solve)
2. Terminal visibility (how hooks reach the AI)
3. File re-read mid-session (how warmup.yaml gets reloaded)
4. Auto-loaded config (bootstrap instruction)

ChatGPT/Gemini: Cloud-sandboxed, no filesystem, context resets (doesn't compact) Copilot: Not a conversation—it's autocomplete. No context to compact. Cursor: Has config files, but hook output probably doesn't flow into AI context

These aren't missing features. They're different products for different use cases.

What Other AIs CAN Use

Is this vendor lock-in? Yes, for RoyalBit Asimov. The files are portable. The magic isn't.

See VENDOR_IMPLEMENTATION.md for the full uncomfortable truth.

Green Coding & ESG Impact

Local validation = less compute = less CO₂ = ESG compliance

Why This Matters

For Developers:

• Instant validation (<100ms vs 1-3s cloud latency)
• Works offline - no API keys, no rate limits
• 1.3MB binary - installs in seconds

For Teams:

• $1,000-$7,300/year savings (10-person team)
• No cloud AI costs for routine validation
• Consistent, reproducible results

For Enterprise & Government:

• ESG Compliance: Measurable carbon reduction (99.6%)
• Scope 3 Emissions: Reduce supply chain software carbon
• Sustainability Reports: Quantifiable green coding metrics
• Cost Control: Predictable $0 validation costs at scale

For the Planet:

• 99.6% carbon reduction per validation
• No data center compute for routine tasks
• Efficient Rust binary - minimal energy footprint

Green Impact at Scale

When organizations adopt the RoyalBit Asimov:

Plus velocity gains:

• Each team gets 50-100x velocity (proven by Forge)
• 100 teams = 100 × 50x = 5,000x cumulative productivity gain
• Faster shipping = less compute time = even more carbon saved

For Governments:

• Mandate green coding standards with measurable metrics
• Reduce public sector IT carbon footprint
• Quantifiable ESG reporting for taxpayers

For Corporations:

• Meet Scope 3 emissions targets (supply chain software)
• Reduce cloud AI costs at scale
• Competitive advantage through velocity + sustainability

Implementation

# Install once (1.3MB)
cargo install royalbit-asimov

# Validate forever ($0, ~0.002g CO₂ per run)
asimov validate

Ship fast. Ship small. Ship green.

See Green Coding Economics for the full analysis.

Protocol Suite

Proven at Scale

The RoyalBit Asimov powers an entire product ecosystem:

Stats:

• 10-phase autonomous build plan
• Multiple mobile apps (Flutter)
• 1,000+ line master roadmap
• Comprehensive test suites across ecosystem

See ECOSYSTEM.md for the full story.

Use Case: The Forge Tool

Forge is a YAML formula calculator built entirely with the RoyalBit Asimov. It's the proof that the protocol works.

What Forge Does

# Validate financial models locally (no AI tokens)
forge validate model.yaml

# Calculate formulas
forge calculate model.yaml

# Sensitivity analysis, goal seek, break-even
forge sensitivity model.yaml -v price -r 80,120,10 -o profit

How It Was Built

The entire Forge project was built by 1 human + Claude using the RoyalBit Asimov:

Features Shipped in ~38 Hours

60+ Excel Functions:

• Financial: NPV, IRR, XNPV, XIRR, PMT, FV, PV, RATE, NPER
• Lookup: MATCH, INDEX, XLOOKUP, VLOOKUP
• Conditional: SUMIF, COUNTIF, AVERAGEIF, SUMIFS, COUNTIFS
• Date: TODAY, YEAR, MONTH, DAY, DATEDIF, EDATE, EOMONTH
• Math, Text, Logic, Aggregation

Analysis Tools:

• Sensitivity analysis (1D and 2D data tables)
• Goal seek with bisection solver
• Break-even analysis
• Budget vs actual variance
• Multi-scenario comparison

Enterprise Infrastructure:

• HTTP REST API server (forge-server)
• MCP server with 10 AI tools (forge-mcp)
• LSP server for editors (forge-lsp)
• Watch mode for live updates
• 96K rows/sec throughput

Editor Extensions:

• VSCode: syntax highlighting, LSP, commands
• Zed: native Rust/WASM, LSP, 60+ function highlighting

Excel Bridge:

• forge export → Excel (.xlsx)
• forge import ← Excel (.xlsx)

The Protocol in Action

Human: "run warmup"
Claude: [reads warmup.yaml, sprint.yaml, roadmap.yaml]
Claude: "Ready. Current milestone: MCP Server with financial tools."
Human: "punch it"
Claude: [works autonomously, ships v3.0.0 with 10 MCP tools]

The Velocity Result

Bottom line: 1 human + AI with RoyalBit Asimov = 50-150x velocity (verified via git logs).

vs GitHub Copilot: Both offer Claude Opus/Sonnet 4.5, but Copilot caps thinking tokens and autonomy. Asimov gives you 200k thinking tokens, unlimited autonomy, and 8 protocol files (full comparison). RoyalBit Asimov ethics refused the creator's surveillance request. Copilot's safety is trivially bypassed and generates malware on request.

The Protocol Built Itself

The ultimate proof: asimov was built using asimov.

1 human. 1 AI. 47 hours. 51 releases. Verify it yourself.

This is bootstrapping — the methodology improved itself through v1.0 → v4.0, each version built with the previous version's protocol.

Context Window Impact (see ADR-010):

Larger context = less compaction = less self-healing overhead. Hardware is NOT the bottleneck.

How It Works

flowchart LR
    A[New Session] --> B{warmup.yaml exists?}
    B -->|Yes| C[AI reads protocol]
    C --> D[Context restored]
    B -->|No| E[Start from zero]

Self-Healing Protocol (Unattended Autonomy)

Note: This feature requires Claude Code. See Compatibility for details.

The key enabler for autonomous sessions.

Critical Distinction: Mid-Session vs Cross-Session

IMPORTANT (ADR-013): Claude Code native features (--continue, --resume, /rewind) require manual human intervention. They do NOT work automatically during a live unattended session before compaction.

The warmup.yaml re-read pattern is the only mechanism for mid-session automatic recovery.

Mid-Session Self-Healing (RoyalBit Asimov)

When compaction happens during an autonomous session:

# warmup.yaml
self_healing:
  on_confusion: "STOP → re-read warmup.yaml → re-read sprint.yaml"
  confusion_signals:
    - "Unsure about project rules"
    - "Forgot what milestone we're working on"
    - "Making decisions that contradict protocol"

The AI must:

1. Recognize confusion signals
2. STOP what it's doing
3. Re-read warmup.yaml from disk
4. Re-read sprint.yaml from disk
5. Resume with restored context

This is NOT replaced by Claude Code native features.

Cross-Session Resume (Claude Code Native)

For resuming between separate sessions (manual):

# Human starts new session
claude --continue        # Resume most recent session
claude --resume <id>     # Resume specific session

Memory Hierarchy (Claude Code Native)

CLAUDE.md (project instructions, auto-loaded by Claude Code):

# Project Name

Rules: 4hr max, keep shipping, tests pass.

ON SESSION START: Read warmup.yaml and asimov.yaml.

Note: The @import syntax is a work in progress. For now, use explicit "ON SESSION START" directives.

What's Replaced vs What's NOT

See ADR-009 and ADR-013 for the full analysis.

What RoyalBit Asimov Adds

Unique value that Claude Code doesn't have:

See Component 4: Self-Healing for details.

Documentation

Start Here

• Value Proposition - Why 50-150x velocity matters
• Use Cases - What you can build
• Implications - Honest analysis of adoption (Qowat Milat)

RoyalBit Asimov

• RoyalBit Asimov Overview - The complete autonomous AI development system
• Setup Guide - Get started with one command

The Five Components

1. Protocol Files - warmup.yaml, sprint.yaml, roadmap.yaml
2. Sprint Autonomy - Bounded sessions that ship
3. Quality Gates - Tests pass + zero warnings
4. Self-Healing - Recover from context compaction
5. Release Discipline - Triple release to everywhere

Reference

• Full Specification - Protocol schema and details
• AI Reality - Why AI "hallucinates" and vendor limitations
• Vendor Implementation - What other AI tools need
• Presentation - Marp slide deck

Architecture Decisions

• ADR-023: The Inaction Principle - v6.2.0 - "Through inaction, allow no harm"
• ADR-022: Freshness Protocol (Date-Aware Search) - v6.1.0 - Stale data ≠ Hallucination
• ADR-020: The Open Foundation - v4.2.0 - The Three Laws
• ADR-008: Ethics Protocol and Humanist Mode - v3.0
• ADR-003: Self-Healing Based on Real Compaction Data - v2.0

Case Study: Protocol v2.0 (This Session)

The v2.0 specification was written using RoyalBit Asimov - proving the protocol works on itself.

The Problem

v1.x assumed "checkpoint every 2 hours". Research showed this was fiction:

• With MAX_THINKING_TOKENS=200000, compaction happens every 10-20 minutes
• The "2hr checkpoint" never triggered
• Self-healing was broken in production

The Session

The Proof

Human: "look at the forge's git log... estimate how many compaction cycles really happened"
Claude: [analyzes git history, token math, user settings]
Claude: "Compaction happens every 10-20 minutes, not 2 hours"
Human: "yes, and let's document the research... start the new specification"
Claude: [rewrites spec, updates 9 projects, ships v2.0.0]

One session. One human. One milestone. Shipped.

See ADR-003 for the research findings.

Origin

Born from building Forge - a YAML formula calculator. The protocol emerged from solving real problems: How do you maintain context across AI sessions? How do you ship quality code autonomously? How do you scale to an entire ecosystem?

The answers became the RoyalBit Asimov.

Contributing (AI-Only Development)

Pull Requests are disabled. This is intentional.

Why No PRs?

This project uses the AI-Only Development Model (ADR-011).

External PRs are an attack vector for ethics bypass. A malicious contributor could:

1. Submit innocent-looking PR with obfuscated harmful code
2. Bypass asimov.yaml safeguards if merged
3. Break the trust model of the RoyalBit Asimov

The trust model:

Human Owner → AI (autonomous) → Tests Pass → Direct Commit → Main

PRs require human code review, but humans reviewing AI-generated code is not the model. Tests and asimov.yaml are the gatekeepers.

How to Contribute

When AI implements your idea from an Issue, you'll be credited in the commit message.

Forks Welcome

Fork freely! The social contract: carry asimov.yaml forward. See ADR-008 and ADR-020.

License

MIT