Files

Steve Yegge 584608a14e 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

2025-12-30 18:27:50 -08:00

2.4 KiB

Raw Blame History

id, title, sidebar_position, slug

id	title	sidebar_position	slug
intro	Introduction	1	/

Beads Documentation

Beads (bd) is a git-backed issue tracker designed for AI-supervised coding workflows.

Why Beads?

Traditional issue trackers (Jira, GitHub Issues) weren't designed for AI agents. Beads was built from the ground up for:

AI-native workflows - Hash-based IDs prevent collisions when multiple agents work concurrently
Git-backed storage - Issues sync via JSONL files, enabling collaboration across branches
Dependency-aware execution - bd ready shows only unblocked work
Formula system - Declarative templates for repeatable workflows
Multi-agent coordination - Routing, gates, and molecules for complex workflows

Quick Start

# Install via Homebrew (macOS/Linux)
brew tap steveyegge/beads
brew install bd

# Initialize in your project
cd your-project
bd init --quiet

# Create your first issue
bd create "Set up database" -p 1 -t task

# See ready work
bd ready

Core Concepts

Concept	Description
Issues	Work items with priorities, types, labels, and dependencies
Dependencies	`blocks`, `parent-child`, `discovered-from`, `related`
Daemon	Background process for auto-sync and performance
Formulas	Declarative workflow templates (TOML or JSON)
Molecules	Work graphs with parent-child relationships
Gates	Async coordination primitives (human, timer, GitHub)

For AI Agents

Beads is optimized for AI coding agents:

# Always use --json for programmatic access
bd list --json
bd show bd-42 --json

# Track discovered work during implementation
bd create "Found bug in auth" --description="Details..." \
  --deps discovered-from:bd-100 --json

# Sync at end of session
bd sync

See the Claude Code integration for detailed agent instructions.

Architecture

SQLite DB (.beads/beads.db, gitignored)
    ↕ auto-sync (5s debounce)
JSONL (.beads/issues.jsonl, git-tracked)
    ↕ git push/pull
Remote JSONL (shared across machines)

The magic is automatic synchronization between a local SQLite database and git-tracked JSONL files.

Next Steps

Installation - Get bd installed
Quick Start - Create your first issues
CLI Reference - All available commands
Workflows - Formulas, molecules, and gates

2.4 KiB Raw Blame History