Skip to main content

Workflows

Declare a workflow in YAML, understand its step kinds, decisions and limits, and run the one shipped workflow, core-dev.

On this page

TL;DR: A workflow is one workflow.yaml under services/workflows/<id>/. One ships: core-dev, a GitHub issue taken to a reviewed pull request with three human decisions. It has only run against the local Vertex stub, never a real model.

Declaring a workflow

services/workflows/core-dev/workflow.yaml is the reference. A definition names its triggers, run_as service account, roles, ordered stages of steps, limits and on_failure handling. Prompts and output schemas sit beside it in prompts/ and schemas/.

Step kind Does
agent Runs an agent with a prompt, an output schema, a tool list, a model and a budget_usd
decision A person with the named role chooses an outcome (approve, request_changes, reject, cancel); request_changes loops back
parallel Runs child steps together; join: all waits for every one
write The one write to a system of record, guarded by requires_decision and an effect_key
gate An expression on a step's output (gate: with loop_to / loop_max in core-dev)
manual, event Trigger kinds: core-dev uses manual; Jira events can start runs once the Atlassian connector is on

Limits and failure

core-dev sets limits: { max_attempts: 3, max_loop: 2, wall_clock: 4h } and a per-step budget_usd. on_failure maps a failure class to an action, for example budget_exceeded: escalate, connector_unavailable: retry_backoff. Decisions carry due and an optional escalate_to.

Running core-dev

  1. just dev-sync-apply locally, so the definition exists.
  2. Provision the run_as account as an active user.
  3. Start from the definition page under /admin/workflows, and follow it in /admin/workflows/runs.
  4. Decide in the inbox, /admin/workflows/inbox, or through the systemprompt MCP server's workflow_inbox and workflow_decide tools.

The final open_pr write needs a GitHub App and the credential broker secret; without them the run suspends there with the approved artefact intact.

Known gaps

A retry can resume a Claude Code session that no longer exists, and the step tool list is not yet narrowed to the declared tools. Both are open.