docs: neutralize formula workflow terminology (#3900)

Remove gastown-specific language. Replace the formula command's Rig/Cook/Run lifecycle wording with existing beads verbs: define formulas, cook them into protos, then pour or wisp them into work. Describe GT_ROOT formulas as a shared workspace root instead of an orchestrator path. Update generated CLI references and add a regression check for the help text.

_codex-gpt-5-medium on behalf of matt wilkie_
This commit is contained in:
matt wilkie 2026-05-13 06:52:11 -07:00 • committed by GitHub
commit 248682bbd2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 60 additions and 50 deletions

View file

@ -21,19 +21,14 @@ var formulaCmd = &cobra.Command{
Short: "Manage workflow formulas",
Long: `Manage workflow formulas - the source layer for molecule templates.
Formulas are YAML/JSON files that define workflows with composition rules.
They are "cooked" into proto beads which can then be poured or wisped.
The Rig → Cook → Run lifecycle:
- Rig: Compose formulas (extends, compose)
- Cook: Transform to proto (bd cook expands macros, applies aspects)
- Run: Agents execute poured mols or wisps
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. <resolved-beads-dir>/formulas/ (active project)
2. <checkout-root>/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
@ -50,7 +45,7 @@ Search paths (in order of priority):
1. <resolved-beads-dir>/formulas/ (active project - highest priority)
2. <checkout-root>/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Formulas in earlier paths shadow those with the same name in later paths.

View file

@ -0,0 +1,35 @@
package main
import (
"strings"
"testing"
)
func TestFormulaHelpUsesGenericWorkflowLanguage(t *testing.T) {
help := formulaCmd.Long + "\n" + formulaListCmd.Long + "\n" + molSeedCmd.Long
for _, want := range []string{
"Formulas are TOML/JSON files",
"Define formulas, cook them into protos, then pour or wisp them into work.",
"shared workspace root",
} {
if !strings.Contains(help, want) {
t.Fatalf("formula help missing %q:\n%s", want, help)
}
}
for _, forbidden := range []string{
"YAML/" + "JSON files",
"Rig:",
"Formula " + "workflow:",
"Author" + ":",
"Compile: " + "Resolve",
"Instantiate: " + "Agents",
"orchestrator, if " + "GT_ROOT set",
"orchestrator level, if " + "GT_ROOT set",
} {
if strings.Contains(help, forbidden) {
t.Fatalf("formula help still contains %q:\n%s", forbidden, help)
}
}
}

View file

@ -20,7 +20,7 @@ Formula search paths (checked in order):
1. <resolved-beads-dir>/formulas/ (active project)
2. <checkout-root>/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (orchestrator level, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula

View file

@ -5437,19 +5437,14 @@ bd defer [id...] [flags]
Manage workflow formulas - the source layer for molecule templates.
Formulas are YAML/JSON files that define workflows with composition rules.
They are "cooked" into proto beads which can then be poured or wisped.
The Rig → Cook → Run lifecycle:
- Rig: Compose formulas (extends, compose)
- Cook: Transform to proto (bd cook expands macros, applies aspects)
- Run: Agents execute poured mols or wisps
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
@ -5498,7 +5493,7 @@ Search paths (in order of priority):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project - highest priority)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Formulas in earlier paths shadow those with the same name in later paths.
@ -6168,7 +6163,7 @@ Formula search paths (checked in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (orchestrator level, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula

View file

@ -12,19 +12,14 @@ Generated from `bd help --doc formula`
Manage workflow formulas - the source layer for molecule templates.
Formulas are YAML/JSON files that define workflows with composition rules.
They are "cooked" into proto beads which can then be poured or wisped.
The Rig → Cook → Run lifecycle:
- Rig: Compose formulas (extends, compose)
- Cook: Transform to proto (bd cook expands macros, applies aspects)
- Run: Agents execute poured mols or wisps
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
@ -73,7 +68,7 @@ Search paths (in order of priority):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project - highest priority)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Formulas in earlier paths shadow those with the same name in later paths.

View file

@ -333,7 +333,7 @@ Formula search paths (checked in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (orchestrator level, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula

View file

@ -12,19 +12,14 @@ Generated from `bd help --doc formula`
Manage workflow formulas - the source layer for molecule templates.
Formulas are YAML/JSON files that define workflows with composition rules.
They are "cooked" into proto beads which can then be poured or wisped.
The Rig → Cook → Run lifecycle:
- Rig: Compose formulas (extends, compose)
- Cook: Transform to proto (bd cook expands macros, applies aspects)
- Run: Agents execute poured mols or wisps
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
@ -73,7 +68,7 @@ Search paths (in order of priority):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project - highest priority)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Formulas in earlier paths shadow those with the same name in later paths.

View file

@ -333,7 +333,7 @@ Formula search paths (checked in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (orchestrator level, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula

View file

@ -12,19 +12,14 @@ Generated from `bd help --doc formula`
Manage workflow formulas - the source layer for molecule templates.
Formulas are YAML/JSON files that define workflows with composition rules.
They are "cooked" into proto beads which can then be poured or wisped.
The Rig → Cook → Run lifecycle:
- Rig: Compose formulas (extends, compose)
- Cook: Transform to proto (bd cook expands macros, applies aspects)
- Run: Agents execute poured mols or wisps
Formulas are TOML/JSON files that define workflows with composition rules.
Define formulas, cook them into protos, then pour or wisp them into work.
Search paths (in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Commands:
list List available formulas from all search paths
@ -73,7 +68,7 @@ Search paths (in order of priority):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project - highest priority)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user)
4. $GT_ROOT/.beads/formulas/ (orchestrator, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Formulas in earlier paths shadow those with the same name in later paths.

View file

@ -333,7 +333,7 @@ Formula search paths (checked in order):
1. &lt;resolved-beads-dir&gt;/formulas/ (active project)
2. &lt;checkout-root&gt;/.beads/formulas/ (repo-local formulas)
3. ~/.beads/formulas/ (user level)
4. $GT_ROOT/.beads/formulas/ (orchestrator level, if GT_ROOT set)
4. $GT_ROOT/.beads/formulas/ (shared workspace root, if GT_ROOT set)
Examples:
bd mol seed mol-feature # Verify specific formula