refactor(openspec): consolidate specs by capability and device class - #260
Open
cleithner-comcast wants to merge 2 commits into
Open
refactor(openspec): consolidate specs by capability and device class#260cleithner-comcast wants to merge 2 commits into
cleithner-comcast wants to merge 2 commits into
Conversation
Reorganize openspec/specs/ from 35 fragmented, inconsistently-scoped specs down to 20 coherent capability specs, and encode a governance rule so the spec count stays bounded as SBMD drivers scale to 100+. - config.yaml: specs are per capability or per device class, never per driver; new device support is a .sbmd.js file governed by the SBMD schema validator - SBMD framework: sbmd-runtime, sbmd-mappers, sbmd-endpoint-resolution, sbmd-claiming - device classes: device-class-light, device-class-thermostat, device-class-environmental-sensor (reframed from per-driver specs) - cross-cutting: agent-skills, release-process, matter-testing Requirement meaning is preserved for consolidations; device-class reframes drop driver-file and integration-test requirements now owned by the .sbmd.js files, the SBMD validator, and the matter-testing spec. All 20 specs pass openspec validate --specs --strict.
cleithner-comcast
requested review from
kfundecmcsa,
mkkoch,
rchowdcmcsa and
tleacmcsa
as code owners
August 4, 2026 20:23
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reorganizes OpenSpec documentation to keep the spec set bounded as SBMD drivers scale, consolidating multiple fragmented specs into a smaller number of capability- and device-class–scoped specs and encoding the organization rule in openspec/config.yaml.
Changes:
- Add a governance rule: OpenSpec specs are per capability or per device class (never per concrete SBMD driver); new device support is added as
.sbmd.jsfiles governed by the SBMD schema validator. - Consolidate SBMD framework and cross-cutting specs (runtime, mappers, endpoint resolution, claiming; agent skills; release process; Matter testing) and delete the consumed source specs.
- Reframe per-driver specs into device-class contracts (
light,thermostat,environmentalSensor) and add a new OpenSpec change bundle documenting the consolidation.
Reviewed changes
Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| openspec/config.yaml | Adds spec-organization governance rules to prevent per-driver spec sprawl. |
| openspec/specs/sbmd-runtime/spec.md | Consolidates SBMD runtime/system + execution-limit requirements into a single runtime spec. |
| openspec/specs/sbmd-mappers/spec.md | Consolidates mapper prerequisite gating + seedFrom requirements. |
| openspec/specs/sbmd-endpoint-resolution/spec.md | Renames/extends endpoint resolution spec to include cluster-based fallback and binding rule. |
| openspec/specs/sbmd-claiming/spec.md | Renames/clarifies vendor/product claiming spec under SBMD naming. |
| openspec/specs/device-class-light/spec.md | Introduces a device-class contract spec for light. |
| openspec/specs/device-class-thermostat/spec.md | Reframes thermostat spec as a device-class contract and mapping description. |
| openspec/specs/device-class-environmental-sensor/spec.md | Introduces a device-class contract spec for environmentalSensor. |
| openspec/specs/matter-testing/spec.md | Consolidates Matter test infrastructure + virtual devices + sideband client + fixtures/tests into one spec. |
| openspec/specs/release-process/spec.md | Consolidates release-workflow + changelog-generation requirements into one spec. |
| openspec/specs/agent-skills/spec.md | Consolidates individual agent-skill specs into one governing spec (note: contains an SBMD-validation mismatch raised in review). |
| openspec/specs/temperature-humidity-sbmd-drivers/spec.md | Deleted (content reframed into device-class-environmental-sensor / testing moved to matter-testing). |
| openspec/specs/sbmd-v4-light-driver/spec.md | Deleted (content reframed into device-class-light). |
| openspec/specs/sbmd-system/spec.md | Deleted (content moved into sbmd-runtime). |
| openspec/specs/sbmd-seed-from-attribute/spec.md | Deleted (content moved into sbmd-mappers). |
| openspec/specs/sbmd-script-execution-limits/spec.md | Deleted (content moved into sbmd-runtime). |
| openspec/specs/python-sideband-client/spec.md | Deleted (content moved into matter-testing). |
| openspec/specs/matterjs-virtual-device-framework/spec.md | Deleted (content moved into matter-testing). |
| openspec/specs/matterjs-door-lock-device/spec.md | Deleted (content moved into matter-testing). |
| openspec/specs/matter-thermostat-testing/spec.md | Deleted (content moved into matter-testing). |
| openspec/specs/matter-test-infrastructure/spec.md | Deleted (content moved into matter-testing). |
| openspec/specs/endpoint-cluster-fallback/spec.md | Deleted (content moved into sbmd-endpoint-resolution). |
| openspec/specs/changelog-generation/spec.md | Deleted (content moved into release-process). |
| openspec/specs/agent-skill-build/spec.md | Deleted (content moved into agent-skills). |
| openspec/specs/agent-skill-debug/spec.md | Deleted (content moved into agent-skills). |
| openspec/specs/agent-skill-format-code/spec.md | Deleted (content moved into agent-skills). |
| openspec/specs/agent-skill-integration-tests/spec.md | Deleted (content moved into agent-skills). |
| openspec/specs/agent-skill-matter-devices/spec.md | Deleted (content moved into agent-skills). |
| openspec/specs/agent-skill-unit-tests/spec.md | Deleted (content moved into agent-skills). |
| openspec/specs/agent-skill-validate-sbmd/spec.md | Deleted (content moved into agent-skills). |
| openspec/changes/consolidate-specs/.openspec.yaml | Adds change metadata for the consolidation change bundle. |
| openspec/changes/consolidate-specs/proposal.md | Proposal documenting rationale, consolidation map, and non-goals. |
| openspec/changes/consolidate-specs/design.md | Design doc capturing decisions/trade-offs for the consolidation/governance model. |
| openspec/changes/consolidate-specs/tasks.md | Task checklist for governance + consolidation + validation steps. |
Comment on lines
+296
to
+312
| ### Requirement: SBMD validation skill documents spec validation | ||
| The skill SHALL explain how to validate SBMD YAML files using `scripts/ci/validate_sbmd_specs.py`. The skill SHALL document the command syntax: `python3 scripts/ci/validate_sbmd_specs.py <schema_file> <sbmd_file> [<sbmd_file> ...]`. The skill SHALL note the validator checks both YAML schema conformance and embedded JavaScript syntax. | ||
|
|
||
| #### Scenario: Agent validates SBMD specs | ||
| - **WHEN** the agent needs to validate SBMD spec files after editing | ||
| - **THEN** the skill SHALL show the validation command with the correct schema and spec file paths | ||
|
|
||
| ### Requirement: SBMD validation skill documents stub generation | ||
| The skill SHALL explain how to generate JavaScript stubs from TypeScript definitions using `scripts/ci/generate_sbmd_stubs.py`. The skill SHALL document the command syntax: `python3 scripts/ci/generate_sbmd_stubs.py <d.ts_file> <output_json>`. The skill SHALL note that stubs keep the validator in sync with TypeScript interface definitions. | ||
|
|
||
| #### Scenario: Agent regenerates SBMD stubs | ||
| - **WHEN** the agent has modified TypeScript definition files | ||
| - **THEN** the skill SHALL show the stub generation command | ||
|
|
||
| ### Requirement: SBMD validation skill documents spec file locations | ||
| The skill SHALL identify that SBMD spec files live at `core/deviceDrivers/matter/sbmd/specs/`, the schema is generated during the build, and the stubs output is at `build/sbmd-stubs.json`. The skill SHALL note that validation runs automatically during build when `BCORE_MATTER_VALIDATE_SCHEMAS=ON` (the default). | ||
|
|
Propagate the camera work from main up the stack after merging it into the base branch: - fold the new 'volatile resource mode' requirement from sbmd-v4-runtime into the consolidated sbmd-runtime spec - rename camera-session-lifecycle -> device-class-camera (Model A: camera is device type 0x0142) - keep webrtc-signaling-endpoint (protocol endpoint, separable by design) and camera-stream-reference-command (reference-app feature) as distinct capabilities rather than folding them, per one-capability-per-spec - update config.yaml governance rule to reference scripts/ci/validate_sbmd_specs.py (main consolidated the SBMD validators and removed validate_sbmd_v4_specs.py) All 23 specs pass openspec validate --specs --strict.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 35 out of 35 changed files in this pull request and generated no new comments.
Suppressed comments (3)
openspec/changes/consolidate-specs/proposal.md:7
- The proposal references
scripts/ci/validate_sbmd_v4_specs.py, but other updated docs in this PR referencescripts/ci/validate_sbmd_specs.pyas the validator (e.g.,openspec/config.yaml). Please standardize on the correct validator script name/path across all docs to avoid sending readers to a non-existent or outdated tool.
- **Governance rule (the durable fix):** encode in `openspec/config.yaml` that OpenSpec specs are authored per capability or per device class — never per concrete driver. A new supported device is added as a `.sbmd.js` driver file governed by the SBMD schema validator (`scripts/ci/validate_sbmd_v4_specs.py`), not as a new spec. This keeps the spec count bounded (~15–25) as drivers scale to 100+.
openspec/changes/consolidate-specs/tasks.md:10
- The task list claims several spec renames/creations (e.g.,
sbmd-claiming,sbmd-mappers,sbmd-endpoint-resolution,release-process), but the diffs shown keep the original spec directory IDs (e.g.,openspec/specs/vendor-product-claiming/,openspec/specs/sbmd-resource-prerequisites/,openspec/specs/device-type-endpoint-resolution/,openspec/specs/release-workflow/). If the intent is to rename spec IDs, the directories should be renamed to match; otherwise the tasks/proposal should be adjusted to reflect that only the titles changed.
- [x] 2.1 Create `sbmd-runtime` from `sbmd-system` + `sbmd-v4-runtime` + `sbmd-script-execution-limits`
- [x] 2.2 Create `sbmd-mappers` from `sbmd-resource-prerequisites` + `sbmd-seed-from-attribute`
- [x] 2.3 Create `sbmd-endpoint-resolution` from `device-type-endpoint-resolution` + `endpoint-cluster-fallback`
- [x] 2.4 Rename `vendor-product-claiming` to `sbmd-claiming`
openspec/changes/consolidate-specs/tasks.md:21
- The task list claims several spec renames/creations (e.g.,
sbmd-claiming,sbmd-mappers,sbmd-endpoint-resolution,release-process), but the diffs shown keep the original spec directory IDs (e.g.,openspec/specs/vendor-product-claiming/,openspec/specs/sbmd-resource-prerequisites/,openspec/specs/device-type-endpoint-resolution/,openspec/specs/release-workflow/). If the intent is to rename spec IDs, the directories should be renamed to match; otherwise the tasks/proposal should be adjusted to reflect that only the titles changed.
- [x] 4.2 Create `release-process` from `changelog-generation` + `release-workflow`
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reorganize openspec/specs/ from 35 fragmented, inconsistently-scoped specs down to 20 coherent capability specs, and encode a governance rule so the spec count stays bounded as SBMD drivers scale to 100+.
Requirement meaning is preserved for consolidations; device-class reframes drop driver-file and integration-test requirements now owned by the .sbmd.js files, the SBMD validator, and the matter-testing spec. All 20 specs pass openspec validate --specs --strict.
Stack created with GitHub Stacks CLI • Give Feedback 💬