spec-driven-with-beads 1.1.5 → 2.0.0

package/README.md

@@ -1,24 +1,29 @@
 # 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.
 
-This schema adds **`consolidate`** — a fourth action that closes the learning loop:
+This schema uses Beads' **formula + molecule** system. One `bd pour` command creates the entire dependency graph:
 
-| 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` |
+```
+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.
 
-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.
+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.
 
@@ -46,11 +51,13 @@ schema: spec-driven-with-beads
 
 Then use standard OpenSpec commands:
 - `/opsx:propose "my feature"`
-- `/opsx:apply`
-- `/opsx:consolidate` — closes issues, compacts, remembers, archives
+- `/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)
+- [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,69 @@
 # 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` |
+## What makes this different
 
-## Why Beads?
+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.
 
-- **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
+| 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)
+```
+
+No manual `bd create` × N or `bd dep add` × N — the formula defines the graph.
 
 ## 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
 
-## Activation
+```bash
+npm install -g spec-driven-with-beads
+```
+
+This copies the schema into OpenSpec's global schemas.
+
+## Usage
 
 In `openspec/config.yaml`:
 
 ```yaml
 schema: spec-driven-with-beads
 ```
+
+Then standard OpenSpec commands, but with Beads molecule awareness:
+- `/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
+
+## 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/schema.yaml

@@ -1,5 +1,5 @@
 name: spec-driven-with-beads
-version: 1
+version: 2
 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,63 @@ 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
+      **2. Pour the molecule**
 
-      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
-
-      - Tasks should be small enough to complete in one session
-
-      - Order tasks by dependency (what must be done first?)
-
-
-      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
-
-      ## 2. Core Implementation
-
-      - [ ] 2.1 Implement data export function
-
-      - [ ] 2.2 Add CSV formatting utilities
+      This creates a molecule (parent epic + 5 child steps) with proper
+      `needs` dependencies:
 
+      ```
+      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)
       ```
 
+      The dependency chain is built into the formula — no manual `bd dep add` 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 bd-xyz change:<change-name>
+      bd label add bd-xyz schema:spec-driven-with-beads
+      ```
 
-      **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 bd-xyz.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 +180,52 @@ apply:
     - tasks
   tracks: tasks.md
   instruction: |
-    Use Beads to drive implementation, not tasks.md directly.
+    Drive implementation through the molecule. The dependency graph
+    enforces order automatically.
 
     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.
+    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.
+    9. Repeat until all steps are closed.
 
-    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`.
+    Tips:
+    - `bd blocked` shows steps waiting on dependencies.
+    - `bd stats` shows molecule progress.
+    - Mark tasks.md checkboxes for human readability, but the molecule
+      is the source of truth.
 
-    Pause if you hit blockers or need clarification. Use `bd show <id>` to
-    inspect task details, and `bd update <id>` to add notes.
+    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. 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:
+    1. Verify all steps are closed:
+       ```
+       bd mol show <mol-id>
+       ```
+    2. Run molecule compaction:
+       ```
+       bd compact
+       ```
+    3. 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 +233,14 @@ 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)
+    4. Label the molecule as consolidated:
+       ```
+       bd label add <mol-id> status:consolidated
+       ```
+    5. Run the OpenSpec archive command:
+       ```
+       openspec archive
+       ```
 
-    This ensures knowledge persists across sessions — future `bd prime` calls will inject these learnings.
+    Future `bd prime` calls will inject the learnings into every session.
+    The labeled molecule remains searchable: `bd list --label status:consolidated`.

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

@@ -0,0 +1,49 @@
+formula = "spec-driven-change"
+description = "OpenSpec spec-driven change with Beads"
+version = 1
+type = "workflow"
+
+[vars.name]
+description = "Change name (kebab-case)"
+required = true
+
+[vars.capabilities]
+description = "Comma-separated list of capability names"
+required = false
+
+# Phases mirror the OpenSpec schema:
+# proposal -> specs -> design -> apply -> consolidate
+#
+# Human steps for proposal/specs/design require agent review.
+# Gate steps for consolidate ensure learnings are captured.
+
+[[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]]
+id = "consolidate"
+title = "Consolidate {{name}}"
+needs = ["implement"]
+type = "human"
+description = "Close issues, compact, remember learnings, archive"

package/package.json

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