- 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.
2 KiB
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,
needsdependencies, 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.