Molecules

# .beads/formulas/feature.yaml
name: feature-workflow
steps:
  - title: "Design phase"
    type: task
    priority: 1
  - title: "Implementation"
    type: feature
    priority: 0
    depends_on: [0]  # Blocks on design phase
  - title: "Testing"
    type: task
    priority: 1
    depends_on: [1]  # Blocks on implementation
  - title: "Documentation"
    type: task
    priority: 2
    depends_on: [1]

# Verify default patrol formula
bd mol seed

# Verify specific formula
bd mol seed .beads/formulas/feature.yaml

# Verify custom formula from any path
bd mol seed ~/my-workflows/release.yaml

# Bond three issues in sequence
bd mol bond bd-a3f8 bd-b7c2 bd-d4f9

# Result: a3f8 → b7c2 → d4f9
# (b7c2 blocks on a3f8, d4f9 blocks on b7c2)

# Two implementation tasks block on design
bd mol bond bd-design bd-impl1 bd-impl2

# Result:
#         ┌─> impl1
# design ─┤
#         └─> impl2

# Testing blocks on implementation OR hotfix
bd mol bond --or bd-impl bd-hotfix bd-test

# Result: test proceeds when EITHER impl OR hotfix completes

# Bond types:
- formula + formula  # Compose workflows
- proto + mol       # Extend molecule
- mol + mol         # Merge molecules
- issue + issue     # Link issues (same as bd dep add)

# Ephemeral bond (for experimentation)
bd mol bond --ephemeral bd-a3f8 bd-b7c2

# Persistent bond (default)
bd mol bond --persistent bd-a3f8 bd-b7c2

# Show current position in active molecule
bd mol current

# Show specific molecule
bd mol current bd-mol-123

# Limit output to 20 steps
bd mol current --limit 20

# Show specific range
bd mol current --range 10-30

# Show only current section
bd mol current --context 5  # Show 5 steps before/after current

# Agent 1: Check position
bd mol current
# "You are at step 3/10: Implementation"

# Agent 1: Claim current step
bd ready --json | jq -r '.[0].id' | xargs bd update --claim

# Agent 2: Check position (after Agent 1 claims)
bd mol current
# "Step 3 is claimed by agent-1. Next ready: Step 5"

# Distill molecule to formula
bd mol distill bd-mol-123 --output .beads/formulas/my-workflow.yaml

# Distill with variable substitution
bd mol distill bd-mol-123 --vars --output feature-template.yaml

# Issues with similar titles get variables
bd create "Add auth to API" -p 0
bd create "Add auth to UI" -p 0
bd create "Add auth to CLI" -p 0

# Distill creates:
# "Add {{component}} to {{feature}}"

# You've done this workflow 5 times manually
# Distill the last instance to create a template
bd mol distill bd-mol-last --output .beads/formulas/onboarding.yaml

# Senior engineer creates canonical workflow
bd mol distill bd-mol-canonical --output .beads/formulas/release-process.yaml

# Junior engineers pour from template
bd mol pour .beads/formulas/release-process.yaml

# Document incident response workflow
bd mol distill bd-mol-incident-42 --output incident-response.yaml

# Next incident: pour instantly
bd mol pour incident-response.yaml

# Create design + implementation + testing pipeline
bd mol bond design.yaml implementation.yaml testing.yaml

# Result: Combined workflow with proper dependencies

# Start with MVP
bd mol pour mvp.yaml

# Later: add polish steps
bd mol bond mvp polish.yaml

# Weekly patrol formula
bd mol pour patrol.yaml --vars '{"week": "2026-W10"}'

# Generates:
# - "Check CI health (2026-W10)"
# - "Review open PRs (2026-W10)"
# - "Update dependencies (2026-W10)"

# Create molecule with custom ID
bd mol pour feature.yaml --id feat-auth-2026q1

# Bond to existing work
bd mol bond bd-epic-123 feat-auth-2026q1

# Later: distill and re-pour
bd mol distill feat-auth-2026q1 | bd mol pour - --id feat-oauth-2026q2

# Formulas are searched in:
# 1. ./.beads/formulas/
# 2. ~/.beads/formulas/
# 3. /usr/local/share/beads/formulas/

# Verify formula exists
ls -la .beads/formulas/

steps:
  - title: "Step A"
    depends_on: [1]  # Depends on Step B
  - title: "Step B"
    depends_on: [0]  # Depends on Step A ← CYCLE!

# Check existing dependencies
bd dep tree bd-a3f8

# Remove conflicting dependency
bd dep rm bd-a3f8 bd-b7c2

# Now bond
bd mol bond bd-a3f8 bd-b7c2