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.
4.2 KiB
4.2 KiB
| title |
|---|
| Formulas |
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:
.beads/formulas/(project-level)~/.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
- Create file:
.beads/formulas/my-workflow.formula.toml - Define structure (see examples above)
- Use with:
bd cook my-workflowthenbd 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"