Add documentation for features implemented in Go source but missing from the website docs: formulas.md: - Convoy formula type (multi-agent coordination) - Formula inheritance (extends field) - Conditional steps (condition field with truthy/negated/equality) - Loop/iteration (count, range, until with max) - Runtime expansion (on_complete with for_each) - bd cook command (compile-time vs runtime modes) - Expanded gate types and aspect composition wisps.md: - Squash lifecycle (bd mol squash - promote to persistent) - Burn lifecycle (bd mol burn - delete without trace) - Garbage collection (bd mol wisp gc) - Corrected storage model (Ephemeral=true in main DB) - Updated commands to match actual CLI surface index.md: - Added swarm commands (validate, create, status, list) - Added cook command - Added wisp lifecycle commands (squash, burn, gc) - Added bond and formula list commands Regenerated website/static/llms-full.txt via scripts/generate-llms-full.sh. Before: 0 hits for swarm, convoy, cook, extends, condition, loop, squash, burn, promote, for_each in llms-full.txt. After: all terms present with substantive documentation. Closes #3244
3.2 KiB
| id | title | sidebar_position |
|---|---|---|
| wisps | Wisps | 5 |
Wisps
Wisps are ephemeral workflows that don't sync to git.
What are Wisps?
Wisps are "vapor phase" molecules - issues stored with Ephemeral=true in the main database. They are local-only and not synced via Dolt push/pull.
Use Cases
| Scenario | Why Wisp? |
|---|---|
| Release workflows | One-time execution, no audit trail needed |
| Operational loops | Recurring cycles that auto-clean up |
| Health checks | Diagnostics that shouldn't clutter history |
| Local experiments | Quick throwaway work |
| Agent coordination | Local-only parallel coordination |
Creating Wisps
# Create wisp from formula
bd mol wisp <formula> [--var key=value]
# Examples
bd mol wisp quick-check
bd mol wisp release --var version=1.0.0
Formulas can recommend wisp usage with phase = "vapor" in the formula definition. If you use bd mol pour on a vapor-phase formula, you'll get a warning suggesting bd mol wisp instead.
Wisp Lifecycle
Formula (template)
| bd mol wisp
v
Wisp (ephemeral, Ephemeral=true)
| normal bd operations
v
Completed Wisp
|
+---> bd mol squash (promote to persistent molecule)
+---> bd mol burn (delete without trace)
+---> bd mol wisp gc (garbage collect old wisps)
Squash (Promote to Persistent)
Convert a wisp into a regular persistent molecule. Clears the Ephemeral flag so the issue syncs to git. Use when ephemeral work turns out to be worth preserving.
bd mol squash <wisp-id>
Burn (Delete Without Trace)
Delete a wisp and all its children without creating a digest or summary. Use for discarding failed or abandoned ephemeral work.
bd mol burn <wisp-id>
Garbage Collection
Clean up old, orphaned, or completed wisps automatically:
# List all wisps (flags old ones > 24h)
bd mol wisp list
# Garbage collect orphaned wisps
bd mol wisp gc
Wisps older than 24 hours are flagged as "old" in list output.
Wisp Commands
bd mol wisp <formula> # Create wisp from formula
bd mol wisp list # List all wisps
bd mol wisp list --json # List in JSON format
bd mol wisp gc # Garbage collect old wisps
bd mol squash <wisp-id> # Promote to persistent
bd mol burn <wisp-id> # Delete without digest
Wisp vs Molecule
| Aspect | Molecule (pour) | Wisp |
|---|---|---|
| Phase | Liquid | Vapor |
| Persistence | Permanent, syncs via Dolt | Ephemeral, local-only |
| Use case | Tracked work, audit trail | Temporary ops, one-time runs |
| Cleanup | Manual close/archive | Squash, burn, or GC |
Phase Control
Use bd mol bond to control phase when bonding formulas together:
# Force liquid (persistent molecule)
bd mol bond <formula> <target> --pour
# Force vapor (ephemeral wisp)
bd mol bond <formula> <target> --wisp
Best Practices
- Default to wisp for operational work - releases, checks, diagnostics
- Use pour for tracked work - features, bugs, anything worth preserving
- Squash if work becomes valuable - promote ephemeral to persistent
- Burn failed experiments - clean up without cluttering history
- Run GC periodically -
bd mol wisp gckeeps the database lean