YAIBOS: The Sovereign AI Operating System Specification
An open architectural standard for an integrated, sovereign AI harness designed for small businesses, founders, and non-technical teams.
✓ SPEC.md copied to clipboard!
01. Executive Summary & Problem Statement
Current autonomous AI agent frameworks (such as CrewAI, AutoGPT, and raw CLI agents) are engineered exclusively for software developers. They demand terminal fluency, package managers, virtual environment maintenance, and unmetered API keys.
Conversely, consumer chat interfaces (ChatGPT, Claude, Gemini) isolate team members in conversational silos. They lack persistent company memory, cannot execute business procedures with verifiable status telemetry, and fail to prevent API token bill shock for the organization.
02. System Layer Architecture
Presentation Layer
- › 1-Click SOP Visual Cockpit with Area Filtering
- › Embedded Rich Markdown Editor and Knowledge Graph Viewer
- › Real-time Telemetry, Duration Counter & Run Audit Logs
Governance & Session Layer
- › Folder-level & File-level Role-Based Access Control (RBAC)
- › BYOS Auth Engine (ChatGPT, Claude, DeepSeek OAuth session bridge)
- › Lifespan Stage Gates: Assisted -> Supervised -> Fully Autonomous
Execution Engine Layer
- › Deterministic Agent Execution Loop & Context Window Assembler
- › Persistent Semantic Memory Provider (Local Hybrid Search)
- › Tool, Skill & MCP Dispatcher with Timeout Management
Storage & Protocol Layer
- › Plain-text Markdown Files on Local Filesystem or Git Repository
- › Model Context Protocol (MCP) Connectors & Local CLI Adapters
03. The Six Architectural Pillars
Detailed normative requirements and architectural specifications.
Zero-Install All-in-One UI
No terminal commands, no Git merge conflicts, no raw editor hurdles.
A unified desktop or sovereign local web cockpit. Non-technical staff click visual cards, view execution status, and inspect outputs without ever opening a terminal.
- ✓ Zero exposed developer terminals during standard business operations.
- ✓ Unified desktop runtime (Tauri / Electron) or local-network web app.
- ✓ Pure Markdown and open JSON data layer behind the visual UI.
- ✓ Data sovereignty guarantee: zero proprietary database lock-in.
1-Click SOP Execution (~ Skills for Business)
Turn company procedures into instant, autonomous action buttons (= skills for business).
Every business SOP (~ skill for business) is declared as a structured Markdown file with frontmatter parameters, rendered as a 1-click execution button with duration, telemetry, and output manifests.
- ✓ Structured SOP Markdown schema with frontmatter parameters and tool scopes.
- ✓ Visual catalog grouped by business area (Marketing, Sales, Accounting, Ops).
- ✓ Live execution telemetry: status, elapsed duration, human minutes saved.
- ✓ Lifespan progression: Assisted (step-by-step) -> Supervised -> Fully Autonomous.
- ✓ REST API endpoint (POST /api/v1/sop/run) and deep-link URL (yaibos://run?sop=...) for integration into Asana, Trello, and ERP workflows with hybrid human/AI tasks.
---
yaibos_version: "1.0"
id: "sop-invoices-audit"
title: "Monthly Invoices Audit & Statement Reconciliation"
area: "Finance"
maturity_stage: "supervised"
timeout_seconds: 300
permissions:
required_role: "finance_viewer"
fs_scope: ["read: Areas/Finance/Invoices/"]
mcp_tools: ["extract_pdf_tables", "reconcile_bank_csv"]
---
BYOS (Bring Your Own Subscription)
Zero token bill shock for the host. Team members use their own accounts.
Team members authenticate using their existing subscriptions (ChatGPT Plus/Team/Pro, Claude Pro, DeepSeek web auth). The harness consumes models directly with zero host token charges.
- ✓ Support consumer subscription OAuth and session bridging alongside metered API keys.
- ✓ Client-side encrypted credential storage with zero third-party broker exposure.
- ✓ Decoupled per-member usage quotas and execution auditing.
Integrated Team Second Brain
Human-legible company memory that autonomous agents can read and update.
Company memory lives in standard, open Markdown files. Staff can read and edit documentation in a built-in rich editor, while agents leverage local hybrid search.
- ✓ Standard open Markdown storage with bi-directional in-app editing.
- ✓ Local hybrid semantic search (lightweight vector embeddings + BM25 keyword matching).
- ✓ Background memory hygiene: stale note detection and duplicate resolution.
Granular Team Permissions (RBAC) & Ownership
Selective folder permissions with designated area responsibility.
Folder-level and file-level permissions (Read, Execute, Write/Propose, Admin) with designated human area owners who approve modifications.
- ✓ Strict folder-level and tool-level execution whitelists.
- ✓ Area ownership gates: agent writes to protected areas require human sign-off.
- ✓ Immutable local audit trail tracking all agent filesystem changes.
Modular Sovereign Engine Architecture
Everything is a plugin. Zero vendor lock-in, swappable models and tools.
A minimal, resilient pluggable engine where model connectors, MCP tool providers, storage layers, and UI themes are swappable, hot-reloadable plugins.
- ✓ Lightweight modular engine with swappable components.
- ✓ Open plugin manifest standard for tools, memory, and model providers.
- ✓ Model Context Protocol (MCP) native integration.
04. Data Formats & Manifest Schemas
4.1 SOP Manifest Frontmatter (YAML)
Stored at the top of any SOP Markdown note inside the workspace (for example in SOP/).
---
yaibos_version: "1.0"
id: "sop-inbound-lead-qualification"
title: "Inbound Lead Qualification & CRM Enrichment"
area: "Sales & Marketing"
owner: "Operations Lead"
maturity_stage: "supervised" # assisted | supervised | autonomous
timeout_seconds: 600
permissions:
required_role: "operations"
fs_scope:
- "read: Resources/Market Data/"
- "write: Projects/Active Leads/"
mcp_tools:
- "business_registry_lookup"
- "email_verification"
- "crm_update"
---
4.2 Execution Telemetry Schema (JSON)
Emitted upon completion of an SOP execution to generate the audit log and output manifest.
{
"execution_id": "exec-20260914-982341",
"sop_id": "sop-inbound-lead-qualification",
"trigger": "manual_1click",
"triggered_by": "[email protected]",
"auth_mode": "byos_session",
"started_at": "2026-09-14T13:42:10Z",
"completed_at": "2026-09-14T13:43:08Z",
"duration_seconds": 58,
"status": "success",
"steps_total": 4,
"steps_completed": 4,
"artifacts_produced": [
"Projects/Active Leads/2026-09-14-qualified-leads.csv"
],
"estimated_human_minutes_saved": 45
}