From 8bc44c415929a0ae5dd8cb015bf318a94a274d4b Mon Sep 17 00:00:00 2001 From: yoinks-yoinks Date: Sun, 21 Jun 2026 16:39:31 +0500 Subject: [PATCH 1/4] feat: add spec-driven-with-beads schema --- .../schemas/spec-driven-with-beads/README.md | 39 ++++ .../spec-driven-with-beads/schema.yaml | 217 ++++++++++++++++++ .../templates/design.md | 19 ++ .../templates/proposal.md | 23 ++ .../spec-driven-with-beads/templates/spec.md | 8 + .../spec-driven-with-beads/templates/tasks.md | 9 + 6 files changed, 315 insertions(+) create mode 100644 openspec/schemas/spec-driven-with-beads/README.md create mode 100644 openspec/schemas/spec-driven-with-beads/schema.yaml create mode 100644 openspec/schemas/spec-driven-with-beads/templates/design.md create mode 100644 openspec/schemas/spec-driven-with-beads/templates/proposal.md create mode 100644 openspec/schemas/spec-driven-with-beads/templates/spec.md create mode 100644 openspec/schemas/spec-driven-with-beads/templates/tasks.md diff --git a/openspec/schemas/spec-driven-with-beads/README.md b/openspec/schemas/spec-driven-with-beads/README.md new file mode 100644 index 0000000..38e4865 --- /dev/null +++ b/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 +``` diff --git a/openspec/schemas/spec-driven-with-beads/schema.yaml b/openspec/schemas/spec-driven-with-beads/schema.yaml new file mode 100644 index 0000000..b0d20e0 --- /dev/null +++ b/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//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//spec.md). + + - Modified capabilities: use the existing spec folder name from + openspec/specs// when creating the delta spec at + specs//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: ` followed by description + - Use SHALL/MUST for normative requirements (avoid should/may) + - Each scenario: `#### Scenario: ` 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//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: " -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 `. + + 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 --claim`. + 3. Read specs/design for context, implement the code. + 4. Run `bd close --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 ` to + inspect task details, and `bd update ` to add notes. diff --git a/openspec/schemas/spec-driven-with-beads/templates/design.md b/openspec/schemas/spec-driven-with-beads/templates/design.md new file mode 100644 index 0000000..4ab5bd8 --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/templates/design.md @@ -0,0 +1,19 @@ +## Context + + + +## Goals / Non-Goals + +**Goals:** + + +**Non-Goals:** + + +## Decisions + + + +## Risks / Trade-offs + + diff --git a/openspec/schemas/spec-driven-with-beads/templates/proposal.md b/openspec/schemas/spec-driven-with-beads/templates/proposal.md new file mode 100644 index 0000000..c79b85d --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/templates/proposal.md @@ -0,0 +1,23 @@ +## Why + + + +## What Changes + + + +## Capabilities + +### New Capabilities + +- ``: + +### Modified Capabilities + +- ``: + +## Impact + + diff --git a/openspec/schemas/spec-driven-with-beads/templates/spec.md b/openspec/schemas/spec-driven-with-beads/templates/spec.md new file mode 100644 index 0000000..095d711 --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/templates/spec.md @@ -0,0 +1,8 @@ +## ADDED Requirements + +### Requirement: + + +#### Scenario: +- **WHEN** +- **THEN** diff --git a/openspec/schemas/spec-driven-with-beads/templates/tasks.md b/openspec/schemas/spec-driven-with-beads/templates/tasks.md new file mode 100644 index 0000000..88ce51e --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/templates/tasks.md @@ -0,0 +1,9 @@ +## 1. + +- [ ] 1.1 +- [ ] 1.2 + +## 2. + +- [ ] 2.1 +- [ ] 2.2 From b32528950e7ab2aea6e0f95593dd3d292d4cc999 Mon Sep 17 00:00:00 2001 From: yoinks-yoinks Date: Sun, 21 Jun 2026 17:19:20 +0500 Subject: [PATCH 2/4] feat: rename archive to consolidate, add bd remember to close learning loop --- .../spec-driven-with-beads/README.md | 39 +++ .../spec-driven-with-beads/schema.yaml | 237 ++++++++++++++++++ .../templates/design.md | 19 ++ .../templates/proposal.md | 23 ++ .../spec-driven-with-beads/templates/spec.md | 8 + .../spec-driven-with-beads/templates/tasks.md | 9 + 6 files changed, 335 insertions(+) create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/design.md create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/proposal.md create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec.md create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/tasks.md diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md new file mode 100644 index 0000000..dd57fd3 --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/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) → 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` | + +## 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 +``` diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml new file mode 100644 index 0000000..9514258 --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml @@ -0,0 +1,237 @@ +name: spec-driven-with-beads +version: 1 +description: > + OpenSpec workflow powered by Beads issue tracking. + proposal -> specs -> design -> tasks+beads -> apply (via Beads) -> consolidate. + +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//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//spec.md). + + - Modified capabilities: use the existing spec folder name from + openspec/specs// when creating the delta spec at + specs//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: ` followed by description + - Use SHALL/MUST for normative requirements (avoid should/may) + - Each scenario: `#### Scenario: ` 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//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: " -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 `. + + 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 --claim`. + 3. Read specs/design for context, implement the code. + 4. Run `bd close --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 ` to + inspect task details, and `bd update ` to add notes. + +consolidate: + requires: + - apply + instruction: | + All tasks are complete. Run consolidate to close the loop: + + 1. Close any remaining open Beads issues: `bd close ...` + 2. Compact old closed issues: `bd compact` + 3. Distill learnings from this change and persist them: + ``` + bd remember --key spec-driven-beads- "Lessons from this change: + - What unexpected problems did you encounter? + - What decisions turned out well or poorly? + - 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. diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/design.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/design.md new file mode 100644 index 0000000..4ab5bd8 --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/design.md @@ -0,0 +1,19 @@ +## Context + + + +## Goals / Non-Goals + +**Goals:** + + +**Non-Goals:** + + +## Decisions + + + +## Risks / Trade-offs + + diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/proposal.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/proposal.md new file mode 100644 index 0000000..c79b85d --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/proposal.md @@ -0,0 +1,23 @@ +## Why + + + +## What Changes + + + +## Capabilities + +### New Capabilities + +- ``: + +### Modified Capabilities + +- ``: + +## Impact + + diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec.md new file mode 100644 index 0000000..095d711 --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec.md @@ -0,0 +1,8 @@ +## ADDED Requirements + +### Requirement: + + +#### Scenario: +- **WHEN** +- **THEN** diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/tasks.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/tasks.md new file mode 100644 index 0000000..88ce51e --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/tasks.md @@ -0,0 +1,9 @@ +## 1. + +- [ ] 1.1 +- [ ] 1.2 + +## 2. + +- [ ] 2.1 +- [ ] 2.2 From a1e0d4b0d8bdc0729be89a34d0b6fae512b5c356 Mon Sep 17 00:00:00 2001 From: yoinks-yoinks Date: Sun, 21 Jun 2026 17:43:10 +0500 Subject: [PATCH 3/4] feat: v2 - use beads formula+molecule instead of manual task creation --- .../spec-driven-with-beads/README.md | 66 +++++--- .../spec-driven-with-beads/schema.yaml | 151 ++++++++++-------- .../templates/spec-driven-change.formula.toml | 49 ++++++ 3 files changed, 177 insertions(+), 89 deletions(-) create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-driven-change.formula.toml diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md index dd57fd3..e07cc1b 100644 --- a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md +++ b/openspec/schemas/spec-driven-with-beads/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=` — 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) diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml index 9514258..0c56cf7 100644 --- a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml +++ b/openspec/schemas/spec-driven-with-beads/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= ``` - ## 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: ) + ├── 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: + bd label add bd-xyz schema:spec-driven-with-beads + ``` - **After writing tasks.md, seed Beads:** - Run `bd create "Spec-driven Change: " -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 `. - 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 --claim`. - 3. Read specs/design for context, implement the code. - 4. Run `bd close --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 ` 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 .N --claim + ``` + 5. Read specs/design for context, implement the code. + 6. Run acceptance criteria check if applicable: + ``` + bd show .N # view acceptance criteria + ``` + 7. Close the step: + ``` + bd close .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 ` to - inspect task details, and `bd update ` 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 ...` - 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 + ``` + 2. Run molecule compaction: + ``` + bd compact + ``` + 3. Distill learnings from this change: ``` bd remember --key spec-driven-beads- "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 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`. diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-driven-change.formula.toml b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-driven-change.formula.toml new file mode 100644 index 0000000..0c8102a --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/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" From 86c8e1ff8f8f1ae8b75e18e4b51edd1b8b1930d7 Mon Sep 17 00:00:00 2001 From: yoinks-yoinks Date: Sun, 21 Jun 2026 18:43:33 +0500 Subject: [PATCH 4/4] feat: v3 - bond points, aspects, lint, squash, distill --- .../spec-driven-with-beads/README.md | 61 +++++++---- .../spec-driven-with-beads/schema.yaml | 102 +++++++++++++++--- .../templates/spec-compliance.aspect.toml | 21 ++++ .../templates/spec-driven-change.formula.toml | 38 +++++-- 4 files changed, 178 insertions(+), 44 deletions(-) create mode 100644 openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-compliance.aspect.toml diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md index e07cc1b..0e987a5 100644 --- a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/README.md +++ b/openspec/schemas/spec-driven-with-beads/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=` — 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) diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml index 0c56cf7..408f68f 100644 --- a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/schema.yaml +++ b/openspec/schemas/spec-driven-with-beads/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: ) - ├── 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 --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 --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: - bd label add bd-xyz schema:spec-driven-with-beads + bd label add change: + bd label add schema:spec-driven-with-beads + bd label add 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 .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 ` to see the step hierarchy. 3. Run `bd ready` — only shows steps whose needs are met. @@ -201,11 +234,27 @@ apply: bd close .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 ` 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 .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 .N --reason "..."`. + Tips: - `bd blocked` shows steps waiting on dependencies. - `bd stats` shows molecule progress. + - `bd show .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 ``` - 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- "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 --summary "Spec-driven change: " ``` - bd label add 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 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 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. diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-compliance.aspect.toml b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-compliance.aspect.toml new file mode 100644 index 0000000..bc61ebe --- /dev/null +++ b/openspec/schemas/spec-driven-with-beads/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. diff --git a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-driven-change.formula.toml b/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-driven-change.formula.toml index 0c8102a..8e8bb39 100644 --- a/openspec/schemas/spec-driven-with-beads/spec-driven-with-beads/templates/spec-driven-change.formula.toml +++ b/openspec/schemas/spec-driven-with-beads/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"