CUO

CUO is not "an AI chatbot in a corner." It is the orchestrator that decides what skill runs, who authorised it, and where the receipt is stored. Three roles converge in one Python package, and the design treats them as equal-weight requirements, not nice-to-have add-ons.

CUO's place in the runtime — every user-facing module touches CUO

Auto vs human-in-loop operations matrix

Internal operations is full of obvious requests that should resolve in one round trip: "validate this MST", "generate a VAT invoice for ACME", "draft a 1:1 prep doc for Thursday with Hanh". Without an orchestrator, every such request goes through a 200ms LLM call, every catalog lookup costs another 200ms, and every audit fact has to be re-implemented in the calling skill. CUO is the single layer that absorbs that pattern: rule-based fast path for unambiguous queries, LLM cascade for the ambiguous tail, BRAIN-anchored audit for every decision.

CUO is also the entry-point that lets the company hire one persona — Genie — and gradually grow the 47 C-suite specialist personas behind it without changing the user-facing interface. The same Slack thread / chat box that asked Genie to "validate MST 0123456789" yesterday can ask it to "draft the Q3 OKR cascade" tomorrow, and the right C-level persona workflow will load.

Six modules in cuo/cuo/core/ form the entire surface. Catalog discovers skills off disk. Router scores. Invoker delegates to the Skill module. Memory-bridge writes the decision. Trace renders the structured row.

Internal components

Phase roadmap

At P3+, every tenant's local CUO instance is the face of Lumi — the org-tenant persona whose JWT is verified by AUTH, whose audit rows feed Lumi's BRAIN, and whose cross-tenant synthesis is the long-game compounding moat. This section locks the contract between local CUO (a stateless Python orchestrator) and Lumi (the org-tenant identity it acts under).

Lumi vs Genie vs local CUO — the three names

AUTH JWT shape for Lumi (per AUTH §2.7)

{
  "iss": "https://auth.cyberos.io/<tenant>",
  "sub": "agent:cuo@cyberskill.world",
  "aud": "lumi-brain.cyberos.io",
  "iat": 1763112131,
  "exp": 1763115731,
  "tenant_id": "org:cyberskill",
  "tenant_residency": "sg-1",
  "agent_persona": "cuo-cpo@0.4.1",
  "scope_grants": [
    {"resource": "brain", "actions": ["read", "write"], "sync_class_max": "shareable"},
    {"resource": "skill",  "actions": ["invoke"], "skills": ["product-requirements-document-author@0.4.1", "vietnam-mst-validate@0.2.0"]},
    {"resource": "proj",   "actions": ["read", "write"], "engagements": ["acme-q3-platform-build"]}
  ],
  "jti": "01HZK…"
}

Cross-tenant synthesis — what Lumi actually does at P3+

Lumi runs on Lumi's BRAIN (the cloud-hosted org-tenant store). Per tenant, it ingests sync_class ∈ {shareable, team-public, org-only} memories from each Member's personal BRAIN and from CUO's decision rows. The compounding moat comes from one fact: the cross-team synthesis improves the personas everyone uses. When the CPO persona gets better at product-brief authoring because Lumi has seen 200 product briefs across 50 tenants, every tenant's CPO improves. The synthesis is bounded by sync_class — never private/personal — and by jurisdictional residency (Lumi's BRAIN shards by region).

CUO does not invoke skills directly. Every invocation passes through the Skill host's capability broker — the same mechanism the Skill module page §3.5 documents. The broker is the protocol-level guarantee that a skill never gets a tool it didn't request and a Member never invokes a skill outside their scope_grants. This section locks the contract from CUO's side.

The seven-step broker flow (per invocation)

CUO ↔ Skill broker contract (locked)

Defer-to-human matrix (per persona)

Each C-level persona declares a defer-to-human matrix. The matrix is normative; CUO refuses to auto-invoke any operation in the "defers" column regardless of confidence.

Genie is not a separate app. Every user-facing module exposes a CUO surface — chat box, command palette, inline action — that routes through the same orchestrator. The table below is the canonical list of surfaces; each surface declares how it parses NL, what context it ships to CUO, and what UI affordance it returns.

Per-surface latency budgets

CUO owns three entities. A SkillEntry is the projection of a Skill manifest into the router's catalog. A RoutingDecision is the result of scoring. An InvocationResult captures what the Skill host actually did.

GraphQL subgraph (planned · P0+)

extend schema
 @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key"])

type RoutingDecision @key(fields: "requestId") {
 requestId: ID!
 query: String!
 actor: String!
 skillName: String # null when routed=false
 arguments: JSON
 confidence: Float!
 rationale: String!
 alternatives: [Candidate!]!
 routed: Boolean!
 routerPhase: RouterPhase!
 invokedAt: DateTime
 result: InvocationResult # null if --invoke not requested
}

type Candidate {
 skillName: String!
 score: Float!
 rank: Int!
}

type InvocationResult {
 exitCode: Int!
 stdout: String!
 stderr: String!
 startedAt: DateTime!
 endedAt: DateTime!
}

enum RouterPhase { phase1_rule phase2_llm phase3_chain phase4_persona }

type Query {
 route(query: String!, persona: Persona): RoutingPreview!
 decision(requestId: ID!): RoutingDecision
 decisions(actor: String, since: DateTime, limit: Int = 50): [RoutingDecision!]!
}

type Mutation {
 routeAndInvoke(query: String!, record: Boolean = true): RoutingDecision!
 invokeSkill(skillName: String!, arguments: JSON!): InvocationResult!
}

type RoutingPreview {
 decision: RoutingDecision!
 catalogFingerprint: String! # for replay
}

MCP tool catalogue

CLI — cyberos-cuo (5 subcommands shipped)

Flow 1 — Single-skill route decision (Phase 1)

Flow 2 — Multi-step chain (Phase 3 preview)

Flow 3 — Confidence cascade (Phase 1 → Phase 2)

Flow 4 — Persona switch (Phase 4 preview)

Each persona is a curated subset of the Skill catalog. Today the catalog lives flat under modules/skill/<name> with full-format names; the supervisor routes via two stages (persona → workflow) then auto-dispatches one of 6 Handlers per workflow pattern: frontmatter. The Auto OK column lists actions that may complete without explicit operator approval; the Defers column lists actions that always escape to the human.

8.1 — All 47 active personas (per-row catalog)

Every persona folder lives at modules/cuo/<persona-slug>/ with a 9-block-schema README and its own workflows/ directory. 221 workflows live across 47 active personas. The supervisor routes a natural-language query → persona → workflow → skill chain, then auto-dispatches one of 6 Handlers per workflow pattern:. The Tier column reflects the staged-introduction wave that first shipped that persona's workflows (Now / Series-A / Scale-up / Enterprise / Niche); operators can ignore tier ordering at runtime — it only governs the authoring backlog. The Representative workflow column links to a concrete, file-verified workflow under that persona's workflows/ folder; some personas carry 5–8 workflows after Tier-C1 depth additions (chief-of-staff, chief-financial-officer, chief-information-security-officer, etc.).

Now-tier Founding rhythm of any startup (5 personas, ~28 workflows)

Series-A-tier Adds when scaling beyond the founders (4 personas, ~16 workflows)

Scale-up-tier Adds when the org passes ~100 people (2 personas, ~10 workflows)

Enterprise-tier Adds at Growth/Enterprise stage (5 personas, ~22 workflows)

Niche-tier Niche / specialty seats added through stable catalog (31 personas, ~124 workflows)

Authored across Sessions I–N as "no new skills needed" waves — every workflow chains through the already-shipped Tier-1/Tier-2 catalog. This validates the v3.0.0 supervisor hypothesis: a stable ~100-skill catalog can serve the long tail.

Total: 47 active personas (chief-metaverse-officer is EXTINCT — see §8.3) · 221 workflows live · all chain through the SKILL module's 104 author+audit pairs / 108 contracts. The C-Suite Reference §5 is the canonical role atlas; the staged-introduction order is documented in REPORTS.md §2.

8.2 — Worked examples · canonical 10 deep-dive

The 10 cards below illustrate the persona-card shape every README under modules/cuo/<persona-slug>/ renders — the routed scope, an Auto-OK action list (low-stakes, takes the auto-action), a Defers-to-human list (high-stakes, escapes to the operator). The full 47-row catalog is in §8.1 above; the patterns shown here generalise to every persona. Per modules/cuo/_template/persona/README.md the per-persona README always follows the 9-block schema from C-Suite Reference §4.

CUO is the most-connected module. It consumes BRAIN (records), Skill (invokes), AI Gateway (Phase 2), MCP Gateway (tool surface), AUTH (actor identity). It is consumed by every user-facing module.

1. List the skills CUO can route to

$ cyberos-cuo catalog --format json | head -30
{
 "fingerprint": "9c8e2a...4b7d",
 "scanned_at": "2026-05-14T07:30:11Z",
 "skill_count": 208,
 "skills": [
 {"name": "product-requirements-document-author", "version": "0.4.1", "region": null, "keywords": ["prd", "author", "draft prd", "product requirements"]},
 {"name": "vietnam-mst-validate", "version": "0.2.0", "region": "VN", "keywords": ["mst", "tax code", "ma so thue"]},
 {"name": "vietnam-vat-invoice", "version": "0.3.0", "region": "VN", "keywords": ["invoice", "hoa don", "vat", "gtgt"]},...
 ]
}

2. Route a query without invoking

$ cyberos-cuo route "kiểm tra MST 0123456789-001"

decision:
 skill_name: vietnam-mst-validate
 arguments: {mst: "0123456789-001"}
 confidence: 1.0
 rationale: "VN-diacritic query + region=VN bonus + 2 keyword hits + name-substring match"
 routed: true

alternatives:
 - vietnam-tax-filing score=0.3
 - vietnam-vat-invoice score=0.2

(not invoked — pass --invoke to dispatch through the Skill host)

3. Route, invoke, and record in BRAIN

$ cyberos-cuo route "validate MST 0123456789" --invoke --record

decision: vietnam-mst-validate (conf=0.7)
invocation: exit=0 elapsed_ms=24
stdout: {"ok": true, "format": "10-digit"}
recorded: brain:/meta/cuo-decisions/1747200611_8c4e.md
 seq=14941 chain=a3c7...2b9f

4. Inspect a past decision (audit replay)

$ cyberos view meta/cuo-decisions/1747200611_8c4e.md
---
kind: decisions
sync_class: private
classification: internal
schema: cuo-decision-v1
---
# CUO routing decision

**Query:** validate MST 0123456789
**Catalog fingerprint:** 9c8e2a4b7d...
**Decision:** vietnam-mst-validate
**Confidence:** 0.7
**Rationale:** 1 name-substring hit + 1 keyword + region tiebreaker
**Alternatives:** [...]
**Invoked at:** 2026-05-14T07:30:11Z
**Result:** exit=0, stdout={"ok": true}

5. Show keyword bank + extractors for a skill

$ cyberos-cuo skills vietnam-vat-invoice

skill: vietnam-vat-invoice
region: VN
keywords: [invoice, hoa don, vat, gtgt, e-invoice, xuat hoa don]
extractor: detect-amount
 pattern: r"(\d[\d.,]*)\s*(triệu|trieu|million|k|VND|đồng)"
 ※ structured extraction deferred to Phase 2
depends_on: [vietnam-mst-validate] ← Phase 3 will walk this
allowed_tools: [read_file, write_file]