ContextQMD
Back to Beads

Workflows

website/docs/workflows/index.md

1.0.31.9 KB
Original Source

Workflows

Beads provides powerful workflow primitives for complex, multi-step processes.

Chemistry Metaphor

Beads uses a molecular chemistry metaphor:

PhaseStorageSyncedUse Case
Proto (solid)Built-inN/AReusable templates
Mol (liquid).beads/YesPersistent work
Wisp (vapor).beads-wisp/NoEphemeral operations

Core Concepts

Formulas

Declarative workflow templates in TOML or JSON:

toml
formula = "feature-workflow"
version = 1
type = "workflow"

[[steps]]
id = "design"
title = "Design the feature"
type = "human"

[[steps]]
id = "implement"
title = "Implement the feature"
needs = ["design"]

Molecules

Work graphs with parent-child relationships:

  • Created by instantiating formulas with bd pour
  • Steps have dependencies (needs)
  • Progress tracked via issue status

Gates

Async coordination primitives:

  • Human gates - Wait for human approval
  • Timer gates - Wait for duration
  • GitHub gates - Wait for PR merge, CI, etc.

Wisps

Ephemeral operations that don't sync to git:

  • Created with bd wisp
  • Stored in .beads-wisp/ (gitignored)
  • Auto-expire after completion

Workflow Commands

CommandDescription
bd pourInstantiate formula as molecule
bd wispCreate ephemeral wisp
bd mol listList molecules
bd pinPin work to agent
bd hookShow pinned work

Simple Example

bash
# Create a release workflow
bd pour release --var version=1.0.0

# View the molecule
bd mol show release-1.0.0

# Work through steps
bd update release-1.0.0.1 --claim
bd close release-1.0.0.1
# Next step becomes ready...