Beads

When to use

• A .beads/ directory exists.
  • If unsure: rg --files -g '.beads/**' --hidden --no-ignore.
• The user asks for bd commands (bd ready, bd create, bd close, bd sync, …).
• The user wants beads to act as a work ledger (plan/progress/decisions recorded during implementation).

Principle: bead as work ledger

• The active bead is the canonical place for plan, progress, decisions, and verification.
• Prefer recording facts into the bead over long chat narration; the bead must survive session resets.

Molecules (workflow steps as beads)

A molecule is how beads turns “do this work” into a durable, stepwise workflow.

• Formula: workflow source file (discover via bd formula list).
• Proto: cooked template epic (solid phase).
• Mol: persistent instantiation of a proto (liquid phase) created by bd mol pour.
• Wisp: ephemeral instantiation (vapor phase) created by bd mol wisp.