docs: Propagate Rig/Cook/Run lifecycle terminology

Updated the following docs to reference the Rig/Cook/Run lifecycle: - propulsion-principle.md: Added lifecycle overview, updated steam metaphor table - sling-design.md: Added see-also reference to molecular-chemistry.md - molecules.md: Added lifecycle summary diagram, formula context - architecture.md: Added Rig/Cook/Run overview, added Formula to concepts table 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-25 12:29:54 -08:00
parent c0ecd31699
commit 68aa592145
4 changed files with 62 additions and 40 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -364,11 +364,19 @@ composable, nondeterministic-idempotent workflow templates**. They encode struct
 workflows that any worker can execute, with full auditability and the ability for
 any worker to pick up where another left off.

+Work flows through the **Rig → Cook → Run** lifecycle:
+- **Rig**: Compose workflow formulas (YAML source files with `extends`, `compose`)
+- **Cook**: Transform formulas into executable protos (`bd cook` expands macros, applies aspects)
+- **Run**: Agents execute the cooked workflow (pour creates mols, wisp creates ephemeral traces)
+
+See [molecular-chemistry.md](molecular-chemistry.md) for the full lifecycle specification.
+
 ### Core Concepts

 | Concept | Name | Description |
 |---------|------|-------------|
-| Template | **Proto Molecule** | Read-only workflow pattern (the "fuel") |
+| Source | **Formula** | YAML workflow definition with composition rules (.formula.yaml) |
+| Template | **Proto Molecule** | Cooked workflow pattern (the "fuel") |
 | Running execution | **Wisp Molecule** | Transient execution trace (the "steam") |
 | Permanent record | **Digest** | Compressed summary of completed work (the "distillate") |
 | Individual step | **Atom/Step** | Smallest unit of work within a molecule |
--- a/docs/molecules.md
+++ b/docs/molecules.md
@@ -3,6 +3,7 @@
 This document covers the molecule system in depth.

 For an overview, see [architecture.md](architecture.md#molecules-composable-workflow-templates).
+For the full lifecycle (Rig → Cook → Run), see [molecular-chemistry.md](molecular-chemistry.md).

 ## Core Concepts

@@ -264,30 +265,29 @@ bd mol bond mol-code-review --var scope="src/"

 ## Lifecycle Summary

+Gas Town work follows the **Rig → Cook → Run** lifecycle:
+
 ```
-┌─────────────┐
-│   Proto     │  Template in molecules.jsonl
-│  (frozen)   │  labels: ["template"]
-└──────┬──────┘
-       │
-       ▼ bd mol bond [--wisp]
-┌─────────────┐
-│  Mol/Wisp   │  Active execution
-│ (flowing)   │  Mol: .beads/ | Wisp: .beads-wisp/
-└──────┬──────┘
-       │
-  ┌────┴────┐
-  ▼         ▼
-burn      squash
-  │         │
-  ▼         ▼
-(gone)   Digest
-         (permanent)
+           RIG (source)              COOK (artifact)           RUN (execution)
+      ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
+      │    Formula      │──────►│     Proto       │──────►│   Mol/Wisp      │
+      │   (.yaml)       │ cook  │  (cooked/frozen)│ pour/ │   (flowing)     │
+      │                 │       │                 │ wisp  │                 │
+      └─────────────────┘       └─────────────────┘       └────────┬────────┘
+                                                                   │
+                                                              ┌────┴────┐
+                                                              ▼         ▼
+                                                            burn      squash
+                                                              │         │
+                                                              ▼         ▼
+                                                           (gone)   Digest
+                                                                   (permanent)
 ```

-**Steam engine metaphor:**
- Proto = Fuel (potential energy)
- Mol/Wisp = Steam (kinetic energy)
- Digest = Distillate (crystallized work)
- Burn = Steam dissipates
- Squash = Steam condenses
+**Full lifecycle:**
+- **Formula** (.formula.yaml) = Recipe (source code for workflows)
+- **Proto** = Fuel (cooked template, ready to instantiate)
+- **Mol/Wisp** = Steam (active execution)
+- **Digest** = Distillate (crystallized work)
+
+See [molecular-chemistry.md](molecular-chemistry.md) for the complete specification.
--- a/docs/propulsion-principle.md
+++ b/docs/propulsion-principle.md
@@ -2,6 +2,7 @@

 > **Status**: Design document (experimental)
 > **See also**: [sling-design.md](sling-design.md) for implementation details
+> **See also**: [molecular-chemistry.md](molecular-chemistry.md) for the full Rig/Cook/Run lifecycle

 ## The Core Idea

@@ -36,14 +37,19 @@ Stateless agents can:

 ### 2. Work Is Molecule-Driven

-All work in Gas Town is encoded in **molecules** - crystallized workflow patterns
-stored as beads. A molecule defines:
+All work in Gas Town follows the **Rig → Cook → Run** lifecycle:
+- **Rig**: Compose workflow formulas (YAML source files)
+- **Cook**: Transform formulas into executable protos (expand macros, apply aspects)
+- **Run**: Agents execute the cooked workflow
+
+A molecule (proto, mol, or wisp) defines:
 - What steps need to happen
 - What order they happen in (via dependencies)
 - What each step should accomplish

 The agent doesn't decide what to do. The molecule tells it. The agent's job is
-execution, not planning.
+execution, not planning. See [molecular-chemistry.md](molecular-chemistry.md)
+for the full lifecycle.

 ### 3. Hooks Deliver Work

@@ -60,7 +66,8 @@ it's your work. Run it.

 ## The Sling Lifecycle

-The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
+The **sling** operation puts work on an agent's hook. This is the **Run** phase
+of the Rig → Cook → Run lifecycle (formulas have already been cooked into protos):

 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -68,11 +75,11 @@ The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
 ├─────────────────────────────────────────────────────────┤
 │                                                          │
 │  1. POUR (if proto)      2. ASSIGN           3. PIN     │
-│     proto → molecule        mol → agent         → hook  │
+│     proto → mol/wisp        mol → agent         → hook  │
 │                                                          │
 │  ┌─────────┐            ┌─────────┐        ┌─────────┐  │
-│  │  Proto  │ ────────►  │Molecule │ ─────► │  Hook   │  │
-│  │(catalog)│   pour     │(instance)│ assign │(pinned) │  │
+│  │  Proto  │ ────────►  │Mol/Wisp │ ─────► │  Hook   │  │
+│  │(cooked) │   pour     │(instance)│ assign │(pinned) │  │
 │  └─────────┘            └─────────┘        └─────────┘  │
 │                                                  │       │
 │                                            agent wakes   │
@@ -84,6 +91,9 @@ The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
 └─────────────────────────────────────────────────────────┘
 ```

+**Pour** instantiates a proto into a running mol (persistent) or wisp (ephemeral).
+This is a phase transition from the Cook output to the Run phase.
+
 **Key insight**: The agent never decides *whether* to run. The molecule tells
 it *what* to do. It executes until complete, then checks the hook again.

@@ -125,15 +135,17 @@ situation and make decisions. The new way requires only execution.

 ## The Steam Engine Metaphor

-Gas Town uses steam engine vocabulary throughout:
+Gas Town uses steam engine vocabulary throughout. The full lifecycle is
+**Rig → Cook → Run**:

-| Metaphor | Gas Town | Description |
-|----------|----------|-------------|
-| **Fuel** | Proto molecules | Templates that define workflows |
-| **Steam** | Wisps/Mols | Active execution traces |
-| **Distillate** | Digests | Condensed permanent records |
-| **Burn** | `bd mol burn` | Discard without record |
-| **Squash** | `bd mol squash` | Compress into digest |
+| Metaphor | Gas Town | Lifecycle Phase | Description |
+|----------|----------|-----------------|-------------|
+| **Recipe** | Formulas | Rig (source) | YAML files that compose workflows |
+| **Fuel** | Proto molecules | Cook (artifact) | Cooked templates ready to instantiate |
+| **Steam** | Wisps/Mols | Run (execution) | Active execution traces |
+| **Distillate** | Digests | (post-Run) | Condensed permanent records |
+| **Burn** | `bd mol burn` | (post-Run) | Discard without record |
+| **Squash** | `bd mol squash` | (post-Run) | Compress into digest |

 Claude is fire. Claude Code is a Steam engine. Gas Town is a Steam Train, with
 Beads as the tracks. Wisps are steam vapors that dissipate after work is done.
--- a/docs/sling-design.md
+++ b/docs/sling-design.md
@@ -2,6 +2,7 @@

 > **Status**: Implemented
 > **Updated**: 2024-12-24
+> **See also**: [molecular-chemistry.md](molecular-chemistry.md) for the full Rig → Cook → Run lifecycle

 ## The Propulsion Principle (GUPP)

@@ -187,5 +188,6 @@ gt mol status
 ## See Also

 - `docs/propulsion-principle.md` - GUPP design
+- `docs/molecular-chemistry.md` - Full Rig/Cook/Run lifecycle (formulas → protos → mols/wisps)
 - `docs/wisp-architecture.md` - Ephemeral wisps for patrol loops
 - `internal/wisp/` - Hook storage implementation