A Staged, Research-Informed Build

Jarvis is not 13 tools wired together. It's a staged build from outward — where solved problems stay solved.

8
Layers
139
Tests (Engram)
45
OMO Commits
46
Hooks

The 3-Type Taxonomy

The Jarvis ecosystem is categorized into three distinct types of components. This framing is critical to understanding how the system is built.

Foundation (user-built)

  • Engram (knowledge-service/) — Rust gRPC, 139 tests, COMPLETE. The MVP core.
  • Exodia — VPS daemon, Agent Mail MCP, 120+ commits.
  • fork — 45 custom commits: Coeus planning, hooks, taxonomy, 46 lifecycle hooks.
  • Coeus — recursive divide-and-conquer planning orchestrator.

Reference Implementations (studied for patterns)

  • Simulation-based testing standard (TigerBeetle) — assertion-driven integrity.
  • Multi-channel AI assistant patterns (OpenClaw) — Slack, Discord, WhatsApp.
  • Company management plane patterns (Paperclip) — org charts, budgets, approvals.
  • Overnight token optimization (Nightshift) — 50+ task taxonomy.
  • Goose — Rust agent harness (HTTP SSE) — studied, used as-is.
  • Mastra — workflow engine — studied, used as-is.

Current Tooling (used as-is)

  • beads/bd/bv — git-native issue tracking.
  • Qdrant/Typesense — infrastructure options.

The 8-Layer Stack

The architecture is divided into 8 distinct layers, from the human interface down to the context rules.

graph TB
    subgraph L1["LAYER 1 · HUMAN INTERFACE 🟢"]
        AB["Autoboard
React + Jotai + Hono
Split-panel review"]
        JCLI["jarvis CLI
packages/cli/"]
        SL["Slack (future)
webhook API"]
    end

    subgraph L2["LAYER 2 · BLUEPRINT ENGINE 🔵"]
        DSL["Blueprint DSL
~500 LOC TypeScript
createBlueprint()
shellStep() · gooseAgent()"]
        LIB["Blueprint Library
implement-feature
fix-bug · code-review
knowledge-capture"]
        BAPI["Blueprint HTTP API
run · status · list"]
    end

    subgraph L3["LAYER 3 · EXECUTION FOUNDATION 🟡"]
        MASTRA["Mastra Workflow
USE AS-IS
.then() .branch() .parallel()
suspend/resume"]
    end

    subgraph L4["LAYER 4 · AGENT HARNESS 🔴"]
        GOOSE["Goose (Rust binary)
RUN AS-IS
HTTP SSE POST /reply
NO FORK"]
    end

    subgraph L5["LAYER 5 · TOOLSHED 🟣"]
        TSCORE["Toolshed Core
MCPClient + Profiles
getToolsForProfile()"]
        subgraph SERVERS["MCP Servers"]
            KSMCP["knowledge-service-mcp ✅"]
            BDMCP["bd-mcp 🔧"]
            GITMCP["git-mcp 🔧"]
            QAMCP["quality-mcp 🔧"]
            CTXMCP["context-mcp 🔧"]
        end
        TSCORE --> KSMCP & BDMCP & GITMCP & QAMCP & CTXMCP
    end

    subgraph L6["LAYER 6 · KNOWLEDGE 🟩"]
        KS["Knowledge Service
Rust · gRPC · 139 tests
PostgreSQL + pgvector
✅ COMPLETE"]
    end

    subgraph L7["LAYER 7 · IN-LOOP COMPANION 🟠"]
        OMO["OMO (oh-my-opencode)
41 hooks · 7 events
Auto-inject context"]
        CC["Claude Code
Engineer present"]
        OMO --> CC
    end

    subgraph L8["LAYER 8 · CONTEXT RULES ⚪"]
        AGMD["AGENTS.md (canonical)
Subdirectory-scoped"]
        SYNC["sync-rules.ts
→ .goosehints
→ .cursor/rules/*.mdc"]
        AGMD --> SYNC
    end

    L1 --> L2
    DSL --> MASTRA
    DSL -->|"agent nodes"| GOOSE
    DSL -->|"tool access"| TSCORE
    KSMCP --> KS
    OMO -->|"Toolshed hook"| TSCORE

Two Modes of Operation

The system operates in two distinct modes: In-Loop (engineer present) and Out-Loop (autonomous). Both share the same knowledge layer.

flowchart TB
    subgraph INLOOP["IN-LOOP MODE (engineer present)"]
        direction TB
        ENG1["👨‍💻 Engineer"] --> CC["Claude Code"]
        CC --> OMO["OMO Hooks
41 hooks · 7 events"]
        OMO -->|"auto-inject"| KS_IN["ks_recall"]
        OMO -->|"auto-capture"| KS_IN2["ks_ingest"]
    end

    subgraph OUTLOOP["OUT-LOOP MODE (autonomous)"]
        direction TB
        ENG2["👨‍💻 Engineer"] -->|"1. write task"| AB["Autoboard / CLI"]
        AB -->|"2. trigger"| BE["Blueprint Engine"]
        BE -->|"3. agent nodes"| G["Goose HTTP SSE"]
        BE -->|"4. det. nodes"| DET["lint · test · git"]
        G --> TS["Toolshed (curated subset)"]
        BE -->|"5. memory"| KS_OUT["ks_recall / ks_ingest"]
        BE -->|"6. done"| PR["Pull Request"]
        PR -->|"7. review"| ENG2
    end

    KS[("Knowledge Service
Rust · gRPC
PostgreSQL + pgvector
✅ COMPLETE")]

    KS_IN --> KS
    KS_IN2 --> KS
    KS_OUT --> KS

Reading Map

  • 01 The Bet: Why Jarvis exists — the and the OpenClaw cautionary tale.
  • 02 The System: 8-layer architecture and component taxonomy.
  • 03 The Loop: Knowledge capture → recall → improvement cycle (Engram).
  • 04 The Agents: 13-agent hierarchy, two modes, blueprint lifecycle.
  • 05 The Principles: Constitution v2.2.0, quality gates, TigerBeetle as quality standard.
  • 06 The Roadmap: Phase 1→2→3, what's built vs studied vs deferred.
README.md docs/architecture/diagrams.md