Every fix verified against the binary or a traced source call path: - How Beads Works: parent-child DOES affect ready work (a blocked parent blocks its children — the blocked-state SQL inherits it), hash-ID inputs are title/description/creator/creation-time plus a collision nonce (live generator is internal/idgen, not the legacy one), and bead gates dropped from the gates bullet (currently unresolvable). - Graph-link type strings are hyphenated (relates-to, replies-to); underscore forms are rejected by the parser. Fixed corpus-wide including the README feature bullet. - upgrading.md: the version-era table's boundaries were refuted by git archaeology (embedded Dolt shipped in v0.60.0 and always used .beads/embeddeddolt/; nothing changed at the claimed v0.63.3 boundary) — replaced with a layout-based identification table. - Phantom .beads/dolt/sql-server.log path in sync-failures and the FAQ; the managed server writes .beads/dolt-server.log. - FAQ: ID growth matches DefaultAdaptiveConfig (min 3, max 8, probability-driven), dependency-type wording no longer claims exactly four types, and unmeasured performance figures are hedged instead of stated as facts. - quickstart: bd migrate --cleanup doesn't exist; init installs hooks by default (no prompt) and has no merge-driver step; ready output quote and bd restore recovery source corrected. - formulas.md: step types map to issue types (task/bug/feature/epic/ chore; anything else falls back to task — human/gate are not step types), and there is no built-in formula search tier. - todo.md: bd update takes --set-labels, not --labels. - graph-links.md: broken #dependencies fragment → #add-dependencies.
249 lines
4.2 KiB
Markdown
249 lines
4.2 KiB
Markdown
---
|
|
title: Formulas
|
|
---
|
|
|
|
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"
|
|
```
|