beads/website/versioned_docs/version-1.0.0/workflows/index.md
seanmartinsmith 2e0da589bb
docs: add missing workflow features to docs and regenerate llms-full.txt (#3250)
Add documentation for features implemented in Go source but missing
from the website docs:

formulas.md:
- Convoy formula type (multi-agent coordination)
- Formula inheritance (extends field)
- Conditional steps (condition field with truthy/negated/equality)
- Loop/iteration (count, range, until with max)
- Runtime expansion (on_complete with for_each)
- bd cook command (compile-time vs runtime modes)
- Expanded gate types and aspect composition

wisps.md:
- Squash lifecycle (bd mol squash - promote to persistent)
- Burn lifecycle (bd mol burn - delete without trace)
- Garbage collection (bd mol wisp gc)
- Corrected storage model (Ephemeral=true in main DB)
- Updated commands to match actual CLI surface

index.md:
- Added swarm commands (validate, create, status, list)
- Added cook command
- Added wisp lifecycle commands (squash, burn, gc)
- Added bond and formula list commands

Regenerated website/static/llms-full.txt via scripts/generate-llms-full.sh.

Before: 0 hits for swarm, convoy, cook, extends, condition, loop,
squash, burn, promote, for_each in llms-full.txt.
After: all terms present with substantive documentation.

Closes #3244
2026-04-20 18:16:30 -07:00

3.1 KiB

id title sidebar_position
index Workflows 1

Workflows

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

Chemistry Metaphor

Beads uses a molecular chemistry metaphor for workflow phases:

Phase Command Synced Use Case
Proto (solid) bd cook N/A Compiled template, reusable
Mol (liquid) bd mol pour Yes Persistent work with audit trail
Wisp (vapor) bd mol wisp No Ephemeral operations

Core Concepts

Formulas

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

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

Command Description
bd cook Compile formula into proto
bd mol pour Instantiate formula as persistent molecule
bd mol wisp Create ephemeral wisp from formula
bd mol list List molecules
bd mol squash Promote wisp to persistent molecule
bd mol burn Delete wisp without trace
bd mol wisp gc Garbage collect old wisps
bd mol bond Bond formulas together with phase control
bd swarm validate Analyze epic for parallel execution
bd swarm create Create swarm from epic
bd swarm status Show swarm progress
bd swarm list List all swarm molecules
bd formula list List available formulas

Simple Example

# 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...

Navigation

  • Molecules - Work graphs and execution
  • Formulas - Declarative templates (types, variables, inheritance, loops, conditions)
  • Gates - Async coordination
  • Wisps - Ephemeral operations (squash, burn, GC lifecycle)