Workflows

Spawning agents one at a time is right for ad-hoc work. But some processes repeat: plan, implement in parallel, review in a loop, ship. For those, Fletch has workflows — a definition you build once and launch on any task. A workflow runs a chain of agents on a single git branch, each step forking from the last, with the engine — not an LLM — owning the control flow.

This page is the mental model. For clicking through the builder and monitor, see Building and Running Workflows.

A workflow is a tree of blocks

Four block types compose into a tree:

Step — one sandboxed agent with a goal (its prompt) and a gate (the condition that means it’s done).
Parallel — fan several steps out from the same commit at once, with a join policy (all must finish, or the first any wins), an optional merge of their results back into one commit, and a concurrency cap.
Loop — repeat a body (say, review → fix) until a designated step’s verdict says done, or a maximum iteration count is hit.
Orchestrate — a lead agent supervises child agents: it spawns them from a template, answers their questions, and can compose bounded sub-workflows on the fly (nesting is capped at depth 2, so an orchestrator can’t recurse forever).

Gates: deterministic “done”

Agents are unreliable narrators about their own completion, so a step never ends because the agent says it’s finished. The engine checks a deterministic predicate you choose:

Gate	The step is done when…
Verdict (default)	the agent wrote a structured `verdict.json` marked done
Commit	the checkout’s `HEAD` moved past the fork point
Artifact	a file you name exists
Tests	the project’s test command passes
Approval	you approved it in the run monitor

A blocked gate isn’t a silent failure: the engine re-prompts the agent once with the reason the gate didn’t pass, and if it’s still blocked, pauses the run for you.

Budgets: bounded spend

Every run gets caps, frozen at launch: total agent turns (default 100), wall-clock time (default 480 minutes of active driving, not calendar time), per-attempt turns (default 10), retry attempts per step (default 2), and — if you set one — a token budget, enforced where the provider reports usage. Exceeding any cap pauses the run; it never silently overspends and never dies. From the monitor you raise the exhausted budget in place and continue.

How steps hand work to each other

Two channels, both observable:

The branch. Every step works on the same run branch (namespaced wf/…); each step’s checkout forks from the previous step’s boundary commit, so code flows forward through git, and parallel steps’ results can be merged or picked.

The blackboard. Each run gets a scratch directory mounted read-write into every step’s sandbox. The engine writes task.md (the run’s task and plan); each step leaves a free-form handoff.md and a structured verdict.json for whatever runs next; a shared/ directory is open cross-agent scratch space. Handoffs are files you can read, not hidden prompt-stuffing.

Beyond the filesystem, steps can message along edges you declare: report progress, ask a question, or (for orchestrators) notify children. A question with no orchestrator above it pauses the run for you to answer.

No silent hangs, fully resumable

Every wait in the engine has a deadline, and every pause names its cause — approval needed, question pending, blocked gate, budget exhausted, merge conflict, stalled step — with its resolution action right in the monitor. There is no state where the run is stuck and the UI shrugs.

Every engine decision is an append-only journal event, so a run survives anything: quit the app mid-run and it resumes where it left off, and each step attempt’s chat is preserved and replayable forever, exactly like any other agent session.

Finishing

A workflow’s finalize policy says what happens when the tree completes: push the wf/… run branch, and optionally open a pull request against a base branch you chose. From there it’s the same review-and-merge flow as any agent’s work.