gastown/docs/molecules.md

Molecules: Composable Workflow Templates

This document covers the molecule system in depth.

For an overview, see architecture.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-engineer-in-box",
  "title": "Engineer in Box: {{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-engineer-in-box --var feature_name="user auth"
# Creates: "Engineer in Box: user auth"

Variables work in:

• Title
• Description
• Child step titles/descriptions

Steps as Children

Steps are hierarchical children of the molecule:

mol-engineer-in-box (epic)
├── mol-engineer-in-box.1  "Design"
├── mol-engineer-in-box.2  "Implement"       Needs: .1
├── mol-engineer-in-box.3  "Review"          Needs: .2
├── mol-engineer-in-box.4  "Test"            Needs: .3
└── mol-engineer-in-box.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-engineer-in-box --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

┌─────────────┐
│   Proto     │  Template in molecules.jsonl
│  (frozen)   │  labels: ["template"]
└──────┬──────┘
       │
       ▼ bd mol bond [--wisp]
┌─────────────┐
│  Mol/Wisp   │  Active execution
│ (flowing)   │  Mol: .beads/ | Wisp: .beads-wisp/
└──────┬──────┘
       │
  ┌────┴────┐
  ▼         ▼
burn      squash
  │         │
  ▼         ▼
(gone)   Digest
         (permanent)

Steam engine metaphor:

• Proto = Fuel (potential energy)
• Mol/Wisp = Steam (kinetic energy)
• Digest = Distillate (crystallized work)
• Burn = Steam dissipates
• Squash = Steam condenses