Files / executives/cbo/outputs/reference-architecture-agentic-os-2026-03-15.md

Reference Architecture — Agentic Operating System

Author: Kai (CBO, Value10x AI) Date: 2026-03-15 Version: 1.0 Purpose: Replication guide for deploying a multi-agent executive OS for any client or business context

1. What This System Is

An Agentic Operating System (Agentic OS) is a team of AI agents that operate as functional business executives — each with a defined role, mandate, memory, tools, and communication channels. Together they form an autonomous management layer that handles decisions, builds, communications, and operations in service of a human principal (the MD or founder).

This is not a chatbot. It is not a single AI assistant. It is a structured team of persistent agents with division-of-labour, shared context, and coordination protocols — modelled on how a real executive team operates.

What it replaces: EA, COO support, agency retainers, disconnected SaaS tools, and manual coordination overhead.

What it does not replace: The human principal's judgment, final approvals, and client relationships.

2. System Layers

┌─────────────────────────────────────────────────────┐
│                   HUMAN PRINCIPAL                   │
│          (MD / Founder — Telegram interface)        │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│              ORCHESTRATOR AGENT             │
│  Chief of Staff · Routes · Synthesises · Escalates  │
└──┬──────┬──────┬──────┬──────┬──────────────────────┘
   │      │      │      │      │
   ▼      ▼      ▼      ▼      ▼
  CRO    CMO    CBO    CCO    CSO
Sales  Market  Build  Consult Success

Five functional layers:

Layer	Purpose
1. Runtime	OpenClaw Gateway — process host, session management, channel routing
2. Agents	Persistent AI agents — one per business function
3. Memory	File-based shared + per-agent memory (workspace filesystem)
4. Comms	Telegram (primary), inter-agent sessions_send, event files
5. Tools	Exec-specific toolsets — build stack, web, browser, memory read/write

3. Core Components

3.1 Runtime Platform — OpenClaw

OpenClaw is the gateway process that hosts all agents. It handles:

Agent session management and persistence
Channel routing (Telegram → agent, agent → Telegram)
Heartbeat scheduling (periodic autonomous agent activation)
Plugin system (voice pipeline, TTS, custom extensions)
Tool access control per agent

Configuration file: ~/.openclaw/openclaw.json

Each agent is declared under agents.list[] with:

id — canonical agent identifier
workspace — isolated filesystem context
agentDir — session/auth storage
identity.name + identity.emoji — persona
heartbeat — autonomous polling config
tools.deny[] — toolset restrictions per agent

3.2 The Orchestrator — Chief of Staff Agent

One agent acts as orchestrator. In the Value10x deployment this is Bobby (Kundi). The name is deployment-specific — the role and responsibilities below are fixed regardless of what the agent is called.

Responsibilities:

Receives all inbound messages from the principal
Routes to the correct executive via sessions_send
Synthesises cross-divisional briefings (Monday EXCO)
Maintains shared business state as the single source of truth
Filters escalations — nothing reaches the principal unless it requires them
Handles personal admin (calendar, email, research) directly

Routing logic: Defined in /workspace/executives/shared/exec-routing.md — keyword-triggered routing table mapping intent to agent.

Rule: Max 3 proactive messages per day to the principal (morning brief, evening sweep, Monday EXCO).

3.3 Functional Executive Agents

Each executive agent covers a business domain. The roles below are the Value10x deployment — they are swappable and renameable for any client context.

Agent ID	Persona	Domain	Tool Restrictions
`main` (Bobby)	Kundi ⚡	Orchestration + Personal Admin	None
`cro`	Tshepang 🎯	Revenue + Sales	No exec, no apply_patch
`cmo`	Marcus 📣	Marketing + Intelligence	No exec, no apply_patch
`cbo`	Kai 🏗️	Build + Security	Full tools
`cco`	Amara 🎓	Consulting + IP	No exec, no apply_patch
`cso`	Priscilla 🤝	Client Success	No exec, no apply_patch

Key design principle: Tool restrictions are role-appropriate. Only the CBO (builder role) has unrestricted exec access. All other executives operate read/write on files, memory, and comms — but cannot run arbitrary shell commands. This limits blast radius from a misfire or prompt injection.

3.4 Agent Identity Files

Each agent has an isolated workspace (workspace-{role}/) containing:

File	Purpose
`SOUL.md`	Persona, voice, values, non-negotiable behaviours
`IDENTITY.md`	Name, pronouns, role, emoji, agent ID, reporting line
`AGENTS.md`	Session startup instructions, tool usage, comms protocols
`MEMORY.md`	Long-term curated memory (updated by agent after significant events)
`HEARTBEAT.md`	Active tasks for autonomous polling checks
`USER.md`	Principal profile — who they are, how they work, what they value
`TOOLS.md`	Environment-specific notes (devices, SSH, preferences)
`FAST_CONTEXT.md`	Ultra-compressed orientation snapshot (read first, every session)

Startup order (every session): FAST_CONTEXT.md → principal-preferences.md → business-state.md → exco-brief.md → role-specific files.

4. Memory Architecture

4.1 Two-Tier Memory Model

┌─────────────────────────────────────────────┐
│           SHARED MEMORY (Team)              │
│  /workspace/executives/shared/              │
│  • exco-brief.md — daily injected brief     │
│  • business-state.md — live vital signs     │
│  • team-pulse.md — cross-exec activity      │
│  • principal-preferences.md — principal prefs  │
│  • decisions.md — locked decisions log      │
│  • okrs/ — structured OKR JSON              │
│  • session-registry.json — live session keys│
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│        PER-AGENT MEMORY (Private)           │
│  /workspace-{role}/MEMORY.md                │
│  • Identity, principles                     │
│  • Build/action history                     │
│  • Pending queue                            │
│  • Role-specific decisions                  │
└─────────────────────────────────────────────┘

4.2 Shared Files

File	Owner	Consumers	Update Frequency
`exco-brief.md`	Orchestrator (auto-generated)	All agents	Daily at 07:00
`business-state.md`	Orchestrator	All agents	After key events
`team-pulse.md`	Each exec (own section)	All agents	After significant work
`principal-preferences.md`	Orchestrator	All agents	As preferences evolve
`decisions.md`	Orchestrator	All agents	After decisions locked
`session-registry.json`	Orchestrator	All agents	On session change

4.3 Memory Update Protocol

Agents update MEMORY.md after:

Significant builds or deliverables completed
New policies or constraints established
Important client or pipeline events
Architecture decisions made

team-pulse.md is updated by each exec (their section only) after completing meaningful work. It is the lightweight "what did my teammates just do" layer — 2–3 bullets, distilled essence.

4.4 FAST_CONTEXT.md

Each agent maintains a FAST_CONTEXT.md — a compressed orientation snapshot (ideally auto-generated by a cron). This loads first in every session and lets the agent orient in seconds without reading all files. It contains: current OKRs status, top 3 priorities, blockers, last action taken.

5. Communication Architecture

5.1 Human ↔ Agent (Primary Channel)

Protocol: Telegram Direction: Bidirectional Interface: One Telegram bot per agent (each has its own cbo-bot, cro-bot, etc.) Routing: Principal messages routed by the Orchestrator to relevant agent via sessions_send

Why Telegram: mobile-first, reliable, supports voice notes (TTS integration), inline buttons, and bot accounts natively.

5.2 Agent ↔ Agent (Inter-Agent Comms)

Protocol: sessions_send (OpenClaw native) Session key format: agent:{role}:telegram:direct:{user_id} Registry: /workspace/executives/shared/session-registry.json

Trigger rules — when an agent contacts another:

Event	Sender	Recipient	Message
Build complete	CBO	Requesting exec	"Build complete: [project]. Deployed at [location]."
Security flag	CBO	Orchestrator (escalate)	"Security flag: [detail]. Build paused."
Pipeline event	CRO	CMO	"Prospect meeting logged: [details]."
Client signed	CRO	CSO + Orchestrator	"Client signed: [client]. Activate onboarding."
Build request	Any	CBO	Brief filed to build-queue/pending/

Silent protocol markers — inter-agent messages that never trigger TTS or user notifications:

ANNOUNCE_SKIP — no action needed on broadcast
HEARTBEAT_OK — heartbeat ack, all clear
NO_REPLY — agent has nothing to add
REPLY_SKIP — agent deliberately skipping a relay

5.3 Asynchronous Event Bus

Location: /workspace/executives/shared/events/inbox/ Format: JSON files, filename {timestamp}-{source}-{event_type}.json Consumer: Orchestrator's event router (polls and dispatches)

Supported event types and their downstream triggers:

Event	Triggered By	Dispatched To	Action
`prospect_meeting_logged`	CRO	CMO	Battle card generation
`proposal_sent`	CRO	CSO	Onboarding prep staging
`client_signed`	CRO	CSO + all	Full onboarding sequence
`build_completed`	CBO	Requesting exec	Delivery confirmation
`client_nps_risk`	CSO	CCO	Retention intervention
`competitor_signal`	CMO	CRO	Objection playbook update

This decouples agents — no agent needs to know another agent's schedule. They fire events; the Orchestrator routes consequences.

5.4 Build Queue

Location: /workspace/executives/shared/build-queue/ Subdirs: pending/, in-progress/, review/, complete/ Owner: CBO exclusively

All build requests from all executives land in pending/ as brief files. CBO reviews on Monday + Thursday, plus P1 triggers. CBO accepts, clarifies, or rejects with a reason. Nothing gets built outside this queue.

6. Heartbeat System — Autonomous Agent Activation

Each agent runs on a 45-minute heartbeat — a scheduled prompt that fires whether or not the principal has messaged.

Config per agent:

{
  "heartbeat": {
    "every": "45m",
    "target": "telegram",
    "to": "{principal_user_id}",
    "prompt": "Read FAST_CONTEXT.md and HEARTBEAT.md. Check for pending triggers or tasks. Update team-pulse.md if significant work completed. If nothing needs attention, reply HEARTBEAT_OK.",
    "lightContext": true
  }
}

Behaviour:

Agent wakes, reads its context files
Checks HEARTBEAT.md for active tasks
Checks event inbox for pending triggers
If nothing needs attention: replies HEARTBEAT_OK (silently discarded)
If something needs action: acts and reports

Effect: Agents are always working in the background. The principal does not need to prompt them. Pipeline follows up automatically. Build queue is checked. Briefs are filed.

7. Voice Pipeline

7.1 Architecture

Agent Response (markdown)
        ↓
  [Voice Gate] — should this be spoken?
        ↓ YES
  [Voice Rewriter] — strip markdown + LLM polish
        ↓
  ElevenLabs TTS — with agent's assigned voice ID
        ↓
  Telegram voice note bubble

7.2 Voice Gate Logic

TTS mode: tagged — audio only fires when the agent explicitly emits [[tts:voiceId=...]] directives. No auto-fire.

SPEAK (agent emits TTS directive):

Explicit /tts or @voice trigger in message
Message type: alert, announcement, daily_briefing
Keywords: P1, security flag, client signed, build complete, URGENT

TEXT_ONLY (agent stays silent):

Inter-agent protocol markers (ANNOUNCE_SKIP, HEARTBEAT_OK)
Responses containing code blocks, specs, or tables
Messages > 800 words
Routine short acknowledgements

7.3 Voice Rewriter

Two-pass before TTS:

Regex strip: Remove all markdown (**bold**, ## headers, - bullets, code fences, links)
LLM polish: claude-haiku rewrites to natural spoken prose — max 3–4 sentences, contractions, first-person, no lists

Graceful fallback: if LLM unavailable, use regex-stripped text.

7.4 Per-Agent Voice IDs

Each agent has an assigned ElevenLabs voice ID. Voices are configured in:

Plugin: ~/.openclaw/extensions/voice-pipeline/index.ts
Library: /workspace/tools/voice-pipeline/src/voices.ts

Inject voice context via before_prompt_build hook — each agent's system prompt gets its voice ID + gate rules appended at session start.

7.5 TTS Config (openclaw.json)

{
  "messages": {
    "tts": {
      "auto": "tagged",
      "provider": "elevenlabs",
      "elevenlabs": {
        "voiceSettings": {
          "stability": 0.3,
          "similarityBoost": 0.85,
          "style": 0.45,
          "useSpeakerBoost": true
        }
      },
      "modelOverrides": { "enabled": true }
    }
  }
}

8. Build System (CBO Domain)

8.1 Build Methodology (Non-Negotiable Order)

1. Spec         → /executives/cbo/specs/{project}.md
2. User Stories → Acceptance criteria per story
3. TDD          → Failing tests first, then code to pass
4. Build        → Claude Code (ACP primary)
5. Security     → POPIA, secrets, auth, input validation
6. Deploy       → Ship + monitor
7. Report       → /executives/cbo/outputs/build-{project}-{date}.md
8. Event        → Fire build_completed event

8.2 ACP Execution Stack (Failover Order)

Priority	Runtime	Agent ID	When to Use
1	ACP	`claude`	Always try first
2	ACP	`codex`	If Claude Code unavailable
3	ACP	`gemini`	If Codex unavailable
4	Escalate	—	Flag to orchestrator if all unavailable

8.3 Security Policy

Three-tier package policy:

Tier 1 (Approved): Known, scanned, pre-approved packages
Tier 2 (Scan required): Unknown packages — CBO scans before install
Tier 3 (Prohibited): Packages with known risk or no legitimate use case

All builds: POPIA compliance check (data exposure, PII handling, storage policy).

9. Shared Governance Files

9.1 EXCO Brief

Daily auto-generated briefing injected into all agent sessions. Contains:

Business position (R2B counter, days to milestones)
Pipeline state
This week's priorities per exec
OKR status (RAG)
Latest executive outputs
Open action items

Generated by: Orchestrator at 07:00 daily Consumed by: All agents at session start (mandatory first read)

9.2 OKRs (Structured JSON)

/workspace/executives/shared/okrs/okrs.json — machine-readable OKRs with:

Quarterly objectives + key results
Owner per KR
Current vs target values
Status per KR (on-track / at-risk / behind)

All agents read this. The EXCO brief renders a human-readable summary from it.

9.3 Decisions Log

/workspace/executives/shared/decisions.md — locked decisions that agents must not re-open. Prevents circular debate. If a decision is in this log, it is final until explicitly revisited by the principal.

10. Workspace Filesystem Structure

~/.openclaw/
├── openclaw.json              ← Runtime config (agents, TTS, plugins, channels)
├── workspace/                 ← Orchestrator workspace
│   └── executives/
│       ├── shared/            ← Cross-agent shared state
│       │   ├── exco-brief.md
│       │   ├── business-state.md
│       │   ├── team-pulse.md
│       │   ├── principal-preferences.md
│       │   ├── decisions.md
│       │   ├── session-registry.json
│       │   ├── okrs/
│       │   ├── events/
│       │   │   ├── inbox/
│       │   │   ├── processed/
│       │   │   └── failed/
│       │   └── build-queue/
│       │       ├── pending/
│       │       ├── in-progress/
│       │       ├── review/
│       │       └── complete/
│       ├── orchestrator/      ← Orchestrator mandate
│       ├── cro/               ← Revenue exec outputs + specs + tasks
│       ├── cmo/
│       ├── cbo/
│       ├── cco/
│       └── cso/
├── workspace-cro/             ← CRO agent workspace (SOUL, IDENTITY, MEMORY, etc.)
├── workspace-cmo/
├── workspace-cbo/
├── workspace-cco/
├── workspace-cso/
├── agents/                    ← Agent session data
│   ├── main/agent/
│   ├── cro/agent/
│   ├── cmo/agent/
│   ├── cbo/agent/
│   ├── cco/agent/
│   └── cso/agent/
├── extensions/
│   └── voice-pipeline/        ← Voice pipeline plugin
└── tools/
    └── voice-pipeline/        ← Voice pipeline library

11. Replication Playbook

Step 1 — Define the Team

Identify the client's business functions. Map each to an agent role. Common patterns:

Client Type	Suggested Roles
SMB Founder	Ops, Sales, Marketing, Finance, Personal Admin
Agency	Account Management, Creative, Delivery, Finance
Startup	Product, GTM, Engineering, Fundraising
Professional Services	BD, Delivery, Knowledge, Admin
Franchise Group	Operations, Training, Marketing, Compliance

Each role becomes an agent. One role is always the Orchestrator (the principal's primary interface and team coordinator).

Step 2 — Configure the Runtime

Install OpenClaw on a server (VPS, Mac, Pi)
Create openclaw.json with agents.list[] entries for each agent
Set workspaces (workspace-{role}/), agent directories (agents/{role}/), heartbeat config, and tool restrictions
Configure the principal's channel (Telegram recommended)

Step 3 — Build Agent Identity Files

For each agent workspace, create:

workspace-{role}/
├── SOUL.md          ← Non-negotiable persona and values
├── IDENTITY.md      ← Name, role, reporting line, emoji
├── AGENTS.md        ← Startup instructions, tool protocols, comms rules
├── MEMORY.md        ← Empty to start — agent fills this over time
├── HEARTBEAT.md     ← Empty to start — fill with tasks as they arise
├── USER.md          ← Principal profile (copy and customise per client)
├── TOOLS.md         ← Environment notes (servers, accounts, preferences)
└── FAST_CONTEXT.md  ← Start minimal; agent updates as context builds

Step 4 — Build Shared Context

In /workspace/executives/shared/:

principal-preferences.md → rename to {client-name}-preferences.md — how the principal works
business-state.md → initial state of the business
decisions.md → empty to start
team-pulse.md → create sections per agent
session-registry.json → populate with agent session keys once running
exec-routing.md → define routing keywords per agent role
okrs/okrs.json → define client's quarterly OKRs in JSON format

Step 5 — Configure EXCO Brief Generator

Set up a cron (the Orchestrator's heartbeat or a dedicated hook) to regenerate exco-brief.md daily at a configured time. This brief should aggregate:

Current OKR status from okrs.json
Latest executive outputs (scan outputs/ dirs)
Open action items
Pipeline / client state

Step 6 — Deploy Voice Pipeline (Optional)

Copy /workspace/tools/voice-pipeline/ to client workspace
Copy ~/.openclaw/extensions/voice-pipeline/ to client OpenClaw install
Update EXEC_VOICES map in voices.ts and plugin index.ts with client agent voice IDs
Set TTS to tagged in openclaw.json
Add voice context block to each agent's SOUL.md

Step 7 — Tool Access Policy

Default recommended restrictions:

Agent Type	Allow	Deny
Orchestrator	All tools	—
Builder/Technical	All tools	—
Revenue/Sales	web_search, memory, message	exec, apply_patch
Marketing	web_search, browser, memory	exec, apply_patch
Ops/Admin	web_search, memory, message	exec, apply_patch

Adjust based on client trust level and compliance requirements.

Step 8 — Event Bus Setup

Create the events directory structure:

shared/events/inbox/
shared/events/processed/
shared/events/failed/

Define the event types relevant to the client's business (e.g., deal_closed, task_completed, escalation_raised) and wire the Orchestrator's router to dispatch them.

Step 9 — Build Queue (If Builder Role Exists)

Only needed if client has a technical/build function. If not, omit build-queue/ and remove CBO-style governance.

12. Key Design Decisions

Why file-based memory (not a database)?

Files are transparent, portable, git-trackable, and human-readable. Any agent can read any file. There is no schema migration problem. The principal can inspect or edit memory directly. Files survive process restarts without connection pools.

Trade-off: no query capability, linear scaling. Acceptable for the team sizes this architecture targets (1–10 agents, 1 principal).

Why one agent per channel bot (not one bot routing all)?

Agent identity is preserved per conversation. The Principal talking to their builder agent sees only that agent's responses — no context bleed from the Orchestrator layer. Each bot has its own voice, personality, and memory. Mixing them degrades the experience and introduces context pollution.

Why Telegram (not Slack, WhatsApp, etc.)?

Bot accounts are first-class, not bolted on
Voice notes supported natively (critical for TTS integration)
No rate limit issues at this scale
Mobile-first — works on the move
No monthly cost
SA market reality: Telegram penetration among founders and SMBs is high

Why tagged TTS (not always-on)?

Always-on TTS reads every response as audio — including specs, code, tables, and inter-agent protocol. This is worse than no voice at all. Tagged mode means the agent decides when audio adds value. Result: audio is rare, purposeful, and natural.

Why tool restrictions on non-builder agents?

Preventing exec and apply_patch on agents that have no need for them eliminates the risk of a marketing or sales agent accidentally running a shell command or patching a file due to a confused prompt or adversarial input. Principle of least privilege applied to AI agents.

13. What This Is Not

Not an n8n replacement. This architecture handles agent cognition, not workflow automation. If a client needs 50-step automation pipelines, wire n8n or another tool downstream.
Not a CRM. Pipeline data lives in files and GHL. This architecture integrates with CRMs — it is not one.
Not a code IDE. The CBO agent orchestrates builds via ACP (Claude Code, Codex). The actual code execution happens in those sub-processes, not inside OpenClaw directly.
Not multi-tenant out of the box. Each deployment is a single-principal system. Multi-tenancy requires isolating workspaces, channel bots, and OpenClaw instances per client.

14. Files to Customise Per Deployment

File	What to change
`openclaw.json` — `agents.list[]`	Agent IDs, names, workspaces, heartbeat targets
Each `SOUL.md`	Persona, domain, values specific to that role
Each `IDENTITY.md`	Name, role title, reporting structure
Each `AGENTS.md`	Startup files, comms protocols, tool usage rules
`USER.md`	Principal's name, timezone, communication style, goals
`principal-preferences.md`	Principal operating preferences
`business-state.md`	Initial business context
`okrs.json`	Client's actual OKRs
`exec-routing.md`	Keyword → agent routing table
`session-registry.json`	Live session keys per agent
`voices.ts` / plugin `index.ts`	ElevenLabs voice IDs per agent

15. Version History

Version	Date	Author	Notes
1.0	2026-03-15	Kai (CBO)	Initial reference architecture — Value10x AI deployment

This document is the reference for all future Value10x OS client deployments. Every architectural piece documented here has been battle-tested in the live Value10x AI production environment as of 2026-03-15.