Skip to content

Sub-workflows

A sub-workflow is a workflow that another workflow references via a single sub_workflow ref node. Sub-workflows are the same artifact as top-level workflows — same schema, same storage, same run lifecycle — they just happen to be invoked from a parent’s graph rather than from a trigger.

The canvas surfaces a 150-node nudge banner and a 200-node hard cap. Before either fires, extract repeating sub-graphs (login, cart, checkout) into named sub-workflows so the parent stays focused on its business intent.

Select 2+ connected nodes, then either:

  • Press ⌘G (macOS) or Ctrl-G (Linux/Windows), or
  • Right-click → Group into sub-workflow, or
  • Click the toolbar’s Extract sub-workflow button.

The extraction modal lets you pick:

  • Name (validates ^[a-zA-Z][a-zA-Z0-9_-]{0,79}$)
  • Description (1 line, optional)
  • Scope — Project library (current project only) or Org library (any project in the same organisation)
  • Inputs / outputs — auto-detected from {{ ... }} references that cross the selection boundary. You can rename each binding before confirming.
  • Trigger — every sub-workflow has an auto-injected “When invoked by parent” entry node. Tick the checkbox to additionally add a Manual trigger for standalone debugging.

On confirm, the parent’s graph replaces the N selected nodes with a single sub_workflow ref node pinned at the new sub-workflow’s v0.1.0.

A purple-accent node with a version chip in the footer:

  • Double-click → opens the referenced sub-workflow in a new tab.
  • Right-click → Open, Inline (un-group), Upgrade to v….
  • Inspector shows the pinned version, the editable input/output bindings, and surfaces an “⏫ vX.Y.Z available” badge when a newer version exists.

Every sub-workflow follows the same semver rules as a top-level workflow. The parent pins to a specific version (v0.1.0, v0.2.0, etc.) and stays on that version until you explicitly call Upgrade. The upgrade modal surfaces a breaking-changes summary; you can opt in to the upgrade even when the diff is breaking.

The right-click menu’s Inline (un-group) action pulls the sub-workflow’s nodes back into the parent. If no other workflow references the sub-workflow, its row is deleted (with confirmation if other refs exist).

Tool Scope Description
kifas.workflow.extract_to_subworkflow workflow:write Group N nodes into a new sub-workflow
kifas.workflow.upgrade_subworkflow_ref workflow:write Repin a parent’s ref node to a different version
kifas.workflow.unfold_subworkflow_ref workflow:write Inline a ref node back into the parent

Every tool honors the workflow’s optimistic-lock If-Match token and the lock-to-code 423 guard.