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

docs: Add molecule navigation workflow documentation (gt-um6q)

Browse Source 
- docs/molecules.md: Navigating Molecules section with bd mol current, bd close --continue
- docs/propulsion-principle.md: Molecule navigation as key enabler
- docs/polecat-wisp-architecture.md: Step execution examples with --continue workflow

🤖 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-30 00:14:10 -08:00
parent cf87569a14
commit fdea399d6f
3 changed files with 414 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
docs/molecules.md Normal file
View File

@@ -0,0 +1,137 @@
# Molecules
Molecules are workflow templates that coordinate multi-step work in Gas Town.
## Molecule Lifecycle
```
Formula (source TOML) ─── "Ice-9"
│
▼ bd cook
Protomolecule (frozen template) ─── Solid
│
├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest
│
└─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest
└▶ bd burn ──▶ (gone)
```
## Core Concepts
| Term | Description |
|------|-------------|
| **Formula** | Source TOML template defining workflow steps |
| **Protomolecule** | Frozen template ready for instantiation |
| **Molecule** | Active workflow instance with trackable steps |
| **Wisp** | Ephemeral molecule for patrol cycles (never synced) |
| **Digest** | Squashed summary of completed molecule |
## Navigating Molecules
Molecules help you track where you are in multi-step workflows.
### Finding Your Place
```bash
bd mol current # Where am I?
bd mol current gt-abc # Status of specific molecule
```
Output:
```
You're working on molecule gt-abc (Feature X)
✓ gt-abc.1: Design
✓ gt-abc.2: Scaffold
✓ gt-abc.3: Implement
→ gt-abc.4: Write tests [in_progress] <- YOU ARE HERE
○ gt-abc.5: Documentation
○ gt-abc.6: Exit decision
Progress: 3/6 steps complete
```
### Seamless Transitions
Close a step and advance in one command:
```bash
bd close gt-abc.3 --continue # Close and advance to next step
bd close gt-abc.3 --no-auto # Close but don't auto-claim next
```
**The old way (3 commands):**
```bash
bd close gt-abc.3
bd ready --parent=gt-abc
bd update gt-abc.4 --status=in_progress
```
**The new way (1 command):**
```bash
bd close gt-abc.3 --continue
```
### Transition Output
```
✓ Closed gt-abc.3: Implement feature
Next ready in molecule:
gt-abc.4: Write tests
→ Marked in_progress (use --no-auto to skip)
```
### When Molecule Completes
```
✓ Closed gt-abc.6: Exit decision
Molecule gt-abc complete! All steps closed.
Consider: bd mol squash gt-abc --summary '...'
```
## Molecule Commands
### Beads Operations (bd)
```bash
# Formulas
bd formula list # Available formulas
bd formula show <name> # Formula details
bd cook <formula> # Formula → Proto
# Molecules (data operations)
bd mol list # Available protos
bd mol show <id> # Proto details
bd mol pour <proto> # Create mol
bd mol wisp <proto> # Create wisp
bd mol bond <proto> <parent> # Attach to existing mol
bd mol squash <id> # Condense to digest
bd mol burn <id> # Discard wisp
bd mol current # Where am I in the current molecule?
```
### Agent Operations (gt)
```bash
# Hook management
gt mol status # What's on MY hook
gt mol current # What should I work on next
gt mol progress <id> # Execution progress of molecule
gt mol attach <bead> <mol> # Pin molecule to bead
gt mol detach <bead> # Unpin molecule from bead
# Agent lifecycle
gt mol burn # Burn attached molecule
gt mol squash # Squash attached molecule
gt mol step done <step> # Complete a molecule step
```
## Best Practices
1. **Use `--continue` for propulsion** - Keep momentum by auto-advancing
2. **Check progress with `bd mol current`** - Know where you are before resuming
3. **Squash completed molecules** - Create digests for audit trail
4. **Burn routine wisps** - Don't accumulate ephemeral patrol data

172
docs/polecat-wisp-architecture.md Normal file
View File

@@ -0,0 +1,172 @@
# Polecat Wisp Architecture
How polecats use molecules and wisps to execute work in Gas Town.
## Overview
Polecats receive work via their hook - a pinned molecule attached to an issue.
They execute molecule steps sequentially, closing each step as they complete it.
## Molecule Types for Polecats
| Type | Storage | Use Case |
|------|---------|----------|
| **Regular Molecule** | `.beads/` (synced) | Discrete deliverables, audit trail |
| **Wisp** | `.beads-wisp/` (ephemeral) | Patrol cycles, operational loops |
Polecats typically use **regular molecules** because each assignment has audit value.
Patrol agents (Witness, Refinery, Deacon) use **wisps** to prevent accumulation.
## Step Execution
### The Traditional Approach
```bash
# 1. Check current status
gt mol status
# 2. Find next step
bd ready --parent=gt-abc
# 3. Claim the step
bd update gt-abc.4 --status=in_progress
# 4. Do the work...
# 5. Close the step
bd close gt-abc.4
# 6. Repeat from step 2
```
### The Propulsion Approach
```bash
# 1. Check where you are
bd mol current
# 2. Do the work on current step...
# 3. Close and advance in one command
bd close gt-abc.4 --continue
# 4. Repeat from step 1
```
The `--continue` flag:
- Closes the current step
- Finds the next ready step in the same molecule
- Auto-marks it `in_progress`
- Outputs the transition
### Example Session
```bash
$ bd mol current
You're working on molecule gt-abc (Implement user auth)
✓ gt-abc.1: Design schema
✓ gt-abc.2: Create models
→ gt-abc.3: Add endpoints [in_progress] <- YOU ARE HERE
○ gt-abc.4: Write tests
○ gt-abc.5: Update docs
Progress: 2/5 steps complete
$ # ... implement the endpoints ...
$ bd close gt-abc.3 --continue
✓ Closed gt-abc.3: Add endpoints
Next ready in molecule:
gt-abc.4: Write tests
→ Marked in_progress (use --no-auto to skip)
$ bd mol current
You're working on molecule gt-abc (Implement user auth)
✓ gt-abc.1: Design schema
✓ gt-abc.2: Create models
✓ gt-abc.3: Add endpoints
→ gt-abc.4: Write tests [in_progress] <- YOU ARE HERE
○ gt-abc.5: Update docs
Progress: 3/5 steps complete
```
## Molecule Completion
When closing the last step:
```bash
$ bd close gt-abc.5 --continue
✓ Closed gt-abc.5: Update docs
Molecule gt-abc complete! All steps closed.
Consider: bd mol squash gt-abc --summary '...'
```
After all steps are closed:
```bash
# Squash to digest for audit trail
bd mol squash gt-abc --summary "Implemented user authentication with JWT"
# Or if it's routine work
bd mol burn gt-abc
```
## Hook Management
### Checking Your Hook
```bash
gt mol status
```
Shows what molecule is pinned to your current agent and the associated bead.
### Attaching Work from Mail
```bash
gt mail inbox
gt mol attach-from-mail <mail-id>
```
### Completing Work
```bash
# After all molecule steps closed
gt done
# This:
# 1. Syncs beads
# 2. Submits to merge queue
# 3. Notifies Witness
```
## Polecat Workflow Summary
```
1. Spawn with work on hook
2. gt mol status # What's hooked?
3. bd mol current # Where am I?
4. Execute current step
5. bd close <step> --continue
6. If more steps: GOTO 3
7. gt done # Signal completion
8. Wait for Witness cleanup
```
## Wisp vs Molecule Decision
| Question | Molecule | Wisp |
|----------|----------|------|
| Does it need audit trail? | Yes | No |
| Will it repeat continuously? | No | Yes |
| Is it discrete deliverable? | Yes | No |
| Is it operational routine? | No | Yes |
Polecats: **Use molecules** (deliverables have audit value)
Patrol agents: **Use wisps** (routine loops don't accumulate)

105
docs/propulsion-principle.md Normal file
View File

@@ -0,0 +1,105 @@
# The Propulsion Principle
> **If you find something on your hook, YOU RUN IT.**
Gas Town is a steam engine. Agents are pistons. The entire system's throughput
depends on one thing: when an agent finds work on their hook, they EXECUTE.
## Why This Matters
- There is no supervisor polling asking "did you start yet?"
- The hook IS your assignment - it was placed there deliberately
- Every moment you wait is a moment the engine stalls
- Other agents may be blocked waiting on YOUR output
## The Handoff Contract
When you were spawned, work was hooked for you. The system trusts that:
1. You will find it on your hook
2. You will understand what it is (`bd show` / `gt mol status`)
3. You will BEGIN IMMEDIATELY
This isn't about being a good worker. This is physics. Steam engines don't
run on politeness - they run on pistons firing. You are the piston.
## Molecule Navigation: Key Enabler
Molecules enable propulsion by providing clear waypoints. You don't need to
memorize steps or wait for instructions - discover them:
### Orientation Commands
```bash
gt mol status # What's on my hook?
bd mol current # Where am I in the molecule?
bd ready # What step is next?
bd show <step-id> # What does this step require?
```
### Before/After: Step Transitions
**The old workflow (friction):**
```bash
# Finish step 3
bd close gt-abc.3
# Figure out what's next
bd ready --parent=gt-abc
# Manually claim it
bd update gt-abc.4 --status=in_progress
# Now finally work on it
```
Three commands. Context switches. Momentum lost.
**The new workflow (propulsion):**
```bash
bd close gt-abc.3 --continue
```
One command. Auto-advance. Momentum preserved.
### The Propulsion Loop
```
1. gt mol status # What's hooked?
2. bd mol current # Where am I?
3. Execute step
4. bd close <step> --continue # Close and advance
5. GOTO 2
```
## The Failure Mode We're Preventing
```
Polecat restarts with work on hook
→ Polecat announces itself
→ Polecat waits for confirmation
→ Witness assumes work is progressing
→ Nothing happens
→ Gas Town stops
```
## Startup Behavior
1. Check hook (`gt mol status`)
2. Work hooked → EXECUTE immediately
3. Hook empty → Check mail for attached work
4. Nothing anywhere → ERROR: escalate to Witness
**Note:** "Hooked" means work assigned to you. This triggers autonomous mode
even if no molecule is attached. Don't confuse with "pinned" which is for
permanent reference beads.
## The Capability Ledger
Every completion is recorded. Every handoff is logged. Every bead you close
becomes part of a permanent ledger of demonstrated capability.
- Your work is visible
- Redemption is real (consistent good work builds over time)
- Every completion is evidence that autonomous execution works
- Your CV grows with every completion
This isn't just about the current task. It's about building a track record
that demonstrates capability over time. Execute with care.