# Workflow Builder

> Author, validate, run, and oversee OpenColab project workflows that coordinate multiple agents through bounded loops, decisions, and human gates.

- **Type:** Skill
- **Install:** `agentstack add skill-jimezsa-opencolab-workflow-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jimezsa](https://agentstack.voostack.com/s/jimezsa)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jimezsa](https://github.com/jimezsa)
- **Source:** https://github.com/jimezsa/opencolab/tree/main/projects/SKILLS/workflow-builder
- **Website:** https://opencolab.ai/

## Install

```sh
agentstack add skill-jimezsa-opencolab-workflow-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
3. Run:
   ```bash
   opencolab workflow create --workflow-id  --from review-loop
   ```
4. Edit the generated `projects//workflows//workflow.xml` to
   reference real project agents, set the loop bound, and tighten prompts.
5. Validate before running:
   ```bash
   opencolab workflow validate --workflow-id 
   ```

## Run a workflow

```bash
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:

```xml

```

- `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:

```xml

```

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](https://github.com/jimezsa)
- **Source:** [jimezsa/opencolab](https://github.com/jimezsa/opencolab)
- **License:** MIT
- **Homepage:** https://opencolab.ai/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jimezsa-opencolab-workflow-builder
- Seller: https://agentstack.voostack.com/s/jimezsa
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.