spec-driven-with-beads 3.0.0 → 3.0.1

package/README.md

@@ -1,55 +1,150 @@
 # spec-driven-with-beads
 
-OpenSpec custom schema that uses [Beads](https://github.com/gastownhall/beads) molecules for task tracking, execution, and durable knowledge retention across sessions.
+**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 (via molecule) → consolidate
+proposal → specs → design → tasks+beads → apply → consolidate
 ```
 
-## What makes this different
+---
 
-Other spec-driven schemas end at `archive` — move files, done. Knowledge dies with the session.
+## The problem every AI coding agent hits
 
-This schema uses Beads' **formula + molecule** system. One `bd pour` creates the entire dependency graph with mandatory `needs:` dependencies, then **consolidate** closes the learning loop — `bd remember` persists lessons as durable memories, `bd mol distill` extracts reusable formulas from completed work.
+You plan a change with OpenSpec: proposal → specs → design. Great. Then you implement. The agent creates a flat `tasks.md`, ticks boxes, done.
 
-### Key features
+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.
 
-- **Mandatory dependency graph** — the formula defines `needs:` between every step. `bd ready` only shows unblocked work. No manual `bd dep add`.
-- **Spec-compliance aspect** — auto-injects a "Verify specs pass" step before consolidate. No config needed.
-- **Bond points for optional behavior** — parallel multi-agent execution, async gates (human approval/CI/timers). Bond a formula to unlock; bond nothing = sequential.
-- **`bd mol squash`** — compresses completed molecules into lightweight digests. Clean issue graph.
-- **`bd mol distill`** — extracts reusable formulas from completed changes. The schema teaches itself.
-- **`bd remember`** — persists learnings that `bd prime` injects into every future session.
+**This schema fixes that.**
 
-## Requirements
+---
 
-- [Beads](https://github.com/gastownhall/beads) installed (`bd` on PATH)
-- `bd init` run in your project
-- OpenSpec installed (`npm install -g @fission-ai/openspec`)
+## The solution: Beads + OpenSpec
 
-## Install
+[Beads](https://github.com/gastownhall/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
 
-```bash
-npm install -g spec-driven-with-beads
+```
+$ 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)
 ```
 
-## Usage
+The agent never picks work it can't start. No wasted cycles.
 
-In `openspec/config.yaml`:
+### Work flows across sessions
 
-```yaml
-schema: spec-driven-with-beads
+```
+# 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
+
+```bash
+# 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
 ```
 
-Then:
-- `/opsx:propose "my feature"`
-- `/opsx:apply` — driven by molecule step order
-- `/opsx:consolidate` — lint, squash, remember, distill, archive
+---
 
 ## Links
 
-- [OpenSpec](https://github.com/Fission-AI/OpenSpec)
-- [Beads](https://github.com/gastownhall/beads)
+- [npm package](https://www.npmjs.com/package/spec-driven-with-beads)
+- [OpenSpec](https://github.com/Fission-AI/OpenSpec) (55k ★)
+- [Beads](https://github.com/gastownhall/beads) (24k ★)
 - [Beads Formula docs](https://gastownhall.github.io/beads/workflows/formulas)
 - [Beads Molecule docs](https://gastownhall.github.io/beads/workflows/molecules)
 - [Community schema catalog](https://github.com/intent-driven-dev/openspec-schemas)

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "spec-driven-with-beads",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "OpenSpec custom schema using Beads molecules with bond points, aspects, and distill for spec-driven development",
-  "keywords": ["openspec", "beads", "spec-driven-development", "schema", "sdd"],
+  "keywords": [
+    "openspec",
+    "beads",
+    "spec-driven-development",
+    "schema",
+    "sdd"
+  ],
   "license": "MIT",
   "author": "yoinks-yoinks",
   "homepage": "https://www.npmjs.com/package/spec-driven-with-beads",