Skip to content
| Marketplace
Sign in
Visual Studio Code>Visualization>OpenSpec DiagramsNew to Visual Studio Code? Get it now.
OpenSpec Diagrams

OpenSpec Diagrams

Juan Pablo Bacallao Castillo

|
1 install
| (0) | Free
Render OpenSpec spec.md files as live Mermaid diagrams, always derived from the scenarios.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

OpenSpec Diagrams

CI License: MIT

Render OpenSpec spec.md files as live diagrams in VS Code.

OpenSpec scenarios (WHEN / THEN) are precise for machines but hard for humans to follow as a whole. A hand-drawn diagram next to them would drift out of sync. OpenSpec Diagrams derives the diagram from the scenarios every time, so the spec stays the single source of truth. Nothing is stored or hand-edited.

Features

  • View as diagram from a CodeLens at the top of the file and from the editor title bar button.
  • One Mermaid flowchart per requirement: the requirement is the root, each scenario a branch, WHEN the condition, THEN the outcome. AND lines extend the previous WHEN / THEN.
  • State-machine diagrams by default (like xstate): GIVEN is the source state, WHEN the event, AND guards, THEN the target state. A flowchart renderer is available in the settings, where a requirement leads to a single diamond with one branch per scenario.
  • AND lines as conditions: each AND becomes its own condition node (hexagon) in the chain, or can be shown as a list.
  • Delta specs are labelled and colour-coded: ADDED, MODIFIED, REMOVED (with reason) and RENAMED.
  • Live: re-renders as you type and on save, follows the VS Code light/dark theme.
  • Clear message when a file has no parseable requirements.
  • Offline: Mermaid is bundled, nothing is loaded from the network, and no files are written to your workspace.
  • No writing convention required: WHEN / THEN text is shown exactly as written.

Where it works

The action is offered on files named spec.md located at:

  • openspec/specs/<capability>/spec.md
  • openspec/changes/<change>/specs/<capability>/spec.md (including archived changes)

Usage

  1. Open a spec.md in one of the locations above.
  2. Click View as diagram (CodeLens on line 1) or the diagram button in the editor title bar. You can also run OpenSpec: View as diagram from the Command Palette.
  3. A panel opens beside the editor. Edit the spec and the diagram updates.

Settings

Setting Values Default
openspecViewer.diagram.renderer statechart, flowchart statechart
openspecViewer.diagram.layout decision-diamond, options-box, scenario-flow decision-diamond
openspecViewer.diagram.andStyle chained, list chained

layout and andStyle only apply when the renderer is flowchart.

The default statechart renderer draws a state machine, similar to xstate: GIVEN is the source state, WHEN the event on the arrow, AND lines before THEN are guards ([a && b]), THEN is the target state and later AND lines are actions listed inside it. Scenarios whose GIVEN or first THEN text is identical share a state, so related scenarios connect on their own.

Open panels re-render as soon as a setting changes.

How to write specs for clear diagrams

The diagram treats the scenarios of one requirement as alternatives of a single decision (for example success / card declined / timeout). If behaviours can apply at the same time, put them in separate requirements.

Install

From the Marketplace or Open VSX: search for OpenSpec Diagrams.

From a .vsix (for example one attached to a GitHub Release):

code --install-extension openspec-diagrams-<version>.vsix

or use Extensions: Install from VSIX… in VS Code.

Recommend it to your team

In the project that holds the specs, add to .vscode/extensions.json:

{
  "recommendations": ["juanpbacallao.openspec-diagrams"]
}

Non-goals

Editing specs from the diagram, sequence diagrams, storing generated diagrams, and changing OpenSpec itself.

Development

See CONTRIBUTING.md. The parser and Mermaid generator live in src/core with no VS Code dependency, so they can be reused by a CLI or other tooling.

License

MIT. See also the Code of Conduct and Security policy.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft