- FAQ: fix bulk migration/export commands (tracker pull/push need explicit IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and correct the cross-project isolation claim (hydration + external targets) - quickstart: replace the broken DOLT.md blob URL with site links - installation: Quick Install Script heading matches its macOS/Linux/FreeBSD body - rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles - add description frontmatter to the 55 authored pages missing it - docs.json: wildcard redirects for the old /next/ and version-prefixed route spaces (1.0.0, 1.0.4, 1.0.5)
250 lines
4.4 KiB
Markdown
250 lines
4.4 KiB
Markdown
---
|
|
title: Formulas
|
|
description: 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
|
|
|
|
```toml
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```toml
|
|
[[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](/workflows/gates).
|
|
|
|
## Dependencies
|
|
|
|
### Sequential
|
|
|
|
```toml
|
|
[[steps]]
|
|
id = "step1"
|
|
title = "First step"
|
|
|
|
[[steps]]
|
|
id = "step2"
|
|
title = "Second step"
|
|
needs = ["step1"]
|
|
```
|
|
|
|
### Parallel then Join
|
|
|
|
```toml
|
|
[[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:
|
|
|
|
```toml
|
|
[[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:
|
|
|
|
```toml
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```toml
|
|
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"
|
|
```
|