CUO: CyberOS Workflow Orchestration and Persona Routing

CUO is the CyberOS workflow engine — the layer that transforms a task file into a shipped, audited change. It drives work through a single governed lifecycle, routing each task to the right C-suite persona, running agent steps between two mandatory human-acceptance gates, and recording every transition in an audit chain. Whether you are building a new feature or hardening an existing one, all work moves through the same machinery.

The single workflow: `ship-tasks`

The ship-tasks workflow (v2.3.x) picks the first eligible task from docs/tasks/BACKLOG.md and drives it end to end. There is exactly one workflow — improvement work and net-new product work both run the same chain, keeping your backlog and audit trail unified.

Task lifecycle

draft → ready_to_implement → implementing → ready_to_review
      → reviewing → ready_to_test → testing → done
                                                    ↕ on_hold  (paused by operator)
                                                    ↕ closed   (cancelled)

Off-ramps on_hold and closed are available at any phase. Together with the eight main progression states, that is ten states in total — defined in .cyberos/cuo/STATUS-REFERENCE.md. The task file’s status frontmatter field is the record of truth. BACKLOG.md is the index kept in lockstep — it never diverges from the individual task files.

Failures never result in a terminal state. A blocked or failed task routes back to ready_to_implement with routed_back_count incremented by one. The agent documents the reason and picks the next eligible task.

Task file anatomy

Every task is a markdown file with structured frontmatter. Create one in docs/tasks/<module>/task-<MODULE>-<NNN>-<slug>.md:

---
id: TASK-SHOP-001
title: Add a login rate limit
module: shop
class: product          # product = new capability; improvement = hardening/refactor/fix
status: ready_to_implement
priority: MUST
depends_on: []
routed_back_count: 0
---

Add a matching line to docs/tasks/BACKLOG.md. Improvement-class rows carry an (improvement) tag; product rows are untagged. There is never a second backlog file.

Human-acceptance gates

CUO requires two human verdicts per task. The agent runs continuously between them — it never stops to ask for confirmation on work it can verify itself.

Gate 1 — Review acceptance

The agent stops at the reviewing → ready_to_test transition and presents its code-review packet: the implementation diff, review findings, edge-case matrix, and any architecture decision records. Read the task’s normative clauses against the change, then say “approved” to advance or route it back with one sentence explaining what is wrong.

Gate 2 — Final acceptance

The agent stops at the testing → done transition and presents its test evidence: gate output (build, lint, coverage, CAF, AWH), and proof per acceptance criterion. Once every machine gate is green and you are satisfied, say “done” to close the task. Route back if anything is missing or incorrect.

An agent that marks its own work done — or transitions reviewing → ready_to_test without a human verdict — is exhibiting broken behavior. Refuse the action, route the task back, and report the incident. Only you can set ready_to_test (Gate 1) and done (Gate 2).

Persona routing

CUO is built on a catalog of C-suite personas. Each persona represents a named executive role with its own area of expertise, knowledge inputs, and set of workflows. When a task arrives, CUO identifies the best-fit persona by matching the task’s domain, module, and keywords against the persona catalog — then selects the most appropriate workflow within that persona’s folder and invokes the declared skill chain. Example personas in the CUO catalog:

Persona folder	Disambiguated title	Primary domain
`chief-technology-officer`	Chief Technology Officer	Engineering, architecture, security
`chief-revenue-officer`	Chief Revenue Officer	Sales, pipeline, go-to-market
`chief-financial-officer`	Chief Financial Officer	Budgeting, forecasting, reporting
`chief-product-officer`	Chief Product Officer	Roadmap, requirements, backlog
`chief-legal-officer`	Chief Legal Officer	Contracts, compliance, risk

When no persona scores above the confidence threshold, CUO escalates to you with the top-three candidates and their applicability rationales. When a workflow references a skill that has not yet shipped, CUO emits a MISSING_SKILL_REQUEST block and halts at that step.

CLI commands

The cyberos-cuo CLI exposes the following commands for inspecting and operating the workflow engine:

# List all personas in the CUO catalog — shows shipped, planned, and extinct entries
cyberos-cuo list-personas

# Include extinct and planned personas in the listing
cyberos-cuo list-personas --show-extinct --show-planned

# List available workflows for a specific persona
cyberos-cuo list-workflows chief-technology-officer

# Dry-run a skill chain for a persona/workflow without invoking skills
cyberos-cuo dry-run chief-technology-officer/ship-tasks

Triggering CUO

You can trigger the ship-tasks workflow from three entry points. All three execute the same workflow, the same gates, and the same required human verdicts.

/ship-tasks

Follow .cyberos/AGENT-ENTRY.md and drive the next eligible task in
docs/tasks/BACKLOG.md. HITL required. repo_root = this repo.

{
  "tool": "ship_task",
  "arguments": {
    "repo_root": "/path/to/your-repo"
  }
}

Install the Claude plugin once via Settings → Plugins → Add, pointing at dist/cyberos/cyberos.plugin. The /ship-tasks command becomes available in every session.

Machine gates

Between the two human gates, the agent runs your repo’s machine gates automatically via bash .cyberos/cuo/gates/run-gates.sh. Gates are derived from the touched module’s audit-profile.yaml and include:

Build and lint — the repo’s standard compile and style checks
Tests and coverage — 90% coverage floor on all files touched by the task
CAF gate — code-audit floor across the change
AWH gate — independent golden-set rerun against the sealed baseline in modules/<m>/.awh/

Green machine gates are necessary but never sufficient — you still decide at each human-acceptance gate.

Dream loop (propose mode)

CUO includes an optional self-improvement feature called the dream loop. When enabled, it evaluates candidate improvements to skill prompts, audit rubric wording, workflow step ordering, and golden-set thresholds — and records what it would do without applying anything. The shipped default is mode: propose. Moving to auto-apply requires four explicit locks to be satisfied simultaneously:

enabled: true in modules/cuo/config/dream.yaml with the kill switch unset
mode: auto set in the config
The explicit runtime flag --allow-auto-apply passed to the runner
You are on a dedicated dream branch whose name contains "dream"

Even in auto mode the loop never commits, pushes, or deploys. You review the applied diff and commit it yourself. Override everything at any time:

export CYBEROS_DREAM_KILL=1   # hard stop, regardless of config

Ship Tasks Workflow

Step-by-step walkthrough of the full ship-tasks lifecycle, from writing your first task file to landing the change.

Human-in-the-Loop

Deep dive into the two acceptance gates: what evidence the agent presents, how to route back, and what counts as a valid verdict.

Get Started

Core Modules

Productivity Modules

People & Finance

Platform

CUO: CyberOS Workflow Orchestration and Persona Routing

The single workflow: `ship-tasks`

Task lifecycle

Task file anatomy

Human-acceptance gates

Persona routing

CLI commands

Triggering CUO

Machine gates

Dream loop (propose mode)

Ship Tasks Workflow

Human-in-the-Loop

​The single workflow: ship-tasks

​Task lifecycle

​Task file anatomy

​Human-acceptance gates

​Persona routing

​CLI commands

​Triggering CUO

​Machine gates

​Dream loop (propose mode)

Ship Tasks Workflow

Human-in-the-Loop

The single workflow: `ship-tasks`

Task lifecycle

Task file anatomy

Human-acceptance gates

Persona routing

CLI commands

Triggering CUO

Machine gates

Dream loop (propose mode)