mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-09-05 08:10:39 +00:00
21aff5431c
Update 47 MDX doc pages, OpenAPI spec, SVG diagram, language grammar, frontend demo data, marketing page, skills, and README to use .fabro extension. Add "fabro" to fileTypes in language grammars. Document stack.child_workflow alongside stack.child_dotfile. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
142 lines
5 KiB
Text
142 lines
5 KiB
Text
---
|
|
title: "Workflows"
|
|
description: "Core workflow concepts in Fabro"
|
|
---
|
|
|
|
A workflow is a directed graph that defines a repeatable process for AI agents, shell commands, and human decisions. Unlike a DAG (directed acyclic graph), an Fabro workflow can and often does include loops — for example, implement-test-fix cycles that repeat until tests pass. You write workflows in [Graphviz DOT](/reference/dot-language), check them into version control, and run them with `fabro run`.
|
|
|
|
## Anatomy of a workflow
|
|
|
|
Every workflow is a `digraph` with a `goal`, a `start` node, an `exit` node, and one or more processing nodes connected by edges:
|
|
|
|
<Frame>
|
|
<img src="/images/anatomy-workflow.svg" alt="Simple workflow: Start → Scan Files → Analyze → Exit" />
|
|
</Frame>
|
|
|
|
```dot title="my-workflow.fabro"
|
|
digraph MyWorkflow {
|
|
graph [goal="Describe the project"]
|
|
rankdir=LR
|
|
|
|
start [shape=Mdiamond, label="Start"]
|
|
exit [shape=Msquare, label="Exit"]
|
|
|
|
scan [label="Scan Files", shape=parallelogram, script="find . -maxdepth 2 -type f | head -30"]
|
|
analyze [label="Analyze", prompt="Review the file listing. Summarize the project structure.", shape=tab]
|
|
|
|
start -> scan -> analyze -> exit
|
|
}
|
|
```
|
|
|
|
The `goal` attribute describes what the workflow accomplishes. Fabro uses it to guide agent behavior and generate retrospectives.
|
|
|
|
## Key node types
|
|
|
|
Each node's Graphviz **shape** determines how it executes. The three most important types are:
|
|
|
|
**Agents** (default `box` shape) run an LLM with access to tools — bash, file editing, sub-agents — looping autonomously until the task is complete:
|
|
|
|
```dot
|
|
implement [label="Implement", prompt="Read plan.md and implement every step."]
|
|
```
|
|
|
|
**Commands** (`parallelogram`) run shell scripts and capture output for downstream nodes:
|
|
|
|
```dot
|
|
validate [label="Run Tests", shape=parallelogram, script="cargo test 2>&1 || true"]
|
|
```
|
|
|
|
**Human gates** (`hexagon`) pause the workflow and wait for a person to choose a path. Edge labels define the options:
|
|
|
|
```dot
|
|
approve [shape=hexagon, label="Approve Plan"]
|
|
|
|
approve -> implement [label="[A] Approve"]
|
|
approve -> plan [label="[R] Revise"]
|
|
```
|
|
|
|
Fabro supports additional node types for one-shot prompts, conditional branching, parallel fan-out/fan-in, and more. See [Stages and Nodes](/workflows/stages-and-nodes) for the full reference.
|
|
|
|
## Branching and loops
|
|
|
|
<Frame>
|
|
<img src="/images/branch-loop-workflow.svg" alt="Branching and loop workflow" />
|
|
</Frame>
|
|
|
|
Edges can have **conditions** that route execution based on outcomes:
|
|
|
|
```dot
|
|
gate [shape=diamond, label="Tests passing?"]
|
|
|
|
gate -> exit [label="Pass", condition="outcome=success"]
|
|
gate -> implement [label="Fix"]
|
|
```
|
|
|
|
Loops are natural — just point an edge back to an earlier node. Use `max_visits` on a node to prevent infinite loops:
|
|
|
|
```dot
|
|
fix [label="Fix Failures", prompt="Fix the failing tests.", max_visits=3]
|
|
```
|
|
|
|
## Parallel execution
|
|
|
|
<Frame>
|
|
<img src="/images/parallel-workflow.svg" alt="Parallel fan-out and merge workflow" />
|
|
</Frame>
|
|
|
|
Fan out to run branches concurrently, then merge the results:
|
|
|
|
```dot
|
|
fork [label="Fan Out", shape=component]
|
|
merge [label="Merge", shape=tripleoctagon]
|
|
|
|
fork -> security
|
|
fork -> architecture
|
|
fork -> quality
|
|
security -> merge
|
|
architecture -> merge
|
|
quality -> merge
|
|
merge -> report -> exit
|
|
```
|
|
|
|
## Goal gates
|
|
|
|
Mark critical nodes with `goal_gate=true`. The workflow fails if any goal gate doesn't succeed — even if execution reaches the exit node:
|
|
|
|
```dot
|
|
validate [label="Validate", prompt="Run the test suite and verify all tests pass.", goal_gate=true]
|
|
```
|
|
|
|
## Running a workflow
|
|
|
|
From the CLI:
|
|
|
|
```bash
|
|
fabro run workflow.fabro
|
|
```
|
|
|
|
Or from a [run config TOML](/execution/run-configuration) for repeatable, parameterized runs:
|
|
|
|
```bash
|
|
fabro run run.toml
|
|
```
|
|
|
|
In the web UI, the Workflows page lists all available workflows. Click into a workflow to view its DOT definition, rendered graph diagram, and run history.
|
|
|
|
<Frame caption="The Workflows page lists all available workflows with their trigger type and last run time.">
|
|
<img src="/images/web/workflows-list.png" alt="Fabro web UI Workflows list showing Fix Build, Implement Feature, Sync Drift, and Expand Product workflows" />
|
|
</Frame>
|
|
|
|
<Frame caption="The workflow detail view shows the DOT definition with syntax highlighting.">
|
|
<img src="/images/web/workflow-detail.png" alt="Fabro web UI workflow detail showing the DOT source for Fix Build" />
|
|
</Frame>
|
|
|
|
<Frame caption="The Diagram tab renders the workflow graph visually, showing nodes, edges, and conditions.">
|
|
<img src="/images/web/workflow-diagram.png" alt="Fabro web UI workflow diagram showing the Fix Build workflow graph" />
|
|
</Frame>
|
|
|
|
<Frame caption="The Runs tab shows all runs for this workflow, filterable by status.">
|
|
<img src="/images/web/workflow-runs.png" alt="Fabro web UI workflow runs tab showing run history for Fix Build" />
|
|
</Frame>
|
|
|
|
See the [Quick Start](/getting-started/quick-start) to try it out, or browse the [example workflows](/examples/implement-feature) for real-world patterns.
|