Workflow state modeling

Separates workflow meaning, canvas layout and execution history into explicit versioned models and state transitions.

workflow-semantics-state-modeling

See how it helps

When is it useful?

Use when editing a diagram accidentally changes running workflow behavior.

What does it help you do?

Distinguishes definitions and versions from visual positioning.
Defines step inputs, outputs and registry compatibility contracts.
Models runs, attempts and allowed transitions independently.

Try asking this

Model a workflow whose canvas can be rearranged while an existing run continues on its original published version. Move nodes visually and publish a changed step while an older run waits. The waiting run must continue with its original contract and versioned inputs.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Workflow Semantics & State Modeling

Use this skill when designing or implementing workflow data models, step contracts, execution state machines, and the boundary between visual graph editors and execution engines.

The Three-Layer Separation Principle

Never conflate a workflow's executable logic, its visual diagram layout, and its live runs:

Workflow Definition (WorkflowDefinition & WorkflowVersion):
- The immutable, versioned directed graph of nodes (nodeId, stepType, typeVersion, config, credentialRefIds), typed ports, control-flow edges, and data-mapping expressions.
Visual Canvas Layout (WorkflowLayout / Viewport Metadata):
- Node coordinates (x, y), dimensions, collapsed groups, zoom/pan camera state, and visual annotations. Moving a node by 50 pixels on the canvas must never alter execution semantics or force a breaking runtime change.
Execution Instance (WorkflowRun, StepExecution, StepAttempt):
- A specific runtime invocation pinned to an immutable workflowVersionId with its own runId, tenant/actor context, input payload, current node token states, step outputs, wait timers, and attempt history.
- Editing or saving a draft on the canvas must never mutate the definition or behavior of an already started WorkflowRun.

Versioned Step Registry & Explicit Contracts

Maintain a versioned Step Type Catalog where every step type declares:
- Input Schema: Required/optional typed parameters and allowed upstream expression bindings.
- Config Schema: Static configuration fields and secret reference slots (never raw plaintext secrets in the definition JSON).
- Output Schema: Deterministic output structure per outcome port (success, branch_true, branch_false, timeout, error).
- Execution Semantics: Sync vs. async/waiting, idempotency behavior, timeout defaults, retry eligibility, and side-effect classification (pure transform vs. external mutation).
Separate Control-Flow Edges (determining when a downstream node is activated) from Data-Flow Bindings (determining where a step reads its inputs from upstream outputs or run context).

Explicit Run and Step State Machines (Lamport)

Model distinct lifecycle states for both runs and steps:

Run States: pending $\to$ running $\leftrightarrow$ waiting (timer / external event / human approval) $\to$ completed | failed | cancelling $\to$ cancelled.
Step Execution States: pending, ready, running, waiting, succeeded, failed, skipped (dead-path eliminated on unchosen branch), cancelled, compensated.

Checklist

Are the executable workflow definition, visual canvas coordinates, and runtime execution state stored as distinct structures?
Is every WorkflowRun pinned to an immutable workflowVersionId so live edits never corrupt in-flight runs?
Does every step type declare explicit input, configuration, and output schemas plus secret reference IDs?
Do step states clearly distinguish skipped (unchosen branch), waiting, running, succeeded, failed, and cancelled?

Included files 1

SKILL.md