CANBAN

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 + 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.
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)

KeyType & DefaultPurpose
schemau32 (required; 10 is CURRENT)Schema version (1..=10 accepted and migrated to 10).
idString (required)Non-empty workflow identifier (e.g., delivery:default).
nameString (required)Display name shown in Studio and Boards.
scopeproject (default) or globalglobal (__global) runs host-level schedules/scripts without Board columns or card: creation rules.
enabledbool (default true)Enables or disables rule matching for this workflow source.
columnslist of { id, name }Declares Board columns (id allows ASCII alphanumeric, -, _). Defaults to Project columns when omitted.
env{ KEY: VALUE } mapScalar 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.
stepslist of Step (1..=256)Ordered step definitions forming a directed acyclic automatic graph.
workspaceWorkspaceSettingscreate_worktree (default true), base_branch, sync_base (requires create_worktree: true), remote (default origin).
max_stepsu32 (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:)

useswith & step fieldsRuntime behavior
agentwith.profile (optional Profile ID), with.instruction (optional; resolves built-in prompt when omitted), env, nextDispatches 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, nextRuns via Herdr Core without consuming scheduler.max_agents. Reads $CANBAN_ENV (inputs.env) and $CANBAN_OUTPUT (outputs.<step_id>).
admitwith.agent_slot (bool, default true), with.max_ready (1..=100, optional), nextEnters waiting_capacity; AppServer releases runs in Board order when capacity is available.
card.movewith.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.
conditionwith.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).
approvalwith.title (non-empty string), on_changes_requested (optional rework step ID), nextPauses in waiting_approval and sets Card.human_gate until approved or sent for rework.
deliverwith.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, nextEnters serialized FIFO Queue Merge (waiting_delivery). Pauses in waiting_approval immediately if card.hold_auto_merge is set.
notifywith.message, nextEmits 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 for --global workflow flags, schedule commands, and --human formatting.