Automation reference and limits

This is the value reference for automation. Use it to confirm a field name, an operator, an output field, an event name, or a ceiling by its exact value. It covers the grammar that defines a Flow and its steps, the expression syntax those steps use, the structured result each skill returns, the real-time events the platform emits while work runs, and the hard limits that bound all of it. The concepts behind these values live in the Flows, Build a Flow, and Skills guides.

Flow definition grammar

A Flow is a template made of a few named parts. These are the exact fields.

Step fields

Each step runs one skill and carries the controls below. The Flows guide explains what each one does; this is the exact shape.

Parameter fields

Defaults fields

Triggers

A Flow runs on demand, and a trigger can fire it on its own. There are three shapes.

How a run starts

A run begins one of four ways. The first is a person; the other three are a trigger firing on its own. All four count the same against the daily-runs limit.

A triggered run has no person to fill the run dialog, so it uses the Flow's defaults and each parameter's default value. A parameter a trigger relies on therefore needs a defaultValue, or a hidden value set on it, or the run starts without it.

Where a template resolves from

The same flowId can exist at three layers, and the most specific one wins. This is how a built-in becomes editable without losing the original.

1. A filesystem default that ships with the platform.
2. A workspace copy your team has saved.
3. A repository copy scoped to a single repo.

A built-in is read-only until you Customize it, which forks it into a workspace copy. Reset to Default removes the copy and restores the built-in, keeping any schedule attached. The full lifecycle is on Flows.

Expression grammar

Conditions and parameter references share one small expression language. It compares and combines values; it does not calculate them. That keeps a Flow easy to read and its behavior easy to predict.

expression  = or_expr
or_expr     = and_expr ( "||" and_expr )*
and_expr    = comparison ( "&&" comparison )*
comparison  = unary ( ("==" | "!=") unary )?
unary       = "(" expression ")" | value
value       = ref | string | number | "null" | "true" | "false"
ref         = "$" segment ("." segment)*
segment     = identifier ( "[" number "]" )?

A resolved reference is turned into text before it reaches the skill, so a comparison against one quotes the value: $steps.verify.output.readyForPr == "true", not a bare boolean. A reference to a field an earlier step did not produce resolves to the string "undefined", so it pays to bind against fields the upstream skill actually emits. The operators are equality (==, !=) and the logical && and ||, with parentheses for grouping. An expression is capped at 4096 characters; a longer one is rejected. When a decision needs more than a match, have a step report a plain result in its output and branch on that.

Step output contracts

Every step returns a structured result validated against a fixed shape for its skill, with a couple of automatic retries if the first result does not fit. Each result carries the base contract below, and named skills extend it with their own fields, which the next step can read.

The built-in skills the SDLC and fix Flows compose extend that base with these fields.

A skill your team authors produces the base contract, so a custom step still reports a summary, a status, and its artifacts, and a later step can read those. The verify, review, and recheck skills declare that they require an applied environment, so the Flow gates them on open environment-health blockers before and after they run, parking the run for attention rather than pressing on with a broken environment. A create-github-pr skill returns the same fields as create-pr for teams that name it explicitly.

Reading one contract end to end

Here is a single output field crossing from one step into the next step's condition. The review step runs and reports its result:

{
  "summary": "Reviewed PR 482. One blocking finding on input validation.",
  "status": "success",
  "overallVerdict": "request-changes",
  "findings": [ { "findingId": "finding-1a2b", "severity": "blocking" } ]
}

A later scoped-implement step reads that verdict by name in its condition, so it runs only when the review asked for changes:

$steps.review.output.overallVerdict == "request-changes"

The verdict was a literal value in one step's result; one step on, it is the gate that decides whether the next step runs at all. Nothing was passed in a prompt and nothing was inferred. The field is a named part of the review contract, the reference reads it by that name, and the comparison quotes it because a resolved reference reaches the expression as text. That is the shape of a Flow: a step states a fact, and a later step acts on it.

Skill reference

A skill is the unit a step runs. A Flow composes skills; a skill is what does the work inside one step. These are the parts that matter when you bind one to a step.

A skill takes its inputs through the step that runs it: the step's parameters are interpolated into the promptTemplate, as literals or as references to earlier output. Authoring a skill is on the Skills guide.

Run states

A run and its steps move through fixed sets of states. The full tables, including what each state means, are in the statuses reference; the values are listed here for quick lookup.

• A flow run is pending, running, paused, completed, failed, rejected, cancelled, blocked, or interrupted_by_deploy.
• A step is pending, running, completed, failed, blocked, skipped, or cancelled.

Who may read, run, edit, or cancel a Flow is set by the flows.read, flows.run, flows.manage, and flows.cancel.any scopes in the permission scope catalog.

Real-time events

The platform keeps every open tab current over a single server-sent events stream at /__/events. The events on it are lightweight signals: each one names what changed so the page can refetch the authoritative record. The store is the source of truth, not the event payload, so a missed signal is corrected on the next read rather than lost.

Record lifecycle signals

These fire as records are created, changed, or removed. They are grouped by the kind of record.

Portfolio and project events are gated by membership, so a person receives one only for a record they can see. The rest fan out across the workspace.

Run and activity signals

Flow runs, background tasks, and fan-out work emit their own progress signals on the same stream. Like the lifecycle signals above, each one names what advanced so the page can refetch the run's authoritative record.

A fan-out subtask inherits the parent's context, its inputs and the prior results, so each one starts oriented without being told everything again. The fine-grained content of a turn travels on its own stream, covered next; these are the coarse signals that tell a surface a run moved.

The chat-turn stream

A single agent turn streams its own output on a separate, cursor-resumable response so a dropped connection can reconnect and replay from where it left off. The chunks on it are typed.

The turn ends on a [DONE] marker rather than a closed connection, so the client can tell a finished turn from a dropped one and resume accordingly.

The operator that drives a self-hosted sandbox talks over a separate command-and-response channel, not this event stream. It carries provisioning instructions to your cluster and their results, never the workspace events above.

Limits and ceilings

These are the numbers the platform enforces. They come in three kinds, and the value column says which: a fixed cap is the same on every plan and keeps one run from affecting another; a plan allowance rises with your plan and is marked "By plan"; and a per-run default is a starting value you can change on a single run, marked "default". Most are sized so they never come up in normal use.

A run's AI authoring is also bounded by per-turn and per-day budgets and is rate-limited and audited as it writes; those are covered on the agent runtime and counted against your quotas.

Programmatic access

Automation on this platform is built where the work lives, as Flows and skills you compose, schedule, and trigger, rather than as scripts that drive the work model from outside. A scheduled or pull-request trigger starts a run with no person and no external caller, and a Flow's steps read each other's results through the contracts on this page, so a multi-step pipeline runs inside the product rather than from a job server you keep alive. The HTTP endpoints behind the web and operator surfaces are internal to them and are not a published API today. If your team wants one, raise it with your account contact so it can be weighed against what Flows and triggers already reach.

Keeping this reference current

These values are read from the platform's own definitions, so they move with the product. The live surfaces own them: a Flow's editor shows its steps and defaults, a run's detail page shows the result fields a step produced, and the Workflows and quota pages show the values in force for your workspace. When a number here drives a decision, confirm it against the surface that owns it.

Why automation is shaped this way

Every value on this page is a contract that holds while a run is in flight. A step's output fields are a promise about what the next step can read, which is what lets a Flow be assembled from parts instead of written as one long prompt. The expression language stays small so a condition reads at a glance. The events are signals rather than payloads because the record is the source of truth, so a Flow that ran while you were away leaves its result in your work model, not in a message you can miss. The limits are stated in full for the same reason: when you build on a platform, the numbers it holds you to should be ones you can read before you reach them, not after.

For a power user, this is the page behind a Flow you are assembling: the step fields when you wire one up, the output contracts when you pass a result forward, and the operators when you write a condition.

For a developer, the event names and the limits are the reference to keep. The lifecycle signals are how a surface stays live, the chat-turn stream is how a turn is followed, and the ceilings are the numbers to design within.

For an administrator, the triggers and the recheck default are the ones to know. A scheduled or pull-request trigger is how work starts without a person, and the recheck ceiling is how a fix loop knows when to hand back to a human.

For a prospect, the takeaway is that the automation is composable and bounded: a small grammar, clear contracts between steps, live signals you do not have to poll for, and limits stated in the open.