CANBAN // DOCS // WORKFLOWS
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+ immutableworkflow_revisions) rather than hidden YAML files in~/.canban. EachWorkflowRunfreezes itsdefinitionanddefinition_revisionat creation so publishing new YAML never mutates in-flight runs. - Linear Schema Migrations (
1..=10):crates/workflow-engine/src/migrations.rssetsBASELINE = 1andCURRENT = 10, sequentially upgrading older YAML documents on parse. - How Visual Studio Maps Stages (
stages.rs): YAML files do not have a top-levelstages:block; instead,canban_workflow_engine::stagesderives one Stage swimlane (StageView) per Board column (column,name, orderedsteps,entry_rule, andexitviacard.moveusingcolumn: $next/next: $entryorStay). EachStepcan setstage: <column_id>explicitly (or let Studio infer it fromoncolumn entry rules andcard.movetransitions) andenabled: falseto skip a step at compile time without breaking links.

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), andenabled(bool, defaulttrue). - Schedule triggers: Set
cron(5-field POSIX cron or@hourly/@daily/@weekly/@monthly) to mark a rule asevent: schedule. Optionaltimezone(Localdefault,UTC, fixed offset like+08:00, or IANA name),overlap(skipdefault,queue,allow), andcard: { column, title, body }(with{{date}},{{datetime}},{{run_number}},{{workflow}},{{rule}}placeholders; omitcardfor Cardless runs).
steps[] fields
- Common keys:
id(unique non-empty string),name,uses(optional when top-levelrun:is present),with,next(defaults to next list item except forconditionandcomplete;card.movemay use$entry),stage(optional column ID),enabled(bool, defaulttrue),on_changes_requested(top-level rework target onapproval/deliver),on_failure(top-level single-use automatic fallback step ID onscriptsteps). script-only keys accepted at step top-level or insidewith:(without conflicting values):run,shell(defaultbash -eo pipefail, fallbacksh -e),working_directory(relative to Card workspace, no..),timeout_minutes(1..=1440),timeout_seconds(1..=86400),continue_on_error(bool, defaultfalse).env:{ KEY: VALUE }map, valid only onagentandscriptsteps. Precedence order: host &CANBAN_*context < workflowenv<$CANBAN_ENVexports < stepenv.
Canonical development.yaml (default_document)
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: originAll 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 againstnull. - External PR gate:
pointer: /card/source_trustwithequals: external_prroutes untrusted PRs toapproval:reviewwhile sending trusted branches todeliver:review. - Script output branching: Any
KEY=VALUEwritten to$CANBAN_OUTPUTin a priorscriptstep is stored at/outputs/<step_id>/<KEY>, e.g.,pointer: /outputs/script:check/gatewithequals: 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, default8) is free.max_ready: K: Caps how many Cards that already passed this gate may remain in that column (for example, gating Backlog planning atmax_ready: 2).canban card adopt: Claiming a live interactive session viastart_adoptedbypassesadmitgates 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 onapprovalanddeliversteps (compiles torework). Requesting changes (workflow.decidewithdecision: "rework") clearshuman_gate, saves optional reviewer notes intoinputs.rework_feedback, and routes back to the target step (e.g.,agent:develop). - Script fallback (
on_failure): When ascriptstep fails (continue_on_error: false),fail_scriptrecords exit code and log tail feedback (rework_origin: "script_failure") and jumps toon_failureat most once per run (script_failures[step_id] == 0). A second consecutive failure (or unconfiguredon_failure) pauses inwaiting_approvalfor human Retry, Rework, or Stop. - Agent reporting & stale detection: Terminal exit or idle never advances
agentsteps.canban report --state completedadvances tonext;blocked/failedmoves the run toblocked;backlogcancels the run. Modifying Card title/body/content mid-run changesinput_digestand marks completionstaleuntil 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:
- Strict FIFO Queue Order: Drains
waiting_deliveryruns in(inputs.queued_at, storage_index)order, grouping up tobatch_size(1..=50, default5) compatible queue-head Cards (target_branch,strategy,sync_upstream,test_command, and conflictprofile) into<home>/worktrees/<project-ns>/_merge_queue. - Agent Turn-Settle Guard: If an Agent invoked
canban report --state completedmid-turn while Herdr still reports active work, Canban waits for the turn to settle (bounded by a 3-minute grace window) before integrating. - Integrate & Verify: Applies
strategy(rebasedefault,squash, or--first-parentmerge), then runstest_commandonce on the integrated batch if configured (skipped when unset). - Fast-Forward, Push & Archive: Clean batches fast-forward the target branch once, push once when
sync_upstream: true, and auto-archive merged Cards after savingrefs/canban/cards/<card-id>. - Conflict Resolution (
@merger): On batch conflict or test failure, Canban persistsMergeBatchandrefs/canban/batch/<short_id>/{target,card-<N>}, marks participating runswaiting_batch, and dispatches one Project-scoped@mergersession in_merge_queue(which can fix in place or evict a failing Card viacanban batch report --state completed --evict <CARD_NUMBER>). Single-Card deliveries withouttest_commandresolve directly in the Card worktree up tomax_conflict_attempts(default3,0disables).
Managing workflows via CLI
Inspect, validate, export, and publish workflows from the terminal (or query the live schema contract via workflow.schema):
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 for --global workflow flags, schedule commands, and --human formatting.