Workflows

Declarative, versioned pipelines: phases, gates, defaults, and the status automation that drives them from the board.

A workflow declares the phases a run moves through and what each phase does. It's stored with your project on the host as plain YAML and edited in the visual workflow editor — in the extension's Workflows library or the dashboard — so the whole team shares one definition and every run is reproducible.

Anatomy

version: 1
id: feature            # stable identity — references never break on rename
name: Feature pipeline

phases:
  - id: spec
    title: Spec
    gate: true                       # park for human review after the spec
    steps:
      - type: prompt
        prompt: Write a short spec for the task. List the files you expect to touch.

  - id: coding
    title: Coding
    gate: true
    steps:
      - { type: command, name: install, run: pnpm install }
      - { type: prompt, prompt: Implement the approved spec. }
      - { type: check, name: lint, run: pnpm lint }
      - { type: check, name: test, run: pnpm test }

  - id: merge
    title: Merge
    terminal: true
    steps:
      - { type: git, action: merge, method: squash }
      - { type: notify, to: [slack], message: Merged and shipped. }

A project keeps as many workflows as it likes; each run selects one. With no workflows defined at all, a built-in spec → coding → merge pipeline applies, so a fresh project runs out of the box.

Phases

  • gate: true — when the phase's steps finish, the run parks until a human approves or requests changes. Who may approve is the phase's approvers policy — see Gates & reviews.
  • terminal: true — marks the closing phase (the editor keeps exactly the last phase terminal; a terminal phase can't gate).
  • Steps run in order; eight types cover the pipeline — see the step reference.

Identity, order, and the default workflow

A workflow's identity is its id — stable and immutable. Renaming changes only the display name; every task and routing rule keeps pointing at the same workflow. There is no magic filename either: the project's default workflow is simply the first one by its order, which is what an unpinned task or a routing rule's fallback resolves to.

Defaults

defaults:
  agent: { provider: claude, model: opus-4.8, effort: high }
  systemPrompt: Never touch files under legal/.
  basePrompt: Keep diffs small; follow the repo architecture docs.
  cacheWorkspace: true
secrets: [NPM_TOKEN, SENTRY_AUTH_TOKEN]
  • agent — the provider/model/effort every prompt-driven step inherits; any step can override it. See Agents & models.
  • systemPrompt — standing instructions for every agent in the run. When both exist, the workflow's value replaces the project system prompt.
  • basePrompt — additive workflow conventions, layered on top: project prompt → base prompt → the step's persona.
  • cacheWorkspace — the warm workspace cache for install-heavy repos.
  • secrets — names of organization secrets to inject into the run's environment, need-to-know: only what's listed resolves. Values never appear in YAML.

Status automation: the board drives execution

Phases bind to board columns, and the binding works both ways:

phases:
  - id: spec
    title: Spec
    gate: true
    onStatus: in-spec          # entering "In Spec" starts the workflow at this phase
    setStatus: in-spec-review  # when the phase's work finishes, the task moves here
    steps: […]
  • onStatus — a task dragged into that column starts this workflow at this phase (mid-pipeline entry is fine); and while the phase runs, the task shows that status, so the board always mirrors the active phase.
  • setStatus — where the task lands when the phase's work completes.

Statuses are origin-qualified. A bare ref like in-spec means your own board (peractor:in-spec); a tracker's real column is referenced as <connector>:<Column> — and a list holds one ref per tracker, so a single workflow can drive tasks from several origins, each in its own vocabulary:

onStatus:
  - peractor:queued
  - "linear-a1b2c3:Todo"
setStatus:
  - peractor:building
  - "linear-a1b2c3:In Progress"

With those two fields, dragging a card across the board is what starts, advances, and files work — in Peractor or in the connected tracker.

Next: the step reference · Gates & reviews