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

docs: consolidate Rig/Cook/Run into molecular-chemistry.md (gt-8tmz.32)

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-23 20:10:22 -08:00
parent 22c5fb6bdf
commit a84eb179db
4 changed files with 198 additions and 220 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/molecular-chemistry.md
View File

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

4
docs/molecule-algebra.md
View File

@@ -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?

201
docs/rig-cook-run.md
View File

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

2
docs/vision.md
View File

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