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

bd sync: 2025-12-22 22:04:04

Browse Source
This commit is contained in:
Steve Yegge
2025-12-22 22:04:04 -08:00
parent 1bac250f5d
commit c9dcaf0c51
12 changed files with 426 additions and 179 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
docs/architecture.md
View File

@@ -109,6 +109,40 @@ 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
**Core Operating Principle**: Gas Town is anti-fragile by design.
The anti-pattern we reject:
```
Centralized Monitor → watches all workers → single point of failure
→ fragile protocols → cascading failures
```
The pattern we embrace:
```
Every worker → understands the whole → can help any neighbor
→ peek is encouraged → distributed awareness
→ ant colony without murder → self-healing system
```
**Key properties:**
- **Distributed awareness**: Every agent understands the system deeply
- **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.
**Practical implications:**
1. **Every patrol includes neighbor-checking** - Witness peeks at Refinery, Refinery peeks at Witness, everyone can peek at the Deacon
2. **`gt peek` is universal vocabulary** - Any agent can check any other agent's health
3. **Exit state enums are teaching tools** - COMPLETED, BLOCKED, REFACTOR, ESCALATE are shared vocabulary
4. **Mail is the nervous system** - Asynchronous, persistent, auditable coordination
### Mail
Agents communicate via **mail** - messages stored as beads issues with `type=message`. Mail enables:
@@ -247,7 +281,7 @@ Gas Town uses a **two-level beads architecture**. This is critical to understand
**Common confusion:**
- `~/gt/gastown/.beads/` at the rig container level is **gitignored** (local runtime state)
- The real project beads live in the **gastown.git clones** (e.g., `crew/max/.beads/`)
- The real project beads live in the **gastown.git worktrees** (e.g., `crew/max/.beads/`)
- All clones share the same beads via git sync on the `beads-sync` branch
#### Mail Routing

472
docs/vision.md
View File

@@ -1,89 +1,191 @@
# Gas Town Vision
# Gas Town Vision: Core Innovations
> Work is fractal. Every piece of work can contain other work, recursively.
> The machine that processes this work must be equally fractal.
> *"Work is fractal. Money is crystallized labor. Blockchain was the mechanism
> searching for its purpose."*
## The Big Picture
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 **enterprise-grade cognitive processing machine**. It takes structured work in the form of molecules - arbitrarily complex guardrails that AI workers follow to completion - and processes that work with full auditability, crash recovery, and guaranteed progress.
---
Think of it as the **IDE of 2026**: not a text editor with AI autocomplete, but a complete execution environment where AI agents are first-class workers with proper lifecycle management, coordination protocols, and quality gates.
## Core Innovation 1: The Steam Engine Metaphor
## The Steam Engine
```
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)
```
Gas Town is an engine. Engines do work and generate steam.
The engine does work and generates steam. Gas Town coordinates many engines on
a shared network, routing work to the right engines, tracking outcomes, and
ensuring nothing is lost.
| Component | Role | Metaphor |
|-----------|------|----------|
| **Proto molecules** | Workflow templates | Fuel |
| **Mols** | Flowing work instances | Liquid fuel |
| **Wisps** | Transient execution traces | Steam |
| **Digests** | Compressed work records | Distillate |
**Protos** define how work should be done. **Wisps** are what happens during execution - transient, observable, but ultimately disposable. **Digests** are what remains: condensed permanent records of what was accomplished.
---
Just as steam can dissipate or be condensed into useful output, wisps can be:
- **Burned**: Discarded without trace (routine work, no audit needed)
- **Squashed**: Compressed into a digest (preserve the outcome, discard the trace)
## Core Innovation 2: Gas Town is a Village
This vocabulary runs through all of Gas Town: bond (instantiate), burn (discard), squash (compress), wisp (transient). It's a steam engine for work.
## Core Insights
### 1. Molecules Crystallize Workflows
Every organization has processes that humans follow: code review checklists, release procedures, onboarding steps. These exist as tribal knowledge, wiki pages, or forgotten documents.
**Molecules make these executable.** A molecule is a structured workflow template that:
- Defines exactly what steps must happen
- Encodes dependencies between steps
- Specifies quality gates that must pass
- Enables any worker to continue where another left off
```markdown
## Molecule: engineer-in-box
Full workflow from design to merge.
## Step: design
Think carefully about architecture. Write a brief design summary.
## Step: implement
Write the code. Follow codebase conventions.
Needs: design
## Step: test
Write and run tests. Cover edge cases.
Needs: implement
## Step: submit
Submit for merge via refinery.
Needs: test
**The anti-pattern we reject:**
```
Centralized Monitor → watches all workers → single point of failure
→ fragile protocols → cascading failures
```
This isn't just documentation - it's a **contract** that Gas Town enforces.
### 2. Nondeterministic Idempotence
The key property that enables autonomous operation:
- **Deterministic structure**: Molecule defines exactly what steps exist
- **Nondeterministic execution**: Any worker can execute any ready step
- **Idempotent progress**: Completed steps stay completed
**Why this matters:**
**The pattern we embrace:**
```
Worker A picks up "design" step
Worker A completes "design"
Worker A crashes mid-"implement"
Worker B restarts, queries ready work
Worker B sees "implement" is ready (design done, implement pending)
Worker B continues from exactly where A left off
Every worker → understands the whole → can help any neighbor
→ peek is encouraged → distributed awareness
→ ant colony without murder → self-healing system
```
No work is lost. No state is in memory. Any worker can continue any molecule. This is what makes 24/7 autonomous operation possible.
### The Antifragility Principle
### 3. Beads: The Universal Data Plane
Gas Town is **anti-fragile by design**. Not merely resilient (bounces back from
stress), but anti-fragile (gets stronger from stress).
Gas Town uses **Beads** as both control plane and data plane. Everything flows through Beads:
Key properties:
- **Distributed awareness**: Every agent understands the system deeply
- **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.
### Practical Implications
1. **Every patrol includes neighbor-checking**
- Polecats peek at other polecats
- Witness peeks at Refinery
- Refinery peeks at Witness
- Everyone can peek at the Deacon
2. **`gt peek` is universal vocabulary**
- Any agent can check any other agent's health
- Health states are shared vocabulary: idle, working, stuck, done
3. **Exit state enums are teaching tools**
- COMPLETED, BLOCKED, REFACTOR, ESCALATE
- Every agent learns these
- When peeking neighbors, agents recognize states and can help
4. **Mail is the nervous system**
- Asynchronous, persistent, auditable
- Survives crashes and restarts
- The village communicates through mail
---
## Core Innovation 3: Molecular Chemistry of Work
Work in Gas Town exists in three phases, following the states of matter:
| Phase | Name | State | Behavior |
|-------|------|-------|----------|
| **Solid** | Proto | Frozen template | Crystallized, immutable, reusable |
| **Liquid** | Mol | Flowing instance | Dynamic, adapting, persistent |
| **Vapor** | Wisp | Ephemeral trace | Transient, dissipates, operational |
### Phase Transition Operators
```
┌─────────────┐
│ PROTO │
│ (solid) │
└──────┬──────┘
│
┌─────────┼─────────┐
│ │ │
pour wisp distill
│ │ ↑
▼ ▼ │
┌─────────┐ ┌─────────┐ │
│ MOL │ │ WISP │ │
│(liquid) │ │ (vapor) │ │
└────┬────┘ └────┬────┘ │
│ │ │
squash squash │
│ │ │
▼ ▼ │
┌─────────┐ ┌─────────┐ │
│ DIGEST │ │evaporates│ │
│(crystal)│ │ or burn │ │
└─────────┘ └──────────┘ │
│ │
└───────────────────┘
(experience crystallizes)
```
| Operator | From | To | Effect |
|----------|------|------|--------|
| `pour` | Proto | Mol | Instantiate as persistent liquid |
| `wisp` | Proto | Wisp | Instantiate as ephemeral vapor |
| `bond` | Any + Any | Compound | Polymorphic combination |
| `squash` | Mol/Wisp | Digest | Condense to permanent record |
| `burn` | Wisp | Nothing | Discard without record |
| `distill` | Mol | Proto | Extract reusable template |
### The Polymorphic Bond Operator
**Bond** adapts to its operands:
- Proto + Proto → Compound Proto (larger template)
- Proto + Mol → Spawn and attach (template melts into flow)
- Proto + Wisp → Spawn as vapor and attach
- Mol + Mol → Link via dependencies
This enables patterns like:
- Patrol wisp discovers issue → bonds new work mol
- Feature work needs diagnostic → bonds vapor wisp
- Witness tracks polecats → bonds lease per polecat
---
## Core Innovation 4: Beads as Universal Data Plane
Beads is Git + Issues + Molecules 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
**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."
### The GUPP Principle
**Git as Universal Persistence Protocol**
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
### Control Plane = Data Plane
Gas Town uses Beads as both control plane and data plane:
| Data Type | Beads Representation |
|-----------|---------------------|
@@ -93,77 +195,120 @@ Gas Town uses **Beads** as both control plane and data plane. Everything flows t
| Merge requests | Queue entries (type=merge-request) |
| Agent state | Status on assigned issues |
**Key architectural insight**: The control state IS data in Beads. Molecule steps, dependencies, and status ARE the control plane. Agents read Beads to know what to do next.
The control state IS data in Beads. Agents read Beads to know what to do next.
There is no separate orchestrator - Beads IS the orchestrator.
This provides:
- **Fault tolerance**: Control state survives agent crashes
- **Observability**: `bd list` shows the full system state
- **Decentralization**: Each agent reads its own state from Beads
- **Recovery**: Restart = re-read Beads = continue from where you left off
---
There is no separate orchestrator maintaining workflow state. Beads IS the orchestrator.
## Core Innovation 5: The Patrol System
### 4. The OS Metaphor
Gas Town runs on continuous monitoring loops called **patrols**.
Gas Town is an operating system for AI work:
### Patrol Agents
| OS Concept | Gas Town |
|------------|----------|
| Kernel | Daemon |
| Process scheduler | Ready work + dependencies |
| Timer interrupts | Timed beads |
| Semaphores | Resource beads |
| Background services | Pinned beads |
| Process templates | Proto molecules |
| Running processes | Wisp molecules |
| Process termination | Burn (discard) or squash (save state) |
| IPC | Mail beads |
| Agent | Role | Patrol Focus |
|-------|------|--------------|
| **Deacon** | Town-level daemon | Health of all agents, plugin execution |
| **Witness** | Per-rig polecat monitor | Polecat lifecycle, nudging, cleanup |
| **Refinery** | Per-rig merge processor | Merge queue, validation, integration |
Just as Unix made computer resources manageable through a consistent process model, Gas Town makes AI agent work manageable through a consistent work model.
### Patrol Wisps
### 5. Hierarchical Auditability
Patrol agents run ephemeral wisps for their cycles:
- Wisp starts at cycle begin
- Steps complete as work progresses
- Wisp squashes to digest at cycle end
- New wisp spawns for next cycle
All work is tracked in a permanent hierarchical ledger:
This prevents accumulation: patrol work is vapor that condenses to minimal
digests, not liquid that pools forever.
### The Witness Polecat-Tracking Wisp
The Witness maintains a rolling wisp with a **lease** per active polecat:
```
Epic: Implement authentication
├── Task: Design auth flow
│ └── completed by polecat-nux, 2h
├── Task: Implement OAuth provider
│ └── completed by polecat-slit, 4h
├── Task: Add session management
│ └── completed by polecat-nux, 3h
└── Task: Write integration tests
└── in_progress, polecat-capable
wisp-witness-patrol
├── lease: furiosa (boot → working → done)
├── lease: nux (working)
└── lease: slit (done, closed)
```
Each lease is a bonded vapor molecule tracking one polecat's lifecycle.
When a polecat exits, its lease closes. When all leases close, the wisp
squashes to a summary digest.
---
## Core Innovation 6: Propulsion Over Protocol
**The Propulsion Principle**
Agents don't wait for explicit commands. They propel themselves through work:
1. **Check hook/pin** - What's attached to me?
2. **Find next step** - What's ready in my molecule?
3. **Execute** - Do the 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.
### Hooks and Pins
Agents have **hooks** where work hangs. Work gets **pinned** to hooks.
```
Agent (with hook)
└── pinned mol (or wisp)
├── step 1 (done)
├── step 2 (in_progress)
└── step 3 (pending)
```
This enables:
- **Audit trails**: Who did what, when, and how long it took
- **Observability**: Real-time visibility into swarm progress
- **Attribution**: Clear accountability for work quality
- **Analytics**: Understand where time goes, identify bottlenecks
- **Crash recovery**: Agent restarts, reads pinned mol, continues
- **Context survival**: Mol state persists across sessions
- **Handoff**: New session reads predecessor's pinned work
- **Observability**: `bd hook` shows what an agent is working on
### 6. Scalable Architecture
### The Four Exits
Gas Town scales through three mechanisms:
Every polecat converges on one of four exits:
| Exit | Meaning | Action |
|------|---------|--------|
| **COMPLETED** | Work finished | Submit to merge queue |
| **BLOCKED** | External dependency | File blocker, defer, notify |
| **REFACTOR** | Work too large | Break down, defer rest |
| **ESCALATE** | Need human judgment | Document, mail human, defer |
All exits pass through the exit-decision step. All exits end in request-shutdown.
The polecat never exits directly - it waits to be killed by the Witness.
---
## Core Innovation 7: Nondeterministic Idempotence
The key property enabling autonomous operation:
- **Deterministic structure**: Molecule defines exactly what steps exist
- **Nondeterministic execution**: Any worker can execute any ready step
- **Idempotent progress**: Completed steps stay completed
**Federation**: Multiple rigs across machines, coordinated through Beads sync
```
Town (global coordinator)
├── Rig: project-alpha (16 polecats, local)
├── Rig: project-beta (8 polecats, cloud VM)
└── Rig: project-gamma (32 polecats, cluster)
Worker A picks up "design" step
Worker A completes "design"
Worker A crashes mid-"implement"
Worker B restarts, queries ready work
Worker B sees "implement" is ready (design done, implement pending)
Worker B continues from exactly where A left off
```
**Tiering**: Hot work in active Beads, cold history archived
- Active issues: instant queries
- Recent history: fast retrieval
- Archive: compressed cold storage
No work is lost. No state is in memory. Any worker can continue any molecule.
**Temporal decay**: Wisps rise and dissipate, digests remain
- Wisp molecules: transient execution traces (the steam)
- Digests: permanent condensed records (the distillate)
- Burn or squash: cleanup happens automatically, leaving clean ledger
---
## The Agent Hierarchy
@@ -178,6 +323,11 @@ Town (global coordinator)
- Coordinates cross-project dependencies
- Handles strategic decisions
### Deacon (AI - Town-level daemon)
- Ensures patrol agents are running
- Executes maintenance plugins
- Handles lifecycle requests
### Witness (AI - Per-rig)
- Manages polecat lifecycle
- Detects stuck workers
@@ -188,29 +338,48 @@ Town (global coordinator)
- Reviews and integrates code
- Maintains branch hygiene
### Polecat (AI - Workers)
- Executes wisp molecules (not just "assigned work")
- Generates summaries and squashes to digest on completion
### Polecat (AI - Ephemeral workers)
- Executes work molecules
- Files discovered issues
- Ephemeral like the wisps they execute - spawn, work, disappear
- Ephemeral - spawn, work, disappear
## Quality Through Structure
---
Gas Town enforces quality through molecules, not prompts:
## The Steam Train in Action
**Without molecules:**
- Agent is prompted with instructions
- Works from memory
- Loses state on restart
- Quality depends on the prompt
Putting it all together:
**With molecules:**
- Agent follows persistent workflow
- State survives restarts
- Quality gates are enforced
- Any worker can continue
```
1. Human files issue in Beads
2. Mayor dispatches: gt spawn --issue <id>
3. Polecat created with:
- Fresh worktree
- mol-polecat-work pinned to hook
- Work assignment in mail
4. Deacon/Witness notified: POLECAT_STARTED
5. Witness bonds lease to patrol wisp
6. Polecat:
- Reads polecat.md, orients
- Reads mail, gets assignment
- Executes mol-polecat-work steps
- Makes commits, runs tests
- Submits to merge queue
- Exits via request-shutdown
7. Witness:
- Receives SHUTDOWN mail
- Closes polecat's lease
- Kills session, cleans up
8. Refinery:
- Processes merge queue
- Rebases, tests, merges
- Pushes to main
9. Digest created: work outcome crystallized
10. Loop: new work, new polecats, new cycles
```
The difference is like giving someone verbal instructions vs. giving them a checklist. Checklists win.
The flywheel spins. The village watches itself. The train keeps running.
---
## Why "IDE of 2026"?
@@ -223,39 +392,32 @@ The next evolution isn't better suggestions - it's **AI as worker, not assistant
| AI suggests code | AI writes code |
| Human reviews suggestions | Human reviews pull requests |
| AI helps with tasks | AI completes tasks |
| Single agent | Coordinated swarm |
| 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.
## Design Principles
---
1. **Work is data**: All work state lives in Beads, not agent memory
2. **Molecules over prompts**: Structured workflows beat clever instructions
3. **Crash-resistant by design**: Any agent can continue any work
4. **Hierarchical coordination**: Mayor → Witness → Refinery → Polecat
5. **Quality through structure**: Gates and checks built into molecules
6. **Observable by default**: `bd list` shows the full picture
## The Vision
## Where This Goes
Gas Town is the **Integrated Delegation Engine**.
### Now: Coding Agent Orchestrator
- Multi-polecat swarms on software projects
- Molecule-based quality workflows
- Merge queue processing
- Full audit trail
For developers today. For all knowledge workers tomorrow.
### Next: Knowledge Work Platform
- Support for non-code work (documents, research, analysis)
- Custom molecule libraries
- Enterprise integrations
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
### Future: Enterprise Cognitive Infrastructure
- Cross-team coordination
- Organization-wide work visibility
- Compliance and governance tooling
Beads is the ledger.
Gas Town is the execution engine.
The village watches itself.
The train keeps running.
---
*"The best tool is invisible. It doesn't help you work - it works."*
*"If you're not a little bit scared, you're not paying attention."*