gastown/docs/concepts/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
Shiny Workflow	Canonical polecat formula: design → implement → review → test → submit

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

Polecat Workflow

Polecats receive work via their hook - a pinned molecule attached to an issue. They execute molecule steps sequentially, closing each step as they complete it.

Molecule Types for Polecats

Type	Storage	Use Case
Regular Molecule	.beads/ (synced)	Discrete deliverables, audit trail
Wisp	.beads/ (ephemeral)	Patrol cycles, operational loops

Polecats typically use regular molecules because each assignment has audit value. Patrol agents (Witness, Refinery, Deacon) use wisps to prevent accumulation.

Hook Management

gt hook                        # What's on MY hook?
gt mol attach-from-mail <id>   # Attach work from mail message
gt done                        # Signal completion (syncs, submits to MQ, notifies Witness)

Polecat Workflow Summary

1. Spawn with work on hook
2. gt hook                 # What's hooked?
3. bd mol current          # Where am I?
4. Execute current step
5. bd close <step> --continue
6. If more steps: GOTO 3
7. gt done                 # Signal completion

Wisp vs Molecule Decision

Question	Molecule	Wisp
Does it need audit trail?	Yes	No
Will it repeat continuously?	No	Yes
Is it discrete deliverable?	Yes	No
Is it operational routine?	No	Yes

Best Practices

1. CRITICAL: Close steps in real-time - Mark in_progress BEFORE starting, closed IMMEDIATELY after completing. Never batch-close steps at the end. Molecules ARE the ledger - each step closure is a timestamped CV entry. Batch-closing corrupts the timeline and violates HOP's core promise.
2. Use --continue for propulsion - Keep momentum by auto-advancing
3. Check progress with bd mol current - Know where you are before resuming
4. Squash completed molecules - Create digests for audit trail
5. Burn routine wisps - Don't accumulate ephemeral patrol data