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
77 lines
1.9 KiB
Markdown
77 lines
1.9 KiB
Markdown
---
|
|
id: index
|
|
title: Core Concepts
|
|
sidebar_position: 1
|
|
---
|
|
|
|
# Core Concepts
|
|
|
|
Understanding the fundamental concepts behind beads.
|
|
|
|
## Design Philosophy
|
|
|
|
Beads was built with these principles:
|
|
|
|
1. **Git as source of truth** - Issues sync via JSONL files, enabling collaboration across branches
|
|
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
|
|
3. **Local-first operation** - SQLite database for fast queries, background sync
|
|
4. **Declarative workflows** - Formulas define repeatable patterns
|
|
|
|
## Key Components
|
|
|
|
### Issues
|
|
|
|
Work items with:
|
|
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
|
|
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
|
|
- **Priority** - 0 (critical) to 4 (backlog)
|
|
- **Status** - `open`, `in_progress`, `closed`
|
|
- **Labels** - Flexible tagging
|
|
- **Dependencies** - Blocking relationships
|
|
|
|
### Dependencies
|
|
|
|
Four types of relationships:
|
|
|
|
| Type | Description | Affects Ready Queue |
|
|
|------|-------------|---------------------|
|
|
| `blocks` | Hard dependency (X blocks Y) | Yes |
|
|
| `parent-child` | Epic/subtask relationship | No |
|
|
| `discovered-from` | Track issues found during work | No |
|
|
| `related` | Soft relationship | No |
|
|
|
|
### Daemon
|
|
|
|
Background process per workspace:
|
|
- Auto-starts on first command
|
|
- Handles auto-sync with 5s debounce
|
|
- Socket at `.beads/bd.sock`
|
|
- Manage with `bd daemons` commands
|
|
|
|
### JSONL Sync
|
|
|
|
The synchronization mechanism:
|
|
|
|
```
|
|
SQLite DB (.beads/beads.db)
|
|
↕ auto-sync
|
|
JSONL (.beads/issues.jsonl)
|
|
↕ git
|
|
Remote repository
|
|
```
|
|
|
|
### Formulas
|
|
|
|
Declarative workflow templates:
|
|
- Define steps with dependencies
|
|
- Variable substitution
|
|
- Gates for async coordination
|
|
- Aspect-oriented transformations
|
|
|
|
## Navigation
|
|
|
|
- [Issues & Dependencies](/core-concepts/issues)
|
|
- [Daemon Architecture](/core-concepts/daemon)
|
|
- [JSONL Sync](/core-concepts/jsonl-sync)
|
|
- [Hash-based IDs](/core-concepts/hash-ids)
|