Prerequisites
-
Load maestro-core first - maestro-core for routing table and fallback policies
-
Routing and fallback policies are defined in AGENTS.md.
Tracking - Persistent Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
Entry Points
Trigger Reference Action
bd , beads
references/workflow.md
Core CLI operations
fb , file-beads
references/FILE_BEADS.md
File beads from plan → auto-orchestration
rb , review-beads
references/REVIEW_BEADS.md
Review filed beads
Quick Decision
bd vs TodoWrite:
-
"Will I need this in 2 weeks?" → YES = bd
-
"Could history get compacted?" → YES = bd
-
"Has blockers/dependencies?" → YES = bd
-
"Done this session?" → YES = TodoWrite
Rule: If resuming in 2 weeks would be hard without bd, use bd.
Essential Commands
Command Purpose
bd ready
Show tasks ready to work on
bd create "Title" -p 1
Create new task
bd show <id>
View task details
bd update <id> --status in_progress
Start working
bd update <id> --notes "Progress"
Add progress notes
bd close <id> --reason completed
Complete task
bd dep add <child> <parent>
Add dependency
bd sync
Sync with git remote
Session Protocol
-
Start: bd ready → pick highest priority → bd show <id> → update to in_progress
-
Work: Add notes frequently (critical for compaction survival)
-
End: Close finished work → bd sync → git push
Reference Files
Category Files
Workflows workflow.md , WORKFLOWS.md , FILE_BEADS.md , REVIEW_BEADS.md
CLI CLI_REFERENCE.md , DEPENDENCIES.md , LABELS.md
Integration conductor-integration.md , VILLAGE.md , GIT_INTEGRATION.md
Operations AGENTS.md , RESUMABILITY.md , TROUBLESHOOTING.md
Anti-Patterns
-
❌ Using TodoWrite for multi-session work
-
❌ Forgetting to add notes (loses context on compaction)
-
❌ Not running bd sync before ending session
-
❌ Creating beads for trivial single-session tasks
Related
-
maestro-core - Workflow router and skill hierarchy
-
conductor - Automated beads operations via facade
-
orchestrator - Multi-agent parallel execution