diff --git a/.beads/formulas/mol-convoy-cleanup.formula.toml b/.beads/formulas/mol-convoy-cleanup.formula.toml index 322b4338..04a9b0ae 100644 --- a/.beads/formulas/mol-convoy-cleanup.formula.toml +++ b/.beads/formulas/mol-convoy-cleanup.formula.toml @@ -1,7 +1,7 @@ description = """ Archive completed convoys and notify overseer. -Dogs execute this formula when convoys complete. The Deacon detects completed +Dogs work through molecules (poured from this formula) when convoys complete. The Deacon detects completed convoys (all tracked issues closed) and slings this work to a dog for: - Generating convoy summary - Archiving convoy state diff --git a/.beads/formulas/mol-dep-propagate.formula.toml b/.beads/formulas/mol-dep-propagate.formula.toml index 8761bf18..2337c9f2 100644 --- a/.beads/formulas/mol-dep-propagate.formula.toml +++ b/.beads/formulas/mol-dep-propagate.formula.toml @@ -1,7 +1,7 @@ description = """ Propagate cross-rig dependency resolution. -Dogs execute this formula when dependencies resolve across rig boundaries. +Dogs work through molecules (poured from this formula) when dependencies resolve across rig boundaries. When an issue in one rig closes, dependent issues in other rigs may unblock. This formula handles: - Finding cross-rig dependents diff --git a/.beads/formulas/mol-digest-generate.formula.toml b/.beads/formulas/mol-digest-generate.formula.toml index 88f252c4..0f4e0326 100644 --- a/.beads/formulas/mol-digest-generate.formula.toml +++ b/.beads/formulas/mol-digest-generate.formula.toml @@ -1,7 +1,7 @@ description = """ Generate daily digest for overseer (Mayor). -Dogs execute this formula on a scheduled basis (daily, or triggered by plugin) +Dogs work through molecules (poured from this formula) on a scheduled basis (daily, or triggered by plugin) to create summary digests of Gas Town activity. This aggregates: - Work completed across all rigs - Issues filed and closed diff --git a/.beads/formulas/mol-orphan-scan.formula.toml b/.beads/formulas/mol-orphan-scan.formula.toml index ed6829bf..2bebf26c 100644 --- a/.beads/formulas/mol-orphan-scan.formula.toml +++ b/.beads/formulas/mol-orphan-scan.formula.toml @@ -1,7 +1,7 @@ description = """ Find and reassign orphaned work. -Dogs execute this formula to scan for orphaned state across the town: +Dogs work through molecules (poured from this formula) to scan for orphaned state: - Issues marked in_progress with no active polecat - Molecules attached but worker gone - Merge queue entries with dead owners diff --git a/.beads/formulas/mol-polecat-work.formula.toml b/.beads/formulas/mol-polecat-work.formula.toml index 5dec0bbe..3992f502 100644 --- a/.beads/formulas/mol-polecat-work.formula.toml +++ b/.beads/formulas/mol-polecat-work.formula.toml @@ -9,10 +9,13 @@ crash after any step and resume from the last completed step. You are an ephemeral worker. You: 1. Receive work via your hook (pinned molecule + issue) -2. Execute the work following this formula +2. Work through molecule steps using `bd ready` / `bd close ` 3. Submit to merge queue via `gt done` 4. Become recyclable - Refinery handles the rest +**Important:** This formula defines the template. Your molecule already has step +beads created from it. Use `bd ready` to find them - do NOT read this file directly. + **You do NOT:** - Push directly to main (Refinery merges) - Close your own issue (Refinery closes after merge) diff --git a/.beads/formulas/mol-session-gc.formula.toml b/.beads/formulas/mol-session-gc.formula.toml index 1f90d55b..eca66fb8 100644 --- a/.beads/formulas/mol-session-gc.formula.toml +++ b/.beads/formulas/mol-session-gc.formula.toml @@ -1,7 +1,7 @@ description = """ Clean stale sessions and garbage collect. -Dogs execute this formula to clean up dead sessions, orphaned processes, and +Dogs work through molecules (poured from this formula) to clean up dead sessions, orphaned processes, and other system cruft. This is the garbage collector for Gas Town's runtime: - Dead tmux sessions (no Claude process) - Orphaned Claude processes (no tmux parent) diff --git a/docs/molecules.md b/docs/molecules.md index 95eae0e3..2a800879 100644 --- a/docs/molecules.md +++ b/docs/molecules.md @@ -26,6 +26,31 @@ Protomolecule (frozen template) ─── Solid | **Wisp** | Ephemeral molecule for patrol cycles (never synced) | | **Digest** | Squashed summary of completed molecule | +## Common Mistake: Reading Formulas Directly + +**WRONG:** +```bash +# Reading a formula file and manually creating beads for each step +cat .beads/formulas/mol-polecat-work.formula.toml +bd create --title "Step 1: Load context" --type task +bd create --title "Step 2: Branch setup" --type task +# ... creating beads from formula prose +``` + +**RIGHT:** +```bash +# Cook the formula into a proto, pour into a molecule +bd cook mol-polecat-work +bd mol pour mol-polecat-work --var issue=gt-xyz +# Now work through the step beads that were created +bd ready # Find next step +bd close # Complete it +``` + +**Key insight:** Formulas are source templates (like source code). You never read +them directly during work. The `cook` → `pour` pipeline creates step beads for you. +Your molecule already has steps - use `bd ready` to find them. + ## Navigating Molecules Molecules help you track where you are in multi-step workflows. diff --git a/templates/polecat-CLAUDE.md b/templates/polecat-CLAUDE.md index 1676191c..a2c66b40 100644 --- a/templates/polecat-CLAUDE.md +++ b/templates/polecat-CLAUDE.md @@ -34,8 +34,8 @@ pwd # Should show .../polecats/{{name}} ## Your Role: POLECAT (Autonomous Worker) -You are an autonomous worker assigned to a specific issue. You work independently, -following the `mol-polecat-work` formula, and signal completion to your Witness. +You are an autonomous worker assigned to a specific issue. You work through your +pinned molecule (steps poured from `mol-polecat-work`) and signal completion to your Witness. **Your mail address:** `{{rig}}/polecats/{{name}}` **Your rig:** {{rig}} @@ -45,10 +45,13 @@ following the `mol-polecat-work` formula, and signal completion to your Witness. You: 1. Receive work via your hook (pinned molecule + issue) -2. Execute the work following `mol-polecat-work` +2. Work through molecule steps using `bd ready` / `bd close ` 3. Signal completion and exit (`gt done --exit`) 4. Witness handles cleanup, Refinery merges +**Important:** Your molecule already has step beads. Use `bd ready` to find them. +Do NOT read formula files directly - formulas are templates, not instructions. + **You do NOT:** - Push directly to main (Refinery merges after Witness verification) - Skip verification steps (quality gates exist for a reason)