> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberskill.world/llms.txt
> Use this file to discover all available pages before exploring further.

# CUO: CyberOS Workflow Orchestration and Persona Routing

> CUO is the CyberOS workflow engine — it drives every task through a governed lifecycle with persona routing, human-in-the-loop gates, and audit evidence.

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.

<Note>
  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.
</Note>

### Task file anatomy

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

```yaml theme={null}
---
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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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).
</Warning>

## 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:

```bash theme={null}
# 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.

<CodeGroup>
  ```text Claude Plugin theme={null}
  /ship-tasks
  ```

  ```text Plain Text (any agent) theme={null}
  Follow .cyberos/AGENT-ENTRY.md and drive the next eligible task in
  docs/tasks/BACKLOG.md. HITL required. repo_root = this repo.
  ```

  ```json MCP Tool theme={null}
  {
    "tool": "ship_task",
    "arguments": {
      "repo_root": "/path/to/your-repo"
    }
  }
  ```
</CodeGroup>

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

## 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:

1. `enabled: true` in `modules/cuo/config/dream.yaml` with the kill switch unset
2. `mode: auto` set in the config
3. The explicit runtime flag `--allow-auto-apply` passed to the runner
4. 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:

```bash theme={null}
export CYBEROS_DREAM_KILL=1   # hard stop, regardless of config
```

<CardGroup cols={2}>
  <Card title="Ship Tasks Workflow" icon="rocket" href="/guides/ship-tasks-workflow">
    Step-by-step walkthrough of the full `ship-tasks` lifecycle, from writing your first task file to landing the change.
  </Card>

  <Card title="Human-in-the-Loop" icon="user-check" href="/guides/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.
  </Card>
</CardGroup>


## Related topics

- [CyberOS Glossary: Terms, Acronyms, and Concepts](/reference/glossary.md)
- [AI Gateway: Multi-Provider AI Routing with Cost Controls](/modules/ai-gateway.md)
- [CyberOS Skills: Verifiable Auditable Agent Capabilities](/modules/skill.md)
- [CyberOS Platform Changelog](/reference/changelog.md)
- [OBS: CyberOS Observability, Alerting, and Runbooks](/modules/obs.md)
- [Human-in-the-Loop: Your Two CyberOS Acceptance Gates](/guides/human-in-the-loop.md)
- [The ship-tasks Workflow: End-to-End Task Lifecycle](/guides/ship-tasks-workflow.md)
- [Build a Custom CyberOS Author and Audit Skill Pair](/guides/authoring-skills.md)
- [What Is CyberOS? The AI-Native Operations Platform](/introduction.md)
- [CyberOS Core Concepts: Memory, Skills, and Workflows](/concepts.md)