docs: add molecular chemistry documentation (bd-ul59)

Create docs/MOLECULES.md with comprehensive coverage of:
- Layer cake architecture (formulas → protos → molecules → epics → issues)
- Phase metaphor (solid/proto, liquid/mol, vapor/wisp)
- Phase transitions (pour, wisp create, squash, burn)
- Bonding patterns (proto+proto, proto+mol, mol+mol)
- Agent pitfalls (temporal language, forgetting to squash)
- Orphan vs stale matrix
- Progress tracking (computed, not stored)
- Parallelism model (default parallel, opt-in sequential)

Update CLI_REFERENCE.md with Molecular Chemistry section covering:
- Proto/template commands
- Pour command
- Wisp commands
- Bonding commands
- Squash and burn commands

Update ARCHITECTURE.md with cross-reference to new MOLECULES.md.

🤖 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-24 19:30:59 -08:00
parent fbae7711bc
commit 5e971bd90a
3 changed files with 417 additions and 0 deletions

View File

@@ -10,6 +10,7 @@
- [Dependencies & Labels](#dependencies--labels)
- [Filtering & Search](#filtering--search)
- [Advanced Operations](#advanced-operations)
- [Molecular Chemistry](#molecular-chemistry)
- [Database Management](#database-management)
- [Editor Integration](#editor-integration)
@@ -340,6 +341,116 @@ bd rename-prefix kw- --dry-run # Preview changes
bd rename-prefix kw- --json # Apply rename
```
## Molecular Chemistry
Beads uses a chemistry metaphor for template-based workflows. See [MOLECULES.md](MOLECULES.md) for full documentation.
### Phase Transitions
| Phase | State | Storage | Command |
|-------|-------|---------|---------|
| Solid | Proto | `.beads/` | `bd mol catalog` |
| Liquid | Mol | `.beads/` | `bd pour` |
| Vapor | Wisp | `.beads-wisp/` | `bd wisp create` |
### Proto/Template Commands
```bash
# List available protos (templates)
bd mol catalog --json
# Show proto structure and variables
bd mol show <proto-id> --json
# Extract proto from ad-hoc epic
bd mol distill <epic-id> --json
```
### Pour (Proto to Mol)
```bash
# Instantiate proto as persistent mol (solid → liquid)
bd pour <proto-id> --var key=value --json
# Preview what would be created
bd pour <proto-id> --var key=value --dry-run
# Assign root issue
bd pour <proto-id> --var key=value --assignee alice --json
# Attach additional protos during pour
bd pour <proto-id> --attach <other-proto> --json
```
### Wisp Commands
```bash
# Instantiate proto as ephemeral wisp (solid → vapor)
bd wisp create <proto-id> --var key=value --json
# List all wisps
bd wisp list --json
bd wisp list --all --json # Include closed
# Garbage collect orphaned wisps
bd wisp gc --json
bd wisp gc --age 24h --json # Custom age threshold
bd wisp gc --dry-run # Preview what would be cleaned
```
### Bonding (Combining Work)
```bash
# Polymorphic combine - handles proto+proto, proto+mol, mol+mol
bd mol bond <A> <B> --json
# Bond types
bd mol bond <A> <B> --type sequential --json # B runs after A (default)
bd mol bond <A> <B> --type parallel --json # B runs alongside A
bd mol bond <A> <B> --type conditional --json # B runs only if A fails
# Phase control
bd mol bond <proto> <mol> --pour --json # Force persistent spawn
bd mol bond <proto> <mol> --wisp --json # Force ephemeral spawn
# Dynamic bonding (custom child IDs)
bd mol bond <proto> <mol> --ref arm-{{name}} --var name=ace --json
# Preview bonding
bd mol bond <A> <B> --dry-run
```
### Squash (Wisp to Digest)
```bash
# Compress wisp to permanent digest
bd mol squash <wisp-id> --json
# With agent-provided summary
bd mol squash <wisp-id> --summary "Work completed" --json
# Preview
bd mol squash <wisp-id> --dry-run
# Keep wisp children after squash
bd mol squash <wisp-id> --keep-children --json
```
### Burn (Discard Wisp)
```bash
# Delete wisp without digest (destructive)
bd mol burn <wisp-id> --json
# Preview
bd mol burn <wisp-id> --dry-run
# Skip confirmation
bd mol burn <wisp-id> --force --json
```
**Note:** Most mol commands require `--no-daemon` flag when daemon is running.
## Database Management
### Import/Export
@@ -604,6 +715,7 @@ See also:
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
- [MOLECULES.md](MOLECULES.md) - Molecular chemistry metaphor (protos, pour, bond, squash, burn)
- [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
- [LABELS.md](../LABELS.md) - Label system guide