beads/website/docs/workflows/index.md
darcy f9b306f152 docs(claim): standardize start-work semantics to --claim (#2070)
Standardize start-work semantics to `bd update <id> --claim` across docs,
examples, templates, and website static LLM artifacts. Replaces
`--status in_progress` with `--claim` where the meaning is start-work.

Also fixes stale comment in llms.txt ("Update status" → "Start work").

Co-Authored-By: Valeriy Pavlovich <iqdoctor@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 22:11:39 -08:00

94 lines
2 KiB
Markdown

---
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 --claim
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