Beads Markdown Plans vs Dependency-Aware Graphs: A Technical Comparison

Beads markdown plans are unstructured linear text files without relationship semantics, while dependency-aware graphs are persisted DAGs stored in a Dolt-backed SQL database that encode explicit blocker relationships enabling queryable ready queues and safe multi-agent workflows.

Beads is an open-source project management system that fundamentally replaces static markdown documents with a dynamic, queryable graph structure. While markdown plans serve as convenient starting points for outlining work, the gastownhall/beads repository implements a sophisticated dependency-aware graph as its core data model to enable automation and long-horizon workflows that linear text cannot support.

What Are Beads Markdown Plans?

In the Beads ecosystem, a markdown plan is a free-form text file that agents can read and edit, but it carries no intrinsic structure for representing relationships between work items. These files typically follow a linear outline format with headings and checkbox items, making them easy for humans to write but difficult for systems to query.

According to the project README.md, markdown plans are described as "messy" because they grow linearly and lack the ability to answer structural questions about the work. As implemented in cmd/bd/commands/create.go, the bd create --from-markdown command parses these files by converting headings into epics and checkbox items into sub-tasks, but the resulting issues exist as isolated nodes until explicit dependencies are added.

The fundamental limitation is that markdown plans cannot be queried for status checks like "what is currently blocked" or "what can I work on next?" Once a plan grows beyond a certain size, it also fails to survive within an agent's context window, losing critical project state.

The Dependency-Aware Graph Architecture

The dependency-aware graph represents the core data model of Beads, replacing linear text with a directed acyclic graph (DAG) stored in a Dolt-backed SQL database. Each node in this graph is an issue—which can be an epic, task, sub-task, message, or other work item—while edges encode explicit relationships such as blocks, relates_to, duplicates, and supersedes.

As documented in website/docs/core-concepts/index.md, this architecture implements "dependency-aware execution" as a foundational feature. The graph structures are defined in internal/graph/*.go, where the system maintains type-safe relationships between work items that survive across sessions and agent interactions.

Unlike markdown plans, the graph persists in a version-controlled database, enabling agents to track full histories of changes, merges, and branch-level versions. This persistence allows for automatic "claim-and-work" cycles that remain safe even when multiple concurrent agents operate on the same project.

Converting Markdown Plans to Graph Structures

Beads provides a migration path from unstructured plans to structured graphs through the CLI. When you run bd create --from-markdown plan.md, as implemented in cmd/bd/commands/create.go, the system parses the document hierarchy but initially creates isolated issues without dependency links.

Consider a typical markdown plan:

# My Feature

## Design

- [ ] Write design doc

## Implementation

- [ ] Implement API
- [ ] Add tests

After conversion:

bd create --from-markdown plan.md

This generates:

• Epic bd-a1b2 titled "My Feature"
• Task bd-a1b2.1 titled "Design"
• Sub-tasks under each section with unique IDs

However, at this stage, the "Implement API" task does not yet know it depends on the "Write design doc" task. You must explicitly link them using the graph commands.

Establishing Dependencies and Querying the Ready Queue

To transform isolated issues into a dependency-aware workflow, use the bd dep add command implemented in cmd/bd/commands/dep.go:

# Create independent tasks

bd create "Write design doc" -p 2 -t task    # → bd-c3d4

bd create "Implement API" -p 2 -t task     # → bd-e5f6

# Establish dependency: implementation is blocked by design

bd dep add bd-e5f6 bd-c3d4 --type blocks

Once dependencies are established, the bd ready command (located in cmd/bd/commands/ready.go) evaluates the graph to return only work items with no open blockers:

# List work ready to start

bd ready

In this example, bd ready initially lists only bd-c3d4 (the design doc). Once that task is closed, bd-e5f6 automatically appears in the ready queue. You can also filter dependencies programmatically:

bd list --filter 'blocks:bd-c3d4' --json

This queryability enables agents to automatically select appropriate work without manual coordination.

Multi-Agent Safety and Context Management

The dependency-aware graph solves critical problems that markdown plans cannot address in multi-agent environments. Because the graph tracks explicit blockers in the Dolt database, agents can implement safe claim-and-work loops:

# Agent automation loop

while true; do
  task=$(bd ready --json | jq -r '.[0].id')
  bd update "$task" --claim   # Atomic claim

  run_agent_on "$task"
  bd close "$task" "Done"
done

This loop guarantees that agents never pick tasks whose dependencies remain open. Additionally, the graph supports decay and summarization of older closed nodes, keeping the active context window small—a feature impossible with static markdown files.

Summary

• Markdown plans are unstructured, linear text files that cannot represent relationships or answer blocker queries.
• Dependency-aware graphs are persisted DAGs in a Dolt-backed SQL database where nodes are issues and edges define relationships like blocks and relates_to.
• The conversion command bd create --from-markdown migrates text to graph nodes, but you must use bd dep add to establish relationships.
• The bd ready command queries the graph to return only unblocked work, enabling safe multi-agent automation.
• Graph persistence and versioning in internal/graph/*.go provides capabilities impossible with static markdown, including atomic claims and context window management.

Frequently Asked Questions

Can I keep using markdown plans without converting to the graph format?

While you can maintain markdown files independently, Beads is designed to replace messy markdown plans with the dependency-aware graph. Without conversion, you lose the ability to query blockers, generate ready queues, or enable safe multi-agent coordination through commands like bd ready and bd claim.

How does the Dolt database improve upon traditional markdown storage?

The Dolt-backed SQL database provides versioning, branching, and structured querying capabilities that flat markdown files cannot support. As implemented in the core graph layer, this allows Beads to track full histories of issue relationships, support concurrent agent access, and perform complex queries like filtering by dependency type—features that would require manual parsing and state management in text files.

What happens if I delete a blocking task in the dependency graph?

Because the graph explicitly tracks blocks relationships in internal/graph/*.go, removing a blocker automatically makes dependent tasks eligible for the ready queue. The system ensures that bd ready only returns issues with no open incoming blocks edges, preventing agents from working on tasks prematurely while maintaining data integrity through the SQL persistence layer.

Is there a limit to how many dependencies a single task can have?

The graph structure in internal/graph/*.go supports multiple incoming and outgoing edges per node, allowing a task to block or be blocked by numerous other issues. However, complex dependency chains may impact query performance when running bd ready or bd list with deep recursive filters, though the Dolt-backed storage generally handles typical project scales efficiently.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}