From 4716b2ee57d0e465cfa888c095a971195a036e5f Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 23 Dec 2025 19:19:04 -0800 Subject: [PATCH] docs: discover Rig/Cook/Run lifecycle - the three phases of work (gt-8tmz) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Key insight: Rig and Bond operate at different abstraction levels: - Rig = source-level composition (formula YAML with extends/compose) - Bond = artifact-level composition (protos, mols, wisps) This preserves the symmetric bond table while cleanly separating authoring (rig) from runtime composition (bond). New docs: - rig-cook-run.md: Canonical spec for the three phases Updated docs: - molecule-algebra.md: Three Phases section, rig/bond distinction - molecular-chemistry.md: Rig/bond clarification in bond section - vision.md: Core Innovation 3 now covers Rig/Cook/Run "This is a discovery, not an invention." πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/molecular-chemistry.md | 18 +++- docs/molecule-algebra.md | 38 ++++++- docs/rig-cook-run.md | 195 ++++++++++++++++++++++++++++++++++++ docs/vision.md | 36 +++++-- 4 files changed, 274 insertions(+), 13 deletions(-) create mode 100644 docs/rig-cook-run.md diff --git a/docs/molecular-chemistry.md b/docs/molecular-chemistry.md index a3d8f402..52984f53 100644 --- a/docs/molecular-chemistry.md +++ b/docs/molecular-chemistry.md @@ -201,8 +201,22 @@ bd mol distill bd-abc123 --var feature=auth --var version=1.0 ## The Polymorphic Bond Operator -**Bond** is Gas Town's polymorphic combiner - it handles different operand -types with different phase behaviors: +Gas Town has **two composition operators** at different abstraction levels: + +| Operator | Level | Inputs | When to Use | +|----------|-------|--------|-------------| +| **Rig** | Source | Formula + Formula | Authoring time, in YAML | +| **Bond** | Artifact | Proto/Mol/Wisp + any | Runtime, on cooked artifacts | + +**Rig** composes formulas (source YAML with `extends`, `compose`). +**Bond** composes artifacts (cooked protos, running mols/wisps). + +See [rig-cook-run.md](rig-cook-run.md) for the full Rig/Cook/Run lifecycle. + +--- + +**Bond** is Gas Town's polymorphic combiner for artifacts - it handles different +operand types with different phase behaviors: ### Bond: Proto + Proto β†’ Compound Proto diff --git a/docs/molecule-algebra.md b/docs/molecule-algebra.md index ac4971c8..e87abdf0 100644 --- a/docs/molecule-algebra.md +++ b/docs/molecule-algebra.md @@ -18,17 +18,35 @@ Molecules = Graph Algebra (mechanical, gt executes) Steps = AI Cognition (agent provides) ``` +## The Three Phases: Rig, Cook, Run + +Gas Town work flows through three phases: + +``` +RIG ────→ COOK ────→ RUN +``` + +| Phase | What Happens | Operator | Output | +|-------|--------------|----------|--------| +| **Rig** | Compose formulas (source level) | extends, compose | Compound Formula | +| **Cook** | Instantiate work | cook, pour, wisp | Proto, Mol, Wisp | +| **Run** | Execute steps | (agent execution) | Work done | + +See [rig-cook-run.md](rig-cook-run.md) for the full specification. + ## Formulas and Cooking > *"Let's cook."* - Walter White -The molecule algebra lives above molecular chemistry. **Formulas** are the -source code; **cooking** is the process that produces executable protos. +**Formulas** are the source code; **rigging** composes them; **cooking** +produces executable artifacts. -### The Four-Tier Model +### The Artifact Tiers ``` Formula (.formula.yaml) ← "The secret formula" (source code) + ↓ rig (compose) ← "Rig it up" (source-level composition) +Compound Formula ← Combined source ↓ cook ← "Let's cook" (pre-expand, flatten) Proto (frozen in beads) ← "Pure product" (compiled, flat graph) ↓ pour/wisp ← Instantiate @@ -37,10 +55,22 @@ Mol/Wisp (running) ← The work flowing | Tier | Name | Format | Nature | |------|------|--------|--------| -| Source | **Formula** | YAML | Composable, has macros/aspects | +| Source | **Formula** | YAML | Composable via `extends`/`compose` | | Compiled | **Proto** | Beads issue | Frozen, flat graph, fast instantiation | | Running | **Mol/Wisp** | Beads issue | Active, flowing work | +### Two Composition Operators + +| Operator | Level | Inputs | Output | +|----------|-------|--------|--------| +| **Rig** | Source | Formula + Formula | Compound Formula | +| **Bond** | Artifact | Proto/Mol/Wisp + any | Combined artifact | + +**Rig** is source-level composition (formula YAML with `extends`, `compose`). +**Bond** is artifact-level composition (combining cooked protos, linking mols). + +See the Bond Table in [rig-cook-run.md](rig-cook-run.md) for full semantics. + ### Why Cook? Cooking **pre-expands** all composition at "compile time": diff --git a/docs/rig-cook-run.md b/docs/rig-cook-run.md new file mode 100644 index 00000000..a51de122 --- /dev/null +++ b/docs/rig-cook-run.md @@ -0,0 +1,195 @@ +# Rig, Cook, Run: The Gas Town Work Lifecycle + +> **Status**: Canonical specification +> **Discovery**: 2025-12-23 + +## The Three Phases + +Gas Town work flows through three phases: + +``` +RIG ────→ COOK ────→ RUN +``` + +| Phase | What Happens | Input | Output | +|-------|--------------|-------|--------| +| **Rig** | Compose formulas | Formula YAML | Compound Formula | +| **Cook** | Instantiate work | Formula/Proto | Proto/Mol/Wisp | +| **Run** | Execute steps | Mol/Wisp | Work done | + +## Phase 1: Rig (Authoring) + +**Rigging** is source-level composition. You write formula YAML files that +reference and compose other formulas. + +```yaml +# shiny-enterprise.formula.yaml +formula: shiny-enterprise +extends: shiny # ← rigging: inherit from shiny +compose: + - expand: + target: implement + with: rule-of-five # ← rigging: expand with macro + - aspect: + pointcut: "implement.*" + with: security-audit # ← rigging: weave in aspect +``` + +**Rig operators** (in formula YAML): +- `extends` - inherit from another formula +- `compose` - apply transformations (expand, aspect, gate, loop, branch) + +**Rigging is static** - it happens before cooking, at authoring time. + +## Phase 2: Cook (Instantiation) + +**Cooking** transforms formulas into executable work. + +```bash +bd cook shiny-enterprise # Formula β†’ Proto (flat, expanded) +bd pour shiny-enterprise # Proto β†’ Mol (liquid, persistent) +bd wisp shiny-enterprise # Proto β†’ Wisp (vapor, ephemeral) +``` + +**Cook produces three artifact types:** + +| Command | Output | Phase of Matter | Storage | +|---------|--------|-----------------|---------| +| `bd cook` | Proto | Solid (frozen) | `.beads/` | +| `bd pour` | Mol | Liquid (flowing) | `.beads/` | +| `bd wisp` | Wisp | Vapor (ephemeral) | `.beads-wisp/` | + +**Cooking is deterministic** - same formula always produces same structure. + +## Phase 3: Run (Execution) + +**Running** executes the steps in a mol or wisp. + +```bash +gt sling shiny-enterprise polecat/alpha # Cook + assign + run +``` + +Agents execute mols/wisps by: +1. Reading the pinned work from their hook +2. Completing steps in dependency order +3. Closing steps as they finish +4. Exiting when all steps complete + +**Running is where cognition happens** - agents provide judgment, code, decisions. + +## The Two Composition Operators + +### Rig (Source-Level) + +Operates on **formulas** (YAML source files). + +``` +Formula + Formula ──rig──→ Compound Formula +``` + +Use rigging when: +- You're authoring new workflows +- You want version-controlled composition +- You need the full algebra (extends, aspects, macros) + +### Bond (Artifact-Level) + +Operates on **artifacts** (protos, mols, wisps). + +``` +Artifact + Artifact ──bond──→ Combined Artifact +``` + +**The Bond Table** (symmetric, complete): + +| bond | Proto | Mol | Wisp | +|------|-------|-----|------| +| **Proto** | Compound Proto | Spawn Mol, attach | Spawn Wisp, attach | +| **Mol** | Spawn Mol, attach | Link via edges | Link via edges | +| **Wisp** | Spawn Wisp, attach | Link via edges | Link via edges | + +Use bonding when: +- Runtime dynamic composition (patrol discovers issue β†’ bond bug mol) +- Ad-hoc combination without writing YAML +- Combining Mol Mall artifacts without source +- Programmatic proto generation + +## The Complete Picture + +``` + SOURCE LEVEL + ════════════ + +Formula ─────rig─────→ Compound Formula + β”‚ β”‚ + β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + cook + β”‚ + β–Ό + ARTIFACT LEVEL + ══════════════ + +Proto ──────bond─────→ Compound Proto + β”‚ \ β”‚ \ + β”‚ \ β”‚ \ +pour wisp pour wisp + β”‚ \ β”‚ \ + β–Ό β–Ό β–Ό β–Ό + Mol Wisp ───bond───→ Linked Work + β”‚ β”‚ + β””β”€β”€β”€β”¬β”€β”€β”€β”˜ + β”‚ + run + β”‚ + β–Ό + EXECUTION + ═════════ + + Steps complete + Work gets done + Digests created +``` + +## Vocabulary Summary + +| Term | Meaning | Example | +|------|---------|---------| +| **Formula** | Source YAML with composition rules | `shiny.formula.yaml` | +| **Rig** | Compose formulas (source level) | `extends: shiny` | +| **Cook** | Transform formula β†’ proto | `bd cook shiny` | +| **Proto** | Frozen workflow template | Cooked, immutable structure | +| **Pour** | Instantiate as mol (liquid) | `bd pour shiny` | +| **Wisp** | Instantiate as wisp (vapor) | `bd wisp shiny` | +| **Mol** | Flowing persistent work | Tracked in `.beads/` | +| **Wisp** | Ephemeral transient work | Tracked in `.beads-wisp/` | +| **Bond** | Combine artifacts (any level) | `bd bond proto-a proto-b` | +| **Sling** | Cook + assign to agent hook | `gt sling shiny polecat/alpha` | +| **Run** | Execute mol/wisp steps | Agent follows molecule | + +## The Metaphor Sources + +| Concept | Breaking Bad | Mad Max | +|---------|--------------|---------| +| Formula | Secret recipe | Fuel formula | +| Rig | Lab setup | War Rig assembly | +| Cook | "Let's cook" | Refining guzzoline | +| Proto | 99.1% pure crystal | Refined fuel | +| Pour/Wisp | Distribution | Pumping/vapor | +| Mol/Wisp | Product in use | Fuel burning | +| Bond | Cutting/mixing | Fuel blending | +| Sling | Dealing | Fuel dispatch | +| Run | The high | The chase | + +## Why This Matters + +1. **Clean separation**: Source composition (rig) vs artifact composition (bond) +2. **Symmetric operations**: Bond table is complete, no holes +3. **Clear phases**: Rig β†’ Cook β†’ Run, each with distinct purpose +4. **Metaphor coherence**: Breaking Bad + Mad Max vocabulary throughout +5. **Implementation clarity**: Each phase maps to specific commands + +--- + +*This is a discovery, not an invention. The structure was always there.* diff --git a/docs/vision.md b/docs/vision.md index 864caf36..95b9f001 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -87,9 +87,28 @@ Workers who need help receive it. --- -## Core Innovation 3: Molecular Chemistry of Work +## Core Innovation 3: Rig, Cook, Run -Work in Gas Town exists in three phases, following the states of matter: +Work in Gas Town flows through three phases: + +``` +RIG ────→ COOK ────→ RUN +``` + +| Phase | What Happens | Key Operator | +|-------|--------------|--------------| +| **Rig** | Compose formulas (source level) | extends, compose | +| **Cook** | Instantiate work (pour/wisp) | cook, pour, wisp | +| **Run** | Execute steps | Agent execution | + +**Rig** is source-level composition (formula YAML). +**Bond** is artifact-level composition (protos, mols, wisps). + +See [rig-cook-run.md](rig-cook-run.md) for the full specification. + +### The Three Phases of Matter + +Work artifacts exist in three phases: | Phase | Name | State | Behavior | |-------|------|-------|----------| @@ -138,11 +157,14 @@ Work in Gas Town exists in three phases, following the states of matter: ### The Polymorphic Bond Operator -**Bond** adapts to its operands: -- Proto + Proto β†’ Compound Proto (larger template) -- Proto + Mol β†’ Spawn and attach (template melts into flow) -- Proto + Wisp β†’ Spawn as vapor and attach -- Mol + Mol β†’ Link via dependencies +**Bond** is the artifact-level combiner (distinct from **rig**, which composes +source formulas). Bond adapts to its operands: + +| bond | Proto | Mol | Wisp | +|------|-------|-----|------| +| **Proto** | Compound Proto | Spawn + attach | Spawn wisp + attach | +| **Mol** | Spawn + attach | Link | Link | +| **Wisp** | Spawn + attach | Link | Link | This enables patterns like: - Patrol wisp discovers issue β†’ bonds new work mol