docs: Add molecule navigation workflow documentation (gt-um6q)
- 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
137
docs/molecules.md
Normal file
137
docs/molecules.md
Normal 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
172
docs/polecat-wisp-architecture.md
Normal 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
105
docs/propulsion-principle.md
Normal 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.
|
||||
Reference in New Issue
Block a user