Workflow Builder

Workflow Builder Skill

Use this skill when the user wants to compose multiple agents into a repeatable workflow such as draft → review → judge, judge-and-retry, parallel reviews followed by a merge, or any other bounded coordination of agents.

This skill authors and operates workflows through the OpenColab CLI. It is not the workflow engine itself. The CLI/runtime owns parsing, execution, persistence, and human gate handling.

Source of truth

• Workflow definitions live at:

projects//workflows//workflow.xml

• Workflow runs live at:

projects//workflows//runs//

• Each run folder contains RUN.md (with YAML frontmatter), state.json,

status.json, events.jsonl, inputs/initial.md, and steps//.

Never edit state.json, status.json, or events.jsonl by hand. They are written by the runtime.

Allowed step types

• agent — runs one project agent with a generated prompt. Required:

id, type="agent", agent, `. Optional: `.

• decision — runs one project agent and expects a strict

` line in the response. Required: id, type="decision", agent, , `.

• human_gate — pauses the run for human input. Required: id,

type="human_gate", `. Optional: allow="approve,stop,retry,edit,branch"`.

• merge — concatenates prior outputs into a single named value. Required: id,

type="merge", at least one `, `.

• terminate — explicitly ends the run with a status of success, failed,

or stopped.

Loops must be bounded

Every `` requires at least one of:

• maxIterations=""
• maxSteps=""
• maxRuntimeMinutes=""

Unbounded loops are rejected during validation.

Prompt references

Inside any `` you can use template variables:

• ${input.} — values supplied when starting the run.
• ${} — named outputs from prior steps (``).
• ${.output> — fallback reference for any step's raw output text.

Author a workflow

1. Decide which project agents will play each role (drafter, reviewer, judge).
2. Pick a template:

• blank for an empty scaffold
• review-loop for draft → review → judge with a bounded loop
• judge-and-retry for draft → judge → retry-or-stop

1. Run:

``bash opencolab workflow create --workflow-id --from review-loop ``

1. Edit the generated projects//workflows//workflow.xml to

reference real project agents, set the loop bound, and tighten prompts.

1. Validate before running:

``bash opencolab workflow validate --workflow-id ``

Run a workflow

opencolab workflow run --workflow-id  --input ""
# or
opencolab workflow run --workflow-id  --input-file inputs.json --wait true

--input is shorthand for { "task": "" }. For richer inputs, pass --input-file or --input-json '{"foo":"bar"}'.

--wait true blocks the CLI until the run reaches a terminal or paused state and streams events as they happen.

Observe a run

• Latest status snapshot:

``bash opencolab workflow status --run-id ``

• Tail events:

``bash opencolab workflow logs --run-id --follow ``

• List all runs:

``bash opencolab workflow runs ``

Stop, resume, approve

• opencolab workflow stop --run-id — cooperative stop.
• opencolab workflow resume --run-id — resume a paused run.
• opencolab workflow approve --run-id --decision continue|stop|retry|branch:|edit

— record a human gate decision. Use --values-json '{"task":"..."}' with --decision edit to update inputs before continuing.

Decision contract for decision steps

Decision agents must end their response with a single line that looks like:

• action: continue, stop, branch, needs_human, or fail.
• next: target step id when action="continue" or action="branch".
• reason: short justification; surfaced in events.jsonl and Studio.

You may use ` blocks under ` to give the agent a fixed menu. The agent can pick a choice by name via:

If the decision block is missing or invalid, the run pauses for human review by default (or fails if onInvalid="fail" was declared on the step).

Memory isolation

Workflow steps do not pollute normal agent chat memory. The runtime uses a workflow-scoped session identity for every agent call and surfaces results through the workflow's run folder, not the agent's memory/Session/.

Things to avoid

• Do not author workflows outside the project workflows directory.
• Do not invent step types beyond the supported list — the validator rejects

unknown tags and unsupported step type attributes.

• Do not skip loop bounds. Bounded loops are mandatory.
• Do not pretend this skill executes workflows. Always shell out to the CLI.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jimezsa
• Source: jimezsa/opencolab
• License: MIT
• Homepage: https://opencolab.ai/

Install and usage instructions live in the source repository linked above.