spec-driven-with-beads 2.0.0 → 3.0.1

package/README.md

@@ -1,63 +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, update specs, done. Knowledge dies with the session.
+## The problem every AI coding agent hits
 
-This schema uses Beads' **formula + molecule** system. One `bd pour` command creates the entire dependency graph:
+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](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-xyz (epic: Spec-driven Change: my-feature)
-├── bd-xyz.1  proposal          (human)
-├── bd-xyz.2  specs             (needs: proposal)
-├── bd-xyz.3  design            (needs: specs)
-├── bd-xyz.4  implement         (needs: design)
-└── bd-xyz.5  consolidate       (human, needs: implement)
+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 manual `bd dep add` × N. The formula defines the graph.
+No manual `bd create` × N. No `bd dep add` × N. The formula defines the graph.
 
-Then **`consolidate`** closes the loop — `bd remember` persists lessons as durable memories that `bd prime` injects into every future session. No context loss, no rediscovery.
+### Dependencies are enforced, not documented
 
-No other OpenSpec schema does this. No task tracker (Linear, GitHub Issues, Jira) has a `bd remember` equivalent.
+```
+$ 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)
+```
 
-## Requirements
+The agent never picks work it can't start. No wasted cycles.
 
-- [Beads](https://github.com/gastownhall/beads) installed (`bd` on PATH)
-- `bd init` run in your project
-- OpenSpec installed (`npm install -g @fission-ai/openspec`)
+### Work flows across sessions
 
-## Install
+```
+# 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
+```
 
-```bash
-npm install -g spec-driven-with-beads
+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
 ```
 
-This copies the schema into OpenSpec's global schemas, making it available in any project.
+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
 
-## Usage
+Bond nothing → sequential, zero config. Bond a formula at a bond point → unlock:
 
-In your project's `openspec/config.yaml`:
+| 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. |
 
-```yaml
-schema: spec-driven-with-beads
+---
+
+## 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 use standard OpenSpec commands:
-- `/opsx:propose "my feature"`
-- `/opsx:apply` — driven by molecule step order
-- `/opsx:consolidate` — remember, compact, 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/openspec/schemas/spec-driven-with-beads/README.md

@@ -8,28 +8,48 @@ OpenSpec custom schema that uses [Beads](https://github.com/gastownhall/beads) m
 proposal → specs → design → tasks+beads → apply (via molecule) → consolidate
 ```
 
-## What makes this different
-
-Other schemas end at `archive` — move files, done. This one uses Beads' **formula + molecule** system: one `bd pour` command creates the entire dependency graph as a Beads molecule.
-
-| Phase | What happens |
-|-------|-------------|
-| `tasks` | Writes `tasks.md` + **pours a molecule** via `bd pour spec-driven-change --var name=<change>` — creates epic + 5 steps with auto-dependency chain |
-| `apply` | Works through molecule steps: `bd ready` → `bd update --claim` → code → `bd close`. Dependencies enforced by the molecule |
-| `consolidate` | Closes molecule, `bd compact`, **`bd remember`** learnings, `openspec archive`. Knowledge persists via `bd prime` |
-
 ## Molecule structure
 
 ```
 bd-xyz (epic: Spec-driven Change: my-feature)
-├── bd-xyz.1  proposal          (human)
-├── bd-xyz.2  specs             (needs: proposal)
-├── bd-xyz.3  design            (needs: specs)
-├── bd-xyz.4  implement         (needs: design)
-└── bd-xyz.5  consolidate       (human, needs: implement)
+├── bd-xyz.1  proposal                (human, needs: —)
+├── bd-xyz.2  specs                   (needs: proposal)
+├── bd-xyz.3  design                  (needs: specs)
+├── bd-xyz.4  implement               (needs: design)
+├── bd-xyz.5  verify-specs-consolidate (auto-injected by spec-compliance aspect)
+└── bd-xyz.6  consolidate             (human, needs: implement, verify-specs)
 ```
 
-No manual `bd create` × N or `bd dep add` × N — the formula defines the graph.
+One `bd pour` creates the entire graph. No manual `bd create` × N.
+
+## What makes this different
+
+Other schemas end at `archive` — knowledge dies with the session. This one closes the learning loop via `bd remember` + `bd mol distill`.
+
+### Key features
+
+| Feature | Description | Default |
+|---------|-------------|---------|
+| Mandatory deps | `needs:` in formula — `bd ready` only shows unblocked steps | Always on |
+| Spec-compliance aspect | Auto-injects "Verify specs pass" before consolidate | Always on |
+| Bond points | Compose additional behavior without forking the schema | Opt-in |
+| `bd pin` | Pin steps to specific agents for parallel work | Opt-in (bond) |
+| Async gates | Human approval, timers, CI checks | Opt-in (bond) |
+| `bd lint` | Structural validation in consolidate | Always on |
+| `bd mol squash` | Compress completed molecule to lightweight digest | Always on |
+| `bd mol distill` | Extract reusable formula from completed change | Agent discretion |
+| `bd remember` | Persist learnings across sessions via `bd prime` | Always on |
+
+### Bond points
+
+The formula defines three bond points where optional formulas attach:
+
+| Bond point | Position | Optional behavior |
+|---|---|---|
+| `parallel-execution` | After implement | Split implement into parallel sub-steps, one per capability, each pinned to a different agent. Uses `waits_for` (fan-in) to rejoin before consolidate |
+| `async-gates` | Before implement | Add human approval gates, timer delays, or GitHub CI checks. Blocks step progression until conditions are met |
+
+Bond nothing → sequential, no extra config. Bond a formula → unlock the feature.
 
 ## Requirements
 
@@ -43,8 +63,6 @@ No manual `bd create` × N or `bd dep add` × N — the formula defines the grap
 npm install -g spec-driven-with-beads
 ```
 
-This copies the schema into OpenSpec's global schemas.
-
 ## Usage
 
 In `openspec/config.yaml`:
@@ -53,12 +71,10 @@ In `openspec/config.yaml`:
 schema: spec-driven-with-beads
 ```
 
-Then standard OpenSpec commands, but with Beads molecule awareness:
+Then:
 - `/opsx:propose "my feature"`
 - `/opsx:apply` — driven by molecule step order
-- `/opsx:consolidate` — remember, compact, archive
-- `bd label list --label change:my-feature` — find past changes
-- `bd list --label status:consolidated` — search consolidated work
+- `/opsx:consolidate` — lint, squash, remember, distill, archive
 
 ## Links
 
@@ -66,4 +82,5 @@ Then standard OpenSpec commands, but with Beads molecule awareness:
 - [Beads](https://github.com/gastownhall/beads)
 - [Beads Formula docs](https://gastownhall.github.io/beads/workflows/formulas)
 - [Beads Molecule docs](https://gastownhall.github.io/beads/workflows/molecules)
+- [Beads Aspect docs](https://gastownhall.github.io/beads/workflows/formulas#aspects-cross-cutting)
 - [Community schema catalog](https://github.com/intent-driven-dev/openspec-schemas)

package/openspec/schemas/spec-driven-with-beads/schema.yaml

@@ -1,5 +1,5 @@
 name: spec-driven-with-beads
-version: 2
+version: 3
 description: >
   OpenSpec workflow powered by Beads issue tracking.
   proposal -> specs -> design -> tasks+beads -> apply (via Beads) -> consolidate.
@@ -128,6 +128,14 @@ artifacts:
       create it from the template at
       `openspec/schemas/spec-driven-with-beads/templates/spec-driven-change.formula.toml`.
 
+      Also copy the spec-compliance aspect:
+      ```
+      cp openspec/schemas/spec-driven-with-beads/templates/spec-compliance.aspect.toml .beads/formulas/spec-compliance.aspect.toml
+      ```
+
+      The aspect auto-injects a "Verify spec scenarios pass" step before
+      consolidate — no further action needed.
+
 
       **2. Pour the molecule**
 
@@ -142,28 +150,53 @@ artifacts:
 
       ```
       bd-xyz (epic: Spec-driven Change: <change-name>)
-      ├── bd-xyz.1  proposal          (human, needs: —)
-      ├── bd-xyz.2  specs             (needs: proposal)
-      ├── bd-xyz.3  design            (needs: specs)
-      ├── bd-xyz.4  implement         (needs: design)
-      └── bd-xyz.5  consolidate       (human, needs: implement)
+      ├── bd-xyz.1  proposal                (human, needs: —)
+      ├── bd-xyz.2  specs                   (needs: proposal)
+      ├── bd-xyz.3  design                  (needs: specs)
+      ├── bd-xyz.4  implement               (needs: design)
+      │   └── [on_complete → bd ready]
+      ├── bd-xyz.5  verify-specs-consolidate (auto-injected by aspect)
+      └── bd-xyz.6  consolidate             (human, needs: implement, verify-specs)
       ```
 
       The dependency chain is built into the formula — no manual `bd dep add` needed.
 
+      **Optional — parallel capability implementation (multi-agent):**
+      If the change has multiple capabilities and you have multiple agents,
+      bond a multi-agent formula at the `parallel-execution` bond point:
+      ```
+      bd mol bond mol-parallel-execution <mol-id> --ref parallel-execution
+      ```
+      This splits the implement step into N sub-steps (one per capability),
+      each pinned to a different agent with `bd pin`. All sub-steps use
+      `waits_for` (fan-in) to rejoin before consolidate.
+
+      **Optional — async gates (human approval, CI checks):**
+      Bond a gated formula at the `async-gates` bond point:
+      ```
+      bd mol bond mol-gated-approval <mol-id> --ref async-gates
+      ```
+      This adds human approval gates before implementation, timer delays,
+      or GitHub CI checks.
+
+      If you don't bond anything, the molecule runs sequential —
+      no extra configuration needed.
+
 
       **3. Label the molecule**
 
       ```
-      bd label add bd-xyz change:<change-name>
-      bd label add bd-xyz schema:spec-driven-with-beads
+      bd label add <mol-id> change:<change-name>
+      bd label add <mol-id> schema:spec-driven-with-beads
+      bd label add <mol-id> mode:sequential
       ```
+      Use `mode:parallel` if you bonded a multi-agent formula.
 
 
       **4. Set acceptance criteria for the implement step**
 
       ```
-      bd update bd-xyz.4 --acceptance "All spec scenarios pass. Tests added."
+      bd update <mol-id>.4 --acceptance "All spec scenarios pass. Tests added."
       ```
 
 
@@ -183,7 +216,7 @@ apply:
     Drive implementation through the molecule. The dependency graph
     enforces order automatically.
 
-    Workflow:
+    Sequential (default — no bonding needed):
     1. Run `bd mol list --json` to find the molecule for this change.
     2. Run `bd dep tree <mol-id>` to see the step hierarchy.
     3. Run `bd ready` — only shows steps whose needs are met.
@@ -201,11 +234,27 @@ apply:
        bd close <mol-id>.N --reason "Implemented"
        ```
     8. Run `bd ready` again — next step in the chain becomes available.
+       The `on_complete` hook on the implement step runs `bd ready` automatically.
     9. Repeat until all steps are closed.
 
+    Parallel (if bonded at parallel-execution bond point):
+    1. Run `bd dep tree <mol-id>` to see the sub-step hierarchy.
+    2. Each sub-step is pinned to an agent via `bd pin`.
+    3. Each agent claims, implements, and closes their sub-step independently.
+    4. The consolidate step waits for ALL sub-steps via `waits_for` (fan-in).
+    5. Use `bd blocked` to check if any sub-step is blocking the fan-in.
+
+    Async (if bonded at async-gates bond point):
+    1. Run `bd show <mol-id>.N` to check gate state.
+    2. For human gates: wait for approval via `bd gate approve`.
+    3. For timer gates: `bd show` shows remaining duration.
+    4. For GitHub gates: `bd show` shows CI/PR status.
+    5. Emergency override: `bd gate skip <mol-id>.N --reason "..."`.
+
     Tips:
     - `bd blocked` shows steps waiting on dependencies.
     - `bd stats` shows molecule progress.
+    - `bd show <mol-id>.N --json | jq '.gate'` shows gate details.
     - Mark tasks.md checkboxes for human readability, but the molecule
       is the source of truth.
 
@@ -221,11 +270,19 @@ consolidate:
        ```
        bd mol show <mol-id>
        ```
-    2. Run molecule compaction:
+
+    2. Run structural validation:
+       ```
+       bd lint
+       ```
+       All issues MUST pass lint. If any fail, fix them before proceeding.
+
+    3. Run molecule compaction:
        ```
        bd compact
        ```
-    3. Distill learnings from this change:
+
+    4. Distill learnings from this change:
        ```
        bd remember --key spec-driven-beads-<change-name> "Lessons from this change:
        - What unexpected problems did you encounter?
@@ -233,14 +290,27 @@ consolidate:
        - Any surprising edge cases or constraints?
        - What should the next similar change do differently?"
        ```
-    4. Label the molecule as consolidated:
+
+    5. Squash the molecule into a digest issue:
+       ```
+       bd mol squash <mol-id> --summary "Spec-driven change: <change-name>"
        ```
-       bd label add <mol-id> status:consolidated
+       This compresses the 5 child steps into a single lightweight record.
+       The molecule remains searchable but no longer clutters the issue graph.
+
+    6. Optionally extract a reusable formula (if this change
+       represents a repeatable pattern):
        ```
-    5. Run the OpenSpec archive command:
+       bd mol distill <mol-id> my-pattern
        ```
+       This creates `.beads/formulas/my-pattern.formula.toml` from the
+       completed change. Future projects can `bd pour my-pattern`.
+
+    7. Label and archive:
+       ```
+       bd label add <mol-id> status:consolidated
        openspec archive
        ```
 
     Future `bd prime` calls will inject the learnings into every session.
-    The labeled molecule remains searchable: `bd list --label status:consolidated`.
+    The squashed digest and distilled formulas persist beyond the change.

package/openspec/schemas/spec-driven-with-beads/templates/spec-compliance.aspect.toml

@@ -0,0 +1,21 @@
+formula = "spec-compliance"
+description = "Auto-inject spec compliance verification before consolidate"
+version = 1
+type = "aspect"
+
+# This aspect targets any step named "consolidate" and injects a
+# spec-verification pre-step. Applied automatically when the aspect file
+# exists in .beads/formulas/.
+
+[[advice]]
+target = "*.consolidate"
+
+[advice.before]
+id = "verify-specs-{step.id}"
+title = "Verify spec scenarios pass for {step.title}"
+needs = ["implement"]
+type = "task"
+description = >
+  Read the spec files at openspec/changes/{{name}}/specs/ and verify
+  every scenario passes against the implementation. If any scenario
+  fails, block consolidate until the issue is resolved.

package/openspec/schemas/spec-driven-with-beads/templates/spec-driven-change.formula.toml

@@ -1,6 +1,6 @@
 formula = "spec-driven-change"
 description = "OpenSpec spec-driven change with Beads"
-version = 1
+version = 2
 type = "workflow"
 
 [vars.name]
@@ -11,11 +11,35 @@ required = true
 description = "Comma-separated list of capability names"
 required = false
 
-# Phases mirror the OpenSpec schema:
-# proposal -> specs -> design -> apply -> consolidate
+# Base dependency chain: proposal -> specs -> design -> implement -> consolidate
 #
-# Human steps for proposal/specs/design require agent review.
-# Gate steps for consolidate ensure learnings are captured.
+# Bond points for optional composition:
+#   parallel-execution (after implement) — split implement into parallel sub-steps
+#     Bond a multi-agent formula here for parallel capability implementation.
+#     Each sub-step gets its own bd pin for agent assignment.
+#     Uses waits_for (fan-in) to rejoin before consolidate.
+#
+#   async-gates (before implement) — add gates for async coordination
+#     Bond a gated formula here for human approval gates, CI checks, or timers.
+#     Gates block step progression until conditions are met.
+#
+#   spec-compliance (before consolidate) — auto-injected by aspect
+#     The spec-compliance.aspect.toml injects "Verify specs pass" here.
+#     Applied automatically when the aspect is installed in .beads/formulas/.
+
+[[compose.bond_points]]
+id = "parallel-execution"
+step = "implement"
+position = "after"
+description = "Bond a multi-agent formula here to split implement into parallel sub-steps per capability"
+
+[[compose.bond_points]]
+id = "async-gates"
+step = "implement"
+position = "before"
+description = "Bond a gated formula here for human approval, CI checks, or timer gates"
+
+# Base steps
 
 [[steps]]
 id = "proposal"
@@ -40,10 +64,12 @@ id = "implement"
 title = "Implement {{name}}"
 needs = ["design"]
 description = "Implement the change per specs and design"
+[steps.on_complete]
+run = "bd ready"
 
 [[steps]]
 id = "consolidate"
 title = "Consolidate {{name}}"
 needs = ["implement"]
 type = "human"
-description = "Close issues, compact, remember learnings, archive"
+description = "Lint, squash, remember learnings, archive"

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "spec-driven-with-beads",
-  "version": "2.0.0",
-  "description": "OpenSpec custom schema using Beads (bd) for task tracking, execution, and knowledge consolidation",
-  "keywords": ["openspec", "beads", "spec-driven-development", "schema", "sdd"],
+  "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"
+  ],
   "license": "MIT",
   "author": "yoinks-yoinks",
   "homepage": "https://www.npmjs.com/package/spec-driven-with-beads",