Skip to main content
This tutorial uses a sub-workflow node to delegate part of a parent workflow to a separate, reusable child workflow. The parent plans a feature, hands off implementation to a child workflow that runs its own implement-test loop, then reviews the result.

​
Prerequisites

Complete the Branch & Loop tutorial — the child workflow in this tutorial reuses that pattern.

​
The child workflow

First, create a standalone implement-and-test workflow. This is a normal workflow that can run on its own or be invoked as a sub-workflow by a parent.
Child workflow: Start → Implement → Validate → Tests passing? → Pass to Exit or Fix back to Implement
implement-and-test.fabro
digraph ImplementAndTest {
    graph [goal="Implement the plan and make tests pass"]
    rankdir=LR

    start [shape=Mdiamond, label="Start"]
    exit  [shape=Msquare, label="Exit"]

    implement [label="Implement", prompt="Read plan.md and implement every step. Write the code and tests to disk."]
    validate  [label="Validate", shape=parallelogram, script="python3 -m pytest -v 2>&1 || true"]
    gate      [shape=diamond, label="Tests passing?"]

    start -> implement -> validate -> gate
    gate -> exit      [label="Pass", condition="outcome=success"]
    gate -> implement [label="Fix", max_visits=5]
}
This is the same implement-test-fix loop from the Branch & Loop tutorial, packaged as its own file.

​
The parent workflow

Now create a parent workflow that delegates to the child:
Sub-Workflow: Start → Plan (agent) → Implement & Test (house) → Review (agent) → Exit
sub-workflow.fabro
digraph SubWorkflow {
    graph [goal="Create a Python module (tempconv.py) that converts between Celsius, Fahrenheit, and Kelvin, with pytest tests"]
    rankdir=LR

    start [shape=Mdiamond, label="Start"]
    exit  [shape=Msquare, label="Exit"]

    plan   [label="Plan", prompt="Analyze the goal. List the functions needed, their signatures, and edge cases. Write the plan to plan.md."]
    impl   [label="Implement & Test", shape=house, stack.child_workflow="implement-and-test.fabro", manager.max_cycles=50]
    review [label="Review", prompt="Read every file the child workflow created. Run the tests yourself with 'python3 -m pytest -v'. Verify the implementation matches plan.md and all tests pass. Write a short verdict to review.md."]

    start -> plan -> impl -> review -> exit
}

fabro run files-internal/demo/12-sub-workflow.fabro

​
The house node

The impl node has shape=house, which makes it a sub-workflow node. Instead of running an LLM or a script, it launches an entirely separate workflow engine to execute the child workflow file: 
impl [label="Implement & Test", shape=house, stack.child_workflow="implement-and-test.fabro", manager.max_cycles=50]
The child workflow runs through its own start → implement → validate → gate → exit sequence. When it finishes, execution returns to the parent and continues to the review node.

​
Sub-workflow attributes

AttributeDescription
stack.child_workflowPath to the child workflow file (resolved relative to the parent). Preferred.
stack.child_dotfileBackward-compatible alias for stack.child_workflow.
stack.child_dot_sourceInline child DOT source (alternative to child_workflow)
manager.max_cyclesSafety limit on poll cycles before the child is cancelled (default: 1000)
manager.poll_intervalHow often to check for completion or stop conditions (default: 45s)
manager.stop_conditionCondition expression that, when true, cancels the child early
Use stack.child_workflow when you want to reuse the child workflow across multiple parents. Use stack.child_dot_source for one-off child workflows that are specific to the parent.

​
Context flow

Context flows bidirectionally between parent and child:
  1. Parent → child: The child receives a clone of the parent’s context. In this example, the plan node writes plan.md to disk and the child’s implement node reads it.
  2. Child → parent: When the child finishes, any context values it added or changed are merged back into the parent. The review node sees the results of the child’s work.
Only the diff is merged — values the child didn’t touch remain unchanged in the parent.

​
Stop conditions

For long-running child workflows, you can set a stop condition that cancels the child early based on the parent’s context: 
impl [shape=house,
      stack.child_workflow="implement-and-test.fabro",
      manager.stop_condition="context.deploy_ready=true",
      manager.max_cycles=100]
The parent polls at manager.poll_interval (default 45 seconds). On each poll, it evaluates the stop condition against the current context. If the condition is true, the child is cancelled and the parent continues. This is useful when an external process (another branch, a webhook, a human gate) signals that the child’s work is no longer needed.

​
When to use sub-workflows

Sub-workflows are most valuable when:
  • Reusability — the same child workflow is used by multiple parents (e.g., a standard test-and-fix loop, a deploy pipeline, a review checklist)
  • Encapsulation — the child runs its own engine with isolated logs and checkpoints, keeping the parent’s execution trace clean
  • Supervisor patterns — the parent needs to monitor or cancel a complex child process based on external conditions
For simpler cases, just add more nodes to a single workflow. Sub-workflows add a layer of indirection — use them when the benefits of reuse or encapsulation justify it.

​
What you’ve learned

  • Sub-workflow nodes (shape=house) run a child workflow inside a parent
  • stack.child_workflow references an external workflow file for reuse (stack.child_dotfile is also supported for backward compatibility)
  • Context flows from parent to child and back via diff merging
  • manager.max_cycles prevents runaway child workflows
  • manager.stop_condition cancels the child when an external signal arrives

​
Further reading

Nodes & Stages

Complete reference for all node types.

DOT Language

Full syntax reference including sub-workflow attributes.

Context

How context flows between nodes and across workflow boundaries.

Branch & Loop

The implement-test-fix pattern used in the child workflow.