Embedding Visual Diagrams (UML / Mermaid / PlantUML) Across Spec Kit Workflows

[Nicered]

Context

Spec Kit’s workflow — /specify → /plan → /tasks → /implement — currently relies heavily on text-based documentation. While this is useful for details, complex flows, algorithms, and architecture decisions are often harder to follow in text alone. Contributors (especially newcomers) could benefit from a more visual representation of these processes.

Problem

• Text-only documentation can be verbose and harder to parse.
• Complex user flows, architecture decisions, or validation pipelines require repeated explanation.
• Contributors may struggle to understand the overall context without a visual overview.

Proposal

Introduce visual diagrams (UML, Mermaid, PlantUML) into various Spec Kit documents:

• Specs: illustrate system architecture, request/response flows, validation pipelines.
• Plans: visualize design options, dependencies, and branching strategies.
• Tasks: show decomposition of work, algorithm flows, or state transitions.
• RFCs / Decision Records: capture trade-offs, before/after states, and impact analysis.

Recommended tooling:

• Mermaid: lightweight, GitHub-renderable (flowcharts, sequence/state diagrams).
• PlantUML: more detailed class, component, or architecture diagrams.
• Diagrams can be embedded in Markdown or stored as .puml files for contributors to edit.

Example (Mermaid Sample)

sequenceDiagram
  user->>specify: submit feature prompt
  specify->>agent: generate spec
  agent->>specify: return spec document
  user->>plan: propose architecture
  plan->>agent: assess design options
  agent->>plan: return detailed plan
  plan->>tasks: decompose into tasks
  tasks->>agent: generate task list

Loading

Expected Benefits

• Faster comprehension: contributors can scan diagrams instead of reading long text.
• Shared visual language: reduces ambiguity, supports collaboration.
• Consistency: diagrams-as-code ensure visuals are version-controlled.
• Improved onboarding: new contributors understand workflows more quickly.

Discussion Points

• Should we standardize on Mermaid or PlantUML, or allow both?
• Where should diagrams be mandatory (specs, plans, RFCs) vs optional?
• How do we ensure diagrams remain up-to-date (review checklists, CI validation)?
• Should we provide starter templates (common UML patterns) for contributors?
• Which areas should we prioritize first (e.g., spec flows, planning architecture)?

[Zyzzx]

This concept is something I have been pondering. I have been trying to come up with some test projects to see if the LLMs are able to architect software processes better with textual descriptions or things like state/model diagrams. I think it is worth hammering on. I found spec-kit not too long ago and the way it works makes it easy to test a lot of different strategies quickly since all of it is just text files of prompts and templates.

Since I am more of an architect than a developer these days, I tend to think about projects as an architect. I would like to use Mermaid to very efficiently specify project layout, or even an abstract layer above to define how and app or service is put together logically. Then provide use cases and then behaviors more like BDD. From that it seems that development can be broken down into distinct phases (in separate files for context even) and they could be done in parallel if top-level scaffolding and interfaces are created.

[yubrshen]

From my experience of playing with text to diagram, I suggest considering graphviz (.dot) format.
I found that PlanUML is too limited in expression. Mermaid may not produce readable layout beyond toy problems.
Graphviz' layout capability is so far the most capable and versatile.
It can be rather simple in syntax with additional detailed specification possible.

Actually, I'm trying to use Graphviz syntax in prompts to express my design intent.

[Zyzzx]

I have always been a fan of GraphViz, but it can be complex, probably complex enough to confuse an LLM. Mermaid is fairly simple and seems to be understood by LLMs fairly well. I am going to see how complex I can make a mermaid diagram before it falters.

I have found that some of the big (100B+) models able to understand my descriptions of hierarchies pretty well, but I want a more succinct way to specify relationships, both logical and physical. My experience maybe a year ago with some models being able to understand GraphViz were limited to simple relationship or state diagrams, but even now I think that having them understand arbitrary graphviz and being able to emit it with the kind of layout and design desired will still be a stretch.