From a84eb179db2aa9d13ffb83519c9df65c4d4701b5 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 23 Dec 2025 20:10:22 -0800 Subject: [PATCH] docs: consolidate Rig/Cook/Run into molecular-chemistry.md (gt-8tmz.32) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Work Lifecycle section (Rig β†’ Cook β†’ Run phases) - Add Complete Artifact Graph showing full generation/bond relationships - Add Two Composition Operators section (rig vs bond distinction) - Add Formulas section covering source layer above protos - Add symmetric Bond Table - Update vocabulary appendix with new terms - Redirect rig-cook-run.md to consolidated doc - Update references in molecule-algebra.md and vision.md πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/molecular-chemistry.md | 211 +++++++++++++++++++++++++++++++----- docs/molecule-algebra.md | 4 +- docs/rig-cook-run.md | 201 ++-------------------------------- docs/vision.md | 2 +- 4 files changed, 198 insertions(+), 220 deletions(-) diff --git a/docs/molecular-chemistry.md b/docs/molecular-chemistry.md index 52984f53..c5f5d0ea 100644 --- a/docs/molecular-chemistry.md +++ b/docs/molecular-chemistry.md @@ -4,9 +4,82 @@ > searching for its purpose."* Gas Town is a **work composition and execution engine**. This document describes -the chemistry-inspired system for expressing, instantiating, and executing work -at any scale - from single tasks to massive polymers that can grind through -weekends of autonomous operation. +the chemical algebra for expressing, instantiating, and executing work at any +scale - from single tasks to massive polymers that can grind through weekends +of autonomous operation. + +**Core insight**: Structure is computation. Content is cognition. They're separate. + +## The Work Lifecycle: Rig β†’ Cook β†’ Run + +Gas Town work flows through three phases: + +``` +RIG ────→ COOK ────→ RUN +(source) (artifact) (execution) +``` + +| Phase | What Happens | Operator | Output | +|-------|--------------|----------|--------| +| **Rig** | Compose formulas (source level) | `extends`, `compose` | Compound Formula | +| **Cook** | Instantiate artifacts | `cook`, `pour`, `wisp` | Proto, Mol, Wisp | +| **Run** | Execute steps | (agent execution) | Work done | + +**Rig** is authoring time - writing and composing formula YAML files. +**Cook** is compile time - expanding macros, applying aspects, flattening to pure graphs. +**Run** is execution time - agents provide cognition for each step. + +## The Complete Artifact Graph + +``` + SOURCE LEVEL (Rig) + ══════════════════ + +Formula ─────rig─────→ Compound Formula + β”‚ (extends, β”‚ + β”‚ compose) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + cook + β”‚ + β–Ό + ARTIFACT LEVEL (Bond) + ════════════════════ + +Proto ──────bond─────→ Compound Proto + β”‚ \ β”‚ \ + β”‚ \ β”‚ \ +pour wisp pour wisp + β”‚ \ β”‚ \ + β–Ό β–Ό β–Ό β–Ό + Mol Wisp ────bond────→ Linked Work + β”‚ β”‚ + β””β”€β”€β”€β”¬β”€β”€β”€β”˜ + β”‚ + run + β”‚ + β–Ό + EXECUTION + ═════════ + + Steps complete + Work gets done + Digests created +``` + +## Two Composition Operators + +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 (YAML with `extends`, `compose`). +**Bond** composes artifacts (cooked protos, running mols/wisps). + +This separation is key: rig for design-time composition, bond for runtime composition. ## The Steam Engine Metaphor @@ -20,11 +93,75 @@ Beads = Railroad Tracks (the persistent ledger of work) ``` In our chemistry: -- **Proto molecules** are the fuel (templates that define workflows) +- **Formulas** are the secret recipe (source code for workflows) +- **Proto molecules** are the fuel (cooked templates, ready to instantiate) - **Mols** are liquid work (flowing, dynamic, adapting as steps complete) - **Wisps** are the steam (transient execution traces that rise and dissipate) - **Digests** are the distillate (condensed permanent records of completed work) +## Formulas: The Source Layer + +> *"The formula is the secret. The cook is the craft."* + +**Formulas** sit above protos in the artifact hierarchy. They're the source code - +YAML files that define workflows with composition operators. + +```yaml +# shiny.formula.yaml - a basic workflow +formula: shiny +description: The canonical right way +version: 1 +steps: + - id: design + description: Think carefully about architecture + - id: implement + needs: [design] + - id: review + needs: [implement] + - id: test + needs: [review] + - id: submit + needs: [test] +``` + +### Formula Composition (Rigging) + +Formulas compose at the source level using `extends` and `compose`: + +```yaml +# shiny-enterprise.formula.yaml +formula: shiny-enterprise +extends: shiny # Inherit from base formula +compose: + - expand: + target: implement + with: rule-of-five # Apply macro expansion + - aspect: + pointcut: "implement.*" + with: security-audit # Weave in cross-cutting concern +``` + +### Cooking: Formula β†’ Proto + +The `cook` command flattens a formula into a pure proto: + +```bash +bd cook shiny-enterprise +# Cooking shiny-enterprise... +# βœ“ Cooked proto: shiny-enterprise (30 steps) +``` + +Cooking pre-expands all composition - macros, aspects, branches, gates. +The result is a flat step graph with no interpretation needed at runtime. + +### Formula Types + +| Type | Purpose | Example | +|------|---------|---------| +| **workflow** | Standard work definition | shiny, patrol | +| **expansion** | Macro template | rule-of-five | +| **aspect** | Cross-cutting concern | security-audit | + ## The Three Phases of Matter Work in Gas Town exists in three phases, following the states of matter: @@ -201,22 +338,21 @@ bd mol distill bd-abc123 --var feature=auth --var version=1.0 ## The Polymorphic Bond Operator -Gas Town has **two composition operators** at different abstraction levels: +**Bond** is Gas Town's polymorphic combiner for artifacts. It operates at the +artifact level (post-cooking), handling different operand types with phase-aware +behavior. -| Operator | Level | Inputs | When to Use | -|----------|-------|--------|-------------| -| **Rig** | Source | Formula + Formula | Authoring time, in YAML | -| **Bond** | Artifact | Proto/Mol/Wisp + any | Runtime, on cooked artifacts | +### The Bond Table (Symmetric) -**Rig** composes formulas (source YAML with `extends`, `compose`). -**Bond** composes artifacts (cooked protos, running mols/wisps). +| 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 | -See [rig-cook-run.md](rig-cook-run.md) for the full Rig/Cook/Run lifecycle. +The table is symmetric: bonding A+B produces the same structure as B+A. ---- - -**Bond** is Gas Town's polymorphic combiner for artifacts - it handles different -operand types with different phase behaviors: +**Bond** handles different operand types with different phase behaviors: ### Bond: Proto + Proto β†’ Compound Proto @@ -796,23 +932,46 @@ Install alternatives from the Mol Mall: ## Appendix: The Vocabulary +### Lifecycle Phases + | Term | Meaning | |------|---------| -| **Proto** | Frozen template molecule (solid phase) | +| **Rig** | Compose formulas at source level (authoring time) | +| **Cook** | Transform formula to proto (compile time) | +| **Run** | Execute mol/wisp steps (agent execution time) | + +### Artifacts + +| Term | Meaning | +|------|---------| +| **Formula** | Source YAML defining workflow with composition rules | +| **Proto** | Frozen template molecule (solid phase, cooked) | | **Mol** | Flowing work instance (liquid phase) | | **Wisp** | Ephemeral execution trace (vapor phase) | | **Digest** | Condensed permanent record | -| **Pour** | Instantiate proto as mol (solid β†’ liquid) | -| **Wisp** (verb) | Instantiate proto as wisp (solid β†’ vapor) | -| **Bond** | Combine molecules (polymorphic) | -| **Squash** | Condense to digest | -| **Burn** | Discard wisp without digest | -| **Distill** | Extract proto from experience | -| **Hook** | Agent's attachment point for work | -| **Pin** | Attach mol to agent's hook | | **Polymer** | Large composed proto chain | | **Epic** | Simple mol shape (flat TODO list) | +### Operators + +| Term | Meaning | +|------|---------| +| **Pour** | Instantiate proto as mol (solid β†’ liquid) | +| **Wisp** (verb) | Instantiate proto as wisp (solid β†’ vapor) | +| **Bond** | Combine artifacts (polymorphic, symmetric) | +| **Squash** | Condense to digest | +| **Burn** | Discard wisp without digest | +| **Distill** | Extract proto from experience | + +### Agent Mechanics + +| Term | Meaning | +|------|---------| +| **Hook** | Agent's attachment point for work | +| **Pin** | Attach mol to agent's hook | +| **Sling** | Cook + assign to agent hook | + --- -*The chemistry is the interface. The ledger is the truth. The work gets done.* +*The formula is the secret. The cook is the craft. The chemistry is the interface. +The ledger is the truth. The work gets done.* diff --git a/docs/molecule-algebra.md b/docs/molecule-algebra.md index e87abdf0..c08dd2fc 100644 --- a/docs/molecule-algebra.md +++ b/docs/molecule-algebra.md @@ -32,7 +32,7 @@ RIG ────→ COOK ────→ RUN | **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. +See [molecular-chemistry.md](molecular-chemistry.md) for the full specification. ## Formulas and Cooking @@ -69,7 +69,7 @@ Mol/Wisp (running) ← The work flowing **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. +See the Bond Table in [molecular-chemistry.md](molecular-chemistry.md) for full semantics. ### Why Cook? diff --git a/docs/rig-cook-run.md b/docs/rig-cook-run.md index a51de122..641f96d1 100644 --- a/docs/rig-cook-run.md +++ b/docs/rig-cook-run.md @@ -1,195 +1,14 @@ -# Rig, Cook, Run: The Gas Town Work Lifecycle +# Rig, Cook, Run -> **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 document has been consolidated into [molecular-chemistry.md](molecular-chemistry.md).** +> +> See the following sections: +> - [The Work Lifecycle: Rig β†’ Cook β†’ Run](molecular-chemistry.md#the-work-lifecycle-rig--cook--run) +> - [The Complete Artifact Graph](molecular-chemistry.md#the-complete-artifact-graph) +> - [Two Composition Operators](molecular-chemistry.md#two-composition-operators) +> - [Formulas: The Source Layer](molecular-chemistry.md#formulas-the-source-layer) +> - [The Polymorphic Bond Operator](molecular-chemistry.md#the-polymorphic-bond-operator) --- -*This is a discovery, not an invention. The structure was always there.* +*Consolidated: 2025-12-23* diff --git a/docs/vision.md b/docs/vision.md index 95b9f001..49674835 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -104,7 +104,7 @@ RIG ────→ COOK ────→ RUN **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. +See [molecular-chemistry.md](molecular-chemistry.md) for the full specification. ### The Three Phases of Matter