Understanding the flow runner's step cap and dependency order

The flow runner is designed to be powerful but bounded — it executes a flat DAG predictably, without runaway loops or unbounded growth. Understanding its limits helps you design flows that complete cleanly.

A flat DAG

A flow is a flat directed acyclic graph: steps depend on earlier steps, but no step spawns more steps at runtime. The graph you define is the graph that runs. (Sub-agents inside a flow do not recursively spawn further sub-agents.)

The step cap

The runner caps execution at a maximum of 16 steps. If a flow defines more than that, the extra steps are skipped. Designing within this ceiling keeps your flows reliable and ensures every intended step actually runs.

Dependency order

Steps execute in dependency order. Each step's dependencies are resolved first, and those dependencies' outputs are passed forward as context to the steps that need them — this is how research feeds analysis, analysis feeds design, and so on.

Stopping cleanly

The runner stops cleanly when it hits unmet dependencies or cycles. Rather than hanging or erroring unpredictably, it halts in an orderly way, so a malformed graph won't run forever.

What gets persisted

A flow produces exactly one run record, written into the project's Flows folder, capturing the run's per-step results. That single record is what powers the run-history view.

Designing within the bounds

Keep flows to 16 steps or fewer, make sure every step's dependencies actually exist earlier in the graph, and avoid cycles. Within those guardrails, you can chain a substantial amount of work — and you can always split a larger process into multiple flows.