beads/docs/workflows/index.md
Chris Sells 54a7547b0d docs: canonical concept page, section overviews, and concept diagrams
- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one
  canonical concept page (modeled on Gas City's how-gas-city-works):
  problem-first framing, the bead -> dependencies -> ready-work loop, hash
  IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync,
  federation, and storage modes, led by four mermaid diagrams. Other pages
  link here instead of re-deriving the model.
- Fact fixes caught while writing (verified against source/live help):
  hash IDs are content-derived SHA-256 (internal/types/id_generator.go),
  not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real
  surface is bd mol pour, bd mol wisp, bd assign, bd update --claim);
  wisps are not stored in .beads-wisp/; cross-repo dependency syntax is
  external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed
  SQLite errors in a Dolt product.
- Section overview pages: rewrite workflows/index, extend recovery,
  multi-agent, and integrations indexes to list every child with one-line
  summaries; add reference/index and put it in the nav.
- New concept diagrams: sequential-vs-hash ID merge collision
  (core-concepts/hash-ids) and embedded-vs-server mode
  (architecture/dolt).
- website/README.md: real build/verify instructions and parallel-run
  status for the Docusaurus site.
- Repoint example READMEs and page labels at the real quickstart page.
2026-07-12 10:37:07 -07:00

2 KiB

title description
Workflows Declare multi-step work once as a formula, then stamp it out as molecules of real, dependency-ordered beads.

Repeatable multi-step work — a release checklist, a feature pipeline, a review process — shouldn't be re-planned by hand every time. Beads lets you declare the shape once and instantiate it on demand: a formula (TOML source) is cooked into a proto (template), and the proto is poured into a molecule — real beads whose steps flow through bd ready like any other work. The full pipeline is diagrammed in How Beads Works.

bd formula list                    # formulas visible on the search paths
bd cook release.formula.toml       # compile the formula into a proto
bd mol pour release --var version=1.2.0   # instantiate real work
bd ready --mol <mol-id>            # which steps can run right now

The three phases, in the chemistry metaphor the CLI uses:

Phase What it is Lifecycle
Proto (solid) template epic with {{variables}}, carries the template label reusable, not live work
Molecule (liquid) persistent beads poured from a proto (bd mol pour) synced like any bead
Wisp (vapor) ephemeral instantiation (bd mol wisp) excluded from federation push by default; deleted by bd purge

Pages in this section

  • Molecules — instantiated work graphs: pouring, inspecting, bonding, and squashing molecules.
  • Formulas — the TOML/JSON source format: steps, needs dependencies, variables, and composition rules.
  • Gates — async wait conditions (human, timer, GitHub run/PR, cross-rig bead) that park a step until the world catches up.
  • Wisps — ephemeral molecules for transient operational work that shouldn't clutter history.
  • TODO Command — bd todo, the lightweight interface for managing TODO items as task beads.