feat: add spec-driven-with-beads schema

openspec/schemas/spec-driven-with-beads/README.md

@@ -0,0 +1,39 @@
+# spec-driven-with-beads
+
+OpenSpec workflow that uses Beads (`bd`) for task tracking and execution instead of flat task lists.
+
+## Workflow
+
+```
+proposal → specs → design → tasks+beads → apply (via Beads) → archive
+```
+
+| 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` |
+| `archive` | moves to archive | `bd compact` on closed issues |
+
+## Why Beads?
+
+- **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
+
+## 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
+
+## Activation
+
+In `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven-with-beads
+```

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

@@ -0,0 +1,217 @@
+name: spec-driven-with-beads
+version: 1
+description: >
+  OpenSpec workflow powered by Beads issue tracking.
+  proposal -> specs -> design -> tasks+beads -> apply (via Beads) -> archive (compact).
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: >
+      Create the proposal document that establishes WHY this change is needed.
+
+
+      Sections:
+
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does
+      this solve? Why now?
+
+      - **What Changes**: Bullet list of changes. Be specific about new
+      capabilities, modifications, or removals. Mark breaking changes with
+      **BREAKING**.
+
+      - **New Capabilities**: List capabilities being introduced. Each becomes
+      a new `specs/<name>/spec.md`. Use kebab-case names.
+
+      - **Modified Capabilities**: List existing capabilities whose
+      REQUIREMENTS are changing. Check `openspec/specs/` for existing spec
+      names. Leave empty if no requirement changes.
+
+      - **Impact**: Affected code, APIs, dependencies, or systems.
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract
+      between proposal and specs phases.
+
+      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+      implementation details belong in design.md.
+
+      This is the foundation — specs, design, and tasks all build on this.
+    requires: []
+
+  - id: specs
+    generates: specs/**/*.md
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: >
+      Create specification files that define WHAT the system should do.
+
+      Create one spec file per capability listed in the proposal's Capabilities
+      section.
+
+      - New capabilities: use the exact kebab-case name from the proposal
+      (specs/<capability>/spec.md).
+
+      - Modified capabilities: use the existing spec folder name from
+      openspec/specs/<capability>/ when creating the delta spec at
+      specs/<capability>/spec.md.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior — MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features — MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only — use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in openspec/specs/<capability>/spec.md
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      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:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: >
+      Create the design document that explains HOW to implement the change.
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Background, current state, constraints, stakeholders
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Outstanding decisions or unknowns to resolve
+
+      Focus on architecture and approach, not line-by-line implementation.
+      Reference the proposal for motivation and specs for requirements.
+
+      Good design docs explain the "why" behind technical decisions.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks. Also seeds Beads issues.
+    template: tasks.md
+    instruction: >
+      Create the task list that breaks down the implementation work AND seed
+      corresponding issues in Beads.
+
+
+      **IMPORTANT: Follow the template below exactly.**
+
+
+      Guidelines:
+
+      - Group related tasks under ## numbered headings
+
+      - 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:
+
+      ```
+
+      ## 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
+
+      ```
+
+
+      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.
+
+
+      **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:
+
+      ```
+      bd create "X.Y Task description" -t task -p 1
+      ```
+
+      Then link dependencies using `bd dep add <child> <parent>`.
+
+      Use `bd ready` to verify the task list is properly seeded.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires:
+    - 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.

openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md

@@ -0,0 +1,86 @@
+# 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.
+
+## Workflow
+
+```
+proposal → specs → design → tasks+beads → apply (via molecule) → consolidate
+```
+
+## Molecule structure
+
+```
+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
+
+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 your project
+- OpenSpec installed (`npm install -g @fission-ai/openspec`)
+
+## Install
+
+```bash
+npm install -g spec-driven-with-beads
+```
+
+## 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)