flow

Syntax

flow "<name>":
  run "a.loop"
  then run "b.loop"

What it does

A pipeline lives in one file; a flow chains separate .loop files, run in order — so a big effort becomes many small, reusable files instead of one monolith. Each step runs the whole file (its full plan→act→observe cycle), and its short text summary carries forward as context for the next step. The chain is fail-fast: a step that ends unsatisfied halts the rest.

Reach for a flow when the stages are genuinely independent deliverables you'd want to run, resume, or reuse on their own — build.loop, test.loop, deploy.loop — rather than tightly-coupled stories that only make sense together (that's a pipeline). The unit of reuse is the file: the same test.loop can appear in several flows. Use then run for a step that should receive the previous step's summary automatically, or with the result of <name> to pull a specific named step's output instead of the auto-carried one. Attach a human approves first to any step that must not run unattended — a deploy, a migration — and the flow blocks there until approved. Because a flow is just an ordering of files, it stays flat and readable even as the overall effort grows.

Example

flow "ship":
  run "build.loop"
  then run "test.loop"
  then run "deploy.loop":
    a human approves first

How it runs

Common mistakes

• Using a flow where a pipeline belongs. If the steps are tightly-coupled stories in one epic, they belong in a single pipeline as stages. A flow is for separate, independently-runnable .loop files.
• Assuming files share state. Only a short text summary crosses between steps — not the full transcript, working memory, or variables. If a later step needs a specific earlier output, name that step and use with the result of <name> rather than hoping it survived the auto-carry.
• Forgetting fail-fast. A step that ends unsatisfied stops the whole chain; later steps never run. Put the cheap, likely-to-fail checks early so you don't pay for expensive steps before a gate that was going to block anyway.
• Wrong relative paths. Each run "<file>" path is resolved relative to the flow file. A path that's right from your shell but wrong from the flow file's directory makes the step unrunnable.

Related