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)