Skip to main content
Agent skill

Workflow Builder

Build a bot or agent that runs on a schedule or event (cron, webhook, twice a day, daily digest, monitor, triage); also multi-agent Reliant workflows. Use to create, edit, test or debug any workflow.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/workflow-builder && curl -fsSL 'https://raw.githubusercontent.com/reliant-labs/reliant/main/internal/skills/catalog/builtin/workflow-builder/SKILL.md' -o ~/.claude/skills/workflow-builder/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Workflow Builder when an AI agent needs a reusable SKILL.md workflow for this job: Build a bot or agent that runs on a schedule or event (cron, webhook, twice a day, daily digest, monitor, triage); also multi-agent Reliant workflows. Use to create, edit, test or debug any workflow.

When not to use it

Skip Workflow Builder when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/workflow-builder && curl -fsSL 'https://raw.githubusercontent.com/reliant-labs/reliant/main/internal/skills/catalog/builtin/workflow-builder/SKILL.md' -o ~/.claude/skills/workflow-builder/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/workflow-builder/SKILL.md. For a shared project, commit the folder at .claude/skills/workflow-builder/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Workflow Builder skill for this task: Building an agent or automation that runs on its own: on a schedule ("every morning", "twice a day", cron), on a webhook or an app event — a bot, monitor, digest or triage job, even when it sounds like "just a script". Confirm any required inputs or files before making changes.

What supports this recommendation?

87/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
100/100
Practical detail
100/100
Source evidence
58/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Workflow Builder

You build Reliant workflows. Your goal: create working workflows that solve the user's problem.

Threading, context, loops, parallelization, inputs, prompts, error handling and composition have their own do's-and-don'ts reference: `skill(action="load", path="workflow-builder/design-patterns")`. Load it before designing a workflow's control flow.

## When to use

- Building an agent or automation that runs on its own: on a schedule ("every morning", "twice a day", cron), on a webhook or an app event — a bot, monitor, digest or triage job, even when it sounds like "just a script" - Creating a new Reliant workflow from scratch - Editing or extending an existing workflow - Debugging workflow execution issues - Writing scenario tests for workflows - Understanding workflow patterns and best practices

## Approach

Every workflow tool that targets an existing workflow (`get_workflow`, `edit_workflow`, `write_workflow`, and the scenario tools) requires an explicit `id` — a UUID, slug, or name. Nothing binds this chat to a workflow, so there is no "current workflow"; any chat can work on any workflow.

Starting from scratch? Call `create_workflow` first — it returns the new draft's `id`, `name`, and `slug`. Pass that `id` to every subsequent call. Omit both `name` and `content` to get a random name and the default agent template; pass `content` with complete workflow YAML to start from a specific design.

Editing an existing workflow? Find it with `list_workflows` and pass its id or slug. If the user's message names a workflow (e.g. "Workflow `swift-fox-a1b2`: ..."), use that as the `id`.

Follow this process:

1. **Setup** — New workflow: call `create_workflow`. Existing workflow: call `get_workflow` with its `id` to see current content. 2. **Understand** — Ask clarifying questions about the user's goal 3. **Learn** — Use `list_workflows` to see examples and patterns, `list_presets`/`get_preset` to see what agent presets exist before inventing a system prompt from scratch. Calling an external service? `search_integrations` finds the action ref and `get_integration_schema` its params before you write the node 4. **Explore** — Read the user's codebase (test commands, code patterns). Note: references to "workflows" and "nodes" in user code are unlikely to be Reliant-specific. 5. **Build** — Use `edit_workflow` for small changes, `write_workflow` for larger rewrites 6. **Test** — Create and run scenarios (aim for 3+ covering positive, negative, and edge cases). Try to break your workflow. It's frustrating for users to run a workflow for an hour and hit a bug at the end—scenarios catch this early.

Working in a chat that isn't running this preset? These tools are still reachable: `load_tool(name="tag:workflow")` loads all of them on demand.

## Key concepts

### Workflows are DAGs

Every workflow must be a directed acyclic graph. You cannot create cycles in the graph structure. Use **loop nodes** (with `while` conditions) for iterative behavior.

### CEL expressions

Two syntax modes:

- **`condition` / `while` fields**: Pure CEL — no `{{}}` wrapping ```yaml condition: "nodes.llm.stop_reason == 'tool_use'" while: "outputs.stop_reason in ['tool_use', 'incomplete', 'truncated', 'interrupted'] && iter.iteration < 50" ``` - **All other fields**: Template interpolation with `{{}}` ```yaml model: "{{inputs.model}}" system_prompt: "You are helping with {{inputs.task}}" ```

Always use `has()` or safe navigation (`object.?field`) before accessing optional fields.

**Template rules.** A `{{ }}` is read as CEL, so a brace inside a string literal is data (`{{ x.startsWith('{') }}` works) and a newline inside it is whitespace (a folded `>-` scalar is fine). A `{{` that never closes, an empty `{{ }}` and an expression that does not parse are validation errors with the field path and line/column, never literal text; write a literal `{{` as `{{ '{{' }}`. Raw-CEL fields (`condition`, `while`, a trigger `filter`) take no `{{ }}`. Inside an inline `type: workflow` body, templates are evaluated in the BODY's scope when it runs (its own `inputs` and `nodes`), not the parent's.

**Deterministic logic belongs in the workflow, not a script.** Use a `type: compute` node (below) for labels, size buckets, lease expiry, id validation and parsing a node's JSON stdout. Expressions have Strings, Lists, Sets, Math, Encoders, Bindings, Regex, optional types, timestamps and durations, and `json.decode(s)` (tolerant: an optional, `.?status.orValue('error')`) beside the strict `parseJson(s)`. Evaluation is cost-bounded (a runaway expression fails with `cost limit exceeded`). The CEL reference has a table of worked helper expressions. **Test an expression with `cel_eval` before writing it into a workflow.**

### Compute node

`type: compute` computes named outputs from CEL in the workflow: no model, no shell, no worker, no mock needed in a scenario. `outputs:` maps a name to a value; a value that is exactly one `{{ }}` keeps its type, text around it makes a string, a non-string is a literal. Read them as `nodes.<id>.<name>` (validation checks the names; values are dyn, so compare a boolean output in a `condition`: `nodes.facts.ready == true`). Outputs cannot read each other: chain two compute nodes. A failing expression fails the node.

```yaml - id: facts type: compute outputs: size: "{{ inputs.adds + inputs.dels < 60 ? 'size:S' : 'size:M' }}" ready: "{{ 'agent:ready' in inputs.labels }}" status: "{{ json.decode(nodes.start.stdout).?status.orValue('error') }}" ```

### Publishing a branch

`type: git_publish` commits a worktree's changes and pushes them to a feature branch with no shell ever holding a credential. Pair it with `credentials: none` on the editing shell.

```yaml - id: publish type: git_publish args: worktree: "{{ nodes.wt.path }}" repo: "{{ inputs.repo }}" # owner/name branch: "autopilot/issue-{{ inputs.issue }}" # or pr_head_of: "{{ inputs.pr }}" allow: ["autopilot/*"] # optional message: "{{ nodes.edit.commit_message }}" ```

Refused (the node completes with `refused: true` and a `refusal`, it does not fail): the default branch, protected branches, `main`, `master`, `release/*`, names that are not plain branches, branches outside `allow`, a pull request head in a fork. Never forces unless `force_with_lease` (below) names a sha: a diverged remote is refused. No changes means `pushed: false` and no error. Outputs: `pushed`, `sha`, `branch`, `base_sha`, `files_changed`, `insertions`, `deletions`, `refused`, `refusal`, `lease_refused`, `remote_sha`, `lease_unsupported`. Route on them: `condition: nodes.publish.pushed == true`. The push is recorded in the write ledger with its sha, so its events carry `trigger.origin`. In a scenario, mock the node's outputs like any activity.

To replace a branch you checked out (a fix that merged or rebased a pull request head), name the commit you built on in `force_with_lease`: the full sha the remote branch must still be at. The push may then be a non-fast-forward, as `git push --force-with-lease=refs/heads/<branch>:<sha>`: one compare-and-swap on the remote. If someone pushed meanwhile (or the branch is gone) nothing is pushed and the node is refused with `lease_refused: true`, `remote_sha` holding the branch's actual head and both commits named in `refusal`; it is not retried. Only a sha is accepted, never `true`; every other refusal above still applies. The machine's daemon must be new enough to enforce the lease: an older one is refused with `lease_unsupported: true` before anything is committed or pushed (upgrade its reliant).

```yaml pr_head_of: "{{ inputs.pr }}" force_with_lease: "{{ nodes.pr.head_sha }}" # the head the worktree was made from ```

### Shells without credentials

`credentials: none` removes GitHub, git, ssh and cloud credentials from a command's environment: no `GH_TOKEN`/`GITHUB_TOKEN`, no ssh agent, no cloud variables, no kubeconfig, git's credential helpers reset, `GIT_TERMINAL_PROMPT=0`, an empty `GH_CONFIG_DIR`. A `git push` or `gh pr merge` from it fails to authenticate at once and never prompts. Set it for an agent's shell with `tools_config.tools.shell` (bound, so the model is never shown it) and on a `run` node with `credentials: none`.

```yaml tools_config: tools: shell: {credentials: none} ```

On Linux (every Reliant cloud machine) the command also runs in a sandbox where the daemon's credential files are absent (`~/.reliant/daemon.json`, `~/.config/forge`, `~/.git-credentials`, `~/.ssh`, `~/.config/gh`, kubeconfig and cloud files, the container engine's socket), sees only its own processes, and has no capabilities. It shares the network and can write its working directory, and on macOS and Windows only the environment is scrubbed. Never tell an agent to look elsewhere for a token; publish with a `git_publish` node.

### Threading

Modes: `inherit` (default), `new`, `fork`

- **inherit**: Reuse parent thread (default) - **new**: Create a fresh thread - **fork**: Copy parent thread into a new one

Key rules: - Use `memo` in loops to reuse the same thread across iterations - Use `inject` to prepend a message when entering a sub-workflow - **Never** run parallel agents on the same thread simultaneously

### Edge routing

- Multiple `cases` on one edge = exactly 1 executes (first match wins) - All cases require a `condition` — use `default` for the fallback - For parallelism: create multiple edges from the same source node, OR use `default: [node-a, node-b]`

## Syntactic sugar

These shorthands compile to standard nodes/edges at parse time. They are **not** in the proto — purely YAML convenience.

### `sequence:` sugar

A top-level workflow field (alongside `name:`, `nodes:`, `edges:`) that replaces the combination of `entry:`, `nodes:`, and sequential `edges:` for linear chains.

Rules: - Cannot coexist with `entry:` (it implies entry from the first node) - CAN coexist with `nodes:` and `edges:` for mixed patterns (e.g., linear main flow with extra branches) - Compiles to standard `entry:` + `nodes:` + `edges:` at parse time

Before (explicit): ```yaml entry: [research] nodes: - id: research type: workflow ref: builtin://agent - id: implement type: workflow ref: builtin://agent - id: review type: workflow ref: builtin://structured-agent edges: - from: research default: implement - from: implement default: review ```

After (sugar): ```yaml sequence: - id: research type: workflow ref: builtin://agent - id: implement type: workflow ref: builtin://agent - id: review type: workflow ref: builtin://structured-agent ```

### `type: parallel` sugar

A node type used inside `nodes:` that desugars into branch nodes + a join node + fan-out/fan-in edges.

Rules: - Must have `id:` and `branches:` fields - `branches:` is a list of regular node definitions - The parallel node's `id` becomes the join node's id (so downstream edges referencing it still work) - Join uses `condition: all` (all branches must complete) - Incoming edges targeting the parallel node get rewritten to fan-out to all branches

Before (explicit): ```yaml nodes: - id: research type: workflow ref: builtin://agent - id: design type: workflow ref: builtin://agent - id: explore type: join condition: all edges: - from: trigger default: [research, design] - from: research default: explore - from: design default: explore ```

After (sugar): ```yaml nodes: - id: explore type: parallel branches: - id: research type: workflow ref: builtin://agent - id: design type: workflow ref: builtin://agent edges: - from: trigger default: explore ```

## Triggers: when a workflow runs

A workflow says WHEN it runs in a top-level `triggers:` list. Declaring a trigger fires nothing. Use create_trigger_activation, update_trigger_activation, enable_trigger or pause_trigger when asked to manage an activation. The owner's automation-approvals setting (Settings > Automations) decides which changes raise an approval card: by default a new activation, or a change that widens its power (a new connection or scope, a different acting identity, a new machine, new secrets, a production deploy step); other edits and resumes apply and are recorded. Pausing never needs a card; delete_trigger always does, because deleting cannot be undone. An unattended run reaches these tools only when its step names them, and a change that needs a card is refused there. Do not bypass approval through the CLI, HTTP or a script. To change several activations, call the tools together in ONE turn: every card the turn needs is raised at once as one batch, which the owner approves in one click (or one by one), instead of one card per turn. Enabling says AS WHOM and WHERE: their project, the machine whose tools the runs use, and for an integration trigger which of their connected accounts it listens through. One declaration can have many activations (one per user or project). When the connection it needs does not exist yet, call propose_connection (provider, scope, reason): the owner connects it in Reliant's connection dialog from an approval card, and you get back only its status and connection id, never the credential.

```yaml name: triage-new-issues inputs: repos: {type: github.repository, multi: true, required: true, min_items: 1} # typed by the integration; the user picks them when enabling issue_number: {type: integer, default: 0} # required inputs must be mapped by every trigger, or set by the user when enabling triggers: - name: new-issue # unique within the workflow: lowercase, digits, - and _ description: A new issue integration: # exactly ONE source: schedule | webhook | integration | workflow_event integration: github events: [issues.opened] # "issues.*" or "*" also match match: {repository: {input: repos}} # scope by an input: only the repositories the user picked. A plain value (repository: acme/app) must equal the attribute filter: "!('wontfix' in trigger.payload.data.issue.labels)" inputs: issue_number: "{{ trigger.payload.data.issue.number }}" prompt: "Triage issue #{{ trigger.payload.data.issue.number }}: label it, ask for a repro if one is missing." - name: nightly schedule: {cron: ["0 9 * * 1-5"], timezone: America/New_York} # 5-field cron, or interval: 1h - name: deploy-hook webhook: {} # POST <api>/hooks/<trigger id>; add hmac: {...} to verify signatures - name: alertmanager webhook: {source: alerting} # hosted: Enable connects the org's alerts, no token to copy; self-hosted: a plain webhook dedupe_key: "{{ trigger.payload.body.groupKey }}:{{ trigger.payload.body.status }}" # see below dedupe_window: 4h - name: after-review-fails workflow_event: {workflows: [code-review], outcomes: [failed]} # finished | failed | blocked entry: [triage] nodes: ... ```

**`filter`** is a raw CEL bool (no `{{ }}`) and **`inputs`** values are `{{ }}` templates. Both read ONLY `trigger` — the run, its inputs and nodes do not exist yet. A schedule has no event, so no filter. An event whose payload a filter or input cannot read is recorded as a FAILED firing: guard optional fields with `has()` or a ternary. Each `inputs` key must be a declared workflow input; a value set there wins over the user's params (enabling drops a param it would override).

**`prompt`** is the message every run the trigger starts begins from, a `{{ }}` template over `trigger` like `inputs`. Write it so enabling needs no prompt: the prompt the user writes when enabling overrides it, and with neither, enabling is refused. The event is still attached after it as untrusted data.

**`trigger.activation`** is the activation the event fires for, readable in a `filter`, `inputs`, `prompt` and `dedupe_key` (not in nodes, which read `inputs`): `trigger.activation.params.<input>`, `.id`, `.owner.user_id`, and `.owner.github_id` (the owner's GitHub user id, a string: the connection it listens through if it names one, else the owner's linked GitHub identity; empty when the owner has neither, in which case a filter on it never matches the owner and the skip reason says so). One declaration serves many activations, each with its own inputs. `params` holds the workflow's inputs except those this trigger's `inputs` map from the event, with defaults applied and declared types. Validation types it from the workflow's inputs: `trigger.activation.params.repo` for a `repos` input is an error when you save.

**Typed inputs: let the integration say what a value is.** An integration defines value types, and an input of that type is a picker in the Enable and Run dialogs, not a text box. `get_integration_schema github` lists them; GitHub has `github.repository` (`owner/name`, from the repositories the Reliant GitHub App is installed on that the user can see), `github.label` (scoped to a repository), `github.user` (a numeric account id, stored as a string, never a login) and `github.installation`.

```yaml inputs: repos: {type: github.repository, multi: true, required: true, min_items: 1, description: The repositories to review.} trusted_ids: {type: github.user, multi: true, default: [], description: People who may ask for a re-review, besides you.} skip_label: {type: github.label, scope: {repository: repos}, default: skip-review} # offers the labels of the picked repositories triggers: - name: pr-opened integration: integration: github events: [pull_request.opened] match: {repository: {input: repos}} ```

- **Never `type: array` (or `string`) for something an integration has a type for.** A repository list typed `array` is a comma-separated text box with nothing checking it, and the trigger cannot tell it is a repository scope. If you cannot find a type, run `get_integration_schema <integration>`; validation names the types the integration does declare. - **Values stay plain JSON**, strings for every GitHub type, so `inputs.repos.exists(r, r == inputs.repo)` and `trigger.sender.id in trigger.activation.params.trusted_ids` keep working. `multi: true` makes it a list (`min_items`/`max_items` bound it); `scope: {repository: repos}` binds the type's scope key to another input. - **`required: true`** is explicit: the user cannot turn the automation on until the input has a value, and an existing activation missing one shows "Needs setup" rather than going quiet. A required input takes no `default` (validation says so). An input with no default is required too; give a `default` (`[]` for a list) only when it is truly optional, like `trusted_ids`. - **`match: {attribute: {input: name}}` scopes a trigger by an input.** The event is routed only when its attribute is one of the input's values, so an event for any other repository is dropped before a firing is recorded. The attribute and the input must have the same type (`repository` is a `github.repository`; validation checks it), the input must not be one the trigger maps from the event, and it should be `required`. It combines with literal `match:` entries and runs before `filter`. Keep `filter` for what a scope cannot say: drafts, labels, trust. Do not write `trigger.payload.attributes.repository in trigger.activation.params.repos` in a filter; validation warns and points at `match:`. - **Trust by id**: `trigger.sender.id` is the GitHub numeric id, a string. `trigger.sender.verified && (trigger.sender.id == trigger.activation.owner.github_id || trigger.sender.id in trigger.activation.params.trusted_ids)` admits you and the people in a `github.user` input. The event attribute `sender_id` (a `github.user`) is the same id: `match: {sender_id: {input: allowed}}` scopes a trigger to the people a `github.user` input lists, on the events that declare `sender_id`. Use the filter, as above, when the owner is trusted without being listed.

**`dedupe_key`** (webhook triggers only) is a `{{ }}` template over `trigger` that names the event a delivery is about. Use it for a sender with no idempotency header, such as Alertmanager, which re-sends a group with a changed body: the default key (an idempotency header, else the body hash within one minute) would make every repeat a new run. Deliveries whose keys render the same within one `dedupe_window` are ONE event (the first starts a run; the rest are recorded as duplicates). The window is a fixed UTC-aligned clock bucket, default 1h, at most 24h, so it is the longest a repeat is suppressed, not a sliding guarantee. A key that cannot render for a delivery falls back to the default key. It needs a `{{ }}`, and `dedupe_window` needs a `dedupe_key`.

**Test a trigger before handing it over.** `cel_eval` with `integration` + `event` generates `trigger.payload` from the payload that event declares (add `trigger_payload` to override only the fields your expression reads), and `scope: trigger` gives a filter's, inputs mapping's or prompt's view (only `trigger`, activation included; give it `activation_params` and `owner_github_id`). It returns the value and its type, or the error with its phase and position, plus `findings` for reads the declared payload rules out. Do this instead of waiting for a real event: evaluation does not require enabling the trigger or waiting for a real event. `reliant workflow eval` is the same on the command line, and `reliant workflow validate --trigger-payload` dry-runs every declared trigger (filter, inputs, prompt, dedupe key) against a sample event, with `--activation-params` and `--owner-github-id` for the sample activation.

**Chat is a trigger too, on by default.** Set top-level `automation_only: true` for a workflow only its `triggers:` should start: chat pickers stop offering it and starting it from a chat is refused. A deliberate start by hand still works: Run now, `reliant workflow run`, an agent's `start_run` and a builder test run. Leave it unset for anything a person starts by chatting. A helper that only other workflows `ref:` sets `hidden: true` as well: hidden keeps it out of every picker and listing, and the pair marks it as an automation's internal step.

**Where an automation's runs go.** A run a trigger fires is a chat, but not one in the chat list: it is listed under Workflows → Runs, named by its automation. Once it finishes successfully it archives itself (still in Runs, marked Archived). A failed run, a completion into a declared `outcome: failure`, a cancelled run and one awaiting input stay unarchived so they surface. So route a blocked or punted path to a terminal node with `outcome: failure` when a person should look at it. An automation with "notify me when a run succeeds" keeps its successful runs too, and raises a desktop notification for each. A successful run is never an Inbox item, whatever that setting says: the Inbox holds what needs a person (a question, an approval, a failed run, a broken automation), and a later successful run clears the automation's failure item. A workflow that must tell a person something after a success does it with an explicit step: a Slack, SMS or email message, or an async ask_user question.

What `trigger.payload` holds, by source:

| Source | trigger.payload | |--------|-----------------| | schedule | `scheduled_for`, `fired_at`, `trigger_name`, `manual` (also `trigger.scheduled_for`) | | webhook | `body` (parsed JSON or text), `headers`, `query`, `content_type` | | integration | `integration`, `event`, `account`, `delivery_id`, `attributes`, `data` (the provider's payload) | | workflow_event | `run_id`, `chat_id`, `workflow_name`, `outcome`, `summary`, `error` |

The payload is untrusted data from outside. Read it in templates; never paste it into a system prompt.

An integration's payload is declared (`get_integration_schema` shows it), and validation type-checks the filter, inputs and prompt against it. Lists of names are strings, not objects: GitHub's `issue.labels` and `issue.assignees`, and `data.label` on `issues.labeled`. Write `'wontfix' in trigger.payload.data.issue.labels`, never `l.name`.

GitHub is the fullest integration for automations. Besides `issues.opened` and the like it delivers `issues.labeled`/`unlabeled`/`reopened`, `pull_request.labeled`/`unlabeled`/`reopened` (`match: {label: ...}`), `pull_request_review_comment.created` (inline diff comments; `match` `is_reply` and `mentions_reliant`), and `check_run.completed` / `check_suite.completed` / `workflow_run.completed` (`conclusion`, `branch`, `app`), and `check_run.rerequested` / `check_suite.rerequested` (GitHub's Re-run button on the App's own checks; GitHub re-runs nothing itself). Its `type: action` nodes cover comments (`issue.comment`, `.update`, `.list`), atomic `issue.labels.add`/`remove` (prefer them to `issue.update`, which replaces the whole label list and races), `issue.search`, `labels.create` (idempotent, for pack setup) / `labels.list`, `pr.create`/`update`, `pr.reviews.list`, `pr.review_comments.list` and `pr.review_comment.reply`. There is no merge action, on purpose. Actions that change GitHub are withheld from an unattended run unless the step names them in its `tools`. A trigger on a label event also fires for a label a run itself adds, so guard it.

**`trigger.sender`** is who sent the event, set by the receiver from what the source authenticated, never from the payload: `kind` (slack, github, email, sms, webhook, workflow, schedule, user), `id`, `display_name`, `verified`. Slack's `id` is the user id, GitHub's the numeric user id as a string (`"583231"`; the login is `display_name`, and since a login can be renamed and then registered by someone else, never allowlist logins), email's the lowercased address (verified only when Gmail's DMARC, or DKIM aligned with the From domain, passed), sms the From number (never verified). To let only certain people start runs, filter on it and require `verified`: `trigger.sender.verified && trigger.sender.id in ["U123", "U456"]`.

**`trigger.origin`** says whether Reliant itself caused the event, so a workflow can tell its own echoes from other people's. Every key is always present (an unattributed event reads `caused_by_reliant: false, confidence: 'none'`), in `filter`, `inputs` and `prompt`:

| Key | Meaning | |-----|---------| | `caused_by_reliant` | Reliant wrote the thing the event reports (any confidence) | | `confidence` | `exact` (the event's own object id is one a run's write produced), `intent` (matches a recent write on target and content), `app` (from Reliant's GitHub App, run unknown), `claimed` (a `Reliant-Run:` commit trailer; anyone can write one, so it is only ever a reason to ignore), `none` | | `run_id`, `workflow`, `trigger_name` | The run that wrote, its workflow, and the declared trigger that launched it. Empty unless it is YOUR run | | `same_workflow` | That run is a run of this trigger's own workflow: the event is its own echo | | `actor` | Who the write was made as: `app`, `owner` or `unknown` | | `lineage_depth` | How many event-driven hops led to the run that wrote (a chain stops at 5) |

A trigger's **`origin_filter`** is a raw CEL bool evaluated BEFORE `filter`. Its default ignores a workflow's own echoes: `!(trigger.origin.same_workflow && trigger.origin.confidence in ['exact', 'intent'])`, so a reviewer does not re-run on its own review. `origin_filter: "true"` receives everything; `!trigger.origin.same_workflow || trigger.origin.trigger_name == 'responder-push'` allows one deliberate re-trigger. A skipped event is recorded with the reason (`origin_filter rejected: caused by run X of this workflow`). The lineage depth cap (5) is a hard loop guard no expression overrides, so two workflows that re-trigger each other still stop. Only writes made through integration actions (`type: action` nodes, integration tools) are attributed exactly; an agent's own shell `gh`/`git` writes look like the person who owns the machine.

**The loop for an integration trigger:** `search_integrations(kind: trigger)` → `get_integration_schema` (its events, the `match` attributes, the payload schema, and a ready `triggers:` block) → write it with `edit_workflow` (validation reports bad cron, filters, inputs, events and match keys like any other error) → test its filter and inputs with `cel_eval` and its graph with `run_scenario` → tell the user the workflow is ready (below).

**When the workflow is ready**, say it is saved and validated. If asked to activate it in an interactive chat, use create_trigger_activation with its declared trigger name, typed params, project_id, explicit machine_id (or no_machine) and connection_id. The approval card shows the resolved workflow, identity, machine and privileges. Use update_trigger_activation to re-point an existing activation, enable_trigger to resume, pause_trigger to pause, and delete_trigger to remove one for good. Never claim success before approval and a successful tool result. list_triggers shows the result and health. The app remains an alternative: **Workflows → Library → open the workflow → Enable** turns on all declared triggers. Unattended runs are refused: they cannot grant themselves standing privileges.

**Editing the YAML changes every activation.** An activation reads its declaration from the workflow each time it fires, so a new cron, filter or input mapping applies on the next event. Renaming or removing a declaration, or changing its source kind or integration, leaves its activations BROKEN: they fire nothing, report why in `list_triggers`, and recover when the declaration is restored (or are enabled again by the user). Runs a trigger starts are unattended — nobody answers questions or approvals.

**Who the run writes as.** Every new activation defaults to `acting_identity: app`, whatever its source: GitHub comments, reviews, labels and pull requests appear as the Reliant bot, `reliant-labs[bot]`. `owner` (writes appear as the user) is an explicit opt-in. Existing activations retain their stored identity, and explicit owner choices stay owner. Only GitHub has a bot: Slack, Gmail, Twilio and HTTP writes always use the owner's connection. It is the ACTIVATION's choice, made in the app, not the workflow's and not yours: nothing in the YAML, an `action` node's `with:` or a prompt can switch it, and a person typing in the run's chat acts as themselves. It covers every GitHub write the run makes, an `action` node and an agent's integration tools alike, and only the writes: reads use the owner's access. Everything the bot authors ends with a footer naming the automation and its owner, so do not write your own signature. The bot only writes to a repository the owner can push to, scoped to that one repository; if the owner cannot push, the Reliant GitHub App is not installed there, the App lacks a permission, the deployment has no App key, or minting fails, the write FAILS with the reason (it never falls back to the owner's name or to a saved connection; a write that names a saved connection on a bot run fails too, and a git_publish push is refused the same way), so a workflow that must keep going should handle the action's error output. When you hand a workflow to the user, say that its GitHub writes default to the bot, and that the user can choose to write as themselves instead. A deployment without a control plane refuses the bot identity on save; the user must configure the App or explicitly choose owner. Comments written by Reliant's own bot never fire `issue_comment.created` or `pull_request_review_comment.created`, so a run that comments cannot trigger itself; other bots' comments do.

### An optional node: `tolerate_failure: true`

A node whose failure must not fail the run (an auxiliary reader agent, a best-effort notification) declares `tolerate_failure: true` at node level, beside `id` and `type`. When it fails, the run goes on instead of failing, and instead of pausing on a step that used up its retries:

```yaml - id: cp_reader type: workflow ref: builtin://autopilot-agent tolerate_failure: true args: { ... } - id: review ... edges: - from: cp_reader cases: - condition: "nodes.cp_reader.?failed.orValue(false)" to: [note_reader_failed] default: [review] ```

- **Its outputs when it failed are exactly** `{failed: true, error: "<why, one line>"}`: route on them with an edge case or a condition. When it succeeded they are its ordinary outputs, with no `failed` key, so read `nodes.<id>.?failed.orValue(false)` and guard its other fields. - **It works on every node type** (an activity, a loop, a sub-workflow or agent, a router), in the main graph, a loop body or a sub-workflow. Its `save_message` is not written when it failed. - **Never tolerated:** a cancel, a pause, a panic, and a run that is already ending (a continue-as-new handoff, an unattended run that gave up). Those are not the node failing. - **It is not a success.** The failure is logged, and an activity's failed attempt stays in the run's node diagnostics (`get_run`). Use it for work the run can do without, not to hide a step it needs: a required step that fails should fail the run (and reach `on_failure`).

### When a run fails: `on_failure:`

A workflow-level `on_failure:` is a finally-style handler: an inline graph (`entry`, `nodes`, `edges`, or `sequence:`) that runs ONCE when a run FAILS, so the people waiting on it are told instead of finding a silent dead end.

```yaml on_failure: sequence: - id: note type: save_message args: role: assistant display_style: warning content: "Failed at {{ failure.node_id }} ({{ failure.error_code }}): {{ failure.error }}. prep: {{ nodes.?prep.n.orValue('-') }}." ```

- **It runs when** a node's error was not handled (a config that will not evaluate, a sub-workflow that failed, an agent that never produced its response and ended the step), or the graph reached a node that declares `outcome: failure`. It does not run when the run completes, pauses (a step that exhausts its retries pauses the run, it does not fail it), or is cancelled. - **`failure`** exists only inside the handler: `failure.node_id`, `failure.node_path` (dotted, through loops and sub-workflows), `failure.error` (one line), `failure.error_code` (`node_error`, `outcome` or `panic`), `failure.attempt` (the loop iteration, 1 if none). `inputs` are the run's. `nodes` are the outputs the run had produced when it failed, as a read-only copy. - **Guard every `nodes.<main node>` read** with `has()` or `.?`: whichever node failed, the ones after it never ran, and validation rejects an unguarded read. A handler node may not reuse a main-graph node id, and `on_failure` itself is a reserved id. - **It cannot mask the failure.** The run still ends FAILED. An error inside the handler (or a handler that outlives its 5-minute budget) is logged and recorded, never handled and never recursive; it has no `outputs`, `inputs` or nested `on_failure`. It can contain actions, `save_message`, sub-workflows and agents, but no `approval` or `ask_question`: nobody is answering. - **Make a failure visible.** A run that ends on a path labelled "blocked", "punted" or "no result" but finishes normally is a success to the platform: it is auto-archived and never reaches the handler. Route those paths to a terminal node with `outcome: failure`. - **Tell a person once.** The Autopilot pack's `builtin://autopilot-failure-note` posts one comment per pull request head commit (or issue): it searches the thread for its own marker first, posts nothing if the thread cannot be read, and writes as whoever the run acts as. - **Test it.** A scenario names the handler's nodes `on_failure.<node>` in `events`, `reached`, `completed` and `messages`, and asserts `expect.on_failure: {ran, node_id, node_path, error_code, attempt, error_contains, handler_failed}`. - **Releasing something?** on_failure never runs for a cancelled run. A lease, claim or label the run takes must be released in `finally:`, below.

### However a run ends: `finally:`

A workflow-level `finally:` is an inline graph, like on_failure, that runs ONCE when a run ENDS: it completed, it failed, or it was cancelled (`control_run cancel`, CancelRun, archiving the chat). It is where a workflow releases what it holds, so nothing stays held until a TTL runs out.

```yaml finally: sequence: - id: release type: run condition: "nodes.?lease.sha.orValue('') != ''" timeout: 3m args: command: "scripts/lease.sh release --sha '{{ nodes.lease.sha }}'" - id: note type: save_message condition: "run.status != 'completed'" args: role: assistant display_style: warning content: "Ended {{ run.status }}{{ run.status == 'failed' ? ' at ' + failure.node_id : '' }}; released the lease." ```

- **It runs when** the run completes, fails (after on_failure), or is cancelled. Not when it pauses (it is coming back) or hands off to a successor run. - **`run.status`** is `'completed'`, `'failed'` or `'cancelled'`, and exists only inside finally. `failure.*` is declared too, every key present and empty unless `run.status == 'failed'`. - **On a cancel**, the run's in-flight steps are cancelled first, and a `run` node's command is stopped on its machine. Then finally runs, on its own budget, so its own commands are not cancelled. A run that does not stop within a few seconds of the cancel is hard-terminated without it. - **The same rules as on_failure:** guard `nodes.<main node>` reads (a cancel can stop the graph anywhere), no node id shared with the main graph, `finally` is a reserved id, no `outputs`, `inputs` or nested handlers, no `approval` or `ask_question`, a 5-minute budget, and an error in it is logged and never changes how the run ended. Make its steps idempotent: releasing a lease that is not held must succeed. - **A child's finally.** A workflow started by a `workflow:` node with `ref:` runs its own finally when it ends, in its own scope, before the parent's (`release.finally.<id>`). - **Test it.** Name its nodes `finally.<node>` in a scenario and assert `expect.finally: {ran, status, handler_failed}`.

### A GitHub check the engine owns: `check:`

A workflow-level `check:` makes every run a trigger fires post ONE GitHub check run, as the Reliant App, whose lifecycle the engine owns: do NOT write `github/check_run.create`/`update` nodes, an `on_failure` that concludes it, or a sweep for stuck checks. A branch ruleset can then require it by name. One workflow can be an agentic check (a code review) or a deterministic one (lint, tests); each is its own workflow with its own `check:`, so each can be required and re-run alone.

```yaml check: name: reliant/ci # the check's name on GitHub; a ruleset requires it by this name output: "{{ nodes.report.check }}" # optional: {title, summary, text?, annotations?} # repository: "{{ trigger.payload.attributes.repository }}" # the default # head_sha: "{{ trigger.payload.data.check_suite.head_sha }}" # default: the event's head commit # timeout: 2h # default 6h, 1m..72h triggers: - name: pr integration: {integration: github, events: [pull_request.opened, pull_request.synchronize, pull_request.reopened]} ```

`check: reliant/ci` (the name alone) is the short form.

- **Lifecycle.** `queued` as soon as the firing is recorded (so a firing waiting for capacity or a waking machine shows), `in_progress` when the run's first node starts, and concluded on EVERY ending: `success` when the run completes; `failure` when it fails, routes to a node with `outcome: failure`, cannot start, or pauses for more than 15 minutes (titled "Reliant could not run this check" for an engine fault); `cancelled` when it is cancelled, skipped or superseded (`concurrency: {waiting: latest}`); `timed_out` when it is still going at `timeout`. Never `neutral` or `skipped`, which a required check counts as passing. - **The verdict is the run's.** The conclusion comes from how the run ended, not from `output`. To fail the check when the gate fails, route that path to a terminal node with `outcome: failure`. - **Output.** `output` is evaluated when the run ends, in a finally handler's scope (`nodes`, `inputs`, `trigger`, `workflow`, and `run.status`), and must be an object with `title` and `summary` (markdown), optionally `text` and `annotations`: a list of `{path, start_line, end_line?, annotation_level: notice|warning|failure, message, title?}`, sent 50 per request. A `run` node and an agent node work the same way: build the object in a `compute` node from either's outputs, or have an agent return it as its structured response. Guard reads of nodes that may not have run (`nodes.?gate.exit_code.orValue(-1)`); an output that fails to evaluate falls back to the engine's own summary. `details_url` is always the run's page. - **Where.** `repository` and `head_sha` are templates over `trigger`, rendered when the firing is recorded. By default the head is the pull request's head, the check suite's or check run's head_sha, the workflow run's head_sha, or the commit a push moved its branch to. A firing that names no repository or commit posts no check, and the run still runs. - **Who.** The activation's GitHub identity: it must act as the Reliant bot (the default), since GitHub lets only an App write a check run. - **One check per firing.** A retried or resumed fire and a resumed run update the same check; a re-run is a new firing and a new check. Only runs an event trigger fires post one (GitHub events, webhooks): a chat, a schedule or a builder test does not. - **Test it.** A scenario runs the graph; what the check concludes follows from how the run ends.

## Important rules

### Parameters - Set model as a param via a **tag** (flagship, moderate, cheap, etc.) — not a hardcoded model ID - **NEVER** assume which models exist. Your training data may be stale, and users have different API keys. - A workflow always runs in the context of a user thread. You never need to create input to consume the user's request.

### Agents and LLMs - `CallLLM` is a single LLM call — it doesn't execute tools or loop - Common patterns: - **Augmented agents**: Do additional work inside the agentic loop (e.g., auditing) - **Parallelization**: Multiple edges from the same source (not switch/case logic) - **Combining agents**: Multiple specialized agents with distinct tools/instructions - **Structured output**: Use response tools to produce output for conditional routing - Combine patterns to create powerful workflows

### Loops - `while` is **do-while**: the body always runs at least once - `iter.iteration` is 0-indexed inside the loop body - `outputs.*` in the `while` condition references the **current iteration's** outputs

### Response tools - Force structured LLM output for routing/classification - `builtin://agent` returns when no tool calls remain (use `ask: true` to prompt for user feedback first). `args.max_turns` bounds it (0, the default, is no limit; set it in any unattended or `max_running` workflow) and `args.tool_params` binds tool parameters the model cannot see, e.g. `{shell: {credentials: none}}` (with `spawn_presets: []`, since a spawned sub-agent's tools are not bound) - `builtin://structured-agent` returns when the response tool is called (use `ask: true` to prompt for user feedback first) - Access structured output via `nodes.<execute_tools_id>.response_data.<tool_name>`

### Conditions on nodes - Skipped nodes forward execution to the next edge target - You **cannot** access outputs of skipped nodes - Join nodes handle skipped inputs correctly

## Available tools

Granted by `tag:workflow` — no `load_tool` needed in a workflow-building chat. All take the required `id` (UUID/slug/name) described above except `create_workflow`, which mints one, and the discovery/reference tools (`list_workflows`, `list_presets`, `get_preset`, `get_schema`, `get_cel_reference`, `cel_eval`, `get_workflow_suggestions`).

| Tool | Purpose | |------|---------| | `create_workflow` | Create a new workflow draft (returns id, name, slug) | | `get_workflow` | Read current workflow content | | `edit_workflow` | Make targeted edits to a workflow | | `write_workflow` | Full workflow rewrite | | `get_schema` | Get full field documentation for any node/input/shared type | | `get_cel_reference` | Authoritative CEL reference (namespaces, functions, types) | | `cel_eval` | Evaluate a CEL expression or template against a sample trigger (generated from an integration event's declared payload), inputs and node outputs: value and type, or a precise error. Test a filter in one call | | `search_integrations` | Find an integration action ref (GitHub, Slack, HTTP, ...) for a `type: action` node's `uses:` | | `get_integration_schema` | Read one integration action's params (`with:`) and output (`nodes.<id>.data`) schemas | | `list_triggers` | List the triggers the user has enabled (optionally one workflow's) with health; read-only. BROKEN means the declaration it activates is gone or changed | | `fire_trigger` | Manually fire an existing activation once, including a paused one; never creates, enables or changes it. Orchestrator-tier; returns an asynchronous fire_workflow_id, not a successful run | | `list_trigger_events` | Read firing history without source payloads. Match fire_workflow_id exactly, then inspect the launched chat_id with get_run; paginate with next_page_token | | `list_workflows` | Browse existing workflows for examples and patterns | | `list_presets` | Discover available agent presets | | `get_preset` | View a preset's full configuration | | `write_scenario` | Create a test scenario | | `run_scenario` | Execute a scenario and check results | | `list_scenarios` | List existing scenarios for a workflow | | `view_scenario` | Read a scenario's content | | `edit_scenario` | Modify an existing scenario | | `delete_scenario` | Remove a scenario | | `get_workflow_suggestions` | Get AI-powered suggestions for workflow improvements |

Outside a workflow-building chat, these tools aren't preloaded, but `load_tool(name="tag:workflow")` is always available (it's in `tag:coding:default`) and loads the full set on demand. Every tool that targets an existing workflow requires its `id` (returned by `create_workflow`, or listed by `list_workflows`).

## CEL Reference

> Auto-generated from `internal/workflow/reference`. Use `get_cel_reference` for the complete authoritative reference.

### Syntax rules

| Context | Syntax | Example | |---------|--------|--------| | `condition`, `while` | Pure CEL (no `{{}}`) | `condition: "nodes.llm.stop_reason == 'tool_use'"` | | All other fields | Template interpolation `{{}}` | `model: "{{inputs.model}}"` |

### Namespaces

| Namespace | Description | Fields | |-----------|-------------|--------| | `failure.*` | What failed, inside a workflow's on_failure and finally handlers only (failure.node_id, failure.node_path, failure.error, failure.error_code, failure.attempt; in finally every key is empty unless run.status is 'failed'). Undeclared everywhere else | workflow-specific | | `inputs.*` | Workflow input values passed at invocation | workflow-specific | | `iter.*` | Loop iteration context (iteration count, first/last flags) | `iteration` | | `nodes.*` | Output from completed nodes (nodes.<id>.<field>) | workflow-specific | | `output.*` | Current activity output (for save_message context) | workflow-specific | | `outputs.*` | Loop iteration outputs for while condition evaluation | workflow-specific | | `run.*` | How the run ended, inside a workflow's finally handler only (run.status: 'completed', 'failed' or 'cancelled'). Undeclared everywhere else | workflow-specific | | `thread.*` | Current thread context (token_count, message_count) | workflow-specific | | `trigger.*` | The event that started this run, fixed at launch (trigger.kind, trigger.name, trigger.scheduled_for, trigger.payload.<x>, trigger.sender.{kind,id,display_name,verified}, trigger.origin.{caused_by_reliant,confidence,run_id,workflow,trigger_name,same_workflow,actor,lineage_depth}). Interactive chats have kind chat.start. A trigger's filter, inputs and prompt can also read trigger.activation.params.<input>, trigger.activation.id and trigger.activation.owner.{user_id,github_id}; nodes cannot | workflow-specific | | `workflow.*` | Workflow execution context (id, name, path, etc.) | `id`, `name`, `chat_id`, `run_id`, `path`, `worktree_path`, `branch`, `mode` |

#### `iter` fields

| Field | Type | Description | |-------|------|-------------| | `iter.iteration` | `int` | Current loop iteration (0-indexed) |

#### `workflow` fields

| Field | Type | Description | |-------|------|-------------| | `workflow.branch` | `string` | That worktree's git branch (empty in the project's main checkout, whose branch is not tracked; test with has(workflow.branch)) | | `workflow.chat_id` | `string` | The chat the run belongs to; its page is /workflows/runs/<chat_id>, so a run can link to itself (a GitHub check run's details_url) | | `workflow.id` | `string` | Workflow execution ID (unique per run) | | `workflow.mode` | `string` | Execution mode (auto, manual, plan), from inputs.mode | | `workflow.name` | `string` | Workflow definition name | | `workflow.path` | `string` | Absolute working directory of the current scope: the chat's worktree or project, or a sub-workflow's project.path. Reading it in a run with no project directory is an error, not ""; test with has(workflow.path) | | `workflow.run_id` | `string` | Workflow run ID (Temporal run ID) | | `workflow.worktree_path` | `string` | The chat's worktree, when

Intended uses

  • Building an agent or automation that runs on its own: on a schedule ("every morning", "twice a day", cron), on a webhook or an app event — a bot, monitor, digest or triage job, even when it sounds like "just a script"
  • Creating a new Reliant workflow from scratch
  • Editing or extending an existing workflow
  • Debugging workflow execution issues
  • Writing scenario tests for workflows
  • Understanding workflow patterns and best practices

Implementation notes

  • Aim for 3+ scenarios per workflow — cover the happy path, error cases, and edge cases
  • outcome: accepts three values — completed, error (workflow terminated with an error;
  • Use completed: to prove a branch ran, not reached: — see above; reached: also passes
  • Test routing logic by mocking the router — reached:/completed: on the destination node
  • Test loop termination — verify loops exit correctly (both via while condition and max iterations)
  • Test skipped nodes with skipped:, not notreached: — a node can be scheduled and skipped
  • Use startat — to test specific sections of complex workflows without simulating the entire flow
  • Use state — to pre-populate node outputs when testing downstream logic
  • Name scenarios descriptively — e.g., errorhandlingapifailure not test3
  • Try to break it — simulate unexpected LLM responses, tool failures, and edge cases. Finding bugs in scenarios is much cheaper than finding them during a real 1-hour workflow run.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.