spec-driven-with-beads 2.0.0 → 3.0.0

package/README.md

@@ -8,24 +8,18 @@ proposal → specs → design → tasks+beads → apply (via molecule) → conso
 
 ## What makes this different
 
-Other spec-driven schemas end at `archive` — move files, update specs, done. Knowledge dies with the session.
+Other spec-driven schemas end at `archive` — move files, done. Knowledge dies with the session.
 
-This schema uses Beads' **formula + molecule** system. One `bd pour` command creates the entire dependency graph:
+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.
 
-```
-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)
-```
-
-No manual `bd create` × N. No manual `bd dep add` × N. The formula defines the graph.
+### Key features
 
-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.
-
-No other OpenSpec schema does this. No task tracker (Linear, GitHub Issues, Jira) has a `bd remember` equivalent.
+- **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.
 
 ## Requirements
 
@@ -39,20 +33,18 @@ No other OpenSpec schema does this. No task tracker (Linear, GitHub Issues, Jira
 npm install -g spec-driven-with-beads
 ```
 
-This copies the schema into OpenSpec's global schemas, making it available in any project.
-
 ## Usage
 
-In your project's `openspec/config.yaml`:
+In `openspec/config.yaml`:
 
 ```yaml
 schema: spec-driven-with-beads
 ```
 
-Then use standard OpenSpec commands:
+Then:
 - `/opsx:propose "my feature"`
 - `/opsx:apply` — driven by molecule step order
-- `/opsx:consolidate` — remember, compact, archive
+- `/opsx:consolidate` — lint, squash, remember, distill, archive
 
 ## Links
 

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,7 +1,7 @@
 {
   "name": "spec-driven-with-beads",
-  "version": "2.0.0",
-  "description": "OpenSpec custom schema using Beads (bd) for task tracking, execution, and knowledge consolidation",
+  "version": "3.0.0",
+  "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",