AgentRoles, AgentWorkflows and AgentWorkflowRuns

Infrared puts humans and agents in one change-management flow. Three resources describe it.

Resource	What it is	Example
AgentRole	One job an agent performs, written so a capable agent could do it cold: mission, ordered responsibilities, triggers, inputs, outputs, evidence, success criteria, guardrails, permissions, escalation and the org's opinions.	Security reviewer
AgentWorkflow	An ordered list of steps a Change or a scheduled job moves through. A step runs an AgentRole, waits for a human, promotes to a zone, waits for CI, or does something automatically.	Change
AgentWorkflowRun	One run of an AgentWorkflow: each step's phase, verdict, attempts, token usage, cost and evidence.	A run of Change for checkout-web#212

AgentRoles

An AgentRole is complete guidance, not a one-line prompt. Every AgentRole in the catalog fills the same sections, and the UI shows them in this order.

Section	What it answers
Summary and mission	What the role does in one sentence, and the outcome it is accountable for.
Responsibilities	The ordered steps it takes, each concrete enough to check.
Triggers	When it runs: on every Change, on an event such as release.cut, on a cron schedule, or on request.
Inputs and outputs	What it reads (the diff, the issue, logs, metrics) and what it leaves behind (commits, comments, issues, documents).
Evidence	The proofs it attaches to the AgentWorkflowRun, and which are required.
Success criteria	Statements a reviewer can check that must all hold for the run to succeed.
Guardrails	What it must never do.
Permissions	The tools it may and may not use, git scopes, cluster verbs, network egress, and whether it may merge. Deny wins over allow, and no catalog role may merge.
Escalation	The conditions that hand work to a human, who that is, and how long it may try first.
Opinions	The org's editable guidance, such as library preferences, semver rules or the coverage bar.
Model	The run budget in US dollars and the turn limit.

Most change-review AgentRoles end each run with one verdict: VERIFIED, MERGE WITH FOLLOW-UPS or BLOCK. AgentRoles that fix things end with CHANGED, NO CHANGE NEEDED or BLOCKED. The verdict is recorded on the step in the AgentWorkflowRun.

Events

Event triggers use a fixed set of names.

Event	Fires when
issue.opened	An issue is opened on a Product repo.
issue.labeled	An issue gets a label.
issue.ready-for-agent	An issue moves to Todo (agent) on the board.
pull_request.opened	A pull request is opened.
pull_request.synchronize	New commits land on a pull request's branch.
conflict.detected	A Change branch can no longer merge cleanly into its base.
ci.failed	A required CI check fails on a Change.
zone.promoted	A pin is promoted to a zone and its Application is Synced and Healthy.
release.candidate	A Release candidate is proposed.
release.cut	A Release is cut.
release.published	A Release is published.

Opinions: edit and switch off

Opinions are where an org makes an AgentRole its own. Each opinion has a name, a title and guidance written in plain words, for example "Patch and minor bumps are applied automatically; major bumps are proposed in a separate issue."

In the UI, open an AgentRole and go to Opinions. For each one you can:

• Edit the guidance. The opinion's origin changes from catalog to org, and the AgentRole shows that it differs from the catalog.
• Switch it off so the agent no longer receives it, without deleting the text.
• Add a new opinion of your own.
• Reset an edited opinion to the catalog text.

Switched-off opinions keep their text and show "Off for " in the UI. In the spec, an opinion is on unless it carries enabled: false.

The same editing applies to every other section: responsibilities, guardrails, permissions and so on. An AgentRole whose spec no longer matches the catalog has status.differsFromCatalog set to true, so catalog upgrades can show what the org changed.

Verdicts and extra instructions

Each AgentRole declares the verdicts a run may end with, in verdicts. A review role ends with VERIFIED, MERGE WITH FOLLOW-UPS or BLOCK; a role that fixes things ends with CHANGED, NO CHANGE NEEDED or BLOCKED. The AgentWorkflowRun records the verdict of each step.

An org can add its own instructions to a role (markdown appended to the agent's prompt) and list the skills and mcpServers the role may use. The UI edits instructions on the role's What it does tab.

Catalog seeding

When an org is created, Infrared copies the default catalog into the org's namespace, ir-org-<org>: every AgentRole and every AgentWorkflow, labeled with the catalog version they came from. From then on they are the org's own resources. A catalog upgrade never overwrites an org's edits; it offers the differences for review.

Some catalog AgentRoles start disabled because they act in public. The socializer drafts posts for social networks and is off until an org turns it on, and even then every post waits for human approval.

AgentWorkflows

An AgentWorkflow lists its steps in order. By default a step starts when the step before it finishes; needs lets a step wait for specific earlier steps instead, and independent: true starts a step with the workflow, so the daily audit's three checks run side by side. A step can carry a when condition, such as change.author in [human] or label:security, and is skipped when the condition doesn't hold or its AgentRole is switched off. Human gates name their approvers, how many approvals they need (minApprovals) and a timeout after which they escalate.

Each step says what happens when it fails:

On failure	What happens
Dead-letter	The run pauses at the step and the work goes to the workflow's dead-letter reviewer, such as @platform/reviewers. This is the default.
Fail	The run stops and is marked Failed.
Continue	The failure is recorded and the next step starts.

A required step cannot be switched off for a Release. In the Change AgentWorkflow, the builder, the security review, the promotion to the rc zone, the end-to-end verification, human approval and the merge are required. Human approval can never be removed: it is the step the product exists to guarantee.

AgentWorkflowRuns

Every time an AgentWorkflow runs, Infrared creates an AgentWorkflowRun in the org's namespace. It records the phase of the run and of each step (Queued, Running, AwaitingApproval, DeadLettered, Succeeded, Failed, Cancelled or Skipped), each step's verdict and attempts, the tokens and cost used, and links to the evidence it captured, with each success criterion marked passed or not.

A reviewer approves a Change from its AgentWorkflowRun: the verdicts, the screenshots and video from the rc zone, the SARIF report and the diff, all in one place.

:::note Phase 5 The AgentWorkflowRun schema is fixed in v1alpha1 so the API, UI and CLI can build against it. Executing runs arrives in phase 5, together with tailoring AgentRoles from analysis of an org's repos. See the roadmap. :::