From 5e9b204d2b82bbd19b659b28e5dbd82d2ef6af96 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Wed, 24 Dec 2025 17:57:04 -0800 Subject: [PATCH] docs: humility pass - frame as exploration, not declaration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove "IDE of 2026" and "Integrated Delegation Engine" claims - Rename "Core Innovations" to "Ideas We're Exploring" - Remove "Universal" from data plane and propulsion docs - Add experimental status badges - Frame concepts as discovery, invite others to explore Closes gt-qvn7.5.2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 24 +++---- docs/architecture.md | 29 ++++---- docs/beads-data-plane.md | 15 ++--- docs/propulsion-principle.md | 8 +-- docs/sling-design.md | 9 ++- docs/vision.md | 124 +++++++++++++---------------------- 6 files changed, 87 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index 14a2982d..ddcdce42 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,19 @@ # Gas Town -**The IDE of 2026** - not Integrated Development Environment, but **Integrated Delegation Engine**. +> **Status**: Experimental (v0.1) - We're exploring these ideas and invite you to explore with us. -Gas Town turns Claude Code (the Steam Engine) into a Steam Train, with Beads as the globally distributed railway network. Workers spawn, work molecules, submit to merge queues, and get cleaned up - all autonomously. +Gas Town is an experiment in multi-agent coordination for Claude Code. It provides infrastructure for spawning workers, tracking work via molecules, and coordinating merges. -## The Vision +We think of it using steam-age metaphors: ``` Claude = Fire (the energy source) Claude Code = Steam Engine (harnesses the fire) Gas Town = Steam Train (coordinates engines on tracks) -Beads = Railroad Tracks (the persistent ledger of work) +Beads = Railroad Tracks (the persistent ledger) ``` -**Core principle: Gas Town is a Village.** - -Not a rigid hierarchy with centralized monitoring, but an anti-fragile village where every agent understands the whole system and can help any neighbor. If you see something stuck, you can help. The village heals itself through distributed awareness. +The goal is a "village" architecture - not rigid hierarchy, but distributed awareness where agents can help neighbors when something is stuck. Whether this actually works at scale is something we're still discovering. ## Install @@ -49,11 +47,15 @@ Town (~/gt/) ## Key Concepts +Ideas we're exploring: + - **Molecular Chemistry of Work**: Protos (templates) → Mols (flowing work) → Wisps (ephemeral) → Digests (outcomes) -- **Beads as Universal Data Plane**: Git-backed, human-readable, fractal ledger ([github.com/steveyegge/beads](https://github.com/steveyegge/beads)) -- **Antifragility**: Self-monitoring village, not centralized hierarchy -- **Propulsion Principle**: Agents pull work from molecules, don't wait for commands -- **Nondeterministic Idempotence**: Any worker can continue any molecule after crashes +- **Beads**: Git-backed, human-readable ledger for tracking work ([github.com/steveyegge/beads](https://github.com/steveyegge/beads)) +- **Village Model**: Distributed awareness instead of centralized monitoring +- **Propulsion Principle**: Agents pull work from molecules rather than waiting for commands +- **Nondeterministic Idempotence**: The idea that any worker can continue any molecule after crashes + +Some of these are implemented; others are still aspirational. See docs for current status. ## Commands diff --git a/docs/architecture.md b/docs/architecture.md index ba670002..d36a9bec 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -108,32 +108,29 @@ Gas Town has four AI agent roles: | **Refinery** | Per-rig | Merge queue processing, PR review, integration | | **Polecat** | Per-rig | Implementation work on assigned issues | -### Gas Town is a Village +### Village Architecture -**Core Operating Principle**: Gas Town is anti-fragile by design. +We're experimenting with a "village" model for agent coordination. -The anti-pattern we reject: +The pattern we're trying to avoid: ``` Centralized Monitor → watches all workers → single point of failure → fragile protocols → cascading failures ``` -The pattern we embrace: +The pattern we're exploring: ``` Every worker → understands the whole → can help any neighbor → peek is encouraged → distributed awareness - → ant colony without murder → self-healing system ``` -**Key properties:** +**Properties we're building toward:** -- **Distributed awareness**: Every agent understands the system deeply +- **Distributed awareness**: Agents understand the system, not just their task - **Mutual monitoring**: Any agent can peek at any other agent's health - **Collective intervention**: If you see something stuck, you can help -- **No single point of failure**: The village survives individual failures -- **Organic healing**: Problems get fixed by whoever notices them first -This is an ant colony, except the ants don't kill defective members - they help them recover. Workers who crash are respawned. Workers who get stuck are nudged. Workers who need help receive it. +Whether this achieves actual resilience at scale is still being tested. **Practical implications:** @@ -215,11 +212,13 @@ sync-branch: beads-sync # Separate branch for beads commits **Why sync-branch?** When multiple agents share a beads database, using a dedicated sync branch prevents beads commits from interleaving with code commits on feature branches. -#### Beads as Universal Data Plane (and Control Plane) +#### Beads as Data Plane -Beads is the data plane for ALL Gas Town operations. Everything flows through beads. +Gas Town uses Beads for persistence. We've combined the data plane and control plane: +- Traditional systems separate "what's stored" from "what to do next" +- We store both in beads, so agent state survives crashes -**Key architectural insight**: Gas Town intentionally blurs the line between data plane and control plane. In traditional systems: +In traditional systems: - **Data plane**: Stores information (issues, messages) - **Control plane**: Coordinates behavior (what to do next, who does what) @@ -745,9 +744,9 @@ gt spawn --issue gt-xyz --molecule mol-engineer-in-box ### Why Molecules? -**The core value proposition: Nondeterministic Idempotence** +**Goal: Nondeterministic Idempotence** -Molecules guarantee that any workflow, once started, will eventually complete correctly - even through crashes, context compaction, and agent restarts. This is what enables Gas Town to run autonomously for extended periods. +The idea is that workflows can survive crashes, context compaction, and restarts because state is stored externally in beads, not in agent memory. 1. **Crash recovery**: Agent dies mid-workflow? Restart and continue from last completed step. No work is lost. 2. **Context survival**: Claude's context compacts? Agent re-reads molecule state from beads and knows exactly where it was. diff --git a/docs/beads-data-plane.md b/docs/beads-data-plane.md index 2c8cf03f..2bbc3c37 100644 --- a/docs/beads-data-plane.md +++ b/docs/beads-data-plane.md @@ -1,19 +1,16 @@ -# Beads: The Universal Data Plane +# Beads as Data Plane -> **Status**: Canonical Architecture Documentation +> **Status**: Design documentation > **See also**: [pinned-beads-design.md](pinned-beads-design.md), [propulsion-principle.md](propulsion-principle.md) ## Overview -Gas Town agents coordinate through a single, unified data store: **Beads**. Every -piece of agent state - work assignments, mail messages, molecules, hooks - lives -in beads as issues with consistent field semantics. +Gas Town agents coordinate through **Beads** - a git-backed issue tracker. +We store agent state (work assignments, mail, molecules, hooks) as beads issues. -This document explains the universal data model that powers agent coordination. +## How We Use It -## The Core Insight - -Beads is not just an issue tracker. It's a **universal data plane** where: +We're treating beads as more than an issue tracker: - **Work molecules** are issues with steps as child issues - **Mail messages** are issues with sender/recipient encoded in fields diff --git a/docs/propulsion-principle.md b/docs/propulsion-principle.md index f13e23f0..e104c086 100644 --- a/docs/propulsion-principle.md +++ b/docs/propulsion-principle.md @@ -1,11 +1,11 @@ -# The Universal Gas Town Propulsion Principle +# The Propulsion Principle -> **Status**: Canonical Theory-of-Operation Documentation +> **Status**: Design document (experimental) > **See also**: [sling-design.md](sling-design.md) for implementation details -## The One Rule +## The Core Idea -Gas Town runs on a single, universal rule: +We're trying a simple rule for agent behavior: > **If you find something on your hook, YOU RUN IT.** diff --git a/docs/sling-design.md b/docs/sling-design.md index 8d26e3b2..4e293b57 100644 --- a/docs/sling-design.md +++ b/docs/sling-design.md @@ -1,17 +1,16 @@ -# The Sling: Gas Town's Universal Work Dispatch +# The Sling: Work Dispatch > **Status**: Design Draft > **Issue**: gt-z3qf ## The Propulsion Principle -Gas Town runs on one rule: +We're experimenting with a simple rule for agent behavior: > **If you find something on your hook, YOU RUN IT.** -No decisions. No "should I?" Just ignition. This is the Universal Gas Town -Propulsion Principle. Every agent - polecat, deacon, witness, refinery - follows -this single rule. +No decisions. No "should I?" Just ignition. We call this the Propulsion +Principle - agents execute what's on their hook rather than deciding what to do. ``` Hook has work → Work happens. diff --git a/docs/vision.md b/docs/vision.md index 7cb1bc3f..a06fb91b 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -1,15 +1,14 @@ -# Gas Town Vision: Core Innovations +# Gas Town: Ideas We're Exploring -> *"Work is fractal. Money is crystallized labor. Blockchain was the mechanism -> searching for its purpose."* +> **Status**: These are ideas we're experimenting with, not proven solutions. +> We're sharing them in case others find them useful or want to explore together. -Gas Town is the IDE of 2026 - not an Integrated Development Environment, but an -**Integrated Delegation Engine**. It turns Claude Code (the Steam Engine) into a -Steam Train, with Beads as the globally distributed railway network. +Gas Town is an experiment in multi-agent coordination. We use steam-age metaphors +to think about how work flows through a system of AI agents. --- -## Core Innovation 1: The Steam Engine Metaphor +## Idea 1: The Steam Engine Metaphor ``` Claude = Fire (the energy source) @@ -31,27 +30,29 @@ ensuring nothing is lost. --- -## Core Innovation 2: Gas Town is a Village +## Idea 2: Village vs Hierarchy -**The anti-pattern we reject:** +We're exploring whether a "village" model works better than centralized monitoring. + +**The pattern we're trying to avoid:** ``` Centralized Monitor → watches all workers → single point of failure → fragile protocols → cascading failures ``` -**The pattern we embrace:** +**The pattern we're experimenting with:** ``` Every worker → understands the whole → can help any neighbor → peek is encouraged → distributed awareness → ant colony without murder → self-healing system ``` -### The Antifragility Principle +### Aspiration: Antifragility -Gas Town is **anti-fragile by design**. Not merely resilient (bounces back from -stress), but anti-fragile (gets stronger from stress). +We're aiming for anti-fragility - a system that gets stronger from stress rather +than just surviving it. Whether we achieve this is an open question. -Key properties: +Properties we're trying to build: - **Distributed awareness**: Every agent understands the system deeply - **Mutual monitoring**: Any agent can peek at any other agent's health @@ -87,7 +88,7 @@ Workers who need help receive it. --- -## Core Innovation 3: Rig, Cook, Run +## Idea 3: Rig, Cook, Run Work in Gas Town flows through three phases: @@ -173,37 +174,26 @@ This enables patterns like: --- -## Core Innovation 4: Beads as Universal Data Plane +## Idea 4: Beads as Data Plane -Beads is Git + Issues + Molecules in one human-readable format. +We use Beads (a separate project) as the persistence layer. It's Git + Issues +in one human-readable format. -**Key properties:** -- **Git-backed**: Cryptographic hashes, Merkle trees, distributed -- **Human-readable**: Markdown, auditable, trustworthy -- **Fractal**: Work at any scale (task → epic → project → organization) -- **Federated**: Multi-repo, multi-org, platform-agnostic +**Properties we liked:** +- **Git-backed**: Uses existing infrastructure +- **Human-readable**: You can read `.beads/` files directly +- **Portable**: No vendor lock-in -**The insight:** -> "Git IS already a blockchain (Merkle tree, cryptographic hashes, distributed -> consensus). Beads is what blockchain was meant to enable - not coin -> speculation, but a universal ledger of work and capability." +See [github.com/steveyegge/beads](https://github.com/steveyegge/beads) for more. -### The GUPP Principle - -**Git as Universal Persistence Protocol** +### Git as Persistence Everything persists through git: - Issues are JSONL in `.beads/` - Molecules are structured issues - Mail is issues with labels -- Work history is commit history -- Entity chains are git histories -This means: -- Offline-first by default -- Distributed without infrastructure -- Auditable forever -- No vendor lock-in +This gives us offline-first operation and no infrastructure requirements. ### Control Plane = Data Plane @@ -222,7 +212,7 @@ There is no separate orchestrator - Beads IS the orchestrator. --- -## Core Innovation 5: The Patrol System +## Idea 5: Patrol Loops Gas Town runs on continuous monitoring loops called **patrols**. @@ -262,11 +252,10 @@ squashes to a summary digest. --- -## Core Innovation 6: Propulsion Over Protocol +## Idea 6: Propulsion Over Protocol -**The Propulsion Principle** - -Agents don't wait for explicit commands. They propel themselves through work: +We're experimenting with "pull-based" work where agents propel themselves +rather than waiting for explicit commands: 1. **Check hook/pin** - What's attached to me? 2. **Find next step** - What's ready in my molecule? @@ -274,8 +263,7 @@ Agents don't wait for explicit commands. They propel themselves through work: 4. **Advance** - Close step, find next 5. **Exit properly** - One of four exit types -This is **pull-based work**, not push-based commands. The molecule IS the -instruction set. The agent IS the executor. +The idea is pull-based work: the molecule provides instructions, the agent executes. ### Hooks and Pins @@ -311,9 +299,9 @@ The polecat never exits directly - it waits to be killed by the Witness. --- -## Core Innovation 7: Nondeterministic Idempotence +## Idea 7: Nondeterministic Idempotence -The key property enabling autonomous operation: +An idea we're exploring for crash recovery: - **Deterministic structure**: Molecule defines exactly what steps exist - **Nondeterministic execution**: Any worker can execute any ready step @@ -403,43 +391,23 @@ The flywheel spins. The village watches itself. The train keeps running. --- -## Why "IDE of 2026"? +## What We're Building Toward -The IDE evolved from text editor → syntax highlighting → autocomplete → AI suggestions. +We're interested in exploring AI as collaborator rather than just assistant. +Instead of AI suggesting code, what if AI could complete tasks while humans +review the outcomes? -The next evolution isn't better suggestions - it's **AI as worker, not assistant**. - -| 2024 IDE | 2026 IDE (Gas Town) | -|----------|---------------------| -| AI suggests code | AI writes code | -| Human reviews suggestions | Human reviews pull requests | -| AI helps with tasks | AI completes tasks | -| Single agent | Coordinated village | -| Context in memory | Context in Beads | -| Manual quality checks | Molecule-enforced gates | - -Gas Town is what happens when you treat AI agents as employees, not tools. +This is early-stage experimentation. Some of it works, much of it doesn't yet. +We're sharing it in case the ideas are useful to others. --- -## The Vision +## Summary -Gas Town is the **Integrated Delegation Engine**. +Gas Town explores: +- Multi-agent coordination via "molecules" of work +- Git-backed persistence via Beads +- Distributed monitoring via the "village" model +- Crash recovery via nondeterministic idempotence -For developers today. For all knowledge workers tomorrow. - -The world has never had a system where: -- Work is fractal and composable -- Execution is distributed and self-healing -- History is permanent and auditable -- Agents are autonomous yet accountable -- The village watches itself - -Beads is the ledger. -Gas Town is the execution engine. -The village watches itself. -The train keeps running. - ---- - -*"If you're not a little bit scared, you're not paying attention."* +We don't know if these ideas will pan out. We invite you to explore with us.