spec-driven-with-beads 1.1.5 → 3.0.0

package/README.md

@@ -1,26 +1,25 @@
 # spec-driven-with-beads
 
-OpenSpec custom schema that uses [Beads](https://github.com/gastownhall/beads) (`bd`) for task tracking, execution, and **durable knowledge retention** across sessions.
+OpenSpec custom schema that uses [Beads](https://github.com/gastownhall/beads) molecules for task tracking, execution, and durable knowledge retention across sessions.
 
 ```
-proposal → specs → design → tasks+beads → apply (via Beads) → consolidate
+proposal → specs → design → tasks+beads → apply (via molecule) → consolidate
 ```
 
 ## 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 adds **`consolidate`** — a fourth action that closes the learning loop:
+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.
 
-| Phase | What happens |
-|-------|-------------|
-| `tasks` | Writes `tasks.md` AND seeds Beads via `bd create` + `bd dep add` |
-| `apply` | Drives work through `bd ready` → `bd update --claim` → code → `bd close` |
-| **`consolidate`** | `bd close` remaining → **`bd compact`** → **`bd remember`** → `openspec archive` |
+### Key features
 
-The key: **`bd remember`** persists lessons, decisions, and edge cases as durable memories. Every future `bd prime` call injects them into the agent's context. Next session, the agent knows what the last change taught you — 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
 
@@ -34,23 +33,23 @@ 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`
-- `/opsx:consolidate` — closes issues, compacts, remembers, archives
+- `/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)
+- [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

@@ -1,39 +1,86 @@
 # spec-driven-with-beads
 
-OpenSpec workflow that uses Beads (`bd`) for task tracking and execution instead of flat task lists.
+OpenSpec custom schema that uses [Beads](https://github.com/gastownhall/beads) molecules for task tracking, execution, and durable knowledge retention across sessions.
 
 ## Workflow
 
 ```
-proposal → specs → design → tasks+beads → apply (via Beads) → consolidate
+proposal → specs → design → tasks+beads → apply (via molecule) → consolidate
 ```
 
-| Phase | Artifact | Beads interaction |
-|-------|----------|-------------------|
-| `propose` | `proposal.md` | None |
-| `specs` | `specs/**/*.md` | None |
-| `design` | `design.md` | None |
-| `tasks` | `tasks.md` + seeds Beads | `bd create` for each task, `bd dep add` for dependencies |
-| `apply` | (tracks via Beads) | `bd ready` → `bd update --claim` → code → `bd close` |
-| `consolidate` | (wraps up) | `bd close` remaining → `bd compact` → `bd remember` learnings → `openspec archive` |
+## Molecule structure
 
-## Why Beads?
+```
+bd-xyz (epic: Spec-driven Change: my-feature)
+├── 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)
+```
+
+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
 
-- **Context efficiency** — agent queries `bd ready` for next task instead of re-reading tasks.md
-- **Dependency tracking** — `bd dep add` makes blockers explicit
-- **Persistence** — survive across sessions, no context loss
-- **Progress visibility** — `bd stats`, `bd dep tree` show real status
+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
 
 - [Beads](https://github.com/gastownhall/beads) installed (`bd` on PATH)
-- `bd init` run in the project
-- Beads MCP server optional but recommended for richer integration
+- `bd init` run in your project
+- OpenSpec installed (`npm install -g @fission-ai/openspec`)
+
+## Install
+
+```bash
+npm install -g spec-driven-with-beads
+```
 
-## Activation
+## Usage
 
 In `openspec/config.yaml`:
 
 ```yaml
 schema: spec-driven-with-beads
 ```
+
+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)
+- [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: 1
+version: 3
 description: >
   OpenSpec workflow powered by Beads issue tracking.
   proposal -> specs -> design -> tasks+beads -> apply (via Beads) -> consolidate.
@@ -79,27 +79,6 @@ artifacts:
       Common pitfall: Using MODIFIED with partial content loses detail at archive time.
       If adding new concerns without changing existing behavior, use ADDED instead.
 
-      Example:
-
-      ```
-      ## ADDED Requirements
-
-      ### Requirement: User can export data
-
-      The system SHALL allow users to export their data in CSV format.
-
-      #### Scenario: Successful export
-
-      - **WHEN** user clicks "Export" button
-      - **THEN** system downloads a CSV file with all user data
-
-      ## REMOVED Requirements
-
-      ### Requirement: Legacy export
-
-      **Reason**: Replaced by new export system
-      **Migration**: Use new export endpoint at /api/v2/export
-      ```
 
       Specs should be testable — each scenario is a potential test case.
     requires:
@@ -135,63 +114,96 @@ artifacts:
 
   - id: tasks
     generates: tasks.md
-    description: Implementation checklist with trackable tasks. Also seeds Beads issues.
+    description: >
+      Implementation checklist. Seeds Beads molecule via formula pour —
+      one command creates the entire dependency graph.
     template: tasks.md
     instruction: >
-      Create the task list that breaks down the implementation work AND seed
-      corresponding issues in Beads.
+      Create the task list AND seed Beads using the formula + molecule system.
 
 
-      **IMPORTANT: Follow the template below exactly.**
+      **1. Ensure the spec-driven-change formula exists**
 
+      If `.beads/formulas/spec-driven-change.formula.toml` does not exist,
+      create it from the template at
+      `openspec/schemas/spec-driven-with-beads/templates/spec-driven-change.formula.toml`.
 
-      Guidelines:
-
-      - Group related tasks under ## numbered headings
-
-      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      Also copy the spec-compliance aspect:
+      ```
+      cp openspec/schemas/spec-driven-with-beads/templates/spec-compliance.aspect.toml .beads/formulas/spec-compliance.aspect.toml
+      ```
 
-      - Tasks should be small enough to complete in one session
+      The aspect auto-injects a "Verify spec scenarios pass" step before
+      consolidate — no further action needed.
 
-      - Order tasks by dependency (what must be done first?)
 
+      **2. Pour the molecule**
 
-      Example:
+      Run:
 
+      ```
+      bd pour spec-driven-change --var name=<change-name>
       ```
 
-      ## 1. Setup
-
-      - [ ] 1.1 Create new module structure
-
-      - [ ] 1.2 Add dependencies to package.json
+      This creates a molecule (parent epic + 5 child steps) with proper
+      `needs` dependencies:
 
-      ## 2. Core Implementation
+      ```
+      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)
+      │   └── [on_complete → bd ready]
+      ├── bd-xyz.5  verify-specs-consolidate (auto-injected by aspect)
+      └── bd-xyz.6  consolidate             (human, needs: implement, verify-specs)
+      ```
 
-      - [ ] 2.1 Implement data export function
+      The dependency chain is built into the formula — no manual `bd dep add` needed.
 
-      - [ ] 2.2 Add CSV formatting utilities
+      **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.
 
-      Reference specs for what needs to be built, design for how to build it.
 
-      Each task should be verifiable — you know when it's done.
+      **3. Label the molecule**
 
+      ```
+      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.
 
-      **After writing tasks.md, seed Beads:**
 
-      Run `bd create "Spec-driven Change: <change-name>" -t epic -p 1` for the
-      parent epic, then for each task run:
+      **4. Set acceptance criteria for the implement step**
 
       ```
-      bd create "X.Y Task description" -t task -p 1
+      bd update <mol-id>.4 --acceptance "All spec scenarios pass. Tests added."
       ```
 
-      Then link dependencies using `bd dep add <child> <parent>`.
 
-      Use `bd ready` to verify the task list is properly seeded.
+      **5. Write tasks.md**
+
+      Write the standard OpenSpec tasks.md for human readability.
+      The molecule is the source of truth; tasks.md is a view.
     requires:
       - specs
       - design
@@ -201,30 +213,76 @@ apply:
     - tasks
   tracks: tasks.md
   instruction: |
-    Use Beads to drive implementation, not tasks.md directly.
-
-    Workflow:
-    1. Run `bd ready` to see the next unblocked task.
-    2. Pick the highest priority task and run `bd update <id> --claim`.
-    3. Read specs/design for context, implement the code.
-    4. Run `bd close <id> --reason "Implemented"`.
-    5. Repeat from step 1 until `bd ready` returns nothing.
-
-    Mark tasks.md checkboxes as you go for a human-readable view, but
-    Beads is the source of truth for task state. Do not skip `bd close`.
-
-    Pause if you hit blockers or need clarification. Use `bd show <id>` to
-    inspect task details, and `bd update <id>` to add notes.
+    Drive implementation through the molecule. The dependency graph
+    enforces order automatically.
+
+    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.
+    4. For the next ready step, claim it:
+       ```
+       bd update <mol-id>.N --claim
+       ```
+    5. Read specs/design for context, implement the code.
+    6. Run acceptance criteria check if applicable:
+       ```
+       bd show <mol-id>.N  # view acceptance criteria
+       ```
+    7. Close the step:
+       ```
+       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.
+
+    Pause if you hit blockers or need clarification.
 
 consolidate:
   requires:
     - apply
   instruction: |
-    All tasks are complete. Run consolidate to close the loop:
+    Close the molecule and persist learnings.
+
+    1. Verify all steps are closed:
+       ```
+       bd mol show <mol-id>
+       ```
+
+    2. Run structural validation:
+       ```
+       bd lint
+       ```
+       All issues MUST pass lint. If any fail, fix them before proceeding.
+
+    3. Run molecule compaction:
+       ```
+       bd compact
+       ```
 
-    1. Close any remaining open Beads issues: `bd close <id1> <id2> ...`
-    2. Compact old closed issues: `bd compact`
-    3. Distill learnings from this change and persist them:
+    4. Distill learnings from this change:
        ```
        bd remember --key spec-driven-beads-<change-name> "Lessons from this change:
        - What unexpected problems did you encounter?
@@ -232,6 +290,27 @@ consolidate:
        - Any surprising edge cases or constraints?
        - What should the next similar change do differently?"
        ```
-    4. Run the OpenSpec archive command: `openspec archive` (moves change folder, updates source specs)
 
-    This ensures knowledge persists across sessions — future `bd prime` calls will inject these learnings.
+    5. Squash the molecule into a digest issue:
+       ```
+       bd mol squash <mol-id> --summary "Spec-driven change: <change-name>"
+       ```
+       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):
+       ```
+       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 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

@@ -0,0 +1,75 @@
+formula = "spec-driven-change"
+description = "OpenSpec spec-driven change with Beads"
+version = 2
+type = "workflow"
+
+[vars.name]
+description = "Change name (kebab-case)"
+required = true
+
+[vars.capabilities]
+description = "Comma-separated list of capability names"
+required = false
+
+# Base dependency chain: proposal -> specs -> design -> implement -> consolidate
+#
+# 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"
+title = "Review proposal for {{name}}"
+type = "human"
+description = "Review the proposal document at openspec/changes/{{name}}/proposal.md"
+
+[[steps]]
+id = "specs"
+title = "Write specs for {{name}}"
+needs = ["proposal"]
+description = "Create spec files under openspec/changes/{{name}}/specs/"
+
+[[steps]]
+id = "design"
+title = "Design {{name}}"
+needs = ["specs"]
+description = "Write design document at openspec/changes/{{name}}/design.md"
+
+[[steps]]
+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 = "Lint, squash, remember learnings, archive"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-driven-with-beads",
-  "version": "1.1.5",
-  "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",