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

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