johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: discover Rig/Cook/Run lifecycle - the three phases of work (gt-8tmz)

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-23 19:19:04 -08:00
parent 733039a6d6
commit 4716b2ee57
4 changed files with 274 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/molecular-chemistry.md
View File

@@ -201,8 +201,22 @@ bd mol distill bd-abc123 --var feature=auth --var version=1.0
## The Polymorphic Bond Operator ## The Polymorphic Bond Operator
**Bond** is Gas Town's polymorphic combiner - it handles different operand Gas Town has **two composition operators** at different abstraction levels:
types with different phase behaviors:
| 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 ### Bond: Proto + Proto → Compound Proto

38
docs/molecule-algebra.md
View File

@@ -18,17 +18,35 @@ Molecules = Graph Algebra (mechanical, gt executes)
Steps = AI Cognition (agent provides) 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 ## Formulas and Cooking
> *"Let's cook."* - Walter White > *"Let's cook."* - Walter White
The molecule algebra lives above molecular chemistry. **Formulas** are the **Formulas** are the source code; **rigging** composes them; **cooking**
source code; **cooking** is the process that produces executable protos. produces executable artifacts.
### The Four-Tier Model ### The Artifact Tiers
``` ```
Formula (.formula.yaml) ← "The secret formula" (source code) 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) ↓ cook ← "Let's cook" (pre-expand, flatten)
Proto (frozen in beads) ← "Pure product" (compiled, flat graph) Proto (frozen in beads) ← "Pure product" (compiled, flat graph)
↓ pour/wisp ← Instantiate ↓ pour/wisp ← Instantiate
@@ -37,10 +55,22 @@ Mol/Wisp (running) ← The work flowing
| Tier | Name | Format | Nature | | 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 | | Compiled | **Proto** | Beads issue | Frozen, flat graph, fast instantiation |
| Running | **Mol/Wisp** | Beads issue | Active, flowing work | | 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? ### Why Cook?
Cooking **pre-expands** all composition at "compile time": Cooking **pre-expands** all composition at "compile time":

195
docs/rig-cook-run.md Normal file
View File

@@ -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.*

36
docs/vision.md
View File

@@ -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 | | 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 ### The Polymorphic Bond Operator
**Bond** adapts to its operands: **Bond** is the artifact-level combiner (distinct from **rig**, which composes
- Proto + Proto → Compound Proto (larger template) source formulas). Bond adapts to its operands:
- Proto + Mol → Spawn and attach (template melts into flow)
- Proto + Wisp → Spawn as vapor and attach | bond | Proto | Mol | Wisp |
- Mol + Mol → Link via dependencies |------|-------|-----|------|
| **Proto** | Compound Proto | Spawn + attach | Spawn wisp + attach |
| **Mol** | Spawn + attach | Link | Link |
| **Wisp** | Spawn + attach | Link | Link |
This enables patterns like: This enables patterns like:
- Patrol wisp discovers issue → bonds new work mol - Patrol wisp discovers issue → bonds new work mol