spec-driven-with-beads

Spec-driven development with git-synced task tracking.
Bridge OpenSpec's spec planning with Beads' persistent, dependency-aware issue graph.

proposal → specs → design → tasks+beads → apply → consolidate

The problem every AI coding agent hits

You plan a change with OpenSpec: proposal → specs → design. Great. Then you implement. The agent creates a flat tasks.md, ticks boxes, done.

Next session? The agent has amnesia. It doesn't know what was done, what was learned, or what's blocked. Multi-day features fragment across disconnected sessions. Multi-developer workflows don't exist — everyone works in isolation.

This schema fixes that.

The solution: Beads + OpenSpec

Beads is a Dolt-powered issue tracker that syncs to git. Unlike flat markdown task lists or cloud issue trackers, Beads stores your task graph in a version-controlled SQL database that lives in your repo. Push, pull, branch, merge — just like code.

| Capability | Flat tasks.md | GitHub Issues | Beads (this schema) | |---|---|---|---| | Dependency graph | ❌ Manual | ❌ Shallow | ✅ needs: in formula, bd ready enforces | | Git-synced | ✅ (file) | ❌ (cloud) | ✅ Dolt DB in .beads/, push/pull with code | | Multi-session persistence | ❌ Lost | ✅ (cloud) | ✅ bd dolt push/pull — pick up where you left off | | Multi-developer sync | ❌ Merge hell | ✅ (cloud) | ✅ Dolt-native replication, cell-level merge | | Cross-session knowledge | ❌ None | ❌ None | ✅ bd remember → bd prime injects into every session | | Reusable workflows | ❌ Copy-paste | ❌ None | ✅ bd mol distill extracts formulas from completed work | | Parallel agents | ❌ Impossible | ❌ Clunky | ✅ bd pin + bond points with waits_for fan-in | | Dependency-aware ready queue | ❌ None | ❌ None | ✅ bd ready only shows unblocked work | | Async coordination | ❌ None | ❌ Partial | ✅ Gates (human approval, timers, CI checks) | | One-command setup | ❌ Manual | ❌ N/A | ✅ bd pour spec-driven-change --var name=my-feature |

How it works

One command creates the entire task graph

bd pour spec-driven-change --var name=add-user-auth

Produces a molecule with mandatory dependency chain:

bd-a3f8 (epic: Spec-driven Change: add-user-auth)
├── bd-a3f8.1  proposal                (human review)
├── bd-a3f8.2  specs                   (needs: proposal)
├── bd-a3f8.3  design                  (needs: specs)
├── bd-a3f8.4  implement               (needs: design)
├── bd-a3f8.5  verify-specs-consolidate (auto-injected spec compliance check)
└── bd-a3f8.6  consolidate             (human, needs: implement, verify-specs)

No manual bd create × N. No bd dep add × N. The formula defines the graph.

Dependencies are enforced, not documented

$ bd ready
1. [P1] bd-a3f8.1: Review proposal for add-user-auth

$ bd ready --explain
● Ready:
  bd-a3f8.1 — no blocking dependencies
  
● Blocked:
  bd-a3f8.2 — blocked by bd-a3f8.1 (proposal)
  bd-a3f8.4 — blocked by bd-a3f8.3 (design)

The agent never picks work it can't start. No wasted cycles.

Work flows across sessions

# Session 1 — morning
bd pour spec-driven-change --var name=add-user-auth
bd update bd-a3f8.1 --claim   # Review proposal
bd close bd-a3f8.1
bd dolt push                  # Save state to repo

# Session 2 — afternoon (new session, zero context)
bd dolt pull                  # Pull task graph
bd ready                      # → bd-a3f8.2: Write specs

Pick up exactly where you left off. The agent doesn't need to re-read tasks.md — it queries bd ready.

Knowledge compounds across changes

After each change, consolidate runs:

bd lint                        # Validate all issues have proper structure
bd compact                     # Compress old Dolt history
bd remember --key ...          # Store lessons learned
bd mol squash                  # Compress molecule to lightweight digest
bd mol distill                 # (optional) Extract reusable formula

Every future bd prime call injects those memories. The agent knows what the last change taught it — no rediscovery.

Optional: parallel multi-agent or async gates

Bond nothing → sequential, zero config. Bond a formula at a bond point → unlock:

| Bond point | What it enables | |---|---| | parallel-execution | Split implement into parallel sub-steps, one per capability, each pinned to a different agent. Fan-in before consolidate. | | async-gates | Add human approval gates, timer delays, or GitHub CI checks before implementation. |

Quick start

# Prerequisites
brew install beads                    # or: npm install -g @beads/bd
npm install -g @fission-ai/openspec   # OpenSpec CLI
npm install -g spec-driven-with-beads # This schema

# In your project
cd your-project
bd init
openspec init
echo "schema: spec-driven-with-beads" >> openspec/config.yaml

# Start your first spec-driven change
# → /opsx:propose "my feature"
# → /opsx:apply
# → /opsx:consolidate

Links

• npm package
• OpenSpec (55k ★)
• Beads (24k ★)
• Beads Formula docs
• Beads Molecule docs
• Community schema catalog