How Gas Town Uses Formulas and Molecules for Workflow Definition

Gas Town separates workflow definition from execution by using immutable TOML Formulas as blueprints and concrete Molecules as runtime instances that agents consume during sessions.

The gastownhall/gastown project implements a declarative automation system where Formulas and Molecules provide version-controlled, reusable workflows for agents. This architecture enables teams to define standardized processes in data rather than code, ensuring consistent execution across different rigs and issue trackers.

Formulas: Immutable Workflow Blueprints

Formulas are declarative TOML templates stored in the repository that define what work should be done without specifying how the system tracks execution.

Formula Structure and Location

All formulas reside under internal/formula/formulas/. For example, internal/formula/formulas/mol-polecat-work.formula.toml defines the canonical polecat workflow.

Each formula file contains:

• description – Human-readable overview of the workflow
• formula – The logical name invoked via bd cook …
• [[steps]] – Ordered checklist items with id, title, optional needs (dependencies), and description that may contain shell snippets
• [vars] – Required variables such as issue or base_branch that callers must supply

Version Control Benefits

Because formulas are committed to the repository in internal/formula/formulas/, they are version-controlled, searchable, and automatically shared across all rigs. Changes to a formula propagate instantly to future workflow instances without requiring code redeployment.

Molecules: Runtime Workflow Instances

A Molecule is a concrete, tracked instantiation of a Formula that agents execute. The lifecycle moves from static template to active runtime object through specific CLI operations.

The Cooking Process

The bd cook <formula> command compiles a Formula into a protomolecule—an intermediate representation ready for instantiation. This command is implemented in internal/cmd/formula.go and validates the TOML structure before creating the runtime object.

Execution Models: Root-Only vs. Poured

Gas Town supports two durability models for Molecules:

• Root-only wisp (default) – Created with bd mol wisp <formula>. Steps are not materialized in the Beads ledger; they render inline at prime time. This keeps the .beads/ ledger minimal for high-frequency, short workflows.
• Poured wisp – Created with bd mol pour <formula> --var … where the formula specifies pour = true. Steps become sub-wisps stored as database rows, enabling checkpoint recovery for expensive, low-frequency pipelines such as releases.

Lifecycle Commands

The workflow lifecycle is managed through specific commands:

• bd formula list – Lists available Formulas from internal/formula/formulas/
• bd cook <formula> – Compiles a Formula into a protomolecule
• bd mol pour <formula> --var issue=gt-abc12 – Instantiates a poured Molecule with persisted sub-wisps
• bd mol wisp <formula> – Creates a root-only wisp (ephemeral)
• gt mol attach <bead> <mol> – Pins a Molecule to a specific issue bead
• gt mol detach <bead> – Unpins a Molecule from an issue
• gt prime – Renders the Formula’s checklist inline when an agent starts a session

How Agents Consume Workflows

The execution flow follows a specific pattern from instantiation to completion:

1. Create a Molecule – Run bd mol pour mol-polecat-work --var issue=gt-abc12 --var base_branch=main to write a protomolecule entry into the .beads/ ledger.

2. Attach to a bead – Execute gt mol attach gt-abc12 <mol-id> to link the Molecule to the issue the polecat will work on.

3. Agent primes – When the polecat runs gt prime, the Formula’s steps display inline (as defined in the formula file’s Load context step). The agent proceeds through the checklist, committing code after each logical unit.

4. Self-cleaning completion – The final submit-and-exit step calls gt done. The polecat pushes the branch, creates an MR bead, destroys its sandbox, and exits. The Molecule then either disappears (root-only) or remains as a completed record (poured).

Because the checklist is part of the Formula definition in internal/formula/formulas/mol-polecat-work.formula.toml, every polecat receives a consistent, version-controlled workflow without manual step tracking.

Benefits of the Formula/Molecule Architecture

Declarative definition – Workflows are expressed in TOML data rather than imperative code, making them easy to audit, diff, and evolve through standard pull requests.

Cross-rig reusability – A single Formula can be instantiated many times across different rigs, enabling standardized processes (such as release or code-review) regardless of where the agent runs.

Resilience options – Poured molecules provide checkpointing for long-running pipelines; root-only wisps keep the beads table lightweight for frequent, short tasks.

Runtime visibility – All steps are visible to agents at prime time and to humans via bd mol show, ensuring transparency in automated workflows.

Extensibility – Adding new steps or variables requires only editing the TOML file; changes propagate automatically to all future instances without rebuilding the binary.

Summary

• Formulas are immutable TOML blueprints stored in internal/formula/formulas/ that define workflow steps and variables.
• Molecules are runtime instances created via bd cook and bd mol pour/wisp that track execution state in the .beads/ ledger.
• Root-only wisps provide ephemeral, lightweight execution for high-frequency tasks, while poured molecules persist sub-wisps for checkpoint recovery.
• Agents consume workflows by attaching Molecules to beads with gt mol attach and rendering steps inline via gt prime.
• The separation between Formula (definition) and Molecule (instance) enables version-controlled, reusable, and resilient automation across the gastownhall/gastown ecosystem.

Frequently Asked Questions

What is the difference between cooking and pouring a Formula?

Cooking (bd cook <formula>) compiles a Formula into a protomolecule—the intermediate representation that validates the TOML structure. Pouring (bd mol pour …) instantiates that protomolecule as a concrete Molecule with specific variable bindings, creating either ephemeral root-only wisps or persisted sub-wisps depending on the formula’s configuration. Cooking prepares the template; pouring creates the executable instance.

When should I use a root-only wisp versus a poured Molecule?

Use root-only wisps (created with bd mol wisp) for high-frequency, short-lived workflows where you want minimal ledger overhead and do not need recovery checkpoints. Use poured Molecules (created with bd mol pour) for expensive, low-frequency pipelines—such as release workflows—where pour = true in the formula enables checkpoint recovery through persisted sub-wisps in the database.

How does the gt prime command interact with Molecules?

The gt prime command renders a Molecule’s step checklist inline when an agent starts a session. If the Molecule is attached to a bead via gt mol attach, the agent sees the Formula-defined steps immediately without creating additional bead records. This allows the agent to proceed through version-controlled workflows while maintaining a lightweight ledger.

Where are Formula definitions stored in the Gas Town repository?

Formula definitions reside in internal/formula/formulas/ as .formula.toml files, with internal/formula/formulas/mol-polecat-work.formula.toml serving as the canonical example. Documentation explaining the full lifecycle from Formulas to Protomolecules to Molecules and Wisps is available in docs/concepts/molecules.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}