Multi-Agent Jorvis Development Architecture

Version: 2.0 Last Updated: 2026-03-06 Status: Active coordination and onboarding model

Operational state authority:

• docs/handoff/HANDOFF_TO_NEXT_AGENT.md
• docs/handoff/CHECKPOINT.md
• docs/agent_ops/TASK_BOARD.md
• docs/agent_ops/GO_NO_GO.md
• project-local AIM KG (location="project", context="jorvis")

Use this document for role boundaries, coordination flow, and memory/onboarding architecture. Do not use it as a live runtime changelog.

For OpenClaw-specific control, role, and security boundaries, use:

• docs/architecture/OPENCLAW_CONTROL_PLANE.md
• docs/architecture/ROLE_AND_CAPABILITY_MATRIX.md
• docs/security/OPENCLAW_SECURITY_MODEL.md

Current Role Model

Canonical Coordination Surfaces

Shared Memory

• Canonical store: .aim/memory-jorvis.jsonl
• Required access mode: location="project", context="jorvis"
• Current truth belongs in *_Current entities.
• Dated entities are historical snapshots and must not be treated as current truth without revalidation.

Shared Documents

Onboarding Flow

graph TB
    A[Agent starts] --> B[Verify project-local KG]
    B --> C[Read HANDOFF_TO_NEXT_AGENT]
    C --> D[Read TASK_BOARD and GO_NO_GO]
    D --> E[Read role prompt]
    E --> F{Assigned role?}
    F -->|Architect| G[@Architect]
    F -->|Executor| H[@Executor]
    F -->|Gatekeeper| I[@Gatekeeper]
    F -->|Tester| J[@Tester]
    F -->|Unknown / mixed| K[@Universal]
    K --> L[Explicit role assignment]

Mandatory Session Start

1. Verify project-local memory with aim_memory_list_stores().
2. Read HANDOFF_TO_NEXT_AGENT.md.
3. Read TASK_BOARD.md.
4. Read GO_NO_GO.md.
5. Read the matching role prompt.
6. Only then decide whether the task is planning, implementation, review, or testing.

Worktree Guardrail

If an agent starts from .claude/worktrees/*:

• the memory server must still resolve the canonical project store at <LOCAL_USER_HOME>/Projects/Jorvis/.aim/
• worktree .aim/memory-jorvis.jsonl and .aim/memory.jsonl should bridge the canonical store
• repo-root MEMORY.md is the canonical bootstrap note
• the checked-out repo-root MEMORY.md should be present in the worktree and treated as the canonical bootstrap note there

Do not silently fall back to global memory.

Execution Model

graph LR
    U[User] --> V[@Universal or @Coordinator]
    V --> A[@Architect]
    V --> E[@Executor]
    V --> G[@Gatekeeper]
    V --> T[@Tester]
    A --> S[Stage 0 spec / sequencing]
    E --> C[Code, tests, deploy work]
    G --> R[Review, GO/NO-GO]
    T --> Q[E2E / regression evidence]
    S --> M[Update KG + SSOT]
    C --> M
    R --> M
    Q --> M

Role Boundaries

Memory and Handoff Rules

Before closing a non-trivial session:

1. Update project-local KG with verified facts or decisions.
2. Update SSOT docs if current-state truth changed.
3. Add OUTBOX evidence for completed work.
4. Keep *_Current entities compact and current-focused.
5. Keep historical lineage in dated entities instead of bloating current entities.

Current Architectural Direction

• Keep Open WebUI bridge logic thin where possible.
• Move canonical policy/control truth into Jorvis-side typed surfaces.
• Treat OpenClaw expansion as security-first work:
  1. contract normalization
  2. typed control/capability surfaces
  3. broader operator features
  4. multi-agent and channel expansion later

OpenClaw should be treated as an assistant/copilot layer, not as a gatekeeper or release authority.

OpenClaw as Assistant / Copilot Layer

OpenClaw is not one of the human governance roles. It is a product/runtime assistant layer with narrower authority.

Current intended role split:

• User Assistant
  • help/reference
  • Jorvis explainer
  • personal/work memory assistance
• Admin Observer
  • read-only monitoring context
  • recommendations
• Admin Planner (partial current mode)
  • plan-oriented guidance
  • no guarded execution gateway yet
• Future modes
  • approval-gated operator actions

OpenClaw must not be treated as:

• gatekeeper
• merge authority
• release authority
• implicit coordinator for human roles

Non-Goals

• This document does not replace runtime verification.
• This document does not grant merge or release authority.
• This document does not make old open PRs active by default.