Workflows

Workflows are a braid-specific prompt type. Unlike rules and skills — which map directly to concepts most agents already support — workflows are a braid primitive that compiles down to each agent’s native format at install time.

They combine sequenced instructions, decision points, and verification steps to guide an agent through a complex task end-to-end.

When to use workflows

Use workflows for tasks that involve multiple steps with a defined order:

• Deployment checklists (“ship a release to production”)
• Onboarding procedures (“set up a new developer environment”)
• Incident response runbooks (“diagnose and resolve a production outage”)
• Migration guides (“upgrade from v2 to v3”)

How workflows differ from skills

A skill teaches an agent how to do one thing well. A workflow orchestrates multiple steps in sequence, often invoking skills along the way.

How workflows work

1. You build a workflow visually in braid using steps, conditionals, loops, and skill references
2. braid install compiles it into a skill bundle — a SKILL.md manifest, a workflow.json graph, and individual step files
3. The agent follows transitions step by step, branching on conditionals and loading referenced skills as needed

Node types

Workflows are directed graphs. Each node has a type that controls execution:

Installed structure

When installed, a workflow compiles into a skill bundle:

workflow-deploy-release-abc123/
  SKILL.md            # Entry point with step index
  workflow.json       # Full graph manifest
  steps/
    01-run-tests.md         # prompt node
    02-check-coverage.md    # conditional node
    03-build-artifacts.md   # prompt node
    04-deploy-staging.md    # skill_ref → deploy-to-env
    05-verify-staging.md    # prompt node
    06-deploy-production.md # skill_ref → deploy-to-env

Example: SKILL.md

The root SKILL.md indexes the steps and tells the agent how to navigate:

---
name: workflow-deploy-release-abc123
description: Ship a release to production with verification gates
license: UNLICENSED
compatibility: opencode
metadata:
  artifact: "workflow"
  flowId: "abc123"
  publishedVersion: "v3"
---

# Deploy Release

Start at `steps/01-run-tests.md` and follow transitions from each step.
Load referenced skills before executing them.
Stop and ask the user for input when a step requires user input.
Only execute a branch when its transition is selected.

## Entry Step

- `steps/01-run-tests.md` - Run Tests

## Available Steps

- `steps/01-run-tests.md` - Run Tests
- `steps/02-check-coverage.md` - Check Coverage
- `steps/03-build-artifacts.md` - Build Artifacts
- `steps/04-deploy-staging.md` - Deploy to Staging
- `steps/05-verify-staging.md` - Verify Staging
- `steps/06-deploy-production.md` - Deploy to Production

Example: conditional step

A conditional step like steps/02-check-coverage.md branches the flow:

# Check Coverage

- Node type: `conditional`
- Requires user input: no

## Instruction

Evaluate the condition and choose the matching branch transition.

## Next Actions

- Evaluate the condition expression against current variables.
- Choose one transition: Then branch -> build-artifacts, Else branch -> fix-coverage.
- Persist chosen branch in workflow progress metadata.

## Transitions

- Then branch -> `build-artifacts`
- Else branch -> `fix-coverage`

Example: skill_ref step

A step like steps/04-deploy-staging.md loads another skill:

# Deploy to Staging

- Node type: `skill_ref`
- Load skill: `deploy-to-env`
- Requires user input: yes

## Instruction

Load the referenced skill guidance, execute it, and persist the resulting output.

## Next Actions

- Run the instruction text and produce the step output.
- Persist progress with currentNodeId/currentStepLabel after completion.
- Choose one transition: Path 1 -> verify-staging.

Where workflows are installed