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

docs: comprehensive molecule architecture and vision

Browse Source 
- 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
2025-12-19 15:55:58 -08:00
parent 269dd9c0d3
commit 4b72a83803
2 changed files with 427 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
docs/architecture.md
View File

@@ -187,36 +187,7 @@ Beads is the data plane for ALL Gas Town operations. Everything flows through be
| **Pinned beads** | Ongoing concerns that don't close | Planned (post-v1) |
| **Resource beads** | Leases, locks, quotas | Planned (post-v1) |
**Molecules** are the key v1 addition - crystallized workflow patterns that can be attached to work items. When attached, a molecule instantiates as child beads forming a DAG:
```yaml
# Example: engineer-in-box molecule
molecule: engineer-in-box
steps:
- id: design
prompt: "Write design doc"
- id: implement
depends: [design]
prompt: "Implement the design"
- id: review
depends: [implement]
prompt: "Self-review for issues"
- id: test
depends: [review]
prompt: "Run tests"
- id: submit
depends: [test]
prompt: "Create MR"
```
Usage:
```bash
gt spawn --issue gt-xyz --molecule engineer-in-box
# Creates: gt-xyz.design, gt-xyz.implement, gt-xyz.review, gt-xyz.test, gt-xyz.submit
# Polecat grinds through via `bd ready`
```
This enables "Engineer in a Box" - polecats that execute structured workflows with quality gates, not just "do this task."
**Molecules** are crystallized workflow patterns that can be attached to work items. See the dedicated **Molecules** section below for full details on composition, nondeterministic idempotence, and built-in workflows.
**The OS Metaphor**: Gas Town is an operating system for work:
@@ -230,6 +201,208 @@ This enables "Engineer in a Box" - polecats that execute structured workflows wi
| Process templates | Molecules |
| IPC | Mail beads |
## Molecules: Composable Workflow Templates
Molecules are **crystallized, composable, nondeterministic-idempotent workflow templates**. They encode structured workflows that any worker can execute, with full auditability and the ability for any worker to pick up where another left off.
### Core Concepts
| Concept | Name | Description |
|---------|------|-------------|
| Template | **Molecule** | Read-only workflow pattern (beads issue with type=molecule) |
| Individual step | **Atom/Step** | Smallest unit of work within a molecule |
| Dependency | **Bond** | Connection between steps (Needs: directive) |
| Composed molecule | **Polymer/Derived** | Molecule built from other molecules |
| Concrete work | **Instance** | Beads created when molecule is instantiated |
### Molecule Format
Molecules use a prose-based format with structured step definitions:
```markdown
## Molecule: engineer-in-box
Full workflow from design to merge.
## Step: design
Think carefully about architecture. Consider:
- Existing patterns in the codebase
- Trade-offs between approaches
- Testability and maintainability
Write a brief design summary before proceeding.
## Step: implement
Write the code. Follow codebase conventions.
Needs: design
## Step: review
Self-review the changes. Look for bugs, style issues, missing error handling.
Needs: implement
## Step: test
Write and run tests. Cover happy path and edge cases.
Needs: implement
## Step: submit
Submit for merge via refinery.
Needs: review, test
```
**Key format elements:**
- `## Step: <name>` - Step header with reference name
- Prose instructions - What the step should accomplish
- `Needs: <step1>, <step2>` - Dependencies (optional)
- `Tier: haiku|sonnet|opus` - Model hint (optional)
### Molecule Composition
Molecules can include other molecules to create derived workflows:
```markdown
## Molecule: gastown-polecat
Full workflow for Gas Town polecats including binary installation.
Includes: mol-engineer-in-box
## Step: install-binary
After merge is submitted, rebuild and install the local gt binary.
Run from the rig directory:
go build -o gt ./cmd/gt
go install ./cmd/gt
Needs: submit
```
**Semantics:**
- `Includes:` brings in all steps from the referenced molecule
- New steps can depend on included steps (e.g., `Needs: submit`)
- Multiple includes are supported for complex polymers
- Dependencies are resolved transitively at parse time
### Nondeterministic Idempotence
This is the key property enabling distributed molecule execution:
1. **Deterministic Structure**: Molecule defines exactly what steps exist and their dependencies
2. **Nondeterministic Execution**: Any worker can execute any ready step
3. **Idempotent Progress**: Completed steps stay completed; re-entry is safe
**How it works:**
```
Worker A picks up "design" (pending → in_progress)
Worker A completes "design" (in_progress → completed)
Worker A dies before "implement"
Worker B queries bd ready, sees "implement" is now ready
Worker B picks up "implement" (any worker can continue)
```
This is like a **distributed work queue** backed by beads:
- Beads is the queue (steps are issues with status)
- Git is the persistence layer
- No separate message broker needed
- Full auditability of who did what, when
### Step States
```
pending → in_progress → completed
↘ failed
```
| State | Meaning |
|-------|---------|
| `pending` (open) | Step not yet started, waiting for dependencies |
| `in_progress` | Worker has claimed this step |
| `completed` (closed) | Step finished successfully |
| `failed` | Step failed (needs intervention) |
**Recovery mechanism:**
- If worker dies mid-step, step stays `in_progress`
- After timeout (default 30 min), step can be reclaimed
- `bd release <step-id>` manually releases stuck steps
- Another worker can then pick it up
### Instantiation
When a molecule is attached to an issue:
```bash
gt spawn --issue gt-xyz --molecule mol-engineer-in-box
```
1. Molecule is validated (steps, dependencies)
2. Child beads are created for each step:
- `gt-xyz.design`, `gt-xyz.implement`, etc.
3. Inter-step dependencies are wired
4. First ready step(s) become available via `bd ready`
5. Polecat starts on first ready step
**Provenance tracking:**
- Each instance has an `instantiated_from` edge to the source molecule
- Enables querying: "show all instances of mol-engineer-in-box"
### Built-in Molecules
Gas Town ships with three built-in molecules:
**mol-engineer-in-box** (5 steps):
```
design → implement → review → test → submit
```
Full quality workflow with design phase and self-review.
**mol-quick-fix** (3 steps):
```
implement → test → submit
```
Fast path for small, well-understood changes.
**mol-research** (2 steps):
```
investigate → document
```
Exploration workflow for understanding problems.
Seed built-in molecules with:
```bash
gt molecule seed
```
### Usage
```bash
# List available molecules
gt molecule list
# Show molecule details
gt molecule show mol-engineer-in-box
# Instantiate on an issue
gt molecule instantiate mol-engineer-in-box --parent=gt-xyz
# Spawn polecat with molecule
gt spawn --issue gt-xyz --molecule mol-engineer-in-box
```
### Why Molecules?
1. **Quality gates**: Every polecat follows the same review/test workflow
2. **Error isolation**: Each step is a checkpoint; failures don't lose prior work
3. **Parallelism**: Independent steps can run in parallel across workers
4. **Auditability**: Full history of who did what step, when
5. **Composability**: Build complex workflows from simple building blocks
6. **Resumability**: Any worker can continue where another left off
### Molecule vs Template
Beads has two related concepts:
- **bd template**: User-facing workflow templates with variable substitution
- **gt molecule**: Agent-focused execution templates with step dependencies
Both use similar structures but different semantics:
- Templates focus on parameterization (`{{variable}}` substitution)
- Molecules focus on execution (step states, nondeterministic dispatch)
## Directory Structure
### Harness Level

224
docs/vision.md Normal file
View 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."*