From 8bfd061f4b225bcc880bd11b7e47e3e11ce49bb7 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Mon, 22 Dec 2025 12:31:31 -0800
Subject: [PATCH] Add canonical Propulsion Principle documentation (gt-7hor)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents the Universal Gas Town Propulsion Principle - the single rule
that drives all agent behavior: "If you find something on your hook,
YOU RUN IT."

Covers:
- The One Rule (hook has work → work happens)
- Why it works (stateless agents, molecule-driven)
- The sling lifecycle diagram
- Agent startup protocol
- Examples and anti-patterns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/propulsion-principle.md | 263 +++++++++++++++++++++++++++++++++++
 1 file changed, 263 insertions(+)
 create mode 100644 docs/propulsion-principle.md

diff --git a/docs/propulsion-principle.md b/docs/propulsion-principle.md
new file mode 100644
index 00000000..ebce3711
--- /dev/null
+++ b/docs/propulsion-principle.md
@@ -0,0 +1,263 @@
+# The Universal Gas Town Propulsion Principle
+
+> **Status**: Canonical Theory-of-Operation Documentation
+> **See also**: [sling-design.md](sling-design.md) for implementation details
+
+## The One Rule
+
+Gas Town runs on a single, universal rule:
+
+> **If you find something on your hook, YOU RUN IT.**
+
+No decisions. No "should I?" No discretionary pondering. Just ignition.
+
+```
+Hook has work → Work happens.
+```
+
+That's the whole engine. Everything else is plumbing.
+
+## Why It Works
+
+The Propulsion Principle works because of three interlocking design decisions:
+
+### 1. Agents Are Stateless
+
+Agents have no memory between sessions. When a session starts, the agent has
+no inherent knowledge of what it was doing before, what the current project
+state is, or what decisions led to its existence.
+
+This sounds like a limitation, but it's actually the foundation of resilience.
+Stateless agents can:
+- Be restarted at any time without data loss
+- Survive context compaction (the agent re-reads its state)
+- Hand off to new sessions seamlessly
+- Recover from crashes without corruption
+
+### 2. Work Is Molecule-Driven
+
+All work in Gas Town is encoded in **molecules** - crystallized workflow patterns
+stored as beads. A molecule 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.
+
+### 3. Hooks Deliver Work
+
+Work arrives on an agent's **hook** - a pinned molecule or assigned issue that
+represents "your current work." When an agent wakes up:
+
+1. Check the hook
+2. Found something? **Execute it.**
+3. Nothing? Check mail for new assignments.
+4. Repeat.
+
+The hook eliminates decision-making about what to work on. If it's on your hook,
+it's your work. Run it.
+
+## The Sling Lifecycle
+
+The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    gt sling lifecycle                    │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  1. SPAWN (if proto)     2. ASSIGN           3. PIN     │
+│     proto → molecule        mol → agent         → hook  │
+│                                                          │
+│  ┌─────────┐            ┌─────────┐        ┌─────────┐  │
+│  │  Proto  │ ────────►  │Molecule │ ─────► │  Hook   │  │
+│  │(catalog)│   spawn    │(instance)│ assign │(pinned) │  │
+│  └─────────┘            └─────────┘        └─────────┘  │
+│                                                  │       │
+│                                            agent wakes   │
+│                                                  │       │
+│                                                  ▼       │
+│                                            ┌─────────┐  │
+│                                            │ IGNITION│  │
+│                                            └─────────┘  │
+└─────────────────────────────────────────────────────────┘
+```
+
+**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.
+
+## Agent Startup Protocol
+
+Every agent follows the same startup protocol:
+
+```bash
+# 1. Check your hook
+gt mol status                  # What's on my hook?
+
+# 2. Found something?
+# Output tells you exactly what to do.
+# Follow the molecule phases.
+
+# 3. Nothing on hook?
+gt mail inbox                  # Check for new assignments
+
+# 4. Repeat
+```
+
+**Old way** (too much thinking):
+```bash
+gt mail inbox
+if has_molecule; then
+    gt molecule instantiate ...
+    # figure out what to do...
+fi
+```
+
+**New way** (propulsion):
+```bash
+gt mol status              # What's on my hook?
+# Just follow the molecule phases
+```
+
+The difference is profound: the old way requires the agent to understand its
+situation and make decisions. The new way requires only execution.
+
+## The Steam Engine Metaphor
+
+Gas Town uses steam engine vocabulary throughout:
+
+| 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 |
+
+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.
+
+The Propulsion Principle is the physics that makes the engine go:
+**Hook has work → Work happens.**
+
+## Examples
+
+### Good: Following the Principle
+
+```markdown
+## Polecat Startup
+
+1. Run `gt prime` to load context
+2. Check `gt mol status` for pinned work
+3. Found molecule? Execute each step in order.
+4. Complete? Run `gt done` to submit to merge queue.
+5. Request shutdown. You're ephemeral.
+```
+
+### Good: Witness Patrol
+
+```markdown
+## Witness Cycle
+
+1. Bond a wisp molecule for this patrol cycle
+2. Execute patrol steps (check polecats, check refinery)
+3. Squash the wisp when done (creates digest)
+4. Sleep until next cycle
+5. Repeat forever
+```
+
+### Anti-Pattern: Decision Paralysis
+
+```markdown
+## DON'T DO THIS
+
+1. Wake up
+2. Think about what I should do...
+3. Look at various issues and prioritize them
+4. Decide which one seems most important
+5. Start working on it
+```
+
+This violates propulsion. If there's nothing on your hook, you check mail or
+wait. You don't go looking for work to decide to do. Work is *slung* at you.
+
+### Anti-Pattern: Ignoring the Hook
+
+```markdown
+## DON'T DO THIS
+
+1. Wake up
+2. See molecule on my hook
+3. But I notice a more interesting issue over there...
+4. Work on that instead
+```
+
+If it's on your hook, you run it. Period. The hook is not a suggestion.
+
+### Anti-Pattern: Partial Execution
+
+```markdown
+## DON'T DO THIS
+
+1. Wake up
+2. See molecule with 5 steps
+3. Complete step 1
+4. Get bored, request shutdown
+5. Leave steps 2-5 incomplete
+```
+
+Molecules are executed to completion. If you can't finish, you squash or burn
+explicitly. You don't just abandon mid-flight.
+
+## Why Not Just Use TODO Lists?
+
+LLM agents have short memories. A TODO list in the prompt will be forgotten
+during context compaction. A molecule in beads survives indefinitely because
+it's stored outside the agent's context.
+
+**Molecules are external TODO lists that persist across sessions.**
+
+This is the secret to autonomous operation: the agent's instructions survive
+the agent's death. New agent, same molecule, same progress point.
+
+## Relationship to Nondeterministic Idempotence
+
+The Propulsion Principle enables **nondeterministic idempotence** - the property
+that any workflow will eventually complete correctly, regardless of which agent
+runs which step, and regardless of crashes or restarts.
+
+| Property | How Propulsion Enables It |
+|----------|---------------------------|
+| **Deterministic structure** | Molecules define exact steps |
+| **Nondeterministic execution** | Any agent can run any ready step |
+| **Idempotent progress** | Completed steps stay completed |
+| **Crash recovery** | Agent dies, molecule persists |
+| **Session survival** | Restart = re-read hook = continue |
+
+## Implementation Status
+
+The Propulsion Principle is documented but not yet fully implemented in the
+`gt sling` command. See:
+
+- **gt-z3qf**: Overhaul gt mol to match bd mol chemistry interface
+- **gt-7hor**: This documentation (Document the Propulsion Principle)
+
+Current agents use mail and molecule attachment, which works but has more
+ceremony than the pure propulsion model.
+
+## Summary
+
+1. **One rule**: If you find something on your hook, you run it.
+2. **Stateless agents**: No memory between sessions - molecules provide continuity.
+3. **Molecule-driven**: Work is defined by molecules, not agent decisions.
+4. **Hook delivery**: Work arrives via sling, sits on hook until complete.
+5. **Just execute**: No thinking about whether. Only doing.
+
+The Propulsion Principle is what makes Gas Town work as an autonomous,
+distributed, crash-resilient execution engine. It's the physics of the steam
+train.
+
+```
+Hook has work → Work happens.
+```