Add molecular chemistry documentation (gt-3x0z.9)
New documents: - docs/molecular-chemistry.md: Comprehensive guide to the chemistry metaphor for work composition. Covers all phases (proto/mol/wisp), transitions (pour/wisp/squash/burn/distill), polymorphic bond operator, and the thermodynamic properties of the work execution engine. - docs/chemistry-design-changes.md: Implementation roadmap for realizing the chemistry UX in Beads and Gas Town. Includes specifications for new commands (bd pour, bd wisp, bd pin, bd hook) and migration notes. 🤖 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
375
docs/chemistry-design-changes.md
Normal file
375
docs/chemistry-design-changes.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# Chemistry Design Changes
|
||||
|
||||
> Implementation roadmap for the molecular chemistry UX described in
|
||||
> `molecular-chemistry.md`
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
The chemistry metaphor requires the following changes to Beads and Gas Town:
|
||||
|
||||
### Beads Changes
|
||||
|
||||
| Change | Priority | Issue |
|
||||
|--------|----------|-------|
|
||||
| Add `bd pour` command (alias for `bd mol spawn --pour`) | P0 | Create |
|
||||
| Add `bd wisp` command (alias for `bd mol spawn`) | P0 | Create |
|
||||
| Add `bd pin` command for agent attachment | P1 | Create |
|
||||
| Add `bd hook` command for hook inspection | P2 | Create |
|
||||
| Rename `--persistent` to `--pour` in `bd mol spawn` | P0 | Update |
|
||||
| Add `--pour` flag to `bd mol bond` | P1 | Update |
|
||||
| Implement digest ID reservation for wisps | P1 | Create |
|
||||
|
||||
### Gas Town Changes
|
||||
|
||||
| Change | Priority | Issue |
|
||||
|--------|----------|-------|
|
||||
| Update daemon: remove permanent attachment for patrol | P0 | gt-3x0z.9 |
|
||||
| Update deacon.md.tmpl: use wisp-based patrol | P0 | gt-3x0z.9 |
|
||||
| Update witness.md.tmpl: use wisp-based patrol | P1 | Create |
|
||||
| Add `gt hook` command (thin wrapper around `bd hook`) | P2 | Create |
|
||||
|
||||
---
|
||||
|
||||
## Detailed Specifications
|
||||
|
||||
### 1. `bd pour` Command
|
||||
|
||||
**Purpose:** Instantiate a proto as a persistent mol (liquid phase).
|
||||
|
||||
**Syntax:**
|
||||
```bash
|
||||
bd pour <proto-id> [flags]
|
||||
|
||||
Flags:
|
||||
--var strings Variable substitution (key=value)
|
||||
--assignee Assign the root issue to this agent
|
||||
--dry-run Preview what would be created
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- Alias/wrapper for `bd mol spawn <proto-id> --pour`
|
||||
- Default behavior: creates mol in permanent `.beads/` storage
|
||||
- Returns the head bead ID of the created mol
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bd pour mol-feature --var name=auth
|
||||
# Output: Created mol bd-abc123 from mol-feature
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. `bd wisp` Command
|
||||
|
||||
**Purpose:** Instantiate a proto as an ephemeral wisp (vapor phase).
|
||||
|
||||
**Syntax:**
|
||||
```bash
|
||||
bd wisp <proto-id> [flags]
|
||||
|
||||
Flags:
|
||||
--var strings Variable substitution (key=value)
|
||||
--dry-run Preview what would be created
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- Alias/wrapper for `bd mol spawn <proto-id>` (wisp is default)
|
||||
- Creates wisp in `.beads-wisp/` storage
|
||||
- Reserves digest ID in permanent storage (placeholder)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bd wisp mol-patrol
|
||||
# Output: Created wisp bd-xyz789 from mol-patrol
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. `bd pin` Command
|
||||
|
||||
**Purpose:** Attach a mol to an agent's hook (work assignment).
|
||||
|
||||
**Syntax:**
|
||||
```bash
|
||||
bd pin <mol-id> [flags]
|
||||
|
||||
Flags:
|
||||
--for string Agent to pin work for (default: current agent)
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
1. Look up the mol by ID
|
||||
2. Set `pinned: true` on the mol's head bead
|
||||
3. Set `assignee` to the target agent
|
||||
4. Update `status` to `in_progress` if not already
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Pin to myself
|
||||
bd pin bd-abc123
|
||||
|
||||
# Pin to specific agent (Witness assigning work)
|
||||
bd pin bd-abc123 --for polecat-ace
|
||||
```
|
||||
|
||||
**Unpin:**
|
||||
```bash
|
||||
bd unpin [mol-id]
|
||||
# Clears pinned flag, optionally releases assignee
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. `bd hook` Command
|
||||
|
||||
**Purpose:** Inspect what's on an agent's hook.
|
||||
|
||||
**Syntax:**
|
||||
```bash
|
||||
bd hook [flags]
|
||||
|
||||
Flags:
|
||||
--agent string Agent to inspect (default: current agent)
|
||||
--json Output in JSON format
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- Query beads for issues where `pinned: true` AND `assignee: <agent>`
|
||||
- Display the mol(s) attached to the hook
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bd hook
|
||||
# Output:
|
||||
# Hook: polecat-ace
|
||||
# Pinned: bd-abc123 (mol-feature) - in_progress
|
||||
# Step: implement (2 of 5)
|
||||
|
||||
bd hook --agent deacon
|
||||
# Output:
|
||||
# Hook: deacon
|
||||
# (empty - patrol uses wisps, no persistent attachment)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Rename `--persistent` to `--pour`
|
||||
|
||||
**Current:**
|
||||
```bash
|
||||
bd mol spawn mol-feature --persistent
|
||||
```
|
||||
|
||||
**New:**
|
||||
```bash
|
||||
bd mol spawn mol-feature --pour
|
||||
# or simply:
|
||||
bd pour mol-feature
|
||||
```
|
||||
|
||||
**Migration:**
|
||||
- Keep `--persistent` as deprecated alias
|
||||
- Log warning when `--persistent` is used
|
||||
- Remove in next major version
|
||||
|
||||
---
|
||||
|
||||
### 6. Add `--pour` flag to `bd mol bond`
|
||||
|
||||
**Purpose:** Override phase when spawning protos during bond.
|
||||
|
||||
**Current behavior:**
|
||||
- Phase follows target (mol → liquid, wisp → vapor)
|
||||
- `--wisp` forces vapor
|
||||
|
||||
**New:**
|
||||
- Add `--pour` to force liquid even when target is vapor
|
||||
|
||||
```bash
|
||||
# Found important bug during patrol, make it a real issue
|
||||
bd mol bond mol-critical-bug wisp-patrol-123 --pour
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. Digest ID Reservation
|
||||
|
||||
**Problem:** When a wisp is created and later squashed, the digest should
|
||||
have the same ID so cross-phase references remain valid.
|
||||
|
||||
**Solution:** Reserve the ID on wisp creation.
|
||||
|
||||
**Implementation:**
|
||||
|
||||
1. **On wisp creation (`bd wisp`):**
|
||||
- Generate the head bead ID
|
||||
- Write a placeholder to permanent beads:
|
||||
```json
|
||||
{
|
||||
"id": "bd-xyz789",
|
||||
"title": "[Wisp Placeholder]",
|
||||
"status": "open",
|
||||
"labels": ["wisp-placeholder"],
|
||||
"description": "Reserved for wisp digest"
|
||||
}
|
||||
```
|
||||
- Create actual wisp in `.beads-wisp/` with same ID
|
||||
|
||||
2. **On squash (`bd mol squash`):**
|
||||
- Replace placeholder with actual digest content
|
||||
- Delete wisp from `.beads-wisp/`
|
||||
|
||||
3. **On burn (`bd mol burn`):**
|
||||
- Delete placeholder from permanent beads
|
||||
- Delete wisp from `.beads-wisp/`
|
||||
|
||||
**Edge cases:**
|
||||
- Crash before squash: Placeholder remains (orphan cleanup needed)
|
||||
- Multiple wisps: Each has unique ID, no collision
|
||||
|
||||
---
|
||||
|
||||
### 8. Daemon Patrol Changes (Gas Town)
|
||||
|
||||
**Current behavior (`checkDeaconAttachment`):**
|
||||
- Checks if Deacon has pinned mol
|
||||
- If not, spawns `mol-deacon-patrol` and attaches permanently
|
||||
- This is wrong for wisp-based patrol
|
||||
|
||||
**New behavior:**
|
||||
- Remove `checkDeaconAttachment` entirely
|
||||
- Deacon manages its own wisp lifecycle
|
||||
- Daemon just ensures Deacon session is running and pokes it
|
||||
|
||||
**Code change in `daemon.go`:**
|
||||
```go
|
||||
// Remove this function entirely:
|
||||
// func (d *Daemon) checkDeaconAttachment() error { ... }
|
||||
|
||||
// Or replace with a simpler check:
|
||||
func (d *Daemon) ensureDeaconReady() error {
|
||||
// Just verify session is running, don't attach anything
|
||||
// Deacon self-spawns wisps for patrol
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. Deacon Template Update
|
||||
|
||||
**Current (`deacon.md.tmpl`):**
|
||||
```markdown
|
||||
If no molecule (naked), **start a new patrol**:
|
||||
```bash
|
||||
bd mol run mol-deacon-patrol
|
||||
```
|
||||
```
|
||||
|
||||
**New:**
|
||||
```markdown
|
||||
## Patrol Cycle (Wisp-Based)
|
||||
|
||||
Each patrol cycle uses ephemeral wisps:
|
||||
|
||||
```bash
|
||||
# 1. Spawn wisp for this cycle
|
||||
bd wisp mol-deacon-patrol
|
||||
|
||||
# 2. Execute steps
|
||||
bd close <step-1>
|
||||
bd close <step-2>
|
||||
# ...
|
||||
|
||||
# 3. Squash with summary
|
||||
bd mol squash <wisp-id> --summary="Patrol complete: <findings>"
|
||||
|
||||
# 4. Loop
|
||||
# Repeat from step 1
|
||||
```
|
||||
|
||||
**Why wisps?**
|
||||
- Patrol cycles are operational, not auditable work
|
||||
- Each cycle is independent
|
||||
- Only the digest matters (and only if notable)
|
||||
- Keeps permanent beads clean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Order
|
||||
|
||||
### Phase 1: Core Commands (P0)
|
||||
|
||||
1. [ ] Add `bd pour` command
|
||||
2. [ ] Add `bd wisp` command
|
||||
3. [ ] Rename `--persistent` to `--pour` (with deprecated alias)
|
||||
4. [ ] Update daemon to remove `checkDeaconAttachment`
|
||||
5. [ ] Update `deacon.md.tmpl` for wisp-based patrol
|
||||
|
||||
### Phase 2: Agent Attachment (P1)
|
||||
|
||||
1. [ ] Add `bd pin` command
|
||||
2. [ ] Add `bd unpin` command
|
||||
3. [ ] Add `--pour` flag to `bd mol bond`
|
||||
4. [ ] Implement digest ID reservation for wisps
|
||||
5. [ ] Update `witness.md.tmpl` for wisp-based patrol
|
||||
|
||||
### Phase 3: Inspection (P2)
|
||||
|
||||
1. [ ] Add `bd hook` command
|
||||
2. [ ] Add `gt hook` command (thin wrapper)
|
||||
|
||||
---
|
||||
|
||||
## Testing Plan
|
||||
|
||||
### Manual Tests
|
||||
|
||||
```bash
|
||||
# Test pour
|
||||
bd pour mol-quick-fix
|
||||
bd show <id> # Verify in permanent beads
|
||||
|
||||
# Test wisp
|
||||
bd wisp mol-patrol
|
||||
ls .beads-wisp/ # Verify wisp created
|
||||
bd show <id> # Should work from permanent (placeholder)
|
||||
|
||||
# Test squash
|
||||
bd mol squash <wisp-id> --summary="Test"
|
||||
ls .beads-wisp/ # Wisp should be gone
|
||||
bd show <id> # Digest should exist
|
||||
|
||||
# Test pin
|
||||
bd pour mol-feature
|
||||
bd pin <id>
|
||||
bd hook # Should show pinned mol
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Deacon patrol cycle with wisps
|
||||
- Cross-phase bonding (mol + wisp)
|
||||
- Digest ID stability after squash
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### Existing Code
|
||||
|
||||
- `bd mol spawn` defaults to wisp (vapor) now
|
||||
- Code using `bd mol spawn` for permanent mols needs `--pour`
|
||||
- `bd mol run` continues to work (creates mol, not wisp)
|
||||
|
||||
### Deprecation Path
|
||||
|
||||
| Old | New | Deprecation |
|
||||
|-----|-----|-------------|
|
||||
| `--persistent` | `--pour` | Warn in 0.x, remove in 1.0 |
|
||||
| `bd mol spawn` (for mols) | `bd pour` | Keep both, prefer new |
|
||||
|
||||
---
|
||||
|
||||
*This document tracks the implementation of chemistry UX changes.*
|
||||
646
docs/molecular-chemistry.md
Normal file
646
docs/molecular-chemistry.md
Normal file
@@ -0,0 +1,646 @@
|
||||
# Molecular Chemistry: Work Composition in Gas Town
|
||||
|
||||
> *"Work is fractal. Money is crystallized labor. Blockchain was the mechanism
|
||||
> searching for its purpose."*
|
||||
|
||||
Gas Town is a **work composition and execution engine**. This document describes
|
||||
the chemistry-inspired system for expressing, instantiating, and executing work
|
||||
at any scale - from single tasks to massive polymers that can grind through
|
||||
weekends of autonomous operation.
|
||||
|
||||
## The Steam Engine Metaphor
|
||||
|
||||
Gas Town is an engine. Engines do work and generate steam.
|
||||
|
||||
```
|
||||
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)
|
||||
```
|
||||
|
||||
In our chemistry:
|
||||
- **Proto molecules** are the fuel (templates that define workflows)
|
||||
- **Mols** are liquid work (flowing, dynamic, adapting as steps complete)
|
||||
- **Wisps** are the steam (transient execution traces that rise and dissipate)
|
||||
- **Digests** are the distillate (condensed permanent records of completed work)
|
||||
|
||||
## The Three Phases of Matter
|
||||
|
||||
Work in Gas Town exists in three phases, following the states of matter:
|
||||
|
||||
| Phase | Name | State | Storage | Behavior |
|
||||
|-------|------|-------|---------|----------|
|
||||
| **Solid** | Proto | Frozen template | `.beads/` (template label) | Crystallized, immutable, reusable |
|
||||
| **Liquid** | Mol | Flowing instance | `.beads/` | Dynamic, adapting, persistent |
|
||||
| **Vapor** | Wisp | Ephemeral trace | `.beads-wisp/` | Transient, dissipates, operational |
|
||||
|
||||
### Proto (Solid Phase)
|
||||
|
||||
Protos are **frozen workflow patterns** - crystallized templates that encode
|
||||
reusable work structures. They're the "molds" from which instances are cast.
|
||||
|
||||
```markdown
|
||||
## Molecule: engineer-in-box
|
||||
Full workflow from design to merge.
|
||||
|
||||
## Step: design
|
||||
Think carefully about architecture.
|
||||
Needs: (none)
|
||||
|
||||
## Step: implement
|
||||
Write the code.
|
||||
Needs: design
|
||||
|
||||
## Step: test
|
||||
Write and run tests.
|
||||
Needs: implement
|
||||
|
||||
## Step: submit
|
||||
Submit for merge.
|
||||
Needs: test
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Immutable once defined (frozen)
|
||||
- Named (e.g., `mol-engineer-in-box`, `mol-code-review`)
|
||||
- Stored in permanent beads with `template` label
|
||||
- Can be composed into larger protos (polymers)
|
||||
|
||||
### Mol (Liquid Phase)
|
||||
|
||||
Mols are **flowing work instances** - live executions that adapt as steps
|
||||
complete, status changes, and work evolves.
|
||||
|
||||
**Properties:**
|
||||
- Identified by head bead ID (e.g., `bd-abc123`)
|
||||
- Dynamic - steps transition through states
|
||||
- Persistent - survives sessions, crashes, context compaction
|
||||
- Auditable - full history in beads
|
||||
|
||||
### Wisp (Vapor Phase)
|
||||
|
||||
Wisps are **ephemeral execution traces** - the steam that rises during work
|
||||
and dissipates when done.
|
||||
|
||||
**Properties:**
|
||||
- Stored in `.beads-wisp/` (gitignored, never synced)
|
||||
- Single-cycle lifetime
|
||||
- Either evaporates (burn) or condenses to digest (squash)
|
||||
- Used for patrol cycles, operational loops, routine work
|
||||
|
||||
## Phase Transition Operators
|
||||
|
||||
Work transitions between phases through specific operators:
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ PROTO │
|
||||
│ (solid) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
pour wisp distill
|
||||
│ │ ↑
|
||||
▼ ▼ │
|
||||
┌───────────────┐ ┌───────────────┐ │
|
||||
│ MOL │ │ WISP │ │
|
||||
│ (liquid) │ │ (vapor) │ │
|
||||
└───────┬───────┘ └───────┬───────┘ │
|
||||
│ │ │
|
||||
squash squash │
|
||||
│ │ │
|
||||
▼ ▼ │
|
||||
┌───────────────┐ ┌───────────────┐ │
|
||||
│ DIGEST │ │ (evaporates) │ │
|
||||
│ (condensed) │ │ or burn │ │
|
||||
└───────────────┘ └───────────────┘ │
|
||||
│ │
|
||||
└────────────────────────────┘
|
||||
(experience crystallizes)
|
||||
```
|
||||
|
||||
### Pour: Solid → Liquid
|
||||
|
||||
**Pour** instantiates a proto into a persistent mol - like pouring molten metal
|
||||
into a mold to create a solid casting that will flow through the workflow.
|
||||
|
||||
```bash
|
||||
bd pour mol-feature # Create mol from proto
|
||||
bd pour mol-feature --var version=1.0 # With variable substitution
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Feature work that spans sessions
|
||||
- Important work needing audit trail
|
||||
- Anything you might need to reference later
|
||||
|
||||
### Wisp: Solid → Vapor (Sublimation)
|
||||
|
||||
**Wisp** instantiates a proto directly into vapor - sublimation that skips
|
||||
the liquid phase for ephemeral, operational work.
|
||||
|
||||
```bash
|
||||
bd wisp mol-patrol # Create wisp from proto
|
||||
bd wisp mol-health-check # Ephemeral operational task
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Patrol cycles (deacon, witness)
|
||||
- Health checks and monitoring
|
||||
- One-shot orchestration runs
|
||||
- Routine operations with no audit value
|
||||
|
||||
### Squash: Liquid/Vapor → Condensed
|
||||
|
||||
**Squash** condenses work into a permanent digest - the outcome crystallizes
|
||||
while the execution trace compresses or evaporates.
|
||||
|
||||
```bash
|
||||
bd mol squash bd-abc123 # Squash mol to digest
|
||||
bd mol squash bd-abc123 --summary="Completed auth" # With summary
|
||||
```
|
||||
|
||||
**For mols:** Creates digest in permanent beads, preserves full outcome
|
||||
**For wisps:** Creates digest, deletes wisp (vapor condenses to residue)
|
||||
|
||||
### Burn: Vapor → Nothing
|
||||
|
||||
**Burn** discards a wisp without creating a digest - the steam simply
|
||||
evaporates with no residue.
|
||||
|
||||
```bash
|
||||
bd mol burn wisp-123 # Discard without digest
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Routine patrol cycles with nothing notable
|
||||
- Failed attempts that don't need recording
|
||||
- Test runs
|
||||
|
||||
### Distill: Liquid → Solid (Crystallization)
|
||||
|
||||
**Distill** extracts a reusable proto from an existing mol or epic - the
|
||||
reverse of pour. Experience crystallizes into a template.
|
||||
|
||||
```bash
|
||||
bd mol distill bd-abc123 --as "Release Workflow"
|
||||
bd mol distill bd-abc123 --var feature=auth --var version=1.0
|
||||
```
|
||||
|
||||
**Process:**
|
||||
1. Analyze the existing work structure
|
||||
2. Extract the pattern (steps, dependencies)
|
||||
3. Replace concrete values with `{{variable}}` placeholders
|
||||
4. Crystallize as a new proto
|
||||
|
||||
**Use cases:**
|
||||
- Team develops a good workflow organically, wants to reuse it
|
||||
- Capture tribal knowledge as executable templates
|
||||
- Create starting points for similar future work
|
||||
|
||||
## The Polymorphic Bond Operator
|
||||
|
||||
**Bond** is Gas Town's polymorphic combiner - it handles different operand
|
||||
types with different phase behaviors:
|
||||
|
||||
### Bond: Proto + Proto → Compound Proto
|
||||
|
||||
Two solid templates fuse into a larger solid template.
|
||||
|
||||
```bash
|
||||
bd mol bond mol-review mol-deploy --as "Review and Deploy"
|
||||
```
|
||||
|
||||
Creates a compound proto that includes both workflows. The result is a
|
||||
reusable template (solid phase).
|
||||
|
||||
### Bond: Proto + Mol → Spawn + Attach
|
||||
|
||||
A solid template melts into an existing liquid workflow.
|
||||
|
||||
```bash
|
||||
bd mol bond mol-hotfix bd-feature-123
|
||||
```
|
||||
|
||||
The proto is instantiated (as liquid by default) and attached to the
|
||||
existing mol. The new issues become part of the flowing work.
|
||||
|
||||
### Bond: Proto + Wisp → Spawn + Attach (Vapor)
|
||||
|
||||
A solid template sublimates into an existing vapor workflow.
|
||||
|
||||
```bash
|
||||
bd mol bond mol-extra-check wisp-patrol-456
|
||||
```
|
||||
|
||||
The proto spawns as vapor (following the wisp's phase) and attaches.
|
||||
|
||||
### Bond: Mol + Mol → Compound Mol
|
||||
|
||||
Two liquid workflows merge into a larger flowing structure.
|
||||
|
||||
```bash
|
||||
bd mol bond bd-feature-123 bd-related-456
|
||||
```
|
||||
|
||||
Links them via dependency edges. Both continue flowing.
|
||||
|
||||
### Bond: Wisp + Wisp → Compound Wisp
|
||||
|
||||
Two vapor traces merge into a larger ephemeral cloud.
|
||||
|
||||
```bash
|
||||
bd mol bond wisp-123 wisp-456
|
||||
```
|
||||
|
||||
### Phase Override Flags
|
||||
|
||||
Bond's spawning behavior can be overridden:
|
||||
|
||||
```bash
|
||||
# Force liquid when attaching to wisp (found something important!)
|
||||
bd mol bond mol-critical-bug wisp-patrol --pour
|
||||
|
||||
# Force vapor when attaching to mol (ephemeral diagnostic)
|
||||
bd mol bond mol-temp-check bd-feature --wisp
|
||||
```
|
||||
|
||||
| Flag | Effect | Use Case |
|
||||
|------|--------|----------|
|
||||
| `--pour` | Force spawn as liquid | "This matters, persist it" |
|
||||
| `--wisp` | Force spawn as vapor | "This is ephemeral, let it evaporate" |
|
||||
|
||||
### Cross-Phase Bonding
|
||||
|
||||
What happens when you bond liquid and vapor directly?
|
||||
|
||||
```bash
|
||||
bd mol bond bd-feature-123 wisp-456 # Mol + Wisp
|
||||
```
|
||||
|
||||
**Answer: Reference-only linking.** They connect via dependency edges but
|
||||
stay in their respective stores. No phase change occurs - you're linking
|
||||
across the phase boundary without forcing conversion.
|
||||
|
||||
This enables patterns like:
|
||||
- Patrol wisp discovers issue → creates liquid mol for the fix
|
||||
- Feature mol needs diagnostic → spawns vapor wisp for the check
|
||||
- The reference survives even when the wisp evaporates (ID stable)
|
||||
|
||||
## Agent Attachment: Hooks and Pins
|
||||
|
||||
Agents need work attached to them. In Gas Town, this uses **hooks** and **pins**.
|
||||
|
||||
### The Hook
|
||||
|
||||
Each agent has a **hook** - an anchor point where work hangs. It's the
|
||||
agent's "pinned bead" - the top of their inbox, the work they're focused on.
|
||||
|
||||
```bash
|
||||
bd hook # Show what's on my hook
|
||||
bd hook --agent deacon # Show deacon's hook
|
||||
```
|
||||
|
||||
**Hook states:**
|
||||
- **Empty (naked)**: Agent awaiting work assignment
|
||||
- **Occupied**: Agent has work to execute
|
||||
- **Multiple**: Agent managing several concurrent mols (rare)
|
||||
|
||||
### Pin: Attaching Work to Agents
|
||||
|
||||
**Pin** attaches a mol to an agent's hook - the action of assigning work.
|
||||
|
||||
```bash
|
||||
bd pin bd-feature-123 # Pin to my hook
|
||||
bd pin bd-feature-123 --for witness # Pin to specific agent's hook
|
||||
bd unpin # Detach current work
|
||||
```
|
||||
|
||||
**The Witness → Polecat flow:**
|
||||
|
||||
```bash
|
||||
# Witness assigns work to polecat
|
||||
bd pour mol-feature # Create liquid mol
|
||||
bd pin bd-abc123 --for polecat-ace # Hang on polecat's hook
|
||||
gt nudge polecat-ace # Wake the polecat
|
||||
```
|
||||
|
||||
### Wisps Don't Need Pinning
|
||||
|
||||
Wisps are single-cycle and don't survive session boundaries in the
|
||||
traditional sense. Agents hold them in working memory for one cycle:
|
||||
|
||||
```bash
|
||||
# Deacon self-spawns patrol (no pin needed)
|
||||
bd wisp mol-deacon-patrol # Create vapor
|
||||
# ... execute steps ...
|
||||
bd mol squash <id> --summary="..." # Condense and dissipate
|
||||
# Loop
|
||||
```
|
||||
|
||||
## The Epic-Mol Relationship
|
||||
|
||||
Epics and mols are **isomorphic** but represent different mental models.
|
||||
|
||||
### Epic: The Business View
|
||||
|
||||
An epic is a **simple mol shape** - essentially a TODO list:
|
||||
|
||||
```
|
||||
epic-root
|
||||
├── child.1
|
||||
├── child.2
|
||||
├── child.3
|
||||
└── child.4
|
||||
(flat list, no sibling dependencies, execution order implicit)
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- One level of children via `.N` numbering
|
||||
- No explicit serial/parallel encoding
|
||||
- Human-readable, business-oriented
|
||||
- The natural shape most humans create
|
||||
|
||||
### Mol: The Chemistry View
|
||||
|
||||
A mol is the **general case** - arbitrary graphs with explicit workflow
|
||||
semantics:
|
||||
|
||||
```
|
||||
mol-root
|
||||
├── phase-A (epic)
|
||||
│ ├── task.1 ───blocks──→ task.2 (serial)
|
||||
│ └── task.3 (parallel with task.1)
|
||||
├── phase-B (epic) ←───blocked-by─── phase-A
|
||||
│ └── ...
|
||||
└── standalone (fanout)
|
||||
(arbitrary DAG, explicit dependencies encode serial/parallel)
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Can contain multiple epics as subgraphs
|
||||
- Dependency edges encode execution order
|
||||
- `blocks` = serial (bottleneck)
|
||||
- No dep = parallel (fanout)
|
||||
- `conditional` = if-fail path
|
||||
|
||||
### The Relationship
|
||||
|
||||
**All epics are mols. Not all mols are epics.**
|
||||
|
||||
| Aspect | Epic | Mol |
|
||||
|--------|------|-----|
|
||||
| Shape | Flat (root + children) | Arbitrary DAG |
|
||||
| Dependencies | Implicit in ordering | Explicit edges |
|
||||
| Parallelism | Assumed parallel | Encoded in structure |
|
||||
| Mental model | TODO list | Workflow graph |
|
||||
| Common use | Simple feature work | Complex orchestration |
|
||||
|
||||
When you `distill` an epic, you get a simple proto.
|
||||
When you `distill` a complex mol, you get a complex proto (preserving structure).
|
||||
|
||||
## Thermodynamic Properties
|
||||
|
||||
Gas Town's chemistry has thermodynamic properties - work is energy flowing
|
||||
through the system.
|
||||
|
||||
### Work as Energy
|
||||
|
||||
```
|
||||
Proto (potential energy) → Pour/Wisp → Mol/Wisp (kinetic energy) → Squash → Digest (stored work)
|
||||
```
|
||||
|
||||
- **Protos** store potential energy - the capability to do work
|
||||
- **Mols/Wisps** are kinetic - work actively flowing
|
||||
- **Digests** are stored energy - crystallized outcomes
|
||||
|
||||
### The Audit Trail as Entropy
|
||||
|
||||
Every execution increases entropy - creating more history, more records,
|
||||
more state. Gas Town manages this through:
|
||||
|
||||
- **Wisps**: High entropy, but evaporates (entropy contained)
|
||||
- **Squash**: Compresses entropy into minimal digest
|
||||
- **Distill**: Reduces entropy by extracting reusable pattern
|
||||
|
||||
### The CV Chain
|
||||
|
||||
Every agent has a **chain** of work - their CV:
|
||||
|
||||
```
|
||||
Agent CV = ∑(digests) = crystallized capability proof
|
||||
```
|
||||
|
||||
Work completed → digest created → agent's chain grows → capability demonstrated.
|
||||
|
||||
This is the foundation for capability-based work matching: your work
|
||||
history IS your resume. The ledger speaks.
|
||||
|
||||
## The Complete Lifecycle
|
||||
|
||||
### Feature Work (Liquid Path)
|
||||
|
||||
```bash
|
||||
# 1. Create work from template
|
||||
bd pour mol-feature --var name=auth
|
||||
|
||||
# 2. Pin to agent
|
||||
bd pin bd-abc123 --for polecat-ace
|
||||
|
||||
# 3. Agent executes steps
|
||||
bd update bd-abc123.design --status=in_progress
|
||||
# ... cognition ...
|
||||
bd close bd-abc123.design
|
||||
bd update bd-abc123.implement --status=in_progress
|
||||
# ... and so on
|
||||
|
||||
# 4. Squash when complete
|
||||
bd mol squash bd-abc123 --summary="Implemented auth feature"
|
||||
|
||||
# 5. Digest remains in permanent ledger
|
||||
```
|
||||
|
||||
### Patrol Work (Vapor Path)
|
||||
|
||||
```bash
|
||||
# 1. Self-spawn wisp (no pin needed)
|
||||
bd wisp mol-deacon-patrol
|
||||
|
||||
# 2. Execute cycle steps
|
||||
bd close <step-1>
|
||||
bd close <step-2>
|
||||
# ...
|
||||
|
||||
# 3. Generate summary and squash
|
||||
bd mol squash <wisp-id> --summary="Patrol complete, no issues"
|
||||
|
||||
# 4. Loop
|
||||
bd wisp mol-deacon-patrol
|
||||
# ...
|
||||
```
|
||||
|
||||
### Template Creation (Distillation)
|
||||
|
||||
```bash
|
||||
# 1. Complete some work organically
|
||||
# ... team develops release workflow over several iterations ...
|
||||
|
||||
# 2. Distill the pattern
|
||||
bd mol distill bd-release-v3 --as "Release Workflow"
|
||||
|
||||
# 3. Result: new proto available
|
||||
bd pour mol-release-workflow --var version=2.0
|
||||
```
|
||||
|
||||
## Polymers: Large-Scale Composition
|
||||
|
||||
Protos can compose into arbitrarily large **polymers** - chains of molecules
|
||||
that encode complex multi-phase work.
|
||||
|
||||
```bash
|
||||
# Create polymer from multiple protos
|
||||
bd mol bond mol-design mol-implement --as "Design and Implement"
|
||||
bd mol bond mol-design-implement mol-test --as "Full Dev Cycle"
|
||||
bd mol bond mol-full-dev mol-deploy --as "End to End"
|
||||
```
|
||||
|
||||
**Polymer properties:**
|
||||
- Preserve phase relationships from constituent protos
|
||||
- Can encode hours, days, or weeks of work
|
||||
- Enable "weekend warrior" autonomous operation
|
||||
- Beads tracks progress; agents execute; humans sleep
|
||||
|
||||
### The Cognition Sausage Machine
|
||||
|
||||
A large polymer is a **cognition sausage machine**:
|
||||
|
||||
```
|
||||
Proto Polymer (input)
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ GAS TOWN ENGINE │
|
||||
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
|
||||
│ │Pole │ │Pole │ │Pole │ │Pole │ │
|
||||
│ │cat │ │cat │ │cat │ │cat │ │
|
||||
│ └──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ │
|
||||
│ │ │ │ │ │
|
||||
│ └────────┴────────┴────────┘ │
|
||||
│ ↓ │
|
||||
│ Merge Queue │
|
||||
│ ↓ │
|
||||
│ Refinery │
|
||||
└─────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
Completed Work + Digests (output)
|
||||
```
|
||||
|
||||
Feed in a polymer. Get back completed features, merged PRs, and audit trail.
|
||||
|
||||
## The Proto Library
|
||||
|
||||
Gas Town maintains a **library of curated protos** - the fuel stockpile:
|
||||
|
||||
```
|
||||
~/gt/molecules/
|
||||
├── mol-engineer-in-box/ # Full quality workflow
|
||||
├── mol-quick-fix/ # Fast path for small changes
|
||||
├── mol-code-review/ # Pluggable review dimensions
|
||||
├── mol-release/ # Release workflow
|
||||
├── mol-deacon-patrol/ # Deacon monitoring cycle
|
||||
├── mol-witness-patrol/ # Witness worker monitoring
|
||||
└── mol-polecat-work/ # Standard polecat lifecycle
|
||||
```
|
||||
|
||||
**Library operations:**
|
||||
|
||||
```bash
|
||||
bd mol list # List available protos
|
||||
bd mol show mol-code-review # Show proto details
|
||||
bd pour mol-code-review # Instantiate for use
|
||||
```
|
||||
|
||||
### Curated vs Organic
|
||||
|
||||
- **Curated protos**: Refined templates in the library, battle-tested
|
||||
- **Organic protos**: Distilled from real work, may need refinement
|
||||
- **Path**: Organic → refine → curate → library
|
||||
|
||||
## Digest ID Stability
|
||||
|
||||
When a wisp is created, its head bead ID is **reserved** in permanent storage.
|
||||
This ensures cross-phase references remain valid:
|
||||
|
||||
```
|
||||
1. bd wisp mol-patrol → Creates wisp-123 (ID reserved)
|
||||
2. bd mol bond ... wisp-123 → Reference created
|
||||
3. bd mol squash wisp-123 → Digest takes same ID
|
||||
4. Reference still valid → Points to digest now
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- On wisp creation: Write placeholder/tombstone to permanent beads
|
||||
- On squash: Replace placeholder with actual digest
|
||||
- Cross-phase references never break
|
||||
|
||||
## Summary of Operators
|
||||
|
||||
| Operator | From | To | Effect |
|
||||
|----------|------|------|--------|
|
||||
| `pour` | Proto | Mol | Instantiate as persistent liquid |
|
||||
| `wisp` | Proto | Wisp | Instantiate as ephemeral vapor |
|
||||
| `bond` | Any + Any | Compound | Combine (polymorphic) |
|
||||
| `squash` | Mol/Wisp | Digest | Condense to permanent record |
|
||||
| `burn` | Wisp | Nothing | Discard without record |
|
||||
| `distill` | Mol/Epic | Proto | Extract reusable template |
|
||||
| `pin` | Mol | Agent | Attach work to agent's hook |
|
||||
|
||||
## Design Implications
|
||||
|
||||
### For Beads
|
||||
|
||||
1. **New commands**: `bd pour`, `bd wisp`, `bd pin`
|
||||
2. **Flag changes**: `--persistent` → `--pour` (or phase follows operand)
|
||||
3. **Wisp storage**: `.beads-wisp/` directory, gitignored
|
||||
4. **Digest ID reservation**: Placeholder in permanent store on wisp creation
|
||||
|
||||
### For Gas Town
|
||||
|
||||
1. **Daemon**: Don't attach permanent molecules for patrol roles
|
||||
2. **Deacon template**: Use `bd wisp mol-deacon-patrol` pattern
|
||||
3. **Polecat lifecycle**: Consider wisp-based with digest on completion
|
||||
4. **Hook inspection**: `bd hook` command for debugging
|
||||
|
||||
### For Agents
|
||||
|
||||
1. **Polecats**: Receive pinned mols, execute, squash, request shutdown
|
||||
2. **Patrol roles**: Self-spawn wisps, execute cycle, squash, loop
|
||||
3. **Recovery**: Re-read beads state, continue from last completed step
|
||||
|
||||
---
|
||||
|
||||
## Appendix: The Vocabulary
|
||||
|
||||
| Term | Meaning |
|
||||
|------|---------|
|
||||
| **Proto** | Frozen template molecule (solid phase) |
|
||||
| **Mol** | Flowing work instance (liquid phase) |
|
||||
| **Wisp** | Ephemeral execution trace (vapor phase) |
|
||||
| **Digest** | Condensed permanent record |
|
||||
| **Pour** | Instantiate proto as mol (solid → liquid) |
|
||||
| **Wisp** (verb) | Instantiate proto as wisp (solid → vapor) |
|
||||
| **Bond** | Combine molecules (polymorphic) |
|
||||
| **Squash** | Condense to digest |
|
||||
| **Burn** | Discard wisp without digest |
|
||||
| **Distill** | Extract proto from experience |
|
||||
| **Hook** | Agent's attachment point for work |
|
||||
| **Pin** | Attach mol to agent's hook |
|
||||
| **Polymer** | Large composed proto chain |
|
||||
| **Epic** | Simple mol shape (flat TODO list) |
|
||||
|
||||
---
|
||||
|
||||
*The chemistry is the interface. The ledger is the truth. The work gets done.*
|
||||
Reference in New Issue
Block a user