gastown/docs/vision.md

Gas Town Vision

Work is fractal. Every piece of work can contain other work, recursively. The machine that processes this work must be equally fractal.

The Big Picture

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

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

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:

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

No work is lost. No state is in memory. Any worker can continue any molecule. This is what makes 24/7 autonomous operation possible.

3. Beads: The Universal Data Plane

Gas Town uses Beads as both control plane and data plane. Everything flows through Beads:

Data Type	Beads Representation
Work items	Issues (tasks, bugs, features)
Workflows	Molecules (type=molecule)
Messages	Mail beads (type=message)
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.

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.

4. The OS Metaphor

Gas Town is an operating system for AI work:

OS Concept	Gas Town
Kernel	Daemon
Process scheduler	Ready work + dependencies
Timer interrupts	Timed beads
Semaphores	Resource beads
Background services	Pinned beads
Process templates	Molecules
IPC	Mail beads

Just as Unix made computer resources manageable through a consistent process model, Gas Town makes AI agent work manageable through a consistent work model.

5. Hierarchical Auditability

All work is tracked in a permanent hierarchical ledger:

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

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

6. Scalable Architecture

Gas Town scales through three mechanisms:

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)

Tiering: Hot work in active Beads, cold history archived

• Active issues: instant queries
• Recent history: fast retrieval
• Archive: compressed cold storage

Temporal decay: Ephemeral execution traces, permanent outcomes

• Molecule step-by-step execution: memory only
• Work outcomes: permanent record
• Intermediate scaffolding: garbage collected

The Agent Hierarchy

Overseer (Human)

• Sets strategy and priorities
• Reviews and approves output
• Handles escalations
• Operates the system

Mayor (AI - Town-wide)

• Dispatches work across rigs
• Coordinates cross-project dependencies
• Handles strategic decisions

Witness (AI - Per-rig)

• Manages polecat lifecycle
• Detects stuck workers
• Handles session cycling

Refinery (AI - Per-rig)

• Processes merge queue
• Reviews and integrates code
• Maintains branch hygiene

Polecat (AI - Workers)

• Implements assigned work
• Follows molecule workflows
• Files discovered issues

Quality Through Structure

Gas Town enforces quality through molecules, not prompts:

Without molecules:

• Agent is prompted with instructions
• Works from memory
• Loses state on restart
• Quality depends on the prompt

With molecules:

• Agent follows persistent workflow
• State survives restarts
• Quality gates are enforced
• Any worker can continue

The difference is like giving someone verbal instructions vs. giving them a checklist. Checklists win.

Why "IDE of 2026"?

The IDE evolved from text editor → syntax highlighting → autocomplete → AI suggestions.

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

Where This Goes

Now: Coding Agent Orchestrator

• Multi-polecat swarms on software projects
• Molecule-based quality workflows
• Merge queue processing
• Full audit trail

Next: Knowledge Work Platform

• Support for non-code work (documents, research, analysis)
• Custom molecule libraries
• Enterprise integrations

Future: Enterprise Cognitive Infrastructure

• Cross-team coordination
• Organization-wide work visibility
• Compliance and governance tooling

---

"The best tool is invisible. It doesn't help you work - it works."