Workflows

YAML workflow definitions for development, marketing, and incident response. How work flows through the company.

YAML files that define how work moves through the company. Not hardcoded. Not sacred. Living documents owned by the CEO agent.

What Are Workflows?

Workflows are state machines stored as YAML files in /company/team/workflows/. They define the sequence of steps a task goes through -- from initial intent to completion. Each step specifies which agent role handles it, what outputs are expected, timeout behavior, and transitions to the next step.

Workflows are not code. They are data. Agents read them, the orchestrator's workflow engine interprets them, and the CEO agent is the only one who can modify them.

Key Principles

Workflows are files -- YAML in the filesystem, versioned with git, diffable, editable
CEO agent owns them -- only the CEO agent can modify workflow files
Any agent can propose changes -- if a developer notices a bottleneck, they send a proposal to the CEO with evidence
Human approves structural changes -- adding or removing approval gates, changing permissions
Agents don't need to understand the engine -- they do their step and call task({ action: "update", ... }). The orchestrator handles routing

Workflow YAML Format

workflow-schema.yaml

id: string                          # Unique identifier
name: string                        # Human-readable name
version: number                     # Incremented on every change
description: string                 # What this workflow does

change_policy:
  propose: [any_agent]
  evaluate: [ceo]
  apply: [ceo]
  human_approval_required_for:
    - adding_approval_gate
    - removing_approval_gate
    - changing_agent_permissions

steps:
  - id: string
    name: string
    assigned_role: string
    type: string                    # Optional: human_gate, terminal, sub_workflow
    description: string
    inputs:
      - from_step: string
        type: string
    outputs:
      - type: file | git_branch | git_pr | deployment | report
        path_template: string
    expected_duration: string
    timeout: string
    timeout_action: string          # alert_human, reassign, auto_approve
    review:
      reviewers_roles: [string]
      min_approvals: number
      on_reject: string
      on_reject_max_rounds: number
    transitions:
      done: string
      approved: string
      rejected: string
      escalated: string

Development Workflow (12 Steps)

The standard development lifecycle workflow covers the full path from intent to production.

development-workflow-flow

Intent
  │
  ▼
┌─────────┐     ┌──────────┐     ┌─────────────┐     ┌─────────────┐
│  Scope  │────▶│   Plan   │────▶│  Implement  │────▶│ Code Review │
│ (strat) │     │ (planner)│     │ (developer) │     │ (reviewer)  │
└─────────┘     └──────────┘     └─────────────┘     └──────┬──────┘
                                                            │
                                                       approved
                                                            │
                                                     ┌──────▼──────┐
                                                     │ Human Merge │
                                                     └──────┬──────┘
                                                            │
                                                     ┌──────▼──────┐
                                                     │   Deploy    │
                                                     │   Staging   │
                                                     └──────┬──────┘
                                                            │
                                                     ┌──────▼──────┐
                                                     │   Verify    │
                                                     └──────┬──────┘
                                                            │
                                                     ┌──────▼──────┐
                                                     │   Deploy    │
                                                     │    Prod     │
                                                     └──────┬──────┘
                                                            │
                                                     ┌──────▼──────┐
                                                     │    Done     │
                                                     └─────────────┘

Marketing Workflow

The marketing campaign workflow handles the path from feature or product to public announcement: briefing, content creation, design assets, human approval, publishing, and engagement monitoring.

Incident Response Workflow

The incident response workflow prioritizes speed over process. Fewer gates, shorter timeouts, and direct-to-production deploys for hotfixes.

Workflow Engine

The orchestrator runs a simple state machine (~300 LOC) that reads workflow YAML, matches task states, and routes accordingly. Each task has a workflow and workflow_step field. The engine watches for task status changes, looks up the current step, checks transition conditions, and moves to the next step.

workflow-engine.ts

async function onTaskChanged(task: Task): Promise<void> {
  if (!task.workflow || !task.workflow_step) return

  const workflow = await loadWorkflow(task.workflow)
  const currentStep = workflow.steps.find(s => s.id === task.workflow_step)
  if (!currentStep) return

  // Terminal step — task is done
  if (currentStep.type === "terminal") {
    await executeTerminalActions(task, currentStep)
    return
  }

  // Human gate — waiting for human action
  if (currentStep.type === "human_gate") {
    if (task.status === "review") return
    await routeToHuman(task, currentStep)
    return
  }

  // Normal step — route based on status
  if (task.status === "done" || task.status === "review") {
    const nextStepId = currentStep.transitions.done ||
                       currentStep.transitions.success
    if (nextStepId) {
      await transition(task, workflow, nextStepId)
    }
  }
}

Conditional Transitions

Transitions can be conditional based on task priority or flags:

conditional-transitions.yaml

transitions:
  done:
    if_priority_critical: quick_review    # Skip full review for hotfixes
    if_priority_high: code_review
    default: code_review

Human Gates & Approval Flow

Human gates are workflow steps where execution pauses until a human takes action. Three types of actions require human gates:

Merge -- merging code to the main branch after agent review
Deploy -- promoting from staging to production
Publish -- releasing marketing content publicly

Human gates include a surface field that tells the dashboard what to show the human -- the PR, review comments, deploy report, or content preview.

Workflow Composition

Workflows can reference other workflows for sub-tasks using the sub_workflow step type:

workflow-composition.yaml

steps:
  - id: build_feature
    name: "Build the Feature"
    type: sub_workflow
    workflow: development
    transitions:
      completed: create_campaign

  - id: create_campaign
    name: "Create Launch Campaign"
    type: sub_workflow
    workflow: marketing
    transitions:
      completed: complete

Standard Workflow Summary

workflows-overview

STORAGE     /company/team/workflows/*.yaml
OWNER       CEO agent (exclusive write access)
PROPOSERS   Any agent can propose changes
APPROVAL    CEO for optimizations, human for structural changes

STANDARD WORKFLOWS
──────────────────
development.yaml    Intent → Scope → Plan → Implement → Review → Merge → Deploy
marketing.yaml      Brief → Content → Design → Human Review → Publish → Monitor
incident.yaml       Triage → Fix/Hotfix → Quick Review → Deploy → Verify

Workflows

On this page