CUO

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 ten specialist skills 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 skill 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

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

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 under skill/skills/cuo/<persona>/ and is loaded uniformly; Phase 4 splits the keyword bank per-persona so the router classifies intent first, then routes intra-persona. The Auto OK column lists actions that may complete without explicit operator approval; the Defers column lists actions that always escape to the human.

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": 20,
  "skills": [
    {"name": "cpo/prd-author", "version": "0.4.1", "region": null, "keywords": ["prd", "author", "draft prd", "product requirements"]},
    {"name": "cyberskill-vn/vn-mst-validate", "version": "0.2.0", "region": "VN", "keywords": ["mst", "tax code", "ma so thue"]},
    {"name": "cyberskill-vn/vn-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: cyberskill-vn/vn-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:
  - cyberskill-vn/vn-tax-filing  score=0.3
  - cyberskill-vn/vn-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:    cyberskill-vn/vn-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:** cyberskill-vn/vn-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 vn-vat-invoice

skill:        cyberskill-vn/vn-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:   [vn-mst-validate]  ← Phase 3 will walk this
allowed_tools: [read_file, write_file]