# How Gas Town Uses Formulas and Molecules for Workflow Definition > Learn how Gas Town defines workflows with immutable TOML Formulas and concrete Molecule instances. Separate definition from execution for efficient agent sessions. - Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown) - Tags: how-to-guide - Published: 2026-07-07 --- **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`](https://github.com/gastownhall/gastown/blob/main/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 ` command compiles a Formula into a **protomolecule**—an intermediate representation ready for instantiation. This command is implemented in [`internal/cmd/formula.go`](https://github.com/gastownhall/gastown/blob/main/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 `. 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 --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 ` – Compiles a Formula into a protomolecule - `bd mol pour --var issue=gt-abc12` – Instantiates a poured Molecule with persisted sub-wisps - `bd mol wisp ` – Creates a root-only wisp (ephemeral) - `gt mol attach ` – Pins a Molecule to a specific issue bead - `gt mol detach ` – 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 ` 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`](https://github.com/gastownhall/gastown/blob/main/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 `) 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`](https://github.com/gastownhall/gastown/blob/main/.formula.toml) files, with [`internal/formula/formulas/mol-polecat-work.formula.toml`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/docs/concepts/molecules.md).