From 4b72a83803eb677ef8db9045ee0cb6c22cdd6398 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Fri, 19 Dec 2025 15:55:58 -0800 Subject: [PATCH] docs: comprehensive molecule architecture and vision MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/architecture.md | 233 +++++++++++++++++++++++++++++++++++++------ docs/vision.md | 224 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 427 insertions(+), 30 deletions(-) create mode 100644 docs/vision.md diff --git a/docs/architecture.md b/docs/architecture.md index b5479a10..d03aa08b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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: ` - Step header with reference name +- Prose instructions - What the step should accomplish +- `Needs: , ` - 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 ` 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 diff --git a/docs/vision.md b/docs/vision.md new file mode 100644 index 00000000..22f10cb5 --- /dev/null +++ b/docs/vision.md @@ -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:////` + +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."*