ContextQMD
Back to Beads

Workflows

website/versioned_docs/version-1.0.0/workflows/index.md

1.0.33.0 KB
Original Source

Workflows

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

Chemistry Metaphor

Beads uses a molecular chemistry metaphor for workflow phases:

PhaseCommandSyncedUse Case
Proto (solid)bd cookN/ACompiled template, reusable
Mol (liquid)bd mol pourYesPersistent work with audit trail
Wisp (vapor)bd mol wispNoEphemeral operations

Core Concepts

Formulas

Declarative workflow templates in TOML or JSON. Support variables, conditional steps, loops, inheritance, and composition.

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"]

Cooking

bd cook compiles a formula into a resolved proto. Two modes: compile-time (keeps {{var}} placeholders for planning) and runtime (substitutes all variables for final output).

Molecules

Work graphs with parent-child relationships:

  • Created by instantiating formulas with bd mol 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:

  • Created with bd mol wisp
  • Stored locally with Ephemeral=true
  • Lifecycle: squash (promote), burn (discard), or GC (auto-clean)

Swarms

Parallel execution across an epic's dependency graph:

  • Analyze epic structure for parallelism: bd swarm validate
  • Create coordinated swarm from epic: bd swarm create
  • Monitor progress across waves: bd swarm status

Workflow Commands

CommandDescription
bd cookCompile formula into proto
bd mol pourInstantiate formula as persistent molecule
bd mol wispCreate ephemeral wisp from formula
bd mol listList molecules
bd mol squashPromote wisp to persistent molecule
bd mol burnDelete wisp without trace
bd mol wisp gcGarbage collect old wisps
bd mol bondBond formulas together with phase control
bd swarm validateAnalyze epic for parallel execution
bd swarm createCreate swarm from epic
bd swarm statusShow swarm progress
bd swarm listList all swarm molecules
bd formula listList available formulas

Simple Example

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

# View the molecule
bd dep tree bd-xyz

# Work through steps
bd update bd-xyz.1 --claim
bd close bd-xyz.1
# Next step becomes ready...
  • Molecules - Work graphs and execution
  • Formulas - Declarative templates (types, variables, inheritance, loops, conditions)
  • Gates - Async coordination
  • Wisps - Ephemeral operations (squash, burn, GC lifecycle)