feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
This commit is contained in:
Steve Yegge
252
website/docs/workflows/formulas.md
Normal file
252
website/docs/workflows/formulas.md
Normal file
@@ -0,0 +1,252 @@
|
||||
---
|
||||
id: formulas
|
||||
title: Formulas
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Formulas
|
||||
|
||||
Formulas are declarative workflow templates.
|
||||
|
||||
## Formula Format
|
||||
|
||||
Formulas can be written in TOML (preferred) or JSON:
|
||||
|
||||
### TOML Format
|
||||
|
||||
```toml
|
||||
formula = "feature-workflow"
|
||||
description = "Standard feature development workflow"
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[vars.feature_name]
|
||||
description = "Name of the feature"
|
||||
required = true
|
||||
|
||||
[[steps]]
|
||||
id = "design"
|
||||
title = "Design {{feature_name}}"
|
||||
type = "human"
|
||||
description = "Create design document"
|
||||
|
||||
[[steps]]
|
||||
id = "implement"
|
||||
title = "Implement {{feature_name}}"
|
||||
needs = ["design"]
|
||||
|
||||
[[steps]]
|
||||
id = "review"
|
||||
title = "Code review"
|
||||
needs = ["implement"]
|
||||
type = "human"
|
||||
|
||||
[[steps]]
|
||||
id = "merge"
|
||||
title = "Merge to main"
|
||||
needs = ["review"]
|
||||
```
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"formula": "feature-workflow",
|
||||
"description": "Standard feature development workflow",
|
||||
"version": 1,
|
||||
"type": "workflow",
|
||||
"vars": {
|
||||
"feature_name": {
|
||||
"description": "Name of the feature",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"steps": [
|
||||
{
|
||||
"id": "design",
|
||||
"title": "Design {{feature_name}}",
|
||||
"type": "human"
|
||||
},
|
||||
{
|
||||
"id": "implement",
|
||||
"title": "Implement {{feature_name}}",
|
||||
"needs": ["design"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Formula Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `workflow` | Standard step sequence |
|
||||
| `expansion` | Template for expansion operator |
|
||||
| `aspect` | Cross-cutting concerns |
|
||||
|
||||
## Variables
|
||||
|
||||
Define variables with defaults and constraints:
|
||||
|
||||
```toml
|
||||
[vars.version]
|
||||
description = "Release version"
|
||||
required = true
|
||||
pattern = "^\\d+\\.\\d+\\.\\d+$"
|
||||
|
||||
[vars.environment]
|
||||
description = "Target environment"
|
||||
default = "staging"
|
||||
enum = ["staging", "production"]
|
||||
```
|
||||
|
||||
Use variables in steps:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
title = "Deploy {{version}} to {{environment}}"
|
||||
```
|
||||
|
||||
## Step Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `task` | Normal work step (default) |
|
||||
| `human` | Requires human action |
|
||||
| `gate` | Async coordination point |
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Sequential
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "step1"
|
||||
title = "First step"
|
||||
|
||||
[[steps]]
|
||||
id = "step2"
|
||||
title = "Second step"
|
||||
needs = ["step1"]
|
||||
```
|
||||
|
||||
### Parallel then Join
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "test-unit"
|
||||
title = "Unit tests"
|
||||
|
||||
[[steps]]
|
||||
id = "test-integration"
|
||||
title = "Integration tests"
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy"
|
||||
needs = ["test-unit", "test-integration"] # Waits for both
|
||||
```
|
||||
|
||||
## Gates
|
||||
|
||||
Add gates for async coordination:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "approval"
|
||||
title = "Manager approval"
|
||||
type = "human"
|
||||
|
||||
[steps.gate]
|
||||
type = "human"
|
||||
approvers = ["manager"]
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy to production"
|
||||
needs = ["approval"]
|
||||
```
|
||||
|
||||
## Aspects (Cross-cutting)
|
||||
|
||||
Apply transformations to matching steps:
|
||||
|
||||
```toml
|
||||
formula = "security-scan"
|
||||
type = "aspect"
|
||||
|
||||
[[advice]]
|
||||
target = "*.deploy" # Match all deploy steps
|
||||
|
||||
[advice.before]
|
||||
id = "security-scan-{step.id}"
|
||||
title = "Security scan before {step.title}"
|
||||
```
|
||||
|
||||
## Formula Locations
|
||||
|
||||
Formulas are searched in order:
|
||||
1. `.beads/formulas/` (project-level)
|
||||
2. `~/.beads/formulas/` (user-level)
|
||||
3. Built-in formulas
|
||||
|
||||
## Using Formulas
|
||||
|
||||
```bash
|
||||
# List available formulas
|
||||
bd mol list
|
||||
|
||||
# Pour formula into molecule
|
||||
bd pour <formula-name> --var key=value
|
||||
|
||||
# Preview what would be created
|
||||
bd pour <formula-name> --dry-run
|
||||
```
|
||||
|
||||
## Creating Custom Formulas
|
||||
|
||||
1. Create file: `.beads/formulas/my-workflow.formula.toml`
|
||||
2. Define structure (see examples above)
|
||||
3. Use with: `bd pour my-workflow`
|
||||
|
||||
## Example: Release Formula
|
||||
|
||||
```toml
|
||||
formula = "release"
|
||||
description = "Standard release workflow"
|
||||
version = 1
|
||||
|
||||
[vars.version]
|
||||
required = true
|
||||
pattern = "^\\d+\\.\\d+\\.\\d+$"
|
||||
|
||||
[[steps]]
|
||||
id = "bump-version"
|
||||
title = "Bump version to {{version}}"
|
||||
|
||||
[[steps]]
|
||||
id = "changelog"
|
||||
title = "Update CHANGELOG"
|
||||
needs = ["bump-version"]
|
||||
|
||||
[[steps]]
|
||||
id = "test"
|
||||
title = "Run full test suite"
|
||||
needs = ["changelog"]
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build release artifacts"
|
||||
needs = ["test"]
|
||||
|
||||
[[steps]]
|
||||
id = "tag"
|
||||
title = "Create git tag v{{version}}"
|
||||
needs = ["build"]
|
||||
|
||||
[[steps]]
|
||||
id = "publish"
|
||||
title = "Publish release"
|
||||
needs = ["tag"]
|
||||
type = "human"
|
||||
```
|
||||
216
website/docs/workflows/gates.md
Normal file
216
website/docs/workflows/gates.md
Normal file
@@ -0,0 +1,216 @@
|
||||
---
|
||||
id: gates
|
||||
title: Gates
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Gates
|
||||
|
||||
Gates are async coordination primitives for workflow orchestration.
|
||||
|
||||
## What are Gates?
|
||||
|
||||
Gates block step progression until a condition is met:
|
||||
- Human approval
|
||||
- Timer expiration
|
||||
- External event (GitHub PR, CI, etc.)
|
||||
|
||||
## Gate Types
|
||||
|
||||
### Human Gate
|
||||
|
||||
Wait for human approval:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "deploy-approval"
|
||||
title = "Approval for production deploy"
|
||||
type = "human"
|
||||
|
||||
[steps.gate]
|
||||
type = "human"
|
||||
approvers = ["team-lead", "security"]
|
||||
require_all = false # Any approver can approve
|
||||
```
|
||||
|
||||
### Timer Gate
|
||||
|
||||
Wait for a duration:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "cooldown"
|
||||
title = "Wait for cooldown period"
|
||||
|
||||
[steps.gate]
|
||||
type = "timer"
|
||||
duration = "24h"
|
||||
```
|
||||
|
||||
Durations: `30m`, `2h`, `24h`, `7d`
|
||||
|
||||
### GitHub Gate
|
||||
|
||||
Wait for GitHub events:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "wait-for-ci"
|
||||
title = "Wait for CI to pass"
|
||||
|
||||
[steps.gate]
|
||||
type = "github"
|
||||
event = "check_suite"
|
||||
status = "success"
|
||||
```
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "wait-for-merge"
|
||||
title = "Wait for PR merge"
|
||||
|
||||
[steps.gate]
|
||||
type = "github"
|
||||
event = "pull_request"
|
||||
action = "closed"
|
||||
merged = true
|
||||
```
|
||||
|
||||
## Gate States
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| `pending` | Waiting for condition |
|
||||
| `open` | Condition met, can proceed |
|
||||
| `closed` | Step completed |
|
||||
|
||||
## Using Gates in Workflows
|
||||
|
||||
### Approval Flow
|
||||
|
||||
```toml
|
||||
formula = "production-deploy"
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build production artifacts"
|
||||
|
||||
[[steps]]
|
||||
id = "staging"
|
||||
title = "Deploy to staging"
|
||||
needs = ["build"]
|
||||
|
||||
[[steps]]
|
||||
id = "qa-approval"
|
||||
title = "QA sign-off"
|
||||
needs = ["staging"]
|
||||
type = "human"
|
||||
|
||||
[steps.gate]
|
||||
type = "human"
|
||||
approvers = ["qa-team"]
|
||||
|
||||
[[steps]]
|
||||
id = "production"
|
||||
title = "Deploy to production"
|
||||
needs = ["qa-approval"]
|
||||
```
|
||||
|
||||
### Scheduled Release
|
||||
|
||||
```toml
|
||||
formula = "scheduled-release"
|
||||
|
||||
[[steps]]
|
||||
id = "prepare"
|
||||
title = "Prepare release"
|
||||
|
||||
[[steps]]
|
||||
id = "wait-window"
|
||||
title = "Wait for release window"
|
||||
needs = ["prepare"]
|
||||
|
||||
[steps.gate]
|
||||
type = "timer"
|
||||
duration = "2h"
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy release"
|
||||
needs = ["wait-window"]
|
||||
```
|
||||
|
||||
### CI Integration
|
||||
|
||||
```toml
|
||||
formula = "ci-gated-deploy"
|
||||
|
||||
[[steps]]
|
||||
id = "create-pr"
|
||||
title = "Create pull request"
|
||||
|
||||
[[steps]]
|
||||
id = "wait-ci"
|
||||
title = "Wait for CI"
|
||||
needs = ["create-pr"]
|
||||
|
||||
[steps.gate]
|
||||
type = "github"
|
||||
event = "check_suite"
|
||||
status = "success"
|
||||
|
||||
[[steps]]
|
||||
id = "merge"
|
||||
title = "Merge PR"
|
||||
needs = ["wait-ci"]
|
||||
type = "human"
|
||||
```
|
||||
|
||||
## Gate Operations
|
||||
|
||||
### Check Gate Status
|
||||
|
||||
```bash
|
||||
bd show bd-xyz.3 # Shows gate state
|
||||
bd show bd-xyz.3 --json | jq '.gate'
|
||||
```
|
||||
|
||||
### Manual Gate Override
|
||||
|
||||
For human gates:
|
||||
|
||||
```bash
|
||||
bd gate approve bd-xyz.3 --approver "team-lead"
|
||||
```
|
||||
|
||||
### Skip Gate (Emergency)
|
||||
|
||||
```bash
|
||||
bd gate skip bd-xyz.3 --reason "Emergency deploy"
|
||||
```
|
||||
|
||||
## waits-for Dependency
|
||||
|
||||
The `waits-for` dependency type creates fan-in patterns:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "test-a"
|
||||
title = "Test suite A"
|
||||
|
||||
[[steps]]
|
||||
id = "test-b"
|
||||
title = "Test suite B"
|
||||
|
||||
[[steps]]
|
||||
id = "integration"
|
||||
title = "Integration tests"
|
||||
waits_for = ["test-a", "test-b"] # Fan-in: waits for all
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use human gates for critical decisions** - Don't auto-approve production
|
||||
2. **Add timeout to timer gates** - Prevent indefinite blocking
|
||||
3. **Document gate requirements** - Make approvers clear
|
||||
4. **Use CI gates for quality** - Block on test failures
|
||||
94
website/docs/workflows/index.md
Normal file
94
website/docs/workflows/index.md
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
id: index
|
||||
title: Workflows
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Workflows
|
||||
|
||||
Beads provides powerful workflow primitives for complex, multi-step processes.
|
||||
|
||||
## Chemistry Metaphor
|
||||
|
||||
Beads uses a molecular chemistry metaphor:
|
||||
|
||||
| Phase | Storage | Synced | Use Case |
|
||||
|-------|---------|--------|----------|
|
||||
| **Proto** (solid) | Built-in | N/A | Reusable templates |
|
||||
| **Mol** (liquid) | `.beads/` | Yes | Persistent work |
|
||||
| **Wisp** (vapor) | `.beads-wisp/` | No | Ephemeral operations |
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Formulas
|
||||
|
||||
Declarative workflow templates in TOML or JSON:
|
||||
|
||||
```toml
|
||||
formula = "feature-workflow"
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "design"
|
||||
title = "Design the feature"
|
||||
type = "human"
|
||||
|
||||
[[steps]]
|
||||
id = "implement"
|
||||
title = "Implement the feature"
|
||||
needs = ["design"]
|
||||
```
|
||||
|
||||
### Molecules
|
||||
|
||||
Work graphs with parent-child relationships:
|
||||
- Created by instantiating formulas with `bd pour`
|
||||
- Steps have dependencies (`needs`)
|
||||
- Progress tracked via issue status
|
||||
|
||||
### Gates
|
||||
|
||||
Async coordination primitives:
|
||||
- **Human gates** - Wait for human approval
|
||||
- **Timer gates** - Wait for duration
|
||||
- **GitHub gates** - Wait for PR merge, CI, etc.
|
||||
|
||||
### Wisps
|
||||
|
||||
Ephemeral operations that don't sync to git:
|
||||
- Created with `bd wisp`
|
||||
- Stored in `.beads-wisp/` (gitignored)
|
||||
- Auto-expire after completion
|
||||
|
||||
## Workflow Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bd pour` | Instantiate formula as molecule |
|
||||
| `bd wisp` | Create ephemeral wisp |
|
||||
| `bd mol list` | List molecules |
|
||||
| `bd pin` | Pin work to agent |
|
||||
| `bd hook` | Show pinned work |
|
||||
|
||||
## Simple Example
|
||||
|
||||
```bash
|
||||
# Create a release workflow
|
||||
bd pour release --var version=1.0.0
|
||||
|
||||
# View the molecule
|
||||
bd mol show release-1.0.0
|
||||
|
||||
# Work through steps
|
||||
bd update release-1.0.0.1 --status in_progress
|
||||
bd close release-1.0.0.1
|
||||
# Next step becomes ready...
|
||||
```
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Molecules](/workflows/molecules) - Work graphs and execution
|
||||
- [Formulas](/workflows/formulas) - Declarative templates
|
||||
- [Gates](/workflows/gates) - Async coordination
|
||||
- [Wisps](/workflows/wisps) - Ephemeral operations
|
||||
166
website/docs/workflows/molecules.md
Normal file
166
website/docs/workflows/molecules.md
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
id: molecules
|
||||
title: Molecules
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Molecules
|
||||
|
||||
Molecules are work graphs created from formulas.
|
||||
|
||||
## What is a Molecule?
|
||||
|
||||
A molecule is a persistent instance of a formula:
|
||||
- Contains steps with dependencies
|
||||
- Tracked in `.beads/` (syncs with git)
|
||||
- Steps map to issues with parent-child relationships
|
||||
|
||||
## Creating Molecules
|
||||
|
||||
### From Formula
|
||||
|
||||
```bash
|
||||
# Pour a formula into a molecule
|
||||
bd pour <formula-name> [--var key=value]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bd pour release --var version=1.0.0
|
||||
```
|
||||
|
||||
This creates:
|
||||
- Parent issue: `bd-xyz` (the molecule root)
|
||||
- Child issues: `bd-xyz.1`, `bd-xyz.2`, etc. (the steps)
|
||||
|
||||
### Listing Molecules
|
||||
|
||||
```bash
|
||||
bd mol list
|
||||
bd mol list --json
|
||||
```
|
||||
|
||||
### Viewing a Molecule
|
||||
|
||||
```bash
|
||||
bd mol show <molecule-id>
|
||||
bd dep tree <molecule-id> # Shows full hierarchy
|
||||
```
|
||||
|
||||
## Working with Molecules
|
||||
|
||||
### Step Dependencies
|
||||
|
||||
Steps have `needs` dependencies:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "implement"
|
||||
title = "Implement feature"
|
||||
needs = ["design"] # Must complete design first
|
||||
```
|
||||
|
||||
The `bd ready` command respects these:
|
||||
|
||||
```bash
|
||||
bd ready # Only shows steps with completed dependencies
|
||||
```
|
||||
|
||||
### Progressing Through Steps
|
||||
|
||||
```bash
|
||||
# Start a step
|
||||
bd update bd-xyz.1 --status in_progress
|
||||
|
||||
# Complete a step
|
||||
bd close bd-xyz.1 --reason "Done"
|
||||
|
||||
# Check what's ready next
|
||||
bd ready
|
||||
```
|
||||
|
||||
### Viewing Progress
|
||||
|
||||
```bash
|
||||
# See blocked steps
|
||||
bd blocked
|
||||
|
||||
# See molecule stats
|
||||
bd stats
|
||||
```
|
||||
|
||||
## Molecule Lifecycle
|
||||
|
||||
```
|
||||
Formula (template)
|
||||
↓ bd pour
|
||||
Molecule (instance)
|
||||
↓ work steps
|
||||
Completed Molecule
|
||||
↓ optional cleanup
|
||||
Archived
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Bond Points
|
||||
|
||||
Formulas can define bond points for composition:
|
||||
|
||||
```toml
|
||||
[compose]
|
||||
[[compose.bond_points]]
|
||||
id = "entry"
|
||||
step = "design"
|
||||
position = "before"
|
||||
```
|
||||
|
||||
### Hooks
|
||||
|
||||
Execute actions on step completion:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build project"
|
||||
|
||||
[steps.on_complete]
|
||||
run = "make build"
|
||||
```
|
||||
|
||||
### Pinning Work
|
||||
|
||||
Assign molecules to agents:
|
||||
|
||||
```bash
|
||||
# Pin to current agent
|
||||
bd pin bd-xyz --start
|
||||
|
||||
# Check what's pinned
|
||||
bd hook
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```bash
|
||||
# 1. Create molecule from formula
|
||||
bd pour feature-workflow --var name="dark-mode"
|
||||
|
||||
# 2. View structure
|
||||
bd dep tree bd-xyz
|
||||
|
||||
# 3. Start first step
|
||||
bd update bd-xyz.1 --status in_progress
|
||||
|
||||
# 4. Complete and progress
|
||||
bd close bd-xyz.1
|
||||
bd ready # Shows next steps
|
||||
|
||||
# 5. Continue until complete
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Formulas](/workflows/formulas) - Creating templates
|
||||
- [Gates](/workflows/gates) - Async coordination
|
||||
- [Wisps](/workflows/wisps) - Ephemeral workflows
|
||||
129
website/docs/workflows/wisps.md
Normal file
129
website/docs/workflows/wisps.md
Normal file
@@ -0,0 +1,129 @@
|
||||
---
|
||||
id: wisps
|
||||
title: Wisps
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Wisps
|
||||
|
||||
Wisps are ephemeral workflows that don't sync to git.
|
||||
|
||||
## What are Wisps?
|
||||
|
||||
Wisps are "vapor phase" molecules:
|
||||
- Stored in `.beads-wisp/` (gitignored)
|
||||
- Don't sync with git
|
||||
- Auto-expire after completion
|
||||
- Perfect for temporary operations
|
||||
|
||||
## Use Cases
|
||||
|
||||
| Scenario | Why Wisp? |
|
||||
|----------|-----------|
|
||||
| Local experiments | No need to pollute git history |
|
||||
| CI/CD pipelines | Ephemeral by nature |
|
||||
| Scratch workflows | Quick throwaway work |
|
||||
| Agent coordination | Local-only coordination |
|
||||
|
||||
## Creating Wisps
|
||||
|
||||
```bash
|
||||
# Create wisp from formula
|
||||
bd wisp create <formula> [--var key=value]
|
||||
|
||||
# Example
|
||||
bd wisp create quick-check --var target=auth-module
|
||||
```
|
||||
|
||||
## Wisp Commands
|
||||
|
||||
```bash
|
||||
# List wisps
|
||||
bd wisp list
|
||||
bd wisp list --json
|
||||
|
||||
# Show wisp details
|
||||
bd wisp show <wisp-id>
|
||||
|
||||
# Delete wisp
|
||||
bd wisp delete <wisp-id>
|
||||
|
||||
# Delete all completed wisps
|
||||
bd wisp cleanup
|
||||
```
|
||||
|
||||
## Wisp vs Molecule
|
||||
|
||||
| Aspect | Molecule | Wisp |
|
||||
|--------|----------|------|
|
||||
| Storage | `.beads/` | `.beads-wisp/` |
|
||||
| Git sync | Yes | No |
|
||||
| Persistence | Permanent | Ephemeral |
|
||||
| Use case | Tracked work | Temporary ops |
|
||||
|
||||
## Phase Control
|
||||
|
||||
Use `bd mol bond` to control phase:
|
||||
|
||||
```bash
|
||||
# Force liquid (persistent molecule)
|
||||
bd mol bond <formula> <target> --pour
|
||||
|
||||
# Force vapor (ephemeral wisp)
|
||||
bd mol bond <formula> <target> --wisp
|
||||
```
|
||||
|
||||
## Example: Quick Check Workflow
|
||||
|
||||
Create a wisp for running checks:
|
||||
|
||||
```toml
|
||||
# .beads/formulas/quick-check.formula.toml
|
||||
formula = "quick-check"
|
||||
description = "Quick local checks"
|
||||
|
||||
[[steps]]
|
||||
id = "lint"
|
||||
title = "Run linter"
|
||||
|
||||
[[steps]]
|
||||
id = "test"
|
||||
title = "Run tests"
|
||||
needs = ["lint"]
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build project"
|
||||
needs = ["test"]
|
||||
```
|
||||
|
||||
Use as wisp:
|
||||
|
||||
```bash
|
||||
bd wisp create quick-check
|
||||
# Work through steps...
|
||||
bd wisp cleanup # Remove when done
|
||||
```
|
||||
|
||||
## Auto-Expiration
|
||||
|
||||
Wisps can auto-expire:
|
||||
|
||||
```toml
|
||||
[wisp]
|
||||
expires_after = "24h" # Auto-delete after 24 hours
|
||||
```
|
||||
|
||||
Or cleanup manually:
|
||||
|
||||
```bash
|
||||
bd wisp cleanup --all # Remove all wisps
|
||||
bd wisp cleanup --completed # Remove only completed
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use wisps for local-only work** - Don't sync to git
|
||||
2. **Clean up regularly** - `bd wisp cleanup`
|
||||
3. **Use molecules for tracked work** - Wisps are ephemeral
|
||||
4. **Consider CI/CD wisps** - Perfect for pipeline steps
|
||||
Reference in New Issue
Block a user