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:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user