Flows

Orchestrate sequences of capabilities with explicit failure modes for each step

What are Flows?

Flows are multi-step workflows that orchestrate sequences of capabilities. When a single capability is not enough — when creating a workspace also requires provisioning a subscription and sending a welcome email — you declare a flow. Each step in a flow references a capability or side effect, and each step declares what should happen if it fails.

Flows make complex operations visible and predictable. An AI agent reading a flow spec knows exactly which capabilities run in sequence, what triggers the flow, and how failures are handled at each step.

FlowSpec Structure

interface FlowSpec {
  name: string;        // unique flow name, e.g. "workspace_onboarding"
  description: string; // what this flow accomplishes
  trigger: string;     // capability name that triggers the flow
  steps: FlowStep[];   // ordered list of steps
  module: string;      // owning module
}

FlowStep Structure

interface FlowStep {
  name: string;           // step name, e.g. "create_default_subscription"
  action: string;         // capability or side-effect name to execute
  onFailure: 'abort' | 'skip' | 'retry' | 'compensate';
  compensation?: string;  // action to run if compensating (required when onFailure is "compensate")
  condition?: string;     // optional condition that must be true for the step to execute
}

Failure Modes

Each step declares how the flow should respond if the step fails:

Mode	Behavior	Use Case
`abort`	Stop the entire flow immediately. No subsequent steps execute.	Critical steps where continuing would leave the system in an inconsistent state. Example: payment processing fails during billing.
`skip`	Log the failure and continue to the next step.	Non-critical steps like sending notifications. The flow can succeed even if the notification fails.
`retry`	Retry the step (with framework-defined retry policy).	Transient failures like network timeouts when calling external services.
`compensate`	Run the compensation action to undo the effects of previous steps, then abort.	Steps where a failure means earlier steps must be rolled back. Example: subscription creation fails after workspace was created, so the workspace must be deleted.

How Flows Connect to Capabilities

Flows connect to the capability system in two ways:

Trigger: The trigger field names the capability whose execution starts the flow. This creates a triggers edge in the AI System Graph from the trigger capability to the flow.
Steps: Each step's action field references a capability (or side effect). This creates step_of edges from the action capability to the flow.

This means the graph can answer questions like "what happens after create_workspace runs?" (follow the triggers edge to find the flow) and "which flows involve generate_invoice?" (find all step_of edges targeting the capability).

YAML Example: Billing Cycle Flow

flows:
  - name: billing_cycle
    description: >
      Recurring billing flow that generates an invoice for a subscription,
      sends the invoice to the workspace owner, and initiates payment processing.
    trigger: generate_invoice
    module: billing
    steps:
      - name: generate_invoice
        action: generate_invoice
        onFailure: retry

      - name: send_invoice_email
        action: notify_invoice_issued
        onFailure: skip

      - name: process_payment
        action: process_payment
        onFailure: abort

This flow is triggered when generate_invoice is called. It generates the invoice (retrying on transient failures), sends an email notification (skipping if it fails), and then processes payment (aborting the entire flow if payment fails).

YAML Example: Workspace Onboarding with Compensation

flows:
  - name: workspace_onboarding
    description: >
      End-to-end onboarding flow when a new workspace is created.
      Creates the workspace, provisions a default free subscription,
      and sends a welcome notification to the owner.
    trigger: create_workspace
    module: workspaces
    steps:
      - name: create_workspace
        action: create_workspace
        onFailure: abort

      - name: create_default_subscription
        action: create_subscription
        onFailure: compensate
        compensation: delete_workspace

      - name: send_welcome_notification
        action: notify_workspace_welcome
        onFailure: skip

Notice the compensation pattern in the second step. If creating the default subscription fails after the workspace has already been created, the flow runs delete_workspace as a compensation action to undo the first step, then aborts. This prevents orphaned workspaces without subscriptions.

YAML Example: Ownership Transfer

flows:
  - name: ownership_transfer
    description: >
      Transfer workspace ownership from one user to another.
      Validates the new owner exists and is a workspace member,
      performs the transfer, and notifies both parties.
    trigger: transfer_workspace_owner
    module: workspaces
    steps:
      - name: validate_new_owner
        action: validate_new_owner
        onFailure: abort

      - name: transfer_ownership
        action: transfer_workspace_owner
        onFailure: abort

      - name: notify_previous_owner
        action: notify_ownership_transferred_from
        onFailure: skip

      - name: notify_new_owner
        action: notify_ownership_transferred_to
        onFailure: skip

Graph Relationships

Each flow creates multiple edges in the AI System Graph:

capability:generate_invoice --triggers--> flow:billing_cycle
capability:generate_invoice --step_of--> flow:billing_cycle
capability:notify_invoice_issued --step_of--> flow:billing_cycle
capability:process_payment --step_of--> flow:billing_cycle

AI-Safe Change Workflows

Flows are surfaced in the Change Protocol's impact analysis. When a capability is modified or removed, the impact analyzer traces all step_of and triggers edges to identify affected flows. The change plan lists these flows as affected items, and the plan generator can flag flows with compensate failure modes for extra review, since compensation logic is particularly sensitive to changes in step ordering or capability behavior.