Skip to main content
Gas City resolves formula files from configured formula layers and stages the winning *.formula.toml files into .beads/formulas/ with ResolveFormulas. Formula instantiation happens through the store interface:
  • Store.MolCook(formula, title, vars) creates a new molecule or wisp
  • Store.MolCookOn(formula, beadID, title, vars) attaches a molecule to an existing bead

​
Minimal Formula

formula = "pancakes"
description = "Make pancakes"
version = 1

[[steps]]
id = "dry"
title = "Mix dry ingredients"
description = "Combine the flour, sugar, and baking powder."

[[steps]]
id = "wet"
title = "Mix wet ingredients"
description = "Combine eggs, milk, and butter."

[[steps]]
id = "cook"
title = "Cook pancakes"
description = "Cook on medium heat."
needs = ["dry", "wet"]

​
Common Top-Level Keys

KeyTypePurpose
formulastringUnique formula name used by gc mol create and Store.MolCook*
descriptionstringHuman-readable description
versionintegerOptional formula version marker
extends[]stringOptional parent formulas to compose from

​
Step Fields

Each [[steps]] entry represents one task bead inside the instantiated molecule.
KeyTypePurpose
idstringStep identifier; unique within the formula
titlestringShort step title
descriptionstringStep instructions shown to the agent
needs[]stringStep IDs that must complete before this step is ready

​
Variable Substitution

Formula descriptions can use {{key}} placeholders. Variables are supplied as key=value pairs when the formula is instantiated, for example: 
gc sling --formula deploy --var env=prod worker

​
Convergence-Specific Fields

Convergence uses a formula subset defined in internal/convergence/formula.go.
KeyTypePurpose
convergenceboolMust be true for convergence loops
required_vars[]stringVariables that must be supplied at creation time
evaluate_promptstringOptional prompt file for the controller-injected evaluate step

​
Where Formulas Come From

  • City-level layers are resolved from [formulas].dir
  • Rig-local overrides come from [[rigs]].formulas_dir
  • Pack formulas participate through pack composition and formula layers
For the current formula-resolution behavior, see Architecture: Formulas & Molecules.
Last modified on March 20, 2026