gastown/docs/molecules.md

Molecules

Molecules are workflow templates that coordinate multi-step work in Gas Town.

Molecule Lifecycle

Formula (source TOML) ─── "Ice-9"
    │
    ▼ bd cook
Protomolecule (frozen template) ─── Solid
    │
    ├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest
    │
    └─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest
                                                     └▶ bd burn ──▶ (gone)

Core Concepts

Term	Description
Formula	Source TOML template defining workflow steps
Protomolecule	Frozen template ready for instantiation
Molecule	Active workflow instance with trackable steps
Wisp	Ephemeral molecule for patrol cycles (never synced)
Digest	Squashed summary of completed molecule

Common Mistake: Reading Formulas Directly

WRONG:

# Reading a formula file and manually creating beads for each step
cat .beads/formulas/mol-polecat-work.formula.toml
bd create --title "Step 1: Load context" --type task
bd create --title "Step 2: Branch setup" --type task
# ... creating beads from formula prose

RIGHT:

# Cook the formula into a proto, pour into a molecule
bd cook mol-polecat-work
bd mol pour mol-polecat-work --var issue=gt-xyz
# Now work through the step beads that were created
bd ready                    # Find next step
bd close <step-id>          # Complete it

Key insight: Formulas are source templates (like source code). You never read them directly during work. The cook → pour pipeline creates step beads for you. Your molecule already has steps - use bd ready to find them.

Navigating Molecules

Molecules help you track where you are in multi-step workflows.

Finding Your Place

bd mol current              # Where am I?
bd mol current gt-abc       # Status of specific molecule

Output:

You're working on molecule gt-abc (Feature X)

  ✓ gt-abc.1: Design
  ✓ gt-abc.2: Scaffold
  ✓ gt-abc.3: Implement
  → gt-abc.4: Write tests [in_progress] <- YOU ARE HERE
  ○ gt-abc.5: Documentation
  ○ gt-abc.6: Exit decision

Progress: 3/6 steps complete

Seamless Transitions

Close a step and advance in one command:

bd close gt-abc.3 --continue   # Close and advance to next step
bd close gt-abc.3 --no-auto    # Close but don't auto-claim next

The old way (3 commands):

bd close gt-abc.3
bd ready --parent=gt-abc
bd update gt-abc.4 --status=in_progress

The new way (1 command):

bd close gt-abc.3 --continue

Transition Output

✓ Closed gt-abc.3: Implement feature

Next ready in molecule:
  gt-abc.4: Write tests

→ Marked in_progress (use --no-auto to skip)

When Molecule Completes

✓ Closed gt-abc.6: Exit decision

Molecule gt-abc complete! All steps closed.
Consider: bd mol squash gt-abc --summary '...'

Molecule Commands

Beads Operations (bd)

# Formulas
bd formula list              # Available formulas
bd formula show <name>       # Formula details
bd cook <formula>            # Formula → Proto

# Molecules (data operations)
bd mol list                  # Available protos
bd mol show <id>             # Proto details
bd mol pour <proto>          # Create mol
bd mol wisp <proto>          # Create wisp
bd mol bond <proto> <parent> # Attach to existing mol
bd mol squash <id>           # Condense to digest
bd mol burn <id>             # Discard wisp
bd mol current               # Where am I in the current molecule?

Agent Operations (gt)

# Hook management
gt hook                    # What's on MY hook
gt mol current               # What should I work on next
gt mol progress <id>         # Execution progress of molecule
gt mol attach <bead> <mol>   # Pin molecule to bead
gt mol detach <bead>         # Unpin molecule from bead

# Agent lifecycle
gt mol burn                  # Burn attached molecule
gt mol squash                # Squash attached molecule
gt mol step done <step>      # Complete a molecule step

Best Practices

1. Use --continue for propulsion - Keep momentum by auto-advancing
2. Check progress with bd mol current - Know where you are before resuming
3. Squash completed molecules - Create digests for audit trail
4. Burn routine wisps - Don't accumulate ephemeral patrol data