Routines

A routine is a directed graph that orchestrates agents, gates, and councils into a deterministic, auditable process. Where a single agent improvises every step, a routine fixes the shape of the work: which steps run, in what order, with what checks, and where it can branch or stop.

A routine is made of two things:

• Steps — the units of work (an agent, a gate, a council, or a terminal).
• Edges — directed connections that define flow and dependencies.

Tasks start routines. A manual or scheduled task can target the same routine; the task owns dispatch and scheduling state while the routine owns only the workflow graph.

Step types

Both agent and gate steps need an agent assigned (a gate needs a model to evaluate its criteria); council steps need a council.

Edges and conditions

Edges connect steps and carry a condition that decides whether they activate:

Gate edges must use on_pass and/or on_fail — never always. Other steps use always.

Failure is asymmetric

This is the most important rule to internalize, because it shapes how every routine is designed:

• An agent step that fails kills the whole routine. Agent steps are atomic — there is no on_fail edge for them. If the work can't complete, the routine fails immediately.
• A gate that fails just takes a different path. Gates are where graceful handling lives: a failed gate follows its on_fail edge to rework, escalation, or a terminal_fail.

That asymmetry is intentional: critical work is treated as all-or-nothing, while gates own the branching and error handling.

How a step reports its outcome:

• Every agent step ends by calling route_next_steps, recording its verdict, reasoning, output, and — on pass — a handoff for each activated downstream edge.
• Every gate step also ends by calling route_next_steps, recording the same structured verdict shape; pass activates on_pass routes and fail activates on_fail routes when present.

Bounded rework: the only allowed loop

Routine graphs are otherwise acyclic. The single exception is a bounded gate failure loop — a gate whose on_fail edge points back to an earlier step:

The gate owns the retry decision. The loop is bounded by metadata.max_attempts (default 3). When the budget is exhausted, the routine fails directly with a structured retry_exhausted result — you do not add a separate "exhausted" branch. Only gates may create a retry cycle; agent steps never use on_fail retry edges.

Graph rules

A valid routine graph follows a short checklist:

• Entry steps — one or more, named in entry_steps. Multiple entries start as parallel branches.
• Reachability — every step must be reachable from an entry step.
• Outgoing edges — every non-terminal step needs at least one; terminal steps have none.
• Joins — a step with multiple activated incoming edges is an all-success join: it runs only after every required upstream branch passes.
• Fan-out — multiple outgoing edges from an agent step are deterministic fan-out; the agent must decompose the work so each downstream branch has a clear task.
• Terminals — every routine must have at least one reachable terminal or terminal_fail.
• Owners — agent and gate steps set an agent; council steps set a council. Steps reference each other by stable slug.

Common patterns

Linear pipeline — ordered transformations, each step feeding the next.

Gated pipeline — work with validation checkpoints and an explicit failure path.

Fan-out / fan-in — independent branches run in parallel, then join for synthesis.

Review pipeline — generate, then send to a council for review before a final gate.

Best practices

• Start simple — a linear or gated pipeline before anything elaborate.
• Give every gate clear acceptance criteria.
• Always define both a success (terminal) and a failure (terminal_fail) path.
• Keep individual steps focused; push complex logic into abilities or sub-agents.
• Use councils only when multiple perspectives genuinely add signal.