# Beads Markdown Plans vs Dependency-Aware Graphs: A Technical Comparison > Compare Beads markdown plans to dependency-aware graphs. Discover how DAGs with blocker relationships enable queryable ready queues and safe multi-agent workflows in this technical deep dive. - Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads) - Tags: deep-dive - Published: 2026-04-27 --- **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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/commands/create.go), the system parses the document hierarchy but initially creates isolated issues without dependency links. Consider a typical markdown plan: ```markdown # My Feature ## Design - [ ] Write design doc ## Implementation - [ ] Implement API - [ ] Add tests ``` After conversion: ```bash 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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/commands/dep.go): ```bash # 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`](https://github.com/gastownhall/beads/blob/main/cmd/bd/commands/ready.go)) evaluates the graph to return only work items with no open blockers: ```bash # 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: ```bash 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: ```bash # 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.