docs: WORKFLOWS.md documents the workflow definition schema and step vocabulary
This commit is contained in:
1 parent
3ba189c07c
commit
231cbc26fe
1 file changed
+286
+286
@@ -0,0 +1,286 @@
|
||||
# Workflow definitions
|
||||
|
||||
A workflow is a YAML document: an id, what it declares to whatever starts it,
|
||||
and an ordered list of steps. Definitions are stored in the control plane's
|
||||
`workflow-definitions` resource and edited on the dashboard's Workflows page
|
||||
(the Canvas and YAML tabs edit the same document). The shipped workflows are in
|
||||
`internal/domain/workflow/shipped/`.
|
||||
|
||||
The server is the authority. It serves the step vocabulary, including each step
|
||||
type's settings schema, in the `workflow-definitions` catalog entry
|
||||
(`x-step-types`), and validates every definition when it is saved. This file
|
||||
describes that vocabulary; when they disagree, the catalog wins.
|
||||
|
||||
```yaml
|
||||
id: implement
|
||||
repository: required
|
||||
inputs:
|
||||
pr_number: {type: number, required: true}
|
||||
steps:
|
||||
- type: repo.prepare
|
||||
- id: plan
|
||||
type: agent.run
|
||||
settings:
|
||||
role: planner
|
||||
read_only: true
|
||||
mission: |
|
||||
Plan this change: {{ task.prompt }}
|
||||
- id: build
|
||||
type: agent.run
|
||||
settings:
|
||||
gate: repository
|
||||
mission: "Implement it following this plan: {{ steps.plan.summary }}"
|
||||
- type: repo.commit
|
||||
settings: {message: "{{ task.title }}", push: true, if_empty: complete}
|
||||
- type: repo.open-pr
|
||||
settings: {body: "{{ steps.build.summary }}"}
|
||||
```
|
||||
|
||||
## The workflow
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `id` | text | The workflow's name. Required, unique. |
|
||||
| `steps` | list | The steps, run in order. At least one. |
|
||||
| `repository` | `required` \| `optional` \| `none` | `required` (the default) clones the task's repository into a worktree. `optional` clones one when the run names a repository and uses a scratch workspace otherwise. `none` never clones; only steps that run without a repository may be used. |
|
||||
| `inputs` | mapping | Named, typed values whatever starts the run must supply: `{type, required}`, where type is `string`, `number`, `bool`, `object`, `array` or `any`. Steps read them as `{{ inputs.<name> }}`. |
|
||||
| `outputs` | mapping | Named, typed results the run writes once each (same shape as inputs). A required output the run never writes parks it. A calling workflow reads them. |
|
||||
| `profile` | text | The container profile (`[containers.profiles]`) the run's agents use. Resolved when the task is dispatched. |
|
||||
| `identity` | text | The identity every run acts as, whatever started it. Empty runs as the starter. |
|
||||
| `needs` | mapping | Harness capabilities the run requires: `captures` (bool), `gate_retries` (number). Declared outputs imply `captures`. |
|
||||
|
||||
## A step
|
||||
|
||||
| Field | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `type` | text | The step type (below). |
|
||||
| `id` | text | Names the step so later steps can read its result. Unique in the workflow; letters, digits, `-` and `_`. The run records the step under this name. |
|
||||
| `settings` | mapping | The step type's settings. String settings may contain references. |
|
||||
| `when` | condition | Skip the step unless the condition holds. |
|
||||
| `on_failure` | `park` \| `continue` | `park` (the default) stops the run for an operator. `continue` records the failure and moves on. |
|
||||
| `retry` | mapping | `attempts` (1 to 10) and `backoff` (a duration such as `30s`). A failed step runs again before `on_failure` applies. |
|
||||
| `parallel` | mapping | Instead of `type`: named branches, each a list of steps, run at the same time. |
|
||||
|
||||
### References
|
||||
|
||||
Any string setting may contain `{{ path }}`, replaced when the step runs:
|
||||
|
||||
| Path | Value |
|
||||
|---|---|
|
||||
| `task.title`, `task.body` | The issue or chat request. |
|
||||
| `task.prompt` | The title and body framed for an agent mission. |
|
||||
| `task.repository` | `owner/name`. |
|
||||
| `task.kind` | What the task came from, as prose: `GitHub issue` or `chat-originated task`. |
|
||||
| `task.issue`, `task.pr` | Issue and pull request numbers. |
|
||||
| `task.plan` | The plan a `human.approve` step handed over (an approved PRD). |
|
||||
| `task.review` | The review comments a remediation round addresses. |
|
||||
| `inputs.<name>` | A declared input. |
|
||||
| `steps.<id>.summary` | What an earlier step reported, e.g. an agent's finish summary or a gate's output. |
|
||||
| `steps.<id>.result.<field>` | A field of an earlier agent's structured result. |
|
||||
|
||||
Only earlier steps may be referenced; a reference to a later or unknown step is
|
||||
refused when the definition is saved. A value that does not exist at run time
|
||||
(for instance, a step that was skipped) renders empty.
|
||||
|
||||
### Conditions
|
||||
|
||||
`when` is a reference path, written without braces:
|
||||
|
||||
- `steps.assess.result.fit` holds when the value is true, a non-empty string other than `false`, or a non-zero number.
|
||||
- `!steps.assess.result.fit` holds when it does not.
|
||||
- `steps.classify.result.workflow == tdd` and `!=` compare the value as text.
|
||||
|
||||
### Parallel branches
|
||||
|
||||
```yaml
|
||||
- id: research
|
||||
parallel:
|
||||
code: [{id: code, type: agent.run, settings: {mission: ..., read_only: true}}]
|
||||
docs: [{id: docs, type: agent.run, settings: {mission: ..., read_only: true}}]
|
||||
- type: agent.run
|
||||
settings: {mission: "{{ steps.code.summary }} {{ steps.docs.summary }}"}
|
||||
```
|
||||
|
||||
Branches share one worktree, so only read-only `agent.run` and `workflow.call`
|
||||
steps may run in them. A branch sees the steps before the parallel step and its
|
||||
own earlier steps, never a sibling's. Every branch's results are visible after
|
||||
it. Parallel steps do not nest, and need at least two branches.
|
||||
|
||||
### How a run ends
|
||||
|
||||
A run ends at the first step that sets an outcome: `workflow.finish`,
|
||||
`workflow.handoff`, `human.approve`, `repo.open-pr`, `repo.commit` with
|
||||
`if_empty: complete`, or `review.reply`. A run that reaches the end of its steps
|
||||
completes, with the last step's summary as its detail. A step that fails parks
|
||||
the run unless it continues on failure.
|
||||
|
||||
## Step types
|
||||
|
||||
### `agent.run`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `extra_rules` | text | Appended to the agent system prompt. |
|
||||
| `gate` | `repository` \| `test-failure` | Hold the agent to the repository gate before it may finish; test-failure requires the tests to fail. |
|
||||
| `mission` | text | What the agent is asked to do. May reference {{ task.* }}, {{ inputs.* }} and {{ steps.<id>.* }}. |
|
||||
| `protect_tests` | bool | Write-block the repository test files. |
|
||||
| `read_only` | bool | Restrict the agent to read-only tools. |
|
||||
| `result` | mapping | A JSON Schema object the agent must return; later steps read it as steps.<id>.result. |
|
||||
| `role` | text | Which configured model role runs the agent, e.g. builder or planner. Empty means builder. |
|
||||
|
||||
### `command.run`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `level` | `error` \| `warn` | error stops the run on a failing command; warn reports it and continues. |
|
||||
| `run` | list of mapping | The commands to run in order; the first failure ends the step. |
|
||||
|
||||
### `repo.commit`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `if_empty` | `fail` \| `skip` \| `complete` | fail stops the run, skip moves on, complete closes the issue and ends the run. |
|
||||
| `message` | text | The commit message. |
|
||||
| `push` | bool | Push the branch after committing. |
|
||||
| `reference` | `Fixes` \| `Implements` \| `Refs` | How the commit links to the task issue. |
|
||||
|
||||
### `repo.open-pr`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `body` | text | The pull request description. |
|
||||
| `review` | bool | Review the change first; a blocking finding parks the task instead of opening the PR. |
|
||||
|
||||
### `repo.prepare`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `branch` | `fresh` \| `task` | fresh starts a new branch from the base; task resumes the branch this task pushed. |
|
||||
|
||||
### `gate.diff-rules`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `rules` | list of mapping | Patterns the change must not match. |
|
||||
|
||||
### `gate.diff-size`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `gate.repository`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `expect` | `pass` \| `test-failure` | pass requires every gate command to pass; test-failure requires the test command to fail. |
|
||||
| `repair` | bool | Let the builder fix a failing gate before the step fails. |
|
||||
|
||||
### `forge.close-issue`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `forge.comment`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `body` | text | The comment text. |
|
||||
| `on` | `issue` \| `pr` | Comment on the issue or the pull request. Empty means issue. |
|
||||
|
||||
### `human.approve`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `plan` | text | What the human decides on; the next workflow reads it as task.plan. |
|
||||
| `then` | text | The workflow the task runs once approved. |
|
||||
|
||||
### `review.pr`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `review.reply`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `body` | text | The reply to the review. |
|
||||
|
||||
### `review.start-round`
|
||||
|
||||
_needs a repository._
|
||||
|
||||
No settings.
|
||||
|
||||
### `workflow.call`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `inputs` | mapping | |
|
||||
| `outputs` | mapping | |
|
||||
| `wait` | bool | Wait for the child run to finish before continuing. |
|
||||
| `workflow` | text | The workflow to start as a child run. |
|
||||
|
||||
### `workflow.finish`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `detail` | text | What the operator reads about the outcome. |
|
||||
| `status` | `completed` \| `parked` \| `waiting_human` \| `declined` | How the run ends. Empty means completed. |
|
||||
|
||||
### `workflow.handoff`
|
||||
|
||||
_runs without a repository._
|
||||
|
||||
| Setting | Type | Meaning |
|
||||
|---|---|---|
|
||||
| `detail` | text | Why the task was handed off. |
|
||||
| `workflow` | text | The workflow the task is requeued under. |
|
||||
|
||||
`command.run` commands are `{name, argv, expect_failure}`: `argv` is the
|
||||
program and its arguments, and `expect_failure` requires a non-zero exit.
|
||||
|
||||
`gate.diff-rules` rules are `{id, level, pattern, path, exclude_path, message}`:
|
||||
`level` (`error` blocks, `warn` reports) and `pattern` (an RE2 expression matched
|
||||
against each added line) are required; `path` and `exclude_path` are RE2
|
||||
expressions that limit which files the rule applies to.
|
||||
|
||||
## What starts a workflow
|
||||
|
||||
- **Issues**, by label: `bug` runs `tdd`, `feature` runs `feasibility`, anything
|
||||
else runs `triage`, which classifies it and hands off.
|
||||
- **Event bindings**: a webhook source mapped onto a workflow and its inputs
|
||||
(Events page).
|
||||
- **Playbooks**: a trigger (issue kind and labels) and actions that dispatch
|
||||
workflows.
|
||||
- **Other workflows**: `workflow.call` (a child run), `workflow.handoff` (the
|
||||
same task, requeued), `human.approve` (once approved).
|
||||
- **By hand**: the New task form, or Run on the Workflows page.
|
||||
|
||||
The canvas Start node lists the triggers of each workflow.
|
||||
Reference in new issue
Block a user