584608a14e
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
167 lines
2.5 KiB
Markdown
167 lines
2.5 KiB
Markdown
---
|
|
id: molecules
|
|
title: Molecules
|
|
sidebar_position: 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
|
|
|
|
```bash
|
|
# Pour a formula into a molecule
|
|
bd pour <formula-name> [--var key=value]
|
|
```
|
|
|
|
**Example:**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
bd mol list
|
|
bd mol list --json
|
|
```
|
|
|
|
### Viewing a Molecule
|
|
|
|
```bash
|
|
bd mol show <molecule-id>
|
|
bd dep tree <molecule-id> # Shows full hierarchy
|
|
```
|
|
|
|
## Working with Molecules
|
|
|
|
### Step Dependencies
|
|
|
|
Steps have `needs` dependencies:
|
|
|
|
```toml
|
|
[[steps]]
|
|
id = "implement"
|
|
title = "Implement feature"
|
|
needs = ["design"] # Must complete design first
|
|
```
|
|
|
|
The `bd ready` command respects these:
|
|
|
|
```bash
|
|
bd ready # Only shows steps with completed dependencies
|
|
```
|
|
|
|
### Progressing Through Steps
|
|
|
|
```bash
|
|
# Start a step
|
|
bd update bd-xyz.1 --status in_progress
|
|
|
|
# Complete a step
|
|
bd close bd-xyz.1 --reason "Done"
|
|
|
|
# Check what's ready next
|
|
bd ready
|
|
```
|
|
|
|
### Viewing Progress
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```toml
|
|
[compose]
|
|
[[compose.bond_points]]
|
|
id = "entry"
|
|
step = "design"
|
|
position = "before"
|
|
```
|
|
|
|
### Hooks
|
|
|
|
Execute actions on step completion:
|
|
|
|
```toml
|
|
[[steps]]
|
|
id = "build"
|
|
title = "Build project"
|
|
|
|
[steps.on_complete]
|
|
run = "make build"
|
|
```
|
|
|
|
### Pinning Work
|
|
|
|
Assign molecules to agents:
|
|
|
|
```bash
|
|
# Pin to current agent
|
|
bd pin bd-xyz --start
|
|
|
|
# Check what's pinned
|
|
bd hook
|
|
```
|
|
|
|
## Example Workflow
|
|
|
|
```bash
|
|
# 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 --status in_progress
|
|
|
|
# 4. Complete and progress
|
|
bd close bd-xyz.1
|
|
bd ready # Shows next steps
|
|
|
|
# 5. Continue until complete
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Formulas](/workflows/formulas) - Creating templates
|
|
- [Gates](/workflows/gates) - Async coordination
|
|
- [Wisps](/workflows/wisps) - Ephemeral workflows
|