docs: comprehensive molecule architecture and vision
- Add detailed Molecules section to architecture.md covering: - Core concepts (molecule, atom, bond, polymer, instance) - Prose-based format with ## Step: definitions - Composition via Includes directive - Nondeterministic idempotence explanation - Step states and recovery mechanism - Built-in molecules (engineer-in-box, quick-fix, research) - Molecule vs template distinction - Create vision.md capturing the broader strategic vision: - Git as blockchain foundation - Work as universal protocol - Entity chains (work history = CV) - Skill vectors and capability matching - Federation and world chain concept - The OS metaphor for work - Phase roadmap from v1 to platform of platforms 🤖 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
224
docs/vision.md
Normal file
224
docs/vision.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Gas Town Vision
|
||||
|
||||
> Work is fractal. Every piece of work can contain other work, recursively.
|
||||
> Work history is proof of capability. Your CV is your chain.
|
||||
|
||||
## The Big Picture
|
||||
|
||||
Gas Town is more than an AI coding agent orchestrator. It's a **work execution engine** built on a universal ledger of work - where every task, every completion, every validation is recorded with cryptographic integrity.
|
||||
|
||||
The system is designed to evolve from "coding agent coordinator" to "universal work allocation platform" without changing its fundamental architecture.
|
||||
|
||||
## Core Insights
|
||||
|
||||
### 1. Git is Already a Blockchain
|
||||
|
||||
Git provides:
|
||||
- **Merkle tree** - Cryptographic hashes linking history
|
||||
- **Distributed consensus** - Push/pull with conflict resolution
|
||||
- **Immutability** - History cannot be rewritten (without force)
|
||||
- **Auditability** - Every change attributed to an author
|
||||
|
||||
We don't need to build a new blockchain. Git, combined with Beads, gives us the ledger infrastructure for free.
|
||||
|
||||
### 2. Work is a Universal Protocol
|
||||
|
||||
Every piece of structured work can be expressed as:
|
||||
- **Identity** - Who is doing the work
|
||||
- **Specification** - What needs to be done
|
||||
- **Acceptance criteria** - How we know it's done
|
||||
- **Validation** - Who approved the completion
|
||||
- **Provenance** - What work led to this work
|
||||
|
||||
This applies equally to:
|
||||
- Code commits and PRs
|
||||
- Design documents
|
||||
- Bug fixes
|
||||
- Research tasks
|
||||
- Any structured human or AI work
|
||||
|
||||
### 3. Your Work History IS Your CV
|
||||
|
||||
Instead of curated resumes:
|
||||
- Every completed task is recorded
|
||||
- Quality signals are captured (acceptance rate, revision count, review feedback)
|
||||
- Skills are derived from demonstrated capability, not claimed expertise
|
||||
- Reputation is earned through work, not credentials
|
||||
|
||||
This is "proof-of-stake" for work:
|
||||
- Stake = accumulated reputation
|
||||
- Claim work → stake your reputation
|
||||
- Complete well → reputation grows
|
||||
- Fail → reputation diminished (but recoverable)
|
||||
|
||||
### 4. Molecules Crystallize Workflows
|
||||
|
||||
Molecules are reusable workflow patterns that encode:
|
||||
- What steps a workflow contains
|
||||
- How steps depend on each other
|
||||
- What quality gates must pass
|
||||
- How work can be parallelized
|
||||
|
||||
Key properties:
|
||||
- **Deterministic structure** - Same molecule, same step graph
|
||||
- **Nondeterministic execution** - Any worker can execute any ready step
|
||||
- **Idempotent progress** - Completed steps stay completed
|
||||
|
||||
This enables the "engineer in a box" - AI agents that follow rigorous workflows with built-in quality gates, not just "do the task."
|
||||
|
||||
### 5. Federation Creates the World Chain
|
||||
|
||||
The recursive structure:
|
||||
```
|
||||
World
|
||||
├── Platform (GitHub, enterprise systems, ...)
|
||||
│ ├── Organization
|
||||
│ │ ├── Project
|
||||
│ │ │ ├── Epic
|
||||
│ │ │ │ └── Task chains
|
||||
│ │ │ │ └── Entity contribution records
|
||||
```
|
||||
|
||||
Each level has its own chain. Work rolls up. Skills aggregate. The world gets a unified view of capability.
|
||||
|
||||
## The Technical Foundation
|
||||
|
||||
### Beads as Ledger
|
||||
|
||||
| Concept | Beads Implementation |
|
||||
|---------|---------------------|
|
||||
| Transaction | Issue/task/work item |
|
||||
| Address | Entity identifier |
|
||||
| Smart Contract | Work specification + acceptance criteria |
|
||||
| Validation | Merge/review/approval |
|
||||
| Stake | Accumulated reputation chain |
|
||||
| Gas | Effort estimation |
|
||||
|
||||
### The OS Metaphor
|
||||
|
||||
Gas Town is an operating system for 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 |
|
||||
|
||||
### Entity Chains
|
||||
|
||||
Every entity (human or agent) accumulates a work chain:
|
||||
- Work they created
|
||||
- Work they claimed
|
||||
- Work they completed
|
||||
- Work they validated
|
||||
- Quality signals at each step
|
||||
|
||||
Format: `entity://<platform>/<org>/<id>`
|
||||
|
||||
Examples:
|
||||
- `entity://gastown/steveyegge/polecat-nux`
|
||||
- `entity://github/acme-corp/jane-doe`
|
||||
|
||||
The chain IS the CV. Skills are derived from demonstrated work, not claimed.
|
||||
|
||||
### Skill Vectors
|
||||
|
||||
Work items carry skill embeddings:
|
||||
- What capabilities does this work demonstrate?
|
||||
- What prior knowledge does it require?
|
||||
- How complex is it?
|
||||
|
||||
Matching displaced workers to unmet demand becomes a vector similarity problem:
|
||||
- Worker's demonstrated skills (from their chain)
|
||||
- Job requirements (from work specification)
|
||||
- Match = high similarity + acceptable reputation
|
||||
|
||||
## Public Framing
|
||||
|
||||
These capabilities can be explained without revealing the full vision:
|
||||
|
||||
| Capability | Public Explanation |
|
||||
|------------|-------------------|
|
||||
| Entity tracking | "Agent accountability and work attribution" |
|
||||
| Recursive structure | "Enterprise-scale hierarchical tracking" |
|
||||
| Skill vectors | "Capability-based task routing" |
|
||||
| Federation | "Multi-repo / org-wide visibility" |
|
||||
| Validation | "Review workflows and quality gates" |
|
||||
| Mail/threading | "Agent coordination for distributed teams" |
|
||||
|
||||
All true - just not the full story.
|
||||
|
||||
## The Execution Model
|
||||
|
||||
### Refineries as Validators
|
||||
|
||||
Refineries don't just merge code - they're validator nodes:
|
||||
- Verify work meets acceptance criteria
|
||||
- Record validation in the ledger
|
||||
- Gate entry to the canonical chain (main branch)
|
||||
|
||||
### Polecats as Workers
|
||||
|
||||
Polecats aren't just coding agents - they're work executors with chains:
|
||||
- Each polecat has an identity
|
||||
- Work history accumulates
|
||||
- Success rate is tracked
|
||||
- Demonstrated skills emerge
|
||||
|
||||
### Molecules as Contracts
|
||||
|
||||
Molecules aren't just workflows - they're smart contracts for work:
|
||||
- Specify exactly what must happen
|
||||
- Encode acceptance criteria per step
|
||||
- Enable deterministic verification
|
||||
- Support nondeterministic execution
|
||||
|
||||
## Where This Goes
|
||||
|
||||
### Phase 1: Gas Town v1 (Now)
|
||||
- Coding agent orchestrator
|
||||
- Beads-backed work tracking
|
||||
- Molecule-based workflows
|
||||
- Local federation ready
|
||||
|
||||
### Phase 2: Federation
|
||||
- Cross-machine outposts
|
||||
- Multi-rig coordination
|
||||
- Git-based sync everywhere
|
||||
|
||||
### Phase 3: Entity Chains
|
||||
- Persistent agent identities
|
||||
- Work history accumulation
|
||||
- Skill derivation from work
|
||||
|
||||
### Phase 4: Platform of Platforms
|
||||
- Adapters for external work sources
|
||||
- Cross-platform skill matching
|
||||
- The world chain emerges
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Git as blockchain** - Don't build new consensus; use git
|
||||
2. **Federation not global consensus** - Each platform validates its own work
|
||||
3. **Skill embeddings as native** - Work items carry capability vectors
|
||||
4. **Human-readable** - Beads is Markdown; auditable, trustworthy
|
||||
5. **Incremental evolution** - Current architecture grows into the full vision
|
||||
|
||||
## The Redemption Arc
|
||||
|
||||
The system doesn't judge - it tracks demonstrated capability and matches it to demand.
|
||||
|
||||
- Someone with a troubled past can rebuild their chain
|
||||
- Skills proven through work matter more than credentials
|
||||
- Every completion is a step toward redemption
|
||||
- The ledger is honest but not cruel
|
||||
|
||||
This is capability matching at scale. The work speaks for itself.
|
||||
|
||||
---
|
||||
|
||||
*"Work is fractal. Money is crystallized labor. The world needs a ledger."*
|
||||
Reference in New Issue
Block a user