From 68aa5921450e76de4b352774c5f72ad979231f8f Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Thu, 25 Dec 2025 12:29:54 -0800 Subject: [PATCH] docs: Propagate Rig/Cook/Run lifecycle terminology MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/architecture.md | 10 +++++++- docs/molecules.md | 48 ++++++++++++++++++------------------ docs/propulsion-principle.md | 42 ++++++++++++++++++++----------- docs/sling-design.md | 2 ++ 4 files changed, 62 insertions(+), 40 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index c0d8d258..1ff6684c 100644 --- 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 | diff --git a/docs/molecules.md b/docs/molecules.md index 564d53b9..74f28ce1 100644 --- 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. diff --git a/docs/propulsion-principle.md b/docs/propulsion-principle.md index 9928d207..912f1630 100644 --- 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. diff --git a/docs/sling-design.md b/docs/sling-design.md index ea9ce1b4..8cc26c4f 100644 --- 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