After each node finishes, Fabro must decide which edge to follow to the next node. This decision is deterministic by default — given the same outcome and context, Fabro always picks the same edge. Nodes can opt into random selection for weighted-random tiebreaking instead. Understanding the transition logic helps you design workflows that route reliably.
How transitions work
When a node completes, it produces an outcome with a status (success, fail, partial_success, or skipped) and optional signals like a preferred label or suggested next node. Fabro evaluates the outgoing edges in a fixed priority order:
- Condition match — Edges with a
condition attribute are evaluated first. If one or more conditions match, the edge with the highest weight wins (lexical tiebreak on target node ID).
- Preferred label — If the node’s outcome includes a preferred label (e.g. from a human gate selection), the edge whose
label matches is chosen.
- Suggested next — If the node suggests a specific next node ID, the edge pointing to that node is chosen.
- Unconditional fallback — Edges without conditions are considered last, again using
weight then lexical tiebreak.
If no edge matches at all, the workflow halts with an error.
Edge attributes
| Attribute | Description |
|---|
label | Display text on the edge; also used for human gate option matching |
condition | Boolean expression that must evaluate to true for this edge (see below) |
weight | Numeric priority for tiebreaking (higher wins, default: 0) |
Conditions
Edge conditions are boolean expressions evaluated against the stage outcome and run context. Conditions go in the condition attribute on an edge:
gate -> exit [label="Pass", condition="outcome=success"]
gate -> implement [label="Fix", condition="outcome=fail"]
Available keys
| Key | Resolves to |
|---|
outcome | The stage status: success, fail, partial_success, or skipped. See Node Outcomes. |
preferred_label | The label selected by a human gate |
context.KEY | A value from the run context (e.g. context.tests_passed) |
KEY | Shorthand for context lookup (without the context. prefix) |
Operators
| Operator | Example | Description |
|---|
= | outcome=success | Equality |
!= | outcome!=fail | Inequality |
> | context.score > 80 | Greater than (numeric) |
< | context.count < 5 | Less than (numeric) |
>= | context.score >= 80 | Greater than or equal (numeric) |
<= | context.count <= 10 | Less than or equal (numeric) |
contains | context.message contains error | Substring match, or array membership |
matches | context.version matches ^v\d+ | Regular expression match |
"false", and not "0":
gate -> next [condition="my_flag"]
Combining conditions
Use && (AND), || (OR), and ! (NOT) to build compound expressions. && binds tighter than ||:
// Both must be true
gate -> deploy [condition="outcome=success && context.tests_passed=true"]
// Either can be true
gate -> proceed [condition="outcome=success || outcome=partial_success"]
// Negation
gate -> retry [condition="!outcome=success"]
// Mixed precedence: (a AND b) OR c
gate -> next [condition="outcome=success && context.ready=true || context.override"]
Agent transitions
Agent and prompt nodes can influence which edge is taken by including a JSON object in their response with routing directives. Fabro scans the LLM output for the last JSON object containing any of these fields:
{
"preferred_next_label": "fix",
"suggested_next_ids": ["implement", "review"],
"context_updates": { "tests_passed": true }
}
| Field | Effect |
|---|
preferred_next_label | Matched against edge labels (same as human gate selection) |
suggested_next_ids | Ordered list of preferred target node IDs |
context_updates | Key-value pairs merged into the run context for downstream conditions |
review [
label="Review",
shape=tab,
prompt="Review the implementation for correctness and \
code quality. If changes are needed, respond with: \
{\"preferred_next_label\": \"fix\"}. If everything \
looks good, respond with: \
{\"preferred_next_label\": \"approve\"}."
]
review -> fix [label="Fix"]
review -> approve [label="Approve"]
Human gate transitions
Human gates use edge labels to present options to the user. The selected label becomes the preferred_label in the outcome, and Fabro matches it to the corresponding edge:
approve [shape=hexagon, label="Approve Plan"]
approve -> implement [label="[A] Approve"]
approve -> plan [label="[R] Revise"]
approve -> skip [label="[S] Skip"]
[A], [R], [S] prefixes are keyboard accelerators — Fabro strips them when matching, so the user can type just the letter.
Unconditional edges
An edge without a condition attribute always matches. When a node has a single outgoing edge, it doesn’t need a condition:
start -> plan -> implement -> exit
gate -> fast_path [condition="outcome=success"]
gate -> slow_path
Weight tiebreaking
When multiple edges match (e.g. two unconditional edges), weight determines the winner. Higher weight wins:
node -> preferred [weight=10]
node -> fallback [weight=1]
Random selection
By default, tiebreaking between candidate edges is deterministic (highest weight, then lexical node ID). Setting selection="random" on a node switches to weighted-random tiebreaking for its outgoing edges:
picker [label="Pick path", selection="random"]
picker -> path_a [weight=3]
picker -> path_b [weight=1]
path_a is chosen ~75% of the time and path_b ~25%. Edges with weight ≤ 0 are treated as weight 1. The cascade priority (conditions → preferred label → suggested next → unconditional) is unchanged — randomness only affects the pick-one-from-candidates step within each tier.
selection="random" cannot be combined with conditional edges on the same node. Validation rejects this combination because condition evaluation order would conflict with random selection. Use unconditional edges with weights instead.
