DevSpace workflows

Use a workflow when a task has a repeatable multi-agent plan. Keep one-off delegation on the subagents commands.

Named workflows live in the current project's .devspace/workflows/ directory.

Write a workflow

Before writing or editing a workflow script, read reference.md next to this file. It defines the only syntax and primitives the sandbox accepts (agent, phase, parallel, pipeline, workflow, log, args), the meta rules, agent options, structured output schemas, and limits. Do not guess the API.

Then read patterns.md for proven engineering loops to adapt: plan with a critic, implement-review-fix until approved, a QA gate that loops until tests pass, explore-then-synthesize, multi-lens review with verified findings, bake-offs between agents, mapping one change over many units, debugging with competing hypotheses, and composing them.

Run a workflow

Run a named workflow or a specific file:

devspace workflow run --name <name> [--args '<json>']
devspace workflow run --file <path> [--args-file <path>]

The command returns a compact <workflow id="..." status="..."/> receipt. Keep the ID. Workflow code is read-only by default; add --write-mode allowed only when the workflow must modify the project.

Wait up to 60 seconds at a time. Repeat wait if the returned status is still running; do not poll status in a loop.

devspace workflow wait <id> --timeout 60

Inspect current state, calls, or one full call when needed:

devspace workflow status <id>
devspace workflow calls <id>
devspace workflow call <id> <index>
devspace workflow events <id> --after <last-sequence>
devspace workflow ls

events returns at most 100 persisted log and phase entries. Keep the highest sequence and pass it with --after for the next page.

Cancel only when the parent task no longer needs the run:

devspace workflow cancel <id>