# Workflow YAML Syntax & Execution Semantics

> Canban workflows are declarative YAML 1.2 graphs (`schema: 10`, `CURRENT` in `crates/workflow-engine`) stored in SQLite (`workflow_sources` and immutable `workflow_revisions`). Visual Studio, manual YAML edits, and Edit with agent all compile and validate through the exact same Rust engine.

## Visual Studio, SQLite source of truth & Stage projection

Open **Workflows** in any Project header to switch between **Visual Studio**, **YAML Source**, **History**, and **Edit with agent**:

- **SQLite Single Source of Truth**: Workflows live inside `canban.sqlite` (`workflow_sources` + immutable `workflow_revisions`) rather than hidden YAML files in `~/.canban`. Each `WorkflowRun` freezes its `definition` and `definition_revision` at creation so publishing new YAML never mutates in-flight runs.
- **Linear Schema Migrations (`1..=10`)**: `crates/workflow-engine/src/migrations.rs` sets `BASELINE = 1` and `CURRENT = 10`, sequentially upgrading older YAML documents on parse.
- **How Visual Studio Maps Stages (`stages.rs`)**: YAML files do not have a top-level `stages:` block; instead, `canban_workflow_engine::stages` derives one Stage swimlane (`StageView`) per Board column (`column`, `name`, ordered `steps`, `entry_rule`, and `exit` via `card.move` using `column: $next` / `next: $entry` or `Stay`). Each `Step` can set `stage: <column_id>` explicitly (or let Studio infer it from `on` column entry rules and `card.move` transitions) and `enabled: false` to skip a step at compile time without breaking links.

![Canban Workflows Visual Studio showing development.yaml with Backlog, Develop (@developer Implement), and Review (External PR check condition, Human approval, and Queue merge) lanes.](https://canban.dev/screenshots/workflow-studio.png)

*Visual Studio for development.yaml: Backlog, Develop (@developer), and Review stages with the /card/source_trust == external_pr branch, Human approval gate, and Rebase · Sync Queue merge.*

## Verified YAML structure (schema: 10)

Parsing uses `serde_yaml_ng` with `#[serde(deny_unknown_fields)]` on `Document`, `Step`, `WorkflowColumn`, `WorkflowRule`, `EventSelector`, and `ScheduleCardConfig`. Unknown fields are rejected before publication.

### Top-level `Document` keys (`crates/workflow-engine/src/source.rs`)

| Key | Type & Default | Purpose |
| --- | --- | --- |
| `schema` | `u32` (required; `10` is `CURRENT`) | Schema version (`1..=10` accepted and migrated to `10`). |
| `id` | `String` (required) | Non-empty workflow identifier (e.g., `delivery:default`). |
| `name` | `String` (required) | Display name shown in Studio and Boards. |
| `scope` | `project` (default) or `global` | `global` (`__global`) runs host-level schedules/scripts without Board `columns` or `card:` creation rules. |
| `enabled` | `bool` (default `true`) | Enables or disables rule matching for this workflow source. |
| `columns` | list of `{ id, name }` | Declares Board columns (`id` allows ASCII alphanumeric, `-`, `_`). Defaults to Project columns when omitted. |
| `env` | `{ KEY: VALUE }` map | Scalar environment variables inherited by all `agent` and `script` steps. |
| `on` | `{ <rule_id>: WorkflowRule }` (non-empty) | Event triggers (`event`, `start_at`, `match`, `enabled`) and cron schedules (`cron`, `timezone`, `overlap`, `card`). Also accepts GitHub Actions `on: { schedule: [{ cron: ... }] }` shorthand. |
| `steps` | list of `Step` (1..=256) | Ordered step definitions forming a directed acyclic automatic graph. |
| `workspace` | `WorkspaceSettings` | `create_worktree` (default `true`), `base_branch`, `sync_base` (requires `create_worktree: true`), `remote` (default `origin`). |
| `max_steps` | `u32` (`1..=1000`, default `100`) | Guardrail cap on total step visits per `WorkflowRun`. |

### `on.<rule_id>` triggers & scheduled rules

- **Event triggers**: `event` (`card.column_entered`, `card.column_left`, `card.created`, `card.updated`, `manual`, etc.), `start_at` (target step ID), `match` (`EventSelector`: `column`, `actor`, `origin`, `source_kind`, `reason`, `changed_fields`, `repository`, `subject`, `reply_to`, `include_related`, `include_initial`), and `enabled` (`bool`, default `true`).
- **Schedule triggers**: Set `cron` (5-field POSIX cron or `@hourly` / `@daily` / `@weekly` / `@monthly`) to mark a rule as `event: schedule`. Optional `timezone` (`Local` default, `UTC`, fixed offset like `+08:00`, or IANA name), `overlap` (`skip` default, `queue`, `allow`), and `card: { column, title, body }` (with `{{date}}`, `{{datetime}}`, `{{run_number}}`, `{{workflow}}`, `{{rule}}` placeholders; omit `card` for Cardless runs).

### `steps[]` fields

- Common keys: `id` (unique non-empty string), `name`, `uses` (optional when top-level `run:` is present), `with`, `next` (defaults to next list item except for `condition` and `complete`; `card.move` may use `$entry`), `stage` (optional column ID), `enabled` (`bool`, default `true`), `on_changes_requested` (top-level rework target on `approval` / `deliver`), `on_failure` (top-level single-use automatic fallback step ID on `script` steps).
- `script`-only keys accepted at step top-level or inside `with:` (without conflicting values): `run`, `shell` (default `bash -eo pipefail`, fallback `sh -e`), `working_directory` (relative to Card workspace, no `..`), `timeout_minutes` (`1..=1440`), `timeout_seconds` (`1..=86400`), `continue_on_error` (`bool`, default `false`).
- `env`: `{ KEY: VALUE }` map, valid only on `agent` and `script` steps. Precedence order: host & `CANBAN_*` context < workflow `env` < `$CANBAN_ENV` exports < step `env`.

### Canonical `development.yaml` (`default_document`)

```yaml
schema: 10
id: delivery:default
name: Development
enabled: true
columns:
  - id: backlog
    name: Backlog
  - id: develop
    name: Develop
  - id: review
    name: Review
on:
  develop:
    event: card.column_entered
    start_at: agent:develop
    match:
      column: develop
  review:
    event: card.column_entered
    start_at: condition:external_pr
    match:
      column: review
steps:
  - id: agent:develop
    name: Implement
    uses: agent
    with:
      profile: developer
    next: move:develop
  - id: move:develop
    name: Move to Review
    uses: card.move
    with:
      column: review
    next: condition:external_pr
  - id: condition:external_pr
    name: External PR check
    uses: condition
    with:
      pointer: /card/source_trust
      equals: external_pr
      then: approval:review
      otherwise: deliver:review
  - id: deliver:review
    name: Queue merge
    uses: deliver
    with:
      sync_upstream: true
    next: __end
    on_changes_requested: agent:develop
  - id: approval:review
    name: Human approval
    uses: approval
    with:
      title: External PR; human approval is required before merging
    next: __end
    on_changes_requested: agent:develop
  - id: __end
    uses: complete
workspace:
  create_worktree: true
  sync_base: true
  remote: origin
```

## All 9 step types (uses:)

| `uses` | `with` & step fields | Runtime behavior |
| --- | --- | --- |
| `agent` | `with.profile` (optional Profile ID), `with.instruction` (optional; resolves built-in prompt when omitted), `env`, `next` | Dispatches an Agent PTY in the Card worktree (`waiting_agent`). Advances only on `canban report --state completed`. |
| `script` (or `run:`) | `run`, `shell`, `working_directory`, `timeout_minutes`, `timeout_seconds`, `continue_on_error`, `env`, `on_failure`, `next` | Runs via Herdr Core without consuming `scheduler.max_agents`. Reads `$CANBAN_ENV` (`inputs.env`) and `$CANBAN_OUTPUT` (`outputs.<step_id>`). |
| `admit` | `with.agent_slot` (`bool`, default `true`), `with.max_ready` (`1..=100`, optional), `next` | Enters `waiting_capacity`; AppServer releases runs in Board order when capacity is available. |
| `card.move` | `with.column` (column ID or `$next`), `next` (step ID or `$entry`) | Moves Card (`origin: "workflow"`) without re-firing duplicate entry triggers; `$entry` jumps to target column's `on` start. |
| `condition` | `with.pointer` (JSON Pointer), `with.equals` (JSON value), `with.then` (step ID), `with.otherwise` (step ID) | Evaluates pointer against `{inputs, outputs, card}` and branches immediately. Ignores `next` (compiled `condition` has no `next` field). |
| `approval` | `with.title` (non-empty string), `on_changes_requested` (optional rework step ID), `next` | Pauses in `waiting_approval` and sets `Card.human_gate` until approved or sent for rework. |
| `deliver` | `with.profile` (default `@merger`), `with.target_branch`, `with.strategy` (`rebase` default, `squash`, `merge`), `with.sync_upstream` (`true` default), `with.batch_size` (`1..=50`, default `5`), `with.test_command`, `with.max_conflict_attempts` (default `3`, `0` disables), `on_changes_requested`, `next` | Enters serialized FIFO Queue Merge (`waiting_delivery`). Pauses in `waiting_approval` immediately if `card.hold_auto_merge` is set. |
| `notify` | `with.message`, `next` | Emits `workflow.notified` timeline event and attention notification, then continues to `next`. |
| `complete` | *(none)* | Terminal step marking the `WorkflowRun` `completed`. |

## Conditions, source_trust & admit gates

### Condition evaluation (`condition`)

During execution (`crates/workflow-engine/src/runtime.rs`), `condition` builds `{ "inputs": run.inputs, "outputs": run.outputs, "card": card }` (with `card.source_trust` populated from `Card::trust_level()` — `"local"`, `"collaborator"` for GitHub Issues, or `"external_pr"` for external GitHub PRs) and resolves `with.pointer` (must be empty or start with `/`):

- **Equality rules**: Matches exact JSON equality, string `"true"` / `"false"` against booleans, numeric strings against numbers, and an absent pointer against `null`.
- **External PR gate**: `pointer: /card/source_trust` with `equals: external_pr` routes untrusted PRs to `approval:review` while sending trusted branches to `deliver:review`.
- **Script output branching**: Any `KEY=VALUE` written to `$CANBAN_OUTPUT` in a prior `script` step is stored at `/outputs/<step_id>/<KEY>`, e.g., `pointer: /outputs/script:check/gate` with `equals: ok`.

### Capacity & ready-queue gates (`admit`)

`admit` validates that at least one of `agent_slot: true` or `max_ready: 1..=100` is enabled (`definition.rs`). Waiting runs enter `waiting_capacity` and are released by AppServer's admission pump (`canban_scheduler::admissions`) strictly in **Board order** within their column:

- `agent_slot: true` (default): Holds the Card until a global automatic Agent slot (`scheduler.max_agents`, default `8`) is free.
- `max_ready: K`: Caps how many Cards that already passed this gate may remain in that column (for example, gating Backlog planning at `max_ready: 2`).
- `canban card adopt`: Claiming a live interactive session via `start_adopted` bypasses `admit` gates so an active user terminal is never queued behind pending capacity.

## Validation, rework loops & failure handling

### Static validation rules (`definition.rs`)

Before saving or publishing, `validate_definition` verifies all column IDs, profile IDs, step targets, `sync_base` prerequisites (`create_worktree: true`), relative `working_directory` bounds, and **cycle freedom**: automatic cycles through `next`, `condition.then`, and `condition.otherwise` are rejected.

### Rework & failure edges

Loops are only permitted across explicit decision or failure boundaries:

- **Human rework (`on_changes_requested`)**: Available on `approval` and `deliver` steps (compiles to `rework`). Requesting changes (`workflow.decide` with `decision: "rework"`) clears `human_gate`, saves optional reviewer notes into `inputs.rework_feedback`, and routes back to the target step (e.g., `agent:develop`).
- **Script fallback (`on_failure`)**: When a `script` step fails (`continue_on_error: false`), `fail_script` records exit code and log tail feedback (`rework_origin: "script_failure"`) and jumps to `on_failure` **at most once per run** (`script_failures[step_id] == 0`). A second consecutive failure (or unconfigured `on_failure`) pauses in `waiting_approval` for human Retry, Rework, or Stop.
- **Agent reporting & stale detection**: Terminal exit or idle never advances `agent` steps. `canban report --state completed` advances to `next`; `blocked` / `failed` moves the run to `blocked`; `backlog` cancels the run. Modifying Card title/body/content mid-run changes `input_digest` and marks completion `stale` until human rework or stop.

## Serialized FIFO Queue Merge (deliver)

Entering `deliver` serializes delivery across parallel Card worktrees so branches never race against the target branch:

1. **Strict FIFO Queue Order**: Drains `waiting_delivery` runs in `(inputs.queued_at, storage_index)` order, grouping up to `batch_size` (`1..=50`, default `5`) compatible queue-head Cards (`target_branch`, `strategy`, `sync_upstream`, `test_command`, and conflict `profile`) into `<home>/worktrees/<project-ns>/_merge_queue`.
2. **Agent Turn-Settle Guard**: If an Agent invoked `canban report --state completed` mid-turn while Herdr still reports active work, Canban waits for the turn to settle (bounded by a 3-minute grace window) before integrating.
3. **Integrate & Verify**: Applies `strategy` (`rebase` default, `squash`, or `--first-parent` `merge`), then runs `test_command` once on the integrated batch if configured (skipped when unset).
4. **Fast-Forward, Push & Archive**: Clean batches fast-forward the target branch once, push once when `sync_upstream: true`, and auto-archive merged Cards after saving `refs/canban/cards/<card-id>`.
5. **Conflict Resolution (`@merger`)**: On batch conflict or test failure, Canban persists `MergeBatch` and `refs/canban/batch/<short_id>/{target,card-<N>}`, marks participating runs `waiting_batch`, and dispatches one Project-scoped `@merger` session in `_merge_queue` (which can fix in place or evict a failing Card via `canban batch report --state completed --evict <CARD_NUMBER>`). Single-Card deliveries without `test_command` resolve directly in the Card worktree up to `max_conflict_attempts` (default `3`, `0` disables).

## Managing workflows via CLI

Inspect, validate, export, and publish workflows from the terminal (or query the live schema contract via `workflow.schema`):

```sh
canban call workflow.schema '{}'
canban workflow sources --project-id <PROJECT_ID>
canban workflow export --project-id <PROJECT_ID> --name development.yaml --output development.yaml
canban workflow submit --project-id <PROJECT_ID> --revision <REVISION> --file development.yaml --check
canban workflow submit --project-id <PROJECT_ID> --revision <REVISION> --file development.yaml
canban workflow set-default --project-id <PROJECT_ID>
```

See [Canban CLI, Agent Optimization & --human](/docs/cli/) for `--global` workflow flags, `schedule` commands, and `--human` formatting.
