gastown/docs/molecules.md

Molecules: Composable Workflow Templates

This document covers the molecule system in depth.

For an overview, see architecture.md. For the full lifecycle (Rig → Cook → Run), see molecular-chemistry.md.

Core Concepts

A molecule is a workflow template stored as a beads issue with labels: ["template"]. When bonded, it creates child issues forming a DAG of steps.

Proto (template)
     │
     ▼ bd mol bond
┌─────────────────┐
│ Mol (durable)   │  ← .beads/ (synced, auditable)
│ or              │
│ Wisp (ephemeral)│  ← .beads-wisp/ (gitignored)
└────────┬────────┘
         │
   ┌─────┴─────┐
   ▼           ▼
bd mol burn  bd mol squash
(no record)  (creates digest)

Concept	Description
Proto	Template molecule (is_template: true in beads)
Mol	Durable instance in .beads/
Wisp	Ephemeral instance in .beads-wisp/
Digest	Condensed completion record
Bond	Instantiate proto → mol/wisp

Molecule Storage

Molecules are standard beads issues stored in molecules.jsonl:

{
  "id": "mol-shiny",
  "title": "Shiny: {{feature_name}}",
  "description": "Full workflow from design to merge.\n\nVars:\n- {{feature_name}} - What to build",
  "labels": ["template"],
  "issue_type": "epic"
}

Loaded from multiple sources (later overrides earlier):

1. Built-in (embedded in bd binary)
2. Town-level: ~/gt/.beads/molecules.jsonl
3. User-level: ~/.beads/molecules.jsonl
4. Project-level: .beads/molecules.jsonl

Variable Substitution

Molecules support {{var}} placeholders resolved at bond time:

bd mol bond mol-shiny --var feature_name="user auth"
# Creates: "Shiny: user auth"

Variables work in:

• Title
• Description
• Child step titles/descriptions

Steps as Children

Steps are hierarchical children of the molecule:

mol-shiny (epic)
├── mol-shiny.1  "Design"
├── mol-shiny.2  "Implement"       Needs: .1
├── mol-shiny.3  "Review"          Needs: .2
├── mol-shiny.4  "Test"            Needs: .3
└── mol-shiny.5  "Submit"          Needs: .4

Dependencies are encoded in beads edges, not in step descriptions.

Molecule CLI Reference

bd mol bond

Instantiate a proto molecule into a runnable mol or wisp.

bd mol bond <proto-id> [--wisp] [--var key=value...]

Flag	Description
--wisp	Create ephemeral wisp instead of durable mol
--var	Variable substitution (repeatable)
--ref	Custom reference ID for the instance

Examples:

# Durable mol
bd mol bond mol-shiny --var feature_name="auth"

# Ephemeral wisp for patrol
bd mol bond mol-witness-patrol --wisp

# Dynamic child with custom ref (Christmas Ornament pattern)
bd mol bond mol-polecat-arm $PATROL_ID --ref arm-ace --var polecat=ace

bd mol squash

Complete a molecule and generate a permanent digest.

bd mol squash <mol-id> --summary='...'

The summary is agent-generated - the intelligence comes from the agent, not beads.

For Mol: Creates digest in .beads/, original steps remain. For Wisp: Evaporates wisp, creates digest. Execution trace gone, outcome preserved.

bd mol burn

Abandon a molecule without record.

bd mol burn <mol-id> [--reason='...']

Use burn for:

• Routine patrol cycles (no audit needed)
• Failed experiments
• Cancelled work

Use squash for:

• Completed work
• Investigations with findings
• Anything worth recording

bd mol list

List available molecules:

bd mol list              # All templates
bd mol list --label plugin  # Plugin molecules only

Plugins ARE Molecules

Patrol plugins are molecules with specific labels:

{
  "id": "mol-security-scan",
  "title": "Security scan for {{polecat_name}}",
  "description": "Check for vulnerabilities.\n\nVars: {{polecat_name}}, {{captured_output}}",
  "labels": ["template", "plugin", "witness", "tier:haiku"],
  "issue_type": "task"
}

Label conventions:

• plugin - marks as bondable at hook points
• witness / deacon / refinery - which patrol uses it
• tier:haiku / tier:sonnet - model hint

Execution in patrol:

# plugin-run step bonds registered plugins:
bd mol bond mol-security-scan $PATROL_WISP \
  --ref security-{{polecat_name}} \
  --var polecat_name=ace \
  --var captured_output="$OUTPUT"

The Christmas Ornament Pattern

Dynamic bonding creates tree structures at runtime:

                    ★ mol-witness-patrol
                   /|\
            ┌─────┘ │ └─────┐
         PREFLIGHT  │    CLEANUP
            │       │        │
        ┌───┴───┐   │    ┌───┴───┐
        │inbox  │   │    │aggreg │
        │load   │   │    │summary│
        └───────┘   │    └───────┘
                    │
          ┌─────────┼─────────┐
          │         │         │
          ●         ●         ●  mol-polecat-arm (dynamic)
         ace       nux      toast
          │         │         │
       ┌──┴──┐   ┌──┴──┐   ┌──┴──┐
       │steps│   │steps│   │steps│
       └──┬──┘   └──┬──┘   └──┬──┘
          │         │         │
          └─────────┴─────────┘
                    │
                 ⬣ base

Key primitives:

• bd mol bond ... --ref - creates named children
• WaitsFor: all-children - fanout gate
• Arms execute in parallel

Mol Mall

Distribution through molecule marketplace:

# Install from registry
bd mol install mol-security-scan

# Updates ~/.beads/molecules.jsonl

Mol Mall serves molecules.jsonl fragments. Installation appends to your catalog.

Code Review Molecule

The code-review molecule is a pluggable workflow:

mol-code-review
├── discovery (parallel)
│   ├── file-census
│   ├── dep-graph
│   └── coverage-map
│
├── structural (sequential)
│   ├── architecture-review
│   └── abstraction-analysis
│
├── tactical (parallel per component)
│   ├── security-scan
│   ├── performance-review
│   └── complexity-analysis
│
└── synthesis (single)
    └── aggregate

Each dimension is a molecule that can be:

• Swapped for alternatives from Mol Mall
• Customized by forking and installing your version
• Disabled by not bonding it

Usage:

bd mol bond mol-code-review --var scope="src/"

Lifecycle Summary

Gas Town work follows the Rig → Cook → Run lifecycle:

           RIG (source)              COOK (artifact)           RUN (execution)
      ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
      │    Formula      │──────►│     Proto       │──────►│   Mol/Wisp      │
      │   (.yaml)       │ cook  │  (cooked/frozen)│ pour/ │   (flowing)     │
      │                 │       │                 │ wisp  │                 │
      └─────────────────┘       └─────────────────┘       └────────┬────────┘
                                                                   │
                                                              ┌────┴────┐
                                                              ▼         ▼
                                                            burn      squash
                                                              │         │
                                                              ▼         ▼
                                                           (gone)   Digest
                                                                   (permanent)

Full lifecycle:

• Formula (.formula.toml or .formula.json) = Recipe (source code for workflows)
• Proto = Fuel (cooked template, ready to instantiate)
• Mol/Wisp = Steam (active execution)
• Digest = Distillate (crystallized work)

See molecular-chemistry.md for the complete specification.

Formula File Formats

Formulas support both TOML (preferred) and JSON formats:

# List available formulas
bd formula list

# Show formula details
bd formula show shiny

# Convert JSON to TOML (better for human editing)
bd formula convert shiny           # Single formula
bd formula convert --all           # All formulas
bd formula convert shiny --stdout  # Preview

Why TOML?

• Multi-line strings without \n escaping
• Comments allowed
• Human-readable diffs
• Same parsing semantics as JSON

The loader tries .formula.toml first, falling back to .formula.json.

Example Formula (TOML)

formula = "shiny"
type = "workflow"
version = 1
description = """
Engineer in a Box - design before code, review before ship.
"""

[vars.feature]
description = "The feature being implemented"
required = true

[[steps]]
id = "design"
title = "Design {{feature}}"
description = """
Think carefully about architecture before writing code.
Consider edge cases and simpler approaches.
"""

[[steps]]
id = "implement"
title = "Implement {{feature}}"
needs = ["design"]