fdea399d6f
- 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>
138 lines
3.6 KiB
Markdown
138 lines
3.6 KiB
Markdown
# 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
|