DEV Community

Koustubh
Koustubh

Posted on

Building Apps with AI: How beads Changed My Development Workflow

#ai #productivity #devtools #webdev

Building Apps with AI: How beads Changed My Development Workflow

Part 1 of 2: From Spec Documents to Living Issue Trackers

TL;DR

I built a real estate comparison app using Claude Code and a tool called beads - a git-native issue tracker designed for AI-assisted development. This post explores how beads transformed my workflow from writing lengthy spec documents to having a living, breathing project tracker that my AI assistant actually understands.

Source Code: GitHub Repository
Live Demo: Mission House App - This is a SPA with no backend, so it requires a Google Maps Platform API key to be provided on the UI to render fully. Have a look at the snapshots in the source code repository above to get an idea of the app.

Spec-Driven Development (SDD)

If you've used AI coding assistants for larger projects, you've likely encountered Spec-Driven Development (SDD) - a methodology where detailed specifications drive the implementation process. I've written about SDD in detail previously - it's a powerful approach that works well for many projects. Different frameworks implement SDD differently.

One popular implementation is agent-os, which formalizes SDD into a six-phase workflow:

agent-os SDD workflow

agent-os uses layered context (Standards → Product → Specs) stored in markdown files like mission.md, roadmap.md, and tech-stack.md. Tasks are derived from specs, not created directly.

agent-os works well, but has trade-offs:

  1. Spec-first philosophy - You write specs before creating tasks
  2. Tasks derived from prose - The AI interprets specs to generate tasks
  3. Layered context - Rich documentation, but more files to maintain
  4. Sequential phases - Structured workflow from planning to orchestration

SDD interpretation flow

SDD frameworks like agent-os are great for complex features that need upfront design. But what if you want to skip straight to task management?

The key difference is where control flow lives:

  • In SDD, control flow is implicit in prose.
  • In beads, control flow is explicit in a DAG.

To be clear: SDD shines when architectural intent must be stabilized early — beads optimizes for execution once intent is roughly understood.

Enter beads: Task-First with Graph-Based Dependencies

Beads is what its creator Steve Yegge calls "a drop-in cognitive upgrade for your coding agents." Instead of the spec-first approach, beads is task-first - you create issues directly, with explicit dependencies stored as graph edges.

1. Compact JSONL, Not Verbose Markdown 

.beads/
├── issues.jsonl    # All issues in ONE compact file
├── config.yaml     # Project configuration
└── db.sqlite       # Local cache for fast queries
Enter fullscreen mode Exit fullscreen mode

One line per issue. No walls of prose. The AI can quickly parse the entire project state:

{
  "id": "mission-house-ogp",
  "title": "Implement scraper",
  "status": "closed",
  "dependencies": [{ "depends_on_id": "mission-house-5mv" }]
}
Enter fullscreen mode Exit fullscreen mode

2. Automatic "What's Next?" via Graph Traversal

This is the killer feature. Instead of the AI parsing prose to figure out order of execution:

bd ready  # Shows only unblocked, high-priority tasks
Enter fullscreen mode Exit fullscreen mode

The graph database computes eligibility automatically based on explicit status, dependencies, and user-defined priority.

bd ready flow

3. Explicit Dependencies = Enforced Execution Order 

bd dep add mission-house-abc mission-house-xyz
# "abc depends on xyz" (xyz blocks abc)
Enter fullscreen mode Exit fullscreen mode

This isn't prose that might be ignored - it's a graph edge. The AI literally cannot see abc in bd ready until xyz is closed.

Quick Start: Installing beads

For macOS users:

brew tap steveyegge/beads
brew install bd

# Initialize in your project
cd your-project
bd init
Enter fullscreen mode Exit fullscreen mode

Other options: npm install -g @beads/bd or go install github.com/steveyegge/beads/cmd/bd@latest

That's it. You now have a .beads directory in your repo.

Also install the beads claude code plugin following this.

The App: Mission House

Before diving deeper into beads, let me briefly introduce what we built. Mission House is a property comparison tool for Melbourne house hunters. It helps answer questions like:

  • Which catchment schools serve this address?
  • How do their NAPLAN scores compare to each other?
  • How long is the commute to the CBD?
  • How do these 4 properties compare on a radar chart?

Mission House architecture

The interesting part isn't the app itself - it's how we built it using beads.

How I Used beads: A Real Example

Although beads is task-first, I didn’t start from a blank slate.

I began with a lightweight requirements.md that described:

  • core user flows
  • data sources (e.g. NAPLAN, Google Maps)
  • output expectations (comparison metrics, charts)

I then asked Claude Code (with beads installed) to:

  • Read requirements.md
  • Propose epics, features, and tasks
  • Encode them directly into beads issues with explicit dependencies

In other words, requirements existed, but they were treated as input, not as a continuously consulted execution artifact.

Once the task graph existed, beads became the primary source of truth.

Here's where the magic happens. When I started my next Claude Code session:

> bd ready

mission-house-5mv [P1] [task] open - Set up frontend project structure
  └─ No blockers - ready to work!
Enter fullscreen mode Exit fullscreen mode

Claude immediately knew what to work on. No spec re-reading, no context reconstruction - just:

> bd update mission-house-5mv --status=in_progress
Enter fullscreen mode Exit fullscreen mode

And we're coding.

The Dependency Graph

Here's what our project looked like after the initial planning:

Dependency graph

Every arrow represents a bd dep add command. The AI knows it can't work on "Web Scraper" until "URL Input Form" is done.

What's Coming in Part 2

In the next post, I'll dive deep into:

  1. The JSONL Advantage - How storing issues in plain text gives AI assistants "long memory"
  2. Workflow Patterns - Epics → Features → Tasks hierarchy
  3. Real Issue Examples - Actual JSON from our project
  4. beads vs. Spec-Driven Development - A detailed comparison
  5. The Drawbacks - What didn't work so well
  6. Advanced Features - Tombstones, sync branches, and multi-session workflows

Key Takeaways

  1. Task-first vs. spec-first - beads lets you create issues directly; SDD requires specs first
  2. Graph-based dependencies - Explicit edges, not prose to interpret
  3. bd ready is the killer feature - Automatic prioritization via graph traversal
  4. Enforced execution order - Blocked tasks are invisible until unblocked

Continue to Part 2: Deep Dive into beads Workflow →

Top comments (0)