Skip to content

Control Plane — Workflows (June 2026)

Archived 2026-10-09

This June-2026 narrative page was superseded by the rewritten page at planes/control/workflows.md (design plan P1). Its WorkflowInstance state machine, MassTransit sagas and replay service are not current direction: the run vocabulary is fixed by ADR-0014, workflow definitions and their engine belong to BC-38 in the Agent Mesh, and recovery replaces replay. It is kept for provenance.

Historical — archived

This page is kept for provenance. Its dates, targets and technology statements are not current direction. See the linked replacement page.

Workflow orchestration was described as the core domain of the Control Plane. A WorkflowInstance was a durable, event-sourced state machine that turns business intent into a governed, traceable sequence of agent tasks, validations, approvals, artifacts, and a release, driven by WorkflowOrchestrator (MassTransit sagas) from versioned WorkflowDefinition templates and grounded in the factory coordinators (Project Bootstrap, Sprint Execution, Milestone Lifecycle, Microservice Assembly, Release).

Main Lifecycle

flowchart LR
    Intent["Project intent<br/>(Factory Studio)"] --> Bootstrap["Project Bootstrap"]
    Bootstrap --> Blueprint["Blueprint design & validation"]
    Blueprint --> Workflow["Workflow instance per module"]
    Workflow --> Tasks["Agent tasks<br/>(Agent Mesh)"]
    Tasks --> Artifacts["Artifacts produced & registered"]
    Artifacts --> Assembly["Microservice assembly"]
    Assembly --> Gate["Release approval gate"]
    Gate --> Release["Release / promotion<br/>(DevOps & GitOps)"]
    Release --> Running["Running SaaS"]
    Running --> Feedback["Runtime feedback"]
    Feedback --> Intent
Hold "Alt" / "Option" to enable pan & zoom

WorkflowInstance State Machine

stateDiagram-v2
    [*] --> Created
    Created --> Running: WorkflowInstanceStarted
    Running --> AssigningTask: step ready
    AssigningTask --> AwaitingAgent: AgentTaskAssigned
    AwaitingAgent --> Running: AgentTaskCompleted
    AwaitingAgent --> Correcting: AgentTaskFailed (retryable)
    Correcting --> AwaitingAgent: reassigned (attempt <= max)
    Correcting --> Failed: max attempts exceeded
    Running --> AwaitingApproval: approval gate reached
    AwaitingApproval --> Running: ApprovalGranted
    AwaitingApproval --> Cancelled: ApprovalRejected
    AwaitingApproval --> Escalated: ApprovalExpired
    Running --> Compensating: step failed (compensation required)
    Compensating --> Failed: compensation complete
    Escalated --> Running: human resumes
    Escalated --> Cancelled: human cancels
    Running --> Completed: WorkflowInstanceCompleted
    Failed --> [*]
    Cancelled --> [*]
    Completed --> [*]
Hold "Alt" / "Option" to enable pan & zoom
State Meaning Emits
Created Instance materialized from a definition. WorkflowInstanceStarted (on start)
Running Advancing through steps. WorkflowStepCompleted
AssigningTask Translating a step into an agent task. —
AwaitingAgent Agent task placed; awaiting execution result. AgentTaskAssigned
Correcting Retryable failure; reassigning with feedback. AgentTaskReassigned
AwaitingApproval Paused at a human gate. ApprovalRequested
Compensating Running compensating actions for a failed step. CompensationStarted
Escalated Handed to a human (timeout/expiry). WorkflowEscalated
Completed All steps done, no open gates. WorkflowInstanceCompleted
Failed / Cancelled Terminal failure / human cancellation. WorkflowInstanceFailed / WorkflowInstanceCancelled

Task Assignment Sequence

sequenceDiagram
    participant Orchestrator as WorkflowOrchestrator
    participant TaskSvc as TaskAssignmentService
    participant Pool as AgentPoolManager
    participant Policy as ModelPolicyService
    participant Mesh as Agent Mesh
    participant Cost as CostUsageService

    Orchestrator->>TaskSvc: AssignAgentTask(step, role, skill)
    TaskSvc->>Policy: resolve model policy
    Policy-->>TaskSvc: modelPolicyId
    TaskSvc->>Pool: acquire lease(role, tenant)
    Pool-->>TaskSvc: lease granted
    TaskSvc-->>Orchestrator: AgentTaskAssigned
    TaskSvc->>Mesh: dispatch task (Agent Task Contract)
    Mesh->>Mesh: load context, execute skill, validate
    Mesh-->>TaskSvc: execution result (artifacts, tokens)
    TaskSvc->>Cost: RecordUsage(tokens, task)
    TaskSvc-->>Orchestrator: AgentTaskCompleted
    Orchestrator->>Pool: release lease
Hold "Alt" / "Option" to enable pan & zoom

Approval Gate Sequence

sequenceDiagram
    participant Orchestrator as WorkflowOrchestrator
    participant Policy as PolicyEngineService
    participant Approval as ApprovalService
    participant Studio as Factory Studio
    participant Reviewer as Human Reviewer
    participant Audit as AuditService

    Orchestrator->>Policy: EvaluatePolicy(action=release:promote, env=prod)
    Policy->>Audit: PolicyDecisionRecorded(effect=RequireApproval)
    Policy-->>Orchestrator: RequireApproval(role=ReleaseManager)
    Orchestrator->>Approval: RequestApproval(role=ReleaseManager)
    Approval-->>Studio: ApprovalRequested
    Studio->>Reviewer: surface gate in Human Review Center
    Reviewer->>Studio: Grant (comment)
    Studio->>Approval: GrantApproval(decidedBy)
    Approval->>Audit: AuditEntryRecorded(Granted)
    Approval-->>Orchestrator: ApprovalGranted
    Orchestrator->>Orchestrator: resume workflow (promote)
Hold "Alt" / "Option" to enable pan & zoom

Failure Handling

  • Classification: failures are transient (retryable), validation (correctable) or terminal (unrecoverable).
  • Transient failures used MassTransit exponential back-off at the message level.
  • Validation failures routed to Correcting: the task is reassigned with validator feedback, bounded by maxCorrectionAttempts.
  • Terminal failures triggered compensation and/or human escalation.

Retry & Compensation

flowchart TB
    StepFailed["Step failed"] --> Classify{Failure type}
    Classify -->|Transient| Retry["Retry with back-off"]
    Classify -->|Validation| Correct["Reassign with feedback<br/>(attempt <= max)"]
    Classify -->|Terminal| Compensate["Run compensating actions"]
    Retry --> Resume["Resume step"]
    Correct --> Resume
    Correct -->|max exceeded| Compensate
    Compensate --> Escalate["Escalate to human"]
    Escalate --> Decision{Human decision}
    Decision -->|Resume| Resume
    Decision -->|Cancel| Cancelled["WorkflowInstanceCancelled"]
Hold "Alt" / "Option" to enable pan & zoom

Compensation was forward-recovery via compensating actions, not distributed rollback. Each WorkflowStepDefinition could declare a CompensationDefinition.

Human Escalation

When a step exceeded its deadline (detected by WorkflowTimeoutWorker) or an approval expired, the instance entered Escalated and surfaced in the Studio's Human Review Center. A human could resume, reassign, or cancel; the decision was audited.

Replay

Because the WorkflowInstance event store was append-only, the WorkflowReplayService could deterministically reconstruct any instance into a shadow stream to debug a failure, re-derive an outcome under a newer definition, or rebuild the ProcessStateService projection. ADR-0014 does not promise replay; this capability is recorded as later in the registry.