Run a Change

A Change is one AgentWorkflowRun: agents implement an issue, review their own work, and a person approves before anything merges. This page walks through one run of the change-quick AgentWorkflow, the short path that's good for trying the flow.

Before you start

• A Product whose repo the agents will change. See Products.

• An issue in that repo, written like a ticket: what to build, and how you'll know it's done. The builder treats the acceptance criteria in the issue as its definition of done.

• A model provider key. Agent steps call Claude with the Anthropic API key in the Secret model-provider-anthropic, key api-key, in the org namespace ir-org-<org>. Use a key scoped to one Anthropic workspace; runs are billed to it.

  kubectl -n ir-org-<org> create secret generic model-provider-anthropic --from-literal=api-key="$ANTHROPIC_API_KEY"

• The GitHub App on the repo, which every org already has from the setup wizard. Each agent step gets a short-lived installation token that can write contents, pull requests and issues.

1. Start the run

In the UI, open Changes and choose Start a Change, or use Start a Change on a Product's page. Pick the Product, enter the issue number, and keep Change (quick) as the AgentWorkflow.

The same call through the API:

curl -X POST https://<host>/api/v1/orgs/<org>/agentworkflowruns \
  -H "Authorization: Bearer $INFRARED_TOKEN" -H 'Content-Type: application/json' \
  -d '{"workflow": "change-quick", "product": "zippy", "issue": "1"}'

2. Watch the agents

The run's page shows each step with its phase, verdict, tokens and time, and the log of the step that's running, live. What happens, in order:

Step	What it does	It ends with
product-feature-builder	Checks out the repo on the branch infrared/<run>, implements the issue with tests, runs the build and tests, commits, and opens a pull request linked to the issue.	A verdict and the pull request
quality-reviewer	Reviews correctness and test quality on the same branch, and fixes what it can.	A verdict
security-reviewer	Looks for malicious edits, secrets and known vulnerabilities. A BLOCK verdict stops the Change.	A verdict
human-approval	Waits for you.	Your approval or rejection
merge	Squash-merges the pull request, but only when every required step succeeded.	MERGED

Each agent step runs as a Kubernetes Job in the org namespace, with the AgentRole's mission, responsibilities, guardrails, opinions and success criteria as its instructions, and its model and budget limits. The runner owns git: agents edit files and run commands, and the runner commits their changes and opens the pull request. Every step records its success criteria and whether each passed, which the run's page shows as evidence.

Jobs and their logs are kept for a day after a step finishes.

kubectl -n ir-org-<org> get agentworkflowruns
kubectl -n ir-org-<org> get jobs,pods -l infrared.darkshift.io/run=<run>

3. Approve or reject

When the run reaches human-approval, its page says it's waiting and shows Approve and Reject. Read the verdicts and the evidence, then the diff on the pull request. Approving records who approved; the merge step then squash-merges within seconds. Rejecting fails the run and leaves the pull request open for you to close.

Through the API:

curl -X POST https://<host>/api/v1/orgs/<org>/agentworkflowruns/<run>/steps/human-approval/approve \
  -H "Authorization: Bearer $INFRARED_TOKEN"

When a step needs a human

A step that fails with onFailure: deadLetter stops the run in DeadLettered, with the reason in the run's message. Fix the cause, then choose Retry on the step (or POST .../steps/<step>/retry): that step and every step after it run again.

Message	Likely cause	What to do
secret "model-provider-anthropic" not found	The org has no model provider key	Create the Secret (above), then retry the step
The runner exited without a verdict	The runner couldn't start, or ran out of memory or time	Read the step's log, fix the cause, retry
BLOCK from security-reviewer	The reviewer found something it won't let through	Read its summary and evidence; fix the branch or reject the run