Factory workflows
A workflow is a graph the scheduler runs: a Trigger says when, a Source brings
items in, other nodes read, decide and write, and an End closes each item.
Factory automates work this way. create-factory-automation is only for the
retired scheduled agent jobs such as PR governance, never for a new request.
Recipe, in this order
- Find the factory.
view-screen gives the open factory and workflow.
No factory yet: list-factories, then create-factory.
- Ask for what is missing, in one message. Never guess these:
- the repository as
owner/name, for any GitHub step
- the time zone (IANA, such as
America/New_York) for daily, weekday and
weekly schedules; without one the save fails with schedule_timezone_required
- the Slack channel id, such as
C0123ABCD. A #channel name is not an
id: ask for the id in this same message, not in a later one.
- Before asking for an id, try
list-provider-options (provider and
resource: slack channels, github repositories, sentry
organizations, then sentry projects with parent; search narrows
it): it returns real channels, repos and projects, and fails with
credential_missing while the provider is not connected.
- Read the catalog in two calls.
describe-workflow-node-catalog with
view: "index" returns connection status, the graph shape, every node kind
with its ports and a settingsShape, and one line per operation. Then one
call with operationIds: [...] for the full fields and outputs of the
operations you use: the index has only each one's id, label, kinds, effect
and field names, and its outputs, limits and notes on each field come with
that call. Read a kind's full schema (kind: "source") only when
its shape is not enough. The unfiltered call is too big for one tool result.
The index lists the API request once, as <provider>.apiRequest: see
"An endpoint no step covers".
- Save the whole graph.
save-factory-workflow with factoryId, name
and graph (JSON text, see "Graph shape") creates it, disabled. A bad graph
fails with graph_invalid and one line per problem,
code @ node x port y: detail, all at once: fix them all, then save again.
Nothing is saved on a failure.
- Read
connections in the save result. Each entry is a provider the
graph needs: status is connected, not connected, unknown or
unreadable, and nodes are the node ids that need it. Call
request-workflow-connection for each one that is not connected. See
"Connecting".
- Dry run.
run-factory-workflow with mode: "dry" and waitSeconds: 25.
See "Dry run loop".
- Enable. Only after a clean dry run of the current version and every
provider connected. First say what will start happening: what runs when, and
what it sends, writes or merges. Then call
set-factory-workflow-enabled with
enabled: true. It stops for the user's approval in chat, and the approval
card names the tool and its arguments, not what they mean, so your sentence is
what they decide on. Until they approve, the workflow is off and nothing was
enabled. If they decline, say it stays off; do not ask again unless they do.
- Tell the user, once the enable call has returned, what runs when, what
it reads and writes, which integrations are connected, and that the first
live run is the schedule. Creating a workflow from chat opens its canvas (
navigated: true). When
navigated is false, call navigate with the result's canvasPath.
Saving into an enabled workflow switches it off (disabledBySave: true): the
new version needs its own dry run. Updating needs workflowId and the
expectedVersion you read; a stale one fails with version_conflict. Read it
again with get-factory-workflow before editing: the user may have changed it.
Graph shape
{ nodes: [{ id, name, label?, kind, position: {x, y}, settings }],
edges: [{ id, from: { node, port }, to: { node } }],
settings: { timezone?, extras? } }
Send this object to save-factory-workflow as JSON text in graph: one string,
quotes escaped. A parse failure names the position: fix it and send again.
id is a slug (letters, digits, -, _). name is an identifier (letters,
digits, _, no spaces) and is how later nodes read this one: nodes.<name>.
Reusing the id as the name is fine. Space position.x by 344.
label is the friendly title people read on the canvas:
free text up to 64 characters, such as Post the digest to #support. Set one
on every node you add, in the user's words. name stays the identifier for
paths and is never shown, so a label can change without breaking a {{ }}
path. Omit it only to keep the default title.
- Exactly one
trigger, with no inputs. Every output port must lead to a node,
or the save fails with port_leads_nowhere.
- Ports:
trigger, source, lookup, action, combine, split, ai,
agent have out. filter has match and otherwise. switch has
route:<route id> for each route and otherwise. wait has replied and
timedOut (reply), done (time), met and timedOut (condition). end has
none. A lookup, action, ai or agent node with onError: "route" also
has error, which must lead somewhere too (see "A failed step").
- Trigger schedules:
{every: "5m"|"10m"|"15m"|"30m"|"60m"}, {daily: {at}},
{weekdays: {at}}, {weekly: {day: 0-6, at}}, at as 24-hour HH:MM.
Put timezone on the trigger's settings.
- Workflow
settings.extras holds free-form values a node reads with a path,
such as the repository and the channel id. Put them there so a person can
change one place. extras.repository (owner/name) is also the one
repository the merge gate allows, set when the graph is saved: a workflow that
merges needs it, and without it the gate refuses with repository_not_allowed.
A GitHub source polling a different repository fails the save with
repository_conflict; a value that is not owner/name fails with
repository_invalid.
- A Source's scope lives on the Source node. For an
inbox-poll source,
filter.scopes[0] is the Slack channel id, the GitHub repo (owner/name) or
the Sentry project (org/project), one per workflow. save-triage-config is
only a fallback; do not rely on it.
- An inbox source starts from now. Its first live run takes the newest
position (the newest Slack message, open GitHub item or Sentry issue) and
nothing else, so history is never processed; the step and the run say
primed, which is not "no new messages". A dry run shows a sample of the
newest items and stores nothing, and a workflow turned off and on goes on from
where it was. Tell the user that what is in the channel today will not be
answered.
- A Slack source ignores the app's own posts. Its notices and replies, which land in the channel it reads, are never taken as new reports; the step counts them as
skippedOwn, a source that cannot learn who the app is fails with identity_unresolved instead of guessing, and filter.includeOwnPosts: true reads them anyway.
Binding values and {{ }} paths
A node's args map each field to a binding. A bare string is rejected.
{ "mode": "path", "path": "item.title" }: read a value (no braces).
{ "mode": "fixed", "value": "..." }: a literal. A string may embed holes,
"Review {{ item.title }}"; a string that is one hole keeps its type.
{ "mode": "ai", "instruction": "..." }: the model writes this one field
from the incoming item. Never for a JSON field, and not on a Source.
- Recipients and targets (who or where an effect lands: email recipients, a Slack
channel or user, a Builder project or branch, a GitHub repo or PR number) come
from fixed values, workflow settings, item fields or earlier lookups, never an
AI step's output; the save refuses it with
model_written_target.
A path is root.field.field[0]: names and [0] indexes only, no calls or
operators. Roots:
| Root |
Reads |
item |
the item at this node (shape below), plus item.id |
nodes.<name> |
the output a node upstream attached (a Lookup's into renames it). A node that is not upstream fails with bad_reference, and so does a field its operation does not return: the error lists the real ones |
settings |
the workflow settings, such as settings.extras.repository |
run |
id, mode, startedAt, scheduledFor, windowStart, windowEnd |
loop |
iteration, max, inside a loop only |
A Source runs before any item exists, so its args read only settings and
run. A missing value fails the item with expression_failed; it never
renders blank.
Item shape
What flows between nodes: id, kind (message, issue, pull_request,
commit, call, lead, ticket, alert, error, spike), provider,
title, text, url, author, occurredAt, thread (channelId,
threadTs, repo, number, ticketId), extras (provider fields, such as
extras.sha) and payload. A pull request has item.thread.repo and
item.thread.number. A Slack message's title is its first line, not who wrote it (that is extras.authorLabel), so name a report with {{ item.title }}, never {{ item.id }}.
Never have a model write back what an item already carries. To group, rank or
label items, use an AI step in perItem mode with a batchSize big enough to
hold them together: the model sees the whole batch, answers once for each item
by its id with only the fields you declare, and the engine attaches those
fields to the item it came from, so item.title, item.thread and
item.author stay the real ones. An answer that leaves out a declared field,
gives it the wrong kind, names an item that was not given, or answers one twice
fails the item (or the batch) as ai_invalid_output; it never invents items.
Have the model say who goes together with a label (groupName), Combine on
nodes.<ai>.groupName with identity: "firstMember", and read the group's
name and id from item.key and item.id: they come from its first member, not
from the label.
combine turns many items into one. Mode list gives { items, count, truncated, totalAvailable }, and with nothing to combine it still gives one item
with count: 0, so a quiet day can say so. Rules in filter and switch are
{ left: "<path>", op, right } with op one of equals, notEquals,
contains, startsWith, isEmpty, isTrue, inList, gt, lt, between,
olderThan, pastDue; isEmpty, isTrue and pastDue take no right.
Worked example: a weekday digest
"Every weekday at 8, send the team a summary of what changed in the repo."
Trigger, a window Source over commits, one list, one AI-written Slack post, End.
This is the shipped story graph (server/workflow/stories/03-morning-digest),
with the repo and channel in settings.extras, and a label on each node:
{
"nodes": [
{"id": "weekdays8", "name": "weekdays8", "label": "Every weekday at 8", "position": {"x": 0, "y": 0}, "kind": "trigger", "settings": {"schedule": {"weekdays": {"at": "08:00"}}, "timezone": "America/New_York"}},
{"id": "commits", "name": "commits", "label": "Commits since last digest", "position": {"x": 344, "y": 0}, "kind": "source", "settings": {"source": "window", "operation": "github.listCommits", "args": {"repo": {"mode": "path", "path": "settings.extras.repository"}}, "maxItems": 100}},
{"id": "digest", "name": "digest", "label": "Build the digest", "position": {"x": 688, "y": 0}, "kind": "combine", "settings": {"mode": "list"}},
{"id": "post", "name": "post", "label": "Post to the team channel", "position": {"x": 1032, "y": 0}, "kind": "action", "settings": {"operation": "slack.postMessage", "args": {"to": {"mode": "path", "path": "settings.extras.digestChannel"}, "text": {"mode": "ai", "instruction": "Write the digest from the commit list: a one-line TL;DR, then at most 5 bullets grouped by area that name notable authors and link the commits. When count is 0, write exactly: No commits since the last digest. When truncated is true, say how many of totalAvailable commits are shown."}}}},
{"id": "done", "name": "done", "label": "Done", "position": {"x": 1376, "y": 0}, "kind": "end", "settings": {"outcome": "done"}}
],
"edges": [
{"id": "e1", "from": {"node": "weekdays8", "port": "out"}, "to": {"node": "commits"}},
{"id": "e2", "from": {"node": "commits", "port": "out"}, "to": {"node": "digest"}},
{"id": "e3", "from": {"node": "digest", "port": "out"}, "to": {"node": "post"}},
{"id": "e4", "from": {"node": "post", "port": "out"}, "to": {"node": "done"}}
],
"settings": {"extras": {"repository": "acme/web", "digestChannel": "C0123ABCD"}}
}
New pull requests, not commits. No catalog operation lists open pull
requests; the GitHub poller does. Replace commits with
{"source": "inbox-poll", "poller": "github", "takeLimit": 10, "filter": {"scopes": ["acme/web"]}}
(at most 10 per run; the poller also brings issues), and put a filter on
item.kind equals pull_request before digest, with both its ports wired
(otherwise to a dismissed End with a reason). Tell the user about the
10-per-run limit.
An endpoint no step covers
When no operation reads what the user wants, add a Lookup with
<provider>.apiRequest rather than saying it cannot be done. It sends a
read-only GET to any path of a connected provider: slack, github, hubspot,
gong, pylon, stripe, posthog, bigquery, jira, notion or sentry. Read it with
operationIds first: its description and field notes are the reference.
- Find the path before you write it.
provider-api-catalog with the
provider gives its base URL, example paths and docs links; provider-api-docs
with a url reads the endpoint's page. path sits below that base URL
(Slack conversations.history, Stripe customers), with no host. PostHog,
BigQuery and Sentry keep {projectId} or {orgSlug} in a path for the
connection to fill. Parameters go in query, never after a ?.
- The answer is the provider's own JSON at
nodes.<name>. Its fields are
not checked at save, so read the real shape after a dry run, from the item's
summary in get-workflow-node-audit, before binding a later step to a path in
it. includeStatus: true makes it {status, headers, body}. With pagination
(the next cursor must be a plain field in the body; at most 5 pages) it is
{pagesRead, moreAvailable, nextCursor, items}: say when moreAvailable.
- A cut answer says so first. Past about 33,000 characters it leads with
truncated: true and cuts: each list shortened (kept of of), text
clipped, or key left out, by path. A list becomes {truncated, count, totalAvailable, cuts, value}, so nodes.x[0] stops reading and
nodes.x.value[0] starts: test nodes.x.truncated before relying on a count,
and tell the user how many came back of how many. The step carries
outputsTruncated. Fewer or narrower results (per_page, a filter) are the
fix, not a bigger read.
- For a list or big objects, set
fieldsToKeep (Fields to keep): dotted
paths such as ["number", "title", "user.login"]. The step passes on only
those, cut before any size limit, so three 25 KB pull requests stay whole.
A path inside a list applies to every entry, and user keeps all of user.
Paths that matched nothing come back in nodes.<name>.fieldsMissing (a list
then reads nodes.<name>.value[0]): fix the typo and tell the user. With
pagination it trims each entry; with includeStatus only the body. An
answer that says the provider did not do it (Slack ok: false, BigQuery
jobComplete: false, an errors list) always keeps those keys, so read
nodes.<name>.ok and .error before trusting an empty result.
- One step hands on about 64 KB in all, counting every item it emits and
every earlier answer still attached to each (
nodes.<step>). Three big reads
in a row, or one read over several items, fail as output_over_cap naming the
step; the cap is not raised. Set fieldsToKeep, narrow the request, or split
the work.
- A curated lookup hands on a bounded answer. A Stripe billing lookup keeps
the customer, subscription and invoice facts (about 4,000 characters), a Gong
transcript the words of its opening, about 15 minutes (18,000), Sentry events
10,000, a thread read 6,500 and the open reports their title, text, thread and
Builder branch, about 13 of them (10,000). A cut answer leads with
truncated: true and cuts (the thread and the open reports instead say
truncated, nextOldest and nextCursor): say how much came back, never
that you read all of it.
- Never from a model.
path may be typed, a setting, an item field or an
earlier lookup, not AI-written (model_written_target), and the step is never
an AI step's tool (unknown_tool). Headers never carry credentials: the
connection signs the request.
- Limits to tell the user: GET only, JSON only, no body, no POST searches,
no page-number or
Link paging. A refused request fails the item as
lookup_failed with the reason in brackets, such as unsafe_path_value,
full_url_refused, header_denied, invalid_fields_to_keep; a 404 is not
retried.
- What the app shows. Test step on an API request shows the whole response on
screen for the person and keeps none of it; a run, and so anything you read back
with
get-workflow-node-audit, keeps only a short summary of the answer.
- Test it on its own. A Lookup that reads no
item.* or nodes.* runs
once in a mode: "test" run with no sampleItemIds. Any other step with none
pinned is refused as test_needs_items, nothing started: pin items from a dry
run, or run the whole workflow first.
Slack channels
Slack needs a channel id such as C0123ABCD, found in Slack under the
channel's details, at the bottom. Ask for it in the same message as the time
zone. Do not resolve a name with provider-api-request: it needs a workspace
connection and ends the turn in a connect request. list-messaging-channels
lists the app's messaging integrations, not Slack channels. A Source's channel
scope that is not an id is rejected at save. A post's to is not checked at
save and a dry run never posts, so a name there only fails on the first live
run.
A Slack report's item.author is a user id (U0123ABCD), never an email. A
step that needs the person's address (Builder's userEmail) reads it first with
a Lookup slack.getUserEmail: userId is item.author, and fallbackEmail
is settings.triageOwnerEmail. Read nodes.<lookup>.email; it is always an
address, and emailSource says slack or fallback. The fallback is used only
when Slack says the person has no email. A lookup that failed (a connection
without the users:read.email scope, an unknown id, Slack down) fails the
step with a typed code and never falls back, because the work would be
attributed to the wrong person. A userId that is not a Slack user id (an email,
a bot id) fails the step with slack_user_invalid.
Connecting
Connections are per provider, from connections in a save or
get-factory-workflow result, or from describe-workflow-node-catalog.
not connected: call request-workflow-connection with the provider.
For Slack, GitHub, Sentry, HubSpot, Jira, Notion and BigQuery the chat shows
a connect card and the turn waits for the user. Ask for one provider per
turn. When the user says it is connected, call get-factory-workflow again
to refresh connections and go on.
- Gong, Pylon, Stripe, PostHog, Builder, email: the call returns
connected: false with where and keys. Tell the user exactly that, then
check again when they say it is done.
unknown: the check itself failed; detail says why. Say so; do not call
it connected or not connected, and check again.
unreadable: a key or sign-in is saved (a Slack or Sentry token, a Sentry
organization slug, a Jira token, a Builder sign-in) but this deployment cannot
decrypt it, usually because the database came from another deployment or its
encryption key changed; detail names the key. A person must save it again
under Keys in Settings, or run with the key that saved it. Do not call a
connect card for it, do not retry it, and do not call it not connected.
request-workflow-connection and set-factory-workflow-enabled refuse it
with connection_unreadable, and a step that hits it fails app_secret_unreadable.
- Sentry also needs
SENTRY_ORG_SLUG: a token alone reads not connected,
with the slug named in detail.
set-factory-workflow-enabled refuses with connection_required until every
provider is connected. A step that fails credential_missing in a dry run
means the same thing: connect it, then dry run again.
A failed step
By default an item that fails at a step ends for a person (Needs you) and
nothing is posted, so nobody learns a loop is stuck. Set settings.onError to
"route" on a lookup, action, ai or agent node and the step gets an
extra error port: the failed item leaves by it, with the failure at
item.error (code, message, node the step's name, outcomeUnknown), and
is not counted as failed. Absent or "stop" is the old behavior.
- Wire the
error port, or the save fails with port_leads_nowhere at that
node and port. Typically error goes to an Action that posts to the owner (a
Slack post whose text reads {{ item.error.code }} and
{{ item.error.message }}), then an End with needsManual and a reason
that reads item.error too, so Needs you shows the real failure.
- The failed step has no output on that path. Read
item.*, item.error.*
and steps before it; nodes.<failed step> does not exist there.
- Retries still come first. A failure worth another try (a timeout, an AI
answer outside its fields) is retried as before and leaves by
error only
when the attempts are spent, so a flaky minute sends no alert. A failure no
retry fixes (no credential) leaves at once. A dry run parks nothing, so it
routes at once and its Action only says what it would send.
- A write never retries, routed or not.
outcomeUnknown: true (code
effect_needs_check) means the write may have happened. It is still handed to
a person and its receipt stays open, so the alert is information and never
makes it read as handled: end that path with needsManual, never done.
- A dry run is not clean proof for that step. The step reads as succeeded
and the run's
counts.errorRouted (and the step's routedErrors and
firstRoutedError fields) say how many items took the error port and why:
above zero, read the reason and fix the cause before enabling.
- Not covered: a step that fails as a whole (a result over the step cap, a
graph the engine cannot run) still stops the run, and a Source, Filter,
Switch, Combine, Split, Wait or End has no
onError.
The shipped builder-to-merge story routes the AI judge's failures this way.
Dry run loop
run-factory-workflow mode: "dry" reads real data and runs the AI, but every
write only reports what it would do. With waitSeconds: 25 it returns:
status: "finished": workflowRunId, runStatus, clean, counts
(taken, done, itemFailures, ...), failedSteps (node, code, message)
and needsConnection (providers to connect).
status: "still_running" with runId and workflowRunId: read it with
get-factory-workflow-run (it takes either id), then again. Reads are not
deduplicated.
status: "skipped", reason: "already_running": another run of this
workflow was going, so this one never started and nothing ran. Read
activeRunId with get-factory-workflow-run, wait for it to end, then run
again.
status: "not_started": the scheduler ended the run before the workflow
began; errorCode and message say why.
Loop: run, read, fix, run again, until clean is true. A failed step's code
says what to fix: expression_failed is a path or value (read the step with
get-factory-workflow-run), credential_missing is a connection,
graph_invalid is the graph. itemFailures above zero with a clean-looking
step: get-workflow-node-audit for the node lists the item errors. Every fix
is a new save, so the next dry run is of the new version. Never use
mode: "live" to test: it sends real messages, only runs for an enabled
workflow, and stops for the user's approval like enabling does.
When a run fails or behaves oddly
Call get-workflow-diagnostics (factoryId, optional workflowId, runId,
sinceHours, default 24, max 168) before guessing. It returns one JSON object
under 30 KB: build and deploy facts, whether recurring jobs are on, the
scheduler's heartbeat age, each provider's connection status, the workflow's
shape and job health, the last 10 runs with their failed steps, waiting items
and how many are overdue, writes that began and never confirmed, and the recent
tripwires with counts by code. truncated lists what was cut and unavailable
what could not be read.
- A tripwire is one typed row for something unexpected at a risky boundary
(a provider answering in a new shape, a wait that woke late, a refused or
slow tool call): ids, status codes, durations, counts and the shape of data,
never raw values. It changes nothing; never branch on whether one exists.
- Read in this order:
unavailable, then scheduler and
environment.recurringJobs (nothing runs when those are off), connections,
runs[].failedSteps, then tripwires.counts and tripwires.recent.
- Tell the user they can paste what "Copy diagnostics" gives them (the
workflow's More actions menu, or Settings, Scheduler health): the same
object, with no tokens, emails or URL query strings, so never ask for those.
- Codes are a closed list in
server/tripwire/types.ts. Never put customer
text, a message body or a credential into a tripwire's details.
An item that needs a person
list-workflow-items with needsYou: true finds them. Once the cause is fixed,
requeue-factory-item sends one back to its workflow (it stops for the user's
approval: say which item and what it may send first); dismiss-factory-item
closes it and sends nothing. Both take factoryId and itemId, and a repeat
changes nothing.
Builder: start, then check
Builder ignores the branch name a start asks for and keeps its own. builder.start
returns it as externalRef (also branchName). A start found already done
supplies externalRef, url, status and projectId and not accepted or
branchName, because a receipt keeps only the fields that name a thing: read
externalRef.
Bind userEmail to a reporter's email, never to item.author. On a Slack
report item.author is a user id, and Builder looks userEmail up against its
Space members. Put a slack.getUserEmail Lookup before the start (see Slack
channels) and bind nodes.<lookup>.email. For a group the start is for its
first report's reporter.
Bind reports on every builder.start (item.reports for a group, item.id for one item). Factory reads each report from its inbox and adds its headline, author, link and text after the task your instruction writes, so never have the model copy the report; a start with no report to read is refused.
Never compare the name you asked for with the one Builder returned. A
check that externalRef equals the asked name turns away every real start.
To test that a start gave a task, test that externalRef is not empty.
Bind every later Builder step to the start's receipt. builder.check and
builder.followUp take branchName as
{ "mode": "path", "path": "nodes.<start step>.externalRef" }. The name you
asked for is not the one Builder keeps, so a check on it reads not_found.
Route on state, hasPullRequest, prNumber and prUrl. There is no
status and no pullRequest.number; a save that reads a name builder.check
does not return is refused with the real names listed. Test hasPullRequest,
never prNumber > 0: prNumber is null until a pull request exists.
state is working, stuck, completed, failed or not_found.
completed means Builder is idle and a pull request exists, whether open,
closed or draft; read prStatus before treating it as done. failed is a real failure (the branch
was archived or deleted without a merge). not_found is not a failure: Builder
has no active branch under that name, which can mean the task finished and was
archived, the name is not the one Builder returned, or the task was never
created. Wait and check again, or hand it to a person; do not report it as
Builder failing.
Put reason in any message that says what Builder is, such as
Builder is {{ nodes.check.state }} ({{ nodes.check.reason }}), so a person
can tell branch_not_found from branch_archived.
A start is deduplicated by its receipt, not by the branch name. The same
item at the same step finds its done receipt and does not call Builder again,
through a requeue, a new run and a workflow saved again. For a grouped start
the item is the group, and its id comes from the group's first report (a
Combine groupBy with identity: "firstMember"), never from a label a model
wrote, so a requeued report is the same group however the model names it. A
report that comes back in a different group has a different member list and so
a different receipt. Builder renames branches, so the lookup by the asked name
never finds one. Ask for a name unique to the task. builder.followUp
succeeding means Builder queued the message, not that it acted on it.
Merging a pull request
github.mergePullRequest merges only what the merge gate clears, and re-runs
the gate itself, so a graph that skips factory.mergeGate still cannot merge a
held pull request. The gate wants: a Builder account (builderio-bot or
builder-io-integration[bot], no other name) opened it from a branch in the
repository, aimed at the default branch; every check on the head commit green;
no unresolved review thread and no review asking for changes; an approval of the
current head commit from a person who is an owner, member or collaborator, not
the author and not a bot or Builder account (a push after the approval needs a
new one); a small diff clear of the never-automate paths; a test change beside
any code change (docs, changesets, lockfiles, package manifests and config need
none); and a ### Verified section in the description with text, a screenshot
or a recording. A held pull request goes to Needs you, and the Slack notice
carries every reason. get-factory-merge-gate returns them as reasonCodes and
reasonText; approval_required comes with approvals counts (seen,
qualifying, byAuthor, fromBots, fromNonCollaborators, stale), and
no_regression_test and no_verification_evidence are the two proof rules.
github.readPullRequest returns verification (present, hasMedia and a
short excerpt of the Verified section, never the description itself) for a
graph that wants to route on it. The shipped builder-to-merge story asks an AI
step, judge, after the gate and before the merge whether that excerpt
plausibly shows the fix: verified goes on to the merge, unsure (or a judge
that fails, which tells the triage owner the typed failure) holds the pull request for a person, and it never approves. Explain
a hold in those words. Never approve or merge for the user: an approval is a person's, and
requeue-factory-item sends the item back once it is given.
Jira and Sentry steps
The issue key (PROJ-123) and the Sentry issue id (digits) come from an item
field or a setting, never an AI step. A bad one fails the item before the
provider is called. Each write is sent once; _outcome_unknown means check.
jira.getIssue (Lookup): status, statusCategory, resolution, assignee,
labels and transitionNames, capped, with truncated when cut.
jira.listTransitions (Lookup): what the issue can take now, each with id,
name and toStatus.
jira.transitionIssue (Action): moves it by transition name or id, read first
against Jira's own list. An unknown or ambiguous name is refused, never
guessed. Naming the status it is already in succeeds with alreadyInState.
sentry.resolveIssue (Action): resolution is resolved or
resolvedInNextRelease. Sentry's answer must confirm it.
sentry.assignIssue (Action): assigneeKind user (assignee is an email),
team (a lowercase slug, read first; unknown is refused) or nobody.
Labels and reactions
Writes run only on an action step, never as a Lookup, a Source or an AI
tool. A dry run and a test of the step say what they would send and send nothing.
Factory has no step that comments on a GitHub issue: findings go to Slack.
github.addLabels: repo, number and labels, a list of 1 to 5 names of
up to 50 characters, no comma. A label already there stays, so a repeat
changes nothing. Gives labels, all the item has now.
github.removeLabel: repo, number and label. An item without it
succeeds with alreadyAbsent: true.
slack.addReaction: channel (an id), ts (the message's time; for a report
that starts a thread, item.thread.threadTs) and name, an emoji without
colons, such as eyes. A repeat succeeds with alreadyReacted: true.
Only the factory's own repository. A label step refuses any other
repo, and a factory with no repository set, with repository_not_allowed,
as the merge step does; set the repository in the factory before using one.
A model writes none of these fields. repo, number, labels, label,
channel and ts say where the write lands (a label can start automation in
the repository): type them, or read a setting, an item field or a lookup,
never an AI step's answer (model_written_target).
A bad value is refused on the first live run, not in a dry run. A dry run
never calls the step, so check the limits above yourself: a refusal is typed
(github_label_invalid, github_repository_invalid, repository_not_allowed,
slack_channel_invalid, slack_reaction_invalid) and sends nothing.
Read a failure by its code. github_access_denied is a connection with no
write access (Slack slack_access_denied, missing_scope: the app needs
reactions:write); connect again with the right access. github_not_found
and slack_not_found wrote nothing. A code ending _outcome_unknown may have
written: the item goes to Needs you and nothing sends it again, so check the
issue or message first.
The loop's own reaction is not a person's. A Source's claimReaction, a
reply Wait's ackReaction and slack.readThread leave out the app's own
bot, so reacting eyes to a report never marks it claimed. slack.readThread
lists the bot's reactions apart, under ownReactions, and reactions holds
only everyone else's.
Other tools
list-factory-workflows, get-factory-workflow (version, or nodeIds for
a graph too large to read at once), list-factory-workflow-versions,
restore-factory-workflow-version, rename-factory-workflow (the workflow's
own name in the list and toolbar; a save never renames, and the version, graph
and on/off state stay), delete-factory-workflow (stops for the
user's approval: name the workflow and what goes with it first),
list-factory-workflow-runs, get-factory-workflow-run,
get-workflow-node-audit, get-workflow-node-data (the item fields a node
took in and put out in a run; not lookup or action responses or AI answers).
To show something, navigate with
/factory?factoryId=<id>&workflow=<id> plus node=, edge=, run= or
version=.
- A person's unsaved edits in the editor autosave as a private draft, and
get-factory-workflow returns hasDraft (true when this person has one). When it is true, say so before saving a new version, because the editor will then offer Keep my changes or Load latest; the agent never reads or writes drafts.
1---2name: factory-workflows3description: >-4 How to build, connect, dry-run and enable a Factory workflow from chat: the5 recipe, graph shape, `{{ }}` paths, item shape, and the connect protocol. Use6 whenever the user asks Factory to automate something (a digest, routing, a7 nudge, a follow-up, "every weekday at 9 post ... to Slack") or to edit, run,8 enable, connect or fix a workflow.9metadata:10 source: https://skillmd.com/skills/builderio/factory-workflows11---1213# Factory workflows1415A workflow is a graph the scheduler runs: a Trigger says when, a Source brings16items in, other nodes read, decide and write, and an End closes each item.17Factory automates work this way. `create-factory-automation` is only for the18retired scheduled agent jobs such as PR governance, never for a new request.1920## Recipe, in this order21221. **Find the factory.** `view-screen` gives the open factory and workflow.23 No factory yet: `list-factories`, then `create-factory`.242. **Ask for what is missing, in one message.** Never guess these:25 - the repository as `owner/name`, for any GitHub step26 - the time zone (IANA, such as `America/New_York`) for daily, weekday and27 weekly schedules; without one the save fails with `schedule_timezone_required`28 - the Slack channel id, such as `C0123ABCD`. A `#channel` name is not an29 id: ask for the id in this same message, not in a later one.30 - Before asking for an id, try `list-provider-options` (`provider` and31 `resource`: slack `channels`, github `repositories`, sentry32 `organizations`, then sentry `projects` with `parent`; `search` narrows33 it): it returns real channels, repos and projects, and fails with34 `credential_missing` while the provider is not connected.353. **Read the catalog in two calls.** `describe-workflow-node-catalog` with36 `view: "index"` returns connection status, the graph shape, every node kind37 with its ports and a `settingsShape`, and one line per operation. Then one38 call with `operationIds: [...]` for the full fields and outputs of the39 operations you use: the index has only each one's id, label, kinds, effect40 and field names, and its outputs, limits and notes on each field come with41 that call. Read a kind's full schema (`kind: "source"`) only when42 its shape is not enough. The unfiltered call is too big for one tool result.43 The index lists the API request once, as `<provider>.apiRequest`: see44 "An endpoint no step covers".454. **Save the whole graph.** `save-factory-workflow` with `factoryId`, `name`46 and `graph` (JSON text, see "Graph shape") creates it, disabled. A bad graph47 fails with `graph_invalid` and one line per problem,48 `code @ node x port y: detail`, all at once: fix them all, then save again.49 Nothing is saved on a failure.505. **Read `connections` in the save result.** Each entry is a provider the51 graph needs: `status` is `connected`, `not connected`, `unknown` or52 `unreadable`, and `nodes` are the node ids that need it. Call53 `request-workflow-connection` for each one that is `not connected`. See54 "Connecting".556. **Dry run.** `run-factory-workflow` with `mode: "dry"` and `waitSeconds: 25`.56 See "Dry run loop".577. **Enable.** Only after a clean dry run of the current version and every58 provider connected. First say what will start happening: what runs when, and59 what it sends, writes or merges. Then call `set-factory-workflow-enabled` with60 `enabled: true`. It stops for the user's approval in chat, and the approval61 card names the tool and its arguments, not what they mean, so your sentence is62 what they decide on. Until they approve, the workflow is off and nothing was63 enabled. If they decline, say it stays off; do not ask again unless they do.648. **Tell the user**, once the enable call has returned, what runs when, what65 it reads and writes, which integrations are connected, and that the first66 live run is the schedule. Creating a workflow from chat opens its canvas (`navigated: true`). When67 `navigated` is false, call `navigate` with the result's `canvasPath`.6869Saving into an enabled workflow switches it off (`disabledBySave: true`): the70new version needs its own dry run. Updating needs `workflowId` and the71`expectedVersion` you read; a stale one fails with `version_conflict`. Read it72again with `get-factory-workflow` before editing: the user may have changed it.7374## Graph shape7576```77{ nodes: [{ id, name, label?, kind, position: {x, y}, settings }],78 edges: [{ id, from: { node, port }, to: { node } }],79 settings: { timezone?, extras? } }80```8182Send this object to `save-factory-workflow` as JSON text in `graph`: one string,83quotes escaped. A parse failure names the position: fix it and send again.8485- `id` is a slug (letters, digits, `-`, `_`). `name` is an identifier (letters,86 digits, `_`, no spaces) and is how later nodes read this one: `nodes.<name>`.87 Reusing the id as the name is fine. Space `position.x` by 344.88- `label` is the friendly title people read on the canvas:89 free text up to 64 characters, such as `Post the digest to #support`. Set one90 on every node you add, in the user's words. `name` stays the identifier for91 paths and is never shown, so a label can change without breaking a `{{ }}`92 path. Omit it only to keep the default title.93- Exactly one `trigger`, with no inputs. Every output port must lead to a node,94 or the save fails with `port_leads_nowhere`.95- Ports: `trigger`, `source`, `lookup`, `action`, `combine`, `split`, `ai`,96 `agent` have `out`. `filter` has `match` and `otherwise`. `switch` has97 `route:<route id>` for each route and `otherwise`. `wait` has `replied` and98 `timedOut` (reply), `done` (time), `met` and `timedOut` (condition). `end` has99 none. A `lookup`, `action`, `ai` or `agent` node with `onError: "route"` also100 has `error`, which must lead somewhere too (see "A failed step").101- Trigger schedules: `{every: "5m"|"10m"|"15m"|"30m"|"60m"}`, `{daily: {at}}`,102 `{weekdays: {at}}`, `{weekly: {day: 0-6, at}}`, `at` as 24-hour `HH:MM`.103 Put `timezone` on the trigger's settings.104- Workflow `settings.extras` holds free-form values a node reads with a path,105 such as the repository and the channel id. Put them there so a person can106 change one place. `extras.repository` (`owner/name`) is also the one107 repository the merge gate allows, set when the graph is saved: a workflow that108 merges needs it, and without it the gate refuses with `repository_not_allowed`.109 A GitHub source polling a different repository fails the save with110 `repository_conflict`; a value that is not `owner/name` fails with111 `repository_invalid`.112- **A Source's scope lives on the Source node.** For an `inbox-poll` source,113 `filter.scopes[0]` is the Slack channel id, the GitHub repo (`owner/name`) or114 the Sentry project (`org/project`), one per workflow. `save-triage-config` is115 only a fallback; do not rely on it.116- **An inbox source starts from now.** Its first live run takes the newest117 position (the newest Slack message, open GitHub item or Sentry issue) and118 nothing else, so history is never processed; the step and the run say119 `primed`, which is not "no new messages". A dry run shows a sample of the120 newest items and stores nothing, and a workflow turned off and on goes on from121 where it was. Tell the user that what is in the channel today will not be122 answered.123- **A Slack source ignores the app's own posts.** Its notices and replies, which land in the channel it reads, are never taken as new reports; the step counts them as `skippedOwn`, a source that cannot learn who the app is fails with `identity_unresolved` instead of guessing, and `filter.includeOwnPosts: true` reads them anyway.124125## Binding values and `{{ }}` paths126127A node's `args` map each field to a binding. A bare string is rejected.128129- `{ "mode": "path", "path": "item.title" }`: read a value (no braces).130- `{ "mode": "fixed", "value": "..." }`: a literal. A string may embed holes,131 `"Review {{ item.title }}"`; a string that is one hole keeps its type.132- `{ "mode": "ai", "instruction": "..." }`: the model writes this one field133 from the incoming item. Never for a JSON field, and not on a Source.134- Recipients and targets (who or where an effect lands: email recipients, a Slack135 channel or user, a Builder project or branch, a GitHub repo or PR number) come136 from fixed values, workflow settings, item fields or earlier lookups, never an137 AI step's output; the save refuses it with `model_written_target`.138139A path is `root.field.field[0]`: names and `[0]` indexes only, no calls or140operators. Roots:141142| Root | Reads |143| --- | --- |144| `item` | the item at this node (shape below), plus `item.id` |145| `nodes.<name>` | the output a node upstream attached (a Lookup's `into` renames it). A node that is not upstream fails with `bad_reference`, and so does a field its operation does not return: the error lists the real ones |146| `settings` | the workflow settings, such as `settings.extras.repository` |147| `run` | `id`, `mode`, `startedAt`, `scheduledFor`, `windowStart`, `windowEnd` |148| `loop` | `iteration`, `max`, inside a loop only |149150A Source runs before any item exists, so its args read only `settings` and151`run`. A missing value fails the item with `expression_failed`; it never152renders blank.153154## Item shape155156What flows between nodes: `id`, `kind` (`message`, `issue`, `pull_request`,157`commit`, `call`, `lead`, `ticket`, `alert`, `error`, `spike`), `provider`,158`title`, `text`, `url`, `author`, `occurredAt`, `thread` (`channelId`,159`threadTs`, `repo`, `number`, `ticketId`), `extras` (provider fields, such as160`extras.sha`) and `payload`. A pull request has `item.thread.repo` and161`item.thread.number`. A Slack message's `title` is its first line, not who wrote it (that is `extras.authorLabel`), so name a report with `{{ item.title }}`, never `{{ item.id }}`.162163Never have a model write back what an item already carries. To group, rank or164label items, use an AI step in `perItem` mode with a `batchSize` big enough to165hold them together: the model sees the whole batch, answers once for each item166by its id with only the fields you declare, and the engine attaches those167fields to the item it came from, so `item.title`, `item.thread` and168`item.author` stay the real ones. An answer that leaves out a declared field,169gives it the wrong kind, names an item that was not given, or answers one twice170fails the item (or the batch) as `ai_invalid_output`; it never invents items.171Have the model say who goes together with a label (`groupName`), Combine on172`nodes.<ai>.groupName` with `identity: "firstMember"`, and read the group's173name and id from `item.key` and `item.id`: they come from its first member, not174from the label.175176`combine` turns many items into one. Mode `list` gives `{ items, count,177truncated, totalAvailable }`, and with nothing to combine it still gives one item178with `count: 0`, so a quiet day can say so. Rules in `filter` and `switch` are179`{ left: "<path>", op, right }` with `op` one of `equals`, `notEquals`,180`contains`, `startsWith`, `isEmpty`, `isTrue`, `inList`, `gt`, `lt`, `between`,181`olderThan`, `pastDue`; `isEmpty`, `isTrue` and `pastDue` take no `right`.182183## Worked example: a weekday digest184185"Every weekday at 8, send the team a summary of what changed in the repo."186Trigger, a window Source over commits, one list, one AI-written Slack post, End.187This is the shipped story graph (`server/workflow/stories/03-morning-digest`),188with the repo and channel in `settings.extras`, and a `label` on each node:189190```json191{192 "nodes": [193 {"id": "weekdays8", "name": "weekdays8", "label": "Every weekday at 8", "position": {"x": 0, "y": 0}, "kind": "trigger", "settings": {"schedule": {"weekdays": {"at": "08:00"}}, "timezone": "America/New_York"}},194 {"id": "commits", "name": "commits", "label": "Commits since last digest", "position": {"x": 344, "y": 0}, "kind": "source", "settings": {"source": "window", "operation": "github.listCommits", "args": {"repo": {"mode": "path", "path": "settings.extras.repository"}}, "maxItems": 100}},195 {"id": "digest", "name": "digest", "label": "Build the digest", "position": {"x": 688, "y": 0}, "kind": "combine", "settings": {"mode": "list"}},196 {"id": "post", "name": "post", "label": "Post to the team channel", "position": {"x": 1032, "y": 0}, "kind": "action", "settings": {"operation": "slack.postMessage", "args": {"to": {"mode": "path", "path": "settings.extras.digestChannel"}, "text": {"mode": "ai", "instruction": "Write the digest from the commit list: a one-line TL;DR, then at most 5 bullets grouped by area that name notable authors and link the commits. When count is 0, write exactly: No commits since the last digest. When truncated is true, say how many of totalAvailable commits are shown."}}}},197 {"id": "done", "name": "done", "label": "Done", "position": {"x": 1376, "y": 0}, "kind": "end", "settings": {"outcome": "done"}}198 ],199 "edges": [200 {"id": "e1", "from": {"node": "weekdays8", "port": "out"}, "to": {"node": "commits"}},201 {"id": "e2", "from": {"node": "commits", "port": "out"}, "to": {"node": "digest"}},202 {"id": "e3", "from": {"node": "digest", "port": "out"}, "to": {"node": "post"}},203 {"id": "e4", "from": {"node": "post", "port": "out"}, "to": {"node": "done"}}204 ],205 "settings": {"extras": {"repository": "acme/web", "digestChannel": "C0123ABCD"}}206}207```208209**New pull requests, not commits.** No catalog operation lists open pull210requests; the GitHub poller does. Replace `commits` with211`{"source": "inbox-poll", "poller": "github", "takeLimit": 10, "filter": {"scopes": ["acme/web"]}}`212(at most 10 per run; the poller also brings issues), and put a `filter` on213`item.kind` `equals` `pull_request` before `digest`, with both its ports wired214(`otherwise` to a `dismissed` End with a `reason`). Tell the user about the21510-per-run limit.216217## An endpoint no step covers218219When no operation reads what the user wants, add a Lookup with220`<provider>.apiRequest` rather than saying it cannot be done. It sends a221read-only GET to any path of a connected provider: slack, github, hubspot,222gong, pylon, stripe, posthog, bigquery, jira, notion or sentry. Read it with223`operationIds` first: its description and field notes are the reference.224225- **Find the path before you write it.** `provider-api-catalog` with the226 provider gives its base URL, example paths and docs links; `provider-api-docs`227 with a `url` reads the endpoint's page. `path` sits below that base URL228 (Slack `conversations.history`, Stripe `customers`), with no host. PostHog,229 BigQuery and Sentry keep `{projectId}` or `{orgSlug}` in a path for the230 connection to fill. Parameters go in `query`, never after a `?`.231- **The answer is the provider's own JSON** at `nodes.<name>`. Its fields are232 not checked at save, so read the real shape after a dry run, from the item's233 summary in `get-workflow-node-audit`, before binding a later step to a path in234 it. `includeStatus: true` makes it `{status, headers, body}`. With `pagination`235 (the next cursor must be a plain field in the body; at most 5 pages) it is236 `{pagesRead, moreAvailable, nextCursor, items}`: say when `moreAvailable`.237- **A cut answer says so first.** Past about 33,000 characters it leads with238 `truncated: true` and `cuts`: each list shortened (`kept` of `of`), text239 clipped, or key left out, by path. A list becomes `{truncated, count,240 totalAvailable, cuts, value}`, so `nodes.x[0]` stops reading and241 `nodes.x.value[0]` starts: test `nodes.x.truncated` before relying on a count,242 and tell the user how many came back of how many. The step carries243 `outputsTruncated`. Fewer or narrower results (`per_page`, a filter) are the244 fix, not a bigger read.245- **For a list or big objects, set `fieldsToKeep`** (Fields to keep): dotted246 paths such as `["number", "title", "user.login"]`. The step passes on only247 those, cut before any size limit, so three 25 KB pull requests stay whole.248 A path inside a list applies to every entry, and `user` keeps all of `user`.249 Paths that matched nothing come back in `nodes.<name>.fieldsMissing` (a list250 then reads `nodes.<name>.value[0]`): fix the typo and tell the user. With251 `pagination` it trims each entry; with `includeStatus` only the `body`. An252 answer that says the provider did not do it (Slack `ok: false`, BigQuery253 `jobComplete: false`, an `errors` list) always keeps those keys, so read254 `nodes.<name>.ok` and `.error` before trusting an empty result.255- **One step hands on about 64 KB in all**, counting every item it emits and256 every earlier answer still attached to each (`nodes.<step>`). Three big reads257 in a row, or one read over several items, fail as `output_over_cap` naming the258 step; the cap is not raised. Set `fieldsToKeep`, narrow the request, or split259 the work.260- **A curated lookup hands on a bounded answer.** A Stripe billing lookup keeps261 the customer, subscription and invoice facts (about 4,000 characters), a Gong262 transcript the words of its opening, about 15 minutes (18,000), Sentry events263 10,000, a thread read 6,500 and the open reports their title, text, thread and264 Builder branch, about 13 of them (10,000). A cut answer leads with265 `truncated: true` and `cuts` (the thread and the open reports instead say266 `truncated`, `nextOldest` and `nextCursor`): say how much came back, never267 that you read all of it.268- **Never from a model.** `path` may be typed, a setting, an item field or an269 earlier lookup, not AI-written (`model_written_target`), and the step is never270 an AI step's tool (`unknown_tool`). Headers never carry credentials: the271 connection signs the request.272- **Limits to tell the user:** GET only, JSON only, no body, no POST searches,273 no page-number or `Link` paging. A refused request fails the item as274 `lookup_failed` with the reason in brackets, such as `unsafe_path_value`,275 `full_url_refused`, `header_denied`, `invalid_fields_to_keep`; a 404 is not276 retried.277- **What the app shows.** Test step on an API request shows the whole response on278 screen for the person and keeps none of it; a run, and so anything you read back279 with `get-workflow-node-audit`, keeps only a short summary of the answer.280- **Test it on its own.** A Lookup that reads no `item.*` or `nodes.*` runs281 once in a `mode: "test"` run with no `sampleItemIds`. Any other step with none282 pinned is refused as `test_needs_items`, nothing started: pin items from a dry283 run, or run the whole workflow first.284285## Slack channels286287Slack needs a channel id such as `C0123ABCD`, found in Slack under the288channel's details, at the bottom. Ask for it in the same message as the time289zone. Do not resolve a name with `provider-api-request`: it needs a workspace290connection and ends the turn in a connect request. `list-messaging-channels`291lists the app's messaging integrations, not Slack channels. A Source's channel292scope that is not an id is rejected at save. A post's `to` is not checked at293save and a dry run never posts, so a name there only fails on the first live294run.295296A Slack report's `item.author` is a user id (`U0123ABCD`), never an email. A297step that needs the person's address (Builder's `userEmail`) reads it first with298a Lookup `slack.getUserEmail`: `userId` is `item.author`, and `fallbackEmail`299is `settings.triageOwnerEmail`. Read `nodes.<lookup>.email`; it is always an300address, and `emailSource` says `slack` or `fallback`. The fallback is used only301when Slack says the person has no email. A lookup that failed (a connection302without the `users:read.email` scope, an unknown id, Slack down) fails the303step with a typed code and never falls back, because the work would be304attributed to the wrong person. A `userId` that is not a Slack user id (an email,305a bot id) fails the step with `slack_user_invalid`.306307## Connecting308309Connections are per provider, from `connections` in a save or310`get-factory-workflow` result, or from `describe-workflow-node-catalog`.311312- **`not connected`:** call `request-workflow-connection` with the provider.313 For Slack, GitHub, Sentry, HubSpot, Jira, Notion and BigQuery the chat shows314 a connect card and the turn waits for the user. Ask for one provider per315 turn. When the user says it is connected, call `get-factory-workflow` again316 to refresh `connections` and go on.317- **Gong, Pylon, Stripe, PostHog, Builder, email:** the call returns318 `connected: false` with `where` and `keys`. Tell the user exactly that, then319 check again when they say it is done.320- **`unknown`:** the check itself failed; `detail` says why. Say so; do not call321 it connected or not connected, and check again.322- **`unreadable`:** a key or sign-in is saved (a Slack or Sentry token, a Sentry323 organization slug, a Jira token, a Builder sign-in) but this deployment cannot324 decrypt it, usually because the database came from another deployment or its325 encryption key changed; `detail` names the key. A person must save it again326 under Keys in Settings, or run with the key that saved it. Do not call a327 connect card for it, do not retry it, and do not call it not connected.328 `request-workflow-connection` and `set-factory-workflow-enabled` refuse it329 with `connection_unreadable`, and a step that hits it fails `app_secret_unreadable`.330- **Sentry also needs `SENTRY_ORG_SLUG`:** a token alone reads `not connected`,331 with the slug named in `detail`.332- `set-factory-workflow-enabled` refuses with `connection_required` until every333 provider is connected. A step that fails `credential_missing` in a dry run334 means the same thing: connect it, then dry run again.335336## A failed step337338By default an item that fails at a step ends for a person (Needs you) and339nothing is posted, so nobody learns a loop is stuck. Set `settings.onError` to340`"route"` on a `lookup`, `action`, `ai` or `agent` node and the step gets an341extra `error` port: the failed item leaves by it, with the failure at342`item.error` (`code`, `message`, `node` the step's name, `outcomeUnknown`), and343is not counted as failed. Absent or `"stop"` is the old behavior.344345- **Wire the `error` port, or the save fails** with `port_leads_nowhere` at that346 node and port. Typically `error` goes to an Action that posts to the owner (a347 Slack post whose text reads `{{ item.error.code }}` and348 `{{ item.error.message }}`), then an End with `needsManual` and a `reason`349 that reads `item.error` too, so Needs you shows the real failure.350- **The failed step has no output on that path.** Read `item.*`, `item.error.*`351 and steps before it; `nodes.<failed step>` does not exist there.352- **Retries still come first.** A failure worth another try (a timeout, an AI353 answer outside its fields) is retried as before and leaves by `error` only354 when the attempts are spent, so a flaky minute sends no alert. A failure no355 retry fixes (no credential) leaves at once. A dry run parks nothing, so it356 routes at once and its Action only says what it would send.357- **A write never retries, routed or not.** `outcomeUnknown: true` (code358 `effect_needs_check`) means the write may have happened. It is still handed to359 a person and its receipt stays open, so the alert is information and never360 makes it read as handled: end that path with `needsManual`, never `done`.361- **A dry run is not clean proof for that step.** The step reads as succeeded362 and the run's `counts.errorRouted` (and the step's `routedErrors` and363 `firstRoutedError` fields) say how many items took the error port and why:364 above zero, read the reason and fix the cause before enabling.365- **Not covered:** a step that fails as a whole (a result over the step cap, a366 graph the engine cannot run) still stops the run, and a Source, Filter,367 Switch, Combine, Split, Wait or End has no `onError`.368369The shipped builder-to-merge story routes the AI judge's failures this way.370371## Dry run loop372373`run-factory-workflow` `mode: "dry"` reads real data and runs the AI, but every374write only reports what it would do. With `waitSeconds: 25` it returns:375376- `status: "finished"`: `workflowRunId`, `runStatus`, `clean`, `counts`377 (`taken`, `done`, `itemFailures`, ...), `failedSteps` (node, code, message)378 and `needsConnection` (providers to connect).379- `status: "still_running"` with `runId` and `workflowRunId`: read it with380 `get-factory-workflow-run` (it takes either id), then again. Reads are not381 deduplicated.382- `status: "skipped"`, `reason: "already_running"`: another run of this383 workflow was going, so this one never started and nothing ran. Read384 `activeRunId` with `get-factory-workflow-run`, wait for it to end, then run385 again.386- `status: "not_started"`: the scheduler ended the run before the workflow387 began; `errorCode` and `message` say why.388389Loop: run, read, fix, run again, until `clean` is true. A failed step's code390says what to fix: `expression_failed` is a path or value (read the step with391`get-factory-workflow-run`), `credential_missing` is a connection,392`graph_invalid` is the graph. `itemFailures` above zero with a clean-looking393step: `get-workflow-node-audit` for the node lists the item errors. Every fix394is a new save, so the next dry run is of the new version. Never use395`mode: "live"` to test: it sends real messages, only runs for an enabled396workflow, and stops for the user's approval like enabling does.397398## When a run fails or behaves oddly399400Call `get-workflow-diagnostics` (`factoryId`, optional `workflowId`, `runId`,401`sinceHours`, default 24, max 168) before guessing. It returns one JSON object402under 30 KB: build and deploy facts, whether recurring jobs are on, the403scheduler's heartbeat age, each provider's connection status, the workflow's404shape and job health, the last 10 runs with their failed steps, waiting items405and how many are overdue, writes that began and never confirmed, and the recent406tripwires with counts by code. `truncated` lists what was cut and `unavailable`407what could not be read.408409- **A tripwire** is one typed row for something unexpected at a risky boundary410 (a provider answering in a new shape, a wait that woke late, a refused or411 slow tool call): ids, status codes, durations, counts and the shape of data,412 never raw values. It changes nothing; never branch on whether one exists.413- **Read in this order:** `unavailable`, then `scheduler` and414 `environment.recurringJobs` (nothing runs when those are off), `connections`,415 `runs[].failedSteps`, then `tripwires.counts` and `tripwires.recent`.416- **Tell the user** they can paste what "Copy diagnostics" gives them (the417 workflow's More actions menu, or Settings, Scheduler health): the same418 object, with no tokens, emails or URL query strings, so never ask for those.419- Codes are a closed list in `server/tripwire/types.ts`. Never put customer420 text, a message body or a credential into a tripwire's `details`.421422## An item that needs a person423424`list-workflow-items` with `needsYou: true` finds them. Once the cause is fixed,425`requeue-factory-item` sends one back to its workflow (it stops for the user's426approval: say which item and what it may send first); `dismiss-factory-item`427closes it and sends nothing. Both take `factoryId` and `itemId`, and a repeat428changes nothing.429430## Builder: start, then check431432Builder ignores the branch name a start asks for and keeps its own. `builder.start`433returns it as `externalRef` (also `branchName`). A start found already done434supplies `externalRef`, `url`, `status` and `projectId` and not `accepted` or435`branchName`, because a receipt keeps only the fields that name a thing: read436`externalRef`.437438- **Bind `userEmail` to a reporter's email, never to `item.author`.** On a Slack439 report `item.author` is a user id, and Builder looks `userEmail` up against its440 Space members. Put a `slack.getUserEmail` Lookup before the start (see Slack441 channels) and bind `nodes.<lookup>.email`. For a group the start is for its442 first report's reporter.443- **Bind `reports` on every `builder.start`** (`item.reports` for a group, `item.id` for one item). Factory reads each report from its inbox and adds its headline, author, link and text after the task your instruction writes, so never have the model copy the report; a start with no report to read is refused.444- **Never compare the name you asked for with the one Builder returned.** A445 check that `externalRef` equals the asked name turns away every real start.446 To test that a start gave a task, test that `externalRef` is not empty.447448- **Bind every later Builder step to the start's receipt.** `builder.check` and449 `builder.followUp` take `branchName` as450 `{ "mode": "path", "path": "nodes.<start step>.externalRef" }`. The name you451 asked for is not the one Builder keeps, so a check on it reads `not_found`.452- **Route on `state`, `hasPullRequest`, `prNumber` and `prUrl`.** There is no453 `status` and no `pullRequest.number`; a save that reads a name `builder.check`454 does not return is refused with the real names listed. Test `hasPullRequest`,455 never `prNumber > 0`: `prNumber` is null until a pull request exists.456- **`state` is `working`, `stuck`, `completed`, `failed` or `not_found`.**457 `completed` means Builder is idle and a pull request exists, whether open,458 closed or draft; read `prStatus` before treating it as done. `failed` is a real failure (the branch459 was archived or deleted without a merge). `not_found` is not a failure: Builder460 has no active branch under that name, which can mean the task finished and was461 archived, the name is not the one Builder returned, or the task was never462 created. Wait and check again, or hand it to a person; do not report it as463 Builder failing.464- **Put `reason` in any message that says what Builder is**, such as465 `Builder is {{ nodes.check.state }} ({{ nodes.check.reason }})`, so a person466 can tell `branch_not_found` from `branch_archived`.467- **A start is deduplicated by its receipt, not by the branch name.** The same468 item at the same step finds its done receipt and does not call Builder again,469 through a requeue, a new run and a workflow saved again. For a grouped start470 the item is the group, and its id comes from the group's first report (a471 Combine `groupBy` with `identity: "firstMember"`), never from a label a model472 wrote, so a requeued report is the same group however the model names it. A473 report that comes back in a different group has a different member list and so474 a different receipt. Builder renames branches, so the lookup by the asked name475 never finds one. Ask for a name unique to the task. `builder.followUp`476 succeeding means Builder queued the message, not that it acted on it.477478## Merging a pull request479480`github.mergePullRequest` merges only what the merge gate clears, and re-runs481the gate itself, so a graph that skips `factory.mergeGate` still cannot merge a482held pull request. The gate wants: a Builder account (`builderio-bot` or483`builder-io-integration[bot]`, no other name) opened it from a branch in the484repository, aimed at the default branch; every check on the head commit green;485no unresolved review thread and no review asking for changes; an approval of the486current head commit from a person who is an owner, member or collaborator, not487the author and not a bot or Builder account (a push after the approval needs a488new one); a small diff clear of the never-automate paths; a test change beside489any code change (docs, changesets, lockfiles, package manifests and config need490none); and a `### Verified` section in the description with text, a screenshot491or a recording. A held pull request goes to Needs you, and the Slack notice492carries every reason. `get-factory-merge-gate` returns them as `reasonCodes` and493`reasonText`; `approval_required` comes with `approvals` counts (`seen`,494`qualifying`, `byAuthor`, `fromBots`, `fromNonCollaborators`, `stale`), and495`no_regression_test` and `no_verification_evidence` are the two proof rules.496`github.readPullRequest` returns `verification` (`present`, `hasMedia` and a497short `excerpt` of the Verified section, never the description itself) for a498graph that wants to route on it. The shipped builder-to-merge story asks an AI499step, `judge`, after the gate and before the merge whether that excerpt500plausibly shows the fix: `verified` goes on to the merge, `unsure` (or a judge501that fails, which tells the triage owner the typed failure) holds the pull request for a person, and it never approves. Explain502a hold in those words. Never approve or merge for the user: an approval is a person's, and503`requeue-factory-item` sends the item back once it is given.504505## Jira and Sentry steps506507The issue key (`PROJ-123`) and the Sentry issue id (digits) come from an item508field or a setting, never an AI step. A bad one fails the item before the509provider is called. Each write is sent once; `_outcome_unknown` means check.510511- `jira.getIssue` (Lookup): status, `statusCategory`, resolution, assignee,512 labels and `transitionNames`, capped, with `truncated` when cut.513- `jira.listTransitions` (Lookup): what the issue can take now, each with `id`,514 `name` and `toStatus`.515- `jira.transitionIssue` (Action): moves it by transition name or id, read first516 against Jira's own list. An unknown or ambiguous name is refused, never517 guessed. Naming the status it is already in succeeds with `alreadyInState`.518- `sentry.resolveIssue` (Action): `resolution` is `resolved` or519 `resolvedInNextRelease`. Sentry's answer must confirm it.520- `sentry.assignIssue` (Action): `assigneeKind` `user` (`assignee` is an email),521 `team` (a lowercase slug, read first; unknown is refused) or `nobody`.522523## Labels and reactions524525Writes run only on an `action` step, never as a Lookup, a Source or an AI526tool. A dry run and a test of the step say what they would send and send nothing.527Factory has no step that comments on a GitHub issue: findings go to Slack.528529- `github.addLabels`: `repo`, `number` and `labels`, a list of 1 to 5 names of530 up to 50 characters, no comma. A label already there stays, so a repeat531 changes nothing. Gives `labels`, all the item has now.532- `github.removeLabel`: `repo`, `number` and `label`. An item without it533 succeeds with `alreadyAbsent: true`.534- `slack.addReaction`: `channel` (an id), `ts` (the message's time; for a report535 that starts a thread, `item.thread.threadTs`) and `name`, an emoji without536 colons, such as `eyes`. A repeat succeeds with `alreadyReacted: true`.537538- **Only the factory's own repository.** A label step refuses any other539 `repo`, and a factory with no repository set, with `repository_not_allowed`,540 as the merge step does; set the repository in the factory before using one.541- **A model writes none of these fields.** `repo`, `number`, `labels`, `label`,542 `channel` and `ts` say where the write lands (a label can start automation in543 the repository): type them, or read a setting, an item field or a lookup,544 never an AI step's answer (`model_written_target`).545- **A bad value is refused on the first live run, not in a dry run.** A dry run546 never calls the step, so check the limits above yourself: a refusal is typed547 (`github_label_invalid`, `github_repository_invalid`, `repository_not_allowed`,548 `slack_channel_invalid`, `slack_reaction_invalid`) and sends nothing.549- **Read a failure by its code.** `github_access_denied` is a connection with no550 write access (Slack `slack_access_denied`, `missing_scope`: the app needs551 `reactions:write`); connect again with the right access. `github_not_found`552 and `slack_not_found` wrote nothing. A code ending `_outcome_unknown` may have553 written: the item goes to Needs you and nothing sends it again, so check the554 issue or message first.555- **The loop's own reaction is not a person's.** A Source's `claimReaction`, a556 reply Wait's `ackReaction` and `slack.readThread` leave out the app's own557 bot, so reacting `eyes` to a report never marks it claimed. `slack.readThread`558 lists the bot's reactions apart, under `ownReactions`, and `reactions` holds559 only everyone else's.560561## Other tools562563`list-factory-workflows`, `get-factory-workflow` (`version`, or `nodeIds` for564a graph too large to read at once), `list-factory-workflow-versions`,565`restore-factory-workflow-version`, `rename-factory-workflow` (the workflow's566own name in the list and toolbar; a save never renames, and the version, graph567and on/off state stay), `delete-factory-workflow` (stops for the568user's approval: name the workflow and what goes with it first),569`list-factory-workflow-runs`, `get-factory-workflow-run`,570`get-workflow-node-audit`, `get-workflow-node-data` (the item fields a node571took in and put out in a run; not lookup or action responses or AI answers).572To show something, `navigate` with573`/factory?factoryId=<id>&workflow=<id>` plus `node=`, `edge=`, `run=` or574`version=`.575576- A person's unsaved edits in the editor autosave as a private draft, and `get-factory-workflow` returns `hasDraft` (true when this person has one). When it is true, say so before saving a new version, because the editor will then offer Keep my changes or Load latest; the agent never reads or writes drafts.