From 5e971bd90ad27f914d9af63f00e592536f54185c Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Wed, 24 Dec 2025 19:30:59 -0800 Subject: [PATCH] docs: add molecular chemistry documentation (bd-ul59) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/ARCHITECTURE.md | 3 + docs/CLI_REFERENCE.md | 112 ++++++++++++++++ docs/MOLECULES.md | 302 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 417 insertions(+) create mode 100644 docs/MOLECULES.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7a46ebd2..7547b967 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -269,6 +269,8 @@ open ──▢ in_progress ──▢ closed **Molecules** are template work items that define structured workflows. When spawned, they create **wisps** - ephemeral child issues that track execution steps. +> **For full documentation** on the molecular chemistry metaphor (protos, pour, bond, squash, burn), see [MOLECULES.md](MOLECULES.md). + ### Wisp Lifecycle ``` @@ -317,6 +319,7 @@ The `bd mol squash` command uses hard delete intentionally - tombstones would be ## Related Documentation +- [MOLECULES.md](MOLECULES.md) - Molecular chemistry metaphor (protos, pour, bond, squash, burn) - [INTERNALS.md](INTERNALS.md) - FlushManager, Blocked Cache implementation details - [DAEMON.md](DAEMON.md) - Daemon management and configuration - [EXTENDING.md](EXTENDING.md) - Adding custom tables to SQLite diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index ccc916d9..2d37f452 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -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 --json + +# Extract proto from ad-hoc epic +bd mol distill --json +``` + +### Pour (Proto to Mol) + +```bash +# Instantiate proto as persistent mol (solid β†’ liquid) +bd pour --var key=value --json + +# Preview what would be created +bd pour --var key=value --dry-run + +# Assign root issue +bd pour --var key=value --assignee alice --json + +# Attach additional protos during pour +bd pour --attach --json +``` + +### Wisp Commands + +```bash +# Instantiate proto as ephemeral wisp (solid β†’ vapor) +bd wisp create --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 --json + +# Bond types +bd mol bond --type sequential --json # B runs after A (default) +bd mol bond --type parallel --json # B runs alongside A +bd mol bond --type conditional --json # B runs only if A fails + +# Phase control +bd mol bond --pour --json # Force persistent spawn +bd mol bond --wisp --json # Force ephemeral spawn + +# Dynamic bonding (custom child IDs) +bd mol bond --ref arm-{{name}} --var name=ace --json + +# Preview bonding +bd mol bond --dry-run +``` + +### Squash (Wisp to Digest) + +```bash +# Compress wisp to permanent digest +bd mol squash --json + +# With agent-provided summary +bd mol squash --summary "Work completed" --json + +# Preview +bd mol squash --dry-run + +# Keep wisp children after squash +bd mol squash --keep-children --json +``` + +### Burn (Discard Wisp) + +```bash +# Delete wisp without digest (destructive) +bd mol burn --json + +# Preview +bd mol burn --dry-run + +# Skip confirmation +bd mol burn --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 diff --git a/docs/MOLECULES.md b/docs/MOLECULES.md new file mode 100644 index 00000000..3f467cad --- /dev/null +++ b/docs/MOLECULES.md @@ -0,0 +1,302 @@ +# Molecular Chemistry in Beads + +This document explains beads' molecular chemistry metaphor for template-based workflows. + +## The Layer Cake + +Beads has a layered architecture where each layer builds on the one below: + +``` +Formulas (YAML compile-time macros) + ↓ +Protos (template issues, read-only) + ↓ +Molecules (pour, bond, squash, burn) + ↓ +Epics (parent-child, dependencies) ← DATA PLANE + ↓ +Issues (JSONL, git-backed) ← STORAGE +``` + +**Key insight:** Molecules work without protos. You can create ad-hoc molecules (epics with children) directly. Protos are templates FOR molecules, not the other way around. + +## Phase Metaphor + +The chemistry metaphor uses phase transitions to describe where work lives: + +| Phase | State | Storage | Synced | Use Case | +|-------|-------|---------|--------|----------| +| **Solid** | Proto | `.beads/` | Yes | Reusable templates | +| **Liquid** | Mol | `.beads/` | Yes | Persistent work | +| **Vapor** | Wisp | `.beads-wisp/` | No | Ephemeral operations | + +### Phase Transitions + +``` +Proto (solid) ──pour──→ Mol (liquid) # Persistent instantiation +Proto (solid) ──wisp──→ Wisp (vapor) # Ephemeral instantiation +Wisp (vapor) ──squash──→ Digest (solid) # Compress to permanent record +Wisp (vapor) ──burn──→ (nothing) # Discard without trace +``` + +## Core Concepts + +### Protos (Templates) + +A proto is an issue with the `template` label. It defines a reusable pattern of work: + +```bash +# List available protos +bd mol catalog + +# Show proto structure +bd mol show +``` + +Protos can contain: +- Template variables using `{{variable}}` syntax +- Hierarchical child issues (subtasks) +- Dependencies between children + +### Molecules (Instances) + +A molecule is a spawned instance of a proto (or an ad-hoc epic). When you "pour" a proto, you create real issues from the template: + +```bash +# Pour: proto β†’ persistent mol (liquid phase) +bd pour --var key=value + +# The mol lives in .beads/ and is synced with git +``` + +### Wisps (Ephemeral Molecules) + +Wisps are ephemeral molecules for operational workflows that shouldn't accumulate: + +```bash +# Wisp: proto β†’ ephemeral wisp (vapor phase) +bd wisp create --var key=value + +# The wisp lives in .beads-wisp/ and is NOT synced +``` + +Use wisps for: +- Patrol cycles (deacon, witness) +- Health checks and monitoring +- One-shot orchestration runs +- Routine operations with no audit value + +### Bonding (Combining Work) + +The `bond` command polymorphically combines protos and molecules: + +```bash +# proto + proto β†’ compound proto (reusable template) +bd mol bond mol-feature mol-deploy + +# proto + mol β†’ spawn proto, attach to molecule +bd mol bond mol-review bd-abc123 + +# mol + mol β†’ join into compound molecule +bd mol bond bd-abc123 bd-def456 +``` + +Bond types: +- `sequential` (default) - B runs after A completes +- `parallel` - B runs alongside A +- `conditional` - B runs only if A fails + +Phase control for bonding: +```bash +# Force spawn as liquid (persistent), even when attaching to wisp +bd mol bond mol-critical-bug wisp-patrol --pour + +# Force spawn as vapor (ephemeral), even when attaching to mol +bd mol bond mol-temp-check bd-feature --wisp +``` + +### Squashing (Compressing) + +Squash compresses a wisp's execution into a permanent digest: + +```bash +# Squash wisp β†’ permanent digest +bd mol squash + +# With agent-provided summary +bd mol squash --summary "Brief description of what was done" + +# Preview what would be squashed +bd mol squash --dry-run +``` + +### Burning (Discarding) + +Burn deletes a wisp without creating any digest: + +```bash +# Delete wisp with no trace +bd mol burn + +# Preview what would be deleted +bd mol burn --dry-run +``` + +## Lifecycle Patterns + +### Patrol Cycle (Ephemeral) + +``` +1. bd wisp create mol-patrol # Create ephemeral wisp +2. (execute patrol steps) # Work through children +3. bd mol squash # Compress to digest + # or + bd mol burn # Discard without trace +``` + +### Feature Work (Persistent) + +``` +1. bd pour mol-feature --var name=auth # Create persistent mol +2. (implement feature) # Work through children +3. bd close # Complete subtasks +4. bd close # Complete the feature +``` + +### Dynamic Bonding (Christmas Ornament Pattern) + +Attach work dynamically using custom IDs: + +```bash +# Spawn per-worker arms on a patrol +bd mol bond mol-polecat-arm bd-patrol --ref arm-{{name}} --var name=ace +# Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture) +``` + +## Progress Tracking + +Molecule progress is **computed, not stored**: + +- `progress.Completed` = count of closed children +- `progress.Total` = count of all children + +This means: +- No state to get out of sync +- Dynamic fanout works automatically (new children increase Total) +- Closing children increases Completed + +## Parallelism Model + +**Default: Parallel.** Issues without `depends_on` relationships run in parallel. + +**Opt-in Sequential:** Add blocking dependencies to create sequence: + +```bash +# phase-2 depends on phase-1 (phase-1 must complete first) +bd dep add phase-2 phase-1 +``` + +**Cognitive trap:** Temporal language ("Phase 1 comes before Phase 2") inverts dependencies. Think requirements: "Phase 2 **needs** Phase 1." + +## Common Agent Pitfalls + +### 1. Temporal Language Inverting Dependencies + +**Wrong thinking:** "Phase 1 comes before Phase 2" β†’ `bd dep add phase1 phase2` + +**Right thinking:** "Phase 2 needs Phase 1" β†’ `bd dep add phase2 phase1` + +**Solution:** Use requirement language, not temporal language. Verify with `bd blocked`. + +### 2. Confusing Protos with Molecules + +- **Proto** = Template (has `template` label, read-only pattern) +- **Molecule** = Instance (real work, created by pour/wisp) + +You can create molecules without protos (ad-hoc epics). Protos are just reusable patterns. + +### 3. Forgetting to Squash/Burn Wisps + +Wisps accumulate in `.beads-wisp/` if not cleaned up. At session end: + +```bash +bd wisp list # Check for orphaned wisps +bd mol squash --summary "" # Compress to digest +# or +bd mol burn # Discard if not needed +# or +bd wisp gc # Garbage collect old wisps +``` + +### 4. Thinking Phases Imply Sequence + +Phases, steps, or numbered items in a plan do NOT create sequence. Only dependencies do. + +```bash +# These tasks run in PARALLEL (no dependencies) +bd create "Step 1: Do X" ... +bd create "Step 2: Do Y" ... +bd create "Step 3: Do Z" ... + +# Add dependencies to create sequence +bd dep add step2 step1 # step2 needs step1 +bd dep add step3 step2 # step3 needs step2 +``` + +## Orphan vs Stale Matrix + +A molecule can be in one of four states based on two dimensions: + +| | Assigned | Unassigned | +|---|---|---| +| **Blocking** | Active work | Orphaned (needs pickup) | +| **Not blocking** | In progress | Stale (complete but unclosed) | + +- **Orphaned:** Complete-but-unclosed molecules blocking other assigned work +- **Stale:** Complete-but-unclosed molecules not blocking anything + +Graph pressure (blocking other work) determines urgency, not time. + +## Commands Reference + +### Proto/Template Commands + +```bash +bd mol catalog # List available protos +bd mol show # Show proto/molecule structure +bd mol distill # Extract proto from ad-hoc epic +``` + +### Phase Transition Commands + +```bash +bd pour --var k=v # Proto β†’ Mol (liquid) +bd wisp create --var k=v # Proto β†’ Wisp (vapor) +bd mol squash # Wisp β†’ Digest (solid) +bd mol burn # Wisp β†’ nothing +``` + +### Bonding Commands + +```bash +bd mol bond # Polymorphic combine +bd mol bond --type parallel +bd mol bond --pour # Force persistent +bd mol bond --wisp # Force ephemeral +bd mol bond --ref # Dynamic child ID +``` + +### Wisp Management + +```bash +bd wisp list # List all wisps +bd wisp list --all # Include closed +bd wisp gc # Garbage collect orphaned wisps +bd wisp gc --age 24h # Custom age threshold +``` + +## Related Documentation + +- [ARCHITECTURE.md](ARCHITECTURE.md) - Overall bd architecture +- [CLI_REFERENCE.md](CLI_REFERENCE.md) - Complete command reference +- [../CLAUDE.md](../CLAUDE.md) - Quick reference for agents