Workflow builder

Goal: Compose, test, and publish a governed workflow in Companion using the native workflow_builder canvas. Adapted from the internal guide; every path below is a real /v1/builder/* route.

Open the builder

From Companion chat: “Open the workflow builder”, “Create a new automation”, or “Edit workflow <id>”. These resolve to builder.edit_workflow / builder.create_workflow and emit a workflow_builder canvas. Command Plane /builder routes redirect here — the builder home is Companion only.

Blank canvas

A new workflow shows three CTAs: Describe it (natural-language compose), Start from template (marketplace gallery), Add first step (node palette). There is no empty grey board.

Natural-language compose

Type intent in the compose strip. Companion POSTs /v1/builder/workflows/intent or /from-companion and loads the returned manifest as an editable draft. Use Regenerate or Accept on the proposal strip.

Node palette

The Canvas tab lists capabilities (POST /v1/builder/workflows/:id/resolve-capabilities), muscles (GET /v1/builder/marketplace/muscles), connector steps (GET /v1/builder/marketplace/connectors), and human approval. Changes autosave via the silent canvas action channel (debounced PUT with manifest.canvas_layout).

Test

POST /v1/builder/workflows/:id/test with mode: dry_run | sample_data | live_safe. Resolution uses HumanOS — not stub confidences. Per-node overlay: resolved_to, confidence, policy.

Publish

Server-enforced publish subset: draft → tested → published → active (kb/136 names ten stages from Intent through Scaled; publish uses this four-state gate). POST /v1/builder/workflows/:id/publish fails closed until the readiness checklist passes. Activate / deactivate via /activate and /deactivate.

API quick reference

GET    /v1/builder/workflows
POST   /v1/builder/workflows
PUT    /v1/builder/workflows/:id
POST   /v1/builder/workflows/:id/test
POST   /v1/builder/workflows/:id/publish
POST   /v1/builder/workflows/:id/activate
GET    /v1/builder/workflows/:id/triggers
POST   /v1/builder/workflows/:id/triggers
GET    /v1/builder/workflows/:id/runs

Export: human workflow export <workflow-id> --language typescript. Errors use RFC 7807 Problem Details.