gastownhall__beads/docs/workflows/formulas.md

title, description

title	description
Formulas	Writing declarative TOML or JSON workflow templates with steps, variables, dependencies, gates, and aspects, then cooking them into protos.

Formulas are declarative workflow templates.

Formula Format

Formulas can be written in TOML (preferred) or JSON:

TOML Format

formula = "feature-workflow"
description = "Standard feature development workflow"
version = 1
type = "workflow"

[vars.feature_name]
description = "Name of the feature"
required = true

[[steps]]
id = "design"
title = "Design {{feature_name}}"
type = "human"
description = "Create design document"

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

[[steps]]
id = "review"
title = "Code review"
needs = ["implement"]
type = "human"

[[steps]]
id = "merge"
title = "Merge to main"
needs = ["review"]

JSON Format

{
  "formula": "feature-workflow",
  "description": "Standard feature development workflow",
  "version": 1,
  "type": "workflow",
  "vars": {
    "feature_name": {
      "description": "Name of the feature",
      "required": true
    }
  },
  "steps": [
    {
      "id": "design",
      "title": "Design {{feature_name}}",
      "type": "human"
    },
    {
      "id": "implement",
      "title": "Implement {{feature_name}}",
      "needs": ["design"]
    }
  ]
}

Formula Types

Type	Description
workflow	Standard step sequence
expansion	Template for expansion operator
aspect	Cross-cutting concerns

Variables

Define variables with defaults and constraints:

[vars.version]
description = "Release version"
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"

[vars.environment]
description = "Target environment"
default = "staging"
enum = ["staging", "production"]

Use variables in steps:

[[steps]]
title = "Deploy {{version}} to {{environment}}"

Step Types

A step's type sets the issue type of the bead it creates: task (default), bug, feature, epic, or chore. Any other value falls back to task. Human sign-offs and async waits are expressed with a [steps.gate] block, not a step type — see Gates.

Dependencies

Sequential

[[steps]]
id = "step1"
title = "First step"

[[steps]]
id = "step2"
title = "Second step"
needs = ["step1"]

Parallel then Join

[[steps]]
id = "test-unit"
title = "Unit tests"

[[steps]]
id = "test-integration"
title = "Integration tests"

[[steps]]
id = "deploy"
title = "Deploy"
needs = ["test-unit", "test-integration"]  # Waits for both

Gates

Add gates for async coordination:

[[steps]]
id = "approval"
title = "Manager approval"
type = "human"

[steps.gate]
type = "human"
approvers = ["manager"]

[[steps]]
id = "deploy"
title = "Deploy to production"
needs = ["approval"]

Aspects (Cross-cutting)

Apply transformations to matching steps:

formula = "security-scan"
type = "aspect"

[[advice]]
target = "*.deploy"  # Match all deploy steps

[advice.before]
id = "security-scan-{step.id}"
title = "Security scan before {step.title}"

Formula Locations

Formulas are searched in order:

1. .beads/formulas/ (project-level)
2. ~/.beads/formulas/ (user-level)

bd formula list shows everything visible on the search paths.

Using Formulas

# List available formulas
bd formula list

# Cook the formula into a proto, then pour it into a molecule
bd cook <formula-file>
bd mol pour <proto-id> --var key=value

# Preview what would be created
bd mol pour <proto-id> --dry-run

Creating Custom Formulas

1. Create file: .beads/formulas/my-workflow.formula.toml
2. Define structure (see examples above)
3. Use with: bd cook my-workflow then bd mol pour <proto-id>

Example: Release Formula

formula = "release"
description = "Standard release workflow"
version = 1

[vars.version]
required = true
pattern = "^\\d+\\.\\d+\\.\\d+$"

[[steps]]
id = "bump-version"
title = "Bump version to {{version}}"

[[steps]]
id = "changelog"
title = "Update CHANGELOG"
needs = ["bump-version"]

[[steps]]
id = "test"
title = "Run full test suite"
needs = ["changelog"]

[[steps]]
id = "build"
title = "Build release artifacts"
needs = ["test"]

[[steps]]
id = "tag"
title = "Create git tag v{{version}}"
needs = ["build"]

[[steps]]
id = "publish"
title = "Publish release"
needs = ["tag"]
type = "human"