- architecture/index.md: /docs/DOLT.md → #dolt-server-mode anchor - core-concepts/index.md: /core-concepts/dolt-server and /dolt-sync → anchor links (pages never existed) - reference/configuration.md: /docs/CONFIG.md → GitHub source link - deploy-docs.yml: add lychee --remap to strip /beads/ baseUrl prefix from internal links - Apply same fixes to versioned_docs/version-1.0.0/ Amp-Thread-ID: https://ampcode.com/threads/T-019d68c4-3efa-71bf-aa9d-6e25fc48fb9a Co-authored-by: Amp <amp@ampcode.com>
1.9 KiB
1.9 KiB
| id | title | sidebar_position |
|---|---|---|
| index | Core Concepts | 1 |
Core Concepts
Understanding the fundamental concepts behind beads.
Design Philosophy
Beads was built with these principles:
- Dolt as source of truth - Issues stored in a version-controlled SQL database (Dolt), enabling collaboration via Dolt-native replication
- AI-native workflows - Hash-based IDs, JSON output, dependency-aware execution
- Local-first operation - Dolt database for fast queries, background sync
- 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 |
Dolt Server Mode
Dolt provides the database backend for beads:
- Start with
bd dolt start - Handles auto-commit and sync
- Logs available at
.beads/dolt/sql-server.log - Check health with
bd doctor
Dolt Sync
The synchronization mechanism:
Dolt DB (.beads/dolt/)
↕ dolt commit
Local Dolt history
↕ dolt push/pull
Remote Dolt repository
Formulas
Declarative workflow templates:
- Define steps with dependencies
- Variable substitution
- Gates for async coordination
- Aspect-oriented transformations