Workflows

A workflow template is a named recipe: a desk, a description, steps, and an optional trigger. Applying it creates a parent task and child tasks on that desk. It does not run arbitrary code inside the template step. The shipped step type creates tasks.

Open Automations → Workflows (/settings/workflows). You can list templates, filter by status, and edit one in the drawer. The API is under /cockpit/api/workflows.

This screen is not Decision flows. Decision flows are a different object, on /settings/decision-flows.

Applying a template

workflow_apply (scope workflows:write) instantiates a template into tasks. In the product this is how a person or an agent starts the recipe against a project. Pass the template id and the context project (the desk the tasks should land on).

workflow_template_create upserts the template and its steps.

Triggers

A template can carry a declarative trigger: a predicate, a JSON input_schema, and a trigger_mode.

Mode	Behavior
shadow_match	Default. The predicate is evaluated and a would_start event is recorded. No tasks are created
live	The trigger may start the template. Switching a template to live is a deliberate cutover, not a casual toggle

So a saved trigger does not start work until that template is live. Inspect events with GET /cockpit/api/workflows/<id>/trigger/events. Dry-run with POST …/trigger/dry-run. Enqueue a manual run with POST …/trigger, or with MCP workflow_trigger.

workflow_trigger_describe returns the input contract for a template. The caller needs a token bound to the template's workspace.

Older activity-matching filters (metadata.filter) still exist on the classic enqueue path. New triggers should use the declarative trigger and input schema. Both can be present during this phase.

flow_start and flow_run_status are the lower-level pgflow run controls (scope workflows:write). Use the template tools unless you are operating a registered flow slug directly.

Scheduled tasks

task_scheduled_create and task_scheduled_enable (scope schedules:write, personal access token only) attach a cron schedule to a task, optionally pointing it at a workflow template. Enable it before the schedule fires. Routines under Agents → Routines are the other scheduler: a cron or instant job bound to a runtime. They are not workflow templates.

What is not in the product yet

Schedule-shaped and webhook-shaped triggers beyond the activity predicate, and a full retirement of the older per-flow doors, are not the behavior the app ships. If the drawer does not show a control, it is not a supported way to start work. The LLMs settings page is a placeholder and does not configure these templates.