docs: Clarify formula vs molecule semantics - formulas are NOT instructions

PROBLEM: Agents were reading formula files directly and manually creating beads
for each step, rather than using the cook→pour→molecule pipeline.

FIXES:
- polecat-CLAUDE.md: Changed "following the formula" to "work through your
  pinned molecule" and added explicit anti-pattern warning
- mol-polecat-work.formula.toml: Added note that formula defines template,
  use bd ready to find step beads
- docs/molecules.md: Added "Common Mistake" section with WRONG/RIGHT examples
- mol-*.formula.toml (5 files): Changed "execute this formula" to "work
  through molecules (poured from this formula)"

The key insight: Formulas are source templates (like source code). You never
read them directly. The cook → pour pipeline creates step beads for you.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
max
2026-01-02 17:25:47 -08:00
committed by Steve Yegge
parent 0bcd8acecb
commit 37ae702427
8 changed files with 40 additions and 9 deletions

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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

View File

@@ -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 <step>`
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)

View File

@@ -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)

View File

@@ -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 <step-id> # 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.

View File

@@ -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 <step>`
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)