584608a14e
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
78 lines
2.3 KiB
Plaintext
78 lines
2.3 KiB
Plaintext
# Beads (bd)
|
|
|
|
> Git-backed issue tracker for AI-supervised coding workflows.
|
|
> Daemon-based CLI with formulas, molecules, and multi-agent coordination.
|
|
|
|
## Quick Start
|
|
|
|
Install:
|
|
```bash
|
|
brew tap steveyegge/beads && brew install bd
|
|
```
|
|
|
|
Initialize:
|
|
```bash
|
|
cd your-project && bd init --quiet
|
|
```
|
|
|
|
## Essential Commands
|
|
|
|
```bash
|
|
bd create "Title" -t bug -p 1 --json # Create issue
|
|
bd list --status open --json # List issues
|
|
bd show bd-42 --json # Show details
|
|
bd update bd-42 --status in_progress # Update status
|
|
bd close bd-42 --reason "Done" # Close issue
|
|
bd ready --json # Show unblocked work
|
|
bd sync # Sync to git
|
|
```
|
|
|
|
## For AI Agents
|
|
|
|
- Always use `--json` for programmatic access
|
|
- Always include `--description` when creating issues
|
|
- Use `--deps discovered-from:<id>` to link found issues
|
|
- Run `bd sync` at end of every session
|
|
|
|
## Key Concepts
|
|
|
|
- **Issues**: Work items with priorities (0-4), types (bug/feature/task/epic/chore)
|
|
- **Dependencies**: `blocks` (affects ready queue), `parent-child`, `discovered-from`, `related`
|
|
- **Formulas**: Declarative workflow templates (TOML/JSON)
|
|
- **Molecules**: Work graphs from formulas
|
|
- **Gates**: Async coordination (human/timer/github)
|
|
- **Wisps**: Ephemeral workflows (don't sync to git)
|
|
|
|
## Recovery
|
|
|
|
Quick fixes for common issues:
|
|
|
|
- Database Corruption: `git checkout HEAD~1 -- .beads/`
|
|
- Merge Conflicts: Resolve JSONL conflicts, then `bd sync`
|
|
- Circular Dependencies: `bd doctor` (diagnose only, NEVER --fix)
|
|
- Sync Failures: `bd sync --import-only`
|
|
|
|
Full runbooks: https://steveyegge.github.io/beads/recovery/
|
|
|
|
## Session Close Protocol
|
|
|
|
Before ending any AI session:
|
|
1. `bd sync` - push changes to git
|
|
2. `bd status` - verify clean state
|
|
3. Resolve conflicts before closing
|
|
|
|
WARNING: Skipping sync causes data loss in multi-agent workflows.
|
|
|
|
## Documentation
|
|
|
|
- Full docs: https://steveyegge.github.io/beads/
|
|
- CLI reference: https://steveyegge.github.io/beads/cli-reference
|
|
- Agent guide: https://steveyegge.github.io/beads/integrations/claude-code
|
|
- Complete LLM context: https://steveyegge.github.io/beads/llms-full.txt
|
|
|
|
## Links
|
|
|
|
- GitHub: https://github.com/steveyegge/beads
|
|
- npm: https://www.npmjs.com/package/@beads/bd
|
|
- PyPI (MCP): https://pypi.org/project/beads-mcp/
|