Skip to content

feat(schemas): let specs draw pictures for the humans #1472

Description

@clay-good

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:

  1. 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.
  2. Add a short Diagrams section to docs/customization.md showing the two-line rules: recipe and the fork path.
  3. 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

  1. 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.
  2. 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.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3-lowNice to have, backlogdesign-reviewNeeds product/design decisionenhancementNew feature or requestschemaSchema system

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions