ToolsJanuary 11, 2026

Spec-Driven Development with Beads

A lightweight, git-backed task tracking system that models dependencies and surfaces ready work. Perfect for agent-assisted development and TDD workflows.

Each entry keeps the writeup and source together, so the page reads like a clipped page from the archive rather than a detached utility screen.

The implementation

The detail page preserves the practical behavior of the original route: the writeup stays readable, the source remains copyable and syntax highlighted, and the item can still link back into the rest of the catalog.

Beads is a git-backed task tracker by Steve Yegge. Tasks are stored as JSONL in your repo, so state is versioned and available to AI assistants.

External trackers (GitHub Issues, Jira) require context switching and can't be read by local tools. Beads keeps task state in the repo, so you stay in your editor and AI assistants can query it directly.

The key command is bd ready, which returns unblocked tasks based on dependency modeling. For projects with 30+ tasks and complex dependencies, this removes the overhead of manually tracking what's actionable.

I use Beads for spec-driven development: tasks.md defines what to do, architecture.md captures design decisions, log.md tracks session history, and Beads tracks task status.

beads-spec-driven-dev.sh
1# Installation
2brew install beads
3bd init
4echo ".beads/*.db" >> .gitignore
5
6# Create tasks
7bd create "T1: Project Structure" -t task -p 0 \
8  -l "project:myapp,phase:1,tdd" \
9  -d "Set up package structure" --json
10
11bd create "T2: Core Client" -t task -p 1 \
12  -l "project:myapp,phase:1,tdd" \
13  -d "Implement client class" --json
14
15# Model dependencies
16bd dep add <T2-id> <T1-id> --type blocks
17
18# Find ready work
19bd ready
20bd show <id>
21bd dep tree <id>
22
23# Claim and link to GitHub
24bd update <id> --status in_progress
25gh issue create --title "T1: Project Structure" \
26  --body "See tasks.md#T1" \
27  --label "project:myapp" --label "tdd"
28
29# TDD loop
30git switch -c feat/1-project-structure
31uv run pytest -k test_project_structure -v
32git add -A && git commit -m "feat: implement T1"
33gh pr create --title "feat(1): Project Structure" --body "Closes #1"
34
35# Close and sync
36bd close <id> --reason implemented
37bd sync -m "Close T1: Project Structure"
38git pull
39bd ready

More from the lab

Related utilities

View full catalog