Schema reference

Top-level

Field	Type	Required	Description
id	string	Yes	Workflow identifier
inputs	map<string, JSONSchema>	No	Input definitions
env	map<string, template>	No	Environment variables
steps	array<Step>	Yes	Non-empty step array

Common step fields

Field	Type	Required	Description
id	string	No	Unique ID
type	string	Yes	Step type
if	expression	No	Conditional execution
env	map<string, template>	No	Step-level env vars
retry	integer or object	No	Retry action or workflow steps

type: shell

Field	Type	Required	Default
with.command	template	Yes	—
with.stdout.mode	none | text | json	No	text

type: codex (kind: turn)

Field	Type	Required
with.kind	turn	Yes
with.prompt	template	Yes
with.collaboration_mode	default | plan	No
with.model	string	No
with.effort	low | medium | high | xhigh	No

kind: turn returns plain text. collaboration_mode: plan uses Codex’s built-in Plan collaboration mode. Plan collaboration turns are planning-only and must not mutate repo-tracked files.

type: codex (kind: review)

Field	Type	Required
with.kind	review	Yes
with.model	string	No
with.target.type	uncommitted | base | commit	Yes
with.target.branch	template	if base
with.target.sha	template	if commit

Built-in result shape:

findings:
  - title: string
    body: string
    confidence_score: number
    priority: integer
    code_location:
      absolute_file_path: string
      line_range:
        start: integer
        end: integer
overall_correctness: string
overall_explanation: string
overall_confidence_score: number

type: claude

Field	Type	Required
with.prompt	template	Yes
with.model	string	No
with.effort	low | medium | high	No
with.max_turns	integer	No
with.max_thinking_tokens	integer	No
with.permission_mode	default | accept_edits | bypass_permissions | plan	No

claude returns the final plain-text assistant response. Claude YAML fields are snake_case and map directly to Claude Agent SDK options in camelCase. Do not set with.kind, with.mode, or with.action on Claude steps. Use a locally installed and authenticated Claude Code CLI (claude login).

type: opencode

Field	Type	Required
with.prompt	template	Yes
with.model	string	No
with.agent	string	No
with.variant	string	No
with.permission_mode	default | auto_approve	No

opencode returns the final plain-text assistant response. OpenCode uses named agents and defaults with.agent to build. with.model must use provider/model. Headless runs reject permission requests by default unless with.permission_mode is auto_approve. OpenCode steps require a local OpenCode CLI installation. Verify with opencode --version.

type: cursor

Field	Type	Required
with.mode	agent | ask | plan	No (default: agent)
with.prompt	template	Yes
with.model	string	No

cursor communicates with Cursor Agent through ACP and returns the final plain-text assistant response. If you need structured JSON from Cursor, use a shell step to run Cursor headless instead.

type: write_file

Field	Type	Required
with.path	template	Yes
with.content	template	Yes

type: workflow

Field	Type	Required
with.workflow	string	Yes
with.inputs	map<string, unknown>	No

with.workflow must be a static string, not a template expression. String with.inputs values are rendered as templates. Non-string YAML literals such as booleans and numbers pass through unchanged. steps.<workflow_step_id>.result is null in v1. workflow steps may set retry.

type: group

Field	Type	Required
steps	array<Step>	Yes
exports	map<string, template>	No

type: loop

Field	Type	Required
max	integer	Yes
until	expression	No
steps	array<Step>	Yes
exports	map<string, template>	No

Loop results are always objects with reason: "until_satisfied" | "max_reached" plus any exported fields. loop.exports.reason is reserved.

type: branch

Field	Type	Required
cases	array<Case>	Yes

Each case: if or else + steps + optional exports. All cases must export the same shape or none.

type: parallel

Field	Type	Required
branches	array<Branch>	Yes
exports	map<string, template>	No

Each branch: id (required) + steps.

Validation rules

1. Step IDs are unique across the entire workflow.
2. steps arrays are non-empty except branch else cases.
3. steps.<id>.result references previous steps only.
4. workflow only references workflows in the same .rigg project.
5. workflow input keys must match the callee input schema.
6. Branch exports must have matching shapes across cases.
7. with is required for all action types.
8. Unknown YAML keys cause errors.
9. retry is only valid on action and workflow steps.