beads/website/versioned_docs/version-1.0.0/workflows/molecules.md
Isaac Karrer 7f0a165f4e
feat(docs): version Docusaurus site and align llms-full with snapshots (#3033)
* feat(docs): version Docusaurus site and align llms-full with snapshots

Add docs version 1.0.0, version dropdown, lastVersion defaulting to stable,
merged markdown config, and RELEASING steps for future doc snapshots.
generate-llms-full.sh reads the latest entry in versions.json.

README links the published documentation site.

Closes #2644

Made-with: Cursor

* fix(docs): update org URLs to gastownhall and refresh 1.0.0 snapshot

- Update default orgName in docusaurus.config.ts from steveyegge to
  gastownhall to match the repo's new home
- Update hardcoded steveyegge URLs in generate-llms-full.sh
- Refresh versioned_docs 1.0.0 snapshot to include quickstart changes
  from #3032 which merged after the original snapshot was taken
- Regenerate llms-full.txt with corrected URLs and updated content

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 21:12:54 -07:00

2.4 KiB

id title sidebar_position
molecules Molecules 2

Molecules

Molecules are work graphs created from formulas.

What is a Molecule?

A molecule is a persistent instance of a formula:

  • Contains steps with dependencies
  • Tracked in .beads/ (syncs with git)
  • Steps map to issues with parent-child relationships

Creating Molecules

From Formula

# Pour a formula into a molecule
bd pour <formula-name> [--var key=value]

Example:

bd pour release --var version=1.0.0

This creates:

  • Parent issue: bd-xyz (the molecule root)
  • Child issues: bd-xyz.1, bd-xyz.2, etc. (the steps)

Listing Molecules

bd mol list
bd mol list --json

Viewing a Molecule

bd mol show <molecule-id>
bd dep tree <molecule-id>  # Shows full hierarchy

Working with Molecules

Step Dependencies

Steps have needs dependencies:

[[steps]]
id = "implement"
title = "Implement feature"
needs = ["design"]  # Must complete design first

The bd ready command respects these:

bd ready  # Only shows steps with completed dependencies

Progressing Through Steps

# Start a step
bd update bd-xyz.1 --claim

# Complete a step
bd close bd-xyz.1 --reason "Done"

# Check what's ready next
bd ready

Viewing Progress

# See blocked steps
bd blocked

# See molecule stats
bd stats

Molecule Lifecycle

Formula (template)
    ↓ bd pour
Molecule (instance)
    ↓ work steps
Completed Molecule
    ↓ optional cleanup
Archived

Advanced Features

Bond Points

Formulas can define bond points for composition:

[compose]
[[compose.bond_points]]
id = "entry"
step = "design"
position = "before"

Hooks

Execute actions on step completion:

[[steps]]
id = "build"
title = "Build project"

[steps.on_complete]
run = "make build"

Pinning Work

Assign molecules to agents:

# Pin to current agent
bd pin bd-xyz --start

# Check what's pinned
bd hook

Example Workflow

# 1. Create molecule from formula
bd pour feature-workflow --var name="dark-mode"

# 2. View structure
bd dep tree bd-xyz

# 3. Start first step
bd update bd-xyz.1 --claim

# 4. Complete and progress
bd close bd-xyz.1
bd ready  # Shows next steps

# 5. Continue until complete

See Also