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>
2025-12-30 00:14:10 -08:00
parent cf87569a14
commit fdea399d6f
3 changed files with 414 additions and 0 deletions
--- a/docs/molecules.md
+++ b/docs/molecules.md
@@ -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