Specs are written for two audiences and only one of them enjoys reading twelve SHALL statements in a row. A diagram would help the humans.
Today
Diagrams are possible, but only as folklore — nothing ships with them and nothing knows about them:
mermaid appears zero times in the repo: not in schemas/spec-driven/templates/*.md, not in validation, not in docs.
- You can ask for one per project via
rules in openspec/config.yaml, or bake it in with openspec schema fork spec-driven my-workflow.
- Nothing can check it. Artifact completion is file existence only (
artifactOutputExists, src/core/artifact-graph/outputs.ts:40-42), and docs/customization.md:121 says plainly that rules/context are "not an enforceable check."
So OpenSpec can nag for a diagram; it can never notice one is missing.
The ask
Make diagrams a supported option rather than something each user rediscovers.
Surgical PR
Scope this to guidance, not enforcement:
- Add an optional diagram line to the
design artifact instruction in schemas/spec-driven/schema.yaml — a mermaid block for component/data flow when the change spans more than one system, skipped when it wouldn't earn its place.
- Add a short Diagrams section to
docs/customization.md showing the two-line rules: recipe and the fork path.
- Nothing in
src/core/validation/ changes.
Golden-hash caveat: touching templates or schema text means pnpm build && pnpm regen:parity-hashes, then re-run the parity tests.
Open questions
- Default or opt-in? Ship diagram guidance in the stock
design.md, or leave it to rules and only document it? Every user inherits the default, and a mandatory-feeling diagram in a two-file change is worse than none.
specs too, or design only? Delta specs are consumed by both agents and archive/sync; a mermaid block in a MODIFIED requirement is more format surface than it looks.
- Content checks at all? "Has a diagram" is the first thing anyone would want validated, and validation is existence-only by design. Worth deciding whether that line stays where it is.
Specs are written for two audiences and only one of them enjoys reading twelve
SHALLstatements in a row. A diagram would help the humans.Today
Diagrams are possible, but only as folklore — nothing ships with them and nothing knows about them:
mermaidappears zero times in the repo: not inschemas/spec-driven/templates/*.md, not in validation, not in docs.rulesinopenspec/config.yaml, or bake it in withopenspec schema fork spec-driven my-workflow.artifactOutputExists,src/core/artifact-graph/outputs.ts:40-42), anddocs/customization.md:121says plainly thatrules/contextare "not an enforceable check."So OpenSpec can nag for a diagram; it can never notice one is missing.
The ask
Make diagrams a supported option rather than something each user rediscovers.
Surgical PR
Scope this to guidance, not enforcement:
designartifact instruction inschemas/spec-driven/schema.yaml— a mermaid block for component/data flow when the change spans more than one system, skipped when it wouldn't earn its place.docs/customization.mdshowing the two-linerules:recipe and the fork path.src/core/validation/changes.Golden-hash caveat: touching templates or schema text means
pnpm build && pnpm regen:parity-hashes, then re-run the parity tests.Open questions
design.md, or leave it torulesand only document it? Every user inherits the default, and a mandatory-feeling diagram in a two-file change is worse than none.specstoo, ordesignonly? Delta specs are consumed by both agents and archive/sync; a mermaid block in aMODIFIEDrequirement is more format surface than it looks.