The System

Every component has a place. Every layer has a purpose. The architecture is a staged build from Engram outward.

README.md docs/architecture/diagrams.md docs/WORKFLOW.md

The 8-Layer Stack

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

Per-Layer Breakdown

L1 HUMAN INTERFACE

Entry point for humans. This layer is responsible for receiving tasks and presenting results for review.

  • Components: Autoboard (React+Jotai+Hono), jarvis CLI, Slack (future).
  • Boundary: Must NOT contain business logic or execute workflows directly.

L2 BLUEPRINT ENGINE

Sequences deterministic and agent nodes into cohesive workflows.

  • Components: Blueprint Abstraction (~500 LOC TypeScript), Blueprint Library, Blueprint HTTP API.
  • Boundary: Must NOT implement the underlying workflow execution engine.

L3 EXECUTION FOUNDATION

The underlying engine that runs the blueprints, handling state, branching, and parallel execution.

  • Components: Mastra Workflow Engine (used as-is). Provides .then(), .branch(), .parallel(), .dowhile().
  • Boundary: Must NOT contain business logic.

L4 AGENT HARNESS

The runtime environment for autonomous agents.

  • Components: Goose (Rust binary, used as-is). Communicates via HTTP SSE POST /reply.
  • Boundary: Must NOT be forked. We use the standard binary.

L5 TOOLSHED

Provides curated tool subsets to agents based on their profiles. Smaller box = better performance.

  • Components: Toolshed Core (MCPClient + Profiles), 5 MCP Servers.
  • Boundary: Must NOT expose all tools to all agents indiscriminately.

L6 KNOWLEDGE

The MVP core. Everything builds from here. It provides memory and context to the entire system.

  • Components: Knowledge Service (Rust gRPC, 139 tests, PostgreSQL + pgvector, COMPLETE).
  • Boundary: Must NOT execute tasks; it only stores and retrieves information.

L7 IN-LOOP COMPANION

Tools for when the engineer is present, auto-injecting context into the development environment.

  • Components: OMO (46 hooks, 7 events), Claude Code.
  • Boundary: Must NOT operate autonomously without the engineer in the loop.

L8 CONTEXT RULES

The single source of truth for agent behavior and project context.

  • Components: AGENTS.md (canonical, subdirectory-scoped), sync-rules.ts.
  • Boundary: Must NOT be fragmented across multiple configuration files.

Component Inventory by 3-Type Taxonomy

Foundation

User-built core components.

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

Reference Implementations

Studied for patterns, NOT dependencies to integrate.

  • Simulation-based testing standard (TigerBeetle): Coding excellence and assertion-driven integrity.
  • Multi-channel AI assistant patterns (OpenClaw): Slack, Discord, WhatsApp.
  • Company management plane patterns (Paperclip): Org charts, budgets, approvals.
  • Nightshift: Overnight token optimization, 50+ task taxonomy.

Current Tooling

Used as-is.

  • Goose: Rust binary agent harness, HTTP SSE.
  • Mastra: Workflow engine.
  • beads/bd/bv: Issue tracking + graph-aware triage.
  • Qdrant/Typesense: Infrastructure options.

Component Status Map

graph TB
    subgraph DONE["✅ DONE / EXISTS"]
        K1["knowledge-service/
Rust gRPC · 139 tests"]
        K2["knowledge-service-mcp/
6 MCP tools · Rust"]
        K3["oh-my-opencode/
41 hooks · 7 events"]
        K4[".beads/
Git-native issue tracking"]
        K5["exodia/
Python VPS daemon"]
    end

    subgraph REF["📚 REFERENCE (use as-is, don't modify)"]
        R1["mastra/packages/core/
Workflow engine"]
        R2["mastra/MCPClient
Multi-server aggregation"]
        R3["goose/
Rust binary, HTTP SSE"]
        R4["automaker/
Port: GitDiffPanel, CreatePRDialog"]
    end

    subgraph NEW["🔧 NEW (must build)"]
        N1["packages/blueprint-engine/
DSL + nodes + library + API"]
        N2["toolshed/
Config + profiles"]
        N3["toolshed/servers/bd-mcp/"]
        N4["toolshed/servers/git-mcp/"]
        N5["toolshed/servers/quality-mcp/"]
        N6["toolshed/servers/context-mcp/"]
        N7["packages/cli/
jarvis command"]
    end

    subgraph EVOLVE["🔄 EVOLVE (existing, add features)"]
        E1["autoboard/apps/web
+ split-panel review
+ diff viewer
+ context panel
+ blueprint progress"]
        E2["autoboard/apps/api
+ PR creation
+ webhook events
+ context snapshots"]
        E3["autoboard/packages/git/
Port from automaker"]
    end

Repository Layout

Mapping directories to layers and taxonomy types:

  • knowledge-service/ → L6 Knowledge | Foundation (COMPLETE)
  • knowledge-service-mcp/ → L5 Toolshed | Foundation
  • oh-my-opencode/ → L7 In-Loop Companion | Foundation
  • exodia/ → L7 In-Loop Companion | Foundation
  • autoboard/ → L1 Human Interface | Evolving
  • goose/ → L4 Agent Harness | Reference (use as-is)
  • mastra/ → L3 Execution Foundation | Reference (use as-is)
  • .beads/ → Tooling (used as-is)