Flow Spec v1

Blocchi Flow Spec v1 is the portable representation of a workflow.

{
  specVersion: "1";
  name: string;
  description?: string;
  executionMode?: "guided" | "agent-driven";
  nodes: WorkflowNode[];
  edges: WorkflowEdge[];
}

The contract intentionally excludes tenant ID, workflow revision and lifecycle state. Those are platform-owned fields.

executionMode is workflow-level interaction policy, not an Agent permission. agent-driven is the backward-compatible default. guided pauses after each Agent reasoning step for human continuation while preserving all independent Governed Action approval rules.

Generated Guided checkpoints are runtime implementation details. Visual authoring, Flow-as-code and MCP return the portable graph without those generated Approval nodes.

Limits in v1

• Name: 1–200 characters.
• Description: up to 2,000 characters.
• Execution mode: guided or agent-driven.
• Nodes: 1–200.
• Edges: up to 500.
• Unknown top-level fields are rejected.

One schema

Visual authoring, Flow-as-code and agent-created flows round-trip through this same contract. If a feature cannot be represented safely in Flow Spec, it should not create a second hidden workflow language.

Human-owned MCP clients can use blocchi.list_workflows, blocchi.get_workflow, blocchi.create_workflow and blocchi.save_workflow_revision. Create/save use the exact Flow Spec v1 contract, including executionMode, and create immutable draft revisions through the same workflow service as the product UI. Activation remains a separate human governance step.

Workflow persistence currently records authorship against a human user profile. For that reason, these authoring MCP tools are intentionally unavailable to service actors rather than impersonating a human author.