beads/docs/workflows/todo.md
Chris Sells 5b660081ed docs: fix fact errors found by adversarial review
Every fix verified against the binary or a traced source call path:

- How Beads Works: parent-child DOES affect ready work (a blocked parent
  blocks its children — the blocked-state SQL inherits it), hash-ID
  inputs are title/description/creator/creation-time plus a collision
  nonce (live generator is internal/idgen, not the legacy one), and
  bead gates dropped from the gates bullet (currently unresolvable).
- Graph-link type strings are hyphenated (relates-to, replies-to);
  underscore forms are rejected by the parser. Fixed corpus-wide
  including the README feature bullet.
- upgrading.md: the version-era table's boundaries were refuted by git
  archaeology (embedded Dolt shipped in v0.60.0 and always used
  .beads/embeddeddolt/; nothing changed at the claimed v0.63.3
  boundary) — replaced with a layout-based identification table.
- Phantom .beads/dolt/sql-server.log path in sync-failures and the FAQ;
  the managed server writes .beads/dolt-server.log.
- FAQ: ID growth matches DefaultAdaptiveConfig (min 3, max 8,
  probability-driven), dependency-type wording no longer claims exactly
  four types, and unmeasured performance figures are hedged instead of
  stated as facts.
- quickstart: bd migrate --cleanup doesn't exist; init installs hooks
  by default (no prompt) and has no merge-driver step; ready output
  quote and bd restore recovery source corrected.
- formulas.md: step types map to issue types (task/bug/feature/epic/
  chore; anything else falls back to task — human/gate are not step
  types), and there is no built-in formula search tier.
- todo.md: bd update takes --set-labels, not --labels.
- graph-links.md: broken #dependencies fragment → #add-dependencies.
2026-07-12 10:37:17 -07:00

4.2 KiB

title
TODO Command

The bd todo command provides a lightweight interface for managing TODO items as task-type issues.

Philosophy

TODOs in bd are not a separate tracking system - they are regular task-type issues with convenient shortcuts. This means:

  • No parallel systems: TODOs use the same storage and sync as all other issues
  • Promotable: Easy to convert a TODO to a bug/feature when needed
  • Full featured: TODOs support all bd features (dependencies, labels, routing)
  • Simple interface: Quick commands for common TODO workflows

Quick Start

# Add a TODO
bd todo add "Fix the login bug" -p 1

# List TODOs
bd todo

# Mark TODO as done
bd todo done <id>

Commands

bd todo (or bd todo list)

List all open task-type issues.

bd todo                  # List open TODOs
bd todo list            # Same as above
bd todo list --all      # Show completed TODOs too
bd todo list --json     # JSON output

Output:

  ○ test-yxg  Fix the login bug                         ● P1  open
  ○ test-ryl  Update documentation                      ● P3  open

Total: 2 TODOs

bd todo add <title>

Create a new TODO item (task-type issue).

bd todo add "Fix the login bug"                                # Default P2
bd todo add "Update docs" -p 3 -d "Add examples"              # With priority and description
bd todo add "Critical fix" --priority 0 --description "ASAP"  # P0 task

Flags:

  • -p, --priority <0-4>: Priority (default: 2)
  • -d, --description <text>: Description

bd todo done <id> [<id>...]

Mark one or more TODOs as complete.

bd todo done test-abc              # Close one TODO
bd todo done test-abc test-def     # Close multiple
bd todo done test-abc --reason "Fixed in PR #42"  # With reason

Flags:

  • --reason <text>: Reason for closing (default: "Completed")

Converting TODOs

TODOs are regular task issues, so you can convert them:

# Promote TODO to bug
bd update test-abc --type bug --priority 0

# Add dependencies
bd dep add test-abc test-def

# Add labels
bd update test-abc --set-labels "urgent,frontend"

Viewing TODO Details

Use regular bd commands:

bd show test-abc        # View TODO details
bd list --type task     # List all tasks (including TODOs)
bd ready               # See ready TODOs in work queue

Examples

Daily TODO workflow

# Morning: add your tasks
bd todo add "Review PRs"
bd todo add "Fix CI pipeline" -p 1
bd todo add "Update changelog" -p 3

# Check what's on your plate
bd todo

# Complete work
bd todo done <id>
bd todo done <id>

# End of day: see what's left
bd todo

Converting TODO to full issue

# Start with a quick TODO
bd todo add "Login is broken"

# Later, realize it's more serious
bd update <id> --type bug --priority 0 --description "Users can't login, multiple reports"
bd update <id> --acceptance "Login works for all user types"

# Now it's a full-fledged bug with proper tracking
bd show <id>

FAQ

Q: Are TODOs different from tasks? A: No, TODOs are just task-type issues. The bd todo command provides shortcuts for common task operations.

Q: Can TODOs have dependencies? A: Yes! Use bd dep add <todo-id> <blocks-id> like any other issue.

Q: Do TODOs sync across machines? A: Yes, they're stored in the Dolt database and synced via Dolt remotes like all other issues.

Q: Can I use TODOs with bd ready? A: Yes! bd ready shows all unblocked issues, including task-type TODOs.

Q: Should I use TODOs or regular tasks? A: Use bd todo for quick, informal tasks. Use bd create -t task for tasks that need more context or are part of larger planning.

Design Rationale

The TODO command follows beads' philosophy of minimal surface area:

  1. No new types: TODOs are task-type issues
  2. No special storage: Same Dolt database as everything else
  3. Convenience layer: Just shortcuts for common operations
  4. Fully compatible: Works with all bd features and commands

This ensures:

  • No duplicate tracking systems
  • No migration needed between TODOs and tasks
  • Works with all existing bd tooling (federation, compaction, routing)
  • Simple to understand and maintain