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